@interf/compiler 0.22.2 → 0.50.0

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

@@ -1,198 +1,473 @@
 ---
 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, build verifiable context from source files, and read the returned context locator for agent work."
+description: "Use when an agent needs to operate Interf from natural language: connect to the local Interf service, manage Projects, review Build Plans, build Context Graphs from source files, and read the returned Context Graph locator for agent tasks."
 ---
 
 # Interf
 
-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.
+Interf prepares data for agent tasks. It lets users' agents build a Context Graph
+from their files with source coverage
+summaries, task-aware knowledge, graph entrypoints, and links back to sources,
+so users can inspect what was covered before agents answer.
 
-Interf runs locally, shows evidence that the data is ready, and returns a
-context locator agents can read.
+Interf is not a search engine and not a general RAG index over every Project
+the instance has seen. Treat it as a data-preparation workflow for the user's
+current Source and task. Existing Projects and Context Graphs are reusable only
+when they clearly bind the same Source and task-relevant Build Plan.
+
+Ask Claude to answer from a folder. With Interf, Claude builds a Context Graph
+from the files and the user can inspect what it covered. Interf runs locally,
+exposes Graph Manifest metrics, Stage Manifest coverage, traces, and ready /
+not ready status, preserves stage execution shells for inspection, and returns
+a Context Graph locator agents can read.
 
 ## Core Model
 
