@interf/compiler 0.18.0 → 0.21.0

package/README.md

@@ -1,19 +1,19 @@
 # Interf
 
-**Prepare your data for AI agents. With proof.**
+**Context compiler for agents.**
 
-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.
+Interf prepares data for agent work by compiling source files into verifiable Artifacts and writing portable context that agents can read, so agents work from a verified full picture instead of guessing.
 
 **Hallucinations aren't an agent problem. They're a data preparation problem.**
 
 When agents start from source files, they have to discover the full picture while they work. That discovery is hidden: you cannot see which files were processed, which evidence was used, or which connections were found.
 
-Interf replaces that hidden discovery with a visible Method run over your source files. You connect to a local instance, name a Preparation against your Source Folder and a Method, run compile, and read the portable context Interf returns. Interf records source references, runs the Method locally, and writes the portable context: evidence, structure, and cross-file connections for agents.
+Interf replaces that hidden discovery with visible compilation. Your agent can ask for the Artifacts it needs — an atlas, index, timeline, summaries, or a custom file — and Interf drafts a Build Plan for you to review before compile. The draft says what should be built; the compile run proves what was actually processed. Under the hood, Interf saves that request as a Preparation, runs a Build Plan locally, records source references, and writes verifiable Artifacts agents can read. Today a Build Plan is implemented by a Method package.
 
 ```text
-Source Folder                       Portable context agents read
+Source files                        Portable context agents read
 
-bristol-office-market/              ~/.interf/preparations/bristol/portable-context/
+bristol-office-market/              <portable-context-locator>/
   q4-market-report.pdf                AGENTS.md
   lease-comps.xlsx                    .interf/runtime/source-snapshot.json
   planning-notes.md                   home.md
@@ -21,15 +21,16 @@ bristol-office-market/              ~/.interf/preparations/bristol/portable-cont
                                       knowledge/
 ```
 
-## What a Method Run Produces
+## What a Compile Run Produces
 
-A Method run produces portable context plus proof of work. The portable context is the folder agents read. The proof shows which source files were assigned, which Method stages ran, what each stage wrote, and whether required outputs exist.
+A compile run produces portable context plus proof of work. The portable context is the folder agents read. The proof shows which source files were assigned, which Build Plan stages ran, what each stage wrote, and whether required artifacts exist.
 
-For the built-in `interf-default` Method, a compile run looks like this:
+For the built-in `interf-default` Build Plan, a compile run looks like this:
 
 ```text
-Source Files: bristol-office-market
-Method: interf-default
+Source: bristol-office-market
+Build Plan: interf-default
+Requested Artifacts: atlas, summaries, knowledge, claims, indexes
 
 compile run
   record source references
@@ -38,28 +39,28 @@ compile run
   shape -> home.md and agent entrypoints
   record proof -> processed files, stage outputs, required artifacts
 
-output
-  portable context -> { kind: "local-path", value: "/Users/me/.interf/preparations/bristol/portable-context" }
+portable context
+  locator -> { kind: "local-path", value: "<local-path-returned-by-interf>" }
 ```
 
-The output is not an answer. It is a prepared local folder with routes, summaries, linked notes, source snapshots, and agent instructions. Your runtime agent reads that folder when it does the actual agent work.
+The output is not an answer. It is a prepared local folder with routes, artifacts, source snapshots, and agent instructions. Your runtime agent reads that folder when it does the actual agent work.
 
 ## Design Choices
 
-- `Method-scoped`: every Method is for one specific kind of agent work over source files, not a generic index over your Source Folder.
-- `Deterministic`: Interf runs each stage, an ordered phase of a Method, and shows stage-by-stage proof of work: which files were processed, what each stage produced, and whether required outputs exist. Agents do not have to rebuild the full picture while they work.
+- `Preparation-scoped`: every Preparation starts from a specific Source, requested Artifacts, and agent job, not a generic index over all your files.
+- `Deterministic`: Interf runs each stage, an ordered phase of a Build Plan, and shows stage-by-stage proof of work: which files were processed, what each stage produced, and whether required outputs exist. Agents do not have to rebuild the full picture while they work.
 - `Local-first and private`: your files, readiness checks, and agent runs stay on your machine. No cloud, no uploads, no telemetry.
 - `Bring your own AI`: use Claude Code, Codex, or another local agent.
