@interf/compiler 0.21.0 → 0.22.0

package/public-repo/plugins/interf/skills/interf/SKILL.md

@@ -1,34 +1,49 @@
 ---
 name: interf
-description: "Use when an agent needs to operate Interf from natural language: install or connect to the local Interf engine, manage Preparations, review Build Plans, compile source files into verifiable Artifacts, and read portable context for agent work."
+description: "Use when an agent needs to operate Interf from natural language: install or connect to the local Interf engine, manage Preparations, review Build Plans, build verifiable context from source files, and read the returned context locator for agent work."
 ---
 
 # Interf
 
-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. It runs locally, shows evidence that the data is ready, and writes portable context that agents can read.
+Agents miss things in files. Interf builds verifiable context for agents from
+your files. It turns hidden file discovery into traceable artifacts with proof
+of how they were built.
 
-The model is **Instance + Preparation + Artifacts + Build Plan**:
+Interf runs locally, shows evidence that the data is ready, and returns a
+context locator agents can read.
 
-- **Instance** = the engine (a local `interf web` process, or a future cloud endpoint). Owns all preparation state. Same wire shape both ends.
-- **Source** = input files or data. A local folder is the current binding shape; Interf scans it by reference, not by copy.
-- **Preparation** = the durable wrapper for a Source, agent goal, user instructions, requested Artifacts, Build Plan, connected agents, compile runs, readiness evidence, and portable-context location. Lives inside an instance.
-- **Build Plan** = the user-facing plan for how Interf will compile the requested Artifacts from the Source. It can be a draft candidate, selected for one Preparation, or saved/promoted for reuse. The current CLI/API still stores this through `method_id`.
-- **Method package** = the saved reusable Build Plan implementation (`method.json` + Artifact declarations + stage docs). It can be applied to different Sources and Preparations when installed or promoted.
-- **Artifact** = a Build Plan output agents need, such as an atlas, index, timeline, summary set, claim set, or custom file.
-- **Compile run** = one execution of a Preparation. Append-only. Produces portable context.
+## Core Model
 
-Agents should think in Artifacts: "what files do I need Interf to compile from this Source so I can do the user's job reliably?"
+- **Instance** = the local engine started by `interf web`, or a future cloud
+  endpoint. It owns all Preparation state.
+- **Source** = input files or data. A local folder is the current binding
+  shape; Interf scans it by reference, not by copy.
+- **Preparation** = the durable wrapper for a Source, agent goal, user
+  instructions, requested Artifacts, selected Build Plan, Build runs, connected
+  agents, readiness checks, and latest verifiable context.
+- **Requested Artifact** = an output agents need Interf to build, such as an
+  atlas, index, timeline, summary set, claim set, or custom file.
+- **Build Plan** = the user-facing plan for how Interf will build requested
+  Artifacts from the Source. It can be drafted, selected, saved, or improved.
+- **Build run** = one execution of a Build Plan for a Preparation. It records
+  what was processed, what was built, what failed, and whether the output is
+  ready.
+- **verifiable context** = the built output agents use.
 
-There is **no workspace concept**. The CLI carries one piece of state: the active connection record.
+Agents should think in requested Artifacts: "what do I need Interf to build
+from this Source so I can do the user's job reliably?"
+
+The CLI carries one piece of state: the active connection record.
 
 When Interf MCP tools are available, prefer them over shelling out to the CLI.
-They are API-backed and, in Cowork, can run from the user's device instead of
-the isolated VM shell. Use the CLI examples below as the fallback and as the
-source of command semantics.
+They are API-backed and can run from the user's device in hosts that support
+local MCP. Use the CLI examples below as fallback and as the source of command
+semantics.
 
-## Connection model
+## Connection Model
 
-The CLI is a thin authorized client of one connected instance. Every mutating command requires a reachable connection. If the active connection is missing or unreachable, the command exits non-zero with:
+Every mutating command requires a reachable Interf instance. If the active
+connection is missing or unreachable, the command exits non-zero with:
 
 ```text
 Not connected to any Interf instance.
@@ -36,47 +51,13 @@ Start one with `interf web` or `interf web start`, or set --url / `interf login`
 ```
 
 There is no hidden auto-start inside mutating commands. Agents must verify a
