docs/tutorial-plan.md

# Tutorial / onboarding plan — show off the LLM features, stay out of the way

**Goal:** a first-run tour that makes the *load-bearing AI* obvious — characters are
**generated** (persona + portrait + voice), you can **talk** to them, and you **forge** their
skills with a coding model — while teaching the basic gameplay loop. **Non-intrusive**: contextual
coachmarks that advance as you play, never a forced wall, always skippable, first-time only.

## Design principles
- **Contextual, not modal.** Small callouts anchored to the real control (the joystick, the ⚔
  button, the ☰/C menu, the Forge button), with one line of copy + `Next` / `Skip tour`. The game
  stays fully playable underneath — coachmarks point, they don't block.
- **Advance on action.** Each step completes when the player *does the thing* (moves, kills a foe,
  opens the sheet, forges a skill) — or taps `Next`. We already have the hooks for most of these.
- **First-run only + opt-out.** One friendly opener: "New here? Take a 60-sec tour. [Start] [No
  thanks]." Either choice is remembered (localStorage); it never nags again. A `?` help button +
  a Settings "Replay tutorial" let them re-run it.
- **Sell the magic in-world.** At each generation step the copy leans on *uniqueness + life*
  ("forged anew", "written for them alone", "made real from your words", "their own voice") rather
  than naming the tech. The existing elapsed-time status shows it working. The AI is the star — in
  costume.

## The coachmark engine — `web/tutorial.js` (new)
A tiny, framework-free coach:
- `startTour()` / `resumeTour()` — runs the step list from saved progress.
- A **step** = `{ id, anchor, text, placement, advanceOn, optional }` where `anchor` is a selector
  or a getter for the live element, `advanceOn` is an event name or a predicate, `placement` is
  top/bottom/left/right. Renders a positioned callout (arrow + text + `Next`/`Skip`), repositions on
  resize/scroll, and dims-but-doesn't-block the rest (a soft spotlight).
- **Progress** persisted to `localStorage['tinyarmy.tutorial.v1']` = `{ step, done, dismissed }`,
  so it survives refresh and won't repeat.
- **Event bus**: the tutorial subscribes to gameplay events. tiny.js already exposes the hooks we
  need — `onRosterChange` (hero created), `spawnWithFly` (spawned), `onEnemyDefeated`→`awardKill`
  (kills), the level-up draft, `setSheet` (sheet opened), `openForge`/`forgeSkillForHero` done,
  `openChat` (chat opened). We add a small `tutorialEmit(event)` at those points (one line each) so
  steps advance naturally.

## DECISION (locked): a **guided opt-in tour**, copy in **in-world game terminology**.
Frame the generation as fantasy ("forged anew", "a tale written just for them", "a voice all their
own", "made real from your words") — never "LLM / coding model / TTS". The AI is still the star;
it just wears a costume. (The wonder = uniqueness + that they're *alive*.)

## The flow (5 phases · ~11 steps) — game-flavored copy

### Phase 1 — Recruit a champion (generated persona + portrait + voice)
1. **Opener** (centered, dismissible): "Welcome, commander. Your champions aren't chosen from a
   roster — each is forged anew, body and soul. A quick tour?" `[Begin] [Skip]`.
2. **Create** — anchor the picker's `+ Create hero`: "Recruit your first champion." *advanceOn:
   create modal opens.*
3. **Recruit** — anchor class picker + Recruit: "Choose a calling and **Recruit** — their name and
   legend are written for them alone, here and now." *advanceOn: persona streamed (name appears).*
4. **Their face & voice** — anchor portrait + ▶: "A face all their own, and a voice to match. Bring
   them to the field." *advanceOn: `Next` (don't gate on a slow paint).* Then **Save & Play**.
   *advanceOn: hero spawns.*

### Phase 2 — Take the field (move · attack · dodge · level)
5. **Lead them** — anchor the joystick: "Lead them with the stick — or WASD." *advanceOn: moves.*
6. **Strike** — anchor ⚔: "Strike with ⚔ (or Space). Most foes fall in a blow or two — thin the
   ranks." *advanceOn: 3 kills.*
7. **Dodge** — anchor ⟲: "Roll with ⟲ (or Shift) to slip a blow — untouchable for a heartbeat."
   *advanceOn: a dodge, or `Next`.*
8. **Grow stronger** — fires on the level-up draft: "Victory makes them stronger. Choose a boon."
   *advanceOn: a card chosen.*

### Phase 3 — Forge a skill (made real from your words) ★
9. **Open their sheet** — anchor the ☰/**C** button: "Press **C** for your champion's sheet — their
   skills, story and voice." *advanceOn: sheet opens.*
10. **Forge** — anchor `⚒ Forge a new skill`: "Forge a skill from your own words — describe it and
    it's made real, unlike any other, with art of its own." *advanceOn: a skill forged.* Then anchor
    a bar slot: "Set it to a slot, then **hold 1/2/3 to aim, release to unleash** — it strikes all
    who stand near." *advanceOn: cast once.*

### Phase 4 — Speak with them (they remember + answer aloud) ★
11. **Talk** — anchor `💬 Talk to {name}`: "They remember every battle they've lived. Speak with
    them — and hear them answer (tap 🔊)." *advanceOn: a reply, or `Next`.* End: "Recruit, fight,
    forge, speak. The field is yours, commander." (one-time done flag.)

### Phase 5 — Payoff (passive, no coachmark)
- On the champion's first fall, the **after-action war-diary recap** is the closing flourish — they
  recount the run in their own voice. One-time caption: "Your champion penned this." It sells itself.

## Persistence, replay, controls
- `tinyarmy.tutorial.v1` tracks `{ step, done, dismissed }`. Done/dismissed → never auto-starts.
- A small `?` button (near ☰) and a **Settings → "Replay tutorial"** reset the flag and re-run.
- `Skip tour` on every callout sets `dismissed` (and can be undone via Replay).
- `Esc` dismisses the current callout (pauses, resumes next session unless done/dismissed).

## Build sequencing
1. `web/tutorial.js` coachmark engine (callout render + positioning + persistence + event bus).
2. Add the ~6 `tutorialEmit(...)` hooks in tiny.js / heroCreator / skillForge (one line each).
3. Author the step list + copy.
4. Settings "Replay tutorial" + the `?` help button.
5. Verify each step advances on its action and the whole thing is skippable + first-run only.

## Status
Decision locked: **guided opt-in tour, game-flavored copy** (above). Ready to build on approval.