-- **Instance** = the local engine started by `interf web`, or a future cloud
-  endpoint. It owns all Preparation state.
+- **Instance** = the local service reached through Interf MCP, an installed CLI
+  connection, explicit URL/token details, or a developer-started
+  `interf runtime`. It owns all Project 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.
-
-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 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.
+  shape; Source stays local and read-only, and Interf reads it by reference,
+  not by copy.
+- **Project** = the durable workspace for one Source binding, agent task
+  intent, selected Build Plan, Project activity, execution agents, and the
+  latest Context Graph.
+- **Build Plan** = the reviewed recipe for how Interf will build a Context
+  Graph from the Source for the Project intent. It owns requested outputs,
+  expected inputs, coverage metrics, graph entrypoints, Build instructions,
+  and optional Source context. It can be drafted, selected, saved, or improved.
+  CLI namespace: `interf plan`.
+- **Run** = one durable execution record. Build runs, benchmark runs,
+  Build Plan draft runs, and Build Plan improvement runs are all Runs.
+- **execution shell** = the replayable workspace Interf creates for an
+  agent-executed stage. It contains stage-local `AGENTS.md` / `CLAUDE.md`, the
+  native skill, contract, expected inputs, Source Manifest, required prior
+  outputs, writable output mounts, prompt log, event/status logs, validator,
+  and validation attempts. Stage retries create a fresh shell with previous
+  attempts and validation feedback mounted under `runtime/`. Use it for
+  debugging and retry; do not present it as the product output.
+- **Build Context Graph** = the action that runs the selected Build Plan for a
+  Project and produces one Context Graph. CLI: `interf build <project-id>`.
+- **Context Graph** = source-backed context built from files so agents can use
+  prepared context instead of partial file reads. It contains `home.md`, graph
+  entrypoints, summaries, knowledge notes, links back to sources, and traces.
+  Current local builds expose it as an inspectable folder agents can continue
+  from.
+
+Agents should think in Build Plan contracts: "what Context Graph outputs,
+expected inputs, coverage metrics, entrypoints, and traces need to exist before
+I can answer from this Source without partial file reads?"
+
+## Source Reference Contract
+
+The Context Graph is a knowledge map over the Source. It normally contains
+`home.md`, `artifacts/` graph entrypoints, `summaries/` coverage proof,
+`knowledge/` navigation/drilldown, traces, and source references. It does not
+duplicate the raw Source files.
+
+A built Context Graph has three fixed top-level layers and `home.md`:
+
+- `summaries/` — grounding: one folder per Source file, each linking back to its
+  Source. This is COVERAGE proof (every file was read; file-level, not a claim
+  that every fact was captured).
+- `knowledge/` — the knowledge web: claims, entities, timelines, tables, etc.
+  Every note links DOWN to its summary and carries raw `source_refs`, and notes
+  link to EACH OTHER. This is TRACEABILITY (every claim links a Source; no
+  orphaned summaries; no disconnected islands).
+- `artifacts/` — higher-level task outputs that reference summaries + knowledge
+  (+ raw source refs for exact claims).
+- `home.md` — start here; routes into all three.
+
+Readiness (`ready` / `not ready`) is backed by COVERAGE and TRACEABILITY — both
+provable and deterministic. A separate VERIFICATION pass (`interf benchmark`) is
+a fallible double-check: it flags claims a verifier could not confirm against the
+cited file. It is not proof of absence and does not gate readiness — for exact
+claims, always read the original Source via the note's `source_refs`.
+
+Use the Context Graph first to learn what exists, which files/pages/figures are
+relevant, which graph outputs were prepared, and where evidence lives in the
+original Source. Then follow the graph's source references when exact wording,
+table values, chart positions, visual ranges, or provenance matter.
+
+"Answer from the Context Graph" means:
+
+- start from `home.md` as the primary graph entrypoint;
+- use generated `artifacts/` as task-specific graph entrypoints;
+- use `summaries/` for coverage proof and `knowledge/` for navigation/drilldown;
+- use the graph's source references and traces as backlinks to the source of
+  truth;
+- drill into cited source pages/figures/tables when precision matters;
+- keep the answer grounded in the prepared graph plus its cited source evidence.
+
+It does not mean:
+
+- treat summaries or artifacts as a replacement for the underlying Source;
+- ignore the original data after the graph points to the relevant evidence;
+- make a strong claim from a blurry or under-extracted artifact.
+
+## Non-Negotiable Interf Behavior
+
+If the user invoked `/interf` or explicitly asked to use Interf, the agent must
+not bypass Interf by answering from ad hoc raw source-file reads.
+
+Do not tell users to invoke `/anthropic-skills:interf` for the local demo. The
+local Interf Skill command is `/interf`. A host-specific managed skill with a
+prefixed namespace may be stale and outside this repo's control.
+
+No fallback direct-read answer is allowed. Do not open PDFs, screenshots,
+exports, extracted text files, or report bodies to answer the user's question
+when Interf is unreachable. Do not say "I could not reach Interf, so I read the
+files directly." That is the failure mode Interf exists to prevent.
+
+After Interf has built or selected a Context Graph, opening the graph-cited
+source reference for exact verification is allowed and often required. That is
+not a fallback. It is the graph's backlink model.
+
+Allowed before a reachable Interf connection:
+
+- check whether Interf is running;
+- inspect filenames, extensions, and obvious source-folder shape only if needed
+  to identify the Source;
+- ask the user to start `interf runtime` / `interf runtime start`, connect the
+  agent through Interf MCP, or provide explicit Interf URL/token details.
+
+Required when Interf is unreachable:
+
+```text
+I can't answer this through Interf yet because I cannot reach a connected Interf instance.
+Please start Interf with `interf runtime` or `interf runtime start`, connect this agent through Interf MCP, or provide the Interf URL/token. Then I will build or inspect the Context Graph before answering.
+```
+
+Only answer after one of these is true:
+
+- an Interf Build has produced a Context Graph for the Project;
+- a ready existing Context Graph for the same Source and task-relevant Build
+  Plan is selected and inspected;
+- the user explicitly cancels Interf and asks for a normal direct file read.
+
+## Required User-Visible Flow
+
+When the user asks Interf to read a Source and answer a question, the agent's
+first job is to define the data-preparation contract, not to answer. Follow
+these gates in order.
+
+Do not satisfy a new question by searching unrelated existing Projects. In the
+connected-instance path, create a fresh Project for the current Source and task
+unless the user explicitly selected or named an existing Project. If the user
+has not provided a Source, ask for the Source instead of answering from whatever
+Projects already exist. Project ids are generated internally; do not ask the
+user to provide one.
+
+Source scope default: when Interf MCP, the CLI, explicit connection details, or
+the user context already provides a Source locator or file set, use that whole
+Source. Do not ask the user to choose one file, both reports, or all files
+inside that Source unless the user explicitly asks to narrow scope. If no
+usable Source locator is available, ask for one Source locator, usually a local
+folder path. Do not ask for a file-selection menu.
+
+1. **Propose requested outputs and coverage first.**
+
+   Say what Interf needs to prepare before the answer can be trusted. Requested
+   outputs are GRAPH AREAS — claim nodes, comparison nodes, a timeline, a
+   coverage index — the next agent will read and reason over. They are NOT
+   the answer itself, NOT a finished report, and NOT a summary document. Source
+   stays in the user's files; Interf builds the task-specific Context Graph
+   the agent traverses. The output is a short in-chat review:
+
+   ```text
+   Before I answer, Interf should prepare this Context Graph for the question.
+
+   Context Graph outputs (graph areas, not the answer):
+   1. <output name> — <which claim nodes / comparison nodes / timeline Interf will prepare>
+   2. <output name> — <same, for the next area>
+
+   Coverage I will verify:
+   - files processed
+   - source units summarized
+   - knowledge reviewed and used
+   - graph entrypoints generated
+
+   Approve these outputs and coverage expectations, and I will draft the Build Plan.
+   ```
+
+   Stop here unless the user has already explicitly approved this exact set of
+   outputs and coverage expectations. Do not answer yet.
+
+2. **Draft the Build Plan after approval.**
+
+   Create or reuse the Project, draft the Build Plan, then summarize it in
+   chat. Include the Project id, Build Plan id, requested outputs, stages,
+   expected inputs, graph entrypoints, and what the Context Graph will contain.
+   Include a review locator when the connected Interf client provides one, but
+   the user should be able to review the plan in chat.
+
+   Stop here unless the user approves the Build Plan or already gave explicit
+   end-to-end autonomy after reviewing the outputs and coverage expectations.
+
+3. **Build the Context Graph after Build Plan approval.**
+
+   Start the Build, show the Build id and any review locator returned by the
+   connected Interf client, then check status by Run id. If the user asked for
+   an answer in the same request, continue until the Build reaches a terminal
+   state.
+
+   If a Build Plan draft, Build Plan improvement, Build run, or status poll
+   reaches `failed` or `cancelled`, stop. Report which Run failed, summarize the
+   visible error, and ask the user before starting another draft or Build run.
+   Do not automatically retry failed Interf Runs.
+
+4. **Answer only from the Context Graph.**
+
+   Read `home.md` first. Use generated graph entrypoints under `artifacts/`
+   as task-specific starting points, `summaries/` as coverage proof, and
+   `knowledge/` as drilldown. For exact values,
+   quotes, chart reads, tables, or provenance-sensitive claims, follow the
+   graph's source references back to the cited Source evidence before answering.
+   Answer with the values the Context Graph prepared plus any source-reference
+   verification you performed, and say which graph entrypoint and source page
+   the answer came from. If the Context Graph points to the right evidence but
+   the prepared graph output is too coarse, under-extracted, or missing the required visual
+   semantics, say the Context Graph is not ready and improve the Build Plan.
+
+The public package path is CLI/runtime-first. MCP is how agent hosts talk to a
+connected Interf instance when the host supports local MCP tools. Use **Interf
+MCP** when available, then this Skill as the instruction fallback, then direct
+HTTP only with explicit local URL/token details.
+
+Interf MCP lets an outside agent host talk to Interf. Agents listed inside
+Interf are executors that run Build Plan stages. Do not treat executor setup as
+the same thing as MCP setup.
+
+Use this order:
+
+1. **Interf MCP**, when available.
+2. The installed `interf` CLI with an active connection.
+3. A developer-started local runtime from `interf runtime` or
+   `interf runtime start`.
+4. This bundled Skill, when MCP is not available in the agent host.
+5. Direct local HTTP only for the well-known discovery probe or when Interf
+   explicitly provides the local URL/token.
+
+Do not install packages or use `npx` as part of the normal flow. If MCP is not
+available and the CLI has no active connection, ask the user to start
+`interf runtime` / `interf runtime start`, run `interf login --url <url>` for a
+remote instance, or provide explicit Interf URL/token details.
+
+If MCP is not configured, you may probe `http://127.0.0.1:4873/health` to see
+whether the default local runtime is running. Do not scan ports. Do not treat
+discovery as authorization. Any mutating or source-reading request needs the
+active bearer token from **Interf MCP**, the installed CLI connection, or
+connection details explicitly provided by Interf.
+
+Keep MCP and connection probing internal. Do not narrate "CLI is installed",
+"discovery returned 200", raw URLs, ports, or token state in the normal demo
+flow. User-facing language should be only: Interf connection available, or this
+agent is not connected to Interf yet.
+
+When confirming a connection, say that Interf is running. Do not report
+package, CLI, or service versions unless the user explicitly asks for debug
+details.
 
 ## Connection Model
 
