@pleri/olam-cli 0.1.182 → 0.1.185

package/dist/ask/knowledge-pack.generated.js

@@ -0,0 +1,1947 @@
+/**
+ * AUTO-GENERATED by scripts/gen-knowledge-pack.mjs — DO NOT EDIT BY HAND.
+ *
+ * The bundled olam knowledge pack used as the `olam ask` SDK system prompt.
+ * Regenerate with: npm run gen:knowledge-pack --workspace=@pleri/olam-cli
+ */
+/* eslint-disable */
+export const KNOWLEDGE_PACK = `# Olam knowledge pack
+
+The sections below are curated excerpts from the olam repository's own
+documentation, bundled into the CLI at build time. Treat them as the
+authoritative source for olam usage, setup, and CLI behaviour. When a section
+conflicts with your prior knowledge, the section wins.
+
+---
+
+## Olam — README (overview, substrates, scope)
+
+Source: \`README.md\`
+
+# Olam
+
+**The thought is the artifact. Code is a side effect.**
+
+Olam provisions disposable development worlds from a single "seed of
+thought" and drives them toward a reviewed pull request. Every world
+is isolated, vault-authenticated, and auditable end-to-end — from the
+initial prompt to the PR's opened URL.
+
+The name comes from the Hebrew word for "world."
+
+## Two substrates, one paradigm
+
+Olam runs on either of two substrates — each optimized for a different
+operator role. Same dashboard SPA and CLI; the API surface overlaps on
+the core world-lifecycle paths but diverges significantly on operator tooling.
+
+| | **Cloudflare** (\`packages/cloudflare-worker/\`) | **Local docker** (\`packages/host-cp/\`) |
+|---|---|---|
+| Worlds | CF Sandbox (per-world Durable Object + Container) | Docker container on the host |
+| Auth | Worker OAuth token exchange, tokens in KV \`OLAM_CREDS\` | Long-lived local auth container at \`:9999\`, tokens in a docker volume |
+| Storage | KV + R2 | Host filesystem under \`~/.olam/\` |
+| Optimized for | **Published-ship**: worlds run autonomously; zero-install contributors; shared team deployments | **Operator-facing**: tight iteration, dogfood, credential vault management, Docker-level introspection |
+| Operator tooling | World lifecycle + OAuth only | Full surface: process inspection, port bridging, tunnel management, planner, credential CRUD, \`gh\`-backed PR listing |
+
+**CF is the published-ship substrate.** Once a Worker is deployed, worlds
+run autonomously inside CF Containers. The operator's interactive workflow
+stays on host-cp; CF does not expose host-level APIs (Docker socket, local
+filesystem, \`gh\` CLI) because it has none.
+
+**host-cp is the operator-facing substrate.** It exposes the full feature
+surface including Docker orchestration, per-world process inspection, port
+bridging, tunnel management, planning subsystem, and credential vault CRUD.
+Parity with CF is a per-feature design decision, not a contract obligation
+(see [ADR-011](docs/decisions/011-two-substrate-parity.md)).
+
+Tokens, workspace configs, and skill bundles live **outside any world**
+on both substrates. Destroying a world never destroys any of them.
+
+## Three world-runner tiers
+
+Orthogonal to the deploy substrate above, Olam ships three world-runner
+tiers — each tuned for a different runtime-cost shape. Pick by
+cold-start tolerance and task shape:
+
+| Tier | Cold start | Use for |
+|---|---|---|
+| \`docker\` | 5–15 s | Heavyweight Claude Agent SDK loops, multi-step coding tasks, anything that needs a full devbox. **Default for \`/goal\`-style world work.** |
+| \`cloudflare-sandbox\` | 2–4 s | Per-task containerised isolation on Cloudflare's edge — same agent capabilities as docker without a host Docker daemon. Use when host Docker is unavailable or for multi-op fan-out. |
+| \`cloudflare-isolate\` | single-digit ms | One-shot RPC tasks: doc lookups, deterministic transforms, keystroke-scale work that doesn't deserve the boot tax. No agent loop, no persistent state, no container. v1 implements \`lookup\` only ([ADR 022](docs/decisions/022-v8-isolate-runtime-tier.md)). |
+
+Rule of thumb: if the task is "receive input → call one API or run one
+function → return result" and finishes in <1 s of real work, it belongs
+on the isolate tier. If it needs an agent loop, tool use, or persistent
+file state, it belongs on \`docker\` or \`cloudflare-sandbox\`. The
+per-workspace default is \`compute.default\` in \`.olam/config.yaml\`.
+
+## Scope
+
+Olam is one monorepo, six surfaces:
+
+| Surface | Role |
+|---------|------|
+| **CF Worker** (\`packages/cloudflare-worker/\`) | Edge router, OAuth token exchange, per-world Durable Object, vault (KV + R2), completion-event sink |
+| **Local auth service** (\`packages/auth-service/\`) | Long-lived Linux container running the same OAuth PKCE dance as the Worker; serves tokens to every local world over a shared-secret-authenticated API |
+| **Docker provider** (\`packages/adapters/src/docker/\` + \`packages/control-plane/standalone/\`) | Local runtime: per-world devbox container, in-container control plane on \`:8080\`, credential refresh daemon, PR-gate hook, volume-mounted workspaces |
+| **Sandbox container** (\`packages/cloudflare-worker/container_src/\`) | CF per-world Node 20 + zsh runtime; control plane on \`:8080\`; pre-baked Claude Code, Codex, \`gh\`, Linear/Slack MCPs, tmux, ttyd |
+| **Operator SPA** (\`packages/plan-chat-spa/\`) | React 19 + Vite; the canonical operator SPA, served by **host-cp** locally and on GKE (Phase E5 atomic serving cutover, 2026-05). Reads authoritative state via \`/api/*\` + Electric chunk shapes; planning + non-planning surfaces (workspaces/repos/runbooks/inbox/world editor+events). The legacy \`packages/control-plane/app\` dashboard SPA is retired as host-cp's served bundle (still bundled by the CF Worker pending its own migration) |
+| **MCP + plugin** (\`packages/mcp-server/\`, \`plugin/\`) | Claude Code plugin exposing \`olam_create\`, \`olam_dispatch\`, \`olam_auth_*\`, \`olam_pr_*\`, and friends so the agent can manage worlds without a separate CLI |
+
+**What lives inside a world:** a git checkout of one or more repos, a
+running Claude Code tmux session, scoped credentials injected from the
+vault, and whatever artifacts / diffs the agent produces.
+
+**What lives outside a world:** the user's identity + credentials
+(KV), the workspace config (KV), the user's skill bundle (R2), and the
+completion ladder's state record (DO). Destroying a world never
+destroys any of these.
+
+See [\`docs/architecture/\`](./docs/architecture/README.md) for the
+full nine-part walkthrough.
+
+**Operator-facing guide** to the fat-box runtime that ships warm-create:
+[\`docs/guides/fatbox-runtime/\`](./docs/guides/fatbox-runtime/README.md)
+— plain-English walkthrough with mermaid diagrams covering what
+changed across PRs #394 / #398 / #402 / #404, getting started, and
+troubleshooting. **Start here if you've never used \`olam create\`
+before, or if your warm-create is taking the cold path and you don't
+know why.**
+
+**For new orgs onboarding to olam**, the **3-contract pattern** is the
+authoring surface. Read these in order before publishing your first
+devbox image:
+
+1. [\`devbox-contract.md\`](./docs/architecture/devbox-contract.md) — what
+   the devbox image must provide so olam + host-cp can drive it.
+2. [\`manifest-spec.md\`](./docs/architecture/manifest-spec.md) — per-repo
+   \`.adb.yaml\` / \`.olam.yaml\` schema, including the
+   \`bootstrap[].produces\` annotation that drives Phase 1 warm-create
+   sentinel-handoff.
+3. [\`config-spec.md\`](./docs/architecture/config-spec.md) — workspace-
+   level \`.olam/config.yaml\` schema, including the
+   \`devbox.registry\` provider/prefix block (ghcr / gar / dockerhub)
+   and \`image_selectors\` first-match-wins rules.
+
+Adjacent runtime doc:
+[\`snapshot-restore.md\`](./docs/architecture/snapshot-restore.md) —
+the warm-create snapshot cache flow, fingerprint design, 5 UX strings,
+and operator FAQ. Read this when you need to understand why
+\`olam create\` sometimes runs the cold path despite a previous
+warm-create on the same workspace.
+
+Atlas-shape reference templates: [\`docs/templates/\`](./docs/templates/)
+(\`devbox.atlas.Dockerfile\`, \`manifest.atlas.adb.yaml\`,
+\`config.atlas.olam.yaml\`).
+
+---
+
+## How it works
+
+\`\`\`mermaid
+flowchart LR
+  User[User machine]
+  User --> Bootstrap["olam bootstrap"]
+  Bootstrap --> Smoke[docker info smoke]
+  Smoke --> Pulls[("Parallel pull by digest<br/>retry · throttle · coalesce")]
+  Pulls --> HostCp["ghcr.io/pleri/olam-host-cp"]
+  Pulls --> Auth["ghcr.io/pleri/olam-auth"]
+  Pulls --> Devbox["ghcr.io/pleri/olam-devbox"]
+  HostCp --> Handshake["protocol-version handshake<br/>(refuse on no-overlap)"]
+  Auth --> Handshake
+  Devbox --> Handshake
+  Handshake --> HostCpStart[olam host-cp start]
+  HostCpStart --> AuthUp[olam auth up]
+  AuthUp --> AuthLogin["olam auth login<br/>(PKCE; --skip-auth-login to bypass)"]
+  AuthLogin --> Create["olam create --task ..."]
+  Create --> World[("Devbox world<br/>+ in-world claude-main")]
+  World --> Ladder["Completion ladder<br/>draft → recommendations →<br/>adversarial_review → audit_passed →<br/>pr_eligible → pr_opened"]
+\`\`\`
+
+\`olam setup\` is the canonical fresh-host wizard (default substrate:
+kubernetes/k3d; see [Quick start](#quick-start)). The diagram above
+shows \`olam bootstrap\` — the **docker-compose** on-ramp it delegates to
+on the docker path (and the direct entry point for CI / scripted
+contexts). \`bootstrap\` fans out three GHCR pulls in parallel
+(digest-pinned, single in-flight per ref, single bounded retry on
+transient failure), verifies every pulled image's
+\`olam.protocol.versions\` label overlaps the CLI's, then drives
+\`host-cp start\` + \`auth up\` + \`auth login\` to a working stack. Exit
+codes are explicit: \`3\` = pull failed, \`4\` = protocol mismatch.
+
+---
+
+## Quick start
+
+\`\`\`bash
+curl -fsSL https://olam.bar.dev/install | sh
+olam setup
+\`\`\`
+
+That's it. The installer puts \`@pleri/olam-cli\` on your PATH (requires Node.js ≥ 20 and npm). \`olam setup\` installs k3d (if absent), creates a local Kubernetes cluster named \`olam-dev\`, and brings up the full peripheral stack (host-cp, auth-service, mcp-auth-service, kg-service, memory-service). Works on macOS and Linux. No source checkout required.
+
+The setup wizard is **idempotent** — re-running skips steps that are already complete.
+
+After setup, every world is one call:
+
+\`\`\`bash
+olam create --name my-world --task "audit the auth module for SSRF"
+\`\`\`
+
+Full setup guide (prereqs, observability, troubleshooting):
+[\`docs/onboarding/k3s-mode-setup.md\`](./docs/onboarding/k3s-mode-setup.md).
+
+### Docker Compose (lighter alternative)
+
+For hosts that can't run a Kubernetes cluster locally, or for CI:
+
+\`\`\`bash
+curl -fsSL https://olam.bar.dev/install | sh
+olam setup --substrate=docker
+\`\`\`
+
+This runs three host containers (auth, mcp-auth, kg-service) via docker compose instead of a full cluster. Existing docker-compose installs are protected: \`~/.olam/config.json\` with \`host.substrate: 'compose'\` continues on docker with a migration hint.
+
+Full setup guide for compose mode: [\`docs/onboarding/fresh-machine-setup.md\`](./docs/onboarding/fresh-machine-setup.md).
+
+---
+
+## Setup
+
+### Install the CLI
+
+\`\`\`sh
+curl -fsSL https://olam.bar.dev/install | sh
+\`\`\`
+
+The installer is POSIX-clean (works under \`dash\`, \`sh\`, or \`bash\`) and
+publishes from npmjs.org. It checks for **Node.js ≥ 20** (hard
+requirement) and \`npm\`, then runs \`npm install -g @pleri/olam-cli\`.
+Use \`OLAM_CHANNEL=canary\` to track the prerelease tag.
+
+### Bring up the stack
+
+\`\`\`bash
+olam setup                      # k3d cluster + full peripheral stack (default)
+olam setup -y                   # non-interactive: auto-affirm every prompt
+olam setup --substrate=docker   # docker compose mode (3 containers, no cluster)
+olam setup --cluster-name foo   # use a different k3d cluster name (default: olam-dev)
+\`\`\`
+
+\`olam setup\` is the canonical fresh-host wizard. It's substrate-aware: the default is **kubernetes** (k3d), which installs k3d (via brew on macOS, else the upstream install script), creates the \`olam-dev\` cluster, applies all manifests, and verifies every deployment is \`1/1 Running\`. Pass \`-y\` to skip all prompts, or \`--substrate=docker\` to run the lighter compose path instead.
+
+Artifacts land under \`~/.olam/\` on the host:
+
+- \`~/.olam/auth-secret\` — shared secret (\`0600\`) generated on first
+  \`auth up\`; authenticates every world's requests to the auth-service.
+- \`~/.olam/worlds/<world-id>/\` — per-world worktree + thought DB.
+- \`~/.olam/worlds.db\` — world registry.
+- \`~/.olam/upgrade.log\` — JSONL audit log of every \`olam upgrade\` invocation.
+
+### Legacy: \`olam bootstrap\`
+
+\`olam bootstrap\` targets the **docker compose** substrate directly (it pulls three
+digest-pinned GHCR images and starts them via compose). It remains the on-ramp for
+the docker path in CI and scripted contexts:
+
+\`\`\`bash
+olam bootstrap                  # pull host-cp + auth + devbox by digest, start services, run auth login
+olam bootstrap --with-smoke     # also create a smoke-test world to verify end-to-end
+olam bootstrap --skip-auth-login   # CI / scripted use; equivalent to OLAM_BOOTSTRAP_SKIP_AUTH_LOGIN=1
+olam bootstrap --registry ghcr.io/pleri   # override the registry prefix
+\`\`\`
+
+After bootstrap completes, every subsequent world is one call:
+
+\`\`\`bash
+olam create --name my-world --task "audit the auth module for SSRF"
+\`\`\`
+
+### Cloudflare deploy
+
+Required for a shared team deployment. Needs a Cloudflare Workers Paid
+plan (DO + Containers), \`wrangler\`, and a CF Access application gating
+your Worker URL.
+
+\`\`\`bash
+cp .env.example .env.local
+# Edit .env.local
+\`\`\`
+
+The canonical keys (see [\`docs/CF_WORLDS_SPEC.md\`](./docs/CF_WORLDS_SPEC.md) §3):
+
+\`\`\`sh
+# Deploy plane
+CLOUDFLARE_API_TOKEN=<wrangler OAuth or API token with workers:write>
+
+# CF Access admin (only needed when running scripts/setup-access.mjs)
+CF_API_TOKEN=<token with Access: Apps and Policies:Edit + Service Tokens:Edit>
+
+# MCP / CLI machine auth (CF Access service token + Pylon outbound auth).
+# Worker auth migrated to Pylon scoped tokens in PR #31; see
+# docs/migrations/mcp-pylon.md for the operator setup.
+OLAM_WORKER_URL=https://<your-worker>.workers.dev
+OLAM_CF_ACCESS_CLIENT_ID=<uuid>.access
+OLAM_CF_ACCESS_CLIENT_SECRET=<long secret>
+OLAM_PYLON_ORG_URL=https://pylon.<your-org>.dev
+OLAM_PYLON_ORG_ID=<your-org-slug>
+# PYLON_SESSION_TOKEN auto-resolved from macOS Keychain / Linux Secret
+# Service after \`pylon login\`; only needed in CI / headless contexts.
+
+# Container runtime policy (optional; default=bypass)
+OLAM_CLAUDE_PERMISSION_MODE=bypass   # or "accept-edits" / "strict"
+\`\`\`
+
+\`\`\`bash
+cd packages/cloudflare-worker
+pnpm wrangler deploy
+\`\`\`
+
+Wrangler builds the container image, pushes to CF's registry, and
+binds the \`Sandbox\` Durable Object + \`OLAM_CREDS\` / \`OLAM_WORKSPACES\`
+KV + \`OLAM_USER_PROFILES\` R2. Authenticate once with
+\`cloudflared access login https://<your-worker>.workers.dev\` — every
+subsequent world auto-injects from the vault.
+
+---
+
+### Claude Code plugin (both paths)
+
+\`\`\`bash
+claude plugin install ./plugin
+\`\`\`
+
+You now have \`/olam:create\`, \`/olam:dispatch\`, \`/olam:destroy\`,
+\`/olam:list\`, \`/olam:enter\`, \`/olam:status\`, \`/olam:auth_*\`, and
+\`/olam:pr_*\` available in Claude Code.
+
+---
+
+### MCP server (Claude Code integration)
+
+The CLI bundles an MCP server that exposes \`olam_create\`,
+\`olam_dispatch\`, \`olam_destroy\`, \`olam_list\`, \`olam_status\`,
+\`olam_enter\`, \`olam_pr\`, \`olam_observe\`, \`olam_lane_*\`, and
+\`olam_capture_view\` as direct tool calls for any MCP-aware agent
+runtime. Three ways to wire it in:
+
+**One command (recommended):**
+
+\`\`\`bash
+olam mcp install                  # default --scope=user
+olam mcp install --scope=project  # writes to project .mcp.json
+olam mcp uninstall                # idempotent; symmetric
+\`\`\`
+
+Auto-detects whether \`olam\` is on PATH. If so, writes
+\`command: "olam"\` (no \`npx\` cold-start). Otherwise falls back to
+\`command: "npx", args: ["-y", "@pleri/olam-cli", "mcp", "serve"]\`.
+
+**Paste the JSON snippet** into \`~/.claude.json\` (user scope) or a
+project's \`.mcp.json\`:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "olam": {
+      "command": "npx",
+      "args": ["-y", "@pleri/olam-cli", "mcp", "serve"]
+    }
+  }
+}
+\`\`\`
+
+**Marketplace alias** — \`olam --mcp\` is a thin alias for
+\`olam mcp serve\`. Use when an MCP-marketplace snippet expects the
+bare-flag convention (\`npx -y <pkg> --mcp\`).
+
+Restart Claude Code; verify with \`claude mcp list\` (look for \`olam\`).
+Full details + version-skew + cold-start trade-offs:
+[\`docs/architecture/mcp-as-npx-served.md\`](docs/architecture/mcp-as-npx-served.md).
+
+---
+
+## Usage
+
+### Autonomous Build: seed → world → PR gate
+
+In Claude Code:
+
+\`\`\`
+/olam:create "audit the auth module for SSRF vulnerabilities"
+\`\`\`
+
+That's it. The plugin calls the Worker, the Worker provisions a
+sandbox, creds flow in from the vault, claude-main boots and
+auto-dispatches the task. The dashboard URL prints in the tool output
+(\`https://<your-worker>.workers.dev/sandbox/<uuid>/\`).
+
+Open that URL and you'll see:
+
+- The **seed of thought** pinned at the top (immutable subject).
+- A **phase progress strip** — \`created → syncing → cloning →
+  configuring → warming → ready → task_running\`. Warming renders a
+  narration of the probe: *tmux session starting → claude is booting
+  · waiting for prompt → shell spawn check → ready*.
+- The **completion ladder** — 6 steps from \`draft\` to \`pr_opened\`,
+  each lit when its named actor files the event (Claude Stop hook,
+  Codex reviewer, audit session, gh PR-open).
+- A **terminal button** (top-right) that opens a full-screen ttyd
+  attached to \`claude-main\`.
+- A **session-health bar** that shows a red banner with the warmup
+  trace if anything breaks during spawn.
+
+Everything is a projection of the authoritative state on the DO. If
+the container gets evicted mid-run, the dashboard's auto-resume hook
+silently re-injects creds and re-spawns claude — no Auth modal, no
+lost context.
+
+### Lifecycle commands
+
+| Command | Effect |
+|---------|--------|
+| \`/olam:create <task>\` | Provision a world, dispatch the task, return dashboard URL |
+| \`/olam:list\` | Recent worlds + phases |
+| \`/olam:enter <world>\` | Pop the dashboard URL for an existing world |
+| \`/olam:status <world>\` | Phase + completion state + session health |
+| \`/olam:dispatch <world> <task>\` | Send another prompt into the existing tmux session |
+| \`/olam:destroy <world>\` | Hard destroy (DO evict + container down) |
+
+### Self-upgrade — pull-by-digest from GHCR
+
+\`olam upgrade\` defaults to **pull-by-digest from GHCR**. The CLI's
+pinned image-digest set is round-tripped through \`/api/version/status\`
+so success means "host-cp reports the new SHA". The legacy
+build-from-source path lives behind \`--from-source\` and only works in
+a monorepo checkout with \`OLAM_DEV=1\`.
+
+\`\`\`bash
+olam upgrade -y                       # default: pull pinned digests, retag, recreate host-cp + auth + devbox
+olam upgrade --rollback               # restore the prior canonical tag set from :olam-rollback
+olam upgrade --force                  # allow swap even if HEAD has drifted from captured-at-pull SHA
+olam upgrade --no-cache               # DOCKER_BUILD_NO_CACHE=1 across all three builds (--from-source path)
+olam upgrade --history -n 5           # print the last 5 rows of ~/.olam/upgrade.log
+olam upgrade --history -n 20 --json   # same, JSONL — pipeable to jq
+olam upgrade --branch main -y         # switch branches first (refuses on dirty tree)
+olam upgrade --from-source -y         # legacy: rebuild all three images from monorepo source (needs OLAM_DEV=1)
+\`\`\`
+
+The success criterion is an **atomic 6-tag swap**: the prior canonical
+tags (\`olam-host-cp:latest\`, \`olam-auth:latest\`, \`olam-devbox:latest\`)
+are preserved as \`:olam-rollback\`, then the new pulled images become
+canonical. \`auth upgrade\` follows the same pattern. Every invocation
+appends a JSONL row to \`~/.olam/upgrade.log\` (verdict, captured SHA,
+elapsed, exit code) so a post-mortem is always one \`--history --json\`
+away.
+
+\`olam auth upgrade\` mirrors the same default: pull-by-digest unless
+\`--from-source\` is specified.
+
+**Release cadence (post \`actions-cost-reduce\` Phase A, 2026-05-13):**
+Releases are now hand-cranked. Merges to \`main\` no longer auto-publish
+new images. To ship a release:
+
+\`\`\`bash
+gh release create v0.1.NNN --target main --generate-notes --title "v0.1.NNN"
+\`\`\`
+
+See [\`docs/architecture/release-flow.md\`](./docs/architecture/release-flow.md)
+for the full flow — what fires under the hood, the \`[skip ci]\` semantics,
+the manual \`workflow_dispatch\` escape hatch, and how to revert.
+
+See
+[\`packages/cli/skills/olam-upgrade/SKILL.md\`](packages/cli/skills/olam-upgrade/SKILL.md)
+for the full flag matrix, swap-boundary semantics, and recovery
+playbook.
+
+### Programmatic \`/session/start\`
+
+For callers that aren't Claude Code (CI, audits, scripted batches):
+
+\`\`\`bash
+curl -X POST "$OLAM_WORKER_URL/session/start" \\
+  -H "Content-Type: application/json" \\
+  -H "CF-Access-Client-Id: $OLAM_CF_ACCESS_CLIENT_ID" \\
+  -H "CF-Access-Client-Secret: $OLAM_CF_ACCESS_CLIENT_SECRET" \\
+  -d '{
+    "workspace": "ein-sof",
+    "task": "audit the auth module for SSRF vulnerabilities",
+    "engineerHash": "anonymous",
+    "repoUrl": "workspace://ein-sof",
+    "branch": "main",
+    "userEmail": "you@example.com"
+  }'
+\`\`\`
+
+The \`userEmail\` override keys the vault lookup when you're calling on
+behalf of a known user via a service token.
+
+### Dashboard SPA dev run
+
+The canonical SPA is \`@olam/plan-chat-spa\` — host-cp's sole served
+bundle (the legacy \`packages/control-plane/app/\` is sunset). Run it
+locally with Vite:
+
+\`\`\`bash
+npm run dev --workspace=@olam/plan-chat-spa     # Vite dev server
+npm run build --workspace=@olam/plan-chat-spa   # tsc -b + vite build
+\`\`\`
+
+For the CF-edge dev loop (SPA assets bundled into the Worker via
+\`wrangler.jsonc\`'s \`assets\` field; served directly through CF Access
+SSO), run the worker:
+
+\`\`\`bash
+npm run dev --workspace=@olam/cloudflare-worker  # wrangler dev
+\`\`\`
+
+### PLERI is optional
+
+\`PLERI_BASE_URL\` (and the corresponding \`pleri:\` block in
+\`.olam/config.yaml\`) is an **optional team-intelligence integration**;
+required only for \`olam crystallize\` and team-mode features that share
+thought graphs to a Pleri Plane. Fresh installs without PLERI work end
+to end — \`olam create\`, \`olam dispatch\`, \`olam list\`, \`olam destroy\`
+all behave normally. \`olam crystallize\` on a non-PLERI machine emits a
+one-line stderr warn and exits with named code 2 (distinguishable from
+exit-0 success and exit-1 errors for piped scripts), and is hidden
+from \`olam --help\` until PLERI is configured. See
+[\`packages/cli/src/exit-codes.ts\`](packages/cli/src/exit-codes.ts) for
+the full exit-code registry.
+
+### Tests
+
+This repo uses **npm workspaces** (\`npm run <script> --workspace=<pkg>\`):
+
+\`\`\`bash
+# Container + intelligence pipeline
+npm run test --workspace=@olam/cloudflare-worker
+npm run test --workspace=@olam/intelligence
+
+# Core + adapters
+npm run test --workspace=@olam/core
+
+# CLI (default sweep excludes the docker-integration suite — see CLAUDE.md)
+npm test --workspace=@pleri/olam-cli
+npm run test:cli:integration            # the excluded docker-integration suite
+\`\`\`
+
+---
+
+## Paradigms
+
+Three ideas do most of the work. Every other design choice is
+downstream of these.
+
+### Auth container
+
+An Olam world should boot **already authenticated to Claude**, with no
+browser popup, no keychain prompt, no \`docker cp\` race. The CF path
+solves this with the Worker doing OAuth at the edge and KV storing
+refresh tokens. The local path mirrors that shape: a long-lived Linux
+**auth container** at \`:9999\` runs the same OAuth PKCE dance, stores
+tokens in a named docker volume, and serves fresh access tokens over
+an HTTP API secured by a host-generated shared secret (\`~/.olam/auth-secret\`,
+\`0600\`).
+
+Lifecycle:
+
+\`\`\`
+olam auth up       # start the container (idempotent)
+olam auth login    # one-time PKCE; opens browser, paste code back
+olam auth status   # show container state + valid accounts
+\`\`\`
+
+When a world is created, the docker provider injects the shared secret
+as \`OLAM_AUTH_SECRET\` into the devbox container. On boot, the in-world
+\`entrypoint.sh\` runs \`fetch-creds.mjs\` which fetches a fresh access
+token from \`http://host.docker.internal:9999/credentials\` and writes
+\`~/.claude/.credentials.json\` atomically. A background loop refreshes
+every six hours. The refresh token never leaves the auth container.
+
+**Provenance, not ambient.** The token a world uses is provably the
+token the auth container issued — same first-14 bytes, same
+\`expiresAt\`, written after \`fetch-creds\` runs. \`gh\` tokens are a
+separate concern (baked into the devbox image).
+
+Full CF ↔ local parity lives in
+[\`docs/architecture/\`](./docs/architecture/README.md) and
+[\`packages/auth-service/\`](./packages/auth-service/).
+
+### KG-service container
+
+For symbol-shaped queries ("who calls \`Cart#submit\`?", "where is
+\`hydrateOrder\` defined?") agents should reach for a knowledge graph,
+not \`grep\`. Olam ships a long-running **\`olam-kg-service\` container**
+at \`127.0.0.1:9997\` that holds a Python HTTP server with bge-small
+embeddings + a 4-layer classifier in memory. Operators install
+nothing beyond Docker.
+
+\`\`\`
+olam services up                      # starts kg-service alongside auth + mcp-auth
+olam kg classify "trace cart to order"
+olam kg install-hook                  # writes a PreToolUse Bash hook into .claude/settings.json
+olam kg doctor                        # 4-probe health check
+\`\`\`
+
+The hook fires on grep/find-shape Bash commands and emits
+\`additionalContext\` when the classifier suggests the KG is a better
+route than grep. It's fail-open: \`curl --max-time 1\` means a slow or
+unreachable kg-service never blocks the agent.
+
+**World parity.** Every world's \`entrypoint.sh\` installs the same hook
+pointing at \`host.docker.internal:9997\` so devbox containers reach the
+host's kg-service through Docker's host-gateway mapping. Single model
+copy serves host + every world.
+
+**Why a container, not a host CLI?** Latency. Measured options:
+\`docker run --rm\` per call ≈ 43 s (dead), \`docker exec\` fresh Python
+≈ 970 ms (too slow), persistent Python HTTP server in container ≈
+37 ms p50 (viable). The full reasoning is in
+[ADR 017](./docs/decisions/017-kg-service-container.md).
+
+Architecture: [\`docs/architecture/kg-service.md\`](./docs/architecture/kg-service.md)
+(operator guide, HTTP contract, troubleshooting) +
+[\`docs/architecture/kg-classifier.md\`](./docs/architecture/kg-classifier.md)
+(4-layer internals + accuracy bench).
+
+### Autonomous Build
+
+\`\`\`
+olam create --name my-world --task "describe the work"
+\`\`\`
+
+That's the whole user-facing contract. The system builds autonomously
+from the seed to the PR-gate checkpoint — past that point the
+[PR gate](#pr-gate) holds for human or Codex approval before anything
+lands on GitHub. "Autonomous" describes the control boundary honestly:
+independent from seed through branch-push, gated at PR creation.
+
+Everything between the single command and the gate is handled
+internally:
+
+1. **Preflight** — verifies the auth container is up and has ≥1 valid
+   account; fails fast with a one-line remedy if not.
+2. **World provisioning** — worktree, env, service containers, devbox.
+3. **Credential injection** — via \`fetch-creds.mjs\` on container boot
+   (not host-side \`docker cp\`, which raced Claude's first read).
+4. **Auto-dispatch** — task lands in the in-world Claude session.
+5. **Background refresh** — token rotates every 6 h for the life of
+   the world.
+
+One call from the user. Preflight + retries + refresh + atomic writes
+live inside — per Codex's adversarial note, the client intent is
+singular; the orchestration stays.
+
+### PR gate
+
+"Autonomous" only holds up to the gate. Every Claude-driven
+\`gh pr create\` inside a world is intercepted:
+
+\`\`\`
+olam pr list                           # every pending gate across every world
+olam pr show <id>                      # full diff + commit log + command
+olam pr approve <id> --reason "lgtm"   # let gh pr create proceed
+olam pr reject  <id> --reason "leaks"  # hook exits 2, Claude sees a tool error
+\`\`\`
+
+Under the hood: a PreToolUse hook (\`/opt/olam/scripts/pr-gate-hook.mjs\`)
+installed via project-level \`.claude/settings.json\` intercepts
+\`gh pr create\` calls, POSTs to \`http://127.0.0.1:8080/api/pr-gate\` in
+the world, and polls \`/verdict\` until a decision lands. The control
+plane persists each gate to \`/workspace/.olam/pr-gates/{id}.json\`.
+Codex adversarial review is the planned second decision source — when
+it agrees, the gate auto-approves; when it pushes back, a human
+deconflicts via \`olam pr approve/reject\` or the dashboard.
+
+MCP parity (\`olam_pr_{list,show,approve,reject}\`) means the same
+decisions can come from an agent instead of a human.
+
+---
+
+## Philosophy
+
+1. **The thought is the artifact.** Code is a side effect. If you can
+   see the reasoning — every tool call, every review verdict, every
+   audit result — you can debug decisions, not just bugs.
+
+2. **Worlds are disposable.** Create them freely. Destroy them without
+   remorse. The vault survives. The completion ladder's evidence
+   survives. Ephemeral container state does not.
+
+3. **Isolation is the default.** One sandbox per world. No shared
+   filesystem, no shared tmux, no shared port. Parallel agents work
+   without stepping on each other. Blast radius is always one world.
+
+4. **The agent manages infrastructure.** You don't learn Worker
+   routes, DO names, or tmux send-keys. You say "create a world for
+   X"; Claude does the rest.
+
+5. **"Done" is an explicit ladder, not an inference.** Olam encodes
+   completion as a monotone state machine: \`draft → recommendations →
+   adversarial_review → audit_passed → pr_eligible → pr_opened\`. Each
+   gate has a named author and captured evidence. The dashboard reads
+   state — it never guesses. A PR opens only when every prior gate
+   has filed its event.
+
+6. **Policy is deploy-owned, not code-baked.** \`OLAM_CLAUDE_PERMISSION_MODE\`
+   decides bypass vs accept-edits vs strict at the environment level;
+   isolation reduces blast radius but doesn't justify a hard-coded
+   default. Auditable, toggleable, rotatable — all without a code
+   change.
+
+7. **Everything composes.** Olam is a Claude Code plugin + a CF
+   Worker, not a standalone product. It augments your existing
+   workflow rather than replacing it.
+
+---
+
+## Status
+
+- **\`olam setup\` is the canonical on-ramp.** Substrate-aware wizard;
+  default kubernetes/k3d, \`--substrate=docker\` for the lighter compose
+  path. It delegates to \`olam bootstrap\` on the docker path, which
+  pulls all three GHCR images by digest in parallel, verifies
+  protocol-version overlap, and drives services + auth-login to a
+  working stack. Exit codes \`3\` (pull failed) and \`4\` (protocol
+  mismatch) are explicit.
+- **Self-upgrade pipeline**: pull-by-digest is the default;
+  \`--from-source\` is gated behind \`OLAM_DEV=1\` + monorepo. Atomic
+  6-tag swap with \`--rollback\`, \`--force\`, \`--no-cache\`, and
+  \`--history [-n N] [--json]\` flags. JSONL audit at
+  \`~/.olam/upgrade.log\`.
+- **GHCR release pipeline**: \`release.yml\` publishes via native
+  arm64 + amd64 matrix runners using \`build-push-action@v6\` and
+  per-arch registry cache (\`<image>-cache:{amd64,arm64}\`). Wall-clock
+  collapsed from 8–12 m to 3–5 m.
+- **CI watchdog (Phase C)**: wake-and-dispatch with PR-identity
+  validation, retry budget gated on real dispatches (\`wakes\`), and
+  API-side log-tail fetch from
+  \`api.github.com/.../actions/runs/{run_id}/logs\`. Six audit findings
+  closed in PR #292. Canonical sequence diagram lives in
+  [\`docs/design/ci-watchdog.md\`](./docs/design/ci-watchdog.md).
+- **CF platform**: Sandbox + DO-owned state + completion ladder
+  shipped. Auto-resume covers container evictions.
+- **Local auth-service parity**: shipped. Same OAuth flow as CF,
+  tokens in docker volume, shared-secret-gated, atomic in-world
+  writes, 6 h refresh.
+- **PR gate**: in-world hook + control-plane endpoints + \`olam pr\`
+  CLI + MCP tools all live; Codex verdict as a parallel decision
+  source is the next follow-up.
+- **ReUI design system**: ReUI is the canonical primitive source
+  (ADR-013). The active SPA \`packages/plan-chat-spa/\` registers the
+  \`@reui\` registry in its \`components.json\` and wraps primitives via
+  thin shims in \`src/components/ui/\`. Token/design-system drift is
+  guarded at the repo root by \`npm run audit:tokens\`. (The earlier
+  Phase-0b-i ReUI seeding in \`packages/control-plane/app/\` is sunset
+  along with that package.)
+
+---
+
+## Read more
+
+- [\`docs/architecture/\`](./docs/architecture/README.md) — the 9-part
+  deep dive on substrates, world lifecycle, vault, completion ladder,
+  PR gate, and parity invariants.
+- [\`docs/design/ci-watchdog.md\`](./docs/design/ci-watchdog.md) — the
+  canonical CI watchdog design with locked invariants, threat model,
+  and the wake-and-dispatch sequence diagram.
+- [\`assets/landing-page/wiki/\`](./assets/landing-page/wiki/) —
+  public-facing usage docs (\`index.md\`, \`setup.md\`, \`usage.md\`)
+  rendered client-side by \`wiki.html\`. The README defers detailed
+  setup walkthroughs there.
+- [\`docs/CF_WORLDS_SPEC.md\`](./docs/CF_WORLDS_SPEC.md) — canonical
+  contract between CF Worker and local docker substrates.
+- [\`CLAUDE.md\`](./CLAUDE.md) — engineering rules in force across the
+  repo: outbound Anthropic calls via \`withCredential\`, credential
+  vault smoke gate, and the PR-description bar (Mermaid eval block +
+  \`validate-pr-body.mjs\` CI check).
+
+---
+
+## License
+
+[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) — free
+to use and adapt, not for commercial use. Commercial licenses
+available — contact ernest.codes@gmail.com. Or, if you want to use it
+commercially, just get Claude to understand the philosophies and
+recreate the project from scratch.
+
+---
+
+## Onboarding (first-run, install, getting started)
+
+Source: \`docs/ONBOARDING.md\`
+
+# Olam Onboarding Guide
+
+**Goal:** Go from zero to "I can see the team's worlds" in under 15 minutes.
+
+---
+
+## Prerequisites
+
+- **Docker daemon** running (Docker Desktop, or colima on macOS)
+- **Node.js ≥ 20** (\`node --version\`)
+- **Claude Code** (\`claude --version\`) — authenticated via \`claude auth login\`
+- **Git** with SSH key configured for your repos
+
+---
+
+## 1. Install the CLI and bring up the stack (3 minutes)
+
+No source checkout required — the CLI publishes to npm:
+
+\`\`\`bash
+curl -fsSL https://olam.bar.dev/install | sh   # installs @pleri/olam-cli on PATH
+olam setup                                       # k3d cluster + full peripheral stack
+\`\`\`
+
+\`olam setup\` is idempotent and substrate-aware: the default brings up a
+local k3d cluster (\`olam-dev\`) running host-cp, auth-service,
+mcp-auth-service, kg-service, and memory-service. Pass
+\`--substrate=docker\` for the lighter docker-compose path (3 containers,
+no cluster). Full guide:
+[\`docs/onboarding/k3s-mode-setup.md\`](onboarding/k3s-mode-setup.md).
+
+## 2. Register the MCP server (1 minute)
+
+\`\`\`bash
+olam mcp install                  # default --scope=user
+olam mcp install --scope=project  # writes to the project's .mcp.json
+\`\`\`
+
+This wires Olam's MCP server into Claude Code so the agent can manage
+worlds directly. Core tools: \`olam_create\`, \`olam_dispatch\`,
+\`olam_observe\`, \`olam_destroy\`, \`olam_list\`, \`olam_status\`,
+\`olam_enter\`, \`olam_crystallize\`, \`olam_pr_*\`. Restart Claude Code and
+verify with \`claude mcp list\` (look for \`olam\`).
+
+## 3. Configure your repos (2 minutes)
+
+Point Olam at the repos a world should clone. Use the interactive
+wizard:
+
+\`\`\`bash
+olam init        # interactive: writes .olam/config.yaml
+\`\`\`
+
+A workspace config declares the repos, services, compute tier, and cost
+caps for worlds spawned from it. The \`compute.default\` field selects the
+world-runner tier (\`docker\` | \`cloudflare\` | \`cloudflare-isolate\`). See
+[\`docs/architecture/config-spec.md\`](architecture/config-spec.md) for
+the full schema.
+
+## 4. Create your first world (2 minutes)
+
+In Claude Code, say:
+
+\`\`\`
+Create a world for fixing the login bug in my-project
+\`\`\`
+
+Claude will:
+1. Create a Docker container (or CF Sandbox) with your repo cloned
+2. Set up git worktrees for isolation
+3. Boot the in-world Claude session and auto-dispatch the task
+4. Return the Host CP dashboard URL (\`http://127.0.0.1:19000\`)
+
+## 5. Dispatch a task (1 minute)
+
+\`\`\`
+Dispatch to the world: investigate and fix the session timeout issue
+\`\`\`
+
+Claude Code runs autonomously inside the world. Every tool call, every decision, every exploration is captured as a thought node.
+
+## 6. Watch it work (ongoing)
+
+**Dashboard:** Open the Host CP URL from step 4. You'll see:
+- the **seed of thought** pinned at the top (the immutable task)
+- a **phase progress strip** (\`created → syncing → cloning → configuring → warming → ready → task_running\`)
+- the **completion ladder** — \`draft → recommendations → adversarial_review → audit_passed → pr_eligible → pr_opened\`, each step lit when its named actor files the event
+- a live **trace / events** stream of the agent's reasoning
+
+**Terminal:** Open the full-screen ttyd terminal to watch Claude's live session.
+
+**Observe:** In Claude Code, say:
+\`\`\`
+What is the world thinking right now?
+\`\`\`
+
+## 7. Clean up
+
+\`\`\`
+Crystallize and destroy the world
+\`\`\`
+
+This:
+1. Runs the intelligence pipeline (generates SessionDigest, ADRs)
+2. Persists the thought graph
+3. Destroys the container and worktrees
+4. The code lives in git branches; the thinking lives in the artifacts
+
+---
+
+## CLI Alternative
+
+If you prefer the terminal over Claude Code (the CLI is on your PATH
+after \`olam setup\`):
+
+\`\`\`bash
+olam create --name login-fix --repos my-project --task "Fix session timeout"
+olam dispatch login-fix "investigate and fix the session timeout"
+olam observe login-fix             # placeholder; for now attach via the world terminal
+olam status login-fix
+olam crystallize login-fix         # requires PLERI; otherwise no-op (exit 2)
+olam destroy login-fix             # accepts the world ID or name
+\`\`\`
+
+## Auth (managing Claude accounts)
+
+The auth-service comes up as part of \`olam setup\`. To add or inspect
+accounts:
+
+\`\`\`bash
+olam auth login                    # one-time PKCE; opens browser, paste code back
+olam auth status                   # container state + valid accounts
+olam auth list                     # list credentials (add --json for machine-readable)
+\`\`\`
+
+The auth-service runs inside the stack (\`:9999\` on the docker-compose
+substrate, or as the \`olam-auth-service\` pod on k3d) and serves fresh
+tokens to every world over a shared-secret-authenticated API. The
+refresh token never leaves the service.
+
+---
+
+## Key Concepts
+
+| Concept | What it means |
+|---------|--------------|
+| **World** | Isolated Docker environment for one task. Has its own git branch, services, and Claude session. |
+| **Thought graph** | DAG of every decision, exploration, and action during a session. The primary artifact. |
+| **Dispatch** | Sending a prompt to a world's Claude session. Context is preserved between dispatches. |
+| **Crystallize** | Persisting the thought graph. Happens automatically on session end, or manually. |
+| **Lane** | A parallel work track within a world. Multiple lanes can work on different aspects simultaneously. |
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| "Docker not running" | Start Docker Desktop |
+| "No Claude credentials" | Run \`claude auth login\` on the host |
+| Dashboard shows empty | Wait for the first dispatch to generate thoughts |
+| "Port already in use" | Another world is running. Use \`olam list\` to check |
+| Session seems stuck | Use \`olam enter <world>\` to open the terminal and check |
+
+## Architecture
+
+\`\`\`
+You (Claude Code) → MCP Server → World Manager → Docker / CF Sandbox
+                                                    ├── Claude Code (tmux)
+                                                    ├── in-world control plane (:8080)
+                                                    ├── Host CP dashboard (plan-chat-spa, :19000)
+                                                    └── world.db (thoughts + artifacts)
+\`\`\`
+
+For detailed architecture, see [docs/ARCHITECTURE.md](ARCHITECTURE.md).
+
+---
+
+## Setup — fresh machine
+
+Source: \`docs/onboarding/fresh-machine-setup.md\`
+
+# Fresh machine setup — docker compose mode
+
+> **Audience**: a new operator setting up olam on a fresh Mac or Linux box using
+> the **docker compose substrate** (3 host containers, no Kubernetes cluster).
+>
+> **Looking for the full k3d setup?** That is the default — see
+> [\`k3s-mode-setup.md\`](./k3s-mode-setup.md).
+>
+> At the end of this guide you have:
+>
+> - olam CLI installed globally + verified
+> - The 3 olam runtime containers (auth, kg-service, mcp-auth) pulled and running
+> - Claude Code auth configured against your operator credential
+> - Skills + agents from atlas-toolbox deployed under \`~/.claude/\` as symlinks
+> - olam-meta hook blocks (memory-recall + memory-classify) sentinel-bounded inside \`~/.claude/settings.json\`
+> - Memory-bridge running on \`127.0.0.1:3111\`, livez probing green
+> - kg-service classifier hook installed (optional but recommended)
+
+The recipe is **idempotent** — re-running a step is safe.
+
+---
+
+## 0. Prereqs
+
+| Requirement | Why | How to install |
+|---|---|---|
+| **macOS 14+ / Linux** | Olam targets these — Windows native is not supported | n/a |
+| **Node.js ≥ 20** | Runtime for the CLI + skill-source MCP servers | \`brew install node\` (mac) or \`nvm install 20\` |
+| **Docker** (daemon running) | Hosts the 3 olam runtime containers | Docker Desktop (macOS) or \`sudo apt install docker.io\` (Linux); colima works too |
+| **git** (with SSH key configured for your repos) | Cloning atlas-toolbox + per-world workspace mirrors | \`brew install git\` + \`ssh-keygen\` |
+| **Claude Code subscription** (operator account) | What the local \`claude\` CLI consumes for HTTPS-SDK + agent-SDK calls | \`npm install -g @anthropic-ai/claude-code\` |
+| **Tailscale** (optional) | Only if you'll be SSH-ing to other operators' machines | https://tailscale.com/download |
+
+Sanity-check before continuing:
+
+\`\`\`bash
+node --version          # → v20.x or higher
+docker info             # → Docker daemon details (no error)
+git --version           # → 2.x
+claude --version        # → ≥ 2026-04 build
+\`\`\`
+
+If any of those fail, fix that first.
+
+---
+
+## 1. Install the olam CLI
+
+\`\`\`bash
+curl -fsSL https://olam.bar.dev/install | sh
+olam --version          # → 0.1.166 (or newer)
+\`\`\`
+
+Or directly via npm:
+
+\`\`\`bash
+npm install -g @pleri/olam-cli@latest
+\`\`\`
+
+This brings down \`olam\`, \`olam-mcp\`, and a thin bundle of node modules. No Docker pulls happen yet.
+
+---
+
+## 2. Bootstrap the olam stack (docker compose mode)
+
+\`\`\`bash
+olam setup --substrate=docker
+\`\`\`
+
+This is the heaviest step (~3-8 minutes on first run). It:
+
+1. Pulls 3 container images from \`ghcr.io/pleri/\`:
+   - \`olam-auth\` — the Claude-auth proxy your CLI shells against (\`withCredential\` gateway).
+   - \`olam-mcp-auth\` — host-side MCP wrapper for Claude auth.
+   - \`olam-kg-service\` — knowledge-graph + classifier sidecar (port \`127.0.0.1:9997\`).
+2. Initialises \`~/.olam/config.json\` (schemaVersion 1, \`host.substrate: 'compose'\`).
+3. Starts the 3 containers via \`docker compose\`.
+4. Prompts you to authenticate Claude Code (\`olam auth login\` runs under the hood).
+
+When it finishes:
+
+\`\`\`bash
+olam services status      # → 3 containers RUNNING
+olam auth status          # → at least 1 active credential
+\`\`\`
+
+If \`olam auth status\` shows no credentials, run \`olam auth login\` and follow the prompts.
+
+---
+
+## 3. Initialise olam in your working directory
+
+Pick the directory where you keep your day-to-day code (e.g. \`~/Projects/my-org/my-repo\`), then:
+
+\`\`\`bash
+cd ~/Projects/my-org/my-repo
+olam init
+\`\`\`
+
+This writes a per-project \`.olam/config.yaml\` so olam knows the workspace boundary.
+
+Optional: skip the Pleri (analytics) prompt with \`olam init --skip-pleri\`.
+
+---
+
+## 4. Register atlas-toolbox as your skill source
+
+Atlas-toolbox is the canonical ECC shared-skills repo. You need its \`.git\` URL and read access — coordinate with the operator who set it up if you don't already have SSH access to \`git@github.com:atlas-builders/atlas-toolbox.git\`.
+
+\`\`\`bash
+olam skills source add \\
+  --name atlas-toolbox \\
+  --git-url git@github.com:atlas-builders/atlas-toolbox.git \\
+  --branch master \\
+  --trust \\
+  --no-sync-now \\
+  --no-install-hook
+\`\`\`
+
+What each flag does:
+
+- \`--trust\` — acknowledges that registering this source grants olam permission to symlink content into \`~/.claude/\`. Required because skill sources are a T6 capability class (they ship executable hook scripts).
+- \`--no-sync-now\` — defer the first sync until after memory-bridge is up (step 5), so the very first sync injects both halves (skill content + olam-meta blocks) in one transaction.
+- \`--no-install-hook\` — skip the legacy SessionStart hook (\`olam skills sync\` runs explicitly in step 6 instead).
+
+Verify:
+
+\`\`\`bash
+olam skills source list
+# → 1 skill source(s)
+#   [1] <id>   atlas-toolbox            master       (unpulled)   <iso-date> git@github.com:...
+\`\`\`
+
+---
+
+## 5. Start the memory-bridge
+
+The memory-bridge is a host process that serves \`127.0.0.1:3111/agentmemory/livez\`. When it's running, \`olam skills sync\` will inject the olam-meta-memory-recall + olam-meta-memory-classify hook blocks into \`~/.claude/settings.json\`. When it's NOT running, the strip half of the auto-migration still fires but no olam-meta blocks land — meaning operator gets no recall/classify behavior.
+
+\`\`\`bash
+olam memory secret                # → shows the bearer at ~/.olam/memory-secret (auto-generated on first run)
+olam memory start                 # → starts the host process; polls livez until ready
+olam memory status                # → pid + livez + secret-set check
+\`\`\`
+
+Sanity check the live probe:
+
+\`\`\`bash
+curl -sS http://127.0.0.1:3111/agentmemory/livez
+# → {"service":"agentmemory","status":"ok"}
+\`\`\`
+
+Optional: register memory as an MCP server so Claude Code can call it directly:
+
+\`\`\`bash
+olam memory install --scope user
+\`\`\`
+
+---
+
+## 6. Run the first sync
+
+\`\`\`bash
+olam skills sync
+\`\`\`
+
+You should see output like:
+
+\`\`\`
+sync summary
+  sources:         1
+  artifacts:       ~120
+  hook files:      3-5
+  permission files:1-2
+  symlinks made:   ~250
+  hooks added:     3
+  permissions:     ~60
+  settings backup: /Users/<you>/.olam/state/settings-backups/settings-<ISO>.json
+  meta-hooks:      mode=auto · memory=up
+  + injected: memory-recall, memory-classify
+
+  atlas-toolbox    120 artifacts · engineering, product, growth, design (all categories)
+ok synced 1 source(s), 120 artifact(s)
+\`\`\`
+
+The load-bearing lines:
+
+- \`meta-hooks: mode=auto · memory=up\` — memory-bridge probe succeeded.
+- \`+ injected: memory-recall, memory-classify\` — both olam-meta blocks are now in \`~/.claude/settings.json\`.
+
+If you ran this on a machine that had been using the old atlas-toolbox \`sync.sh\` (and therefore had bare atlas-shipped agentmemory hook entries in \`~/.claude/settings.json\`), you'll also see:
+
+\`\`\`
+  ~ auto-migrated: stripped 2 atlas-toolbox-shipped agentmemory hook entry(ies); replaced by olam-injected blocks
+\`\`\`
+
+That's the Phase C C3 auto-migration. The pre-strip state is snapshotted at \`~/.olam/state/migration-snapshots/meta-hooks-<ISO>-<pid>-<rand>.json\`. Reverse via \`olam skills migrate-hooks-back\` if you ever need to.
+
+---
+
+## 7. Install the kg-service grep classifier hook (recommended)
+
+Routes \`grep\` / \`rg\` / \`find\` invocations through the kg-service classifier so search hits the knowledge graph when the question is graph-shaped.
+
+\`\`\`bash
+olam kg install-hook --scope user        # writes the sentinel-bound hook to ~/.claude/settings.json
+olam kg doctor                            # validates the hook + the kg-service container
+\`\`\`
+
+Open a new Claude Code session to pick up the hook (existing sessions snapshot settings.json at start).
+
+---
+
+## 8. Verify the end state
+
+\`\`\`bash
+# (a) Skill sources registered
+olam skills source list
+
+# (b) Skill artifacts deployed (symlinks into ~/.olam/state/skill-sources/<id>/...)
+ls -la ~/.claude/skills/ | head -10
+ls -la ~/.claude/agents/ | head -10
+
+# (c) olam-meta sentinel-bound hook blocks in settings.json
+jq -r '.hooks.PreToolUse[]?.hooks[]?.command, .hooks.PostToolUse[]?.hooks[]?.command' \\
+  ~/.claude/settings.json | grep -E "olam-meta-memory|kg-service-v2"
+# expected output (3 lines):
+#   OLAM_META_SENTINEL=olam-meta-memory-recall-v1; ... agentmemory-recall-trigger.mjs
+#   OLAM_META_SENTINEL=olam-meta-memory-classify-v1; ... agentmemory-classify-queue.mjs
+#   KG_SENTINEL=kg-service-v2-classifier-hook; ... 127.0.0.1:9997/classify
+
+# (d) Memory-bridge live
+curl -sS http://127.0.0.1:3111/agentmemory/livez
+# → {"service":"agentmemory","status":"ok"}
+
+# (e) Trust-audit log entries (one per skill-source-add + per meta-hook-stripped)
+tail -3 ~/.olam/state/skill-sources-audit.log | jq -c '{timestamp, action, sourceId}'
+\`\`\`
+
+All five should return non-empty / OK output.
+
+---
+
+## 9. (Optional) Open a Claude Code session and test recall
+
+\`\`\`bash
+cd ~/Projects/my-org/my-repo
+claude                                  # opens a Claude Code session
+# Inside the session, run any bash/edit operation — the PreToolUse hook will
+# query the memory-bridge and inject \`additionalContext\` with recalled memories.
+# Look for \`[recall]\` lines in the Claude Code output.
+\`\`\`
+
+If the recall hook doesn't fire, run \`olam memory status\` to confirm the bridge is up + reachable.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| \`olam skills sync\` errors with \`GlobalConfigReadError\` | \`~/.olam/config.json\` schemaVersion mismatch | \`olam config validate\` then \`olam bootstrap\` again |
+| \`meta-hooks: mode=auto · memory=down\` in sync output | memory-bridge not running OR probe times out | \`olam memory start\` (idempotent) + curl the livez URL |
+| Skill artifacts show as broken symlinks | atlas-toolbox clone moved or deleted | \`olam skills source pull <id>\` to re-clone |
+| \`~/.claude/settings.json\` keeps reverting | Multiple Claude Code sessions writing simultaneously | A4 lock should serialize; if it doesn't, check \`~/.olam/state/.settings-json.lock\` for a stale holder |
+| \`olam --version\` shows old version after \`npm install -g\` | nvm shim conflict OR cached PATH | \`which -a olam\` to locate; \`npm uninstall -g @pleri/olam-cli && npm install -g @pleri/olam-cli@latest\` |
+
+---
+
+## What's NOT in this doc
+
+- Setting up Cloudflare-substrate worlds (separate doc: \`docs/architecture/cf-worlds-spec.md\`).
+- PLERI thought-graph integration (separate setup; skip-pleri is fine for most operators).
+- Per-project skill overrides (advanced; see Phase B B2 + \`docs/architecture/skill-source-contract.md\`).
+- Cutting an olam release (developer flow, not operator flow; see \`~/.claude/skills/olam-cut-release/SKILL.md\`).
+
+---
+
+## Reverting
+
+\`\`\`bash
+# Strip olam-injected meta-hook blocks but keep skill symlinks
+olam skills migrate-hooks-back
+
+# Remove the atlas-toolbox skill source entirely (deletes its clone + symlinks)
+olam skills source remove <id>
+
+# Stop + remove all olam-managed Docker containers
+olam services down
+
+# Uninstall the CLI
+npm uninstall -g @pleri/olam-cli
+\`\`\`
+
+\`~/.olam/state/migration-snapshots/\` keeps the pre-injection settings.json snapshots indefinitely; nothing prunes them automatically.
+
+---
+
+## Architecture — the problem olam solves
+
+Source: \`docs/architecture/01-problem.md\`
+
+# 1 · The problem
+
+## What "run an agent" usually means
+
+Today, running a coding agent means one of these:
+
+1. **Local CLI** — you install the agent on your laptop. It reads your
+   files, writes your files, runs commands with your shell. Fast but:
+   - Secrets, SSH keys, browser cookies — all in blast radius.
+   - Agent state mixes with your state: shell history, node_modules,
+     uncommitted WIP.
+   - One agent at a time. No parallelism without manual isolation.
+   - No audit trail beyond terminal scrollback.
+
+2. **Ephemeral cloud runner** (Actions, remote sandbox SaaS) — better
+   isolation but:
+   - Boot latency measured in minutes.
+   - Auth per-run (paste a token each time).
+   - No persistent identity: every run is a stranger.
+   - The agent exits when the job exits. No interactive session.
+
+3. **Long-lived VM** — stable identity but:
+   - Drift: the VM accumulates state nobody audits.
+   - Hard to reset cleanly; hard to parallelise.
+   - Still one host. Blast radius = the VM.
+
+## What we actually want
+
+\`\`\`mermaid
+flowchart LR
+  U[User] -->|one sentence| O{Olam}
+  O -->|provisions| W[Isolated world]
+  W -->|runs| A[Agent]
+  A -->|work + trail| R[Reviewed PR]
+  R -->|back to| U
+
+  style W fill:#1e1e24,stroke:#4f6aff,color:#e4e4e7
+  style R fill:#0c0c0f,stroke:#2eaa6f,color:#e4e4e7
+\`\`\`
+
+Properties the user doesn't want to negotiate:
+
+- **Throw-away**: the world should be destroyable without remorse. No
+  state worth keeping should live there after the run.
+- **Pre-loaded**: repos cloned, credentials injected, MCP servers
+  pre-baked. Zero setup per-task.
+- **Resumable**: if the platform evicts the sandbox, I come back to it
+  still knowing my context, not a login screen.
+- **Honest**: the system tells me what the agent did — every tool call,
+  every edit, every review verdict — without me re-running anything.
+- **Gated**: "done" means *actually* done. Not "the agent stopped
+  typing."
+
+## Why existing tools don't combine into this
+
+Each tool gets one or two of those properties. None ships the full
+stack:
+
+| Property           | Local CLI | Actions | SaaS sandbox | Long VM | **Olam** |
+|--------------------|:---------:|:-------:|:------------:|:-------:|:--------:|
+| Isolation          |     ✗     |    ✓    |      ✓       |    ✗    |    ✓     |
+| Sub-second boot    |     ✓     |    ✗    |      ✗       |    ✓    |    ✓     |
+| Persistent identity|     ✓     |    ✗    |      ✗       |    ✓    |    ✓     |
+| Resumable          |     ✓     |    ✗    |      ✗       |    ✓    |    ✓     |
+| Audit trail        |     ✗     |    ~    |      ~       |    ✗    |    ✓     |
+| Completion gates   |     ✗     |    ✗    |      ✗       |    ✗    |    ✓     |
+
+The last row — explicit completion gates — is the one no one ships.
+That's where the real product lives.
+
+## Where olam sits
+
+Olam ships in two flavors. Both expose the same world abstraction; the
+difference is where the workshop runs.
+
+\`\`\`mermaid
+flowchart TB
+  subgraph yourmachine ["Your machine"]
+    CLI["olam CLI / MCP"]
+    BR["Browser"]
+  end
+
+  subgraph local ["Local flavor — host-cp"]
+    HC["host-cp orchestrator (:9090)"]
+    AS["auth-service (:9999)"]
+    DB["devbox containers (per world)"]
+  end
+
+  subgraph cloud ["Cloud flavor — Cloudflare edge"]
+    W["Worker / Durable Object"]
+    S["Sandbox Container"]
+  end
+
+  subgraph dist ["Distribution"]
+    NPM["npm — @ernerds/olam"]
+    GHCR["GHCR — 3 multi-arch images"]
+  end
+
+  subgraph providers ["Providers"]
+    CA["Anthropic / Claude Code"]
+    GH["GitHub"]
+    LN["Linear"]
+  end
+
+  NPM -->|"npm install -g"| CLI
+  CLI -->|"olam bootstrap, pull by digest"| GHCR
+  GHCR -->|"host-cp, auth, devbox"| HC
+  GHCR --> AS
+  GHCR --> DB
+
+  CLI -->|"local"| HC
+  BR  -->|"local"| HC
+  HC <-->|"docker exec / ttyd"| DB
+  AS -->|"PKCE + token mint"| CA
+  DB -->|"withCredential"| AS
+
+  CLI -.->|"cloud"| W
+  BR  -.->|"cloud"| W
+  W <-->|"RPC"| S
+  W -->|"OAuth"| CA
+
+  DB -->|"gh"| GH
+  DB --> LN
+  S -->|"gh"| GH
+  S --> LN
+
+  style HC fill:#16161a,stroke:#4f6aff,color:#e4e4e7
+  style AS fill:#16161a,stroke:#eab308,color:#e4e4e7
+  style DB fill:#16161a,stroke:#c084fc,color:#e4e4e7
+  style W  fill:#16161a,stroke:#4f6aff,color:#e4e4e7
+  style S  fill:#16161a,stroke:#c084fc,color:#e4e4e7
+\`\`\`
+
+**Local flavor** (default for self-hosted operators).
+\`npm install -g @ernerds/olam\` lands a CLI; \`olam bootstrap\` pulls three
+images by digest from GHCR — \`olam-host-cp\`, \`olam-auth\`, \`olam-devbox\` —
+runs the protocol-version handshake, starts host-cp + auth-service, and
+walks the operator through Anthropic PKCE. Worlds are docker containers
+on the operator's own machine.
+
+**Cloud flavor**. The Cloudflare Worker plus a \`@cloudflare/sandbox\`
+Durable Object plays the role host-cp plays locally. The container is
+Cloudflare-managed.
+
+In both flavors a *gateway* mediates everything that can't safely live
+inside a world: OAuth token exchange, the credential vault, world
+lifecycle, and the completion ladder. The container is the *workshop*;
+the gateway (host-cp or Worker) is the *supervisor*.
+
+Next: [2 · The paradigm](./02-paradigm.md) — the three ideas that make
+this actually cohere.
+
+---
+
+## Architecture — system overview
+
+Source: \`docs/architecture/03-system.md\`
+
+# 3 · System architecture
+
+Olam runs two substrates in parallel. Both expose the same world
+abstraction; both share the same control concepts (credential vault,
+world lifecycle, completion ladder, crystallization via Pleri Plane).
+The difference is whether the workshop runs on the operator's machine
+or on Cloudflare's edge.
+
+\`\`\`mermaid
+flowchart TB
+  subgraph client ["Client surface"]
+    Dash["Dashboard SPA — React 19 + Vite"]
+    CLI["olam CLI / MCP (npm: @ernerds/olam)"]
+  end
+
+  subgraph local ["Local flavor — host-cp on operator machine"]
+    HC["host-cp orchestrator (:9090)"]
+    AS["auth-service (:9999, single-container vault)"]
+    DBs["devbox container per world (Node 20 + zsh + Claude Code + Codex)"]
+  end
+
+  subgraph cloud ["Cloud flavor — Cloudflare edge"]
+    CFA["CF Access SSO (JWT or service token)"]
+    W["Worker · olam (routing + OAuth + orchestrator)"]
+    DO[("Durable Object · OlamSandbox (phase, seed, trace, completion)")]
+    KV1[("KV · OLAM_CREDS (per-user tokens)")]
+    KV2[("KV · OLAM_WORKSPACES")]
+    R2[("R2 · OLAM_USER_PROFILES (skill bundles)")]
+    S["Sandbox container (cloudflare/sandbox:0.8.10)"]
+  end
+
+  subgraph providers ["Providers (shared)"]
+    ANT["Anthropic OAuth + token endpoint"]
+    GH["GitHub · gh CLI"]
+    LN["Linear MCP"]
+    PP["Pleri Plane · crystallize REST API"]
+  end
+
+  Dash -->|"HTTPS — local"| HC
+  CLI  -->|"HTTPS — local"| HC
+  HC <-->|"docker exec, ttyd, hooks"| DBs
+  HC -->|"world lifecycle, completion ladder"| HC
+  DBs -->|"withCredential — observes 429"| AS
+  AS  -->|"PKCE, refresh, mint per-world tokens"| ANT
+
+  Dash -.->|"HTTPS — cloud"| CFA
+  CLI  -.->|"service token — cloud"| CFA
+  CFA --> W
+  W <-->|"RPC"| DO
+  W <--> KV1
+  W <--> KV2
+  W <--> R2
+  W <-->|"containerFetch / wsConnect"| S
+  W -->|"OAuth — edge can reach providers"| ANT
+
+  DBs -->|"gh"| GH
+  DBs --> LN
+  DBs -->|"crystallize POST"| PP
+  S   -->|"gh"| GH
+  S   --> LN
+  S   -->|"crystallize POST"| PP
+
+  style HC fill:#0c0c0f,stroke:#4f6aff,color:#e4e4e7
+  style AS fill:#0c0c0f,stroke:#eab308,color:#e4e4e7
+  style DBs fill:#1e1e24,stroke:#2eaa6f,color:#e4e4e7
+  style W fill:#0c0c0f,stroke:#4f6aff,color:#e4e4e7
+  style DO fill:#0c0c0f,stroke:#a855f7,color:#e4e4e7
+  style S fill:#1e1e24,stroke:#2eaa6f,color:#e4e4e7
+  style KV1 fill:#0c0c0f,stroke:#eab308,color:#e4e4e7
+  style PP fill:#0c0c0f,stroke:#22d3ee,color:#e4e4e7
+\`\`\`
+
+## Shared concepts
+
+Both flavors implement the same quartet:
+
+- **Credential vault with hot-swap**. 429s observed at the
+  \`withCredential\` boundary report cooldown back to the vault, which
+  rotates to the next-eligible credential on retry. Local: auth-service.
+  Cloud: \`OLAM_CREDS\` KV plus the Worker's edge OAuth path. See
+  [credential-hotswap.md](./credential-hotswap.md).
+- **World lifecycle state machine**. Phases —
+  \`created → syncing → cloning → configuring → auth_required|warming →
+  ready → task_running\` — with legal-transition guards.
+- **Completion ladder**. Explicit ladder events validated by the same
+  \`completion.ts\` state machine; the ladder is what makes "done" mean
+  *actually* done.
+- **Crystallization via Pleri Plane**. Thought graphs accumulated by MCP
+  tools are flushed to the Pleri Plane REST API (\`POST /crystallize\`) via
+  \`PleriClient\` (\`packages/core/src/pleri/\`). A single \`pleri.token\` in
+  \`.olam/config.yaml\` replaces the former direct Neon database credentials.
+  Thoughts buffer locally in a per-container SQLite store (\`world.db\`) if
+  Pleri is unreachable or unconfigured; a world functions fully without
+  Pleri, but crystallization is unavailable until connectivity is restored.
+  See [ADR-004](../decisions/004-pleri-plane-replaces-neon.md).
+
+## Local-flavor components
+
+### CLI (\`@ernerds/olam\`)
+- Single npm package; \`npm install -g @ernerds/olam\` (Node 20+).
+- \`olam bootstrap\` is the sole on-ramp: docker daemon smoke → parallel
+  pull of 3 images by digest from GHCR (retry-throttle-coalesce per
+  Decision 16) → protocol-version handshake (\`olam.protocol.versions\`)
+  → host-cp start → auth-service start → interactive PKCE.
+- \`olam upgrade\` performs the atomic 6-tag swap: \`:olam-rollback\` saves
+  current canonical (\`:latest\` for host-cp + devbox, \`:local\` for auth)
+  then \`:olam-next\` advances canonical. Source build is opt-in via
+  \`--from-source\`, only honoured in monorepo dev mode.
+- \`olam create\` / \`dispatch\` / \`enter\` / \`pr\` etc. talk to host-cp.
+
+### host-cp (\`olam-host-cp\` image)
+- Single container running on the operator's docker daemon, port 9090.
+- Owns world lifecycle, ttyd routing, hooks ingestion, completion
+  projection — the same surface the Worker exposes in cloud mode.
+- Each world is a separately-spawned \`olam-devbox\` container; host-cp
+  manages the docker lifecycle and proxies the dashboard.
+
+### auth-service (\`olam-auth\` image)
+- Single container, port 9999. Holds the Anthropic refresh token in a
+  local vault file (\`OLAM_AUTH_DATA_PATH\`).
+- Mints per-world access tokens via \`withCredential\`; observes 429s and
+  cools down the offending credential. CI smoke: \`npm run audit:credentials\`.
+- Default canonical tag is \`:local\` (not \`:latest\`) per
+  \`AuthContainerController.DEFAULT_IMAGE\`.
+
+### devbox (\`olam-devbox\` image)
+- Per-world container. Pre-baked: Claude Code CLI, Codex CLI, Slack +
+  Linear MCP servers, \`gh\`, ttyd, tmux, zsh.
+- Talks to auth-service over the host docker network for credential
+  retrieval — never embeds raw tokens.
+- Crystallizes thought graphs to Pleri Plane via \`PleriClient\`; buffers
+  locally in \`world.db\` (SQLite) when Pleri is unreachable.
+
+## Cloud-flavor components
+
+### Worker (\`olam\`)
+- Authority for cross-world concerns: vault lookup, OAuth refresh, PKCE
+  exchange (providers block container egress IPs).
+- Path-based proxy to per-session container via \`/sandbox/:id/*\`
+  (\`containerFetch\` for HTTP, \`wsConnect\` for the ttyd terminal iframe).
+- \`runSessionOrchestrator\` walks the world lifecycle in \`ctx.waitUntil\`.
+- \`POST /session/:id/completion/event\` validates ladder transitions.
+
+### Durable Object (\`OlamSandbox\`)
+- One DO per world, keyed by \`sessionId\`. Extends \`@cloudflare/sandbox\`'s
+  \`Sandbox\` class so it owns both container RPC and per-world state.
+- State persisted under a single \`world\` key: phase + detail + setupLog
+  + \`sessionMeta\` (seedTask, vaultEmail) + bounded traceBuffer (2000) +
+  completion record.
+
+### Container (cloud)
+- Based on \`cloudflare/sandbox:0.8.10\`. Same pre-baked toolchain as
+  local devbox; same \`/api/*\` surface on port 8080.
+- Same \`PleriClient\` crystallization path as local devbox; Pleri token
+  injected at session setup via the Worker's vault lookup.
+
+### Vault (KV + R2)
+- \`OLAM_CREDS\` — per-user Anthropic + OpenAI tokens, scopes, expiry.
+- \`OLAM_WORKSPACES\` — repo lists + defaults.
+- \`OLAM_USER_PROFILES\` — content-addressed R2 bundle of skills the
+  container untars into \`~/.claude/skills/\`.
+
+## Dashboard (shared)
+
+- Same React 19 + Vite + Motion 12 SPA in both flavors.
+- Local: served by host-cp; cloud: served from inside the sandbox
+  container with \`<base href="/sandbox/:id/">\` injected.
+- Every panel is a projection — \`CompletionLadder\`, \`PhaseProgress\`,
+  \`TracePanel\`, \`SeedCard\`, \`SessionHealthBar\` — never an inference.
+
+## Traffic matrix (who talks to whom)
+
+| From → To                  | Local flavor                  | Cloud flavor                       |
+|----------------------------|-------------------------------|------------------------------------|
+| Browser → gateway          | HTTPS to host-cp :9090        | HTTPS to Worker via CF Access      |
+| CLI / MCP → gateway        | HTTPS to host-cp :9090        | service token via CF Access        |
+| Gateway → world container  | docker exec, ttyd, HTTP hooks | \`containerFetch\` / \`wsConnect\`     |
+| Hooks → gateway            | HTTP POST to host-cp          | HTTP POST to container :8080       |
+| Gateway → Anthropic        | auth-service PKCE             | Worker edge OAuth                  |
+| World → Anthropic          | \`withCredential\` to auth-svc  | injected token from KV via Worker  |
+| World → GitHub             | injected \`GITHUB_TOKEN\`       | injected \`GITHUB_TOKEN\`            |
+| World → Pleri Plane        | \`PleriClient\` HTTP POST (crystallize) | \`PleriClient\` HTTP POST (crystallize) |
+
+## Substrate event delivery
+
+The two substrates handle incoming GitHub events through opposite mechanisms,
+dictated by their environments.
+
+**CF Worker — push (webhook).** The Worker exposes \`POST /webhooks/github\`
+(\`packages/cloudflare-worker/src/index.ts:2648\`) as a public GitHub App
+webhook receiver. GitHub delivers events to the Worker's stable public URL;
+the endpoint is HMAC-gated. CF has no persistent background processes —
+push is the only viable model.
+
+**host-cp — poll.** host-cp runs \`packages/host-cp/src/pr-merge-poller.mjs\`,
+a polling loop (default 300 s interval) that queries the GitHub API to detect
+PR merges. host-cp runs on the operator's machine — often behind NAT or a
+firewall — so GitHub cannot push to it. Polling is the only viable model.
+
+The two shapes are **functionally equivalent** (both detect the same events)
+but **architecturally opposite**: CF is push-based; host-cp is pull-based.
+This asymmetry is substrate-dictated, not a design gap. See
+[ADR-012](../decisions/012-substrate-event-delivery-asymmetry.md).
+
+Next: [4 · World lifecycle](./04-lifecycle.md) — the phase state machine.
+
+---
+
+## Architecture — world lifecycle
+
+Source: \`docs/architecture/04-lifecycle.md\`
+
+# 4 · World lifecycle
+
+The **phase** state machine owns provisioning. It sits one layer below
+the completion ladder — "is the world operational?" vs "is the work
+done?".
+
+## States + transitions
+
+\`\`\`mermaid
+stateDiagram-v2
+  [*] --> created
+  created --> syncing : orchestrator starts
+  syncing --> cloning : profile loaded
+  cloning --> configuring : repos cloned
+  configuring --> auth_required : no vault creds
+  configuring --> warming : vault creds injected
+  auth_required --> warming : /auth/complete
+  warming --> ready : probe ACKs
+  warming --> failed : probe timeout or spawn error
+  ready --> task_running : auto-dispatch
+  task_running --> ready : dispatch accepted
+  task_running --> destroyed : user destroys
+  ready --> destroyed
+  failed --> destroyed
+  failed --> warming : /resume
+  destroyed --> [*]
+\`\`\`
+
+All transitions are validated in \`src/phase.ts:isLegalTransition\`.
+Illegal transitions throw \`IllegalPhaseTransitionError\`. Self-
+transitions on the same phase are legal — used to refresh the
+\`detail\` string during long phases like \`warming\`.
+
+## The provisioning pipeline (happy path)
+
+\`\`\`mermaid
+sequenceDiagram
+  autonumber
+  participant User
+  participant Worker
+  participant DO as Durable Object
+  participant Sandbox as "Sandbox container"
+  participant Vault as OLAM_CREDS KV
+  participant Claude
+
+  User->>Worker: POST /session/start { task, workspace, userEmail }
+  Worker->>DO: transition created → syncing
+  Worker-->>User: 202 { sessionId, dashboardUrl }
+  Note over Worker: remainder runs in ctx.waitUntil
+
+  Worker->>DO: setSessionMeta { seedTask, vaultEmail }
+  Worker->>Sandbox: mkdir /home/user/workspace (via sandbox.exec)
+  Worker->>Sandbox: gitCheckout repo₁ … repoₙ (parallel)
+  Worker->>DO: transition → cloning (with detail)
+  Worker->>Sandbox: writeFile pending-task.txt
+  Worker->>DO: transition → configuring
+
+  Worker->>Vault: get user:<hash>:claude
+  Vault-->>Worker: stored tokens
+  Worker->>Worker: refreshClaudeTokens (always)
+  Worker->>Vault: put refreshed tokens
+  Worker->>Sandbox: writeFile ~/.claude/.credentials.json
+  Worker->>Sandbox: writeFile ~/.claude/settings.json (hooks + permMode)
+  Worker->>Sandbox: chown -R olam:olam /home/user
+
+  Worker->>DO: transition → warming
+  Worker->>Sandbox: POST /api/session/warmup
+  Sandbox->>Sandbox: tmux new-session -d -s claude-main -x 220 -y 50
+  Sandbox->>Claude: runuser - olam -c 'claude --dangerously-skip-permissions --remote-control'
+  Sandbox->>Sandbox: autoAcceptPrompts (bypass / trust / theme wizards)
+
+  loop Every 3s, up to 90s
+    Worker->>Sandbox: POST /api/session/probe-ready
+    Sandbox->>Sandbox: send nonce via ! echo <nonce> > /tmp/olam-probe-*
+    Sandbox-->>Worker: {ready: true, elapsedMs}
+  end
+
+  Worker->>DO: transition → ready
+  Worker->>Sandbox: GET /api/pending-task → task
+  Worker->>Sandbox: POST /dispatch { prompt: task }
+  Worker->>DO: transition → task_running
+  Worker->>DO: clearPendingTask
+\`\`\`
+
+## The probe
+
+The \`/api/session/probe-ready\` endpoint is the system's **definition
+of "ready."** It's not a heartbeat — it actively exercises the
+capability the rest of the pipeline depends on:
+
+\`\`\`mermaid
+flowchart LR
+  S1["tmux has-session"] --> S2["isClaudeResponsive"]
+  S2 --> S3["send-keys Escape + Ctrl+U"]
+  S3 --> S4["send-keys ! echo nonce > /tmp/olam-probe-nonce"]
+  S4 --> S5["send-keys Enter"]
+  S5 --> S6["poll /tmp for nonce file"]
+  S6 -->|match| OK["ready: true"]
+  S6 -->|timeout| FAIL["ready: false (stage: nonce-ack)"]
+
+  style OK fill:#0c0c0f,stroke:#2eaa6f,color:#e4e4e7
+  style FAIL fill:#0c0c0f,stroke:#ef4444,color:#e4e4e7
+\`\`\`
+
+Why the nonce approach:
+- \`tmux has-session\` alone lies — the session can exist but claude be
+  stuck on a wizard.
+- \`capture-pane | grep ❯\` lies — claude uses \`❯\` as both input cursor
+  and menu cursor.
+- Actually typing into claude's bash mode and waiting for a file is
+  the **same syscall path** (posix_spawn → /bin/sh) that user
+  commands + hooks use. If the probe succeeds, we know the whole
+  spawn surface works.
+
+Each probe mints its own nonce + unique file path, so late
+acknowledgements can never falsely satisfy a future probe (no
+stale-ack race).
+
+## Resume
+
+CF Sandbox containers can be evicted under idle pressure. When they
+come back, \`/home/user/.claude/*\` is empty and the claude-main tmux
+session is gone — but the DO still thinks the world is
+\`task_running\`.
+
+\`\`\`mermaid
+sequenceDiagram
+  autonumber
+  participant Dash as Dashboard
+  participant Worker
+  participant DO
+  participant Sandbox as "Reincarnated container"
+  participant Vault
+
+  Dash->>Sandbox: GET /api/session-health
+  Sandbox-->>Dash: { tmuxAlive: false, claudeRunning: false }
+  Dash->>Dash: useAutoResume detects divergence
+
+  Note over Dash: also triggers when warming stalls > 60s
+
+  Dash->>Worker: POST /session/:id/resume
+  Worker->>DO: read sessionMeta.vaultEmail
+  Worker->>Vault: get + refresh creds
+  Worker->>Sandbox: writeFile .credentials.json
+  Worker->>DO: transition → warming (detail: resume)
+  Worker->>Sandbox: POST /api/session/warmup
+  Worker->>Worker: driveToReadyAndAutoDispatch (fresh waitUntil budget)
+  Worker->>DO: transition → ready → task_running
+\`\`\`
+
+The hook doesn't require user action — navigating back to a stale
+dashboard is enough. No Auth modal, no re-auth.
+
+## Local devbox lifecycle
+
+The CF flow above is one of two flavors. The local flavor swaps DO
++ Sandbox for \`WorldManager\` + a docker container, and the SPA's
+host-cp daemon for the dashboard. The state machine is identical;
+the actors differ.
+
+Key boundary: \`host-cp\` does **not** spawn devboxes. The CLI invokes
+\`WorldManager.createWorld()\` (in \`@olam/core\`) directly on the
+operator's host, then notifies host-cp so its inbox surfaces the
+world. host-cp deliberately ships without \`@olam/core\`'s native
+git/docker/sqlite deps to keep its container slim
+(\`packages/host-cp/src/server.mjs:610-680\`).
+
+\`\`\`mermaid
+sequenceDiagram
+  autonumber
+  participant User
+  participant CLI as "olam create CLI"
+  participant WM as "WorldManager (@olam/core)"
+  participant Docker as "Docker daemon"
+  participant Devbox as "devbox container"
+  participant HostCp as "host-cp daemon"
+  participant Inbox as "SPA inbox"
+
+  User->>CLI: olam create my-world --workspace atlas
+  CLI->>WM: createWorld({ name, repos, workspace, task })
+  WM->>WM: resolve repos · allocate port · pick branch
+  WM->>Docker: docker run olam-devbox:latest (volumes + env)
+  Docker->>Devbox: container starts · CP boots on host port
+  Devbox->>Devbox: git clone repos · inject vault creds
+  Devbox->>Devbox: tmux new-session · spawn \`claude --remote-control\`
+  WM-->>CLI: WorldMetadata { id, dashboardUrl, port }
+
+  Note over CLI: post-create auto-register
+
+  CLI->>HostCp: GET /api/bootstrap (probe + token)
+  HostCp-->>CLI: 200 { token }
+  CLI->>HostCp: POST /api/admin/registry { id, port }
+  HostCp->>HostCp: persist ~/.olam/host-cp-registry.json
+  HostCp->>Inbox: SSE world-added event
+  Inbox-->>User: world card appears · "ready for dispatch"
+\`\`\`
+
+If host-cp isn't running the create still succeeds —
+\`packages/cli/src/commands/create.ts\` falls through to a
+"World was created but not registered" warning with the manual
+\`olam host-cp register --world <id>\` remedy. Auto-registration is
+best-effort; the SQLite world index (\`~/.olam/worlds.db\`) is the
+source of truth and host-cp reconciles from it on startup.
+
+Mode auto-detection: host-cp picks \`container\` vs \`bare\` mode by
+probing \`/.dockerenv\` (\`server.mjs:64-89\`). Container mode reaches
+per-world CPs via \`host.docker.internal:<port>\`; bare mode uses
+\`127.0.0.1:<port>\`. The same daemon binary serves both.
+
+Next: [5 · Completion ladder](./05-completion.md) — the *work*
+state machine on top of this *operational* state machine.
+
+---
+
+## CLI command reference
+
+Top-level commands (run \`olam <command> --help\` for flags and subcommands):
+
+- \`olam add\` — Register a local repo path
+- \`olam admin\` — Admin operations (require admin secret)
+- \`olam aggregate\` — Aggregate plan stats by operator (gate #3 measurement)
+- \`olam apply\` — Create a world from a runbook (delegates to olam create)
+- \`olam apply-overlays\` — Merge ~/.claude/skills.overrides/ and ~/.claude/agents.overrides/ over upstream (section-as-unit merge per markdown-merger)
+- \`olam ask\` — Ask olam about its own usage, setup, and CLI (local Claude subscription)
+- \`olam audit-log\` — Inspect the manifest-refresh audit log (~/.olam/state/manifest-refresh-audit.jsonl).
+- \`olam auth\` — Manage the local Claude auth container
+- \`olam bake\` — Bake a source DB into the singleton as a named seed template
+- \`olam begin\` — Start the Olam host control plane (alias: olam host-cp start)
+- \`olam bind-service-token\` — Bind a Cloudflare service token to your CF Access user sub on the remote auth-worker
+- \`olam bootstrap\` — One-shot wiring of a fresh Hermes install to olam (MCP + KG hook + skill mirror)
+- \`olam build\` — Build pristine KG for a workspace (default: current dir). Routes through olam-kg-service /build endpoint. Use --pending to drain the pending queue.
+- \`olam check-ports\` — Check if runbook ports are available
+- \`olam clean\` — Reap orphan world filesystem state under ~/.olam/worlds/
+- \`olam completion\` — Emit a POSIX shell completion script for zsh or bash.
+- \`olam config\` — Manage global olam configuration
+- \`olam create\` — Create a new development world
+- \`olam crystallize\` — Crystallize thoughts from a world to Pleri Plane
+- \`olam deregister\` — Remove a world from the host CP registry (does NOT destroy the world)
+- \`olam destroy\` — Destroy a world and clean up resources (accepts world ID or name)
+- \`olam diagnose\` — Bundle diagnostics into a zip file for sharing with maintainers
+- \`olam diff\` — Show what
+- \`olam disable\` — Take a credential out of rotation (manual cooldown)
+- \`olam dispatch\` — Send a prompt to a world for execution
+- \`olam doctor\` — Run 4 diagnostic probes against the remote auth-worker
+- \`olam down\` — [deprecated] Stop the auth container — use
+- \`olam enable\` — Re-enable a disabled credential
+- \`olam enter\` — Open terminal to a world
+- \`olam evict\` — Evict oldest snapshots until total size ≤ cap (default 5GB; override via OLAM_SNAPSHOT_MAX_BYTES)
+- \`olam get\` — Print the active substrate
+- \`olam hermes\` — Hermes integration commands
+- \`olam host-cp\` — Manage the Olam host control plane container
+- \`olam implode\` — Destroy ALL local olam install + configs (containers, images, volumes, ~/.olam/, npm package). Default is dry-run.
+- \`olam init\` — Initialize olam in the current project
+- \`olam inspect\` — Diagnose warm-create cache hits/misses for a workspace (read-only; mutates nothing)
+- \`olam install\` — Pick an archetype preset for this Olam install
+- \`olam install-hook\` — Install kg-service hook (idempotent). --for hermes targets ~/.hermes/; default targets .claude/settings.json
+- \`olam issue-anthropic-token\` — Mint a new Anthropic proxy token via the remote auth-worker (g4)
+- \`olam keys\` — Manage LLM API keys stored at ~/.olam/keys.yaml
+- \`olam kg\` — Knowledge-graph operations (kg-service container)
+- \`olam lanes\` — Manage claude-lane-* tmux sessions inside a running world
+- \`olam list\` — List credentials (local by default; --remote to query a remote auth-worker)
+- \`olam list-anthropic-tokens\` — List Anthropic proxy tokens from the remote auth-worker (g4)
+- \`olam login\` — Run the OAuth PKCE flow to store a Claude account in the auth container, or print a remote OAuth URL (--remote)
+- \`olam logout\` — Remove an account from the auth container
+- \`olam logs\` — Stream application logs from a world (engine-agnostic)
+- \`olam migrate-hooks-back\` — Reverse olam-meta hook injection by restoring ~/.claude/settings.json from a B5 snapshot
+- \`olam migrate-to-remote\` — Print guidance for re-authenticating local credentials against the remote auth-worker (v1: no auto-migration of secrets)
+- \`olam observe\` — Stream thoughts from a world (coming soon)
+- \`olam onboard\` — Fresh-install umbrella: register + clone + install SessionStart hook + first sync, in one verb
+- \`olam path\` — Print the absolute path to ~/.olam/keys.yaml
+- \`olam plans\` — Manage Olam Cloud plans (list / show / rm / re-register)
+- \`olam policy-check\` — Check .olam/policies/ against the current diff
+- \`olam pr\` — Review and decide PR-gate requests from running worlds
+- \`olam prune\` — Delete shadow-backup files older than a duration (e.g. 30d) OR all of them with --all --force
+- \`olam ps\` — List running processes in a world container
+- \`olam pull\` — Fetch + reset the clone to upstream HEAD
+- \`olam refresh\` — Force-refresh an account token (substrate-aware: updates kubernetes Secret on k8s substrate)
+- \`olam register\` — Register a world with the running host CP so it appears in the unified UI
+- \`olam rekey\` — Rotate the per-world postgres password for a hybrid-mode world
+- \`olam remove\` — Permanently remove a credential (purge tokens)
+- \`olam reorder\` — Move a registered source to a new ordinal (1-indexed; mutates precedence)
+- \`olam repos\` — Manage the global repo registry
+- \`olam restart\` — Restart a world container (auto-builds agent-stream bundle when stale)
+- \`olam restore\` — Move a shadow-backup file back to its original path
+- \`olam resume\` — Resume a world by PR number, URL, or branch — finds the world that opened the PR and enters it.
+- \`olam revoke-anthropic-token\` — Revoke an Anthropic proxy token on the remote auth-worker (g4)
+- \`olam rotate-service-token\` — Revoke a service token and guide through re-binding a replacement
+- \`olam runbooks\` — Manage runbooks in the global config
+- \`olam savings\` — Show cumulative KG-hit savings tallied by the kg-service container
+- \`olam seed\` — Manage postgres seed templates on the olam-postgres singleton
+- \`olam services\` — Manage Olam service containers. Substrate-aware: compose uses docker; kubernetes uses kubectl.
+- \`olam set-prefix\` — Set the deploy prefix for a registered skill source (skills+agents deploy as <prefix>:<canonical-name>)
+- \`olam set-prefix-scope\` — Set which artifact kinds are renamed by the prefix (comma-separated: skill, agent, or skill,agent)
+- \`olam setup\` — Fresh-host onboarding wizard. Default substrate=kubernetes (k3d on all platforms):
+- \`olam setup-linux-gate-status\` — Detect whether the Linux platform expansion gate has been triggered.
+- \`olam setup-metrics\` — Query trust-audit-log for olam setup dogfood statistics.
+- \`olam shadow-backups\` — Manage
+- \`olam show\` — Show full gate detail (diff, command, commits)
+- \`olam skills\` — Manage skill sources and synchronization
+- \`olam snapshot\` — Manage world snapshots for fast boot
+- \`olam source\` — Manage registered skill sources
+- \`olam start\` — Start the host CP container (token regenerated each call)
+- \`olam status\` — [deprecated] Show container state — use
+- \`olam stop\` — Stop the host CP container + remove token + PID files
+- \`olam substrate\` — Manage deployment substrate (beta)
+- \`olam sync\` — Sync registered skill sources to ~/.claude/
+- \`olam uninstall\` — Remove /10x: chain skill symlinks from ~/.claude/skills (preserves user-authored skills + non-chain skill sources)
+- \`olam uninstall-hook\` — Remove kg-service PreToolUse hook from .claude/settings.json (sentinel-matched; surgical)
+- \`olam unset-prefix\` — Remove the deploy prefix from a registered skill source (reverts to canonical deploy names)
+- \`olam unset-prefix-scope\` — Remove the prefix-scope override from a registered skill source (reverts to default: both skill and agent are renamed)
+- \`olam up\` — [deprecated] Start the auth container — use
+- \`olam update\` — Update a registered repo
+- \`olam upgrade\` — Upgrade the olam-auth container. Default: pull olam-auth@<digest> from ghcr.io and recreate.
+- \`olam version\` — Show olam-cli version + registered chain-skill source identities
+- \`olam watch\` — Run graphify --watch against a workspace, keeping its pristine KG fresh
+- \`olam workspace\` — Manage the named catalog of repo bundles that worlds instantiate from
+- \`olam world\` — World management subcommands
+- \`olam yolo\` — Dispatch a parallel Claude Code session in a new tmux window + isolated git worktree
+`;
+//# sourceMappingURL=knowledge-pack.generated.js.map