feat(questionnaires): F9.4 demo-content seed + F9.2 operational runbook

.context/app/planning/features/f0.1.md

@@ -2,7 +2,7 @@
 feature: F0.1
 title: Foundation scaffolding
 phase: P0 — Foundations
-status: in flight
+status: done
 owner: Simon Holmes
 deps: none (first feature)
 opened: 2026-06-01

.context/app/planning/features/f2.1.md

@@ -2,7 +2,7 @@
 feature: F2.1
 title: Questionnaire authoring
 phase: P2 — Admin CRUD over questionnaires
-status: in flight
+status: done
 owner: TBD
 deps: F1.1
 opened: 2026-06-02

.context/app/planning/features/f2.2.md

@@ -2,7 +2,7 @@
 feature: F2.2
 title: Tagging
 phase: P2 — Admin CRUD over questionnaires
-status: in flight
+status: done
 owner: TBD
 deps: F2.1
 opened: 2026-06-02

.context/app/planning/features/f2.3.md

@@ -2,7 +2,7 @@
 feature: F2.3
 title: Extraction-change review
 phase: P2 — Admin CRUD over questionnaires
-status: in flight
+status: done
 owner: TBD
 deps: F1.1, F2.1
 opened: 2026-06-03

.context/app/planning/features/f2.4.md

@@ -2,7 +2,7 @@
 feature: F2.4
 title: Re-ingest
 phase: P2 — Admin CRUD over questionnaires
-status: in flight
+status: done
 owner: TBD
 deps: F1.1, F2.1
 opened: 2026-06-04

.context/app/planning/features/f3.1.md

@@ -2,7 +2,7 @@
 feature: F3.1
 title: Questionnaire configuration
 phase: P3 — Configuration, invitations, and cost estimation
-status: in flight
+status: done
 owner: TBD
 deps: F2.1
 opened: 2026-06-04

.context/app/planning/features/f3.2.md

@@ -2,7 +2,7 @@
 feature: F3.2
 title: Invitation flow
 phase: P3 — Configuration, invitations, and cost estimation
-status: in flight
+status: done
 owner: TBD
 deps: F3.1
 opened: 2026-06-04

.context/app/planning/features/f3.3.md

@@ -2,7 +2,7 @@
 feature: F3.3
 title: Pre-launch cost estimation
 phase: P3 — Configuration, invitations, and cost estimation
-status: in flight
+status: done
 owner: TBD
 deps: F3.1
 opened: 2026-06-04

.context/app/planning/features/f4.1.md

@@ -2,7 +2,7 @@
 feature: F4.1
 title: Selection strategies
 phase: P4 — Conversational engine (non-streaming)
-status: in flight
+status: done
 owner: TBD
 deps: F0.1, F2.2 (tags), F3.1 (config)
 opened: 2026-06-04

.context/app/planning/features/f4.2.md

@@ -2,7 +2,7 @@
 feature: F4.2
 title: Answer extraction into slots
 phase: P4 — Conversational engine (non-streaming)
-status: in flight
+status: done
 owner: TBD
 deps: F0.1, F1.1 (slots), F2.1 (typeConfig)
 opened: 2026-06-04

.context/app/planning/features/f4.3.md

@@ -2,7 +2,7 @@
 feature: F4.3
 title: Contradiction detection
 phase: P4 — Conversational engine (non-streaming)
-status: in flight
+status: done
 owner: TBD
 deps: F0.1, F1.1 (slots), F2.1 (typeConfig), F3.1 (contradiction config), F4.2 (answer shapes)
 opened: 2026-06-05

.context/app/planning/features/f4.4.md

@@ -2,7 +2,7 @@
 feature: F4.4
 title: Answer refinement
 phase: P4 — Conversational engine (non-streaming)
-status: in flight
+status: done
 owner: TBD
 deps: F0.1, F1.1 (slots), F2.1 (typeConfig), F4.2 (answer shapes + value validation)
 opened: 2026-06-05

.context/app/planning/features/f4.5.md

@@ -2,7 +2,7 @@
 feature: F4.5
 title: Completion logic
 phase: P4 — Conversational engine (non-streaming)
-status: in flight
+status: done
 owner: TBD
 deps: F4.1 (coverage helpers + config), F4.2 (answers), F4.3 (completion-sweep), F4.4 (session/answer persistence)
 opened: 2026-06-05

.context/app/planning/features/f4.6.md