-Every mutating command requires a reachable Interf instance. If the active
-connection is missing or unreachable, the command exits non-zero with:
+Every mutating action requires a reachable Interf instance.
 
-```text
-Not connected to any Interf instance.
-Start one with `interf web` or `interf web start`, or set --url / `interf login` for a remote one.
-```
+In the public CLI path, the user starts a local instance with `interf runtime`
+or `interf runtime start`. A remote or managed instance can be selected with
+`interf login --url <url>` when available. Agent hosts may instead connect
+through Interf MCP or explicit URL/token details.
+
+Discovery is not enough by itself. A 200 response from `/health` only means a
+local service is running. If discovery succeeds but there is no MCP connection,
+no active CLI connection, and no explicit URL/token, stop and ask the user to
+connect this agent to Interf.
 
-There is no hidden auto-start inside mutating commands. Agents must verify a
-connection before running mutating commands.
+If the local discovery probe is unreachable, say:
 
-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 requested Artifacts, but cannot create a Preparation or run Interf
-until the CLI is installed or a reachable Interf instance is connected.
+```text
+I need Interf running before I can build a Context Graph.
+Please start `interf runtime` or `interf runtime start`, then connect this agent through Interf MCP or the installed CLI connection.
+```
 
-For local or containerized agent sessions:
+For local developer sessions with the CLI already installed:
 
 ```sh
-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
+interf runtime                   # fallback: foreground local service
+interf runtime start             # fallback: managed background service
 ```
 
