Expand AGENTS docs to multi-level structure

Author: napetrov

.github/AGENTS.md

@@ -0,0 +1,15 @@
+# AGENTS.md — .github/
+
+CI/CD workflows and repo automation.
+
+## Workflows (source of truth)
+- `conda-package.yml` — Intel channel conda build/test pipeline
+- `conda-package-cf.yml` — conda-forge-oriented build/test pipeline
+- `build-with-clang.yml` — clang compatibility checks
+- `build_pip.yaml` — wheel build pipeline
+- `pre-commit.yml` — lint/format checks
+- `openssf-scorecard.yml` — security scanning
+
+## Policy
+- Treat workflow YAML as canonical for platform/Python matrices.
+- Avoid doc claims about CI coverage unless present in workflow config.

.github/copilot-instructions.md

@@ -1,50 +1,45 @@
 # GitHub Copilot Instructions — mkl_fft
 
 ## Identity
-You are an expert Python/C developer working on `mkl_fft` at Intel.
-Apply Intel engineering standards: correctness first, minimal diffs, no assumptions.
+You are an expert Python/C/Cython developer working on `mkl_fft` at Intel.
+Prioritize correctness, API compatibility, and minimal diffs.
 
 ## Source of truth
 This file is canonical for Copilot/agent behavior.
-`AGENTS.md` provides project context.
+`AGENTS.md` files provide project context.
 
 ## Precedence
 copilot-instructions > nearest AGENTS > root AGENTS
-Higher-precedence file overrides; lower must not restate overridden guidance.
+Higher-precedence file overrides lower-precedence context.
 
 ## Mandatory flow
 1. Read root `AGENTS.md`. If absent, stop and report.
