@interf/compiler 0.16.0 → 0.18.0

package/LICENSE.md

@@ -0,0 +1 @@
+© 2026 Interf Inc. All rights reserved. Use is subject to Interf's [Commercial Terms of Service](https://interf.com/legal/commercial-terms).

package/README.md

@@ -1,5 +1,7 @@
 # Interf
 
+**Prepare your data for AI agents. With proof.**
+
 Interf prepares data for agent work. It runs locally, processes your files, shows evidence that your data is ready, and writes portable context: a local folder with verifiable outputs agents can use.
 
 **Hallucinations aren't an agent problem. They're a data preparation problem.**
@@ -63,7 +65,7 @@ The agent can still do the processing. Interf shows what ran, which files were p
 
 ```bash
 npm install -g @interf/compiler
-interf            # opens the wizard once an instance is running
+interf            # opens the wizard; start or connect an engine when needed
 ```
 
 Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run `interf doctor --live` if the executor is not detected.
@@ -80,9 +82,10 @@ interf test bristol                             # check readiness
 ```
 
 `interf web` starts the engine in the foreground and writes
-`~/.interf/connection.json` so subsequent CLI commands can connect. Mutating
-commands never auto-start an engine — if no instance is connected, every
-command exits with a hint pointing at `interf web` (local) or
+`~/.interf/connection.json` so subsequent CLI commands can connect. The
+interactive `interf` wizard can ask whether to start `interf web` or connect a
+remote engine. Mutating commands never auto-start an engine — if no instance is
+connected, they exit with a hint pointing at `interf web` (local) or
 `interf login` (future cloud).
 
 `interf compile` returns the artifact locator on success — for a local
@@ -193,7 +196,7 @@ Verify runs always resolve to the `verifier` role. Method-authoring runs ask the
 
 The instance owns preparation state. A preparation declares a source binding (`{ kind: "local-folder", locator: <path> }`) and a method id; the instance stores its config at `~/.interf/preparations/<prep-id>/config.json` and writes portable context to `~/.interf/preparations/<prep-id>/portable-context/`. A compile run processes the selected source files and produces the artifact locator the API returns. `interf test` checks Source Folder files and portable context against the same readiness checks.
 
-Readiness is one `ready` / `not ready` status, not a separate score. Interf builds it from evidence primitives: stage/Method acceptance criteria, proof records, file coverage, artifact validation, and readiness checks.
+Readiness is one `ready` / `not ready` status, not a separate score. Interf builds it from evidence primitives: Method Artifact checks, proof records, file coverage, artifact validation, and readiness checks.
 
 `interf web` runs the local Interf instance and serves Interf Compiler UI. The UI reads local-service resources: Source Files, Methods, runs, stages, proof, artifacts, readiness checks, and whether portable context is `ready` or `not ready`. It renders local instance state; it does not own compiler, Method, or readiness semantics.
 
@@ -225,7 +228,7 @@ There is no auto-start. There is no per-folder pointer file. One mental model: c
 
 There are two checks in the system, and they answer different questions.
 
-Method acceptance criteria check the build: did the Method produce the files, folders, artifacts, and stage outputs it promised? Interf checks those while it compiles.
+Method Artifact checks check the build: did the Method produce the files, folders, Artifacts, and stage outputs it promised? Interf checks those while it compiles.
 
 Readiness checks check the Method output: is this portable context good enough for the specific agent work? They are the confidence layer on top of the portable context, not the product output.
 
@@ -304,5 +307,5 @@ A maintained public test example uses this preparation:
 
 Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-Code: proprietary (this repo is private; the package is not published).
+License: see [LICENSE.md](./LICENSE.md). © 2026 Interf Inc. All rights reserved.
 Name and branding: see [TRADEMARKS.md](./TRADEMARKS.md).

package/TRADEMARKS.md

@@ -1,8 +1,8 @@
 # Trademarks
 
-`Interf`, the Interf word mark, and related logos are trademarks of Interf, Inc.
+`Interf`, the Interf word mark, and related logos are trademarks of Interf Inc.
 
-This repository is proprietary and currently private. The Interf marks are
-not licensed for public use.
+The Interf marks are not licensed for public use. Public visibility of any
+Interf code, docs, or package does not grant trademark or branding rights.
 
-If you need official brand usage permission, contact Interf, Inc.
+If you need official brand usage permission, contact Interf Inc.

package/builtin-methods/interf-default/README.md

@@ -7,20 +7,19 @@ Built-in file-processing Method: summarize source-grounded evidence, structure c
 - General portable-context Method for agent use
 - Compile mixed source files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents running the readiness checks this task depends on.
 
-## Zones
+## Artifacts
 
-- `summaries` — working directory at `summaries`
+- `summaries` — output directory at `summaries`
 - `knowledge-entities` — output directory at `knowledge/entities`
 - `knowledge-claims` — output directory at `knowledge/claims`
 - `knowledge-indexes` — output directory at `knowledge/indexes`
-- `home` — output file at `home.md` used as the primary entrypoint for this Method
-- `runtime` — runtime zone at `.interf/runtime`
+- `atlas` — output file at `home.md` used as the primary entrypoint for this Method
 
 ## Stages
 
-- `summarize` — Turn source files into per-file summaries. (compiled-file-evidence; reads: runtime; writes: summaries)
-- `structure` — Build the cross-file knowledge structure from the summaries. (compiled-knowledge-structure; reads: summaries, runtime; writes: knowledge-entities, knowledge-claims, knowledge-indexes)
-- `shape` — Shape the final portable context around the saved task focus and readiness checks. (compiled-query-shape; reads: summaries, knowledge-entities, knowledge-claims, knowledge-indexes, runtime; writes: knowledge-indexes, home)
+- `summarize` — Turn source files into per-file summaries. (compiled-file-evidence; reads: none; writes: summaries)
+- `structure` — Build the cross-file knowledge structure from the summaries. (compiled-knowledge-structure; reads: summaries; writes: knowledge-entities, knowledge-claims, knowledge-indexes)
+- `shape` — Shape the final portable context around the saved task focus and readiness checks. (compiled-query-shape; reads: summaries, knowledge-entities, knowledge-claims, knowledge-indexes; writes: knowledge-indexes, atlas)
 
 ## Why `home.md` exists here
 

package/builtin-methods/interf-default/method.json

@@ -26,35 +26,10 @@
       "description": "Turn source files into per-file summaries.",
       "contract_type": "compiled-file-evidence",
       "skill_dir": "summarize",
-      "reads": [
-        "runtime"
-      ],
+      "reads": [],
       "writes": [
         "summaries"
-      ],
-      "acceptance": {
-        "stage_truthy": [
-          "finished_at"
-        ],
-        "zone_counts_at_least_counts": {
-          "summaries": "source_total"
-        },
-        "markdown_frontmatter_valid_zones": [
-          "summaries"
-        ],
-        "frontmatter_required_keys_in_zones": {
-          "summaries": [
-            "source",
-            "source_kind",
-            "evidence_tier",
-            "truth_mode",
-            "state"
-          ]
-        },
-        "markdown_abstract_valid_zones": [
-          "summaries"
-        ]
-      }
+      ]
     },
     {
       "id": "structure",
@@ -63,28 +38,13 @@
       "contract_type": "compiled-knowledge-structure",
       "skill_dir": "structure",
       "reads": [
-        "summaries",
-        "runtime"
+        "summaries"
       ],
       "writes": [
         "knowledge-entities",
         "knowledge-claims",
         "knowledge-indexes"
-      ],
-      "acceptance": {
-        "artifacts_exist": [
-          "knowledge/indexes"
-        ],
-        "stage_truthy": [
-          "finished_at"
-        ],
-        "wikilinks_valid_in_zones": [
-          "summaries",
-          "knowledge-entities",
-          "knowledge-claims",
-          "knowledge-indexes"
-        ]
-      }
+      ]
     },
     {
       "id": "shape",
@@ -96,33 +56,12 @@
         "summaries",
         "knowledge-entities",
         "knowledge-claims",
-        "knowledge-indexes",
-        "runtime"
+        "knowledge-indexes"
       ],
       "writes": [
         "knowledge-indexes",
-        "home"
-      ],
-      "acceptance": {
-        "artifacts_exist": [
-          "home.md"
-        ],
-        "stage_truthy": [
-          "finished_at"
-        ],
-        "wikilinks_valid_in_zones": [
-          "summaries",
-          "knowledge-entities",
-          "knowledge-claims",
-          "knowledge-indexes",
-          "home"
-        ],
-        "artifacts_must_not_contain": {
-          "home.md": [
-            "Not yet compiled."
-          ]
-        }
-      }
+        "atlas"
+      ]
     }
   ],
   "stage_policy_notes": {

package/builtin-methods/interf-default/method.schema.json

@@ -3,71 +3,73 @@
   "version": 1,
   "target_type": "compiled",
   "label": "Interf built-in Method schema",
-  "zones": [
+  "artifacts": [
+    {
+      "id": "atlas",
+      "description": "Primary entrypoint note that agents read first. Routes to summaries, knowledge entities, claims, and indexes.",
+      "shape": { "kind": "path", "path": "home.md", "artifact_kind": "file" },
+      "checks": [
+        { "id": "exists", "kind": "file_exists", "required": true },
+        {
+          "id": "no-placeholder",
+          "kind": "must_not_contain",
+          "required": true,
+          "params": { "phrases": ["Not yet compiled."] }
+        },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
+      ],
+      "built_by_stages": ["shape"]
+    },
     {
       "id": "summaries",
-      "role": "working",
-      "path": "summaries",
-      "kind": "directory",
-      "required": true,
-      "owned_by": [
-        "summarize"
+      "description": "Per-file evidence notes that preserve the source-grounded synthesis agents quote against.",
+      "shape": { "kind": "path", "path": "summaries", "artifact_kind": "directory" },
+      "checks": [
+        {
+          "id": "all-files-summarized",
+          "kind": "min_file_count_matches_source",
+          "required": true,
+          "params": { "match": "source_total" }
+        },
+        { "id": "frontmatter-valid", "kind": "frontmatter_valid", "required": true },
+        {
+          "id": "evidence-keys",
+          "kind": "frontmatter_required_keys",
+          "required": true,
+          "params": { "keys": ["source", "source_kind", "evidence_tier", "truth_mode", "state"] }
+        }
       ],
-      "description": "Per-file evidence notes produced by file-evidence stages."
+      "built_by_stages": ["summarize"]
     },
     {
       "id": "knowledge-entities",
-      "role": "output",
-      "path": "knowledge/entities",
-      "kind": "directory",
-      "required": true,
-      "owned_by": [
-        "structure"
+      "description": "Canonical entity notes that anchor the cross-file knowledge structure.",
+      "shape": { "kind": "path", "path": "knowledge/entities", "artifact_kind": "directory" },
+      "checks": [
+        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
       ],
-      "description": "Canonical entity notes produced by knowledge-structure stages."
+      "built_by_stages": ["structure"]
     },
     {
       "id": "knowledge-claims",
-      "role": "output",
-      "path": "knowledge/claims",
-      "kind": "directory",
-      "required": true,
-      "owned_by": [
-        "structure"
+      "description": "Claim notes extracted from summaries with evidence references.",
+      "shape": { "kind": "path", "path": "knowledge/claims", "artifact_kind": "directory" },
+      "checks": [
+        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
       ],
-      "description": "Claim notes produced by knowledge-structure stages."
+      "built_by_stages": ["structure"]
     },
     {
       "id": "knowledge-indexes",
-      "role": "output",
-      "path": "knowledge/indexes",
-      "kind": "directory",
-      "required": true,
-      "owned_by": [
-        "structure",
-        "shape"
-      ],
-      "description": "Retrieval indexes and navigation notes produced by structure and shape stages."
-    },
-    {
-      "id": "home",
-      "role": "output",
-      "path": "home.md",
-      "kind": "file",
-      "required": true,
-      "owned_by": [
-        "shape"
+      "description": "Retrieval indexes and navigation notes for the knowledge structure.",
+      "shape": { "kind": "path", "path": "knowledge/indexes", "artifact_kind": "directory" },
+      "checks": [
+        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
       ],
-      "description": "Primary entrypoint note for agents using the portable context."
-    },
-    {
-      "id": "runtime",
-      "role": "runtime",
-      "path": ".interf/runtime",
-      "kind": "runtime",
-      "required": true,
-      "owned_by": [],
-      "description": "CLI-owned runtime state, health, stage contracts, and proof artifacts."
+      "built_by_stages": ["structure", "shape"]
     }
   ]
 }

package/dist/cli/commands/prep.js

@@ -45,6 +45,52 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
+function statusColor(status) {
+    if (status === "ready")
+        return chalk.green;
+    if (status === "failed")
+        return chalk.red;
+    if (status === "skipped")
+        return chalk.dim;
+    return chalk.yellow;
+}
+function renderPreparationSummary(prep) {
+    console.log();
+    console.log(`  ${chalk.bold(prep.name)}`);
+    if (prep.method_id)
+        console.log(chalk.dim(`    method:  ${prep.method_id}`));
+    if (prep.source_path)
+        console.log(chalk.dim(`    source:  ${prep.source_path}`));
+    if (prep.portable_context_path) {
+        console.log(chalk.dim(`    output:  ${prep.portable_context_path}`));
+    }
+    if (prep.readiness?.status) {
+        const aggColor = prep.readiness.ready ? chalk.green : chalk.yellow;
+        console.log(`    readiness: ${aggColor(prep.readiness.status)}${prep.readiness.summary ? chalk.dim(` (${prep.readiness.summary})`) : ""}`);
+    }
+    if (prep.artifacts && prep.artifacts.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Artifacts"));
+        const idWidth = Math.max(...prep.artifacts.map((entry) => entry.artifact_id.length), 8);
+        for (const artifact of prep.artifacts) {
+            const colored = statusColor(artifact.status)(artifact.status);
+            const stages = artifact.built_by_stages && artifact.built_by_stages.length > 0
+                ? chalk.dim(` ← ${artifact.built_by_stages.join(", ")}`)
+                : "";
+            console.log(`      ${artifact.artifact_id.padEnd(idWidth)}  ${colored}${stages}`);
+        }
+    }
+    if (prep.latest_compile_run_id) {
+        console.log();
+        console.log(chalk.dim(`    latest compile run: ${prep.latest_compile_run_id}`));
+    }
+    if (prep.latest_test_run_id) {
+        console.log(chalk.dim(`    latest verify run:  ${prep.latest_test_run_id}`));
+    }
+    console.log();
+    console.log(chalk.dim(`  Run with --json for the raw resource record.`));
+    console.log();
+}
 export const prepCommand = {
     command: "prep <subcommand>",
     describe: "Manage preparations on the connected instance",
@@ -122,7 +168,13 @@ export const prepCommand = {
         }
         console.log(chalk.green(`Bound ${chalk.bold(args.methodId)} to ${chalk.bold(args.prepId)}.`));
     })
-        .command("show <prep-id>", "Show a preparation's full record", (y) => y.positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" }), async (args) => {
+        .command("show <prep-id>", "Show a preparation's full record", (y) => y
+        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw JSON record instead of the formatted summary",
+    }), async (args) => {
         const { url, token } = requireConnection(args);
         const { status, body, raw } = await callJson(`${url}${preparationResourcePath(args.prepId)}`, token);
         if (status !== 200) {
@@ -131,7 +183,11 @@ export const prepCommand = {
                 console.error(raw);
             process.exit(1);
         }
-        console.log(JSON.stringify(body, null, 2));
+        if (args.json || !body) {
+            console.log(JSON.stringify(body, null, 2));
+            return;
+        }
+        renderPreparationSummary(body);
     })
         .command("rm <prep-id>", "Delete a preparation", (y) => y.positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" }), async (args) => {
         const { url, token } = requireConnection(args);

package/dist/cli/commands/verify.d.ts

@@ -1,6 +1,8 @@
 import type { CommandModule } from "yargs";
+type VerifyTarget = "compiled" | "source-files";
 interface VerifyArgs {
     prepId: string;
+    target?: VerifyTarget;
     url?: string;
     token?: string;
 }

package/dist/cli/commands/verify.js

@@ -1,10 +1,14 @@
 /**
  * `interf verify <prep-id>` — verify a preparation's claim-checks via a
- * judge against the latest compiled portable context. Together with the
- * method's structural checks (auto-run on every `interf compile`), this
- * feeds the preparation's overall readiness state.
+ * judge against the latest compiled portable context (default) or
+ * against the source folder baseline (`--target source-files`). The
+ * source-files target reveals how much value the Method actually adds.
+ * Together with the method's structural checks (auto-run on every
+ * `interf compile`), this feeds the preparation's overall readiness
+ * state.
  *
  *   interf verify bristol
+ *   interf verify bristol --target source-files
  */
 import chalk from "chalk";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
@@ -40,9 +44,15 @@ async function callJson(url, token, init = {}) {
 }
 export const verifyCommand = {
     command: "verify <prep-id>",
-    describe: "Verify a preparation's claim-checks against its portable context",
+    describe: "Verify a preparation's claim-checks against its portable context (or source-files baseline)",
     builder: (yargs) => yargs
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .option("target", {
+        type: "string",
+        choices: ["compiled", "source-files"],
+        default: "compiled",
+        describe: "Judge target: 'compiled' (default) checks the portable context, 'source-files' checks the raw source folder baseline",
+    })
         .option("url", { type: "string", describe: "Override the active connection URL" })
         .option("token", { type: "string", describe: "Override the active bearer token" }),
     handler: async (args) => {
@@ -57,10 +67,8 @@ export const verifyCommand = {
             console.error("  register a custom CLI: `interf agents register <name> --command <cmd>`.");
             process.exit(1);
         }
-        // Verify the user's claims against the compiled portable context.
-        // The legacy "source-files" / "both" targets (file-as-is judging)
-        // are gone — claims are evaluated against the compiled output only.
-        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/verify-runs`, token, { method: "POST", body: JSON.stringify({ mode: "compiled" }) });
+        const target = args.target ?? "compiled";
+        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/verify-runs`, token, { method: "POST", body: JSON.stringify({ target }) });
         if (status !== 201 && status !== 200) {
             console.error(chalk.red(`Failed to start verify run for ${args.prepId} (HTTP ${status}).`));
             if (raw)
@@ -69,6 +77,7 @@ export const verifyCommand = {
         }
         console.log();
         console.log(`  Run ${chalk.bold(body?.run_id ?? "(?)")} ${chalk.dim(`(${body?.status ?? "started"})`)}`);
+        console.log(`  Target: ${target}`);
         if (body?.readiness?.status)
             console.log(`  Readiness: ${body.readiness.status}`);
         if (body?.error)

package/dist/cli/commands/wizard.js

@@ -2,7 +2,8 @@
  * `interf` (no subcommand) and `interf init` — the wizard.
  *
  * Casual-user entry point. End-to-end onboarding:
- *   - If no connection → offer to start a local engine inline (or connect remote, or quit).
+ *   - If no connection → connect to an already-running local engine, or ask
+ *     whether to start the foreground local engine, connect remote, or quit.
  *   - Once connected → action menu (list / create / compile / test / open UI / stop engine / quit).
  *   - Each action loops back to the menu instead of exiting.
  *
@@ -15,7 +16,7 @@ import { existsSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, resolve } from "node:path";
 import { spawn } from "node:child_process";
-import { readActiveConnection, writeConnection, } from "../../packages/engine/connection-config.js";
+import { ConnectionRecordSchema, readActiveConnection, writeConnection, } from "../../packages/engine/connection-config.js";
 import { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT } from "../../packages/engine/routes.js";
 async function callJson(url, token) {
     const headers = new Headers();
@@ -46,6 +47,18 @@ function spawnInterf(args) {
     });
 }
 const DEFAULT_ENGINE_URL = `http://${LOCAL_SERVICE_DEFAULT_HOST}:${LOCAL_SERVICE_DEFAULT_PORT}`;