-- `File over app`: the portable context is a real local folder owned by the instance — no hidden store, no hidden index. Inspect it, diff it, version it.
+- `File over app`: the portable context is a local folder owned by the instance — no hidden store, no hidden index. Inspect it, diff it, version it.
 - `Readiness checks you control`: every build can be checked against gates you wrote from the files. If the portable context is `not ready`, `interf test` shows the readiness evidence behind that status.
 
 ## Why Not Just Ask Your Agent?
 
 You can. Interf can use Claude Code, Codex, or another local agent while it builds the portable context.
 
-A one-off preprocessing prompt gives you another agent answer to trust. Interf puts that work inside a Method you can inspect: declared stages, required outputs, stage-by-stage proof of work, and readiness checks that decide whether the portable context is `ready` or `not ready`.
+A one-off preprocessing prompt gives you another agent answer to trust. Interf puts that work inside a Build Plan you can inspect: requested artifacts, declared stages, stage-by-stage proof of work, and readiness checks that decide whether the portable context is `ready` or `not ready`.
 
-The agent can still do the processing. Interf shows what ran, which files were processed, what evidence was produced, and whether the result is ready for the agent work.
+The agent can still execute the stages. Interf shows what ran, which files were processed, what artifacts and evidence were produced, and whether the result is ready for the agent work.
 
 ## Install
 
@@ -74,35 +75,39 @@ Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run
 
 ```bash
 interf web                                      # terminal 1: start the local engine
-interf prep create bristol \                    # terminal 2: name the unit of work
+interf prep create bristol \                    # terminal 2: save the source + requested Artifacts
   --source ./bristol-office-market \
-  --method interf-default
+  --about "Bristol annual take-up and availability chart lookup" \
+  --requested-artifacts-json '[{"title":"Guide to the report","checks":["Every page or file is listed.","Pages about Bristol and annual take-up are marked."]},{"title":"Annual take-up figures","checks":["Every figure has a source reference."]}]'
+interf method draft bristol \                   # draft the Build Plan for review
+  --task "Bristol annual take-up and availability chart lookup"
 interf compile bristol                          # build portable context, returns the locator
 interf test bristol                             # check readiness
 ```
 
-`interf web` starts the engine in the foreground and writes
-`~/.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 web` starts the engine in the foreground and writes the active
+connection record so subsequent CLI commands can connect. Agents can use
+`interf web start` for an explicit managed background engine, then
+`interf web stop` when their work is done. Mutating commands never implicitly
+auto-start an engine — if no instance is connected, they exit with a hint
+pointing at `interf web` / `interf web start` (local) or `interf login`
+(future cloud).
 
 `interf compile` returns the artifact locator on success — for a local
 engine that's a `local-path` you can open with any tool. Point your agent at
 that path. There's no `--out` flag, no implicit copy, no hidden store: the
 instance owns the bytes and the API tells you where they are.
 
-If you want a baseline before preparing, run `interf test bristol --target source-files`. It is optional proof, not the main path.
+If you want a baseline before compile, run `interf test bristol --target source-files`. It is optional proof, not the main path.
 
 ## Portable Context
 
-The portable context is the local folder Interf writes from your files. The instance owns its location — `~/.interf/preparations/<prep-id>/portable-context/` for a local engine, a signed remote URL for a cloud engine. The API returns a typed locator (`{ kind: "local-path" | "remote-url", value }`); your agent reads from there.
+The portable context is the local folder Interf writes from your files. Do not hardcode its location. The API returns a typed locator (`{ kind: "local-path" | "remote-url", value }`); your agent reads from there.
 
 It gives agents evidence, structure, and cross-file connections for navigating the files. It is not a replacement for your files. For the built-in `interf-default`, it includes:
 
 ```text
-~/.interf/preparations/bristol/portable-context/
+<portable-context-locator>/
   AGENTS.md       # agent-facing entry point and source-checking rules
   CLAUDE.md       # same guidance for Claude Code
   .interf/
@@ -114,7 +119,7 @@ It gives agents evidence, structure, and cross-file connections for navigating t
   knowledge/      # linked notes built from the files
 ```
 