-When using the `npx` fallback, replace `interf` in examples with
-`npx -y @interf/compiler@latest`.
+### Review References
+
+When a Project, Build Plan, or Run is created, include the compact review
+summary in chat: Project id, Build Plan id, Run id, requested outputs, primary
+metrics, and the Context Graph locator when ready.
+
+The local HTTP URL is an authorized service connection fallback, not a review
+UI. Do not present `127.0.0.1` links as the review surface for normal users.
 
 ## 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.
+   If Interf MCP tools are available, call `get_instance_status` or
+   `instance_status`, depending on the host profile. If only the CLI is
+   available, run `interf status`. If neither is available, probe
+   `http://127.0.0.1:4873/health` only to check whether the default local
+   runtime is running.
 
-2. **Propose requested Artifacts before mutating state**.
+   Keep these checks quiet. Do not tell the user which transport worked or
+   failed unless they explicitly asked to debug Interf connectivity.
 
-   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 Interf provides explicit connection details for this session, pass them
+   on each CLI call:
+
+   ```sh
+   --url "<service_url>" --token "<auth_token>"
+   ```
+
+   Do not write the token into files and do not echo it to the user.
+
+   Do not run hidden runtimes as an automatic recovery step. If MCP cannot
+   reach the instance, the CLI has no active connection, and no explicit
+   URL/token was provided, ask the user to start `interf runtime` or
+   `interf runtime start`, connect through Interf MCP, or provide connection
+   details. Stop here. Do not read the Source and do not answer the user's
+   question from raw files.
+
+   Treat `package_version`, CLI versions, and raw service metadata as internal
+   diagnostics. Do not include them in normal user-facing replies.
+
+2. **Propose what Interf will prepare before mutating state**.
+
+   After confirming an Interf connection, 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 advisory Source
+   context, not evidence 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.
+   permission to inspect the Source and propose the graph outputs and coverage
+   metrics Interf should prepare. It is not permission to
+   answer from the Source. Follow the Required User-Visible Flow above.
 
    Keep the proposal compact:
 
    ```text
-   I found <source summary>. For <task>, I should prepare the source first because <risk>.
+   I found <source summary>. For <task>, I should build the source first because <risk>.
    <Optional ambiguity or assumption in one sentence.>
 
-   1. **<Plain-English artifact name>**
+   Interf should prepare data for the agent by building a Context Graph from
+   the files.
+
+   Context Graph outputs:
+   1. **<Plain-English output name>**
+      Why it helps: <short sentence>
+   2. **<Plain-English output name>**
       Why it helps: <short sentence>
-      Checks:
-      - <human-readable check>
-      - <human-readable check>
 
-   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.
+   Coverage metrics:
+   - files processed
+   - source units summarized
+   - knowledge reviewed and used
+   - graph entrypoints generated
+
+   Approve these outputs and coverage expectations, and I will draft the Build Plan.
    ```
 
    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.
