Add demo validation CI workflow and expand demo/readiness docs

[DanFashauer]

Motivation

• Add an automated CI workflow to validate browser demo flows and deterministic media capture on relevant PRs and main pushes.
• Improve documentation and business-facing guidance to clearly separate demo/simulated behavior from pilot/production claims.
• Surface repository readiness and hygiene state so demo hosts and reviewers can run and validate scenarios safely.
• Reduce accidental use of demo defaults by documenting required hardening and next steps.

Description

• Add .github/workflows/demo-validation.yml to run typecheck, lint, build, a demo API unit test, deterministic demo media generation, and upload demo artifacts for PRs touching demo files.
• Update README.md to add business-facing doc links and adjust roadmap/readiness language.
• Add and populate several docs: docs/READINESS_HYGIENE_STATUS.md, docs/CLAIM_BOUNDARIES.md, docs/ARCHITECTURE_FUTURE_NOTES.md, docs/INTEGRATION_PRIORITIES.md, docs/PRODUCT_BOARD.md, and docs/VALUE_MAP.md to clarify demo boundaries and next work.
• Revise docs/DEMO_READINESS_CHECKLIST.md, docs/REPO_ENV_AUDIT_2026-03-31.md, docs/REPO_REVIEW_NEXT_STEPS_2026-03-30.md, and docs/ROADMAP.md to reflect current posture-read/readiness changes and prioritized remediation tasks.

Testing

• Ran npm run typecheck (TypeScript) in the workflow and it completed successfully.
• Ran npm run lint (ESLint) in the workflow and it completed successfully.
• Ran npm run build in the workflow and the build step completed successfully.
• Executed the demo API unit test with npx vitest run tests/api/demo-session-start.test.ts and it passed, followed by npm run demo:media which generated artifacts/demo-media/capture-report.json and was uploaded as an artifact.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c747921240

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Install Playwright browsers before capturing media

On a fresh GitHub runner, npm ci installs @playwright/test but does not provide the Chromium browser binary; in this repo chromium.launch() reports that npx playwright install is required. Because scripts/capture-demo-media.ts catches browser launch failures, writes capture-report.json, and exits successfully with only fallback storyboards, this workflow can pass the new “browser demo” validation without ever producing real browser screenshots/video. Add a Playwright browser install step (for example with dependencies) or assert browserAutomation.available before accepting the report.

Useful? React with 👍 / 👎.