-connection exists before running mutating commands.
+connection before running mutating commands.
 
 Use `interf` when it is installed. If the command is missing, try
 `npx -y @interf/compiler@latest` for this session. If neither works, stop
-before mutating work and say plainly that this runtime can inspect the source
-and propose Artifacts, but cannot create a Preparation or run Interf until the
-CLI is installed or a reachable Interf instance is connected. Do not probe
-machine-specific install paths in the skill flow.
-
-Be explicit about which runtime you are using:
-
-- **Claude Code local / local terminal**: shell commands run on the user's
-  machine. This is the best current path for full Interf execution.
-- **Claude Code remote / cloud session**: shell commands run in the provider's
-  cloud environment. It can run Interf only if the Source, CLI, engine, and
-  compile-time agent executor are available inside that environment.
-- **Claude Cowork**: shell/code execution may run inside an isolated VM.
-  `127.0.0.1` from that shell may refer to the VM, not the Mac/Windows host.
-  Do not treat VM shell failure as proof that the user's local Interf engine is
-  down. Use a local Interf MCP bridge only when the host has actually launched
-  it on the user's device; otherwise use a local Claude Code / Codex session
-  for execution.
-- **Computer use**: Claude may be able to operate the user's actual desktop
-  apps with permission, but do not rely on screen automation as the primary
-  Interf execution path.
-
-In Cowork, a plain Skill is guidance only. It can teach Claude when to use
-Interf and how to explain requested Artifacts, but it does not by itself give
-Claude a host-level Interf tool. For full Cowork execution, the host must launch
-a local MCP server or desktop extension whose tools call the Interf service on
-the user's machine. The local tool surface should be `interf mcp`, which
-forwards to the same Interf service API as the CLI and UI. A remote connector is
-useful for Interf Cloud or public HTTPS endpoints; it is not the default way to
-reach `127.0.0.1` on the user's machine.
-
-When Interf is unavailable in the current runtime, do not create helper
-scripts, driver files, shell files, or command files for the user to run later.
-Do not write anything into the Source folder. The Source is read-only input.
-Give a short limitation message and the smallest next action instead, such as
-continuing in a local Claude Code / Codex session that can reach the Interf
-engine.
+before mutating work and say plainly that this runtime can inspect the Source
+and propose requested Artifacts, but cannot create a Preparation or run Interf
+until the CLI is installed or a reachable Interf instance is connected.
 
 For local or containerized agent sessions:
 
@@ -84,80 +65,42 @@ For local or containerized agent sessions:
 interf web                       # local: foreground server in another terminal
 interf web start                 # local: managed background server for agent sessions
 interf login --url <...>         # remote: writes connection.json
