@interf/compiler 0.9.5 → 0.16.0

package/README.md

@@ -6,53 +6,49 @@ Interf prepares data for agent work. It runs locally, processes your files, show
 
 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 Preparation: a Source Folder, a Method for processing it, readiness checks, runs, and the portable context agents use. You choose the Source Folder and Interf Workspace, define what the agent work needs, choose or draft a Method, prepare the files, check readiness, and open the portable context. Interf runs the Method locally and writes the portable context: evidence, structure, and cross-file connections for agents.
+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.
 
 ```text
 Source Folder                       Portable context agents read
 
-bristol-office-market/              interf/bristol-office-market/
+bristol-office-market/              ~/.interf/preparations/bristol/portable-context/
   q4-market-report.pdf                AGENTS.md
-  lease-comps.xlsx                    raw/
-  planning-notes.md                     q4-market-report.pdf
-  exports/availability.csv             lease-comps.xlsx
-                                       planning-notes.md
-                                       exports/availability.csv
-                                     home.md
-                                     summaries/
-                                     knowledge/
+  lease-comps.xlsx                    .interf/runtime/source-snapshot.json
+  planning-notes.md                   home.md
+  exports/availability.csv            summaries/
+                                      knowledge/
 ```
 
-## What a Preparation Produces
+## What a Method Run Produces
 
-A Preparation produces portable context plus proof of work. The portable context is the folder agents read. The proof shows which files Interf processed, which Method stages ran, what each stage wrote, and whether required outputs exist.
+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.
 
-For the built-in `interf-default` Method, a prepare run looks like this:
+For the built-in `interf-default` Method, a compile run looks like this:
 
 ```text
-Preparation: bristol-office-market
+Source Files: bristol-office-market
 Method: interf-default
 
-prepare run
-  read Source Folder
+compile run
+  record source references
   summarize -> summaries/
   structure -> knowledge/
   shape -> home.md and agent entrypoints
   record proof -> processed files, stage outputs, required artifacts
 
 output
-  portable context -> interf/bristol-office-market/
+  portable context -> { kind: "local-path", value: "/Users/me/.interf/preparations/bristol/portable-context" }
 ```
 
 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.
 
 ## Design Choices
 
-- `Preparation-scoped`: every Preparation is for one specific job agents need to do, not a generic index over your Source Folder.
+- `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.
 - `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 local folder in the Interf Workspace — no hidden store, no hidden index. Inspect it, diff it, version it.
+- `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.
 - `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?
@@ -67,58 +63,68 @@ The agent can still do the processing. Interf shows what ran, which files were p
 
 ```bash
 npm install -g @interf/compiler
-interf            # opens the setup wizard in the current folder
+interf            # opens the wizard once an instance is running
 ```
 
 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.
 
 ## Quick Start
 
-1. Run `interf` from the Source Folder you want to prepare, or from a parent folder that contains it.
-2. Choose the Source Folder and Interf Workspace.
-3. Create a Preparation by describing what the agent should do with those files.
-4. Choose or draft the Method: autogenerate one with your agent, use the built-in Method, or create your own.
-5. Run `interf compile` to prepare files and build portable context.
-6. Review or edit the readiness checks Interf will use to decide whether the portable context is `ready` or `not ready`.
-7. Run `interf test` to check readiness.
-8. If agents pass more checks with portable context, point your agent at `interf/<preparation>/`.
+```bash
+interf web                                      # terminal 1: start the local engine
+interf prep create bristol \                    # terminal 2: name the unit of work
+  --source ./bristol-office-market \
+  --method interf-default
+interf compile bristol                          # build portable context, returns the locator
+interf test bristol                             # check readiness
+```
 
-If you want a baseline before preparing, run `interf test --target source-files`. It is optional proof, not the main path.
+`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 login` (future cloud).
 
