deadhead-space-freight-tycoon/memory-bank/change-requests/CR-022-welcome-screens.md

# 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.