+interf status                    # confirm the active connection
 ```
 
 When using the `npx` fallback, replace `interf` in examples with
 `npx -y @interf/compiler@latest`.
 
-## Agent flow
-
-1. **Confirm a connection** — call `interf status` or `interf prep ls`. If the
-   command is missing, try the `npx` fallback once. If the command returns
-   `Not connected...`, start a managed local engine with `interf web start`,
-   then call `interf status` again. If the user already has a visible
-   `interf web` terminal running, do not start another engine; just connect to
-   it. Track whether you started the engine in this turn. Before ending the
-   session, run `interf web stop` if you started it and no compile/test run is
-   still active. Do not run foreground `interf web` inside the agent loop
-   because it blocks.
-   In Cowork, only start or stop Interf from a trusted host-level Interf MCP
-   tool or local desktop extension. Do not ask the VM shell to start a local
-   Mac/Windows engine and then expect the VM's `127.0.0.1` to reach it.
-2. **Propose requested Artifacts in human language** — first inspect what you
-   can about the Source the user gave you: filenames, file types, obvious page
-   counts, section names, and anything that affects the user's question. Treat
-   that as an advisory source profile, not proof that Interf processed the
-   files. Then propose the Artifacts you need before answering.
-
-   Focus on what the agent needs Interf to prepare so it does not miss
-   important source evidence. Do not turn normal analysis choices into blocking
-   questions. If a term is ambiguous but the Source gives reasonable candidates,
-   state the assumption and record the ambiguity as an Artifact check. Ask a
-   clarification only when the Source or task cannot be identified, or when the
-   ambiguity makes the Artifact request impossible to draft.
-
-   If the user invoked `/interf` or explicitly said to use Interf for this
-   task, that is permission to inspect the Source and propose requested
-   Artifacts only. Stop after the proposal. Do not create the Preparation,
-   draft the Build Plan, or compile until the user explicitly says to create,
-   draft, proceed, or do the flow end-to-end.
-
-   Do not show JSON to the user. Do not copy example wording from this skill.
-   Do not use technical labels such as "scope resolver", "evidence map",
-   "market page relevance map", or "comparison evidence". Use short names a
-   knowledge worker understands. Prefer a few meaningful Artifacts, but do not
-   invent a fixed maximum.
-
-   Keep the first proposal compact enough to fit on one screen:
-
-   - one sentence naming the source and what you know about it
-   - one short sentence explaining why Interf helps for this task
-   - one short sentence for any important ambiguity, phrased as an assumption
-   - a compact numbered list of Artifacts
-   - one final line asking the user to approve or edit
-
-   Do not use markdown tables; some chat surfaces collapse them into unreadable
-   text. Do not write Artifact entries as paragraphs. For each Artifact, use a
-   readable mini-card:
-
-   - Artifact name as the numbered line, in bold
-   - `Why it helps:` one short sentence
-   - `Checks:` followed by two or three plain-English bullet points
-
-   Each check must be a complete human-readable sentence, not compressed
-   shorthand. Keep checks concrete enough that a user can say "yes, that is
-   what I wanted." Do not include extracted numbers, chart readings, JSON
-   fields, stage names, or commands in the human proposal. Detailed numbers
-   belong in the compiled Artifacts, not in the proposal.
-
-   Format shape. Replace the placeholders with the actual source and task; do
-   not output angle-bracket placeholders.
+## Agent Flow
+
+1. **Confirm a connection**.
+
+   Run `interf status` or `interf prep ls`. If the command returns the
+   connection hint, start a managed local engine with `interf web start`, then
+   call `interf status` again. If the user already has a visible `interf web`
+   terminal running, do not start another engine. Track whether you started the
+   engine in this turn. Before ending the session, run `interf web stop` if you
+   started it and no Build run or check run is still active.
+
+2. **Propose requested Artifacts before mutating state**.
+
+   First inspect what you can about the Source: filenames, file types, obvious
+   page counts, section names, and anything that affects the user's question.
+   Treat that as an advisory source profile, not proof that Interf processed the
+   files.
+
+   If the user invoked `/interf` or explicitly asked to use Interf, that is
+   permission to inspect the Source and propose requested Artifacts only. Stop
+   after the proposal unless the user explicitly says to create, draft, proceed,
+   or do the flow end-to-end.
+
+   Keep the proposal compact:
 
    ```text
    I found <source summary>. For <task>, I should prepare the source first because <risk>.
    <Optional ambiguity or assumption in one sentence.>
 
-   1. **<Plain-English name>**
+   1. **<Plain-English artifact name>**
       Why it helps: <short sentence>
       Checks:
       - <human-readable check>
@@ -166,273 +109,228 @@ When using the `npx` fallback, replace `interf` in examples with
    If this looks right, tell me to create the Preparation and draft the Build Plan for review. I will stop here until you approve it.
    ```
 
-   Store the same proposal as structured
-   `requested_artifacts[]` on the Preparation. Store the advisory source
-   interpretation as `source_profile` when useful. `requested_artifacts[]`
-   requires only a `title`; include `purpose`, `checks[]`, and stable `id`
-   values when you know them. Only include exact `output.shape` / typed output
-   checks when you already know the required Build Plan output contract.
-3. **List or create a preparation after the user approves the Artifact proposal** —
+   Do not show JSON to the user. Do not use markdown tables. Do not include
+   extracted numbers, chart readings, schema fields, stage names, or commands in
+   the human proposal. Detailed numbers belong in the built Artifacts.
+
+3. **Create the Preparation after approval**.
+
    ```sh
