> 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/phase11-session01-documentation-and-privacy-sync/spec.md). # Session Specification **Session ID**: `phase11-session01-documentation-and-privacy-sync` **Phase**: 11 - Codex Hardening and Validation **Status**: Not Started **Created**: 2026-05-31 **Package**: Cross-cutting **Package Stack**: Markdown stable docs, package README files, npm workspace metadata, Biome JSON formatting *** ## 1. Session Overview This session synchronizes the stable documentation and package metadata after Phase 10 made Codex a supported local hook target. The current source supports Claude Code by default and user-level Codex hook installation when selected, but the stable docs still mix Phase 09 readiness language, Phase 10 implementation status, and Claude-centered setup paths. Phase 11 starts by turning that implementation status into clear, source-backed user guidance. The work is intentionally cross-cutting and documentation-led. It updates the root README, onboarding, development, environment, privacy, API contract, CLI README, hooks README, docs index, and package metadata so Claude Code and Codex CLI are both described as supported local hook targets without weakening existing Claude guidance. The docs must keep the local-first privacy boundary visible: Codex hooks require user trust through `/hooks`, FactionOS installs user-level managed hooks by default, and FactionOS must not recommend bypassing hook trust as the normal path. This session does not add new runtime features, fixtures, tests, browser surfaces, hosted behavior, plugin packaging, or release notes. It prepares the documentation contract that Session 02 fixture hardening and Session 03 end-to-end validation can verify against. *** ## 2. Objectives 1. Present Claude Code and Codex CLI consistently as supported local hook targets across stable docs and package README files. 2. Document the Codex install, `/hooks` trust review, troubleshooting, `CODEX_HOME`, and installer-managed `FACTIONOS_CLI=codex-cli` behavior without overclaiming project-local trust or plugin packaging. 3. Add Codex-specific privacy guidance for hook payloads, transcripts, MCP arguments, `apply_patch`, prompts, command previews, and local state. 4. Update package metadata only where source-backed Phase 10 support makes Codex claims accurate. *** ## 3. Prerequisites ### Required Sessions * [x] `phase10-session01-cli-provider-selection-and-installer-split` - provides `--cli claude|codex|all` provider selection. * [x] `phase10-session02-codex-hook-install-uninstall-and-diagnostics` - provides backup-first Codex hook install, uninstall, status, and doctor behavior. * [x] `phase10-session03-server-ingest-codex-lifecycle` - provides Codex lifecycle ingest, bounded event handling, and API contract updates. * [x] `phase10-session04-web-codex-awareness` - provides Codex labels, search/filter handling, and replay/export privacy coverage in the cockpit. ### Required Tools/Knowledge * Current stable docs under `docs/`. * Package-level READMEs for `apps/cli` and `apps/hooks`. * Phase 11 PRD documentation plan and Session 01 stub. * Current CLI package behavior for provider selection, Codex hook install, status, doctor, and uninstall. * Current hook package behavior for `hooks.json`, `hooks.claude.json`, and `hooks.codex.json`. ### Environment Requirements * No OpenAI, Codex, Claude, Anthropic, hosted, Cloudflare, database, or provider credentials are required. * Documentation must use ASCII-only text and Unix LF line endings. * Metadata changes must remain valid JSON and compatible with Biome formatting. *** ## 4. Scope ### In Scope (MVP) * Users can find both Claude and Codex hook setup paths in the root README - add a Codex quick-start branch beside the existing Claude flow. * Users can onboard a local Codex session - add setup steps, `/hooks` trust review, and expected local cockpit behavior in `docs/onboarding.md`. * Developers can test Codex install and state paths - document `factionos init --cli codex`, `--cli all`, status, doctor, uninstall, `~/.codex`, and local FactionOS state in `docs/development.md`. * Operators can understand environment behavior - document optional `CODEX_HOME` and installer-managed `FACTIONOS_CLI=codex-cli` in `docs/environments.md`. * Users can understand Codex privacy boundaries - add trust, transcript, MCP, `apply_patch`, prompt, command preview, path, and local-state notes in `docs/privacy-and-security.md`. * API readers can distinguish provider hook contracts - split Claude-only language into provider-specific Claude and Codex subsections in `docs/api/event-api-hook-contracts.md`. * Package readers can understand shared hook runtime and CLI provider routing - refresh `apps/hooks/README_hooks.md` and `apps/cli/README_cli.md`. * Docs index readers can see active Codex support - update `docs/README_docs.md`. * Package metadata can mention Codex where source-backed - update root and relevant package descriptions or keywords after Phase 10 support. ### Out of Scope (Deferred) * Marketing copy or release notes - *Reason: this session is stable documentation synchronization, not release promotion.* * New runtime code, fixtures, tests, or UI behavior - *Reason: Phase 10 provided implementation; Phase 11 Session 02 owns fixture hardening.* * Plugin packaging docs beyond a deferral note - *Reason: Phase 12 decides whether a Codex plugin ships.* * Hosted auth, hosted storage, analytics, push, public replay hosting, remote execution, or production-hosted validation claims - *Reason: those remain disabled, deferred, unavailable, or no-claim.* * Recommending `--dangerously-bypass-hook-trust` as normal setup - *Reason: users must review Codex hooks through `/hooks` after install.* *** ## 5. Technical Approach ### Architecture Treat stable docs as the product contract. The root README should provide the shortest supported setup paths, while `docs/onboarding.md`, `docs/development.md`, and package READMEs hold more operational detail. The API contract doc should describe provider-specific hook behavior without turning the Codex path into a Claude alias or implying project-local trusted state. Keep Codex guidance local-first and boundary-specific. The CLI installs user-level Codex hooks into `CODEX_HOME` or `~/.codex`, backs up existing hook files where supported, preserves user-owned hooks, and leaves trust decisions to Codex `/hooks`. Privacy docs should describe what FactionOS summarizes and what it must not store or publish: raw prompts, patch bodies, transcript contents, terminal output, MCP argument bodies, token-like values, broad local paths, provider credentials, and unrelated Codex auth/provider/model/profile settings. Update package metadata only after verifying the current descriptions and keywords. The likely metadata targets are the root `package.json`, `apps/cli/package.json`, and `apps/hooks/package.json`, because those currently carry the most visible Claude-oriented wording. JSON should remain formatted consistently with the rest of the workspace. ### Design Patterns * Source-backed docs: describe only behavior implemented in Phase 10 or explicitly deferred by the PRD. * No-overclaim language: pair supported Codex hook setup with clear limits around trust, plugin packaging, hosted behavior, and external transfer. * Provider-specific sections: keep Claude Code and Codex CLI guidance distinct where setup, config files, and trust models differ. * Local-first privacy framing: explain local storage, hook payload minimization, and user-controlled trust at the point of setup. * Metadata conservatism: add Codex keywords/descriptions only where they reflect implemented source behavior. ### Technology Stack * Markdown stable docs and package READMEs. * npm workspace package metadata in JSON. * Node 20+ workspace conventions. * Biome format checking for JSON and Markdown-adjacent tracked files where applicable. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---- | ------------------------------------------------------------ | ---------- | | None | This session updates existing stable docs and metadata only. | 0 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- | | `README.md` | Add Codex quick-start path, `/hooks` trust reminder, and updated current capability wording. | \~70 | | `docs/onboarding.md` | Add Codex CLI local session setup and troubleshooting entry points. | \~90 | | `docs/development.md` | Document Codex install/test workflow and local state under `~/.codex`. | \~80 | | `docs/environments.md` | Document optional `CODEX_HOME` and installer-managed `FACTIONOS_CLI=codex-cli`. | \~50 | | `docs/privacy-and-security.md` | Add Codex hook trust, transcript, MCP, `apply_patch`, prompt, and local-state privacy notes. | \~90 | | `docs/api/event-api-hook-contracts.md` | Split provider-specific hook contract guidance for Claude and Codex. | \~110 | | `apps/hooks/README_hooks.md` | Refresh shared runtime, provider maps, trust review, and privacy boundary language. | \~70 | | `apps/cli/README_cli.md` | Refresh provider selection, Codex install/uninstall/status/doctor, and limitations wording. | \~70 | | `docs/README_docs.md` | Update docs index with active Codex support and routing guidance. | \~40 | | `package.json` | Add source-backed Codex keyword and root metadata wording where accurate. | \~10 | | `apps/cli/package.json` | Update package description to include Claude and Codex provider routing. | \~5 | | `apps/hooks/package.json` | Update package description to include provider-neutral Claude and Codex hooks. | \~5 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Root README shows both Claude Code and Codex CLI local hook setup paths. * [ ] Codex docs instruct users to review installed hooks with `/hooks` after install. * [ ] Docs do not recommend `--dangerously-bypass-hook-trust` as normal local setup. * [ ] Claude Code setup remains intact and still documented as the default CLI install path. * [ ] `CODEX_HOME` is documented as optional and `FACTIONOS_CLI=codex-cli` is documented as installer-managed for Codex hook commands. * [ ] Privacy docs cover Codex prompt, transcript, MCP, `apply_patch`, terminal, path, token, and local-state boundaries. * [ ] API contract docs describe provider-specific Claude and Codex hook maps without implying unsupported plugin packaging or hosted telemetry. * [ ] Package metadata includes Codex only where current source support makes the claim accurate. ### Testing Requirements * [ ] Markdown edits are reviewed for consistent provider terminology and no-overclaim wording. * [ ] Package metadata remains valid JSON. * [ ] Focused formatting check passes for modified JSON files. * [ ] Diff check, ASCII, and LF validation pass for planned files. ### Non-Functional Requirements * [ ] Documentation remains local-first and avoids hosted auth, hosted storage, analytics, public replay, remote execution, and production-hosted validation claims. * [ ] Documentation does not copy raw Codex payload examples containing prompts, patch bodies, transcript contents, terminal output, MCP argument bodies, token-like values, provider credentials, or broad absolute paths. * [ ] Docs keep Phase 12 plugin packaging explicitly deferred. * [ ] Docs keep hosted identity, trusted erasure, and production-hosted validation no-claim boundaries intact. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Key Considerations * Phase 10 source support is complete, so package metadata can now mention Codex where the package actually supports it. * `factionos init` remains Claude-only by default; Codex requires `--cli codex` or `--cli all`. * Codex hooks are user-level by default through `CODEX_HOME` or `~/.codex`; this session should not document project-local `.codex/` generation as FactionOS behavior. * Codex trust remains user controlled through `/hooks`; docs should say review/trust hooks after install, not bypass trust. * `apps/hooks/README_hooks.md` already contains useful Codex source constraints but still carries older later-phase language that should be reconciled with Phase 10 completion and Phase 11 hardening. * `apps/cli/README_cli.md` already documents many provider-selection behaviors; implementation should tighten consistency rather than duplicate new sections. ### Potential Challenges * Docs may overstate Codex release readiness: mitigate by saying Phase 11 hardening and validation are active while direct user-level hooks are supported. * Provider-specific docs can drift: mitigate by using the same names across docs: `Claude Code`, `Codex CLI`, `--cli claude|codex|all`, `CODEX_HOME`, `FACTIONOS_CLI=codex-cli`, and `/hooks`. * Privacy examples can accidentally expose sensitive shapes: mitigate with descriptive field names only and no raw payload bodies. * Metadata wording can imply unsupported plugin packaging: mitigate by keeping package descriptions focused on hook maps, installer routing, and local observability. ### Relevant Considerations * \[P03] **Stable docs are the current contract**: stable docs and package READMEs must represent source-backed Codex behavior before fixture and validation sessions rely on them. * \[P07] **Redaction is boundary-specific**: privacy docs should describe Codex hook, replay, export, diagnostics, transcript, MCP, and `apply_patch` boundaries separately. * \[P10-apps/cli+apps/hooks] **Backup-first Codex hook management worked**: setup docs should preserve this as the supported install/uninstall model. * \[P10-packages/protocol+apps/web] **Codex display labels need one shared source of truth**: docs should use the protocol-backed user-facing labels rather than raw fallback names as copy. * \[P09-apps/hooks] **Do not forward raw Codex payloads**: docs must not include raw patch bodies, terminal output, transcript paths, token-like values, or MCP arguments. * \[Security] **P06-S07-HOSTED-IDENTITY**: this session does not add hosted identity; keep no-claim wording intact. * \[Security] **P06-S07-ERASURE**: this session does not claim trusted unified erasure. * \[Security] **P06-S07-HOSTED-VALIDATION**: this session does not create production-hosted validation claims. *** ## 9. Testing Strategy ### Unit Tests * No unit tests are required because this session changes documentation and package metadata only. ### Integration Tests * No runtime integration tests are required for this planning session. Session 02 owns focused automated fixture hardening. ### Manual Testing * Review each modified doc for consistent provider terminology, default Claude behavior, Codex `--cli` selection, `/hooks` trust guidance, and no-overclaim wording. * Validate package metadata JSON by running a JSON-aware formatter or `npm` metadata read command. * Confirm links and referenced paths exist for `README.md`, docs, and package READMEs. ### Edge Cases * Existing Claude setup instructions must remain intact when Codex setup is added. * Codex plugin packaging must remain deferred to Phase 12. * `CODEX_HOME` must be described as optional, not required. * `FACTIONOS_CLI=codex-cli` must be described as installer-managed, not something users normally export. * `/hooks` trust review must be required after install in normal setup. * Advanced trust bypass flags must not appear as a recommended path. *** ## 10. Dependencies ### External Libraries * None. ### Other Sessions * **Depends on**: `phase10-session01-cli-provider-selection-and-installer-split`, `phase10-session02-codex-hook-install-uninstall-and-diagnostics`, `phase10-session03-server-ingest-codex-lifecycle`, `phase10-session04-web-codex-awareness` * **Depended by**: `phase11-session02-test-fixture-hardening`, `phase11-session03-end-to-end-validation-and-integration-fixes` *** ## 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/phase11-session01-documentation-and-privacy-sync/spec.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.