docs/beta-preflight-checklist.md

# Beta Preflight Checklist

Use this before a human beta session or any long continuation where continuity, visuals, and pacing matter.

## 1. Run The Audit

```powershell
python plugins\questforge\scripts\preflight.py `
  --campaign-root campaigns\<campaign-slug> `
  --repair-missing-templates `
  --refresh-gallery `
  --title "<campaign title>"
```

Continue only when errors are zero. Warnings are prep prompts, not automatic blockers.

For a public release candidate, use the stricter visual gate:

```powershell
python scripts\preflight.py `
  --campaign-root campaigns\<campaign-slug> `
  --require-player-journal `
  --require-generated-visuals `
  --require-opening-visual `
  --refresh-gallery `
  --title "<campaign title>"
```

This command fails when the opening is still only `prompt-saved`, when no generated asset is registered, or when an indexed asset is missing. A row marked `unavailable` is distinct from a silent pending prompt, but it does not satisfy the release requirement for a surface that advertises native image generation.

## 2. Fill The Player Surface

Update `player-journal.md` with only spoiler-free facts:

- current objective;
- immediate risk;
- known clues and NPCs;
- inventory, money, XP, rewards, leverage, and contacts;
- damage, conditions, disguises, wounds, or visible states;
- open threads the player can act on next.

## 3. Fill The Visual Ledger

If preflight reports `empty_visual_ledger`, add active rows to `images/visual-ledger.md` before play. Keep this short and high-impact:

- player character appearance, current outfit, injuries, bandages, disguise, or carried signature gear;
- recurring NPCs or creatures that are likely to reappear;
- important objects with scale and shape, such as a 40 cm iron box with seven brass studs;
- locations whose layout must stay stable across maps, POVs, and scene frames;
- campaign style constraints, such as immersive fantasy realism and no unwanted film grain.

Do not try to document every prop. Track only details that would feel wrong if they changed.

## 4. Prepare The Visual Surfaces

Open `images/visual-gallery.html#latest` in the Codex in-app Browser when available. Keep the same gallery URL for the session as the desktop/history surface. Static generated images should still be shown once in the Codex conversation so mobile users can see them. Use the local gallery for 360 viewers, desktop review, and chronological history.

## 5. Prepare The Next Scene

Before the first live turn, decide:

- the current location and immediate pressure;
- one NPC, faction, clock, or danger that can move without player permission;
- the next meaningful choice;
- one possible reward, clue, XP moment, or useful loot;
- whether the next visual should be a scene frame, comic page, map, inventory board, or POV 360.

## 6. During Play

For each meaningful turn:

- move the fiction forward even on failed rolls;
- show relevant ability modifiers when suggesting options;
- award XP, loot, clues, or leverage for meaningful progress;
- update `player-journal.md`, `campaign-state.md`, and `images/visual-ledger.md` as states change;
- show each selected static generated image once in chat with absolute-path Markdown;
- refresh the gallery after registering a generated image.

## 7. Product-Surface Acceptance

The filesystem cannot prove that an image was rendered in the conversation. Before submitting a plugin release, perform one clean installed-plugin run on the target OpenAI surface and retain review evidence that:

- the first actionable scene invoked native image generation rather than only saving a prompt;
- the selected static image appeared once in the same conversation;
- the image was copied into `images/assets/` and registered in `images/visual-index.md` when a writable local workspace was available;
- `visual-gallery.html#latest` displayed that same asset;
- the strict preflight command above returned zero errors;
- the task did not claim a gallery, 360 viewer, audio loop, or local persistence on a surface that could not create it.

Treat any silent `prompt-saved` opening as a failed acceptance run.