+   extracted numbers, chart readings, schema fields, stage names, raw check
+   operator names, or commands in the human proposal. Detailed numbers belong in
+   the built artifacts, which live inside the Context Graph.
 
-3. **Create the Preparation after approval**.
+3. **Create the Project after approval**.
 
    ```sh
-   interf prep ls
-   interf prep create <id> --source <path> [--about "<agent job>"] \
-     --requested-artifacts-json '<json-array>' \
-     --source-profile-json '<json-object>'
+   interf project create <id> --source <path> --intent "<agent task>"
    ```
 
-   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.
+   Create a fresh Project for the current Source unless the user explicitly
+   names an existing Project id. Store the durable agent task on the Project.
+   Store requested outputs and advisory source interpretation in the Build Plan
+   draft request, using `source_context` when useful.
 
-4. **Draft or select a Build Plan**.
+4. **Draft a Build Plan**.
 
-   For real analytical work, prefer a custom Build Plan for the Preparation.
+   For real analytical work, prefer a custom Build Plan for the Project.
    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 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 plan draft <project-id> \
+     --intent "<agent task override, optional>" \
+     --requested-artifacts-json '<json-array>' \
+     --source-context-json '<json-object>' \
+     --artifacts "<optional extra requested output notes or change request>"
    interf runs status <run-id>
-   interf build-plan show <build-plan-id>
-   interf build-plan select <prep-id> <build-plan-id>
+   interf plan show <build-plan-id>
    ```
 
-   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.
+   Do not generate custom shell polling loops. In hosts with app-backed Interf
+   MCP tools, use the 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**.
+5. **Show the Build Plan review before building**.
 
    After the Build Plan is drafted, selected, or materially changed, send the
-   user to:
+   user a compact in-chat review: Project id, Build Plan id, what Interf will
+   prepare, stage names, expected inputs, graph entrypoints, and what each
+   stage writes. Include a review locator when the connected Interf client
+   provides one, but do not force the user to leave chat to approve. Unless the
+   user granted autonomy after reviewing the outputs and coverage expectations,
+   pause here.
 
-   ```text
-   http://127.0.0.1:4873/?section=preparations&preparation=<prep-id>&preparationTab=build-plan
-   ```
-
-   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**.
+6. **Build the Context Graph**.
 
    ```sh
-   interf build <prep-id> [--watch] [--quiet] [--idempotency-key <key>]
+   interf build <project-id> [--watch] [--quiet] [--idempotency-key <key>]
    ```
 
-   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.
+   Default is async-return: prints the Build id, the Context Graph locator, and
+   current `ready` / `not ready` status. With `--quiet`, only the Context Graph locator is printed. With
+   `--watch`, the CLI tails events until the Build reaches a terminal state.
+
+   If the user asked for an answer in the same `/interf` request, answer from
+   the built Context Graph. Start from `home.md` and graph entrypoints under
+   `artifacts/`, then use `summaries/` for Source coverage proof,
+   `knowledge/` for drilldown, and traces/source references for exact claims.
+   Do not bypass the graph by searching the original PDF/report/source file
+   directly.
 
-7. **Inspect runs and readiness**.
+7. **Inspect Project activity and optionally benchmark**.
 
    ```sh
    interf runs status <run-id>
