@interf/compiler 0.33.0 → 0.50.0

package/README.md

@@ -1,268 +1,164 @@
 # Interf
 
-**Interf prepares data for agents.**
+**Interf prepares data for agent tasks.**
 
-This npm package ships the `interf` CLI and local Interf runtime for building
-task-specific Context Graphs from files.
+Interf structures your files into a task-specific graph your agent can navigate.
+Your agent starts from prepared context built for the task, instead of a partial
+read of whatever files it happened to open.
 
-Agents miss things in files. When agents answer from a folder, they first have
-to discover what is in it, decide what matters, extract evidence, and connect
-facts across files. That file-to-context step is hidden, inconsistent, and hard
-to inspect.
+> This npm package is the `interf` CLI and local runtime. A Mac app (Interf
+> Desktop) is coming soon.
 
-Interf separates that step. It makes users' agents build a Context Graph from
-their files. It has source coverage summaries, task-aware knowledge, artifact
-handoffs, and links back to sources. Your agent uses the prepared map instead
-of rediscovering the files during the task.
-
-```text
-Source files                        Context Graph agents use
-
-bristol-office-market/              <context-graph>/
-  q4-market-report.pdf                AGENTS.md
-  lease-comps.xlsx                    home.md
-  planning-notes.md                   summaries/
-  exports/availability.csv            knowledge/
-                                      artifacts/
-                                      traces/
-```
-
-## What a Build Produces
-
-A Build produces a Context Graph. The Context Graph is source-backed context
-built from files so agents can use prepared context instead of partial file
-reads.
-
-For a local Build, the Context Graph is an inspectable folder:
-
-```text
-<context-graph>/
-  AGENTS.md              # agent guidance
-  home.md                # overview and routes
-  artifacts/             # task-specific agent handoffs
-  summaries/             # source coverage proof
-  knowledge/             # navigation and drilldown
-  traces/                # links back to sources
-```
-
-The output is not an answer. It is a prepared map over the Source: artifact
-handoffs, summaries, knowledge notes, and links back to sources. The Source
-remains the ground truth. Agents start from `artifacts/`, use `summaries/` for
-coverage proof and `knowledge/` for drilldown, then follow source links when
-exact wording, table values, chart reads, or provenance-sensitive claims matter.
-
-## Design Choices
-
-- `Project-scoped`: every Project starts from a specific Source and selected
-  Build Plan, not a generic index over every file.
-- `Inspectable`: Interf records what was built, which requested Artifacts exist,
-  and where source-backed traces live.
-- `Local-first`: local Builds keep Source files on your machine and read-only.
-- `Bring your own agent`: use Claude Code, Codex, or another registered
-  command-line agent.
-- `File over hidden index`: local Builds expose the Context Graph as a folder
-  agents can inspect.
-- `Context Checks you control`: every Build can be checked against
-  plain-English conditions such as "Every page is covered" or "Every figure
-  cites a source page."
-
-## Why Not Just Ask Your Agent?
-
-You can. Interf can use Claude Code, Codex, or another registered local agent
-while it builds the Context Graph.
-
-A one-off preprocessing prompt gives you another answer to trust. Interf puts
-the preparation step inside a Build Plan you can inspect: requested Artifacts,
-declared stages, Build evidence, Context Checks, and traces.
-
-The agent can still execute the stages. Interf shows what was covered, what was
-produced, and whether the Context Graph is ready for the task.
-
-## Install
+## Quick start
 
 ```bash
 npm install -g @interf/compiler
-interf            # opens the wizard
+interf                 # the interactive wizard walks you through your first build
 ```
 
-Requires Node.js 20+ and a local agent CLI such as Claude Code, Codex, or
-another registered command-line agent. Run `interf doctor --live` if the
-executor is not detected.
+Requires Node 20+ and a local agent CLI (Claude Code, Codex, or another). Check
+it with `interf doctor --live`.
 
-## Quick Start
+Or run it command by command:
 
 ```bash
-# terminal 1: start the local Interf runtime
-interf runtime
-
-# terminal 2: create a Project from a local Source
-interf project create bristol --source ./bristol-office-market
+interf runtime                                 # start the local runtime
+interf project create bristol \                # bind a folder + the agent's task
+  --source ./bristol-office-market \
+  --intent "Bristol annual take-up and availability"
+interf plan draft bristol                      # draft a Build Plan, then review it
+interf plan select bristol <build-plan-id>     # pick the reviewed plan
+interf build bristol                           # build the graph
+```
 