-2. For edited files, use root AGENTS (no local AGENTS files exist here).
-3. If future local `AGENTS.md` files appear, find nearest per file.
+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 diffs minimal; prefer atomic single-purpose commits.
-- Preserve NumPy/SciPy FFT API compatibility by default.
-- For API changes: update tests + docstrings when user-visible.
-- For bug fixes: add regression tests in `mkl_fft/tests/`.
-- Do not generate code without a corresponding test update in the same step.
-- Run `pre-commit run --all-files` before proposing code changes.
+- Keep changes atomic and single-purpose.
+- Preserve NumPy/SciPy FFT compatibility by default.
+- For behavior changes: update/add tests in `mkl_fft/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.
 
 ## Authoring rules
-- Use source-of-truth files for all mutable details.
-- Never invent/hardcode versions, flags, or matrix values.
-- Use stable entry points: `pip install -e .` (dev), `pytest mkl_fft/tests` (test).
-- Never include sensitive data in any file.
-- **C templates:** Edit only `src/*.c.src`; do not manually edit generated `.c` files.
-- **Cython/MKL calls:** Release GIL with `with nogil:` blocks for performance-critical MKL functions.
-- **Memory:** Ensure proper alignment for FFT buffers; respect MKL object lifecycle.
-- **Compiler flags:** Do not hardcode ISA flags (AVX-512, etc.) outside `setup.py`.
+- Never invent versions, build flags, CI matrices, or channel policies.
+- Use source-of-truth files for mutable details.
+- **C templates:** edit only `mkl_fft/src/*.c.src`; do not manually edit generated `.c` files.
+- Prefer stable local entry points:
+  - `python -m pip install -e .`
+  - `pytest mkl_fft/tests`
 
 ## Source-of-truth files
 - Build/config: `pyproject.toml`, `setup.py`
-- Dependencies: `pyproject.toml` (dependencies, optional-dependencies), `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml`
+- Dependencies: `pyproject.toml`, `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml`
 - CI: `.github/workflows/*.{yml,yaml}`
-- Style/lint: `.pre-commit-config.yaml`, `.flake8`, `pyproject.toml` (tool.black, tool.isort, tool.cython-lint)
-- API contracts: `mkl_fft/__init__.py`, `mkl_fft/interfaces/*.py`, NumPy FFT docs (https://numpy.org/doc/stable/reference/routines.fft.html), SciPy FFT docs (https://docs.scipy.org/doc/scipy/reference/fft.html)
-- Test data: `mkl_fft/tests/`
+- API: `mkl_fft/__init__.py`, `mkl_fft/interfaces/*.py`, `mkl_fft/_pydfti.pyx`
+- Tests: `mkl_fft/tests/`
 
 ## Intel-specific constraints
-- Package channels: Intel PyPI (https://software.repos.intel.com/python/pypi), Intel conda (https://software.repos.intel.com/python/conda), conda-forge
-- MKL backend: requires `mkl-devel` at build time, `mkl-service` at runtime
-- Performance: for claims, reference https://github.com/intelpython/fft_benchmark
-- Do not hardcode MKL version assumptions; respect `pyproject.toml` `requires-python` range
+- Build-time MKL: `mkl-devel`; runtime MKL integration via `mkl-service`
+- Performance claims require reproducible benchmark context
+- Do not introduce ISA-specific assumptions outside explicit build configuration

AGENTS.md

@@ -1,35 +1,47 @@
 # AGENTS.md — mkl_fft
 
-## What this project is
-NumPy-based Python interface to Intel® oneMKL FFT functions. Provides MKL-accelerated FFT for real/complex transforms. Part of Intel® Distribution for Python. Archetype: **python** (Cython + C extensions).
-
-Layers: Python interfaces, Cython bindings (`_pydfti.pyx`), C backend (`src/*.c.src`).
-
-## How it's structured
-- `mkl_fft/interfaces/` — drop-in replacements for `numpy.fft`, `scipy.fft`
-- `mkl_fft/src/` — C templates (`.c.src`)
-- `mkl_fft/tests/` — pytest suite
-- `conda-recipe/`, `conda-recipe-cf/` — Intel/conda-forge builds
-
-Build: `pyproject.toml` + `setup.py`. Runtime: `mkl-service`, `numpy>=1.26.4`.
+Entry point for agent context in this repo.
 
-## How to work in it
-- Keep changes atomic and single-purpose.
-- Preserve NumPy/SciPy FFT API; document divergence in commit message.
-- Pair changes with tests and docstrings.
-- Never assume MKL or NumPy versions; use source-of-truth files.
-- **C templates:** Edit only `*.c.src` files; generated `.c` is ephemeral (via `_vendored/conv_template.py`).
-- **Local dev:** `conda create -n dev python numpy cython mkl-devel pytest && pip install -e .`
-
-For agent policy: `.github/copilot-instructions.md`
+## What this project is
+`mkl_fft` is a NumPy/SciPy-compatible FFT interface backed by Intel® oneMKL.
+It provides accelerated FFT transforms while aiming to preserve upstream API behavior.
+
+## Key components
+- **Package:** `mkl_fft/`
+- **Cython bindings:** `mkl_fft/_pydfti.pyx`
+- **Template-based C backend:** `mkl_fft/src/*.c.src`
+- **Interface adapters:** `mkl_fft/interfaces/`
+- **Tests:** `mkl_fft/tests/`
+- **Vendored helpers:** `_vendored/`
+- **Packaging:** `conda-recipe/`, `conda-recipe-cf/`
+
+## Build/runtime basics
+- Build system: `pyproject.toml` + `setup.py`
+- Build deps: `cython`, `numpy`, `mkl-devel`
+- Runtime deps: `numpy`, `mkl-service`
+
+## Development guardrails
+- Preserve NumPy/SciPy FFT API compatibility unless change is explicitly requested.
+- Edit template sources (`*.c.src`), not generated C artifacts.
+- Pair behavior changes with tests and keep diffs minimal.
+- Avoid hardcoding mutable versions/matrices/channels in docs.
 
 ## Where truth lives
 - Build/config: `pyproject.toml`, `setup.py`
-- Dependencies: `pyproject.toml` (`dependencies`, `optional-dependencies`), `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml`
-- CI: `.github/workflows/`
-- Style/lint: `.pre-commit-config.yaml`, `.flake8`, `pyproject.toml` (black/isort/cython-lint)
-- API/contracts: `mkl_fft/__init__.py`, `mkl_fft/interfaces/`, NumPy/SciPy FFT docs
-- Stable entry points: `python -m pip install .`, `pytest mkl_fft/tests`
+- Dependencies: `pyproject.toml`, `conda-recipe*/meta.yaml`
+- CI/workflows: `.github/workflows/*.{yml,yaml}`
+- Public API: `mkl_fft/__init__.py`, `mkl_fft/interfaces/`
+- Tests: `mkl_fft/tests/`
+
+For behavior policy, see `.github/copilot-instructions.md`.
 
 ## Directory map
-No local AGENTS files — project is small enough for root-level guidance only.
+Use nearest local `AGENTS.md` when present:
+- `.github/AGENTS.md` — CI workflows and automation policy
+- `mkl_fft/AGENTS.md` — package-level implementation context
+- `mkl_fft/interfaces/AGENTS.md` — NumPy/SciPy interface adapters
+- `mkl_fft/src/AGENTS.md` — C template backend rules
+- `mkl_fft/tests/AGENTS.md` — test scope/conventions
+- `conda-recipe/AGENTS.md` — Intel-channel conda packaging
+- `conda-recipe-cf/AGENTS.md` — conda-forge recipe context
+- `_vendored/AGENTS.md` — vendored tooling boundaries

_vendored/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md — _vendored/
+
+Vendored utilities used by build/code-generation flows.
+
+## Guardrails
+- Prefer updating upstream source when feasible; keep local vendored diffs minimal.
+- Do not refactor vendored code opportunistically in unrelated PRs.
+- If vendored logic affects generated sources, validate downstream build/test paths.

conda-recipe-cf/AGENTS.md

@@ -0,0 +1,10 @@
+# AGENTS.md — conda-recipe-cf/
+
+Conda-forge recipe context for `mkl_fft`.
+
+## Scope
+- conda-forge specific recipe files under this directory.
+
+## Guardrails
+- Keep conda-forge recipe semantics separate from Intel-channel recipe.
+- Align changes with `conda-package-cf.yml` workflow behavior.

conda-recipe/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md — conda-recipe/
+
+Intel-channel conda packaging context.
+
+## Scope
+- `meta.yaml` — package metadata and dependency pins
+- `build.sh` / `bld.bat` — platform build scripts
+
+## Guardrails
+- Treat recipe files as canonical for packaging intent.
+- Keep recipe updates synchronized with CI workflow behavior.

mkl_fft/AGENTS.md

@@ -0,0 +1,16 @@
+# AGENTS.md — mkl_fft/
+
+Core package implementation for MKL-backed FFT operations.
+
+## Key files
+- `__init__.py` — public package API surface
+- `_pydfti.pyx` — Cython bindings for DFTI interactions
+- `_mkl_fft.py` / `_fft_utils.py` — runtime FFT helper logic
+- `interfaces/` — NumPy/SciPy adapter modules
+- `src/` — C template backend (`*.c.src`)
+- `tests/` — package tests (see local AGENTS in tests)
+
+## Guardrails
+- Preserve NumPy/SciPy-compatible behavior by default.
+- Keep adapter, binding, and backend changes coordinated with tests.
+- Prefer minimal isolated edits around changed API paths.

mkl_fft/interfaces/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md — mkl_fft/interfaces/
+
+Adapter layer for `numpy.fft` / `scipy.fft` style interfaces.
+
+## Scope
+- Interface modules mapping user-facing calls to MKL-backed implementation.
+
+## Guardrails
+- Preserve function signatures and behavioral expectations unless explicitly requested.
+- Keep compatibility with upstream NumPy/SciPy semantics in mind.
+- Any user-visible behavior change here should include tests in `mkl_fft/tests/`.

mkl_fft/src/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md — mkl_fft/src/
+
+C template backend for FFT internals.
+
+## Scope
+- Template sources (`*.c.src`) used to generate C implementation artifacts.
+
+## Guardrails
+- Edit template files (`*.c.src`) rather than generated `.c` files.
+- Keep template changes tightly scoped and validated by tests.
+- Coordinate with Cython/binding/API layers when changing function behavior.

mkl_fft/tests/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md — mkl_fft/tests/
+
+Test suite for FFT API compatibility and regressions.
+
+## Expectations
+- Behavior changes should include test updates in the same PR.
+- Bug fixes require regression tests.
+- Keep tests deterministic and avoid brittle performance-dependent assertions.
+
+## Entry point
+- `pytest mkl_fft/tests`