@@ -2,7 +2,7 @@
 feature: F4.6
 title: Session state machine
 phase: P4 — Conversational engine (non-streaming)
-status: in flight
+status: done
 owner: TBD
 deps: F4.4 (session/answer persistence), F4.5 (markSessionCompleted seam)
 opened: 2026-06-05

.context/app/planning/features/f6.1.md

@@ -2,7 +2,7 @@
 feature: F6.1
 title: Per-turn orchestrator + streaming
 phase: P6 — Conversational session (streaming)
-status: in flight
+status: done
 owner: TBD
 deps: F4.1–F4.6 (P4 capabilities + session state machine)
 opened: 2026-06-06

.context/app/planning/features/f6.3.md

@@ -2,7 +2,7 @@
 feature: F6.3
 title: Cost cap enforcement at turn boundary
 phase: P6 — Conversational session (streaming)
-status: in flight
+status: done
 owner: TBD
 deps: F4.6 (session state machine), F6.1 (per-turn orchestrator + streaming)
 opened: 2026-06-06

.context/app/planning/features/f7.1.md

@@ -2,7 +2,7 @@
 feature: F7.1
 title: Chat surface
 phase: P7 — Demo-grade respondent experience
-status: in flight
+status: done
 owner: TBD
 deps: F6.1 (live respondent surface + SSE turn loop), F6.2 (transcribe endpoint), F3.4 (theming module)
 opened: 2026-06-06

.context/app/planning/features/f7.2.md

@@ -2,7 +2,7 @@
 feature: F7.2
 title: Answer-slot panel
 phase: P7 — Demo-grade respondent experience
-status: in flight
+status: done
 owner: TBD
 deps: F6.1 (live respondent surface + SSE turn loop), F7.1 (chat surface)
 opened: 2026-06-06

.context/app/planning/features/f8.1.md

@@ -2,7 +2,7 @@
 feature: F8.1
 title: Admin analytics dashboards
 phase: P8 — Admin analytics, exports, anonymous mode
-status: in flight
+status: done
 owner: TBD
 deps: F4.2 (answer slots), F4.6 (session events), F3.2 (invitations), F6.1 (live turns)
 opened: 2026-06-08

.context/app/planning/features/f8.2.md

@@ -2,7 +2,7 @@
 feature: F8.2
 title: Result exports
 phase: P8 — Admin analytics, exports, anonymous mode
-status: in flight
+status: done
 owner: TBD
 deps: F8.1 (analytics scope + filter), F4.2 (answer slots), F4.6 (session events), F6.1 (turns)
 opened: 2026-06-08

.context/app/planning/features/f8.3.md

@@ -2,7 +2,7 @@
 feature: F8.3
 title: Anonymous-mode hardening (+ respondent profile collection)
 phase: P8 — Admin analytics, exports, anonymous mode
-status: in flight
+status: done
 owner: TBD
 deps: F8.1 (analytics surfaces), F8.2 (result exports), F7.4 (PDF export), F6.1 (sessions)
 opened: 2026-06-09

.context/app/planning/features/f9.1.md

@@ -2,7 +2,7 @@
 feature: F9.1
 title: Production hardening
 phase: P9 — Hardening + forking docs
-status: in flight
+status: done
 owner: TBD
 deps: everything (final pass — P0–P8 complete)
 opened: 2026-06-09

.context/app/planning/features/f9.2.md