-# draft the Build Plan for review
-interf plan draft bristol \
-  --intent "Bristol annual take-up and availability chart lookup" \
-  --artifacts "Guide to the report; annual take-up figures with source references" \
-  --ready-when "Every page is listed and every figure has a source reference."
+`interf build` returns the graph path: a folder your agent opens and continues
+from. No `--out` flag, no copy of your Source. Mutating commands never auto-start
+the runtime; they exit with a hint if nothing is connected.
 
-# select the reviewed Build Plan
-interf plan select bristol <build-plan-id>
+## What you get
 
-# build the Context Graph
-interf build bristol
+A folder your agent navigates instead of grepping raw files. Interf calls it a
+**Context Graph**:
 
-# optional: benchmark/evaluate answers from the Source baseline, Context Graph, or both
-interf benchmark bristol
+```text
+<graph>/
+  home.md          # start here. routes into the three layers below
+  summaries/       # one folder per source file. every file read and summarized
+  knowledge/       # the connected web: linked notes, claims, entities, source refs
+  artifacts/       # task handoffs that reference summaries and knowledge
+  traces/          # provenance: every claim links back to source
+  AGENTS.md        # how agents use the graph (plus CLAUDE.md for Claude Code)
 ```
 
-`interf runtime` starts the local runtime in the foreground and writes the
-active connection record so subsequent CLI commands can connect. Agents can use
-`interf runtime start` for an explicit managed background runtime, then
-`interf runtime stop` when their task is done.
+`summaries/`, `knowledge/`, and `artifacts/` are the three fixed layers, plus
+`home.md`. What goes inside `knowledge/` (claims, entities, timelines, tables) is
+up to the Build Plan, so any task shapes its own web. Your Source stays read-only
+and the ground truth. Agents follow source links when exact wording, table
+values, or chart reads matter.
 
-Mutating commands never implicitly auto-start a runtime. If no instance is
-connected, they exit with a hint pointing at `interf runtime`,
-`interf runtime start`, or `interf login`.
+## Why Interf is different
 
-`interf build` returns the Context Graph locator on success. For local Builds,
-that locator points to a folder agents can inspect and continue from. There is
-no `--out` flag and no implicit copy of your Source folder.
+Most tools prepare your files one way for every question: chunks in a vector
+store, or a single knowledge graph that maps everything the same way (RAG
+indexes, Obsidian-style graphs, code-graph tools). Interf is `task-specific`. You
+tell it what the agent needs to do, and it builds a graph tailored to that task:
+the right summaries, connections, and entrypoints for *this* work, not a one-size
+index of all your files.
 
-## Context Graph
+And the graph is `provable`:
 
-The Context Graph is the output Interf builds from your files for agents. It is
-a knowledge map over the Source, not a replacement for the Source.
+- `Coverage`: every Source file was read and summarized.
+- `Traceability`: every claim links back to a Source, and every note connects to
+  the web. No orphans, no islands.
 
-It gives agents structure and source-backed routes for navigating files. For
-the built-in `interf-default`, it includes:
+It is `provider-agnostic` by design: the same prepared context works across
+Claude, Codex, GPT, and whatever you switch to next, because the graph is a
+portable folder you own, never trapped in one vendor's session. Your own agents
+do the work, your files never leave your machine, and the output is files you can
+read, diff, commit, and reuse.
 
-```text
-<context-graph>/
-  AGENTS.md       # agent-facing guidance and source-checking rules
-  CLAUDE.md       # same guidance for Claude Code
-  home.md         # graph index
-  artifacts/      # task-specific handoffs for agents
-  summaries/      # one source-named folder per source file
-  knowledge/      # linked notes built from summaries and source refs
-  traces/         # source provenance for claims and checks
-```
+## Design principles
 
