@pleri/olam-cli 0.1.186 → 0.1.195

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

@@ -173,20 +173,16 @@ 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
 \`\`\`
 
-That's it. The installer puts \`@pleri/olam-cli\` on your PATH (requires Node.js ≥ 20 and npm). \`olam setup\` installs k3d (if absent), creates a local Kubernetes cluster named \`olam-dev\`, and brings up the full peripheral stack (host-cp, auth-service, mcp-auth-service, kg-service, memory-service). Works on macOS and Linux. No source checkout required.
-
-The setup wizard is **idempotent** — re-running skips steps that are already complete.
-
-After setup, every world is one call:
-
-\`\`\`bash
-olam create --name my-world --task "audit the auth module for SSRF"
-\`\`\`
+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).
@@ -204,6 +200,16 @@ This runs three host containers (auth, mcp-auth, kg-service) via docker compose
 
 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
@@ -783,6 +789,7 @@ Source: \`docs/ONBOARDING.md\`
 
 - **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
 
@@ -793,7 +800,7 @@ Source: \`docs/ONBOARDING.md\`
 No source checkout required — the CLI publishes to npm:
 
 \`\`\`bash
-curl -fsSL https://olam.bar.dev/install | sh   # installs @pleri/olam-cli on PATH
+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
 \`\`\`
 
@@ -804,7 +811,15 @@ mcp-auth-service, kg-service, and memory-service. Pass
 no cluster). Full guide:
 [\`docs/onboarding/k3s-mode-setup.md\`](onboarding/k3s-mode-setup.md).
 
-## 2. Register the MCP server (1 minute)
+## 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
@@ -817,7 +832,7 @@ worlds directly. Core tools: \`olam_create\`, \`olam_dispatch\`,
 \`olam_enter\`, \`olam_crystallize\`, \`olam_pr_*\`. Restart Claude Code and
 verify with \`claude mcp list\` (look for \`olam\`).
 
-## 3. Configure your repos (2 minutes)
+## 4. Configure your repos (2 minutes)
 
 Point Olam at the repos a world should clone. Use the interactive
 wizard:
@@ -832,7 +847,29 @@ world-runner tier (\`docker\` | \`cloudflare\` | \`cloudflare-isolate\`). See
 [\`docs/architecture/config-spec.md\`](architecture/config-spec.md) for
 the full schema.
 
-## 4. Create your first world (2 minutes)
+## 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:
 
@@ -844,9 +881,9 @@ Claude will:
 1. Create a Docker container (or CF Sandbox) with your repo cloned
 2. Set up git worktrees for isolation
 3. Boot the in-world Claude session and auto-dispatch the task
-4. Return the Host CP dashboard URL (\`http://127.0.0.1:19000\`)
+4. Return the Host CP dashboard URL (\`http://127.0.0.1:19001\`)
 
-## 5. Dispatch a task (1 minute)
+## 6. Dispatch a task (1 minute)
 
 \`\`\`
 Dispatch to the world: investigate and fix the session timeout issue
@@ -854,7 +891,7 @@ Dispatch to the world: investigate and fix the session timeout issue
 
 Claude Code runs autonomously inside the world. Every tool call, every decision, every exploration is captured as a thought node.
 
-## 6. Watch it work (ongoing)
+## 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)
@@ -869,7 +906,7 @@ Claude Code runs autonomously inside the world. Every tool call, every decision,
 What is the world thinking right now?
 \`\`\`
 
-## 7. Clean up
+## 8. Clean up
 
 \`\`\`
 Crystallize and destroy the world
@@ -891,7 +928,7 @@ after \`olam setup\`):
 \`\`\`bash
 olam create --name login-fix --repos my-project --task "Fix session timeout"
 olam dispatch login-fix "investigate and fix the session timeout"
-olam observe login-fix             # placeholder; for now attach via the world terminal
+olam 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
@@ -929,11 +966,39 @@ refresh token never leaves the service.
 
 | 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
 
@@ -1088,16 +1153,18 @@ olam skills source list
 
 ---
 
-## 5. Start the memory-bridge
+## 5. Start the memory service (Docker container)
 
-The memory-bridge is a host process that serves \`127.0.0.1:3111/agentmemory/livez\`. When it's running, \`olam skills sync\` will inject the olam-meta-memory-recall + olam-meta-memory-classify hook blocks into \`~/.claude/settings.json\`. When it's NOT running, the strip half of the auto-migration still fires but no olam-meta blocks land — meaning operator gets no recall/classify behavior.
+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 host process; polls livez until ready
-olam memory status                # → pid + livez + secret-set check
+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
@@ -1225,6 +1292,7 @@ If the recall hook doesn't fire, run \`olam memory status\` to confirm the bridg
 ## 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\`).
@@ -1251,6 +1319,345 @@ npm uninstall -g @pleri/olam-cli
 
 ---
 
+## 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\`
@@ -1857,13 +2264,13 @@ Top-level commands (run \`olam <command> --help\` for flags and subcommands):
 - \`olam bootstrap\` — One-shot wiring of a fresh Hermes install to olam (MCP + KG hook + skill mirror)
 - \`olam build\` — Build pristine KG for a workspace (default: current dir). Routes through olam-kg-service /build endpoint. Use --pending to drain the pending queue.
 - \`olam check-ports\` — Check if runbook ports are available
-- \`olam clean\` — Reap orphan world filesystem state under ~/.olam/worlds/
-- \`olam completion\` — Emit a POSIX shell completion script for zsh or bash.
+- \`olam 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 resources (accepts world ID or name)
+- \`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)
@@ -1876,8 +2283,8 @@ Top-level commands (run \`olam <command> --help\` for flags and subcommands):
 - \`olam get\` — Print the active substrate
 - \`olam hermes\` — Hermes integration commands
 - \`olam host-cp\` — Manage the Olam host control plane container
-- \`olam implode\` — Destroy ALL local olam install + configs (containers, images, volumes, ~/.olam/, npm package). Default is dry-run.
-- \`olam init\` — Initialize olam in the current project
+- \`olam 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
@@ -1892,6 +2299,7 @@ Top-level commands (run \`olam <command> --help\` for flags and subcommands):
 - \`olam logs\` — Stream application logs from a world (engine-agnostic)
 - \`olam migrate-hooks-back\` — Reverse olam-meta hook injection by restoring ~/.claude/settings.json from a B5 snapshot
 - \`olam migrate-to-remote\` — Print guidance for re-authenticating local credentials against the remote auth-worker (v1: no auto-migration of secrets)
+- \`olam mirror\` — cloud-kg-mirror operations (build via CF Worker, classify at edge)
 - \`olam observe\` — Stream thoughts from a world (coming soon)
 - \`olam onboard\` — Fresh-install umbrella: register + clone + install SessionStart hook + first sync, in one verb
 - \`olam path\` — Print the absolute path to ~/.olam/keys.yaml
@@ -1909,18 +2317,18 @@ Top-level commands (run \`olam <command> --help\` for flags and subcommands):
 - \`olam repos\` — Manage the global repo registry
 - \`olam restart\` — Restart a world container (auto-builds agent-stream bundle when stale)
 - \`olam restore\` — Move a shadow-backup file back to its original path
-- \`olam resume\` — Resume a world by PR number, URL, or branch — finds the world that opened the PR and enters it.
+- \`olam 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. Substrate-aware: compose uses docker; kubernetes uses kubectl.
+- \`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 setup\` — Fresh-host onboarding wizard. Default substrate=kubernetes (k3d on all platforms):
-- \`olam setup-linux-gate-status\` — Detect whether the Linux platform expansion gate has been triggered.
-- \`olam setup-metrics\` — Query trust-audit-log for olam setup dogfood statistics.
+- \`olam 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
@@ -1931,6 +2339,7 @@ Top-level commands (run \`olam <command> --help\` for flags and subcommands):
 - \`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 /10x: chain skill symlinks from ~/.claude/skills (preserves user-authored skills + non-chain skill sources)
 - \`olam uninstall-hook\` — Remove kg-service PreToolUse hook from .claude/settings.json (sentinel-matched; surgical)
 - \`olam unset-prefix\` — Remove the deploy prefix from a registered skill source (reverts to canonical deploy names)
@@ -1942,6 +2351,6 @@ Top-level commands (run \`olam <command> --help\` for flags and subcommands):
 - \`olam watch\` — Run graphify --watch against a workspace, keeping its pristine KG fresh
 - \`olam workspace\` — Manage the named catalog of repo bundles that worlds instantiate from
 - \`olam world\` — World management subcommands
-- \`olam yolo\` — Dispatch a parallel Claude Code session in a new tmux window + isolated git worktree
+- \`olam yolo\` — Parallel Claude Code session in a new tmux window + isolated worktree
 `;
 //# sourceMappingURL=knowledge-pack.generated.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"knowledge-pack.generated.js","sourceRoot":"","sources":["../../src/ask/knowledge-pack.generated.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAoB;AAEpB,MAAM,CAAC,MAAM,cAAc,GAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAk5DrC,CAAC"}
+{"version":3,"file":"knowledge-pack.generated.js","sourceRoot":"","sources":["../../src/ask/knowledge-pack.generated.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAoB;AAEpB,MAAM,CAAC,MAAM,cAAc,GAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2yErC,CAAC"}