loki-mode 11.3.9 → 11.5.1

package/docs/CLI-CORE-VERBS.md

@@ -0,0 +1,112 @@
+# Core verbs (CLI reference)
+
+The commands most people use, with their main flags. The complete generated
+command table is `docs/CLI-REFERENCE.md` (do not edit that file by hand).
+`loki help` prints the grouped summary; `loki help all` prints every command;
+`loki help <topic>` prints a topic (start, models, providers, agents, verify,
+exit-codes, config); `loki help <command>` runs `<command> --help`. Scripts that
+parse the old default `loki help` output must switch to `loki help all`.
+
+`loki start` is the primary path. Everything else is a shortcut, a check, or an
+alternative surface for the same engine. Claude Code is the default Tier-1
+provider; other providers and model routes are additions selected with
+`--provider` or `LOKI_MODEL_ROUTE`.
+
+## Start
+
+| Command | What it does |
+| --- | --- |
+| `loki start [SPEC]` | The primary path. Build from a PRD file, an issue (`owner/repo#N`, issue URL, `PROJ-1`), a quoted task or a one-word brief. Alias: `run`. Shorthand: `loki "<task>"`, `loki owner/repo#N` |
+| `loki edit "<change>"` | One targeted change to the current repo in one pass. No PRD, plan, council, PR or branch switch |
+| `loki quick "<task>"` | One small task with a verify loop, no PR |
+| `loki chat` | Interactive alternative to `loki start` (Plan and Build modes, slash commands) |
+
+`start` flags: `--no-pr`, `--deep`, `--provider NAME`, `--max-cost USD`
+(aliases `--budget`, `--budget-limit`), `--session-model TIER`, `-v` (verbose),
+`--quiet`, `--json`, `--engine legacy|engine10`, `--explain-route`. Flags that
+only the previous loop honors (`--simple`, `--complex`, `--parallel`,
+`--isolation`, `--sandbox`, `--max-iterations`, `--compliance`, ...) send that
+one call to the previous loop with a one-line notice.
+
+Spend cap: `--max-cost`, else `budgets.per_run` in `loki.yaml`, else $100 when
+`ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is set, else no dollar cap
+(subscription). Model routes: `LOKI_MODEL_ROUTE=ollama/qwen3-coder loki start prd.md`.
+
+### loki edit
+
+`loki edit [paths...] "<change>"` with `--verify` (fast verifier), `--receipt`
+(unsigned receipt in `.loki/edit-receipts/`), `--commit` (only touched files, by
+name; skipped when verify failed) and `--dry-run` (plan only). `LOKI_EDIT_MODEL`
+overrides the model. Claude provider only for now.
+
+### loki chat
+
+Needs a TTY (otherwise exit 2; use `loki quick`). Starts in Plan mode
+(read-only); `/plan` and `/build` switch. Slash commands: `/plan`, `/build`,
+`/run <prd|brief>` (starts a normal `loki start` run with the chat's model and
+provider), `/quick`, `/edit`, `/verify`, `/receipt`, `/cost`, `/diff`, `/undo`,
+`/model <id>`, `/provider <name>`, `/help`, `/exit`. `loki chat --attach` joins a
+running or the last `loki start` session (`/status`, `/steer`, `/diff`,
+`/verify`, `/receipt`, `/stop`). `loki chat --tui` launches the Claude Code TUI
+with Loki context. Bare `loki` does not open chat.
+
+## Check
+
+| Command | What it does |
+| --- | --- |
+| `loki status [--json]` | Current run status |
+| `loki verify [--fast] [--json] [--pubkey FILE]` | Deterministic verification with CI-gate exit codes |
+| `loki receipt` (alias of `proof`) | Inspect the proof-of-run receipt |
+| `loki diff` / `loki undo <run> [--plan]` | Show what a run changed; plan or apply an undo |
+| `loki route [start\|quick] <args> [--json]` | Print the engine, provider, model, input type and reason without running |
+
+Every run ends with one unified summary on both engines: `Result:`, `Files:`,
+`Cost:` (marked `(estimated)` or `not measured`), `Elapsed:`, `Receipt:` and a
+`next:` line. `--quiet` prints only that block; `--json` adds a `summary`
+object; `NO_COLOR=1` disables color.
+
+## Configure
+
+| Command | What it does |
+| --- | --- |
+| `loki setup [--yes] [--check]` | First-run wizard: tools, Claude login, provider, model route, spend cap. Flags: `--provider`, `--model`, `--budget USD`, `--global` |
+| `loki doctor [--fix] [--json]` | Check prerequisites, providers and login. `--fix` creates state dirs and a default config and prints exact commands for the rest; never runs sudo |
+| `loki config list\|get\|set\|path\|show\|validate` | Settings; `config list --json` for machines |
+| `loki models [--local] [--json]` | Model routes (openrouter, ollama, lmstudio, llamacpp, vllm, custom); `--local` probes local runtimes and prints ready-to-paste values |
+| `loki agents list\|new\|show\|export --claude` | Custom child agents in `.loki/agents/*.md` (project) or `~/.config/loki/agents/` (user). `loki agent` (singular) is the unchanged built-in agent-type command |
+| `loki provider list\|set NAME` | Providers and install status |
+
+## --json
+
+`status`, `doctor`, `verify`, `config list` and `models` accept `--json`.
+`status`, `doctor` and `models` emit native JSON. `verify` and `config list`
+emit one object from the shared helper `autonomy/lib/json-output.sh`:
+
+```json
+{"command": "verify", "exit_code": 0, "ok": true, "output": "..."}
+```
+
+The process exit code equals `exit_code`.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Failure |
+| 2 | Usage error for an unknown command, or setup error |
+| 3 | Missing component, or verifier error |
+| 64 | Usage error for `verify`, `quick` and `start` (unknown option, missing task) |
+
+Severity rises with the code. `loki verify` exits 0 VERIFIED, 1 CONCERNS, 2
+BLOCKED or not a git directory, 3 verifier error or empty diff, 64 usage error.
+Gate CI with `loki verify || fail` and treat any code of 2 or higher as worse
+than CONCERNS. From 11.4.0 this is a breaking change for scripts that tested
+`rc == 1` on an empty diff or a non-git directory. Per-command detail:
+`docs/exit-codes.md`.
+
+## Unknown commands
+
+An unknown command prints a "Did you mean" suggestion (edit distance), points
+to `loki help` and `loki help all`, and exits 2. A bare one-word `loki <word>`
+is the command namespace; use `loki start <word>` for a one-word brief.

package/docs/CLI-REFERENCE.md

@@ -1,6 +1,6 @@
 # CLI reference
 
-Generated from `loki-ts/src/cli/registry.ts` by `scripts/generate-stale-zero.sh` for v11.3.9. Do not edit by hand.
+Generated from `loki-ts/src/cli/registry.ts` by `scripts/generate-stale-zero.sh` for v11.5.1. Do not edit by hand.
 Hidden and legacy-only commands are omitted; see `docs/v10/CLI-MODERN.md` for the full inventory.
 
 | Command | Description |
@@ -12,6 +12,8 @@ Hidden and legacy-only commands are omitted; see `docs/v10/CLI-MODERN.md` for th
 | `loki provider show` | Show current provider |
 | `loki provider list` | List providers and install status |
 | `loki provider set` | Switch the active provider |
+| `loki provider info` | Provider details; --json prints the capability contract |
+| `loki provider matrix` | Capability matrix per provider and engine |
 | `loki memory` | Cross-project learnings |
 | `loki memory list` | All learnings |
 | `loki memory index` | Show or rebuild the memory index |
@@ -74,6 +76,11 @@ Hidden and legacy-only commands are omitted; see `docs/v10/CLI-MODERN.md` for th
 | `loki engine10 dashboard` | v10 dashboard |
 | `loki engine10 modernize` | v10 modernize |
 | `loki help` | Show help |
+| `loki chat` | Interactive chat with the active provider |
+| `loki edit` | Make one small scoped edit |
+| `loki diff` | Show what the last run changed |
+| `loki models` | Show per-provider model routes |
+| `loki setup` | Guided first-run setup wizard |
 | `loki quick` | One small task |
 | `loki quickstart` | Guided first build |
 | `loki init` | Scaffold from a template |
@@ -90,6 +97,7 @@ Hidden and legacy-only commands are omitted; see `docs/v10/CLI-MODERN.md` for th
 | `loki dashboard open` | Open in browser |
 | `loki config` | Manage configuration |
 | `loki config show` | Show config |
+| `loki config list` | List config (alias of show) |
 | `loki config init` | Create config |
 | `loki config edit` | Edit config |
 | `loki config path` | Print config path |

package/docs/COMPARE-OPENCODE.md

@@ -0,0 +1,94 @@
+# Loki Mode and opencode: an honest comparison
+
+opencode is a general-purpose interactive coding agent. Loki is an autonomous
+delivery system that works from a task to a verified, receipted result.
+They overlap in the terminal and differ in intent, so this page scores them
+category by category and says where opencode is ahead. It describes opencode
+from its public behavior as of this writing; check its docs for current detail.
+Loki can also drive opencode as a provider (`loki start --provider opencode`).
+
+## Summary
+
+| Category | Loki Mode (11.4.0) | opencode | Edge |
+|---|---|---|---|
+| Everyday UX | `loki start` with one unified summary; `loki chat` for interactive use | Polished TUI as the main surface | opencode for interactive feel; Loki for hands-off runs |
+| Install and onboarding | npm install, `loki setup`, `loki doctor --fix`; needs Node, Python, git, jq, curl and a model | Single binary or npm, provider login flow | opencode lighter; Loki now guided |
+| Learning curve | Few core verbs (`loki help`), one route for every input, `loki route` explains it | Learn one TUI | Roughly even |
+| Interactive coding | `loki chat`: Plan/Build modes, slash commands, `--attach` | Full TUI with sessions and rich editing flow | opencode |
+| Small changes | `loki edit` (one pass, diff, opt-in verify and receipt) | Prompt in the TUI or `opencode run` | Even |
+| Provider flexibility | Claude default; codex, cline, aider, opencode; OpenRouter and local routes | Very wide provider catalog, first-class | opencode |
+| Local models | `loki models --local`, `LOKI_MODEL_ROUTE=ollama/...`, lmstudio, llamacpp, vllm, custom URL | Local providers via config | Even |
+| Multi-agent | Role agents, council review, custom agents in `.loki/agents/*.md`, export to Claude Code subagents | Configurable agents and subagents | Even; Loki adds council |
+| Docs consistency | One routing story, one cap rule, generated CLI table | Single product surface | Even |
+| Predictability | Order-independent routing, documented exit-code contract, spend cap | Interactive, user-driven | Loki for unattended use |
+
+## Per category
+
+**Everyday UX.** In opencode you work inside one TUI and watch each step. In
+Loki you hand over a task with `loki start` and read one summary at the end:
+Result, Files, Cost, Elapsed, Receipt and a `next:` command. If you want to
+watch and steer, `loki chat --attach` joins the run. opencode's interactive
+experience is more mature.
+
+**Install and onboarding.** opencode installs as one tool and logs in to a
+provider. Loki needs Node.js 18+, Python 3.8+, git, jq, curl and a model:
+Claude Code is the default and needed for the default path; other CLIs are
+optional. `loki setup` walks through it and `loki doctor --fix` repairs state
+safely, printing exact commands for the rest. More prerequisites than opencode.
+
+**Learning curve.** `loki help` shows grouped core verbs (Start, Check,
+Configure); `loki help all` and `loki help <topic>` go deeper. Flag order and
+input form never change the engine, and `loki route` or `--explain-route`
+prints the engine, provider, model and reason. Unknown commands suggest the
+nearest match and exit 2.
+
+**Interactive coding.** `loki chat` has Plan mode (read-only for Claude) and
+Build mode, slash commands (`/run`, `/quick`, `/edit`, `/verify`, `/receipt`,
+`/diff`, `/undo`, `/model`, `/provider`) and `--tui` for the Claude Code TUI.
+It is newer and smaller than opencode's TUI. Its advantage is the handoff: `/run`
+starts a real `loki start` run and `--attach` joins one in progress.
+
+**Small changes.** `loki edit "<change>"` is one pass with no plan, council or
+PR, then diff stat, diff, cost and time. `--verify`, `--receipt`, `--commit`
+and `--dry-run` are opt-in. Claude provider only for now.
+
+**Provider flexibility.** opencode has the broader provider catalog. Loki's
+Tier-1 provider is Claude Code; codex, cline, aider and opencode are optional.
+On those, the Loki 10 engine now measures cost (parsed or estimated, flagged
+`estimated`) so `--max-cost` applies, and enforces the wall-clock limit,
+`BUDGET_LIMIT` kill and a post-iteration guard scan. Kill blocking is still
+Claude-only and receipts say so (`kill blocking not enforced`).
+
+**Local models.** `loki models --local` probes Ollama, LM Studio, llama.cpp and
+vLLM and prints ready-to-paste values. `LOKI_MODEL_ROUTE=<kind>/<id>` runs a
+local or OpenRouter model through the Claude harness, so Loki's controls still
+apply. Small local models can fail tool use; that limit is the model's.
+
+**Multi-agent.** Loki has built-in roles and a council. You can add your own
+as markdown with frontmatter (model, provider, tools, deny, permission) in
+`.loki/agents/`, manage them with `loki agents list|new|show|export --claude`,
+and council reviewers use a matching agent automatically.
+
+**Docs consistency.** The prerequisites, the spend cap ($100 with an API key,
+none on a subscription), routing and the provider table are stated once and
+match the code on this branch.
+
+**Predictability.** One execution path for every input form, a documented
+exit-code contract (`loki verify` 0 to 3, usage errors 64) and a spend cap
+that applies on every engine10 provider.
+
+## What Loki adds
+
+- **Autonomy.** A task, PRD or issue goes to a pull request without turn-by-turn
+  prompting, with a stop-and-ask when the contract cannot be met.
+- **Receipts.** A signed receipt per run that `loki verify` re-checks and that
+  lists what was NOT PROVEN.
+- **Verification.** Checks written from the task before code, a deterministic
+  `loki verify` for CI, and test-weakening detection.
+- **Council.** Specialist review selected from the changed files and diff.
+
+## When to pick which
+
+Pick opencode for hands-on interactive coding across many providers. Pick Loki
+when you want to delegate a task and get back a verified, receipted result, or
+to gate CI on `loki verify`. They compose: run opencode as a Loki provider.

package/docs/COMPONENTS.md

@@ -166,6 +166,7 @@ capability degradation.
 - `cline.sh` - Cline (Tier 2: reduced parallelism).
 - `codex.sh` - OpenAI Codex CLI (Tier 3: degraded, sequential).
 - `aider.sh` - Aider (Tier 3: degraded).
+- Non-Claude engine10 sessions run under `loki-ts/src/providers/provider_guard.ts` (timeout, budget stop, post-iteration diff scan with revert).
 - `loader.sh` - Provider loader utility.
 - `models.sh`, `model_catalog.json` - Model name registry and catalog.
 - `managed.py` - Managed provider client.

package/docs/EVALUATING.md

@@ -184,6 +184,33 @@ per-call cost was not recorded.
 
 ---
 
+## 8. Harness attribution: what Loki adds to the same model
+
+Question: what does Loki add to the same underlying coding agent, and is the benefit worth its cost? Status: pilot. Six tasks, small n. A pilot reports variance; it is not proof of superiority. Running it is a separate, paid step.
+
+```bash
+loki bench attribution --dry-run                       # validate task set, print plan, no model call
+loki bench attribution --model <model-id> --execute    # run, spends API budget
+loki bench attribution --report <result.json>          # re-render the markdown report
+```
+
+Source checkout only. Implementation: `benchmarks/bench/attribution.py`, reusing `runner._apply_overlay`, `report._median` and `benchmarks/bench/adapters` (process-tree reaping, the Claude JSON parser, the Loki adapter and its cost collection). Options: `--tasks id,id`, `--repeats N` (default 1), `--model ID` (default `claude-sonnet-5`, or `LOKI_BENCH_MODEL`), `--budget-usd X` (default 5), `--timeout SECONDS` (default 900, capped by each task's `agent_timeout_s`), `--out-dir DIR`, `--tasks-dir DIR`. Without `--execute` it only prints the plan and never spawns `claude` or `loki`.
+
+Arms and controls: `raw_claude` runs `claude -p <prompt> --output-format json --model M --dangerously-skip-permissions --max-budget-usd B`; `loki` runs `loki start <prompt-file> --provider claude --no-dashboard --yes` with `LOKI_SESSION_MODEL=M` and `LOKI_BUDGET_LIMIT=B`. Both get a byte-identical seed in a fresh git repo with one fixed "seed" commit, the same prompt text (the PRD file for Loki is kept outside the workspace), the same wall-clock cap with the process tree reaped on timeout, separate scratch directories, a scoped child environment and `LOKI_NO_BROWSER=1`. The arm that goes first alternates per task and repeat. Every result JSON pins `claude --version`, `loki version`, the Loki commit SHA, Python version, model, budget, timeout, repeats, and per task the sha256 of the seed tree, acceptance tree and prompt. Disclosed difference: Loki runs its own planning, review and verification loop; that overhead is what is measured. Provider comparisons are out of scope so model and harness effects are not mixed.
+
+Tasks live under `benchmarks/attribution/tasks/<id>/` (2 bug fixes, 2 features, 1 refactor, 1 integration): `task.json`, `prompt.md` (the only instruction either arm sees), `seed/` (workspace), `acceptance/` (hidden test, copied in only after the run, overwriting same-named files) and `reference/` (known-good overlay, used only by tests). Exit code 0 from `acceptance.cmd` means accepted. The loader rejects a task whose acceptance test also appears in the seed. Neither arm grades itself: no council, RARV-C or LLM judge takes part in scoring.
+
+Metrics, per arm and per task class, computed by `compute_metrics`; failures, timeouts and harness errors stay in every denominator:
+
+- Acceptance rate: accepted / assigned, with a 95% Wilson interval.
+- False-completion rate: (reported success and not accepted) / reported success; null when nothing reported success. Reported success means `claude -p` exits 0 with `is_error` false, or `loki start` exits 0.
+- Cost per accepted task: total measured spend across all attempts / accepted. Null (`undefined_no_accepted`) when none accepted. A run with no cost figure is `unmeasured`, never zero: some unmeasured gives `partial_lower_bound` (per-accepted null, lower bound only), all unmeasured gives `unmeasured`. Cost is API-dollar accounting; subscription use is not converted.
+- Elapsed time: median over accepted runs, with completion rate, timeout count and error count; median over all runs is also given.
+
+Not measured: human effort, recovery success, review quality. Output: `--out-dir` (default `benchmarks/attribution/results/`) receives `attribution-<UTC stamp>.json` and the matching `.md`. Publish failures, timeouts and exclusions with the report; do not drop rows. Do not claim superiority from overlapping intervals on a handful of runs; use the pilot to size a larger run with `--repeats` above 1. Tests: `python3 benchmarks/bench/tests/test_attribution.py` (no model call).
+
+---
+
 ## What we do not have
 
 Stating this plainly, because you will find it out anyway and it is cheaper for

package/docs/HARNESS-INTELLIGENCE-PLAN.md

@@ -133,6 +133,26 @@ Cap overrides (only meaningful when feature 8 is on):
 Profile knobs: `LOKI_REPO_PROFILE_TTL_SECONDS` (86400),
 `LOKI_REPO_PROFILE_MAX_CHARS` (2000).
 
+## Repo commands and baseline (REPOMEM, same module)
+
+`loki-ts/src/runner/repo_profile.ts` also owns the commands profile the engine10 path uses (`loki start`). The goal: the user never explains how the repo builds and tests, and a failure that was already there never blocks the run. It is not gated by `LOKI_REPO_PROFILE`; disable it with `LOKI_REPO_BASELINE=0`. Both profiles share one manifest hash (`manifestHash`: sha256 over name and content of package.json, requirements.txt, Makefile, pyproject.toml, tox.ini, pytest.ini, setup.cfg, go.mod, Cargo.toml and `.github/workflows/*.yml`).
+
+Artifact: `.loki/state/repo-profile.json` (version 1, `CommandProfile`), written by engine10 intake.
+
+- `revision`: HEAD the baseline ran on. `manifest_hash`: as above.
+- `commands[]`: `{kind: test|lint|typecheck|build, cmd, source, validated, exit_code, duration_s, failing_ids}`. `validated` is true only when the command ran to completion on the untouched tree, false when it could not run (missing, timed out), null when discovered but not executed. Only the first test command is executed.
+- `baseline`: `{ran, command, exit_code, duration_s, timed_out, failing_ids, attributable, reason?}`. `attributable` means exit 0, or non-zero with parseable failing ids (`failIds`).
+
+Lifecycle:
+
+1. Intake (after the dirty-tree refusal and the `.loki/` exclude, before any agent edit): same manifest hash and HEAD reuses the file; same hash and a new HEAD keeps the commands and re-runs only the baseline; a changed hash rediscovers and re-runs (`ensureProfile`).
+2. Baseline: `sh -c <test cmd>` in the repo, 60s timeout (SIGKILL), scoped env (`plainTestEnv`, `PYTHONDONTWRITEBYTECODE=1`, `CI=1`). Untracked files the run created are removed so the diff stays the agent's.
+3. Implementer brief (`briefContext`, e10ext/context.ts): a "Repo commands" block and the known-red test ids (`profileBrief`). Bytes depend only on the profile content (no timestamps).
+4. Verify (`verifyStage`): `attribute()` marks a failing check pre-existing only when the profile revision equals the run base sha, the baseline was attributable, the check is neither a Wall/task-named target nor in a file the diff touched, and every one of its failing ids is in the baseline. Those join `pre_red` and `pre_red_checks`. Everything else that fails is introduced and blocks as before; a check with no parsed ids is introduced. Verify data gains `baseline_line` (`baseline: N pre-existing failing check(s) (not blocking), M introduced (blocking)`) and `introduced_checks`; seal lists the line under NOT PROVEN only when a baseline failure was excused.
+5. Surface: `loki doctor --repo` (and `--repo --json`) prints the profile, read-only, from the current directory.
+
+`e10ext/repomemory.ts` still holds the last verified command, flaky list and failure causes (dynamic per-repo cache data, not discovery).
+
 ## Acceptance
 
 1. With all flags unset, `bun test tests/parity/` stays 60/60 byte-exact.

package/docs/INSTALLATION.md

@@ -2,9 +2,9 @@
 
 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.9
+**Version:** v11.5.1
 
-**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).
+**Engine note:** `loki start` is the primary command. `loki start`, `loki "<task>"`, `loki owner/repo#N` and `loki quick` all run the Loki 10 engine, whatever the flag order or input form (PRD file, issue ref, task or one-word brief). The previous loop runs only on `--engine legacy`, `LOKI_ENGINE=legacy`, or for one call when a flag Loki 10 cannot honor is present. See the [user guide](v10/GUIDE.md) and the [5-minute quickstart](QUICKSTART.md).
 
 ---
 
@@ -51,19 +51,52 @@ loki --version    # prints the installed version
 loki doctor       # checks providers, Bun, skill links and prerequisites
 ```
 
-You need at least one provider CLI. Claude Code (`claude`) is the default and the only one with every feature.
+## Prerequisites
+
+Required (`loki doctor` fails without them):
+
+| Tool | Minimum |
+|------|---------|
+| Node.js | 18 (20+ recommended, 22 LTS is the CI target) |
+| Python 3 | 3.8 |
+| git | any recent version |
+| jq | any |
+| curl | any |
+
+Plus a way to reach a model. Claude Code (`claude`) is the default provider and the only one with every feature, so the default path needs it installed and logged in: `npm install -g @anthropic-ai/claude-code`, then `claude auth login`. The bundled Claude Agent SDK with `ANTHROPIC_API_KEY` can stand in for the CLI on the engine10 path. `loki edit` and `loki chat` call the `claude` CLI directly. Every other provider CLI (`codex`, `cline`, `aider`, `opencode`) is optional.
+
+Optional: Bun 1.3+ (bundled by the npm package), bash 4+ (recommended), Ollama or an OpenRouter key for non-Claude model routes.
+
+One command checks and configures all of this:
+
+```bash
+loki setup            # wizard: tools, Claude login, provider, model route, spend cap
+loki setup --yes      # non-interactive, accept defaults
+loki setup --check    # report only
+loki doctor --fix     # apply safe fixes; prints exact commands for the rest
+loki config list      # show settings; also: loki config get|set|path
+loki doctor --json    # machine-readable
+```
+
+`loki doctor --fix` creates state directories and a default config. It never installs system packages or runs sudo; it prints those commands instead.
 
 ---
 
 ## First run
 
 ```bash
-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
+loki setup                         # first-run wizard
+loki start "add a /health route"   # the primary path: build, verify, seal a receipt
+loki start prd.md                  # same, from a PRD file
+loki start owner/repo#42           # same, from a GitHub, GitLab or Jira issue
+loki edit "rename fooBar to foo_bar"   # one small change, no loop
+loki chat                          # interactive alternative (Plan/Build modes)
+loki welcome                       # what Loki is and what to do next
+loki quickstart                    # guided first build: setup check, idea, template, plan, go
 ```
 
+The shorter forms `loki "<task>"` and `loki owner/repo#42` run the same engine. The spend cap defaults to $100 when `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is set and to no dollar cap on a subscription login; change it with `--max-cost <usd>`, `budgets.per_run` in `loki.yaml`, or `loki setup --budget`. A quick walkthrough is in [QUICKSTART.md](QUICKSTART.md).
+
 `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.
 
 Every finished run leaves a receipt. Check a branch the same way CI does:
@@ -93,14 +126,25 @@ See [control-plane-migration.md](control-plane-migration.md) and [control-plane-
 
 | 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`. |
+| `claude` | Default (Tier 1). Full feature set. |
+| `cline` | Full feature set; small local models may fail tool use. Engine10 cost parsed or estimated, guardrail scan. |
+| `codex` | Sequential only. Engine10 cost parsed or estimated, guardrail scan, `--sandbox workspace-write`. |
+| `aider` | Sequential only; `ollama_chat/<model>` works for local models. Engine10 cost reported or estimated, guardrail scan, `--no-auto-commits`. |
+| `opencode` | Sequential only. Supported in engine10 (`--provider opencode`); cost not measured. Install with `npm install -g opencode-ai`; model via `LOKI_OPENCODE_MODEL=provider/model`. |
 
 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.
 
+### Model routes and local models
+
+Run OpenRouter or a local model through the Claude harness with `LOKI_MODEL_ROUTE=<kind>/<id>`, where kind is `openrouter`, `ollama`, `lmstudio`, `llamacpp`, `vllm` or `custom` (custom needs `LOKI_MODEL_BASE_URL`):
+
+```bash
+loki models --local                                     # discover local models, print ready-to-paste values
+LOKI_MODEL_ROUTE=ollama/qwen3-coder loki start prd.md
+```
+
+OpenRouter reads `OPENROUTER_API_KEY`. The route applies to the Claude child process only and every Loki control (cost, kill blocking, receipts) still applies. Details: [user guide](v10/GUIDE.md).
+
 ---
 
 ## Configuration

package/docs/KNOWN-ISSUES.md

@@ -2,16 +2,15 @@
 
 Issues in the current release that are known and not yet fixed. Report new ones with `loki crash` or at https://github.com/asklokesh/loki-mode/issues.
 
-## `loki verify` exit codes differ from the target table in three cases
+## Which engine runs
 
-| Input | Command | Exit today | Target |
-|---|---|---|---|
-| Empty diff (a git repo with no changes vs base) | `loki verify` | 1 (CONCERNS) | 3 |
-| Not a git directory | `loki verify` | 1 (CONCERNS) | 2 |
-| Unknown flag | `loki verify` with a flag it does not know | 3 | 64 |
+From 11.4.0, `loki start`, `loki "<task>"`, `loki owner/repo#N` and `loki quick` run the Loki 10 engine whatever the flag order or input form. The previous loop runs only on `--engine legacy`, `LOKI_ENGINE=legacy`, for a provider with no Loki 10 invoker, for a PRD over 100000 bytes, or for one call when a flag Loki 10 cannot honor is present (`--simple`, `--parallel`, `--sandbox`, ...). Check with `loki route start <args> --json`: it reports `engine`, `adapter`, `reason` and `capability_differences`. The full table is in the Routing contract section of `docs/exit-codes.md`.
 
-Changing these is a breaking change for CI gates, so it waits for a planned release. Details: [exit-codes.md](exit-codes.md#known-gaps).
+## Exit codes
 
-## `loki start` uses the older engine
+The exit code of every command is listed in `docs/exit-codes.md`. Two things are kept as they are for compatibility:
 
-`loki "<task>"`, `loki owner/repo#N` and `loki quick` run the Loki 10 engine. `loki start ./prd.md` still routes to the older engine, which is being removed. Prefer `loki owner/repo#N` or `loki "<task>"`.
+- `loki run` (deprecated alias of `loki start <issue-ref>`) exits 1 on an unknown option, not 64.
+- `loki start` without `LOKI_DURABLE_STATE=1` has no finer run-outcome signal than 0 versus nonzero.
+
+An empty diff has a distinct exit code only for `loki verify` (3). `loki quick`, `loki start` and `loki run` do not define one.

package/docs/PROOF-PASSPORT.md

@@ -29,3 +29,117 @@ trust limitations, but no repository or machine-specific paths.
 Proof Passport does not currently sign the passport itself. Receipt signature
 status is reported separately and must not be interpreted as a passport
 signature.
+
+## Verification record
+
+Status: v1 (schema_version 1). Closes review finding LM-005: a passing outcome label could be misread when checks were not performed.
+
+Implementation: the verification-record section of `autonomy/lib/proof-verify.py` (CLI: `proof-verify.py <label|summary|json> <file>`). Both routes of `loki verify` and `loki proof show` use this one module, so the bash and Bun paths cannot drift.
+
+### Why three properties
+
+A single "verified" word hides three different questions. The record answers each one separately and never lets one stand in for another.
+
+1. **Integrity.** Is this record the one that was written, unaltered?
+2. **Execution validity.** Did the checks run against the code in front of you, and in what environment?
+3. **Requirement coverage.** Do the checks that ran actually cover what was asked for?
+
+A signature alone proves neither execution validity nor requirement coverage. A signed record can describe checks run on a different commit, on a dirty tree, or against only some of the requirements. The signature says the bytes are unchanged. It says nothing about whether the claims in those bytes are current or complete.
+
+### Property 1: integrity
+
+| status | meaning |
+| --- | --- |
+| `valid` | `verification.hash` matches the canonical bytes, gpg (when present) verifies, the recorded headline matches the headline re-derived from the facts, and the cost claim is coherent. |
+| `invalid` | Any of the above failed. The label becomes `NOT VERIFIED (integrity failed ...)` regardless of what the checks say. |
+| `not_recorded` | The record carries no hash. `.loki/verify/evidence.json` is always in this state: it is unhashed and unsigned. |
+| `unchecked` | The integrity code could not run. |
+
+The Ed25519 attestation is reported as present but is not verified inside the record. Use `loki proof verify --jwks` for that.
+
+### Property 2: execution validity
+
+Recorded with every receipt:
+
+- `git.head_sha` and `git.dirty` (dirty ignores `.loki/`), plus `git.tree_sha256` when the generator computed it.
+- `environment`: os, machine, python, node, bun and git versions, as found.
+
+Status:
+
+| status | meaning |
+| --- | --- |
+| `fresh` | Recorded HEAD equals live HEAD and the tree digest (or clean flag) still matches. |
+| `stale` | HEAD moved, or the working tree changed since the checks ran. Every previously passed check is reported as `stale`, and the label is `STALE (...)`. |
+| `unknown` | Not enough was recorded to compare (older receipts, no git tree). Unknown is never promoted to fresh. The label carries `revision freshness unknown`. |
+
+### Property 3: requirement coverage
+
+Read from `.loki/state/requirements-map.json`:
+
+```json
+{"requirements": [{"id": "R1", "text": "...", "checks": ["lint"], "status": "covered"}]}
+```
+
+| status | meaning |
+| --- | --- |
+| `recorded` | `total`, `covered`, `uncovered` and `uncovered_ids` are filled in. Uncovered requirements appear in the label. |
+| `not_recorded` | No map exists. Coverage is unknown, not zero. Counts are `null`. |
+| `unreadable` | The file exists but is not a valid map. Counts are `null`. |
+
+`covered_but_check_not_passed` lists covered requirements whose named check did not pass. Matching check ids to gate names is best effort.
+
+### Per-check status
+
+Every check is exactly one of: `passed`, `failed`, `skipped`, `not_run`, `stale`.
+
+Recorded words map as follows: pass-like words (`pass`, `passed`, `verified`, `ok`, `success`) become `passed`; fail-like words (`fail`, `failed`, `blocked`, `weakened`, `error`) become `failed`; `skipped` and `disabled` become `skipped`; `stale` stays `stale`. Everything else, including `inconclusive` and empty, becomes `not_run`. A check that did not reach a conclusion never reads as passed.
+
+### Label rules
+
+Evaluated in this order, first match wins:
+
+1. Integrity `invalid`: `NOT VERIFIED (integrity failed: ...)`.
+2. Any `failed` check: `NOT VERIFIED (failed: <ids>)`. A failed check never yields a passing label.
+3. Record has no facts or no base verdict: `INCOMPLETE (...)`.
+4. Base verdict is not `VERIFIED` or `VERIFIED WITH GAPS`: that verdict, unchanged.
+5. Execution `stale`: `STALE (...)`.
+6. Anything not run, recorded gaps, uncovered requirements, modified tests or unknown freshness: `VERIFIED (scoped: 5 of 7 checks ran; not run: lint, e2e)` with the applicable clauses.
+7. Otherwise `VERIFIED`.
+
+The bare word `VERIFIED` therefore means: integrity not failed, no failed checks, every check ran and passed, tree fresh, no uncovered requirements, no modified tests.
+
+### Modified tests
+
+`modified_tests` lists existing test files the change modified, deleted, renamed or type-changed, derived from `git diff --name-status` between the recorded base and head. Added test files are not listed. Status is `measured` or `unknown` (no base recorded or diff not computable). Modified tests appear in the label and in the summary because an implementer who edits the tests that judge the change weakens the evidence.
+
+### Record shape
+
+`loki proof show <id> --json` keeps the full proof. The verification record is produced by `proof-verify.py json`, embedded as `verification` in `.loki/verify/evidence.json`, and added as `verification` to the `loki proof verify` JSON. Fields are added, never renamed.
+
+```json
+{
+  "schema_version": 1,
+  "kind": "proof | evidence",
+  "label": "VERIFIED (scoped: ...)",
+  "base_verdict": "VERIFIED",
+  "integrity": {"status": "valid", "hash_ok": true, "signature": "none", "detail": "..."},
+  "execution": {"status": "fresh", "reason": "", "recorded": {}, "current": {}, "environment": {}},
+  "requirements": {"status": "recorded", "total": 3, "covered": 1, "uncovered": 2, "uncovered_ids": []},
+  "checks": [{"id": "lint", "status": "skipped", "detail": ""}],
+  "counts": {"passed": 1, "failed": 0, "skipped": 1, "not_run": 0, "stale": 0, "total": 2, "ran": 1},
+  "modified_tests": {"status": "measured", "files": [{"path": "tests/a.py", "change": "modified"}]},
+  "complete": true,
+  "record_path": ""
+}
+```
+
+### Human output
+
+`loki verify` (banner), `loki proof show <id>` and `loki proof verify <id> --human` print a compact summary of about 12 lines: the label, revision and freshness, environment, integrity, check counts with the checks that did not pass, requirement coverage, modified tests, and the signature caveat. Pass `--json` to `loki proof show` for the full record.
+
+### Compatibility
+
+- Exit codes are unchanged: `loki verify` keeps its verdict-based codes; `loki proof verify` keeps 0 clean, 1 tamper or drift, 2 unusable.
+- Existing JSON fields are untouched. `verification` is additive.
+- Receipts written before this contract lack `facts.environment` and `facts.git.dirty`. They report environment `not recorded` and may report freshness `unknown`.
+- `loki proof show <id>` used to print the raw JSON. Scripts that parsed it must now pass `--json`.