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

# Docs Directory

FactionOS is a local-first observability **and control** platform for AI coding agents. Both dimensions are core to the product vision: full situational awareness of what agents are doing, and active operator authority to direct, approve, orchestrate, and coordinate multi-agent workflows. Documentation here covers both.

Stable supporting documentation lives here.

The product PRD is exposed at `docs/PRD.md` from the spec workflow. UX PRD material lives in `docs/PRD_UX.md`. Phase 02 product-surface routing lives in `.spec_system/archive/phases/phase_02/product_surface_gap_matrix.md`. Phase 03 local orchestration routing lives in `.spec_system/archive/phases/phase_03/orchestration_gap_matrix.md`. Current source, tests, package READMEs, and API docs describe shipped behavior. Historical reports and progress ledgers remain evidence only until cleanup gates close.

The public documentation website is hosted externally on GitBook at <https://faction-os.gitbook.io/faction-os-docs>. The `public-website/` folder contains the static main `faction-os.com` website: landing page, product story, blog, news, investor-related material, and links to both `public-demo/` and the public docs website.

Claude Code and Codex CLI are the supported local hook targets. Use these provider terms consistently: `Claude Code`, `Codex CLI`, `--cli claude|codex|all`, `CODEX_HOME`, `FACTIONOS_CLI=codex-cli`, and Codex `/hooks` trust review. `factionos init` remains Claude Code by default; Codex setup is selected with `--cli codex` or `--cli all`, installs user-level hooks, and still leaves hook trust decisions to Codex.

Phase 09 provider-neutral hook naming and Codex hook-map readiness are owned by `packages/protocol/README_protocol.md` and `apps/hooks/README_hooks.md`. Phase 10 Codex product integration is documented across the root `README.md`, `apps/cli/README_cli.md`, `apps/hooks/README_hooks.md`, `apps/server/README_server.md`, `apps/web/README_web.md`, and `docs/api/README_api.md`. Use those sources for the current CLI, hook, server ingest, and cockpit boundaries before duplicating Codex claims in docs. Phase 12 Session 01 explicitly defers Codex plugin packaging for this release, and hosted telemetry, hosted identity, production-hosted validation, and broad trusted erasure remain no-claim unless a later source-backed record proves them.

## Quest Board Documentation Routing

Use these current docs for the shipped Quest Board suggestion system:

| Topic                                                                                                    | Source                                    |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| REST routes, WebSocket `suggestion_update`, aliases, validation, and error envelopes                     | `api/README_api.md`                       |
| Runtime architecture, source-of-truth ownership, persistence, and action boundaries                      | `ARCHITECTURE.md`                         |
| Local data inventory, `suggestions.json`, provider opt-in, manual deletion, and trusted-erasure no-claim | `privacy-and-security.md`                 |
| Protocol contracts and compatibility events                                                              | `../packages/protocol/README_protocol.md` |
| Server manager, engines, scan privacy, persistence, freshness, and route ownership                       | `../apps/server/README_server.md`         |
| Web typed cards, actions, scan triggers, feedback, and keyboard shortcuts                                | `../apps/web/README_web.md`               |

## Current Docs

