loki-mode 11.3.9 → 11.4.2

package/completions/_loki

@@ -64,8 +64,52 @@ function _loki {
                 doctor)
                     _arguments \
                         '--json[Output machine-readable JSON]' \
+                        '--fix[Create state dirs and a default config]' \
                         '--help[Show help]'
                     ;;
+                chat)
+                    _arguments \
+                        '--attach[Attach to a running session]' \
+                        '--tui[Use the terminal UI]' \
+                        '--help[Show help]'
+                    ;;
+                agents)
+                    _arguments \
+                        '1:subcommand:(list new show export)' \
+                        '--claude[Export to .claude/agents]' \
+                        '--user[Use the user-level agents directory]' \
+                        '--help[Show help]'
+                    ;;
+                models)
+                    _arguments \
+                        '--local[Show local models]' \
+                        '--json[Output machine-readable JSON]' \
+                        '--help[Show help]'
+                    ;;
+                setup)
+                    _arguments \
+                        '--yes[Non-interactive defaults]' \
+                        '--check[Report only]' \
+                        '--help[Show help]'
+                    ;;
+                route)
+                    _arguments \
+                        '1:verb:(start quick)' \
+                        '--json[Output machine-readable JSON]' \
+                        '--provider[AI provider]:provider name:(claude cline codex aider opencode)' \
+                        '--model[Model or route override]:model:' \
+                        '--no-pr[Skip the pull request]' \
+                        '--max-cost[Spend cap in USD]:amount:' \
+                        '--help[Show help]'
+                    ;;
+                edit)
+                    _arguments \
+                        '--verify[Run verification after the edit]' \
+                        '--commit[Commit the edit]' \
+                        '--dry-run[Describe the change only]' \
+                        '--help[Show help]' \
+                        '*:file:_files'
+                    ;;
                 reset)
                     _loki_reset
                     ;;
@@ -219,6 +263,13 @@ function _loki_commands {
         'queue:Overnight issue queue with a morning digest'
         'issues:Run every open issue in a repo and open PRs'
         'undo:Show what undoing a run would do (read-only plan)'
+        'chat:Interactive chat session (run, attach)'
+        'route:Print the engine, provider and model route without running'
+        'edit:Make a scoped edit to files'
+        'setup:First-run wizard for tools, provider, model route and spend cap'
+        'models:List models and routes (--local for local models)'
+        'agents:List, scaffold, show and export agent definitions'
+        'diff:Show what the last run changed'
         'control:Control plane (preview, LOKI_CONTROL=1)'
         'workspace:Multi-project workspaces (preview, LOKI_WORKSPACES=1)'
         'backlog:Run every matching open issue, N in parallel'
@@ -275,6 +326,10 @@ function _loki_start {
         '--yes[Skip confirmation prompts]' \
         '-y[Skip confirmation prompts]' \
         '--budget[Cost budget limit in USD]:amount:' \
+        '--model[Model or route override]:model:' \
+        '--max-cost[Spend cap in USD]:amount:' \
+        '--no-pr[Build and verify without opening a pull request]' \
+        '--explain-route[Print the route without running]' \
         '--max-iterations[Max iterations]:number:' \
         '--attempts[Independent attempts in worktrees, 1-5]:number:(1 2 3 4 5)' \
         '*:spec file:_loki_spec_files'

package/completions/loki.bash

@@ -5,7 +5,7 @@ _loki_completion() {
     _init_completion || return
 
     # Main subcommands (must match autonomy/loki main case statement)
-    local main_commands="start backlog quick monitor demo tour welcome init stop pause resume steer status next ship dashboard web serve api sandbox notify import github issue intent config provider reset memory compound checkpoint council dogfood projects enterprise secrets cockpit secure own handoff doctor watchdog audit metrics syslog onboard share proof receipt outcomes explain plan report cost estimate kpis stats test ci watch telemetry agent context ctx code run export review optimize heal modernize migrate cluster worktree wt trigger failover remote deploy docker mcp magic assets analyze compliance crash control workspace open otel preview quickstart rc rollback merge self-update sentrux setup-skill spec state template trust trust-metrics ultracode update verify voice why wiki bench cleanup logs grill docs cp version completions help keys answer queue issues undo acp verify-pr"
+    local main_commands="start backlog quick monitor demo tour welcome init stop pause resume steer status next ship dashboard web serve api sandbox notify import github issue intent config provider reset memory compound checkpoint council dogfood projects enterprise secrets cockpit secure own handoff doctor watchdog audit metrics syslog onboard share proof receipt outcomes explain plan report cost estimate kpis stats test ci watch telemetry agent context ctx code run export review optimize heal modernize migrate cluster worktree wt trigger failover remote deploy docker mcp magic assets analyze compliance crash control workspace open otel preview quickstart rc rollback merge self-update sentrux setup-skill spec state template trust trust-metrics ultracode update verify voice why wiki bench cleanup logs grill docs cp version completions help keys answer queue issues undo acp verify-pr chat route edit setup models agents diff"
 
     # 1. If we are on the first argument (subcommand)
     if [[ $cword -eq 1 ]]; then
@@ -27,7 +27,7 @@ _loki_completion() {
 
             # If the word starts with a dash, show flags
             if [[ "$cur" == -* ]]; then
-                local flags="--provider --max-iterations --parallel --background --bg --simple --complex --github --no-dashboard --sandbox --skip-memory --spec --spec-first --yes --budget --attempts --help"
+                local flags="--provider --max-iterations --parallel --background --bg --simple --complex --github --no-dashboard --sandbox --skip-memory --spec --spec-first --yes --budget --attempts --model --isolation --max-cost --no-pr --explain-route --help"
                 COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
                 return 0
             fi
@@ -125,7 +125,53 @@ _loki_completion() {
 
         doctor)
             if [[ "$cur" == -* ]]; then
-                COMPREPLY=( $(compgen -W "--json --help" -- "$cur") )
+                COMPREPLY=( $(compgen -W "--json --fix --help" -- "$cur") )
+                return 0
+            fi
+            ;;
+
+        chat)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "--attach --tui --help" -- "$cur") )
+                return 0
+            fi
+            ;;
+
+        agents)
+            if [[ $cword -eq 2 ]]; then
+                COMPREPLY=( $(compgen -W "list new show export" -- "$cur") )
+            elif [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "--claude --user --help" -- "$cur") )
+            fi
+            return 0
+            ;;
+
+        models)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "--local --json --help" -- "$cur") )
+                return 0
+            fi
+            ;;
+
+        setup)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "--yes --check --help" -- "$cur") )
+                return 0
+            fi
+            ;;
+
+        route)
+            if [[ $cword -eq 2 ]]; then
+                COMPREPLY=( $(compgen -W "start quick" -- "$cur") )
+            elif [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "--json --provider --model --no-pr --max-cost --help" -- "$cur") )
+            fi
+            return 0
+            ;;
+
+        edit)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "--verify --commit --dry-run --help" -- "$cur") )
                 return 0
             fi
             ;;

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "11.3.9"
+__version__ = "11.4.2"
 
 # Expose the control app for easy import
 try:

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.4.2. Do not edit by hand.
 Hidden and legacy-only commands are omitted; see `docs/v10/CLI-MODERN.md` for the full inventory.
 
 | Command | Description |