-   interf prep ls                                                    # see what exists
+   interf prep ls
    interf prep create <id> --source <path> [--about "<agent job>"] \
      --requested-artifacts-json '<json-array>' \
      --source-profile-json '<json-object>'
-   interf prep set-method <id> <method-id>                           # select later if needed
    ```
-   Keep JSON out of the human proposal. Use compact JSON only in the command
-   or API request after the user confirms.
-4. **Draft the Build Plan after the user approves the Artifact proposal unless the user chose a saved one** — for real
-   analytical work, the recommended path is a custom Build Plan for this
-   Preparation. Do not silently bind `interf-default` as the final plan just
-   because it exists. Use `interf-default` only when the user explicitly asks
-   for the default/smoke-test flow or when you need a temporary fallback.
 
-   If the user has not chosen an existing Build Plan, say plainly:
+   Store the approved proposal as `requested_artifacts[]`. Store the advisory
+   source interpretation as `source_profile` when useful. Use compact JSON only
+   in the command or API request after the user confirms.
 
-   ```text
-   I'll create the Preparation and draft a custom Build Plan for review. This may take a few minutes. I'll send the review link when the plan is ready; I will not compile until you approve it.
-   ```
+4. **Draft or select a Build Plan**.
 
-   Then run:
+   For real analytical work, prefer a custom Build Plan for the Preparation.
+   Use the default `interf-default` Build Plan only when the user explicitly
+   asks for the default/smoke-test flow or accepts it as a fallback.
 
    ```sh
-   interf method draft <prep-id> \
+   interf build-plan draft <prep-id> \
      --task "<agent job>" \
      --artifacts "<optional extra Artifact notes or change request>" \
      --ready-when "<proof and coverage the user should trust>"
-   interf runs status <run-id>      # poll until the draft run is terminal
-   interf method show <method-id>   # summarize the drafted Build Plan headlessly
+   interf runs status <run-id>
+   interf build-plan show <build-plan-id>
+   interf build-plan select <prep-id> <build-plan-id>
    ```
 
-   Do not generate custom shell polling loops. In Cowork or any MCP-enabled
-   host, use the Interf MCP `runs_status` tool for status checks. In CLI-only
-   hosts, run `interf runs status <run-id>` as a single command when you need a
-   fresh status, or share the run link and continue without blocking. Avoid
-   asking the user to approve repeated polling commands.
-
-   `interf method draft` automatically receives saved `requested_artifacts[]`
-   and `source_profile` from the Preparation. If you already resolved exact
-   Build Plan output constraints, pass them with
-   `--artifact-requirements-json '<json-array>'`; otherwise let the Build Plan
-   draft agent decide the output paths and checks from the requested Artifacts.
-
-   While the Build Plan is being drafted, do not show the Preparation review
-   link as if the plan is ready. You may show the run link so the user can see
-   activity, but the review link comes after the draft run finishes and the
-   candidate Build Plan is available. After the draft finishes, show the user a
-   short text summary of the Build Plan Artifacts and stages from
-   `interf method show <method-id>` so review works even when they do not open
-   the UI.
-5. **Show the review link before compile by default** — after the Build Plan is
-   drafted, selected, or materially changed, send the user to the Preparation
-   Build Plan review:
+   Do not generate custom shell polling loops. In MCP-enabled hosts, use the
+   Interf MCP run-status tool. In CLI-only hosts, run `interf runs status
+   <run-id>` as a single command when you need fresh status.
+
+5. **Show the Build Plan review before building by default**.
+
+   After the Build Plan is drafted, selected, or materially changed, send the
+   user to:
+
    ```text
    http://127.0.0.1:4873/?section=preparations&preparation=<prep-id>&preparationTab=build-plan
    ```
-   Build Plan drafting creates or updates a candidate plan with its own Activity
-   record. A successful draft run selects that Build Plan on the Preparation so
-   the review page is concrete; it still does not mean the user approved a
-   compile run.
-   The thing to review is the requested Artifacts and the Build Plan: which
-   Artifacts will be compiled, why the agent needs them, which stages will
-   build them, and what proof should show the Source was fully processed.
-   Include the same information in the chat as a compact summary: requested
-   Artifacts, stage names, and what each stage writes.
-   Unless the user explicitly asked you to handle the whole flow autonomously,
-   pause here so they can select, remove, or ask you to change the proposed
-   Artifacts, then select the candidate Build Plan for the Preparation before
-   you start a compile run. If the plan should be reused, save/promote it as a
-   Method package. If they ask for changes, draft/improve the Build Plan and
-   show the review link again. If they already granted autonomy, you may select
-   the candidate Build Plan and compile, but still print the Artifacts review
-   link and the compile run link so the user can inspect what happened.
-6. **Compile** — preparation id is positional:
+
+   Include a compact chat summary: requested Artifacts, stage names, what each
+   stage writes, and the proof/readiness checks the user should expect. Unless
+   the user granted autonomy, pause here.
+
+6. **Build verifiable context**.
+
    ```sh