-`interf init` sets up the local Interf Workspace, saves `interf/interf.json`, and copies the built-in Method to `interf/methods/interf-default/`. It does not create a Preparation until you choose to add one. The Method is stored as a Method package you can inspect, edit, or fork with `interf create method`.
+`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.
 
 ## Portable Context
 
-`interf/<preparation>/` is the local folder Interf writes from your files. 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:
+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.
+
+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/bristol-office-market/
+~/.interf/preparations/bristol/portable-context/
   AGENTS.md       # agent-facing entry point and source-checking rules
   CLAUDE.md       # same guidance for Claude Code
-  raw/            # same source files copied here
-    q4-market-report.pdf
-    lease-comps.xlsx
-    planning-notes.md
-    exports/availability.csv
+  .interf/
+    runtime/
+      source-snapshot.json  # source references captured for the latest run
+      stages/               # per-stage source input lists
   home.md         # overview and routes for agents
   summaries/      # one note per source file
   knowledge/      # linked notes built from the files
 ```
 
-The source files stay the source of truth. Interf writes portable context in the Interf Workspace; 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 Folder.
 
-`AGENTS.md` tells agents how to use the portable context: start from the prepared outputs, follow the prepared routes, and verify against `raw/` when exact source evidence matters.
+`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.
 
 Interf also records stage-by-stage proof of work: which files were processed, what each stage produced, and whether required outputs were created.
 
-The portable context is self-contained — it carries its own `raw/` snapshot, so the evidence the agent works from stays attached to the result. Hand it to a different agent and the folder stands on its own.
+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
 
-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 lives at `interf/methods/interf-default/`. Fork it with `interf create method` when you need a different Method, a different output, or both.
+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>`.
 
 ```text
-interf/methods/interf-default/
+~/.interf/methods/interf-default/
   method.json         # Method: source data, stages, and processing rules
   method.schema.json  # output contract: required portable-context files and folders
   README.md             # what this Method is for, for humans and agents
@@ -142,44 +148,78 @@ A Method defines the stages, output contract, proof requirements, and improvemen
 
 ## Method Improvement
 
-When the first prepare run still misses readiness checks, Interf edits the Method itself and compiles again. Same files, same checks, different preparation.
+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.
+
+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.
+
+## How Interf Compiles
+
+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.
+
+```text
+Connected agents             Role map (per-instance)
+  claude-code (active)         extractor   → claude-code
+  codex                        summarizer  → claude-code
+  pdf-extract (custom)         structurer  → claude-code
+                               verifier    → claude-code
+                               general     → claude-code
+
+A Method compile run
+  for each stage in the Method
+    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`.
+
+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:
 
-Interf saves every readiness-check run under `interf/<preparation>/.interf/tests/`. You can inspect what changed and why a later prepare run did better.
+```bash
+interf agents ls
+interf agents register opencode --command "opencode --prompt"
+interf agents map structurer codex
+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.
+
+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`.
 
 ## How the Pieces Fit
 
-`interf/interf.json` stores the Source Folder binding and saved Preparations: readiness checks, selected Method, and defaults. A prepare run processes the Source Folder and writes portable context under `interf/<preparation>/`. `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> }`) 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.
 
-`interf web` starts the local Interf service and serves Interf Compiler UI. The UI reads local-service resources: Preparations, Methods, runs, stages, proof, artifacts, readiness checks, and whether portable context is `ready` or `not ready`. It renders local compiler 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 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.
 
-Maintainer package boundaries live in [src/packages/README.md](./src/packages/README.md).
+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.
 
-## interf/interf.json
+## CLI Connection
 
-`interf/interf.json` is the main config file for the local Interf Workspace. It lives under `interf/` with Method packages, run state, snapshots, and portable-context outputs. By default, Interf stores that workspace outside the Source Folder so source files stay clean. It prefers the parent folder when the sibling `interf/` path is available and falls back to `~/.interf/<source-folder>` when that path is already occupied. `source_folder.path` records the Source Folder before any Preparation exists. Each `preparations[]` entry describes one Preparation: the source path, the saved readiness checks, the Method that prepares the portable context, and optional defaults.
+The CLI is a thin authorized client of one connected instance. It carries one piece of state — `~/.interf/connection.json`:
 
 ```text
 {
-  "source_folder": {
-    "path": "./bristol-office-market"
-  },
-  "preparations": [
-    {
-      "name": "bristol-office-market",
-      "path": "./bristol-office-market",
-      "about": "Answer Bristol office-market questions from the report, comps, notes, and exports.",
-      "method": "interf-default",
-      "checks": [
-        { "question": "...", "answer": "..." }
-      ]
-    }
-  ]
+  "url": "http://127.0.0.1:4873",
+  "auth_token": null
 }
 ```
 
-The `method` field selects the Method for that Preparation. It points to a folder id under `interf/methods/`. Set it to `interf-default` (the built-in default) or to a Method you have authored. A different Method is different processing and a different output. Same files, different portable context.
+`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.
+
+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.
+```
+
+There is no auto-start. There is no per-folder pointer file. One mental model: client connects to instance, or doesn't.
 
 ## Readiness Checks
 
@@ -187,9 +227,9 @@ 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.
 
-Readiness checks check the Preparation: 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 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.
 
-In the setup flow, readiness checks often look like plain question-and-answer pairs. In `interf/interf.json`, they live under `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:
+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:
 
 - one exact number from a chart, table, or filing
 - one short statement that should be true or false