| File                                         | Purpose                                                                                                                                                         |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PRD.md`                                     | Current product requirements, phase status vocabulary, local-first policy, product-surface requirements, explicit exclusions, and historical-source boundaries. |
| `PRD_UX.md`                                  | Current UX, interaction, visual, motion, responsive, accessibility, public demo, replay, notification, scan UX, and reduced-motion requirements.                |
| `CONVENTIONS.md`                             | Stable docs-facing pointer to workspace conventions.                                                                                                            |
| `SECURITY-COMPLIANCE.md`                     | Stable docs-facing pointer to archived security posture.                                                                                                        |
| `ARCHITECTURE.md`                            | Current system architecture, package map, runtime flow, Quest Board source-of-truth, data layer, and gaps.                                                      |
| `CODEOWNERS`                                 | Pointer to the enforced ownership source at `.github/CODEOWNERS`.                                                                                               |
| `api/README_api.md`                          | Shipped local server, Quest Board, WebSocket, and War Room Worker API reference.                                                                                |
| `battlefield.md`                             | Current asset-driven 2D battlefield visual system, runtime assets, interaction contract, effects, and validation gates.                                         |
| `battlefield-3d.md`                          | Historical archive for the removed pre-2D Three.js battlefield. Not current product behavior.                                                                   |
| `onboarding.md`                              | Zero-to-local setup checklist.                                                                                                                                  |
| `orchestration-quickstart.md`                | Operator quickstart for using the shipped local Orchestration Command Center: queue, terminal, Git, file, campaign, channel conversion, and API fallback paths. |
| `development.md`                             | Local development commands, ports, package boundaries, tests, and state.                                                                                        |
| `environments.md`                            | Local, demo, Worker, optional hosted, and reserved environment config.                                                                                          |
| `deployment.md`                              | Current deployment status, CI/CD workflows, demo deploy, website deploy posture, and Worker deploy.                                                             |
| `release.md`                                 | Release gates, version alignment, and decommission criteria.                                                                                                    |
| `privacy-and-security.md`                    | Data inventory, `suggestions.json`, controls, external transfers, and open release risks.                                                                       |
| `hosted-services.md`                         | Current optional integrations and future hosted-service guardrails.                                                                                             |
| `media-assets.md`                            | Tracked assets, generated battlefield asset record, quarantined media policy, and promotion requirements.                                                       |
| `public-demo-code-sharing.md`                | Public demo standalone artifact boundary and indirect sharing with the main app.                                                                                |
| `../public-website/README_public-website.md` | Static commercial and product website workspace, build posture, deploy posture, content rules, and approved website media notes.                                |
| `legacy-consolidation.md`                    | Historical artifact disposition and deletion gates.                                                                                                             |
| `adr/`                                       | Architecture decision records.                                                                                                                                  |
| `runbooks/`                                  | Incident and operations runbooks, including local Umami analytics verification.                                                                                 |
| `ongoing-projects/`                          | Active readiness audits and follow-up todo lists.                                                                                                               |

## Codex Documentation Routing

Use these current docs for Codex support instead of older Phase 09 readiness notes:

| Need                                                                                             | Current source                                                                      |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| Quick start and capability boundaries                                                            | `../README.md`                                                                      |
| First local Codex session setup                                                                  | `onboarding.md`                                                                     |
| Contributor install, status, doctor, and uninstall workflow                                      | `development.md`                                                                    |
| `CODEX_HOME` and installer-managed hook environment behavior                                     | `environments.md`                                                                   |
| Prompt, transcript, MCP, `apply_patch`, command, path, token, and local-state privacy boundaries | `privacy-and-security.md`                                                           |
| Provider-specific hook event contract                                                            | `api/event-api-hook-contracts.md`                                                   |
| CLI provider routing and diagnostics                                                             | `../apps/cli/README_cli.md`                                                         |
| Hook runtime maps, managed entries, and payload minimization                                     | `../apps/hooks/README_hooks.md`                                                     |
| Server ingest and cockpit display/search/filter behavior                                         | `api/README_api.md`, `../apps/server/README_server.md`, `../apps/web/README_web.md` |

Phase 11 validation is complete. Fixture hardening and end-to-end validation closeout is recorded in the Phase 11 session artifacts. Phase 12 Session 01 records the Codex plugin packaging decision: direct user-level hooks remain the supported path and plugin packaging is deferred. Phase 12 Session 02 records final rollout readiness, release notes, privacy/security review, and known limitations for that supported path.

Phase 13 public website foundation, Phase 14 homepage and core product story, Phase 15 trust, content, and conversion pages, Phase 16 quality/deployment handoff, Phase 17 Notice Board parity, Phase 18 Quest Board parity, Phase 19 Orchestration Command Center execution, Phase 20 Orchestration Actionability execution, Phase 21 bottom-rail focused surface expansion, Phase 22 Projection Foundation, Phase 23 Legion I scanner camps, and Phase 24 Legion II live tier and combat playback are complete.

The active game-design implementation ledgers are `game-design/14-implemented-phases.md` and `game-design/15-phases-yet-to-be-implemented.md`. Use them with `../apps/web/README_web.md`, `battlefield.md`, `media-assets.md`, `privacy-and-security.md`, and `ARCHITECTURE.md` before adding or duplicating projection, scanner camp, live tier, combat playback, generated-asset, Quest Board, or battlefield-state claims.

## Command Center Documentation Routing

Phase 19 shipped the local Orchestration Command Center across protocol, server, web, API, and privacy docs. Phase 20 completed the evidence-backed local actionability slice for terminal, Git, file, container, campaign, guarded, managed lifecycle, template, and channel-intake paths. Phase 21 routes the operator-facing Command Center through the bottom-rail Orchestration compact card and focused surface. Use these current sources before adding or duplicating command-center claims:

| Need                                                                                                                              | Current source                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operator quickstart and concrete click/API paths                                                                                  | `orchestration-quickstart.md`                                                                                                                         |
| Bottom-rail focused Command Center, Quest Board, and War Room web contract                                                        | `../apps/web/README_web.md`, `.spec_system/specs/phase21-session07-final-regression-and-documentation/phase-handoff.md`                               |
| Product status, no-claim boundaries, and carry-forward executor limits                                                            | `.spec_system/PRD/PRD.md`                                                                                                                             |
| Phase 19 source record and session split                                                                                          | `.spec_system/archive/phases/phase_19/PRD_phase_19.md`                                                                                                |
| Phase 20 source record and release evidence                                                                                       | `.spec_system/archive/phases/phase_20/PRD_phase_20.md`, `.spec_system/specs/phase20-session11-release-evidence-and-event-privacy/release-evidence.md` |
| Phase 21 source record and focused-surface closeout                                                                               | `.spec_system/archive/phases/phase_21/PRD_phase_21.md`, `.spec_system/specs/phase21-session07-final-regression-and-documentation/phase-handoff.md`    |
| REST routes, WebSocket events, channel/webhook intake, terminal/container, File/Git, handoff, metrics, and notification contracts | `api/README_api.md`                                                                                                                                   |
| Runtime ownership, data layer, optional-service boundaries, and current gaps                                                      | `ARCHITECTURE.md`                                                                                                                                     |
| Local data inventory, blocked payloads, external transfer, and executor/privacy posture                                           | `privacy-and-security.md`                                                                                                                             |
| Server managers, route ownership, local in-memory command-center state, executor registry, channel intake, and diagnostics        | `../apps/server/README_server.md`                                                                                                                     |
| Web workbenches, shortcuts, adjacent surfaces, redaction rules, and browser no-claim copy                                         | `../apps/web/README_web.md`                                                                                                                           |
| Shared TypeScript contracts and parser/guard ownership                                                                            | `../packages/protocol/README_protocol.md`                                                                                                             |

The shipped command center is local-first. Channel/webhook intake remains proposal-first until local conversion, file mutation and rollback stay manager-owned, terminal/Git/container queue and campaign work is bounded by explicit local readiness gates, and the primary browser work surface is the focused Orchestration bottom-rail panel. Retained summary/detail popups are secondary inspectors. Remote access, hosted execution, broad inbound commands, production-hosted validation, and trusted unified erasure remain no-claim unless a later source-backed phase adds implementation, tests, and docs.

## Notice Board Documentation Routing

Phase 17 ports the historical Notice Board coordination system into the current runtime. The Notice Board is explicit active-room coordination, not automatic raw event logging. It may carry typed, concise status, question, review, announcement, conflict, completion, or human messages and safe relative related files. It must not carry raw prompts, transcripts, terminal output, command bodies, file contents, secrets, absolute paths, logs, exports, replay buffers, scans, diagnostics, backups, media drafts, or quarantined historical content.

Use these stable docs for current Notice Board behavior:

| Need                                                                                       | Current source                                         |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| Product charter, source evidence, acceptance checks, and session split                     | `.spec_system/archive/phases/phase_17/PRD_phase_17.md` |
| Canonical REST routes, compatibility routes, and WebSocket events                          | `api/README_api.md`                                    |
| Server persistence, filters, context, pruning, compatibility adapters, and automatic posts | `../apps/server/README_server.md`                      |
| Cockpit hydrate/message/resolve behavior, targeting, states, and room-notice convergence   | `../apps/web/README_web.md`                            |
| Agent CLI post/list/filter/context/resolve commands                                        | `../apps/cli/README_cli.md`                            |
| Hook prompt-start context lookup and provider output boundary                              | `../apps/hooks/README_hooks.md`                        |
| Worker relay, resolution relay, catch-up, filtered history, and external transfer boundary | `../apps/warroom/README_warroom.md`                    |
| Shared protocol contracts and blocked Worker relay fields                                  | `../packages/protocol/README_protocol.md`              |
| Cross-package runtime flow and data storage                                                | `ARCHITECTURE.md`                                      |
| Data inventory, allowed coordination data, blocked payloads, and transfer boundary         | `privacy-and-security.md`                              |

The former `docs/ongoing-projects/notice-board-coordination-recovery.md` note is absent from the active ongoing-project directory. Its source evidence, requirements, acceptance checks, and session split details are represented by the Phase 17 PRD, Session 01-10 artifacts, and the stable docs listed above.

## Historical Docs

* `PROGRESS.md` is a historical build ledger. The PRD says it should be deleted in Phase 08 after relevant milestones are represented by stable docs, `docs/legacy-consolidation.md`, and Git history.
* The former `REPORT.md` and `REPORT.html` extraction reports have been moved to ignored `EXAMPLES/` as local traceability intake.
* Older historical artifact dumps, if present locally, follow the same evidence-only policy.

Do not use historical docs as product authority. Do not repeat obsolete licensing, hosted-service, or planned-as-shipped claims from them in stable docs.

## Cleanup Gates

Historical docs can be deleted or reduced only after their unique requirements, contracts, risks, and decisions are captured in the PRD, UX PRD, stable docs, tests, `docs/legacy-consolidation.md`, or explicit rejection notes. The completed phase records own product-surface, orchestration, media, collaboration, hosted-service, release, and Codex closeout evidence. The release guide owns ongoing release readiness, and Phase 08 owns final release cleanup gates.

Phase 08 Session 08 closeout evidence lives in `.spec_system/archive/phases/phase_08/release_candidate_validation_record.md` and `.spec_system/archive/sessions/phase08-session08-release-candidate-validation-and-documentation-closeout/`. Use those records for the final release-candidate evidence, docs sync decisions, and residual no-claim wording.

For Phase 02 browser-facing work, use the product PRD, UX PRD, and `.spec_system/archive/phases/phase_02/product_surface_gap_matrix.md` before relying on any historical report. The matrix records current source evidence, required behavior, acceptance notes, owner session, and deferral or exclusion boundaries. Session 07 closeout evidence lives in `.spec_system/archive/sessions/phase02-session07-product-surface-validation-and-documentation-closeout/` and records the final Phase 02 app/public-demo browser validation, security posture, quality gates, and remaining later-phase gaps.

For Phase 03 local orchestration work, use the product PRD, UX PRD, Phase 03 PRD, orchestration gap matrix, API docs, and package READMEs before relying on historical route, hook, template, Docker, or progress records. Session 07 closeout evidence lives in `.spec_system/archive/sessions/phase03-session07-orchestration-validation-and-documentation-closeout/` and records local orchestration browser validation, focused command evidence, security posture, quality gates, and Phase 04-08 remaining gaps.

For Phase 06 collaboration, isolation, and mobile work, use the Phase 06 PRD, collaboration/isolation baseline, requirement routing matrix, mobile accessibility checklist, API docs, privacy docs, War Room runbook, and package READMEs before relying on historical collaboration or hosted-service notes. Session 07 closeout evidence lives in `.spec_system/archive/sessions/phase06-session07-collaboration-isolation-and-mobile-validation-closeout/` and records local command evidence, local app desktop/mobile Playwright evidence, security posture, docs synchronization, and Phase 07/08 residual risks.

## Asset Rule

Visual media assets do not live in `docs/`. Cross-surface showcase media lives in `../assets/showcase/`; app-served runtime media lives with the owning app or package. Quarantined media remains in ignored `EXAMPLES/` as reference-only intake for standards, style direction, and implementation-gap analysis. Do not import, copy, transform, or ship `EXAMPLES/` files directly; create owned or generated replacements and track them through manifests or typed catalogs.


---

# 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/docs/readme_docs.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.