> 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/product_surface_gap_matrix.md).

# Phase 02 Product Surface Gap Matrix

This matrix routes Phase 02 browser-facing product work from current source state to acceptance criteria and owning follow-up sessions. It is requirements source material, not an implementation changelog.

## Matrix Schema

| Column                         | Required content                                                       |
| ------------------------------ | ---------------------------------------------------------------------- |
| Surface                        | User-facing product area or workflow.                                  |
| Current source                 | Current source, tests, docs, or asset paths used as evidence.          |
| Current state                  | Shipped, partial, stubbed, deferred, excluded, or evidence-only state. |
| Phase 02 requirement           | Required product behavior for this phase.                              |
| Acceptance notes               | Observable checks a later session can validate.                        |
| Owner session                  | Phase 02 session responsible for implementation or validation.         |
| Deferral or exclusion boundary | Later-phase owner or explicit non-goal.                                |

## Status Values

| Status        | Use                                                                        |
| ------------- | -------------------------------------------------------------------------- |
| Shipped       | Current source implements the behavior and stable docs can claim it.       |
| Partial       | Current source exists but needs Phase 02 completion or polish.             |
| Stubbed       | Current UI or API is a placeholder that must not be described as complete. |
| Phase 02      | Required in one of the remaining Phase 02 sessions.                        |
| Deferred      | Planned after Phase 02.                                                    |
| Excluded      | Not in scope unless a future PRD changes the decision.                     |
| Evidence only | Historical or quarantined source that can support traceability only.       |

## Product Surface Matrix

Rows are grouped by follow-up session. Session 01 owns this matrix and requirements reconciliation only; Sessions 02 through 07 own implementation and validation.

### Session 02 - Cockpit Shell And Navigation Cohesion

| Surface                             | Current source                                                                                                                                        | Current state                                      | Phase 02 requirement                                                                                                                               | Acceptance notes                                                                                                                                                  | Owner session | Deferral or exclusion boundary                                                              |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------- |
| Shell layout and rails              | `apps/web/src/App.tsx`, `apps/web/src/components/Layout.tsx`, `apps/web/src/components/TitleBar.tsx`, `apps/web/tests/keyboardShortcuts.test.ts`      | Partial                                            | Make battlefield, mission log, notices, roster, scrolls, quest board, War Room status, settings, and global overlays feel like one stable cockpit. | Desktop and mobile viewport checks show no overlapping controls, battlefield remains visible, rail content remains reachable, and top controls are discoverable.  | Session 02    | Do not add a landing page or hosted dashboard.                                              |
| Connection and local runtime status | `TitleBar.tsx`, `useWsClient.ts`, `useGameStore.ts`, `docs/api/README_api.md`                                                                         | Shipped, needs clearer surfacing                   | Show local server connection state and fallback behavior without implying hosted availability.                                                     | Server unavailable, connecting, open, and closed states have visible status and do not blank the cockpit.                                                         | Session 02    | Hosted account and cloud status indicators are deferred to Phase 07.                        |
| Settings entry point                | `SettingsDrawer.tsx`, `useSettingsStore.ts`, `apps/web/tests/useSettingsStore.test.ts`                                                                | Shipped                                            | Keep settings reachable from the shell with accessible name, stable position, close behavior, and no overlap with main controls.                   | Keyboard and pointer users can open and close settings; panel fits supported viewports.                                                                           | Session 02    | Deep settings redesign belongs to Session 06.                                               |
| Global keyboard shortcuts           | `useKeyboardShortcuts.ts`, `KeyboardShortcutsModal.tsx`, `apps/web/tests/keyboardShortcuts.test.ts`, `apps/web/tests/KeyboardShortcutsModal.test.tsx` | Shipped, needs product polish                      | Preserve shortcut routing while preventing input hijacking and exposing help from the shell.                                                       | Typing targets are ignored, `?` opens help, Escape closes supported overlays, and help labels match implemented routes.                                           | Session 02    | No OS-level global shortcuts.                                                               |
| Command palette                     | `CommandPalette.tsx`, `lib/commandPalette.ts`, command palette tests                                                                                  | Shipped, needs cohesion                            | Keep command ranking, keyboard navigation, overlay routes, settings toggles, and deep links aligned with visible product surfaces.                 | Palette opens from shortcut and shell, active item remains visible, actions route to the intended overlay or setting, and disabled/unavailable behavior is clear. | Session 02    | Do not expose commands for deferred hosted, Worker federation, or release cleanup features. |
| War Room shell panel                | `WarRoomPanel.tsx`, `apps/warroom/README_warroom.md`, `docs/api/README_api.md`                                                                        | Stubbed web panel, separate Worker backend shipped | Present the web panel as stubbed or separate-surface status only.                                                                                  | UI copy and status do not imply live web-to-Worker federation; links point to Worker docs or later phase.                                                         | Session 02    | Phase 05 owns web War Room federation.                                                      |