@@ -206,28 +246,25 @@ 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 Preparation is `ready` for this agent work.
+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.
 
-A maintained public test example in this repo stores them like this:
+A maintained public test example uses this preparation:
 
 <!-- PUBLIC_TEST_CHECKS:START -->
 ```text
 {
-  "preparations": [
+  "id": "cbre-chart-sanity",
+  "source": { "kind": "local-folder", "locator": "./task-files" },
+  "method_id": "interf-default",
+  "about": "Bristol historical take-up and availability chart lookup.",
+  "checks": [
+    {
+      "question": "What were Bristol's annual take-up values in 2018 and 2016?",
+      "answer": "Around half a million sq ft in 2018, roughly 0.45 to 0.6 million sq ft, and about 0.7 to 0.8 million sq ft in 2016. These are approximate chart-derived reads."
+    },
     {
-      "name": "cbre-chart-sanity",
-      "path": "./task-files",
-      "about": "Bristol historical take-up and availability chart lookup.",
-      "checks": [
-        {
-          "question": "What were Bristol's annual take-up values in 2018 and 2016?",
-          "answer": "Around half a million sq ft in 2018, roughly 0.45 to 0.6 million sq ft, and about 0.7 to 0.8 million sq ft in 2016. These are approximate chart-derived reads."
-        },
-        {
-          "question": "What were Bristol's availability values in 2018 and 2016?",
-          "answer": "About 0.55 to 0.6 million sq ft in 2018 and about 1.2 to 1.3 million sq ft in 2016. These are approximate chart-derived reads."
-        }
-      ]
+      "question": "What were Bristol's availability values in 2018 and 2016?",
+      "answer": "About 0.55 to 0.6 million sq ft in 2018 and about 1.2 to 1.3 million sq ft in 2016. These are approximate chart-derived reads."
     }
   ]
 }
@@ -236,29 +273,36 @@ A maintained public test example in this repo stores them like this:
 
 ## What Interf Is Not
 
-- Not a second brain or memory product. One local folder per agent job; nothing global.
+- 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. Interf runs locally and `interf/` is yours.
+- 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.
 
 ## Useful Commands
 
-- `interf` or `interf init` — set up the Interf Workspace or manage Preparations
-- `interf web` — start Interf Compiler UI and the local service for this Workspace
-- `interf compile` — build portable context agents can use
-- `interf test` — run readiness checks against source files and/or portable context
-- `interf create method` — draft a reusable Method
+- `interf web` — run the local engine in the foreground (Compiler UI + API)
+- `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 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 status` — show the active connection and a preparation summary
 - `interf doctor --live` — verify the local executor
 
 ## Maintainer Docs
 
-- [CHANGELOG.md](./CHANGELOG.md) - 0.9 release notes and cleanup status
+- [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
 
 Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-Code: Apache 2.0. Name and branding: see [TRADEMARKS.md](./TRADEMARKS.md).
+Code: proprietary (this repo is private; the package is not published).
+Name and branding: see [TRADEMARKS.md](./TRADEMARKS.md).

package/TRADEMARKS.md

@@ -2,18 +2,7 @@
 
 `Interf`, the Interf word mark, and related logos are trademarks of Interf, Inc.
 
-This repository's code is available under the Apache 2.0 license in [LICENSE](./LICENSE). That license does not grant trademark rights.
-
-You may:
-
-- describe this project factually as a fork or derivative of Interf
-- state that your project is based on Interf or integrates with Interf
-- reproduce the name where required by the Apache 2.0 license for attribution
-
-You may not:
-
-- present your fork, hosted service, or product as the official Interf product
-- use the Interf name or logos in a way that implies endorsement by Interf, Inc.
-- ship a confusingly similar product name, branding, or visual identity
+This repository is proprietary and currently private. The Interf marks are
+not licensed for public use.
 
 If you need official brand usage permission, contact Interf, Inc.

package/agent-skills/interf-actions/SKILL.md

@@ -1,41 +1,154 @@
 ---
 name: interf-actions
-description: Use when an agent needs to operate Interf from natural language: inspect the local Interf Workspace, propose safe CLI commands, run approved Interf commands, or prepare action proposals for Interf Compiler UI.
+description: Use when an agent needs to operate Interf from natural language: connect to an instance, manage preparations, compile a Method against a Source Folder, propose safe CLI commands, or write action proposals for Interf Compiler UI.
 ---
 
 # Interf Actions
 
-Interf prepares data for agent work. It runs locally, processes source files, shows evidence that the data is ready, and writes portable context: a local folder with verifiable outputs agents can use.
+Interf prepares data for agent work. It runs locally, processes source files, shows evidence that the data is ready, and writes portable context: a local folder agents can read from.
 
-The Interf local service owns the typed action contract and run observability. For agents, the installed CLI is the supported facade over that contract. Outside Interf Compiler UI freeform proposal mode, inspect the current command surface when needed:
+The model in 0.13 is **instance + preparation**:
+
+- **Instance** = the engine (a local `interf web` process, or a future cloud endpoint). Owns all preparation state. Same wire shape both ends.
+- **Method** = reusable recipe (`method.json` + stage docs). A package, no runtime state. Lives bundled with `@interf/compiler` or installed in the user library at `~/.interf/methods/<id>/`.
+- **Preparation** = a unit of work — `id + source binding + method + readiness checks + run history`. The project-level identifier the agent names. Lives inside an instance.
+- **Compile run** = one execution of a Preparation. Append-only. Produces portable context.
+
+A **Source Folder** is the agent's input — files Interf scans by reference, not by copy. The agent's executor reads them; Interf never copies.
+
+There is **no workspace concept** in 0.13. The CLI carries one piece of state: the active connection at `~/.interf/connection.json`.
+
+## Connection model
+
+The CLI is a thin authorized client of one connected instance. Every mutating command requires a reachable connection. If `~/.interf/connection.json` is missing or unreachable, the 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.
+```
+
+There is **no auto-start**. Agents must verify a connection exists before running mutating commands. To set up a connection:
 
 ```sh
-interf --help
-interf list
-interf status
-interf doctor
+interf web              # local: starts the engine in the foreground (blocks)
+interf login --url <…>  # remote: writes connection.json
 ```
 
