@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/docs/README.md

@@ -1,6 +1,6 @@
 # Codex Orchestrator (Repository Guide)
 
-> **Internal/Contributor guide:** This document covers repository internals and workflow details. End‑user installation and usage live in `README.md`.
+> Internal contributor guide. Public downstream docs live in `README.md` and `docs/public/`.
 
 Codex Orchestrator is the coordination layer that glues together Codex-driven agents, run pipelines, approval policies, and evidence capture for multi-stage automation projects. It wraps a reusable orchestration core with a CLI that produces auditable manifests, integrates with control-plane validators, and syncs run results to downstream systems.
 
@@ -13,19 +13,31 @@ Codex Orchestrator is the coordination layer that glues together Codex-driven ag
 ## Collab vs MCP
 - Decision guide: `docs/guides/collab-vs-mcp.md`.
 
-## Downstream init
-- See `README.md` for the recommended quick-start flow.
+## Public docs
+- Public front door: `README.md`
+- Downstream setup: `docs/public/downstream-setup.md`
+- Provider onboarding: `docs/public/provider-onboarding.md`
 
 ## Upstream Sync
 - Codex CLI sync strategy: `docs/guides/upstream-codex-cli-sync.md`.
 
+## Current Posture
+- Current CO-local ChatGPT-auth/appserver model posture: `gpt-5.5` / `xhigh` on Codex CLI `0.125.0` when live access smoke passes.
+- Release-facing cloud/downstream pins remain evidence-gated in `docs/guides/codex-version-policy.md`; the exact CO-352 cloud blocker is the configured environment id not found.
+- Current model posture is `gpt-5.5` / `xhigh` when available in ChatGPT-auth Codex sessions; keep `explorer_fast` on `gpt-5.3-codex-spark` for file/codebase search only.
+- Portable packaged/generated defaults still keep `gpt-5.4` / `xhigh` as fallback values when `gpt-5.5`, API/cloud portability, or downstream/no-network access is not proven.
+- `codex-orchestrator doctor` treats `gpt-5.5` as non-drift when `codex debug models` verifies current model access; additive defaults keep fresh configs on portable fallback values unless `--auth-scope chatgpt` is explicitly requested after live access smoke, and they preserve compatible prior `gpt-5.5` role files without requiring extra marker metadata.
+- Local default runtime is `appserver`; keep `--runtime-mode cli` as break-glass.
+- Full posture and promotion gates live in `docs/guides/codex-version-policy.md`.
+
 ## Release Notes
 - Shipped skills note: `docs/release-notes-template-addendum.md`.
-- Optional overview override: add and commit a release overview file at .github/release-overview.md before tagging; the release workflow uses it when present.
+- Canonical promoted sections: generated `Overview` and `Bug Fixes` become top-level release-note sections; generated `Documentation` remains under `Full Changelog`.
+- Optional one-shot overview override: put release-specific narrative text in the signed annotated tag body before pushing the tag. The workflow reads the tag body for that release only and does not read .github/release-overview.md.
 
 ## How It Works
 - **Planner → Builder → Tester → Reviewer:** The core `TaskManager` (see `orchestrator/src/manager.ts`) wires together agent interfaces that decide *what* to run (planner), execute the selected pipeline stage (builder), verify results (tester), and give a final decision (reviewer).
-- **Execution modes:** Each plan item can flag `requires_cloud` and task metadata can set `execution.parallel`; the mode policy picks `mcp` (local MCP runtime) or `cloud` execution accordingly. Cloud runs perform a quick preflight (env id, codex availability, optional remote branch) and fall back to `mcp` with both summary text and a structured `cloud_fallback` manifest block when preflight fails.
+- **Execution modes:** Each plan item can flag canonical `requires_cloud`; planner output still carries legacy `requiresCloud` as a compatibility alias while current code should prefer `requires_cloud`. Task metadata can set `execution.parallel`, and the mode policy picks `mcp` (local MCP runtime) or `cloud` execution accordingly. Cloud runs perform a quick preflight (env id, codex availability, optional remote branch) and fall back to `mcp` with both summary text and a structured `cloud_fallback` manifest block when preflight fails.
 - **Runtime provider modes:** `runtimeMode=cli|appserver` is orthogonal to `executionMode`; local default runtime is `appserver` with `cli` break-glass support preserved. Explicit `executionMode=cloud + runtimeMode=appserver` remains unsupported and fails fast.
 - **Advanced feature posture:** `js_repl` is enabled by default globally (local + cloud lanes). For deterministic cloud contracts, pin explicit feature lanes (`CODEX_CLOUD_ENABLE_FEATURES=js_repl` and separate `CODEX_CLOUD_DISABLE_FEATURES=js_repl` runs). Use `CODEX_CLOUD_DISABLE_FEATURES=js_repl` for task-scoped cloud break-glass; reserve `codex features disable js_repl` for global emergency toggles and re-enable with `codex features enable js_repl`; `memories` remains scoped to explicit eval lanes (legacy alias `memory_tool` is compatibility-only).
 - **Event-driven persistence:** Milestones emit typed events on `EventBus`. `PersistenceCoordinator` captures run summaries in the task state store and writes manifests so nothing is lost if the process crashes.