-   interf compile <prep-id> [--watch] [--quiet] [--idempotency-key <key>]
+   interf build <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. With `--watch`, the CLI tails events until the run reaches a terminal state.
-7. **Inspect runs** —
+
+   Default is async-return: prints the Build run id, the artifact locator, and
+   current readiness. With `--quiet`, only the locator is printed. With
+   `--watch`, the CLI tails events until the run reaches a terminal state.
+
+7. **Inspect runs and readiness**.
+
    ```sh
    interf runs status <run-id>
    interf runs ls [--prep <id>]
-   interf runs fetch <run-id> --to <abs-path>
    interf runs cancel <run-id>
+   interf test <prep-id>
    ```
-8. **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.
-9. **On `not ready`**, propose Build Plan improvement:
+
+8. **On `not ready`, improve the Build Plan**.
+
    ```sh
-   interf method improve <prep-id> \
+   interf build-plan improve <prep-id> \
      --task "<what needs to change>" \
      --artifacts "<Artifact changes, if any>" \
      --ready-when "<proof or coverage changes, if any>"
    ```
 
-## Connected agents and the role map
+## Connected Agents
 
-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 test` will hard-error** — install one or register a custom CLI before retrying.
+Interf treats the agents it can shell out to, such as Claude Code, Codex, and
+custom CLIs, as connected local agents. `GET /v1/instance` reports
+`agent_count` and `default_agent`. If `agent_count` is `0`, `interf build` and
+`interf test` hard-error until the user installs or registers an agent.
 
 ```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
+interf agents ls
+interf agents use <name>
+interf agents register <name> --command "<cmd>"
+interf agents unregister <name>
+interf agents map <role> <agent>
+interf agents unmap <role>
 ```
 
-Roles are: `extractor`, `summarizer`, `structurer`, `verifier`, `general` (Build Plans / Method packages 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.
+Roles are `extractor`, `summarizer`, `structurer`, `verifier`, and `general`.
+Build Plans may declare custom names; the engine treats unknown roles as
+`general`. Default behavior is single-active-agent.
 
-## Agent contract — flags every CLI run uses
+## CLI Flags
 
 | 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 changing the active connection record. |
+| `--url <url>` | Override the active connection URL for one call. | Multiple instances or remote target. |
 | `--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. |
+| `--watch` | Block until the run finishes and tail stages. | Only when the agent must wait inline. |
 | `--quiet` | Print only the artifact locator on success. | Scripting and agent handoff. |