@@ -74,6 +74,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 +95,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/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.4.2
 
-**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,6 @@
 
 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 |
-
-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).
-
-## `loki start` uses the older engine
-
-`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>"`.
+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`, or for one call when a flag Loki 10 cannot honor is present (`--simple`, `--parallel`, `--sandbox`, ...). Check with `loki route start <args>`.

package/docs/QUICKSTART.md

@@ -0,0 +1,108 @@
+# Quickstart (5 minutes)
+
+`loki start` is the primary path. This page gets you from install to a
+verified result, then shows the interactive alternative and the small-change
+path.
+
+## 1. Install
+
+```bash
+npm install -g loki-mode
+```
+
+You need Node.js 18+ (20+ recommended), Python 3.8+, git, jq and curl. Claude
+Code (`claude`) is the default provider and is needed for the default path:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude auth login
+```
+
+Other coding CLIs (codex, cline, aider, opencode) are optional. Full list:
+[INSTALLATION.md](INSTALLATION.md).
+
+## 2. Set up
+
+```bash
+cd your-repo
+loki setup          # checks tools, Claude login, provider, model route, spend cap
+```
+
+`loki setup --yes` accepts defaults. `loki doctor --fix` creates state
+directories and a default config and prints exact commands for anything
+missing; it never runs sudo.
+
+## 3. Run
+
+```bash
+loki start "add rate limiting to /api/login"
+```
+
+Also accepted: `loki start prd.md`, `loki start owner/repo#123`, and a
+one-word brief as `loki start <word>`. Add `--no-pr` to skip the pull request.
+Preview the route first with `loki route start prd.md`.
+
+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>`.
+
+## 4. Read the summary
+
+Every run ends with one block:
+
+```
+Result:   verified
+Files:    3 changed (+42 -5)
+Cost:     $0.42
+Elapsed:  4m12s
+Receipt:  .loki/runs/<run-id>/receipt.json
+next:     loki diff
+```
+
+`Cost` reads `(estimated)` when the provider did not report it and `not
+measured` when unknown. The `next:` line names the one command to run now.
+`loki verify` re-checks the receipt; `loki undo` reverts the run. Exit codes
+are in [exit-codes.md](exit-codes.md): usage errors are 64, and a CI gate
+should be `loki verify || fail`.
+
+## 5. Talk to a run: loki chat --attach
+
+```bash
+loki chat --attach     # joins the running or last `loki start` session
+```
+
+Inside: `/status`, `/steer <text>`, `/diff`, `/verify`, `/receipt`, `/stop`.
+`loki chat` on its own is the interactive alternative: it starts in Plan mode
+(read-only), `/build` allows edits, and `/run <brief>` starts a normal
+`loki start` run with the chat's model and provider. Bare `loki` does not open
+chat.
+
+## 6. Small changes: loki edit
+
+```bash
+loki edit "rename fooBar to foo_bar"
+loki edit src/foo.ts "rename X to Y"
+loki edit --verify --commit src/a.ts "add null checks"
+```
+
+One pass, no plan, council or PR. It prints the diff and one line with cost and
+time. Use `loki quick "<task>"` when you want a verify loop.
+
+## 7. Local and other models
+
+```bash
+loki models --local                              # finds Ollama, LM Studio, llama.cpp, vLLM
+LOKI_MODEL_ROUTE=ollama/qwen3-coder loki start prd.md
+LOKI_MODEL_ROUTE=openrouter/deepseek/deepseek-v3.2 loki start prd.md   # needs OPENROUTER_API_KEY
+loki start --provider codex prd.md               # another coding CLI
+```
+
+Routes: `openrouter`, `ollama`, `lmstudio`, `llamacpp`, `vllm`, and `custom`
+(set `LOKI_MODEL_BASE_URL`). They run through the Claude harness, so cost,
+kill blocking and receipts still apply.
+
+## Next
+
+[User guide](v10/GUIDE.md), [core verbs](CLI-CORE-VERBS.md),
+[custom agents](v10/GUIDE.md#custom-agents), [comparison with
+opencode](COMPARE-OPENCODE.md).