> 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/phase19-session16-ergonomics-and-documentation/spec.md).

# Session Specification

**Session ID**: `phase19-session16-ergonomics-and-documentation` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-28 **Package**: null **Package Stack**: mixed

***

## 1. Session Overview

This session closes Phase 19 by making the shipped command center faster to operate, easier to navigate, and accurately documented. It is next because the analyzer reports Phase 19 in progress, Sessions 01-15 complete, no active current session, and Session 16 as the only unfinished candidate.

The primary implementation surface is `apps/web`, where keyboard workflows, accessible shortcut labels, cross-links, focused controls, and browser coverage belong. The session is still cross-cutting because the required closeout updates include `docs/api/`, `apps/server/README_server.md`, `apps/web/README_web.md`, and `packages/protocol/README_protocol.md`.

No new executor, hosted-service, remote-access, or destructive approval claim is introduced. Keyboard workflows must accelerate existing visible controls only, and mutating shortcuts must require a current focused or selected target with duplicate-trigger prevention and visible result states.

***

## 2. Objectives

1. Add command-center keyboard workflows for details, attention focus, pending decisions, blocked or failed queue cycling, state filters, and spawn or handoff entry points without unsafe hidden approvals.
2. Surface accessible command-center shortcut labels in the existing shortcuts modal and keep typing-field and browser-reserved chord guards intact.
3. Add adjacent-surface cross-links or capability rows for Mission Control, Plan Workpad, Permission Modal, Notice Board, Quest Board, War Room, Settings, Git/Codex, terminal, handoff, export, replay, achievements, mission history, channels, remote access, and usage surfaces.
4. Add focused Vitest and Playwright coverage for approval, campaign, executor, attention, detail modal, shortcut, and cross-link flows, then update stable docs to match shipped behavior and remaining limits.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase19-session01-protocol-and-events` - provides command-center contracts and event vocabulary.
* [x] `phase19-session03-web-shell-and-store` - provides the Orchestration shell, store slices, tabs, drawer, and WebSocket reducers.
* [x] `phase19-session04-campaign-workbench` - provides campaign and queue mutation surfaces.
* [x] `phase19-session05-attention-and-permissions` - provides attention and permission decision flows.
* [x] `phase19-session06-executor-registry` - provides executor capability and run-history surfaces.
* [x] `phase19-session08-file-and-git` - provides Git workbench and file-intent links.
* [x] `phase19-session10-mission-artifacts` - provides workpad, evidence, verification, and review-gate records.
* [x] `phase19-session12-terminal-and-containers` - provides terminal/container surfaces and readiness states.
* [x] `phase19-session13-collaboration-and-handoff` - provides handoff and War Room/Notice linkback surfaces.
* [x] `phase19-session14-channels-and-scope` - provides channel and scope surfaces.
* [x] `phase19-session15-metrics-and-notifications` - provides usage and notification surfaces.

### Required Tools Or Knowledge

* Current keyboard shortcut routing in `apps/web/src/lib/useKeyboardShortcuts.ts`.
* Current Orchestration shell, panes, drawer, tabs, and workbench controls in `apps/web/src/components/orchestration/`.
* Current state actions and selected command-center detail in `apps/web/src/store/useGameStore.ts`.
* Current root Playwright setup in `playwright.config.ts` and `tests/e2e/app.e2e.ts`.
* Stable docs boundaries in `docs/api/README_api.md`, `apps/server/README_server.md`, `apps/web/README_web.md`, and `packages/protocol/README_protocol.md`.

### Environment Requirements

* Node 26.2.0+ and npm 11.16.0.
* Root npm workspace dependencies installed.
* Local validation through Vitest, TypeScript, Biome, and Playwright app projects.

***

## 4. Scope

### In Scope (MVP)

* Operators can open Orchestration details, focus the Attention tab, approve or reject the selected pending attention item, cycle blocked or failed queue items, adjust command-center filters, and launch existing spawn or handoff flows from documented shortcuts with platform-appropriate accessibility labels, focus management, and input support.
* Operators can discover command-center shortcuts in the existing shortcuts modal with product-facing copy and no hidden debug instructions.
* Operators can see adjacent-surface cross-links or capability rows for current Mission Control, Plan Workpad, Permission Modal, Notice Board, Quest Board, War Room, Settings, Git/Codex, terminal, handoff, export, replay, achievements, mission history, channels, remote access, and usage surfaces.
* Engineers can validate primary approval, campaign, executor, attention, detail modal, shortcut, cross-link, and no-overclaim flows through focused Vitest and app Playwright coverage.
* Stable docs describe the final command-center ergonomics, API boundaries, shortcut behavior, cross-link coverage, e2e evidence path, and unchanged no-claim limits.

### Out Of Scope (Deferred)

* New executor families, autonomous queue execution, or destructive approvals without visible focused controls - Reason: Session 16 closes ergonomics and docs only.
* Hosted identity, hosted storage, hosted push delivery, remote access, production-hosted validation, or trusted erasure claims - Reason: cumulative no-claim findings remain open.
* Remappable shortcuts or persisted custom key bindings - Reason: the existing shortcut system uses static bindings and modal labels.
* Importing or copying historical `EXAMPLES/` code, prompts, assets, or transcripts - Reason: `EXAMPLES/` remains traceability evidence only.
* Debug-only panels or in-app diagnostic instructions - Reason: product surfaces must stay product-facing; diagnostics belong in tests, docs, or dev tools.

***

## 5. Technical Approach

### Architecture

Keep shortcut logic in the existing keyboard layer and add command-center-specific pure helpers where routing becomes complex. `apps/web/src/lib/useKeyboardShortcuts.ts` should remain the global listener, while a new `apps/web/src/lib/commandCenterShortcuts.ts` can resolve selected attention, queue, filter, detail, spawn, handoff, and terminal targets from current store state.

The Orchestration shell already owns mutation callbacks and selected command-center detail. New shortcut actions should route through existing store methods and component callbacks instead of creating a second mutation path. Mutating shortcuts must only fire when a visible selected or focused control exists, must use existing in-flight mutation keys, and must surface the same success, stale, offline, and duplicate-trigger feedback as pointer actions.

Cross-links should be data-driven through a small helper such as `apps/web/src/lib/commandCenterCrossLinks.ts` and a product panel under `apps/web/src/components/orchestration/CommandCenterAdjacentSurfaces.tsx`. Rows should either link to an existing surface, select an existing tab/detail, or state an explicit unavailable/no-claim capability without implying active hosted or remote behavior.

Playwright coverage should extend the root app projects. If a new e2e file is created, `playwright.config.ts` must include it in the app desktop/mobile projects so it actually runs.

### Design Patterns

* Existing shortcut listener: preserve the current document-level listener and typing-target guards.
* Store-owned selection: use `useGameStore` selection and command-center actions as the source of truth.
* Focused-control safety: mutating shortcuts act only on a visible selected pending item or active focused control.
* Data-driven links: centralize adjacent-surface labels, availability, destination, and no-claim copy in a pure helper.
* Product-facing copy: user-visible rows describe current capability, not implementation internals.

***

## 6. Deliverables

### Files To Create

| File                                                                      | Purpose                                                                                                   | Est. Lines |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- |
| `apps/web/src/lib/commandCenterShortcuts.ts`                              | Pure command-center shortcut action routing, selected-target resolution, safety guards, and labels.       | \~220      |
| `apps/web/src/lib/commandCenterCrossLinks.ts`                             | Data-driven adjacent-surface rows, destinations, availability states, and no-claim copy.                  | \~180      |
| `apps/web/src/components/orchestration/CommandCenterAdjacentSurfaces.tsx` | Product-facing cross-link and capability-row panel for adjacent command-center surfaces.                  | \~180      |
| `apps/web/tests/commandCenterShortcuts.test.ts`                           | Unit tests for shortcut routing, typing guards, selected-target safety, duplicate prevention, and labels. | \~180      |
| `apps/web/tests/commandCenterCrossLinks.test.ts`                          | Unit tests for adjacent-surface availability, no-claim rows, destinations, and safe copy.                 | \~140      |
| `tests/e2e/orchestration-command-center.e2e.ts`                           | Playwright app coverage for detail modal, attention, campaign, executor, shortcut, and cross-link flows.  | \~240      |

### Files To Modify

| File                                                                  | Changes                                                                                                                     | Est. Lines |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `apps/web/src/lib/useKeyboardShortcuts.ts`                            | Add command-center shortcut actions, dispatch integration, static help labels, and preserved browser/typing guards.         | \~160      |
| `apps/web/src/components/KeyboardShortcutsModal.tsx`                  | Add or expose an Orchestration category and ensure accessible rows remain grouped and counted.                              | \~45       |
| `apps/web/src/components/orchestration/OrchestrationShell.tsx`        | Wire command-center shortcut dispatch to existing details, attention, queue, filter, terminal, spawn, and handoff handlers. | \~170      |
| `apps/web/src/components/orchestration/OrchestrationHeader.tsx`       | Add accessible shortcut hint labels for details and refresh controls without crowding the header.                           | \~45       |
| `apps/web/src/components/orchestration/OrchestrationTabs.tsx`         | Add stable tab ids/test ids and focus targets for shortcut navigation.                                                      | \~55       |
| `apps/web/src/components/orchestration/CommandCenterPanes.tsx`        | Mount adjacent-surface rows and pass current command-center state for availability.                                         | \~70       |
| `apps/web/src/components/orchestration/AttentionWorkbench.tsx`        | Support selected/focused pending attention rows and shortcut-safe approve/reject entry points.                              | \~90       |
| `apps/web/src/components/orchestration/CampaignWorkbench.tsx`         | Add focusable campaign controls and shortcut-safe launch/approve/dispatch affordances where existing state allows.          | \~70       |
| `apps/web/src/components/orchestration/QueueWorkbench.tsx`            | Add blocked/failed queue cycling targets and visible selected-row state for keyboard workflows.                             | \~80       |
| `apps/web/src/components/orchestration/ExecutorFamiliesPanel.tsx`     | Add focus targets for executor refresh/detail paths and preserve no-claim copy for unavailable families.                    | \~60       |
| `apps/web/src/components/orchestration/CollaborationHandoffPanel.tsx` | Add shortcut-safe handoff launch/focus targets and link rows to Notice/War Room posture.                                    | \~65       |
| `apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx`     | Ensure terminal drawer focus and shortcut labels align with the new terminal entry point.                                   | \~45       |
| `apps/web/tests/keyboardShortcuts.test.ts`                            | Cover command-center shortcuts, category labels, typing guards, browser-reserved chords, and selected-target safety.        | \~140      |
| `apps/web/tests/KeyboardShortcutsModal.test.tsx`                      | Cover Orchestration category grouping, row count, accessible labels, and command-center shortcut copy.                      | \~80       |
| `apps/web/tests/OrchestrationPanel.test.tsx`                          | Cover shortcut dispatch wiring, selected attention decisions, queue cycling, detail modal, and adjacent-surface rows.       | \~220      |
| `apps/web/tests/AttentionWorkbench.test.tsx`                          | Cover focused pending item state, approve/reject button parity, in-flight disabled state, and accessibility labels.         | \~90       |
| `apps/web/tests/CommandCenterPanes.test.tsx`                          | Cover adjacent-surface panel mounting and tab-specific availability states.                                                 | \~100      |
| `playwright.config.ts`                                                | Include the new command-center e2e file in app desktop/mobile projects.                                                     | \~20       |
| `docs/api/README_api.md`                                              | Document final command-center API and shortcut/e2e boundaries without adding new route claims.                              | \~70       |
| `apps/server/README_server.md`                                        | Document closeout behavior, unchanged local API boundaries, and no new executor/hosted claims.                              | \~55       |
| `apps/web/README_web.md`                                              | Document command-center shortcuts, cross-links, focused-control safety, and Playwright coverage.                            | \~90       |
| `packages/protocol/README_protocol.md`                                | Document final protocol ownership and that ergonomics/docs do not add new contracts.                                        | \~45       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Orchestration details, Attention focus, selected pending decisions, blocked/failed queue cycling, state filters, terminal entry, spawn entry, and handoff entry are reachable by documented shortcuts.
* [ ] Mutating shortcuts do not approve, reject, dispatch, spawn, or hand off unless a visible selected or focused control makes the target unambiguous.
* [ ] The shortcut modal lists command-center shortcuts with accessible labels and preserves the existing count/group behavior.
* [ ] Adjacent-surface rows cover Mission Control, Plan Workpad, Permission Modal, Notice Board, Quest Board, War Room, Settings, Git/Codex, terminal, handoff, export, replay, achievements, mission history, channels, remote access, and usage.
* [ ] Docs match implemented behavior and keep unsupported executor, hosted, remote-access, production-hosted, and trusted-erasure claims out of product language.

### Testing Requirements

* [ ] Unit tests cover pure command-center shortcut routing, typing-field suppression, browser-reserved chord suppression, selected-target safety, and duplicate-trigger prevention.
* [ ] Component tests cover shortcut modal labels, Orchestration dispatch wiring, attention decision parity, queue cycling, details modal, adjacent-surface rows, loading, empty, error, and offline states.
* [ ] Playwright app coverage exercises primary approval, campaign, executor, attention, detail modal, shortcut, and cross-link flows on desktop and mobile projects.

### Non-Functional Requirements

* [ ] User-facing shortcut and cross-link copy is product-facing and does not expose raw prompts, command bodies, terminal output, diffs, file contents, tokens, absolute paths, replay buffers, exports, or debug data.
* [ ] Keyboard workflows preserve focus management, visible focus states, reduced-motion compatibility, and text fit on mobile and desktop.
* [ ] No new hosted identity, hosted storage, Web Push delivery, remote access, autonomous execution, production-hosted validation, or trusted erasure claim is introduced.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces contain product-facing copy only.
* [ ] `npm --workspace apps/web run typecheck` passes.
* [ ] Focused Vitest suites for shortcuts, Orchestration, and adjacent surfaces pass.
* [ ] `npm run test:e2e -- --project=app-desktop --project=app-mobile orchestration-command-center.e2e.ts` passes or records bounded local blocker evidence.
* [ ] Root `npm run format:check`, `npm run lint`, `npm run typecheck --workspaces --if-present`, and `npm test` are run before validation handoff.

***

## 8. Implementation Notes

### Working Assumptions

* Session 16 is the next executable session: the analysis script reports Phase 19 in progress, Sessions 01-15 complete, no active current session, and Session 16 as the only unfinished candidate.
* The session is cross-cutting even though the candidate stub lists `apps/web`: the same stub requires `docs/api/`, `apps/server/README_server.md`, `apps/web/README_web.md`, and `packages/protocol/README_protocol.md`, so a single-package `apps/web` path constraint would not fit the deliverables.
* A new Playwright e2e file is acceptable if `playwright.config.ts` is updated to include it in app projects; current config only matches `app.e2e.ts` for app desktop/mobile.
* Existing command-center mutation callbacks in `OrchestrationShell.tsx` are the safest execution path for shortcut actions because they already apply in-flight keys, expected revisions, refresh-on-success, and toast feedback.

### Conflict Resolutions

* The candidate stub says `Package: apps/web`, while its deliverables require API, server README, web README, and protocol README updates. The chosen interpretation is `Package: null` with `apps/web` as the primary implementation surface because docs and protocol/server boundary wording are part of the required closeout.
* The stub asks for spawn/handoff shortcut flows, while the security posture forbids hidden destructive approvals and unsupported executor claims. The chosen interpretation is to add shortcut entry points that focus or open existing spawn/handoff controls, not to perform spawn or handoff mutations without visible focused controls.
* The stub asks for Playwright coverage, while current app projects only match `app.e2e.ts`. The chosen interpretation is to either extend `app.e2e.ts` or add a new e2e file and wire it into `playwright.config.ts` so the coverage runs.

### Key Considerations

* Keyboard shortcuts must not fire while the user is typing in inputs, textareas, selects, or contenteditable regions except for already-supported explicit help/palette chords.
* Approve/reject shortcuts are state-mutating actions and need duplicate-trigger prevention while in flight.
* Cross-link rows for remote access, hosted behavior, and unavailable executor families must be explicit no-claim or unavailable rows, not active links.
* Documentation must replace stale read-only or unavailable claims only where Phase 19 actually shipped behavior.

### Potential Challenges

* Shortcut scope can collide with browser and existing app chords: keep command-center bindings in a distinct sequence family and preserve existing modifier guards.
* Selected-target ambiguity can make approval shortcuts unsafe: require current selected or focused pending rows and visible labels before mutation.
* Playwright app coverage can become slow or flaky: use focused flows, existing browser guards, and deterministic local fixtures.
* The adjacent-surface list can crowd the panel: use compact rows with stable labels, icons or text where existing style supports them, and responsive wrapping.

### Relevant Considerations

* \[P03] **Stable docs are the current contract**: update README files and `docs/api/` as the final Phase 19 source of truth.
* \[P03] **Real executors remain unimplemented by design**: keyboard and cross-link work cannot imply new executor families or automatic execution.
* \[P03-apps/server] **Local server boundary must stay conservative**: docs must preserve auth, CORS, body cap, validation, rate-limit, and unavailable-state wording.
* \[P07] **Redaction is boundary-specific**: shortcut, cross-link, e2e, replay, export, terminal, notification, and docs copy must not broaden sensitive data exposure.
* \[P07] **Hosted services ship as disabled-default guardrails only**: remote access, hosted identity, hosted storage, analytics, push, and production validation remain no-claim unless separately proven.
* \[P18-apps/web] **Pointer and keyboard actions should share store methods**: keyboard workflows should call the same store or shell actions as visible controls.
* \[P18-apps/web] **Pure normalization before store mutation**: shortcut helpers should resolve safe targets before dispatching state changes.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* A keyboard shortcut accidentally approving or rejecting the wrong pending item.
* A shortcut firing while the operator is typing a reason, search query, terminal input, or form field.
* Cross-link rows implying unavailable hosted, remote, or executor behavior is active.
* E2E coverage asserting debug implementation details instead of product-facing behavior.

***

## 9. Testing Strategy

### Unit Tests

* `commandCenterShortcuts` tests for route resolution, selected/focused target safety, command-center sequence handling, browser chord suppression, typing target suppression, and duplicate in-flight state.
* `commandCenterCrossLinks` tests for row availability, destination kinds, no-claim copy, and safe labels.
* Existing `useKeyboardShortcuts` tests for integration with global shortcuts and shortcut help labels.

### Integration Tests

* Orchestration component tests for details open/close, attention focus, selected pending approve/reject, queue cycling, campaign and executor focus paths, handoff/terminal entry points, adjacent-surface rows, loading, empty, error, and offline states.
* Shortcut modal component tests for Orchestration category grouping, row count, accessible names, and keyboard-close behavior.
* Store/shell tests proving keyboard and pointer paths share mutation guards and feedback.

### Runtime Verification

* Run focused Vitest suites for shortcut helpers, modal labels, Orchestration panel wiring, Attention workbench, and CommandCenterPanes.
* Run Playwright app desktop/mobile coverage for command-center detail modal, attention decision flow, campaign controls, executor cards, keyboard shortcuts, and adjacent-surface rows.
* Run package and workspace checks before the validate handoff.

### Edge Cases

* No attention items, no queue items, no selected detail, selected item filtered out, and stale selected detail.
* Pending item becomes resolved while a shortcut decision is in flight.
* User types in reason fields, terminal input, search fields, or contenteditable regions.
* Browser-reserved shortcuts such as Cmd+R, Ctrl+S, Cmd+Shift+K, Alt+Left, and platform navigation chords.
* Offline local server, malformed command-center snapshot, loading state, empty state, stale revision, timeout, and duplicate-trigger conflict.
* Mobile viewport where shortcuts are listed but hardware keyboard may be absent.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase19-session01-protocol-and-events`, `phase19-session03-web-shell-and-store`, `phase19-session04-campaign-workbench`, `phase19-session05-attention-and-permissions`, `phase19-session06-executor-registry`, `phase19-session08-file-and-git`, `phase19-session10-mission-artifacts`, `phase19-session12-terminal-and-containers`, `phase19-session13-collaboration-and-handoff`, `phase19-session14-channels-and-scope`, `phase19-session15-metrics-and-notifications`.
* Depended by: Phase 19 closeout, `audit`, and any future orchestration execution hardening phase.

***

## Next Steps

Run the `implement` workflow step to begin 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/phase19-session16-ergonomics-and-documentation/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.