loki-mode 11.3.0 → 11.3.1

package/docs/INSTALLATION.md

@@ -1,1132 +1,154 @@
 # Loki Mode Installation Guide
 
-The flagship product of [Autonomi](https://www.autonomi.dev/). Loki Mode is a spec-driven autonomous builder with a built-in trust layer that takes any spec to a deployed product and verifies completion with evidence (quality gates plus a completion council), not just a "done" claim. Complete installation instructions for all platforms and use cases.
+Loki Mode, by [Autonomi](https://www.autonomi.dev/), turns a spec or an issue into a verified pull request with a receipt you can check. This page covers installing it, a first run, and the options around it.
 
-**Version:** v11.3.0
+**Version:** v11.3.1
 
-**Engine note:** `loki "<task>"`, `loki owner/repo#N` and `loki quick` run the Loki 10 engine. `loki start` still routes to the legacy engine, which is being removed (planned work resumes 2026-10-07); prefer `loki owner/repo#N`. See [docs/v10/GUIDE.md](v10/GUIDE.md).
+**Engine note:** `loki "<task>"`, `loki owner/repo#N` and `loki quick` run the Loki 10 engine. `loki start` still routes to the older engine, which is being removed; prefer `loki owner/repo#N`. See the [user guide](v10/GUIDE.md).
 
 ---
 
-## What's New in v7.5.x
+## Install
 
-### Phase 1 RARV-C closure (shipped v7.5.0, default-on as of v7.5.3)
-Phase 1 closure features now activate automatically when you run
-`loki start` -- no env flags required. Power users can opt out by
-setting any flag to `0`.
+Pick one. All three install the same `loki` CLI.
 
-- `findings_injector.ts` -- structured per-finding records (severity, file,
-  line, reviewer) injected into the next iteration's prompt instead of bare
-  comma-separated tokens. Default: ON. Opt out with `LOKI_INJECT_FINDINGS=0`.
-- `counter_evidence.ts` -- override council. Drop a
-  `.loki/state/counter-evidence-<iter>.json` to dispute reviewer findings;
-  approval lifts the BLOCK. Default: ON. Opt out with `LOKI_OVERRIDE_COUNCIL=0`.
-- `learnings_writer.ts` -- automatic structured learnings to
-  `.loki/state/relevant-learnings.json` on every code_review failure.
-  Default: ON. Opt out with `LOKI_AUTO_LEARNINGS=0`.
-- `escalation_handoff.ts` -- structured human-handoff doc to
-  `.loki/escalations/handoff-*.md` before PAUSE. Default: ON. Opt out
-  with `LOKI_HANDOFF_MD=0`.
-- `loki status` shows a "Phase 1 artifacts" section when findings,
-  learnings, or escalations exist (added v7.5.5; see the `phase1` block
-  in `loki status --json`).
-- See `skills/quality-gates.md` for full schema and reachability notes.
-
-### Output-token compressor (caveman, default-on, Claude-only)
-Loki integrates [caveman](https://github.com/JuliusBrussee/caveman), an optional
-Claude Code skill that compresses the model's OUTPUT tokens only (keeping all
-technical substance). It activates on free-form generation (the main RARV dev
-loop) and is HARD-SUPPRESSED on every trust-gate subcall (council votes, code
-review verdict, evidence-related parses) so determinism is never affected.
-- Claude-provider-only; runs are byte-identical on Cline / Codex / Aider / opencode.
-- Default on; opt out with `LOKI_CAVEMAN=0`.
-- Level: `LOKI_CAVEMAN_LEVEL` (default `full`; also `lite`, `ultra`, `wenyan*`).
-- Pinned + vendor-less: `LOKI_CAVEMAN_VERSION` (default `1.9.0`); Loki bootstraps
-  the pinned version on demand (opt out `LOKI_CAVEMAN_AUTO_BOOTSTRAP=0`).
-- Savings are output-token-only and bounded; Loki never quotes a dollar figure.
-- See `skills/quality-gates.md` (Output-token compressor) for details.
-
-### Earlier highlights still in scope
-- Bash-to-Bun runtime migration in progress (see `UPGRADING.md`)
-- Provider-agnostic runtime: Claude (full), Cline, Codex, Aider, opencode (no vendor lock-in)
-- Memory system (episodic / semantic / procedural)
-- ChromaDB semantic code search via MCP
-
----
-
-## Table of Contents
-
-- [Bun (Recommended)](#bun-recommended)
-- [npm](#npm)
-- [Homebrew](#homebrew)
-- [Quick Start](#quick-start)
-- [Verify Installation](#verify-installation)
-- [Other Methods](#other-methods)
-- [VS Code Extension (Deprecated)](#vs-code-extension-deprecated)
-- [Sandbox Mode](#sandbox-mode)
-- [Multi-Provider Support](#multi-provider-support)
-- [Environment Variables](#environment-variables)
-- [Claude Code (CLI)](#claude-code-cli)
-- [Claude.ai (Web)](#claudeai-web)
-- [Anthropic API Console](#anthropic-api-console)
-- [Ports](#ports)
-- [Shell Completions](#shell-completions)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## Bun (Recommended)
-
-```bash
-bun install -g loki-mode
-```
-
-Installs the `loki` CLI. Bun is the recommended path: the `loki` shim runs the
-faster TypeScript runtime when `bun` is on `PATH`, and the stable bash engine
-(the autonomous loop, quality gates, and completion council) runs underneath on
-every route, so you lose nothing by choosing Bun. Run `loki setup-skill` once
-after install to create the per-provider skill symlinks (Claude Code, Codex CLI).
-
-**Prerequisites:** Bun 1.3+ (`curl -fsSL https://bun.sh/install | bash`, or
-`brew install oven-sh/bun/bun`). No separate Node install is required.
-
-**Update:** `bun update -g loki-mode`
-
-**Uninstall:** `bun remove -g loki-mode`
-
----
-
-## npm
-
-```bash
-npm install -g loki-mode
-```
-
-A fully supported alternative when you prefer npm or do not have Bun. As of
-v7.4.12 there is no postinstall step; run `loki setup-skill` once after install
-to create the per-provider skill symlinks (Claude Code, Codex CLI). The `loki`
-shim auto-routes read-only commands to the Bun runtime when `bun` is on `PATH`
-and falls back to the bash CLI otherwise (the core autonomous engine is the
-same on both routes).
-
-**Prerequisites:** Node.js 20+ (Node 22 LTS recommended; it is the primary
-tested/CI target). Bun 1.3+ optional but recommended for the faster routed
-commands and forward-compat with v8.0.0.
-
-**What it does:**
-- Installs the `loki` CLI binary to your PATH (`bin/loki` shim)
-- Subsequent `loki setup-skill` creates symlinks at `~/.claude/skills/loki-mode`, `~/.codex/skills/loki-mode`
-
-**Anonymous telemetry is ON by default for an individual interactive install**
-and auto-off in CI, non-interactive sessions, and when `LOKI_ENTERPRISE=true` or
-`LOKI_AIRGAP=true` is set. It is disclosed once on first use. Turn it off with
-`loki telemetry off`; `loki doctor --airgap` shows its current state. To make
-opting in impossible across a fleet, bake an opt-out into your base image
-(opt-out always wins):
 ```bash
-# Hard-disable everywhere (belt and suspenders; opt-out always wins):
-LOKI_TELEMETRY_DISABLED=true npm install -g loki-mode
-# Or set DO_NOT_TRACK=1
+npm install -g loki-mode                          # Node.js 20+ (Node 22 LTS is the CI target)
+bun install -g loki-mode                          # Bun 1.3+
+brew tap asklokesh/tap && brew install loki-mode  # Homebrew
 ```
-See [PRIVACY.md](./PRIVACY.md) for the exact data sent and the full opt-in /
-opt-out model.
 
-**Update:** `npm update -g loki-mode`
-
-**Uninstall:** `npm uninstall -g loki-mode`
-
----
+The Loki 10 engine runs on Bun. The npm package bundles a Bun binary for macOS and Linux (x64 and arm64) as an optional dependency, so a plain npm install needs nothing else. With Homebrew, install Bun too if you do not have it: `brew install oven-sh/bun/bun`.
 
-## Slim install (no bundled bun)
-
-```bash
-npm install -g loki-mode --omit=optional
-```
-
-Install Loki Mode without the bundled bun binary. This reduces the package size by 62-86 MB per platform but requires you to manage the Loki 10 engine dependency separately.
-
-**What it skips:**
-- `bun` (62-86 MB binary for darwin-aarch64, darwin-x64, linux-aarch64, linux-x64)
-- Claude Agent SDK packages
-- OpenTelemetry instrumentation packages
-
-**What happens:**
-- Loki 10 requires Bun. Each `loki` command prints an error on stderr if Bun is not found: "loki: the Loki 10 engine cannot run on this machine: no working bun (none on PATH, and the bundled bun for darwin-aarch64 is missing). To fix: install bun from https://bun.sh, or reinstall loki-mode without --omit=optional."
-
-**To restore Loki access:**
-- Install bun: `curl -fsSL https://bun.sh/install | bash` or `brew install oven-sh/bun/bun`
-- Or reinstall loki-mode without the flag: `npm install -g loki-mode`
-
----
-
-## Homebrew
-
-```bash
-brew tap asklokesh/tap && brew install loki-mode
-```
-
-Installs the `loki` CLI. Loki 10 requires Bun; if bun is not installed, run `brew install oven-sh/bun/bun`. Without bun, each command exits 1 with an error message.
-
-To also install the skill for interactive use with all providers:
+The npm postinstall step repoints any stale skill links and installs shell completions (skipped in CI or with `LOKI_NO_COMPLETIONS=1`). It never fails the install. To install the Loki skill into each detected provider CLI (`~/.claude/skills/`, `~/.codex/skills/`, ...), run:
 
 ```bash
 loki setup-skill
 ```
 
-**Update:** `brew upgrade loki-mode`
-
-**Uninstall:** `brew uninstall loki-mode`
-
----
-
-## PyPI / Python SDK
-
-**The `loki` CLI is NOT available via `pip install loki-mode`.** PyPI hosts only the
-Python REST client SDK at `loki-mode-sdk` (v7.4.18+). The dashboard, MCP server,
-and orchestrator components ship via npm, Docker, and Homebrew only.
-
-```bash
-# Install the Python REST client only
-pip install loki-mode-sdk
-
-# Install the full CLI (recommended)
-bun install -g loki-mode  # or: npm install -g loki-mode, or: brew tap asklokesh/tap && brew install loki-mode
-```
-
-The naming asymmetry (`loki-mode` on npm vs `loki-mode-sdk` on PyPI) is
-intentional: PyPI's `loki-mode` namespace is reserved for a future server
-package, while `loki-mode-sdk` is the thin client.
-
----
-
-## Quick Start
-
-New here? `loki quickstart` (v7.29.0) walks you through your first build in
-four questions (setup check, one-line idea, template pick, plan review with
-a real cost estimate before anything is spent). Pressing Enter at every step
-builds the sample Todo app.
-
-```bash
-loki quickstart
-```
-
-For a fully specified first build, provide the idea, an optional exact shipped
-starter template, and explicit consent:
-
-```bash
-loki quickstart "an internal reporting workspace" --template dashboard --yes
-```
-
-Use `--dry-run` instead of `--yes` to preview the same template and plan without
-provider discovery, file writes, or execution; add `--json` for one versioned
-machine-readable object.
-
-For a local pipeline, pass that object to `--from-preview - --yes`. Loki accepts
-at most 1 MiB from non-terminal stdin, revalidates the schema, and recomputes the
-current estimate before the explicitly consented build starts:
-
-```bash
-loki quickstart "an internal reporting workspace" --template dashboard --dry-run --json \
-  | loki quickstart --from-preview - --yes
-```
-
-Omit `--yes`, pipe malformed or oversized JSON, or use `-` from a terminal and
-the continuation exits `2` before provider discovery, PRD writes, or execution.
-
-Drop a spec -- any artifact that describes what you want built -- and Loki
-Mode takes it from spec to deployed app. Specs can be a markdown PRD, a
-GitHub issue URL, or a YAML feature description.
+### Slim install (no bundled Bun)
 
 ```bash
-# CLI mode (works with any provider) -- spec as markdown PRD
-loki start ./spec.md
-loki start ./spec.md --provider codex
-loki start ./spec.md --provider cline
-
-# Spec as a GitHub issue -- pass it positionally, it is auto-detected
-loki start https://github.com/owner/repo/issues/42
-loki start owner/repo#42
-
-# Spec as a YAML feature description
-loki start ./feature.yaml
-
-# Interactive mode (inside your coding agent)
-claude --dangerously-skip-permissions
-# Then say: "Loki Mode with spec at ./my-spec.md"
-```
-
----
-
-## Verify Installation
-
-```bash
-loki --version    # Should print the current version
-loki doctor       # Check skill symlinks, providers, and system prerequisites
-```
-
----
-
-## Configuration file
-
-Instead of exporting many `LOKI_*` env vars, point `loki start` at a config file with `--config <path>` (aliases: `--env-file`, `--vars`), or set `LOKI_CONFIG_FILE`. The format is detected from the extension or content: `.yaml`/`.yml`, `.json`, or `.env` (flat `LOKI_*=value` lines). Values resolve by precedence: a CLI flag beats an ambient env var, which beats the `--config` file, which beats built-in defaults. Never inline a secret; reference an env var with `${VAR}` and the loader expands it at load time (an unset reference is skipped with a warning, and a raw-looking secret literal is flagged and rejected by `loki config validate`). Run `loki config example` to generate an annotated starter.
-
-```bash
-# config.yaml
-dashboard:
-  port: 9000
-github:
-  token: ${GITHUB_TOKEN}   # expanded from the environment, never stored inline
-
-loki start --config config.yaml ./prd.md
-loki config validate config.yaml    # check refs and reject raw secrets before a run
-```
-
----
-
-## Other Methods
-
-Git clone and Docker installation methods are also available. See
-[alternative-installations.md](alternative-installations.md) for details and
-trade-offs.
-
----
-
-## VS Code Extension (Deprecated)
-
-> **DEPRECATED as of v7.2.0.** The Loki Mode VS Code extension is no longer
-> maintained. Use the Control Plane (`loki dashboard`) instead.
->
-> The marketplace listing remains for users on v7.2.0 and earlier but will
-> not receive further updates. The `vscode-extension/` source remains in the
-> repository for contributors who want to build the extension locally; it is
-> no longer published to the VS Code Marketplace and is not included in npm
-> tarballs.
-
-### Recommended replacement: the dashboard
-
-```bash
-loki dashboard
-# Opens the Control Plane (default http://127.0.0.1:47821).
-```
-
-The dashboard provides session monitoring, task views, the completion
-council, log streaming, and the managed-memory panel -- the same surface
-the extension exposed, plus everything added since v7.2.0.
-
----
-
-## Sandbox Mode
-
-Run Loki Mode in an isolated Docker container for enhanced security.
-
-### Features
-
-- **Docker isolation**: Complete process isolation from host system
-- **Seccomp profiles**: Restricted system calls
-- **Resource limits**: CPU, memory, and process limits enforced
-- **Dropped capabilities**: Minimal Linux capabilities
-- **Read-only rootfs**: Immutable container filesystem
-- **Git worktree fallback**: Automatic fallback when Docker unavailable
-
-### Usage
-
-```bash
-# Run in sandbox mode (spec can be PRD, issue link, or YAML)
-./autonomy/sandbox.sh ./my-spec.md
-
-# With provider selection
-./autonomy/sandbox.sh --provider codex ./my-spec.md
+npm install -g loki-mode --omit=optional
 ```
 
-### Security Controls
+Skips the bundled Bun binary (62 to 86 MB per platform), the Claude Agent SDK and the OpenTelemetry packages. You then need Bun on `PATH` (`curl -fsSL https://bun.sh/install | bash`); without it every command exits with an error that says how to fix it.
 
-#### Prompt Injection Protection
+### Python SDK
 
-By default, prompt injection is **disabled** for enterprise safety:
+`pip install loki-mode-sdk` installs only the Python REST client. The `loki` CLI is not on PyPI.
 
-```bash
-# Default: prompt injection disabled
-./autonomy/run.sh ./my-spec.md
-
-# Opt-in to enable prompt injection
-LOKI_PROMPT_INJECTION=true ./autonomy/run.sh ./my-spec.md
-```
-
-#### Human Input Security
-
-The `HUMAN_INPUT.md` file has security controls:
-- **Symlink protection**: Symlinks are rejected
-- **Size limit**: Maximum 1MB file size
-- **Path validation**: Must be within `.loki/` directory
-
-### When to Use Sandbox Mode
+### Docker and other methods
 
-- Running untrusted spec files (PRD, issue export, YAML)
-- Enterprise environments with strict security requirements
-- Automated CI/CD pipelines
-- Multi-tenant deployments
+See [alternative-installations.md](alternative-installations.md) for Docker, the GitHub Action and a git clone install.
 
 ---
 
-## Multi-Provider Support
-
-Loki Mode supports five active providers across three capability modes, plus historical/upcoming entries. Pick by capability + cost.
-
-### Supported Providers
-
-| Provider | Status | Tier | Notes |
-|----------|--------|------|-------|
-| `claude` | Active | Tier 1 (full) | Default. All features incl. Task subagents, MCP, council. |
-| `cline`  | Active | Tier 2 | Full feature set; small models (<13B) may fail tool-use. |
-| `codex`  | Active | Tier 3 (degraded) | Sequential only, no Task tool; aligned with `@openai/codex` v0.125+. |
-| `aider`  | Active | Tier 3 (degraded) | Sequential only; `ollama_chat/<model>` works for local models. |
-| `opencode` | Active | Sequential | Model-agnostic route (`providers/opencode.sh`); autonomous flag `--auto`. Install: `npm install -g opencode-ai`. |
-| `gemini` | REMOVED v7.5.18 | -- | Upstream Gemini CLI deprecated by Google. Runtime removed; `LOKI_PROVIDER=gemini` exits with a migration message. |
-
-When `LOKI_PROVIDER` is unset, Loki auto-detects the first installed provider in
-this order: `claude`, `cline`, `codex`, `aider`, `opencode`
-(`providers/loader.sh:191`). An explicit `LOKI_PROVIDER` always wins and is
-never silently substituted.
-
-### Configuration
-
-#### Environment Variable
-
-Set the `LOKI_PROVIDER` environment variable to select your provider:
+## Verify the install
 
 ```bash
-# Use Claude (default)
-export LOKI_PROVIDER=claude
-
-# Use OpenAI Codex
-export LOKI_PROVIDER=codex
-
-# Use Cline
-export LOKI_PROVIDER=cline
+loki --version    # prints the installed version
+loki doctor       # checks providers, Bun, skill links and prerequisites
 ```
 
-#### CLI Flag
-
-Use the `--provider` flag when invoking Loki Mode:
-
-```bash
-# Use Claude (default)
-loki start ./my-spec.md --provider claude
-
-# Use OpenAI Codex
-loki start ./my-spec.md --provider codex
-
-# Use Cline
-loki start ./my-spec.md --provider cline
-```
-
-#### Docker
-
-Docker is where sandboxes and runs happen. The easiest way to run Loki in a
-container is the `loki docker` host wrapper, which gives you the full local
-experience (including `.loki/` state, resume, and continuity) in one command.
-The raw `docker run` and `docker compose` methods below remain as alternatives.
-
-##### loki docker (easiest)
-
-If you have loki installed on the host (npm/brew/bun) plus Docker, `loki docker`
-runs any loki command inside the published `asklokesh/loki-mode` image with zero
-config:
-
-```bash
-loki docker start owner/repo#17      # work a GitHub issue or PR in Docker (primary path)
-loki docker start prd.md             # full local experience in Docker
-loki docker status                   # any loki command works
-loki docker --dry-run start prd.md   # print the docker command, do not run
-```
-
-On macOS, pass your GitHub login for PRs with
-`GH_TOKEN=$(gh auth token) loki docker start owner/repo#17`.
-
-It bind-mounts the current folder to `/workspace`, so `.loki/` state (memory,
-session, queue, checkpoints) persists on the host and resume and continuity
-behave exactly like the local `loki` CLI. Auth is auto-detected:
-`ANTHROPIC_API_KEY` if set, else your host's existing Claude Code login
-(Max/Pro subscribers need no API key), else an honest error with guidance. It
-also forwards `~/.gitconfig` and `~/.config/gh` (read-only) plus
-`GITHUB_TOKEN`/`GH_TOKEN` if set, so commits and PRs work like local, and
-exposes the API on port 57374. Use `--image IMG` to override the image.
-
-`loki docker` is a thin host wrapper around the image; it requires loki and
-Docker installed on the host.
-
-Multi-repo + unified dashboard: you can run `loki docker start` in several
-different repos at once, exactly like the host CLI. Each repo gets its own
-container (deterministic name `loki-<hash-of-path>`) and its own bind-mounted
-`.loki/` state. Every `loki docker` project registers with the host dashboard,
-so running `loki dashboard` on the host (the Control Plane) shows ALL your projects in one unified
-view, whether they run via local `loki start` or via `loki docker start`. Builds
-run with the dashboard off by default (so concurrent runs do not collide on port
-57374); use the host `loki dashboard`, or `loki docker start --api` for a single
-containerized run's UI.
-
-##### docker run
-
-As of v7.45.0 the image ships the Claude Code CLI, so the default `claude`
-provider works inside the container. Provide auth with your Anthropic API key:
-
-```bash
-# Run Loki Mode in Docker (Claude provider, API-key auth)
-docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
-  -v $(pwd):/workspace -w /workspace \
-  asklokesh/loki-mode:latest start ./my-spec.md
-```
-
-##### docker compose + .env (no host install)
-
-If you prefer not to install loki on the host, the repo ships a
-`docker-compose.yml` with `env_file: .env`. Copy the example,
-set your key once, then run without retyping long `-e` flags:
-
-```bash
-cp .env.example .env          # then edit .env and set ANTHROPIC_API_KEY
-docker compose run loki start prd.md
-```
-
-`.env` is gitignored. Edit it and re-run any time; compose reloads it
-automatically.
-
-##### Host OAuth (Claude Code Max/Pro subscribers, no API key)
-
-If you have a Claude Code subscription and no API key, you can reuse your host
-login by mounting your credentials file at
-`/home/loki/.claude/.credentials.json` instead of setting `ANTHROPIC_API_KEY`.
-See [DOCKER_README.md](../DOCKER_README.md) "Option 2: host OAuth" for the
-one-line export command and the compose volume to uncomment.
-
-##### Other providers in Docker
-
-The image ships only the Claude Code CLI. Cline, Codex, Aider, and opencode are
-bring-your-own-CLI: install the provider CLI in a derived image (or mount it),
-then select it with `-e LOKI_PROVIDER=<name>`. See
-[DOCKER_README.md](../DOCKER_README.md) for details.
-
-### Degraded Mode
-
-When using `codex`, `cline`, or `aider` providers, Loki Mode operates in **degraded mode**:
-
-- Core autonomous workflow functions normally
-- Some advanced features may be unavailable or behave differently
-- Model-specific optimizations (Opus/Sonnet/Haiku routing) are adapted for each provider
-- Quality gates and RARV cycle remain fully functional
-
-**Recommendation:** For the best experience and full feature support, use the default `claude` provider.
-
----
-
-## Environment Variables
-
-Loki Mode is designed to run with zero configuration: the trust-layer and
-quality features below are default-on and decide intelligently by inspecting
-the work. The environment variables here are opt-out escape hatches for power
-users, not required setup. Set the documented value to disable a feature; leave
-the variable unset to keep the intelligent default.
-
-### Trust-gate and completion knobs (default-on)
-
-These are read by the orchestrator (`autonomy/run.sh`) on every run.
-
-- `LOKI_REVIEW_INCONCLUSIVE_BLOCK` (default `1`) -- when a code-review cycle
-  returns zero usable verdicts (every reviewer produced empty output), the
-  review is treated as INCONCLUSIVE and the gate BLOCKS, because an all-empty
-  review proves nothing. A bounded one-shot retry runs first
-  (`LOKI_REVIEW_RETRY`, default `1`). Set `LOKI_REVIEW_INCONCLUSIVE_BLOCK=0` to
-  record the inconclusive result without blocking.
-
-- `LOKI_COMPLETION_TEST_CAPTURE` (default `1`) -- before the verified-completion
-  evidence gate runs, Loki captures a fresh `test-results.json` so the gate
-  scores on real PASS/FAIL test results instead of a stale or missing file. It
-  reuses this iteration's results if already fresh, and never crashes the
-  completion path on red tests (the gate is the decider). Set
-  `LOKI_COMPLETION_TEST_CAPTURE=0` to opt out.
-
-- `LOKI_AUTO_DOCS` (default `true`) -- auto-generates the `.loki/docs/` suite
-  before the documentation gate evaluates, so the gate scores on real generated
-  docs instead of nagging you to run `loki docs generate` by hand. Bounded:
-  runs at most once per run when docs are missing, and again only when existing
-  docs are substantially stale; best-effort, never fails the iteration loop.
-  Set `LOKI_AUTO_DOCS=false` to opt out.
-
-### Output-token compressor (caveman, Claude-only)
-
-Loki integrates [caveman](https://github.com/JuliusBrussee/caveman), an optional
-Claude Code skill that compresses the model's OUTPUT tokens only (keeping all
-technical substance). It activates on free-form generation (the main RARV dev
-loop) and is HARD-SUPPRESSED on every trust-gate subcall (council votes, code
-review verdicts, evidence-related parses) so determinism is never affected. It
-is Claude-provider-only; runs are byte-identical on Cline / Codex / Aider / opencode. These
-variables are read in `autonomy/lib/claude-flags.sh`.
-
-- `LOKI_CAVEMAN` (default on) -- set `LOKI_CAVEMAN=0` to disable the compressor.
-  Suppression on trust-gate subcalls is unconditional and applies even when
-  caveman is globally installed but `LOKI_CAVEMAN=0`, so trust gates are never
-  exposed to compression.
-
-- `LOKI_CAVEMAN_LEVEL` (default `full`) -- the compression level for free-form
-  activation. When you do NOT set this, the level is inferred per-invocation
-  from the run's RARV tier (planning -> `lite`, development/fast -> `full`); the
-  auto path never selects `ultra`. Setting `LOKI_CAVEMAN_LEVEL` explicitly
-  overrides the inference entirely (the opt-out escape hatch).
-
-- `LOKI_CAVEMAN_VERSION` (default `1.9.0`) -- the pinned caveman version used by
-  the one-time bootstrap. Bump only to upgrade the compressor.
-
-### RARV-C closure knobs (default-on)
-
-The Phase 1 / RARV-C closure loop (findings injection, override council,
-learnings writer, handoff doc) is default-on and documented in detail at the
-top of this guide under [Phase 1 RARV-C closure](#phase-1-rarv-c-closure-shipped-v750-default-on-as-of-v753):
-`LOKI_INJECT_FINDINGS`, `LOKI_OVERRIDE_COUNCIL`, `LOKI_AUTO_LEARNINGS`, and
-`LOKI_HANDOFF_MD` (each opt out with `=0`). For the full schema and
-reachability notes, see `skills/quality-gates.md`.
+You need at least one provider CLI. Claude Code (`claude`) is the default and the only one with every feature.
 
 ---
 
-## Claude Code (CLI)
-
-Loki Mode can be installed as a skill in three ways:
+## First run
 
-### Option A: Git Clone (Recommended)
-
-**Personal installation (available in all projects):**
 ```bash
-git clone https://github.com/asklokesh/loki-mode.git ~/.claude/skills/loki-mode
+loki welcome                 # what Loki is and what to do next
+loki quickstart              # guided first build: setup check, idea, template, plan, go
+loki owner/repo#42           # work a GitHub issue end to end and open a PR
+loki "add a /health route"   # run one task in the current repo
 ```
 
-**Project-specific installation:**
-```bash
-# Navigate to your project directory first
-cd /path/to/your/project
-
-# Clone to local skills directory
-git clone https://github.com/asklokesh/loki-mode.git .claude/skills/loki-mode
-```
+`loki quickstart` asks four questions and shows the plan before anything runs. Press Enter at every step to build the sample Todo app. Add `--dry-run --json` to preview the plan without writing files.
 
-### Option B: Download from Releases
+Every finished run leaves a receipt. Check a branch the same way CI does:
 
 ```bash
-# Navigate to skills directory
-cd ~/.claude/skills
-
-# Get latest version number
-VERSION=$(curl -s https://api.github.com/repos/asklokesh/loki-mode/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d 'v')
-
-# Download and extract
-curl -L -o loki-mode.zip "https://github.com/asklokesh/loki-mode/releases/download/v${VERSION}/loki-mode-claude-code-${VERSION}.zip"
-unzip loki-mode.zip && rm loki-mode.zip
+loki verify          # deterministic verification of HEAD against the base branch
 ```
 
-**Result:** Creates `~/.claude/skills/loki-mode/SKILL.md`
-
-### Option C: Minimal Install (curl)
-
-If you only want the essential files without the full repository:
-
-```bash
-# Create directory structure
-mkdir -p ~/.claude/skills/loki-mode/references
-
-# Download core skill file
-curl -o ~/.claude/skills/loki-mode/SKILL.md \
-  https://raw.githubusercontent.com/asklokesh/loki-mode/main/SKILL.md
-
-# Download agent definitions
-curl -o ~/.claude/skills/loki-mode/references/agent-types.md \
-  https://raw.githubusercontent.com/asklokesh/loki-mode/main/references/agent-types.md
-
-# Download deployment guides
-curl -o ~/.claude/skills/loki-mode/references/deployment.md \
-  https://raw.githubusercontent.com/asklokesh/loki-mode/main/references/deployment.md
-
-# Download business operations reference
-curl -o ~/.claude/skills/loki-mode/references/business-ops.md \
-  https://raw.githubusercontent.com/asklokesh/loki-mode/main/references/business-ops.md
-```
-
-**Note:** This minimal install won't include examples, tests, or the autonomous runner. Use Option A or B for full functionality.
-
----
-
-## Claude.ai (Web)
-
-For using Loki Mode on the Claude.ai web interface:
-
-### Step 1: Download the Skill Package
-
-1. Go to [Releases](https://github.com/asklokesh/loki-mode/releases)
-2. Download **either**:
-   - `loki-mode-X.X.X.zip` (standard format)
-   - `loki-mode-X.X.X.skill` (skill format)
-
-   Both contain the same skill and will work.
-
-### Step 2: Upload to Claude.ai
-
-1. Open [Claude.ai](https://claude.ai)
-2. Go to **Settings** (gear icon)
-3. Navigate to **Features → Skills**
-4. Click **Upload Skill**
-5. Select the downloaded `.zip` or `.skill` file
-
-**File Structure:** The Claude.ai package has `SKILL.md` at the root level as required by the web interface.
+Exit codes are listed in [exit-codes.md](exit-codes.md). Receipt signing and third-party checking are covered in [SIGNED-RECEIPTS.md](SIGNED-RECEIPTS.md).
 
 ---
 
-## Anthropic API Console
-
-For using Loki Mode through the Anthropic API Console (console.anthropic.com):
-
-### Step 1: Download the API Package
-
-1. Go to [Releases](https://github.com/asklokesh/loki-mode/releases)
-2. Download **`loki-mode-api-X.X.X.zip`** (note the `-api-` version)
-
-   **Important:** The API version has a different file structure than the web version.
-
-### Step 2: Upload to API Console
-
-1. Go to [console.anthropic.com](https://console.anthropic.com)
-2. Navigate to **Skills** section
-3. Click **Upload Skill**
-4. Select the downloaded `loki-mode-api-X.X.X.zip` file
-
-**File Structure:** The API package has `SKILL.md` inside a `loki-mode/` folder as required by the API.
-
----
+## Control Plane
 
-## Verify Installation
-
-### For Claude Code (CLI)
-
-Check that the skill file is in place:
+The Control Plane is the local UI for runs, work and cost. It needs Bun.
 
 ```bash
-cat ~/.claude/skills/loki-mode/SKILL.md | head -10
-```
-
-**Expected output:** Should show YAML frontmatter starting with:
-```yaml
----
-name: loki-mode
-description: Autonomous Spec-to-Product System (RARV-C closure loop)
-...
----
+loki control serve   # 127.0.0.1:47821 by default
+loki dashboard       # reuse a running Control Plane, or start one, and open it
 ```
 
-### For Claude.ai (Web)
-
-1. Start a new conversation
-2. Type: `Loki Mode`
-3. Claude should recognize the skill and ask for a spec (PRD, GitHub issue link, or YAML)
-
-### For API Console
-
-1. Create a new API call with skills enabled
-2. Include the skill in your request
-3. The skill should be available for use
+See [control-plane-migration.md](control-plane-migration.md) and [control-plane-container.md](control-plane-container.md).
 
 ---
 
-## File Structure
+## Providers
 
-After installation, you should have this structure:
-
-```
-loki-mode/
-├── SKILL.md              # Main skill file (required)
-├── README.md             # Documentation
-├── docs/
-│   └── INSTALLATION.md   # This file
-├── CHANGELOG.md          # Version history
-├── VERSION               # Current version number
-├── LICENSE               # Business Source License 1.1
-├── references/           # Agent and deployment references
-│   ├── agents.md
-│   ├── deployment.md
-│   └── business-ops.md
-├── autonomy/             # Autonomous runner (CLI only)
-│   ├── run.sh
-│   └── README.md
-├── templates/            # 22 spec templates (PRD-style) for project scaffolding
-│   ├── simple-todo-app.md
-│   ├── api-only.md
-│   ├── static-landing-page.md
-│   └── ... (22 templates total)
-├── tests/                # Test suite (CLI only)
-│   ├── run-all-tests.sh
-│   ├── test-bootstrap.sh
-│   └── ...
-└── integrations/         # Third-party integrations
-    └── vibe-kanban.md
-```
+| Provider | Notes |
+|----------|-------|
+| `claude` | Default. Full feature set. |
+| `cline` | Full feature set; small local models may fail tool use. |
+| `codex` | Sequential only. |
+| `aider` | Sequential only; `ollama_chat/<model>` works for local models. |
+| `opencode` | Sequential only. Install with `npm install -g opencode-ai`. |
 
-**Note:** Some files/directories (autonomy, tests, templates) are only available with full installation (Options A or B).
+When `LOKI_PROVIDER` is unset, Loki uses the first installed CLI in this order: `claude`, `cline`, `codex`, `aider`, `opencode`. An explicit `LOKI_PROVIDER` or `--provider NAME` always wins.
 
 ---
 
-## Ports
-
-Loki Mode uses two network ports for different services:
-
-| Port | Service | Description |
-|------|---------|-------------|
-| **47821** | Control Plane UI + API | The only UI, plus the `/v1/*` API. Started by `loki control serve` or `loki dashboard`. See [control-plane-migration.md](control-plane-migration.md). |
-| **57374** | Legacy API (FastAPI) | The classic dashboard UI is removed in 10.8; this port no longer serves a UI. |
-
-### When to Use Which Port
-
-- **Browser access** (UI, monitoring): Use the Control Plane, port **47821** -- `http://127.0.0.1:47821`
-- **API calls** (REST, programmatic): Use port **57374** -- `http://localhost:57374`
-- **VS Code extension** (deprecated as of v7.2.0): Connects to API on port **57374** automatically (configurable via `loki.apiPort` setting). No new releases will be published; see the deprecation notice above.
-- The server is started automatically when you run `loki start` or `./autonomy/run.sh`. No manual configuration is needed.
-
-### Port Configuration
+## Configuration
 
-```bash
-# Control Plane port (default: 47821)
-loki control serve --port 47821
-
-# API port (default: 57374)
-loki api start --port 57374   # was: loki serve
-```
-
-### CORS Configuration
-
-The Control Plane has no CORS setting and requires a loopback Host header unless it is bound to a non-loopback address with `LOKI_CONTROL_TOKEN` set (see [control-plane-migration.md](control-plane-migration.md)). The `LOKI_DASHBOARD_CORS` variable below applies only to the legacy API server:
+Loki runs with zero configuration. To set options in one place, use a config file:
 
 ```bash
-# Allow specific origins
-LOKI_DASHBOARD_CORS="http://localhost:3000,https://my-dashboard.example.com" loki dashboard start
-
-# Default: http://localhost:57374,http://127.0.0.1:57374 (localhost-only, secure by default)
+loki config example > loki.yaml   # annotated starter
+loki config validate loki.yaml    # rejects raw secrets and bad keys
+loki start --config loki.yaml ./prd.md
 ```
 
----
-
-## Shell Completions
-
-Enable tab completion for the `loki` CLI to support subcommands, flags, and file arguments.
-
----
-
-## Bash Setup
-
-### Option 1: Permanent Setup (Recommended)
-
-Add the source command to your startup file so completions load every time you open a terminal.
-
-Add this line to your `~/.bashrc` (Linux) or `~/.bash_profile` (macOS):
-
-```bash
-# npm install: use the npm package path
-source "$(npm root -g)/loki-mode/completions/loki.bash"
-
-# git clone: use the skills directory
-source ~/.claude/skills/loki-mode/completions/loki.bash
-```
+A CLI flag beats an environment variable, which beats the config file, which beats the defaults. Reference secrets as `${VAR}`; never write them inline. Every variable is listed in [environment-variables.md](environment-variables.md).
 
 ---
 
-### Option 2: Manual Sourcing (Temporary)
-
-If you only want to enable completions for your current terminal session (for example, for testing), run:
+## Privacy
 
-```bash
-source completions/loki.bash
-```
+Anonymous diagnostics are on for an ordinary interactive install and off automatically in CI, non-interactive sessions, and when `LOKI_ENTERPRISE=true` or `LOKI_AIRGAP=true` is set. They never include code, prompts, file paths or keys. Turn them off with `loki telemetry off` or `DO_NOT_TRACK=1`. Details: [PRIVACY.md](PRIVACY.md).
 
 ---
 
-### Optional: Smoother Bash Experience
+## Shell completions
 
-By default, Bash requires two **TAB** presses to show the completion menu. To make it instant (similar to Zsh) and cycle through options more easily, add the following lines to your `~/.inputrc` file:
+The npm install sets them up for you. To install them by hand:
 
 ```bash
-# Show menu immediately on first TAB
-set show-all-if-ambiguous on
-
-# Case-insensitive completion (optional)
-set completion-ignore-case on
+loki completions install          # detects bash or zsh
+loki completions bash > ~/.loki-completion.bash   # or print the script
 ```
 
-> **Note:** You will need to restart your terminal for `~/.inputrc` changes to take effect.
-
 ---
 
-## Zsh Setup
-
-Zsh completions require the script to be located in a directory listed in your `$fpath`.
-
-### Permanent Setup
+## Update and uninstall
 
-Add the `loki` completions directory to your `$fpath` in `~/.zshrc` **before** initializing completions:
+| Method | Update | Uninstall |
+|--------|--------|-----------|
+| npm | `npm update -g loki-mode` | `npm uninstall -g loki-mode` |
+| Bun | `bun update -g loki-mode` | `bun remove -g loki-mode` |
+| Homebrew | `brew upgrade loki-mode` | `brew uninstall loki-mode` |
 
-```bash
-# 1. Add the completions directory to fpath
-fpath=(/path/to/loki/completions $fpath)
-
-# 2. Initialize completions
-autoload -Uz compinit && compinit
-```
-
----
-
-## Testing Completions
-
-After installation, restart your shell or source your configuration file, then verify:
-
-### Bash
-
-```bash
-loki <TAB>            # Should immediately list subcommands
-loki start -<TAB>     # Should list flags (--provider, --parallel, etc.)
-```
-
-### Zsh
-
-```bash
-loki <TAB>                # Should show subcommands with descriptions
-loki start --pro<TAB>     # Should autocomplete to --provider
-```
-
----
-
-## Completion Features
-
-The completion scripts support:
-
-* **Subcommands**
-  `start`, `stop`, `pause`, `resume`, `status`, `dashboard`, `import`, `council`, `memory`, `provider`, `config`, `audit`, `metrics`, `watchdog`, `secrets`, `help`, `completions`
-
-* **Smart Context**
-
-  * `loki start --provider <TAB>` completes the supported providers (`claude`, `cline`, `codex`, `aider`, `opencode`; see `completions/loki.bash:24`).
-  * `loki start <TAB>` defaults to file completion for spec files (PRD templates, YAML).
-
-* **Nested Commands**
-  Handles specific subcommands for `council`, `memory`, `config`, `audit`, `metrics`, `watchdog`, and `secrets`.
+Run state lives in `.loki/` inside each project and in `~/.loki/`. Remove those directories to delete it.
 
 ---
 
 ## Troubleshooting
 
-### Skill Not Found
-
-**Problem:** Claude doesn't recognize "Loki Mode" command.
-
-**Solutions:**
-1. **Check installation path:**
-   ```bash
-   ls -la ~/.claude/skills/loki-mode/SKILL.md
-   ```
-
-2. **Verify YAML frontmatter:**
-   ```bash
-   cat ~/.claude/skills/loki-mode/SKILL.md | head -5
-   ```
-   Should show `name: loki-mode`
-
-3. **Restart Claude Code:**
-   ```bash
-   # Exit and restart claude command
-   ```
-
-### Permission Denied
-
-**Problem:** Cannot create directories or download files.
-
-**Solution:**
-```bash
-# Ensure skills directory exists
-mkdir -p ~/.claude/skills
-
-# Check permissions
-ls -la ~/.claude/
-```
-
-### Download Fails
-
-**Problem:** curl or wget commands fail.
-
-**Solutions:**
-1. **Check internet connection**
-
-2. **Try alternate download method:**
-   ```bash
-   # Use wget instead of curl
-   wget -O ~/.claude/skills/loki-mode/SKILL.md \
-     https://raw.githubusercontent.com/asklokesh/loki-mode/main/SKILL.md
-   ```
-
-3. **Manual download:**
-   - Visit the URL in a browser
-   - Save file manually to `~/.claude/skills/loki-mode/`
-
-### Autonomous Runner Won't Start
-
-**Problem:** `./autonomy/run.sh` gives "command not found" or permission errors.
-
-**Solutions:**
-1. **Make executable:**
-   ```bash
-   chmod +x autonomy/run.sh
-   ```
-
-2. **Run from repository root:**
-   ```bash
-   # Make sure you're in the loki-mode directory
-   cd ~/.claude/skills/loki-mode
-   ./autonomy/run.sh
-   ```
-
-3. **Check prerequisites:**
-   ```bash
-   # Ensure Claude Code is installed
-   claude --version
-
-   # Ensure Python 3 is available
-   python3 --version
-   ```
-
-### References Not Loading
-
-**Problem:** Skill loads but agent definitions or deployment guides are missing.
-
-**Solution:**
-```bash
-# Ensure all reference files are present
-ls -la ~/.claude/skills/loki-mode/references/
-
-# Should show:
-# agents.md
-# deployment.md
-# business-ops.md
-
-# If missing, download them:
-curl -o ~/.claude/skills/loki-mode/references/agent-types.md \
-  https://raw.githubusercontent.com/asklokesh/loki-mode/main/references/agent-types.md
-```
-
----
-
-## Updating Loki Mode
-
-### For Git Installations
-
-```bash
-cd ~/.claude/skills/loki-mode
-git pull origin main
-```
-
-### For Manual Installations
-
-1. Download the latest release
-2. Extract to the same directory (overwrite existing files)
-3. Or delete old installation and reinstall
-
-### Check Current Version
-
-```bash
-cat ~/.claude/skills/loki-mode/VERSION
-```
-
----
-
-## Uninstalling
-
-### Claude Code (CLI)
-
-```bash
-# Remove the skill directory
-rm -rf ~/.claude/skills/loki-mode
-```
-
-### Claude.ai (Web)
-
-1. Go to **Settings → Features → Skills**
-2. Find "loki-mode" in the list
-3. Click **Remove**
-
-### API Console
-
-1. Go to **Skills** section
-2. Find "loki-mode"
-3. Click **Delete**
-
----
-
-## Next Steps
-
-After installation:
-
-1. **Verify Setup:** Check your environment is ready
-   ```bash
-   loki doctor
-   ```
-
-2. **Scaffold a Project:** Create a project from a template
-   ```bash
-   loki init my-app --template simple-todo-app
-   cd my-app
-   ```
-
-3. **Start Building:** Launch autonomous development from any spec (PRD, GitHub issue, or YAML)
-   ```bash
-   loki start spec.md
-   ```
-
-4. **Read Documentation:** Check out [README.md](../README.md) for usage guides
-
-5. **Join the Community:** Report issues or contribute at [GitHub](https://github.com/asklokesh/loki-mode)
-
----
-
-## Release Operations
-
-<details>
-<summary>Token Rotation Runbook (maintainers only)</summary>
-
-Follow this runbook when a release workflow fails to publish to npm.
-
-**Symptom:** The `publish-npm` step in `.github/workflows/release.yml` fails with:
-```
-npm error 404 Not Found - PUT https://registry.npmjs.org/loki-mode
-```
-
-A 404 on PUT means the registry rejected the credential, not that the package is missing.
-
-**Likely causes:**
-- The `NPM_TOKEN` Automation token has expired.
-- The token was revoked or its owner lost publish rights on the `loki-mode` package.
-- The npm account requires a 2FA refresh and the existing Automation token is no longer accepted.
-
-**Remediation steps:**
-1. Log in to npmjs.com as the publish account and regenerate an Automation token with publish access scoped to `loki-mode`.
-2. Open https://github.com/asklokesh/loki-mode/settings/secrets/actions
-3. Update the `NPM_TOKEN` repository secret with the new token value.
-4. Re-run the failed Release workflow: `gh run rerun <run-id>`. If re-run is not available for that run, push a no-op commit to `main` to retrigger.
-
-**Verification:**
-- Watch the new run: `gh run watch <new-run-id>` and confirm `publish-npm` and `publish-ts-sdk` succeed.
-- Confirm publish: `npm view loki-mode version` returns the new version.
-
-**Note on `publish-ts-sdk`:** This job publishes `sdk/typescript` to npm and uses the same `secrets.NPM_TOKEN` as `publish-npm` (see `.github/workflows/release.yml`). Rotating `NPM_TOKEN` fixes both jobs. The new Automation token must have publish access to both the `loki-mode` package and the TypeScript SDK package.
-
-</details>
-
----
-
-## Need Help?
-
-- **Issues/Bugs:** [GitHub Issues](https://github.com/asklokesh/loki-mode/issues)
-- **Discussions:** [GitHub Discussions](https://github.com/asklokesh/loki-mode/discussions)
-- **Documentation:** [README.md](../README.md)
-
----
-
-**Happy Building!**
+- `loki: command not found`: the global bin directory of your package manager is not on `PATH` (`npm prefix -g` shows where npm installs).
+- `the Loki 10 engine cannot run on this machine: no working bun`: install Bun, or reinstall without `--omit=optional`.
+- A provider is missing: `loki doctor` names it and prints the install command.
+- Anything else: `loki doctor --json`, then [KNOWN-ISSUES.md](KNOWN-ISSUES.md), then `loki crash` to file a report.