@@ -0,0 +1,66 @@
+---
+feature: F9.2
+title: Operational runbook
+phase: P9 — Hardening + forking docs
+status: in flight
+owner: TBD
+deps: F9.1, F9.4 (demo content seed — built first so the runbook can exercise it)
+opened: 2026-06-09
+plan: .context/app/planning/development-plan.md#f92--operational-runbook
+docs: .context/app/questionnaire/runbook.md
+---
+
+# F9.2 — Operational runbook
+
+> Committable tracker for **F9.2**. A road-tested "spin up a demo client end-to-end" runbook so
+> a presenter can go from a fresh checkout to a respondent answering the first question without
+> reverse-engineering the admin UI. A **documentation** feature — it adds no runtime capability.
+
+## Intent
+
+Every surface the demo needs already exists (demo clients, theming, ingestion, clone-for-client,
+config, launch, invitations, sessions, reset). What was missing was the **sequence**: which
+screens, in what order, with the gotchas that trip a first-timer. F9.2 captures that as
+`.context/app/questionnaire/runbook.md`, then road-tests it on a clean machine and folds the
+friction back in. F9.4's demo-content seed (built first) gives the runbook a one-command fast
+path so a stock demo needs zero manual setup.
+
+## Decisions
+
+- **Build F9.4 first.** The plan calls for the `LOAD_DEMO_CONTENT` seed to land before the
+  road-test so the runbook can exercise it. F9.4 was not started, so it was built first on this
+  same branch ([f9.4.md](./f9.4.md)); the runbook leads with that seeded fast path.
+- **Two content paths, clone-first.** The runbook leads with clone-for-client (fastest demo
+  path from a template) and documents upload-and-extract as the alternative for net-new content
+  — rather than picking only one.
+- **Demo-doc convention, not the index.** The runbook is demo-oriented, so it follows the
+  established demo-doc pattern: a `> **DEMO-ONLY**` callout, cross-linked from
+  [demo-clients.md](../../app/questionnaire/demo-clients.md) (the demo hub) rather than added to
+  the namespace `README.md` index — which deliberately excludes demo docs to stay fork-clean. A
+  callout notes the middle of the flow (content → configure → launch → invite → session) is the
+  core product, identical for a real engagement.
+- **Road-test is a human task.** The "live road-test on a clean machine" is John/Simon's to run.
+  This feature delivers the draft + a road-test checklist (a tick-and-note table in the doc);
+  the reported friction is folded back as the closing change before the phase ships.
+
+## Build shape (branch `feat/F9.4-demo-seed-and-F9.2-runbook`)
+
+- **Runbook** — `.context/app/questionnaire/runbook.md`. Sections: prerequisites (flags are DB
+  rows, not env vars; LLM key; email) → seeded fast path (§1A) → manual client + content
+  (clone-first / upload) → review/configure/launch → attribute → invite → first session
+  (respondent view) → reset between prospects → troubleshooting table → road-test checklist →
+  see-also. Concrete admin routes + API endpoints throughout.
+- **Cross-link** — a pointer from `demo-clients.md`'s header callout into the runbook.
+
+## Verification
+
+- `npm run validate` clean (the runbook + tracker are docs; no code beyond F9.4).
+- Doc links resolve (sibling `.md` files exist; `forking.md` is a known P9 forward-reference,
+  matching the existing `demo-clients.md` reference).
+- **Pending — human road-test.** John/Simon run the checklist on a clean machine; friction is
+  folded into the doc, then the feature flips to `shipped`.
+
+## No CHANGELOG entry
+
+F9.2 is app-owned documentation — no Sunrise platform surface. Per the repo's platform-scoped
+CHANGELOG policy, it adds no `CHANGELOG.md` bullet.

.context/app/planning/features/f9.4.md

