Update AGENTS for interfaces namespace and patching guidance

Author: napetrov

.github/copilot-instructions.md

@@ -19,7 +19,7 @@ Higher-precedence file overrides lower-precedence context.
 
 ## Contribution expectations
 - Keep changes atomic and single-purpose.
-- Preserve `numpy.random` compatibility by default.
+- Preserve `numpy.random` compatibility by default, including compatibility aliases during namespace transitions.
 - For behavior changes: update/add tests in `mkl_random/tests/` in the same change.
 - For bug fixes: include a regression test.
 - Run `pre-commit run --all-files` when `.pre-commit-config.yaml` is present.
@@ -36,7 +36,7 @@ Higher-precedence file overrides lower-precedence context.
 - Build/config: `pyproject.toml`, `setup.py`
 - Dependencies: `pyproject.toml`, `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml`
 - CI: `.github/workflows/*.{yml,yaml}`
-- API: `mkl_random/__init__.py`, `mkl_random/mklrand.pyx`
+- API: `mkl_random/__init__.py`, `mkl_random/mklrand.pyx`, `mkl_random/interfaces/*.py` (when present)
 - Tests: `mkl_random/tests/`
 
 ## Intel-specific constraints

AGENTS.md

@@ -9,7 +9,7 @@ It provides accelerated random sampling with API compatibility goals relative to
 ## Key components
 - **Python package:** `mkl_random/`
 - **Cython layer:** `mkl_random/mklrand.pyx`
-- **C backend/templates:** `mkl_random/src/`
+- **C/C++ backend sources:** `mkl_random/src/` (`*.cpp`, `*.h`, support scripts)
 - **Tests:** `mkl_random/tests/`
 - **Packaging:** `conda-recipe/`, `conda-recipe-cf/`
 - **Examples:** `examples/`
@@ -21,15 +21,17 @@ It provides accelerated random sampling with API compatibility goals relative to
 
 ## Development guardrails
 - Preserve `numpy.random` API compatibility unless change is explicitly requested.
+- Keep namespace/API transitions explicit (e.g., `mkl_random.MKLRandomState` with compatibility aliases where applicable).
 - RNG changes must preserve statistical correctness and reproducibility expectations.
+- If patching/integration entry points are touched, keep patch semantics and rollback behavior explicit.
 - Keep diffs minimal and pair behavior changes with tests.
 - Avoid hardcoding mutable versions/matrices/channels in docs.
 
 ## Where truth lives
 - Build/config: `pyproject.toml`, `setup.py`
 - Dependencies: `pyproject.toml`, `conda-recipe*/meta.yaml`
 - CI matrices/workflows: `.github/workflows/*.{yml,yaml}`
-- Public API: `mkl_random/__init__.py`
+- Public API: `mkl_random/__init__.py`, `mkl_random/interfaces/*.py` (when present)
 - Tests: `mkl_random/tests/`
 
 For behavior policy, see `.github/copilot-instructions.md`.

mkl_random/AGENTS.md

@@ -6,11 +6,13 @@ Core package implementation for MKL-backed random functionality.
 - `__init__.py` — public package exports/API wiring
 - `mklrand.pyx` — Cython bindings to MKL RNG support
 - `_init_helper.py` — platform/runtime loading helpers
-- `src/` — C-level support and generation assets
+- `src/` — C/C++ support sources and headers
 - `tests/` — package tests (see local AGENTS in tests)
 
 ## Guardrails
 - Preserve `numpy.random`-compatible behavior by default.
+- Keep namespace compatibility explicit (`MKLRandomState` + compatibility aliases where needed).
 - RNG algorithm/distribution changes must preserve statistical correctness.
 - Keep BRNG/distribution behavior explicit and test-covered.
+- If patching/integration shims are modified, ensure behavior remains reversible and test-covered.
 - Prefer minimal, isolated edits around touched API paths.