@@ -104,7 +116,7 @@ Use `npx @kbediako/codex-orchestrator resume --run <run-id>` to continue interru
 - `codex-orchestrator mcp serve [--repo <path>] [--dry-run] [-- <extra args>]`: launch the MCP stdio server (delegates to `codex mcp-server`; stdout guard keeps protocol-only output, logs to stderr).
 - `codex-orchestrator init codex [--cwd <path>] [--force]`: copy starter templates into a repo (includes `mcp-client.json`, `AGENTS.md`, downstream .codex/config.toml + .codex/agents/* role files sourced from `templates/codex/.codex/*`, and `codex.orchestrator.json`; no overwrite unless `--force`).
 - `codex-orchestrator setup [--yes] [--refresh-skills]`: one-shot bootstrap for downstream users (installs bundled skills, configures delegation + DevTools wiring, and prints policy/usage guidance). By default, setup does not overwrite existing skills; add `--refresh-skills` when you want to replace existing bundled skill files.
-- Canonical bundled skill roster lives in `README.md` ("Bundled skills" section) and shipped files under `skills/`.
+- Canonical bundled skill roster lives in `skills/README.md`, with shipped-file parity enforced against `skills/`.
 - `codex-orchestrator start [pipeline] [--auto-issue-log] [--repo-config-required]`: starts a pipeline run. `--auto-issue-log` writes failure bundles automatically (including setup failures before manifest creation); `--repo-config-required` disables packaged config fallback.
 - `codex-orchestrator flow [--task <task-id>] [--auto-issue-log] [--repo-config-required]`: runs `docs-review` then `implementation-gate` in sequence; stops on the first failure. `--auto-issue-log` writes failure bundles automatically (including setup failures before manifest creation); `--repo-config-required` disables packaged config fallback.
 - `codex-orchestrator doctor [--format json] [--usage] [--cloud-preflight] [--issue-log] [--apply]`: check optional tooling dependencies plus collab/cloud/delegation readiness and print enablement commands. `--usage` appends a local usage snapshot (scans `.runs/`) with adoption KPIs. `--issue-log` appends/creates `docs/codex-orchestrator-issues.md` (or `--issue-log-path`) and writes a JSON bundle under `out/<resolved-task>/doctor/issue-bundles/` with doctor context plus latest run context when available. `--apply` plans/applies quick fixes (use with `--yes`).
@@ -117,11 +129,11 @@ Use `npx @kbediako/codex-orchestrator resume --run <run-id>` to continue interru
 ## Publishing (npm)
 - Pack audit: `npm run pack:audit` (validates the tarball file list; run `npm run clean:dist && npm run build` first if `dist/` contains non-runtime artifacts).
 - Pack smoke: `npm run pack:smoke` (installs the tarball in a temp mock repo, runs CLI behavior checks including `review` artifacts and `long-poll-wait` skill install, and validates delegate-server JSONL; uses network). Treat this as a spot-check gate; use `npm run pack:audit` for full tarball inventory validation.
-- Release tags: `vX.Y.Z` or `vX.Y.Z-alpha.N` must match `package.json` version.
-- Dist-tags: stable publishes to `latest`; alpha publishes to `alpha` and uses a GitHub prerelease.
+- Release tags: `vX.Y.Z` or `vX.Y.Z-<prerelease>` must match `package.json` version, for example `vX.Y.Z-alpha.N`, `vX.Y.Z-beta.N`, or `vX.Y.Z-rc.N`.
+- Dist-tags: stable releases publish to `latest`; prereleases publish with a dist-tag derived from the leading prerelease label before the first `.` or `-`, lowercased and sanitized. Examples: `alpha.1` -> `alpha`, `beta.1` -> `beta`, `rc.1` -> `rc`; empty or numeric-leading labels fall back to `next`. Prerelease tags create a GitHub prerelease.
 - Publishing auth: workflow attempts OIDC trusted publishing first (`id-token: write` + `--provenance`), then falls back to `secrets.NPM_TOKEN` when OIDC is unavailable. `secrets.NPM_TOKEN` must be an npm automation token (not a token that requires OTP).
 - Trusted publisher config: npm expects workflow filename `release.yml` (the file must exist at `.github/workflows/release.yml` on the default branch). Leave environment blank unless the publish job sets `environment: ...`.
-- OIDC runtime prereqs: npm trusted publishing currently requires Node.js `22.14.0+` and npm `11.5.1+`; the publish job installs npm `^11.5.1` before publishing.
+- OIDC runtime prereqs: npm trusted publishing currently requires Node.js `22.14.0+` and npm `11.5.1+`; the publish job logs the runner versions, then runs the publish commands through `npx --yes npm@11.5.1` instead of mutating the runner-global npm install.
 
 ## Parallel Runs (Meta-Orchestration)
 The orchestrator executes a single pipeline serially. “Parallelism” comes from running multiple orchestrator runs at the same time, ideally in separate git worktrees so builds/tests don’t contend for the same working tree outputs.
@@ -211,14 +223,17 @@ Note: the commands below assume a source checkout; `scripts/` helpers are not in
 | --- | --- |
 | `npm run build` | Compiles TypeScript to `dist/` (required for packaging and running the CLI from `dist/`). |
 | `npm run lint` | Lints orchestrator, adapters, shared packages. Auto-runs `node scripts/build-patterns-if-needed.mjs` so codemods compile when missing/outdated. |
-| `npm run test` | Vitest suite covering orchestration core, CLI services, and patterns. |
-| `npm run eval:test` | Optional evaluation harness (enable when `evaluation/fixtures/**` is populated). |
-| `npm run docs:check` | Deterministically validates scripts/pipelines/paths referenced in agent-facing docs. |
-| `npm run docs:freshness` | Validates docs registry coverage + review recency; writes `out/<task-id>/docs-freshness.json`. |
+| `npm run test:core` | Narrow Core Lane matrix via `vitest.config.core.ts`; excludes `adapters/**` and `evaluation/tests/**`. |
+| `npm run test` | Default repo validation alias; runs `test:core` so the historical core-only surface stays explicit. |
+| `npm run test:all` | Explicit broader Vitest matrix (`test:core` + `test:adapters`) without implicitly enabling the opt-in evaluation lane. |
+| `npm run eval:test` | Optional evaluation-only harness lane; alias to `npm run test:evaluation` when `evaluation/fixtures/**` or evaluation scope is in play. |
+| `npm run docs:check` | Deterministically validates scripts/pipelines/paths referenced in agent-facing docs, current posture locks, bundled-skill roster parity, and the README front-door budget. |
+| `npm run docs:freshness` | Validates docs registry coverage plus catalog class coverage and writes a class-separated report to `out/<task-id>/docs-freshness.json`. |
+| `npm run repo:stewardship` | Audits every tracked file via `git ls-files`, classifies each tracked surface as `validate`, `update`, `delete`, or `retain_with_rationale`, and writes `out/<task-id>/repo-stewardship.json`. |
 | `npm run ci:cloud-canary` | Runs the cloud canary harness (`scripts/cloud-canary-ci.mjs`) to verify cloud lifecycle manifest + run-summary evidence; credential-gated by `CODEX_CLOUD_ENV_ID` and optional auth secrets (`CODEX_CLOUD_BRANCH` defaults to `main`). Feature flags can be passed through with `CODEX_CLOUD_ENABLE_FEATURES` / `CODEX_CLOUD_DISABLE_FEATURES` (comma- or space-delimited, e.g. `sqlite,memories`). |
 | `node scripts/delegation-guard.mjs` | Enforces subagent delegation evidence before review (repo-only). |
 | `node scripts/spec-guard.mjs --dry-run` | Validates spec freshness; required before review (repo-only). |
-| `node scripts/diff-budget.mjs` | Guards against oversized diffs before review (repo-only; defaults: 25 files / 800 lines; supports explicit overrides). |
+| `node scripts/diff-budget.mjs` | Guards against oversized diffs before review (repo-only; defaults: 25 files / 1200 lines; supports explicit overrides). |
 | `npm run pack:smoke` | Downstream simulation gate for npm consumers (tarball install in temp mock repo, `review` wrapper artifacts, delegate-server JSONL, and `skills install --only long-poll-wait`). Spot-check gate; pair with `npm run pack:audit` when you need full tarball inventory coverage. Core lane runs it automatically when downstream-facing paths change, and `.github/workflows/pack-smoke-backstop.yml` runs a weekly `main` backstop. |
 | `codex-orchestrator review` | Runs the standalone review wrapper with task-scoped manifest evidence; delegation MCP is enabled by default (explicit disable available via `CODEX_REVIEW_DISABLE_DELEGATION_MCP=1` / `--disable-delegation-mcp`), runtime guards are opt-in via `CODEX_REVIEW_*` env vars, and patience-first checkpoints log by default (`CODEX_REVIEW_MONITOR_INTERVAL_SECONDS` tunes/disables). Large uncommitted scopes get an automatic prompt advisory (`CODEX_REVIEW_LARGE_SCOPE_FILE_THRESHOLD` / `CODEX_REVIEW_LARGE_SCOPE_LINE_THRESHOLD`). Optional auto failure issue logging via `CODEX_REVIEW_AUTO_ISSUE_LOG=1` or `--auto-issue-log`. |
 | `npm run review` | Runs `codex review` with task-scoped manifest evidence; delegation MCP is enabled by default (explicit disable available via `CODEX_REVIEW_DISABLE_DELEGATION_MCP=1` / `--disable-delegation-mcp`), runtime guards are opt-in via `CODEX_REVIEW_*` env vars, and patience-first checkpoints log by default (`CODEX_REVIEW_MONITOR_INTERVAL_SECONDS` tunes/disables). Large uncommitted scopes get an automatic prompt advisory (`CODEX_REVIEW_LARGE_SCOPE_FILE_THRESHOLD` / `CODEX_REVIEW_LARGE_SCOPE_LINE_THRESHOLD`). Optional auto failure issue logging via `CODEX_REVIEW_AUTO_ISSUE_LOG=1` or `--auto-issue-log`. |
@@ -229,13 +244,14 @@ Run `npm run build` to compile TypeScript before packaging or invoking the CLI d
 
 This repo enforces a small “diff budget” via `node scripts/diff-budget.mjs` to keep PRs reviewable and avoid accidental scope creep (repo-only).
 
-- Defaults: 25 changed files / 800 total lines changed (additions + deletions), excluding ignored paths.
-- CI: `.github/workflows/core-lane.yml` runs the diff budget on pull requests and sets `BASE_SHA` to the PR base commit.
-- Local: run `node scripts/diff-budget.mjs` before `npm run review` (the review wrapper runs it automatically).
+- Defaults: 25 changed files / 1200 total lines changed (additions + deletions), excluding ignored paths.
+- CI: `.github/workflows/core-lane.yml` runs the diff budget on pull requests and sets `BASE_SHA` to the PR base commit, so PR/base scope remains hard-gated.
+- Local: run `node scripts/diff-budget.mjs` before `npm run review` (the review wrapper runs it automatically). Without an explicit base, the hard local gate uses the current working tree relative to `HEAD`; when `origin/main` exists and the broader stacked aggregate is larger, the script prints that aggregate as advisory context.
+- If `--base`, `BASE_SHA`, or `DIFF_BUDGET_BASE` is provided but cannot be resolved, the script fails instead of downgrading to local auto mode or silently falling through to a lower-priority base source.
 
 ### Local usage
-- Working tree diff against the default base (uses `BASE_SHA`/`origin/main`/initial commit as available): `node scripts/diff-budget.mjs`
-- Explicit base: `node scripts/diff-budget.mjs --base <ref>`
+- Current working tree hard gate relative to `HEAD` (default local mode): `node scripts/diff-budget.mjs`
+- Explicit PR/base scope: `node scripts/diff-budget.mjs --base <ref>`
 - Commit-scoped mode (ignores working tree state): `node scripts/diff-budget.mjs --commit <sha>`
 
 ### Overrides (exceptional)
@@ -272,6 +288,13 @@ Optional prompt overrides:
 
 Check readiness with `codex-orchestrator doctor --format json` (reports DevTools skill + MCP config availability). Use `codex-orchestrator devtools setup` to print setup steps.
 
+## Linear Runtime Proof Handoff
+- Use `codex-orchestrator linear runtime-proof --issue-id <issue-id> --origin <app-url> --format json` to inspect the permit posture for app-touching lanes before review handoff.
+- When the permit allows a proof mode, rerun with `--kind <screenshot|external-link|video> --proof-url <reviewer-url>` plus optional `--title` / `--summary` to generate `handoff.workpad_markdown` and `handoff.pr_markdown`.
+- The helper is intentionally fail-closed for reviewer handoff: unreadable permit files, unapproved origins, blocked proof kinds, and local-only artifact paths all return non-zero instead of pretending proof is review-ready.
+- Screenshot and external-link proof are controlled independently through `compliance/permit.json` `runtime_proof.allow_screenshot` and `runtime_proof.allow_external_link`; video stays disabled unless `runtime_proof.allow_video` or legacy `allow_video_capture` explicitly enables it.
+- Add `--reachability-mode dns-public` only when you want explicit worker-local DNS public-resolution evidence for the reviewer URL. The default deterministic path never depends on live DNS, and a dns-public pass is still only worker-local evidence, not a universal reviewer-reachability guarantee.
+
 ## Mirror Workflows
 - `npm run mirror:fetch -- --project <name> [--dry-run] [--force]`: reads `packages/<project>/mirror.config.json` (origin, routes, asset roots, rewrite/block/allow lists), caches downloads **per project** under `.runs/<task>/mirror/<project>/cache`, strips tracker patterns, rewrites externals to `/external/<host>/...`, localizes OG/twitter preview images, rewrites share links off tracker-heavy hosts, and stages into `.runs/<task>/mirror/<project>/<timestamp>/staging/public` before promoting to `packages/<project>/public`. Non-origin assets fall back to Web Archive when the primary host is down; promotion is skipped if errors are detected unless `--force` is set. Manifests live at `.runs/<task>/mirror/<project>/<timestamp>/manifest.json` (warns when `MCP_RUNNER_TASK_ID` is unset; honors `compliance/permit.json` when present).
 - `npm run mirror:serve -- --project <name> [--port <port>] [--csp <self|strict|off>] [--no-range]`: shared local-mirror server with traversal guard, HTML no-cache/asset immutability, optional CSP, optional Range support, and directory-listing blocks.
@@ -297,7 +320,7 @@ Use the hi-fi pipeline to snapshot complex marketing sites (motion, interactions
    python3 -m http.server 4173
    ```
    The build now mirrors all `/assets/...` content and adds root shortcuts (`wp-content`, `wp-includes`, etc.) so even absolute WordPress paths work offline. A lightweight `codex-scroll-fallback` script only unlocks scrolling if the captured page never enables it.
-6. **Document learnings:** Drop run evidence into `docs/findings/<slug>.md` (see `docs/findings/ethical-life.md` for the latest example) so reviewers know which manifest, artifacts, and diffs back each finding.
+6. **Document learnings:** Drop run evidence into `docs/findings/<slug>.md` (see `docs/findings/slimdown-audit.md` for a current example) so reviewers know which manifest, artifacts, and diffs back each finding.
 
 ## Extending the Orchestrator
 - Add new agent strategies by implementing the planner/builder/tester/reviewer interfaces and wiring them into `TaskManager`.

package/docs/book/README.md

@@ -0,0 +1,19 @@
+# Codex Orchestrator Book
+
+This folder keeps the long-form public and maintainer guidance out of the GitHub front door while preserving stable links for operators and reviewers.
+
+## Contents
+
+- [Setup](setup.md): npm baseline, Codex marketplace/plugin install, rollback, downstream bootstrap, and provider onboarding links
+- [Operations](operations.md): common commands, run artifacts, workflow modes, and review handoff expectations
+- [Bundled Skills](skills.md): install behavior and pointer to the canonical roster in [skills/README.md](../../skills/README.md)
+- [Public Posture](public-posture.md): current compatibility target, model/runtime posture, and evidence gates
+- [Local Hook Impact](local-hook-impact.md): evidence for the local CO auto-continue hook and whether it affects subagents/provider agents
+- [Codex CLI 0.124.0 Adoption Evidence](codex-cli-0124-adoption.md): historical CO-341/CO-345 evidence for the `0.124.0` step; see the canonical version policy for the current local ChatGPT-auth appserver/model posture, package/downstream-smoke `0.125.0` compatibility, and cloud-only `0.124.0` candidate split
+
+## Navigation Contract
+
+- Keep the root [README.md](../../README.md) concise.
+- Put detailed setup and posture guidance in this folder or in the focused public guides under [docs/public](../public/).
+- Keep canonical version-policy decisions in [docs/guides/codex-version-policy.md](../guides/codex-version-policy.md) and summarize them here instead of duplicating the full policy.
+- Keep task-specific evidence in the task packet; link to durable summaries when a future operator needs the decision context.

package/docs/book/codex-cli-0124-adoption.md

@@ -0,0 +1,68 @@
+# CO-345 Evidence Book: Codex CLI 0.124.0 Adoption Evidence
+
+Scope: CO-345 README/book evidence page. This page preserves the CO-341/CO-345 `codex-cli 0.124.0` adoption step against repo evidence and official OpenAI Codex docs. Current posture has since moved: release-facing package/downstream-smoke compatibility and local ChatGPT-auth/appserver posture now use `0.125.0`, while cloud execution remains separately pinned to `0.124.0`. This page does not change runtime defaults.
+
+## Bottom Line
+
+CO adopted Codex CLI `0.124.0` as the repo compatibility target during CO-341/CO-345.
+
+That adoption was intentionally narrow. It promoted `0.124.0` after CO-341 runtime, cloud, pack-smoke, and review evidence while keeping packaged/generated model defaults on portable `gpt-5.4` with `model_reasoning_effort = "xhigh"`. Local ChatGPT-auth `gpt-5.5` / `xhigh` remained a marker-backed local opt-in rather than the generic shipped default. Current local ChatGPT-auth appserver/model posture, package/downstream-smoke `0.125.0` compatibility, and the cloud-only `0.124.0` candidate split now live in `docs/guides/codex-version-policy.md`.
+
+## Evidence Boundary
+
+Host-specific absolute paths and local account state stay in the CO-345 task packet, Linear workpad, and run artifacts. This shipped page records the portable adoption decision and the evidence classes without exposing operator-local paths.
+
+## Recorded Evidence Snapshot
+
+Commands were run from the issue workspace or the active operator environment during CO-345/CO-341 evidence gathering.
+
+| Evidence | Observation |
+| --- | --- |
+| `which codex` | The active executable was identified before posture checks. |
+| `codex --version` | Active executable reports `codex-cli 0.124.0`. |
+| `codex login status` | Local CLI auth state was checked before model/posture conclusions. |
+| `codex debug models` | Live model catalog includes `gpt-5.4`, `gpt-5.5`, and `gpt-5.3-codex-spark`; `gpt-5.4` and `gpt-5.5` expose `low/medium/high/xhigh` reasoning levels. |
+| `codex debug models --bundled` | Bundled catalog filtering found `gpt-5.4`; local `gpt-5.5` is not treated as a portable bundled default. |
+| User-level Codex config | The inspected operator environment has an explicit local `gpt-5.5` / `xhigh` opt-in; this is not a packaged/generated default. |
+| `codex features list` | Local feature list reports `multi_agent`, `plugins`, `apps`, `tool_search`, and `codex_hooks` as stable/enabled; `js_repl` and `memories` are experimental/enabled. |
+| `codex exec --help` | Supports `[PROMPT]`, stdin appending, `resume`, `review`, `--output-schema`, `--json`, `--ignore-user-config`, and feature toggles. |
+| `codex review --help` | Supports `[PROMPT]`, `--uncommitted`, `--base`, `--commit`, `--title`, and feature toggles. |
+
+## Official OpenAI Docs Context
+
+Official Codex docs describe the CLI setup, ChatGPT/API-key auth, app-server APIs, model/config fields, feature flags, plugin marketplace operations, skills listing, and feature maturity levels. Those docs support treating the 0.124-era local surfaces as real capabilities, while still requiring repo-specific evidence before CO changes shipped defaults or provider-worker supervision.
+
+Relevant docs:
+
+- [Codex CLI setup](https://developers.openai.com/codex/cli#cli-setup)
+- [Codex auth](https://developers.openai.com/codex/auth#sign-in-with-chatgpt)
+- [Codex CLI reference: login](https://developers.openai.com/codex/cli/reference#codex-login)
+- [Codex config reference](https://developers.openai.com/codex/config-reference#configtoml)
+- [Codex app-server](https://developers.openai.com/codex/app-server)
+- [Codex feature maturity](https://developers.openai.com/codex/feature-maturity)
+
+## Repo Adoption Matrix
+
+| Surface | Current posture on `main` | Classification |
+| --- | --- | --- |
+| Compatibility target | This page records the previous `0.124.0` target evidence; current local ChatGPT-auth appserver/model posture, package/downstream-smoke `0.125.0` compatibility, and the cloud-only `0.124.0` candidate split live in `docs/guides/codex-version-policy.md`. | Historical evidence |
+| Packaged/generated model defaults | `gpt-5.4` with `model_reasoning_effort = "xhigh"`. | Adopted, intentionally portable |
+| Local `gpt-5.5` / `xhigh` | Allowed after live access smoke plus `[codex_orchestrator] local_model_opt_in = "gpt-5.5"`. | Adopted as local opt-in |
+| Generic shipped `gpt-5.5` default | Not promoted because bundled/cloud/API portability remains unproven. | Held |
+| Appserver runtime | Local appserver remains the default runtime path. | Adopted |
+| `executionMode=cloud` + `runtimeMode=appserver` | Still fails fast as unsupported. | Held |
+| Provider-worker supervision | Still uses `codex exec` / `codex exec resume` until a separate app-server control seam lands. | Held |
+| `explorer_fast` | Remains `gpt-5.3-codex-spark` for file/codebase search only. | Adopted exception |
+| Marketplace/plugin guidance | npm remains baseline; Codex `0.121.0` accepts `codex marketplace add` or `codex plugin marketplace add`, while `0.122.0+` uses `codex plugin marketplace add`. | Adopted |
+
+## Follow-Up Assessment
+
+CO-345 did not find a new unresolved `0.124.0` adoption blocker that belonged in a follow-up issue.
+
+The meaningful holds are already intentional posture boundaries:
+
+- Do not promote `gpt-5.5` as a generic shipped default from local ChatGPT-auth evidence alone.
+- Do not move provider workers from `codex exec` / `codex exec resume` without a separate governed app-server control seam.
+- Do not treat experimental or under-development feature flags as default CO behavior without task-scoped evidence.
+
+Those holds were policy, not README-cleanup defects. Current posture and newer holds are recorded in `docs/guides/codex-version-policy.md`.

package/docs/book/local-hook-impact.md

@@ -0,0 +1,73 @@
+# CO-345 Evidence Book: Local Hook Impact
+
+Date: 2026-04-24
+
+Scope: docs-only child lane for CO-345. This page covers local Codex hook impact only. It does not change hook configuration, repo policy, README content, task packets, Linear state, or PR state.
+
+## Bottom Line
+
+Local hooks are an ambient host-level input, not a repo-shipped CO behavior in this child lane.
+
+The checked-out lane contains no repo-level Codex hooks config file and no repo-local Codex hook scripts. It does contain the tracked utility script `scripts/hooks/continue_co_orchestration.py`, but no repo config wires that script into Codex hooks in this lane. The inspected operator environment has user-level hook configuration under `${CODEX_HOME:-~/.codex}/hooks/`, and `codex features list` on the active `codex-cli 0.124.0` install reports `codex_hooks` as enabled.
+
+Current conclusion: the inspected user-level `continue_co_orchestration.py` hook does not directly affect spawned subagents or Linear/provider agents under the inspected state because the hook only emits a blocking auto-continue prompt when hooks are enabled, the event `cwd` is inside the local CO checkout, no stop sentinel is present, and the event `session_id` matches the configured `root_session_id`. The inspected state has `root_session_id` set, so other Codex sessions, subagent sessions, and provider-worker sessions with different ids fall through with `{"continue": true}`. If `root_session_id` is cleared later, the same hook would become broader for any hook-enabled Codex event inside the CO repo tree.
+
+## Evidence Boundary
+
+Host-specific absolute paths and local state values stay in the CO-345 task packet, Linear workpad, and run artifacts. This shipped page records the portable conclusion and the evidence classes without exposing operator-local paths.
+
+## Official Codex Hook Semantics
+
+Official OpenAI Codex docs describe hooks as a lifecycle extensibility framework for running deterministic scripts inside the Codex loop. The docs identify the useful hook locations as user-level hooks.json and repo-level .codex/hooks.json; if more than one hook file exists, Codex loads all matching hooks, and a higher-precedence config layer does not replace lower-precedence hooks. The docs also note that matching hooks for the same event can run concurrently, and that hooks are behind the `features.codex_hooks` flag. Sources: [Hooks](https://developers.openai.com/codex/hooks), [Advanced configuration: Hooks](https://developers.openai.com/codex/config-advanced#hooks-experimental), [Config basics: Supported features](https://developers.openai.com/codex/config-basic#supported-features).
+
+Important limits from the same docs:
+
+| Hook area | Documented behavior | CO-345 impact |
+| --- | --- | --- |
+| Load path | Codex discovers hooks next to active config layers, including user-level and repo-level files. | A user-level hook can affect this lane even when the repo does not ship a hook file. |
+| Multiple hooks | All matching hooks load; higher-precedence config does not replace lower-precedence hooks. | Adding a repo hook in a later issue would not automatically disable a user hook. |
+| Command hooks | Multiple matching command hooks for one event launch concurrently. | Hook ordering should not be used as a correctness dependency. |
+| `PreToolUse` | Current docs frame Bash interception as incomplete and a guardrail, not a complete enforcement boundary. | A hook can add safety signal but does not replace CO approval, sandbox, and review gates. |
+| `PostToolUse` | It cannot undo side effects from a command that already ran. | It is evidence/continuation signal, not rollback. |
+| Windows | Hooks are currently disabled on Windows in the docs. | Cross-platform claims need separate validation before repo-level hook adoption. |
+
+## Lane Evidence
+
+Commands were run from the issue workspace only, unless noted.
+
+| Evidence | Observation |
+| --- | --- |
+| `git status --short` | Clean before edits. |
+| `find docs/book -maxdepth 2 -type f -print` | `docs/book/` did not exist before this child lane created the two scoped docs files. |
+| `find . -maxdepth 4 -path '*hooks.json' -o -path '*/.codex/hooks/*' -o -path '*/hooks/*'` | No repo Codex hook config was found under `.codex`; `scripts/hooks/continue_co_orchestration.py` exists as a tracked utility/script surface and is not wired by repo config in this lane. |
+| `find .codex -maxdepth 3 -type f -print` | `.codex/orchestrator.toml` exists and contains `[sandbox] network = true`; no repo hook config was present. |
+| `codex features list` | Local `codex-cli 0.124.0` reports `codex_hooks` as `stable true`. |
+| User-level Codex config | `codex_hooks` and `multi_agent` are enabled in the inspected operator environment. |
+| User-level hook script | The installed user-level hook is the operative local hook; it differs from the tracked utility script and adds `root_session_id` scoping plus memory-citation handling. It checks repo containment, allows exact stop sentinels, and otherwise emits the auto-continue orchestration prompt. Exceptions fail open with `{"continue": true}`. |
+| User-level hook state | Current state is enabled for the local CO checkout, and `root_session_id` is non-empty. |
+
+## Risk Posture
+
+The local hook surface is a real source of run variance because user-level hooks can load outside the repo. That is useful for operator safety and local automation, but it is not portable evidence that CO itself ships or requires hooks.
+
+The parent lane should classify hook-driven observations into three categories:
+
+| Category | Treatment |
+| --- | --- |
+| Repo-local hook behavior | Requires committed or patch-visible repo-level Codex hook wiring. Not present in this child lane; the tracked `scripts/hooks/` utility is not active by itself. |
+| User-local hook behavior | May affect local runs through user-level Codex hook config. In the inspected state it is scoped by a non-empty `root_session_id`, so different subagent/provider sessions fall through. |
+| Official Codex hook capability | Cite OpenAI docs for expected semantics, but validate actual local behavior on the active CLI before depending on it. |
+
+## Recommended Parent Handling
+
+- Preserve this page as evidence that this child lane found no repo-level Codex hook config, while separately noting the tracked `scripts/hooks/` utility script.
+- Keep the local auto-continue hook out of shipped README/setup guidance. It is a local operator guard, not a downstream CO default.
+- If a future issue wants broader local auto-continue behavior, require a separate governed lane because clearing `root_session_id` would broaden the hook to any hook-enabled Codex session inside the CO repo tree.
+- If CO wants repo-governed hooks, open a separate docs-first implementation lane that owns repo-level hook configuration, hook scripts, cross-platform policy, and focused hook tests.
+- For adoption canaries, compare a normal local run against a run with `--disable codex_hooks` when the goal is to isolate hook-driven behavior from Codex CLI behavior.
+
+## Sources
+
+- OpenAI Codex Hooks: https://developers.openai.com/codex/hooks
+- OpenAI Codex Advanced Configuration, Hooks: https://developers.openai.com/codex/config-advanced#hooks-experimental
+- OpenAI Codex Config Basics, Supported features: https://developers.openai.com/codex/config-basic#supported-features

package/docs/book/operations.md

@@ -0,0 +1,60 @@
+# Operations
+
+## Task-Scoped Runs
+
+Use a task id for every governed run so manifests, metrics, and summaries are grouped consistently.
+
+```bash
+export MCP_RUNNER_TASK_ID=<task-id>
+codex-orchestrator start diagnostics --task <task-id> --format json
+codex-orchestrator status --run <run-id> --watch --interval 10
+```
+
+Run artifacts live under:
+
+- `.runs/<task-id>/cli/<run-id>/manifest.json`
+- `.runs/<task-id>/metrics.json`
+- `out/<task-id>/state.json`
+
+## Common Workflows
+
+```bash
+codex-orchestrator flow --task <task-id>
+codex-orchestrator review --task <task-id>
+codex-orchestrator doctor --usage --window-days 30
+codex-orchestrator co-status
+codex-orchestrator control-host supervise status --format json
+```
+
+`flow` runs the docs-review and implementation-gate sequence. `review` prepares reviewer handoff evidence and can execute Codex review when the environment is configured to force non-interactive review execution.
+
+## Execution Modes
+
+- Default execution mode is `mcp`.
+- Cloud mode is reserved for long-running, highly parallel, or locally constrained work after preflight confirms branch/ref, non-interactive setup, and required cloud secrets.
+- `runtimeMode=cli|appserver` is independent of `executionMode=mcp|cloud`.
+- Local appserver remains the expected default runtime path.
+- `executionMode=cloud` with explicit `runtimeMode=appserver` is unsupported and should fail fast.
+
+## Validation Floor
+
+For implementation work, use the repo-local gate list from `AGENTS.md`. For documentation-only README/book work, the targeted floor is:
+
+```bash
+node scripts/spec-guard.mjs --dry-run
+npm run docs:check
+npm run docs:freshness
+node scripts/diff-budget.mjs
+```
+
+Add build, lint, tests, pack smoke, or runtime proof when the diff touches scripts, package surfaces, runtime behavior, or UI/app surfaces.
+
+## Review Handoff
+
+Before handing an issue to `Human Review` or `In Review`, refresh the Linear workpad with:
+
+- final implementation summary
+- validation results
+- standalone review or fallback review evidence
+- explicit elegance/minimality pass result
+- PR link and ready-review drain result when a PR exists

package/docs/book/public-posture.md

@@ -0,0 +1,34 @@
+# Public Posture
+
+## Stable Compatibility Vs Local Posture
+
+CO's current release-facing package/downstream-smoke compatibility target is Codex CLI `0.125.0`. Current `gpt-5.5` / `xhigh` local ChatGPT-auth/appserver posture and release-facing package Codex CLI pins are already adopted; cloud execution remains separately gated by the canonical version policy.
+
+Newer stable and prerelease Codex CLI builds remain evidence-gated. The canonical policy is [docs/guides/codex-version-policy.md](../guides/codex-version-policy.md).
+
+## Current Model / Runtime Posture
+
+- Current model posture: `gpt-5.5` / `xhigh` when available in ChatGPT-auth Codex sessions.
+- Portable packaged/generated defaults keep `gpt-5.4` / `xhigh` as fallback values when `gpt-5.5`, API, or cloud portability is unavailable.
+- Local `gpt-5.5` use is the current CO posture after live access smoke; legacy marker metadata is ignored for posture decisions.
+- `explorer_fast` remains the explicit `gpt-5.3-codex-spark` exception for file/codebase search only.
+- Local appserver remains the expected default runtime path.
+- Provider workers keep the current `codex exec` / `codex exec resume` supervision seam until a separate governed lane promotes a replacement.
+
+## Evidence Gates
+
+Local model-posture updates must record:
+
+1. Local appserver path success on the candidate Codex CLI and model posture.
+2. Delegated/review surface verification under the actual auth provider.
+3. `node scripts/runtime-mode-canary.mjs` success.
+4. No P0/P1 regression versus the current stable baseline.
+
+Cloud execution or release-facing promotion additionally requires:
+
+1. Required cloud canary success with configured cloud env.
+2. Cloud fallback contract success.
+
+## Marketplace Split
+
+Marketplace/plugin support is additive. npm remains the supported baseline install path. Release-facing smoke lanes can stay pinned to a marketplace-capable Codex CLI while newer candidates are audited separately for cloud/runtime posture.

package/docs/book/setup.md

@@ -0,0 +1,91 @@
+# Setup
+
+## Baseline Install
+
+CO is shipped as the scoped npm package `@kbediako/codex-orchestrator`.
+
+```bash
+npm i -g @kbediako/codex-orchestrator
+codex-orchestrator --version
+```
+
+Node.js `>=20` is required. npm remains the supported baseline because it gives downstream operators the CLI directly without requiring Codex plugin support.
+
+## Machine Setup
+
+```bash
+codex login
+codex-orchestrator --version
+```
+
+Use `codex login --device-auth` when browser auth is not practical.
+
+Run repo-bound `codex-orchestrator setup --yes --repo /path/to/repo` after bootstrapping the downstream repository so delegation is registered with the repo root while bundled skills are installed and DevTools wiring is applied at the machine level.
+
+## Codex Marketplace / Plugin Install
+
+Use this path only on Codex releases that expose the marketplace/plugin flow. The npm install remains the baseline CLI path.
+
+Packaged npm source:
+
+```bash
+# Codex 0.121.0 accepts either command.
+codex marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
+
+# Codex 0.122.0+ uses the plugin command.
+codex plugin marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
+```
+
+For a local checkout, pass the repository root instead of the npm install path. For a Git-backed source, pass `owner/repo[@ref]`, an HTTPS Git URL, or an SSH Git URL. Use `codex marketplace add ...` only on Codex `0.121.0`; use `codex plugin marketplace add ...` on `0.122.0+`.
+
+On current Codex CLI `0.125.0`, refresh a Git-backed marketplace checkout with:
+
+```bash
+codex plugin marketplace upgrade codex-orchestrator
+```
+
+Then open `/plugins` in Codex, install `Codex Orchestrator`, and restart Codex if the plugin does not appear immediately.
+
+The shipped marketplace files are:
+
+- `.agents/plugins/marketplace.json`
+- `plugins/codex-orchestrator/.codex-plugin/plugin.json`
+- `plugins/codex-orchestrator/.mcp.json`
+- `plugins/codex-orchestrator/launcher.mjs`
+
+The plugin launcher reads the `codex-orchestrator` marketplace entry in `${CODEX_HOME:-~/.codex}/config.toml` and resolves the recorded source checkout before starting the packaged CO CLI with `node`. Local-directory sources run from the recorded path. Git-backed sources run from Codex's installed marketplace checkout under `${CODEX_HOME:-~/.codex}/.tmp/marketplaces/codex-orchestrator`.
+
+Re-run the version-appropriate marketplace add command after moving a local-directory source, replacing it, or removing Codex's installed marketplace checkout.
+
+CO-355 only rebaselines marketplace/downstream-smoke compatibility to Codex CLI `0.125.0`. Model/runtime posture remains governed by `docs/guides/codex-version-policy.md` and the CO-351/CO-352 validation lanes: use `gpt-5.5` / `xhigh` for validated local ChatGPT-auth/appserver access, and keep `gpt-5.4` / `xhigh` as the portable fallback when access, API/cloud portability, or downstream/no-network evidence is missing.
+
+## Rollback / Removal
+
+- Uninstall `Codex Orchestrator` from the Codex plugin browser to remove the plugin.
+- Set the plugin entry in `${CODEX_HOME:-~/.codex}/config.toml` to `enabled = false` to disable without uninstalling.
+- On Codex CLI `0.125.0` or newer, remove the marketplace registration with `codex plugin marketplace remove codex-orchestrator`; on older support lanes or when that command is unavailable, remove the `[marketplaces.codex-orchestrator]` block from `${CODEX_HOME:-~/.codex}/config.toml` manually.
+- Remove the standalone CLI with:
+  ```bash
+  npm uninstall -g @kbediako/codex-orchestrator
+  ```
+
+## Repository Bootstrap
+
+```bash
+codex-orchestrator init codex --cwd /path/to/repo
+cd /path/to/repo
+codex-orchestrator setup --yes --repo /path/to/repo
+codex-orchestrator doctor --format json
+codex-orchestrator flow --task <task-id>
+```
+
+`init codex` seeds:
+
+- `AGENTS.md`
+- `.codex/config.toml`
+- `.codex/providers/README.md`
+- `.codex/providers/provider.env.example`
+- `.codex/providers/control.example.json`
+- `codex.orchestrator.json`
+
+Provider-specific setup continues in [docs/public/provider-onboarding.md](../public/provider-onboarding.md).

package/docs/book/skills.md

@@ -0,0 +1,11 @@
+# Bundled Skills
+
+Install bundled skills into `$CODEX_HOME/skills`:
+
+```bash
+codex-orchestrator skills install
+```
+
+The canonical shipped roster lives in [skills/README.md](../../skills/README.md). `docs:check` uses that file as the shipped-file parity surface so the GitHub front door can stay concise.
+
+Prefer globally installed skills when present, fall back to bundled `skills/<name>/SKILL.md`, and refresh skills after upgrading the npm package when you need new workflow instructions.