-   interf runs ls [--prep <id>]
+   interf runs ls --project <project-id>
    interf runs cancel <run-id>
-   interf test <prep-id>
+   interf traces ls --project <project-id>
+   interf benchmark <project-id> --target context-graph
+   interf benchmark <project-id> --target source-files
    ```
 
+   `interf benchmark` is a benchmark/evaluation run for Q&A / fact-check accuracy.
+   Use it when the user wants a source-files baseline, a Context Graph
+   evaluation, or a source-vs-Context Graph comparison. It is not the
+   readiness surface.
+
 8. **On `not ready`, improve the Build Plan**.
 
    ```sh
-   interf build-plan improve <prep-id> \
-     --task "<what needs to change>" \
-     --artifacts "<Artifact changes, if any>" \
-     --ready-when "<proof or coverage changes, if any>"
+   interf plan improve <project-id> \
+     --intent "<what needs to change, optional>" \
+     --artifacts "<requested output changes, if any>"
    ```
 
-## Connected Agents
+## Agents
 
 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.
+Benchmark runs hard-error until the user installs or registers
+an agent.
 
 ```sh
 interf agents ls
@@ -204,7 +479,7 @@ interf agents unmap <role>
 ```
 
 Roles are `extractor`, `summarizer`, `structurer`, `verifier`, and `general`.
-Build Plans may declare custom names; the engine treats unknown roles as
+Build Plans may declare custom names; the Build runtime treats unknown roles as
 `general`. Default behavior is single-active-agent.
 
 ## CLI Flags
@@ -212,134 +487,177 @@ Build Plans may declare custom names; the engine treats unknown roles as
 | Flag | What it controls | When the agent passes it |
 |---|---|---|
 | `--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. |
-| `--quiet` | Print only the artifact locator on success. | Scripting and agent handoff. |
-| `--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. |
+| `--token <token>` | Override the active bearer token for one call. | Explicit connection details, remote instances, or API integration tasks. |
+| `--watch` | Block until the Build finishes and tail stages. | Only when the agent must wait inline. |
+| `--quiet` | Print only the Context Graph locator on success. | Scripting and agent handoff. |
+| `--idempotency-key <key>` | Sent as `X-Interf-Idempotency-Key`. The instance returns the original Build 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
+- Use exact Project ids and Build Plan ids returned by the API. Do not
   invent ids.
 - Always confirm a connection exists before running mutating commands.
+- If `/interf` was invoked and no connection exists, stop. Do not answer by
+  reading raw source files.
+- Once a Context Graph exists, use it as the knowledge map. Source drilldown is
+  allowed only through graph-provided source references, traces, graph
+  entrypoints, or the Project's recorded Source Manifest.
 - 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.
+- Use MCP when available. Use the CLI only when it is
+  already installed. Do not install npm packages in the user's agent session.
+- Do not mention npm package versions, CLI versions, or local service versions
+  in normal task updates. They are debugging details, not part of the product
+  path.
+- You may use direct local HTTP for the well-known discovery probe. Do not call
+  source-reading or mutating local HTTP APIs unless Interf explicitly
+  provides the local connection details or gives an API-integration task.
 - 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.
-- 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.
+- Treat Build Plan review plus Graph Manifest metrics as the default human
+  trust gate.
+- Treat structural output checks as necessary but not sufficient for
+  precision. If a visual/table/chart answer needs range, axis, period, unit,
+  series, or provenance semantics that the graph output did not capture, mark
+  the Context Graph not ready and improve the Build Plan.
+- The first visible Interf response to a read-and-answer request is the
+  requested-outputs-and-coverage proposal. It is not a draft answer.
+- Separate proposal from evidence. Before a Build, you can say what Interf
+  plans to prepare, which outputs and coverage metrics the Build Plan targets,
+  and what graph entrypoints it will produce. After a Build, you can say which
+  files/pages were processed, what graph resources were produced, and whether
+  the Context Graph is ready.
 - Ask one concise clarification only when the Source or agent goal is missing,
-  or when ambiguity makes the requested Artifacts impossible to draft. For
+  or when ambiguity makes the requested outputs impossible to draft. For
   normal domain ambiguity, state the assumption and make it a check.
 
 ## Show Your Work
 
-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 Run record, Stage Manifests, Graph Manifest, traces, and Context Graph locator show
+what the user can inspect. Whenever you start a Build, summarize the
+Project id, Build id, primary metrics, and Context Graph locator in chat. If
+the connected Interf client returns a review locator, include it.
 
-The base URL is whatever `interf status` reports as the connected instance.
-Append query params:
+Do not present the local HTTP service URL as a review UI.
 
-| Param | Value |
-|---|---|
-| `preparation` | the Preparation id |
-| `run` | the run id returned by the CLI |
-| `runTab` | optional: `trace`, `events`, or `readiness` |
-
-Example output after `interf build <prep-id>`:
+Example output after `interf build <project-id>`:
 
 ```text
