> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase02-session07-product-surface-validation-and-documentation-closeout/spec.md).

# Session Specification

**Session ID**: `phase02-session07-product-surface-validation-and-documentation-closeout` **Phase**: 02 - Product Surface and 2D Battlefield Completion **Status**: Implementation Complete - Pending Validate Workflow **Created**: 2026-05-29 **Package**: Cross-cutting (`apps/web`, `public-demo`, docs, spec system) **Package Stack**: React 18.3.1, Vite 6.4.2, TypeScript 5.9.3, Express 4, ws 8.21.0, Vitest 4.1.7, Playwright 1.60.0, Biome 2.4.16, Node.js 20, static public demo

***

## 1. Session Overview

This session validates Phase 02 as a browser-facing product surface and closes the documentation contract before the phase can move to `updateprd` and phase-transition work. Sessions 01 through 06 reconciled requirements, completed the cockpit shell, hero and mission workflows, battlefield interaction, app/demo asset parity, and privacy-sensitive settings, replay, notification, export, and scan UX. Session 07 turns that work into recorded evidence.

The session is cross-cutting because the evidence spans the app cockpit, the standalone public demo, root quality gates, stable docs, PRD status, and spec-system closeout artifacts. The main output is not a new feature; it is a reliable validation record, any small fixes needed by validation, and documentation that clearly separates shipped Phase 02 behavior from later War Room, orchestration, media, hosted-service, collaboration, and release-decommission work.

The expected outcome is a Phase 02 closeout package: browser screenshots and guard results for app and public demo desktop/mobile viewports, repo quality gate results, updated stable docs and README references, a privacy/security closeout, an implementation summary, and a remaining-gap list that can feed Phase 03 and later sessions without overstating what Phase 02 shipped.

***

## 2. Objectives

