@pleri/olam-cli 0.1.201 → 0.1.205

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

@@ -1,2362 +0,0 @@
-/**
- * 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
-
-**Two paths: Kubernetes (default, full-featured) or Docker Compose (lighter, for CI).**
-
-### Kubernetes (recommended)
-
-\`\`\`bash
-curl -fsSL https://olam.bar.dev/install | sh
-olam setup
-\`\`\`
-
-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.
-
-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).
-
-### Create your first world
-
-After setup completes, every world is one call:
-
-\`\`\`bash
-olam create --name my-world --task "audit the auth module for SSRF"
-\`\`\`
-
-Open the dashboard URL in your browser — you'll see the world provisioning, credentials flowing in from the vault, and your task dispatching to an in-world Claude session.
-
----
-
-## 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\`)
-- **GitHub CLI authenticated** (\`gh auth login\`) — \`olam setup\` uses \`gh auth token\` to create a GHCR pull secret; skipping this fails on first image pull
-- **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 (PLERI is the GitHub org & npm scope)
-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. Verify your setup (1 minute)
-
-\`\`\`bash
-olam doctor      # runs 8–23 checks: auth, services, vault, network
-\`\`\`
-
-This diagnoses common issues (Docker daemon, images, credentials, etc.). Any FAIL row shows an actionable remedy — fix and re-run until all rows PASS.
-
-## 3. 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\`).
-
-## 4. 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.
-
-## 4b. Multi-project workspaces (optional)
-
-Olam supports managing multiple repos across different projects. Each
-workspace is a named bundle of repos that can be reused across worlds.
-
-\`\`\`bash
-olam workspace list                                    # see configured workspaces
-olam workspace add my-workspace --repo <url>#<branch> # create from repos
-olam workspace add my-workspace --from-config          # seed from current .olam/config.yaml
-olam workspace show my-workspace                       # pretty-print workspace YAML
-olam workspace remove my-workspace                     # delete a workspace
-\`\`\`
-
-When creating a world, specify the workspace:
-
-\`\`\`bash
-olam create --name <world> --workspace my-workspace --task "..."
-\`\`\`
-
-See [\`docs/architecture/config-spec.md\`](architecture/config-spec.md) for
-the full workspace schema.
-
-## 5. 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:19001\`)
-
-## 6. 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.
-
-## 7. 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?
-\`\`\`
-
-## 8. 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             # Alternative: \`olam enter login-fix\` for a shell inside the world (until \`olam observe\` ships)
-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 |
-|---------|-----|
-| Something not working | Run \`olam doctor\` — it diagnoses the setup and shows remedies for each issue |
-| "Docker not running" | Start Docker Desktop |
-| "No Claude credentials" | Run \`claude auth login\` on the host |
-| "GHCR pull secret failed" or "401 unauthorized" on first \`olam setup\` | Run \`gh auth login\` and verify with \`gh auth status\` |
-| 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 |
-| Blank page at localhost:19001 (npm install) | Run \`olam services up\` to restart host-cp; check \`olam doctor\` for SPA dist staging. |
-| Blank page at localhost:19001 (source checkout) | Run \`cd packages/host-cp && npm run build:spa\` to rebuild the SPA dist locally. |
-| Cloud toggle missing in SPA | Both \`OLAM_CLOUD_URL\` and \`OLAM_SHOWCASE_PASSWORD\` must be set. If only one is set the server logs a \`[cloud]\` warning at startup. |
-
-## Bare-node / source-checkout mode
-
-If you are running host-cp directly from source (not via \`olam setup\`
-or a pulled Docker image), you need to build the SPA before first boot:
-
-\`\`\`bash
-# From the repo root:
-cd packages/host-cp
-npm run build:spa   # builds plan-chat-spa and stages it into packages/host-cp/dist/
-npm start           # prestart hook runs check:spa first; rebuilds if dist is stale
-\`\`\`
-
-\`npm start\` runs \`check:spa\` first. If \`dist/\` is already populated and
-self-consistent (every asset in \`index.html\` is present on disk) it skips
-the build and starts immediately. If not, it calls \`build:spa\` to rebuild.
-
-The \`build:spa\` script triggers a full \`npm run build:ci\` + \`vite build\`
-chain on a cold checkout (takes ~60s the first time; subsequent runs skip
-the vite build if \`packages/plan-chat-spa/dist/client/\` is already populated).
-
-**This is not required when using \`olam setup\`** — the Docker image has the
-SPA baked in and host-cp never touches the local \`dist/\` directory.
-
-## 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 service (Docker container)
-
-The memory-service is a Docker container (managed by \`olam services\`) 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 olam-memory-service container; polls livez until ready
-olam memory status                # → container state + livez + secret-set check
-\`\`\`
-
-**Note:** \`~/.olam/memory-secret\` is used with the Docker Compose substrate (this guide). For Kubernetes, the file is \`~/.olam/memory-bearer-secret\`. They are the same logical service in different deployment substrates.
-
-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\`).
-- **Cloud-mode (optional)**: if you want dispatches to run on Cloudflare Sandboxes instead of local Docker, follow [plan-cloud-mode-setup.md](../runbooks/plan-cloud-mode-setup.md) to set \`OLAM_CLOUD_URL\` + \`OLAM_SHOWCASE_PASSWORD\` on host-cp.
-- 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.
-
----
-
-## Setup — k3d/k3s mode (default substrate, port 19001)
-
-Source: \`docs/onboarding/k3s-mode-setup.md\`
-
-# Olam in k3d mode — definitive setup guide
-
-> **Audience**: an operator setting up olam on their workstation. k3d mode runs olam's full peripheral stack (host-cp, auth-service, mcp-auth-service, kg-service, memory-service) as a real Kubernetes deployment on a local k3d cluster, with Prometheus + Grafana + Loki + Kyverno for observability.
->
-> **End state**: a local k3d cluster \`olam-dev\`, five peripheral pods at \`1/1 Running\` in the \`olam\` namespace, a \`monitoring\` namespace with kube-prometheus-stack + Grafana, the \`olam\` CLI talking to host-cp inside the cluster.
->
-> **Time**: ~5 minutes warm, ~10 minutes cold (image pulls).
->
-> **k3d on all platforms**: olam uses k3d (k3s wrapped in Docker) on both macOS and Linux. No sudo needed — k3d only requires a Docker daemon. Same substrate, same mental model, same teardown on every machine.
-
-k3d is the **default mode** for olam. For the lighter docker-compose mode (3 containers, no cluster), see [fresh-machine-setup.md](fresh-machine-setup.md).
-
----
-
-## 0. Prerequisites
-
-You need these tools installed. \`olam setup\` will prompt to install missing brew-formulae for you on macOS (answer y); on Linux it uses the upstream k3d install script (no sudo needed). Pass \`-y\` to skip all prompts.
-
-| Tool | Why | Install |
-|---|---|---|
-| **Node.js ≥ 20** | The olam CLI runs on Node | \`nvm install 20\` |
-| **Docker daemon** | k3d runs k3s nodes as Docker containers (required on all platforms) | Docker Desktop (macOS/Windows) or \`sudo apt install docker.io\` (Linux); colima works too |
-| **colima** (macOS, optional) | Lightweight Docker runtime for macOS | \`brew install colima && colima start --cpu 4 --memory 8 --vm-type=vz --mount-type=virtiofs\` |
-| **k3d** | Wraps k3s in Docker for local clusters — works on macOS and Linux, no sudo | \`brew install k3d\` (macOS/Linux with brew) or \`curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh \\| bash\` |
-| **kubectl** | Cluster operations | \`brew install kubectl\` |
-| **helm** | Installs Loki + Promtail + Grafana + Prometheus + Kyverno | \`brew install helm\` |
-| **gh** | ghcr-pull secret + \`gh auth token\` | \`brew install gh && gh auth login\` |
-| **docker** + \`docker compose\` plugin | Hosts the docker-socket-proxy sibling container | Docker Desktop, or colima ships it |
-| **jq, curl, openssl** | Shell helpers | macOS defaults |
-| **Claude Code subscription** | The \`claude\` CLI inside each world consumes your local subscription | \`npm install -g @anthropic-ai/claude-code\` |
-
----
-
-## 1. Install the olam CLI
-
-\`\`\`bash
-# One-line installer (recommended)
-curl -fsSL https://olam.bar.dev/install | sh
-
-# Or via npm directly
-npm install -g @pleri/olam-cli
-\`\`\`
-
-Verify:
-
-\`\`\`bash
-olam --version
-\`\`\`
-
-The CLI ships every manifest, secret template, and observability install script it needs inside the npm tarball — no \`git clone\` required.
-
----
-
-## 2. Authenticate \`gh\`
-
-\`\`\`bash
-gh auth login
-\`\`\`
-
-The bootstrap creates a \`ghcr-pull\` Kubernetes Secret from \`gh auth token\` so pulls of \`ghcr.io/pleri/olam-*\` images don't hit anonymous rate limits.
-
----
-
-## 3. Bootstrap
-
-Single command, end-to-end:
-
-\`\`\`bash
-olam setup
-\`\`\`
-
-Pass \`-y\` to skip all prompts (non-interactive, auto-affirm every step):
-
-\`\`\`bash
-olam setup -y
-\`\`\`
-
-The command is **idempotent** — re-running against an existing cluster only does work for incomplete steps. It runs five ordered phases:
-
-| # | Phase | What it does |
-|---|---|---|
-| 0 | **Preflight** | Detects missing tools and prints actionable install commands. Verifies \`gh\` is authenticated and the docker daemon is reachable. |
-| 1 | **Secrets** | Generates \`~/.olam/{auth-secret,kg-bearer-token,auth-db-secret,mcp-auth-jwt-secret,memory-bearer-secret}\` if absent (32-byte hex, mode 0600). |
-| 2 | **Colima** (macOS only) | Ensures colima is running; if not, starts it with sensible defaults. Applies \`chmod 666 /var/run/docker.sock\` inside the colima VM (virtiofs mitigation). |
-| 3 | **Cluster** | \`k3d cluster create olam-dev\` with the gh-config bind. Skipped if cluster exists. (Override the name with \`--cluster-name\`.) |
-| 4 | **Observability** | Chains the bundled install scripts: Loki + Promtail, Grafana with port-forward + admin secret, kube-prometheus-stack with recording rules, Kyverno admission policy. |
-| 5 | **Apply manifests + rollout** | Delegates to the existing \`olam upgrade\` flow: namespace, RBAC, secrets, ghcr-pull, host-side docker-socket-proxy, manifest apply, rollout status (per-deployment, 90s timeout), port-forward, \`/health\` verify, audit log. |
-
-Flag reference:
-
-\`\`\`bash
-olam setup --help
-\`\`\`
-
-Common overrides:
-
-- \`-y, --yes\` — auto-affirm every prompt (non-interactive).
-- \`--substrate <docker|kubernetes>\` — force a substrate instead of auto-detecting.
-- \`--cluster-name <name>\` — k3d cluster name to create/use (default: \`olam-dev\`).
-- \`--reuse-cluster <name>\` — reuse an existing reachable kube context instead of provisioning.
-- \`--skip-cluster-create\` — cluster already exists; skip cluster provisioning.
-- \`--skip-doctor\` — skip final health check (useful in CI).
-
----
-
-## 4. Verify the cluster is healthy
-
-\`\`\`bash
-kubectl get pods -n olam
-\`\`\`
-
-Expected — all five \`1/1 Running\`:
-
-\`\`\`
-NAME                                     READY   STATUS    RESTARTS   AGE
-olam-auth-service-...                    1/1     Running   0          ~5m
-olam-host-cp-...                         1/1     Running   0          ~5m
-olam-kg-service-...                      1/1     Running   0          ~5m
-olam-mcp-auth-service-...                1/1     Running   0          ~5m
-olam-memory-service-...                  1/1     Running   0          ~5m
-\`\`\`
-
-If something's off:
-
-\`\`\`bash
-olam doctor                       # checks substrate, cluster, pods, secrets
-olam services status              # k8s-aware status table
-\`\`\`
-
----
-
-## 5. Open Grafana
-
-\`\`\`bash
-kubectl port-forward -n monitoring svc/olam-grafana 3000:80
-open http://localhost:3000
-\`\`\`
-
-User \`admin\`, password from:
-
-\`\`\`bash
-kubectl get secret olam-grafana-admin -n monitoring \\
-  -o jsonpath='{.data.admin-password}' | base64 -d
-\`\`\`
-
-Pre-installed dashboards (under "Olam"):
-
-- **olam-home** — at-a-glance status across all peripherals.
-- **host-cp** — request rate, p50/p95/p99 latency, world counts.
-- **kg-service** — classifier hit rate, classify latency, hook traffic.
-- **request-rate** — per-route HTTP request rate (uses recording rule \`olam:http_requests:rate5m_by_service_route\`).
-
----
-
-## 6. Day-to-day operations
-
-\`\`\`bash
-olam doctor                       # health check across substrate
-olam services status              # peripherals status table (k8s-aware)
-olam services restart <name>      # kubectl rollout restart for one peripheral
-olam services down                # scale all peripherals to 0 replicas
-olam services up                  # scale them back to 1
-\`\`\`
-
-To pick up a new release after \`npm install -g @pleri/olam-cli@latest\`:
-
-\`\`\`bash
-olam upgrade
-\`\`\`
-
-The upgrade flow re-applies all manifests (Kubernetes rolls the deployments to the new image digests); persistent volumes survive.
-
----
-
-## 7. Tear down
-
-\`\`\`bash
-olam implode --dry-run            # preview what will be removed
-olam implode                      # confirmed: cluster + secrets + state
-\`\`\`
-
-\`olam implode\` removes the k3d cluster, the host-side docker-socket-proxy sibling, every container, every secret in \`~/.olam/\`, and the global config. Use it when you want to start completely fresh; otherwise prefer \`olam services down\` or scale to 0.
-
----
-
-## Choosing compose mode instead
-
-To use the lighter 3-container compose path instead:
-
-\`\`\`bash
-curl -fsSL https://olam.bar.dev/install | sh
-olam setup --substrate=docker
-\`\`\`
-
-The CLI is substrate-aware: \`olam setup\`, \`olam services up|down|status|restart\`, \`olam upgrade\`, and \`olam doctor\` all route to the correct backend based on \`~/.olam/config.json\`'s \`host.substrate\` value.
-
-Full compose guide: [\`fresh-machine-setup.md\`](./fresh-machine-setup.md).
-
----
-
-## Architecture quick-ref
-
-\`\`\`
-                    ┌─────────────────────────┐
-                    │   operator's machine    │
-                    │                         │
-                    │  ~/.olam/*-secret  ─────┼──▶ Kubernetes Secrets
-                    │  ~/.config/gh      ─────┼──▶ k3d --volume bind
-                    │                         │
-                    │  ┌─────────────────┐    │
-                    │  │ docker daemon   │    │
-                    │  │                 │    │
-                    │  │  ┌──────────┐   │    │
-                    │  │  │ k3d node │   │    │     ┌─────────────────────────┐
-                    │  │  │  cluster │◀──┼────┼─────│  ghcr.io/pleri/olam-*   │
-                    │  │  │ olam-dev │   │    │     │  (pulled with gh token) │
-                    │  │  └────┬─────┘   │    │     └─────────────────────────┘
-                    │  │       │ TCP     │    │
-                    │  │       ▼ :2375   │    │
-                    │  │  ┌──────────────┴┐   │
-                    │  │  │ docker-socket │   │
-                    │  │  │     proxy     │   │
-                    │  │  │ (sibling      │   │
-                    │  │  │  container)   │   │
-                    │  │  └───────────────┘   │
-                    │  └─────────────────────┘
-                    └─────────────────────────┘
-                                  │
-                                  ▼ k3d nodes via host.k3d.internal:2375
-                          ┌──────────────────────────────────────┐
-                          │           cluster: olam-dev          │
-                          │                                      │
-                          │  namespace: olam                     │
-                          │    olam-host-cp        (1/1 Running) │
-                          │    olam-auth-service   (1/1 Running) │
-                          │    olam-mcp-auth-svc   (1/1 Running) │
-                          │    olam-kg-service     (1/1 Running) │
-                          │    olam-memory-service (1/1 Running) │
-                          │                                      │
-                          │  namespace: monitoring               │
-                          │    olam-grafana                      │
-                          │    prometheus-operated               │
-                          │    loki + promtail                   │
-                          │    kyverno (admission)               │
-                          └──────────────────────────────────────┘
-\`\`\`
-
-Why the sibling docker-socket-proxy? On macOS, colima exposes \`/var/run/docker.sock\` via virtiofs, which blocks unix-socket bind-mounts into k3d pods. The proxy runs as a normal Docker container on the operator's daemon and exposes the same socket over TCP \`:2375\`. Pods reach it through an ExternalName Service. See [\`docs/test-reports/olam-k3d-on-mac-substrate-decision-eli5.md\`](../test-reports/olam-k3d-on-mac-substrate-decision-eli5.md).
-
----
-
-## Common issues
-
-| Symptom | Fix |
-|---|---|
-| \`colima not running\` | \`colima start --cpu 4 --memory 8 --vm-type=vz --mount-type=virtiofs\` |
-| \`permission denied\` on docker socket | \`colima ssh -- sudo chmod 666 /var/run/docker.sock\` |
-| Missing tool errors at preflight | Install manually per the prereq table, then re-run \`olam setup\` |
-| \`helm install\` timeout during observability bootstrap | Set \`OLAM_HELM_TIMEOUT=600s\` (or higher on loaded machines). See [Tuning](#tuning-helm-timeouts-on-resource-constrained-machines) for details. |
-| \`host-cp\` \`CrashLoopBackOff\` with \`inClusterContext is not in the allowlist\` | Image pre-dates v0.1.161 — \`npm install -g @pleri/olam-cli@latest && olam upgrade\` |
-| \`memory-service\` \`CrashLoopBackOff\` with \`port 3111 is already in use\` | Image pre-dates v0.1.163 — \`npm install -g @pleri/olam-cli@latest && olam upgrade\` |
-| \`imagePullBackOff\` from \`ghcr.io/pleri/olam-*\` | The bootstrap creates \`ghcr-pull\` from \`gh auth token\`; re-run \`olam setup\` after \`gh auth login\` |
-| Grafana dashboards missing | \`kubectl rollout restart deploy/olam-grafana -n monitoring\` |
-| host-cp can't reach docker | \`docker ps \\| grep docker-socket-proxy\` — restart with \`olam setup --skip-cluster-create\` to re-run only the proxy + manifest-apply steps |
-| \`helm install\` fails with \`Error: context deadline exceeded\` during observability bootstrap (grafana / loki / kube-prometheus-stack / kyverno) | The Colima VM is sharing CPU/memory with too many other containers. Bump the helm timeout via \`OLAM_HELM_TIMEOUT=900s olam setup\` (default is \`600s\`). On very loaded machines, \`1200s\` is reasonable. Applies to every \`helm install\` step in the observability chain. |
-
-### Tuning helm timeouts on resource-constrained machines
-
-Every observability \`helm install\` (grafana, loki, promtail, kube-prometheus-stack, kyverno) reads \`OLAM_HELM_TIMEOUT\` (default \`600s\`). When the Colima VM is sharing resources with a heavy local workload, charts can take longer than the default to converge — bump the env var instead of editing scripts:
-
-\`\`\`bash
-OLAM_HELM_TIMEOUT=900s olam setup           # bootstrap with longer timeout
-OLAM_HELM_TIMEOUT=1200s olam setup          # very loaded machines
-\`\`\`
-
-CI Linux runners run unmodified at \`600s\` (dedicated resources). The knob exists for macOS-Colima hosts that share a VM with other docker workloads.
-
-### Tuning Prometheus scrape/discovery waits
-
-The Phase C E2E scripts in \`scripts/e2e/\` poll Prometheus for synthetic-target discovery (\`TARGET_DISCOVERY_TIMEOUT\`, default 240s — \`cardinality-drop.sh\`, \`kyverno-cardinality-mutate.sh\`, \`dashboards-have-data.sh\`) and then sleep for recording-rule evaluation (\`SCRAPE_WAIT\`, default 70s — \`dashboards-have-data.sh\`). Both default values cover ≥2 rule-evaluation cycles at the 30s rule interval against a 15s scrape interval. Override on very slow runners:
-
-\`\`\`bash
-OLAM_PROM_DISCOVERY_TIMEOUT=300 OLAM_PROM_SCRAPE_WAIT=120 npm run test:ingress-integration
-\`\`\`
-
-### Troubleshooting port-forwards
-
-**Problem:** connections to a port-forward (e.g. \`localhost:19001\` for host-cp, \`localhost:3000\` for Grafana) suddenly fail with "connection refused".
-
-**Why:** kubectl port-forwards die when:
-- The terminal that started them exits
-- k3d restarts or the cluster reboots
-- The underlying pod crashes or is redeployed
-- The local kube context changes
-
-**Diagnose:**
-\`\`\`bash
-ps aux | grep "kubectl port-forward"
-\`\`\`
-
-If nothing shows up, the port-forward is dead and needs to be re-established.
-
-**Fix:**
-
-Option 1 — re-establish all port-forwards at once:
-\`\`\`bash
-olam services up
-\`\`\`
-
-Option 2 — manually restart the port-forward (canonical command from the setup doc):
-\`\`\`bash
-kubectl port-forward -n olam svc/host-cp 19001:19001
-\`\`\`
-
-Use \`olam services status\` to see which services are running and which port each binds to locally.
-
-When everything else fails, tear down and re-create:
-
-\`\`\`bash
-olam implode
-olam setup
-\`\`\`
-
-\`olam implode\` removes everything; \`olam setup\` re-creates from scratch.
-
----
-
-## What to read next
-
-- \`olam --help\`, \`olam setup --help\` — the canonical CLI surface.
-- [\`docs/architecture/peripheral-services-on-k3s.md\`](../architecture/peripheral-services-on-k3s.md) — design doc for the k3s peripheral architecture.
-- [\`docs/test-reports/olam-k3d-on-mac-substrate-decision-eli5.md\`](../test-reports/olam-k3d-on-mac-substrate-decision-eli5.md) — why the docker-socket-proxy sits where it sits.
-
----
-
-## 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 spec (port-validates then delegates to WorldManager.createWorld)
-- \`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 classify\` — Route a query through the remote edge classifier (POST /v1/classify on the proxy Worker)
-- \`olam clean\` — Reap orphaned world filesystem state
-- \`olam completion\` — Emit a 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 its resources
-- \`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). LOCAL ONLY — no cloud equivalent yet (see OQ7 in docs/plans/cloud-only-vault/README.md).
-- \`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. LOCAL ONLY — no cloud equivalent yet (see OQ7 in docs/plans/cloud-only-vault/README.md).
-- \`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 graph\` — Query the cross-repo graph: locate a symbol, its relationships, or browse a repo (POST /v1/graph)
-- \`olam hermes\` — Hermes integration commands
-- \`olam host-cp\` — Manage the Olam host control plane container
-- \`olam implode\` — Destroy ALL local olam install and configs (dry-run by default)
-- \`olam init\` — Initialize olam in the current project or globally
-- \`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 install-model-router\` — Deploy the model-router.py UserPromptSubmit hook script to ~/.claude/hooks/ (idempotent; auto-run by
-- \`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. Defaults to the cloud auth-worker (Phase B). Pass --local to read the legacy ~/.olam/auth-data/accounts.json (emits deprecation warning).
-- \`olam list-anthropic-tokens\` — List Anthropic proxy tokens from the remote auth-worker (g4)
-- \`olam login\` — Log into the cloud auth-worker by default (Phase B); use --local to opt into the legacy local auth-service container PKCE flow.
-- \`olam logout\` — Remove an account from the auth container
-- \`olam logs\` — Stream application logs from a world (engine-agnostic)
-- \`olam migrate\` — Migrate local ~/.olam/auth-data/accounts.json to the cloud auth-worker.
-- \`olam migrate-hooks-back\` — Reverse olam-meta hook injection by restoring ~/.claude/settings.json from a B5 snapshot
-- \`olam migrate-to-remote\` — (deprecated) renamed to
-- \`olam mirror\` — cloud-kg-mirror operations (build via CF Worker, classify at edge)
-- \`olam observe\` — redirect to
-- \`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). LOCAL ONLY — no cloud equivalent yet (see OQ7 in docs/plans/cloud-only-vault/README.md).
-- \`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\` — Re-enter a world by PR number, URL, or branch name
-- \`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 (up/down/status/logs)
-- \`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 set-prefix-target\` — Restrict prefix renaming to canonical names matching the given glob patterns (only * wildcard supported).
-- \`olam setup\` — Fresh-host onboarding wizard (k3d cluster + services, idempotent)
-- \`olam setup-linux-gate-status\` — Check whether the Linux platform expansion gate has been triggered
-- \`olam setup-metrics\` — Query trust-audit-log for 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 tls-install\` — Provision a locally-trusted TLS cert (mkcert) for the Traefik IngressRoute
-- \`olam uninstall\` — Remove /100x: 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 unset-prefix-target\` — Remove the prefix-target override from a registered skill source (reverts to default: all canonical names 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\` — Parallel Claude Code session in a new tmux window + isolated worktree
-`;
-//# sourceMappingURL=knowledge-pack.generated.js.map