# Neural Forge — Spaced-Repetition Card Decks

Each module ships a deck at `cards/m{NN}.json`. The hub renders a daily review
queue at [`tools/cards.html`](../tools/cards.html) (shipped externally by
coder run 14 **E27**); this folder ships the *content*, the renderer reads
and grades it.

## Schema

```json
{
  "module": "m01",
  "version": 1,
  "cards": [
    {
      "id": "m01-c01",
      "front": "What does the Cauchy-Schwarz inequality say about |u.v|?",
      "back":  "|u.v| <= ||u||*||v||, with equality iff u and v are linearly dependent.",
      "claim": "cs",
      "difficulty": "medium"
    }
  ]
}
```

### Fields

- `module` — the module slug (`m{NN}`). Must match the deck filename.
- `version` — integer; bump when a card's `front`/`back` text changes materially
  (the spaced-repetition state may need to reset to avoid drilling a different
  question with the student's prior answer history).
- `cards` — array of card objects:
  - `id` — `m{NN}-c{KK}` where `{KK}` is zero-padded two-digit (`c01`, `c02`, ...).
  - `front` — the question or prompt the student sees.
  - `back` — the answer or full derivation snippet.
  - `claim` — the prove-list claim slug this card reinforces (see FRAMEWORK
    §11 reserved slugs). May be `null` for "drill" cards that exercise
    mechanical computation without claiming a proof.
  - `difficulty` — `"easy"` | `"medium"` | `"hard"`. Seeds the
    spaced-repetition algorithm's initial interval: easy → 4 days,
    medium → 2 days, hard → 1 day.

## Authoring rule (rigor-side)

Every claim a module asserts in its `<ul class="prove-list">` should be
reinforced by at least one card in the deck. That way the spaced-repetition
loop and the rigor coverage metric reinforce the same set of identities —
the student doesn't tick a claim once and lose it; the deck brings it back
two days later.

Drill cards (no `claim`) are allowed and encouraged for mechanical
computations (norm of (3,4), self-cosine, etc.) — they reinforce intuition
without claiming a proof.

## Storage of student review state

The renderer at `tools/cards.html` (coder **E27**, shipped run 14)
persists per-card review state under the top-level localStorage key
`forge.state`, nested at `state.cards.m{NN}[card.id]`. Each per-card
record has shape:

```
{ last_reviewed: <epoch ms>, next_due: <epoch ms>, ease: <float 1.3..2.5>, streak: <int> }
```

This sits alongside `state.labs[labId]` (E1, coder; also nested under
`forge.state`) and as a sibling rigor signal to the top-level keys
`forge.prove.m{NN}` (D23, rigor) and `forge.pretest.m{NN}` (D6, rigor).

**Persistence-key divergence note (rigor D65, 2026-05-13):** the cards
renderer chose to nest under `forge.state` for single-write-key
efficiency; prove-list ticking and pre-test diagnostics keep separate
top-level keys. The four signals together power the AI tutor's
per-student calibration (cross-ref **D25**, **D63**). See FRAMEWORK §7
(data contract) once that section is rebuilt — cross-ref **coherency
C24**.

## Cross-references

- **Rigor D7** — the parent direction logged on `course-worker-rigor.md`.
- **Rigor D23** — `prove.m{NN}` ticking state the cards reinforce.
- **Rigor D65** — the run-20 truth-up that aligned this README's storage
  schema with the shipped `tools/cards.html` implementation.
- **Coder E1 / E17 / E27** — the lab-state schema precedent (E1, E17)
  and the now-shipped renderer at `tools/cards.html` (E27, run 14).
- **Coherency C24** — the truncation crisis that motivated creating this
  spec in a new directory rather than appending it to FRAMEWORK §11.

## Files

- `cards/README.md` — this file (the convention).
- `cards/m{NN}.json` — per-module deck content. Today only `cards/m01.json`
  exists.