> 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/phases/phase_02/prd_phase_02.md). # PRD Phase 02: Product Surface and 2D Battlefield Completion **Status**: Complete **Sessions**: 7 **Estimated Duration**: 7-14 days **Progress**: 7/7 sessions (100%) *** ## Overview Phase 02 turns the hardened local runtime from Phase 01 into a coherent browser-facing product surface. It reconciles the product and UX requirements with current implementation, completes the web cockpit workflows that sit on top of the local runtime, finishes the asset-driven 2D battlefield behavior, keeps the public demo aligned, and closes browser-facing validation gaps. This phase stays local-first. It does not wire web War Room federation, build the broader media catalog pipeline, implement hosted services or analytics, replace agent orchestration, or run final legacy decommission gates. Session 01 produces the Phase 02 requirements baseline: * Expanded product requirements in `.spec_system/PRD/PRD.md`. * Expanded UX requirements in `.spec_system/PRD/PRD_UX.md`. * Product surface routing matrix in `.spec_system/archive/phases/phase_02/product_surface_gap_matrix.md`. * Historical-source and asset-quarantine boundaries in `docs/legacy-consolidation.md`. Sessions 02 through 07 should use the gap matrix as the first routing table for current source evidence, required behavior, acceptance notes, owner session, and deferral boundaries. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ----------------------------------------------------- | --------- | ---------- | ---------- | | 01 | Product Surface Requirements Reconciliation | Completed | \~14-18 | 2026-05-29 | | 02 | Cockpit Shell and Navigation Cohesion | Completed | \~16-22 | 2026-05-29 | | 03 | Hero and Mission Workflow Completion | Completed | \~16-22 | 2026-05-29 | | 04 | Battlefield State and Interaction Polish | Completed | \~16-24 | 2026-05-29 | | 05 | Battlefield Asset and Public Demo Parity | Completed | \~14-20 | 2026-05-29 | | 06 | Settings Replay Notifications and Scan UX | Completed | \~16-22 | 2026-05-29 | | 07 | Product Surface Validation and Documentation Closeout | Completed | \~12-18 | 2026-05-29 | *** ## Completed Sessions * Session 01: Product Surface Requirements Reconciliation - completed 2026-05-29 * Session 02: Cockpit Shell and Navigation Cohesion - completed 2026-05-29 * Session 03: Hero and Mission Workflow Completion - completed 2026-05-29 * Session 04: Battlefield State and Interaction Polish - completed 2026-05-29 * Session 05: Battlefield Asset and Public Demo Parity - completed 2026-05-29 * Session 06: Settings Replay Notifications and Scan UX - completed 2026-05-29 * Session 07: Product Surface Validation and Documentation Closeout - implemented 2026-05-29 *** ## Upcoming Sessions No remaining Phase 02 implementation sessions. Next workflow step: audit. ## Session Output Contract | Session | Consumes from Session 01 | Primary output | | ------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | 02 | PRD shell requirements, UX shell requirements, gap matrix Session 02 rows | Cohesive cockpit shell, navigation, command palette, shortcuts, settings entry, and honest War Room stub treatment. | | 03 | PRD workflow requirements, UX workflow requirements, gap matrix Session 03 rows | Completed hero, mission, permission, plan, and contextual overlay workflows. | | 04 | Battlefield requirements, UX battlefield requirements, gap matrix Session 04 rows | Polished 2D battlefield state, selection, accessibility, reduced motion, and failure behavior. | | 05 | Asset/public-demo requirements, media boundaries, gap matrix Session 05 rows | App and public demo battlefield asset parity with provenance and standalone demo constraints. | | 06 | Settings/replay/notification/scan requirements and gap matrix Session 06 rows | Clear local settings, replay, export, notification, and scan-root UX with privacy-preserving failure paths. | | 07 | All requirements, matrix rows, stable docs, and implementation output from Sessions 02-06 | Browser validation, documentation closeout, and Phase 02 readiness evidence. | ## Phase 02 Exclusions Phase 02 must keep these surfaces out of implementation scope unless a later approved spec changes ownership: * Web-to-Worker War Room federation beyond honest stub/separate-surface treatment. * Hosted auth, hosted storage, analytics dashboards, public replay hosting, or production database requirements. * Agent orchestration features such as spawn/resume/stop/fork/handoff controls. * Media catalog pipeline, broad voice/SFX/music cataloging, and unknown provenance media promotion. * Mobile collaboration and multi-user presence. * Deletion or final reduction of `EXAMPLES/`, `docs/PROGRESS.md`, extraction reports, or historical source groups. *** ## Objectives 1. Rebuild product and UX requirements into stable spec-managed source files. 2. Make the web cockpit's primary workflows coherent against the current local runtime. 3. Complete app-side 2D battlefield state, interaction, accessibility, and reduced-motion behavior. 4. Keep battlefield assets and public demo behavior aligned without promoting quarantined historical media. 5. Validate and document the Phase 02 browser-facing product contract. *** ## Prerequisites * Phase 01 completed. * Current local runtime docs and API contracts are stable. * Current 2D battlefield assets remain available in app and public demo paths. * `EXAMPLES/` remains quarantined evidence only. *** ## Technical Considerations ### Architecture The web product surface consumes the hardened local server and protocol contracts from Phase 01. Shared event, mission, hero, replay, and notification shapes should continue to originate in `packages/protocol` before app code duplicates them. The public demo remains a standalone no-build artifact and must not import workspace packages. ### Technologies * React 18, Vite, TypeScript, Tailwind, and Zustand in `apps/web` * Express and WebSocket local runtime in `apps/server` * Shared TypeScript contracts in `packages/protocol` * Public demo static HTML, CSS, JavaScript, and service worker * Vitest, Testing Library, Playwright, Biome, and npm workspace scripts ### Risks * Product drift: reconcile PRD and UX requirements before changing surfaces. * Battlefield regressions: keep DOM hit targets, labels, motion, and fallback paths covered by tests. * Asset provenance: update only owned or generated assets and record any changes in stable docs. * Privacy exposure: replay, export, notifications, settings, and scan-root errors must not leak raw prompts, paths, tokens, or provider inputs. * Scope bleed: defer War Room federation, full mobile collaboration, hosted analytics, and release decommission to their later phases. ### Relevant Considerations * \[P01-apps/web] **Scan-root UX needs follow-through**: settings and scan workflows should explain approved-root failures clearly. * \[P01] **Redaction is boundary-specific**: replay, export, notification, settings, and scan UX must preserve Phase 01 redaction posture. * \[P01-packages/protocol] **Protocol leads cross-package work**: add shared shapes before wiring web or server behavior. * \[P00] **Asset provenance gate**: no battlefield or showcase media should ship from quarantined historical artifacts. * \[P00-apps/web] **Responsive and accessibility debt**: product surface work should verify focus, reduced motion, contrast, and non-overlap on supported web viewports. * \[P01] **Stable docs are the current contract**: use README files, `docs/api/`, architecture, privacy, release, and legacy-consolidation docs as current truth. *** ## Success Criteria Phase complete when: * [ ] All 7 sessions completed. * [ ] Product and UX requirements reflect the current web surface and planned phase boundaries. * [ ] Phase 02 sessions use the product surface gap matrix for source, acceptance, owner, and deferral decisions. * [ ] Cockpit shell, hero, mission, overlay, replay, settings, notification, and scan-root workflows are coherent and tested. * [ ] App-side 2D battlefield behavior is polished, accessible, reduced-motion aware, and browser-validated. * [ ] Public demo battlefield assets and behavior remain aligned with the app-owned asset set. * [ ] Stable docs identify shipped, planned, deferred, and excluded Phase 02 behavior. *** ## Dependencies ### Depends On * Phase 01: Core Runtime Hardening ### Enables * Phase 03: Agent Orchestration --- # 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/phases/phase_02/prd_phase_02.md?ask=&goal= ``` `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.