AGENTS.md

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 SourceFiles; 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).