# Demo Release Runbook

This runbook is for the person recording or presenting the milestone #5 demo. It turns the integrated app, tests, QA notes, and release checklist into a repeatable public-demo process.

## Roles

- **Demo presenter:** records the walkthrough or presents live.
- **Release driver:** runs tests, starts services, confirms deployment URLs, and watches logs.
- **Backup operator:** keeps a second clean browser/session ready in case the primary demo state is exhausted.

For a small team, one person can cover all roles, but keep the responsibilities separate in the checklist.

## Pre-demo timeline

### T-24 hours

1. Pull the latest repository state.
2. Install dependencies from a clean checkout.
3. Generate a real package lockfile through the package manager install command if the repository policy uses one.
4. Run API integration tests.
5. Run web unit tests.
6. Run Playwright E2E tests.
7. Run optional static accessibility guard:

   ```sh
   node scripts/qa/a11y-static-check.mjs
   ```

8. If using a preview deployment, run optional HTTP smoke:

   ```sh
   node scripts/qa/http-smoke.mjs --api <preview-api-url> --web <preview-web-url>
   ```

9. Capture screenshots listed in `docs/full-stack-acceptance-matrix.md`.

### T-2 hours

1. Confirm the API and web URLs still respond.
2. Clear or reset the demo browser profile.
3. Rehearse `docs/demo-script.md` once.
4. Confirm the demo user has enough uncompleted actions available:
   - at least one uncollected team;
   - at least one uncollected stadium or match;
   - at least one unanswered trivia question;
   - at least one prediction target;
   - at least one challenge near completion.
5. Keep terminal logs visible but not distracting.

### T-10 minutes

1. Close unrelated browser tabs.
2. Disable notification popups.
3. Set browser zoom to 100%.
4. Confirm microphone/screen recording settings.
5. Open the app on the starting screen.
6. Keep a fallback URL/session ready.

## Recommended demo story

Use this sequence for a concise public update:

1. **Opening promise:** “This is a digital football passport for the World Cup journey.”
2. **Passport baseline:** show empty/in-progress teams, stadiums, predictions, badges, and leaderboard.
3. **Collect a team:** collect England or another recognizable team.
4. **Show reward:** point out XP/progress/badge changes.
5. **Trivia loop:** answer a World Cup trivia question and show feedback.
6. **Prediction loop:** submit a prediction, ideally an upset/giant-killing pick.
7. **Challenge completion:** complete or advance a challenge.
8. **Leaderboard movement:** show how XP changes ranking.
9. **Return hook:** mention daily trivia, match-day memories, sticker-style collections, and future Premier League/Champions League passports.

Target duration: 2–5 minutes for a recorded update, 7–10 minutes for a live walkthrough.

## Presenter talking points

Use language that explains the product rather than the implementation:

- “Fans build a living passport as the tournament unfolds.”
- “Every action can feed challenges, badges, and leaderboard progress.”
- “The demo is seeded for World Cup 2026 content and designed to evolve after the tournament.”
- “The important integration milestone is that the frontend is no longer static; actions now hit the backend gamification engine.”
- “We can test real edge cases: duplicate actions do not farm points, empty states are handled, and leaderboard movement is visible.”

## Technical monitoring during demo

The release driver should watch for:

- API process restart/crash;
- browser console runtime errors;
- CORS errors;
- failed network requests;
- repeated 500 responses;
- sudden leaderboard inconsistency;
- long request latency.

If a non-blocking request fails but the UI recovers, continue and mention resilience only if appropriate. If a primary action fails, use the fallback plan below.

## Fallback plan

### If the frontend fails to load

1. Refresh once.
2. Confirm the web server/deployment URL.
3. Open fallback session or local build.
4. If still blocked, show prepared screenshots and explain the issue transparently.

### If the API fails

1. Restart the API process or redeploy preview if available.
2. Refresh the web app.
3. Run:

   ```sh
   node scripts/qa/http-smoke.mjs --api <api-url> --skip-web
   ```

4. Resume from the previous stable step.

### If demo state is exhausted

Use one of these options:

- open the backup clean browser profile;
- change to a fresh demo user if the app supports user identifiers;
- restart the in-memory API store if using local demo state;
- switch to prepared screenshots for the already-completed moment.

### If a mutation is accidentally repeated

Continue if idempotency works. This can become a positive proof point: “Notice it does not double-award XP when I click again.”

## Post-demo checklist

After recording or presenting:

1. Save the recording.
2. Save screenshots.
3. Save terminal test output if publishing a technical update.
4. Note any bugs observed during the run.
5. Confirm no secret environment values appeared on screen.
6. Update `docs/crowdfunding-update.md` with the final screenshots/video link.
7. If using a public preview, verify it is still in a safe demo configuration.

## Public release gate

Before posting the crowdfunding update, confirm:

- README setup steps were followed successfully on a clean checkout.
- API integration tests pass.
- Web unit tests pass.
- Playwright E2E demo passes.
- Manual QA scenarios for collection, trivia, prediction, badge unlock, challenge progress, and leaderboard movement pass.
- Accessibility review has no critical blockers.
- Responsive review passes mobile and desktop.
- Deployment guidance matches the actual host/provider.
- Release checklist is complete.