-The source files stay the source of truth. Interf writes portable context inside the instance's data dir; it does not modify the Source Folder.
+The source files stay the source of truth. Interf writes portable context inside the instance's data dir; it does not modify the source.
 
 `AGENTS.md` tells agents how to use the portable context: start from the prepared outputs, follow the prepared routes, and use the recorded source references when exact source evidence matters.
 
@@ -122,15 +127,17 @@ Interf also records stage-by-stage proof of work: which files were processed, wh
 
 The portable context carries source references, not a mandatory copy of every source file. The source files remain where you keep them; Interf records which sources were assigned and what artifacts were produced from them.
 
-## Methods
+## Build Plans and Method Packages
 
-A Method tells Interf how to process your files for the job agents need to do. When you create one, describe three things: what data is in the Source Folder, what the portable context should contain, and what evidence should show the portable context is `ready`. The built-in `interf-default` Method ships with `@interf/compiler`. Install your own with `interf method install <path>`; draft new ones with `interf method draft <prep-id>`.
+A Build Plan tells Interf how to compile requested Artifacts from your source files for the job agents need to do. It can start as a draft inside one Preparation, based on the user's instructions, the agent goal, and the described Source. If it works, save it as a Method package and reuse it on another Source.
+
+Today saved Build Plans are implemented as Method packages. The built-in `interf-default` Method package ships with `@interf/compiler`. Install your own with `interf method install <path>`; draft new ones with `interf method draft <prep-id>`.
 
 ```text
-~/.interf/methods/interf-default/
-  method.json         # Method: source data, stages, and processing rules
+<method-package>/
+  method.json         # Build Plan: artifacts, stages, compile rules
   method.schema.json  # output contract: required portable-context files and folders
-  README.md             # what this Method is for, for humans and agents
+  README.md             # what this Build Plan is for
   compile/
     stages/
       summarize/        # stage instructions Interf runs during compile
@@ -138,20 +145,20 @@ A Method tells Interf how to process your files for the job agents need to do. W
       shape/
   use/
     query/              # how agents read the portable context
-  improve/              # how Interf revises this Method if readiness checks still fail
+  improve/              # how Interf revises this plan if readiness checks still fail
 ```
 
-- `method.json` describes the Method: source data, stages, and how the files should be processed.
+- `method.json` describes the Build Plan: source data, requested artifacts, stages, and how the files should be compiled.
 - `method.schema.json` describes the output contract: what the portable context must contain. Interf enforces it when you run `interf compile`.
 - `compile/stages/<stage>/` is where you author one folder per stage — a small, specific phase like `summarize` or `structure`. You write the instructions; Interf runs them during compile.
 - `use/query/` holds the instructions agents follow when they read the portable context for live agent work.
-- `improve/` holds the instructions Interf follows when the first build misses and the Method itself needs editing.
+- `improve/` holds the instructions Interf follows when the first build misses and the Build Plan itself needs editing.
 
-A Method defines the stages, output contract, proof requirements, and improvement instructions Interf runs on your files. Technically, each Method is stored as a Method package with `method.json` and `method.schema.json`. The result is portable context your agents can read.
+A Build Plan defines the stages, output contract, proof requirements, and improvement instructions Interf runs on your files. Technically, a saved/reusable Build Plan is stored as a Method package with `method.json` and `method.schema.json`. The result is portable context your agents can read.
 
-## Method Improvement
+## Build Plan Improvement
 
-When the first compile run still misses readiness checks, Interf edits the Method itself and compiles again. Same files, same checks, improved Method and portable context. Run `interf method improve <prep-id>` to invoke that loop manually.
+When the first compile run still misses readiness checks, Interf edits the Build Plan and compiles again. Same files, same checks, improved plan and portable context. Run `interf method improve <prep-id>` to invoke that loop manually.
 
 Interf saves every readiness-check run inside the preparation's portable context under `.interf/tests/`. You can inspect what changed and why a later compile run did better.
 