-The source files stay the source of truth. Interf writes generated state inside
-the instance data directory and does not modify the Source.
+- `Not a replacement for your agent harness`: just a task-specific graph to navigate.
+- `Your files stay yours`: local, read-only, never sent to Interf's servers.
+- `Runs with your agents`: your CLIs, your subscriptions, in a replayable shell.
+- `File over app`: the graph is inspectable files, not a hidden index.
+- `Connected, not orphaned`: every note links to others and back to sources.
+- `Coverage-first`: exact file, summary, knowledge, and output counts.
+- `Project-scoped`: one Source, one agent task, one Build Plan.
 
-`AGENTS.md` tells agents how to use the Context Graph: start from the prepared
-outputs, follow the prepared routes, and use the recorded source references
-when exact source evidence matters.
+## Readiness is provable
 
-## Build Plans
+Every Build reports exact coverage metrics (files processed, source units
+summarized, knowledge reviewed and used, graph outputs, entrypoints) behind a
+single `ready` / `not ready` verdict backed by two deterministic guarantees:
 
-A Build Plan tells Interf how to build requested Artifacts from your Source for
-the agent task. It also states the Context Checks the user can review before the
-Build.
+- **Coverage**: every Source file was read and summarized. This is file-level. It
+  does not claim every fact was caught, only that no file went unread.
+- **Traceability**: every claim links back to a Source, every summary is linked,
+  and every knowledge note connects to the web. No orphans, no islands.
 
-The built-in `interf-default` Build Plan ships with `interf`. Save your own
-local Build Plan with `interf plan save <path>`; draft new ones with
-`interf plan draft <project-id>`.
+If a file is unread, a claim is unlinked, or a note is an island, the graph is
+`not ready` and the gap is named.
 
-```text
-<build-plan-folder>/
-  build-plan.json         # Build Plan definition: artifacts, stages, build rules
-  build-plan.schema.json  # output contract: required Context Graph files/folders
-  README.md               # what this Build Plan is for
-  build/
-    stages/
-      summarize/          # stage instructions Interf runs during the Build
-      structure/
-      shape/
-  use/
-    query/                # how agents read the Context Graph
-  improve/                # how Interf revises the plan if checks still fail
-```
+`interf benchmark` is a separate, optional check that scores answer accuracy
+against the Source baseline, the graph, or both. It is a fallible double-check,
+never a readiness gate.
 
-- `build-plan.json` is the technical filename for the Build Plan definition:
-  requested Artifacts, stages, and how the files should be built.
-- `build-plan.schema.json` describes the output contract: what the Context Graph
-  must contain.
-- `build/stages/<stage>/` is where you author one folder per stage.
-- `use/query/` holds the instructions agents follow when they read the Context
-  Graph for the task.
-- `improve/` holds the instructions Interf follows when the first Build misses
-  and the Build Plan itself needs editing.
+## Build Plans
 
-## Build Plan Improvement
+A Build Plan is the reviewed recipe for how Interf builds the graph from your
+Source for the task: requested outputs, stage instructions, expected inputs, and
+the entrypoints you review before building. `interf-default` ships built in.
+Draft your own with `interf plan draft <project-id>`, or save one with
+`interf plan save <path>`.
 
-When the first Build is `not ready`, Interf can edit the Build Plan and build
-again. Same Source, same checks, improved Build Plan and Context Graph.
+When a Build comes back `not ready`, Interf can revise the plan and build again
+(same Source, same intent, better plan), recorded as a Run:
 
 ```bash
 interf plan improve <project-id>
 ```
 
-Interf records Build Plan improvement as a Run with the revised Build Plan,
-Build evidence, and resulting Context Graph.
-
-## Context Checks And Benchmarks
-
-Context Checks are plain-English promises the user reviews before a Build.
-Requested Artifacts back those checks.
-
-Examples:
+A Build Plan is a folder you can read and version:
 