1. Validate the full app and public demo browser surfaces across desktop and mobile Playwright projects with screenshots, console/page-error guards, failed-request checks, nonzero battlefield dimensions, and public demo offline reload evidence.
2. Run local quality gates relevant to Phase 02 product-surface work, including formatting, linting, typecheck, tests, battlefield asset parity, and e2e checks or explicit blockers.
3. Update stable docs, package README files, PRD status references, and legacy-consolidation notes so shipped, deferred, excluded, and evidence-only behavior is accurate after Sessions 02 through 06.
4. Produce implementation notes, security/privacy closeout, validation report, implementation summary, and remaining-gap handoff for Phase 03 and later phases.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase02-session01-product-surface-requirements-reconciliation` - Provides the Phase 02 PRD, UX PRD, and product surface gap matrix.
* [x] `phase02-session02-cockpit-shell-and-navigation-cohesion` - Provides the coherent app shell, global command controls, and honest War Room stub boundary.
* [x] `phase02-session03-hero-and-mission-workflow-completion` - Provides hero, mission, permission, plan, and contextual overlay workflows to validate.
* [x] `phase02-session04-battlefield-state-and-interaction-polish` - Provides app battlefield accessibility, state, fallback, and reduced-motion behavior to validate.
* [x] `phase02-session05-battlefield-asset-and-public-demo-parity` - Provides app/demo asset parity checks, service-worker coverage, and public demo validation expectations.
* [x] `phase02-session06-settings-replay-notifications-and-scan-ux` - Provides settings, replay, notification, export, and scan UX closeout to validate.

### Required Tools/Knowledge

* Node.js 20 and npm workspace scripts from the root lockfile.
* Vitest, Playwright, Testing Library, happy-dom, and Biome.
* Root Playwright configuration for `app-desktop`, `app-mobile`, `public-demo-desktop`, and `public-demo-mobile`.
* Browser guard helpers in `tests/e2e/support/browserGuards.ts`.
* Public demo validation rules in `public-demo/docs_public-demo/validation.md`.
* Stable docs under `docs/`, package README files, and the Phase 02 gap matrix.

### Environment Requirements

* Repository dependencies are installed.
* Local ports 2468, 5193, and 8101 are available or Playwright can reuse compatible existing servers.
* Browser validation can run without hosted accounts, hosted storage, analytics, Cloudflare, Anthropic provider transfer, push backend, or War Room federation.
* Public demo offline validation starts with an online load before switching the browser context offline.

***

## 4. Scope

### In Scope (MVP)

* Maintainer can validate app browser surface - Run app desktop and mobile browser checks with screenshot attachments, console/page-error guards, failed-request checks, nonzero battlefield dimensions, loaded/fallback asset state checks, and obvious overlap review.
* Maintainer can validate public demo surface - Run public demo desktop and mobile checks with splash entry, battlefield interaction, audio toggles, limitation copy, service-worker readiness, and offline reload evidence.
* Maintainer can trust repo quality gates - Run focused and repo-wide quality gates for formatting, linting, typecheck, Vitest, battlefield asset parity, e2e, `git diff --check`, ASCII, and LF checks, or document explicit blockers with reproduction detail.
* User can rely on stable docs - Update README files, docs index, architecture, battlefield, public demo, privacy/security, release, PRD, UX PRD, gap matrix, and legacy-consolidation references so current Phase 02 behavior is accurate.
* Reviewer can audit privacy and security posture - Produce a closeout report covering local-first boundaries, redaction, browser localStorage/replay/export/scan surfaces, public demo synthetic data, War Room deferral, and known release risks.
* Future phases have a clean handoff - Produce an implementation summary and remaining-gap list for Phase 03 and later phases without writing Phase 03 implementation specs.

### Out of Scope (Deferred)

* Writing Phase 03 implementation specs - Reason: Session 07 only closes Phase 02; `phasebuild` owns future phase structure.
* Running final release decommission gates or deleting historical material - Reason: Phase 08 owns final release hardening and legacy decommission.
* Implementing web-to-Worker War Room federation - Reason: Phase 05 owns the web federation surface.
* Implementing agent orchestration controls such as spawn, resume, stop, fork, or handoff - Reason: Phase 03 owns orchestration.
* Claiming hosted auth, hosted storage, analytics, public replay hosting, push backend delivery, or production database requirements - Reason: Later phases own hosted-service guardrails.
* Full mobile collaboration validation or WCAG certification - Reason: Session 07 performs browser closeout for Phase 02 supported viewports, not a certification program.

***

## 5. Technical Approach

### Architecture

Use existing validation infrastructure before adding new harnesses. Root Playwright projects already start the app and public demo servers, exercise desktop/mobile viewports, capture screenshots, and install browser guards for page errors, console errors, failed local requests, and failed asset requests. Extend these tests only if closeout evidence is missing.

Keep quality gates command-driven and reproducible from the repository root. Use `npm run battlefield:check` for app/demo asset parity, focused Playwright commands for browser validation, root Vitest for unit and integration coverage, and Biome/typecheck commands for static quality. Record exact commands, pass/fail status, and blockers in implementation notes.

Treat stable docs as the release-facing product contract. Docs should describe the shipped local-first product surface, the standalone public demo, privacy and local retention boundaries, and explicit deferred surfaces. Do not copy raw historical content from `EXAMPLES/`, and do not change product scope while closing documentation.

### Design Patterns

* Evidence-first validation: Capture command output summaries, screenshots, browser guard results, and manual visual observations before changing docs.
* Small corrective fixes: If validation finds a blocking app, demo, test, or docs issue, fix the narrow cause and rerun the affected gate before closeout.
* Local-first boundary language: Preserve clear wording that core workflows do not require hosted accounts, analytics, provider transfer, push backend, or War Room federation.
* Stable-doc single source: Update docs and README files to point to current PRD, UX PRD, API, privacy, battlefield, public demo, and release sources instead of duplicating obsolete historical detail.
* Deferral discipline: Record remaining gaps for later phases without starting new feature implementation.

### Technology Stack

* React 18.3.1, Vite 6.4.2, TypeScript 5.9.3, and Zustand in `apps/web`.
* Static no-build public demo under `public-demo/`.
* Express 4 and `ws` 8.21.0 local runtime for app e2e hydration.
* Vitest 4.1.7, Playwright 1.60.0, Testing Library, and happy-dom for tests.
* Biome 2.4.16 for format and lint checks.
* Node.js 20 for root validation commands.

***

## 6. Deliverables

### Files to Create

| File                                                                                                                   | Purpose                                                                              | Est. Lines |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------- |
| `.spec_system/specs/phase02-session07-product-surface-validation-and-documentation-closeout/implementation-notes.md`   | Command log, browser evidence, decisions, blockers, fixes, and remaining-gap handoff | \~180      |
| `.spec_system/specs/phase02-session07-product-surface-validation-and-documentation-closeout/security-compliance.md`    | Privacy and security closeout for Phase 02 browser-facing surfaces                   | \~120      |
| `.spec_system/specs/phase02-session07-product-surface-validation-and-documentation-closeout/validation.md`             | Final validation report for Session 07 and Phase 02 readiness                        | \~180      |
| `.spec_system/specs/phase02-session07-product-surface-validation-and-documentation-closeout/IMPLEMENTATION_SUMMARY.md` | Session closeout summary and next-step handoff                                       | \~100      |

### Files to Modify

| File                                                      | Changes                                                                                            | Est. Lines |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------- |
| `tests/e2e/app.e2e.ts`                                    | Extend closeout browser coverage if validation evidence is missing                                 | \~80       |
| `tests/e2e/public-demo.e2e.ts`                            | Extend demo, offline, guard, or screenshot coverage if validation evidence is missing              | \~80       |
| `tests/e2e/support/browserGuards.ts`                      | Tighten browser guard diagnostics only if e2e evidence needs better failure detail                 | \~40       |
| `README.md`                                               | Align shipped Phase 02 product-surface summary, boundaries, and known gaps                         | \~50       |
| `apps/web/README_web.md`                                  | Confirm app cockpit contract after Phase 02 validation and document any remaining validation notes | \~50       |
| `public-demo/README_public-demo.md`                       | Confirm standalone demo contract, synthetic data, assets, audio, offline, and limitation wording   | \~40       |
| `public-demo/docs_public-demo/validation.md`              | Align manual and automated validation checklist with final browser evidence                        | \~40       |
| `docs/README_docs.md`                                     | Refresh stable-doc routing and Phase 02 closeout status                                            | \~40       |
| `docs/ARCHITECTURE.md`                                    | Align current product-surface architecture and deferred War Room/orchestration/hosted boundaries   | \~40       |
| `docs/battlefield.md`                                     | Record final Phase 02 browser validation expectations and asset parity status                      | \~40       |
| `docs/public-demo-code-sharing.md`                        | Confirm no-build, no-workspace-import, static artifact, and manual parity boundary                 | \~30       |
| `docs/privacy-and-security.md`                            | Refresh Phase 02 browser privacy posture and remaining release risks                               | \~40       |
| `docs/release.md`                                         | Add Phase 02 closeout gates and keep Phase 08 decommission boundaries clear                        | \~40       |
| `docs/legacy-consolidation.md`                            | Add Phase 02 retained product-surface value and historical evidence boundaries                     | \~50       |
| `.spec_system/PRD/PRD.md`                                 | Update Phase 02 status language after validation evidence is complete                              | \~40       |
| `.spec_system/PRD/PRD_UX.md`                              | Update UX status language and closeout evidence references after validation                        | \~40       |
| `.spec_system/PRD/phase_02/PRD_phase_02.md`               | Mark Session 07 complete during implementation closeout, not during planning                       | \~30       |
| `.spec_system/PRD/phase_02/product_surface_gap_matrix.md` | Update Session 07 acceptance evidence and remaining deferrals                                      | \~30       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] App desktop and mobile Playwright projects pass or have explicit blockers with reproduction steps, screenshots, and failing guard output.
* [ ] Public demo desktop and mobile Playwright projects pass or have explicit blockers with reproduction steps, screenshots, and failing guard output.
* [ ] Browser validation records console/page errors, failed local requests, failed asset requests, battlefield dimensions, image loading or fallback states, and obvious UI overlap observations.
* [ ] Public demo offline reload after one online visit is validated or an explicit service-worker blocker is documented.
* [ ] Root quality gates pass or documented blockers are explicit: format check, lint, typecheck, Vitest, battlefield asset parity, e2e, `git diff --check`, ASCII, and LF checks.
* [ ] Stable docs distinguish shipped Phase 02 behavior from deferred War Room federation, agent orchestration, media pipeline, hosted services, collaboration, analytics, public replay hosting, push backend, and release decommission work.
* [ ] Security and privacy closeout confirms local-first defaults, redaction boundaries, browser localStorage/replay/export/scan posture, public demo synthetic-data boundary, and remaining release risks.
* [ ] Implementation summary and remaining-gap list are ready for `validate` and then `updateprd`.

### Testing Requirements

* [ ] Browser e2e validation covers app desktop, app mobile, public demo desktop, and public demo mobile.
* [ ] Unit/integration test suite passes with root `npm test` or explicit blockers.
* [ ] `npm run battlefield:check` passes for app/demo asset parity.
* [ ] Static quality gates pass for formatting, linting, and typechecking.
* [ ] Manual screenshot review checks no obvious text overlap, clipped controls, blank panels, or missing battlefield assets in captured desktop/mobile evidence.

### Non-Functional Requirements

* [ ] No docs or reports copy raw prompts, command bodies, provider errors, token-like values, OAuth IDs, probe output, or sensitive local paths.
* [ ] Core docs preserve the local-first posture and do not imply hosted account, hosted persistence, analytics, push backend, provider transfer, or War Room federation are required.
* [ ] Public demo docs preserve synthetic-data and no-workspace-import boundaries.
* [ ] Historical `EXAMPLES/` material remains evidence only and is not promoted, copied, transformed, or deleted.

### Quality Gates

* [ ] All spec-system output files are ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code and docs follow existing workspace patterns.
* [ ] Implementation notes capture command evidence, browser evidence, blockers, fixes, and remaining risks.

***

## 8. Implementation Notes

### Key Considerations

* The project-level `.spec_system/CONVENTIONS.md` currently contains only a pointer, so this spec follows concrete workspace rules from `docs/development.md`, package READMEs, current Phase 02 specs, and root scripts.
* Session 06 validation recorded a PASS with the full root Vitest suite, focused Biome checks, app/server typechecks, and `git diff --check`; Session 07 should rerun current gates instead of relying on old evidence.
* The e2e tests already cover app and public demo desktop/mobile projects, screenshot attachments, browser guards, battlefield nonzero sizes, asset loading, public demo interaction, and offline reload. Extend them only where closeout evidence is materially missing.
* Public demo validation must use the `/factionos/` path-prefixed server shape, not only direct file opening or root-path serving.
* Stable docs should preserve concise product truth. Avoid duplicating long historical context or copying raw historical content.
* Do not mark Phase 02 complete in PRD state during planning. That belongs to implementation closeout after validation evidence exists.

### Potential Challenges

* Long-running quality gates: Mitigate by running focused e2e and static gates first, then root suites, and recording exact blockers if a gate is environmental.
* Browser flake from service worker state: Mitigate with fresh browser context behavior already built into Playwright and the path-prefixed demo server.
* Port conflicts: Mitigate by using Playwright `reuseExistingServer` behavior or documented `FACTIONOS_E2E_WEB_PORT` and `FACTIONOS_E2E_DEMO_PORT` overrides when needed.
* Screenshot review subjectivity: Mitigate by recording concrete observations: nonzero board dimensions, visible controls, readable labels, no clipped buttons, and no obvious overlap.
* Documentation overclaiming: Mitigate by cross-checking README, PRD, UX PRD, architecture, privacy, release, battlefield, and public demo docs against the gap matrix and known deferred rows.
* Historical-content leakage: Mitigate by citing historical paths only for traceability and never copying raw prompts, probe output, token values, OAuth IDs, or sensitive local paths.

### Relevant Considerations

* \[P01] **Stable docs are the current contract**: This session must align README files, stable docs, PRD, UX PRD, and the gap matrix with the implemented Phase 02 surface.
* \[P00-apps/web] **Responsive and accessibility debt**: Browser validation must inspect desktop/mobile screenshots, focusable controls, readable labels, nonzero battlefield dimensions, and obvious overlap.
* \[P01] **Redaction is boundary-specific**: Closeout docs and reports must preserve replay, export, scan, notification, browser localStorage, archive, and LLM redaction boundaries.
* \[P00] **Asset provenance gate**: Asset validation should confirm the app/demo generated battlefield set, parity check, public demo service worker coverage, and no promotion from quarantined `EXAMPLES/`.
* \[P01-apps/web] **Scan-root UX needs follow-through**: Final docs and validation should confirm `FACTIONOS_SCAN_ROOTS` failures and scan-root privacy copy are accurately represented.
* \[P01-apps/warroom+apps/web] **War Room is not wired into the web runtime yet**: Phase 02 docs must keep web federation deferred to Phase 05.
* \[P01] **Phase complete is not release complete**: Phase 02 closeout must not imply trusted erasure, final decommission, hosted analytics, hosted auth, or broader release hardening is done.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Browser validation can miss blank, overlapping, or off-screen UI if screenshots are captured but not reviewed against concrete criteria.
* E2E tests can hide real runtime issues if console/page-error and failed-request guards are not asserted after interactions.
* Documentation closeout can overclaim deferred surfaces as shipped or imply local redacted artifacts are public-safe.
* Public demo offline validation can pass a root-path local server while failing the deployed `/factionos/` path shape.
* Security reports can accidentally copy raw command output, paths, or probe details while documenting blockers.

***

## 9. Testing Strategy

### Unit Tests

* Run root `npm test` to cover protocol, server, hooks, CLI, adapters, Worker, web helpers, and component behavior.
* If browser validation exposes narrow helper regressions, add or extend focused Vitest tests near the owning package before rerunning the root suite.

### Integration Tests

* Run `npm run battlefield:check` to verify app/demo battlefield hashes, byte budgets, service-worker precache, public demo import boundaries, and stable docs references.
* Run `npm run test:e2e -- --project=app-desktop --project=app-mobile tests/e2e/app.e2e.ts`.
* Run `npm run test:e2e -- --project=public-demo-desktop --project=public-demo-mobile tests/e2e/public-demo.e2e.ts`.
* Review Playwright attachments for desktop/mobile app and public demo screenshots, battlefield board screenshots, visual overlay screenshots, and offline shell screenshot.

### Manual Testing

* Inspect generated Playwright screenshots for blank panels, missing art, zero-size battlefield, clipped controls, overlapping text, unreadable labels, inaccessible-looking icon-only controls, and modal overflow.
* Confirm public demo copy says data is synthetic and no local server, LLM endpoint, plan workpad, persistent server state, hosted replay, or War Room federation is active.
* Confirm stable docs and package README files route users to current PRD, UX PRD, API, battlefield, public demo, privacy, development, and release sources.

### Edge Cases

* App local server unavailable or WebSocket reconnecting while the cockpit should stay visible.
* Battlefield background or hero asset fallback states.
* Mobile viewport stacking and rail scrolling.
* Public demo path-prefix service-worker scope.
* Public demo offline reload after one online visit.
* Browser console errors, page errors, failed local requests, and failed asset requests.
* Docs accidentally marking deferred hosted, War Room, orchestration, push, analytics, or release-decommission work as shipped.

***

## 10. Dependencies

### External Libraries

* Playwright: 1.60.0
* Vitest: 4.1.7
* Biome: 2.4.16
* React: 18.3.1
* Vite: 6.4.2
* TypeScript: 5.9.3

### Other Sessions

* **Depends on**: `phase02-session01-product-surface-requirements-reconciliation`, `phase02-session02-cockpit-shell-and-navigation-cohesion`, `phase02-session03-hero-and-mission-workflow-completion`, `phase02-session04-battlefield-state-and-interaction-polish`, `phase02-session05-battlefield-asset-and-public-demo-parity`, `phase02-session06-settings-replay-notifications-and-scan-ux`
* **Depended by**: Phase 02 `validate`, `updateprd`, and phase-transition `audit` workflow steps

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase02-session07-product-surface-validation-and-documentation-closeout/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.