### Session 03 - Hero And Mission Workflow Completion

| Surface                     | Current source                                                                                                          | Current state                    | Phase 02 requirement                                                                                                                                   | Acceptance notes                                                                                                                                                | Owner session | Deferral or exclusion boundary                                                      |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------- |
| Hero roster                 | `HeroRoster.tsx`, `HeroCard.tsx`, `useSettingsStore.ts`, roster tests                                                   | Shipped, needs workflow polish   | Make roster sorting, selection, state, metrics, specialization, efficiency, and active mission cues clear and keyboard reachable.                      | State and activity sort modes are visible, active selection syncs with battlefield/detail, and cards expose accessible labels for key status.                   | Session 03    | Agent spawn/resume orchestration controls are Phase 03.                             |
| Hero detail                 | `HeroDetailDrawer.tsx`, hero detail tests, hero analytics helpers                                                       | Shipped, needs hierarchy polish  | Prioritize current state, active work, recent history, achievements, specialization, efficiency, tool usage, and complexity without raw event dumping. | Drawer opens from roster/battlefield context, close control is accessible, empty sections have useful copy, and sensitive text is redacted where applicable.    | Session 03    | Hosted profile, team, or account identity is deferred.                              |
| Mission log                 | `MissionLog.tsx`, `lib/missionTags.ts`, mission log tests                                                               | Shipped, needs completion polish | Keep search, state filters, inferred tags, click-through rows, empty state, and active/completed/error treatment coherent.                             | Keyboard users can open mission detail from rows, filters are visibly active and reversible, and search/tag empty states explain why no rows match.             | Session 03    | Full task queue management is deferred to later orchestration phases.               |
| Mission detail and timeline | `MissionDetailDrawer.tsx`, `MissionTimeline.tsx`, mission detail and timeline tests                                     | Shipped                          | Show prompt summary, state, timing, tool steps, tokens, costs, and failure data while preserving redaction boundaries.                                 | Detail drawer labels sections, timeline has a text summary, and missing metrics degrade without layout breakage.                                                | Session 03    | Hosted replay or public sharing is deferred.                                        |
| Permission context          | `PermissionModal.tsx`, WebSocket client messages, `docs/api/README_api.md`                                              | Shipped                          | Explain requester, action, rationale, expiry or pending state, and accepted/rejected result without duplicate decision risk.                           | Duplicate clicks do not produce duplicate resolution, resolved requests disappear or show completed status, and inaccessible permission details are not leaked. | Session 03    | Stronger remote approval and room-based participant controls are Phase 05 or later. |
| Plan context                | `PlanWorkpad.tsx`, protocol plan shapes, plan approval API docs                                                         | Shipped                          | Show generated plan steps, approval state, requester context, and failure state in a way that aligns with local runtime contract.                      | Approve/reject controls are clear, repeat responses are ignored or disabled, and no provider-transfer claim appears unless configured.                          | Session 03    | Agent orchestration and multi-agent handoff controls are Phase 03.                  |
| Overlay context links       | `MissionHeatmap.tsx`, `FactionStandings.tsx`, `Leaderboard.tsx`, `ToolUsageOverlay.tsx`, `MissionComplexityOverlay.tsx` | Shipped analytics overlays       | Ensure overlays route back to hero or mission context without losing selection clarity.                                                                | Overlay rows that open hero or mission detail have accessible labels and preserve expected selected context.                                                    | Session 03    | Hosted analytics dashboards are Phase 07 and not current product.                   |

### Session 04 - Battlefield State And Interaction Polish

