> 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-session02-cockpit-shell-and-navigation-cohesion/spec.md).

# Session Specification

**Session ID**: `phase02-session02-cockpit-shell-and-navigation-cohesion` **Phase**: 02 - Product Surface and 2D Battlefield Completion **Status**: Not Started **Created**: 2026-05-29 **Package**: apps/web **Package Stack**: React 18, Vite 6, TypeScript 5, Tailwind CSS 3, Zustand 4

***

## 1. Session Overview

This session makes the primary FactionOS web cockpit read as one coherent operational surface. It focuses on the shell, rails, top command area, global overlays, command palette, keyboard shortcuts, settings entry point, first-run state, local-server connection state, and the War Room status panel.

Session 01 established the Phase 02 requirements baseline and product surface gap matrix. Session 02 now applies the Session 02 matrix rows in `apps/web` without expanding into hero and mission workflow polish, battlefield behavior, public demo parity, scan UX, or real War Room federation.

The result should keep the current local-first runtime honest: the browser can show seed or fallback data when the server is down, but it must not imply hosted availability, public collaboration, or web-to-Worker federation.

***

## 2. Objectives

1. Make the cockpit shell, rails, settings entry point, and global overlay controls visible, reachable, and consistent across supported desktop and tablet-sized layouts.
2. Surface first-run, no-faction, connecting, connected, disconnected, no-server, and empty-data states without blank panels or misleading hosted-service language.
3. Align the command palette, keyboard shortcuts help, and visible shell controls so keyboard and pointer users can reach the same product surfaces without input hijacking.
4. Keep the War Room panel clearly marked as a stub or separate surface until Phase 05 owns web-to-Worker federation, and cover the behavior with focused tests and package docs.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase01-session07-runtime-contract-documentation` - Provides stable local runtime and API documentation.
* [x] `phase02-session01-product-surface-requirements-reconciliation` - Provides Phase 02 PRD, UX PRD, and product surface gap matrix.

### Required Tools/Knowledge

* Node.js 20 and npm workspace commands.
* React 18, Testing Library, happy-dom, Vitest, Tailwind CSS, and Zustand.
* Current `apps/web` shell files: `App.tsx`, `Layout.tsx`, `TitleBar.tsx`, `SettingsDrawer.tsx`, `CommandPalette.tsx`, `KeyboardShortcutsModal.tsx`, `FactionPicker.tsx`, and `WarRoomPanel.tsx`.

### Environment Requirements

* Dependencies installed from the workspace lockfile.
* Existing `apps/web` shell, command palette, keyboard shortcut, and settings tests can run before edits.
* Local server availability is optional for implementation; disconnected and no-server states must be testable without a running server.

***

## 4. Scope

### In Scope (MVP)

* Developer can identify local server status from the shell - Add clear idle, connecting, connected, and offline treatment without hosted-service claims.
* Developer can reach cockpit surfaces from visible controls - Align top controls, settings, command palette, shortcuts help, overlays, rails, and bottom panel affordances.
* Keyboard user can navigate global commands safely - Preserve input-aware shortcut guards, Escape cleanup, and command palette focus behavior.
* First-run user can select a faction without losing local-first context - Keep the faction picker accessible and explicit about local setup boundaries.
* Reviewer can see War Room is not live web federation - Replace or constrain any fake live-room implication and point to the separate Worker surface.
* Maintainer can verify shell behavior - Add focused tests for command accessibility, disconnected status, visible command parity, and stub boundaries.

### Out of Scope (Deferred)

* Full mobile redesign - Reason: Phase 02 Session 02 only needs supported desktop and tablet shell cohesion; broader mobile collaboration is Phase 06.
* Hero and mission workflow hierarchy - Reason: Session 03 owns roster, detail drawers, mission log, permission, plan, and contextual overlays.
* Battlefield state and interaction polish - Reason: Session 04 owns 2D battlefield behavior and reduced-motion validation.
* Battlefield asset or public demo parity - Reason: Session 05 owns app asset validation and static demo parity.
* Deep settings, replay, notification, export, and scan UX redesign - Reason: Session 06 owns detailed settings and scan failure paths.
* Web-to-Worker War Room federation - Reason: Phase 05 owns real federation, signed trust boundaries, and participant relay.
* Hosted auth, hosted storage, analytics dashboards, or public replay hosting - Reason: Later phases own hosted-service guardrails.

***

## 5. Technical Approach

### Architecture

Keep all runtime changes inside `apps/web`. The shell should continue consuming existing Zustand stores and protocol shapes. Add small, testable shell metadata helpers only where they reduce duplication between the title bar, command palette, tests, and documentation.

Use the existing transient-settings pattern for overlays. Settings drawer visibility should behave like the other shell overlays: controlled through shared state, reachable from visible controls, keyboard-safe, and cleaned up on Escape or outside click.

War Room work stays presentational. The web panel must describe the Worker as a separate shipped backend and the current web panel as a stub, without pretending a room join or live relay is implemented in this package.

### Design Patterns

* Controlled overlay state: Keeps settings, help, palette, and overlay commands consistent with keyboard shortcuts and visible buttons.
* Pure helper plus component tests: Keeps shell labels, status copy, and command metadata testable without broad component setup.
* Progressive status disclosure: Shows connection and local-server state in the title area without blocking the seed-data cockpit.
* Local-first copy at action boundaries: Explains unavailable or deferred surfaces where the user would otherwise expect remote behavior.

### Technology Stack

* React 18.3.1
* Vite 6.4.2
* TypeScript 5.9.3
* Tailwind CSS 3.4.6
* Zustand 4.5.4
* Vitest 4.1.7, Testing Library, happy-dom

***

## 6. Deliverables

### Files to Create

| File                                                                                                 | Purpose                                                       | Est. Lines |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase02-session02-cockpit-shell-and-navigation-cohesion/implementation-notes.md` | Implementation evidence, decisions, and validation notes      | \~80       |
| `apps/web/src/lib/cockpitShell.ts`                                                                   | Pure shell status, surface, and stub metadata helpers         | \~120      |
| `apps/web/tests/cockpitShell.test.ts`                                                                | Unit coverage for shell metadata helpers                      | \~120      |
| `apps/web/tests/CockpitShell.test.tsx`                                                               | Component coverage for shell controls and disconnected states | \~180      |