@@ -159,7 +166,7 @@ Interf saves every readiness-check run inside the preparation's portable context
 
 You don't need to think about roles. By default Interf uses your active agent for every stage of every compile run, the same way 0.14 did. Roles are available for advanced users who want different agents per stage; defaults are good and stable.
 
-Interf treats connected agents as a first-class primitive and uses a small role taxonomy internally to route stages between them. The default behavior is single-active-agent — one installed agent runs everything — but you can opt into per-role specialization without changing any Method.
+Interf treats connected agents as a first-class primitive and uses a small role taxonomy internally to route stages between them. The default behavior is single-active-agent — one installed agent runs everything — but you can opt into per-role specialization without changing any Build Plan.
 
 ```text
 Connected agents             Role map (per-instance)
@@ -169,16 +176,16 @@ Connected agents             Role map (per-instance)
                                verifier    → claude-code
                                general     → claude-code
 
-A Method compile run
-  for each stage in the Method
+A Build Plan compile run
+  for each stage in the Build Plan
     look up the stage's role in the role map
     invoke the mapped agent on the prepared shell
     record which agent ran which stage
 ```
 
-Methods declare an optional `role` per stage — one of `extractor`, `summarizer`, `structurer`, `verifier`, or `general`. Custom role names are allowed; unknown roles fall through to `general`.
+Build Plans declare an optional `role` per stage — one of `extractor`, `summarizer`, `structurer`, `verifier`, or `general`. Custom role names are allowed; unknown roles fall through to `general`.
 
-The role map lives in `~/.interf/agents.json`. On a fresh install with one agent installed, every role maps to that agent and you get the same single-active-agent behavior 0.14 had. To change which agent runs which role:
+The role map lives in the instance's agent settings. On a fresh install with one agent installed, every role maps to that agent and you get the same single-active-agent behavior 0.14 had. To change which agent runs which role:
 
 ```bash
 interf agents ls
@@ -188,23 +195,23 @@ interf agents use claude-code   # set the active agent
 interf agents unmap structurer  # fall back to active
 ```
 
-Or use the **Agents** tab in Interf Compiler UI. Either surface mutates the same `~/.interf/agents.json` through the local service.
+Or use the **Agents** tab in Interf Compiler UI. Either surface mutates the same instance agent settings through the local service.
 
-Verify runs always resolve to the `verifier` role. Method-authoring runs ask the authoring agent to propose a `role` per stage based on the prompt content; missing roles default to `general`.
+Readiness-check runs always resolve to the `verifier` role. Build Plan authoring runs ask the authoring agent to propose a `role` per stage based on the prompt content; missing roles default to `general`.
 
 ## How the Pieces Fit
 
-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.
+The instance owns preparation state. A preparation declares a source binding (`{ kind: "local-folder", locator: <path> }`), requested artifacts, and a selected Build Plan. The current local engine still stores the selected Build Plan as `method_id` while the schema catches up. It stores preparation state and generated bytes in the instance data directory. A compile run processes the selected source files and produces the artifact locator the API returns. `interf test` checks source 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: Method Artifact checks, 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: Build Plan 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.
+`interf web` runs the local Interf instance and serves Interf Compiler UI. The UI reads local-service resources: Source, Preparations, Build Plans, Method packages, compile 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, Build Plan, Method-package, or readiness semantics.
 
-Everywhere Interf shows a resource — Source Folder, portable context, Method files, run artifacts — the API returns a single locator shape: `{ kind, value }`. `local-path` means the engine has filesystem access to the same host as the user; `remote-url` is a signed URL the UI opens in a browser tab; `api-served` is a relative API route the UI fetches and renders inline. Local engines today return `local-path`; the same shape carries forward unchanged when a remote instance fronts the API.
+Everywhere Interf shows a resource — Source, portable context, Build Plan files, run artifacts — the API returns a single locator shape: `{ kind, value }`. `local-path` means the engine has filesystem access to the same host as the user; `remote-url` is a signed URL the UI opens in a browser tab; `api-served` is a relative API route the UI fetches and renders inline. Local engines today return `local-path`; the same shape carries forward unchanged when a remote instance fronts the API.
 
 ## CLI Connection
 
