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

# Session 16: Ergonomics And Documentation

**Session ID**: `phase19-session16-ergonomics-and-documentation` **Package**: apps/web **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Finish the command center with keyboard workflows, cross-links, end-to-end coverage, and accurate documentation.

***

## Scope

### In Scope (MVP)

* Keyboard shortcuts for opening Orchestration details, focusing attention, approving/rejecting selected pending items, cycling blocked or failed queue items, filtering states, and launching spawn/handoff flows behind explicit focused controls
* Accessible shortcut labels in the shortcuts modal
* Cross-links to 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 where available
* Playwright coverage for primary approval, campaign, executor, attention, and detail modal flows
* Updates to `docs/api/`, `apps/server/README_server.md`, `apps/web/README_web.md`, and `packages/protocol/README_protocol.md`

### Out of Scope

* New product claims for unimplemented executor or hosted families
* Destructive keyboard approvals without visible focused controls

***

## Prerequisites

* [ ] Functional Phase 19 slices complete enough to document and test
* [ ] Current shortcut modal, route constants, and docs indexes inspected

***

## Deliverables

1. Shortcut handling and accessible labels
2. Cross-links or documented capability rows for adjacent surfaces
3. Playwright and component coverage for primary flows
4. Stable docs replacing obsolete read-only or unavailable claims where execution families actually shipped

***

## Source Coverage And Evidence

Source coverage:

* Session Split Plan Session 16: Ergonomics And Documentation
* Implementation Targets 23 and 26 for keyboard shortcuts, control-group ergonomics, historical UI chunk cross-link checklist, docs, and tests
* Balls-To-The-Wall Track F: Tests And Done Criteria
* Appendix A Reference Index for final documentation traceability

Key EXAMPLES links:

* [Guide shortcuts](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L400-L415)
* [Keyboard shortcuts reference](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/keyboard-shortcuts.md#L1-L90)
* [Historical asset inventory chunks](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/asset-inventory.md#L56-L88)
* [Historical component chunks](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/tech-stack.md#L122-L139)
* [Historical user guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L1-L466)

***

## Success Criteria

* [ ] Keyboard workflows improve operator speed without accidental destructive approvals
* [ ] Every historical adjacent surface in the study has a current cross-link, capability row, or documented deferment
* [ ] End-to-end tests cover the detail modal and primary mutating flows
* [ ] README and API docs match implemented behavior and remaining limits


---

# 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_19/session_16_ergonomics_and_documentation.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.