loki-mode 8.5.2 → 8.6.1

package/autonomy/verify.sh

@@ -39,12 +39,23 @@
 #   2  BLOCKED
 #   3  verifier error (could not complete; never silently passes)
 #
-# NOTE on exit-code divergence from the spec: spec Section 1.1 lists
-# 0=VERIFIED, 1=BLOCKED, 2=CONCERNS, 3=error (BLOCKED and CONCERNS swapped
-# vs this implementation). This module follows the explicit BUILD TASK
-# ordering (0/1/2 = VERIFIED/CONCERNS/BLOCKED). A human must reconcile the
-# two before the GitHub App (Phase 2) consumes exit codes. The divergence is
-# surfaced in `loki verify --help`.
+# EXIT-CODE ORDERING, RECONCILED. An early draft spec listed
+# 0=VERIFIED, 1=BLOCKED, 2=CONCERNS, and this header used to say a human must
+# reconcile the two before the GitHub App consumed exit codes. That is now
+# done, in favor of THIS implementation: 0/1/2/3 =
+# VERIFIED/CONCERNS/BLOCKED/error.
+#
+# Why this ordering wins. The code is authoritative and always has been
+# (VERIFY_EXIT_* below), `loki verify --help` documents it, and
+# wiki/CLI-Reference.md documents it. The draft spec that said otherwise is not
+# in this repository and has no consumers. Renumbering working code to match an
+# absent document would break every existing caller to satisfy nothing.
+#
+# It is also the ordering an integrator expects: severity rises with the code,
+# so `[ $rc -ge 2 ]` means "at least blocked". The reverse would make 1 more
+# severe than 2, which no one guesses correctly.
+#
+# See docs/exit-codes.md for the exit codes of every command.
 
 set -uo pipefail
 
