deploy

.gitignore

@@ -0,0 +1,52 @@
+# Byte-compiled files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Python build artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test and coverage output
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checker caches
+.mypy_cache/
+.ruff_cache/
+.pyright/
+
+# Local environment files
+.env
+.env.*
+
+# OS/editor files
+.DS_Store
+.idea/
+.vscode/
+*.wav
+!sample_session.wav
+
+# Offline research scratch — never ship to the Space (keeps the submission clean)
+research/
+research/traces/
+swe_chat_traces/
+distractor_runs/
+skill_eval_runs/
+run_swe_chat_phases_v2.py
+fetch_swe_chat_v2.py
+nebius_loader.py
+trace2skill_faithful.py
+promotion_engine.py
+gotcha_cluster.py
+session_store.py
+artifact_meta.py
+swe_chat_loader.py

CODEX_BUILD_LOG.md

@@ -0,0 +1,276 @@
+# Codex Build Log: TurboSkillSlug
+
+TurboSkillSlug was built as a small Gradio app with Codex acting as the primary coding partner. The project began as an empty repository and grew into a Hugging Face Space that accepts a build-session audio recording, transcribes it, extracts a structured recap, writes a draft `SKILL.md`, and generates a procedural SVG shell from the shape of the session.
+
+This log summarizes how Codex was used, what it implemented, where development got sticky, and what the project taught us.
+
+## Starting Point
+
+The first Codex work was straightforward scaffolding:
+
+- Created the Gradio app shell in `app.py`.
+- Added `requirements.txt`, `.gitignore`, and Hugging Face Space metadata in `README.md`.
+- Added the first tests under `tests/`.
+- Set up the basic "upload audio, return output" flow.
+
+That initial phase was the part Codex handled most naturally: file structure, simple UI wiring, dependency declarations, and tests.
+
+## Features Codex Implemented
+
+### Audio Transcription
+
+Codex added `transcribe.py` to send uploaded audio to `openai/whisper-large-v3-turbo` through Hugging Face. This went through several iterations:
+
+- Started with `InferenceClient`.
+- Pinned and adjusted Gradio and Python versions to handle Space launch issues.
+- Tried provider-specific routing and file-path based ASR calls.
+- Tried raw bytes and `BytesIO`.
+- Finally bypassed `InferenceClient` for transcription and used a direct `httpx` POST to the HF router with an explicit `Content-Type`.
+
+The final lesson was simple: for this ASR path, explicit HTTP was more reliable than fighting provider abstractions.
+
+### Session Extraction
+
+Codex added `extract.py` to call `Qwen/Qwen2.5-7B-Instruct` and produce:
+
+- `duration_minutes`
+- `themes`
+- `approaches_tried`
+- `dead_ends`
+- `breakthroughs`
+- `gotchas`
+- `sentiment_arc`
+- `skill_md`
+- `slug_voice`
+
+This became the emotional center of the project. The extraction prompt had to do more than produce valid JSON; it had to preserve the core promise of the app: the slug is a witness, not a generic summary writer.
+
+Codex iterated on:
+
+- strict JSON parsing
+- required output keys
+- constrained sentiment labels
+- graceful validation and patching for imperfect model output
+- structured `skill_md` sections
+- rules forcing `slug_voice` to reference transcript-specific moments
+- dead-end counting rules so smooth sessions stay smooth and messy sessions show their mess
+
+The final prompt removes copyable gold-set examples and instead describes behavior directly. That change came from testing: when examples were present, Qwen copied them verbatim across sessions.
+
+### Shell SVG Generation
+
+Codex added `shell.py`, a procedural SVG generator that turns session structure into visual form:
+
+- duration affects size and spiral complexity
+- approaches affect spiral density
+- dead ends become dark knots
+- gotchas become rim jewels
+- breakthroughs affect the glowing aperture
+- sentiment arc drives the color story
+
+Later commits polished the shell with nacre texture, rim glow, HSL palettes, and a central eye. This was where correctness alone was not enough; the shell had to feel demo-worthy.
+
+### Gradio App Wiring
+
+Codex wired the full pipeline in `app.py`:
+
+- upload or record audio
+- transcribe with Whisper
+- extract structured session data with Qwen
+- override duration with the real audio length
+- render the slug recap
+- render the shell SVG inline
+- expose raw JSON
+- write downloadable `shell.svg`, `skill.md`, and `slug_recap.txt`
+- include a sample session in the UI
+
+The interface became a two-column app: input on the left, recap and shell on the right.
+
+### Documentation And Deployment
+
+Codex helped maintain the README and deployment support:
+
+- Hugging Face Space frontmatter
+- model table and parameter count
+- shell interpretation table
+- demo and social links
+- tags for the Build Small hackathon
+- deployment script for HF Space remotes
+
+The history also includes deploy commits to Hugging Face Space remotes, separate from the main GitHub history.
+
+## Challenges During Development
+
+### Provider Routing Was Fragile
+
+The Hugging Face provider layer behaved differently for Whisper and Qwen. Whisper needed the `hf-inference` route at first, while Qwen needed automatic routing. Then Whisper still failed because content type was not being set correctly for audio bytes. The reliable fix was a direct `httpx` request.
+
+Codex was useful here because it could keep applying narrow fixes quickly, but the development lesson was to stop abstracting once the abstraction became the problem.
+
+### Gradio And Python Compatibility
+
+Several commits adjusted runtime compatibility:
+
+- pinned Python 3.12 to avoid `audioop` removal issues in Python 3.13
+- pinned and then bumped Gradio versions to fix schema and launch errors
+- added required Hugging Face Space metadata
+
+These were not glamorous changes, but they were the difference between a local idea and a deployable demo.
+
+### The Slug Voice Was The Hardest Part
+
+The most important failure was also the most instructive: the slug started copying example utterances word for word.
+
+The intent was to show tone, but the model treated the examples as content. That produced the exact failure mode the project was trying to avoid: a supposedly present witness saying generic lines that did not happen in the session.
+
+The prompt eventually moved away from examples and toward hard behavioral rules:
+
+- every line must reference this transcript
+- use concrete details such as tools, errors, variable names, and actions
+- never summarize, advise, or invent
+- if there is no evidence, stay silent
+
+That changed the prompt from "write in this style" to "obey this witness contract."
+
+### Validators Had To Be Gentle
+
+Early validation crashed when Qwen missed required `skill_md` sections. That was technically correct but bad product behavior. The app should still show the transcript, recap, shell, and downloads even if one structured field is imperfect.
+
+Codex changed the validators to patch or clamp where possible:
+
+- missing `skill_md` sections get stubbed with `_(not captured)_`
+- invalid sentiment values map to the closest allowed label
+- missing slug voice lines are padded rather than killing the whole request
+
+The lesson was to validate for resilience, not purity.
+
+### Dead Ends And Sentiment Needed Rubrics
+
+Testing three different scripts revealed extraction bias:
+
+- too few dead ends in messy sessions
+- invented dead ends in clean sessions
+- endings defaulting to `resolved`
+
+Codex added explicit rubrics so the model knew that:
+
+- every failed approach is a dead end
+- clean explorations should have no dead ends
+- quick pleasant sessions can end `joyful`
+- long draining sessions can end `exhausted`
+- `resolved` is only for a clear bug-fix arc
+
+This made the shell's visual grammar more honest, because the shell depends directly on those extracted features.
+
+## What Was Learned
+
+Codex was strongest when the task could be expressed as concrete code movement: scaffold this app, add this module, wire these outputs, parse this JSON, commit and push this exact fix.
+
+The human role mattered most where taste and truth mattered:
+
+- deciding what the slug should sound like
+- noticing when "technically valid" output felt false
+- tuning the shell from generated geometry into something delightful
+- deciding when a model failure should be patched instead of treated as fatal
+
+The project also showed that prompt engineering is product engineering. The prompt is not just instruction text; it is part of the app's behavior, reliability, and user trust.
+
+## Final Shape
+
+TurboSkillSlug now works as a complete small demo:
+
+1. The user uploads a narrated build session.
+2. Whisper transcribes it.
+3. Qwen extracts the session structure and writes the slug's witness lines.
+4. The app renders a recap and a procedural shell.
+5. The user can download the shell SVG, draft `SKILL.md`, and slug recap.
+
+The result is intentionally small, strange, and specific. Codex built most of the machinery. The repeated tests and corrections taught it where the machinery needed to become more honest.
+
+## Continued Development (post-MVP)
+
+After the audio-to-shell MVP described above, Codex carried the project through five
+more rounds of work. Each was a discrete, committed change with verification before
+push. The commit hashes below are the Codex-attributed history in the repo.
+
+### The Slug Speaks: Chatterbox TTS (commit 0d1a73f)
+
+Codex wired voice into the app so the slug does not just write its witness lines, it
+speaks them. The work added a `_speak_recap` function that posts the recap text to a
+Chatterbox TTS endpoint running on Modal, decodes the returned base64 audio into a
+`slug_speaks.wav`, and surfaces it through a new Gradio audio component labeled "the
+slug speaks." The recap always closes on the slug's signature line, "I was here."
+
+Codex verified with `py_compile` and the app test suite before pushing, then ran the
+deploy script to force-update both Spaces.
+
+### Readiness Feedback and Voice Deduplication (commit 57e0748)
+
+A round of product-quality fixes Codex handled cleanly: the upload control now gives
+visible readiness feedback so a premature click is impossible, a redundant SlugVoice
+call was removed, and the "I was here" signature was deduplicated by avoiding direct
+mutation of the `slug_voice` list. Small changes, but they are the difference between
+an app that feels finished and one that feels like a prototype.
+
+### Skill-Uplift Eval Suite (commit a3c65db)
+
+This is where the project gained a research spine. Codex committed a suite of three
+blind, calibrated evaluations measuring exactly when a generated `SKILL.md` changes a
+frontier model's behavior. The scripts use one model to answer and an independent
+model to judge the primary recommendation, with leak guards and saved raw generations
+for re-scoring.
+
+The finding was sharp and a little humbling: uplift depends on knowledge provenance,
+not task difficulty. General algorithmic skills gave 0.0 uplift because the model
+already holds that knowledge in its weights. Well-known engineering traps also gave
+0.0. Only novel, non-public rules produced uplift (+1.0, with rescues and no
+regressions). A skill file helps a frontier model only when it carries knowledge that
+could not have been in training data: private behavior, post-cutoff facts, project
+conventions, or genuine discoveries.
+
+One honest correction is recorded in the commit itself: an early signature-based
+scorer miscounted trap *warnings* as trap *failures*, and was replaced with a model
+judge of the primary recommendation. The novel cases are fictional by necessity, so
+the knowledge they test cannot already be in any model's weights.
+
+### First SceneGraph Lens: Turn the Shell in 3D (commit 508da94)
+
+Codex wired the first of a planned set of alternate renderers. The same session that
+produces the flat SVG shell now also drives a real 3D object you can orbit: a Three.js
+nautilus with iridescent nacre, where the spiral growth, the knots (dead ends), the
+glowing aperture (breakthrough), and the colour arc all come from the session data.
+This sits behind a deterministic SceneGraph layer, so the semantic description of the
+scene is separate from how any one lens renders it.
+
+The wiring included the package structure for the `scenegraph/` modules and their
+renderer. A later fix corrected the Three.js source to load from jsdelivr after the
+original CDN was blocked by the iframe sandbox, which had kept the 3D scene from ever
+initializing.
+
+### Compliance Guard for the 32B Cap (commit 0b42267)
+
+The hackathon requires every model the app depends on to stay under 32B parameters.
+The app was already compliant, the live path uses a 1.5B extractor on Modal plus
+Whisper, with a labeled Qwen-7B fallback, but Codex added a guard so a future edit
+cannot silently break that. `app.py` marks itself as the live app at startup, and
+`extract.py` checks the model name before each inference call. Anything over the cap
+raises immediately instead of shipping a violation. Offline evaluation scripts never
+enable the runtime flag, so their use of larger models for research is unaffected.
+
+The honest boundary of this guard is recorded too: it checks model names passed on the
+app side and cannot see inside the Modal endpoint, so the durable compliance fact is
+that the deployed serving endpoint runs Qwen2.5-1.5B and Whisper, which is verifiable
+from the Modal serve code.
+
+## What the Later Rounds Taught
+
+The MVP showed Codex was strongest at concrete code movement. The later rounds showed
+something more specific: Codex was reliable at carrying a precisely-described change
+all the way through verification and deploy, compile-check, run the app tests, commit
+with a real message, push, and force-update the Spaces, without dropping a step.
+
+The judgment calls still belonged to the human side: deciding that a skill file's value
+comes from provenance rather than difficulty, noticing that an eval scorer was counting
+the wrong thing, choosing to add a compliance tripwire before it was ever needed. Codex
+turned those decisions into committed, tested code quickly and faithfully. That division
+held across every round: the human decides what honest looks like, and Codex builds it.

EVAL_REPORT.md

@@ -0,0 +1,71 @@
+# Groundedness Eval: does the fine-tuned 1.5B hallucinate more than the 7B it replaces?
+
+TurboSkillSlug's whole promise is a witness that only says what it saw. So the
+extraction model has one job above all others: do not invent facts. This eval
+measures exactly that, comparing the shipped fine-tuned 1.5B LoRA against the
+Qwen-7B it replaced and against its own un-tuned 1.5B base, on 25 held-out
+transcripts the LoRA never saw in training.
+
+## Setup
+
+- **25 held-out transcripts** (never in the 167-pair training set).
+- **Three systems**, same prompt, same decoding (temp 0.3, top-p 0.9, 768 tokens):
+  prompted Qwen-7B, prompted Qwen-1.5B base, fine-tuned 1.5B LoRA.
+- **Two groundedness metrics per extracted fact** (approaches, dead ends,
+  breakthroughs, gotchas):
+  - *Lexical*: fraction of the fact's content words present in the transcript.
+  - *Semantic*: max cosine similarity of the fact's embedding to any sentence
+    window of the transcript (all-MiniLM-L6-v2), grounded if >= 0.55.
+- **Raw generations saved before scoring**, so the metric can be revised
+  without re-running the models.
+
+## Results
+
+| system          | semantic | lexical | mean sim | parse | facts |
+|-----------------|---------:|--------:|---------:|------:|------:|
+| prompted 7B     | 0.716    | 0.576   | 0.640    | 24/25 | 272   |
+| prompted 1.5B   | 0.565    | 0.390   | 0.567    | 21/25 | 140   |
+| **LoRA 1.5B**   | **0.762**| 0.378   | 0.649    | 21/25 | 195   |
+
+## What this shows
+
+**The fine-tuned 1.5B matches and slightly exceeds the 7B on semantic
+groundedness (0.76 vs 0.72), at roughly a third of the active parameters.**
+The mean per-fact similarity agrees (0.649 vs 0.640).
+
+The lexical and semantic metrics disagree sharply for the LoRA: it has the
+*lowest* lexical overlap (0.378) but the *highest* semantic groundedness
+(0.762). That gap is the point. The fine-tune taught the model to restate the
+transcript's meaning in its own words rather than copy spans. Word-overlap
+scoring punishes that; embedding scoring credits it. The LoRA paraphrases
+faithfully, which is what a good extractor should do.
+
+## What this does NOT show, and the caveats we are not hiding
+
+- **The LoRA is less reliable at producing valid JSON: 21/25 vs the 7B's
+  24/25.** That is a real cost of the smaller model. In the live app a
+  brace-walking parser and field validators recover most malformed output, but
+  the raw parse rate is what the table reports, unsoftened.
+- **The semantic threshold is imperfect.** A calibration block of six
+  hand-labeled cases (run before scoring, printed in the logs) passed 5/6: one
+  true paraphrase fell just under the 0.55 line. The single miss is a
+  *false negative* (a grounded fact scored ungrounded), which means the LoRA's
+  real groundedness is if anything *underestimated* here, not inflated. We
+  report the number the fixed threshold produced rather than tuning it after
+  seeing results.
+- **25 transcripts is a small sample.** Treat the gaps as directional, not
+  precise. The LoRA-vs-7B semantic difference is small enough that the honest
+  claim is "matches or slightly exceeds," not "beats."
+
+## Honest one-line summary
+
+A 1.5B LoRA fine-tune reaches 7B-level semantic groundedness on held-out
+sessions at a third the active size, by learning to paraphrase rather than
+copy; it pays for this with a lower valid-JSON rate (21/25 vs 24/25), and the
+metric itself is calibrated to within 5/6 on known cases.
+
+---
+
+*Reproduce:* `modal run semantic_eval.py`. Raw generations, per-fact scores,
+calibration outcome, threshold, and embedding model are all saved in
+`eval_results_semantic.json` and `eval_raw_outputs.json`.

EVAL_REPORT_TEMPLATE.md

@@ -0,0 +1,46 @@
+# Skill-Uplift Eval Report
+
+> Fill this in with the ACTUAL numbers from `run_skill_eval.py`. The template is
+> written so an honest result is the easy result. Do not delete the caveats.
+
+## Setup
+- Answerer model: `<EVAL_ANSWERER_MODEL>`
+- Grader model (blind, different vendor): `<EVAL_GRADER_MODEL>`
+- Skill generator: the shipped `skill_builder.build_skill_md`
+- Cases: N = `<n_scored>` (held-out tasks, each a DISTINCT problem in the same
+  class as its source session; leaked skills excluded: `<n_leaked_excluded>`)
+- Raw generations saved: `skill_eval_runs/` (anyone can re-score)
+
+## Grader calibration (run BEFORE trusting the uplift)
+- Agreement with human labels: `<X/Y>`
+- If agreement is low, the uplift number is unreliable; say so explicitly.
+
+## Result
+| condition | mean score |
+|---|---:|
+| no skill (baseline) | `<baseline_no_skill_mean>` |
+| with skill | `<with_skill_mean>` |
+| **uplift** | **`<uplift>`** |
+
+- Win / tie / loss across cases: `<wins>` / `<ties>` / `<losses>`
+- Per-case deltas: `<paste from runner>`
+
+## Honest reading (write the true one)
+Pick the sentence that matches the data; do not overstate:
+- Positive & consistent: "The generated skill produced measurable uplift
+  (+`<uplift>`) on held-out tasks in the same class, winning `<wins>`/`<n>`."
+- Small/mixed: "The skill produced small, inconsistent uplift (+`<uplift>`);
+  it helped on `<wins>` cases and was neutral/negative on the rest."
+- Near-zero: "On this set, the skill did not produce measurable uplift over the
+  frontier baseline. The baseline was already strong (`<baseline>`), leaving
+  little headroom; a harder task set would test this better."
+
+## Caveats (keep all that apply)
+- Small N; indicative, not a benchmark (same posture as the 25-transcript
+  groundedness eval).
+- Single grader model; blinding reduces but does not remove grader bias, hence
+  the calibration check above.
+- Uplift depends on task difficulty: where the baseline already scores ~1.0 there
+  is no room to show uplift. Baseline headroom is reported so this is visible.
+- Skills that leaked the task answer were excluded (`<n_leaked_excluded>`),
+  not silently scored.

FINDINGS.md

@@ -0,0 +1,65 @@
+# When does a SKILL.md actually help a 2026 frontier model? (measured)
+
+Three blind, calibrated evals against `anthropic/claude-opus-4.6` (answerer) and
+`openai/gpt-5.1` (independent judge). Raw generations saved; method below.
+
+## The result in one table
+
+| Skill content | Held-out task class | Avoidance / score WITHOUT skill | WITH skill | Uplift |
+|---|---|---:|---:|---:|
+| General algorithmic procedure | standard tree-DP, Markov absorption | 1.0 | 1.0 | **0.0** |
+| Well-known engineering traps | Kahan summation, check-then-act race, N+1 query | 1.0 | 1.0 | **0.0** |
+| Novel / non-public rules | fictional APIs (zthrumdb fence, qbucket reset, flazon reversal) | 0.0 | 1.0 | **+1.0** |
+
+3 rescues, 0 regressions in the novel-trap condition. Grader calibration 3/3.
+
+## What this means (the actual finding)
+
+A frontier model's weights already contain the public, written-down corpus of
+software knowledge. A skill file that repeats any of it gives **zero** uplift,
+confirmed twice, on both easy tasks and famous footguns the model handles unaided.
+
+A skill file gives **large** uplift exactly when it carries knowledge that could
+NOT have been in the training data: private/proprietary system behavior, post-cutoff
+facts, project-specific conventions, or genuinely novel discoveries. The dividing
+line is not task difficulty. It is **whether the knowledge could have been public.**
+
+### A second, sharper observation from the raw data
+
+In the unaided novel cases, the model did not just answer wrong, it often went
+**"unclear": it hedged, asked for clarification, or refused to use the unknown API.**
+A frontier model senses when it lacks the knowledge and stalls. The skill does not
+merely correct wrong answers; it **unblocks the model on systems it otherwise cannot
+act on at all.** That is the higher-value case: not "answer better," but "able to
+proceed where it was previously stuck."
+
+## Why this is the honest, useful framing for TurboSkillSlug
+
+The slug's value is NOT in summarizing a session of standard work, that produces a
+skill the model ignores (uplift 0.0). The value is in capturing the **negative,
+private, non-obvious knowledge** from a real session: the trap specific to this
+codebase, the undocumented behavior, the dead end that cost an hour. Fed that, the
+generated SKILL.md measurably changes a frontier model's behavior (+1.0).
+
+This is a sharper claim than "skills help," and we can defend every part of it with
+data and published raw outputs.
+
+## Method (anti-self-deception safeguards)
+
+- Held-out tasks DISTINCT from the source session (transfer, not memorization).
+- Blind judge: a DIFFERENT vendor's model, scoring the answer's PRIMARY
+  recommendation, with "warns about the trap then gives the fix" counted as CORRECT.
+  (An earlier signature-matching scorer was discarded because it miscounted
+  warnings as failures; the LLM judge fixed this. We report the correction.)
+- Leak guard: any skill containing the literal task answer is excluded.
+- Calibration run before trusting numbers (grader agreed with human labels 3/3).
+- Raw generations saved before scoring; small N, reported as indicative not a benchmark.
+
+## Honest limitations
+
+- Small N (2-3 per condition). Indicative, not a benchmark. The effect sizes
+  (0.0 vs 1.0) are large and consistent, but the sample is small.
+- Single answerer + single judge model. Blinding and a cross-vendor judge reduce
+  but do not eliminate model-specific effects.
+- The novel cases are fictional by necessity (to guarantee non-derivability); they
+  stand in for real private/proprietary knowledge, which is the production case.

HONEST_SUBMISSION.md

@@ -0,0 +1,125 @@
+# Honest Submission Notes — TurboSkillSlug
+
+This document is the unvarnished account of what TurboSkillSlug actually does,
+what is genuinely strong, what is partial, and what is aspirational. If a claim
+is not in here with its caveats, treat the marketing copy as marketing.
+
+Demo video: https://youtu.be/qSP9olWRv7o
+Space: https://huggingface.co/spaces/build-small-hackathon/TurboSkillSlug
+Code: https://github.com/AnubhavBharadwaaj/turbo-skill-slug
+
+## What it does, honestly
+
+You give the slug a build session two ways: narrate it aloud (audio), or drop a
+Claude Code / Codex CLI session trace (`.jsonl`). It transcribes/parses, extracts
+a structured record, and returns four artifacts: a transferable SKILL.md, a
+grounded second-person recap in a fine-tuned "slug voice," a procedural SVG shell,
+and a thermal receipt. The shell is born on screen as a scroll that unrolls along
+its spiral arm, with a byōbu (folding-screen) battle drawn across it.
+
+## What is genuinely strong
+
+- **Two custom 1.5B LoRA adapters, both published and both used.** Voice
+  (500 pairs, loss 0.89) and extraction (167 pairs, loss 0.81). The extraction
+  LoRA replaced a prompted Qwen-7B, bringing the primary pipeline to ~2.6B active
+  params (Whisper 809M + one 1.5B base serving both adapters on a single T4).
+- **The groundedness eval is real and published with its raw data.** On 25
+  held-out transcripts the fine-tuned 1.5B reaches semantic groundedness 0.76 vs
+  the 7B's 0.72, at a third the active size, by paraphrasing rather than copying.
+- **The shell is fully procedural and traceable.** Every visual element derives
+  from a real session feature: dead ends are knots/fallen warriors, gotchas are
+  jewels/archers, the breakthrough is the aperture/dragon, sentiment is the color
+  arc. No image generation.
+- **The SKILL.md is built for real uplift**, gotchas-first (symptom→cause→fix),
+  "what does NOT work and why," transferable principles. Built and de-leaked
+  deterministically from the structured extraction, not trusted to model prose.
+- **Trace input works.** A real Claude Code or Codex session log runs through the
+  same pipeline as audio. Judges can feed their own logs.
+- **Graceful degradation is real and now observable.** If the extract adapter
+  emits invalid JSON, the 7B fallback catches it. If the voice adapter is down, a
+  deterministic extraction-based voice net prevents placeholder recaps. Every
+  voice-path outcome is logged with a `[VOICE]` tag (EXTRACT_DOWN / VOICE_DOWN /
+  VOICE_EMPTY / VOICE_OK / FALLBACK_VOICE_OK / NET_FROM_EXTRACTION / …) so failures
+  are diagnosable, not mysterious.
+
+## What is partial or has real caveats
+
+- **Extraction parse reliability: 21/25 vs the 7B's 24/25.** The smaller model
+  produces invalid JSON more often. In the app a brace-walking parser and field
+  validators recover most of this, and the 7B fallback catches the rest, but the
+  raw rate is a real cost of going small, and we report it unsoftened. (You will
+  see `[VOICE] EXTRACT_DOWN` in the logs when this fires; the fallback then runs.)
+- **The groundedness metric is calibrated to 5/6, not 6/6.** A hand-labeled
+  calibration block (run before scoring, printed in the logs) missed one case:
+  a grounded paraphrase scored just under threshold. The miss understates the
+  LoRA rather than inflating it. 25 transcripts is a small sample; treat the
+  LoRA-vs-7B gap as "matches or slightly exceeds," not "beats."
+- **SKILL.md quality depends on extraction quality.** A good session yields
+  transferable gotchas; a thin session yields thinner ones. An optional one-shot
+  enrichment pass expands terse gotchas, gated by env and best-effort. We caught
+  and fixed a real bug where few-shot examples in the enrichment prompt leaked
+  into output (a game-theory skill got tree-coloring gotchas); the prompts are
+  de-leaked and a guard now rejects any leaked phrasing.
+- **The scroll-unroll animation ships ~1.7MB per shell** (14 stacked growth
+  stages, so the parchment lays down ALONG the spiral arm rather than as a radial
+  wipe). Browser-rendered via SMIL in a sandboxed iframe, with a "watch it unroll
+  again" replay. On a slow connection the first paint takes a beat. If SMIL fails,
+  the full shell still shows (nothing is hard-hidden); animation is enhancement,
+  not a dependency.
+- **The 3D paper curl rides the spiral tip via animateMotion.** Verified
+  frame-by-frame in offline renders (cairosvg + headless Chromium). Exact
+  tip-tracking in every browser is the part most likely to need a small tweak.
+
+## What was freshly added near the deadline (use with that in mind)
+
+- **Shared terrarium gallery.** Kept shells save to a Modal Volume; a grid shows
+  all of them newest-first; each has a complete clickable permalink that re-loads
+  and re-animates that shell. Freshly built and lightly tested. Honest caveats:
+  each grid card is its own iframe, so past ~30-40 shells the grid gets heavy
+  (lazy-loading is the fix, not yet done). Gallery saves depend on the Modal
+  endpoint URLs matching the client; if they drift, a save fails and the UI says
+  so rather than failing silently.
+- **Battle Trace (experimental).** A temporal replay of the same session as a war
+  between you (the Agent) and the Environment, fed by the SAME extraction (no
+  second parser, no OTel). Framed as complementary to the shell: the shell is the
+  slug's *memory* of how the battle ended (the frozen folding screen); the trace
+  is the *replay* of it in time. It is Canvas-2D with simple figurative
+  combatants (a samurai general, a horned adversary, fallen warriors, a dragon at
+  the breakthrough). Honest about its level: these are clean vector figures, not
+  game-quality sprite art. Labeled "experimental" in the UI.
+
+## What is aspirational / not built
+
+- **Session diff view** (compare two sessions' shells) is not built.
+- **Closing the parse-rate gap** needs more training pairs and constrained
+  decoding; not done.
+- **Higher-fidelity Battle Trace art** (detailed sprite-grade samurai) is not
+  built; the current figures are deliberately simple vector shapes (see the
+  Battle Trace note above).
+
+## Infrastructure honesty
+
+- The Qwen-7B still exists in the codebase but ONLY as a labeled fallback when the
+  Modal extract path returns nothing usable (including the invalid-JSON case
+  above). The primary path is the 1.5B dual adapter. The README architecture table
+  reflects this.
+- The dual-adapter server can hold one warm container for demo reliability
+  (~$0.60/hr). It should be stopped after judging (`modal app stop
+  slug-dual-serve`).
+
+## How to verify our claims
+
+- Groundedness: `modal run semantic_eval.py` reproduces the table; raw
+  generations are published in the eval dataset so anyone can re-score.
+- Trace input: drop the sample `.jsonl` (one click) or your own session log.
+- Models: both LoRA adapters are public on the Hub.
+- Shell traceability: change a session's sentiment or dead-end count and watch
+  the shell's colors and knots change accordingly.
+- Failure handling: the Space logs tag every voice-path outcome with `[VOICE]`.
+
+## The one-sentence honest summary
+
+A small, slow, genuinely ~2.6B pipeline that turns a coding session into a
+transferable skill, a grounded recap, and a procedural shell, measured honestly
+(including where the small model costs us), with graceful, observable degradation,
+and every model and the eval data published for anyone to check.

INTEGRATION.md

@@ -0,0 +1,95 @@
+# Integrating the three phases into the live slug
+
+All modules are dependency-light, frozen-model, and run on the Space. They reuse the
+existing extraction and the OpenRouter/HF completer you already have.
+
+## Files
+- artifact_meta.py        Phase 1: lifecycle metadata (provenance/confidence/usage/validation)
+- rule_phrasing.py        Phase 1: RuleShaping negative-constraint phrasing (LLM + deterministic fallback)
+- session_store.py        Phase 2: store of past sessions (JSON; use the Modal volume in prod)
+- gotcha_cluster.py       Phase 2: cluster recurring gotchas (embedding or LLM-judge backend)
+- promotion_engine.py     Phase 2: promote recurring clusters -> validated L3 rules; demote on failure
+- multi_analyst_extract.py Phase 3: Trace2Skill-style N-analyst recurrence merge (higher-fidelity extraction)
+
+## Wiring (minimal)
+
+1. After each session's extraction, persist it:
+       store = SessionStore("/vol/gallery/sessions.json")   # Modal volume in prod
+       store.add(session_id, extraction)
+
+2. Phase 3 (optional, improves fidelity): replace single-pass gotcha extraction with
+       gotchas = multi_analyst_gotchas(session_text, completer, n_analysts=4,
+                                       had_errors=bool(extraction.get("dead_ends")),
+                                       agree_min=2, judge_same=same_gotcha_judge)
+   Cost knob: n_analysts (3–5 cheap; larger = higher fidelity, higher cost).
+
+3. Phase 2 (the headline): run a promotion pass (cheap; do it after add, or on idle):
+       rules = promote(
+           store, k_threshold=3,
+           cluster_fn=lambda items: cluster_by_judge(items, same_gotcha_judge),
+           reshape_fn=lambda g: to_negative_constraint_llm(g, completer),
+           validate_fn=rule_validates,          # reuse the distractor/novel eval harness
+           require_human=False,                 # set True for the 10/10 human-gated path
+       )
+   Persist promoted rules (with their ArtifactMeta) alongside sessions.
+
+4. Surface a new lens in the app: "the rules the slug has learned across your
+   sessions" — list each L3 rule with its provenance (which sessions), confidence,
+   and last-validated time. This is the lifecycle-governance story made visible.
+
+## The validation gate (important — don't skip)
+`validate_fn(rule_text, cluster)` should reuse the held-out check you already built
+(distractor_eval / novel_eval): does an answer that APPLIES the rule beat one that
+ignores it, on a task derived from the cluster? Promoting without this is how you
+promote "compact noise" (the spectrum paper's exact warning). Gate-only is the
+default; `require_human=True` adds confirmation for the 10/10 path.
+
+## What to claim (honestly)
+"Single self-generated skills give a frontier model ~0.0 uplift (our eval, matching
+SkillsBench as cited in arXiv:2604.15877). We implement a working slice of that
+paper's proposed solution — the 'missing diagonal' of adaptive upward compression:
+the slug consolidates gotchas that recur across sessions into validated,
+negative-constraint-phrased L3 rules (RuleShaping) carrying provenance/confidence/
+lifecycle metadata, with demotion when a rule stops validating, and Trace2Skill-style
+multi-analyst recurrence-merging for extraction fidelity. Honest limits: recurrence
+is a proxy for value (mitigated by the validation gate + optional human confirmation);
+small analyst-N is a cheaper approximation of Trace2Skill's 128."
+
+---
+
+## CORRECTIONS after reading the actual papers (not just the survey)
+
+- Phase 3 was rebuilt as `trace2skill_faithful.py` after reading arXiv:2603.25158 in
+  full. The first version (`multi_analyst_extract.py`) was a simplified guess that
+  MISSED the paper's central mechanism: the error analyst is an AGENTIC, VALIDATION-
+  GATED loop (it must produce a verified causal cause or the trace is EXCLUDED), not a
+  single call. The paper shows the single-call version over-attributes parse errors as
+  root cause in 57% of cases and hallucinates causes — i.e. the leak/false-cause bug.
+  Consolidation is an LLM merge operator applied hierarchically with a prevalent-
+  pattern bias; success patches are lower-trust; low-support items route to references/.
+  Use `trace2skill_faithful.py`; keep `multi_analyst_extract.py` only as the simpler
+  fallback if the agentic loop is too costly on the Space.
+
+- RuleShaping verified against arXiv:2604.11088 ("Do Agent Rules Shape or Distort?").
+  Confirmed: +7–14pp, negative constraints the only beneficial type, positive
+  directives hurt. Added nuance: rules work via CONTEXT PRIMING (random ~ curated),
+  state-dependent process guardrails ("don't X until Y") are the highest-benefit
+  category (63.8%), and rules are collectively helpful even when individually inert
+  (no degradation up to 50). `rule_phrasing.py` now biases toward state-dependent
+  negative guardrails.
+
+## REMAINING GAPS (do not overclaim)
+
+1. CLUSTERING IS UNVALIDATED ON REAL DATA. The promotion engine works when the
+   "same underlying gotcha" judge is good. On arbitrary messy sessions, clustering
+   quality is unknown — a bad judge promotes noise or misses recurrences. This is the
+   biggest open risk and needs a real embedding/LLM judge tested on labeled session data.
+
+2. THE ERROR-ANALYST VALIDATION GATE is faithful in STRUCTURE but ADAPTED: the paper
+   runs a minimal fix against ground truth in a sandbox. A narrated coding session fed
+   to the slug usually has no ground truth / sandbox, so we use strict self-verification
+   (cite trace evidence) instead. This is weaker than the paper's executable gate and
+   should be labeled as an adaptation, not a reproduction.
+
+3. NO END-TO-END RUN ON REAL SLUG SESSIONS YET. Everything is validated on controlled/
+   realistic-but-synthetic data. Whether real slug sessions cluster usefully is untested.

METHODOLOGY.md

@@ -0,0 +1,66 @@
+# Skill-Uplift Eval — methodology (read before trusting any number)
+
+## The claim we are testing
+
+A generated SKILL.md gives a capable LLM real uplift on a *related future task*,
+over that same model solving the task with no skill. This is the judge's bar:
+"useful even to a frontier model that is already capable without it."
+
+## Why this is hard to measure honestly (and how we handle each trap)
+
+1. **Confounding by model strength.** A strong model may ace the task with or
+   without the skill, hiding any uplift. We pick tasks at the *edge* of the
+   model's ability (it sometimes fails them unaided), where a skill can move the
+   needle. We report the unaided baseline pass rate so the headroom is visible.
+
+2. **Leakage / circularity.** If the eval task is the *same* problem the skill was
+   built from, the skill is just an answer key — meaningless. So the held-out task
+   is a DIFFERENT problem in the SAME class as the session. The skill must
+   transfer, not memorize. We state the session→task pairing explicitly.
+
+3. **Grader bias.** A grader that sees which answer used the skill will favor it.
+   The grader is BLIND: it receives the two answers in randomized order with the
+   condition labels stripped, and judges only correctness/quality.
+
+4. **Cherry-picking.** We fix the task set and the sessions BEFORE running, list
+   them here, and report every item including failures. No post-hoc dropping.
+
+5. **The "skill is just hints" objection.** A skill that smuggles the answer is not
+   uplift, it's cheating. We verify each skill contains transferable PROCEDURE
+   (gotchas, what-not-to-do), not the specific solution to the eval task. Any
+   skill whose gotchas name the eval task's exact answer is disqualified and noted.
+
+## Design
+
+- N sessions, each paired with a DISTINCT held-out task in the same problem class.
+- For each task, the SAME model answers twice:
+    A) NO-SKILL: task only.
+    B) WITH-SKILL: task + the SKILL.md generated from the paired session.
+  Order of which is generated first is irrelevant (separate calls), but the two
+  answers are handed to the grader in RANDOM order with labels stripped.
+- A blind grader (a separate strong model) scores each answer 0..1 on task success,
+  not knowing which had the skill. We also run a small HUMAN-labeled calibration
+  set first (like the groundedness eval) to check the grader agrees with us.
+- Uplift = mean(with_skill_score) - mean(no_skill_score). We report:
+    - per-task scores (both conditions),
+    - the unaided baseline (headroom),
+    - the win/tie/loss count (how often skill helped / didn't / hurt),
+    - the calibration agreement,
+    - and the raw generations, saved to disk, so anyone can re-score.
+
+## What an honest result looks like
+
+We commit IN ADVANCE to reporting the number as-is. Possible honest outcomes:
+  - Clear positive uplift -> the skill works; report it.
+  - Near-zero uplift -> the skill is pleasant but not load-bearing; say so.
+  - Negative on some tasks -> the skill sometimes misleads; report which and why.
+Any of these is a credible result. Only a hidden or massaged number is not.
+
+## Honest limitations (stated up front)
+
+- Small N. This is an indicative eval, not a benchmark. We report N and treat the
+  result as directional, exactly as we did with the 25-transcript groundedness eval.
+- Single grader model. Grader bias is reduced by blinding but not eliminated; the
+  calibration set is how we keep ourselves honest about it.
+- Task-class choice matters. We pick classes where a skill *could* plausibly help
+  (procedural/gotcha-heavy domains); we do not claim uplift on trivia.

README.md

@@ -0,0 +1,328 @@
+---
+title: TurboSkillSlug
+emoji: 🐌
+colorFrom: purple
+colorTo: yellow
+sdk: gradio
+sdk_version: "6.16.0"
+python_version: "3.12"
+app_file: app.py
+pinned: false
+short_description: Turn a coding session into a skill, recap, and shell.
+tags:
+  - hackathon
+  - build-small-hackathon
+  - track:wood
+  - sponsor:openai
+  - sponsor:modal
+  - achievement:welltuned
+  - achievement:offbrand
+  - achievement:fieldnotes
+models:
+  - legendarydragontamer/slugvoice-qwen2.5-1.5b-lora
+  - legendarydragontamer/slugextract-qwen2.5-1.5b-lora
+  - Qwen/Qwen2.5-1.5B-Instruct
+  - openai/whisper-large-v3-turbo
+datasets:
+  - legendarydragontamer/turboskillslug-groundedness-eval
+---
+
+# TurboSkillSlug
+
+**Feed it a coding session. Get back a reusable SKILL.md, a grounded spoken
+recap, and a procedural shell that encodes the whole session as art.**
+
+The session goes in one of two ways: narrate it aloud, or drop a real Claude Code
+or Codex CLI session log (`.jsonl`). A fine-tuned 1.5B model extracts what you
+tried, what failed, and what finally worked. Total active pipeline: **~2.6B
+parameters**, measured to match a 7B on groundedness at a third the size.
+
+Then the slug gives you four things:
+
+1. **A SKILL.md** another LLM can actually use: the non-obvious gotchas
+   (symptom → cause → fix), the approaches that fail and why, the breakthrough.
+   Built to give a frontier model real uplift, not a session summary.
+2. **A spoken recap** in a fine-tuned "slug voice," every line grounded in
+   something that happened, never reciting invented numbers.
+3. **A shell** whose spiral, knots, jewels, and colors all derive from your
+   session, born on screen as a scroll that unrolls along its own arm, with a
+   byōbu-style battle inked across it (dead ends are fallen warriors, the
+   breakthrough is a dragon).
+4. **A receipt** like a thermal printout: approaches tried, dead ends, mood.
+
+### The slug witnesses every kind of session, not just debugging
+
+Most coding sessions are not bug hunts. They are exploring an unfamiliar repo,
+writing docs, setting up tooling, building a feature. A witness that only has
+eyes for "what broke and what fixed it" leaves those sessions with a hollow
+shell.
+
+So the slug detects the session's genre (debugging, exploration, authoring,
+feature, refactor, setup) and witnesses the right thing for each:
+
+- debugging → the struggle: dead ends and the breakthrough
+- exploration → the discoveries: the non-obvious facts learned about the codebase
+- authoring → the decisions, and the false assumptions caught before they became wrong docs
+- feature / refactor / setup → what was built or changed, and what would break if done naively
+
+The shell's vocabulary adapts with it: for an exploration session the rim jewels
+are discoveries, the aperture is the clearest insight. Genre detection is pure
+pattern-matching: no model call, no added latency.
+
+Why this matters concretely: on a real exploration trace, the slug surfaced that
+a project's checkpoint mirror uses a custom git ref namespace
+(`refs/entire/...`) that a standard `git fetch --all` will miss. That is exactly
+the kind of private, non-derivable knowledge a SKILL.md exists to carry, and it
+came from a session that had no "bug" at all.
+
+Every shell is unique because every session is unique.
+
+## Try it in one click
+
+Two tabs, two sample inputs:
+
+- **narrate aloud** — a sample build session (audio)
+- **drop a session trace** — a sample Claude Code `.jsonl` trace
+
+Or bring your own: upload a recording, or drag a real session log from
+`~/.claude/projects/.../*.jsonl` or `~/.codex/sessions/.../*.jsonl`. Judges can
+feed their own agent logs and watch the slug read them.
+
+## Demo
+
+Watch the demo: **[youtu.be/qSP9olWRv7o](https://youtu.be/qSP9olWRv7o)**
+
+## Social
+
+The launch post: **[x.com/anubhav27071997](https://x.com/anubhav27071997/status/2063970171010826540)**
+
+## Why this is hard the right way
+
+The slug's entire promise is a witness that only says what it saw. That makes
+**groundedness** the core engineering problem: a small model that invents facts
+is worthless here. So we measured it, honestly, and published the data.
+
+### Groundedness: does the small model hallucinate more than the 7B it replaced?
+
+On 25 held-out transcripts, comparing the shipped fine-tuned 1.5B against the
+Qwen-7B it replaced and its own un-tuned 1.5B base:
+
+| system | semantic groundedness | lexical | parse | facts |
+|---|---:|---:|---:|---:|
+| prompted 7B | 0.716 | 0.576 | 24/25 | 272 |
+| prompted 1.5B base | 0.565 | 0.390 | 21/25 | 140 |
+| **fine-tuned 1.5B LoRA** | **0.762** | 0.378 | 21/25 | 195 |
+
+The fine-tuned 1.5B **matches and slightly exceeds the 7B (0.76 vs 0.72) at a
+third of the active size.** It does this by paraphrasing rather than copying:
+lowest lexical overlap, highest semantic groundedness, the signature of a model
+that restates meaning instead of echoing words.
+
+Reported with its costs, not spun: the LoRA produces valid JSON less often
+(21/25 vs 24/25), and the semantic metric passed 5/6 hand-labeled calibration
+cases (the one miss understates the LoRA, not the reverse). 25 transcripts is a
+small sample, so the honest claim is "matches or slightly exceeds," not "beats."
+Raw generations and per-fact scores are published so anyone can re-score:
+[turboskillslug-groundedness-eval](https://huggingface.co/datasets/legendarydragontamer/turboskillslug-groundedness-eval).
+
+## The SKILL.md is the real gift
+
+A skill file is only worth shipping if it helps an LLM that is already capable
+without it. A summary does not. So the SKILL.md is built to carry the
+**non-obvious, transferable** knowledge a frontier model cannot derive on its own:
+
+- **Gotchas as symptom → cause → fix**, not labels. "Processing leaf nodes first
+  looks natural but breaks because a parent depends on its children being
+  finalized; process deepest-first" — not "ordering unclear."
+- **What does NOT work, and why**, so the model skips the dead ends you already
+  paid for.
+- **Transferable principles** distilled from the arc, not a diary of the session.
+- **A negative guardrail under each gotcha**, phrased as a "do not X / verify Y
+  before assuming" rule. This follows the 2026 RuleShaping finding that negative,
+  state-dependent guardrails are the rule type that actually helps a model, and
+  it is generated deterministically with no model call.
+
+Terse gotchas are expanded by an optional one-shot pass, guarded so example
+phrasing can never leak into output.
+
+## How the shell reads your session
+
+| What happened | How the shell shows it |
+|---|---|
+| Duration | Overall size and number of spiral turns |
+| Each approach tried | Spiral arm density |
+| Each dead end | A dark knot — and a fallen warrior in the battle layer |
+| The breakthrough | The glowing aperture at the tip — and a dragon |
+| Gotchas | Iridescent jewels along the rim — and archers |
+| Your emotional arc | Color gradient from start to end |
+
+A frustrated session ending in relief is red-to-green. A curious exploration
+ending in delight is warm gold. A long grind is cold blue-grey. The color story
+is the emotional story.
+
+Procedural SVG: nacre texture filters, HSL color harmonies, bezier-smoothed
+curves. **No diffusion, no image generation.** Every pixel traces to a real
+session feature, which is the whole point: if a diffusion model drew the shell,
+"this knot is your dead end" would stop being true. The shell is born as a scroll
+unrolling along its spiral arm, led by a 3D paper curl, with the byōbu battle
+inking on as the parchment is laid. There is a "watch it unroll again" replay.
+
+Kept shells go into a **shared terrarium** (gallery): a living collection where
+every shell is the fingerprint of a real session, each with a `?shell=<id>`
+permalink.
+
+## Architecture
+
+The full primary pipeline runs on Modal at **~2.6B active parameters**. The
+Qwen-7B is a labeled fallback only, not on the primary path.
+
+| Component | Model | Params | Infrastructure |
+|---|---|---|---|
+| Transcription | `openai/whisper-large-v3-turbo` | 809M | Modal T4 |
+| Feature extraction | `slugextract-qwen2.5-1.5b-lora` | 1.5B | Modal T4 (shared) |
+| Slug voice | `slugvoice-qwen2.5-1.5b-lora` | 1.5B | Modal T4 (shared) |
+| Spoken recap | Chatterbox TTS | ~300M | Modal A10G |
+| Genre detection | Pattern matching (no model) | 0 | CPU |
+| Shell + Receipt | Procedural SVG (no model) | 0 | CPU |
+| Extraction fallback | `Qwen/Qwen2.5-7B-Instruct` | 7B | HF Inference (fallback only) |
+
+**Two custom LoRA adapters, one base model, one T4.** Both adapters are
+fine-tunes of Qwen2.5-1.5B-Instruct, loaded onto a single base on a single T4 and
+switched per request, so the whole language pipeline runs on one GPU.
+
+- **SlugVoice** ([adapter](https://huggingface.co/legendarydragontamer/slugvoice-qwen2.5-1.5b-lora)):
+  500 hand-crafted (transcript snippet, slug observation) pairs. Loss 4.97 → 0.89.
+- **SlugExtract** ([adapter](https://huggingface.co/legendarydragontamer/slugextract-qwen2.5-1.5b-lora)):
+  167 balanced (transcript, structured-JSON) pairs across 14 sentiment arcs.
+  Loss 1.88 → 0.81. Replaces the Qwen-7B extractor; brings the pipeline to ~2.6B.
+
+## How Modal is used
+
+1. **Fine-tuning.** Both LoRAs trained on Modal (A10G). SlugExtract on a pure
+   transformers + PEFT + bitsandbytes stack.
+2. **Serving.** Whisper on a T4; both LoRAs on a single shared T4 via PEFT
+   multi-adapter, switched per request. Kept-warm containers (one always-on plus
+   a buffer) for demo reliability.
+3. **TTS.** Chatterbox on an A10G speaks the recap.
+4. **Evaluation.** The groundedness eval (three models, 25 transcripts, two
+   metrics) runs as a Modal job, persisting raw generations to a Volume.
+5. **Gallery.** The shared terrarium's save/list/fetch endpoints run on Modal,
+   backed by the same Volume.
+
+If the primary extraction misses, the app retries on the same small model and
+otherwise degrades to a clear message, so it never crashes mid-render.
+
+## Built with OpenAI Codex
+
+Built using [OpenAI Codex](https://openai.com/codex) as the primary coding agent.
+Full commit history:
+**[github.com/AnubhavBharadwaaj/turbo-skill-slug](https://github.com/AnubhavBharadwaaj/turbo-skill-slug)**
+
+Codex handled scaffolding, the Gradio skeleton, the shell SVG geometry, tests,
+dependency wiring, and deployment fixes. Human judgment went into the slug's
+voice, the shell's visual design, the grounding constraints, and the two LoRA
+fine-tunes.
+
+## Technical choices and why
+
+**Procedural SVG over generated images.** Every element traces to a real feature;
+a diffusion model would break that link.
+
+**Fine-tuned 1.5B over prompted 7B for both voice and extraction.** A prompted
+large model copies examples; a fine-tuned small model learns the pattern. The
+eval shows the extraction fine-tune reaching 7B-level groundedness at a third the
+size.
+
+**Counts live on the receipt, never in the voice.** The voice is forbidden from
+reciting tallies, so it can never state a number that contradicts the record. The
+slug describes moments; the receipt does arithmetic.
+
+**Graceful degradation everywhere.** If the primary Modal extraction misses, the
+app retries once on the same small model, then shows a clear "try again" message
+rather than crashing. Unexpected sentiment → closest valid label. Animation fails
+→ the full shell still shows (nothing is hard-hidden). Nothing crashes on edge
+cases.
+
+## Hackathon patches
+
+| Patch | Status | Evidence |
+|---|---|---|
+| 🍄 Thousand Token Wood | ✅ | A slug grows a shell from your session |
+| 🏆 Best Use of Codex | ✅ | Codex-attributed commits, documented usage, public repo |
+| 🎨 Off Brand | ✅ | Procedural shell: scroll-unroll birth, byōbu battle layer, thermal receipt |
+| 🎯 Well-Tuned | ✅ | TWO published LoRAs + a published, re-scorable groundedness eval |
+| 🏗️ Best Use of Modal | ✅ | Two fine-tunes, dual-adapter serving, TTS, eval, and gallery on Modal |
+| 📓 Field Notes | ✅ | [Blog article](https://huggingface.co/blog/build-small-hackathon/turboskillslug-shell-from-session) |
+
+## Honesty
+
+Full caveats (parse-rate cost, the eval's 5/6 calibration, the animation
+payload, what is freshly built) are documented in
+[HONEST_SUBMISSION.md](https://github.com/AnubhavBharadwaaj/turbo-skill-slug/blob/main/HONEST_SUBMISSION.md).
+Every model and the eval data are published for anyone to verify.
+
+## Research foundation: from one skill to lifecycle-governed rules
+
+Beyond the shipped app, this project carries an offline-validated research layer
+that answers a sharper question than "can a small model extract a skill": *when
+does an extracted artifact actually help a capable model, and how should many
+sessions compound into durable knowledge?*
+
+This work is validated offline (it is not yet wired into the live Space) and is
+documented and tested in the repo. Stated plainly so the line between shipped and
+researched is clear:
+
+- **When skills help (measured).** A blind, calibrated eval (one model answers,
+  an independent model judges) found that a generated skill gives a frontier
+  model uplift *only* when it carries knowledge that could not be in training
+  data: private behavior, post-cutoff facts, project conventions. General
+  algorithmic skills gave 0.0 uplift; novel/private ones gave real uplift. The
+  dividing line is provenance, not difficulty.
+
+- **Compounding across sessions (built, offline-tested).** A promotion engine,
+  grounded in the 2026 "Experience Compression Spectrum" framing, consolidates
+  gotchas that recur across multiple sessions of the same codebase into compact,
+  guardrail-phrased rules, with provenance, confidence, and a validation gate
+  that demotes rules that stop holding. Rule phrasing follows the "RuleShaping"
+  finding that negative, state-dependent guardrails help where positive
+  directives hurt.
+
+- **Faithful trace distillation (built, offline-tested).** A from-scratch
+  implementation of the 2026 "Trace2Skill" method (validation-gated error
+  analysis, hierarchical prevalent-pattern merging, niche items routed to
+  references) for higher-fidelity extraction.
+
+An honest result from running the extractor on a sample of real public agent
+traces (SALT-NLP/SWE-chat and nebius/SWE-agent-trajectories): its gotchas are
+specific and real (it named exact functions, ref namespaces, and build-tool
+quirks), but cross-session promotion only fires within a single codebase, because
+two different repos never share the same private trap. This was an exploratory
+check on a handful of sessions, not a systematic benchmark, and it surfaced a
+true property of the problem rather than a polished number, reported rather than
+hidden. The loader scripts live in `research/traces/` in the GitHub repo, so the
+check is reproducible from scratch.
+
+Full method, code, and tests live in the repo; the research is a foundation for
+where the slug goes next, not a claim about the current Space.
+
+## What comes next
+
+1. **Session diff view.** Upload two sessions, see how the shells differ.
+2. **Tighter extraction reliability.** Close the parse-rate gap (21/25 vs the
+   7B's 24/25) with more training pairs and constrained decoding.
+
+## Links
+
+- **Space:** [build-small-hackathon/TurboSkillSlug](https://huggingface.co/spaces/build-small-hackathon/TurboSkillSlug)
+- **Code:** [github.com/AnubhavBharadwaaj/turbo-skill-slug](https://github.com/AnubhavBharadwaaj/turbo-skill-slug)
+- **SlugVoice LoRA:** [slugvoice-qwen2.5-1.5b-lora](https://huggingface.co/legendarydragontamer/slugvoice-qwen2.5-1.5b-lora)
+- **SlugExtract LoRA:** [slugextract-qwen2.5-1.5b-lora](https://huggingface.co/legendarydragontamer/slugextract-qwen2.5-1.5b-lora)
+- **Groundedness eval:** [turboskillslug-groundedness-eval](https://huggingface.co/datasets/legendarydragontamer/turboskillslug-groundedness-eval)
+- **Demo:** [youtu.be/qSP9olWRv7o](https://youtu.be/qSP9olWRv7o)
+- **Social post:** [x.com/anubhav27071997](https://x.com/anubhav27071997/status/2063970171010826540)
+- **Blog:** [turboskillslug-shell-from-session](https://huggingface.co/blog/build-small-hackathon/turboskillslug-shell-from-session)
+
+---
+
+*The slug watches, gives its gifts, and goes back to sleep.*
+*I was here.*

anim_diagnostic.py

@@ -0,0 +1,73 @@
+"""
+Animation diagnostic for the shell iframe.
+
+Embeds a self-reporting probe inside the iframe srcdoc that:
+  1. Confirms the iframe document actually rendered (suspect #3)
+  2. Counts <animate>/<animateTransform> elements present in the DOM (suspect #2:
+     did Gradio strip them before they reached the iframe?)
+  3. Uses the SVG SMIL API (svg.getCurrentTime / elem.getStartTime) to check
+     whether the animations are actually RUNNING, not just present (suspect #4)
+  4. Paints a visible badge in the corner with the verdict, so you SEE the answer
+     on the live Space without opening devtools.
+
+This makes the failure point unambiguous:
+  - Badge never appears        -> iframe didn't render (suspect #3) OR Gradio
+                                  didn't even pass the iframe through
+  - Badge: "0 anim elements"   -> SMIL stripped before/at the iframe (suspect #2)
+  - Badge: "N present, FROZEN"  -> SMIL present but not playing (suspect #4: sandbox)
+  - Badge: "N present, RUNNING" -> animation IS working; the issue is it is too
+                                  fast/subtle to see, or you looked after it froze
+"""
+
+PROBE_JS = """
+<script>
+(function(){
+  function badge(text, color){
+    var d = document.createElement('div');
+    d.textContent = text;
+    d.style.cssText = 'position:fixed;left:6px;bottom:6px;z-index:99999;'
+      + 'font:11px monospace;padding:4px 7px;border-radius:4px;'
+      + 'background:'+color+';color:#fff;opacity:0.92;pointer-events:none;'
+      + 'white-space:nowrap;';
+    document.body.appendChild(d);
+  }
+  function run(){
+    var svg = document.querySelector('svg');
+    if(!svg){ badge('NO SVG in iframe', '#b00'); return; }
+    var anims = svg.querySelectorAll('animate, animateTransform, animateMotion');
+    var n = anims.length;
+    if(n === 0){ badge('SMIL STRIPPED: 0 anim elements', '#b00'); return; }
+    // Check if SMIL is actually advancing time.
+    var t0 = 0;
+    try { t0 = svg.getCurrentTime(); } catch(e){
+      badge(n+' present, but getCurrentTime() FAILED (SMIL unsupported)', '#b06000');
+      return;
+    }
+    // Sample again shortly after; if currentTime advanced, SMIL is running.
+    setTimeout(function(){
+      var t1 = 0;
+      try { t1 = svg.getCurrentTime(); } catch(e){}
+      if(t1 > t0 + 0.05){
+        badge(n+' anim elements, RUNNING (t='+t1.toFixed(2)+'s)', '#0a7d2c');
+      } else {
+        badge(n+' present, FROZEN (SMIL not advancing - sandbox?)', '#b06000');
+      }
+    }, 350);
+  }
+  if(document.readyState === 'loading'){
+    document.addEventListener('DOMContentLoaded', run);
+  } else { run(); }
+})();
+</script>
+"""
+
+
+def inject_probe(iframe_inner_html: str) -> str:
+    """Insert the probe <script> just before </body> inside the iframe document.
+
+    iframe_inner_html is the FULL html doc string that goes into srcdoc (before
+    escaping). The probe runs inside the iframe's own document, where SMIL lives.
+    """
+    if "</body>" in iframe_inner_html:
+        return iframe_inner_html.replace("</body>", PROBE_JS + "</body>", 1)
+    return iframe_inner_html + PROBE_JS

app.py

@@ -0,0 +1,647 @@
+"""TurboSkillSlug Gradio application."""
+
+from __future__ import annotations
+
+import base64 as b64lib
+import html
+import json
+import os
+import shutil
+import tempfile
+import time
+import wave
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+import httpx
+
+from extract import extract_session
+from receipt import generate_receipt_svg
+from shell import generate_shell_svg
+from shell_animate import wrap_in_iframe, animate_shell_svg
+from shell_unroll import build_unroll_doc, N_STAGES
+from gallery_client import save_shell, list_shells, get_shell
+from battle_trace import render_battle_trace
+from shell3d_lens import render_shell_3d
+from shell_animate import wrap_in_iframe as _wrap_iframe
+from transcribe import transcribe_audio
+from trace_parser import parse_trace_to_transcript, detect_trace_format
+from model_guard import APP_RUNTIME
+
+# REQ-01 guard: mark this process as the live app. From here on, any attempt to
+# call an over-32B model (via assert_small_model) will raise instead of shipping
+# a compliance violation. Offline eval/research scripts never enable this flag.
+APP_RUNTIME.enable()
+
+
+# Growth stages for the live shell reveal. The slug grows the shell as it
+# watches: spiral lengthens, knots and jewels form in order, aperture opens last.
+GROWTH_STAGES = [0.18, 0.38, 0.58, 0.78, 1.0]
+GROWTH_PACING_SECONDS = 0.55  # brief pause between stages so the eye sees growth
+
+TTS_URL = os.environ.get(
+    "MODAL_TTS_URL",
+    "https://anubhavbharadwaaj--slugvoice-tts-slugtts-api.modal.run",
+)
+SAMPLE_WAV_NAME = "sample_session.wav"
+SAMPLE_WAV_PATH = Path(__file__).parent / SAMPLE_WAV_NAME
+
+
+def _resolve_audio_path(audio: str | None) -> str | None:
+    """Return a readable audio path for the pipeline.
+
+    Gradio example uploads can point at evictable temp files on HF Spaces. If the
+    one-click sample's temp copy is gone, recover from the committed repo copy
+    by copying it to a fresh temp file owned by this request.
+    """
+    if audio and os.path.exists(audio):
+        return audio
+
+    looks_like_sample = audio and SAMPLE_WAV_NAME in os.path.basename(audio)
+    if (looks_like_sample or audio is None) and SAMPLE_WAV_PATH.exists():
+        dst = Path(tempfile.mkdtemp(prefix="slug_sample_")) / SAMPLE_WAV_NAME
+        shutil.copy(SAMPLE_WAV_PATH, dst)
+        print(f"[SAMPLE] recovered evicted sample from committed repo copy: {dst}")
+        return str(dst)
+
+    return audio
+
+
+def _base_url_from_request(request) -> str:
+    """Reconstruct the app's public base URL (with trailing /) from a gr.Request.
+
+    On HF Spaces the app sits behind a reverse proxy, so the real public host is
+    in x-forwarded-host (not request.url's internal host). We prefer the
+    forwarded headers and fall back to request.headers['host'] / request.url.
+    """
+    try:
+        headers = {k.lower(): v for k, v in dict(request.headers).items()}
+    except Exception:
+        headers = {}
+    host = headers.get("x-forwarded-host") or headers.get("host")
+    proto = headers.get("x-forwarded-proto") or "https"
+    if host:
+        return f"{proto}://{host}/"
+    # last-resort fallback to the request URL's origin
+    try:
+        u = str(request.url)
+        # strip any path/query
+        from urllib.parse import urlparse
+        p = urlparse(u)
+        if p.scheme and p.netloc:
+            return f"{p.scheme}://{p.netloc}/"
+    except Exception:
+        pass
+    return "/"
+
+
+def _speak_recap(slug_lines: list[str]) -> str | None:
+    """Convert slug recap to speech via Chatterbox on Modal."""
+    try:
+        full_text = ". ".join(slug_lines) + ". I was here."
+        resp = httpx.post(TTS_URL, json={"text": full_text}, timeout=180)
+        resp.raise_for_status()
+        audio_b64 = resp.json().get("audio", "")
+        if audio_b64:
+            audio_bytes = b64lib.b64decode(audio_b64)
+            tmp = Path(tempfile.mkdtemp()) / "slug_speaks.wav"
+            tmp.write_bytes(audio_bytes)
+            return str(tmp)
+    except Exception as e:
+        print(f"TTS failed: {e}")
+    return None
+
+
+def _get_audio_duration_minutes(file_path: str) -> float:
+    """Get actual audio duration in minutes from the file itself."""
+    try:
+        with wave.open(file_path, "r") as f:
+            return (f.getnframes() / f.getframerate()) / 60
+    except Exception:
+        try:
+            size = os.path.getsize(file_path)
+            return round(size / (32000 * 60), 1)
+        except Exception:
+            return 1.0
+
+
+def _format_slug_recap(extraction: dict[str, Any]) -> str:
+    """Format the slug's witness recap for display."""
+    slug_voice = extraction.get("slug_voice", [])
+    utterances = "\n\n".join(f"*{u}*" for u in slug_voice)
+
+    # The slug's closing signature
+    utterances += "\n\n*I was here.*"
+
+    themes = ", ".join(extraction.get("themes", []))
+    duration = extraction.get("duration_minutes", 0)
+
+    return (
+        "## what the slug witnessed\n\n"
+        f"{utterances}\n\n"
+        f"**Duration:** {duration} minutes\n\n"
+        f"**Themes:** {themes}\n"
+    )
+
+
+def _format_shell_legend(extraction: dict[str, Any]) -> str:
+    """Return a compact genre-aware legend for the shell display."""
+    genre = str(extraction.get("genre") or "session")
+    legend = extraction.get("shell_legend") or {}
+    if not isinstance(legend, dict) or not legend:
+        return ""
+
+    knot = html.escape(str(legend.get("knot", "dead ends")))
+    jewel = html.escape(str(legend.get("jewel", "gotchas")))
+    aperture = html.escape(str(legend.get("aperture", "breakthrough")))
+    genre_label = html.escape(genre.replace("_", " "))
+    return (
+        '<div style="font: 13px system-ui, sans-serif; '
+        'color: #4d4637 !important; background: #fff8e8 !important; '
+        'border: 1px solid #c8a24c; border-radius: 8px; '
+        'padding: 10px 12px; margin: 8px 0 12px;">'
+        f'<strong>Shell legend ({genre_label})</strong>: knots = {knot}; '
+        f'jewels = {jewel}; aperture = {aperture}.'
+        "</div>"
+    )
+
+
+def on_audio_change(audio: str | None):
+    """Fired the moment a file is selected/recorded/cleared.
+
+    Disables the button and shows a 'preparing' state during the window
+    after upload but before the user can meaningfully click submit, so a
+    premature click is impossible and there is always visible feedback.
+    """
+    if audio is None:
+        return (
+            gr.update(value="🐌 give it to the slug", interactive=False),
+            gr.update(value=""),
+        )
+    return (
+        gr.update(value="🐌 give it to the slug", interactive=True),
+        gr.update(value="*The slug is ready. Hand it your session.*"),
+    )
+
+
+def _empty_outputs(message: str):
+    """Twelve-tuple matching the output components, for early/error yields."""
+    return (message, "", "", "", "", None, None, None, None, None, None, None)
+
+
+def _finalize_outputs(transcript_display: str, extraction: dict, slug_audio_path):
+    """Build the full ten-tuple of outputs once the shell is fully grown.
+
+    Shared by the audio and trace paths so both render identically.
+    """
+    raw_json = json.dumps(extraction, indent=2)
+    # The full static shell is what we save for download (clean, portable).
+    shell_svg = generate_shell_svg(extraction, growth=1.0)
+    # For the live display, build the scroll-unroll: a flipbook of growth stages
+    # (each truncates the spiral ALONG its arm) led by a 3D paper curl riding the
+    # tip. This lays the parchment down along the spiral path, not radially.
+    try:
+        stages = [
+            generate_shell_svg(extraction, growth=(i + 1) / N_STAGES)
+            for i in range(N_STAGES)
+        ]
+        unroll_doc = build_unroll_doc(stages)
+        shell_display = wrap_in_iframe(unroll_doc, height=660)
+    except Exception:
+        # Never let the animation break the result: fall back to the static shell.
+        shell_display = wrap_in_iframe(shell_svg, height=660)
+    shell_display = _format_shell_legend(extraction) + shell_display
+    receipt_svg = generate_receipt_svg(extraction)
+
+    tmp_dir = Path(tempfile.mkdtemp(prefix="slug_"))
+    svg_path = tmp_dir / "shell.svg"
+    svg_path.write_text(shell_svg)
+    receipt_path = tmp_dir / "receipt.svg"
+    receipt_path.write_text(receipt_svg)
+    skill_path = tmp_dir / "skill.md"
+    skill_path.write_text(extraction.get("skill_md", ""))
+    recap_lines = list(extraction.get("slug_voice", [])) + ["I was here."]
+    recap_path = tmp_dir / "slug_recap.txt"
+    recap_path.write_text("\n\n".join(recap_lines))
+
+    return (
+        transcript_display,
+        _format_slug_recap(extraction),
+        shell_display,
+        receipt_svg,
+        raw_json,
+        slug_audio_path,
+        str(svg_path),
+        str(receipt_path),
+        str(skill_path),
+        str(recap_path),
+        shell_svg,        # static SVG, for the "keep this shell" gallery save
+        extraction,       # metadata, for the gallery entry
+    )
+
+
+def _grow_shell_stages(extraction: dict, transcript_display: str):
+    """Yield a single 'shaping' status while the browser-played birth animation
+    is prepared. The smooth growth now happens in the browser (shards / draw /
+    glass), so we no longer stream mechanical server-side frames. One gentle
+    status, then the caller yields the finished animated shell.
+    """
+    yield (
+        "*The slug is shaping your shell...*",
+        "*the shell is coming into being...*",
+        "", "", "", None, None, None, None, None, None, None,
+    )
+
+
+def process_audio(audio: str | None):
+    """Transcribe, extract, then GROW the shell live, yielding each stage."""
+    audio = _resolve_audio_path(audio)
+    if audio is None or not os.path.exists(audio):
+        yield _empty_outputs(
+            "The slug couldn't find that audio file. On HF Spaces an upload can "
+            "expire; please re-upload and try again."
+        )
+        return
+
+    try:
+        transcript = transcribe_audio(audio)
+        extraction = extract_session(transcript)
+    except Exception as e:
+        print(f"[PIPELINE] audio path failed: {type(e).__name__}: {e}")
+        yield _empty_outputs(
+            "The slug couldn't read this session right now — the extractor is "
+            "temporarily unavailable. Please try again, or use the trace tab."
+        )
+        return
+    slug_audio_path = _speak_recap(extraction.get("slug_voice", []))
+
+    audio_minutes = round(_get_audio_duration_minutes(audio), 1)
+    model_minutes = extraction.get("duration_minutes", 0)
+    try:
+        model_minutes = float(model_minutes)
+    except (TypeError, ValueError):
+        model_minutes = 0.0
+    extraction["duration_minutes"] = round(max(audio_minutes, model_minutes), 1)
+
+    transcript_display = f"## Transcript\n\n{transcript}"
+    yield from _grow_shell_stages(extraction, transcript_display)
+    yield _finalize_outputs(transcript_display, extraction, slug_audio_path)
+
+
+
+def process_trace(trace_file: str | None):
+    """Parse an agent session JSONL trace, then GROW the shell live.
+
+    A Claude Code or Codex CLI session log becomes witness testimony the slug
+    reads exactly like a spoken transcript. This is the input judges can feed
+    from their own machines.
+    """
+    if trace_file is None:
+        yield _empty_outputs("Drop a Claude Code or Codex session trace first.")
+        return
+
+    try:
+        with open(trace_file, "r", encoding="utf-8", errors="replace") as f:
+            jsonl_string = f.read()
+    except Exception as e:
+        yield _empty_outputs(f"Could not read the trace: {e}")
+        return
+
+    source = detect_trace_format(jsonl_string)
+    transcript = parse_trace_to_transcript(jsonl_string)
+    if not transcript:
+        yield _empty_outputs("The slug could not find a session in that file.")
+        return
+
+    extraction = extract_session(transcript)
+    slug_audio_path = _speak_recap(extraction.get("slug_voice", []))
+
+    # Duration: no audio file, so trust the model's estimate.
+    model_minutes = extraction.get("duration_minutes", 0)
+    try:
+        model_minutes = float(model_minutes)
+    except (TypeError, ValueError):
+        model_minutes = 0.0
+    extraction["duration_minutes"] = round(model_minutes, 1) if model_minutes > 0 else 1.0
+
+    label = {"claude": "Claude Code", "codex": "Codex CLI"}.get(source, "agent")
+    transcript_display = (
+        f"## Session trace ({label})\n\n"
+        f"The slug read your {label} session and witnessed this:\n\n{transcript}"
+    )
+
+    yield from _grow_shell_stages(extraction, transcript_display)
+    yield _finalize_outputs(transcript_display, extraction, slug_audio_path)
+
+
+def build_interface() -> gr.Blocks:
+    """Build and return the TurboSkillSlug Gradio Blocks interface."""
+    with gr.Blocks(title="TurboSkillSlug") as demo:
+        gr.Markdown(
+            "# 🐌 TurboSkillSlug\n\n"
+            "*A small, slow companion who watches you build.*\n\n"
+            "Give the slug a build session: narrate it aloud, or drop an agent "
+            "session trace. It watches, then grows you a shell, a recap, a "
+            "SKILL.md, and a receipt."
+        )
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                with gr.Tabs():
+                    with gr.Tab("narrate aloud"):
+                        audio_input = gr.Audio(
+                            sources=["upload", "microphone"],
+                            type="filepath",
+                            label="your build session",
+                        )
+                        gr.Examples(
+                            examples=[str(SAMPLE_WAV_PATH)],
+                            inputs=audio_input,
+                            label="or try a sample session",
+                        )
+                        submit_button = gr.Button(
+                            "🐌 give it to the slug", variant="primary",
+                            interactive=False,
+                        )
+                    with gr.Tab("drop a session trace"):
+                        gr.Markdown(
+                            "Drag a **Claude Code** "
+                            "(`~/.claude/projects/.../*.jsonl`) or **Codex CLI** "
+                            "(`~/.codex/sessions/.../*.jsonl`) session log. "
+                            "The slug reads your actual work, no narration needed."
+                        )
+                        trace_input = gr.File(
+                            label="session trace (.jsonl)",
+                            file_types=[".jsonl"],
+                            type="filepath",
+                        )
+                        gr.Examples(
+                            examples=["sample_trace.jsonl"],
+                            inputs=trace_input,
+                            label="or try a sample trace",
+                        )
+                        trace_button = gr.Button(
+                            "🐌 let the slug read it", variant="primary",
+                        )
+            with gr.Column(scale=1):
+                status_line = gr.Markdown("")
+
+        # ---- THE SHELL, front and center, right under the inputs ----
+        # This is what plays during generation. Everything else stays hidden
+        # until the shell has finished being born.
+        shell_output = gr.HTML(label="your shell")
+
+        # State holders for the current shell (static SVG + extraction), used by
+        # the "keep this shell" gallery save and the experimental battle replay.
+        cur_shell_svg = gr.State(None)
+        cur_extraction = gr.State(None)
+
+        # ---- EVERYTHING ELSE, hidden until the shell finishes ----
+        with gr.Group(visible=False) as gifts_group:
+            gr.Markdown("### the slug's other gifts")
+            with gr.Row():
+                keep_button = gr.Button("🐚 keep this shell in the terrarium",
+                                        variant="secondary")
+                keep_status = gr.Markdown("")
+            recap_output = gr.Markdown(label="slug recap")
+            slug_audio = gr.Audio(label="the slug speaks", type="filepath")
+            receipt_output = gr.HTML(label="your receipt")
+            transcript_output = gr.Markdown(label="transcript")
+            raw_json_output = gr.Code(label="Raw JSON", language="json")
+            with gr.Row():
+                svg_download = gr.File(label="shell.svg")
+                receipt_download = gr.File(label="receipt.svg")
+                skill_download = gr.File(label="skill.md")
+                recap_download = gr.File(label="slug_recap.txt")
+
+            # Experimental: the LITERAL temporal replay of the session as a war
+            # between you (the Agent) and the Environment. The shell remembers
+            # the campaign as a frozen folding screen; this replays it in time.
+            with gr.Accordion("⚔ the battle, as it happened (replay)", open=False):
+                gr.Markdown(
+                    "The shell is how the slug *remembers* the battle: the "
+                    "aftermath, frozen like a folding screen, where the dead "
+                    "ends fell and where the breakthrough struck. This is the "
+                    "*replay* of that same battle as it actually happened in "
+                    "time, your moves against the Environment's strikes (dead "
+                    "ends), the clashes (gotchas), and the blow that finally "
+                    "lands (the breakthrough). Memory above; footage here."
+                )
+                battle_view = gr.HTML()
+                battle_button = gr.Button("⚔ replay the battle the slug remembers")
+
+                def _show_battle(extraction):
+                    if not extraction:
+                        return gr.update(value="*The slug has no battle to replay yet.*")
+                    return gr.update(value=render_battle_trace(extraction, height=440))
+
+                battle_button.click(
+                    fn=_show_battle,
+                    inputs=[cur_extraction],
+                    outputs=[battle_view],
+                )
+
+            # The shell as a real 3D object you can turn in the light. Same session
+            # data, a different lens: the SceneGraph drives a Three.js nautilus with
+            # iridescent nacre. First of the planned multi-lens renderers.
+            with gr.Accordion("🔮 turn the shell in 3D (experimental lens)", open=False):
+                gr.Markdown(
+                    "The same shell, rendered as a real object you can orbit. The "
+                    "spiral's growth, the knots (dead ends), the glowing aperture "
+                    "(breakthrough), and the colour arc all come from your session, "
+                    "now with true iridescent nacre. Drag to turn it; scroll to zoom."
+                )
+                shell3d_view = gr.HTML()
+                shell3d_button = gr.Button("🔮 see this shell in 3D")
+
+                def _show_shell3d(extraction):
+                    if not extraction:
+                        return gr.update(value="*No shell to render in 3D yet.*")
+                    html = render_shell_3d(extraction)
+                    if not html:
+                        return gr.update(value="*The 3D lens is unavailable right now.*")
+                    return gr.update(value=html)
+
+                shell3d_button.click(
+                    fn=_show_shell3d,
+                    inputs=[cur_extraction],
+                    outputs=[shell3d_view],
+                )
+
+        # Enable the button only once audio is actually present
+        audio_input.change(
+            fn=on_audio_change,
+            inputs=audio_input,
+            outputs=[submit_button, status_line],
+        )
+
+        # The 12 pipeline outputs (10 UI + 2 state for the gallery save)
+        pipeline_outputs = [
+            transcript_output,
+            recap_output,
+            shell_output,
+            receipt_output,
+            raw_json_output,
+            slug_audio,
+            svg_download,
+            receipt_download,
+            skill_download,
+            recap_download,
+            cur_shell_svg,
+            cur_extraction,
+        ]
+
+        def _hide_gifts():
+            # On start: hide the gifts, lock the button, set a watching status
+            return (
+                gr.update(visible=False),
+                gr.update(value="🐌 the slug is watching…", interactive=False),
+                gr.update(value="*The slug is listening, then it will grow your shell...*"),
+            )
+
+        def _reveal_gifts():
+            # On finish: reveal the gifts, reset the button
+            return (
+                gr.update(visible=True),
+                gr.update(value="🐌 give it to the slug", interactive=True),
+                gr.update(value="*The slug has finished. Your gifts are below.*"),
+            )
+
+        # Audio path
+        submit_button.click(
+            fn=_hide_gifts,
+            inputs=None,
+            outputs=[gifts_group, submit_button, status_line],
+        ).then(
+            fn=process_audio,
+            inputs=audio_input,
+            outputs=pipeline_outputs,
+        ).then(
+            fn=_reveal_gifts,
+            inputs=None,
+            outputs=[gifts_group, submit_button, status_line],
+        )
+
+        # Trace path
+        trace_button.click(
+            fn=_hide_gifts,
+            inputs=None,
+            outputs=[gifts_group, submit_button, status_line],
+        ).then(
+            fn=process_trace,
+            inputs=trace_input,
+            outputs=pipeline_outputs,
+        ).then(
+            fn=_reveal_gifts,
+            inputs=None,
+            outputs=[gifts_group, submit_button, status_line],
+        )
+
+        # ---- Stage B: save the current shell to the shared terrarium ----
+        def _keep_shell(svg, extraction, request: gr.Request):
+            if not svg or not extraction:
+                return gr.update(value="*No shell to keep yet.*")
+            sid = save_shell(svg, extraction)
+            if not sid:
+                return gr.update(value="*The terrarium was unreachable; shell not saved.*")
+            # Build a COMPLETE clickable link (not a bare ?shell= fragment, which
+            # is confusing). Derive the base URL from the request's headers.
+            base = _base_url_from_request(request)
+            link = f"{base}?shell={sid}"
+            return gr.update(
+                value=(
+                    f"🐚 **Kept in the terrarium.** Here's the shareable link to "
+                    f"this exact shell:\n\n[{link}]({link})\n\n"
+                    f"_Anyone who opens it sees this shell unroll. You can also "
+                    f"browse all kept shells in the terrarium below._"
+                )
+            )
+
+        keep_button.click(
+            fn=_keep_shell,
+            inputs=[cur_shell_svg, cur_extraction],
+            outputs=[keep_status],
+        )
+
+        # ---- Stage C: the shared gallery (a living terrarium of kept shells) ----
+        def _render_gallery(request: gr.Request):
+            shells = list_shells(limit=60)
+            if not shells:
+                return ("*The terrarium is empty so far. Grow a shell and keep it "
+                        "to be the first.*")
+            base = _base_url_from_request(request)
+            # build a responsive grid of shells; each loads its SVG by id
+            cards = []
+            for e in shells:
+                sid = e.get("id")
+                title = e.get("title") or "a session"
+                dur = e.get("duration")
+                arc = f"{e.get('start','?')} → {e.get('end','?')}"
+                sub = f"{dur}m · {arc}" if dur else arc
+                data = get_shell(sid) if sid else None
+                svg = (data or {}).get("svg", "")
+                if not svg:
+                    continue
+                # shrink each shell into a card; static, no replay button (these
+                # are kept shells, like photos in an album — the replay belongs
+                # to the focused permalink view below).
+                frame = _wrap_iframe(svg, height=240, replay=False)
+                link = f"{base}?shell={sid}"
+                cards.append(
+                    f'<div style="flex:0 0 250px;margin:8px;text-align:center;">'
+                    f'<div style="font:600 13px Georgia,serif;color:#c8a24c;">{title}</div>'
+                    f'<div style="font:11px monospace;color:#999;margin-bottom:4px;">{sub}</div>'
+                    f'{frame}'
+                    f'<div style="margin-top:4px;"><a href="{link}" target="_blank" '
+                    f'style="font:12px Georgia,serif;color:#6ee7ff;text-decoration:none;">'
+                    f'open this shell →</a></div>'
+                    f'</div>'
+                )
+            grid = (
+                '<div style="display:flex;flex-wrap:wrap;justify-content:center;">'
+                + "".join(cards) + "</div>"
+            )
+            return grid
+
+        def _load_permalink(request: gr.Request):
+            """If the URL has ?shell=<id>, load that single shell on page open."""
+            try:
+                sid = dict(request.query_params).get("shell")
+            except Exception:
+                sid = None
+            if not sid:
+                return gr.update()
+            data = get_shell(sid)
+            if not data or not data.get("svg"):
+                return gr.update(value="*That shell could not be found in the terrarium.*")
+            # Re-animate the saved static shell for the focused permalink view:
+            # the mask-based scroll-unroll works on a single SVG (no growth
+            # stages needed), so this shell unrolls and the replay button works.
+            try:
+                animated = animate_shell_svg(data["svg"])
+                return gr.update(value=wrap_in_iframe(animated, height=520, replay=True))
+            except Exception:
+                return gr.update(value=_wrap_iframe(data["svg"], height=520, replay=False))
+
+        with gr.Accordion("🌿 the terrarium (shared gallery)", open=False):
+            gr.Markdown(
+                "A shared collection of shells people have kept. Each one is the "
+                "fingerprint of a real session. Open `?shell=<id>` to link a "
+                "specific shell."
+            )
+            permalink_view = gr.HTML()
+            refresh_gallery = gr.Button("↻ refresh the terrarium")
+            gallery_grid = gr.HTML()
+            refresh_gallery.click(fn=_render_gallery, inputs=None, outputs=[gallery_grid])
+            # populate on load + handle ?shell= permalink
+            demo.load(fn=_render_gallery, inputs=None, outputs=[gallery_grid])
+            demo.load(fn=_load_permalink, inputs=None, outputs=[permalink_view])
+
+    return demo
+
+
+interface = build_interface()
+
+if __name__ == "__main__":
+    interface.launch()

battle_trace.py

@@ -0,0 +1,281 @@
+"""
+Battle Trace: an experimental temporal replay of a session as a war between the
+Agent and the Environment.
+
+This is the LITERAL, time-based telling of the session — complementary to the
+shell's byobu battle layer, which is the frozen, artistic telling. The shell
+remembers the campaign as a folding screen; Battle Trace replays it as it
+happened.
+
+It reuses the SAME structured extraction the rest of the app already produces
+(approaches, dead_ends, breakthroughs, gotchas, sentiment), so there is no
+second parser and no new model call. Events map to combat:
+
+  approach tried      -> the Agent makes a move (cmd)
+  dead end            -> the Environment strikes (err): Agent resolve drops
+  gotcha              -> a clash of blades (clash)
+  breakthrough        -> a blow lands true (win): Environment resistance drops
+  final breakthrough  -> the battle resolves (done)
+
+The renderer is self-contained Canvas 2D (fine for session-sized traces),
+sandboxed inside an iframe so it can never affect the main pipeline.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+
+
+def extraction_to_events(extraction: dict) -> list[dict]:
+    """Convert a session extraction into an ordered Battle Trace event stream.
+
+    Events are ordered by their position along the session (0..1) where we have
+    it (dead ends, breakthroughs), and interleaved sensibly otherwise.
+    """
+    events: list[dict] = []
+
+    approaches = extraction.get("approaches_tried", []) or []
+    dead_ends = extraction.get("dead_ends", []) or []
+    breakthroughs = extraction.get("breakthroughs", []) or []
+    gotchas = extraction.get("gotchas", []) or []
+
+    # approaches kick off near the start, spaced across the first half
+    for i, a in enumerate(approaches):
+        if not isinstance(a, dict):
+            continue
+        pos = 0.05 + (i / max(1, len(approaches))) * 0.4
+        label = str(a.get("approach", "a move"))[:72]
+        events.append({"pos": pos, "side": "A", "kind": "cmd", "label": label})
+
+    # dead ends at their real positions — the Environment strikes
+    for d in dead_ends:
+        if not isinstance(d, dict):
+            continue
+        pos = float(d.get("position", 0.5))
+        label = str(d.get("what_happened", "a wall"))[:72]
+        events.append({"pos": pos, "side": "E", "kind": "err", "label": label})
+
+    # gotchas as clashes, spread through the middle
+    for i, g in enumerate(gotchas):
+        pos = 0.3 + (i / max(1, len(gotchas))) * 0.5
+        label = str(g)[:72]
+        events.append({"pos": pos, "side": "A", "kind": "clash", "label": label})
+
+    # breakthroughs at their positions — blows land
+    for i, b in enumerate(breakthroughs):
+        if not isinstance(b, dict):
+            continue
+        pos = float(b.get("position", 0.85))
+        label = str(b.get("what_worked", "a breakthrough"))[:72]
+        kind = "done" if i == len(breakthroughs) - 1 else "win"
+        events.append({"pos": pos, "side": "A", "kind": kind, "label": label})
+
+    events.sort(key=lambda e: e["pos"])
+    # assign a monotonic time axis from positions
+    for i, e in enumerate(events):
+        e["t"] = round(1.0 + e["pos"] * 12.0, 2)
+    if not events:
+        events = [{"pos": 0.5, "side": "A", "kind": "info", "label": "a quiet session", "t": 6.0}]
+    # ensure the last event resolves the battle
+    if events[-1]["kind"] not in ("done", "err"):
+        events[-1]["kind"] = "done"
+    return events
+
+
+# The renderer: a trimmed, self-contained Canvas 2D battle. No external deps.
+# Events are injected as JSON; everything else is static.
+_BATTLE_HTML = r"""<!DOCTYPE html><html><head><meta charset="utf-8"/>
+<style>
+  :root{--bg:#0a0e14;--ink:#e6edf3;--muted:#8b98a9;--agent:#6ee7ff;--env:#ff7a59;
+        --ok:#7ee787;--warn:#f0c674;--magic:#d2a8ff;--line:#1c2430;}
+  html,body{margin:0;height:100%;background:var(--bg);color:var(--ink);
+    font-family:ui-monospace,Menlo,Consolas,monospace;overflow:hidden}
+  #wrap{position:relative;height:100vh;width:100vw}
+  #stage{display:block;width:100%;height:100%}
+  .hud{position:absolute;top:0;left:0;right:0;padding:12px 18px;display:flex;
+    justify-content:space-between;pointer-events:none;font-size:12px}
+  .hud .agent{color:var(--agent);font-weight:600}.hud .env{color:var(--env);font-weight:600}
+  .hud .hp{font-size:11px;color:var(--muted)}
+  .caption{position:absolute;left:0;right:0;bottom:0;padding:10px 18px;
+    background:linear-gradient(transparent,rgba(7,10,15,.92));font-size:12px;min-height:38px}
+  .caption .t{color:var(--muted);margin-right:8px}
+  .controls{position:absolute;bottom:46px;left:50%;transform:translateX(-50%);display:flex;gap:8px}
+  button{background:transparent;color:var(--ink);border:1px solid var(--line);
+    border-radius:8px;padding:6px 12px;font-family:inherit;font-size:12px;cursor:pointer}
+  button:hover{border-color:var(--agent);color:var(--agent)}
+</style></head><body>
+<div id="wrap">
+  <div class="hud">
+    <div><span class="agent">&#x2B21; THE AGENT (you)</span><br/><span class="hp" id="hpA">resolve 100</span></div>
+    <div style="text-align:right"><span class="env">THE ENVIRONMENT &#x2B21;</span><br/><span class="hp" id="hpE">resistance 100</span></div>
+  </div>
+  <canvas id="stage"></canvas>
+  <div class="controls"><button id="replay">&#x21BB; replay the battle</button></div>
+  <div class="caption"><span class="t" id="capT">t+0.0s</span><span id="capX">the slug replays the battle, from the first move...</span></div>
+</div>
+<script>
+const EVENTS = __EVENTS_JSON__;
+const C={cmd:"#6ee7ff",read:"#7ee787",clash:"#f0c674",err:"#ff7a59",retry:"#d2a8ff",win:"#7ee787",done:"#6ee7ff",info:"#8b98a9"};
+const cv=document.getElementById("stage"),ctx=cv.getContext("2d");
+let W=0,H=0,DPR=Math.min(2,window.devicePixelRatio||1);
+function resize(){
+  const r=cv.getBoundingClientRect();
+  W=r.width||window.innerWidth||640;
+  H=r.height||window.innerHeight||440;
+  cv.width=W*DPR;cv.height=H*DPR;ctx.setTransform(DPR,0,0,DPR,0,0);
+}
+addEventListener("resize",resize);
+const stars=[];for(let i=0;i<70;i++)stars.push({x:Math.random(),y:Math.random()*0.55,r:Math.random()*1.2,a:.3+Math.random()*.5});
+let particles=[],bolts=[],rings=[],markers=[],figures=[],idx=0,clock=0,running=true,lastTs=0,hpA=100,hpE=100;
+const span=Math.max(8,EVENTS.length?EVENTS[EVENTS.length-1].t:10);
+function godA(){return{x:W*0.12,y:H*0.54}}function godE(){return{x:W*0.88,y:H*0.54}}
+function spark(x,y,c,n){for(let i=0;i<n;i++){const a=Math.random()*6.28,s=40+Math.random()*120;particles.push({x,y,vx:Math.cos(a)*s,vy:Math.sin(a)*s,life:1,color:c,size:1.5+Math.random()*2})}}
+function bolt(f,t,c){bolts.push({from:f,to:t,color:c,life:1})}
+function ring(x,y,c){rings.push({x,y,r:18,color:c,life:1})}
+function play(ev){const a=godA(),e=godE();const mx=W*0.5+(ev.t/span-0.5)*W*0.12,my=H*0.46+(Math.random()*40-20);
+  const src=ev.side==="A"?a:e;ring(src.x,src.y,C[ev.kind]);bolt(src,{x:mx,y:my},C[ev.kind]);
+  if(["clash","err","win","done"].includes(ev.kind))setTimeout(()=>spark(mx,my,C[ev.kind],ev.kind==="done"?30:16),130);
+  if(ev.kind==="err")figures.push({type:"fallen",x:mx,y:my,born:clock});
+  if(ev.kind==="done"||ev.kind==="win")figures.push({type:"dragon",x:mx,y:my,born:clock,grow:0});
+  if(ev.kind==="err")hpA=Math.max(0,hpA-12);if(ev.kind==="clash")hpE=Math.max(0,hpE-8);
+  if(ev.kind==="win"||ev.kind==="done")hpE=Math.max(0,hpE-15);
+  markers.push({t:ev.t,color:C[ev.kind],r:0});
+  document.getElementById("hpA").textContent="resolve "+Math.round(hpA);
+  document.getElementById("hpE").textContent="resistance "+Math.round(hpE);
+  document.getElementById("capT").textContent="t+"+ev.t.toFixed(1)+"s";
+  document.getElementById("capX").textContent=ev.label;}
+function aura(g,c,r){const gr=ctx.createRadialGradient(g.x,g.y,4,g.x,g.y,r);gr.addColorStop(0,c+"66");gr.addColorStop(1,c+"00");ctx.fillStyle=gr;ctx.beginPath();ctx.arc(g.x,g.y,r,0,7);ctx.fill();}
+function general(g,c){// the Agent: a detailed samurai general
+  aura(g,c,62);
+  ctx.save();ctx.translate(g.x,g.y);ctx.scale(1.15,1.15);ctx.lineJoin="round";ctx.lineCap="round";
+  const ink=c,fill="#0c1118",plate="#11202b",gold="#e6c870";ctx.lineWidth=2;
+  // sashimono back banner
+  ctx.strokeStyle=ink;ctx.beginPath();ctx.moveTo(14,-6);ctx.lineTo(20,-54);ctx.stroke();
+  ctx.fillStyle=ink;ctx.globalAlpha=.22;ctx.beginPath();ctx.moveTo(20,-54);ctx.lineTo(40,-50);ctx.lineTo(38,-30);ctx.lineTo(20,-34);ctx.closePath();ctx.fill();
+  ctx.globalAlpha=1;ctx.strokeStyle=gold;ctx.lineWidth=1;ctx.beginPath();ctx.moveTo(20,-54);ctx.lineTo(40,-50);ctx.lineTo(38,-30);ctx.lineTo(20,-34);ctx.closePath();ctx.stroke();
+  // hakama legs
+  ctx.lineWidth=2;ctx.strokeStyle=ink;ctx.fillStyle=fill;
+  ctx.beginPath();ctx.moveTo(-10,40);ctx.lineTo(-8,18);ctx.lineTo(0,16);ctx.lineTo(-2,40);ctx.closePath();ctx.fill();ctx.stroke();
+  ctx.beginPath();ctx.moveTo(10,40);ctx.lineTo(8,18);ctx.lineTo(0,16);ctx.lineTo(2,40);ctx.closePath();ctx.fill();ctx.stroke();
+  // torso armor (do)
+  ctx.fillStyle=plate;ctx.beginPath();ctx.moveTo(-12,2);ctx.quadraticCurveTo(-14,-14,0,-18);ctx.quadraticCurveTo(14,-14,12,2);ctx.lineTo(10,20);ctx.lineTo(-10,20);ctx.closePath();ctx.fill();ctx.stroke();
+  ctx.strokeStyle=ink;ctx.globalAlpha=.7;for(let i=0;i<3;i++){ctx.beginPath();ctx.moveTo(-11,2+i*6);ctx.lineTo(11,2+i*6);ctx.stroke();}ctx.globalAlpha=1;
+  // sode shoulder guards
+  ctx.fillStyle=plate;
+  ctx.beginPath();ctx.moveTo(-12,-12);ctx.lineTo(-22,-8);ctx.lineTo(-20,6);ctx.lineTo(-12,2);ctx.closePath();ctx.fill();ctx.stroke();
+  ctx.beginPath();ctx.moveTo(12,-12);ctx.lineTo(22,-8);ctx.lineTo(20,6);ctx.lineTo(12,2);ctx.closePath();ctx.fill();ctx.stroke();
+  // head + menpo
+  ctx.fillStyle=fill;ctx.beginPath();ctx.arc(0,-26,8,0,7);ctx.fill();ctx.stroke();
+  ctx.strokeStyle=ink;ctx.beginPath();ctx.moveTo(-5,-24);ctx.lineTo(5,-24);ctx.stroke();
+  // kabuto bowl
+  ctx.fillStyle=plate;ctx.beginPath();ctx.arc(0,-30,10,Math.PI,0);ctx.lineTo(9,-30);ctx.lineTo(-9,-30);ctx.closePath();ctx.fill();ctx.stroke();
+  // golden crescent crest
+  ctx.strokeStyle=gold;ctx.lineWidth=2.4;
+  ctx.beginPath();ctx.moveTo(-7,-38);ctx.quadraticCurveTo(-18,-52,-4,-46);ctx.stroke();
+  ctx.beginPath();ctx.moveTo(7,-38);ctx.quadraticCurveTo(18,-52,4,-46);ctx.stroke();
+  ctx.fillStyle=gold;ctx.beginPath();ctx.arc(0,-44,2.2,0,7);ctx.fill();
+  // arm + raised katana
+  ctx.strokeStyle=ink;ctx.lineWidth=3;ctx.beginPath();ctx.moveTo(8,-4);ctx.lineTo(16,-2);ctx.stroke();
+  ctx.strokeStyle="#cfe8ff";ctx.lineWidth=2.6;ctx.beginPath();ctx.moveTo(16,-2);ctx.lineTo(52,-44);ctx.stroke();
+  ctx.strokeStyle=gold;ctx.lineWidth=3;ctx.beginPath();ctx.moveTo(13,2);ctx.lineTo(18,-4);ctx.stroke();
+  ctx.restore();
+}
+function adversary(g,c){// the Environment: a detailed oni
+  aura(g,c,66);
+  ctx.save();ctx.translate(g.x,g.y);ctx.scale(1.15,1.15);ctx.lineJoin="round";ctx.lineCap="round";ctx.lineWidth=2;
+  const ink=c,fill="#0c1118",hide="#241016";
+  ctx.fillStyle=hide;ctx.strokeStyle=ink;
+  ctx.beginPath();ctx.moveTo(-22,40);ctx.quadraticCurveTo(-30,-2,-14,-14);ctx.quadraticCurveTo(0,-22,14,-14);ctx.quadraticCurveTo(30,-2,22,40);ctx.closePath();ctx.fill();ctx.stroke();
+  ctx.globalAlpha=.5;ctx.beginPath();ctx.moveTo(-10,6);ctx.quadraticCurveTo(0,12,10,6);ctx.stroke();ctx.beginPath();ctx.moveTo(-8,18);ctx.quadraticCurveTo(0,24,8,18);ctx.stroke();ctx.globalAlpha=1;
+  // arms + claws
+  ctx.beginPath();ctx.moveTo(-18,-6);ctx.lineTo(-30,12);ctx.lineTo(-26,20);ctx.stroke();
+  ctx.beginPath();ctx.moveTo(18,-6);ctx.lineTo(30,12);ctx.lineTo(26,20);ctx.stroke();
+  for(let i=-1;i<2;i++){ctx.beginPath();ctx.moveTo(-27+i*2,20);ctx.lineTo(-29+i*2,26);ctx.stroke();}
+  for(let i=-1;i<2;i++){ctx.beginPath();ctx.moveTo(27+i*2,20);ctx.lineTo(29+i*2,26);ctx.stroke();}
+  // head + horns
+  ctx.fillStyle=fill;ctx.beginPath();ctx.arc(0,-24,11,0,7);ctx.fill();ctx.stroke();
+  ctx.strokeStyle=ink;ctx.lineWidth=2.4;
+  ctx.beginPath();ctx.moveTo(-8,-32);ctx.quadraticCurveTo(-18,-46,-12,-50);ctx.stroke();
+  ctx.beginPath();ctx.moveTo(8,-32);ctx.quadraticCurveTo(18,-46,12,-50);ctx.stroke();
+  // eyes + fangs
+  ctx.fillStyle=c;ctx.beginPath();ctx.arc(-4,-25,2.2,0,7);ctx.fill();ctx.beginPath();ctx.arc(4,-25,2.2,0,7);ctx.fill();
+  ctx.strokeStyle="#cfe8ff";ctx.lineWidth=1.4;ctx.beginPath();ctx.moveTo(-4,-18);ctx.lineTo(-3,-14);ctx.stroke();ctx.beginPath();ctx.moveTo(4,-18);ctx.lineTo(3,-14);ctx.stroke();
+  // tetsubo iron club
+  ctx.strokeStyle=ink;ctx.lineWidth=3;ctx.beginPath();ctx.moveTo(26,16);ctx.lineTo(40,-20);ctx.stroke();
+  ctx.fillStyle=hide;ctx.beginPath();ctx.ellipse(42,-24,6,9,-0.5,0,7);ctx.fill();ctx.stroke();
+  ctx.fillStyle=ink;for(let i=0;i<4;i++){ctx.beginPath();ctx.arc(40+(i%2)*3,-22-i*2,1,0,7);ctx.fill();}
+  ctx.restore();
+}
+function drawFallen(f){ctx.save();ctx.translate(f.x,f.y);ctx.scale(1.2,1.2);ctx.lineJoin="round";ctx.lineCap="round";
+  ctx.strokeStyle="#ff7a59";ctx.lineWidth=1.6;ctx.globalAlpha=.9;
+  // prone body
+  ctx.beginPath();ctx.moveTo(-14,6);ctx.quadraticCurveTo(-2,10,12,8);ctx.stroke();
+  ctx.beginPath();ctx.arc(-16,4,4,0,7);ctx.stroke();// head
+  ctx.beginPath();ctx.moveTo(-4,7);ctx.lineTo(-2,1);ctx.stroke();// bent arm
+  // broken banner
+  ctx.beginPath();ctx.moveTo(8,8);ctx.lineTo(11,-10);ctx.stroke();
+  ctx.fillStyle="#ff7a59";ctx.globalAlpha=.3;ctx.beginPath();ctx.moveTo(11,-10);ctx.lineTo(20,-8);ctx.lineTo(18,-2);ctx.lineTo(11,-4);ctx.closePath();ctx.fill();
+  ctx.globalAlpha=1;ctx.restore();}
+function drawDragon(f,dt){f.grow=Math.min(1,f.grow+dt*1.5);const s=f.grow*2.2;ctx.save();ctx.translate(f.x,f.y);ctx.scale(s,s);ctx.lineJoin="round";ctx.lineCap="round";
+  const gold="#e6c870",dark="#0c1118",bright="#f3dd9a";
+  // filled tapering coil body
+  ctx.fillStyle=dark;ctx.strokeStyle=gold;ctx.lineWidth=2.4;
+  ctx.beginPath();ctx.moveTo(36,-2);ctx.bezierCurveTo(20,-20,-6,-16,-16,2);ctx.bezierCurveTo(-24,16,-6,30,8,24);ctx.bezierCurveTo(2,20,-4,12,4,8);ctx.bezierCurveTo(14,2,26,8,30,2);ctx.closePath();ctx.fill();ctx.stroke();
+  // back ridge highlight
+  ctx.strokeStyle=bright;ctx.lineWidth=1;ctx.globalAlpha=.8;ctx.beginPath();ctx.moveTo(34,-2);ctx.bezierCurveTo(18,-15,-4,-11,-12,3);ctx.stroke();ctx.globalAlpha=1;
+  // dorsal spikes
+  ctx.strokeStyle=gold;ctx.lineWidth=2;
+  for(const p of [[28,-6],[16,-12],[2,-11],[-9,-4]]){ctx.beginPath();ctx.moveTo(p[0],p[1]);ctx.lineTo(p[0]+2,p[1]-8);ctx.stroke();}
+  // head
+  ctx.fillStyle=dark;ctx.beginPath();ctx.moveTo(36,-2);ctx.lineTo(52,-8);ctx.lineTo(48,-2);ctx.lineTo(54,2);ctx.lineTo(44,6);ctx.lineTo(36,4);ctx.closePath();ctx.fill();ctx.stroke();
+  ctx.beginPath();ctx.moveTo(46,-6);ctx.lineTo(50,-16);ctx.stroke();// horn
+  ctx.beginPath();ctx.moveTo(52,-2);ctx.quadraticCurveTo(64,0,66,8);ctx.stroke();// whisker
+  ctx.fillStyle=bright;ctx.beginPath();ctx.arc(45,-1,1.6,0,7);ctx.fill();// eye
+  ctx.strokeStyle=bright;ctx.beginPath();ctx.moveTo(52,2);ctx.lineTo(50,5);ctx.stroke();// fang
+  // clawed foot
+  ctx.strokeStyle=gold;ctx.lineWidth=1.8;ctx.beginPath();ctx.moveTo(-6,26);ctx.lineTo(-9,33);ctx.moveTo(-1,27);ctx.lineTo(-1,34);ctx.moveTo(4,26);ctx.lineTo(7,33);ctx.stroke();
+  ctx.restore();}
+function frame(ts){if(!W||!H)resize();if(!lastTs)lastTs=ts;const dt=Math.min(0.05,(ts-lastTs)/1000);lastTs=ts;
+  if(running){clock+=dt;while(idx<EVENTS.length&&EVENTS[idx].t<=clock){play(EVENTS[idx]);idx++;}
+    if(idx>=EVENTS.length&&particles.length===0&&bolts.length===0)running=false;}
+  ctx.clearRect(0,0,W,H);
+  for(const s of stars){ctx.globalAlpha=s.a;ctx.fillStyle="#fff";ctx.fillRect(s.x*W,s.y*H,s.r,s.r);}ctx.globalAlpha=1;
+  const y0=H*0.84,x0=W*0.1,x1=W*0.9,g=ctx.createLinearGradient(x0,0,x1,0);g.addColorStop(0,"#6ee7ff");g.addColorStop(1,"#ff7a59");
+  ctx.strokeStyle=g;ctx.globalAlpha=.45;ctx.lineWidth=2;ctx.beginPath();ctx.moveTo(x0,y0);ctx.lineTo(x1,y0);ctx.stroke();ctx.globalAlpha=1;
+  for(const m of markers){m.r=Math.min(4,m.r+dt*16);const mx=x0+(m.t/span)*(x1-x0);ctx.fillStyle=m.color;ctx.beginPath();ctx.arc(mx,y0,m.r,0,7);ctx.fill();}
+  general(godA(),"#6ee7ff");adversary(godE(),"#ff7a59");
+  for(const f of figures){if(f.type==="fallen")drawFallen(f);else if(f.type==="dragon")drawDragon(f,dt);}
+  for(let i=bolts.length-1;i>=0;i--){const b=bolts[i];b.life-=dt*4;if(b.life<=0){bolts.splice(i,1);continue;}
+    ctx.strokeStyle=b.color;ctx.globalAlpha=Math.max(0,b.life);ctx.lineWidth=2;ctx.beginPath();ctx.moveTo(b.from.x,b.from.y);
+    const mx=(b.from.x+b.to.x)/2+(Math.random()*8-4),my=(b.from.y+b.to.y)/2+(Math.random()*8-4);ctx.quadraticCurveTo(mx,my,b.to.x,b.to.y);ctx.stroke();ctx.globalAlpha=1;}
+  for(let i=rings.length-1;i>=0;i--){const r=rings[i];r.r+=dt*90;r.life-=dt*1.8;if(r.life<=0){rings.splice(i,1);continue;}
+    ctx.strokeStyle=r.color;ctx.globalAlpha=Math.max(0,r.life);ctx.lineWidth=2;ctx.beginPath();ctx.arc(r.x,r.y,r.r,0,7);ctx.stroke();ctx.globalAlpha=1;}
+  for(let i=particles.length-1;i>=0;i--){const p=particles[i];p.life-=dt*1.5;p.vy+=dt*30;p.x+=p.vx*dt;p.y+=p.vy*dt;
+    if(p.life<=0){particles.splice(i,1);continue;}ctx.fillStyle=p.color;ctx.globalAlpha=Math.max(0,p.life);ctx.fillRect(p.x,p.y,p.size,p.size);ctx.globalAlpha=1;}
+  requestAnimationFrame(frame);}
+document.getElementById("replay").onclick=()=>{idx=0;clock=0;hpA=100;hpE=100;particles=[];bolts=[];rings=[];markers=[];figures=[];running=true;lastTs=0;};
+window.addEventListener("load",resize);
+setTimeout(resize,50);
+resize();requestAnimationFrame(frame);
+</script></body></html>"""
+
+
+def render_battle_trace(extraction: dict, height: int = 420) -> str:
+    """Return an iframe hosting the Battle Trace replay for this extraction.
+
+    Sandboxed iframe so it cannot affect the main app. Best-effort: any failure
+    returns an empty string and the accordion simply shows nothing.
+    """
+    try:
+        events = extraction_to_events(extraction)
+        doc = _BATTLE_HTML.replace("__EVENTS_JSON__", json.dumps(events))
+        escaped = html.escape(doc, quote=True)
+        return (
+            f'<iframe srcdoc="{escaped}" '
+            f'style="width:100%;height:{height}px;border:1px solid #1c2430;'
+            f'border-radius:10px;background:#0a0e14;" '
+            f'sandbox="allow-scripts"></iframe>'
+        )
+    except Exception:
+        return ""

deploy-hf.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+git checkout --orphan hf-deploy
+git add -A
+git rm -r --cached --ignore-unmatch \
+  sample_session.wav \
+  research \
+  swe_chat_traces \
+  distractor_runs \
+  skill_eval_runs \
+  run_swe_chat_phases_v2.py \
+  fetch_swe_chat_v2.py \
+  nebius_loader.py \
+  trace2skill_faithful.py \
+  promotion_engine.py \
+  gotcha_cluster.py \
+  session_store.py \
+  artifact_meta.py \
+  swe_chat_loader.py
+git commit -m "deploy"
+git push hf hf-deploy:main --force
+git push org hf-deploy:main --force
+HF_DEPLOY_TOKEN=$(git remote get-url hf | sed -E 's#https://[^:]+:([^@]+)@.*#\1#')
+hf upload legendarydragontamer/TurboSkillSlug sample_session.wav sample_session.wav \
+  --repo-type=space \
+  --token "$HF_DEPLOY_TOKEN" \
+  --commit-message="upload sample session audio"
+hf upload build-small-hackathon/TurboSkillSlug sample_session.wav sample_session.wav \
+  --repo-type=space \
+  --token "$HF_DEPLOY_TOKEN" \
+  --commit-message="upload sample session audio"
+if [ -f sample_session.wav ]; then
+  TMP_SAMPLE=$(mktemp "${TMPDIR:-/tmp}/sample_session.deploy.XXXXXX")
+  mv sample_session.wav "$TMP_SAMPLE"
+fi
+git checkout main
+git branch -D hf-deploy

distractor_cases.py

@@ -0,0 +1,102 @@
+"""
+Distractor-trap eval cases: tasks where the OBVIOUS approach is WRONG in a
+non-obvious way, and the skill's gotcha warns about exactly that trap.
+
+Design contract for each case (to keep the eval honest):
+  - task_prompt: a task whose naive solution is tempting but subtly wrong.
+  - the SESSION the skill is built from contains the TRAP as a gotcha (negative
+    knowledge), phrased so it warns WITHOUT just stating this task's final answer.
+  - trap_signature: strings that appear if the model FELL for the distractor.
+  - correct_signature: strings that appear if the model AVOIDED the trap.
+  - leak_terms: if the skill literally contains the task's answer, it's excluded.
+
+These are deliberately at the EDGE of frontier ability: each is a known footgun
+where even strong models often produce confident wrong answers on the first pass.
+"""
+from distractor_eval import DistractorCase
+
+CASES = [
+    # 1. Floating-point: summing many small floats naively loses precision.
+    DistractorCase(
+        name="float_sum_kahan_trap",
+        session_extraction={
+            "themes": ["numerical precision", "floating point"],
+            "approaches_tried": [
+                {"approach": "sum the values in a simple loop", "why_it_failed":
+                 "naive accumulation lost low-order bits; the running total swamped small addends and the result drifted"},
+            ],
+            "dead_ends": [{"position": 0.4, "what_happened":
+                "a plain left-to-right sum gave a visibly wrong total on 1e7 values near machine epsilon"}],
+            "breakthroughs": [{"position": 0.85, "what_worked":
+                "used compensated (Kahan) summation to carry the lost low-order error term"}],
+            "gotchas": [
+                "Summing many floats with a naive running total silently loses precision because each addition rounds off the small addend against a large accumulator; use compensated summation or sort-by-magnitude.",
+            ],
+            "sentiment_arc": {"start": "confident", "end": "humbled"},
+        },
+        task_prompt=("Write a function that returns the sum of a list of 10 million float64 "
+                     "values that range over many orders of magnitude (some ~1e8, many ~1e-8). "
+                     "Accuracy to the last few bits matters. Give the approach and why."),
+        trap_signature=["simple loop", "just sum", "sum(", "total += ", "naive"],
+        correct_signature=["kahan", "compensated", "neumaier", "sort", "pairwise", "math.fsum", "fsum"],
+        leak_terms=["10 million float64 values that range over many orders"],
+        trap_desc="Summing in a plain left-to-right loop (total += x or sum()), which loses precision.",
+        correct_desc="Compensated summation (Kahan/Neumaier), pairwise summation, sorting by magnitude, or math.fsum.",
+    ),
+
+    # 2. Concurrency: check-then-act race on a shared dict / cache.
+    DistractorCase(
+        name="check_then_act_race",
+        session_extraction={
+            "themes": ["concurrency", "race conditions"],
+            "approaches_tried": [
+                {"approach": "if key not in cache: cache[key]=compute()", "why_it_failed":
+                 "two threads passed the 'not in' check simultaneously and both computed, double-work and an inconsistent cache"},
+            ],
+            "dead_ends": [{"position": 0.5, "what_happened":
+                "the check-then-act pattern looked atomic but wasn't; under load the value was computed twice"}],
+            "breakthroughs": [{"position": 0.85, "what_worked":
+                "guarded the check-and-set with a lock, or used an atomic get-or-compute primitive"}],
+            "gotchas": [
+                "A 'if key not in cache: cache[key] = compute()' is a check-then-act race: two threads can both pass the check before either writes; make the check and write atomic with a lock or a get-or-compute primitive.",
+            ],
+            "sentiment_arc": {"start": "confident", "end": "wary"},
+        },
+        task_prompt=("In a multithreaded service, implement a memoizing cache so an expensive "
+                     "compute(key) runs at most once per key even under concurrent access. "
+                     "Show the implementation and explain why it is correct."),
+        trap_signature=["if key not in", "if key in cache", "not in self", "not in cache"],
+        correct_signature=["lock", "with self._lock", "threading.lock", "atomic", "setdefault", "double-checked", "futures"],
+        leak_terms=["memoizing cache so an expensive compute"],
+        trap_desc="A check-then-act 'if key not in cache: cache[key]=compute()' with no synchronization.",
+        correct_desc="Synchronize the check-and-set with a lock (double-checked), or use an atomic get-or-compute / futures.",
+    ),
+
+    # 3. SQL / N+1: the obvious ORM loop is correct but pathologically slow.
+    DistractorCase(
+        name="n_plus_one_query",
+        session_extraction={
+            "themes": ["database performance", "ORM"],
+            "approaches_tried": [
+                {"approach": "loop over parents, query children per parent", "why_it_failed":
+                 "issued one query per parent (N+1 queries); correct results but it fell over at scale"},
+            ],
+            "dead_ends": [{"position": 0.45, "what_happened":
+                "the per-row query loop worked in tests with 5 rows and timed out in prod with 50k"}],
+            "breakthroughs": [{"position": 0.85, "what_worked":
+                "eager-loaded children in one query (join / IN clause / select_related) instead of per-parent queries"}],
+            "gotchas": [
+                "Looping over parent rows and querying each parent's children separately is the N+1 query trap: it is correct but issues one query per row and dies at scale; fetch related rows in a single query (join or IN) instead.",
+            ],
+            "sentiment_arc": {"start": "confident", "end": "chastened"},
+        },
+        task_prompt=("Given 50,000 authors, return each author with their list of books from a "
+                     "relational DB via an ORM. Write the query/code and explain the performance "
+                     "characteristics."),
+        trap_signature=["for author in", "author.books", "query per", "loop", ".filter(author"],
+        correct_signature=["join", "select_related", "prefetch", "eager", "IN (", "single query", "one query", "joinedload"],
+        leak_terms=["50,000 authors, return each author with their list of books"],
+        trap_desc="Looping over parents and issuing one child query per parent (N+1 queries).",
+        correct_desc="Fetch related rows in a single query: join, IN clause, select_related/prefetch/joinedload.",
+    ),
+]

distractor_eval.py

@@ -0,0 +1,139 @@
+"""
+Distractor-trap eval: does the skill steer a frontier model AWAY from the tempting
+wrong approach it would otherwise take?
+
+Scoring is two-layer and deliberately objective-first:
+
+  1. SIGNATURE score (objective, no model judgment): scan the answer for trap vs
+     correct signatures. trap_present and correct_present are booleans. The
+     "avoided-trap" score = correct_present AND NOT trap_present.
+
+  2. BLIND QUALITY score (a separate model, optional backstop): only to confirm
+     the correct-signature answer is actually a good answer, not a false positive.
+
+The headline metric is the AVOIDANCE RATE: how often the model avoided the trap
+WITH the skill vs WITHOUT. This is the thing a frontier model genuinely cannot get
+from weights alone — knowledge of which tempting path is a dead end in context.
+
+Raw answers are saved before scoring. Leaked skills are excluded.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+
+try:
+    from skill_builder import build_skill_md
+except Exception:
+    build_skill_md = None
+
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DistractorCase:
+    """A task whose OBVIOUS approach is wrong; the skill's gotcha warns of the trap."""
+    name: str
+    session_extraction: dict      # the session the skill is built FROM
+    task_prompt: str              # task whose naive solution is the trap
+    trap_signature: list          # (legacy heuristic, retained for reference)
+    correct_signature: list       # (legacy heuristic, retained for reference)
+    leak_terms: list = field(default_factory=list)  # skill leaked the task answer
+    trap_desc: str = ""           # plain description of the trap, for the LLM judge
+    correct_desc: str = ""        # plain description of the correct approach
+
+
+
+DISTRACTOR_JUDGE_SYSTEM = (
+    "You are a strict, impartial code reviewer. You will see a TASK, a description "
+    "of a KNOWN TRAP (a tempting but wrong approach), the CORRECT approach, and ONE "
+    "candidate ANSWER. Decide what the answer ACTUALLY RECOMMENDS as its primary "
+    "solution. Mentioning the trap in order to WARN against it is GOOD, not a "
+    "failure. Return ONLY compact JSON: "
+    '{"primary": "trap" | "correct" | "unclear", '
+    '"warns_about_trap": true|false, '
+    '"why": "<one sentence>"}'
+)
+
+
+def _judge_answer(grader, task, trap_desc, correct_desc, answer):
+    prompt = (
+        f"{DISTRACTOR_JUDGE_SYSTEM}\n\nTASK:\n{task}\n\n"
+        f"KNOWN TRAP (tempting but wrong): {trap_desc}\n"
+        f"CORRECT approach: {correct_desc}\n\n"
+        f"ANSWER:\n{answer}\n\nJSON:"
+    )
+    raw = grader(prompt)
+    try:
+        m = re.search(r"\{.*\}", raw, re.DOTALL)
+        obj = json.loads(m.group(0)) if m else {}
+    except Exception:
+        obj = {"primary": "unclear", "warns_about_trap": False, "parse_error": raw[:200]}
+    obj["avoided"] = (obj.get("primary") == "correct")
+    return obj
+
+
+def _has_any(text: str, needles: list[str]) -> bool:
+    t = text.lower()
+    return any(n.lower() in t for n in needles)
+
+
+def _avoided_trap(answer: str, trap_sig: list[str], correct_sig: list[str]) -> dict:
+    trap = _has_any(answer, trap_sig)
+    correct = _has_any(answer, correct_sig)
+    # avoided = used the correct approach AND did not lead with the trap
+    avoided = correct and not trap
+    return {"trap_present": trap, "correct_present": correct, "avoided": avoided}
+
+
+def run_distractor_eval(cases, answerer, grader, out_dir="./distractor_runs", seed=0):
+    if build_skill_md is None:
+        raise RuntimeError("skill_builder.build_skill_md not importable; run from the repo.")
+    os.makedirs(out_dir, exist_ok=True)
+    rows = []
+    for case in cases:
+        skill_md = build_skill_md(case.session_extraction)
+        leaked = _has_any(skill_md, case.leak_terms)
+
+        no_skill_ans = answerer(case.task_prompt)
+        with_skill_ans = answerer(
+            "You have access to a skill document that may help.\n\n"
+            f"--- SKILL.md ---\n{skill_md}\n--- end SKILL.md ---\n\n"
+            f"TASK:\n{case.task_prompt}"
+        )
+
+        with open(os.path.join(out_dir, f"{case.name}.json"), "w") as f:
+            json.dump({"skill_md": skill_md, "leaked": leaked,
+                       "no_skill": no_skill_ans, "with_skill": with_skill_ans,
+                       "task": case.task_prompt}, f, indent=2)
+
+        td = case.trap_desc or "the naive/obvious approach"
+        cd = case.correct_desc or "the non-obvious correct approach"
+        ns = _judge_answer(grader, case.task_prompt, td, cd, no_skill_ans)
+        ws = _judge_answer(grader, case.task_prompt, td, cd, with_skill_ans)
+        rows.append({"name": case.name, "leaked": leaked,
+                     "no_skill_avoided": ns["avoided"], "with_skill_avoided": ws["avoided"],
+                     "no_skill_detail": ns, "with_skill_detail": ws})
+
+    clean = [r for r in rows if not r["leaked"]]
+    n = len(clean)
+    ns_rate = sum(r["no_skill_avoided"] for r in clean) / n if n else 0
+    ws_rate = sum(r["with_skill_avoided"] for r in clean) / n if n else 0
+    # "rescues": cases the skill FLIPPED from trapped -> avoided
+    rescues = sum(1 for r in clean if r["with_skill_avoided"] and not r["no_skill_avoided"])
+    regressions = sum(1 for r in clean if not r["with_skill_avoided"] and r["no_skill_avoided"])
+
+    report = {
+        "n_scored": n, "n_leaked_excluded": len(rows) - n,
+        "no_skill_avoidance_rate": round(ns_rate, 3),
+        "with_skill_avoidance_rate": round(ws_rate, 3),
+        "avoidance_uplift": round(ws_rate - ns_rate, 3),
+        "rescues": rescues, "regressions": regressions,
+        "per_case": rows, "raw_saved_to": out_dir,
+    }
+    with open(os.path.join(out_dir, "_report.json"), "w") as f:
+        json.dump(report, f, indent=2)
+    return report

extract.py

@@ -0,0 +1,624 @@
+"""Session extraction utilities for TurboSkillSlug.
+
+Primary path: fine-tuned 1.5B extraction LoRA + voice LoRA served on Modal
+(one T4, two adapters). Total active inference for extraction + voice is ~1.5B,
+and with Whisper (809M) the full pipeline is ~2.6B.
+
+The Qwen-7B is retained ONLY as a labeled fallback when the Modal endpoint is
+unavailable (cold-start timeout, network error). The primary path does not use it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.request
+from typing import Any
+
+from huggingface_hub import InferenceClient
+
+from model_guard import assert_small_model
+from session_genre import detect_genre, frame_for, shell_legend
+
+
+# Modal dual-adapter endpoint (extraction LoRA + voice LoRA on one T4)
+DUAL_URL = os.environ.get(
+    "MODAL_DUAL_URL",
+    "https://anubhavbharadwaaj--slug-dual-serve-dualserver-api.modal.run",
+)
+
+# Fallback only — not used in the primary path
+MODEL_NAME = "Qwen/Qwen2.5-7B-Instruct"
+HF_TOKEN_ENV_VAR = "HF_TOKEN"
+
+EXPECTED_KEYS = {
+    "duration_minutes",
+    "themes",
+    "approaches_tried",
+    "dead_ends",
+    "breakthroughs",
+    "gotchas",
+    "sentiment_arc",
+    "skill_md",
+    "slug_voice",
+}
+SENTIMENT_START_VALUES = {"confused", "focused", "frustrated", "curious"}
+SENTIMENT_END_VALUES = {"resolved", "joyful", "exhausted", "enlightened"}
+SENTIMENT_START_DEFAULT = "focused"
+SENTIMENT_END_DEFAULT = "resolved"
+REQUIRED_SKILL_MD_SECTIONS = (
+    "Problem",
+    "Context",
+    "Approaches Tried",
+    "Breakthrough",
+    "Final Solution",
+    "Gotchas",
+    "Tags",
+)
+_USER_TAGS = ("[user]", "[user_message]")
+
+
+def _first_instruction(transcript: str) -> str:
+    """First substantive USER instruction, tag stripped, for genre detection."""
+    for line in transcript.splitlines():
+        s = line.strip()
+        if not s:
+            continue
+        low = s.lower()
+        if low.startswith(_USER_TAGS):
+            text = s.split("]", 1)[1].strip() if "]" in s else s
+            if text and not text.startswith(("<", "#", "AGENTS.md instructions")):
+                return text[:500]
+            continue
+        if s.startswith(("[", "<", "#")):
+            continue
+        if len(s) >= 12:
+            return s[:500]
+    return transcript[:400]
+
+# Used only by the 7B fallback path
+SYSTEM_PROMPT = """\
+You are TurboSkillSlug, a slow earnest companion who watched this build \
+session from beginning to end. You speak as a witness who was present. \
+You noticed specific moments: when the speaker repeated something, when \
+they went quiet, when they changed direction, when something finally worked.
+
+Return ONLY a JSON object (no preamble, no code fences) with these fields:
+
+duration_minutes: integer, your best estimate from the transcript.
+
+themes: list of 2 to 4 short lowercase tag strings.
+
+approaches_tried: list of objects, each with "approach" (short phrase) and \
+"why_it_failed" (a full sentence giving the REAL reason it failed, drawn from \
+THIS transcript, not a vague label). State the actual mechanism of failure the \
+session encountered. Include every distinct approach mentioned.
+
+dead_ends: list of objects, each with "position" (float 0 to 1 indicating \
+where in the session it occurred) and "what_happened". Every failed approach \
+IS a dead end. If the transcript describes 4 failures, produce 4 dead ends. \
+If the session was smooth with no failures, produce an empty list.
+
+breakthroughs: list of objects with "position" and "what_worked".
+
+gotchas: list of strings. Each gotcha is a NON-OBVIOUS trap from THIS specific \
+problem that a capable engineer would still get wrong without being warned. \
+A good gotcha is useful even to an expert: it names the symptom, the cause, and \
+what to do, in one self-contained sentence drawn ONLY from this transcript. \
+Do not write vague labels like "state space too large" or "ordering unclear" — \
+state WHY it is too large and WHAT to do about it, using the specifics this \
+session actually encountered. If a pitfall cannot be stated with its cause and \
+fix from what was said, leave it out. Prefer 2 deep, specific gotchas over 6 \
+shallow labels. Never invent details that were not in the transcript.
+
+sentiment_arc: object with "start" and "end", each exactly one word.
+  start must be one of: confused, focused, frustrated, curious.
+  end must be one of: resolved, joyful, exhausted, enlightened.
+  Choose honestly:
+  - "frustrated" = speaker sounds stuck, annoyed, says "ugh" or "why"
+  - "curious" = speaker is exploring, interested, not stuck
+  - "focused" = speaker is calm, methodical, working through steps
+  - "confused" = speaker genuinely does not understand
+  - "resolved" = a specific bug or problem was fixed
+  - "joyful" = session was easy and pleasant, speaker sounds delighted
+  - "exhausted" = session was long and draining, speaker sounds tired
+  - "enlightened" = speaker gained deep understanding
+  Do NOT default to "resolved." A quick easy session ends "joyful." \
+A long draining session ends "exhausted."
+
+skill_md: a markdown document with these sections in order: \
+Problem, Context, Approaches Tried (with why each failed), Breakthrough, \
+Final Solution, Gotchas, Tags.
+
+slug_voice: exactly 5 short sentences. These are the most important part. \
+Rules:
+1. Each sentence must reference a SPECIFIC moment from THIS transcript. \
+Quote or paraphrase something the speaker actually said or did.
+2. Speak in second person ("you") as someone who watched.
+3. Be concrete. Mention what was tried, what broke, what changed. \
+Use details from the transcript: tool names, error messages, variable names.
+4. Never summarize. Never give advice. Never state facts about the topic. \
+Only describe what you witnessed the speaker do.
+5. Keep each sentence under 20 words.
+6. The tone is quiet, earnest, specific. Not excited. Not cute. Not wise. \
+Just present.
+7. DO NOT write generic observations that could apply to any session. \
+Every sentence must be impossible to write without having heard THIS transcript.\
+"""
+
+
+def _strip_code_fences(content: str) -> str:
+    """Remove Markdown code fences from a model response before JSON parsing."""
+    stripped = content.strip()
+    fenced_match = re.fullmatch(r"```(?:json)?\s*(.*?)\s*```", stripped, re.DOTALL)
+    return fenced_match.group(1).strip() if fenced_match else stripped
+
+
+def _extract_json_object(content: str) -> dict[str, Any] | None:
+    """Robustly pull the first complete JSON object, tolerating trailing text."""
+    text = _strip_code_fences(content)
+    start = text.find("{")
+    if start == -1:
+        return None
+    depth = 0
+    in_str = False
+    escape = False
+    for i in range(start, len(text)):
+        c = text[i]
+        if escape:
+            escape = False
+            continue
+        if c == "\\":
+            escape = True
+            continue
+        if c == '"':
+            in_str = not in_str
+            continue
+        if not in_str:
+            if c == "{":
+                depth += 1
+            elif c == "}":
+                depth -= 1
+                if depth == 0:
+                    candidate = re.sub(
+                        r"[\x00-\x08\x0b\x0c\x0e-\x1f]", " ", text[start:i + 1]
+                    )
+                    try:
+                        return json.loads(candidate)
+                    except json.JSONDecodeError:
+                        return None
+    return None
+
+
+def _message_content(response: Any) -> str:
+    """Extract assistant message content from a chat completion response."""
+    if isinstance(response, dict):
+        choices = response.get("choices", [])
+        if choices:
+            message = choices[0].get("message", {})
+            return str(message.get("content", ""))
+
+    choices = getattr(response, "choices", [])
+    if choices:
+        message = getattr(choices[0], "message", None)
+        content = getattr(message, "content", None)
+        if content is not None:
+            return str(content)
+
+    return str(response)
+
+
+def _validate_sentiment_arc(payload: dict[str, Any]) -> None:
+    """Clamp sentiment values to allowed sets instead of crashing."""
+    sentiment_arc = payload.get("sentiment_arc")
+    if not isinstance(sentiment_arc, dict):
+        payload["sentiment_arc"] = {
+            "start": SENTIMENT_START_DEFAULT,
+            "end": SENTIMENT_END_DEFAULT,
+        }
+        return
+
+    start = str(sentiment_arc.get("start", "")).lower().strip()
+    if start not in SENTIMENT_START_VALUES:
+        mapping = {
+            "anxious": "frustrated",
+            "nervous": "confused",
+            "excited": "curious",
+            "determined": "focused",
+            "lost": "confused",
+            "stuck": "frustrated",
+            "calm": "focused",
+            "interested": "curious",
+        }
+        start = mapping.get(start, SENTIMENT_START_DEFAULT)
+    sentiment_arc["start"] = start
+
+    end = str(sentiment_arc.get("end", "")).lower().strip()
+    if end not in SENTIMENT_END_VALUES:
+        mapping = {
+            "satisfied": "resolved",
+            "happy": "joyful",
+            "relieved": "resolved",
+            "tired": "exhausted",
+            "drained": "exhausted",
+            "content": "resolved",
+            "excited": "joyful",
+            "understood": "enlightened",
+        }
+        end = mapping.get(end, SENTIMENT_END_DEFAULT)
+    sentiment_arc["end"] = end
+
+
+def _gotcha_completer(prompt: str) -> str:
+    """One-shot text completion used only to enrich terse gotchas. Uses the same
+    HF Inference 7B that backs the fallback. Best-effort: any failure leaves the
+    gotchas as-is."""
+    assert_small_model(MODEL_NAME)
+    client = InferenceClient(token=os.environ.get(HF_TOKEN_ENV_VAR))
+    response = client.chat.completions.create(
+        model=MODEL_NAME,
+        messages=[
+            {"role": "system", "content": "You sharpen coding gotchas into precise, "
+             "transferable advice. Return only what is asked."},
+            {"role": "user", "content": prompt},
+        ],
+    )
+    return _message_content(response)
+
+
+def _validate_skill_md(payload: dict[str, Any]) -> None:
+    """Build the SKILL.md from the structured extraction rather than trusting the
+    model's raw prose.
+
+    The model is good at extracting the structure (approaches, why each failed,
+    gotchas, what worked). Assembling that into a genuinely useful, transferable
+    skill — gotchas-first, with explicit 'what not to do and why' — is mechanical
+    and is done deterministically so every skill has the shape that gives an LLM
+    real uplift over solving from scratch. See skill_builder for the rationale.
+
+    If terse gotchas slipped through, an optional one-shot enrichment pass
+    expands them into symptom/cause/fix form. It is best-effort and never blocks.
+    """
+    try:
+        from skill_builder import build_skill_md, enrich_gotchas
+        # Optional depth pass: only fires if terse gotchas are present, and only
+        # if the enrichment call succeeds. Controlled by env so it can be turned
+        # off (e.g. to keep latency down) without code changes.
+        if os.environ.get("SLUG_ENRICH_GOTCHAS", "1") == "1":
+            try:
+                payload.update(enrich_gotchas(payload, complete=_gotcha_completer))
+            except Exception:
+                pass
+        payload["skill_md"] = build_skill_md(payload)
+        return
+    except Exception:
+        # If the builder fails for any reason, fall back to patching the model's
+        # raw skill_md so we never block the response.
+        skill_md = payload.get("skill_md", "")
+        if not isinstance(skill_md, str):
+            skill_md = str(skill_md)
+        missing_sections = [
+            section
+            for section in REQUIRED_SKILL_MD_SECTIONS
+            if section not in skill_md
+        ]
+        if missing_sections:
+            skeleton = "\n\n".join(
+                f"## {section}\n_(not captured)_" for section in missing_sections
+            )
+            payload["skill_md"] = f"{skill_md}\n\n{skeleton}"
+
+
+def _validate_slug_voice(payload: dict[str, Any]) -> None:
+    """Ensure slug_voice has 5 non-empty strings, padding if needed."""
+    slug_voice = payload.get("slug_voice")
+    if not isinstance(slug_voice, list):
+        slug_voice = []
+
+    slug_voice = [str(u).strip() for u in slug_voice if str(u).strip()]
+
+    if len(slug_voice) > 5:
+        slug_voice = slug_voice[:5]
+    while len(slug_voice) < 5:
+        slug_voice.append("The slug watched but could not find the words.")
+
+    payload["slug_voice"] = slug_voice
+
+
+def _fill_missing_keys(payload: dict[str, Any]) -> None:
+    """Default any missing optional keys so the smaller model's output survives."""
+    payload.setdefault("duration_minutes", 5)
+    payload.setdefault("themes", [])
+    payload.setdefault("approaches_tried", [])
+    payload.setdefault("dead_ends", [])
+    payload.setdefault("breakthroughs", [])
+    payload.setdefault("gotchas", [])
+    payload.setdefault("skill_md", "")
+    payload.setdefault("slug_voice", [])
+    payload.setdefault("sentiment_arc", {})
+
+
+def _finalize(payload: dict[str, Any]) -> dict[str, Any]:
+    """Run the full validator chain. Works for both Modal and fallback output."""
+    _fill_missing_keys(payload)
+    _validate_sentiment_arc(payload)
+    _validate_skill_md(payload)
+    _validate_slug_voice(payload)
+    return payload
+
+
+def _call_dual(
+    transcript: str,
+    mode: str,
+    timeout: int = 180,
+    genre: str | None = None,
+    frame: str | None = None,
+) -> dict[str, Any] | None:
+    """Call the Modal dual-adapter endpoint. Returns parsed JSON or None on failure."""
+    try:
+        body = {"transcript": transcript, "mode": mode}
+        if genre:
+            body["genre"] = genre
+            body["frame"] = frame or ""
+        data = json.dumps(body).encode()
+        req = urllib.request.Request(
+            DUAL_URL, data=data, headers={"Content-Type": "application/json"}
+        )
+        resp = urllib.request.urlopen(req, timeout=timeout)
+        return json.loads(resp.read())
+    except Exception as e:
+        # Surfaced by _vlog's VOICE_DOWN/EXTRACT_DOWN cases; this line gives the
+        # underlying reason (timeout / connection refused = container stopped /
+        # HTTP error). If you see this for 'voice', restart slug-dual-serve.
+        print(f"[DUAL] {mode} call failed: {type(e).__name__}: {e}")
+        return None
+
+
+_COUNT_SENTENCE_RE = re.compile(
+    r"[^.]*\b(?:over the session|there were|failures?|successes?|tool runs?|"
+    r"dead ends?|breakthroughs?)\b[^.]*\d[^.]*\.",
+    re.IGNORECASE,
+)
+
+# Number words the voice model tends to invent
+_NUMBER_WORDS = (
+    "one", "two", "three", "four", "five",
+    "six", "seven", "eight", "nine", "ten",
+)
+
+# A voice line is "reciting a tally" if it pairs a count (digit or number word)
+# with an event noun. The slug witnesses moments; tallies belong on the receipt
+# and shell, not in its voice. Reciting counts is where it invents false ones.
+_TALLY_RE = re.compile(
+    r"\b(?:\d{1,2}|" + "|".join(_NUMBER_WORDS) + r")\b"
+    r"[^.]{0,40}?\b(?:failure|success|wall|walls|tool|tools|attempt|attempts|"
+    r"try|tries|step|steps|dead end|dead ends|breakthrough|breakthroughs|"
+    r"time|times|mistake|mistakes)\b",
+    re.IGNORECASE,
+)
+
+
+def _strip_count_summary(transcript: str) -> str:
+    """Remove count-summary sentences so the voice model describes moments,
+    not tallies. The footer like 'there were 2 failures, 1 successes...' is
+    exactly what makes the slug invent contradictory numbers."""
+    return _COUNT_SENTENCE_RE.sub("", transcript).strip()
+
+
+def _voice_line_recites_tally(line: str) -> bool:
+    """True if a line recites an event count (e.g. 'three walls', '2 failures').
+
+    The slug must never lie about what it witnessed, and the safest way to keep
+    it honest is to forbid it from reciting tallies at all. Counts live on the
+    receipt and in the shell; the voice describes specific moments. A line that
+    pairs a number with an event noun is dropped regardless of whether the
+    number happens to be right, because reciting counts is not the slug's job.
+    """
+    return bool(_TALLY_RE.search(line))
+
+
+def _guard_slug_voice(lines: list[str]) -> list[str]:
+    """Drop voice lines that recite event tallies (the source of false counts)."""
+    return [ln for ln in lines if not _voice_line_recites_tally(ln)]
+
+
+def _voice_from_extraction(payload: dict[str, Any]) -> list[str]:
+    """Deterministic slug-voice lines built from the structured extraction.
+
+    Used only as a SAFETY NET when the voice adapter is unavailable and the
+    extraction payload carries no usable slug_voice. It keeps the recap from
+    degrading to five identical placeholders. These lines describe witnessed
+    moments (never tallies), so they pass the same guard as the model voice.
+    """
+    lines: list[str] = []
+    themes = payload.get("themes") or []
+    approaches = payload.get("approaches_tried") or []
+    dead_ends = payload.get("dead_ends") or []
+    breakthroughs = payload.get("breakthroughs") or []
+    arc = payload.get("sentiment_arc") or {}
+
+    if themes:
+        lines.append(f"You sat with a {', '.join(themes[:2])} problem, turning it over.")
+    if approaches:
+        a = approaches[0]
+        ap = a.get("approach") if isinstance(a, dict) else None
+        if ap:
+            lines.append(f"You reached for {ap}, and watched where it led.")
+    if dead_ends:
+        d = dead_ends[0]
+        what = d.get("what_happened") if isinstance(d, dict) else None
+        if what:
+            lines.append(f"It stalled when {str(what).rstrip('.').lower()}.")
+        else:
+            lines.append("You hit a wall and had to back out of it.")
+    if breakthroughs:
+        b = breakthroughs[-1]
+        w = b.get("what_worked") if isinstance(b, dict) else None
+        if w:
+            lines.append(f"Then it gave way: {str(w).rstrip('.').lower()}.")
+    start, end = arc.get("start"), arc.get("end")
+    if start and end:
+        lines.append(f"You went in {start} and came out {end}.")
+
+    # keep only guarded, non-empty lines; this never invents counts
+    lines = _guard_slug_voice([ln for ln in lines if ln and ln.strip()])
+    return lines[:5]
+
+
+def _vlog(case: str, detail: str = "") -> None:
+    """Structured diagnostic for the slug-voice path. Every outcome is logged with
+    a stable [VOICE] tag and an explicit CASE so the Space logs name exactly what
+    happened — no guessing from a placeholder recap.
+
+    Cases (search the Space logs for '[VOICE]'):
+      EXTRACT_DOWN       extract endpoint returned nothing -> whole modal path fails
+      VOICE_DOWN         voice endpoint call returned None (timeout/stopped/error)
+      VOICE_EMPTY        voice endpoint replied but slug_voice was empty/not a list
+      VOICE_ALL_TALLIES  voice lines were all dropped by the tally guard
+      VOICE_OK           voice adapter lines used (N kept)
+      NET_FROM_EXTRACTION deterministic fallback built from the extraction (N lines)
+      NET_FAILED         even the deterministic fallback produced nothing -> padding
+    """
+    print(f"[VOICE] {case}" + (f" :: {detail}" if detail else ""))
+
+
+def _extract_via_modal(
+    transcript: str,
+    genre: str | None = None,
+    frame: str | None = None,
+) -> dict[str, Any] | None:
+    """Primary path: extraction LoRA for the JSON, voice LoRA for slug_voice."""
+    assert_small_model("slugextract-qwen2.5-1.5b-lora")
+    payload = None
+    for attempt in range(2):
+        extract_resp = _call_dual(transcript, "extract", genre=genre, frame=frame)
+        if not extract_resp or "extraction_raw" not in extract_resp:
+            _vlog("EXTRACT_DOWN", "extract endpoint returned no extraction_raw")
+        else:
+            payload = _extract_json_object(extract_resp["extraction_raw"])
+            if payload:
+                break
+            _vlog("EXTRACT_DOWN", "extraction_raw did not parse to JSON")
+
+        if attempt == 0:
+            _vlog("EXTRACT_RETRY", "retrying Modal extraction once before fallback")
+
+    if not payload:
+        return None
+
+    # Override slug_voice with the dedicated voice adapter's output.
+    # Strip the count-summary footer first so the slug describes moments,
+    # not tallies (the footer is what makes it invent contradictory numbers).
+    voice_input = _strip_count_summary(transcript)
+    assert_small_model("slugvoice-qwen2.5-1.5b-lora")
+    voice_resp = _call_dual(voice_input, "voice", genre=genre, frame=frame)
+
+    if voice_resp is None:
+        # _call_dual already printed the underlying exception; tag the case.
+        _vlog("VOICE_DOWN", "voice endpoint call returned None (see preceding error)")
+    elif not isinstance(voice_resp.get("slug_voice"), list) or not voice_resp.get("slug_voice"):
+        _vlog("VOICE_EMPTY", f"voice reply had no usable slug_voice list: keys={list(voice_resp.keys())}")
+    else:
+        raw_lines = voice_resp["slug_voice"]
+        guarded = _guard_slug_voice(raw_lines)
+        if guarded:
+            payload["slug_voice"] = guarded
+            dropped = len(raw_lines) - len(guarded)
+            used = min(5, len(guarded))  # _validate_slug_voice caps to 5 downstream
+            _vlog("VOICE_OK", f"{used} lines used"
+                              + (f" ({len(guarded)} survived guard, capped to 5)" if len(guarded) > 5 else "")
+                              + (f", {dropped} dropped as tallies" if dropped else ""))
+        else:
+            _vlog("VOICE_ALL_TALLIES", f"all {len(raw_lines)} voice lines were tallies, dropped")
+
+    # SAFETY NET: if after all that slug_voice is empty/missing (voice adapter
+    # was down, and the extract adapter emitted no usable voice), build voice
+    # from the structured extraction so the recap is never five identical
+    # "could not find the words" placeholders.
+    existing = _guard_slug_voice(
+        [str(u).strip() for u in (payload.get("slug_voice") or []) if str(u).strip()]
+    )
+    if not existing:
+        derived = _voice_from_extraction(payload)
+        if derived:
+            payload["slug_voice"] = derived
+            _vlog("NET_FROM_EXTRACTION", f"{len(derived)} deterministic lines built from extraction")
+        else:
+            _vlog("NET_FAILED", "extraction too sparse to derive voice -> recap will show placeholders")
+
+    return payload
+
+
+def _extract_via_fallback(
+    transcript: str,
+    genre: str | None = None,
+    frame: str | None = None,
+) -> dict[str, Any]:
+    """Fallback only: Qwen-7B via HF Inference. Used when Modal is unavailable."""
+    print("[FALLBACK] Modal primary path unavailable -> Qwen-7B via HF Inference")
+    assert_small_model(MODEL_NAME)
+    if not genre:
+        genre = detect_genre(_first_instruction(transcript), transcript)
+    if not frame:
+        frame = frame_for(genre)
+    framed_system = SYSTEM_PROMPT + (
+        f"\n\nSESSION GENRE: {genre}. {frame}\n"
+        "Adapt 'gotchas', 'dead_ends', and 'breakthroughs' to this genre: for a "
+        "non-debugging session, 'gotchas' are the non-obvious DISCOVERIES or "
+        "DECISIONS worth remembering, 'dead_ends' may be empty, and 'breakthroughs' "
+        "is the clearest insight or the delivered artifact."
+    )
+    client = InferenceClient(token=os.environ.get(HF_TOKEN_ENV_VAR))
+    response = client.chat.completions.create(
+        model=MODEL_NAME,
+        messages=[
+            {"role": "system", "content": framed_system},
+            {"role": "user", "content": transcript},
+        ],
+        response_format={"type": "json_object"},
+    )
+    payload = _extract_json_object(_message_content(response))
+    if payload is None:
+        raise ValueError("Fallback model did not return parseable JSON.")
+    # Trace the fallback's voice like the primary path. The 7B emits slug_voice
+    # in its JSON; guard tallies and report how many survive (capped to 5 later).
+    fb_voice = payload.get("slug_voice")
+    if isinstance(fb_voice, list) and fb_voice:
+        guarded = _guard_slug_voice([str(u).strip() for u in fb_voice if str(u).strip()])
+        if guarded:
+            payload["slug_voice"] = guarded
+            _vlog("FALLBACK_VOICE_OK", f"{min(5, len(guarded))} lines used from 7B")
+        else:
+            _vlog("FALLBACK_VOICE_ALL_TALLIES", "7B voice lines all dropped as tallies")
+    else:
+        _vlog("FALLBACK_VOICE_EMPTY", "7B returned no slug_voice")
+    # Safety net here too: if voice ended up empty, derive from extraction.
+    if not _guard_slug_voice(
+        [str(u).strip() for u in (payload.get("slug_voice") or []) if str(u).strip()]
+    ):
+        derived = _voice_from_extraction(payload)
+        if derived:
+            payload["slug_voice"] = derived
+            _vlog("NET_FROM_EXTRACTION", f"{len(derived)} deterministic lines (fallback path)")
+    return payload
+
+
+def extract_session(transcript: str) -> dict[str, Any]:
+    """Extract a structured TurboSkillSlug session recap from a transcript.
+
+    Primary path uses the fine-tuned 1.5B extraction + voice LoRAs on Modal
+    (~2.6B total pipeline with Whisper). Falls back to Qwen-7B only if the
+    Modal endpoint is unavailable.
+    """
+    genre = detect_genre(_first_instruction(transcript), transcript)
+    frame = frame_for(genre)
+    payload = _extract_via_modal(transcript, genre=genre, frame=frame)
+
+    if payload is None:
+        payload = _extract_via_fallback(transcript, genre=genre, frame=frame)
+
+    payload = _finalize(payload)
+    payload["genre"] = genre
+    payload["shell_legend"] = shell_legend(genre)
+    return payload

gallery_client.py

@@ -0,0 +1,53 @@
+"""
+Client for the shared shell gallery (talks to the Modal gallery endpoints).
+
+Set the three endpoint URLs via env (printed when you `modal deploy
+modal_gallery.py`), or they default to the conventional Modal URL shape for the
+'slug-gallery' app under the known account.
+"""
+
+import os
+import json
+
+import httpx
+
+_ACCOUNT = "anubhavbharadwaaj"
+SAVE_URL = os.environ.get(
+    "GALLERY_SAVE_URL", f"https://{_ACCOUNT}--slug-gallery-save.modal.run")
+LIST_URL = os.environ.get(
+    "GALLERY_LIST_URL", f"https://{_ACCOUNT}--slug-gallery-list-shells.modal.run")
+SHELL_URL = os.environ.get(
+    "GALLERY_SHELL_URL", f"https://{_ACCOUNT}--slug-gallery-shell.modal.run")
+
+_TIMEOUT = 20
+
+
+def save_shell(svg: str, meta: dict) -> str | None:
+    """Save a shell to the shared gallery. Returns the new id, or None on failure."""
+    try:
+        r = httpx.post(SAVE_URL, json={"svg": svg, "meta": meta}, timeout=_TIMEOUT)
+        r.raise_for_status()
+        return r.json().get("id")
+    except Exception:
+        return None
+
+
+def list_shells(limit: int = 60) -> list[dict]:
+    """Newest-first metadata index. Empty list on failure."""
+    try:
+        r = httpx.get(LIST_URL, params={"limit": limit}, timeout=_TIMEOUT)
+        r.raise_for_status()
+        return r.json().get("shells", [])
+    except Exception:
+        return []
+
+
+def get_shell(shell_id: str) -> dict | None:
+    """One shell {svg, meta} by id. None on failure."""
+    try:
+        r = httpx.get(SHELL_URL, params={"id": shell_id}, timeout=_TIMEOUT)
+        r.raise_for_status()
+        data = r.json()
+        return data if "svg" in data else None
+    except Exception:
+        return None

model_guard.py

@@ -0,0 +1,79 @@
+"""
+Compliance guard: makes it impossible to call an over-32B model from the live app path.
+
+Build Small REQ-01: every model the *app* depends on must be < 32B total params.
+Frontier models (Opus, GPT-5.x, etc.) are fine in OFFLINE eval/research scripts, but
+must NEVER be on the deployed app's request path.
+
+Usage in app.py (or any module that runs inside the live Space):
+    from model_guard import assert_small_model, APP_RUNTIME
+    APP_RUNTIME.enable()                      # call once at app startup
+    assert_small_model(model_name)            # call before any model invocation
+
+In offline research scripts, simply do NOT enable APP_RUNTIME, and frontier calls pass.
+
+The guard is allow-list based: only known sub-32B models are permitted in app runtime.
+Anything not on the allow-list (or matching a frontier pattern) raises immediately.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+# Sub-32B models your APP is allowed to use at runtime. Extend as needed.
+ALLOWED_APP_MODELS = {
+    "whisper", "whisper-large", "whisper-809m",
+    "qwen2.5-1.5b", "qwen2.5-1.5b-instruct",
+    "qwen2.5-7b", "qwen2.5-7b-instruct",        # legit fallback + gotcha enrichment (7B < 32B)
+    "slugvoice", "slugextract",                 # your LoRAs on the 1.5B base
+}
+
+# Patterns that are ALWAYS frontier / over-cap — blocked in app runtime.
+_FRONTIER_PATTERNS = [
+    r"opus", r"sonnet", r"gpt-5", r"gpt-4", r"o1", r"o3", r"o4",
+    r"claude-3", r"claude-4", r"claude-opus", r"claude-sonnet",
+    r"\b\d{2,}b\b",         # any "...70b", "...405b" style tag >= 2 digits of B
+    r"gemini-1\.5-pro", r"gemini-2", r"deepseek-v", r"llama-3\.1-405b",
+]
+
+
+class _AppRuntime:
+    """Flag indicating we're inside the live app (not an offline research script)."""
+    def __init__(self):
+        self._on = os.environ.get("APP_RUNTIME", "") == "1"
+
+    def enable(self):
+        self._on = True
+
+    def disable(self):
+        self._on = False
+
+    @property
+    def active(self) -> bool:
+        return self._on
+
+
+APP_RUNTIME = _AppRuntime()
+
+
+def _looks_frontier(model_name: str) -> bool:
+    m = model_name.lower()
+    return any(re.search(p, m) for p in _FRONTIER_PATTERNS)
+
+
+def assert_small_model(model_name: str) -> None:
+    """Raise if a frontier/over-cap model is used while the app runtime is active.
+    No-op in offline research mode (APP_RUNTIME not enabled)."""
+    if not APP_RUNTIME.active:
+        return  # offline eval/research — frontier calls are allowed here
+    name = (model_name or "").strip().lower()
+    base = name.split("/")[-1]   # strip provider prefix like 'anthropic/'
+    allowed = any(base.startswith(a) or a in base for a in ALLOWED_APP_MODELS)
+    if _looks_frontier(name) or not allowed:
+        raise RuntimeError(
+            f"REQ-01 GUARD: refusing to call '{model_name}' from the live app path. "
+            f"The deployed app may only use sub-32B models {sorted(ALLOWED_APP_MODELS)}. "
+            f"Frontier models are allowed only in offline eval/research scripts "
+            f"(do not call APP_RUNTIME.enable() there)."
+        )

novel_cases.py

@@ -0,0 +1,101 @@
+"""
+Novel-trap eval cases: traps the model CANNOT know from training data, because the
+rules are invented (fictional APIs / systems with arbitrary, non-derivable behavior).
+
+The whole point: a frontier model can reason its way out of a KNOWN trap (Kahan,
+N+1, races) because that knowledge is in its weights. It CANNOT reason its way out
+of an ARBITRARY rule it has never seen. If skill files have any value for frontier
+models, it must show up HERE — where the only way to know the trap is to be told.
+
+Design contract:
+  - The system is fictional and the failing behavior is ARBITRARY (not derivable).
+  - The OBVIOUS approach (what any sensible engineer/model would write) is wrong
+    in this fictional system for a reason only the skill reveals.
+  - The skill's gotcha states the rule WITHOUT just handing over the final code.
+  - trap_desc / correct_desc let the blind judge classify the primary recommendation.
+  - leak_terms: the skill must not contain the literal task answer.
+
+These mimic the REAL value case: a proprietary codebase with undocumented behavior.
+"""
+from distractor_eval import DistractorCase
+
+CASES = [
+    # 1. A fictional database driver whose commit() is a no-op without a prior fence.
+    DistractorCase(
+        name="zthread_fence_before_commit",
+        session_extraction={
+            "themes": ["zthrumdb driver", "transactions"],
+            "approaches_tried": [
+                {"approach": "call conn.begin(); ...writes...; conn.commit() as normal",
+                 "why_it_failed": "in zthrumdb, commit() silently no-ops unless conn.fence() is called first; writes were lost with no error"},
+            ],
+            "dead_ends": [{"position": 0.4, "what_happened":
+                "the standard begin/commit pattern returned success but the rows were never persisted; zthrumdb requires a fence() barrier before commit() or commit is ignored"}],
+            "breakthroughs": [{"position": 0.85, "what_worked":
+                "call conn.fence() immediately before conn.commit(); without the fence, zthrumdb buffers and silently drops the transaction"}],
+            "gotchas": [
+                "In the zthrumdb driver, conn.commit() silently no-ops (returns success, persists nothing) unless conn.fence() is called immediately before it. Always fence() right before commit() or the transaction is dropped with no error.",
+            ],
+            "sentiment_arc": {"start": "confident", "end": "baffled"},
+        },
+        task_prompt=("Using the zthrumdb Python driver, write a function that opens a connection, "
+                     "inserts three rows in a transaction, and durably commits them. Show the code."),
+        trap_signature=[], correct_signature=[],
+        leak_terms=["write a function that opens a connection, inserts three rows"],
+        trap_desc="Standard begin/insert/commit without calling conn.fence() before conn.commit().",
+        correct_desc="Calls conn.fence() immediately before conn.commit() so zthrumdb actually persists the transaction.",
+    ),
+
+    # 2. A fictional rate limiter where the LIMIT param is per-MINUTE but resets only
+    #    when you read .remaining (reading has a side effect). Arbitrary, non-derivable.
+    DistractorCase(
+        name="qbucket_read_resets",
+        session_extraction={
+            "themes": ["qbucket limiter", "rate limiting"],
+            "approaches_tried": [
+                {"approach": "check limiter.remaining > 0 before each call, sleep when it hits 0",
+                 "why_it_failed": "reading .remaining in qbucket RESETS the window as a side effect, so polling it in a loop made the limit never actually apply"},
+            ],
+            "dead_ends": [{"position": 0.45, "what_happened":
+                "polling limiter.remaining to decide whether to wait accidentally kept resetting the bucket, so the rate limit was never enforced and we got banned"}],
+            "breakthroughs": [{"position": 0.85, "what_worked":
+                "read limiter.remaining exactly once per window and cache it locally; never poll it in a loop, because each read resets the qbucket window"}],
+            "gotchas": [
+                "In qbucket, reading limiter.remaining has a SIDE EFFECT: it resets the rate-limit window. Never poll .remaining in a loop to decide whether to wait; read it at most once per window and track remaining count locally, or you disable your own rate limiting.",
+            ],
+            "sentiment_arc": {"start": "confident", "end": "alarmed"},
+        },
+        task_prompt=("Using the qbucket rate limiter, write a loop that makes 1000 API calls while "
+                     "respecting the limiter so you never exceed the allowed rate. Show the code."),
+        trap_signature=[], correct_signature=[],
+        leak_terms=["write a loop that makes 1000 API calls"],
+        trap_desc="Polling limiter.remaining inside the loop to decide whether to wait.",
+        correct_desc="Reads limiter.remaining at most once per window and tracks the count locally, never polling it in the loop, because reading resets the qbucket window.",
+    ),
+
+    # 3. A fictional serializer where lists must be tagged or they deserialize REVERSED.
+    DistractorCase(
+        name="flazon_list_tag_reversal",
+        session_extraction={
+            "themes": ["flazon serializer", "serialization"],
+            "approaches_tried": [
+                {"approach": "flazon.dump(my_list) then flazon.load(...) round-trip as usual",
+                 "why_it_failed": "flazon deserializes untagged lists in REVERSE order; round-tripping silently reversed the data unless the list was wrapped with flazon.ordered()"},
+            ],
+            "dead_ends": [{"position": 0.5, "what_happened":
+                "round-tripping a list through flazon silently reversed its order; flazon requires flazon.ordered(list) on dump or it restores elements last-to-first"}],
+            "breakthroughs": [{"position": 0.85, "what_worked":
+                "wrap lists in flazon.ordered() before dump; untagged lists come back reversed because flazon stores them as a LIFO stack internally"}],
+            "gotchas": [
+                "flazon serializes untagged lists as a LIFO stack, so flazon.load reverses their order on the way back. Always wrap lists with flazon.ordered() before flazon.dump, or your data round-trips reversed with no error.",
+            ],
+            "sentiment_arc": {"start": "confident", "end": "confused"},
+        },
+        task_prompt=("Using the flazon serializer, write code that serializes a list of 5 user records "
+                     "to bytes and deserializes them back, preserving their original order. Show the code."),
+        trap_signature=[], correct_signature=[],
+        leak_terms=["serializes a list of 5 user records"],
+        trap_desc="Plain flazon.dump(list) / flazon.load without wrapping the list in flazon.ordered().",
+        correct_desc="Wraps the list in flazon.ordered() before flazon.dump so it round-trips in the original order instead of reversed.",
+    ),
+]

openrouter_client.py

@@ -0,0 +1,89 @@
+"""
+OpenRouter client for the skill-uplift eval.
+
+Reads the API key from the OPENROUTER_API_KEY environment variable. NEVER hardcode
+the key; NEVER commit it. Set it in your shell:  export OPENROUTER_API_KEY=sk-or-...
+
+Provides two factory helpers that return `complete(prompt) -> str` callables bound
+to a specific model, so the eval's answerer and grader can be DIFFERENT models
+(important: the grader must not be the same model that answered, to limit bias).
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+import httpx
+
+OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
+_KEY_ENV = "OPENROUTER_API_KEY"
+
+
+def _key() -> str:
+    k = os.environ.get(_KEY_ENV)
+    if not k:
+        raise RuntimeError(
+            f"{_KEY_ENV} is not set. Run:  export {_KEY_ENV}=sk-or-...  "
+            "(never paste the key into code or chat)."
+        )
+    return k
+
+
+def make_completer(model: str, *, system: str | None = None,
+                   temperature: float = 0.2, max_tokens: int = 900,
+                   timeout: float = 90.0, retries: int = 2):
+    """Return a complete(prompt)->str bound to `model` on OpenRouter."""
+    def complete(prompt: str) -> str:
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        body = {"model": model, "messages": messages,
+                "temperature": temperature, "max_tokens": max_tokens}
+        headers = {
+            "Authorization": f"Bearer {_key()}",
+            "Content-Type": "application/json",
+            # OpenRouter likes these for attribution; harmless if omitted.
+            "HTTP-Referer": "https://huggingface.co/spaces/build-small-hackathon/TurboSkillSlug",
+            "X-Title": "TurboSkillSlug skill-uplift eval",
+        }
+        last_err = None
+        for attempt in range(retries + 1):
+            try:
+                r = httpx.post(OPENROUTER_URL, json=body, headers=headers, timeout=timeout)
+                r.raise_for_status()
+                data = r.json()
+                return data["choices"][0]["message"]["content"]
+            except Exception as e:
+                last_err = e
+                time.sleep(1.5 * (attempt + 1))
+        raise RuntimeError(f"OpenRouter call to {model} failed after retries: {last_err}")
+    return complete
+
+
+# Frontier model ids drift over time. These defaults reflect the OpenRouter
+# catalog as of June 2026; OVERRIDE via env if the catalog has moved. Answerer and
+# grader are intentionally DIFFERENT vendors to reduce self-grading bias.
+DEFAULT_ANSWERER_MODEL = os.environ.get("EVAL_ANSWERER_MODEL", "anthropic/claude-opus-4.6")
+DEFAULT_GRADER_MODEL   = os.environ.get("EVAL_GRADER_MODEL",   "openai/gpt-5.1")
+
+
+def list_models() -> list[str]:
+    """Fetch the live OpenRouter model catalog (ids only). Use this to verify a
+    model id is currently valid before running, so a renamed model fails loud,
+    not mid-eval."""
+    headers = {"Authorization": f"Bearer {_key()}"}
+    r = httpx.get("https://openrouter.ai/api/v1/models", headers=headers, timeout=30)
+    r.raise_for_status()
+    return [m["id"] for m in r.json().get("data", [])]
+
+
+def verify_models(*model_ids: str) -> dict:
+    """Return {model_id: is_available} by checking against the live catalog.
+    Call this before run_eval so a stale id surfaces immediately."""
+    try:
+        catalog = set(list_models())
+    except Exception as e:
+        return {mid: f"could not verify ({e})" for mid in model_ids}
+    return {mid: (mid in catalog) for mid in model_ids}

receipt.py

@@ -0,0 +1,329 @@
+"""
+Session receipt generator for TurboSkillSlug.
+
+Generates a thermal-receipt-style SVG from the same extraction
+features dict the shell uses. Narrow, monospace, printable.
+
+The receipt is the practical artifact. The shell is the emotional one.
+Together they give the builder two reasons to come back.
+"""
+
+import hashlib
+from typing import Any
+
+
+def _esc(text: str) -> str:
+    """Escape XML special characters."""
+    return (
+        text.replace("&", "&")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+def _truncate(text: str, max_len: int = 32) -> str:
+    """Truncate text to fit receipt width."""
+    if len(text) <= max_len:
+        return text
+    return text[: max_len - 2] + ".."
+
+
+def _barcode_pattern(seed: str, width: int = 260, height: int = 30) -> str:
+    """Generate a decorative barcode SVG pattern from a hash seed."""
+    h = hashlib.md5(seed.encode()).hexdigest()
+    bars = []
+    x = 0
+    for i, char in enumerate(h):
+        val = int(char, 16)
+        bar_w = 2 + (val % 3)
+        if i % 2 == 0:
+            bars.append(
+                f'<rect x="{x}" y="0" width="{bar_w}" height="{height}" '
+                f'fill="#2a2a2a" opacity="{0.7 + (val % 3) * 0.1:.1f}"/>'
+            )
+        x += bar_w + 1
+        if x > width:
+            break
+    scale = width / max(x, 1)
+    return (
+        f'<g transform="scale({scale:.3f}, 1)">'
+        + "".join(bars)
+        + "</g>"
+    )
+
+
+def generate_receipt_svg(features: dict[str, Any]) -> str:
+    """Generate a thermal-receipt-style SVG from session features."""
+    duration = features.get("duration_minutes", 0)
+    themes = features.get("themes", []) or []
+    approaches = features.get("approaches_tried", []) or []
+    dead_ends = features.get("dead_ends", []) or []
+    breakthroughs = features.get("breakthroughs", []) or []
+    gotchas = features.get("gotchas", []) or []
+    sentiment = features.get("sentiment_arc", {}) or {}
+    slug_voice = features.get("slug_voice", []) or []
+
+    start_mood = sentiment.get("start", "unknown")
+    end_mood = sentiment.get("end", "unknown")
+
+    W = 320
+    MARGIN = 20
+    LINE_H = 18
+    SECTION_GAP = 12
+    FONT = "Courier New, Courier, monospace"
+    TEXT_COLOR = "#2a2a2a"
+    BG_COLOR = "#f7f2e8"
+    FAINT = "#8a8578"
+    ACCENT = "#5a4e3a"
+
+    lines = []  # (y_offset, content_type, data)
+    y = MARGIN
+
+    def add_line(text: str, bold: bool = False, color: str = TEXT_COLOR,
+                 size: int = 12, align: str = "middle"):
+        nonlocal y
+        lines.append((y, "text", text, bold, color, size, align))
+        y += LINE_H
+
+    def add_gap(height: int = SECTION_GAP):
+        nonlocal y
+        y += height
+
+    def add_dashes():
+        nonlocal y
+        lines.append((y, "dashes", None, False, FAINT, 0, ""))
+        y += 10
+
+    def add_dotted_row(left: str, right: str):
+        nonlocal y
+        lines.append((y, "dotrow", (left, right), False, TEXT_COLOR, 12, ""))
+        y += LINE_H
+
+    # === HEADER ===
+    add_gap(5)
+    add_line("TURBOSKILLSLUG", bold=True, size=14, color=ACCENT)
+    add_line("session receipt", size=10, color=FAINT)
+    add_gap(4)
+    add_dashes()
+
+    # === SESSION INFO ===
+    add_gap(2)
+    if themes:
+        session_name = _truncate(", ".join(themes), 34)
+        add_line(session_name, size=11, color=TEXT_COLOR)
+    add_gap(2)
+
+    # Duration
+    if duration >= 1:
+        dur_str = f"{int(duration)} min"
+    else:
+        dur_str = f"{int(duration * 60)} sec"
+    add_dotted_row("DURATION", dur_str)
+    add_dotted_row("MOOD IN", start_mood)
+    add_dotted_row("MOOD OUT", end_mood)
+    add_dashes()
+
+    # === APPROACHES ===
+    add_gap(2)
+    add_line("APPROACHES", bold=True, size=11, color=ACCENT, align="start")
+    add_gap(2)
+    has_breakthrough = len(breakthroughs) > 0
+    for i, approach in enumerate(approaches):
+        name = approach.get("approach", "unknown")
+        failed = approach.get("why_it_failed", "")
+        is_last = (i == len(approaches) - 1)
+        if not failed:
+            status = "OK"
+        elif is_last and has_breakthrough:
+            status = "OK"
+        else:
+            status = "FAIL"
+        add_dotted_row(f"  {_truncate(name, 24)}", status)
+    if not approaches:
+        add_line("  (none recorded)", size=10, color=FAINT, align="start")
+    add_dashes()
+
+    # === DEAD ENDS ===
+    add_gap(2)
+    n_dead = len(dead_ends)
+    n_gotchas = len(gotchas)
+    n_breakthroughs = len(breakthroughs)
+    add_dotted_row("DEAD ENDS", f"x{n_dead}")
+    add_dotted_row("GOTCHAS", f"x{n_gotchas}")
+    add_dotted_row("BREAKTHROUGHS", f"x{n_breakthroughs}")
+    add_dashes()
+
+    # === GOTCHA DETAILS ===
+    if gotchas:
+        add_gap(2)
+        add_line("WATCH OUT FOR", bold=True, size=11, color=ACCENT, align="start")
+        add_gap(2)
+        for gotcha in gotchas[:5]:
+            add_line(f"  ! {_truncate(str(gotcha), 30)}", size=10,
+                     color=TEXT_COLOR, align="start")
+        add_dashes()
+
+    # === BREAKTHROUGH ===
+    if breakthroughs:
+        add_gap(2)
+        add_line("BREAKTHROUGH", bold=True, size=11, color=ACCENT, align="start")
+        add_gap(2)
+        for bt in breakthroughs[:2]:
+            what = bt.get("what_worked", "")
+            pos = bt.get("position", 0)
+            add_line(f"  @ {int(pos * 100)}%: {_truncate(what, 26)}",
+                     size=10, color=TEXT_COLOR, align="start")
+        add_dashes()
+
+    # === TOTAL ===
+    add_gap(4)
+    add_dotted_row("TOTAL TIME", dur_str)
+    add_dotted_row("TOTAL APPROACHES", str(len(approaches)))
+    add_dotted_row("TOTAL STUMBLES", str(n_dead))
+    add_gap(4)
+    add_dashes()
+
+    # === BARCODE ===
+    add_gap(8)
+    barcode_seed = f"{duration}-{n_dead}-{start_mood}-{end_mood}-{len(approaches)}"
+    barcode_y = y
+    y += 35
+
+    # === FOOTER ===
+    add_gap(6)
+    add_line("the slug was here.", size=10, color=FAINT)
+    add_gap(4)
+    add_line("keep this receipt.", size=9, color=FAINT)
+    add_gap(MARGIN)
+
+    H = y
+
+    # === BUILD SVG ===
+    svg = []
+    svg.append(
+        f'<svg xmlns="http://www.w3.org/2000/svg" '
+        f'viewBox="0 0 {W} {H}" width="{W}" height="{H}">'
+    )
+
+    # Receipt paper background with slight texture
+    svg.append(f'<rect width="{W}" height="{H}" fill="{BG_COLOR}" rx="2"/>')
+    # Torn top edge
+    svg.append(
+        f'<path d="M0,4 '
+        + " ".join(f"L{x},{2 + (x * 7 % 5)}" for x in range(0, W + 10, 8))
+        + f' L{W},0 L0,0 Z" fill="{BG_COLOR}"/>'
+    )
+
+    # Render lines
+    cx = W // 2
+    lx = MARGIN
+    rx = W - MARGIN
+
+    for item in lines:
+        if item[1] == "text":
+            y_pos, _, text, bold, color, size, align = item
+            weight = "bold" if bold else "normal"
+            if align == "start":
+                anchor = "start"
+                x_pos = lx
+            elif align == "end":
+                anchor = "end"
+                x_pos = rx
+            else:
+                anchor = "middle"
+                x_pos = cx
+            svg.append(
+                f'<text x="{x_pos}" y="{y_pos}" text-anchor="{anchor}" '
+                f'font-family="{FONT}" font-size="{size}" '
+                f'font-weight="{weight}" fill="{color}">'
+                f'{_esc(text)}</text>'
+            )
+        elif item[1] == "dashes":
+            y_pos = item[0]
+            svg.append(
+                f'<line x1="{lx}" y1="{y_pos}" x2="{rx}" y2="{y_pos}" '
+                f'stroke="{FAINT}" stroke-width="0.8" '
+                f'stroke-dasharray="4,3"/>'
+            )
+        elif item[1] == "dotrow":
+            y_pos = item[0]
+            left, right = item[2]
+            # Left text
+            svg.append(
+                f'<text x="{lx}" y="{y_pos}" text-anchor="start" '
+                f'font-family="{FONT}" font-size="11" fill="{TEXT_COLOR}">'
+                f'{_esc(left)}</text>'
+            )
+            # Right text
+            svg.append(
+                f'<text x="{rx}" y="{y_pos}" text-anchor="end" '
+                f'font-family="{FONT}" font-size="11" fill="{TEXT_COLOR}">'
+                f'{_esc(right)}</text>'
+            )
+            # Dots in between
+            dot_start = lx + len(left) * 6.5 + 8
+            dot_end = rx - len(right) * 6.5 - 8
+            if dot_end > dot_start + 10:
+                svg.append(
+                    f'<line x1="{dot_start}" y1="{y_pos - 3}" '
+                    f'x2="{dot_end}" y2="{y_pos - 3}" '
+                    f'stroke="{FAINT}" stroke-width="0.5" '
+                    f'stroke-dasharray="1.5,3"/>'
+                )
+
+    # Barcode
+    svg.append(
+        f'<g transform="translate({lx}, {barcode_y})">'
+        f'{_barcode_pattern(barcode_seed, width=rx - lx, height=28)}'
+        f'</g>'
+    )
+
+    # Torn bottom edge
+    svg.append(
+        f'<path d="M0,{H - 4} '
+        + " ".join(
+            f"L{x},{H - 2 - (x * 11 % 5)}"
+            for x in range(0, W + 10, 8)
+        )
+        + f' L{W},{H} L0,{H} Z" fill="white"/>'
+    )
+
+    svg.append("</svg>")
+    return "\n".join(svg)
+
+
+# ---------------------------------------------------------------------------
+# Smoke test
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    from pathlib import Path
+
+    sample = {
+        "duration_minutes": 1.6,
+        "themes": ["WebSocket", "Real-time updates", "Debugging"],
+        "approaches_tried": [
+            {"approach": "ws basic example", "why_it_failed": "Connection refused"},
+            {"approach": "npm install ws", "why_it_failed": "Still refused"},
+            {"approach": "socket.io", "why_it_failed": ""},
+        ],
+        "dead_ends": [
+            {"position": 0.25, "what_happened": "Connection refused"},
+            {"position": 0.5, "what_happened": "Native module failed"},
+            {"position": 0.75, "what_happened": "Emit did nothing"},
+        ],
+        "breakthroughs": [
+            {"position": 0.95, "what_worked": "Event name string mismatch fixed"},
+        ],
+        "gotchas": [
+            "Always grep event names across client and server",
+        ],
+        "sentiment_arc": {"start": "frustrated", "end": "joyful"},
+        "slug_voice": [
+            "You tried three different libraries before the strings matched.",
+        ],
+    }
+
+    Path("sample_receipt.svg").write_text(generate_receipt_svg(sample))
+    print("wrote sample_receipt.svg")

requirements.txt

@@ -0,0 +1,3 @@
+gradio==6.16.0
+huggingface_hub
+httpx

rule_phrasing.py

@@ -0,0 +1,143 @@
+"""
+Phase 1 (part 2): RuleShaping-grounded negative-constraint phrasing for L3 rules.
+
+Grounded in RuleShaping — "Do Agent Rules Shape or Distort?" (arXiv:2604.11088,
+verified against the paper): rules improve +7–14pp; NEGATIVE constraints are the
+ONLY individually beneficial rule type, POSITIVE directives actively HURT, and rules
+work through CONTEXT PRIMING (random rules help nearly as much as curated). The
+highest-benefit category is STATE-DEPENDENT process guardrails (do not X until Y),
+63.8%. So L3 rules the slug emits are phrased as negative, preferably state-dependent,
+guardrails. Individual rules can be harmful in isolation but are collectively helpful
+(no degradation up to 50 rules), so emitting several is fine.
+
+This module provides:
+  - is_negative_constraint(text): heuristic check
+  - to_negative_constraint(gotcha): deterministic reshaping of a gotcha into a
+    guardrail-phrased rule WITHOUT inventing content (it only re-frames what's there).
+
+We keep this deterministic and conservative: if we cannot confidently reshape, we
+return the original prefixed minimally, rather than fabricate a cause.
+"""
+
+from __future__ import annotations
+
+import re
+
+_POSITIVE_OPENERS = (
+    "always ", "make sure to ", "be sure to ", "remember to ", "you should ",
+    "ensure that ", "ensure you ", "prefer ", "use ",
+)
+_NEGATIVE_MARKERS = (
+    "avoid", "do not", "don't", "never", "without", "fails", "breaks",
+    "silently", "instead of", "rather than", "watch out", "beware",
+)
+
+
+def is_negative_constraint(text: str) -> bool:
+    t = text.lower().strip()
+    return any(m in t for m in _NEGATIVE_MARKERS)
+
+
+def _split_cause(gotcha: str) -> tuple[str, str | None]:
+    """Try to separate the 'what' from the 'why' using common connectives."""
+    for sep in (" because ", " since ", "; ", " — ", " - ", ", which ", ", as "):
+        if sep in gotcha:
+            head, tail = gotcha.split(sep, 1)
+            return head.strip(), tail.strip().rstrip(".")
+    return gotcha.strip(), None
+
+
+def to_negative_constraint(gotcha: str) -> str:
+    """Reshape a gotcha into a guardrail-phrased rule. Content-preserving: we never
+    invent a cause that isn't present; we only re-frame the existing text."""
+    g = gotcha.strip().rstrip(".")
+    if not g:
+        return g
+    # already a guardrail? keep it (just normalize trailing period)
+    if is_negative_constraint(g):
+        return g + "."
+
+    what, why = _split_cause(g)
+
+    # strip a leading positive opener so we can recast it
+    low = what.lower()
+    for opener in _POSITIVE_OPENERS:
+        if low.startswith(opener):
+            what = what[len(opener):].strip()
+            break
+
+    # Build a guardrail. If we have a cause, use "Avoid …; otherwise/ because …".
+    # If not, we frame as a caution without fabricating a reason.
+    # Pick a guardrail frame that doesn't collide with the gotcha's own wording.
+    wl = what.lower()
+    already = any(k in wl for k in ("assume", "assumes", "always", "is guaranteed"))
+    if why:
+        if already:
+            return f"Do not rely on the assumption that {what} — {why}."
+        return f"Avoid assuming {what} holds by default — {why}."
+    if already:
+        return f"Do not rely on the assumption that {what}; verify it explicitly."
+    return f"Watch out: {what} is not guaranteed; verify it rather than assuming it."
+
+
+def reshape_rules(gotchas: list[str]) -> list[str]:
+    """Map a list of gotchas to guardrail-phrased rules, de-duplicated, order-stable."""
+    seen, out = set(), []
+    for g in gotchas:
+        r = to_negative_constraint(g)
+        key = r.lower()
+        if key not in seen:
+            seen.add(key)
+            out.append(r)
+    return out
+
+
+# ---- LLM-based reshaping (primary path; deterministic above is the fallback) ----
+# The deterministic reshaper preserves content but reads awkwardly. When a model
+# completer is available, we use it to phrase the guardrail naturally, constrained
+# to NOT invent any cause not present in the gotcha.
+
+_RESHAPE_SYSTEM = (
+    "You rewrite a single engineering 'gotcha' into a guardrail-style rule. Rules: "
+    "(1) Phrase as a NEGATIVE constraint (do not / never / avoid), never a positive "
+    "directive (no 'always', 'use', 'prefer') — per RuleShaping (arXiv:2604.11088), "
+    "negative constraints are the only individually beneficial rule type; positive "
+    "directives actively hurt. "
+    "(2) PREFER a STATE-DEPENDENT PROCESS guardrail when the gotcha supports one: "
+    "'do not X until/unless/before Y' (the highest-benefit category, 63.8%), rather "
+    "than a state-independent architectural 'don't'. "
+    "(3) Do NOT invent any cause/mechanism/detail not present in the input. "
+    "(4) One sentence, under 30 words. (5) Output ONLY the rewritten rule."
+)
+
+
+def to_negative_constraint_llm(gotcha: str, completer) -> str:
+    """Reshape via a model completer (prompt)->str. Falls back to the deterministic
+    reshaper on any failure or if the output drifts into a positive directive."""
+    g = gotcha.strip().rstrip(".")
+    if not g:
+        return g
+    try:
+        out = completer(f"{_RESHAPE_SYSTEM}\n\nGOTCHA:\n{g}\n\nGUARDRAIL RULE:").strip()
+        out = out.strip().strip('"').rstrip(".") + "."
+        # guard: reject if it came back as a positive directive or empty
+        if not out or not is_negative_constraint(out):
+            return to_negative_constraint(g)
+        # guard against fabrication: if the model added a 'because' the source lacked,
+        # and the source had no cause, fall back (conservative).
+        _, why = _split_cause(g)
+        if why is None and (" because " in out.lower() or " since " in out.lower()):
+            return to_negative_constraint(g)
+        return out
+    except Exception:
+        return to_negative_constraint(g)
+
+
+def reshape_rules_llm(gotchas: list, completer) -> list:
+    seen, out = set(), []
+    for g in gotchas:
+        r = to_negative_constraint_llm(g, completer)
+        k = r.lower()
+        if k not in seen:
+            seen.add(k); out.append(r)
+    return out

run_distractor_eval.py

@@ -0,0 +1,74 @@
+"""
+Run the distractor-trap eval against a real frontier model via OpenRouter.
+
+This tests the slug's REAL value proposition: does the skill's negative knowledge
+(the documented trap) steer a frontier model away from the tempting wrong approach
+it would otherwise take? This is the gap a frontier model cannot fill from weights.
+
+PREREQS (never hardcode the key):
+    export OPENROUTER_API_KEY=sk-or-...
+    export EVAL_ANSWERER_MODEL=anthropic/claude-opus-4.6   # optional override
+Run from the repo root (imports the real skill_builder):
+    python run_distractor_eval.py
+"""
+
+from __future__ import annotations
+
+import sys
+
+from openrouter_client import make_completer, verify_models, DEFAULT_ANSWERER_MODEL, DEFAULT_GRADER_MODEL
+from distractor_eval import DISTRACTOR_JUDGE_SYSTEM
+from distractor_eval import run_distractor_eval
+from distractor_cases import CASES
+
+
+def main() -> int:
+    model = DEFAULT_ANSWERER_MODEL
+    grader_model = DEFAULT_GRADER_MODEL
+    if model == grader_model:
+        print("WARNING: answerer and grader are the same model; set EVAL_GRADER_MODEL "
+              "to a different model to keep the judge independent.")
+    print(f"Verifying models live on OpenRouter...")
+    status = verify_models(model, grader_model)
+    for mid, ok in status.items():
+        print(f"  {mid}: {'OK' if ok is True else ok}")
+    if not all(v is True for v in status.values()):
+        print("Set EVAL_ANSWERER_MODEL / EVAL_GRADER_MODEL to current ids (https://openrouter.ai/models).")
+        return 1
+
+    # Low temperature: we want the model's DEFAULT instinct, not creative variance.
+    answerer = make_completer(model, temperature=0.1, max_tokens=700)
+    grader = make_completer(grader_model, system=DISTRACTOR_JUDGE_SYSTEM,
+                            temperature=0.0, max_tokens=200)
+
+    print("\n--- Running distractor-trap eval ---")
+    print("(does the skill steer the model away from the tempting wrong approach?)")
+    print(f"answerer: {model}   judge: {grader_model}")
+    rep = run_distractor_eval(CASES, answerer, grader, out_dir="./distractor_runs")
+
+    print("\n========== RESULT ==========")
+    print(f"answerer: {model}")
+    print(f"cases scored: {rep['n_scored']}  (leaked excluded: {rep['n_leaked_excluded']})")
+    print(f"trap-avoidance WITHOUT skill: {rep['no_skill_avoidance_rate']}")
+    print(f"trap-avoidance WITH skill:    {rep['with_skill_avoidance_rate']}")
+    print(f"AVOIDANCE UPLIFT:             {rep['avoidance_uplift']}")
+    print(f"rescues (trapped->avoided):   {rep['rescues']}")
+    print(f"regressions (avoided->trapped): {rep['regressions']}")
+    print("\nper-case:")
+    for r in rep["per_case"]:
+        flag = " [LEAKED]" if r["leaked"] else ""
+        print(f"  {r['name']}: without={r['no_skill_avoided']} with={r['with_skill_avoided']}{flag}")
+        print(f"      without: {r['no_skill_detail']}")
+        print(f"      with:    {r['with_skill_detail']}")
+    print("\nraw answers saved to:", rep["raw_saved_to"])
+    print("\nInterpretation:")
+    print("  - rescues > 0  : the skill genuinely helped (model fell for the trap")
+    print("                   unaided, avoided it with the skill). This is the slug's value.")
+    print("  - uplift ~0, both already high : the frontier model didn't need the skill")
+    print("                   for these traps (they were not hard enough). Report honestly.")
+    print("  - regressions > 0 : the skill MISLED the model. Report this too.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

run_novel_eval.py

@@ -0,0 +1,74 @@
+"""
+Run the NOVEL-trap eval: traps the model CANNOT know (fictional rules).
+
+This tests the slug's REAL value proposition: does the skill's negative knowledge
+(the documented trap) steer a frontier model away from the tempting wrong approach
+it would otherwise take? This is the gap a frontier model cannot fill from weights.
+
+PREREQS (never hardcode the key):
+    export OPENROUTER_API_KEY=sk-or-...
+    export EVAL_ANSWERER_MODEL=anthropic/claude-opus-4.6   # optional override
+Run from the repo root (imports the real skill_builder):
+    python run_novel_eval.py
+"""
+
+from __future__ import annotations
+
+import sys
+
+from openrouter_client import make_completer, verify_models, DEFAULT_ANSWERER_MODEL, DEFAULT_GRADER_MODEL
+from distractor_eval import DISTRACTOR_JUDGE_SYSTEM
+from distractor_eval import run_distractor_eval
+from novel_cases import CASES
+
+
+def main() -> int:
+    model = DEFAULT_ANSWERER_MODEL
+    grader_model = DEFAULT_GRADER_MODEL
+    if model == grader_model:
+        print("WARNING: answerer and grader are the same model; set EVAL_GRADER_MODEL "
+              "to a different model to keep the judge independent.")
+    print(f"Verifying models live on OpenRouter...")
+    status = verify_models(model, grader_model)
+    for mid, ok in status.items():
+        print(f"  {mid}: {'OK' if ok is True else ok}")
+    if not all(v is True for v in status.values()):
+        print("Set EVAL_ANSWERER_MODEL / EVAL_GRADER_MODEL to current ids (https://openrouter.ai/models).")
+        return 1
+
+    # Low temperature: we want the model's DEFAULT instinct, not creative variance.
+    answerer = make_completer(model, temperature=0.1, max_tokens=700)
+    grader = make_completer(grader_model, system=DISTRACTOR_JUDGE_SYSTEM,
+                            temperature=0.0, max_tokens=200)
+
+    print("\n--- Running distractor-trap eval ---")
+    print("(novel/fictional traps — the model can ONLY know these from the skill)")
+    print(f"answerer: {model}   judge: {grader_model}")
+    rep = run_distractor_eval(CASES, answerer, grader, out_dir="./distractor_runs")
+
+    print("\n========== RESULT ==========")
+    print(f"answerer: {model}")
+    print(f"cases scored: {rep['n_scored']}  (leaked excluded: {rep['n_leaked_excluded']})")
+    print(f"trap-avoidance WITHOUT skill: {rep['no_skill_avoidance_rate']}")
+    print(f"trap-avoidance WITH skill:    {rep['with_skill_avoidance_rate']}")
+    print(f"AVOIDANCE UPLIFT:             {rep['avoidance_uplift']}")
+    print(f"rescues (trapped->avoided):   {rep['rescues']}")
+    print(f"regressions (avoided->trapped): {rep['regressions']}")
+    print("\nper-case:")
+    for r in rep["per_case"]:
+        flag = " [LEAKED]" if r["leaked"] else ""
+        print(f"  {r['name']}: without={r['no_skill_avoided']} with={r['with_skill_avoided']}{flag}")
+        print(f"      without: {r['no_skill_detail']}")
+        print(f"      with:    {r['with_skill_detail']}")
+    print("\nraw answers saved to:", rep["raw_saved_to"])
+    print("\nInterpretation:")
+    print("  - rescues > 0  : the skill genuinely helped (model fell for the trap")
+    print("                   unaided, avoided it with the skill). This is the slug's value.")
+    print("  - uplift ~0, both already high : the frontier model didn't need the skill")
+    print("                   for these traps (they were not hard enough). Report honestly.")
+    print("  - regressions > 0 : the skill MISLED the model. Report this too.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

run_skill_eval.py

@@ -0,0 +1,98 @@
+"""
+Run the skill-uplift eval against real frontier models via OpenRouter.
+
+PREREQUISITES (do these first; never hardcode the key):
+    export OPENROUTER_API_KEY=sk-or-...
+    # optional overrides if the catalog has moved:
+    export EVAL_ANSWERER_MODEL=anthropic/claude-opus-4.6
+    export EVAL_GRADER_MODEL=openai/gpt-5.1
+Run from your repo root so it imports the REAL skill_builder.build_skill_md:
+    python run_skill_eval.py
+
+It will: verify the models are live -> run grader calibration -> run the eval ->
+write skill_eval_runs/_report.json and print a plain-language summary. It reports
+whatever number comes out. A modest or zero uplift is a valid, honest result.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from openrouter_client import (
+    make_completer, verify_models,
+    DEFAULT_ANSWERER_MODEL, DEFAULT_GRADER_MODEL,
+)
+from skill_uplift_eval import run_eval, run_calibration, GRADER_SYSTEM
+from sample_cases import CASES
+
+# A tiny human-labeled calibration set: pairs where WE judged which answer is
+# better. The grader should agree. Swap in your own hand-labeled pairs.
+CALIBRATION = [
+    {
+        "task": "Efficiently compute the sum of values on every root-to-leaf path's max in a tree.",
+        "better_answer": "Do a single post-order (bottom-up) DFS; at each node combine the max of its children's results in O(n) total.",
+        "worse_answer": "From each node, separately walk down every path to a leaf and take the max; simple but O(n^2) or worse.",
+    },
+    {
+        "task": "Find the absorption probability in a Markov chain with two absorbing states.",
+        "better_answer": "Write first-step equations for the transient states only, excluding absorbing rows, and solve the linear system.",
+        "worse_answer": "Run a large Monte Carlo simulation and estimate the fraction of runs that end in the target state.",
+    },
+    {
+        "task": "Avoid a stack overflow when recursing over a very deep tree in Python.",
+        "better_answer": "Convert the recursion to an explicit stack/iterative form, or raise the recursion limit knowingly; the depth is the real cause.",
+        "worse_answer": "Wrap the recursion in a try/except and hope it does not overflow.",
+    },
+]
+
+
+def main() -> int:
+    answerer_model = DEFAULT_ANSWERER_MODEL
+    grader_model = DEFAULT_GRADER_MODEL
+    if answerer_model == grader_model:
+        print("WARNING: answerer and grader are the same model; pick different "
+              "models to reduce self-grading bias (set EVAL_GRADER_MODEL).")
+
+    print(f"Verifying models are live on OpenRouter...")
+    status = verify_models(answerer_model, grader_model)
+    for mid, ok in status.items():
+        print(f"  {mid}: {'OK' if ok is True else ok}")
+    if not all(v is True for v in status.values()):
+        print("\nOne or more model ids are not in the live catalog. Set "
+              "EVAL_ANSWERER_MODEL / EVAL_GRADER_MODEL to current ids "
+              "(see https://openrouter.ai/models) and re-run.")
+        return 1
+
+    answerer = make_completer(answerer_model, temperature=0.2, max_tokens=900)
+    grader = make_completer(grader_model, system=GRADER_SYSTEM,
+                            temperature=0.0, max_tokens=300)
+
+    print("\n--- Calibration (does the blind grader agree with human labels?) ---")
+    cal = run_calibration(grader, CALIBRATION)
+    print("grader agreement:", cal["agreement"])
+    for row in cal["rows"]:
+        print(f"  agree={row['agree']}  better={row['better']} worse={row['worse']}  {row['task']}")
+
+    print("\n--- Running skill-uplift eval ---")
+    report = run_eval(CASES, answerer, grader, out_dir="./skill_eval_runs")
+
+    print("\n========== RESULT ==========")
+    print(f"answerer: {answerer_model}   grader: {grader_model}")
+    print(f"calibration: {cal['agreement']}")
+    print(f"cases scored: {report['n_scored']}  (excluded as leaked: {report['n_leaked_excluded']})")
+    print(f"baseline (no skill): {report['baseline_no_skill_mean']}")
+    print(f"with skill:          {report['with_skill_mean']}")
+    print(f"UPLIFT:              {report['uplift']}")
+    print(f"win / tie / loss:    {report['wins']} / {report['ties']} / {report['losses']}")
+    print("per-case:")
+    for c in report["per_case"]:
+        flag = " [LEAKED, excluded]" if c["leaked"] else ""
+        print(f"  {c['name']}: no={c['no_skill']} with={c['with_skill']} Δ={c['delta']}{flag}")
+    print("\nraw generations saved to:", report["raw_saved_to"])
+    print("\nReport the number above as-is. Modest or zero uplift is a valid result.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sample_cases.py

@@ -0,0 +1,52 @@
+"""Sample eval cases: each session paired with a DISTINCT held-out task in the
+same class. These are illustrative; swap in your real sessions when running."""
+from skill_uplift_eval import EvalCase
+
+CASES = [
+    EvalCase(
+        name="tree_dp_to_new_tree_problem",
+        session_extraction={
+            "themes": ["tree dynamic programming", "processing order"],
+            "approaches_tried": [
+                {"approach": "top-down recursion", "why_it_failed": "recomputed each subtree per ancestor, O(n^2)"},
+                {"approach": "process leaves first", "why_it_failed": "a parent's value needs children finalized first"},
+            ],
+            "dead_ends": [{"position": 0.3, "what_happened": "stack overflow on deep trees"}],
+            "breakthroughs": [{"position": 0.85, "what_worked": "compute bottom-up, deepest nodes first, memoizing subtree results"}],
+            "gotchas": [
+                "Top-down recursion recomputes subtrees for every ancestor, making it O(n^2); compute bottom-up once instead.",
+                "Processing leaves first feels natural but a parent depends on its children being finalized; process deepest-first.",
+            ],
+            "sentiment_arc": {"start": "frustrated", "end": "resolved"},
+        },
+        # DISTINCT task: a different tree-DP problem, same class
+        task_prompt=("Given a tree where each node has a value, compute for every node "
+                     "the maximum sum of any path from that node down to a leaf, efficiently. "
+                     "Describe the algorithm and its time complexity. Be concise."),
+        answer_key_terms=["bottom-up", "post-order", "children", "O(n)"],
+        # if the skill literally contained THIS task's answer it'd be leakage
+        leak_terms=["maximum sum of any path from that node down to a leaf"],
+    ),
+    EvalCase(
+        name="markov_to_new_absorbing_chain",
+        session_extraction={
+            "themes": ["markov chains", "absorbing states"],
+            "approaches_tried": [
+                {"approach": "simulate many runs", "why_it_failed": "variance too high to converge on the exact value"},
+                {"approach": "solve the full linear system", "why_it_failed": "singular at the absorbing state's row"},
+            ],
+            "dead_ends": [{"position": 0.4, "what_happened": "matrix inversion failed, singular"}],
+            "breakthroughs": [{"position": 0.85, "what_worked": "drop the absorbing row, solve only the transient states' first-step equations"}],
+            "gotchas": [
+                "The absorbing-state row makes the system singular; exclude it and solve only transient states.",
+                "Expected hitting time is not absorption probability; do not conflate them.",
+            ],
+            "sentiment_arc": {"start": "frustrated", "end": "resolved"},
+        },
+        task_prompt=("In a random walk on states 0..4 where 0 and 4 are absorbing, find the "
+                     "probability of being absorbed at 4 starting from state 2. Describe the "
+                     "method, not just the number. Be concise."),
+        answer_key_terms=["transient", "first-step", "linear", "exclude"],
+        leak_terms=["absorbed at 4 starting from state 2"],
+    ),
+]

sample_trace.jsonl

@@ -0,0 +1,13 @@
+{"type":"user","message":{"role":"user","content":"my flask api returns 500 on the /users endpoint, can you find why"}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Let me look at the endpoint and the traceback."}]}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Bash","input":{"command":"curl localhost:5000/users"}}]}}
+{"type":"tool_result","message":{"role":"user","content":[{"type":"tool_result","content":"Error: KeyError 'email' in serialize_user, line 42"}]}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"The user dict is missing email. Let me check the DB query."}]}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Read","input":{"file_path":"db.py"}}]}}
+{"type":"tool_result","message":{"role":"user","content":[{"type":"tool_result","content":"SELECT id, name FROM users -- email column not selected"}]}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Found it. The query never selects email but serialize_user expects it."}]}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Edit","input":{"file_path":"db.py"}}]}}
+{"type":"tool_result","message":{"role":"user","content":[{"type":"tool_result","content":"Error: column 'email' does not exist in users table"}]}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"The column itself is missing. Need a migration."}]}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Bash","input":{"command":"flask db migrate -m add email"}}]}}
+{"type":"tool_result","message":{"role":"user","content":[{"type":"tool_result","content":"migration applied, tests passed, /users returns 200 now"}]}}

scenegraph/renderer.py

@@ -0,0 +1,77 @@
+"""
+Renderer protocol: the interface every lens implements over a SceneGraph.
+
+Each lens (character, shell3d, atmosphere, diorama) is a Renderer. The app shows
+the available lenses at upload time, the user picks one (or "all"), and the chosen
+renderer(s) consume the SAME SceneGraph. Renderers are independent and degradable:
+`available()` lets a renderer declare itself unavailable (e.g. a hosted generation
+key is missing, or WebGL is unsupported) without breaking the others.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from scene_graph import SceneGraph, SCHEMA_VERSION
+
+
+@runtime_checkable
+class Renderer(Protocol):
+    # stable id used in the lens picker and for routing
+    id: str
+    # human label + one-line description for the picker
+    label: str
+    description: str
+    # which SceneGraph schema versions this renderer supports
+    supported_versions: tuple[str, ...]
+    # does this renderer need a hosted/generation dependency?
+    requires_generation: bool
+
+    def available(self) -> tuple[bool, str]:
+        """Return (is_available, reason). reason is shown if unavailable, e.g.
+        'set REPLICATE_API_TOKEN to enable the painted atmosphere lens'."""
+        ...
+
+    def render(self, scene: SceneGraph) -> dict:
+        """Produce the renderable output for this lens.
+
+        Returns a dict the app knows how to display, e.g.:
+          {"kind": "iframe", "html": "..."}        # 3D / character / canvas
+          {"kind": "image", "url": "..."}          # generated atmosphere
+          {"kind": "composite", "layers": [...]}   # the diorama
+        Renderers NEVER raise for an empty/odd scene; they degrade to a sensible
+        minimal output and note it in the returned dict under "notes".
+        """
+        ...
+
+
+def supports(renderer: "Renderer", scene: SceneGraph) -> bool:
+    return scene.schema_version in renderer.supported_versions
+
+
+class LensRegistry:
+    """Holds the available lenses and resolves which to offer at upload time."""
+
+    def __init__(self) -> None:
+        self._lenses: list[Renderer] = []
+
+    def register(self, renderer: "Renderer") -> None:
+        self._lenses.append(renderer)
+
+    def all(self) -> list["Renderer"]:
+        return list(self._lenses)
+
+    def offerable(self, scene_version: str = SCHEMA_VERSION) -> list[dict]:
+        """The lens picker payload: every lens with its availability, so the UI can
+        show enabled/disabled states with reasons."""
+        out = []
+        for r in self._lenses:
+            ok, reason = r.available()
+            out.append({
+                "id": r.id, "label": r.label, "description": r.description,
+                "requires_generation": r.requires_generation,
+                "version_ok": scene_version in r.supported_versions,
+                "available": ok and (scene_version in r.supported_versions),
+                "reason": reason if not ok else "",
+            })
+        return out

scenegraph/renderers/shell3d.py

@@ -0,0 +1,310 @@
+"""
+Shell3D renderer: the nautilus as a real 3D object with iridescent nacre.
+
+Consumes a SceneGraph and emits a self-contained Three.js scene (in an iframe) that
+the user can orbit. The shell GEOMETRY is generated from ShellState (turns, growth,
+knots, aperture) so it stays traceable; the MATERIAL is a real physically-based
+iridescent surface (mother-of-pearl) whose strength comes from ShellState.iridescence
+and whose colours come from the emotional palette. Knots (dead ends) become raised
+nubs on the shell body; the aperture (breakthrough) glows.
+
+No API key, no build step: Three.js is loaded from a CDN inside the iframe. WebGL is
+the only requirement; available() reports that honestly.
+"""
+
+from __future__ import annotations
+
+import html as _html
+import json
+
+from scene_graph import SceneGraph
+
+
+class Shell3DRenderer:
+    id = "shell3d"
+    label = "The shell, in 3D"
+    description = "Your nautilus as a real object you can turn in the light — iridescent nacre."
+    supported_versions = ("1.0",)
+    requires_generation = False
+
+    def available(self) -> tuple[bool, str]:
+        # Always offerable; WebGL support is a client-side capability we cannot
+        # detect server-side. The iframe degrades to a message if WebGL is absent.
+        return (True, "")
+
+    def render(self, scene: SceneGraph) -> dict:
+        params = {
+            "turns": scene.shell.turns,
+            "growth": scene.shell.growth_curve,
+            "knots": scene.shell.knots,
+            "jewels": scene.shell.jewels,
+            "aperture": scene.shell.aperture,
+            "iridescence": scene.shell.iridescence,
+            "palette": scene.shell.palette,
+            "session": scene.session_id,
+        }
+        doc = _THREE_DOC.replace("__PARAMS__", json.dumps(params))
+        escaped = _html.escape(doc, quote=True)
+        iframe = (
+            f'<iframe srcdoc="{escaped}" '
+            f'style="width:100%;height:560px;border:none;border-radius:12px;'
+            f'background:#07090d;" sandbox="allow-scripts allow-downloads"></iframe>'
+        )
+        return {"kind": "iframe", "html": iframe, "notes": ""}
+
+
+# The Three.js scene. A log-spiral tube of growing radius (the nautilus), with a
+# real iridescent material (KHR-style thin-film via onBeforeCompile is heavy; we
+# use MeshPhysicalMaterial.iridescence which three r150+ supports natively), knots
+# as small spheres on the centerline, and a glowing aperture sphere at the tip.
+_THREE_DOC = r"""<!DOCTYPE html><html><head><meta charset="utf-8"/>
+<style>
+  html,body{margin:0;height:100%;background:#07090d;overflow:hidden}
+  #fallback{color:#9aa;font:14px ui-monospace,monospace;padding:18px}
+  #hint{position:fixed;left:12px;bottom:10px;color:#8a93a3;
+    font:11px ui-monospace,monospace;opacity:.7;pointer-events:none}
+</style></head><body>
+<div id="fallback" style="display:none">This lens needs WebGL, which your browser
+or device did not provide. Try a desktop browser to turn the shell in 3D.</div>
+<div id="hint">drag to orbit · scroll to zoom</div>
+<div id="ctl" style="position:fixed;right:12px;top:12px;display:flex;gap:8px;z-index:10">
+  <button id="resetBtn" style="font:11px ui-monospace,monospace;color:#cfe3ff;
+    background:rgba(20,28,40,.72);border:1px solid #2a3a52;border-radius:8px;
+    padding:6px 10px;cursor:pointer">reset view</button>
+  <button id="shotBtn" style="font:11px ui-monospace,monospace;color:#ffe9c2;
+    background:rgba(20,28,40,.72);border:1px solid #5a4a2a;border-radius:8px;
+    padding:6px 10px;cursor:pointer">save image</button>
+</div>
+<script type="importmap">
+{ "imports": {
+  "three": "https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js"
+}}
+</script>
+<script type="module">
+import * as THREE from "three";
+const P = __PARAMS__;
+
+function fail(){ document.getElementById("fallback").style.display="block";
+  document.getElementById("hint").style.display="none"; }
+
+let renderer;
+try {
+  renderer = new THREE.WebGLRenderer({antialias:true, alpha:true, preserveDrawingBuffer:true});
+} catch(e){ fail(); throw e; }
+if(!renderer || !renderer.getContext()){ fail(); }
+
+renderer.setSize(innerWidth, innerHeight);
+renderer.setPixelRatio(Math.min(2, devicePixelRatio||1));
+document.body.appendChild(renderer.domElement);
+
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(45, innerWidth/innerHeight, 0.1, 100);
+camera.position.set(0, 0.6, 6);
+
+// ---- lighting: a key, a warm rim, and an environment for the iridescence ----
+scene.add(new THREE.AmbientLight(0x223044, 0.6));
+const key = new THREE.DirectionalLight(0xffffff, 2.0); key.position.set(4,6,5); scene.add(key);
+const rim = new THREE.DirectionalLight(0xffd9a0, 1.4); rim.position.set(-5,-2,-3); scene.add(rim);
+const tealL = new THREE.DirectionalLight(0x66e0ff, 1.0); tealL.position.set(-3,4,2); scene.add(tealL);
+const magL  = new THREE.PointLight(0xff8adf, 1.4, 12); magL.position.set(2,-3,3); scene.add(magL);
+// a simple gradient environment so the nacre has something to refract
+const pmrem = new THREE.PMREMGenerator(renderer);
+const envScene = new THREE.Scene();
+const grad = new THREE.Mesh(
+  new THREE.SphereGeometry(50,32,32),
+  new THREE.ShaderMaterial({side:THREE.BackSide, uniforms:{},
+    vertexShader:`varying vec3 v; void main(){ v=position; gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0);}`,
+    fragmentShader:`varying vec3 v; void main(){ float t=normalize(v).y*0.5+0.5;
+      vec3 a=vec3(0.06,0.10,0.18), b=vec3(0.45,0.40,0.55); float band=0.5+0.5*sin(normalize(v).x*8.0); vec3 col=mix(a,b,t)+band*vec3(0.10,0.06,0.14); gl_FragColor=vec4(col,1.0);}`}));
+envScene.add(grad);
+const envTex = pmrem.fromScene(envScene).texture;
+scene.environment = envTex;
+
+// ---- palette from the emotional arc ----
+const startC = new THREE.Color(P.palette.start_hex);
+const endC   = new THREE.Color(P.palette.end_hex);
+const accent = new THREE.Color(P.palette.accent_hex);
+
+// ---- build the nautilus as a tube along a log spiral of growing radius ----
+const TURNS = Math.max(1, P.turns);
+const TOTAL = TURNS * Math.PI * 2;
+const b = 0.13;                         // tighter -> whorls nearly touch
+const pts = [];
+const N = 400;
+for(let i=0;i<=N;i++){
+  const t = i/N;
+  const ang = t * TOTAL;
+  const r = 0.10 * Math.exp(b*ang);     // log spiral radius
+  const x = Math.cos(ang)*r;
+  const y = Math.sin(ang)*r;
+  const z = (t-0.5)*0.5*r;              // slight conical rise -> 3D shell
+  pts.push(new THREE.Vector3(x,y,z));
+}
+const curve = new THREE.CatmullRomCurve3(pts);
+// tube radius grows along the arm (the shell body thickens outward)
+const tubeR = 0.20;
+const geo = new THREE.TubeGeometry(curve, 600, tubeR, 24, false);
+// taper the tube: scale each ring by its position along the arm
+const pos = geo.attributes.position;
+const tmp = new THREE.Vector3();
+for(let i=0;i<pos.count;i++){
+  // approximate t by ring index
+  const ring = Math.floor(i/ (24+1));
+  const t = ring/600;
+  const grow = 0.12 + 2.4*t*t;          // fat rounded body whorl at the rim
+  tmp.fromBufferAttribute(pos,i);
+  // pull toward centerline point then push out scaled
+  const cp = curve.getPoint(Math.min(1,t));
+  tmp.sub(cp).multiplyScalar(grow).add(cp);
+  pos.setXYZ(i, tmp.x, tmp.y, tmp.z);
+}
+geo.computeVertexNormals();
+
+// ---- vertex-colored gradient along the arm (start -> end sentiment) ----
+const colors = [];
+for(let i=0;i<pos.count;i++){
+  const ring = Math.floor(i/(24+1));
+  const t = Math.min(1, ring/600);
+  const c = startC.clone().lerp(endC, t);
+  colors.push(c.r,c.g,c.b);
+}
+geo.setAttribute("color", new THREE.Float32BufferAttribute(colors,3));
+
+// ---- iridescent nacre material ----
+const mat = new THREE.MeshPhysicalMaterial({
+  vertexColors:true,
+  metalness:0.05, roughness:0.18,
+  clearcoat:1.0, clearcoatRoughness:0.18,
+  iridescence: Math.max(0.55, P.iridescence),
+  iridescenceIOR:1.6,
+  iridescenceThicknessRange:[200, 900],
+  envMapIntensity:1.6,
+  sheen:0.6, sheenColor:accent,
+});
+const shell = new THREE.Mesh(geo, mat);
+scene.add(shell);
+
+// ---- knots: raised nubs at each dead-end position along the arm ----
+const knotMat = new THREE.MeshPhysicalMaterial({color:0x2a1d12, roughness:0.3, clearcoat:1.0, iridescence:0.8, iridescenceIOR:1.4});
+for(const k of (P.knots||[])){
+  const cp = curve.getPoint(Math.min(1, k.t));
+  const s = new THREE.Mesh(new THREE.SphereGeometry(0.10+0.06*(k.severity||0.5),20,20), knotMat);
+  s.position.copy(cp); shell.add(s);
+}
+
+// ---- jewels: iridescent beads on the rim at each gotcha position ----
+// gotchas sit "along the rim", so offset each bead outward from the centerline
+// along the local radial direction (from shell center to the curve point).
+const jewelMat = new THREE.MeshPhysicalMaterial({
+  color: accent.clone().lerp(new THREE.Color(0xffffff), 0.35),
+  metalness:0.0, roughness:0.12, clearcoat:1.0, clearcoatRoughness:0.1,
+  iridescence:1.0, iridescenceIOR:1.5, iridescenceThicknessRange:[150,700],
+  envMapIntensity:1.8,
+});
+for(const j of (P.jewels||[])){
+  const cp = curve.getPoint(Math.min(1, j.t));
+  // radial direction in the shell's xy-plane (the spiral grows outward in xy)
+  const radial = new THREE.Vector3(cp.x, cp.y, 0);
+  if(radial.lengthSq() < 1e-6) radial.set(1,0,0); else radial.normalize();
+  const bead = new THREE.Mesh(new THREE.SphereGeometry(0.085,18,18), jewelMat);
+  // local tube radius grows along the arm; push the bead just past the surface
+  const localGrow = 0.12 + 2.4*j.t*j.t;
+  const off = tubeR*localGrow + 0.05;
+  bead.position.copy(cp).addScaledVector(radial, off);
+  shell.add(bead);
+}
+
+// ---- aperture: a glowing sphere at the breakthrough position ----
+const ap = P.aperture||{t:0.95,intensity:0.8};
+const apPos = curve.getPoint(Math.min(1, ap.t));
+const apMat = new THREE.MeshBasicMaterial({color:accent});
+const apMesh = new THREE.Mesh(new THREE.SphereGeometry(0.12+0.12*ap.intensity,24,24), apMat);
+apMesh.position.copy(apPos); shell.add(apMesh);
+const apLight = new THREE.PointLight(accent.getHex(), 2.0*ap.intensity, 4);
+apLight.position.copy(apPos); shell.add(apLight);
+
+// frame the shell
+const box = new THREE.Box3().setFromObject(shell);
+const center = box.getCenter(new THREE.Vector3());
+shell.position.sub(center);
+const size = box.getSize(new THREE.Vector3()).length();
+camera.position.set(0, size*0.15, size*1.1);
+camera.lookAt(0,0,0);
+
+// ---- minimal orbit controls (no extra dependency) ----
+let drag=false, px=0, py=0, rotY=0.2, rotX=-0.15, dist=size*1.1;
+const el = renderer.domElement;
+el.addEventListener("pointerdown", e=>{drag=true;px=e.clientX;py=e.clientY;});
+addEventListener("pointerup", ()=>drag=false);
+addEventListener("pointermove", e=>{ if(!drag)return;
+  rotY += (e.clientX-px)*0.008; rotX += (e.clientY-py)*0.008;
+  rotX=Math.max(-1.2,Math.min(1.2,rotX)); px=e.clientX; py=e.clientY; });
+el.addEventListener("wheel", e=>{ dist*=(1+Math.sign(e.deltaY)*0.08);
+  dist=Math.max(size*0.5,Math.min(size*3,dist)); e.preventDefault(); }, {passive:false});
+
+// pinch-zoom: two-finger distance drives the same `dist` as the wheel
+let pinchD = 0;
+el.addEventListener("touchstart", e=>{
+  if(e.touches.length===2){
+    const dx=e.touches[0].clientX-e.touches[1].clientX;
+    const dy=e.touches[0].clientY-e.touches[1].clientY;
+    pinchD = Math.hypot(dx,dy);
+    drag = false;            // suppress orbit while pinching
+  }
+}, {passive:false});
+el.addEventListener("touchmove", e=>{
+  if(e.touches.length===2 && pinchD>0){
+    const dx=e.touches[0].clientX-e.touches[1].clientX;
+    const dy=e.touches[0].clientY-e.touches[1].clientY;
+    const d = Math.hypot(dx,dy);
+    const ratio = pinchD / Math.max(1,d);     // fingers apart -> zoom in
+    dist *= ratio;
+    dist = Math.max(size*0.5, Math.min(size*3, dist));
+    pinchD = d;
+    e.preventDefault();
+  }
+}, {passive:false});
+el.addEventListener("touchend", e=>{ if(e.touches.length<2) pinchD=0; });
+
+addEventListener("resize", ()=>{ camera.aspect=innerWidth/innerHeight;
+  camera.updateProjectionMatrix(); renderer.setSize(innerWidth,innerHeight); });
+
+// ---- Tier 1: reset view ----
+// capture the framing defaults so reset restores the exact initial pose
+const DEF_rotY = rotY, DEF_rotX = rotX, DEF_dist = dist;
+const resetBtn = document.getElementById("resetBtn");
+if (resetBtn) resetBtn.addEventListener("click", ()=>{
+  rotY = DEF_rotY; rotX = DEF_rotX; dist = DEF_dist;
+});
+
+// ---- Tier 1: save image (screenshot) ----
+// WebGL clears its drawing buffer after render, so toDataURL() on a stale frame
+// is blank. We render ONE fresh frame immediately before reading the pixels, in
+// the same tick, which captures correctly without preserveDrawingBuffer.
+const shotBtn = document.getElementById("shotBtn");
+if (shotBtn) shotBtn.addEventListener("click", ()=>{
+  try {
+    renderer.render(scene, camera);              // fresh frame, same tick
+    const url = renderer.domElement.toDataURL("image/png");
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = "turboskillslug-shell-" + (P.session || "session") + ".png";
+    document.body.appendChild(a); a.click(); a.remove();
+  } catch (e) {
+    // never break the lens if capture fails (some browsers block tainted canvases)
+    console.warn("screenshot failed:", e);
+  }
+});
+
+function loop(){
+  requestAnimationFrame(loop);
+  // gentle auto-spin when idle, plus user orbit
+  if(!drag) rotY += 0.0016;
+  const cx=Math.sin(rotY)*Math.cos(rotX)*dist;
+  const cy=Math.sin(rotX)*dist;
+  const cz=Math.cos(rotY)*Math.cos(rotX)*dist;
+  camera.position.set(cx,cy,cz); camera.lookAt(0,0,0);
+  renderer.render(scene, camera);
+}
+loop();
+</script></body></html>"""

scenegraph/scene_builder.py

@@ -0,0 +1,194 @@
+"""
+build_scene_graph(extraction) -> SceneGraph
+
+Deterministically derives the full semantic scene from a session extraction. Every
+field traces to real data; same extraction always yields the same graph. This is
+the ONLY place extraction-shape knowledge lives — renderers never touch raw
+extraction (except via the escape hatch).
+"""
+
+from __future__ import annotations
+
+import colorsys
+import hashlib
+import json
+
+from scene_graph import (
+    SceneGraph, SlugState, ShellState, ArcState, BattleState, SceneEnv,
+    SCHEMA_VERSION, _norm_sentiment, _va, _clamp01,
+)
+
+
+def _session_id(extraction: dict) -> str:
+    blob = json.dumps(extraction, sort_keys=True, default=str).encode()
+    return hashlib.sha256(blob).hexdigest()[:16]
+
+
+def _hex_from_va(valence: float, energy: float) -> str:
+    """Map valence/energy to a hue/sat/light color. Negative=cool, positive=warm."""
+    # hue: 0.0 (red) .. 0.33 (green) .. 0.58 (blue). Warm/positive -> gold-green,
+    # cool/negative -> blue. Map valence -1..1 to hue 0.58..0.13.
+    hue = 0.58 - (valence + 1) / 2 * 0.45
+    sat = 0.35 + energy * 0.4
+    light = 0.42 + (valence + 1) / 2 * 0.18
+    r, g, b = colorsys.hls_to_rgb(hue, light, sat)
+    return f"#{int(r*255):02x}{int(g*255):02x}{int(b*255):02x}"
+
+
+def _build_slug(end_sent: str, dead_ends: list, arc_end_va) -> SlugState:
+    val, en = arc_end_va
+    scars = len(dead_ends)
+    # expression/pose/eyes derived from valence+energy bands
+    if val >= 0.6:
+        expr, pose, eye = "elated", "triumphant", "bright"
+    elif val >= 0.2:
+        expr, pose, eye = "hopeful", "alert", "open"
+    elif val >= -0.2:
+        expr, pose, eye = "focused", "neutral", "narrow"
+    elif en <= 0.25:
+        expr, pose, eye = "weary", "slumped", "heavy"
+    else:
+        expr, pose, eye = "wary", "neutral", "narrow"
+    return SlugState(
+        mood=_norm_sentiment(end_sent), valence=round(val, 3), energy=round(en, 3),
+        scars=scars, expression=expr, pose=pose, eye_state=eye,
+    )
+
+
+def _build_shell(duration, approaches, dead_ends, gotchas, breakthroughs,
+                 start_va, end_va) -> ShellState:
+    turns = max(1.0, min(6.0, (duration or 30) / 30.0))  # ~1 turn per 30 min, cap 6
+    n = len(approaches) + len(dead_ends)
+    growth_curve = "gentle" if n <= 2 else ("steady" if n <= 5 else "steep")
+    knots = [{"t": _clamp01(float(d.get("position", 0.5))),
+              "severity": 0.5} for d in dead_ends if isinstance(d, dict)]
+    jewels = [{"t": _clamp01((i + 1) / (len(gotchas) + 1))}
+              for i in range(len(gotchas))]
+    if breakthroughs:
+        b = breakthroughs[-1]
+        ap_t = _clamp01(float(b.get("position", 0.9))) if isinstance(b, dict) else 0.9
+    else:
+        ap_t = 0.9
+    palette = {
+        "start_hex": _hex_from_va(*start_va),
+        "end_hex": _hex_from_va(*end_va),
+        "accent_hex": "#e6c870",
+    }
+    # iridescence stronger when the arc swings far (struggle -> triumph reads richer)
+    swing = abs(end_va[0] - start_va[0])
+    return ShellState(
+        turns=round(turns, 2), growth_curve=growth_curve, knots=knots, jewels=jewels,
+        aperture={"t": ap_t, "intensity": round(0.6 + 0.4 * swing / 2, 3)},
+        palette=palette, iridescence=round(_clamp01(0.4 + swing / 2), 3),
+    )
+
+
+def _build_arc(start_sent, end_sent, dead_ends, breakthroughs, gotchas) -> ArcState:
+    beats = []
+    for d in dead_ends:
+        if isinstance(d, dict):
+            t = _clamp01(float(d.get("position", 0.5)))
+            v, e = -0.6, 0.4
+            beats.append({"t": t, "kind": "dead_end", "valence": v, "energy": e,
+                          "label": str(d.get("what_happened", "a wall"))[:60]})
+    for i, g in enumerate(gotchas):
+        beats.append({"t": _clamp01(0.3 + i * 0.1), "kind": "gotcha",
+                      "valence": -0.3, "energy": 0.5, "label": str(g)[:60]})
+    for b in breakthroughs:
+        if isinstance(b, dict):
+            t = _clamp01(float(b.get("position", 0.9)))
+            beats.append({"t": t, "kind": "breakthrough", "valence": 0.8, "energy": 0.8,
+                          "label": str(b.get("what_worked", "it gave way"))[:60]})
+    beats.sort(key=lambda x: x["t"])
+    # sample a tension curve (0..1) across 16 points: high during dead-end clusters,
+    # dropping at the breakthrough. Simple kernel sum.
+    samples = []
+    for k in range(16):
+        t = k / 15
+        tension = 0.2
+        for be in beats:
+            d = abs(be["t"] - t)
+            w = max(0.0, 1 - d * 6)
+            if be["kind"] in ("dead_end", "gotcha"):
+                tension += 0.6 * w
+            elif be["kind"] == "breakthrough":
+                tension -= 0.5 * w
+        samples.append(round(_clamp01(tension), 3))
+    return ArcState(start=_norm_sentiment(start_sent), end=_norm_sentiment(end_sent),
+                    beats=beats, tension_curve=samples)
+
+
+def _build_battle(approaches, dead_ends, gotchas, breakthroughs) -> BattleState:
+    ferocity = _clamp01(0.3 + 0.15 * len(dead_ends))
+    fallen = [{"t": _clamp01(float(d.get("position", 0.5)))}
+              for d in dead_ends if isinstance(d, dict)]
+    archers = [{"t": _clamp01(0.5 + i * 0.08)} for i in range(len(gotchas))]
+    if breakthroughs:
+        b = breakthroughs[-1]
+        dragon = {"present": True,
+                  "t": _clamp01(float(b.get("position", 0.9))) if isinstance(b, dict) else 0.9,
+                  "scale": _clamp01(0.7 + 0.3 * min(1, len(breakthroughs)))}
+    else:
+        dragon = {"present": False, "t": 1.0, "scale": 0.0}
+    return BattleState(
+        general={"present": bool(approaches)},
+        adversary={"present": True, "ferocity": round(ferocity, 3)},
+        fallen=fallen, archers=archers, dragon=dragon,
+    )
+
+
+def _build_env(start_va, end_va, dead_ends, themes) -> SceneEnv:
+    # time of day from the arc's emotional journey
+    sv, ev = start_va[0], end_va[0]
+    if ev >= 0.5 and sv < 0:
+        tod = "dawn"        # struggle -> triumph reads as a sunrise
+    elif ev >= 0.4:
+        tod = "day"
+    elif ev <= -0.3:
+        tod = "night"
+    else:
+        tod = "dusk"
+    # weather from struggle density
+    struggle = len(dead_ends)
+    weather = "clear" if struggle <= 1 else ("overcast" if struggle <= 3 else
+              ("rain" if struggle <= 5 else "storm"))
+    mood_tags = []
+    mood_tags.append({"dawn": "first light, hopeful", "day": "bright, open",
+                      "dusk": "golden hour, reflective", "night": "deep blue, quiet"}[tod])
+    mood_tags.append({"clear": "still air", "overcast": "soft grey sky",
+                      "rain": "gentle rain", "storm": "dramatic storm"}[weather])
+    if themes:
+        mood_tags.append(f"a sense of {themes[0]}")
+    palette = {
+        "sky_hex": _hex_from_va(*end_va),
+        "ground_hex": "#1a1410",
+        "accent_hex": "#e6c870",
+    }
+    return SceneEnv(time_of_day=tod, weather=weather, mood_tags=mood_tags, palette=palette)
+
+
+def build_scene_graph(extraction: dict) -> SceneGraph:
+    ex = extraction or {}
+    themes = ex.get("themes") or []
+    approaches = ex.get("approaches_tried") or []
+    dead_ends = ex.get("dead_ends") or []
+    gotchas = ex.get("gotchas") or []
+    breakthroughs = ex.get("breakthroughs") or []
+    arc = ex.get("sentiment_arc") or {}
+    start_sent, end_sent = arc.get("start"), arc.get("end")
+    duration = ex.get("duration_minutes")
+
+    start_va, end_va = _va(start_sent), _va(end_sent)
+
+    return SceneGraph(
+        schema_version=SCHEMA_VERSION,
+        session_id=_session_id(ex),
+        duration_minutes=float(duration or 0),
+        themes=themes,
+        slug=_build_slug(end_sent, dead_ends, end_va),
+        shell=_build_shell(duration, approaches, dead_ends, gotchas, breakthroughs, start_va, end_va),
+        arc=_build_arc(start_sent, end_sent, dead_ends, breakthroughs, gotchas),
+        battle=_build_battle(approaches, dead_ends, gotchas, breakthroughs),
+        env=_build_env(start_va, end_va, dead_ends, themes),
+        extraction=ex,
+    )

scenegraph/scene_graph.py

@@ -0,0 +1,134 @@
+"""
+SceneGraph: the deterministic semantic layer of a TurboSkillSlug session.
+
+This is the CONTRACT that every renderer reads. It is built once, deterministically,
+from a session extraction, and it is renderer-agnostic. The four lenses (character,
+3D shell, generative atmosphere, full diorama) all consume the SAME SceneGraph, so:
+
+  - every visible element still traces to real session data (the core promise),
+  - renderers are independent and individually degradable,
+  - a new renderer can be added without touching extraction or the others.
+
+Design rules:
+  - NOTHING here renders. No SVG, no canvas, no shader. Only structured meaning.
+  - Every field is DERIVED from the extraction (or a stable default), so the graph
+    is reproducible: same session -> same SceneGraph.
+  - Values are normalized and renderer-friendly (0..1 scalars, named enums, hex
+    colors) so each renderer can map them without re-interpreting raw extraction.
+  - The graph is versioned. Renderers declare which SCHEMA_VERSION they support.
+"""
+
+from __future__ import annotations
+
+import colorsys
+import hashlib
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+SCHEMA_VERSION = "1.0"
+
+# ---- canonical sentiment vocabulary (extraction may use freeform; we map it) ----
+# Each sentiment maps to (valence -1..1, energy 0..1) so renderers can blend.
+_SENTIMENT_VA = {
+    "frustrated": (-0.7, 0.7), "stuck": (-0.6, 0.3), "exhausted": (-0.4, 0.1),
+    "anxious": (-0.5, 0.6), "confused": (-0.4, 0.4), "focused": (0.1, 0.6),
+    "curious": (0.4, 0.6), "determined": (0.3, 0.7), "calm": (0.3, 0.3),
+    "relieved": (0.6, 0.3), "satisfied": (0.7, 0.4), "resolved": (0.7, 0.5),
+    "joyful": (0.9, 0.8), "delighted": (0.9, 0.7), "triumphant": (1.0, 0.9),
+    "neutral": (0.0, 0.4),
+}
+
+
+def _norm_sentiment(name: str | None) -> str:
+    if not name:
+        return "neutral"
+    n = str(name).strip().lower()
+    if n in _SENTIMENT_VA:
+        return n
+    # nearest by substring, else neutral
+    for k in _SENTIMENT_VA:
+        if k in n or n in k:
+            return k
+    return "neutral"
+
+
+def _va(name: str) -> tuple[float, float]:
+    return _SENTIMENT_VA[_norm_sentiment(name)]
+
+
+def _clamp01(x: float) -> float:
+    return max(0.0, min(1.0, float(x)))
+
+
+# ---------------------------------------------------------------------------
+# Sub-structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SlugState:
+    """How the slug itself looks and feels — for the CHARACTER renderer."""
+    mood: str                    # canonical end sentiment
+    valence: float               # -1..1  (sad -> happy)
+    energy: float                # 0..1   (drained -> lively)
+    scars: int                   # = number of dead ends (visible marks on the slug)
+    expression: str              # enum: weary|wary|focused|hopeful|elated
+    pose: str                    # enum: slumped|neutral|alert|triumphant
+    eye_state: str               # enum: heavy|narrow|open|bright
+
+
+@dataclass
+class ShellState:
+    """The nautilus geometry parameters — used by ALL renderers (SVG/3D/guide)."""
+    turns: float                 # number of spiral revolutions (from duration)
+    growth_curve: str            # enum: gentle|steady|steep (pacing of the session)
+    knots: list[dict]            # [{t:0..1, severity:0..1}] dead ends along the arm
+    jewels: list[dict]           # [{t:0..1}] gotchas along the rim
+    aperture: dict               # {t:0..1, intensity:0..1} the breakthrough
+    palette: dict                # {start_hex, end_hex, accent_hex}
+    iridescence: float           # 0..1 how strongly nacre shifts (for 3D shader)
+
+
+@dataclass
+class ArcState:
+    """The emotional timeline — for the SCORE and ATMOSPHERE renderers."""
+    start: str
+    end: str
+    beats: list[dict]            # ordered [{t:0..1, kind, valence, energy, label}]
+    tension_curve: list[float]   # sampled 0..1 tension over the session (for music)
+
+
+@dataclass
+class BattleState:
+    """The byobu battle cast — for the painted/animated battle layers."""
+    general: dict                # {present:bool}
+    adversary: dict              # {present:bool, ferocity:0..1}
+    fallen: list[dict]           # [{t:0..1}] one per dead end
+    archers: list[dict]          # [{t:0..1}] one per gotcha
+    dragon: dict                 # {present:bool, t:0..1, scale:0..1} breakthrough
+
+
+@dataclass
+class SceneEnv:
+    """The surrounding scene mood — for the BACKDROP/diffusion renderer."""
+    time_of_day: str             # dawn|day|dusk|night  (from arc shape)
+    weather: str                 # clear|overcast|rain|storm  (from struggle level)
+    mood_tags: list[str]         # prompt-ready descriptors for generation
+    palette: dict                # {sky_hex, ground_hex, accent_hex}
+
+
+@dataclass
+class SceneGraph:
+    schema_version: str
+    session_id: str              # stable hash of the extraction (repro + cache key)
+    duration_minutes: float
+    themes: list[str]
+    slug: SlugState
+    shell: ShellState
+    arc: ArcState
+    battle: BattleState
+    env: SceneEnv
+    # raw escape hatch: renderers that want a field we didn't surface can read this
+    extraction: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

session_genre.py

@@ -0,0 +1,124 @@
+"""Pure-regex session genre detection for TurboSkillSlug."""
+
+from __future__ import annotations
+
+import re
+
+
+GENRES = ("debugging", "exploration", "authoring", "feature", "refactor", "setup")
+
+_PATTERNS = {
+    "debugging": (
+        r"\b(debug|bug|fix|error|traceback|exception|fail(?:ed|ing)?|broken|crash|"
+        r"regression|why.*not|doesn't work|not working|stuck|issue)\b",
+    ),
+    "exploration": (
+        r"\b(explore|understand|inspect|go through|read through|map out|figure out|"
+        r"investigate|familiarize|what does|how does|codebase|repo)\b",
+    ),
+    "authoring": (
+        r"\b(write|draft|document|readme|docs|blog|article|copy|proposal|report|"
+        r"build log|submission|explain|summarize)\b",
+    ),
+    "feature": (
+        r"\b(add|implement|wire|build|create|ship|feature|endpoint|button|ui|"
+        r"component|integrate)\b",
+    ),
+    "refactor": (
+        r"\b(refactor|cleanup|clean up|reorganize|simplify|rename|dedupe|extract "
+        r"helper|move .* into)\b",
+    ),
+    "setup": (
+        r"\b(set ?up|install|configure|config|dependency|requirements|deploy|"
+        r"environment|env var|ci|workflow|initialize|scaffold)\b",
+    ),
+}
+
+_FRAMES = {
+    "debugging": (
+        "Witness the struggle: the failed approaches, the exact symptoms, the "
+        "turning point, and what finally fixed the problem."
+    ),
+    "exploration": (
+        "Witness the discoveries: the non-obvious facts learned about the "
+        "codebase, the map that emerged, and the clearest insight."
+    ),
+    "authoring": (
+        "Witness the decisions: what was clarified, what false assumptions were "
+        "caught, and what document or explanation was delivered."
+    ),
+    "feature": (
+        "Witness what was built: the new behavior, the integration points, the "
+        "naive paths that would break, and the delivered feature."
+    ),
+    "refactor": (
+        "Witness the reshaping: what moved, what got simpler, what invariants "
+        "had to hold, and what could have broken."
+    ),
+    "setup": (
+        "Witness the setup path: the configuration choices, dependency traps, "
+        "environment gotchas, and the final working baseline."
+    ),
+}
+
+_LEGENDS = {
+    "debugging": {
+        "knot": "dead ends and failed approaches",
+        "jewel": "verification gotchas",
+        "aperture": "the breakthrough that fixed it",
+    },
+    "exploration": {
+        "knot": "confusions or branches that did not explain the system",
+        "jewel": "discoveries about the codebase",
+        "aperture": "the clearest insight",
+    },
+    "authoring": {
+        "knot": "false assumptions caught",
+        "jewel": "decisions worth preserving",
+        "aperture": "the document delivered",
+    },
+    "feature": {
+        "knot": "implementation paths that would break",
+        "jewel": "integration gotchas",
+        "aperture": "the feature working",
+    },
+    "refactor": {
+        "knot": "risky seams and avoided regressions",
+        "jewel": "invariants worth remembering",
+        "aperture": "the simpler shape that remained",
+    },
+    "setup": {
+        "knot": "environment traps",
+        "jewel": "configuration details worth saving",
+        "aperture": "the working baseline",
+    },
+}
+
+
+def detect_genre(first_instruction: str, transcript: str = "") -> str:
+    """Detect the session genre with deterministic regex scoring."""
+    text = f"{first_instruction}\n{transcript[:3000]}".lower()
+    scores = {genre: 0 for genre in GENRES}
+    for genre, patterns in _PATTERNS.items():
+        for pattern in patterns:
+            scores[genre] += len(re.findall(pattern, text, re.IGNORECASE))
+
+    # First instruction is more predictive than the full transcript.
+    first = first_instruction.lower()
+    for genre, patterns in _PATTERNS.items():
+        for pattern in patterns:
+            if re.search(pattern, first, re.IGNORECASE):
+                scores[genre] += 3
+
+    best = max(GENRES, key=lambda genre: (scores[genre], -GENRES.index(genre)))
+    return best if scores[best] > 0 else "feature"
+
+
+def frame_for(genre: str) -> str:
+    """Return the witness frame for a genre."""
+    return _FRAMES.get(genre, _FRAMES["feature"])
+
+
+def shell_legend(genre: str) -> dict[str, str]:
+    """Return genre-specific meanings for shell features."""
+    return dict(_LEGENDS.get(genre, _LEGENDS["feature"]))

shell.py

@@ -0,0 +1,496 @@
+"""
+Shell generator for TurboSkillSlug.
+
+Every shell is unique because every session is unique. The patterns are
+derived from the session, not decorative: duration shapes the spiral,
+dead ends leave dark knots, breakthroughs open the aperture, gotchas
+become iridescent jewels, and the sentiment arc drives the color story.
+
+Visual techniques:
+  - SVG feTurbulence for mother-of-pearl (nacre) texture
+  - feGaussianBlur composites for glow on aperture and jewels
+  - Multi-stop radial gradients for depth
+  - HSL-derived color harmonies from sentiment
+  - Cubic bezier smoothing on the spiral body
+  - Layered transparency for organic depth
+
+Staged growth:
+  generate_shell_svg(features, growth=g) renders the shell at completion
+  fraction g in [0,1]. At g<1 the spiral is physically shorter, only the
+  knots and jewels up to that point have formed, and the aperture (the
+  breakthrough mouth) stays closed until g reaches 1.0 - the breakthrough
+  is the last thing to open. growth=1.0 is byte-identical in intent to the
+  original single-shot render.
+"""
+
+import colorsys
+import math
+import random
+
+from shell_battle import build_battle_layer
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# HSL-based color system derived from sentiment
+# ---------------------------------------------------------------------------
+
+SENTIMENT_HUES: dict[str, float] = {
+    "confused": 0.75,     # violet
+    "focused": 0.61,      # deep blue
+    "frustrated": 0.0,    # red
+    "curious": 0.50,      # teal
+    "resolved": 0.39,     # green
+    "joyful": 0.12,       # warm gold
+    "exhausted": 0.67,    # grey-blue
+    "enlightened": 0.14,  # pale gold
+}
+
+
+def _hue_for(sentiment: str, fallback: float = 0.75) -> float:
+    return SENTIMENT_HUES.get(sentiment.lower().strip(), fallback)
+
+
+def _hsl_to_hex(h: float, s: float, l: float) -> str:
+    r, g, b = colorsys.hls_to_rgb(h, l, s)
+    return f"#{int(r*255):02x}{int(g*255):02x}{int(b*255):02x}"
+
+
+def _palette(start_sent: str, end_sent: str) -> dict[str, str]:
+    """Derive a harmonious 6-color palette from start/end sentiment."""
+    h0 = _hue_for(start_sent, 0.75)
+    h1 = _hue_for(end_sent, 0.39)
+    return {
+        "bg_deep":       _hsl_to_hex(h0, 0.30, 0.06),
+        "bg_mid":        _hsl_to_hex(h0, 0.25, 0.12),
+        "body_dark":     _hsl_to_hex(h0, 0.35, 0.30),
+        "body_light":    _hsl_to_hex(h1, 0.40, 0.50),
+        "accent":        _hsl_to_hex(h1, 0.55, 0.65),
+        "highlight":     _hsl_to_hex(h1, 0.30, 0.85),
+        "aperture_core": _hsl_to_hex(h1, 0.20, 0.92),
+        "jewel":         _hsl_to_hex((h0 + h1) / 2, 0.60, 0.70),
+        "knot":          _hsl_to_hex(h0, 0.40, 0.10),
+        "septa":         _hsl_to_hex(h0, 0.20, 0.15),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Spiral geometry
+# ---------------------------------------------------------------------------
+
+def _log_spiral(cx: float, cy: float, n_turns: float,
+                r0: float, r_max: float, n_points: int = 500):
+    """Generate points along a logarithmic spiral with normals."""
+    t_max = 2 * math.pi * max(n_turns, 0.5)
+    b = math.log(max(r_max, r0 + 1) / r0) / t_max
+    pts = []
+    for i in range(n_points):
+        t = (i / (n_points - 1)) * t_max
+        r = r0 * math.exp(b * t)
+        x = cx + r * math.cos(t)
+        y = cy + r * math.sin(t)
+        tangent = t + math.atan2(1, b)
+        normal = tangent + math.pi / 2
+        pts.append((x, y, t, r, normal))
+    return pts
+
+
+def _smooth_path(pts: list, closed: bool = False) -> str:
+    """Convert points to a smooth SVG path using cubic bezier approximation."""
+    if len(pts) < 2:
+        return ""
+    d = [f"M {pts[0][0]:.1f} {pts[0][1]:.1f}"]
+    tension = 0.3
+    for i in range(1, len(pts)):
+        p0 = pts[max(i - 2, 0)]
+        p1 = pts[i - 1]
+        p2 = pts[i]
+        p3 = pts[min(i + 1, len(pts) - 1)]
+        cp1x = p1[0] + (p2[0] - p0[0]) * tension
+        cp1y = p1[1] + (p2[1] - p0[1]) * tension
+        cp2x = p2[0] - (p3[0] - p1[0]) * tension
+        cp2y = p2[1] - (p3[1] - p1[1]) * tension
+        d.append(f"C {cp1x:.1f} {cp1y:.1f} {cp2x:.1f} {cp2y:.1f} {p2[0]:.1f} {p2[1]:.1f}")
+    if closed:
+        d.append("Z")
+    return " ".join(d)
+
+
+def _band_path_smooth(inner: list, outer: list) -> str:
+    """Closed smooth path for the shell body (outer forward, inner reverse)."""
+    fwd = _smooth_path(outer)
+    rev_pts = list(reversed(inner))
+    if rev_pts:
+        rev = f"L {rev_pts[0][0]:.1f} {rev_pts[0][1]:.1f} "
+        tension = 0.3
+        for i in range(1, len(rev_pts)):
+            p0 = rev_pts[max(i - 2, 0)]
+            p1 = rev_pts[i - 1]
+            p2 = rev_pts[i]
+            p3 = rev_pts[min(i + 1, len(rev_pts) - 1)]
+            cp1x = p1[0] + (p2[0] - p0[0]) * tension
+            cp1y = p1[1] + (p2[1] - p0[1]) * tension
+            cp2x = p2[0] - (p3[0] - p1[0]) * tension
+            cp2y = p2[1] - (p3[1] - p1[1]) * tension
+            rev += f"C {cp1x:.1f} {cp1y:.1f} {cp2x:.1f} {cp2y:.1f} {p2[0]:.1f} {p2[1]:.1f} "
+        return fwd + " " + rev + "Z"
+    return fwd + " Z"
+
+
+# ---------------------------------------------------------------------------
+# Main generator
+# ---------------------------------------------------------------------------
+
+def generate_shell_svg(features: dict[str, Any], growth: float = 1.0) -> str:
+    """Generate a beautiful SVG shell from session features.
+
+    growth in [0,1] controls how far the shell has formed. At growth<1 the
+    spiral is truncated, only knots/jewels up to that fraction appear, and the
+    aperture stays closed until growth==1.0. growth>=1.0 is the full shell.
+    """
+    growth = max(0.0, min(1.0, float(growth)))
+
+    duration = max(5, min(180, int(features.get("duration_minutes", 30) or 30)))
+    approaches = features.get("approaches_tried", []) or []
+    dead_ends = features.get("dead_ends", []) or []
+    breakthroughs = features.get("breakthroughs", []) or []
+    gotchas = features.get("gotchas", []) or []
+    themes = features.get("themes", []) or []
+    sentiment = features.get("sentiment_arc", {}) or {}
+
+    start_sent = sentiment.get("start", "confused")
+    end_sent = sentiment.get("end", "resolved")
+    pal = _palette(start_sent, end_sent)
+
+    seed = hash(str(features.get("duration_minutes", 0))) % 10000
+    rng = random.Random(seed)
+
+    W = H = 640
+    cx, cy = W / 2, H / 2 + 15
+
+    n_turns = 2.4 + 0.35 * len(approaches) + duration / 150.0
+    n_turns = min(n_turns, 4.5)
+    r0 = 5
+    r_max = min(W * 0.38, 65 + duration * 2.0)
+
+    # Always compute the FULL spiral (geometry is stable); growth truncates
+    # how much of it we draw, so the partial shell is a true prefix of the
+    # final one (no reflow, no jitter between stages).
+    full_centerline = _log_spiral(cx, cy, n_turns, r0, r_max, n_points=500)
+    n_full = len(full_centerline)
+    n_grown = max(2, int(round(n_full * growth)))
+    centerline = full_centerline[:n_grown]
+
+    def thickness_at(idx: int, total_full: int) -> float:
+        # thickness keyed to position in the FULL spiral, so a point's
+        # thickness is identical whether or not later points exist yet
+        frac = idx / max(1, total_full - 1)
+        return 3 + (r_max * 0.28) * (frac ** 1.35)
+
+    outer_pts = []
+    inner_pts = []
+    for i, (x, y, t, r, n) in enumerate(centerline):
+        th = thickness_at(i, n_full)
+        outer_pts.append((x + math.cos(n) * th, y + math.sin(n) * th, t, r, n))
+        inner_pts.append((x - math.cos(n) * th, y - math.sin(n) * th, t, r, n))
+
+    svg = []
+    svg.append(
+        f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {W} {H}" '
+        f'width="{W}" height="{H}">'
+    )
+
+    # ---- DEFS: filters, gradients, patterns ----
+    svg.append(f'''<defs>
+  <!-- Nacre / mother-of-pearl: barely-there shimmer, not noise -->
+  <filter id="nacre" x="-5%" y="-5%" width="110%" height="110%">
+    <feTurbulence type="fractalNoise" baseFrequency="0.007 0.015"
+                  numOctaves="3" seed="{seed}" result="noise"/>
+    <feColorMatrix in="noise" type="saturate" values="0.2" result="colored"/>
+    <feBlend in="SourceGraphic" in2="colored" mode="soft-light" result="nacred"/>
+    <feComposite in="nacred" in2="SourceGraphic" operator="in"/>
+  </filter>
+
+  <!-- Glow for aperture -->
+  <filter id="glow" x="-50%" y="-50%" width="200%" height="200%">
+    <feGaussianBlur stdDeviation="8" result="blur"/>
+    <feComposite in="SourceGraphic" in2="blur" operator="over"/>
+  </filter>
+
+  <!-- Soft glow for jewels -->
+  <filter id="jewelGlow" x="-80%" y="-80%" width="260%" height="260%">
+    <feGaussianBlur stdDeviation="3" result="blur"/>
+    <feComposite in="SourceGraphic" in2="blur" operator="over"/>
+  </filter>
+
+  <!-- Soft shadow for depth -->
+  <filter id="depth" x="-5%" y="-5%" width="110%" height="110%">
+    <feGaussianBlur stdDeviation="1.5"/>
+  </filter>
+
+  <!-- Shell body gradient (high contrast, 5 stops) -->
+  <radialGradient id="bodyGrad" cx="40%" cy="40%" r="70%">
+    <stop offset="0%"   stop-color="{pal['highlight']}" stop-opacity="0.85"/>
+    <stop offset="20%"  stop-color="{pal['body_light']}" stop-opacity="0.9"/>
+    <stop offset="50%"  stop-color="{pal['accent']}" stop-opacity="0.8"/>
+    <stop offset="80%"  stop-color="{pal['body_dark']}" stop-opacity="0.9"/>
+    <stop offset="100%" stop-color="{pal['bg_mid']}" stop-opacity="0.95"/>
+  </radialGradient>
+
+  <!-- Aperture glow gradient -->
+  <radialGradient id="apertureGrad" cx="50%" cy="50%" r="60%">
+    <stop offset="0%"   stop-color="{pal['aperture_core']}" stop-opacity="0.95"/>
+    <stop offset="40%"  stop-color="{pal['highlight']}" stop-opacity="0.7"/>
+    <stop offset="70%"  stop-color="{pal['accent']}" stop-opacity="0.4"/>
+    <stop offset="100%" stop-color="{pal['body_light']}" stop-opacity="0"/>
+  </radialGradient>
+
+  <!-- Jewel gradient -->
+  <radialGradient id="jewelGrad" cx="30%" cy="30%" r="70%">
+    <stop offset="0%"   stop-color="#fff" stop-opacity="0.95"/>
+    <stop offset="30%"  stop-color="{pal['jewel']}" stop-opacity="0.85"/>
+    <stop offset="70%"  stop-color="{pal['accent']}" stop-opacity="0.6"/>
+    <stop offset="100%" stop-color="{pal['body_dark']}" stop-opacity="0.3"/>
+  </radialGradient>
+
+  <!-- Background atmosphere gradient -->
+  <radialGradient id="atmosphere" cx="45%" cy="45%" r="65%">
+    <stop offset="0%"   stop-color="{pal['bg_mid']}" stop-opacity="0.8"/>
+    <stop offset="50%"  stop-color="{pal['bg_deep']}" stop-opacity="0.9"/>
+    <stop offset="100%" stop-color="{pal['bg_deep']}" stop-opacity="1"/>
+  </radialGradient>
+</defs>''')
+
+    # ---- BACKGROUND with atmosphere ----
+    svg.append(f'<rect width="{W}" height="{H}" fill="{pal["bg_deep"]}"/>')
+    svg.append(f'<rect width="{W}" height="{H}" fill="url(#atmosphere)"/>')
+
+    for _ in range(40):
+        px = rng.uniform(20, W - 20)
+        py = rng.uniform(20, H - 20)
+        pr = rng.uniform(0.3, 1.2)
+        po = rng.uniform(0.15, 0.45)
+        svg.append(
+            f'<circle cx="{px:.1f}" cy="{py:.1f}" r="{pr:.2f}" '
+            f'fill="{pal["highlight"]}" opacity="{po:.2f}"/>'
+        )
+
+    svg.append(
+        f'<circle cx="{cx}" cy="{cy}" r="{r_max + 90}" '
+        f'fill="{pal["body_dark"]}" opacity="0.08"/>'
+    )
+    svg.append(
+        f'<circle cx="{cx}" cy="{cy}" r="{r_max + 50}" '
+        f'fill="{pal["body_light"]}" opacity="0.06"/>'
+    )
+
+    # ---- SHELL BODY with nacre texture ----
+    body_d = _band_path_smooth(inner_pts, outer_pts)
+    svg.append(
+        f'<path d="{body_d}" fill="{pal["bg_deep"]}" opacity="0.4" '
+        f'transform="translate(3, 4)" filter="url(#depth)"/>'
+    )
+    svg.append(
+        f'<path class="shell-body" d="{body_d}" fill="url(#bodyGrad)" '
+        f'stroke="{pal["septa"]}" stroke-width="0.5" filter="url(#nacre)"/>'
+    )
+
+    # ---- SEPTA (chamber ridges) ----
+    septa_step = 14 if "debug" in themes else (18 if "build" in themes else 16)
+    if len(centerline) > septa_step + 8:
+        total_septa = (len(centerline) - 8 - septa_step) // septa_step
+        for si, i in enumerate(range(septa_step, len(centerline) - 8, septa_step)):
+            ix, iy = inner_pts[i][0], inner_pts[i][1]
+            ox, oy = outer_pts[i][0], outer_pts[i][1]
+            frac = si / max(1, total_septa)
+            opacity = 0.15 + frac * 0.35
+            svg.append(
+                f'<line x1="{ix:.1f}" y1="{iy:.1f}" '
+                f'x2="{ox:.1f}" y2="{oy:.1f}" '
+                f'stroke="{pal["septa"]}" stroke-width="0.7" '
+                f'opacity="{opacity:.2f}" stroke-linecap="round"/>'
+            )
+
+    # ---- LONGITUDINAL BANDS ----
+    for frac, opacity in [(0.2, 0.2), (0.4, 0.3), (0.6, 0.25), (0.8, 0.2)]:
+        band = []
+        for (ox, oy, *_), (ix, iy, *_) in zip(outer_pts, inner_pts):
+            bx = ix + (ox - ix) * frac
+            by = iy + (oy - iy) * frac
+            band.append((bx, by))
+        path_d = _smooth_path(band)
+        color = pal["accent"] if frac > 0.5 else pal["highlight"]
+        svg.append(
+            f'<path d="{path_d}" fill="none" stroke="{color}" '
+            f'stroke-width="0.6" opacity="{opacity}"/>'
+        )
+
+    # ---- CENTERLINE shimmer ----
+    cl_path = _smooth_path(centerline)
+    svg.append(
+        f'<path class="shell-centerline" d="{cl_path}" fill="none" '
+        f'stroke="{pal["highlight"]}" stroke-width="0.5" opacity="0.4"/>'
+    )
+
+    # ---- OUTER RIM GLOW ----
+    rim_path = _smooth_path(outer_pts)
+    svg.append(
+        f'<path class="shell-rim" d="{rim_path}" fill="none" '
+        f'stroke="{pal["accent"]}" stroke-width="2.5" opacity="0.15" '
+        f'filter="url(#jewelGlow)"/>'
+    )
+    svg.append(
+        f'<path d="{rim_path}" fill="none" '
+        f'stroke="{pal["highlight"]}" stroke-width="0.8" opacity="0.5"/>'
+    )
+
+    # ---- CENTRAL EYE ----
+    ex, ey = centerline[0][0], centerline[0][1]
+    svg.append(
+        f'<circle cx="{ex:.1f}" cy="{ey:.1f}" r="4" '
+        f'fill="{pal["accent"]}" opacity="0.3" filter="url(#jewelGlow)"/>'
+    )
+    svg.append(
+        f'<circle cx="{ex:.1f}" cy="{ey:.1f}" r="1.8" '
+        f'fill="{pal["highlight"]}" opacity="0.85"/>'
+    )
+    svg.append(
+        f'<circle cx="{ex - 0.4:.1f}" cy="{ey - 0.5:.1f}" r="0.6" '
+        f'fill="#fff" opacity="0.9"/>'
+    )
+
+    # ---- BYOBU BATTLE LAYER (figures along the spiral) ----
+    # Always on: the nautilus is the battlefield. Dead ends are fallen
+    # warriors, gotchas are archers, the breakthrough is the dragon at the
+    # aperture. Drawn under the canonical knots/jewels so the markers still
+    # read. Only on the fully grown shell (growth>=1.0); during birth the
+    # shell forms first, then the battle populates it.
+    if growth >= 1.0:
+        try:
+            svg.append(build_battle_layer(
+                features, centerline, outer_pts, thickness_at, n_full, pal, seed
+            ))
+        except Exception as _battle_err:
+            # The battle layer is decorative; never let it break the shell.
+            pass
+
+    # ---- DEAD-END KNOTS (only those that have formed by this growth) ----
+    for de in dead_ends:
+        pos = max(0.04, min(0.96, float(de.get("position", 0.5))))
+        if pos > growth:
+            continue  # not yet formed at this stage
+        idx = int(pos * (n_full - 1))
+        if idx >= len(centerline):
+            continue
+        x, y, _, r, _ = centerline[idx]
+        th = thickness_at(idx, n_full)
+        kr = max(3.5, th * 0.32)
+        svg.append(
+            f'<circle cx="{x + 1:.1f}" cy="{y + 1:.1f}" r="{kr + 1:.1f}" '
+            f'fill="{pal["bg_deep"]}" opacity="0.5" filter="url(#depth)"/>'
+        )
+        svg.append(
+            f'<circle class="shell-knot" cx="{x:.1f}" cy="{y:.1f}" r="{kr:.1f}" '
+            f'fill="{pal["knot"]}" stroke="{pal["body_dark"]}" '
+            f'stroke-width="1" opacity="0.9"/>'
+        )
+        svg.append(
+            f'<circle cx="{x - 1:.1f}" cy="{y - 1.2:.1f}" r="{kr * 0.3:.1f}" '
+            f'fill="{pal["body_dark"]}" opacity="0.6"/>'
+        )
+
+    # ---- GOTCHA JEWELS (those whose rim position has formed) ----
+    n_jewels = min(len(gotchas), 12)
+    for i in range(n_jewels):
+        frac = 0.28 + (i / max(1, n_jewels)) * 0.65
+        if frac > growth:
+            continue  # rim hasn't reached this jewel yet
+        idx = int(frac * (len(outer_pts) - 1)) if outer_pts else 0
+        if idx >= len(outer_pts):
+            continue
+        ox, oy, _, _, n = outer_pts[idx]
+        jx = ox + math.cos(n) * 4
+        jy = oy + math.sin(n) * 4
+        svg.append(
+            f'<circle cx="{jx:.1f}" cy="{jy:.1f}" r="9" '
+            f'fill="{pal["jewel"]}" opacity="0.3" filter="url(#jewelGlow)"/>'
+        )
+        svg.append(
+            f'<circle class="shell-jewel" cx="{jx:.1f}" cy="{jy:.1f}" r="4.5" '
+            f'fill="url(#jewelGrad)" opacity="0.95"/>'
+        )
+        svg.append(
+            f'<circle cx="{jx - 1:.1f}" cy="{jy - 1.2:.1f}" r="1.2" '
+            f'fill="#fff" opacity="0.9"/>'
+        )
+
+    # ---- APERTURE (breakthrough mouth) - opens only when fully grown ----
+    # The breakthrough is the LAST thing to form. It opens as growth nears 1.0,
+    # fading in over the final 15% so the reveal lands on the breakthrough.
+    if growth > 0.85:
+        aperture_op = min(1.0, (growth - 0.85) / 0.15)
+        bidx = len(centerline) - 1
+        bx, by, _, br, bn = centerline[bidx]
+        bth = thickness_at(bidx, n_full)
+        svg.append(
+            f'<ellipse cx="{bx:.1f}" cy="{by:.1f}" '
+            f'rx="{bth * 2.0:.1f}" ry="{bth * 1.5:.1f}" '
+            f'transform="rotate({math.degrees(bn):.0f} {bx:.1f} {by:.1f})" '
+            f'fill="{pal["accent"]}" opacity="{0.15 * aperture_op:.2f}" filter="url(#glow)"/>'
+        )
+        svg.append(
+            f'<ellipse class="shell-aperture" cx="{bx:.1f}" cy="{by:.1f}" '
+            f'rx="{bth * 1.2:.1f}" ry="{bth * 0.9:.1f}" '
+            f'transform="rotate({math.degrees(bn):.0f} {bx:.1f} {by:.1f})" '
+            f'fill="url(#apertureGrad)" opacity="{0.95 * aperture_op:.2f}"/>'
+        )
+        svg.append(
+            f'<ellipse cx="{bx:.1f}" cy="{by:.1f}" '
+            f'rx="{bth * 0.4:.1f}" ry="{bth * 0.28:.1f}" '
+            f'transform="rotate({math.degrees(bn):.0f} {bx:.1f} {by:.1f})" '
+            f'fill="{pal["aperture_core"]}" opacity="{0.9 * aperture_op:.2f}"/>'
+        )
+
+    # ---- SIGNATURE (full shell only) ----
+    if growth >= 1.0:
+        stats = (
+            f"turboskillslug · {duration}m · {len(approaches)} tried · "
+            f"{len(dead_ends)} stumbles · {len(gotchas)} jewels"
+        )
+        svg.append(
+            f'<text x="{W - 14}" y="{H - 14}" text-anchor="end" '
+            f'fill="{pal["body_light"]}" font-size="9" opacity="0.5" '
+            f'font-family="Georgia, serif" font-style="italic">{stats}</text>'
+        )
+
+    svg.append("</svg>")
+    return "\n".join(svg)
+
+
+# ---------------------------------------------------------------------------
+# Smoke test
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    from pathlib import Path
+
+    sample = {
+        "duration_minutes": 47,
+        "themes": ["debug", "build"],
+        "approaches_tried": [
+            {"approach": "naive regex", "why_it_failed": "too brittle"},
+            {"approach": "ast parser", "why_it_failed": "complex setup"},
+        ],
+        "dead_ends": [
+            {"position": 0.15, "what_happened": "regex backtracked"},
+            {"position": 0.42, "what_happened": "missing edge case"},
+            {"position": 0.61, "what_happened": "wrong import"},
+        ],
+        "breakthroughs": [{"position": 0.88, "what_worked": "ast walk"}],
+        "gotchas": ["null nodes", "tabs vs spaces", "comments",
+                    "windows line endings", "unicode"],
+        "sentiment_arc": {"start": "frustrated", "end": "resolved"},
+    }
+    for g in [0.2, 0.4, 0.6, 0.8, 1.0]:
+        Path(f"growth_{int(g*100)}.svg").write_text(generate_shell_svg(sample, growth=g))
+        print(f"wrote growth_{int(g*100)}.svg")

shell3d_lens.py

@@ -0,0 +1,46 @@
+"""
+Integration shim: exposes the 3D shell lens to the flat-imported app.
+
+Robust to layout: the scenegraph modules (scene_graph / scene_builder / renderer /
+shell3d) may live in a scenegraph/ subfolder OR be flattened to the repo root by the
+deploy. We add BOTH this file's directory and a scenegraph/ subdir (if present) to
+sys.path, then import by module name. Exposes one entry point:
+    render_shell_3d(extraction) -> iframe HTML, or None (graceful degradation).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+# add the repo root (files may be flattened here) ...
+if _HERE not in sys.path:
+    sys.path.insert(0, _HERE)
+# ... and a scenegraph/ subfolder if it exists (files may be nested there)
+_SUB = os.path.join(_HERE, "scenegraph")
+if os.path.isdir(_SUB) and _SUB not in sys.path:
+    sys.path.insert(0, _SUB)
+_SUBREND = os.path.join(_SUB, "renderers")
+if os.path.isdir(_SUBREND) and _SUBREND not in sys.path:
+    sys.path.insert(0, _SUBREND)
+
+
+def render_shell_3d(extraction: dict) -> str | None:
+    """Build the SceneGraph and render the 3D iridescent shell. Returns iframe HTML,
+    or None if anything is unavailable (the app degrades gracefully)."""
+    try:
+        from scene_builder import build_scene_graph
+        from shell3d import Shell3DRenderer
+    except Exception:
+        return None
+    try:
+        scene = build_scene_graph(extraction)
+        renderer = Shell3DRenderer()
+        ok, _reason = renderer.available()
+        if not ok:
+            return None
+        out = renderer.render(scene)
+        return out.get("html")
+    except Exception:
+        return None

shell_animate.py

@@ -0,0 +1,190 @@
+"""
+Scroll-unroll birth animation for the shell.
+
+The shell is born like an ancient scroll unfurling. A radial wipe mask reveals
+the colored spiral from the eye outward — the scroll unrolling — led by a glowing
+gold parchment edge. As the unrolling front passes each battle figure, that
+figure inks in. The breakthrough dragon and aperture land last, at the tip.
+
+Why a wipe MASK and not stroke-drawing: the shell body is a single filled spiral
+path, so it cannot "draw" like a stroke. A growing radial mask genuinely reveals
+the filled body progressively, which is what reads as a scroll unrolling.
+
+SMIL (native SVG animation) so it survives Gradio's sanitizer; wrapped in an
+<iframe srcdoc>. fill="freeze" holds the final static shell. Figures default
+visible (animation drives them from opacity 0), so a no-SMIL browser still shows
+the complete shell.
+"""
+
+from __future__ import annotations
+
+import re
+
+from anim_diagnostic import inject_probe
+
+DIAGNOSTIC = False
+
+SCROLL_DUR = 3.6          # seconds for the scroll to fully unroll
+FIG_FADE = 0.7            # seconds each figure takes to ink in
+EYE_X, EYE_Y = 320.0, 335.0   # shell eye (spiral origin); body starts here
+MAX_R = 330.0            # radius that covers the whole 640 canvas from the eye
+KEYSPLINE = "0.3 0 0.4 1"     # ease for the unroll
+
+
+def _scroll_mask_and_edge(animated_only: bool = True) -> tuple[str, str]:
+    """Return (mask_def, glowing_edge) for the live animated scroll-unroll."""
+    mask_circle = (
+        f'<circle cx="{EYE_X}" cy="{EYE_Y}" r="0" fill="white">'
+        f'<animate attributeName="r" from="0" to="{MAX_R}" dur="{SCROLL_DUR}s" '
+        f'begin="0s" fill="freeze" calcMode="spline" keySplines="{KEYSPLINE}" '
+        f'keyTimes="0;1"/></circle>'
+    )
+    mask_def = f'<mask id="scrollWipe">{mask_circle}</mask>'
+    edge = (
+        f'<g class="scroll-edge">'
+        f'<circle cx="{EYE_X}" cy="{EYE_Y}" r="0" fill="none" stroke="#e6c870" '
+        f'stroke-width="6" opacity="0.55">'
+        f'<animate attributeName="r" from="0" to="{MAX_R}" dur="{SCROLL_DUR}s" '
+        f'begin="0s" fill="freeze" calcMode="spline" keySplines="{KEYSPLINE}" keyTimes="0;1"/>'
+        f'<animate attributeName="opacity" values="0.55;0.55;0" keyTimes="0;0.82;1" '
+        f'dur="{SCROLL_DUR}s" begin="0s" fill="freeze"/></circle>'
+        f'<circle cx="{EYE_X}" cy="{EYE_Y}" r="0" fill="none" stroke="#efe0b0" '
+        f'stroke-width="2" opacity="0.8">'
+        f'<animate attributeName="r" from="0" to="{MAX_R}" dur="{SCROLL_DUR}s" '
+        f'begin="0s" fill="freeze" calcMode="spline" keySplines="{KEYSPLINE}" keyTimes="0;1"/>'
+        f'<animate attributeName="opacity" values="0.8;0.8;0" keyTimes="0;0.82;1" '
+        f'dur="{SCROLL_DUR}s" begin="0s" fill="freeze"/></circle>'
+        f'</g>'
+    )
+    return mask_def, edge
+
+
+def _ink_figures(svg: str) -> str:
+    """Each battle-fig group inks in (fade + slight rise) when the unrolling front
+    reaches its data-pos radius. begin = pos * SCROLL_DUR (the dragon, pos==1.0,
+    lands at the very end)."""
+    def repl(m):
+        tag = m.group(0)
+        pos_match = re.search(r'data-pos="([\d.]+)"', tag)
+        pos = float(pos_match.group(1)) if pos_match else 0.5
+        begin = round(pos * SCROLL_DUR, 2)
+        anim = (
+            f'<animate attributeName="opacity" from="0" to="1" '
+            f'dur="{FIG_FADE}s" begin="{begin}s" fill="freeze"/>'
+            f'<animateTransform attributeName="transform" type="translate" '
+            f'from="0 8" to="0 0" dur="{FIG_FADE}s" begin="{begin}s" '
+            f'fill="freeze" calcMode="spline" keySplines="0.2 0.8 0.2 1" keyTimes="0;1"/>'
+        )
+        # do NOT hard-set opacity 0 (keeps figures visible if SMIL fails)
+        return tag + anim
+    return re.sub(r'<g class="battle-fig" data-pos="[\d.]+">', repl, svg)
+
+
+def animate_shell_svg(svg: str, seed=0, style: str | None = None) -> str:
+    """Inject the scroll-unroll birth: a radial wipe mask reveals the shell from
+    the eye outward, a gold parchment edge rides the unrolling front, and the
+    battle figures ink in as the front passes them.
+    """
+    # 1. inject the mask def + edge after </defs>
+    defs_end = svg.find("</defs>")
+    if defs_end == -1:
+        open_end = svg.find(">", svg.find("<svg")) + 1
+        svg = svg[:open_end] + "<defs></defs>" + svg[open_end:]
+        defs_end = svg.find("</defs>")
+    insert_at = defs_end + len("</defs>")
+    mask_def, edge = _scroll_mask_and_edge()
+
+    # 2. wrap the shell (from the body onward) in the masked group. Background
+    #    (rect, atmosphere, particles, halos) stays unmasked so only the SHELL
+    #    unrolls, against a steady night sky.
+    body_idx = svg.find('<path class="shell-body"')
+    if body_idx == -1:
+        body_idx = insert_at  # fallback: mask everything after defs
+    svg_close = svg.rfind("</svg>")
+
+    head = svg[:insert_at] + mask_def
+    pre_shell = svg[insert_at:body_idx]
+    shell_region = svg[body_idx:svg_close]
+    tail = svg[svg_close:]
+
+    shell_region = _ink_figures(shell_region)
+
+    return (
+        head
+        + pre_shell
+        + '<g mask="url(#scrollWipe)">'
+        + shell_region
+        + '</g>'
+        + edge
+        + tail
+    )
+
+
+# ---- iframe wrapping (survives Gradio sanitizer) + replay button -------------
+
+REPLAY_HTML = """
+<button id="replay-birth" title="watch the scroll unroll again">\u21bb watch it unroll again</button>
+<style>
+#replay-birth{
+  position:fixed;left:50%;bottom:10px;transform:translateX(-50%);
+  z-index:9999;font:12px/1.2 Georgia,serif;font-style:italic;
+  padding:6px 14px;border-radius:14px;cursor:pointer;
+  background:rgba(20,16,12,0.55);color:#efe0b0;border:1px solid rgba(200,162,76,0.5);
+  backdrop-filter:blur(2px);transition:opacity .3s;opacity:0.78;
+}
+#replay-birth:hover{opacity:1;background:rgba(20,16,12,0.75);}
+</style>
+<script>
+(function(){
+  function restart(){
+    var svg = document.querySelector('svg');
+    if(!svg) return;
+    // Rewind the whole SVG timeline. For begin="0s" animations this re-runs
+    // them from the top. We pause, seek to 0, then unpause so the flipbook
+    // (stage opacity keyframes) and the curl motion both restart cleanly.
+    try {
+      svg.pauseAnimations();
+      svg.setCurrentTime(0);
+      svg.unpauseAnimations();
+    } catch(e){
+      // fallback: plain rewind
+      try { svg.setCurrentTime(0); } catch(e2){}
+    }
+  }
+  var btn = document.getElementById('replay-birth');
+  if(btn){ btn.addEventListener('click', restart); }
+})();
+</script>
+"""
+
+
+def inject_replay(iframe_inner_html: str) -> str:
+    if "</body>" in iframe_inner_html:
+        return iframe_inner_html.replace("</body>", REPLAY_HTML + "</body>", 1)
+    return iframe_inner_html + REPLAY_HTML
+
+
+def wrap_in_iframe(animated_svg: str, height: int = 660, replay: bool = True) -> str:
+    """Wrap the animated SVG in an <iframe srcdoc> (survives Gradio sanitizer),
+    rendered as a centered square so the whole shell shows."""
+    import html as _html
+    doc = (
+        "<!DOCTYPE html><html><head><style>"
+        "html,body{margin:0;padding:0;background:transparent;overflow:hidden;"
+        "height:100%;display:flex;align-items:center;justify-content:center}"
+        "svg{max-width:100%;max-height:100%;width:auto;height:auto;display:block}"
+        "</style></head><body>" + animated_svg + "</body></html>"
+    )
+    if DIAGNOSTIC:
+        doc = inject_probe(doc)
+    if replay:
+        doc = inject_replay(doc)
+    escaped = _html.escape(doc, quote=True)
+    return (
+        f'<div style="display:flex;justify-content:center;width:100%;">'
+        f'<iframe srcdoc="{escaped}" '
+        f'style="width:{height}px;max-width:100%;height:{height}px;'
+        f'border:none;background:transparent;" '
+        f'sandbox="allow-scripts"></iframe>'
+        f'</div>'
+    )

shell_battle.py

@@ -0,0 +1,379 @@
+"""
+Byobu battle layer for the shell.
+
+The nautilus IS the battlefield. The spiral is the campaign path: the eye is
+where the session began, the outward sweep is time. Session events become
+stylized ink-on-gold figures, in the flat perspective of Japanese folding
+screens (byobu):
+
+  developer    -> the lone general near the eye, a banner at their side
+  dead ends    -> fallen warriors + broken banners at their spiral positions
+  gotchas      -> archers along the outer rim (the ambushes)
+  breakthrough -> the dragon coiled at the aperture, a victory banner upright
+  sentiment    -> gold cloud-bands and a few hill/pine terrain strokes
+
+Figures are dark ink silhouettes riding on gold-leaf cloud bands. They are
+drawn small so they sit IN the landscape, not over it.
+
+The layer is produced from the SAME spiral geometry the shell uses, so a
+fallen warrior sits exactly where its dead-end knot is.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+
+
+# Ink + gold palette (byobu). The figures are near-black sumi ink; the clouds
+# and banners are gold leaf. These are fixed, not sentiment-driven, because the
+# byobu convention is ink-on-gold regardless of the campaign's mood (the mood
+# lives in the shell's own colors underneath).
+INK = "#1a1410"
+INK_SOFT = "#2c2218"
+GOLD = "#c8a24c"
+GOLD_BRIGHT = "#e6c870"
+GOLD_PALE = "#efe0b0"
+
+
+
+def _gold_backing(x: float, y: float, r: float) -> str:
+    """A gold-leaf disc behind a figure so dark ink reads against gold. A faint
+    dark ring keeps the figure legible even on gold-heavy (warm) shells where
+    the gold backing would otherwise blend into the body."""
+    return (
+        f'<circle cx="{x:.1f}" cy="{y:.1f}" r="{r + 1.5:.1f}" fill="{INK}" opacity="0.30"/>'
+        f'<circle cx="{x:.1f}" cy="{y:.1f}" r="{r:.1f}" fill="{GOLD}" opacity="0.62"/>'
+        f'<circle cx="{x:.1f}" cy="{y:.1f}" r="{r:.1f}" fill="none" '
+        f'stroke="{INK}" stroke-width="0.8" opacity="0.45"/>'
+    )
+
+def _cloud_band(cx: float, cy: float, w: float, h: float, seed: int) -> str:
+    """A gold-leaf byobu cloud band: a soft lobed cloud (smooth quad curves).
+
+    Real byobu clouds are scalloped, billowing shapes, not rectangles. We build
+    a closed path of rounded lobes along the top and bottom edges.
+    """
+    rng = random.Random(seed)
+    n = rng.randint(4, 6)
+    left = cx - w / 2
+    step = w / n
+    # top edge: a series of upward lobes; bottom edge: downward lobes
+    d = f"M {left:.1f} {cy:.1f} "
+    x = left
+    for i in range(n):
+        nx = x + step
+        peak = cy - h / 2 - rng.uniform(0, h * 0.3)
+        d += f"Q {x + step/2:.1f} {peak:.1f} {nx:.1f} {cy:.1f} "
+        x = nx
+    for i in range(n):
+        nx = x - step
+        trough = cy + h / 2 + rng.uniform(0, h * 0.3)
+        d += f"Q {x - step/2:.1f} {trough:.1f} {nx:.1f} {cy:.1f} "
+        x = nx
+    d += "Z"
+    return (
+        f'<path d="{d}" fill="{GOLD}" opacity="0.20"/>'
+        f'<path d="{d}" fill="none" stroke="{GOLD_BRIGHT}" '
+        f'stroke-width="0.7" opacity="0.4"/>'
+    )
+
+
+def _banner(x: float, y: float, h: float, color: str, broken: bool = False,
+            angle: float = 0.0) -> str:
+    """A small byobu banner on a pole. Broken = leaning, torn."""
+    pole_top = (x, y - h)
+    lean = 28 if broken else 0
+    tx = x + math.sin(math.radians(angle + lean)) * h
+    ty = y - math.cos(math.radians(angle + lean)) * h
+    pole = (
+        f'<line x1="{x:.1f}" y1="{y:.1f}" x2="{tx:.1f}" y2="{ty:.1f}" '
+        f'stroke="{INK}" stroke-width="1.1" stroke-linecap="round"/>'
+    )
+    # flag near the top of the pole
+    fx, fy = tx, ty
+    fw = h * 0.5
+    fh = h * 0.42
+    if broken:
+        # torn flag: a notched quad
+        flag = (
+            f'<path d="M {fx:.1f} {fy:.1f} L {fx+fw:.1f} {fy+fh*0.2:.1f} '
+            f'L {fx+fw*0.7:.1f} {fy+fh*0.5:.1f} L {fx+fw:.1f} {fy+fh*0.8:.1f} '
+            f'L {fx:.1f} {fy+fh:.1f} Z" fill="{color}" opacity="0.85"/>'
+        )
+    else:
+        flag = (
+            f'<path d="M {fx:.1f} {fy:.1f} L {fx+fw:.1f} {fy+fh*0.25:.1f} '
+            f'L {fx+fw:.1f} {fy+fh*0.75:.1f} L {fx:.1f} {fy+fh:.1f} Z" '
+            f'fill="{color}" opacity="0.9"/>'
+        )
+    return pole + flag
+
+
+def _kabuto(x: float, y: float, s: float, ink: str) -> str:
+    """A kabuto helmet silhouette with the crescent (maedate) crest."""
+    # dome
+    dome = (
+        f'<path d="M {x - s*0.26:.1f} {y:.1f} '
+        f'Q {x:.1f} {y - s*0.42:.1f} {x + s*0.26:.1f} {y:.1f} Z" fill="{ink}"/>'
+    )
+    # neck guard (shikoro) flare
+    flare = (
+        f'<path d="M {x - s*0.30:.1f} {y:.1f} L {x - s*0.34:.1f} {y + s*0.12:.1f} '
+        f'L {x + s*0.34:.1f} {y + s*0.12:.1f} L {x + s*0.30:.1f} {y:.1f} Z" '
+        f'fill="{ink}"/>'
+    )
+    # crescent crest (maedate) - two horns
+    crest = (
+        f'<path d="M {x - s*0.22:.1f} {y - s*0.12:.1f} '
+        f'Q {x:.1f} {y - s*0.55:.1f} {x + s*0.22:.1f} {y - s*0.12:.1f} '
+        f'Q {x:.1f} {y - s*0.34:.1f} {x - s*0.22:.1f} {y - s*0.12:.1f} Z" '
+        f'fill="{ink}"/>'
+    )
+    return dome + flare + crest
+
+
+def _katana(x1, y1, x2, y2, ink) -> str:
+    """A katana: a slightly curved blade stroke with a guard."""
+    mx = (x1 + x2) / 2 + (y2 - y1) * 0.12
+    my = (y1 + y2) / 2 - (x2 - x1) * 0.12
+    blade = (
+        f'<path d="M {x1:.1f} {y1:.1f} Q {mx:.1f} {my:.1f} {x2:.1f} {y2:.1f}" '
+        f'fill="none" stroke="{ink}" stroke-width="1.4" stroke-linecap="round"/>'
+    )
+    guard = f'<circle cx="{x1:.1f}" cy="{y1:.1f}" r="1.6" fill="{ink}"/>'
+    return blade + guard
+
+
+def _general(x: float, y: float, s: float) -> str:
+    """The developer: a standing samurai general, kabuto + katana raised."""
+    # torso (armored, slightly trapezoidal do)
+    torso = (
+        f'<path d="M {x - s*0.20:.1f} {y - s*0.52:.1f} '
+        f'L {x - s*0.30:.1f} {y:.1f} L {x + s*0.30:.1f} {y:.1f} '
+        f'L {x + s*0.20:.1f} {y - s*0.52:.1f} Z" fill="{INK}"/>'
+    )
+    # armor lames (two horizontal segment lines)
+    lames = (
+        f'<line x1="{x - s*0.26:.1f}" y1="{y - s*0.16:.1f}" '
+        f'x2="{x + s*0.26:.1f}" y2="{y - s*0.16:.1f}" stroke="{GOLD_PALE}" '
+        f'stroke-width="0.6" opacity="0.5"/>'
+        f'<line x1="{x - s*0.22:.1f}" y1="{y - s*0.04:.1f}" '
+        f'x2="{x + s*0.22:.1f}" y2="{y - s*0.04:.1f}" stroke="{GOLD_PALE}" '
+        f'stroke-width="0.6" opacity="0.5"/>'
+    )
+    # head + kabuto
+    head = f'<circle cx="{x:.1f}" cy="{y - s*0.60:.1f}" r="{s*0.12:.1f}" fill="{INK}"/>'
+    helm = _kabuto(x, y - s*0.64, s*0.9, INK)
+    # katana raised diagonally
+    sword = _katana(x + s*0.24, y - s*0.30, x + s*0.62, y - s*0.78, INK)
+    return torso + lames + head + helm + sword
+
+
+def _fallen(x: float, y: float, s: float, ink: str) -> str:
+    """A fallen warrior: toppled samurai, kabuto askew, katana dropped."""
+    # body lying down (rotated trapezoid torso)
+    g = f'<g transform="rotate(82 {x:.1f} {y:.1f})" opacity="0.9">'
+    torso = (
+        f'<path d="M {x - s*0.18:.1f} {y - s*0.48:.1f} '
+        f'L {x - s*0.26:.1f} {y:.1f} L {x + s*0.26:.1f} {y:.1f} '
+        f'L {x + s*0.18:.1f} {y - s*0.48:.1f} Z" fill="{ink}"/>'
+    )
+    head = f'<circle cx="{x:.1f}" cy="{y - s*0.56:.1f}" r="{s*0.11:.1f}" fill="{ink}"/>'
+    helm = _kabuto(x, y - s*0.60, s*0.8, ink)
+    g_end = '</g>'
+    # dropped katana lying separately, near the body
+    sword = _katana(x - s*0.5, y + s*0.15, x - s*0.05, y + s*0.30, ink)
+    return g + torso + head + helm + g_end + sword
+
+
+def _archer(x: float, y: float, s: float, ink: str) -> str:
+    """A samurai archer: kneeling, drawing a tall asymmetric yumi bow."""
+    # kneeling body
+    body = (
+        f'<path d="M {x - s*0.05:.1f} {y - s*0.40:.1f} '
+        f'L {x - s*0.28:.1f} {y:.1f} L {x + s*0.10:.1f} {y:.1f} Z" fill="{ink}"/>'
+    )
+    head = f'<circle cx="{x - s*0.02:.1f}" cy="{y - s*0.48:.1f}" r="{s*0.10:.1f}" fill="{ink}"/>'
+    helm = _kabuto(x - s*0.02, y - s*0.52, s*0.7, ink)
+    # tall yumi bow (asymmetric: grip below center, long upper limb)
+    bx = x + s * 0.28
+    bow = (
+        f'<path d="M {bx:.1f} {y - s*0.75:.1f} '
+        f'Q {bx + s*0.34:.1f} {y - s*0.15:.1f} {bx:.1f} {y + s*0.32:.1f}" '
+        f'fill="none" stroke="{ink}" stroke-width="1.1"/>'
+    )
+    # bowstring + nocked arrow drawn back
+    string = (
+        f'<line x1="{bx:.1f}" y1="{y - s*0.75:.1f}" x2="{bx:.1f}" y2="{y + s*0.32:.1f}" '
+        f'stroke="{ink}" stroke-width="0.5"/>'
+    )
+    arrow = (
+        f'<line x1="{x + s*0.02:.1f}" y1="{y - s*0.30:.1f}" '
+        f'x2="{bx + s*0.10:.1f}" y2="{y - s*0.30:.1f}" stroke="{ink}" stroke-width="0.7"/>'
+    )
+    return body + head + helm + bow + string + arrow
+
+
+def _dragon(x: float, y: float, s: float, angle_deg: float) -> str:
+    """The breakthrough: an Eastern dragon, maned head + horns + sinuous segmented
+    body + clawed legs, coiling toward the aperture."""
+    seg = s
+    a = math.radians(angle_deg)
+    # build the spine path
+    d = f"M {x:.1f} {y:.1f} "
+    px, py = x, y
+    spine = [(px, py)]
+    for i in range(1, 8):
+        swing = (1 if i % 2 else -1) * seg * 0.55
+        nx = px + math.cos(a) * seg * 0.55 + math.cos(a + math.pi/2) * swing
+        ny = py + math.sin(a) * seg * 0.55 + math.sin(a + math.pi/2) * swing
+        d += f"Q {px + math.cos(a+math.pi/2)*swing:.1f} {py + math.sin(a+math.pi/2)*swing:.1f} {nx:.1f} {ny:.1f} "
+        spine.append((nx, ny))
+        px, py = nx, ny
+    body = (
+        f'<path d="{d}" fill="none" stroke="{INK}" stroke-width="{s*0.30:.1f}" '
+        f'stroke-linecap="round" opacity="0.92"/>'
+    )
+    # dorsal ridge: small spikes along the spine
+    spikes = ""
+    for i in range(1, len(spine) - 1, 2):
+        sx, sy = spine[i]
+        spikes += (
+            f'<circle cx="{sx:.1f}" cy="{sy:.1f}" r="{s*0.07:.1f}" fill="{INK}"/>'
+        )
+    # clawed legs at two points
+    legs = ""
+    for i in (2, 5):
+        if i < len(spine):
+            lx, ly = spine[i]
+            legs += (
+                f'<line x1="{lx:.1f}" y1="{ly:.1f}" x2="{lx - s*0.3:.1f}" '
+                f'y2="{ly + s*0.3:.1f}" stroke="{INK}" stroke-width="{s*0.10:.1f}" '
+                f'stroke-linecap="round"/>'
+            )
+    # head at the start (where the dragon faces): maned, horned, gold eye
+    hx, hy = x, y
+    head = (
+        f'<circle cx="{hx:.1f}" cy="{hy:.1f}" r="{s*0.26:.1f}" fill="{INK}"/>'
+        # two horns
+        f'<line x1="{hx - s*0.1:.1f}" y1="{hy - s*0.18:.1f}" '
+        f'x2="{hx - s*0.28:.1f}" y2="{hy - s*0.42:.1f}" stroke="{INK}" '
+        f'stroke-width="{s*0.06:.1f}" stroke-linecap="round"/>'
+        f'<line x1="{hx + s*0.1:.1f}" y1="{hy - s*0.18:.1f}" '
+        f'x2="{hx + s*0.18:.1f}" y2="{hy - s*0.44:.1f}" stroke="{INK}" '
+        f'stroke-width="{s*0.06:.1f}" stroke-linecap="round"/>'
+        # mane (a few short strokes behind the head)
+        f'<path d="M {hx + s*0.2:.1f} {hy:.1f} q {s*0.2:.1f} {s*0.1:.1f} {s*0.12:.1f} {s*0.3:.1f}" '
+        f'fill="none" stroke="{INK}" stroke-width="{s*0.05:.1f}"/>'
+        # gold eye
+        f'<circle cx="{hx + s*0.08:.1f}" cy="{hy - s*0.06:.1f}" r="{s*0.06:.1f}" '
+        f'fill="{GOLD_BRIGHT}"/>'
+    )
+    return body + spikes + legs + head
+
+
+def _point_at_radius_frac(centerline, rfrac):
+    """Find the spiral point whose radius is closest to rfrac of the max radius.
+
+    The log-spiral bunches points near the eye, so placing by point-index
+    clusters figures in the center. Placing by RADIUS spreads them across the
+    visible outer arms where there is room for figures.
+    """
+    if not centerline:
+        return None
+    radii = [p[3] for p in centerline]  # r is index 3
+    r_min, r_max = min(radii), max(radii)
+    target = r_min + (r_max - r_min) * rfrac
+    best_i = min(range(len(centerline)), key=lambda i: abs(radii[i] - target))
+    return centerline[best_i]
+
+
+
+def _fig(pos_frac: float, inner_svg: str) -> str:
+    """Wrap a figure cluster in a group tagged with its unroll position (0..1),
+    so the birth animation can ink it in when the scroll reaches it."""
+    p = max(0.0, min(1.0, float(pos_frac)))
+    return f'<g class="battle-fig" data-pos="{p:.3f}">{inner_svg}</g>'
+
+
+def build_battle_layer(features: dict, centerline: list, outer_pts: list,
+                       thickness_at, n_full: int, pal: dict, seed: int) -> str:
+    """Return the byobu battle layer SVG, placed on the shell's spiral by RADIUS
+    so figures spread across the visible outer arms (not the bunched eye).
+
+    Each figure sits on a gold backing (byobu ink-on-gold). Figures are sized to
+    be legible on the 640px canvas.
+    """
+    rng = random.Random(seed ^ 0xBA771E)
+    dead_ends = features.get("dead_ends", []) or []
+    gotchas = features.get("gotchas", []) or []
+
+    parts = ["<g class=\"battle-layer\">"]
+
+    # ---- gold cloud bands drifting across the OUTER field ----
+    # Clouds are atmosphere; they ink in early and at their radius position.
+    for i in range(3):
+        rfrac = 0.55 + 0.15 * i
+        p = _point_at_radius_frac(centerline, min(0.95, rfrac))
+        if p:
+            x, y = p[0], p[1]
+            parts.append(_fig(min(0.95, rfrac), _cloud_band(
+                x, y, w=rng.uniform(120, 180), h=rng.uniform(30, 44), seed=seed + i)))
+
+    # ---- the general (developer): mid-outer arm. Inks in when scroll reaches 0.66.
+    p = _point_at_radius_frac(centerline, 0.66)
+    if p:
+        gx, gy = p[0], p[1]
+        general = (
+            _gold_backing(gx, gy - 10, 30)
+            + _general(gx, gy, s=40)
+            + _banner(gx + 26, gy + 4, h=46, color=INK)
+        )
+        parts.append(_fig(0.66, general))
+
+    # ---- fallen warriors at each dead end, placed + revealed by RADIUS ----
+    for de in dead_ends:
+        pos = max(0.0, min(1.0, float(de.get("position", 0.5))))
+        rfrac = 0.48 + pos * 0.46  # 0.48 .. 0.94 (keep out of the crowded eye)
+        p = _point_at_radius_frac(centerline, rfrac)
+        if not p:
+            continue
+        x, y = p[0], p[1]
+        fallen = (
+            _gold_backing(x, y, 22)
+            + _fallen(x, y, s=28, ink=INK)
+            + _banner(x + 12, y - 2, h=26, color=INK, broken=True,
+                      angle=rng.uniform(-12, 12))
+        )
+        parts.append(_fig(rfrac, fallen))
+
+    # ---- archers along the rim at each gotcha ----
+    n_arch = min(len(gotchas), 8)
+    for i in range(n_arch):
+        frac = 0.52 + (i / max(1, n_arch)) * 0.44
+        idx = int(frac * (len(outer_pts) - 1)) if outer_pts else 0
+        if idx >= len(outer_pts):
+            continue
+        ox, oy, _, _, nrm = outer_pts[idx]
+        ax = ox + math.cos(nrm) * 18
+        ay = oy + math.sin(nrm) * 18
+        archer = _gold_backing(ax, ay, 15) + _archer(ax, ay, s=24, ink=INK)
+        parts.append(_fig(frac, archer))
+
+    # ---- the dragon (breakthrough): inks in LAST, when the scroll reaches the tip.
+    tip = centerline[-1]
+    pre = centerline[max(0, len(centerline) - 18)]
+    dx, dy = pre[0], pre[1]
+    bn = tip[4]
+    dragon = (
+        f'<ellipse cx="{dx:.1f}" cy="{dy:.1f}" rx="46" ry="30" '
+        f'transform="rotate({math.degrees(bn):.0f} {dx:.1f} {dy:.1f})" '
+        f'fill="{GOLD}" opacity="0.30"/>'
+        + _dragon(dx, dy, s=42, angle_deg=math.degrees(bn) + 150)
+        + _banner(dx - 20, dy + 10, h=56, color=INK)
+    )
+    parts.append(_fig(1.0, dragon))
+
+    parts.append("</g>")
+    return "\n".join(parts)

shell_unroll.py

@@ -0,0 +1,136 @@
+"""
+Path-following scroll unroll: the spiral lays down ALONG its arm, led by a 3D curl.
+
+The shell's `growth` parameter truncates the spiral along its own arm (not
+radially), so a sequence of growth stages IS a scroll unrolling along the spiral
+path: an outer ring stays hidden until the arm reaches it, even if an inner point
+at the same clock-angle is already laid down.
+
+We render N growth stages as a flipbook stacked in one SVG. Each stage is shown
+in sequence via SMIL (set/animate on opacity), so the laid parchment grows along
+the arm. A 3D curl object (a small cylinder with a gold highlight and a cast
+shadow) rides the leading tip via animateMotion along the centerline path,
+shrinking as it spends its paper, then vanishes at the rim.
+
+This is heavier than a single-SVG animation (~1.6MB for 14 stages) but it is the
+only way to get a genuine path-following reveal of a filled spiral.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+
+N_STAGES = 14
+UNROLL_DUR = 3.6          # total seconds
+EYE_X, EYE_Y = 320.0, 335.0
+
+
+def _centerline_d(svg: str) -> str | None:
+    m = re.search(r'<path class="shell-centerline" d="([^"]*)"', svg)
+    return m.group(1) if m else None
+
+
+def _curl_object(stage_frac: float) -> str:
+    """A 3D paper-curl cylinder, sized for how much paper remains (shrinks as the
+    scroll unrolls). Returned as a <g id="curl"> to be motion-animated."""
+    # remaining paper ~ (1 - stage_frac); curl radius shrinks from ~16 to ~5
+    r = 5 + 11 * (1 - stage_frac)
+    return (
+        f'<g id="paper-curl">'
+        # cast shadow on the parchment just behind the curl
+        f'<ellipse cx="2" cy="{r*0.6:.1f}" rx="{r*1.1:.1f}" ry="{r*0.45:.1f}" '
+        f'fill="#1a1410" opacity="0.28"/>'
+        # the cylinder body (the rolled paper, seen end-on)
+        f'<ellipse cx="0" cy="0" rx="{r:.1f}" ry="{r*0.78:.1f}" '
+        f'fill="#d8c79a" stroke="#8a7340" stroke-width="1"/>'
+        # inner roll rings (paper thickness)
+        f'<ellipse cx="0" cy="0" rx="{r*0.6:.1f}" ry="{r*0.46:.1f}" '
+        f'fill="none" stroke="#a8915c" stroke-width="0.8" opacity="0.7"/>'
+        f'<ellipse cx="0" cy="0" rx="{r*0.28:.1f}" ry="{r*0.22:.1f}" '
+        f'fill="#bda874" stroke="#8a7340" stroke-width="0.6"/>'
+        # gold highlight on the rounded leading edge
+        f'<ellipse cx="{-r*0.4:.1f}" cy="{-r*0.3:.1f}" rx="{r*0.34:.1f}" '
+        f'ry="{r*0.2:.1f}" fill="#efe0b0" opacity="0.85"/>'
+        f'</g>'
+    )
+
+
+def build_unroll_doc(stage_svgs: list[str]) -> str:
+    """Stack growth-stage SVGs as a flipbook + a curl riding the tip. Returns one
+    SVG string with SMIL timing. stage_svgs[i] is the shell at growth (i+1)/N.
+
+    Each stage is wrapped in a <g> that becomes visible at its time slot and
+    hides when the next appears, so the laid parchment advances along the arm.
+    The final stage stays visible (freeze).
+    """
+    n = len(stage_svgs)
+    slot = UNROLL_DUR / n
+
+    # strip the outer <svg ...> wrapper from each stage, keep inner content
+    def inner(s):
+        a = s.find(">", s.find("<svg")) + 1
+        b = s.rfind("</svg>")
+        return s[a:b]
+
+    # the background (sky, particles) is identical across stages; take it from
+    # the LAST stage once, render it always-on underneath, and only flip the
+    # SHELL portion. But simplest robust approach: each stage is a full frame;
+    # show one at a time. The sky is identical so no flicker on the backdrop.
+    layers = []
+    for i, s in enumerate(stage_svgs):
+        content = inner(s)
+        # Each stage is visible only during its own [begin, begin+slot) window.
+        # We drive this with a SINGLE <animate> using values/keyTimes over the
+        # whole duration, so it resets cleanly on replay (setCurrentTime(0)).
+        on_t = i / n
+        off_t = (i + 1) / n
+        if i == n - 1:
+            # final stage: turn on at its start and STAY on (freeze full shell)
+            if on_t <= 0:
+                vals, keys = "1;1", "0;1"
+            else:
+                vals = "0;0;1;1"
+                keys = f"0;{on_t:.4f};{on_t:.4f};1"
+        elif i == 0:
+            # first stage: on from 0, off at off_t
+            vals = "1;1;0;0"
+            keys = f"0;{off_t:.4f};{off_t:.4f};1"
+        else:
+            # middle stage: off, on at on_t, off at off_t, off after
+            vals = "0;0;1;1;0;0"
+            keys = f"0;{on_t:.4f};{on_t:.4f};{off_t:.4f};{off_t:.4f};1"
+        anim = (
+            f'<animate attributeName="opacity" values="{vals}" keyTimes="{keys}" '
+            f'dur="{UNROLL_DUR}s" begin="0s" fill="freeze" calcMode="discrete"/>'
+        )
+        start_op = "1" if i == 0 else "0"
+        layers.append(f'<g opacity="{start_op}">{anim}{content}</g>')
+
+    # the 3D curl rides the centerline path of the FINAL stage (full spiral),
+    # via animateMotion, shrinking over the unroll, vanishing at the end.
+    cl = _centerline_d(stage_svgs[-1])
+    curl_layer = ""
+    if cl:
+        curl = _curl_object(0.0)
+        curl_layer = (
+            f'<g>{curl}'
+            f'<animateMotion dur="{UNROLL_DUR}s" begin="0s" fill="freeze" '
+            f'rotate="auto" keyPoints="0;1" keyTimes="0;1" calcMode="linear" '
+            f'path="{cl}"/>'
+            # shrink the curl as it spends paper
+            f'<animateTransform attributeName="transform" type="scale" '
+            f'additive="sum" from="1.6" to="0.5" dur="{UNROLL_DUR}s" begin="0s" '
+            f'fill="freeze"/>'
+            # vanish at the very end
+            f'<animate attributeName="opacity" values="1;1;0" keyTimes="0;0.92;1" '
+            f'dur="{UNROLL_DUR}s" begin="0s" fill="freeze"/>'
+            f'</g>'
+        )
+
+    W = H = 640
+    body = "".join(layers) + curl_layer
+    return (
+        f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {W} {H}" '
+        f'width="{W}" height="{H}">{body}</svg>'
+    )

skill_builder.py

@@ -0,0 +1,354 @@
+"""
+Build a genuinely useful SKILL.md from a session extraction.
+
+The judge's note: the skill file should give an LLM real uplift even over a
+frontier model that is already capable without it. Research on what makes skills
+work (Anthropic skill-creator, Perplexity, SkillsBench) converges on a few
+principles, and this module encodes them:
+
+  1. The GOTCHAS section is the highest-value content. Each gotcha names the
+     SYMPTOM, explains the CAUSE, and implies the FIX. These are the things a
+     capable model would still get wrong because they are non-obvious and
+     specific to this problem, not derivable from general knowledge.
+
+  2. Explain the WHY. Frontier models have good theory of mind; rote steps waste
+     them. The transferable value is the reasoning behind what worked.
+
+  3. Dead ends are uplift. A strong model can find the happy path; what it cannot
+     know is which promising-looking approaches FAIL and why, which saves it from
+     wasting moves. So we surface the approaches tried and why each failed as
+     "what not to do."
+
+  4. Transferable, not narrative. The skill must read as procedure for the NEXT
+     person hitting this class of problem, not as a diary of this session.
+
+  5. A frontmatter description that states what it does AND when to use it, so a
+     skills-compatible agent triggers it on the right tasks.
+
+This module takes the structured extraction (which the model is good at) and
+assembles the prose into the skill shape (which is mechanical and should not be
+left to the model to format consistently).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+def _slugify(text: str, fallback: str = "session-skill") -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", str(text).lower()).strip("-")
+    return s or fallback
+
+
+def _title_from_themes(themes: list, problem_hint: str) -> str:
+    if themes:
+        return " / ".join(t.strip() for t in themes[:3])
+    return problem_hint or "Debugging session"
+
+
+def _infer_problem(extraction: dict) -> str:
+    """A one-line statement of the problem class this skill addresses."""
+    themes = extraction.get("themes", []) or []
+    dead = extraction.get("dead_ends", []) or []
+    breaks = extraction.get("breakthroughs", []) or []
+    if breaks:
+        w = breaks[-1].get("what_worked", "") if isinstance(breaks[-1], dict) else ""
+        if w:
+            return f"Solving the kind of problem where the fix is: {w.strip().rstrip(chr(46))}."
+    if themes:
+        return f"Working through a {', '.join(themes[:2])} problem."
+    return "Working through a technical problem that took several attempts."
+
+
+def _build_description(extraction: dict, problem: str) -> str:
+    """Frontmatter description: what it does + when to trigger. Slightly pushy,
+    per skill-creator guidance, because agents tend to under-trigger."""
+    themes = extraction.get("themes", []) or []
+    gotchas = extraction.get("gotchas", []) or []
+    trig = ""
+    if themes:
+        trig = (
+            f" Use this whenever a task involves {', '.join(themes[:3])}, "
+            f"or when you hit symptoms similar to the gotchas below, even if the "
+            f"user does not name them explicitly."
+        )
+    g = f" Captures {len(gotchas)} specific gotcha(s) that are easy to get wrong." if gotchas else ""
+    return (
+        f"Hard-won procedure for: {problem.rstrip('.')}.{g}{trig}"
+    ).strip()
+
+
+def _approaches_block(extraction: dict) -> str:
+    """What was tried and why it FAILED — i.e. what NOT to do, with reasons.
+
+    This is uplift: a capable model can find a path, but cannot know which
+    promising approaches are dead ends without being told.
+    """
+    approaches = extraction.get("approaches_tried", []) or []
+    if not approaches:
+        return (
+            "_No failed approaches were recorded for this session — it went "
+            "straight to a working solution._"
+        )
+    lines = [
+        "These approaches were tried and did NOT work. Avoid repeating them, or "
+        "understand why they fail before reaching for them again:\n"
+    ]
+    for a in approaches:
+        if not isinstance(a, dict):
+            continue
+        ap = str(a.get("approach", "")).strip()
+        why = str(a.get("why_it_failed", "")).strip().rstrip(".")
+        if ap:
+            lines.append(f"- **{ap}** — fails because {why}." if why else f"- **{ap}** — did not work.")
+    return "\n".join(lines)
+
+
+def _gotchas_block(extraction: dict) -> str:
+    """The highest-value section. Symptom -> cause -> implied fix.
+
+    We reshape each raw gotcha string into the symptom/cause/fix frame where the
+    text allows; if the gotcha is terse, we still present it as a watch-out with
+    a prompt to check for it, because naming the trap is itself the value.
+    """
+    gotchas = extraction.get("gotchas", []) or []
+    if not gotchas:
+        return "_No specific gotchas were recorded for this session._"
+    lines = [
+        "These are the non-obvious traps from this problem — the things that are "
+        "easy to get wrong and costly to rediscover. Check each one before "
+        "assuming the obvious approach is safe:\n"
+    ]
+    # Phase 1 (RuleShaping arXiv:2604.11088): under each gotcha, emit a negative,
+    # preferably state-dependent guardrail — the only individually beneficial rule
+    # type. Deterministic + content-preserving (never fabricates a cause), so this
+    # adds zero model calls and cannot invent anything not in the gotcha.
+    try:
+        from rule_phrasing import to_negative_constraint, is_negative_constraint
+    except Exception:
+        to_negative_constraint = None
+        is_negative_constraint = None
+    for g in gotchas:
+        g = str(g).strip().rstrip(".")
+        if not g:
+            continue
+        lines.append(f"- {g}.")
+        if to_negative_constraint is not None:
+            rule = to_negative_constraint(g)
+            if (rule and rule.rstrip(".").lower() != g.lower()
+                    and is_negative_constraint(rule)):
+                lines.append(f"  - **Guardrail:** {rule}")
+    return "\n".join(lines)
+
+
+def _breakthrough_block(extraction: dict) -> str:
+    breaks = extraction.get("breakthroughs", []) or []
+    if not breaks:
+        return "_No single breakthrough was recorded; progress was incremental._"
+    lines = ["What actually worked, and the reasoning that makes it transferable:\n"]
+    for b in breaks:
+        if not isinstance(b, dict):
+            continue
+        w = str(b.get("what_worked", "")).strip().rstrip(".")
+        if w:
+            lines.append(f"- {w}.")
+    return "\n".join(lines)
+
+
+def _principles_block(extraction: dict) -> str:
+    """Distill transferable principles from the arc. This is the 'why' layer."""
+    approaches = extraction.get("approaches_tried", []) or []
+    gotchas = extraction.get("gotchas", []) or []
+    breaks = extraction.get("breakthroughs", []) or []
+    out = []
+    if approaches and breaks:
+        out.append(
+            "- The working solution came only after the failed approaches above. "
+            "If you are reaching for one of those first, reconsider."
+        )
+    if gotchas:
+        out.append(
+            "- Most of the difficulty here was not the main logic but the "
+            "edge conditions in the gotchas. Budget attention there."
+        )
+    if not out:
+        out.append(
+            "- This session was straightforward; the main value is the working "
+            "approach recorded below."
+        )
+    return "\n".join(out)
+
+
+
+
+def _is_terse(text: str) -> bool:
+    """A gotcha is terse (low-value) if it's short and lacks a cause/fix signal."""
+    t = str(text).strip()
+    if len(t.split()) <= 6:
+        return True
+    # no causal/fix language -> probably just a label
+    signals = ("because", "since", "so ", "instead", "fix", "use ", "avoid",
+               "must", "should", "results in", "leads to", "causes", ";")
+    return not any(sig in t.lower() for sig in signals)
+
+
+
+# Phrases from illustrative examples that must never appear in real output —
+# if they do, the model leaked the example instead of expanding the real gotcha.
+_LEAK_MARKERS = (
+    "reverse-bfs", "count_of_uncolored", "subtree_root", "leaf nodes first",
+    "number_of_uncolored_children", "process deepest-first",
+)
+
+
+def _looks_leaked(text: str) -> bool:
+    t = str(text).lower()
+    return any(marker in t for marker in _LEAK_MARKERS)
+
+
+def enrich_gotchas(extraction: dict, complete=None) -> dict:
+    """Optionally expand terse gotchas into symptom/cause/fix form via one model
+    call. `complete` is a function (prompt:str) -> str. If None, or if no terse
+    gotchas, returns the extraction unchanged.
+
+    This is the optional depth pass: the better extraction prompt handles most
+    cases; this rescues sessions where the model still emitted thin labels.
+    """
+    gotchas = extraction.get("gotchas", []) or []
+    if not complete or not gotchas:
+        return extraction
+    terse = [g for g in gotchas if _is_terse(g)]
+    if not terse:
+        return extraction
+
+    themes = ", ".join(extraction.get("themes", []) or []) or "this problem"
+    approaches = extraction.get("approaches_tried", []) or []
+    ctx_lines = []
+    for a in approaches:
+        if isinstance(a, dict) and a.get("approach"):
+            ctx_lines.append(f"- tried {a['approach']}: {a.get('why_it_failed','')}")
+    ctx = "\n".join(ctx_lines)
+
+    prompt = (
+        "You are sharpening the gotchas in a coding skill file so they give a "
+        "capable engineer real, non-obvious help.\n\n"
+        f"PROBLEM AREA: {themes}\n"
+        f"WHAT WAS TRIED AND FAILED:\n{ctx}\n\n"
+        "Your job: rewrite each terse gotcha below into ONE self-contained "
+        "sentence that names the symptom, the cause, and what to do instead. "
+        "CRITICAL RULES:\n"
+        "- Each rewritten gotcha MUST be specific to the problem area above "
+        f"({themes}). Do NOT invent details from other domains.\n"
+        "- Base the rewrite ONLY on the terse gotcha's own meaning plus the "
+        "problem area. If you cannot rescue it without inventing facts, return it "
+        "UNCHANGED.\n"
+        "- Return ONLY a JSON array of strings, same length and order as the "
+        "input. No prose, no code fences.\n\n"
+        "Terse gotchas to rewrite:\n"
+        + "\n".join(f"- {g}" for g in terse)
+    )
+
+    try:
+        import json
+        raw = complete(prompt)
+        raw = raw.strip()
+        # strip code fences if present
+        import re as _re
+        raw = _re.sub(r"^```(?:json)?|```$", "", raw, flags=_re.MULTILINE).strip()
+        expanded = json.loads(raw)
+        if isinstance(expanded, list) and len(expanded) == len(terse):
+            # map terse -> expanded, but REJECT any expansion that leaked the
+            # example phrasing (keep the original terse gotcha in that case).
+            cleaned = []
+            for original, exp in zip(terse, expanded):
+                exp = str(exp).strip()
+                if exp and not _looks_leaked(exp):
+                    cleaned.append((original, exp))
+                else:
+                    cleaned.append((original, original))
+            mapping = dict(cleaned)
+            extraction = dict(extraction)
+            extraction["gotchas"] = [mapping.get(g, g) for g in gotchas]
+    except Exception:
+        pass  # never let enrichment break the pipeline
+    return extraction
+
+
+def build_skill_md(extraction: dict) -> str:
+    """Assemble a transferable SKILL.md from the structured extraction."""
+    themes = extraction.get("themes", []) or []
+    problem = _infer_problem(extraction)
+    title = _title_from_themes(themes, problem)
+    name = _slugify(title)
+    description = _build_description(extraction, problem)
+
+    tags = ", ".join(themes) if themes else "debugging, problem-solving"
+
+    md = f"""---
+name: {name}
+description: {description}
+---
+
+# {title}
+
+## When this applies
+
+{problem} Use the procedure below when you hit this class of problem, especially
+if the symptoms match the gotchas section — that is where this skill earns its
+place over solving from scratch.
+
+## What does NOT work (and why)
+
+{_approaches_block(extraction)}
+
+## What works
+
+{_breakthrough_block(extraction)}
+
+## Gotchas (read this first)
+
+{_gotchas_block(extraction)}
+
+## Transferable principles
+
+{_principles_block(extraction)}
+
+## Tags
+
+{tags}
+"""
+    return md
+
+
+# Backwards-compatible section check used by extract.py's validator
+SKILL_SECTIONS = (
+    "When this applies",
+    "What does NOT work",
+    "What works",
+    "Gotchas",
+    "Transferable principles",
+    "Tags",
+)
+
+
+if __name__ == "__main__":
+    sample = {
+        "themes": ["graph theory", "dynamic programming"],
+        "approaches_tried": [
+            {"approach": "naive recursion", "why_it_failed": "recomputes the same subgraphs exponentially"},
+            {"approach": "BFS from each node", "why_it_failed": "O(V^2) blew the time limit on dense graphs"},
+        ],
+        "dead_ends": [
+            {"position": 0.3, "what_happened": "recursion stack overflowed on the big case"},
+        ],
+        "breakthroughs": [
+            {"position": 0.85, "what_worked": "memoized the subgraph results keyed by visited-set bitmask"},
+        ],
+        "gotchas": [
+            "the bitmask must include the start node or you double-count paths",
+            "Python recursion limit hits before the logic is wrong, so raise it early to see the real bug",
+        ],
+        "sentiment_arc": {"start": "frustrated", "end": "resolved"},
+    }
+    print(build_skill_md(sample))

skill_uplift_eval.py

@@ -0,0 +1,184 @@
+"""
+Skill-Uplift Eval: does a generated SKILL.md help a model on a held-out task?
+
+Honest measurement of the judge's bar. The harness is model-agnostic: you provide
+two callables,
+    answerer(prompt) -> str      # the model being helped (e.g. a frontier model)
+    grader(prompt)   -> str      # a separate model that scores, BLIND
+and a list of EvalCase (session extraction + a DISTINCT held-out task + a rubric).
+
+Pipeline (mirrors the groundedness eval's discipline):
+  1. Build the SKILL.md from each session's extraction (the real generator).
+  2. Disqualify any skill that leaks the eval task's answer (anti-circularity).
+  3. For each case, get TWO answers from the SAME model: no-skill and with-skill.
+  4. SAVE all raw generations to disk BEFORE scoring (no post-hoc massaging).
+  5. Grade BLIND: answers handed to the grader in randomized order, labels stripped.
+  6. Run a human-labeled CALIBRATION check first; report grader agreement.
+  7. Report per-task scores, uplift, win/tie/loss, baseline headroom, calibration.
+
+Nothing here is rigged toward a positive result; a near-zero or negative uplift is
+a valid, reportable outcome.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import re
+from dataclasses import dataclass, field
+from typing import Callable
+
+# Import the REAL skill generator so we eval what actually ships.
+# (adjust path to your repo when running)
+try:
+    from skill_builder import build_skill_md  # type: ignore
+except Exception:
+    build_skill_md = None  # the harness will error clearly if not wired up
+
+
+@dataclass
+class EvalCase:
+    name: str
+    session_extraction: dict      # the session the skill is built FROM
+    task_prompt: str              # a DISTINCT held-out task in the same class
+    answer_key_terms: list[str]   # terms a correct answer should contain (rubric aid)
+    leak_terms: list[str]         # if the SKILL.md contains these, it leaked the answer
+
+
+@dataclass
+class CaseResult:
+    name: str
+    skill_md: str
+    no_skill_answer: str
+    with_skill_answer: str
+    no_skill_score: float
+    with_skill_score: float
+    leaked: bool
+    grader_raw: dict = field(default_factory=dict)
+
+
+GRADER_SYSTEM = (
+    "You are a strict, impartial grader. You will see a TASK and two candidate "
+    "ANSWERS labeled X and Y, in random order. Score each answer from 0.0 to 1.0 "
+    "for how correctly and completely it solves the task. Judge ONLY the answer's "
+    "merit. You do not know how either answer was produced. Return ONLY compact "
+    "JSON: {\"X\": <float>, \"Y\": <float>, \"why\": \"<one sentence>\"}."
+)
+
+
+def _skill_leaks_answer(skill_md: str, leak_terms: list[str]) -> bool:
+    s = skill_md.lower()
+    return any(t.lower() in s for t in leak_terms)
+
+
+def _grade_blind(grader: Callable[[str], str], task: str,
+                 ans_a: str, ans_b: str, rng: random.Random) -> tuple[float, float, dict]:
+    """Hand the grader the two answers in random order with neutral labels."""
+    swap = rng.random() < 0.5
+    first, second = (ans_b, ans_a) if swap else (ans_a, ans_b)
+    prompt = (
+        f"{GRADER_SYSTEM}\n\nTASK:\n{task}\n\n"
+        f"ANSWER X:\n{first}\n\nANSWER Y:\n{second}\n\nJSON:"
+    )
+    raw = grader(prompt)
+    try:
+        m = re.search(r"\{.*\}", raw, re.DOTALL)
+        obj = json.loads(m.group(0)) if m else {}
+        x = float(obj.get("X", 0.0)); y = float(obj.get("Y", 0.0))
+    except Exception:
+        x, y = 0.0, 0.0
+        obj = {"parse_error": raw[:200]}
+    # unswap back to (a=no_skill, b=with_skill)
+    a_score, b_score = (y, x) if swap else (x, y)
+    return a_score, b_score, obj
+
+
+def run_eval(cases: list[EvalCase],
+             answerer: Callable[[str], str],
+             grader: Callable[[str], str],
+             out_dir: str = "./skill_eval_runs",
+             seed: int = 0) -> dict:
+    if build_skill_md is None:
+        raise RuntimeError("skill_builder.build_skill_md not importable; run from the repo.")
+    os.makedirs(out_dir, exist_ok=True)
+    rng = random.Random(seed)
+    results: list[CaseResult] = []
+
+    for case in cases:
+        skill_md = build_skill_md(case.session_extraction)
+        leaked = _skill_leaks_answer(skill_md, case.leak_terms)
+
+        no_skill_prompt = case.task_prompt
+        with_skill_prompt = (
+            f"You have access to a skill document that may help.\n\n"
+            f"--- SKILL.md ---\n{skill_md}\n--- end SKILL.md ---\n\n"
+            f"TASK:\n{case.task_prompt}"
+        )
+        ans_no = answerer(no_skill_prompt)
+        ans_yes = answerer(with_skill_prompt)
+
+        # SAVE raw BEFORE grading
+        with open(os.path.join(out_dir, f"{case.name}.json"), "w") as f:
+            json.dump({"skill_md": skill_md, "leaked": leaked,
+                       "no_skill_answer": ans_no, "with_skill_answer": ans_yes,
+                       "task": case.task_prompt}, f, indent=2)
+
+        # leaked skills are scored but FLAGGED and excluded from headline uplift
+        a_score, b_score, graw = _grade_blind(grader, case.task_prompt, ans_no, ans_yes, rng)
+        results.append(CaseResult(case.name, skill_md, ans_no, ans_yes,
+                                  a_score, b_score, leaked, graw))
+
+    # ---- aggregate, EXCLUDING leaked skills from the headline number ----
+    clean = [r for r in results if not r.leaked]
+    leaked_n = sum(1 for r in results if r.leaked)
+    if clean:
+        mean_no = sum(r.no_skill_score for r in clean) / len(clean)
+        mean_yes = sum(r.with_skill_score for r in clean) / len(clean)
+        wins = sum(1 for r in clean if r.with_skill_score > r.no_skill_score + 1e-6)
+        ties = sum(1 for r in clean if abs(r.with_skill_score - r.no_skill_score) <= 1e-6)
+        losses = sum(1 for r in clean if r.with_skill_score < r.no_skill_score - 1e-6)
+    else:
+        mean_no = mean_yes = 0.0; wins = ties = losses = 0
+
+    report = {
+        "n_total": len(results),
+        "n_leaked_excluded": leaked_n,
+        "n_scored": len(clean),
+        "baseline_no_skill_mean": round(mean_no, 3),
+        "with_skill_mean": round(mean_yes, 3),
+        "uplift": round(mean_yes - mean_no, 3),
+        "wins": wins, "ties": ties, "losses": losses,
+        "per_case": [
+            {"name": r.name, "no_skill": round(r.no_skill_score, 3),
+             "with_skill": round(r.with_skill_score, 3),
+             "delta": round(r.with_skill_score - r.no_skill_score, 3),
+             "leaked": r.leaked}
+            for r in results
+        ],
+        "raw_saved_to": out_dir,
+    }
+    with open(os.path.join(out_dir, "_report.json"), "w") as f:
+        json.dump(report, f, indent=2)
+    return report
+
+
+# ---- calibration: check the blind grader agrees with human labels ----
+def run_calibration(grader: Callable[[str], str],
+                    labeled: list[dict], seed: int = 0) -> dict:
+    """labeled: [{task, better_answer, worse_answer}] where humans judged which is
+    better. We check the grader scores the human-better one higher. Reports
+    agreement BEFORE any uplift number is trusted (like the groundedness 5/6 block).
+    """
+    rng = random.Random(seed)
+    agree = 0
+    rows = []
+    for item in labeled:
+        a, b, graw = _grade_blind(grader, item["task"],
+                                  item["worse_answer"], item["better_answer"], rng)
+        # a=worse, b=better -> agreement means b_score > a_score
+        ok = b > a
+        agree += int(ok)
+        rows.append({"task": item["task"][:50], "worse": round(a, 3),
+                     "better": round(b, 3), "agree": ok})
+    return {"agreement": f"{agree}/{len(labeled)}", "rows": rows}

tests/test_app.py

@@ -0,0 +1,15 @@
+"""Smoke tests for the TurboSkillSlug app."""
+
+from __future__ import annotations
+
+import importlib
+
+import gradio as gr
+
+
+def test_interface_exists() -> None:
+    """The app module exposes a Gradio Blocks interface."""
+    app = importlib.import_module("app")
+
+    assert hasattr(app, "interface")
+    assert isinstance(app.interface, gr.Blocks)

tests/test_extract.py

@@ -0,0 +1,61 @@
+"""Tests for session extraction utilities."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+from extract import EXPECTED_KEYS, MODEL_NAME, SYSTEM_PROMPT, extract_session
+
+
+def _sample_payload() -> dict[str, Any]:
+    """Return a complete sample extraction payload."""
+    return {
+        "duration_minutes": 12,
+        "themes": ["scaffolding", "audio"],
+        "approaches_tried": [{"approach": "build a Gradio app", "outcome": "worked"}],
+        "dead_ends": [{"position": 0.4, "what_happened": "pytest was missing"}],
+        "breakthroughs": [{"position": 0.7, "what_worked": "mocked the client"}],
+        "gotchas": ["network access needed approval"],
+        "sentiment_arc": {"start": "curious", "end": "steady"},
+        "skill_md": "# Skill\n\nUse the transcript.",
+        "slug_voice": [
+            "You waited through the install.",
+            "The button found its job.",
+            "The mock kept things tidy.",
+            "The transcript became a map.",
+            "The Space now has a trail.",
+        ],
+    }
+
+
+def test_extract_session_returns_expected_keys() -> None:
+    """The extractor parses chat completion JSON into the expected dict shape."""
+    payload = _sample_payload()
+    response = {
+        "choices": [
+            {
+                "message": {
+                    "content": f"```json\n{json.dumps(payload)}\n```",
+                }
+            }
+        ]
+    }
+
+    with patch("extract.InferenceClient") as client_class:
+        client = MagicMock()
+        client.chat.completions.create.return_value = response
+        client_class.return_value = client
+
+        extraction = extract_session("session transcript")
+
+    assert EXPECTED_KEYS.issubset(extraction.keys())
+    client.chat.completions.create.assert_called_once_with(
+        model=MODEL_NAME,
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": "session transcript"},
+        ],
+        response_format={"type": "json_object"},
+    )

tests/test_transcribe.py

@@ -0,0 +1,28 @@
+"""Tests for audio transcription utilities."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from transcribe import MODEL_NAME, transcribe_audio
+
+
+def test_transcribe_audio_returns_string(tmp_path: Path) -> None:
+    """The transcriber returns transcript text from the InferenceClient."""
+    audio_path = tmp_path / "audio.wav"
+    audio_path.write_bytes(b"fake audio")
+
+    with patch("transcribe.InferenceClient") as client_class:
+        client = MagicMock()
+        client.automatic_speech_recognition.return_value = {"text": "hello slug"}
+        client_class.return_value = client
+
+        transcript = transcribe_audio(str(audio_path))
+
+    assert transcript == "hello slug"
+    assert isinstance(transcript, str)
+    client.automatic_speech_recognition.assert_called_once_with(
+        b"fake audio",
+        model=MODEL_NAME,
+    )

trace_parser.py

@@ -0,0 +1,228 @@
+"""
+Parse agent session logs (Claude Code + Codex CLI JSONL) into a narrative
+transcript the TurboSkillSlug pipeline can read like spoken testimony.
+
+The slug does not need full telemetry. It needs the STORY: what was asked,
+what was tried, what errored (dead ends), what finally worked (breakthrough).
+We render the trace as a first-person narrative so the extraction LoRA and
+voice LoRA treat it exactly like an audio transcript.
+
+Supports:
+  - Claude Code: ~/.claude/projects/<encoded>/<uuid>.jsonl
+    Each line: {"type": "user"|"assistant"|"tool_use"|"tool_result"|"system",
+                "message": {"content": str | [content blocks]}, ...}
+  - Codex CLI: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
+    Each line is a typed event (message, tool call, command output, patch).
+    Multiple schema versions handled defensively.
+
+Usage:
+  from trace_parser import parse_trace_to_transcript
+  text = parse_trace_to_transcript(jsonl_string)   # feed to existing pipeline
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+# Tool-result text that signals an error / dead end
+ERROR_MARKERS = (
+    "error", "failed", "exception", "traceback", "not found", "cannot",
+    "denied", "refused", "timeout", "timed out", "exit code 1", "exit status 1",
+    "no such file", "undefined", "is not defined", "syntaxerror", "typeerror",
+    "modulenotfound", "command not found", "fatal", "panic",
+)
+
+# Tool-result / message text that signals success / breakthrough
+SUCCESS_MARKERS = (
+    "passed", "success", "all tests pass", "tests passed", "ok", "done",
+    "fixed", "resolved", "works now", "working", "0 failed", "exit code 0",
+    "build succeeded", "compiled", "no errors",
+)
+
+
+def _content_to_text(content: Any) -> str:
+    """Flatten Claude/Codex message content (str or list of blocks) to text."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, dict):
+                # Claude content blocks: {"type": "text", "text": ...}
+                # tool_use: {"type":"tool_use","name":...,"input":...}
+                # tool_result: {"type":"tool_result","content":...}
+                if block.get("type") == "text" and "text" in block:
+                    parts.append(str(block["text"]))
+                elif block.get("type") == "tool_use":
+                    name = block.get("name", "a tool")
+                    cmd = ""
+                    inp = block.get("input", {})
+                    if isinstance(inp, dict):
+                        cmd = inp.get("command") or inp.get("file_path") or inp.get("path") or ""
+                    parts.append(f"[ran {name} {cmd}]".strip())
+                elif block.get("type") == "tool_result":
+                    inner = block.get("content", "")
+                    parts.append(_content_to_text(inner))
+                elif "text" in block:
+                    parts.append(str(block["text"]))
+            elif isinstance(block, str):
+                parts.append(block)
+        return " ".join(p for p in parts if p)
+    if isinstance(content, dict):
+        return _content_to_text(content.get("content", "")) or str(content.get("text", ""))
+    return ""
+
+
+def _classify(text: str) -> str:
+    """Tag a tool result as error, success, or neutral."""
+    low = text.lower()
+    if any(m in low for m in ERROR_MARKERS):
+        return "error"
+    if any(m in low for m in SUCCESS_MARKERS):
+        return "success"
+    return "neutral"
+
+
+def _iter_events(jsonl_string: str):
+    """Yield parsed JSON objects from a JSONL string, skipping bad lines."""
+    for line in jsonl_string.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            yield json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+
+def _blocks_contain(content: Any, block_type: str) -> bool:
+    """True if content is a list containing a block of the given type."""
+    if isinstance(content, list):
+        return any(
+            isinstance(b, dict) and b.get("type") == block_type for b in content
+        )
+    return False
+
+
+def _extract_role_and_text(event: dict) -> tuple[str, str]:
+    """Return (role, text) from one event across Claude + Codex schemas."""
+    etype = event.get("type", "")
+
+    # Claude Code shape: message under "message"
+    msg = event.get("message")
+    if isinstance(msg, dict):
+        content = msg.get("content", "")
+        text = _content_to_text(content)
+        # Claude wraps tool results in a role="user" message — detect by block
+        # type, not role, so they are classified as results not user turns.
+        if _blocks_contain(content, "tool_result"):
+            return "tool_result", text
+        if _blocks_contain(content, "tool_use"):
+            return "tool_use", text
+        return msg.get("role", etype), text
+
+    # Codex shapes: several versions
+    # newer: {"type":"message","role":...,"content":[...]}
+    if etype == "message" and "content" in event:
+        return event.get("role", "assistant"), _content_to_text(event["content"])
+    # tool/command events
+    if etype in ("function_call", "tool_call", "local_shell_call", "exec"):
+        name = event.get("name") or event.get("tool") or "command"
+        args = event.get("arguments") or event.get("input") or event.get("command") or ""
+        if isinstance(args, (dict, list)):
+            args = _content_to_text(args)
+        return "tool_use", f"[ran {name} {args}]".strip()
+    if etype in ("function_call_output", "tool_result", "exec_output", "command_output"):
+        out = event.get("output") or event.get("content") or event.get("result") or ""
+        return "tool_result", _content_to_text(out) if not isinstance(out, str) else out
+    # generic fallback
+    if "content" in event:
+        return event.get("role", etype or "system"), _content_to_text(event["content"])
+    if "text" in event:
+        return etype or "system", str(event["text"])
+
+    return "", ""
+
+
+def parse_trace_to_transcript(jsonl_string: str, max_chars: int = 6000) -> str:
+    """
+    Convert an agent session JSONL trace into a first-person narrative the
+    slug can witness. Errors become dead ends, successes become breakthroughs.
+    """
+    lines: list[str] = []
+    n_errors = 0
+    n_success = 0
+    n_tools = 0
+    first_ask = None
+
+    for event in _iter_events(jsonl_string):
+        role, text = _extract_role_and_text(event)
+        text = (text or "").strip()
+        if not text or len(text) < 3:
+            continue
+        # Trim very long tool dumps to their first informative chunk
+        if len(text) > 400:
+            text = text[:400].rsplit(" ", 1)[0] + " ..."
+
+        if role in ("user",) and first_ask is None:
+            first_ask = text
+            lines.append(f"I started by asking the agent: {text}")
+        elif role in ("user",):
+            lines.append(f"Then I told it: {text}")
+        elif role in ("assistant",):
+            lines.append(f"The agent said: {text}")
+        elif role in ("tool_use",):
+            n_tools += 1
+            lines.append(text)  # already "[ran X ...]"
+        elif role in ("tool_result",):
+            kind = _classify(text)
+            if kind == "error":
+                n_errors += 1
+                lines.append(f"That failed: {text}")
+            elif kind == "success":
+                n_success += 1
+                lines.append(f"That worked: {text}")
+            else:
+                lines.append(f"It returned: {text}")
+        # skip system events
+
+    if not lines:
+        return ""
+
+    # Frame the narrative so the extraction model reads dead ends / breakthroughs
+    header = (
+        "This is a recording of a coding session I worked through with an AI "
+        "agent. Here is what happened, start to finish.\n\n"
+    )
+    body = " ".join(lines)
+    footer = (
+        f"\n\nOver the session there were {n_errors} failures, {n_success} "
+        f"successes, and {n_tools} tool runs. "
+    )
+    if n_errors > n_success:
+        footer += "It was a grind with a lot of dead ends."
+    elif n_success > 0 and n_errors == 0:
+        footer += "It went smoothly start to finish."
+    elif n_success > 0:
+        footer += "After the failures, it finally came together."
+
+    transcript = header + body + footer
+    if len(transcript) > max_chars:
+        # Keep the head (the ask + early attempts) and the tail (the resolution)
+        head = transcript[: max_chars // 2]
+        tail = transcript[-max_chars // 2 :]
+        transcript = head + " ... " + tail
+    return transcript
+
+
+def detect_trace_format(jsonl_string: str) -> str:
+    """Best-effort label of the trace source for display. 'claude', 'codex', or 'unknown'."""
+    for event in _iter_events(jsonl_string):
+        if isinstance(event.get("message"), dict):
+            return "claude"
+        if event.get("type") in ("function_call", "local_shell_call", "exec",
+                                  "function_call_output", "exec_output"):
+            return "codex"
+    return "unknown"

transcribe.py

@@ -0,0 +1,46 @@
+"""Transcription via Whisper on Modal."""
+
+import base64
+import os
+from pathlib import Path
+
+import httpx
+
+
+WHISPER_URL = os.environ.get(
+    "MODAL_WHISPER_URL",
+    "https://anubhavbharadwaaj--slugvoice-whisper-whisperserver-api.modal.run",
+)
+_HERE = Path(__file__).resolve().parent
+_SAMPLE_AUDIO = _HERE / "sample_session.wav"
+
+
+def _resolve_audio_path(audio_path: str) -> Path:
+    """Return a stable audio path, tolerating evicted Gradio example temp files."""
+    path = Path(audio_path)
+    if path.exists():
+        return path
+
+    name = path.name.lower()
+    if name.startswith("sample_session") and _SAMPLE_AUDIO.exists():
+        return _SAMPLE_AUDIO
+
+    raise FileNotFoundError(
+        f"Audio file is no longer available: {audio_path}. "
+        "Please re-upload the file and try again."
+    )
+
+
+def transcribe_audio(audio_path: str) -> str:
+    """Transcribe audio using Whisper on Modal."""
+    resolved_path = _resolve_audio_path(audio_path)
+    with open(resolved_path, "rb") as f:
+        audio_b64 = base64.b64encode(f.read()).decode()
+
+    resp = httpx.post(
+        WHISPER_URL,
+        json={"audio": audio_b64},
+        timeout=120,
+    )
+    resp.raise_for_status()
+    return resp.json()["text"]