| # 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). |
|
|
