Record CR-022: welcome screens (Phase 22)

Received as CR-020 for Phase 20; renumbered. Decisions 0.5.131-0.5.132.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

DECISIONS.md

@@ -1741,3 +1741,7 @@ Implementation decisions not spelled out in `memory-bank/implementation-plan.md`
 ## Step 21.9
 
 - **The game design document is left to the designer** (CR-021 §6), as with CR-016.
+
+## CR-022 recorded (Welcome Screens)
+
+- **Numbering:** received as "CR-020 — Welcome Screens" for "Phase 20"; stored as **CR-022**, built as **Phase 22** (its 20.n = 22.n), since CR-020 (Bridge) and CR-021 (Independent Pilots) exist. Its decisions CR-020.D1–D2 are **0.5.131–0.5.132**. Its references: CR-008 → CR-011, CR-011 → CR-014; CR-001 is unchanged.

memory-bank/change-requests/CR-022-welcome-screens.md

@@ -0,0 +1,85 @@
+# Change Request CR-022 — Welcome Screens
+
+> **Numbering note (added when recorded):** this request arrived titled "CR-020 — Welcome Screens" for "Phase 20". CR-020 (Bridge dashboard) and CR-021 (Independent Pilots), and Phases 20 and 21, already existed, so it is stored as **CR-022** and done as **Phase 22**: every "20.n" below means **22.n**. Its references map to this repo as: "Phase 13 and CR-001 through CR-019" = Phase 13 and **CR-001 to CR-021**; "CR-001 faster start" (the tutorial intro card, decision 0.5.36's one-time tip `tutorial-intro`) is the same number; "CR-008 settings" = **CR-011** (Settings → Help, "Show tips again", reduced motion, "Start a new company", decision 0.5.74); "CR-011 local-first" = **CR-014**. Its new decisions CR-020.D1–D2 are recorded as **0.5.131 Welcome on every new company** and **0.5.132 How to play**.
+>
+> **On recording:** the plan has no "first dispatch under 30 seconds" target from Phase 12. Step 22.4 adds that check (see DECISIONS, Step 22.4). The tutorial board is the Contracts screen during the tutorial.
+
+**Project:** Deadhead: Space Freight Tycoon
+**Applies to:** a build with Phase 13 and CR-001 through CR-019 complete
+**Do this:** as **Phase 20**
+**Related docs:** `change-request-faster-start.md` (CR-001), `change-request-settings.md` (CR-008), `change-request-local-first.md` (CR-011), `DECISIONS.md`
+
+This change request is written for the local-first engine (CR-011).
+
+---
+
+## 1. Why
+
+A new player goes straight from "Start your company" to the tutorial contract board without being told what kind of game this is. A short welcome explains the idea in a few seconds, then hands off to the existing tutorial.
+
+## 2. The welcome
+
+Three short cards in one pop-up, swiped or tapped through with **Next**, with **Skip** on every card. The last card's button starts the game.
+
+**Card 1 — What this is**
+> **Welcome to Deadhead**
+> A space trucking tycoon. Haul freight across the solar system, grow from a hired pilot into a shipping company, and never fly home empty.
+
+**Card 2 — How it plays**
+> **Your ships keep flying**
+> Pick contracts, choose a ship and pilot, and send them off. Trips run in real time, even when the app is closed. Come back to finished deliveries, then send them out again.
+
+**Card 3 — Where you start**
+> **First, earn your wings**
+> You're flying for Halvorsen Lunar Freight on the Earth–Moon run. Do good work, and the old man might have an offer for you.
+>
+> [Let's fly]
+
+### Rules
+| Rule | Detail |
+|---|---|
+| When it shows | Right after "Start your company" creates a new company, and after "Start a new company" in Settings (CR-008). Every new company, not just the first. |
+| Order | Welcome first. When it closes, the CR-001 tutorial intro card on the Contracts screen shows as before. |
+| After closing | Skip and "Let's fly" both close it and go to the Contracts screen. |
+| Reopen | Settings → Help gets **"How to play"**, which opens the same three cards (the last button reads "Close" instead of "Let's fly"). |
+| Saved state | The save records that the welcome was seen for this company, so it doesn't reappear after a reload mid-tutorial. |
+| Motion | Card transitions slide; with reduced motion on (CR-008), they cross-fade instantly. |
+| Accessibility | Focus moves into the pop-up and stays there until it closes; Next, Skip, and the final button are reachable by keyboard and screen reader; card position is announced ("1 of 3"). |
+
+All text lives in content so it can be edited without code changes. "Halvorsen Lunar Freight" comes from the existing content name.
+
+## 3. Rules for this change
+
+- All rules in `implementation-plan.md` §0.1 apply: steps in order, one commit per step, each step's test must pass.
+- Save migration: existing companies are marked as having seen the welcome, so current players don't get it mid-game.
+- Update `progress.md` after every step. Stop for the user's review at the end of Phase 20.
+
+## 4. Decisions
+
+Record these in `DECISIONS.md` and `implementation-plan.md` §0.5, using the next free numbers (labeled CR-020.D1–D2 here; note the mapping).
+
+- **CR-020.D1 Welcome on every new company.** Three cards per §2, shown once per company, before the tutorial intro card.
+- **CR-020.D2 How to play.** Reopenable from Settings → Help.
+
+## 5. Steps — Phase 20
+
+### Step 20.1 — Content and save field
+- Add the three cards' titles, body text, and button labels to content. Add a "welcome seen" field to the save, set to false for new companies; save migration sets it to true for existing ones.
+- **Test:** Content validates. A new company has "welcome seen" false; an older save migrates with it true.
+
+### Step 20.2 — Client: welcome pop-up
+- Build the three-card pop-up per §2: Next, Skip, card position, final "Let's fly", reduced-motion behavior, and focus handling. Closing it marks the welcome seen and goes to Contracts, where the CR-001 intro card appears.
+- **Test:** Component tests: after starting a company, card 1 shows; Next advances to 2 and 3; Skip on any card closes it; "Let's fly" closes it; both mark it seen and land on Contracts with the intro card. Reloading after closing doesn't show it again. With reduced motion on, no slide animation runs. Focus stays inside the pop-up until it closes.
+
+### Step 20.3 — Client: new company and "How to play"
+- "Start a new company" (Settings) shows the welcome for the new company.
+- Settings → Help adds "How to play", which opens the cards with a final "Close" button and doesn't change the saved flag.
+- **Test:** Component tests: starting a new company from Settings shows card 1; "How to play" opens the cards anytime and its last button reads "Close".
+
+### Step 20.4 — Regression
+- Run the full suite.
+- **Test:** CI is green. The Phase 12 "first dispatch under 30 seconds" target still holds when the simulated player skips the welcome. Manual check: start a new company on a phone and read through the three cards.
+
+## 6. Out of scope
+
+Illustrations or animation on the cards, a longer interactive tutorial, voice-over, and anything else in `implementation-plan.md` §0.3.

memory-bank/implementation-plan.md

@@ -186,6 +186,8 @@ These answer the pre-build review. Log each one in `DECISIONS.md` as it is imple
 128. **Idle behavior** (CR-021). With nothing to take, a pilot waits for the next board period; after 3 empty periods in a row away from their home HQ they deadhead home when they can.
 129. **Deterministic catch-up** (CR-021). On open or resume the engine replays events since the last saved time in time order (ties by pilot id), at most 7 days; the result doesn't depend on how the time is split.
 130. **No independent-trip notifications** (CR-021). Independent trips are decided on the device as time is replayed, so none are scheduled as notifications.
+131. **Welcome on every new company** (CR-022). Three welcome cards (what the game is, how it plays, where you start), with text in content, shown once per company right after it's created ("Start your company" or "Start a new company"), before the CR-001 tutorial intro card. The save records that this company's welcome was seen; saves from before CR-022 count as seen.
+132. **How to play** (CR-022). Settings → Help reopens the three cards any time, ending in "Close"; it doesn't change the saved flag.
 
 ### 0.6 Translating change requests written for the server (CR-014 §7)
 
@@ -873,6 +875,12 @@ Steps 21.1–21.9 are specified in `memory-bank/change-requests/CR-021-independe
 
 ---
 
+## Phase 22 — Welcome Screens (CR-022)
+
+Steps 22.1–22.4 are specified in `memory-bank/change-requests/CR-022-welcome-screens.md` §5 (written there as 20.1–20.4). Stop for review at the end.
+
+---
+
 ## Definition of Done (Base Game)
 
 - All step tests pass in CI.

memory-bank/progress.md

@@ -484,3 +484,12 @@ Spec: `memory-bank/change-requests/CR-021-independent-pilots.md` (received as "C
 - [x] **Step 21.9 — Plan amendments and regression.** CR-021 §6 applied: plan 0.3 (automation struck; standing orders, pilot traits, decision events and a hiring market stay deferred) and 0.5 (0.5.122–0.5.130); a note on CR-001's goals (a Dispatch Office goal later, not now); CR-014 Step 14.6 (the loop is the event-queue catch-up); CR-019 (pilots choose from completable boards); plan Step 12.1 (the away scenario). `game-design-document.md` is the designer's to update. Full suite: typecheck, lint, 1399 unit tests and 9 e2e tests pass.
 
 **Phase 21 is complete; stopped for review.** Manual check for the user: buy the Dispatch Office on the Bridge, set Rosa to Independent with default orders, close the app for an hour, reopen and read her logbook; then confirm a first-contact job stayed on the board for you.
+
+## Phase 22 — Welcome Screens (CR-022)
+
+Spec: `memory-bank/change-requests/CR-022-welcome-screens.md` (received as "CR-020 … Phase 20"). New decisions recorded as plan §0.5.131–0.5.132.
+
+- [ ] Step 22.1 — Content and save field
+- [ ] Step 22.2 — Client: welcome pop-up
+- [ ] Step 22.3 — Client: new company and "How to play"
+- [ ] Step 22.4 — Regression