| Surface                        | Current source                                                                  | Current state                       | Phase 02 requirement                                                                                                                                  | Acceptance notes                                                                                                                                                          | Owner session | Deferral or exclusion boundary                                               |
| ------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------- |
| 2D battlefield board           | `Battlefield.tsx`, `battlefield2d.ts`, `docs/battlefield.md`, battlefield tests | Shipped, needs polish               | Preserve the asset-driven 2D DOM battlefield with stable 16:9 board, fallback background, readable center, and clamped hero positioning.              | Desktop and mobile screenshots show nonzero board dimensions, readable labels, and no blank board on image failure.                                                       | Session 04    | No return to Three.js, WebGL, canvas physics, Phaser, or PixiJS in Phase 02. |
| Hero token interaction         | `Battlefield.tsx`, `HeroRoster.tsx`, `HeroDetailDrawer.tsx`                     | Shipped                             | Keep hero tokens as native buttons with accessible names, `aria-pressed`, pointer and keyboard selection, and empty-board clear behavior.             | Selecting via battlefield, roster, and detail context remains synchronized; clicking selected token toggles off; click propagation does not clear selection accidentally. | Session 04    | Multi-select battle commands are deferred.                                   |
| Battlefield state treatment    | `Battlefield.tsx`, `index.css`, `docs/battlefield.md`                           | Shipped, needs accessibility review | Active, awaiting input, verifying, error, spawning, dismissed, selected, and idle states must be distinct without relying only on animation or color. | Reduced-motion mode still shows static labels/rings; color-only states have text or shape support; state labels remain readable.                                          | Session 04    | Gameplay combat simulation is excluded.                                      |
| Achievement battlefield bursts | `achievementCelebration.ts`, `Battlefield.tsx`, celebration tests               | Shipped                             | Keep bursts bounded, nonblocking, timer-cleaned, and reduced-motion compatible.                                                                       | New unlocks create no more than the concurrent cap, timers clean up on unmount, and reduced motion disables nonessential animation.                                       | Session 04    | Full particle engine or sound pipeline is Phase 04 or later.                 |

### Session 05 - Battlefield Asset And Public Demo Parity

| Surface                        | Current source                                                                             | Current state                  | Phase 02 requirement                                                                                                                               | Acceptance notes                                                                                                                                                   | Owner session | Deferral or exclusion boundary                                           |
| ------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------ |
| App battlefield assets         | `apps/web/public/battlefield/`, `assets/battlefield-2d/reference/`, `docs/media-assets.md` | Shipped approved generated set | Validate current background and five standees against readability, size budget, paths, and provenance.                                             | All six app asset paths exist, load in browser checks, remain under documented budget, and match the media asset record.                                           | Session 05    | Direct `EXAMPLES/` media promotion is excluded.                          |
| Public demo battlefield assets | `public-demo/assets/battlefield/`, `public-demo/sw.js`, public demo tests                  | Shipped mirror                 | Keep demo assets aligned with app-approved assets and service worker precache.                                                                     | Demo asset paths exist, service worker references current paths, cache version changes when precache changes, and offline reload passes after one online visit.    | Session 05    | Demo must not import `apps/web` or `@factionos/protocol`.                |
| Public demo behavior parity    | `public-demo/index.html`, `docs/public-demo-code-sharing.md`, public demo docs             | Partial mirror                 | Mirror visible battlefield, roster, heatmap, standings, command, achievement, audio, and replay concepts only where the standalone demo owns them. | Demo clearly uses synthetic data, keeps no-build operation, and labels limitations for hooks, LLM, plan workpad, War Room federation, and persistent server state. | Session 05    | Real local sessions and Worker federation are excluded from static demo. |
| Asset provenance and promotion | `docs/media-assets.md`, `docs/battlefield.md`, `docs/legacy-consolidation.md`              | Shipped policy                 | Any new or changed media must be generated or owned, recorded, optimized, measured, smoke-tested, and routed through stable docs.                  | Promotion record includes source, dimensions or duration, size, runtime path, decision, caveat, and release blocker status where relevant.                         | Session 05    | Unknown provenance remains a release blocker.                            |

### Session 06 - Settings Replay Notifications And Scan UX

| Surface                         | Current source                                                                      | Current state                       | Phase 02 requirement                                                                                                                                                  | Acceptance notes                                                                                                              | Owner session | Deferral or exclusion boundary                                  |
| ------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------- |
| Settings preferences            | `SettingsDrawer.tsx`, `useSettingsStore.ts`, settings tests                         | Shipped                             | Keep faction, theme, audio, reduced motion, severity, mock, notifications, scan root, replay entry, reset, and local auth behavior coherent.                          | Settings recover from malformed localStorage, controls have accessible labels, and reset behavior is visible.                 | Session 06    | Hosted account preferences are deferred.                        |
| Browser notifications           | `notifications.ts`, `useNotifications.ts`, `SettingsDrawer.tsx`, notification tests | Shipped opt-in                      | Make unsupported, default, denied, granted, throttled, delivered, and test paths explicit.                                                                            | Toggle and test actions produce visible feedback and never imply push backend delivery.                                       | Session 06    | Push backend is not shipped.                                    |
| Replay scrubber and share links | `ReplayPanel.tsx`, `useGameStore.ts`, `replayLink.ts`, replay tests                 | Shipped, needs UX polish            | Keep replay window controls, persisted local ring, redacted share links, malformed-link handling, and feedback-loop prevention clear.                                 | Shared replay token redacts sensitive fields, caps event size, strips consumed hash, and reports replay outcome to the user.  | Session 06    | Hosted replay storage and public replay galleries are deferred. |
| Session export                  | `lib/exportSession.ts`, server export route, export tests, API docs                 | Shipped local export                | UI must preserve CSV/JSON choice, local server dependency, failure feedback, and Phase 01 redaction guarantees.                                                       | Export failures produce visible local errors; downloaded payloads use server privacy headers and redacted schemas.            | Session 06    | Hosted exports are deferred.                                    |
| Scan-root UX                    | `SettingsDrawer.tsx`, server scan docs, `docs/privacy-and-security.md`, scan tests  | Shipped, needs clearer failure copy | Explain explicit root requirement, approved-root allowlist, invalid root, no symlink, file cap, and provider-transfer boundaries without broad absolute-path leakage. | Empty root, invalid root, denied root, server offline, success, and issue-count paths are visible and redacted appropriately. | Session 06    | Arbitrary filesystem browsing UI is excluded.                   |