@@ -0,0 +1,93 @@
+---
+feature: F9.4
+title: Demo content seed (DEMO-ONLY)
+phase: P9 — Hardening + forking docs
+status: done
+owner: TBD
+deps: F2.5.1 (AppDemoClient), F7.1 (themeable vertical to seed)
+opened: 2026-06-09
+plan: .context/app/planning/development-plan.md#f94--demo-content-seed-demo-only
+docs: .context/app/questionnaire/runbook.md
+---
+
+# F9.4 — Demo content seed (DEMO-ONLY)
+
+> Committable tracker for **F9.4**. A one-command seed that populates a sample demo client
+> plus a fully launched, attributed questionnaire on a fresh DB, so the F9.2 operational
+> runbook can be road-tested end-to-end without manual admin clicks. **Strictly demo-only** —
+> a fork strips it. Built ahead of F9.2 (per the plan) so the runbook can exercise it.
+
+## Intent
+
+F9.4 removes the manual click-path from "fresh DB → something to demo". Before it, a presenter
+had to create a demo client, upload or clone a questionnaire, configure it, and launch it by
+hand before they could invite anyone. F9.4 collapses that into `LOAD_DEMO_CONTENT=1 npm run
+db:seed`: a believable "Northwind Logistics" demo client and a launched, attributed
+questionnaire appear, ready to invite a respondent against. It adds **no runtime capability** —
+it is pure demo scaffolding that takes the same persistence path a real upload does.
+
+## Decisions
+
+- **Env-gated, off by default.** The seed no-ops unless `LOAD_DEMO_CONTENT=1`, so it can never
+  load in production. The gate lives **inside** `run()` (not as a file-skip) so the runner still
+  stamps `SeedHistory` on the no-op — see the gotcha below.
+- **Reuse the ingestion writer, don't hand-roll inserts.** The section/slot graph is written
+  through `writeGraph` (the same function the ingestion route uses), fed a hand-authored
+  `ExtractQuestionnaireStructureData`. The demo content therefore exercises the real
+  persistence seam, not a parallel one. `persistIngestion` was rejected — it demands a fake
+  source-document row the demo has no use for.
+- **Set `status: 'launched'` directly.** There is no pure launch helper (the gate lives in the
+  status HTTP route), so the seed re-asserts the gate's invariants itself (goal, non-empty
+  audience, ≥1 section, ≥1 question, config row) and flips the version status in the same
+  transaction. The whole build is one `executeTransaction` so a partial demo never exists.
+- **Replace-on-rerun idempotency.** The demo client upserts by unique `slug`; the questionnaire
+  is found-and-replaced by a stable title marker (`Northwind Logistics — Onboarding Experience
+Review`). Editing the sample content and re-seeding refreshes the demo with no duplicates.
+- **Profile capture on.** `anonymousMode` stays false and two profile fields (name, work email)
+  are seeded, so the demo visibly shows the F8.3 session-start profile step.
+
+## Build shape (branch `feat/F9.4-demo-seed-and-F9.2-runbook`)
+
+- **Seed unit** — `prisma/seeds/app-questionnaire/025-demo-content.ts`, name
+  `app-questionnaire/025-demo-content` (next free prefix after `024`). Env-gate → upsert demo
+  client → replace prior demo questionnaire → create questionnaire (attributed) → version
+  (goal + audience + provenance) → `writeGraph` (2 sections, 6 slots spanning the question-type
+  range) → config row (defaults + profile fields) → flip version to `launched`. Whole file
+  marked `// DEMO-ONLY`; nothing imports it, so a fork deletes it wholesale.
+- **`.env.example`** — a documented, commented `# LOAD_DEMO_CONTENT=1` block (DEMO-ONLY) under
+  a new "Demo content" section, including the re-load recipe for the no-op gotcha.
+
+## The no-op gotcha
+
+The runner records a `SeedHistory` row with the file's content hash after **any** successful
+`run()` — including the env-gated no-op. So if `db:seed` runs once without
+`LOAD_DEMO_CONTENT=1` (the normal case), the row is stamped; later setting the env var alone
+won't reload, because the file content is unchanged and the runner skips it. To load demo
+content after a prior no-op, clear the history row and re-seed:
+
+```sql
+DELETE FROM "SeedHistory" WHERE name = 'app-questionnaire/025-demo-content';
+```
+
+then `LOAD_DEMO_CONTENT=1 npm run db:seed`. Documented in `.env.example` and the F9.2 runbook.
+
+## Sample content
+
+Vertical: **B2B SaaS onboarding feedback** — "Northwind Logistics" demo client (branded
+CTA/accent/logo/welcome copy) and a launched questionnaire "Northwind Logistics — Onboarding
+Experience Review": 2 sections (Getting started · Value & support), 6 questions covering
+`likert | free_text | single_choice | numeric | multi_choice | boolean`, a full 7-field
+audience, and name/email profile capture.
+
+## Verification
+
+- `LOAD_DEMO_CONTENT=1 npm run db:seed` — seeds the client + launched questionnaire; logged.
+- Row check: 1 demo client, 1 questionnaire (attributed), 1 version (`launched`, goal set),
+  2 sections, 6 slots, 1 config row (2 profile fields, `anonymousMode=false`).
+- `npm run db:seed` again **without** the env var → seed no-ops (skip log), creates nothing.
+- `npm run validate` clean (type-check + lint + format).
+
+## No CHANGELOG entry
+
+F9.4 is app-owned, demo-only seed scaffolding — no Sunrise platform surface. Per the repo's
+platform-scoped CHANGELOG policy, it adds no `CHANGELOG.md` bullet.

.context/app/questionnaire/demo-clients.md

@@ -4,6 +4,10 @@
 > sales demo — **not** a security boundary and **not** real multi-tenancy. A real
 > client engagement strips it. See [forking.md] § "Replacing demo tenancy" (P9) and
 > the [development plan][plan] P2.5 section.
+>
+> **Spinning one up?** The end-to-end operational walkthrough — seed fast path,
+> branding, content, launch, invite, first session, reset — is in
+> [runbook.md](./runbook.md).
 
 ## What it is (and isn't)