# AGENTS.md — rules for any agent (Codex) working in this repo

StoryCode explains a non-coder's project to them as a story. Read `HANDOFF.md` for
the task list and `~/.claude/plans/so-uh-this-is-modular-curry.md` for the why.

## The one rule that defines this app
**Static analysis is the source of truth; the model only narrates it.**
`analyzer/` computes the real files, import edges, fan-in/out, roles, entry points,
and safe-to-edit verdicts. The language model (via `narrate.py` / `story.py`) writes
plain-English *about* those facts. Never let the model invent files, edges, or
safety verdicts, and never let model text override what `analyzer/` produced. The
Architecture Map (`diagram.py`) and Safe-to-Edit panel are built directly from the
ProjectModel — keep them that way.

## Architecture (where things live)
- `ingest.py` — zip/file → clean `SourceFile`s; **redacts secrets** before anything
  leaves it. All code text must pass through here first.
- `analyzer/` — the deterministic engine. `graph.py` owns edges, fan-in/out, roles,
  and the safe-to-edit logic. Touch with care; it's covered by tests.
- `narrate.py` — map (per-file) + reduce (project), with caching and a model-free
  fallback. `story.py` — the prompts. `llm.py` — the Modal/vLLM client.
- `app.py` + `ui/` — the Gradio UI. `modal_app.py` — the GPU backend.

## Hard constraints — do not violate
1. **No `torch` / `vllm` / `transformers` in `requirements.txt`.** The Space is a
   CPU container; the GPU lives on Modal (`modal_app.py`). The only exception is the
   ZeroGPU break-glass path, and only if you deliberately switch to it.
2. **Model ≤ 32B and it must be a MiniCPM** (OpenBMB prize). Default is
   `openbmb/MiniCPM4.1-8B`. Don't swap in a non-OpenBMB model as the core brain.
3. **Don't claim the Tiny Titan badge** (that needs all models ≤4B; ours is ~8B).
4. **Keep the custom UI** (`ui/styles.css`) — it's the Off-Brand badge and a user
   requirement. Don't fall back to the default Gradio theme.
5. **Secrets:** never display or send code without `ingest.redact_secrets` having
   run. Don't weaken the secret patterns.
6. **Tests stay green.** If you change `analyzer/`, update `tests/test_analyzer.py`
   and keep `python tests/test_analyzer.py` at 10/10 (or higher).

## Style conventions (match the existing code)
- `from __future__ import annotations`; PEP 604 unions (`str | None`); module
  docstrings that explain *why*, not just *what*.
- Keep functions small and pure where you can; parsing/analysis code never calls
  the network or the model.
- Prefer extending the curated map in `analyzer/deps.py` over adding a model call.

## What to work on
Only the next unchecked item in `HANDOFF.md`. Don't start post-MVP features until
steps 1–6 there are deployed. One feature per commit; write Codex-attributed
commit messages (the OpenAI Codex prize depends on them).