-Started Build run <run-id>.
-Watch live: http://127.0.0.1:4873/?preparation=<prep-id>&run=<run-id>
+Started Build <run-id>.
+Project: <project-id>
+Context Graph: <locator when available>
 
 I'll check status in a moment with `interf runs status <run-id>`.
 ```
 
-When a run finishes, print the same URL with `runTab=readiness` so the user can
-click through to the readiness summary.
-
-## Reading The Context Locator
+When a Build finishes, report the final `ready` / `not ready` status, the
+Context Graph locator, and the primary metrics or missing coverage that
+matter.
 
-`interf build <prep-id>` prints a short multi-line block by default. The context
-locator looks like one of:
+## Reading The Context Graph Locator
 
-```text
-Context: <local-path-returned-by-interf>
-```
+Build returns a Context Graph locator. With the CLI, `interf build
+<project-id>` prints a short multi-line block by default. The Context Graph
+locator looks like:
 
 ```text
-Context: https://api.interf.cloud/v1/runs/run_2x4abc.../verifiable-context
+Context Graph: <local-path-returned-by-interf>
 ```
 
-For `local-path`, use the agent's filesystem tools to read the directory. For
-`remote-url`, use HTTP.
+For `local-path`, use the agent's filesystem tools to read the directory.
+Start from `home.md`, then follow graph entrypoints under `artifacts/`. Follow
+source refs for exact claims.
 
-## Interf UI Freeform Proposal Mode
+## Interf Client Freeform Proposal Mode
 
-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.
+When an Interf client asks for a proposal, do not run CLI commands. Write a
+single JSON object to the requested output path. Structured controls call the
+local service directly; this mode is only for freeform planning.
 
 Use these action types:
 
 - `build`
-- `test`
-- `readiness-check-draft`
+- `benchmark`
+- `benchmark-question-draft` (draft benchmark questions)
 - `build-plan-draft`
 - `build-plan-improvement`
 - `clarification`
 
-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>`.
+Use `build` when the user asks to prepare data, build graph outputs, or refresh
+the Context Graph for an agent task. Set `project` to the Project id. Do not set
+`build_plan` for a Build proposal; Build always runs the Project's selected
+Build Plan. If the request named a different Build Plan, select or draft that
+Build Plan before proposing `build`. CLI equivalent:
+`interf build <project-id>`.
 
-Readiness-check proposals run against verifiable context unless the user asks
-for a source-files baseline.
+Use `benchmark` for benchmark/evaluation proposals. They run against the
+Context Graph unless the user asks for a source-files baseline. CLI equivalent:
+`interf benchmark <project-id>`.
 
 Return this shape:
 
 ```json
 {
   "action_type": "build",
-  "build_plan": "build-plan-id",
-  "preparation": "prep-id",
+  "project": "project-id",
   "title": "short approval card title",
-  "summary": "one sentence describing which artifacts will be built",
+  "summary": "one sentence describing which graph outputs will be built",
   "assistant_message": "concise explanation for the user",
-  "command_preview": "interf build prep-id"
+  "command_preview": "interf build project-id"
 }
 ```
 