### Files to Modify

| File                                                 | Changes                                                                | Est. Lines |
| ---------------------------------------------------- | ---------------------------------------------------------------------- | ---------- |
| `apps/web/src/App.tsx`                               | Align primary rail composition and shell-level empty state affordances | \~50       |
| `apps/web/src/components/Layout.tsx`                 | Improve responsive grid, stable rail sizing, and overflow behavior     | \~60       |
| `apps/web/src/components/TitleBar.tsx`               | Make top command area the visible shell control surface                | \~160      |
| `apps/web/src/components/SettingsDrawer.tsx`         | Use controlled open state and preserve accessible dismissal behavior   | \~80       |
| `apps/web/src/components/CommandPalette.tsx`         | Align result states, focus, and unavailable/empty behavior             | \~90       |
| `apps/web/src/components/KeyboardShortcutsModal.tsx` | Align help groups and labels with current routes                       | \~50       |
| `apps/web/src/components/FactionPicker.tsx`          | Clarify first-run shell context and accessibility semantics            | \~50       |
| `apps/web/src/components/WarRoomPanel.tsx`           | Present honest stub or separate-surface status only                    | \~90       |
| `apps/web/src/lib/commandPalette.ts`                 | Align commands to visible surfaces and exclude deferred features       | \~90       |
| `apps/web/src/lib/useKeyboardShortcuts.ts`           | Keep shortcut routing consistent with controlled shell state           | \~70       |
| `apps/web/src/store/useSettingsStore.ts`             | Add transient settings drawer state                                    | \~30       |
| `apps/web/tests/CommandPalette.test.tsx`             | Cover visible-surface parity and deferred command absence              | \~80       |
| `apps/web/tests/keyboardShortcuts.test.ts`           | Cover shortcut route changes and typing-target guards                  | \~70       |
| `apps/web/tests/KeyboardShortcutsModal.test.tsx`     | Cover updated labels and grouping                                      | \~50       |
| `apps/web/README_web.md`                             | Document supported shell behavior and War Room boundary                | \~40       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Shell controls expose connection state, settings, keyboard help, command palette, and current global overlays without requiring hidden-only commands.
* [ ] Battlefield, mission log, notices, roster, scroll shelf, quest board, and War Room status remain reachable in supported desktop and tablet layouts.
* [ ] Idle, connecting, connected, closed, no-server, first-run, and empty-data states are visible and non-blocking.
* [ ] Keyboard shortcut help and command palette entries match implemented routes and visible controls.
* [ ] Shortcut handling does not hijack normal typing in inputs or editable content.
* [ ] War Room panel copy and controls do not imply live web-to-Worker federation.

### Testing Requirements

