# Vocabulary — the named pedagogical primitives

The house-invented structures the LLM composes with. **This file is data, not law.** Each primitive's own properties (purpose, when it's required, where it goes) live here once; the laws in `laws.md` enforce *conformance* to these records — they never redefine a primitive. Counts and time costs live in `levers.json`, referenced by name, not repeated here.

A primitive's `id` (its name) is the stable cross-reference used everywhere.

---

## 1. Content types

The three kinds a journey can be. Each fixes a CPA rule and a difficulty ceiling (enforced by `R-BLU-03`, `R-BLU-13`; numbers in `lever:blueprint.*`).

| id | Structure | CPA rule | Difficulty ceiling |
|---|---|---|---|
| **Learn** | Full CPA progression. Definition/formula locked in. Worked examples before student practice. | full C → P → A | caps at `variation` (do not reach combination) |
| **Practice** | Begins Pictorial or Abstract; escalating difficulty; synthesis with prior learning. Waning-scaffold template. | may begin Pictorial, **must** reach Abstract | must reach `combination` + `transfer` |
| **Challenge** | Transfer + extension; non-routine problems; minimal scaffolding. Socratic time-boxed template. | abbreviated | reaches `transfer` |

---

## 2. Journey sections — the delivery arc

Ordered. A journey traverses these in order (`R-BLU-01`). Screen-count guidance is soft; time cost is `lever:time.role_minutes_table`.

| # | id | Purpose | Notable contents |
|---|---|---|---|
| 1 | **Activate** | Prerequisite activation — surface prior knowledge, flag gaps | 1–3 screens |
| 2 | **Teach** | Introduce the concept, Concrete then Pictorial | Math_Vault lands here |
| 3 | **Get** | Worked examples, C → P → A progression | fading worked examples |
| 4 | **Ask** | Students practice; may embed an applet or video | Math_Trap lands here |
| 5 | **Review** | Consolidate; active recall | Snapshot, Shout_Out_Loud |
| 6 | **Consolidate** | Real-world grounding + verification | Math_World, Exit_Question |

---

## 3. The seven tropes

Named instructional moves. Each carries: **purpose**, **required-when**, **position_rule**, **setup_reveal** (whether it is a two-screen setup→reveal pair — a hard invariant under `R-BLU-02`), and **compile_key** (where the deterministic pass looks). Minimum instance counts are `lever:blueprint.trope_minimum_requirements`.

| id | Purpose | Required when | Position | setup_reveal | compile_key |
|---|---|---|---|---|---|
| **Snapshot** | Visual anchor — "see it". One durable image of the concept. | every new/unique idea in the journey | after concept introduced, before worked examples; also on every applet/video consolidation screen | no | `trope_map.snapshots` (tag) |
| **Math_Vault** | Permanent deposit — "lock it in". Definition/formula/procedure in formal language. | every newly-introduced definition, formula, or procedure | Teach, after concrete demonstration | no | `trope_map.math_vaults` (tag) |
| **Math_Trap** | Misconception confrontation — "don't get fooled". Shows the wrong path, then corrects. | every high-severity misconception in the research synthesis | Ask, before/during practice; one per major misconception | **yes** | `trope_map.math_traps` |
| **Shout_Out_Loud** | Active recall + energy — "say it together". Whole-class choral response. | wherever classroom engagement is possible | Review, after knowledge established | no | `trope_map.shout_out_louds` (tag) |
| **Math_Twist** | Cognitive surprise — "think deeper". A counter-intuitive-but-correct result, OR the moment an everyday false-friend word is displaced by its formal meaning. Distinct from Math_Trap (a Trap confronts a *wrong* path; a Twist reveals a deeper *correct* one). | when the synthesis has a twist candidate (VIR `surprise_factor ≥ 3`, or a false-friend with `confusion_risk ∈ {medium, high}`). Exactly ONE per journey, highest-priority candidate. | screen-pair: setup elicits commitment, reveal displaces the framing; at the moment formal vocabulary first meets its everyday false-friend, or where the counter-intuitive visual first appears | **yes** | `trope_map.math_twists` (never merge with math_traps) |
| **Math_World** | Real-world grounding — "find it in your world". Authentic context. | to consolidate journey learnings for the age group | Consolidate, near end | no | `trope_map.math_worlds` (tag) |
| **Exit_Question** | Understanding verification — "prove you got it". One diagnostic. | ≥1 per journey (may be served by an applet) | final screen or final applet screen | no | `trope_map.exit_questions` |

**Cost note (for pacing, `R-BLU`/levers):** Snapshot, Math_Vault, Shout_Out_Loud are semantic *tags* on existing screens — zero time cost. Only Math_Trap / Math_Twist as a screen-pair (`trope_setup` + `trope_reveal`) or as a trope-applet add time.

---

## 4. Applet six stages

Ordered arc of an applet (`R-BLU-11`). Its scaffolding reduces across stages (`R-BLU-04`).

| # | id | Purpose |
|---|---|---|
| 1 | **Launch** | Why this matters, what to explore. Context + curiosity, no instruction yet. |
| 2 | **Explore** | Encounter the phenomenon through interaction. Scaffolded; help without revealing. |
| 3 | **Notice** | Pattern recognition — the invariant structure surfaces through designed interaction. |
| 4 | **Explain** | Name the pattern; student articulates the principle in their own words. |
| 5 | **Apply** | Test in new contexts. Transfer; scaffolding reduced. |
| 6 | **Consolidate** | Summarize, connect to journey LO, preview what follows. |

---

## 5. Pedagogy-structure templates

Attached to Practice and Challenge journeys (`R-CHP-14` requires the field; shapes here). Minute windows reference `lever:time.journey_budget_minutes`.

### Waning Scaffold (Practice)
Four phases, scaffolding fades across them (`R-BLU-04` applies):
1. **I-do** — `scaffold: full`
2. **We-do** — `scaffold: high`
3. **You-do (fading)** — `scaffold: fading`
4. **You-do (independent)** — `scaffold: none`
Plus `scaffold_artefacts[]` — the actual hint/reference cards used.

### Socratic Time-Boxed (Challenge)
- `driving_question` — one substantial question the student has no ready path to.
- `sub_prompts[]` — 5 entries, each `{window, prompt, expected_move, reveal}`, each in a hard time window.
- `takeaway_question` — unanswered, take-home, no time box.
- `transition_cadence` — the reveal-and-jump rhythm.

---

## 6. Screen roles

The canonical role taxonomy. A screen's `asset_context_role` is assigned **deterministically by the compile pass, not the LLM** — sourced from applet/video placements, `screen.tropes`, and section. Named here so laws and the compiler share one vocabulary.

`content` (default) · `worked_example` · `summary` · `exit_question` ·
`applet_context` · `applet_placeholder` · `applet_consolidation` ·
`video_context` · `video_placeholder` · `video_consolidation` ·
`trope_setup` · `trope_reveal` · `trope_applet_placeholder`

**Placeholder screens** (`*_placeholder`) are developer briefs, not student copy — several laws (`R-BLU-07`, and any style/density rule) suspend on them by declaration.