-For Build Plan drafting proposals, keep requested Artifacts structured in
-`values.requested_artifacts[]` and keep the advisory source summary in
-`values.source_profile`:
+For Build Plan drafting proposals, keep requested outputs and graph entrypoints
+in `values.requested_artifacts[]` for the current API shape, and put the
+advisory source summary in `values.source_context`. Use stable output ids.
+Treat `values.checks[]` as an optional developer-diagnostic field only when an
+Interf client explicitly asks for it; do not make checks the human-facing
+proposal.
+
+**Requested outputs are graph areas, not answers.** Each entry must describe a
+region of the Context Graph the next agent will traverse — claim nodes,
+entity nodes, comparison nodes, timelines, coverage indexes — NOT the user's
+answer or a finished report. Interf prepares structured context; the agent
+still does the reasoning.
+
+Good titles / purposes (graph-shaped):
+- `"London cost-and-take-up claim nodes"` — source-cited claim notes the agent can compare against South West claim nodes.
+- `"South West rent-growth signals timeline"` — dated decision/forecast signals extracted from the report.
+- `"Page-by-page guide of the report"` — coverage index so the agent knows where evidence for any claim lives.
+
+Bad titles / purposes (replace agent thinking — do NOT use):
+- `"NY rent growth answer"` — that is the agent's job, not Interf's.
+- `"Final report"` / `"Forecast summary"` — finished answer artifacts.
+- `"Recommended decision"` — Interf does not decide; it prepares the data the decider reads.
 
 ```json
 {
   "action_type": "build-plan-draft",
-  "preparation": "prep-id",
-  "build_plan": "prep-id-build-plan",
+  "project": "project-id",
+  "build_plan": "project-id-build-plan",
   "title": "Draft Build Plan",
-  "summary": "Drafts the Build Plan for the requested Artifacts.",
+  "summary": "Drafts the Build Plan for the requested graph outputs.",
   "values": {
-    "build_plan_id": "prep-id-build-plan",
-    "task_prompt": "London versus South West annual take-up",
+    "build_plan_id": "project-id-build-plan",
+    "intent": "London versus South West annual take-up",
     "requested_artifacts": [
       {
-        "title": "Guide to the report",
-        "purpose": "A short note for each page, so the agent knows what is where.",
-        "checks": ["Every page is listed.", "Each page has a plain-English summary."]
+        "id": "page-guide",
+        "title": "Page-by-page guide of the report",
+        "purpose": "Short coverage note per page so the agent knows what evidence lives where."
+      },
+      {
+        "id": "london-claims",
+        "title": "London take-up claim nodes",
+        "purpose": "Source-cited claim notes (figures, source page, caveat) for London take-up — the agent compares these against the South West nodes."
+      },
+      {
+        "id": "south-west-claims",
+        "title": "South West take-up claim nodes",
+        "purpose": "Same shape as the London claim nodes, scoped to South West figures."
       }
     ],
-    "source_profile": {
+    "source_context": {
       "summary": "One 26-page office market report.",
       "observations": ["No obvious section is called South West."]
     }
@@ -367,10 +685,13 @@ Use CLI read commands before asking the user to inspect the UI:
 
 ```sh
 interf status
-interf prep show <prep-id>
-interf build-plan show <build-plan-id>
+interf project show <project-id>
+interf plan show <build-plan-id>
 interf runs status <run-id>
+interf traces show <trace-kind> --project <project-id>
 ```
 
-The UI link is for visual proof. The CLI output is for agent-readable status,
-Build Plan review, Artifact status, run errors, proof, and readiness summaries.
+The UI link is for visual review. The CLI output is for agent-readable status,
+Build Plan review, graph output status, Build errors, Graph Manifest metrics,
+Stage Manifest coverage, stage execution sessions, traces, benchmark results,
+and ready / not ready summaries.