-For command-specific flags, run `interf <command> --help`.
+## Agent flow
+
+1. **Confirm a connection** — call `interf status` or `interf prep ls`. If they return `Not connected…`, ask the user to start an instance.
+2. **List or create a preparation** —
+   ```sh
+   interf prep ls                                                    # see what exists
+   interf prep create <id> --source <path> --method <method-id>      # create one
+   ```
+3. **Compile** — preparation id is positional:
+   ```sh
+   interf compile <prep-id> [--watch] [--quiet] [--idempotency-key <key>]
+   ```
+   Default is async-return: prints `run id`, the artifact `locator`, and current readiness. With `--quiet`, only the locator is printed (suitable for `$(interf compile bristol --quiet)/home.md`). With `--watch`, the CLI tails events until the run reaches a terminal state.
+4. **Inspect runs** —
+   ```sh
+   interf runs status <run-id>
+   interf runs watch <run-id>
+   interf runs ls [--prep <id>]
+   interf runs fetch <run-id> --to <abs-path>
+   interf runs cancel <run-id>
+   ```
+5. **Read the portable context** — for a local engine the locator is a `local-path` you can open directly with any tool. For a remote engine it is a signed `remote-url`; `interf runs fetch` localizes it.
+6. **On `not ready`**, propose method improvement:
+   ```sh
+   interf method improve <prep-id>
+   ```
+
+## Connected agents and the role map
+
+Interf treats the agents it can shell out to (Claude Code, Codex, custom CLIs) as a first-class primitive. `GET /v1/instance` reports `agent_count` and `default_agent`; if `agent_count` is `0`, **`interf compile` and `interf verify` will hard-error** — install one or register a custom CLI before retrying.
 
