feat(local): prove first local inference

Refresh the local discovery and first-inference proof on the merged Router base. Add ADR 0086 to make operator-owned runtime state and genuine loaded-model evidence explicit; retain bounded prompt-free receipts and fail closed when local delivery is not proven.

[roadmap:WF-ROADMAP-0017]

Author: tcballard

CHANGELOG.md

@@ -8,6 +8,18 @@ details, release history over commit history.
 
 ### Added
 
+- **Operator-owned local runtime proof** (WF-ADR-0086). Local discovery and
+  first-inference checks distinguish configured from genuinely proven delivery;
+  mocks validate only the contract and never stand in for loaded-model evidence.
+
+- **Proven local first run** (WF-ADR-0087, issue #207). The Router can discover
+  model IDs only from fixed literal-loopback runtime catalogs and run one fixed
+  public inference probe. The versioned probe succeeds only when the matching
+  bounded receipt proves a terminal on-device or local-network delivery; it
+  emits no response text, credentials, repository paths, tool arguments, or
+  private reasoning and never installs, pulls, selects, or activates a model
+  silently.
+
 - **Prompt-free outcomes and review-only local policy proposals** (WF-ADR-0085,
   issue #207). Authenticated local operators can attach an explicit success,
   correction, or failure to a retained terminal workspace receipt without

README.md

@@ -13,10 +13,15 @@ Install the flagship Omarchy experience:
 omarchy plugin add https://github.com/asdecided/omarchy-wayfinder.git
 cd ~/.config/omarchy/plugins/io.github.asdecided.wayfinder
 ./install.sh
-wayfinder-router init
+wayfinder-router local discover --json
+wayfinder-router init --preset local --endpoint http://127.0.0.1:11434/v1 --model qwen2.5-coder:7b
 wayfinder-router doctor
+wayfinder-router serve
+wayfinder-router local probe --model local --json
 ```
 
+Choose the endpoint and model from the discovery output rather than copying the example blindly. Discovery touches only fixed loopback catalogs and never installs or pulls a model; setup is not complete until the fixed public inference probe returns a local execution receipt.
+
 Point Codex, Claude Code, OpenCode, Pi, or Aider at the same loopback policy with
 `wayfinder-router connect <client>`. See the
 [verified coding-agent quick starts](docs/coding-agent-quickstarts.md), or run

decisions/WF-ADR-0086-local-runtime-ownership-and-proof.md

@@ -0,0 +1,52 @@
+---
+schema_version: 1
+id: WF-ADR-0086
+type: decision
+status: accepted
+date: 2026-08-31
+tags: [omarchy, local, runtime, evidence, privacy]
+---
+
+# Keep local runtime ownership with the operator and prove delivery
+
+## Context
+
+Wayfinder can generate a local configuration without proving that a model is
+actually loaded. A first-run surface must distinguish configured, discoverable,
+and proven states without installing software, downloading weights, scanning
+the network, or claiming that a hosted fallback was local.
+
+## Decision
+
+1. Runtime installation, model downloads, endpoint selection, and policy
+   activation remain explicit operator actions. Wayfinder may inspect only the
+   fixed literal-loopback catalogs and an endpoint the operator supplies.
+2. A local first-run proof consists of one bounded fixed public request through
+   the running Router, a non-empty normalized response, and the matching
+   terminal prompt-free receipt. The receipt must identify an on-device or
+   local-network execution boundary.
+3. The proof is observational and single-shot. It never stores prompt or
+   response content, credentials, repository paths, tool arguments, or private
+   reasoning, and it never changes routing configuration.
+4. A missing runtime, unloaded model, unavailable receipt, hosted boundary,
+   failed response, or ambiguous route is visibly `not-ready`; no health or
+   discovery response may promote it to ready.
+5. The acceptance surface is repeatable on a real operator-owned runtime. A
+   mock HTTP fixture may test parsing and bounds, but it cannot be presented as
+   evidence that a model was loaded or that local inference succeeded.
+
+## Consequences
+
+Omarchy gets a truthful setup gate while the operator retains control of
+runtime and model state. CI can validate the bounded contract and a real local
+runtime can supply the final loaded-model evidence; environments without one
+must report that proof as unavailable rather than passing by simulation.
+
+## Related
+
+- WF-ADR-0001 (offline deterministic decision path)
+- WF-ADR-0068 (Omarchy Quattro plugin boundary)
+- WF-ADR-0070 (native activation surface)
+- WF-ADR-0085 (prompt-free outcomes and review-only policy proposals)
+- WF-ADR-0087 (first local inference evidence)
+- WF-ROADMAP-0017 (Omarchy-first delivery)

decisions/WF-ADR-0087-local-first-success-evidence.md

@@ -0,0 +1,38 @@
+---
+schema_version: 1
+id: WF-ADR-0087
+type: decision
+status: accepted
+date: 2026-08-31
+tags: [omarchy, onboarding, local, privacy, evidence]
+---
+
+# Prove a local inference before declaring first-run success
+
+## Context
+
+The native `local` starter preset names Ollama and `llama3.1`, but creating and parsing that file does not prove that either the runtime or model exists. An Omarchy surface can therefore report a configured service as ready while the first agent request will fail. Installing a runtime, pulling a model, scanning arbitrary ports, or choosing a discovered model without review would cross ownership, network, storage, and policy boundaries.
+
+## Decision
+
+1. `wayfinder-router local discover --json` queries only a fixed catalog of literal-loopback runtime endpoints for Ollama, LM Studio, llama.cpp, and vLLM. It emits `wf-local-discovery-v1` candidates containing only runtime name, loopback endpoint, fixed route ID, and public model ID. It does not install, pull, select, or write anything, and it does not scan the network.
+2. `wayfinder-router init --preset local --endpoint URL --model MODEL` accepts one explicitly selected discovery result. The endpoint must remain literal loopback, the model ID is bounded, the generated policy is parse-validated, and the existing no-clobber create contract remains authoritative.
+3. `wayfinder-router local probe --endpoint URL --model ROUTE_ID --json` sends one fixed, public, low-output request through an already running loopback Router. Success requires a non-empty normalized response plus the exact bounded receipt for that request with a terminal success and an `on-device` or `local-network` execution boundary.
+4. The `wf-local-probe-v1` report includes endpoint, route, served destination, execution boundary, timestamp, request count, and the fixed-prompt disclosure. It never includes response text, prompt text beyond the public disclosure label, provider payloads, credentials, repository paths, tool arguments, or private reasoning.
+5. Consumers may call setup complete only after the probe passes. An empty discovery, failed probe, missing receipt, hosted boundary, missing capability, or older Router remains visibly not ready.
+
+## Consequences
+
+- First run distinguishes “configuration exists” from “a local model actually answered.”
+- Operators keep control of runtime installation, model downloads, and policy selection.
+- Discovery intentionally misses runtimes on nonstandard ports until the operator supplies and reviews an explicit loopback endpoint.
+- Hosted and account-backed first runs remain separate provider contracts; this decision does not import credentials or change Automatic routing.
+
+## Related
+
+- WF-ADR-0001 (offline deterministic decision path)
+- WF-ADR-0068 (Omarchy plugin boundary)
+- WF-ADR-0070 (native activation surface)
+- WF-ADR-0073 (Omarchy-first portable core)
+- WF-ADR-0086 (local runtime ownership and proof)
+- WF-ROADMAP-0017 (Omarchy-first delivery)

docs/coding-agent-quickstarts.md

@@ -7,7 +7,26 @@ the selected destination.
 
 ## Start Wayfinder
 
-From a directory that does not already contain `wayfinder-router.toml`:
+For an honest local-only first run, discover only the supported fixed-loopback runtime catalogs and review one candidate:
+
+```sh
+wayfinder-router local discover --json
+wayfinder-router init --preset local \
+  --endpoint http://127.0.0.1:11434/v1 \
+  --model qwen2.5-coder:7b
+wayfinder-router doctor
+wayfinder-router serve
+```
+
+In another terminal, prove one real delivery through the running Router:
+
+```sh
+wayfinder-router local probe --model local --json
+```
+
+Discovery never scans arbitrary ports, installs a runtime, pulls a model, selects a candidate, or writes configuration. `init` retains its no-clobber contract. The fixed public probe reports `passed` only when its matching bounded receipt proves a successful on-device or local-network execution; it does not emit the request or response text. An empty candidate list means that no supported fixed-loopback catalog answered, not that the machine has no local runtime.
+
+For a two-arm local/hosted policy, start from a directory that does not already contain `wayfinder-router.toml`:
 
 ```sh
 wayfinder-router init --preset hybrid

llms.txt

@@ -14,6 +14,17 @@ cd ~/.config/omarchy/plugins/io.github.asdecided.wayfinder
 
 Then ask the user to open the Wayfinder bar item and choose **Set up Wayfinder**. The plugin creates only a missing policy, validates it, and installs the independent user service. Never replace an existing policy, provider credential, coding-agent configuration, or independently installed Router binary.
 
+For the local-only first-success path, discover fixed loopback catalogs, explicitly choose a returned model, initialize a no-clobber policy, start the Router, and prove one real routed response:
+
+```sh
+wayfinder-router local discover --json
+wayfinder-router init --preset local --endpoint http://127.0.0.1:11434 --model MODEL
+wayfinder-router serve
+wayfinder-router local probe --endpoint http://127.0.0.1:8787 --model local --json
+```
+
+Discovery never scans the network, installs a runtime, pulls a model, or chooses on the user's behalf. The probe sends one fixed public prompt and reports only bounded delivery evidence; it never prints the model response. A policy is not created and readiness is not claimed unless every explicit step succeeds.
+
 For a two-arm local/OpenAI policy outside the panel, run:
 
 ```sh

rust/crates/wayfinder-cli/src/activation_command.rs

@@ -7,13 +7,16 @@ use std::process::Command;
 #[cfg(test)]
 use std::fs;
 
-use crate::app_setup_command::{preset_config, write_new_config};
+use crate::app_setup_command::{local_preset_config, preset_config, write_new_config};
+use crate::local_command::{validate_identifier, validate_loopback_endpoint};
 use crate::{EXIT_OK, EXIT_USAGE, expand_tilde, write_error, write_output};
 
 const DEFAULT_CONFIG: &str = "wayfinder-router.toml";
 const DEFAULT_ENDPOINT: &str = "http://127.0.0.1:8088";
-const INIT_HELP: &str =
-    "usage: wayfinder-router init [--preset local|hybrid|openai|gemini|apple-local] [--path PATH]";
+const INIT_HELP: &str = concat!(
+    "usage: wayfinder-router init [--preset local|hybrid|openai|gemini|apple-local] [--path PATH]\n",
+    "       wayfinder-router init --preset local --endpoint URL --model MODEL [--path PATH]"
+);
 const CONNECT_HELP: &str =
     "usage: wayfinder-router connect codex|claude-code|opencode|pi|aider [--endpoint URL]";
 const OPEN_HELP: &str = "usage: wayfinder-router open [--print]";
@@ -29,6 +32,8 @@ pub(crate) fn run_init(
     }
     let mut preset = "local".to_owned();
     let mut path = PathBuf::from(DEFAULT_CONFIG);
+    let mut endpoint = None;
+    let mut model = None;
     let mut index = 0;
     while let Some(argument) = arguments.get(index) {
         match argument.as_str() {
@@ -46,15 +51,55 @@ pub(crate) fn run_init(
                 }
                 None => return usage_error(stderr, "--path needs a value"),
             },
+            "--endpoint" if endpoint.is_none() => match arguments.get(index + 1) {
+                Some(value) => {
+                    endpoint = Some(value.clone());
+                    index += 1;
+                }
+                None => return usage_error(stderr, "--endpoint needs a value"),
+            },
+            "--model" if model.is_none() => match arguments.get(index + 1) {
+                Some(value) => {
+                    model = Some(value.clone());
+                    index += 1;
+                }
+                None => return usage_error(stderr, "--model needs a value"),
+            },
+            "--endpoint" | "--model" => {
+                return usage_error(stderr, &format!("{argument} may only be supplied once"));
+            }
             value => return usage_error(stderr, &format!("unrecognized init argument: {value}")),
         }
         index += 1;
     }
-    let contents = match preset_config(&preset) {
-        Ok(Some(contents)) => contents,
-        Ok(None) => return usage_error(stderr, &format!("unknown init preset: {preset}")),
-        Err(message) => return usage_error(stderr, &message),
+    let custom_local = match (endpoint, model) {
+        (None, None) => None,
+        (Some(endpoint), Some(model)) if preset == "local" => {
+            if let Err(message) = validate_loopback_endpoint(&endpoint) {
+                return usage_error(stderr, &message);
+            }
+            if let Err(message) = validate_identifier(&model, "model id") {
+                return usage_error(stderr, &message);
+            }
+            match local_preset_config(&endpoint, &model) {
+                Ok(contents) => Some(contents),
+                Err(message) => return usage_error(stderr, &message),
+            }
+        }
+        (Some(_), Some(_)) => {
+            return usage_error(
+                stderr,
+                "--endpoint and --model are available only with --preset local",
+            );
+        }
+        _ => return usage_error(stderr, "--endpoint and --model must be supplied together"),
     };
+    let contents =
+        match custom_local.map_or_else(|| preset_config(&preset), |value| Ok(Some(value))) {
+            Ok(Some(contents)) => contents,
+            Ok(None) => return usage_error(stderr, &format!("unknown init preset: {preset}")),
+            Err(message) => return usage_error(stderr, &message),
+        };
     match write_new_config(&path, &contents) {
         Ok(()) => {
             write_output(
@@ -221,6 +266,64 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn init_accepts_an_explicit_discovered_local_model_without_clobbering()
+    -> Result<(), Box<dyn std::error::Error>> {
+        let root = std::env::temp_dir().join(format!("wayfinder-init-{}", uuid::Uuid::new_v4()));
+        let path = root.join("wayfinder-router.toml");
+        let arguments = vec![
+            "--preset".to_owned(),
+            "local".to_owned(),
+            "--endpoint".to_owned(),
+            "http://127.0.0.1:11434/v1".to_owned(),
+            "--model".to_owned(),
+            "qwen2.5-coder:7b".to_owned(),
+            "--path".to_owned(),
+            path.display().to_string(),
+        ];
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        assert_eq!(run_init(&arguments, &mut stdout, &mut stderr), EXIT_OK);
+        let generated = fs::read_to_string(&path)?;
+        assert!(generated.contains("base_url = \"http://127.0.0.1:11434/v1\""));
+        assert!(generated.contains("model = \"qwen2.5-coder:7b\""));
+        assert_eq!(run_init(&arguments, &mut stdout, &mut stderr), EXIT_USAGE);
+        fs::remove_dir_all(root)?;
+        Ok(())
+    }
+
+    #[test]
+    fn explicit_local_init_rejects_remote_and_partial_selection() {
+        for arguments in [
+            vec![
+                "--preset".to_owned(),
+                "local".to_owned(),
+                "--endpoint".to_owned(),
+                "https://example.com/v1".to_owned(),
+                "--model".to_owned(),
+                "model".to_owned(),
+            ],
+            vec![
+                "--preset".to_owned(),
+                "local".to_owned(),
+                "--model".to_owned(),
+                "model".to_owned(),
+            ],
+            vec![
+                "--preset".to_owned(),
+                "hybrid".to_owned(),
+                "--endpoint".to_owned(),
+                "http://127.0.0.1:11434/v1".to_owned(),
+                "--model".to_owned(),
+                "model".to_owned(),
+            ],
+        ] {
+            let mut stdout = Vec::new();
+            let mut stderr = Vec::new();
+            assert_eq!(run_init(&arguments, &mut stdout, &mut stderr), EXIT_USAGE);
+        }
+    }
+
     #[test]
     fn connect_only_accepts_loopback_and_renders_each_client() {
         for (client, marker) in [

rust/crates/wayfinder-cli/src/app_setup_command.rs

@@ -217,6 +217,34 @@ pub(crate) fn preset_config(name: &str) -> Result<Option<String>, String> {
     }
 }
 
+pub(crate) fn local_preset_config(endpoint: &str, model: &str) -> Result<String, String> {
+    let endpoint = serde_json::to_string(endpoint)
+        .map_err(|error| format!("cannot render local endpoint: {error}"))?;
+    let model = serde_json::to_string(model)
+        .map_err(|error| format!("cannot render local model: {error}"))?;
+    let generated = format!(
+        "# Generated by wayfinder-router init (preset: local; explicit model).\n\
+[routing]\n\
+threshold = 1.0\n\n\
+[gateway]\n\
+offline = true\n\n\
+[gateway.models.local]\n\
+base_url = {endpoint}\n\
+model = {model}\n\
+cost_per_1k = 0.0\n"
+    );
+    routing_config_from_toml(
+        &generated,
+        "generated explicit local preset",
+        None,
+        TierOrderPolicy::StrictInput,
+    )
+    .map_err(|error| format!("generated local routing is invalid: {error}"))?;
+    gateway_config_from_toml(&generated, "generated explicit local preset")
+        .map_err(|error| format!("generated local gateway is invalid: {error}"))?;
+    Ok(generated)
+}
+
 const STARTER_CORPUS: &str =
     include_str!("../../../../benchmarks/blind/openai-cross-provider.jsonl");
 const STARTER_SEMANTIC_WEIGHT: f64 = 0.05;