Make the running game pedagogy-first: lesson cards, spaced retry, Codex, and sound

.agents/skills/codequest-game-designer/SKILL.md

@@ -222,11 +222,75 @@ behaviors; the manifest can reorder or reuse them but cannot define arbitrary
 code or create a new renderer. Typed art templates select only renderers shipped
 with CODE QUEST; mechanics and template-less art remain validated design
 metadata. Schema v1 remains compatible metadata and uses the built-in flow.
+Sound follows the trusted handler rather than the manifest: classify an
+implemented cue as Implemented with its audio test as evidence, and its
+`art.kind = "audio"` entry as Configured/metadata.
 
 When the desired game type is unsupported, finish the design brief but do not
 put an invalid type in `CODEQUEST.toml`. Explain the runtime gap and propose the
 smallest schema/engine increment needed before authoring that manifest change.
 
+### 8. Build on the runtime learning mechanisms
+
+In the CODE QUEST engine repository, quiz cartridges already provide these
+mechanisms. Reuse them before proposing new ones, and cite them as evidence in
+the pedagogy map and runtime traceability:
+
+- Concept lenses: every generated question names one of five lenses
+  (`learning::Concept`: purpose, responsibility, interaction, invariant,
+  tradeoff) and carries a rationale for every choice (payload v2 in
+  `questions.rs`). A question without a known lens, with a missing or overlong
+  rationale, or with other mechanical failures (length, non-ASCII text) gets
+  one bounded repair call through the same provider when the batch falls
+  short, and is dropped only if that repair fails. Location-citing, trivia,
+  and malformed questions are dropped immediately.
+- Lesson card: after commitment the `concept-quiz` handler replaces the
+  choices with the committed pick's rationale (the misconception) and then the
+  answer's rationale, holds input for 45 ticks, and waits for A or Start.
+- Shuffled choices: `learning::presentation_order` gives each question a stable
+  order and moves every choice on each retry, so answer position is never a
+  cue.
+- Spaced retry: a survivable miss inserts a review copy after exactly three
+  other questions (`RETRY_GAP`), carrying into the next batch when the current
+  one ends sooner. A correct same-launch retry is relearning
+  (`learning::Review::InSession`); only a correct answer when the miss returns
+  in a later launch (`Review::Spaced`) is a redemption.
+- Lens mastery: evidence (first-try successes plus redemptions) wakes three
+  runes per lens at 1, 3, and 5 (`learning::MASTERY_THRESHOLDS`); rune II also
+  needs 60% and rune III 80% of the newest five graded outcomes correct, and
+  rune III no pending review (`LensRecord::stage_with`). Gated runes draw
+  cracked. The save retires first-try and spaced successes, keeps misses and
+  relearned questions queued across launches, and stores mastery per cartridge.
+- Oracle Codex: the `codex` handler, reached through the quiz menu's
+  `open-codex` signal and drawn by the `oracle-codex` template, shows lens
+  mastery with pending-review counts and rereads every lesson. Pending lessons
+  are self-tests: the player's wrong pick and its misconception show, the
+  answer stays sealed until A, and a redemption after a reveal counts as
+  relearning rather than evidence.
+- Difficulty as concept depth: `Concept::focus_for_level` sets each level's
+  focus lenses, level 4+ requests PREDICT transfer questions, and each request
+  names the player's weakest lens and earlier stems. These are prompt-level
+  requirements; acceptance does not enforce the focus share or the PREDICT
+  count.
+- Reduced motion: the engine follows the system's reduced-motion preference by
+  freezing decorative motion while keeping scene timing, input, and data.
+- Screen transcript: `engine/transcript.rs` derives plain-language sentences
+  from the same state the renderers use and publishes them through
+  `engine_transcript` into a visually hidden, polite `aria-live` region
+  (`src/index.html`). It is republished only when its words change: a new
+  screen is read whole, then only in-screen changes such as focus moves, and
+  decorative motion is never announced. A new scene or handler needs
+  transcript sentences, which is proposed engine work that the manifest cannot
+  configure.
+- Oracle line: while generation waits, the Oracle's second header line names
+  a failed request's category with a retry countdown, or recalls journal
+  lessons (outstanding misses first) as retrieval practice that records no
+  evidence.
+
+When a design needs different thresholds, gaps, or feedback, name the constant
+or handler that would change and classify it as proposed engine work; the
+manifest cannot configure these values.
+
 ## Produce the artifacts
 
 Create or revise:
@@ -241,10 +305,15 @@ production status, and implementation gaps; the manifest is the stable graph
 the engine can validate. Preserve unrelated existing design decisions and show
 material changes clearly.
 
-When the runtime contract has no dedicated sound schema, retain sound needs as
-referenced production entries (for example `art.kind = "audio"`) instead of
-inventing fields. State plainly that metadata does not play audio. Do not use a
-visual `template` name to imply sound playback.
+The runtime contract has no sound schema and no audio `template` value, so
+retain sound needs as referenced production entries (for example
+`art.kind = "audio"`) instead of inventing fields. In the CODE QUEST engine,
+sound is engine-owned: the audio director in `src-tauri/src/audio.rs` diffs a
+per-tick state snapshot and derives cues and scene loops for each trusted
+handler, so an audio entry is the requirement the director implements, not a
+switch that plays anything. State which ledger cues the director already
+implements and which need engine work. Do not use a visual `template` name to
+imply sound playback.
 
 ## Validate before handoff
 
@@ -270,6 +339,28 @@ CQA_VISUAL_PREVIEW_DIR=/tmp/codequest-previews \
   oracle_templates_produce_nine_distinct_native_scene_frames --lib
 ```
 
+That test writes every reachable Oracle scene, including the Codex mastery,
+sealed-lesson, and lesson layouts, despite its historical name. Lesson-card states come from
+`lesson_cards_render_the_misconception_and_the_answer`. The menu-to-Codex route
+and the remaining Codex states come from
+`dogfood_manifest_routes_its_menu_into_the_templated_codex`,
+`empty_codex_says_no_lessons_yet_and_cannot_page`, and
+`codex_lesson_pages_show_the_answer_and_mark_outstanding_reviews`. The quiz
+header's batch progress, `RETRY` label, and `BACK IN` note come from
+`the_header_counts_the_batch_and_labels_the_returning_retry`; the lens-rune
+wake banner from `waking_a_lens_rune_banners_blinks_and_sounds_above_insight`
+and the legacy footer under it from
+`the_legacy_lesson_footer_carries_a_woken_rune_iii_banner_readably`; cracked
+mastery runes from
+`codex_mastery_runes_crack_at_the_exact_gate_breakpoints_on_the_rendered_frame`
+and `the_lesson_footer_meter_shows_a_cracked_rune_for_an_open_miss`;
+the Oracle recall and failure line from
+`the_oracle_line_stays_contained_disjoint_and_readable` and
+`recalled_lessons_are_written_in_but_stay_static_under_reduced_motion`; and the
+Ascension and Aftermath learning debriefs from
+`the_result_prompt_stays_lit_on_every_frame`. Run them with the same variable
+when those surfaces change.
+
 When the repository includes `scripts/compile-oracle-assets.sh`, run it before
 the preview test so inspectable PNG sources and embedded runtime buffers cannot
 drift.
@@ -285,7 +376,9 @@ Then perform a traceability pass:
   easiest successful strategy cannot bypass the intended knowledge through
   guessing, superficial pattern matching, or unrelated dexterity.
 - Failure feedback identifies the consequence of the player's misconception
-  and enables an informed retry.
+  and enables an informed retry. In a question-based design, every choice
+  carries a rationale and a miss returns for a spaced retry, or the brief
+  explains why not.
 - Progression increases conceptual independence or complexity, not only speed,
   punishment, health, score, or visual intensity.
 - Every start/transition target resolves and every scene is reachable.

.agents/skills/codequest-game-designer/assets/game-design-brief.md

@@ -51,6 +51,12 @@ without copying the original solution?]
 | Assessment | | | | |
 | Transfer | | | | |
 
+[For a quiz cartridge, cite the runtime mechanisms each stage relies on—concept
+lenses and per-choice rationales, the lesson card, shuffled choices, spaced
+retry and redemption, lens mastery runes, the Oracle Codex, level focus
+lenses, and PREDICT transfer questions—and mark any stage that needs new
+engine work as proposed.]
+
 ## Scene storyboard
 
 | ID | Purpose | Learning role | Entry state | Player actions | State/feedback | Exit and next scenes | Mechanics | Art |
@@ -80,6 +86,12 @@ without copying the original solution?]
 
 ## Sound requirement ledger
 
+[Sound needs are `art.kind = "audio"` entries; the manifest has no sound schema
+or audio template. In the CODE QUEST engine the audio director derives cues and
+scene loops from game state per trusted handler. Describe each cue by the state
+change that triggers it, and record whether the director implements it
+(Implemented, with its audio test) or needs engine work (Needed).]
+
 | ID | Used by scenes | Player-facing purpose | Cues/loops and variants | Constraints and acceptance | Status |
 |---|---|---|---|---|---|
 | `sound-id` | | | | | Needed |
@@ -90,6 +102,9 @@ without copying the original solution?]
 |---|---|---|---|---|---|---|
 | `scene-id` | | | | | | Proposed |
 
+[State the reduced-motion resting composition for any scene whose motion
+carries meaning; the engine freezes decorative motion but not scene timing.]
+
 ## Runtime traceability
 
 | Element | Status | Evidence or required work |

.agents/skills/codequest-game-designer/evals/evals.json

@@ -22,7 +22,14 @@
     {
       "id": 3,
       "prompt": "Our existing quiz storyboard needs an accessibility pass. Add a reduced-motion Oracle state, non-color-only answer feedback, and clearer retry behavior. Preserve existing IDs wherever possible and update both the brief and manifest.",
-      "expected_output": "An incremental, traceable revision that preserves stable IDs, updates mechanics and art requirements, and keeps all manifest references valid.",
+      "expected_output": "An incremental, traceable revision that preserves stable IDs, updates mechanics and art requirements, and keeps all manifest references valid, while recognizing what the engine already provides instead of proposing it again.",
+      "expectations": [
+        "Preserves existing scene, mechanic, and art IDs and keeps the manifest valid under the bundled validator.",
+        "Recognizes that the engine already follows the system reduced-motion preference by freezing decorative motion without changing timing, and specifies the Oracle's resting composition rather than proposing a new setting.",
+        "Recognizes the existing lesson card with -/+ verdict markers and per-choice rationales, and the spaced retry with redemption, and builds on them.",
+        "Recognizes the existing engine screen transcript (a polite live region that reads each screen whole, then its changes) instead of proposing screen-reader support as new work, and names the transcript sentences any new state needs.",
+        "Classifies any remaining gap, such as an in-game reduced-motion toggle, as proposed engine work rather than a manifest field."
+      ],
       "files": []
     },
     {
@@ -34,6 +41,7 @@
         "Finds possible loading, failure, held-input, back, replay, and terminal open states rather than checking reachability alone.",
         "Defines perceptible beginning, middle, and end progression through at least two feedback channels beyond a level number.",
         "Inventories real template assets and does not claim that manifest metadata dynamically loads them unless the repository contract supports it.",
+        "Treats sound as engine-derived from state: audio art entries remain production requirements, implemented cues cite the audio director and its tests, and no sound field or audio template is invented.",
         "Keeps the brief and CODEQUEST.toml valid, linked, and honest about implemented versus proposed work."
       ],
       "files": []
@@ -63,6 +71,19 @@
         "Adds executable evidence at values immediately below, at, and above the declared breakpoints and inspects the final 240x160 composites."
       ],
       "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "Players say the quiz feels like guessing and they forget what they got wrong. Make the Oracle quiz teach better: I want mistakes to explain themselves, missed ideas to come back, and some way to see what I have actually learned. Update the brief and the manifest.",
+      "expected_output": "A pedagogy pass that names the learner, objective, mental model, misconception, evidence, mastery criterion, and transfer task, maps them through a pedagogy map, and builds on the engine's existing learning mechanisms instead of re-proposing them.",
+      "expectations": [
+        "Fills every pedagogy field in the experience frame and a five-stage pedagogy map with evidence and scaffolding per stage.",
+        "Cites the existing lesson card, per-choice rationales, shuffled choices, spaced retry and redemption, lens mastery thresholds, and the Oracle Codex as implemented runtime evidence.",
+        "Routes the menu to the Codex with the codex handler, the open-codex signal, and the oracle-codex template when the manifest lacks that route, and keeps the manifest valid.",
+        "Distinguishes prompt-level requirements such as level focus lenses and PREDICT transfer questions from rules the acceptance policy enforces.",
+        "Proposes any new threshold, retry gap, or mastery state as engine work rather than inventing manifest fields."
+      ],
+      "files": []
     }
   ]
 }

.agents/skills/codequest-game-designer/references/polish.md

@@ -60,6 +60,19 @@ or motion only when the silence/stillness has a purpose and a defined handoff.
 - Ensure entering and exiting frames share a motif or deliberately clear it.
 - Provide a reduced-motion version with equivalent information and duration;
   avoid full-frame flashes as a substitute for impact.
+- In the CODE QUEST engine, reduced motion follows the system preference: the
+  shell forwards `prefers-reduced-motion`, and renderers draw decorative motion
+  from a frozen clock (`motion_ticks`), show settling motions at their end state
+  (`settled_ticks`), and keep blinking prompts lit (`blink_lit`), while scene
+  timing, input, and data use the real clock. Specify the resting composition
+  each scene shows under that freeze, and keep state changes out of the
+  decorative clock so they survive it.
+- In the CODE QUEST engine, screen readers already get every screen in words:
+  `engine/transcript.rs` derives plain-language sentences from renderer state
+  and the shell places them in a polite live region (`engine_transcript`). The
+  transcript is republished only when its words change, a new screen is read
+  whole, and in-screen changes such as focus moves are read on their own.
+  Specify the sentences a new scene or state needs; adding them is engine work.
 
 ### Sound design
 
@@ -73,6 +86,15 @@ or motion only when the silence/stillness has a purpose and a defined handoff.
   fullest arrangement for earned peaks.
 - Specify muted and reduced-audio behavior. Never make sound the only carrier of
   required information.
+- In the CODE QUEST engine, sound is derived from state, like rendering. The
+  audio director (`src-tauri/src/audio.rs`) compares each tick's state snapshot
+  with the previous one and chooses at most one cue per tick by priority, owns
+  each scene's loop and cuts it on the exit tick, and grows the Datafall and
+  reward arrangements by presentation tier; the shell speaker only plays the
+  notes, behind a MUTE/LOW/MID/HIGH volume wheel. Specify each cue as the state
+  change that triggers it, not as a button handler, and record audio tests as
+  evidence. The manifest has no sound schema: audio art entries remain the
+  production requirements, and a new cue or loop is engine work.
 
 ### Mechanical closure
 
@@ -88,6 +110,10 @@ animation whose skip path bypasses required initialization.
 - Give loading, empty, offline/disabled, invalid-data, timeout, and retry states
   honest behavior when they are possible.
 - Make success, failure, back, replay, and abandon paths explicit.
+- Give feedback holds an owned exit. The quiz lesson card ignores input for its
+  45-tick hold and then waits for a fresh A or Start; a reward hold is set by
+  the manifest's `after_ticks` gate, and its prompt appears only when the scene
+  graph would accept the continuation.
 - Verify input-edge behavior across transitions and deterministic state reset on
   new runs.
 - Test graph reachability and event closure; reachability alone is insufficient.
@@ -107,7 +133,9 @@ animation whose skip path bypasses required initialization.
   counts. For each, name the desirable direction, reachable range, breakpoints,
   staged reward or consequence, crossing feedback, cap, and reset. If changing
   the number has no meaningful threshold response, remove it from the HUD or
-  turn it into a real system.
+  turn it into a real system. Include learning metrics that outlive a run: in
+  CODE QUEST quizzes, per-lens mastery runes (1/3/5 evidence) and pending
+  reviews persist per cartridge and never reset with a new run.
 - Test the values immediately below, at, and above every threshold. Include
   decreasing metrics so danger, recovery, and low-value mastery receive staged
   feedback rather than only a terminal zero state.

.agents/skills/codequest-game-designer/references/visual-floor.md

@@ -62,7 +62,10 @@ palette to otherwise sparse geometry.
    High-resolution concept art is not evidence until the 240×160 frame passes.
 8. Compile the PNGs into the runtime format, render every reachable scene, and
    inspect credits, opening stages, title, menus, gameplay, rewards, failure,
-   and replay.
+   and replay. Include the states layered over a shared plate: the quiz lesson
+   card (missed, correct, legacy, and worst-case rationale copy) and both Oracle
+   Codex layouts (mastery over the archive plate, lessons over the trial
+   plate) with empty-journal and missing-rationale states.
 9. Run layout checks on the final native composite with worst-case live strings
    and counters. Fail the build when text or focus exceeds its usable interior,
    any pair of live/static foreground siblings overlaps, a plate ornament enters
@@ -99,6 +102,8 @@ number.
 - Is the brightest/densest region meaningful?
 - Can focus, correctness, and failure change without repainting the source?
 - Does the scene remain legible in grayscale and when audio is muted?
+- Does the resting composition carry every state when reduced motion freezes
+  decorative motion and keeps blinking prompts lit?
 - Do all live bounds remain inside their containers without intersecting other
   foreground content?
 - Is every centered or aligned element positioned relative to its measured art

.agents/skills/codequest-game-designer/scripts/validate_codequest.py

@@ -41,17 +41,19 @@
     "oracle-ascension",
     "oracle-aftermath",
     "oracle-progression",
+    "oracle-codex",
 }
 HANDLER_SIGNALS = {
     "repository-credits": {"continue", "elapsed"},
     "opening-fanfare": {"continue", "elapsed"},
     "title": {"continue"},
-    "quiz-menu": {"new-run", "back"},
+    "quiz-menu": {"new-run", "open-codex", "back"},
     "character-creation": {"hero-ready", "back"},
     "oracle": {"questions-ready", "back"},
     "concept-quiz": {"needs-question", "batch-complete", "hearts-empty", "back"},
     "level-up": {"questions-ready", "needs-question"},
     "game-over": {"replay"},
+    "codex": {"back"},
     "quest-select": {"quest-selected", "back"},
     "battle": {"victory", "defeat"},
     "victory": {"continue"},
@@ -66,6 +68,7 @@
         "concept-quiz",
         "level-up",
         "game-over",
+        "codex",
     },
     "quest": {"quest-select", "battle", "victory", "defeat"},
 }

.gitattributes

@@ -0,0 +1,12 @@
+# Source contracts (Node and Rust tests) parse files with line-sensitive
+# patterns, so every platform checks out text with LF endings.
+* text=auto eol=lf
+
+# Raw framebuffer plates and sprites are embedded byte-for-byte with
+# include_bytes!; never let content sniffing treat them as text.
+*.rgb binary
+*.rgba binary
+*.png binary
+*.ico binary
+*.icns binary
+*.woff2 binary