-In Interf Compiler UI freeform proposal mode, do not run CLI commands. Use `references/cli.md` instead. It is a generated snapshot of the current Interf CLI help and is checked against the built package in the repo test suite.
+```sh
+interf agents ls                                       # list registered + detected agents
+interf agents use <name>                               # set the active agent (sweeps role map)
+interf agents register <name> --command "<cmd>"        # register a custom CLI
+interf agents unregister <name>                        # remove a custom CLI
+interf agents map <role> <agent>                       # pin a role to an agent
+interf agents unmap <role>                             # fall back to the active agent
+```
+
+Roles are: `extractor`, `summarizer`, `structurer`, `verifier`, `general` (Methods may declare custom names; the engine treats unknown roles as `general`). Default behavior is single-active-agent — every role maps to the same agent — so existing agent flows do not change unless the user opts into per-role specialization.
+
+## Agent contract — flags every CLI run uses
+
+| Flag | What it controls | When the agent passes it |
+|---|---|---|
+| `--url <url>` | Override the active connection URL for one call. | When the user has multiple instances and wants to target a specific one without rewriting `~/.interf/connection.json`. |
+| `--token <token>` | Override the active bearer token for one call. | Cloud / non-loopback connections only. |
+| `--watch` | Block until the run finishes and tail stages. | Only when the agent must wait inline. Default is async return-with-id. |
+| `--quiet` | Print only the artifact locator on success. | Scripting (`$(interf compile bristol --quiet)`). |
+| `--idempotency-key <key>` | Sent as `X-Interf-Idempotency-Key`. The instance caches the key for an hour and returns the original run id on retries instead of starting a fresh run. | Whenever the agent might retry the same compile. |
+| `--to <abs-path>` | (`interf runs fetch`) Absolute destination to copy portable context into. Must be empty or non-existent unless `--overwrite` is set. | When the agent needs portable context outside the instance. |
+| `--overwrite` | (`interf runs fetch`) Allow copying into a destination that already has files. | Only when the agent wants to replace existing files. |
 
-## Operating Rules
+## Operating rules
 
-- Use exact Preparation ids from `interf list` or `interf/interf.json`.
-- Prefer the selected Preparation only when it is explicit or there is one obvious Preparation.
-- Do not invent readiness checks, Method ids, paths, or executor names.
-- Interf CLI actions should run through a connected local service so status and runs are visible in Interf. If the service is not running, tell the user to start `interf web` for the Workspace before running write actions.
-- Do not call the local HTTP API directly unless Interf explicitly gives an API integration task. Use CLI commands for normal agent work.
+- Use exact preparation ids and Method ids returned by the API. Do not invent ids.
+- Always confirm a connection exists before running mutating commands. Agents must not call `interf web` themselves — that command blocks the foreground; running it inside an agent loop hangs the loop.
+- For long-running work, use the async default and check status by id (`interf runs status <id>`). Only use `--watch` when the agent must wait inline.
+- Do not call the local HTTP API directly unless Interf explicitly gives an API-integration task. Use CLI commands for normal agent work.
 - Propose the command first and wait for approval before running commands that write files, start runs, create Method packages, build portable context, or run readiness checks.
-- If the request names an existing Preparation and asks to prepare, build, or refresh portable context, use `interf compile --preparation <name>`. The saved Preparation and selected Method are the source of truth.
 - If the request is ambiguous, ask one concise clarification instead of guessing.
 