@@ -1810,6 +1821,7 @@ verify_emit_evidence() {
     _VERIFY_GATES="$_VERIFY_GATES_FILE" \
     _V_VERDICT="$VERIFY_VERDICT" \
     _V_EXIT="$VERIFY_EXIT" \
+    _V_JSON_STDOUT="${VERIFY_JSON:-0}" \
     _V_SCHEMA="$VERIFY_SCHEMA_VERSION" \
     _V_TOOLVER="$tool_version" \
     _V_REPO="$repo_name" \
@@ -1833,7 +1845,7 @@ verify_emit_evidence() {
     _V_SCOPE_MAX_FILES="${VERIFY_SCOPE_MAX_FILES:-}" \
     _V_SCOPE_MAX_NET="${VERIFY_SCOPE_MAX_NET_LINES:-}" \
     python3 - <<'PYEOF'
-import json, os, hashlib
+import json, os, hashlib, sys
 
 out_dir = os.environ["_VERIFY_OUT_DIR"]
 findings_file = os.environ["_VERIFY_FINDINGS"]
@@ -1959,6 +1971,27 @@ with open(ev_path, "w") as f:
     json.dump(doc, f, indent=2)
     f.write("\n")
 
+# --json emits the SAME document to stdout. Deliberately the same `doc` rather
+# than a second serializer: two writers of one contract drift, and the drift
+# shows up as a caller trusting a field the file no longer has. The evidence
+# file is still written either way, so --json adds a pipe without removing the
+# artifact.
+#
+# Written to FD 3, not stdout. The caller redirects this function's stdout to
+# /dev/null (it emits progress chatter the human path does not want), so a
+# plain stdout write here is discarded. FD 3 is opened by the caller only under
+# --json and routed to the real stdout.
+if os.environ.get("_V_JSON_STDOUT") == "1":
+    try:
+        with os.fdopen(os.dup(3), "w") as _jf:
+            _jf.write(json.dumps(doc, indent=2) + "\n")
+    except OSError:
+        # FD 3 not open: --json was requested but the caller did not wire it.
+        # Fail loudly rather than exit 0 having emitted nothing, which would
+        # look to a pipeline like a verify that produced an empty document.
+        sys.stderr.write("verify: --json requested but FD 3 is not open\n")
+        raise SystemExit(3)
+
 # ----- Markdown report -----
 def sev_rank(s):
     return {"Critical": 0, "High": 1, "Medium": 2, "Low": 3, "Info": 4}.get(s, 5)
@@ -2050,6 +2083,11 @@ OPTIONS:
                        Default: critical,high  (one notch looser than the
                        Loki build loop, which also blocks on medium).
     --no-llm           Accepted for forward-compat; LLM is already off in MVP.
+    --json             Emit the evidence document to stdout so it can be piped
+                       (`loki verify --json | jq .verdict`). The same document
+                       is still written to <out>/evidence.json. The human
+                       VERDICT banner moves to stderr so stdout stays valid
+                       JSON. The verdict and exit code are unchanged.
     --explain          Print a one-screen, skeptic-legible trust proof: every
                        gate that ran, its status, the runner/scanner that
                        produced the evidence, whether it is reproducible, plus
@@ -2093,16 +2131,16 @@ VERDICT MODEL:
     Uncommitted working-tree changes are not verified; commit them first. An
     empty diff yields CONCERNS (nothing to verify), never VERIFIED.
 
-EXIT CODES (this implementation):
+EXIT CODES:
     0  VERIFIED
     1  CONCERNS
     2  BLOCKED
     3  verifier error (could not complete; never silently passes)
 
-    NOTE: the verification spec (Section 1.1) lists 1=BLOCKED, 2=CONCERNS.
-    This implementation follows the build-task ordering (1=CONCERNS,
-    2=BLOCKED). A human must reconcile the two before the GitHub App consumes
-    these codes.
+    Severity rises with the code, so `[ $rc -ge 2 ]` means "at least blocked".
+    An early draft spec listed 1=BLOCKED, 2=CONCERNS; that ordering was
+    rejected and is not used anywhere. See docs/exit-codes.md for every
+    command's codes.
 
 OUTPUT:
     <out>/evidence.json   consolidated machine-readable evidence (schema 1.0)
@@ -2620,6 +2658,8 @@ verify_main() {
     # verify does NOT re-run gates: it reads a prior evidence.json and fails
     # closed if the repo has drifted since that evidence was graded.
     VERIFY_CHECK_FRESH=0
+    # Opt-in machine-readable stdout (--json). Default 0 = exactly today.
+    VERIFY_JSON=0
 
     # Fail-closed defaults. These globals are read at the end of this function
     # (the VERDICT banner and the function return code). verify_compute_verdict()
@@ -2644,6 +2684,16 @@ verify_main() {
                 block_on="$(printf '%s' "${2:-}" | tr '[:upper:]' '[:lower:]')"; shift 2 ;;
             --no-llm)
                 shift ;;
+            --json)
+                # Emit the evidence document to STDOUT so a caller can pipe it.
+                # The same document is still written to <out>/evidence.json --
+                # this adds a pipe, it does not move the artifact.
+                #
+                # Implies --quiet-banner: stdout must be JSON and nothing else,
+                # or `loki verify --json | jq` breaks on the human banner. The
+                # banner still goes to stderr, so an operator watching a
+                # terminal loses nothing.
+                VERIFY_JSON=1; shift ;;
             --explain)
                 # Render a one-screen, skeptic-legible trust proof: every gate
                 # that ran, its status, the runner/scanner that produced the
@@ -2793,10 +2843,21 @@ verify_main() {
 
     completed_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 
-    verify_emit_evidence "$out_dir" "$started_at" "$completed_at" "$block_on" >/dev/null || {
-        _verify_err "failed to emit evidence document"
-        return $VERIFY_EXIT_ERROR
-    }
+    # stdout is discarded (the emitter's own chatter is not wanted on the human
+    # path). Under --json, FD 3 is opened onto the REAL stdout so the emitter
+    # can write the evidence document there while everything else stays
+    # suppressed -- that is what keeps `loki verify --json | jq` parseable.
+    if [ "${VERIFY_JSON:-0}" = "1" ]; then
+        verify_emit_evidence "$out_dir" "$started_at" "$completed_at" "$block_on" 3>&1 >/dev/null || {
+            _verify_err "failed to emit evidence document"
+            return $VERIFY_EXIT_ERROR
+        }
+    else
+        verify_emit_evidence "$out_dir" "$started_at" "$completed_at" "$block_on" >/dev/null || {
+            _verify_err "failed to emit evidence document"
+            return $VERIFY_EXIT_ERROR
+        }
+    fi
 
     # Opt-in (--hosted): fold the embedded Autonomi Verify engine's verdict
     # fields into the just-written evidence.json. Fully additive and fail-open:
@@ -2814,9 +2875,14 @@ verify_main() {
         _verify_render_explain "$started_at" "$completed_at" "$VERIFY_VERDICT"
     fi
 
-    printf 'VERDICT: %s\n' "$VERIFY_VERDICT"
-    printf 'Evidence: %s/evidence.json\n' "$out_dir"
-    printf 'Report:   %s/report.md\n' "$out_dir"
+    # Under --json stdout carries the evidence document alone, so the human
+    # banner is redirected to stderr rather than dropped: an operator watching a
+    # terminal still sees the verdict, and `| jq` still parses.
+    _v_banner_fd=1
+    [ "${VERIFY_JSON:-0}" = "1" ] && _v_banner_fd=2
+    printf 'VERDICT: %s\n' "$VERIFY_VERDICT" >&$_v_banner_fd
+    printf 'Evidence: %s/evidence.json\n' "$out_dir" >&$_v_banner_fd
+    printf 'Report:   %s/report.md\n' "$out_dir" >&$_v_banner_fd
     # --hosted only: surface the enrichment in human output so the extra signal
     # is visible without parsing JSON. Printed solely when a fold succeeded;
     # the default path never sets VERIFY_HOSTED_SUMMARY, so it stays byte-identical.

package/completions/_loki

@@ -153,6 +153,7 @@ function _loki_commands {
         'memory:Memory commands'
         'compound:Knowledge compounding commands'
         'checkpoint:Snapshot and restore session state'
+        'cp:Snapshot and restore session state (alias of checkpoint)'
         'council:Completion council commands'
         'dogfood:Self-development statistics'
         'projects:Project registry commands'

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 quick monitor demo tour welcome init stop pause resume steer status next ship dashboard web serve api sandbox notify import github issue config provider reset memory compound checkpoint council dogfood projects enterprise secrets cockpit secure own doctor watchdog audit metrics syslog onboard share proof explain plan report cost 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 open otel preview quickstart rc rollback 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"
+    local main_commands="start quick monitor demo tour welcome init stop pause resume steer status next ship dashboard web serve api sandbox notify import github issue config provider reset memory compound checkpoint council dogfood projects enterprise secrets cockpit secure own handoff doctor watchdog audit metrics syslog onboard share proof receipt explain plan report cost 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 open otel preview quickstart rc rollback 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"
 
     # 1. If we are on the first argument (subcommand)
     if [[ $cword -eq 1 ]]; then

package/dashboard/__init__.py

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

package/docs/EVALUATING.md

@@ -154,6 +154,34 @@ expose something the CLI does not. If a competitor does ship output
 verification, this test is how we would find out, and the claim above would be
 corrected rather than defended.
 
+## 7. Headless latency, five trials per tool
+
+Same task, same machine, artifact verified by content, five trials each:
+
+| CLI | Success | Median | Range |
+| --- | --- | --- | --- |
+| opencode 1.18.9 | 5/5 | 11s | 4s to 265s |
+| codex-cli 0.146.0 | 4/5 | 69s | 48s to 80s (one 300s timeout) |
+
+**Read the range, not just the median.** opencode's first trial took 265
+seconds and the next four took 4 to 12. A new user experiences the 265, not the
+11. Reporting only the median would hide the thing they will actually feel.
+
+**The timeout is kept in.** Dropping codex's one failure would turn 4-of-5 into
+an implied 5-of-5 and overstate reliability.
+
+**Five trials, not one, and that is the point.** An earlier single-shot run of
+this same codex command timed out, and publishing it would have recorded
+"codex: timeout" as a fact about a competitor when the identical command
+completed in 51 seconds minutes later. The spread is the finding.
+
+**What this does not measure.** One trivial file-creation task is not a proxy
+for build quality, multi-iteration work, or brownfield capability. It measures
+headless invocation latency and nothing else. aider, Claude Code and
+cursor-agent have not been run on this task; Devin and Replit Agent ship no
+local CLI. Cost is not compared: codex ran on a free tier and opencode's
+per-call cost was not recorded.
+
 ---
 
 ## What we do not have

package/docs/PRIVACY.md

@@ -114,10 +114,33 @@ it sits below the base telemetry gate, every telemetry opt-out (`loki telemetry
 off` / `LOKI_TELEMETRY=off` / `DO_NOT_TRACK=1`) also disables it -- opt-out
 always wins.
 
+### 5. First-run blocker (anonymous, STRICT opt-in, default OFF)
+
+A `first_run_blocked` event naming which CLASS of dependency stopped a first
+run, sent at most ONCE per install. It sits behind the same strict second
+opt-in as build-outcome analytics above (`LOKI_ANALYTICS=on`), so it is off by
+default even with telemetry enabled.
+
+It exists because we could see that a first run was ATTEMPTED and nothing about
+whether it succeeded, which made "why does a trial not convert" unanswerable.
+A real example we found and fixed: on a machine with no AI provider CLI, one
+route ended with a dead end instead of pointing at `loki tour` (which needs no
+provider, no key and no spend). Nobody could see that happening.
+
+The ONLY field is `blocker`, clamped to this fixed enum:
+
+    no_provider | node | python3 | jq | git | curl | disk | skill_symlink | other
+
+Anything not on that list becomes `other`. It is deliberately coarse: `node` is
+enough to act on, and a version string or an install path would be a leak. It
+NEVER sends paths, versions, hostnames, spec text, or command lines -- a test
+(`tests/test-first-run-blocked-signal.sh`) feeds a filesystem path through the
+real emitter and fails the build if anything but `other` reaches the payload.
+
 This document and the first-run notice describe ALL paths. The model is unified:
 opt-out always wins and disables everything; crash reporting and usage telemetry
-opt in together (default ON for individuals); build-outcome analytics needs its
-own explicit second opt-in on top (default OFF).
+opt in together (default ON for individuals); build-outcome analytics and the
+first-run blocker each need an explicit second opt-in on top (default OFF).
 
 ## What is collected (the whitelist)
 

package/docs/STRATEGY-2026-2028.md

@@ -0,0 +1,124 @@
+# Two-year adoption strategy
+
+Written 2026-07-31 from measured inputs: registry download data, competitor
+documentation fetched the same day, and benchmark results from this repository.
+Where a claim is inference rather than measurement, it says so.
+
+## The one number that matters
+
+**Floor: ~94 downloads/day. Peak: 1,263.** The 13x swing tracks our own
+release activity -- eight releases landed on 07-30. A curve that rises when we
+publish and falls when we stop is CI and mirrors, not word of mouth.
+
+Organic growth is a **rising floor**. Everything below is judged against that
+single number, measured on days we ship nothing.
+
+Two years from now the question is not "how many releases did we cut." It is
+"what is the floor, and does it rise when we are quiet."
+
+## What we actually sell, stated so it survives a demo
+
+Competitor documentation, fetched 2026-07-31:
+
+- **Lovable** runs a security scan on every publish and admins can block the
+  publish outright.
+- **Claude Code** has a review step that checks findings against actual code
+  behavior.
+- **Replit** says its agent tests its own work.
+
+So **"we verify and they don't" is false**, and a founder demo against Lovable
+would expose it. That framing is retired.
+
+What is true and unoccupied across all seven competitors: **nobody ships a
+persisted, portable, diff-bound artifact.** Theirs live in a dashboard --
+Lovable's is a findings count in a dialog, Claude Code's check run is
+deliberately non-blocking. Ours is a file: bound to a diff by `diff_sha256`,
+recording what was NOT proven as prominently as what was, verifiable by someone
+who never installed us.
+
+That is the sentence. Portable, diff-bound, honest about gaps.
+
+## The second thing we sell, now measured
+
+**The harness carries quality, not the model.** On `hard-2-ledger`, a task
+authored so a bare model fails it:
+
+| arm | result | cost |
+|---|---|---|
+| haiku, harness off | 1/4 passed | $0.86 |
+| haiku, harness on | 1/1 passed | $0.54 |
+
+Same model. Same prompt. The harness is the only variable. A correct
+implementation cost **less** than the failing ones, because a cheap failure is
+not cheap.
+
+Caveat, stated because it will be checked: n is small and trials are still
+accumulating. This demonstrates the mechanism. The rate needs more trials, and
+those are now worth buying -- before this task existed, the baseline passed
+everything and more trials bought precision around a ceiling.
+
+## Where we win, and where we should not fight
+
+**Do not fight on:** hosted preview URLs, visual editing, zero-install browser
+onboarding, managed backend primitives. Those are structural properties of a
+hosted product. Lovable publishes to `[name].lovable.app` free at zero credit
+balance; we cannot and should not try.
+
+**Win on the three axes competitors structurally cannot occupy:**
+
+1. **Air-gapped operation.** Measured with egress severed: `version`, `doctor`,
+   `plan --json`, `proof verify`, `heal --assess` all return real results. No
+   competitor can do this -- "Devin's brain always resides within Cognition's
+   Cloud." For defence, government, and regulated banking this is winnable on
+   this axis alone. One required egress (model inference), disclosed.
+
+2. **In-place brownfield.** Lovable **cannot import an existing repository at
+   all**. Replit and Cursor import into *their* environment. For a private
+   monorepo with internal dependencies, that is frequently not permitted. We
+   run where the code already lives.
+
+3. **Cost per correct result.** Haiku-plus-harness beat opus-baseline in the
+   aggregate at roughly an eighth the cost. If that holds under more trials, it
+   is a procurement argument, not a benchmark curiosity.
+
+## The two-year sequence
+
+**Year 1, first half -- earn the floor.** Every item judged by whether a first
+run reaches a result. Ship `first_run_blocked` (done, v8.6.0), read what it
+says, fix the top blocker, repeat. The floor is the scoreboard.
+
+Concretely already done and testable: 43 of 112 commands were unreachable from
+`loki help` including `loki proof`; a first-run dead end on provider-less hosts;
+`loki proof md` so the receipt travels into a PR or Slack.
+
+**Year 1, second half -- make the receipt the artefact people forward.** A
+receipt in a PR is a person showing a colleague. That is the only word-of-mouth
+mechanic available to a CLI, and it costs no infrastructure.
+
+**Year 2 -- enterprise pull, not push.** Air-gapped + in-place brownfield +
+signed provenance is a procurement story no competitor can match today. It sells
+to the buyer who cannot use the others at all, and those buyers talk to each
+other.
+
+## What would falsify this
+
+Stated so it is checkable rather than reassuring:
+
+- **The floor does not rise** over the next quarter despite first-run fixes ->
+  the bottleneck is not discoverability, and this plan is wrong.
+- **`first_run_blocked` shows trials dying on something we did not predict** ->
+  follow the data, not this document.
+- **The harness lift does not survive more trials** -> the cost argument
+  collapses and the differentiator narrows to portability alone.
+- **A competitor ships a portable signed receipt** -> the wedge is gone and we
+  compete on cost and air-gap only.
+
+## What is deliberately not here
+
+No 80-item backlog. The items that exist are the ones with a measured
+mechanism. Padding this list to look comprehensive would be the fabrication
+this project has already paid for once.
+
+Release cadence is explicitly **not** a growth lever: eight releases in one day
+produced a 1,263 spike and a 94 floor. If the floor is the goal, cadence is
+noise.

package/docs/adoption-baseline-2026-07-31.md

@@ -0,0 +1,84 @@
+# Adoption baseline, 2026-07-31
+
+The first numbers in this project taken from the registry rather than from
+intuition. Recorded so the next measurement has something to compare against.
+
+## What we actually have
+
+**4,456 npm downloads in the last 7 days.** Daily:
+
+| Day | Downloads |
+|---|---|
+| 07-24 | 863 |
+| 07-25 | 1,160 |
+| 07-26 | 196 |
+| 07-27 | 94 |
+| 07-28 | 386 |
+| 07-29 | 494 |
+| 07-30 | 1,263 |
+
+Two things follow, and the second matters more than the first.
+
+**1. We have users.** Roughly 4.5k downloads a week is not a project nobody
+has heard of. Every strategy discussion in this repo has proceeded as though
+adoption were hypothetical. It is not.
+
+**2. The shape is release-driven, not organic.** The 13x swing between 07-27
+(94) and 07-30 (1,263) tracks publishing activity -- eight releases landed on
+07-30 alone. A curve that rises when we publish and falls when we stop is
+mirrors and CI, not word of mouth. Organic growth would show a floor that
+rises over time; this shows a floor near 94.
+
+**Do not read 4,456 as 4,456 humans.** npm counts mirrors, CI, and Docker
+layer pulls. The honest statement is that the ceiling is real and the floor is
+what needs to move.
+
+## Why the floor is the metric
+
+The founder's goal is word-of-mouth growth over two years. The number that
+measures it is the **trough**, not the peak: how many installs happen on a day
+we publish nothing. Today that is ~94.
+
+Peaks are bought with releases. Floors are earned by people telling other
+people. Every adoption item should be judged against whether it moves the
+floor.
+
+## What we still cannot see, and what changed today
+
+Until v8.6.0 shipped this morning, we could see that a first run was ATTEMPTED
+and nothing about whether it succeeded. `first_run_blocked` (v8.6.0) now names
+the class of dependency that stops a first run -- enum-clamped, once per
+install, strict opt-in.
+
+That data does not exist yet: the release is hours old and the telemetry is
+off by default behind a second opt-in. It will accumulate slowly and from a
+minority of users, which is the correct trade for not exfiltrating anyone's
+environment.
+
+So the sequence is: floor today ~94/day -> ship things that plausibly move it
+-> watch the floor, not the peak.
+
+## The three things measured this session that plausibly move it
+
+Ranked by how directly they affect someone's first ten minutes:
+
+1. **43 of 112 commands were unreachable from `loki help`**, including
+   `loki proof` -- the Evidence Receipt, the thing the product argues on. Fixed
+   and gated. A user who cannot find the differentiator does not repeat it to
+   anyone.
+2. **A first-run dead end on hosts with no provider CLI.** One route named the
+   blockers and pointed at `loki tour` (no provider, no key, no spend); the
+   other said "some required prerequisites are missing" and stopped. That is
+   the exact moment an evaluator decides whether to continue.
+3. **`loki proof md`** puts the receipt in a form a person can paste into a PR
+   or a Slack message. Competitors' verification output lives in their
+   dashboard; a file is the only artifact that travels.
+
+None of these is proven to move the floor. They are the candidates with a
+plausible mechanism, and the floor is now being watched.
+
+## Reproduce
+
+```sh
+curl -s "https://api.npmjs.org/downloads/range/last-week/loki-mode"
+```

package/docs/air-gapped.md

@@ -0,0 +1,91 @@
+# Running without egress
+
+If your code cannot leave your network, most of this category is unavailable to
+you regardless of what the sales conversation suggests.
+
+## Where the tools actually stand
+
+Verified from vendor documentation, 2026-07-31:
+
+| Tool | Air-gapped |
+|---|---|
+| Devin | **No.** Single-tenant VPC via AWS PrivateLink, customer-managed KMS, a federal docs tree -- but "Devin's brain... always resides within Cognition's Cloud." |
+| Cursor | No. Cloud service; embeddings are uploaded (obfuscated and encrypted). |
+| Claude Code | Partly. Runs against Bedrock / Vertex / Foundry in your own cloud, so data residency is yours -- but a model endpoint is still required. |
+| Lovable, Replit, Emergent | No. Browser products on their infrastructure. |
+| opencode | Structurally yes (MIT, self-hostable) -- but no SOC2, SSO, audit logs, or support. |
+
+Devin's is the strongest enterprise packaging in the category and it still
+cannot run disconnected. That is a structural property of a hosted control
+plane, not an oversight.
+
+## What we measured
+
+Executed 2026-07-31 with outbound HTTP forced through an unroutable proxy --
+not a flag, not an assumption. Every one of these returned a real result with
+egress severed:
+
+| Command | Result |
+|---|---|
+| `loki version` | works |
+| `loki doctor --json` | works |
+| `loki plan <spec> --json` | works -- full cost and complexity estimate |
+| `loki proof list` | works |
+| `loki proof verify <id>` | works, and correctly reported `tree_drift: true` |
+| `loki heal <repo> --assess --json` | works -- maturity, ranked targets, runtime |
+
+The whole evaluate-before-you-buy path runs disconnected. You can assess a
+legacy codebase, estimate what a build would cost, and verify an existing
+receipt without a single packet leaving the machine.
+
+`loki proof verify` deserves emphasis: an auditor can re-check a receipt against
+the repository offline and get a genuine verdict, including detecting drift.
+That is the property competitors' dashboard-bound verification cannot have.
+
+## The one required egress, stated plainly
+
+```sh
+loki doctor --airgap
+```
+
+prints the egress inventory. Today it reports exactly one REQUIRED point:
+
+```
+REQUIRED  model inference -> https://api.anthropic.com
+          Set ANTHROPIC_BASE_URL to an in-network gateway, or switch to a
+          local-weights provider.
+optional  telemetry  [off]  disable: loki telemetry off (default off)
+```
+
+**We cannot run a build with no model at all.** Nobody can. What we can do is
+let you point at a model you host: set `ANTHROPIC_BASE_URL` to an in-network
+gateway, or run a provider with local weights. The engine abstracts over CLIs
+rather than over one vendor's API.
+
+Telemetry is off by default and every opt-out wins (`DO_NOT_TRACK=1`,
+`LOKI_TELEMETRY=off`, `~/.loki/config`). The adoption instrumentation added in
+v8.6.0 requires a second explicit opt-in on top of that -- see
+[PRIVACY.md](./PRIVACY.md).
+
+## Why `unknown` is the right answer offline
+
+`loki heal --assess` reports `dependency_staleness: unknown` and always will
+without a network call. We know your manifest pins lodash 3.x; we do not know
+what is current upstream, and we will not guess.
+
+That refusal is what makes the assessment trustworthy inside a disconnected
+network. A tool that fabricates a staleness number offline is more dangerous
+than one that declines.
+
+## Honest limits
+
+- **A model endpoint is required.** If you have no model at all -- not local,
+  not in-network -- we cannot build anything, and neither can anyone else.
+- **The five mutating healing phases need a provider.** Only `--assess` is
+  genuinely zero-dependency.
+- **Not measured here:** a full disconnected build against a local-weights
+  provider. The commands above were measured; that one was not, and this page
+  does not claim it.
+
+See [Kubernetes air-gapped install](../deploy/helm/README.md) for the
+cluster-side path.