-- every file in scope was processed
-- required pages or slides were inventoried
-- required outputs exist
-- every figure cites a source page
-- the Source has not changed since the Build
-
-Benchmarks are different. A benchmark asks saved questions and measures answer
-accuracy against an agent source-access baseline, the Context Graph, or both.
-
-```bash
-interf benchmark bristol
-interf benchmark bristol --target source-files
-interf benchmark bristol --target context-graph
+```text
+<build-plan>/
+  build-plan.json         # outputs, stages, and build rules
+  build-plan.schema.json  # the output contract: what the graph must contain
+  build/stages/<stage>/   # the instructions Interf runs for each stage
+  use/query/              # how agents read the graph for the task
+  improve/                # how Interf revises the plan when checks still fail
 ```
 
-`interf benchmark` is optional evaluation. It is not the main readiness surface.
-
-## What Interf Is Not
-
-- Not a second brain or memory product. One Project starts from one Source and
-  agent task.
-- Not a vector store or hosted RAG server. The Context Graph is structured
-  source-backed context agents can inspect.
-- Not a hosted data platform by default. Local Builds run on your machine.
-- Not a generic agent task orchestrator. Interf prepares files into Context
-  Graphs for agents.
-
-## Useful Commands
-
-- `interf` / `interf init` - open the interactive wizard.
-- `interf runtime` - run the local Interf runtime in the foreground.
-- `interf runtime start` - start a managed background local runtime.
-- `interf runtime stop` - stop the running local runtime.
-- `interf project ls / create / show / rm` - manage Projects.
-- `interf plan list / show / save / draft / select / improve` - manage Build
-  Plans.
-- `interf build <project-id>` - Build the Context Graph for a Project.
-- `interf graphs ls --project <id>` / `show <graph-id> --project <id>` - inspect
-  Context Graphs.
-- `interf traces ls --project <id>` / `show <trace-kind> --project <id>` -
-  inspect Context Graph traces.
-- `interf runs ls --project <id>` / `status <run-id>` - inspect Runs.
-- `interf benchmark <project-id>` - run an optional benchmark/evaluation pass.
-- `interf agents ls / use / register / unregister / map / unmap` - configure
-  local agents and role mapping.
-- `interf login / logout` - connect the CLI to another Interf instance.
-- `interf status` - show the active connection and Project summary.
-- `interf doctor --live` - check the local executor before a Build.
-
-## Public Assets
-
-- [skills/interf](./skills/interf/) - bundled agent Skill for Interf.
-- [build-plans/interf-default](./build-plans/interf-default/) - default Build
-  Plan that ships with `interf`.
-
-Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md).
-
-License: see [LICENSE.md](./LICENSE.md). © 2026 Interf Inc. All rights reserved.
-Name and branding: see [TRADEMARKS.md](./TRADEMARKS.md).
+## Commands
+
+| Command | What it does |
+|---|---|
+| `interf` / `interf init` | Open the interactive wizard |
+| `interf runtime` / `start` / `stop` | Run, background, or stop the local runtime |
+| `interf project create / ls / show / rm` | Manage Projects |
+| `interf plan draft / select / improve / save / list / show` | Manage Build Plans |
+| `interf build <id>` | Build the graph for a Project |
+| `interf graphs ls / show --project <id>` | Inspect built graphs |
+| `interf traces ls / show --project <id>` | Inspect source provenance |
+| `interf runs ls / status --project <id>` | Inspect Runs |
+| `interf benchmark <id>` | Optional accuracy check |
+| `interf agents ls / use / register / map` | Configure local execution agents |
+| `interf status` | Connection and Project summary |
+| `interf doctor --live` | Check your agent before a Build |
+
+## What Interf is not
+
+- Not a second brain or memory product: one Project, one Source, one task.
+- Not a vector store or hosted RAG server: the graph is inspectable, source-backed files.
+- Not a hosted data platform: local Builds run on your machine.
+- Not a general knowledge graph or notes app: each graph is built for one agent task, not a single index of everything.
+
+## More
+
+- [skills/interf](./skills/interf/): the bundled agent Skill.
+- [build-plans/interf-default](./build-plans/interf-default/): the default Build Plan.
+- [CONTRIBUTING.md](./CONTRIBUTING.md) · [LICENSE.md](./LICENSE.md) · [TRADEMARKS.md](./TRADEMARKS.md)
+
+© 2026 Interf Inc. All rights reserved.

package/dist/cli/commands/agents.js

@@ -12,38 +12,7 @@
  * `~/.interf/agents.json` directly — the service is the source of truth.
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/runtime/connection-config.js";
-function resolveConnection(args) {
-    const conn = readActiveConnection({
-        urlOverride: args.url,
-        authTokenOverride: args.token,
-    });
-    if (!conn) {
-        console.error(CONNECT_OR_ERROR_HINT);
-        process.exit(1);
-    }
-    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
-}
-async function callJson(url, token, init = {}) {
-    const headers = new Headers(init.headers ?? {});
-    if (token)
-        headers.set("authorization", `Bearer ${token}`);
-    if (init.body && !headers.has("content-type")) {
-        headers.set("content-type", "application/json");
-    }
-    const response = await fetch(url, { ...init, headers });
-    const raw = await response.text();
-    let body = null;
-    if (raw.length > 0) {
-        try {
-            body = JSON.parse(raw);
-        }
-        catch {
-            body = null;
-        }
-    }
-    return { status: response.status, body, raw };
-}
+import { callJson, resolveConnection } from "../lib/http-client.js";
 function formatAgentLine(agent, registry) {
     const isActive = agent.name === registry.active_agent?.name;
     const sourceLabel = agent.source === "builtin" ? "builtin" : "user";

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

@@ -1,10 +1,9 @@
 import type { CommandModule } from "yargs";
+import { type ConnectionArgs } from "../lib/http-client.js";
 type BenchmarkTarget = "context-graph" | "source-files" | "both";
-interface BenchmarkArgs {
+interface BenchmarkArgs extends ConnectionArgs {
     projectId: string;
     target?: BenchmarkTarget;
-    url?: string;
-    token?: string;
 }
 export declare const benchmarkCommand: CommandModule<unknown, BenchmarkArgs>;
 export {};

package/dist/cli/commands/benchmark.js

@@ -9,37 +9,7 @@
  *
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.js";
-function resolveConnection(args) {
-    const conn = readActiveConnection({
-        urlOverride: args.url,
-        authTokenOverride: args.token,
-    });
-    if (!conn) {
-        console.error(CONNECT_OR_ERROR_HINT);
-        process.exit(1);
-    }
-    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
-}
-async function callJson(url, token, init = {}) {
-    const headers = new Headers(init.headers ?? {});
-    if (token)
-        headers.set("authorization", `Bearer ${token}`);
-    if (init.body && !headers.has("content-type"))
-        headers.set("content-type", "application/json");
-    const response = await fetch(url, { ...init, headers });
-    const raw = await response.text();
-    let body = null;
-    if (raw.length > 0) {
-        try {
-            body = JSON.parse(raw);
-        }
-        catch {
-            body = null;
-        }
-    }
-    return { status: response.status, body, raw };
-}
+import { callJson, resolveConnection } from "../lib/http-client.js";
 function buildBenchmarkArgs(yargs) {
     return yargs
         .positional("project-id", { type: "string", demandOption: true, describe: "Project id" })

package/dist/cli/commands/build-plan.js

@@ -13,41 +13,11 @@
  */
 import chalk from "chalk";
 import { resolve } from "node:path";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.js";
+import { callJson, resolveConnection } from "../lib/http-client.js";
 import { buildPlanResourcePath, projectResourcePath, projectSubresourcePath, } from "../../packages/runtime/service/routes.js";
 import { BuildPlanAuthoringArtifactRequirementSchema, BuildPlanContextCheckDraftSchema, RequestedArtifactSchema, SourceContextSchema, } from "../../packages/runtime/schemas/index.js";
 import { artifactRequirementsFromRequestedArtifacts, formatRequestedArtifactsForPrompt, requestedArtifactsFromPlanArtifacts, } from "../../packages/runtime/requested-artifacts.js";
 import { slugify } from "../../packages/contracts/utils/naming.js";
-function resolveConnection(args) {
-    const conn = readActiveConnection({
-        urlOverride: args.url,
-        authTokenOverride: args.token,
-    });
-    if (!conn) {
-        console.error(CONNECT_OR_ERROR_HINT);
-        process.exit(1);
-    }
-    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
-}
-async function callJson(url, token, init = {}) {
-    const headers = new Headers(init.headers ?? {});
-    if (token)
-        headers.set("authorization", `Bearer ${token}`);
-    if (init.body && !headers.has("content-type"))
-        headers.set("content-type", "application/json");
-    const response = await fetch(url, { ...init, headers });
-    const raw = await response.text();
-    let body = null;
-    if (raw) {
-        try {
-            body = JSON.parse(raw);
-        }
-        catch {
-            body = null;
-        }
-    }
-    return { status: response.status, body, raw };
-}
 const BuildPlanAuthoringArtifactRequirementsCliSchema = BuildPlanAuthoringArtifactRequirementSchema.array();
 const BuildPlanChecksCliSchema = BuildPlanContextCheckDraftSchema.array();
 const RequestedArtifactsCliSchema = RequestedArtifactSchema.array();
@@ -105,7 +75,7 @@ function renderBuildPlanSummary(buildPlan) {
     const artifacts = buildPlan.artifacts ?? [];
     if (artifacts.length > 0) {
         console.log();
-        console.log(chalk.bold("    Artifacts"));
+        console.log(chalk.bold("    Requested outputs"));
         for (const artifact of artifacts) {
             const shape = artifact.shape?.path
                 ? chalk.dim(` -> ${artifact.shape.path}`)
@@ -158,10 +128,10 @@ function buildTaskPrompt(args, requestedArtifacts, projectId, mode) {
     const sections = [
         `${mode === "improve" ? "Improve" : "Draft"} a Build Plan for Project "${projectId}".`,
         args.intent?.trim() ? `Intent:\n${args.intent.trim()}` : null,
-        requestedArtifactsText ? `Requested Artifacts:\n${requestedArtifactsText}` : null,
-        args.artifacts?.trim() ? `Additional Artifact notes:\n${args.artifacts.trim()}` : null,
-        args.readyWhen?.trim() ? `Context Check:\n${args.readyWhen.trim()}` : null,
-        "Return a Build Plan definition that declares Context Checks, the requested Artifacts backing them, the stages that build those Artifacts, and Artifact diagnostics for internal validation.",
+        requestedArtifactsText ? `Requested graph outputs:\n${requestedArtifactsText}` : null,
+        args.artifacts?.trim() ? `Additional output notes:\n${args.artifacts.trim()}` : null,
+        args.readyWhen?.trim() ? `Coverage goal:\n${args.readyWhen.trim()}` : null,
+        "Return a Build Plan definition that starts from Project intent, declares the Context Graph outputs, stage inputs, coverage metrics, and deterministic validation needed for local service review.",
     ].filter((section) => Boolean(section));
     return sections.join("\n\n");
 }
@@ -180,6 +150,8 @@ async function readProjectContext(url, token, projectId) {
 async function startBuildPlanRun(args, mode) {
     const { url, token } = resolveConnection(args);
     const { project } = await readProjectContext(url, token, args.projectId);
+    const projectIntent = typeof project.intent === "string" ? project.intent.trim() : "";
+    const effectiveIntent = args.intent?.trim() || projectIntent;
     const existingBuildPlan = selectedBuildPlanId(project);
     const buildPlanId = args.buildPlan ?? (mode === "improve" ? existingBuildPlan : defaultBuildPlanIdForProject(args.projectId));
     const explicitRequestedArtifacts = parseJsonOption("--requested-artifacts-json", args.requestedArtifactsJson, (input) => RequestedArtifactsCliSchema.parse(input));
@@ -200,18 +172,22 @@ async function startBuildPlanRun(args, mode) {
             : []);
     if (!buildPlanId) {
         console.error(chalk.red(`Project ${args.projectId} has no selected Build Plan to improve.`));
-        console.error(chalk.dim(`Draft a Build Plan first: interf plan draft ${args.projectId} --intent "..."`));
+        console.error(chalk.dim(`Draft a Build Plan first: interf plan draft ${args.projectId}`));
+        process.exit(1);
+    }
+    if (!effectiveIntent) {
+        console.error(chalk.red(`Project ${args.projectId} has no saved intent.`));
+        console.error(chalk.dim("Create or update the Project with an agent task intent before drafting a Build Plan."));
         process.exit(1);
     }
     const body = {
-        project: args.projectId,
         ...(args.baseBuildPlan ? { base_build_plan_id: args.baseBuildPlan } : {}),
         ...(args.referenceBuildPlan ? { reference_build_plan_id: args.referenceBuildPlan } : {}),
         ...(mode === "improve" && !args.referenceBuildPlan && existingBuildPlan ? { reference_build_plan_id: existingBuildPlan } : {}),
         build_plan_id: buildPlanId,
         label: args.label ?? labelFromBuildPlanId(buildPlanId),
         hint: args.hint ?? `Build Plan for Project ${args.projectId}.`,
-        intent: buildTaskPrompt(args, requestedArtifacts, args.projectId, mode),
+        intent: buildTaskPrompt({ ...args, intent: effectiveIntent }, requestedArtifacts, args.projectId, mode),
         checks: buildPlanChecks,
         requested_artifacts: requestedArtifacts,
         artifact_requirements: artifactRequirements,
@@ -328,13 +304,13 @@ export const buildPlanCommand = {
     })
         .command("draft <project-id>", "Start a Build Plan draft run for a Project", (y) => y
         .positional("project-id", { type: "string", demandOption: true, describe: "Project id" })
-        .option("intent", { type: "string", demandOption: true, describe: "Agent task this Build Plan should support" })
-        .option("artifacts", { type: "string", describe: "Requested Artifacts and why the agent needs them" })
-        .option("requested-artifacts-json", { type: "string", describe: "JSON array of structured requested Artifacts for Build Plan authoring" })
-        .option("checks-json", { type: "string", describe: "JSON array of Context Checks for Build Plan authoring" })
-        .option("artifact-requirements-json", { type: "string", describe: "JSON array of exact Artifact output requirements for the Build Plan" })
+        .option("intent", { type: "string", describe: "Agent task this Build Plan should support. Defaults to the Project intent." })
+        .option("artifacts", { type: "string", describe: "Requested outputs and why the agent needs them" })
+        .option("requested-artifacts-json", { type: "string", describe: "JSON array of structured requested outputs for Build Plan authoring" })
+        .option("checks-json", { type: "string", describe: "JSON array of coverage goals for Build Plan authoring" })
+        .option("artifact-requirements-json", { type: "string", describe: "JSON array of exact output requirements for the Build Plan" })
         .option("source-context-json", { type: "string", describe: "JSON object with advisory Source context for Build Plan authoring" })
-        .option("ready-when", { type: "string", describe: "Plain-English Context Check the requested Artifacts should satisfy" })
+        .option("ready-when", { type: "string", describe: "Plain-English coverage goal the Context Graph should satisfy" })
         .option("build-plan", { type: "string", describe: "Build Plan id to write" })
         .option("label", { type: "string", describe: "Human-readable Build Plan label" })
         .option("hint", { type: "string", describe: "Short Build Plan summary for review" })
@@ -346,12 +322,12 @@ export const buildPlanCommand = {
         .command("improve <project-id>", "Start a Build Plan improvement run for a Project", (y) => y
         .positional("project-id", { type: "string", demandOption: true, describe: "Project id" })
         .option("intent", { type: "string", describe: "Change request for the selected Build Plan" })
-        .option("artifacts", { type: "string", describe: "Requested Artifact changes and why they matter" })
-        .option("requested-artifacts-json", { type: "string", describe: "JSON array of structured requested Artifacts for Build Plan authoring" })
-        .option("checks-json", { type: "string", describe: "JSON array of Context Checks for Build Plan authoring" })
-        .option("artifact-requirements-json", { type: "string", describe: "JSON array of exact Artifact output requirements for the Build Plan" })
+        .option("artifacts", { type: "string", describe: "Requested output changes and why they matter" })
+        .option("requested-artifacts-json", { type: "string", describe: "JSON array of structured requested outputs for Build Plan authoring" })
+        .option("checks-json", { type: "string", describe: "JSON array of coverage goals for Build Plan authoring" })
+        .option("artifact-requirements-json", { type: "string", describe: "JSON array of exact output requirements for the Build Plan" })
         .option("source-context-json", { type: "string", describe: "JSON object with advisory Source context for Build Plan authoring" })
-        .option("ready-when", { type: "string", describe: "Plain-English Context Check to add or change" })
+        .option("ready-when", { type: "string", describe: "Plain-English coverage goal to add or change" })
         .option("build-plan", { type: "string", describe: "Build Plan id to update" })
         .option("label", { type: "string", describe: "Human-readable Build Plan label" })
         .option("hint", { type: "string", describe: "Short Build Plan summary for review" })