* [ ] Unit tests cover pure shell metadata and command catalog decisions.
* [ ] Component tests cover title bar controls, settings/help/palette reachability, disconnected status, and War Room stub copy.
* [ ] Existing command palette, keyboard shortcut, settings, and shell-adjacent tests remain passing.
* [ ] Manual desktop and tablet viewport smoke checks are recorded in implementation notes.

### Non-Functional Requirements

* [ ] Local-first privacy posture is preserved; no hosted account, hosted storage, analytics, public replay, or federation claim is introduced.
* [ ] Text and controls do not overlap or truncate incoherently in supported shell layouts.
* [ ] Interactive controls have accessible names, visible focus treatment, and keyboard paths.
* [ ] Reduced-motion and seed-data fallback behavior remain compatible with changed shell layout.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Focused tests and `npm --workspace apps/web run typecheck` pass.

***

## 8. Implementation Notes

### Key Considerations

* The current settings trigger is fixed-position and local-state controlled. Moving it into the shell control model should preserve the `data-settings-trigger` contract or replace all callers together.
* The command palette already has strong keyboard and listbox behavior; this session should align its catalog and empty/unavailable states rather than rewrite the ranking model.
* The current War Room panel contains fake room join behavior. That is useful as a visual placeholder but conflicts with the Phase 02 requirement to avoid implying real federation.
* Session 03 owns detailed hero and mission workflow polish, so shell empty states should stay at the navigation and reachability level.

### Potential Challenges

* Title bar crowding: Use responsive grouping, stable buttons, and readable status text instead of adding more horizontally scrolling labels.
* Shared overlay state drift: Keep settings drawer state in the existing settings store with other transient overlay flags.
* Test brittleness: Prefer role, label, and test-id assertions for product contracts rather than exact Tailwind class strings.
* Scope bleed into Session 06: Do not redesign scan, notification, replay, or export internals while making settings reachable.

### Relevant Considerations

* \[P00-apps/web] **Responsive and accessibility debt**: This session directly addresses focus, labels, reduced motion compatibility, and non-overlap for shell surfaces.
* \[P01-apps/warroom+apps/web] **War Room is not wired into the web runtime yet**: The web panel must remain stubbed or separate-surface copy only.
* \[P01] **Local-first boundary is architectural**: Shell status must degrade cleanly without hosted services, API keys, or remote relays.
* \[P01] **Stable docs are the current contract**: Use README files, `docs/api/`, architecture, privacy, release, and legacy-consolidation docs as current truth.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Reopenable overlays can keep stale focus or state after Escape, outside click, or command-palette activation.
* Global shortcuts can hijack normal typing if command routes bypass input-target guards.
* Disconnected and empty states can either blank the cockpit or overclaim hosted/server availability.
* Stubbed War Room controls can create false expectations of live federation or external data transfer.

***

## 9. Testing Strategy

### Unit Tests

* Test shell metadata helper output for each WebSocket status and War Room boundary state.
* Test command catalog entries for visible shell surfaces and absence of deferred hosted or Worker federation commands.
* Test keyboard route decisions for settings, palette, help, Escape, typing targets, and modifier guards.

### Integration Tests

* Render shell components with seeded stores and assert settings, help, palette, overlays, connection status, and War Room stub affordances are reachable by role or accessible label.
* Verify controlled settings drawer open and close paths work from visible shell controls, keyboard shortcuts, command palette actions, Escape, and outside click.

### Manual Testing

* Run the web app with the server unavailable and confirm seed-data fallback, offline status, and no blank shell panels.
* Check desktop and tablet-width layouts for visible battlefield, reachable rails, readable status text, and no incoherent overlap.
* Open and close settings, command palette, keyboard help, and War Room status using pointer and keyboard paths.

### Edge Cases

* No selected faction on first run.
* Empty hero, mission, notice, scroll, and quest collections.
* WebSocket `idle`, `connecting`, `open`, and `closed` states.
* Typing in search, scan root, palette input, or other form fields while global shortcuts are registered.
* Reopening settings, help, and palette after Escape or outside click.

***

## 10. Dependencies

### External Libraries

* No new external libraries planned.

### Other Sessions

* **Depends on**: `phase02-session01-product-surface-requirements-reconciliation`
* **Depended by**: `phase02-session03-hero-and-mission-workflow-completion`, `phase02-session06-settings-replay-notifications-and-scan-ux`, `phase02-session07-product-surface-validation-and-documentation-closeout`

***

## 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-session02-cockpit-shell-and-navigation-cohesion/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.