@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "codex-orchestrator",
+  "interface": {
+    "displayName": "Codex Orchestrator"
+  },
+  "plugins": [
+    {
+      "name": "codex-orchestrator",
+      "source": {
+        "source": "local",
+        "path": "./plugins/codex-orchestrator"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/README.md

@@ -1,352 +1,81 @@
 # Codex Orchestrator
 
-![Setup demo](docs/assets/setup.gif)
+Codex Orchestrator (CO) is a CLI and runtime for Codex-driven pipelines, auditable manifests, delegation workflows, and downstream repo bootstrapping.
 
-Codex Orchestrator is the CLI + runtime that coordinates Codex-driven runs, pipelines, and delegation MCP tooling. The npm release focuses on running pipelines locally, emitting auditable manifests, and hosting the delegation server.
+## Release Posture
 
-## Install
-
-- Global install (recommended for CLI use):
-  ```bash
-  npm i -g @kbediako/codex-orchestrator
-  ```
-- After install, use either `codex-orchestrator` or the short alias `codex-orch`:
-  ```bash
-  codex-orchestrator --version
-  ```
-- Or run via npx:
-  ```bash
-  npx @kbediako/codex-orchestrator --version
-  ```
-
-Node.js >= 20 is required.
-
-## Quick start
-
-1. Run a pipeline with a task id so artifacts are grouped under `.runs/<task-id>/`:
-   ```bash
-   codex-orch start diagnostics --format json --task <task-id>
-   ```
-   The command prints the `run_id` plus the manifest path under `.runs/<task-id>/cli/<run-id>/manifest.json`.
-2. Watch status:
-   ```bash
-   codex-orch status --run <run-id> --watch --interval 10
-   ```
-3. Resume if needed:
-   ```bash
-   codex-orch resume --run <run-id>
-   ```
-   > Tip: if you prefer `npx`, replace `codex-orch` with `npx @kbediako/codex-orchestrator`.
-   > Tip: for multiple commands, you can also `export MCP_RUNNER_TASK_ID=<task-id>` once.
-
-## Runtime + Execution Modes
-
-- Mode semantics are orthogonal:
-  - `executionMode=mcp|cloud` controls where stages execute.
-  - `runtimeMode=cli|appserver` controls local runtime provider selection.
-- Local default runtime is `appserver`; preserve `--runtime-mode cli` as break-glass.
-- `--execution-mode cloud --runtime-mode appserver` is intentionally unsupported and fails fast with actionable errors.
-- `js_repl` is enabled by default globally. For deterministic cloud contracts, run 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).
+This README tracks the current `main` branch. Published-package users should follow the README and docs for the tag or release they installed.
 
-## Downstream init (recommended)
+- Latest package docs: [GitHub releases](https://github.com/Kbediako/CO/releases/latest)
+- Older `v0.2.0` package docs: [README for `v0.2.0`](https://github.com/Kbediako/CO/blob/v0.2.0/README.md)
+- Detailed source-head docs: [docs/book/README.md](docs/book/README.md)
 
-Use this when you want Codex to drive work inside another repo with the CO defaults.
-
-1. Install templates:
-   ```bash
-   codex-orchestrator init codex --cwd /path/to/repo
-   ```
-   One-shot (templates + optional CO-managed Codex CLI install):
-   ```bash
-   codex-orchestrator init codex --codex-cli --yes
-   ```
-   This seeds `AGENTS.md`, `mcp-client.json`, and downstream .codex/config.toml + .codex/agents/* role files (sourced from `templates/codex/.codex/*`), plus `codex.orchestrator.json`.
-2. Register the delegation MCP server (one-time per machine):
-   ```bash
-   codex mcp add delegation -- codex-orchestrator delegate-server --repo /path/to/repo
-   ```
-3. Optional (managed/pinned CLI path): set up a CO-managed Codex CLI:
-   ```bash
-   codex-orchestrator codex setup
-   ```
-   Use this when you want a pinned binary, build-from-source behavior, or a custom fork.
-   Stock/global `codex` is still the default selection; activate managed binary routing with:
-   ```bash
-   export CODEX_CLI_USE_MANAGED=1
-   ```
-4. Optional (additive global defaults in `~/.codex/config.toml`):
-   ```bash
-   codex-orchestrator codex defaults
-   codex-orchestrator codex defaults --yes
-   ```
-   This updates only the CO baseline keys/role wiring and preserves unrelated config entries.
-5. Optional (fast refresh helper for downstream users):
-   ```bash
-   scripts/codex-cli-refresh.sh --repo /path/to/codex --align-only
-   ```
-   Repo-only helper (not included in npm package). Add `--no-push` when you only want local alignment and do not want to update `origin/main`. To refresh the CO-managed CLI, run a separate command with `--force-rebuild` (without `--align-only`). Set `CODEX_REPO` or `CODEX_CLI_SOURCE` to avoid passing `--repo` each time.
-
-## Delegation MCP server
-
-Run the delegation MCP server over stdio:
-```bash
-codex-orchestrator delegate-server --repo /path/to/repo
-```
-Optional: add `--mode question_only` to disable `delegate.spawn/pause/cancel`, keeping only `delegate.question.*` + `delegate.status` in the delegate namespace. GitHub tools remain available when GitHub integration is enabled.
+## Install
 
-Register it with Codex once. Delegation MCP is enabled by default (the only MCP enabled by default). To override the default or re-enable after disabling:
 ```bash
-codex mcp add delegation -- codex-orchestrator delegate-server --repo /path/to/repo
-codex -c 'mcp_servers.delegation.enabled=true' ...
-```
-`delegate-server` is the canonical name; `delegation-server` is supported as an alias (older docs may use it).
-
-## Agent role defaults (recommended)
-
-Codex built-ins are `default`, `explorer`, `worker`, and `awaiter`. `researcher` is user-defined.
-- `spawn_agent` defaults to `default` when `agent_type` is omitted, so always set `agent_type` explicitly.
-- Multi-turn loops are supported (`spawn_agent` -> `send_input` -> `wait`/`resume_agent` -> `close_agent`), so subagents can iterate before parent synthesis.
-- Keep `fork_context` off by default for bounded subagent streams; set `fork_context=true` only when the subagent must inherit prior thread history.
-
-In Codex CLI `0.105.0`, built-in `explorer` no longer pins an older model profile; it inherits top-level defaults unless you attach a role `config_file`.
-CO now ships this downstream starter config via `init codex` (source template: `templates/codex/.codex/config.toml`; installed as .codex/config.toml in target repos):
-
-```toml
-model = "gpt-5.3-codex"
-model_reasoning_effort = "xhigh"
-
-[agents]
-max_threads = 12
-max_depth = 4
-max_spawn_depth = 4
-
-[agents.explorer_fast]
-description = "Fast explorer (spark text-only)."
-config_file = "./agents/explorer-fast.toml"
-
-[agents.worker_complex]
-description = "Complex worker role."
-config_file = "./agents/worker-complex.toml"
-
-[agents.awaiter]
-description = "Awaiter override (keeps awaiter behavior with latest codex/high reasoning)."
-config_file = "./agents/awaiter-high.toml"
-```
-
-```toml
-# .codex/agents/explorer-fast.toml
-model = "gpt-5.3-codex-spark"
-model_reasoning_effort = "xhigh"
-```
-
-```toml
-# .codex/agents/worker-complex.toml
-model = "gpt-5.3-codex"
-model_reasoning_effort = "xhigh"
-```
-
-`init codex` also writes downstream .codex/agents/awaiter-high.toml from `templates/codex/.codex/agents/awaiter-high.toml` so CO users can keep awaiter semantics while meeting a high-reasoning minimum.
-
-Caveats:
-- `gpt-5.3-codex-spark` is text-only (no image inputs). Keep it for fast search/synthesis.
-- Leave `agents.explorer` undefined unless you intentionally want to override built-in explorer behavior.
-- Keep RLM/collab built-ins-first by default; add specialist custom roles only when a measured benefit justifies ongoing maintenance.
-- `max_threads = 12`, `max_depth = 4`, and `max_spawn_depth = 4` are CO's standard multi-agent baseline.
-- Fallbacks are contingency-only: use `8/2/2` on constrained hosts or deterministic high-risk lanes; use `6/1/1` only as break-glass under severe contention.
-- Awaiter triage: long waits are expected for long-running jobs; treat it as stuck only after multiple polling windows with no status/progress movement.
-- `codex review` delegates with collab tools disabled in review threads; keep review expectations single-agent even when multi-agent is enabled elsewhere.
-
-Delegation guard profile:
-- `CODEX_ORCHESTRATOR_GUARD_PROFILE=auto` (default): strict in CO-style repos, warn in lightweight repos.
-- Set `CODEX_ORCHESTRATOR_GUARD_PROFILE=warn` for ad-hoc/no-task-id runs.
-- Set `CODEX_ORCHESTRATOR_GUARD_PROFILE=strict` to enforce full delegation evidence checks.
-
-## Delegation + RLM flow
-
-RLM (Recursive Language Model) is the long-horizon loop used by the `rlm` pipeline (`codex-orchestrator rlm "<goal>"` or `codex-orchestrator start rlm --goal "<goal>"`). Delegated runs only enter RLM when the child is launched with the `rlm` pipeline (or the rlm runner directly). In auto mode it resolves to symbolic only when context is large (`RLM_SYMBOLIC_MIN_BYTES`) and an explicit context signal is present (`RLM_CONTEXT_PATH` or delegated run); otherwise it stays iterative. The runner writes state to `.runs/<task-id>/cli/<run-id>/rlm/state.json` and stops when the validator passes or budgets are exhausted.
-For symbolic mode, the Option 2 alignment checker is enabled by default (`RLM_ALIGNMENT_CHECKER=1`) and writes append-only alignment artifacts under `.runs/<task-id>/cli/<run-id>/rlm/alignment/` (ledger + projection). Rollback toggle: set `RLM_ALIGNMENT_CHECKER=0`. Enforcement is opt-in via `RLM_ALIGNMENT_CHECKER_ENFORCE=1`.
-Symbolic subcalls can optionally use collab tools. Fast path: `codex-orchestrator rlm --multi-agent auto "<goal>"` (legacy alias: `--collab auto`; sets `RLM_SYMBOLIC_MULTI_AGENT=1` plus legacy `RLM_SYMBOLIC_COLLAB=1` for compatibility, and implies symbolic mode). Collab requires `multi_agent=true` in `codex features list` (`collab` remains a legacy alias). Collab tool calls parsed from `codex exec --json --enable multi_agent` are stored in `manifest.collab_tool_calls` (bounded by `CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS`, set to `0` to disable); when present in events, `spawn_agent.fork_context` is captured for observability and surfaced in `codex-orchestrator doctor --usage` fork-context counters. For auditable role routing, prefix spawned prompts with `[agent_type:<role>]` and set `spawn_agent.agent_type` when supported; lifecycle validation enforces prompt-role evidence and validates `agent_type` when present (`RLM_SYMBOLIC_MULTI_AGENT_ROLE_POLICY=warn|off`, legacy alias `RLM_COLLAB_ROLE_POLICY`; `RLM_SYMBOLIC_MULTI_AGENT_ALLOW_DEFAULT_ROLE=1`, legacy alias `RLM_COLLAB_ALLOW_DEFAULT_ROLE`). `codex-orchestrator codex setup` remains available when you want a managed/pinned CLI path (opt-in via `CODEX_CLI_USE_MANAGED=1`).
-For batch fan-out jobs, prefer native `spawn_agents_on_csv` before building custom orchestration wrappers.
-
-### Delegation flow
-```mermaid
-flowchart TB
-  A["Parent run<br/>(delegation MCP enabled)"]
-  C["Delegation MCP server"]
-  D["delegate.spawn"]
-  E["Child run<br/>(pipeline resolved)"]
-  N{Pipeline = rlm?}
-  P["Standard pipeline<br/>(plan/build/test/review)"]
-  RLM["RLM pipeline<br/>(see next chart)"]
-
-  A --> C --> D --> E --> N
-  N -- yes --> RLM
-  N -- no --> P
-  E -. optional .-> Q["delegate.question.enqueue/poll"] -.-> A
+npm i -g @kbediako/codex-orchestrator
+codex-orchestrator --version
 ```
 
-### RLM loop
-```mermaid
-flowchart TB
-  F["Resolve mode<br/>(auto -> iterative/symbolic)"]
-  G{Symbolic?}
-  H["Context store<br/>(chunk + search)"]
-  I["Planner JSON<br/>(select subcalls)"]
-  J["Subcalls<br/>(tool + edits, collab optional)"]
-  K["Validator<br/>(test command)"]
-  L["State + artifacts<br/>.runs/&lt;task-id&gt;/cli/&lt;run-id&gt;/rlm/state.json"]
-  M["Exit status"]
+Node.js `>=20` is required. npm remains the supported baseline install path.
 
-  F --> G
-  G -- yes --> H --> I --> J --> K
-  G -- no --> J
-  J --> K
-  K --> L --> M
-  K -- fail & budget left --> F
-```
-
-## Skills (bundled)
+## Current Posture
 
-Recommended one-shot bootstrap (skills + delegation + DevTools wiring):
-```bash
-codex-orchestrator setup --yes
-# Optional: overwrite existing bundled skills in $CODEX_HOME/skills
-# codex-orchestrator setup --yes --refresh-skills
-```
-
-The release ships skills under `skills/` for downstream packaging. If you already have global skills installed, treat those as the primary reference and use bundled skills as the shipped fallback. Install bundled skills into `$CODEX_HOME/skills`:
-```bash
-codex-orchestrator skills install
-```
+- Current CO-local Codex CLI `0.125.0` ChatGPT-auth/appserver 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 default runtime: `appserver`
+- Unsupported combination: `executionMode=cloud` with explicit `runtimeMode=appserver`
 
-Options:
-- `--force` overwrites existing files.
-- `--only <skills>` installs only selected skills (comma-separated). Combine with `--force` to overwrite only those.
-- `--codex-home <path>` targets a different Codex home directory.
+The full version and model policy lives in [docs/guides/codex-version-policy.md](docs/guides/codex-version-policy.md).
 
-Bundled skills (may vary by release):
-- `codex-orchestrator`
-- `collab-subagents-first`
-- `chrome-devtools`
-- `delegation-usage`
-- `standalone-review`
-- `elegance-review`
-- `docs-first`
-- `collab-evals`
-- `collab-deliberation`
-- `long-poll-wait`
-- `release`
-- `agent-first-adoption-steering`
-- `delegate-early` (compatibility alias; use `delegation-usage`)
+## Quickstart
 
-## DevTools readiness
-
-Check readiness (deps + capability wiring):
 ```bash
+codex-orchestrator init codex --cwd /path/to/repo
+cd /path/to/repo
+codex-orchestrator setup --yes --repo /path/to/repo
+codex login
+codex-orchestrator flow --task <task-id>
 codex-orchestrator doctor --format json
 ```
 
-Auto-fix wiring (delegation + DevTools):
-```bash
-codex-orchestrator doctor --apply --yes
-```
+Use `codex login --device-auth` when browser login is not available.
 
-Usage snapshot (scans local `.runs/`):
-```bash
-codex-orchestrator doctor --usage
-```
-`doctor --usage` prints adoption KPIs (advanced/cloud/rlm/collab/delegation coverage), and per-run `run-summary.json` now includes a `usageKpi` section plus cloud fallback metadata when preflight downgrades to MCP.
-`doctor` also includes a codex-defaults advisory section (model/reasoning/agent baseline drift) and points to additive remediation via `codex-orchestrator codex defaults --yes`.
+## Plugin Install
 
-Issue bundle logging (downstream dogfooding / repro handoff):
-```bash
-codex-orchestrator doctor --issue-log --issue-title "Observed failure" --issue-notes "what happened"
-```
-`doctor --issue-log` appends `docs/codex-orchestrator-issues.md` (override via `--issue-log-path`) and writes a JSON bundle under `out/<resolved-task>/doctor/issue-bundles/` with doctor/cloud context (latest run context is included when available).
+The npm CLI install is the baseline. Codex plugin marketplace setup is additive for Codex releases that expose plugin flows. Current Codex CLI `0.125.0` keeps marketplace management under `codex plugin marketplace ...`:
 
-Auto-capture issue bundles when runs fail:
 ```bash
-codex-orchestrator start <pipeline> --auto-issue-log
-codex-orchestrator flow --task <task-id> --auto-issue-log
-```
-This captures both post-manifest run failures and setup failures that occur before a run manifest is created (for example strict repo-config enforcement).
+# Codex 0.121.0 accepts either command.
+codex marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
 
-Cloud preflight check (without starting a pipeline):
-```bash
-codex-orchestrator doctor --cloud-preflight
+# Codex 0.122.0+ uses the plugin command.
+codex plugin marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
 ```
 
-## Downstream usage cheatsheet (agent-first)
+For local checkout installs, pass the repository root instead of the npm install directory. For Git-backed installs, pass `owner/repo[@ref]`, an HTTPS Git URL, or an SSH Git URL. Use `codex plugin marketplace upgrade codex-orchestrator` to refresh a Git-backed marketplace checkout and `codex plugin marketplace remove codex-orchestrator` to remove the marketplace registration. Then open `/plugins` in Codex, install `Codex Orchestrator`, and restart Codex if the plugin is not picked up immediately. More local checkout, Git-backed, and rollback details are in [docs/book/setup.md](docs/book/setup.md).
 
-- Bootstrap + wire everything: `codex-orchestrator setup --yes` (non-destructive for existing skills by default; add `--refresh-skills` to overwrite)
-- Enable required MCP servers with least privilege: `codex-orchestrator mcp enable --servers delegation --yes` (plan with `--format json`; omit `--servers` only when you intentionally want all disabled servers enabled; env/secret values are redacted in displayed command lines)
-- Low-friction docs->implementation guardrails: `codex-orchestrator flow --task <task-id>`
-- Validate + measure adoption locally: `codex-orchestrator doctor --usage --format json`
-- Run docs relevance as an advisory lane (non-blocking): `codex-orchestrator start docs-relevance-advisory --task <task-id>`
-- Capture reproducible downstream failures: `codex-orchestrator doctor --issue-log --issue-title "<title>" --issue-notes "<notes>"`
-- Auto-capture failed run issue bundles: `codex-orchestrator start <pipeline> --auto-issue-log` or `codex-orchestrator flow --auto-issue-log`
-- Active PR watch-resolve-merge loop: `codex-orchestrator pr resolve-merge --pr <number> --quiet-minutes <window>` (add `--auto-merge` when approved; exits early when author action is required).
-- Passive PR monitor loop: `codex-orchestrator pr watch-merge --pr <number> --quiet-minutes <window>` (monitor-only behavior; keeps waiting unless terminal/timeout).
-- Review checkpoints (npm-only safe): `NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review --task <task-id>` for manifest-backed standalone review wrapper behavior (auto-skips repo-only diff-budget script when unavailable in downstream installs); use `codex review "<focus>"` for quick prompt-only checks; use `codex-orchestrator start implementation-gate --task <task-id> --format json` when you want a full gate run.
-- Downstream simulation before shipping wrapper/skill changes: `npm run pack:smoke` (packaged CLI in temp mock repo; validates `review` artifacts and `long-poll-wait` install path; spot-check gate). Use `npm run pack:audit` for full tarball inventory validation.
-- Delegation: `codex-orchestrator doctor --apply --yes`, then enable for a Codex run with: `codex -c 'mcp_servers.delegation.enabled=true' ...`
-- Collab (symbolic RLM subagents): `codex-orchestrator rlm --multi-agent auto "<goal>"` (legacy alias: `--collab auto`; requires Codex `features.multi_agent=true`)
-- Cloud: set `CODEX_CLOUD_ENV_ID` (and optional `CODEX_CLOUD_BRANCH`), then run: `codex-orchestrator start <pipeline> --cloud --target <stage-id>`
-- Cloud fail-fast (avoid fallback reliance): set `CODEX_ORCHESTRATOR_CLOUD_FALLBACK=deny`
-- Repo-config fail-fast (deny packaged config fallback): set `CODEX_ORCHESTRATOR_REPO_CONFIG_REQUIRED=1` or pass `--repo-config-required`
-- Cloud status retry tuning (optional): `CODEX_CLOUD_STATUS_RETRY_LIMIT`, `CODEX_CLOUD_STATUS_RETRY_BACKOFF_MS`
+## Common Commands
 
-Print DevTools MCP setup guidance:
 ```bash
-codex-orchestrator devtools setup
+codex-orchestrator flow --task <task-id>
+codex-orchestrator start diagnostics --task <task-id> --format json
+codex-orchestrator status --run <run-id> --watch --interval 10
+codex-orchestrator review
+codex-orchestrator linear issue-context --issue-id <linear-uuid>
 ```
 
-## Common commands
-
-- `codex-orchestrator start <pipeline>` — run a pipeline (add `--auto-issue-log` for automatic failure bundle capture; add `--repo-config-required` for strict repo-local config mode).
-- `codex-orchestrator flow --task <task-id>` — run `docs-review` then `implementation-gate` in sequence (supports `--auto-issue-log` and `--repo-config-required`).
-- `codex-orchestrator start docs-relevance-advisory --task <task-id>` — run non-blocking docs relevance signals (warn-mode freshness + advisory review lane).
-- `NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review --task <task-id>` — run standalone review wrapper with manifest-backed evidence (supports run-review flags/env).
-- `codex-orchestrator plan <pipeline>` — preview pipeline stages.
-- `codex-orchestrator exec <cmd>` — run a one-off command with the exec runtime.
-- `codex-orchestrator init codex` — install starter templates (`mcp-client.json`, `AGENTS.md`, downstream .codex/config.toml + .codex/agents/* role files sourced from `templates/codex/.codex/*`, `codex.orchestrator.json`) into a repo.
-- `codex-orchestrator setup --yes` — install bundled skills and configure delegation + DevTools wiring (add `--refresh-skills` to overwrite existing skills in `$CODEX_HOME/skills`).
-- `codex-orchestrator init codex --codex-cli --yes --codex-source <path>` — optionally provision a CO-managed Codex CLI binary (build-from-source default; set `CODEX_CLI_SOURCE` to avoid passing `--codex-source` every time, and `CODEX_CLI_USE_MANAGED=1` to route runs to it).
-- `codex-orchestrator init codex --codex-cli --yes --codex-download-url <url> --codex-download-sha256 <sha>` — opt-in to a prebuilt Codex CLI download.
-- `codex-orchestrator codex setup` — plan/apply a CO-managed Codex CLI install (optional managed/pinned path; use `--download-url` + `--download-sha256` for prebuilts; activate with `CODEX_CLI_USE_MANAGED=1`).
-- `codex-orchestrator codex defaults` — plan/apply additive global defaults in `~/.codex/config.toml` and `~/.codex/agents/*.toml` (`--yes` applies, `--force` allows role file overwrite).
-- `codex-orchestrator delegation setup --yes` — configure delegation MCP server wiring.
-- `codex-orchestrator mcp enable --servers <csv> --yes` — enable specific disabled MCP servers from existing Codex config entries.
-- `codex-orchestrator self-check --format json` — JSON health payload.
-- `codex-orchestrator mcp serve` — Codex MCP stdio server.
-- `npm run pack:smoke` — maintainer smoke gate for packaged downstream behavior (tarball install + review/skill checks). Core lane runs it on downstream-facing diffs; `.github/workflows/pack-smoke-backstop.yml` runs a weekly `main` backstop.
-
-## What ships in the npm release
-
-- CLI + built-in pipelines
-- Delegation MCP server (`delegate-server`)
-- Bundled skills under `skills/`
-- Schemas and templates needed by the CLI
-
-## Repository + contributor guide
+Run artifacts live under `.runs/<task-id>/` and summaries under `out/<task-id>/`.
 
-Repo internals, development workflows, and deeper architecture notes (contributor/internal) live in the GitHub repository:
-- `docs/README.md`
-- `docs/diagnostics-prompt-guide.md` (first-run diagnostics prompt + expected outputs)
-- `docs/guides/collab-vs-mcp.md` (agent-first decision guide)
-- `docs/guides/rlm-recursion-v2.md` (RLM recursion reference)
-- `docs/guides/cloud-mode-preflight.md` (cloud-mode preflight + fallback guidance)
-- `docs/guides/review-artifacts.md` (where `codex-orchestrator review` / `npm run review` write prompt/output artifacts)
-- `docs/standalone-review-guide.md` (repo-local wrapper behavior + downstream-safe review alternatives)
+## Downstream Setup
 
-## RLM benchmark graphs
+- [Book index](docs/book/README.md): setup, operations, skills, public posture, and CO-345 evidence notes
+- [Bundled skills](skills/README.md): shipped skill roster and install behavior
+- [Downstream setup](docs/public/downstream-setup.md): install, repo bootstrap, machine setup, and first run
+- [Provider onboarding](docs/public/provider-onboarding.md): Linear and provider-worker setup
+- [Docs index](docs/README.md): repo-local documentation map
 
-Seeded OOLONG accuracy curves (Wilson 95% CI, runs=5). In these runs, the baseline accuracy degrades as context length grows, while RLM stays near the ceiling across the tested lengths.
+## Contributing
 
-<table>
-  <tr>
-    <td><img src="docs/assets/oolong-baseline-seeded-wilson95-runs5.png" alt="Baseline OOLONG seeded Wilson 95% CI" width="420"></td>
-    <td><img src="docs/assets/oolong-rlm-seeded-wilson95-runs5.png" alt="RLM OOLONG seeded Wilson 95% CI" width="420"></td>
-  </tr>
-</table>
+Contributor and repo-internal guidance lives in [docs/README.md](docs/README.md).

package/bin/codex-orchestrator.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { existsSync, writeSync } from 'node:fs'
+import { join, normalize } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const FORWARDABLE_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP']
+
+function main() {
+  const packageRoot = resolvePackageRoot()
+  const sourceEntry = join(packageRoot, 'bin', 'codex-orchestrator.ts')
+  const distEntry = join(packageRoot, 'dist', 'bin', 'codex-orchestrator.js')
+  const sourceLoader = existsSync(sourceEntry) ? resolveTsNodeLoader(packageRoot) : null
+
+  let args
+  if (sourceLoader) {
+    args = ['--no-warnings', '--loader', sourceLoader, sourceEntry, ...process.argv.slice(2)]
+  } else if (existsSync(distEntry)) {
+    args = [distEntry, ...process.argv.slice(2)]
+    if (existsSync(sourceEntry)) {
+      writeWarning(
+        [
+          'Source checkout fallback: ts-node/esm is unavailable, so execution is using the built dist artifact instead of the live source entrypoint.',
+          `source=${sourceEntry}`,
+          `dist=${distEntry}`,
+          'Fresh merged TypeScript changes may remain stale until dist is rebuilt.'
+        ].join(' ')
+      )
+    }
+  } else if (existsSync(sourceEntry)) {
+    throw new Error(
+      `Unable to run ${sourceEntry} because ts-node/esm is unavailable, and fallback dist artifact ${distEntry} is missing.`
+    )
+  } else {
+    throw new Error(`Unable to locate CLI entrypoint. Expected ${distEntry}.`)
+  }
+
+  const env = {
+    ...process.env,
+    CODEX_ORCHESTRATOR_PACKAGE_ROOT: packageRoot
+  }
+  if (sourceLoader) {
+    env.TS_NODE_PROJECT = join(packageRoot, 'tsconfig.json')
+  }
+
+  const child = spawn(process.execPath, [...process.execArgv, ...args], {
+    env,
+    stdio: 'inherit'
+  })
+  let forwardedStopSignal = null
+  const disposeSignalForwarding = installSignalForwarding(child, (signal) => {
+    forwardedStopSignal ??= signal
+  })
+  child.once('error', (error) => {
+    disposeSignalForwarding()
+    writeWarning(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  })
+  child.once('close', (code, signal) => {
+    disposeSignalForwarding()
+    if (forwardedStopSignal) {
+      reemitSignal(forwardedStopSignal)
+      return
+    }
+    if (signal) {
+      reemitSignal(signal)
+      return
+    }
+    process.exitCode = typeof code === 'number' ? code : 1
+  })
+}
+
+function resolvePackageRoot() {
+  const selfPath = fileURLToPath(import.meta.url)
+  const selfRoot = normalize(join(selfPath, '..', '..'))
+  const configured = normalizeOptionalString(process.env.CODEX_ORCHESTRATOR_PACKAGE_ROOT)
+  if (configured && pathsEqual(configured, selfRoot)) {
+    return normalize(configured)
+  }
+  return selfRoot
+}
+
+function resolveTsNodeLoader(packageRoot) {
+  try {
+    return createRequire(join(packageRoot, 'package.json')).resolve('ts-node/esm')
+  } catch {
+    return null
+  }
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== 'string') {
+    return null
+  }
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+function pathsEqual(leftPath, rightPath) {
+  return normalize(leftPath) === normalize(rightPath)
+}
+
+function writeWarning(message) {
+  const line = `${message}\n`
+  const stderrFd = process.stderr.fd
+  if (typeof stderrFd === 'number') {
+    try {
+      writeSync(stderrFd, line)
+      return
+    } catch {
+      // Fall through to process.stderr when direct fd writes are unavailable.
+    }
+  }
+  process.stderr.write(line)
+}
+
+function installSignalForwarding(child, onForwardedSignal) {
+  const handlers = new Map()
+  for (const signal of FORWARDABLE_SIGNALS) {
+    const handler = () => {
+      onForwardedSignal(signal)
+      forwardSignal(child, signal)
+    }
+    process.on(signal, handler)
+    handlers.set(signal, handler)
+  }
+  return () => {
+    for (const [signal, handler] of handlers) {
+      process.off(signal, handler)
+    }
+  }
+}
+
+function forwardSignal(child, signal) {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return
+  }
+  try {
+    child.kill(signal)
+  } catch {
+    // Ignore forwarding races when the child exits between checks.
+  }
+}
+
+function reemitSignal(signal) {
+  try {
+    process.kill(process.pid, signal)
+  } catch {
+    process.exitCode = 1
+  }
+}
+
+try {
+  main()
+} catch (error) {
+  writeWarning(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+}