HANDOFF.md

# StoryCode — Handoff for the executing agent (Codex)

Full design rationale: `~/.claude/plans/so-uh-this-is-modular-curry.md`.
This file is the **do-this-next checklist**. Deadline: **2026-06-15**.

Read `AGENTS.md` first — it has the rules you must not break.

## What's already built & verified ✅

The whole app is written, and the **deterministic core is tested green**
(`python tests/test_analyzer.py` → 10/10, no GPU). The Gradio UI builds and every
panel renders. The only thing not yet exercised is the live model — because it
needs the Modal endpoint.

| File | State |
|---|---|
| `config.py`, `schema.py`, `ingest.py` (+ secret scan) | ✅ done & tested |
| `analyzer/` (`python_ast`, `js_treesitter`, `generic`, `graph`, `deps`, `__init__`) | ✅ done & tested — **the source of truth** |
| `diagram.py`, `story.py`, `narrate.py`, `db.py` | ✅ done; narration verified via the model-free fallback |
| `llm.py` | ✅ written; needs the live Modal endpoint to exercise the real path |
| `ui/theme.py`, `ui/styles.css`, `app.py` | ✅ written; UI builds. Needs a live `python app.py` run |
| `modal_app.py` (vLLM serving MiniCPM4.1-8B) | ✅ written; **you must deploy + version-pin it** |
| `zerogpu_backend.py` | ✅ break-glass fallback |
| `scripts/sample_project/`, `tests/test_analyzer.py` | ✅ done; tests pass |
| `README.md` (HF frontmatter+tags), `.env.example`, `requirements.txt` | ✅ done |

## Do these in order

1. **Deploy the GPU backend.**
   - In `modal_app.py`: confirm `VLLM_VERSION` against the **MiniCPM4.1-8B model
     card** (it uses custom code → `--trust-remote-code`). Set a real shared secret:
     `modal secret create storycode-api MODAL_API_KEY=<secret>`, then
     `modal token new` and `modal deploy modal_app.py`.
   - Smoke-test the endpoint:
     `curl -H "Authorization: Bearer <secret>" <url>/v1/chat/completions -d '{"model":"openbmb/MiniCPM4.1-8B","messages":[{"role":"user","content":"Reply with JSON {\"ok\":true}"}]}'`
   - **Risk:** MiniCPM4.1 is a *hybrid-reasoning* model. If it emits long `<think>`
     chains or ignores `guided_json`, (a) check the model card for the flag that
     disables thinking and add it to the vLLM args, and (b) confirm the installed
     vLLM version supports `xgrammar` guided decoding. The contract `llm.py`
     expects is a plain OpenAI `/v1/chat/completions` that honours
     `extra_body={"guided_json": ...}`.

2. **Wire secrets.** Copy `.env.example` → `.env` locally; on the Space set
   `MODAL_ENDPOINT_URL` (= `<url>/v1`) and `MODAL_API_KEY` (same shared secret).

3. **Run locally.** `pip install -r requirements.txt && python app.py`.
   Click **"Try the sample project"** → you should get a Story + Plain-English
   panel + a rendered Architecture Map + the Safe-to-Edit list + Dependencies.
   Switch styles/difficulty → the Story re-narrates (no re-analysis).

4. **Tune the narration prompts** in `story.py` (and only `story.py`) until the
   output is accurate AND in-voice for each of the 5 styles × 3 difficulties.
   This is the main creative loop and your clearest Codex-attributed work. Keep
   the grounding rule intact (the model narrates facts; it never invents files).
   Re-run `python tests/test_analyzer.py` after — it must stay 10/10.

5. **Real-user proof (Backyard AI requirement).** Run the friend's actual
   Claude-generated app through StoryCode. Capture: a quote from them, before/after
   screenshots, and the story it produced. Put these in the README.

6. **Deploy + submission assets.**
   - Create a Gradio Space under `build-small-hackathon`; push this repo; set the
     two secrets. Verify it reaches Modal (check Modal logs). **Test on mobile.**
   - Record a 60–90s demo video (upload → Story → Map → Safe-to-Edit); link in README.
   - Push to a public GitHub repo with **Codex-attributed commits**; link it in
     the README (OpenAI Codex prize requirement).
   - Post once on social; link it. Confirm README frontmatter tags are present.

## Post-MVP queue — only after steps 1–6 are deployed. One at a time.

In priority order (each is a clean, bounded task; details in the plan file):
1. **Grounded chat Q&A** — "Ask anything about your code", answered from the
   ProjectModel + summaries already in `gr.State` (no new analysis).
2. **"How do I change X?"** assistant → "file X, line Y, change Z to W."
3. **Error detective** — paste an error + file → detective-story fix.
4. **Dependency panel polish** — surface `analyzer/deps.py` risk flags more loudly.
5. **Save / revisit + Share** (wire `db.py` into the UI).
6. **Export story as PDF / Markdown.**
7. **GitHub URL ingestion** (add a `from_github` path to `ingest.py`).
8. **Before/after edit preview.**

## Gotchas
- **Don't** add `torch`/`vllm`/`transformers` to `requirements.txt` — the GPU is on
  Modal; the Space is a CPU container. (Those belong only in `modal_app.py`, or in
  the Space *only* if you switch to the ZeroGPU fallback.)
- Keep the UI custom (`ui/styles.css`) — Off-Brand badge + explicit requirement.
- **Don't claim Tiny Titan** — MiniCPM4.1-8B is ~8B, not ≤4B.
- The static analysis is the source of truth. Never let the model override the
  Architecture Map or the Safe-to-Edit verdicts. If you change `analyzer/`, update
  `tests/test_analyzer.py` to match and keep it green.