-The CLI is a thin authorized client of one connected instance. It carries one piece of state — `~/.interf/connection.json`:
+The CLI is a thin authorized client of one connected instance. It carries one active connection record:
 
 ```text
 {
@@ -213,24 +220,24 @@ The CLI is a thin authorized client of one connected instance. It carries one pi
 }
 ```
 
-`interf web` writes that record on startup. `interf login --url <remote>` writes a remote one (the cloud backend ships in a future release; the wire shape and config layer ship now). `interf logout` clears it.
+`interf web` and `interf web start` write that record on startup. `interf login --url <remote>` writes a remote one (the cloud backend ships in a future release; the wire shape and config layer ship now). `interf logout` clears it.
 
 If the connection is unreachable, every mutating command exits non-zero with:
 
 ```text
 Not connected to any Interf instance.
-Start one with `interf web`, or set --url / `interf login` for a remote one.
+Start one with `interf web` or `interf web start`, or set --url / `interf login` for a remote one.
 ```
 
-There is no auto-start. There is no per-folder pointer file. One mental model: client connects to instance, or doesn't.
+There is no implicit auto-start. There is no per-folder pointer file. One mental model: client connects to instance, explicitly starts one, or doesn't.
 
 ## Readiness Checks
 
 There are two checks in the system, and they answer different questions.
 
-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.
+Build Plan Artifact checks check the build: did the plan 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.
+Readiness checks check the portable context: is this Preparation good enough for the specific agent work? They are the confidence layer on top of the portable context, not the product output.
 
 In the setup flow, readiness checks often look like plain question-and-answer pairs. On the API, they live under each preparation's `checks[]`. They help define whether the portable context is `ready` or `not ready`. A check should be a small, verifiable fact or condition you already know from the files:
 
@@ -238,7 +245,7 @@ In the setup flow, readiness checks often look like plain question-and-answer pa
 - one short statement that should be true or false
 - one comparison across years, files, or sections
 
-Interf proposes an initial set from the files and the description of the job agents need to do. You confirm, edit, or replace them. `interf test` runs those checks through the configured local agent against Source Folder files, portable context, or both. The portable context itself does not answer; the agent answers while using it.
+Interf proposes an initial set from the files and the description of the job agents need to do. You confirm, edit, or replace them. `interf test` runs those checks through the configured local agent against source files, portable context, or both. The portable context itself does not answer; the agent answers while using it.
 
 A maintained readiness example in this repo uses one market report, two readiness checks, and two agents:
 
@@ -249,7 +256,7 @@ A maintained readiness example in this repo uses one market report, two readines
 | Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
 <!-- PUBLIC_BENCHMARK_TABLE:END -->
 
-Codex passed from the Source Folder files; Claude Code only passed when working from Interf's portable context. Both numbers come from the same readiness-check pass. That is evidence about whether this Method output is `ready` for this agent work.
+Codex passed from the source files; Claude Code only passed when working from Interf's portable context. Both numbers come from the same readiness-check pass. That is evidence about whether this portable context is `ready` for this agent work.
 
 A maintained public test example uses this preparation:
 
@@ -260,6 +267,16 @@ A maintained public test example uses this preparation:
   "source": { "kind": "local-folder", "locator": "./task-files" },
   "method_id": "interf-default",
   "about": "Bristol historical take-up and availability chart lookup.",