### Session 07 - Validation And Documentation Closeout

| Surface                                | Current source                                                                      | Current state                   | Phase 02 requirement                                                                                                | Acceptance notes                                                                                                                                                                                                                                                                                                                 | Owner session | Deferral or exclusion boundary                            |
| -------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------- |
| Browser validation                     | `tests/e2e/app.e2e.ts`, `tests/e2e/public-demo.e2e.ts`, `docs/battlefield.md`       | Shipped and closeout-recorded   | Validate full app and public demo desktop/mobile behavior after Sessions 02 through 06.                             | App desktop/mobile Playwright evidence records screenshots, browser guards, nonzero dimensions, loaded/fallback art states, and no canvas path. Public demo desktop/mobile evidence records splash/cockpit/board/overlay screenshots, limitation copy, service-worker readiness, and offline reload after one online visit.      | Session 07    | Production hosted validation is Phase 07 or release work. |
| Stable docs alignment                  | `README.md`, `docs/README_docs.md`, `docs/ARCHITECTURE.md`, PRD, UX PRD, gap matrix | Shipped closeout alignment      | Ensure stable docs identify shipped, Phase 02, deferred, excluded, and evidence-only behavior after implementation. | README files, architecture, battlefield, public-demo sharing, public-demo validation, privacy, release, PRD, UX PRD, and this matrix now separate shipped Phase 02 behavior from deferred War Room, orchestration, media, hosted-service, collaboration, analytics, release-decommission, and evidence-only historical material. | Session 07    | Phase 08 owns final deletion.                             |
| Accessibility and reduced motion audit | Web components, tests, UX PRD                                                       | Shipped with scoped browser fix | Verify focus, labels, keyboard access, non-overlap, contrast, and reduced-motion behavior across changed surfaces.  | Browser validation and screenshot review found and fixed a small-viewport public demo header overlap; app and demo tests retain accessible names, `aria-pressed`, nonzero battlefield dimensions, visible fallback labels, and reduced-motion/fallback unit coverage.                                                            | Session 07    | Full WCAG certification is not claimed.                   |

## Boundary Rows

| Surface                           | Current source                                                      | Current state                             | Phase 02 requirement                                                                                      | Acceptance notes                                                          | Owner session | Deferral or exclusion boundary                          |
| --------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------- | ------------------------------------------------------- |
| Web War Room federation           | `apps/warroom/`, `WarRoomPanel.tsx`, API docs                       | Worker backend shipped, web panel stubbed | Keep Phase 02 docs honest that full web-to-Worker federation is not shipped.                              | PRD, UX PRD, README, and matrix consistently mark this deferred.          | Session 01    | Phase 05 owns integration.                              |
| Hosted services and analytics     | `docs/hosted-services.md`, `docs/privacy-and-security.md`, ADR 0003 | Deferred                                  | Do not introduce hosted auth, hosted storage, analytics dashboards, or tracking requirements in Phase 02. | Requirements say optional/deferred and local-first fallback remains core. | Session 01    | Phase 07 owns hosted-service and analytics guardrails.  |
| Historical media and build output | `EXAMPLES/`, `docs/media-assets.md`, `docs/legacy-consolidation.md` | Evidence only                             | Preserve traceability while prohibiting direct promotion into runtime or demo assets.                     | Stable docs cite policy and do not copy raw historical content.           | Session 01    | Phase 08 owns deletion gates.                           |
| Release cleanup                   | `docs/release.md`, `docs/legacy-consolidation.md`                   | Deferred                                  | Do not delete or approve deletion of historical files in Phase 02.                                        | Cleanup candidates remain candidates only.                                | Session 01    | Phase 08 owns final release hardening and decommission. |


---

# 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/product_surface_gap_matrix.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.