task: agent ready prep

.github/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md — .github/
+
+CI/CD workflows and repo automation.
+
+## Workflows (source of truth)
+- `conda-package.yml` — Intel-channel conda build and test
+- `conda-package-cf.yml` — conda-forge conda build and test
+- `build_pip.yml` — editable pip build and test, including pre-release NumPy
+- `build-with-clang.yml` — build and test with `icx`/`icpx` from the oneAPI apt
+  repository
+- `build-with-standard-clang.yml` — build and test with Ubuntu's `clang`
+  package
+- `build-docs.yml` — Sphinx build; publishes to `gh-pages` from `master`
+- `pre-commit.yml` — lint/format checks
+- `coverity.yml` — Coverity static analysis (see `coverity/README.md`)
+- `openssf-scorecard.yml` — OpenSSF Scorecard
+- `zizmor.yml` — GitHub Actions security lint
+
+The three pip workflows test the editable install: `build_pip.yml` runs
+`pytest mkl_random/tests`, the clang workflows `pytest --pyargs mkl_random`.
+Both conda workflows build with `conda build --no-test` and test the built
+package in separate jobs: `conda-package.yml` runs `pytest --pyargs mkl_random`,
+`conda-package-cf.yml` runs the recipe's test section with `conda build --test`.
+
+## Templates and config
+- `copilot-instructions.md` — GitHub Copilot behavior; points back to the
+  `AGENTS.md` files
+- `pull_request_template.md` — PR description, verification, and checklist
+- `ISSUE_TEMPLATE/` — bug report and feature request forms; `config.yml` adds
+  contact links that send security reports to Intel's vulnerability process
+  and usage questions to the docs
+- `dependabot.yml` — update schedule for GitHub Actions and pre-commit hooks
+- `CODEOWNERS` — default reviewers
+
+## Policy
+- Treat workflow YAML as canonical for platform/Python matrices.
+- Avoid doc claims about CI coverage unless present in workflow config.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,70 @@
+name: Bug report
+description: Report incorrect results, a crash, or a build failure
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        For security vulnerabilities, do not open an issue — follow [SECURITY.md](https://github.com/IntelPython/mkl_random/blob/master/SECURITY.md).
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened, and what did you expect instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: Reproducer
+      description: A minimal, self-contained snippet. Include the seed, the `brng`, the distribution and its arguments, and `size`. For a build failure, give the build command.
+      render: python
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-source
+    attributes:
+      label: How was `mkl_random` installed?
+      options:
+        - Intel conda channel (software.repos.intel.com)
+        - conda-forge
+        - pip, Intel index (software.repos.intel.com)
+        - pip / PyPI
+        - Built from source
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: versions
+    attributes:
+      label: Versions
+      description: |
+        Output of:
+        ```
+        python -c "import mkl_random, numpy; print(mkl_random.__version__); print(numpy.__version__)"
+        ```
+        Add the MKL version (`conda list mkl` or `pip list | grep -i mkl`), your OS, and your Python version too. If the build failed, give the NumPy and compiler versions instead.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error output or build log
+      description: Optional. The full traceback, or the build log for a build failure.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else
+      description: Optional. Whether NumPy patching was active (`mkl_random.is_patched()`), whether you used `mkl_random.interfaces.numpy_random`, or a non-default `MKL_NUM_THREADS`.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html
+    about: Report security vulnerabilities through Intel's process, not a public issue.
+  - name: Question about usage
+    url: https://intelpython.github.io/mkl_random/
+    about: Check the documentation and README first.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Feature request
+description: Propose a new distribution, generator, or capability
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: The use case, not the implementation.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: What you would like `mkl_random` to do. If it mirrors a legacy `numpy.random` function, name it — its signature is the contract for the NumPy interface.
+    validations:
+      required: true
+
+  - type: input
+    id: upstream
+    attributes:
+      label: Upstream equivalent
+      description: Link to the NumPy or oneMKL docs for the equivalent, if there is one.
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Optional. Workarounds you are using today.
+    validations:
+      required: false

.github/copilot-instructions.md

@@ -0,0 +1,43 @@
+# GitHub Copilot Instructions — mkl_random
+
+## Identity
+You are an expert Python/C/Cython developer working on `mkl_random` at Intel.
+Prioritize correctness, statistical integrity, and minimal diffs.
+
+## Source of truth
+This file is canonical for Copilot/agent behavior.
+`AGENTS.md` files provide project context.
+
+## Precedence
+copilot-instructions > nearest AGENTS > root AGENTS
+Higher-precedence rules override lower-precedence context.
+
+## Mandatory flow
+1. Read root `AGENTS.md`. If absent, stop and report.
+2. For each edited file, locate and follow the nearest `AGENTS.md`.
+3. If no local file exists, inherit from root `AGENTS.md`.
+
+## Contribution expectations
+- Keep changes atomic and single-purpose.
+- Keep signatures and accepted arguments compatible with legacy `numpy.random`.
+- For behavior changes, update tests in `mkl_random/tests/` in the same step.
+- For bugs, include a regression test.
+- Edit `mkl_random/mklrand.pyx` and `mkl_random/src/`, not the Cython-generated C++.
+
+## Authoring rules
+- Never invent versions, build flags, CI matrices, or channel policies.
+- Use source-of-truth files for dependencies and build config.
+- Keep BRNG selection behind the existing API and configuration points.
+- Never include secrets or credentials in code/docs.
+
+## Source-of-truth files
+- Build/config: `pyproject.toml`, `meson.build`
+- Dependencies/packaging: `pyproject.toml`, `conda-recipe*/meta.yaml`
+- CI: `.github/workflows/*.yml`
+- API: `mkl_random/__init__.py`, `mkl_random/mklrand.pyx`, `mkl_random/interfaces/numpy_random.py`
+- Tests: `mkl_random/tests/`
+
+## Intel-specific constraints
+- Build-time MKL: `mkl-devel`; runtime MKL: `mkl`.
+- Distribution and BRNG changes must preserve statistical properties.
+- Claim performance or statistical improvements only with a reproducible validation.

.github/pull_request_template.md

@@ -0,0 +1,27 @@
+# Description
+
+<!-- What changed and why. Link any related issues. -->
+
+## Verification
+
+<!-- The commands you ran, and the platform and versions you ran them on. -->
+
+- Tests: <!-- e.g. `pytest mkl_random/tests`, Python 3.12 / NumPy 2.x, Linux -->
+- Lint: <!-- `pre-commit run --all-files` -->
+
+## Not verified
+
+<!--
+Anything skipped or left to CI, and why. Examples: Windows, the Intel-channel
+conda build, the docs build, the benchmarks. Write "none" if you ran everything
+relevant.
+-->
+
+## Checklist
+
+- [ ] Legacy `numpy.random` API compatibility preserved, or the break is intentional and called out above.
+- [ ] Seeded output is unchanged, or the `CHANGELOG.md` entry says which streams changed.
+- [ ] Behavior changes have tests in `mkl_random/tests/`; bug fixes have a regression test.
+- [ ] `CHANGELOG.md` updated under `## [dev]` with a `[gh-NNN](https://github.com/IntelPython/mkl_random/pull/NNN)` link, or the change isn't user-visible.
+
+<!-- See CONTRIBUTING.md for the build and test workflow, and AGENTS.md for the module map. -->

.gitignore

@@ -9,5 +9,14 @@ mkl_random/mklrand.cpp
 # Byte-compiled / optimized / DLL files
 __pycache__/
 
+# Virtual environments, test caches, local env files
+.venv/
+venv/
+.pytest_cache/
+.env
+
 # ASV benchmark artifacts
 .asv/
+
+# Developer-local coding agent settings
+.claude/settings.local.json

AGENTS.md

@@ -0,0 +1,71 @@
+# AGENTS.md — mkl_random
+
+Entry point for agent context in this repo.
+
+## What this project is
+`mkl_random` is a NumPy-based interface to Intel® oneMKL random number
+generation. `MKLRandomState` exposes the distributions of legacy
+`numpy.random.RandomState` with a choice of MKL basic generators (`brng`).
+`mkl_random.interfaces.numpy_random` is a drop-in replacement for legacy
+`numpy.random`, and runtime patching can install it in NumPy's place.
+
+## Key components
+- **Package and public API:** `mkl_random/`, `mkl_random/__init__.py`
+- **Cython extension:** `mkl_random/mklrand.pyx`
+- **C++ kernels:** `mkl_random/src/`
+- **NumPy interface:** `mkl_random/interfaces/`
+- **Patching:** `mkl_random/_patch_numpy.py`, plus persistent and one-shot
+  patching in `mkl_random/patch.py`, `mkl_random/with_patch.py`,
+  `mkl_random/_patch_startup.py`, and the `mkl_random/__main__.py` CLI
+- **Tests:** `mkl_random/tests/`
+- **Docs:** `docs/` (Sphinx)
+- **Packaging:** `conda-recipe/`, `conda-recipe-cf/`
+- **Benchmarks:** `benchmarks/`
+- **Examples:** `examples/` (parallel Monte Carlo with generator families)
+- **Coverity:** `coverity/` (Coverity Scan triage guide)
+
+## Build/runtime basics
+- Build system: `pyproject.toml` + `meson.build`
+- Build deps: `mkl-devel`, `numpy`, `meson-python`, `cmake`, `ninja`, `cython`,
+  and C and C++ compilers
+- Runtime deps: `numpy`; the conda recipes add MKL
+- Setup, checks, and style: `CONTRIBUTING.md`
+- Single test: `pytest mkl_random/tests/<file>.py::<test>`, from the editable
+  install in `CONTRIBUTING.md`
+- Single-file lint: `pre-commit run --files <path>`, from a branch (see
+  `CONTRIBUTING.md`)
+
+## Development guardrails
+- Keep signatures and accepted arguments compatible with legacy `numpy.random`.
+- Seeded output is part of the contract: a change to what a fixed seed
+  produces needs a CHANGELOG entry naming the affected streams.
+- Edit `mkl_random/mklrand.pyx` and `mkl_random/src/`, not the
+  Cython-generated C++.
+- Keep patching reversible, with `is_patched()` reporting the truth.
+- Keep the extension free-threading compatible.
+- `meson.build` changes must keep both the GCC-syntax (Linux) and MSVC-syntax
+  (Windows) branches working; CI covers both.
+- Distribution and BRNG changes must preserve statistical properties.
+- Claim performance or statistical improvements only with a reproducible
+  validation.
+- Pair behavior changes with tests and keep diffs minimal.
+- Avoid hardcoding mutable versions/matrices/channels in docs.
+
+## Where truth lives
+- Build/config: `pyproject.toml`, `meson.build`
+- Dependencies: `pyproject.toml`, `conda-recipe*/meta.yaml`
+- CI/workflows: `.github/workflows/*.yml`
+- Public API: `mkl_random/__init__.py`, `mkl_random/interfaces/numpy_random.py`
+- Tests: `mkl_random/tests/`
+
+## Directory map
+Use nearest local `AGENTS.md` when present:
+- `.github/AGENTS.md` — CI workflows and automation policy
+- `mkl_random/AGENTS.md` — package modules, the extension, and generators
+- `mkl_random/src/AGENTS.md` — C++ kernels
+- `mkl_random/interfaces/AGENTS.md` — `numpy.random` drop-in interface
+- `mkl_random/tests/AGENTS.md` — test scope and conventions
+- `docs/AGENTS.md` — Sphinx documentation
+- `conda-recipe/AGENTS.md` — Intel-channel conda packaging
+- `conda-recipe-cf/AGENTS.md` — conda-forge recipe
+- `benchmarks/AGENTS.md` — ASV performance suite

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to `mkl_random`
+
+See [README.md](README.md) for usage, [AGENTS.md](AGENTS.md) for a map of the
+source tree, and [SECURITY.md](SECURITY.md) to report a vulnerability.
+
+## Setup
+
+Building needs C and C++ compilers (`gcc`/`g++`, `clang`/`clang++`, or
+`icx`/`icpx`; MSVC on Windows).
+
+```sh
+conda create -n mkl_random-dev --override-channels -c conda-forge python pip \
+    mkl-devel numpy meson-python ninja cmake "cython>=3.1.0" pytest \
+    pre-commit pylint shellcheck
+conda activate mkl_random-dev
+pip install -e . --no-build-isolation --no-deps
+```
+
+`--override-channels` keeps MKL from mixing with your configured channels.
+
+To build the docs, install `sphinx`, `furo`, `sphinx-design`, and
+`sphinxcontrib-programoutput`, then run
+`sphinx-build -M html docs/source docs/build`.
+
+## Checks
+
+Work on a branch: on `master` or a `maintenance/*` branch, the
+`no-commit-to-branch` hook makes `pre-commit run` fail. From the editable
+install above:
+
+```sh
+pytest mkl_random/tests
+pre-commit run --all-files
+```
+
+The editable install rebuilds the extension on import, and the `pylint` and
+`shellcheck` hooks run the copies installed in the environment, so activate
+`mkl_random-dev` first. The first run needs network access: pre-commit fetches
+each hook, and builds `gitleaks` and `actionlint` from source with Go,
+downloading a Go toolchain if none is on `PATH`. Run `pre-commit install` once
+to run the hooks on each commit.
+
+The pre-commit hooks enforce formatting; otherwise, match the surrounding code.
+
+## Guidelines
+
+- Keep changes small and focused.
+- Keep signatures compatible with legacy `numpy.random`.
+- If a change alters what a fixed seed produces, say which streams changed in
+  the `CHANGELOG.md` entry.
+- Add tests with behavior changes, and a regression test with bug fixes. Seed
+  every generator a test uses.
+- Edit `mkl_random/mklrand.pyx` and `mkl_random/src/`, not generated C++.
+- Keep patching reversible.
+
+## Pull requests
+
+Fill in the PR template. For user-visible changes, add a `CHANGELOG.md` entry
+under `## [dev]`, in the matching section, with a
+`[gh-NNN](https://github.com/IntelPython/mkl_random/pull/NNN)` link.
+
+Contributions are licensed under the terms in [LICENSE.txt](LICENSE.txt).

README.md

@@ -158,3 +158,10 @@ then build against the existing installation with:
 ```sh
 python -m pip install --no-build-isolation --no-deps .
 ```
+
+---
+# Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow: setting up a
+build environment, running the tests and lint hooks, code style, and what to
+include in a pull request.

SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+## Report a Vulnerability
+
+Please report security issues or vulnerabilities to the [Intel® Security Center].
+
+For more information on how Intel® works to resolve security issues, see
+[Vulnerability Handling Guidelines].
+
+[Intel® Security Center]:https://www.intel.com/content/www/us/en/security-center/default.html
+
+[Vulnerability Handling Guidelines]:https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html