task: agent-ready prep

.gitattributes

@@ -0,0 +1,3 @@
+# Keep shell scripts LF on checkout so shellcheck and conda build scripts work
+# the same on Windows and WSL checkouts with core.autocrlf enabled.
+*.sh text eol=lf

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+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_fft/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 input shape and dtype.
+      render: python
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-source
+    attributes:
+      label: How was `mkl_fft` installed?
+      options:
+        - Intel channel (software.repos.intel.com)
+        - conda-forge
+        - pip / PyPI
+        - Built from source
+    validations:
+      required: true
+
+  - type: textarea
+    id: versions
+    attributes:
+      label: Versions
+      description: |
+        Output of:
+        ```
+        python -c "import mkl_fft, numpy, mkl; print(mkl_fft.__version__); print(numpy.__version__); print(mkl.get_version_string())"
+        ```
+        Add your OS and Python version too.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else
+      description: |
+        Optional. Whether NumPy patching was active (`mkl_fft.is_patched()`), whether
+        the result differs from `numpy.fft`/`scipy.fft`, 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://github.com/IntelPython/mkl_fft/blob/master/README.md
+    about: Check the README and the interfaces documentation first.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: Feature request
+description: Propose a new transform, interface, 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_fft` to do. If it mirrors a `numpy.fft` or
+        `scipy.fft` function, name it — upstream signature and semantics are the
+        contract for the interface layer.
+    validations:
+      required: true
+
+  - type: input
+    id: upstream
+    attributes:
+      label: Upstream equivalent
+      description: Link to the NumPy or SciPy docs for the equivalent API, 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/pull_request_template.md

@@ -0,0 +1,25 @@
+# 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_fft/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 benchmarks. Write "none" if you ran everything relevant.
+-->
+
+## Checklist
+
+- [ ] NumPy/SciPy FFT API compatibility preserved, or the break is intentional and called out above.
+- [ ] Behavior changes have tests in `mkl_fft/tests/`; bug fixes have a regression test.
+- [ ] `CHANGELOG.md` updated under `## [dev]` with a `[gh-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

@@ -5,10 +5,19 @@ mkl_fft.egg-info/
 # Byte-compiled / optimized / DLL files
 __pycache__/
 
+# Virtual environments, test caches, local env files
+.venv/
+venv/
+.pytest_cache/
+.env
+
 mkl_fft/_pydfti.c
 mkl_fft/_pydfti.cpython*.so
 mkl_fft/_pydfti.*-win_amd64.pyd
 mkl_fft/src/mklfft.c
 
 # ASV benchmark artifacts
 .asv/
+
+# Developer-local coding agent settings
+.claude/settings.local.json

AGENTS.md

@@ -14,6 +14,7 @@ It provides accelerated FFT transforms while aiming to preserve upstream API beh
 - **Tests:** `mkl_fft/tests/`
 - **Vendored helpers:** `_vendored/`
 - **Packaging:** `conda-recipe/`, `conda-recipe-cf/`
+- **Benchmarks:** `benchmarks/`
 
 ## Build/runtime basics
 - Build system: `pyproject.toml` + `meson.build`
@@ -46,3 +47,4 @@ Use nearest local `AGENTS.md` when present:
 - `conda-recipe/AGENTS.md` — Intel-channel conda packaging
 - `conda-recipe-cf/AGENTS.md` — conda-forge recipe context
 - `_vendored/AGENTS.md` — vendored tooling boundaries
+- `benchmarks/AGENTS.md` — ASV performance suite

CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing to `mkl_fft`
+
+This document covers the development workflow: how to get a working build, how
+to run the checks, and what to include in a pull request.
+
+For end-user installation and API usage, see [README.md](README.md). For a map
+of the source tree, see [`AGENTS.md`](AGENTS.md), which links to the local
+`AGENTS.md` files in directories that have their own rules. Security
+vulnerabilities go through the process in [SECURITY.md](SECURITY.md).
+
+---
+
+## Development setup
+
+Building requires a C compiler, oneMKL headers and libraries (`mkl-devel`), and
+NumPy. A conda environment is the least surprising way to get them:
+
+```sh
+# add python=X.Y to target a specific interpreter
+conda create -n mkl_fft-dev -c conda-forge python pip mkl-devel numpy \
+    meson-python ninja cmake cython pytest
+conda activate mkl_fft-dev
+```
+
+Then build in place, which reuses the environment's MKL and NumPy:
+
+```sh
+pip install -e . --no-build-isolation --verbose
+```
+
+`pyproject.toml` defines the supported Python range, and
+`.github/workflows/build_pip.yml` is canonical for the versions CI covers.
+
+SciPy and `mkl-service` are optional. They are needed only for the
+`mkl_fft.interfaces.scipy_fft` adapter, and the tests that exercise it are
+skipped without them. To use or test the SciPy interface, add both to the
+environment:
+
+```sh
+conda install -c conda-forge scipy mkl-service
+```
+
+The matching pip extras are declared in `pyproject.toml`: `scipy_interface` for
+the SciPy adapter, `test` for `pytest` plus both packages, and `benchmark` for
+the ASV suite.
+
+`README.md` documents the non-editable install paths, including the isolated
+build that resolves its own `mkl` and `numpy`.
+
+### Rebuilding
+
+`meson-python` rebuilds the extension on import for editable installs, so
+editing `.pyx`, `.c.src`, or `meson.build` and rerunning `pytest` is usually
+enough. Generated sources and the compiled extension live under `build/<tag>/`
+rather than in the source tree. If a build gets into a bad state, `rm -rf build`
+and reinstall.
+
+## Running the checks
+
+```sh
+pytest mkl_fft/tests          # test suite
+pre-commit run --all-files    # lint and format hooks
+```
+
+Install the hooks once with `pre-commit install` and they run on each commit.
+`.pre-commit-config.yaml` is the source of truth for the tooling.
+
+Opening a pull request also runs CI, which builds and tests the package across
+platforms and Python versions and runs various lint and static-analysis checks.
+
+## Code style
+
+Style is loose, and the pre-commit hooks enforce most of it:
+
+- Python and Cython are formatted with `black` and `isort`, with a line length
+  of 80.
+- C sources follow the repository's `.clang-format`.
+- Otherwise, match the surrounding code.
+
+## Dos and don'ts
+
+**Do**
+
+- Keep changes atomic and single-purpose.
+- Preserve NumPy/SciPy FFT compatibility. This package is used as a drop-in
+  replacement, so a behavioral difference is a bug even when the new behavior is
+  arguably better. Call out an intentional break in the PR.
+- Add tests in `mkl_fft/tests/` alongside behavior changes, and a regression
+  test with every bug fix.
+- Keep tests deterministic.
+- Edit the `*.c.src` templates in `mkl_fft/src/` for C backend changes. The
+  `.c` files are generated from them on every build.
+- Keep patching reversible and observable: anything installed can be
+  uninstalled, and `is_patched()` reports the truth.
+- Cite the source-of-truth file for mutable details: `pyproject.toml`,
+  `meson.build`, `conda-recipe*/meta.yaml`, `.github/workflows/`.
+- Give benchmark numbers reproducible context — hardware, versions, and the
+  command you ran.
+
+**Don't**
+
+- Commit generated artifacts, or hand-edit a generated `.c`.
+- Hardcode versions, build flags, CI matrices, or channel URLs in documentation.
+- Assert on timing or throughput in the test suite.
+- Refactor `_vendored/` opportunistically. Keep local diffs minimal and send
+  fixes upstream where you can.
+- Introduce ISA-specific assumptions outside explicit build configuration.
+
+## Submitting a change
+
+Work on a branch: the `no-commit-to-branch` hook blocks direct commits to
+`master` and `maintenance/*`.
+
+If the change is user-visible — behavior, API, packaging, or build output — add
+a `CHANGELOG.md` entry under `## [dev]` in the matching section, with a
+`[gh-NNN](https://github.com/IntelPython/mkl_fft/pull/NNN)` link. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Docs,
+tooling, and CI-only changes are usually left out.
+
+Then open the PR and fill in the template, including what you verified locally
+and what you left to CI.
+
+By contributing you agree that your contributions are licensed under the
+BSD-3-Clause terms in [LICENSE.txt](LICENSE.txt).

README.md

@@ -165,3 +165,10 @@ Optionally, install `scipy` to use the `mkl_fft.interfaces.scipy_fft` module:
 ```sh
 pip install scipy
 ```
+
+---
+# 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.

benchmarks/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md — benchmarks/
+
+ASV performance suite for `mkl_fft`.
+
+## Scope
+- `asv.conf.json` — ASV configuration, channels, and regression thresholds
+- `benchmarks/` — benchmark modules (`bench_fft1d`, `bench_fftnd`,
+  `bench_interfaces`, `bench_memory`) plus shared bases in `_utils.py`
+- `README.md` — coverage table, threading model, and run commands
+
+## Guardrails
+- Treat `asv.conf.json` as canonical for ASV settings; treat `README.md` as
+  canonical for what each module covers.
+- Comparability across machines depends on the thread default in
+  `benchmarks/__init__.py` and the DFTI warmup in each `setup`. Changing either
+  invalidates comparison against existing results — call it out explicitly.
+- Keep inputs deterministic; benchmarks seed their own RNG.
+- Report performance numbers with reproducible context: hardware, thread count,
+  versions, and the command used.
+- Benchmark results under `.asv/` are local artifacts and are gitignored.