+  "requested_artifacts": [
+    {
+      "title": "Guide to the report",
+      "checks": ["Every page is listed.", "Pages about Bristol charts are marked."]
+    },
+    {
+      "title": "Annual take-up and availability figures",
+      "checks": ["Every figure has a page reference.", "Approximate chart-derived reads are labelled."]
+    }
+  ],
   "checks": [
     {
       "question": "What were Bristol's annual take-up values in 2018 and 2016?",
@@ -279,31 +296,28 @@ A maintained public test example uses this preparation:
 - Not a second brain or memory product. One preparation per agent job; nothing global.
 - Not a vector store or RAG server. The portable context is plain files.
 - Not a hosted data platform. The local instance runs on your machine; your bytes never leave it.
-- Not an agent harness. Interf prepares the data; your existing agent reads the portable context.
+- Not an agent harness. Interf compiles the context; your existing agent reads the portable context.
 
 ## Useful Commands
 
 - `interf web` — run the local engine in the foreground (Compiler UI + API)
+- `interf web start` — start a managed background local engine for agent sessions
 - `interf web stop` — kill the running local engine
 - `interf prep ls / create / show / rm` — manage preparations
 - `interf compile <prep-id>` — build portable context, returns the artifact locator
 - `interf test <prep-id>` — run readiness checks against source files and/or portable context
-- `interf method ls / install / draft / improve` — manage Method packages
+- `interf method ls / show / install / draft / improve` — manage Build Plans / Method packages
 - `interf agents ls / use / register / unregister / map / unmap` — manage connected agents and the role map
-- `interf runs ls / status / watch / cancel / fetch` — inspect runs
-- `interf login / logout` — manage `~/.interf/connection.json` (remote backend ships in a future release)
+- `interf runs ls / status / cancel / fetch` — inspect runs
+- `interf login / logout` — manage the active connection record (remote backend ships in a future release)
 - `interf status` — show the active connection and a preparation summary
-- `interf doctor --live` — verify the local executor
+- `interf doctor --live` — check the local executor
 
-## Maintainer Docs
+## Public Assets
 
-- [src/README.md](./src/README.md) - source tree index
-- [src/packages/README.md](./src/packages/README.md) - package boundaries
-- [src/cli/README.md](./src/cli/README.md) - CLI orchestration
-- [apps/compiler-ui/README.md](./apps/compiler-ui/README.md) - Interf Compiler UI
-- [apps/compiler-ui/DESIGN.md](./apps/compiler-ui/DESIGN.md) - UI design source of truth
-- [scripts/README.md](./scripts/README.md) - maintainer automation
-- [AGENTS.md](./AGENTS.md) / [CLAUDE.md](./CLAUDE.md) - maintainer compass + navigation index for agent sessions
+- [skills/interf](./skills/interf/) — bundled agent Skill for Interf.
+- [plugins/interf](./plugins/interf/) — local MCP host bundle for agents that support local MCP servers.
+- [methods/interf-default](./methods/interf-default/) — default Method package that ships with `@interf/compiler`.
 
 Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md).
 

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

@@ -1,37 +1,3 @@
-/**
- * `interf mcp` — Model Context Protocol server.
- *
- * Wraps the local-service HTTP API as a typed agent surface so coding
- * agents can interact with Interf the same way they call other MCP tools
- * (instead of shelling out to the CLI).
- *
- *   interf mcp                              # stdio transport (default)
- *   interf mcp --transport=http --port=4889 # advanced: HTTP transport
- *
- * The server reads `~/.interf/connection.json` (the same file every other
- * client uses) and exits non-zero with the connect-or-error hint if no
- * instance is reachable. Tools call straight through to the API; the
- * server itself holds no state. The transport options are intentionally
- * minimal — agents speaking MCP today are stdio-first.
- *
- * Tool list mirrors the API verbatim:
- *   prep_list           GET /v1/preparations
- *   prep_create         POST /v1/preparations
- *   prep_show           GET /v1/preparations/{id}
- *   prep_set_method     PATCH /v1/preparations/{id}
- *   prep_remove         DELETE /v1/preparations/{id}
- *   prep_compile        POST /v1/preparations/{id}/compile-runs
- *   prep_verify         POST /v1/preparations/{id}/verify-runs
- *   method_list         GET /v1/methods
- *   method_install      POST /v1/methods (preparation-scoped via `prep_id`)
- *   method_draft        POST /v1/preparations/{id}/method-authoring-runs
- *   method_improve      POST /v1/preparations/{id}/method-improvement-runs
- *   runs_status         GET /v1/runs/{run-id}
- *   runs_watch          GET /v1/runs/{run-id}/events  (snapshot, not SSE)
- *   runs_cancel         POST /v1/runs/{run-id}/cancel
- *   runs_fetch          GET /v1/runs/{run-id}/artifacts
- *   instance_status     GET /v1/instance
- */
 import type { CommandModule } from "yargs";
 interface McpArgs {
     transport?: "stdio" | "http";