-| `--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. | When the agent needs portable context outside the instance. |
-
-## Operating rules
-
-- Use exact preparation ids and Build Plan / Method-package ids returned by the API. Do not invent ids.
-- Always confirm a connection exists before running mutating commands. If no
-  instance is connected, explicitly run `interf web start` for an agent-owned
-  local/container session, ask the user to start foreground `interf web` when
-  they want to own the engine, or connect a remote instance. Do not call
-  foreground `interf web` inside the agent loop because it blocks.
-- 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.
-- If the user invoked `/interf` or explicitly asked to use Interf for a data
-  task, stop after the concise Artifact proposal. Do not create the
-  Preparation or start the Build Plan draft run until the user explicitly
-  approves the proposal or grants autonomy. Print run links only after a run
-  actually starts.
-- Do not create shell scripts or handoff files when the CLI is unavailable.
-  Never write helper files into the Source folder. If you cannot run Interf,
-  say that directly and stop after the Artifact proposal.
+| `--idempotency-key <key>` | Sent as `X-Interf-Idempotency-Key`. The instance returns the original run id on retries. | Whenever the agent might retry the same build. |
+
+## Operating Rules
+
+- Use exact Preparation ids and Build Plan ids returned by the API. Do not
+  invent ids.
+- Always confirm a connection exists before running mutating commands.
+- For long-running work, use the async default and check status by id. Use
+  `--watch` only 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 or Interf MCP tools for normal agent
+  work.
+- Never write helper files into the Source folder. The Source is read-only
+  input.
 - Treat requested-Artifact and Build Plan review as the default human trust
-  gate. Do not bury the proposed Artifacts in prose; link the user to the
-  Preparation Build Plan review before compile when the Build Plan was newly drafted or
-  materially changed. Drafted Build Plans are candidates until they are selected
-  for the Preparation by the user or by an agent acting under explicit autonomy.
-  Save/promote a useful plan as a Method package when reuse matters.
-- When the user asks for a new analysis over their data, prefer “create
-  Preparation → draft custom Build Plan → show review link → compile after
-  approval.” Only use `interf-default` as the selected Build Plan when the user
-  explicitly asks for the default, asks for a fast smoke test, or accepts that
-  fallback after you explain the tradeoff.
-- When drafting or improving a Build Plan, pass the user's requested Artifact
-  shape and change request in the UI/action form when available. From CLI,
-  pass the request through `--task`, `--artifacts`, and `--ready-when` so the
-  Build Plan run has the actual user intent, not just the Preparation id.
-- Separate proposal from proof. Before compile, you can say what Interf plans
-  to build and what coverage/proof it will check. After compile, you can say
-  which files/pages were processed, what evidence was produced, and whether
-  portable context is ready.
-- In review copy, lead with proposed Artifacts and the stage plan that will
-  build them. The Method package is the technical container; the user's decision
-  is whether those Artifacts and the Build Plan are the right portable context
-  for the agent work.
+  gate.
+- Separate proposal from proof. Before a Build run, you can say what Interf
+  plans to build and what coverage/proof it will check. After a Build run, you
+  can say which files/pages were processed, what evidence was produced, and
+  whether the verifiable context is ready.
 - Ask one concise clarification only when the Source or agent goal is missing,
-  or when the ambiguity makes the requested Artifacts impossible to draft. For
-  normal domain ambiguity, state the assumption and make it a check in the
-  requested Artifacts / Build Plan.
+  or when ambiguity makes the requested Artifacts impossible to draft. For
+  normal domain ambiguity, state the assumption and make it a check.
 
-## Show your work — always print the run URL
+## Show Your Work
 
-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.
+Interf UI is the user's verification surface. Whenever you start a run, print a
+deep link to the run page in the same message as the run id.
 
-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:
+The base URL is whatever `interf status` reports as the connected instance.
+Append query params:
 
 | Param | Value |
 |---|---|
-| `preparation` | the preparation id |
+| `preparation` | the Preparation id |
 | `run` | the run id returned by the CLI |
-| `runTab` | optional: `trace` (default), `events`, or `readiness` |
+| `runTab` | optional: `trace`, `events`, or `readiness` |
 
-**Example output after `interf compile <prep-id>`:**
+Example output after `interf build <prep-id>`:
 
 ```text
