> 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/docs-audit.md). # Documentation Audit Report **Date**: 2026-07-08 **Project**: FactionOS **Audit Mode**: Phase-Focused ## Summary | Category | Required | Found | Status | | ------------------- | -------------------------- | ----- | ------ | | Root files | 3 | 3 | PASS | | Required docs files | 9 | 9 | PASS | | ADRs | 1 | 5 | PASS | | Runbooks | 1 | 5 | PASS | | Package READMEs | 8 | 8 | PASS | | README naming | 1 tracked root `README.md` | 1 | PASS | Coverage is current for the completed Phase 24 Legion II - Live Tier And Combat Playback phase. Required root files, standard docs, ADRs, runbooks, and analyzer-reported package READMEs are present. The stable docs already cover the Phase 24 live tier, combat playback, pending-link binding, verified burn-down, scrying, alert focus, world-cue, generated-asset, replay/mock, and no-overclaim boundaries. This run refreshed the docs index routing and replaced the previous Phase 23 docs-audit record with this Phase 24 evidence ledger. ## Scope **Recently completed phase**: 24 - Legion II - Live Tier And Combat Playback **Current open phase**: None **Audit basis**: bundled analyzer output, master PRD, archived Phase 24 PRD, Phase 24 session specs, implementation notes, validation report, phase-exit audit, stable docs, tracked documentation inventory, package READMEs, and targeted source/doc inspections. The local analyzer directory `.spec_system/scripts/` is absent in this checkout, so the bundled apex-spec analyzer was used. It reported: * `project`: `FactionOS` * `current_phase`: `24` * `current_session`: `null` * `monorepo`: `true` * `completed_sessions_count`: `17` * Phase 24 status: `complete` * Candidate sessions: none * Packages: `apps/adapters`, `apps/cli`, `apps/hooks`, `apps/server`, `apps/warroom`, `apps/web`, `packages/protocol`, `public-website` The master PRD marks Phase 24 complete. The planned phase table lists phases 13 through 24 as complete and does not define a remaining unfinished phase. ## Per-Package Documentation Status | Package | Path | README | Status | | -------------- | ------------------- | -------------------------- | ----------------------------- | | adapters | `apps/adapters` | `README_adapters.md` | Found | | cli | `apps/cli` | `README_cli.md` | Found | | hooks | `apps/hooks` | `README_hooks.md` | Found | | server | `apps/server` | `README_server.md` | Found | | warroom | `apps/warroom` | `README_warroom.md` | Found | | web | `apps/web` | `README_web.md` | Verified current for Phase 24 | | protocol | `packages/protocol` | `README_protocol.md` | Found | | public-website | `public-website` | `README_public-website.md` | Found | ## Change Manifest The first Phase 24 spec, `.spec_system/specs/phase24-session01-pure-strike-and-combo-model/spec.md`, does not contain a usable `Base Commit` value, so the command fallback applies: the phase manifest is built from implementation-note file lists and targeted inspection instead of `git diff` from a phase base. | Area | Created | Updated | | ------------------- | ------- | ---------------------------- | | Documentation audit | - | `.spec_system/docs-audit.md` | | Docs index | - | `docs/README_docs.md` | No new documentation file was required. Existing package READMEs and stable docs already covered the shipped Phase 24 implementation. ## Actions Taken ### Updated * `docs/README_docs.md` - extended the completed phase routing note through Phase 24 and added live tier, combat playback, generated-asset, and media-asset routing guidance. * `.spec_system/docs-audit.md` - refreshed the documentation audit for Phase 24 and replaced stale Phase 23 findings. ### Verified Current * Root support files: `README.md`, `CONTRIBUTING.md`, `LICENSE`. * One-command quickstart: `README.md` documents `npm install` and `npm run dev`; `package.json` defines `dev`. * Required docs: `docs/ARCHITECTURE.md`, `docs/CODEOWNERS`, `docs/onboarding.md`, `docs/development.md`, `docs/environments.md`, `docs/deployment.md`, `docs/adr/0000-template.md`, `docs/runbooks/incident-response.md`, and `docs/api/README_api.md`. * ADRs: template plus ADRs 0001 through 0004 exist. * Runbooks: incident response plus Cloudflare WAF, FactionOS backup, local Umami analytics, and War Room operations exist. * Package README coverage matches the eight packages returned by the analyzer. * Phase 24 package scope is `apps/web` for the primary implementation; Session 02 also records `apps/server` as secondary for Quest Board issue accept fallthrough. * `README.md` version badge matches `package.json` version `0.3.2`, and both record the Node `>=26.2.0` baseline. * Tracked README naming matches the project convention: `git ls-files` shows only root `README.md` as a tracked `README.md`; package and subdirectory docs use `README_.md`. The TypeScript page `public-website/src/pages/press/README.md.ts` is not a Markdown README. ## Documentation Gaps * No blocking documentation gaps requiring new product, platform, legal, or operational decisions were found in this audit. * Existing external project gaps remain tracked in `.spec_system/SECURITY-COMPLIANCE.md`, including production-hosted validation and formal legal/privacy owner approval. ## Evidence Ledger | Area | Document | Codebase or Spec Evidence | Result | | ---------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | Project state | `.spec_system/docs-audit.md` | Bundled analyzer reported current phase 24, no active session, monorepo true, eight packages, Phase 24 complete, and no candidate sessions | Updated | | PRD phase status | `.spec_system/PRD/PRD.md` | PRD says "Phase 24 is complete" and planned phase table lists Phase 24 as complete with 9 sessions | Verified | | Phase 24 archive | `.spec_system/archive/phases/phase_24/PRD_phase_24.md` | Archived Phase 24 PRD has `Status: Complete` and `Progress: 9/9 sessions (100%)` | Verified | | Phase 24 package scope | Phase 24 specs | Session specs identify `apps/web` as the implementation package; Session 02 names `apps/server` as secondary | Verified | | Phase 24 implementation anchors | Stable docs and implementation notes | Implementation notes and docs name `combatPlayback.ts`, `combatPlaybackEffects.ts`, `liveLegion.ts`, `scryingAndAlertFocus.ts`, `worldCues.ts`, `generatedPhase3Assets.ts`, `CombatPlaybackLayer.tsx`, `LiveLegionLayer.tsx`, `ScryingAndAlertFocusLayer.tsx`, `Battlefield.tsx`, `QuestBoard.tsx`, and `mediaCatalog.ts` | Verified | | Phase 24 validation | `.spec_system/specs/phase24-session09-validation-and-documentation/validation.md` | Validation records `Result: PASS`, focused tests 238/238, root tests 3395 passed / 1 skipped / 0 failed, web and workspace typecheck, format, lint, ASCII/LF, and security checks | Verified | | Phase exit audit | `.spec_system/specs/phase24-session09-validation-and-documentation/phase-exit-audit.md` | Audit records PASS/source-backed evidence for all eight section 13A criteria, Fun Law 1, Fun Law 4, replay/reconnect/mock/storage/privacy, and generated Phase 3 asset posture | Verified | | Diff manifest fallback | `.spec_system/docs-audit.md` | First Phase 24 spec has no usable `Base Commit`; per documents command fallback, implementation-note file lists and targeted inspections were used instead of a phase-base diff | Verified | | Live tier and combat playback docs | `apps/web/README_web.md`, `docs/battlefield.md`, `docs/ARCHITECTURE.md` | Targeted `rg` found Phase 24 docs for pending links, `mission_start` camp binding, linked mission strikes, counterattacks, combo stages, display-only HP drain, verified burn-downs, live enemies, scrying, alert focus, world cues, and no new rewards/protocol/server/storage/hosted claims | Verified | | Projection and storage boundary | `apps/web/README_web.md`, `docs/ARCHITECTURE.md`, `docs/development.md`, `docs/privacy-and-security.md` | Targeted reads found `factionos-game-v1`, aggregate-only projection storage, browser-local erasure, replay/reconnect/mock guards, and no trusted unified erasure claim | Verified | | Generated Phase 3 asset posture | `docs/media-assets.md`, `docs/battlefield.md`, `docs/ARCHITECTURE.md`, `apps/web/README_web.md` | Stable docs name the three source paths under `assets/generated/game-design/phase03/`, the typed map `apps/web/src/lib/generatedPhase3Assets.ts`, catalog records in `apps/web/src/data/mediaCatalog.ts`, and the runtime no-direct-load boundary | Verified | | Event contract sync | `docs/api/event-api-hook-contracts.md` | Contract doc lists `test_pass` with the dev-health event family alongside `test_failure`, `build_error`, `build_fix`, `ts_errors`, `lint_error`, and `loop_update` | Verified | | Game-design ledgers | `docs/game-design/14-implemented-phases.md`, `docs/game-design/15-phases-yet-to-be-implemented.md` | Implemented ledger records Phase 24 complete; pending backlog says design Phase 3 moved out and remaining backlog starts at Phase 4 | Verified | | Docs routing | `docs/README_docs.md` | Targeted read found completed phase routing stopped at Phase 23; this run updated it through Phase 24 with live tier/combat/generated-asset routing | Updated | | Root version badge | `README.md`, `package.json` | `package.json` reports version `0.3.2`; README badge reports `0.3.2`; `package.json` engines require Node `>=26.2.0` and README badge says Node 26.2.0 or newer | Verified | | Required docs | Standard docs surface | `git ls-files` and presence checks found root docs, required `/docs/` files, ADR template, incident runbook, and API README | Verified | | Package README coverage | Package READMEs | Shell loop over analyzer package paths found all eight `README_.md` files | Verified | | Security and privacy | `docs/privacy-and-security.md`, `.spec_system/SECURITY-COMPLIANCE.md` | Targeted reads preserve local-first, aggregate-only, external-transfer, generated-asset, replay/export, hosted, production, certification, and trusted-erasure boundaries | Verified | | Documentation readiness | Updated audit | Documentation readiness checklist applied to commands, paths, package README coverage, completion wording, stable docs, and no-overclaim claims | Verified | ## Next Action Neither the master PRD nor analyzer state facts define a remaining unfinished phase. The workflow is complete after this `documents` run. --- # 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/docs-audit.md?ask=&goal= ``` `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.