-## Interf Compiler UI Freeform Proposal Mode
+## Show your work — always print the run URL
+
+Interf Compiler UI is the user's verification surface. The agent does
+the work; the user clicks a URL to see live trace, events, readiness,
+and proof. **Whenever you kick off a run, print a deep-link to the run
+page in the same message as the run id.** The user should never have
+to navigate the UI manually to find what you just started.
+
+The base URL is whatever `interf status` reports as the connected
+instance (e.g. `http://127.0.0.1:4873` for a local engine,
+`https://api.interf.cloud/...` for cloud). Append query params:
+
+| Param | Value |
+|---|---|
+| `preparation` | the preparation id |
+| `run` | the run id returned by the CLI |
+| `runTab` | optional: `trace` (default), `events`, or `readiness` |
+
+**Example output after `interf compile serge`:**
 
-When Interf Compiler UI asks for a proposal, do not run CLI commands. Write a
-single JSON object to the requested output path. Structured UI controls call the
-local service directly; this mode is only for freeform planning.
+```text
+Started compile run compile_8x2abc...
+Watch live: http://127.0.0.1:4873/?preparation=serge&run=compile_8x2abc...
+
+I'll check status in a moment with `interf runs status compile_8x2abc...`.
+```
+
+The same pattern applies to verify, method-improvement, and method-authoring
+runs. When a run finishes, print the same URL with `runTab=readiness` so the
+user can click through to the readiness summary.
+
+The agent stays the executor; the URL is the user's "I can see what's
+happening" handle. It also makes failures self-explanatory — when a run
+errors, the user clicks through to the same trace the agent is reading.
+
+## Reading the artifact locator
+
+`interf compile <prep-id>` prints a short multi-line block by default. The portable-context locator looks like one of:
+
+```text
+Portable context: /Users/me/.interf/preparations/bristol/portable-context
+```
+
+```text
+Portable context: https://api.interf.cloud/v1/runs/run_2x4abc.../portable-context
+```
+
+For `local-path`, use the agent's filesystem tools to read the directory. For `remote-url`, use HTTP or `interf runs fetch <run-id> --to <path>`.
+
+## Interf Compiler UI freeform proposal mode
+
+When Interf Compiler UI asks for a proposal, do not run CLI commands. Write a single JSON object to the requested output path. Structured UI controls call the local service directly; this mode is only for freeform planning.
 
 Use these action types:
 
@@ -46,35 +159,27 @@ Use these action types:
 - `method-improvement`
 - `clarification`
 
-Do not propose deterministic Preparation or Method mutations from this mode.
-Create, select, duplicate, and remove actions go through direct service
-endpoints in the UI or through the CLI for agent work. If freeform chat asks for
-one of those actions, return `clarification` and tell the caller to use the
-direct page control or CLI.
+Use `compile` when the user asks to prepare, build, or refresh portable context. Set `method` to the Method id and, if the request named one, `preparation` to the preparation id. CLI equivalent: `interf compile --method`.
 
-Use `compile` when the user asks to prepare, build, or refresh portable context for an existing Preparation. Do not ask what "prepare" means when the Preparation exists. Set `preparation` to the selected or mentioned Preparation id. CLI equivalent: `interf compile --preparation <name>`.
-
-For a readiness-check proposal, set `values.mode` to:
-
-- `raw` for source files only
-- `compiled` for portable context only
-- `both` for source files and portable context
+Readiness-check proposals always run against the compiled portable context in 0.15+. The legacy `values.mode` field is gone — omit it from `test` proposals.
 
 Return this shape:
 
 ```json
 {
   "action_type": "compile",
-  "preparation": "preparation-id",
-  "method": "method-id if applicable",
-  "values": {
-    "mode": "both if applicable"
-  },
+  "method": "method-id",
+  "preparation": "prep-id",
+  "values": { "mode": "both if applicable" },
   "title": "short approval card title",
   "summary": "one sentence describing what will run",
   "assistant_message": "concise explanation for the user",
-  "command_preview": "interf compile --preparation preparation-id"
+  "command_preview": "interf compile --method method-id"
 }
 ```
 
 Use `clarification` only when the request cannot be mapped safely to one Interf action.
+
+## Reference
+
+For the full CLI surface and per-command flags, see [`references/cli.md`](./references/cli.md). It is a generated snapshot of `interf <command> --help` and is checked against the built package in the repo test suite. The installed `interf` command remains the source of truth when available.