# Cursor and IDE agents — repository guidance

Use this file together with **[README.md](README.md)** (onboarding),
**[CLAUDE.md](CLAUDE.md)** (commands and patterns for Claude Code), and
**[AGENTS.md](AGENTS.md)** (full system reference, troubleshooting, configuration).

## What to read first

| Goal | Primary doc |
| --- | --- |
| Clone → run pipeline | [README.md](README.md) Quickstart, [docs/RUN_GUIDE.md](docs/RUN_GUIDE.md) |
| Exact shell commands, CI mirror, examples | [CLAUDE.md](CLAUDE.md) |
| Pipeline stages, validation, multi-project rules, deep TOC | [AGENTS.md](AGENTS.md) |
| Directory-specific APIs and conventions | `AGENTS.md` / `README.md` within that subdirectory (each `projects/<name>/manuscript/` has its own `AGENTS.md`) |
| Public project names (`infrastructure.project.public_scope`) | [docs/_generated/active_projects.md](docs/_generated/active_projects.md) |
| Live counts and coverage claims | [docs/_generated/COUNTS.md](docs/_generated/COUNTS.md) (refresh via measured `pytest` + [`scripts/docgen/active_projects.py`](scripts/docgen/active_projects.py); see [`docs/_generated/README.md`](docs/_generated/README.md)) |

## Architecture (non-negotiable)

- **Thin orchestrators:** Business logic belongs only in `infrastructure/` (generic)
  or `projects/{name}/src/` (domain). Root `scripts/` and `projects/{name}/scripts/`
  coordinate I/O, subprocesses, and plotting — they call tested functions; they do
  not own algorithms.
- **Layer 1:** `infrastructure/`, repo `scripts/`, `tests/infra_tests/`.
- **Layer 2:** Each active project under `projects/<name>/` with `src/`, `tests/`,
  `manuscript/`, `scripts/`, `output/`. Final deliverables are copied to `output/<name>/`.
- **Canonical exemplars** (always tracked, per `infrastructure.project.public_scope.PUBLIC_PROJECT_NAMES`): `template_active_inference`, `template_advanced_literature_review`, `template_autopoiesis`, `template_autoresearch_project`, `template_autoscientists`, `template_code_project`, `template_data_descriptor`, `template_eda_notebook`, `template_formal`, `template_gold_refinement`, `template_literature_meta_analysis`, `template_madlib`, `template_methods_paper`, `template_newspaper`, `template_pitch_deck`, `template_pools_rules_tools`, `template_prose_project`, `template_redacted_report`, `template_registered_report`, `template_search_project`, `template_sia`, `template_storybook`, `template_template`, `template_textbook`.
  Authoritative roster: `docs/_generated/active_projects.md`.
  Do not assume other folder names under `projects/` exist in every checkout; use discovery output above.
- **`output/` is disposable:** Both `projects/<name>/output/` and root `output/<name>/`
  are regenerated by the pipeline — do not commit their contents.

## Tooling

- **Python / deps:** `uv sync` at repo root. Prefer `uv run …` for every tool.
- **Pre-commit (matches CI lint for Python):** `ruff` + `mypy` on `infrastructure/`
  and `projects/*/src/`; **pre-push** adds no-mocks check, fast pytest smoke, Bandit
  (`bandit.yaml`), skills manifest check (all hooks are blocking — a failure prevents the push).
  See [.pre-commit-config.yaml](.pre-commit-config.yaml).
- **Adding dependencies:** `uv add <pkg>` at repo root for shared deps; use
  `uv add <pkg> --project projects/<name>` for project-local deps. Always run `uv sync` after.
- **Tests:** No mocks (`unittest.mock`, `MagicMock`, `mocker.patch`, etc.). Use real data,
  temp files, `pytest-httpserver` for HTTP, subprocess for CLIs. Infra coverage floor 60%,
  project src floor 90% (unless CI documents an exception for a rotating project — see
  `.github/AGENTS.md` and `.github/workflows/ci.yml` for current exceptions).

## Editing discipline

- Prefer **registry-backed** manuscript figures, equations, and variables over hard-coded
  numbers in prose when the project defines injectors.
- After adding, removing, or moving any folder under `projects/`, regenerate
  `docs/_generated/active_projects.md`: `uv run python scripts/docgen/active_projects.py`.
- Keep stage numbering and pipeline phrasing aligned across README, CLAUDE, AGENTS, and
  `infrastructure/core/pipeline/pipeline.yaml`.
- Touch only files and behaviour the user requested; avoid drive-by refactors.

## Agent memory (local only)

- Continual-learning writes to `.cursor/hooks/state/continual-learning-memory.json` only; never add Learned sections to root `AGENTS.md` (public-repo contract).

## Security and secrets

- Follow [docs/rules/security.md](docs/rules/security.md) and [bandit.yaml](bandit.yaml).
- Do not commit secrets, API keys, or machine-local paths into shared docs.