-Started compile run <run-id>.
+Started Build run <run-id>.
 Watch live: http://127.0.0.1:4873/?preparation=<prep-id>&run=<run-id>
 
 I'll check status in a moment with `interf runs status <run-id>`.
 ```
 
-The same pattern applies to readiness-check, Build Plan improvement, and
-Build Plan 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.
+When a run finishes, print the same URL with `runTab=readiness` so the user can
+click through to the readiness summary.
 
-## Reading the artifact locator
+## Reading The Context Locator
 
-`interf compile <prep-id>` prints a short multi-line block by default. The portable-context locator looks like one of:
+`interf build <prep-id>` prints a short multi-line block by default. The context
+locator looks like one of:
 
 ```text
-Portable context: <local-path-returned-by-interf>
+Context: <local-path-returned-by-interf>
 ```
 
 ```text
-Portable context: https://api.interf.cloud/v1/runs/run_2x4abc.../portable-context
+Context: https://api.interf.cloud/v1/runs/run_2x4abc.../verifiable-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>`.
+For `local-path`, use the agent's filesystem tools to read the directory. For
+`remote-url`, use HTTP.
 
-## Interf Compiler UI freeform proposal mode
+## Interf 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.
+When Interf 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:
 
-- `compile`
+- `build`
 - `test`
 - `readiness-check-draft`
-- `method-authoring`
-- `method-improvement`
+- `build-plan-draft`
+- `build-plan-improvement`
 - `clarification`
 
-Use `compile` when the user asks to prepare data, build artifacts, refresh portable context, or compile source files for agent work. Set `method` to the selected Build Plan id, and, if the request named one, `preparation` to the preparation id. CLI equivalent: `interf compile <prep-id>`.
+Use `build` when the user asks to prepare data, build artifacts, or refresh
+verifiable context for agent work. Set `build_plan` to the selected Build Plan
+id if the request named one, and set `preparation` to the Preparation id if the
+request named one. CLI equivalent: `interf build <prep-id>`.
 
-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.
+Readiness-check proposals run against verifiable context unless the user asks
+for a source-files baseline.
 
 Return this shape:
 
 ```json
 {
-  "action_type": "compile",
-  "method": "method-id",
+  "action_type": "build",
+  "build_plan": "build-plan-id",
   "preparation": "prep-id",
   "title": "short approval card title",
-  "summary": "one sentence describing which artifacts will be compiled",
+  "summary": "one sentence describing which artifacts will be built",
   "assistant_message": "concise explanation for the user",
-  "command_preview": "interf compile prep-id"
+  "command_preview": "interf build prep-id"
 }
 ```
 
 For Build Plan drafting proposals, keep requested Artifacts structured in
 `values.requested_artifacts[]` and keep the advisory source summary in
-`values.source_profile`. Do not flatten them into prose only:
+`values.source_profile`:
 
 ```json
 {
-  "action_type": "method-authoring",
+  "action_type": "build-plan-draft",
   "preparation": "prep-id",
-  "method": "prep-id-build-plan",
+  "build_plan": "prep-id-build-plan",
   "title": "Draft Build Plan",
   "summary": "Drafts the Build Plan for the requested Artifacts.",
   "values": {
-    "method_id": "prep-id-build-plan",
+    "build_plan_id": "prep-id-build-plan",
     "task_prompt": "London versus South West annual take-up",
     "requested_artifacts": [
       {
@@ -449,7 +347,8 @@ For Build Plan drafting proposals, keep requested Artifacts structured in
 }
 ```
 
-Use `clarification` only when the request cannot be mapped safely to one Interf action.
+Use `clarification` only when the request cannot be mapped safely to one Interf
+action.
 
 ## Reference
 
@@ -469,7 +368,7 @@ Use CLI read commands before asking the user to inspect the UI:
 ```sh
 interf status
 interf prep show <prep-id>
-interf method show <method-id>
+interf build-plan show <build-plan-id>
 interf runs status <run-id>
 ```