+function hasInteractiveTerminal() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+function isHttpUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "http:" || parsed.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Probe a URL's `/health` endpoint and return whether the engine is up.
  * Used as a fallback when `connection.json` may be missing (e.g. older
@@ -133,6 +146,69 @@ function exitNoEngineConnected(reason) {
     console.log();
     process.exit(1);
 }
+async function promptForConnection(reason) {
+    if (!hasInteractiveTerminal()) {
+        exitNoEngineConnected(reason);
+    }
+    console.log();
+    console.log(chalk.yellow(`  ${reason}`));
+    console.log();
+    const choice = await p.select({
+        message: "How do you want to continue?",
+        options: [
+            { value: "start-local", label: "Start local engine (serves Compiler UI)" },
+            { value: "connect-remote", label: "Connect to remote engine" },
+            { value: "quit", label: chalk.dim("Exit") },
+        ],
+        initialValue: "start-local",
+    });
+    if (p.isCancel(choice) || choice === "quit") {
+        p.outro("Bye.");
+        return null;
+    }
+    if (choice === "start-local") {
+        console.log();
+        console.log(chalk.dim("  Starting `interf web` in this terminal. Press Ctrl-C to stop the engine."));
+        console.log();
+        const code = await spawnInterf(["web"]);
+        process.exit(code);
+    }
+    const urlValue = await p.text({
+        message: "Remote engine URL",
+        placeholder: "https://api.interf.cloud",
+        validate: (value) => {
+            const trimmed = String(value ?? "").trim();
+            if (!trimmed)
+                return "URL is required.";
+            const parsed = ConnectionRecordSchema.safeParse({ url: trimmed, auth_token: null });
+            return parsed.success && isHttpUrl(trimmed) ? undefined : "Enter a valid http(s) URL.";
+        },
+    });
+    if (p.isCancel(urlValue)) {
+        p.outro("Bye.");
+        return null;
+    }
+    const tokenValue = await p.password({
+        message: "Bearer token (optional)",
+        mask: "*",
+    });
+    if (p.isCancel(tokenValue)) {
+        p.outro("Bye.");
+        return null;
+    }
+    const record = ConnectionRecordSchema.parse({
+        url: String(urlValue).trim(),
+        auth_token: String(tokenValue ?? "").trim() || null,
+    });
+    const url = record.url.replace(/\/+$/, "");
+    const probe = await callJson(`${url}/health`, record.auth_token);
+    if (probe.status === 0) {
+        return promptForConnection(`Connection ${url} is unreachable.`);
+    }
+    writeConnection(record);
+    console.log(chalk.green("Connection saved."));
+    return { url, token: record.auth_token };
+}
 /** Validate that a path exists and is a directory. */
 function validateSourcePath(value) {
     const abs = resolve(value);
@@ -522,25 +598,57 @@ async function fetchAgentSnapshot(conn) {
     };
 }
 async function runWizard(args) {
-    // Connect-or-error: the wizard never auto-starts an engine. If
-    // `~/.interf/connection.json` is missing or unreachable, exit
-    // non-zero and tell the user to run `interf web` (or
-    // `interf login`) explicitly. This keeps the engine lifecycle in
-    // the user's hands — no surprise background processes, no stale
-    // binaries served by a long-lived auto-spawn.
+    // The wizard is the human entry point, so it can ask how to connect.
+    // It still never auto-starts an engine: starting `interf web` is an
+    // explicit foreground choice, and script/agent commands keep the
+    // connect-or-error behavior.
     const initial = readActiveConnection({
         urlOverride: args.url,
         authTokenOverride: args.token,
     });
+    let conn = null;
     if (!initial) {
-        exitNoEngineConnected("No Interf engine is connected.");
+        if (await probeHealth(DEFAULT_ENGINE_URL)) {
+            try {
+                writeConnection({ url: DEFAULT_ENGINE_URL, auth_token: null });
+            }
+            catch {
+                // best effort
+            }
+            console.log();
+            console.log(chalk.dim(`  Engine already running at ${DEFAULT_ENGINE_URL} — connecting.`));
+            conn = { url: DEFAULT_ENGINE_URL, token: null };
+        }
+        else {
+            conn = await promptForConnection("No Interf engine is connected.");
+        }
     }
-    const url = initial.url.replace(/\/+$/, "");
-    const probe = await callJson(`${url}/health`, initial.auth_token);
-    if (probe.status === 0) {
-        exitNoEngineConnected(`Connection ${url} is unreachable.`);
+    else {
+        const url = initial.url.replace(/\/+$/, "");
+        const probe = await callJson(`${url}/health`, initial.auth_token);
+        if (probe.status === 0) {
+            if (!args.url && await probeHealth(DEFAULT_ENGINE_URL)) {
+                try {
+                    writeConnection({ url: DEFAULT_ENGINE_URL, auth_token: null });
+                }
+                catch {
+                    // best effort
+                }
+                console.log();
+                console.log(chalk.dim(`  Saved connection ${url} is unreachable; using local engine at ${DEFAULT_ENGINE_URL}.`));
+                conn = { url: DEFAULT_ENGINE_URL, token: null };
+            }
+            else {
+                conn = await promptForConnection(`Connection ${url} is unreachable.`);
+            }
+        }
+        else {
+            conn = { url, token: initial.auth_token };
+        }
+    }
+    if (!conn) {
+        return;
     }
-    let conn = { url, token: initial.auth_token };
     const instance = await callJson(`${conn.url}/v1/instance`, conn.token);
     console.log();
     console.log(chalk.bold(`  Connected to ${conn.url}`));