Adding some claude tools for claude / cursor

.claude/commands/docs-serve.md

@@ -0,0 +1,32 @@
+Build the HTML documentation and then serve it locally so it can be viewed in a browser.
+
+Ask the user which build mode they want if not specified:
+
+**Step 1 — build (choose one):**
+
+Fast build (skips example gallery):
+
+```bash
+make docs
+```
+
+Full build (includes all examples, slow):
+
+```bash
+make docs-full
+```
+
+Targeted single-example build (ask the user for the filename stem if not provided):
+
+```bash
+make docs-dev FILENAME=<example_stem>
+```
+
+**Step 2 — serve:**
+
+```bash
+uv run python -m http.server 8000 --directory docs/_build/html
+```
+
+The docs will be available at <http://localhost:8000>. Inform the user of the URL and that they
+can stop the server with Ctrl-C.

.claude/commands/docs.md

@@ -0,0 +1,29 @@
+Build the HTML documentation. Ask the user which build mode they want if not specified:
+
+**Fast build** — skips the example gallery, quickest iteration:
+
+```bash
+make docs
+```
+
+**Full build** — includes the complete example gallery (slow, requires all extras):
+
+```bash
+make docs-full
+```
+
+**Targeted example build** — builds a single example page by filename stem, useful when
+developing or debugging a specific example. Ask the user for the example filename if not
+provided:
+
+```bash
+make docs-dev FILENAME=<example_stem>
+```
+
+For example, to build only `examples/run_inference.py`:
+
+```bash
+make docs-dev FILENAME=run_inference
+```
+
+All builds output to `docs/_build/html/`. Report any Sphinx warnings or errors encountered.

.claude/commands/format.md

@@ -0,0 +1,7 @@
+Run the black formatter on the entire codebase:
+
+```bash
+make format
+```
+
+Report whether any files were reformatted or if everything was already compliant.

.claude/commands/license.md

@@ -0,0 +1,18 @@
+Check that every Python source file carries the required SPDX Apache-2.0 license header:
+
+```bash
+make license
+```
+
+The expected header is:
+
+```python
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES.
+# SPDX-FileCopyrightText: All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# ...
+```
+
+Report any files that are missing or have an incorrect header.

.claude/commands/lint.md

@@ -0,0 +1,8 @@
+Run all pre-commit lint checks on the codebase (large-file check, trailing whitespace,
+end-of-file fixer, debug statements, markdownlint, test naming, pyupgrade, ruff, and mypy):
+
+```bash
+make lint
+```
+
+Report every failure with its file path and a short explanation of what needs to be fixed.

.claude/commands/test-full.md

@@ -0,0 +1,17 @@
+Run the full test suite across all tox environments with coverage enabled.
+
+This requires all optional extras to be available. tox handles syncing each environment's
+extras automatically via `uv sync`.
+
+```bash
+make pytest-full
+```
+
+After the run completes, print a coverage summary:
+
+```bash
+make coverage
+```
+
+Report overall pass/fail counts and the final coverage percentage. Flag any modules below the
+90% coverage threshold.

.claude/commands/test.md

@@ -0,0 +1,51 @@
+Run the test suite for a specific tox environment.
+
+## Choosing the right environment
+
+Each tox environment installs a specific set of uv extras before running. When the user asks
+to test a file or feature, check the top of the relevant source file for
+`OptionalDependencyFailure("group-name")` calls — the group name tells you which extra (and
+therefore which tox environment) is required.
+
+| TOX_ENV | uv extras | Test paths |
+|---|---|---|
+| `test` | _(none)_ | `test/io`, `test/run`, `test/utils/`, `test/models/test_auto_models.py` |
+| `test-data` | `data`, `cbottle` | `test/data`, `test/lexicon` |
+| `test-perturb` | `perturbation` | `test/perturbation` |
+| `test-stats` | `statistics`, `utils` | `test/statistics`, `test/utils/test_interp.py` |
+| `test-px-models` | `all` | `test/models/px` (except ACE2) |
+| `test-dx-models` | `all` | `test/models/dx` |
+| `test-da-models` | `all` | `test/models/da` |
+| `test-px-models-ace2` | `ace2` | `test/models/px/test_ace2.py` |
+| `test-serve` | `serve` | `test/serve` |
+
+> **Note**: The `test` environment also covers `test/models/test_batch.py` and
+> `test/utils/test_imports.py`. Check `tox.ini` for the full authoritative list.
+
+If the user has not specified a `TOX_ENV`, infer it from the file or feature being tested using
+the table above.
+
+## Running via tox (recommended)
+
+```bash
+make pytest TOX_ENV=<env>
+```
+
+tox handles the `uv sync --extra <extras>` automatically before running pytest.
+
+## Running a single test directly (faster, no tox overhead)
+
+First sync the required extras manually:
+
+```bash
+uv sync --extra <extras>   # e.g. uv sync --extra data,cbottle
+```
+
+Then run pytest directly:
+
+```bash
+uv run pytest test/path/to/test_file.py -v
+uv run pytest test/path/to/test_file.py -k "test_name" -v
+```
+
+Report the test results, including any failures with their tracebacks.