@interf/compiler 0.18.0 → 0.22.0

package/dist/cli/commands/mcp.js

@@ -1,25 +1,113 @@
+/**
+ * `interf mcp` — Model Context Protocol server.
+ *
+ * Wraps the local-service HTTP API as a typed agent surface so coding
+ * agents can interact with Interf the same way they call other MCP tools
+ * (instead of shelling out to the CLI).
+ *
+ *   interf mcp                              # stdio transport (default)
+ *   interf mcp --transport=http --port=4889 # advanced: HTTP transport
+ *
+ * API-backed tools read `~/.interf/connection.json` (the same file every
+ * other client uses) on each call. The MCP server can start before an
+ * engine is connected so local plugin hosts such as Cowork can load the
+ * tool surface first, then call `web_start` or `web_status`. The MCP
+ * server itself holds no Interf runtime state. The transport options are
+ * intentionally minimal — agents speaking MCP today are stdio-first.
+ *
+ * Tool list:
+ *   web_start           shell out to `interf web start`
+ *   web_stop            shell out to `interf web stop`
+ *   web_status          shell out to `interf web status`
+ *   prep_list           GET /v1/preparations
+ *   prep_create         POST /v1/preparations
+ *   prep_show           GET /v1/preparations/{id}
+ *   prep_select_build_plan PATCH /v1/preparations/{id}
+ *   prep_remove         DELETE /v1/preparations/{id}
+ *   prep_build          POST /v1/preparations/{id}/build-runs
+ *   prep_test           POST /v1/preparations/{id}/verify-runs
+ *   build_plan_list     GET /v1/build-plans
+ *   build_plan_draft    POST /v1/preparations/{id}/build-plan-draft-runs
+ *   build_plan_improve  POST /v1/preparations/{id}/build-plan-improvement-runs
+ *   runs_status         GET /v1/runs/{run-id}
+ *   runs_watch          GET /v1/build-runs/{run-id}/events  (snapshot, not SSE)
+ *   runs_cancel         POST /v1/build-runs/{run-id}/cancel
+ *   runs_fetch          GET /v1/build-runs/{run-id}/artifacts
+ *   instance_status     GET /v1/instance
+ */
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/engine/connection-config.js";
-import { LOCAL_SERVICE_ROUTES, preparationResourcePath, preparationSubresourcePath, runResourcePath, runSubresourcePath, } from "../../packages/engine/routes.js";
+import { LOCAL_SERVICE_ROUTES, preparationResourcePath, preparationSubresourcePath, runResourcePath, } from "../../packages/engine/routes.js";
+import { BuildPlanAuthoringArtifactRequirementSchema, } from "../../packages/engine/lib/schema.js";
+import { RequestedArtifactSchema, SourceProfileSchema, } from "../../packages/project/lib/schema.js";
 function trimTrailingSlash(value) {
     return value.replace(/\/+$/, "");
 }
-function resolveConnection(args) {
+function packageVersionFromManifest() {
+    try {
+        const url = new URL("../../../package.json", import.meta.url);
+        const raw = readFileSync(url, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function resolveConnectionOrNull(args) {
     const conn = readActiveConnection({
         urlOverride: args.url ?? null,
         authTokenOverride: args.token ?? null,
     });
-    if (!conn) {
-        process.stderr.write(`${CONNECT_OR_ERROR_HINT}\n`);
-        process.exit(1);
-    }
+    if (!conn)
+        return null;
     return {
         url: trimTrailingSlash(conn.url),
         token: conn.auth_token ?? null,
     };
 }
+function runInterfCli(args) {
+    const binPath = process.argv[1];
+    if (!binPath) {
+        return Promise.resolve({
+            code: 1,
+            signal: null,
+            stdout: "",
+            stderr: "Cannot locate the Interf CLI entrypoint.",
+        });
+    }
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [binPath, ...args], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            resolve({
+                code: 1,
+                signal: null,
+                stdout,
+                stderr: stderr || error.message,
+            });
+        });
+        child.on("close", (code, signal) => {
+            resolve({ code, signal, stdout, stderr });
+        });
+    });
+}
 async function callApi(conn, path, init = {}) {
     const headers = new Headers(init.headers ?? {});
     if (conn.token)
@@ -57,38 +145,109 @@ function toolErrorJson(message, payload) {
         isError: true,
     };
 }
-async function callAndReturn(conn, path, init = {}) {
+function cliToolResult(result) {
+    const output = [
+        result.stdout.trim(),
+        result.stderr.trim(),
+    ].filter(Boolean).join("\n");
+    if (result.code === 0)
+        return toolResultJson(output || "OK");
+    return toolErrorJson(`interf command exited with ${result.signal ?? result.code ?? "unknown"}.`, output);
+}
+async function callAndReturn(args, path, init = {}) {
+    const conn = resolveConnectionOrNull(args);
+    if (!conn)
+        return toolErrorJson(CONNECT_OR_ERROR_HINT);
     const response = await callApi(conn, path, init);
     if (response.status >= 200 && response.status < 300) {
         return toolResultJson(response.body ?? response.raw);
     }
     return toolErrorJson(`Local service responded with HTTP ${response.status}.`, response.body ?? response.raw);
 }
-function registerTools(server, conn) {
+function registerTools(server, connectionArgs) {
+    // ── Local engine lifecycle ─────────────────────────────────────────────
+    server.registerTool("web_start", {
+        title: "Start local Interf engine",
+        description: "Start the Interf engine in the background on the user's machine. "
+            + "Use this when no Interf instance is connected yet.",
+        inputSchema: {
+            host: z.string().min(1).optional().describe("Host to bind. Defaults to 127.0.0.1."),
+            port: z.number().int().positive().optional().describe("Port to bind. Defaults to 4873."),
+            timeout_ms: z.number().int().positive().optional().describe("Startup timeout in milliseconds."),
+            log: z.string().min(1).optional().describe("Optional path for background engine logs."),
+        },
+    }, async (args) => {
+        const cliArgs = ["web", "start"];
+        if (args.host)
+            cliArgs.push("--host", args.host);
+        if (args.port)
+            cliArgs.push("--port", String(args.port));
+        if (args.timeout_ms)
+            cliArgs.push("--timeout-ms", String(args.timeout_ms));
+        if (args.log)
+            cliArgs.push("--log", args.log);
+        return cliToolResult(await runInterfCli(cliArgs));
+    });
+    server.registerTool("web_stop", {
+        title: "Stop local Interf engine",
+        description: "Stop the connected Interf engine or the live engine recorded in the "
+            + "local service registry.",
+        inputSchema: {
+            url: z.string().url().optional().describe("Optional engine URL to stop."),
+            token: z.string().min(1).optional().describe("Optional bearer token."),
+        },
+    }, async (args) => {
+        const cliArgs = ["web", "stop"];
+        if (args.url)
+            cliArgs.push("--url", args.url);
+        if (args.token)
+            cliArgs.push("--token", args.token);
+        return cliToolResult(await runInterfCli(cliArgs));
+    });
+    server.registerTool("web_status", {
+        title: "Show local Interf engine status",
+        description: "Return the connected engine status using the same connection record "
+            + "as the CLI.",
+        inputSchema: {
+            url: z.string().url().optional().describe("Optional engine URL."),
+            token: z.string().min(1).optional().describe("Optional bearer token."),
+        },
+    }, async (args) => {
+        const cliArgs = ["web", "status"];
+        if (args.url)
+            cliArgs.push("--url", args.url);
+        if (args.token)
+            cliArgs.push("--token", args.token);
+        return cliToolResult(await runInterfCli(cliArgs));
+    });
     // ── Preparations ────────────────────────────────────────────────────────
     server.registerTool("prep_list", {
         title: "List preparations",
         description: "List every Preparation registered on the connected Interf instance, "
-            + "with source binding, Method id, and current readiness.",
+            + "with source binding, Build Plan id, and current readiness.",
         inputSchema: {},
-    }, async () => callAndReturn(conn, LOCAL_SERVICE_ROUTES.preparations));
+    }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.preparations));
     server.registerTool("prep_create", {
         title: "Create a preparation",
-        description: "Create a new Preparation. The Preparation binds a Source Folder "
-            + "to an optional Method and is the saved unit of work for compile runs.",
+        description: "Create a new Preparation. The Preparation binds a Source, "
+            + "agent intent, requested Artifacts, and optional Build Plan.",
         inputSchema: {
             id: z.string().min(1).describe("Preparation id (kebab-case)."),
-            source_path: z.string().min(1).describe("Absolute or workspace-relative Source Folder path."),
-            method_id: z.string().min(1).optional().describe("Optional Method id to bind. Bind later with prep_set_method if omitted."),
+            source_path: z.string().min(1).describe("Source path visible to the connected instance."),
+            build_plan_id: z.string().min(1).optional().describe("Optional Build Plan id to select. Select later with prep_select_build_plan if omitted."),
             about: z.string().min(1).optional().describe("Optional human-readable description."),
+            requested_artifacts: z.array(RequestedArtifactSchema).optional().describe("Requested Artifacts the agent/user confirmed for this Preparation."),
+            source_profile: SourceProfileSchema.optional().describe("Advisory source profile from the agent's inspection before build."),
         },
-    }, async (args) => callAndReturn(conn, LOCAL_SERVICE_ROUTES.preparations, {
+    }, async (args) => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.preparations, {
         method: "POST",
         body: JSON.stringify({
             id: args.id,
             source: { kind: "local-folder", locator: args.source_path },
-            ...(args.method_id ? { method_id: args.method_id } : {}),
+            ...(args.build_plan_id ? { build_plan_id: args.build_plan_id } : {}),
             ...(args.about ? { about: args.about } : {}),
+            ...(args.requested_artifacts ? { requested_artifacts: args.requested_artifacts } : {}),
+            ...(args.source_profile ? { source_profile: args.source_profile } : {}),
         }),
     }));
     server.registerTool("prep_show", {
@@ -97,72 +256,115 @@ function registerTools(server, conn) {
         inputSchema: {
             id: z.string().min(1).describe("Preparation id."),
         },
-    }, async (args) => callAndReturn(conn, preparationResourcePath(args.id)));
-    server.registerTool("prep_set_method", {
-        title: "Bind a Method to a preparation",
-        description: "Update the Method binding on a Preparation. Use this to swap "
-            + "Methods between compile runs without rebuilding the Preparation.",
+    }, async (args) => callAndReturn(connectionArgs, preparationResourcePath(args.id)));
+    server.registerTool("prep_select_build_plan", {
+        title: "Select a Build Plan for a Preparation",
+        description: "Update the selected Build Plan on a Preparation. Use this to swap "
+            + "Build Plans between Build runs without rebuilding the Preparation.",
         inputSchema: {
             id: z.string().min(1).describe("Preparation id."),
-            method_id: z.string().min(1).describe("Method id to bind."),
+            build_plan_id: z.string().min(1).describe("Build Plan id to use."),
         },
-    }, async (args) => callAndReturn(conn, preparationResourcePath(args.id), {
+    }, async (args) => callAndReturn(connectionArgs, preparationResourcePath(args.id), {
         method: "PATCH",
-        body: JSON.stringify({ method_id: args.method_id }),
+        body: JSON.stringify({ build_plan_id: args.build_plan_id }),
     }));
     server.registerTool("prep_remove", {
         title: "Remove a preparation",
-        description: "Delete a Preparation. Portable context is removed too.",
+        description: "Delete a Preparation. Verifiable context is removed too.",
         inputSchema: {
             id: z.string().min(1).describe("Preparation id."),
         },
-    }, async (args) => callAndReturn(conn, preparationResourcePath(args.id), {
+    }, async (args) => callAndReturn(connectionArgs, preparationResourcePath(args.id), {
         method: "DELETE",
     }));
-    // ── Compile + verify runs ──────────────────────────────────────────────
-    server.registerTool("prep_compile", {
-        title: "Start a compile run",
-        description: "Kick off a compile run for a Preparation. Returns the new run "
+    // ── Build + readiness-check runs ───────────────────────────────────────
+    server.registerTool("prep_build", {
+        title: "Start a Build run",
+        description: "Run the selected Build Plan for a Preparation. Returns the new Build run "
             + "resource immediately; use runs_status to poll progress and "
             + "runs_fetch when the run finishes.",
         inputSchema: {
             id: z.string().min(1).describe("Preparation id."),
         },
-    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.id, "compileRuns"), { method: "POST", body: "{}" }));
-    server.registerTool("prep_verify", {
+    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.id, "buildRuns"), { method: "POST", body: "{}" }));
+    server.registerTool("prep_test", {
         title: "Run readiness checks",
-        description: "Run the Preparation's readiness checks against the latest portable "
-            + "context. Verify runs always judge against the compiled output in 0.15+.",
+        description: "Run the Preparation's readiness checks against the latest verifiable "
+            + "context.",
         inputSchema: {
             id: z.string().min(1).describe("Preparation id."),
         },
-    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.id, "verifyRuns"), {
+    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.id, "verifyRuns"), {
         method: "POST",
         body: JSON.stringify({}),
     }));
-    // ── Methods ─────────────────────────────────────────────────────────────
-    server.registerTool("method_list", {
-        title: "List Methods",
-        description: "List every Method visible to the connected instance: workspace "
-            + "drafts, the user library at ~/.interf/methods/, and bundled Methods.",
+    // ── Build Plans ────────────────────────────────────────────────────────
+    server.registerTool("build_plan_list", {
+        title: "List Build Plans",
+        description: "List every Build Plan visible to the connected instance: Preparation drafts, "
+            + "saved Build Plans, and bundled Build Plans.",
         inputSchema: {},
-    }, async () => callAndReturn(conn, LOCAL_SERVICE_ROUTES.methods));
-    server.registerTool("method_draft", {
-        title: "Author a new Method draft",
-        description: "Run the Method-authoring agent for a Preparation. Produces a new "
-            + "Method package draft under <workspace>/methods/<id>/.",
+    }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.buildPlans));
+    server.registerTool("build_plan_draft", {
+        title: "Draft a Build Plan",
+        description: "Run the Build Plan authoring agent for a Preparation. Saved requested "
+            + "Artifacts are used automatically when omitted from the request.",
         inputSchema: {
             prep_id: z.string().min(1).describe("Preparation id."),
+            source_folder_path: z.string().min(1).describe("Source folder path visible to the connected instance."),
+            build_plan_id: z.string().min(1).describe("Build Plan id to create."),
+            label: z.string().min(1).describe("Human-readable Build Plan label."),
+            hint: z.string().min(1).describe("Short Build Plan hint."),
+            task_prompt: z.string().min(1).describe("Agent job this Build Plan should support."),
+            requested_artifacts: z.array(RequestedArtifactSchema).optional(),
+            source_profile: SourceProfileSchema.nullable().optional(),
+            artifact_requirements: z.array(BuildPlanAuthoringArtifactRequirementSchema).optional(),
         },
-    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.prep_id, "methodAuthoringRuns"), { method: "POST", body: "{}" }));
-    server.registerTool("method_improve", {
-        title: "Run Method improvement",
-        description: "Run the Method-improvement agent for a Preparation. Iterates on "
-            + "the bound Method based on the latest readiness-check results.",
+    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.prep_id, "buildPlanDraftRuns"), {
+        method: "POST",
+        body: JSON.stringify({
+            preparation: args.prep_id,
+            source_folder_path: args.source_folder_path,
+            build_plan_id: args.build_plan_id,
+            label: args.label,
+            hint: args.hint,
+            task_prompt: args.task_prompt,
+            ...(args.requested_artifacts ? { requested_artifacts: args.requested_artifacts } : {}),
+            ...(args.source_profile !== undefined ? { source_profile: args.source_profile } : {}),
+            ...(args.artifact_requirements ? { artifact_requirements: args.artifact_requirements } : {}),
+        }),
+    }));
+    server.registerTool("build_plan_improve", {
+        title: "Improve a Build Plan",
+        description: "Run the Build Plan improvement agent for a Preparation. Iterates on "
+            + "the selected Build Plan based on requested Artifacts and latest readiness evidence.",
         inputSchema: {
             prep_id: z.string().min(1).describe("Preparation id."),
+            source_folder_path: z.string().min(1).describe("Source folder path visible to the connected instance."),
+            build_plan_id: z.string().min(1).describe("Selected Build Plan id to improve."),
+            label: z.string().min(1).describe("Human-readable Build Plan label."),
+            hint: z.string().min(1).describe("Short Build Plan hint."),
+            task_prompt: z.string().min(1).describe("Change request or improvement goal."),
+            requested_artifacts: z.array(RequestedArtifactSchema).optional(),
+            source_profile: SourceProfileSchema.nullable().optional(),
+            artifact_requirements: z.array(BuildPlanAuthoringArtifactRequirementSchema).optional(),
         },
-    }, async (args) => callAndReturn(conn, preparationSubresourcePath(args.prep_id, "methodImprovementRuns"), { method: "POST", body: "{}" }));
+    }, async (args) => callAndReturn(connectionArgs, preparationSubresourcePath(args.prep_id, "buildPlanImprovementRuns"), {
+        method: "POST",
+        body: JSON.stringify({
+            preparation: args.prep_id,
+            source_folder_path: args.source_folder_path,
+            build_plan_id: args.build_plan_id,
+            reference_build_plan_id: args.build_plan_id,
+            label: args.label,
+            hint: args.hint,
+            task_prompt: args.task_prompt,
+            ...(args.requested_artifacts ? { requested_artifacts: args.requested_artifacts } : {}),
+            ...(args.source_profile !== undefined ? { source_profile: args.source_profile } : {}),
+            ...(args.artifact_requirements ? { artifact_requirements: args.artifact_requirements } : {}),
+        }),
+    }));
     // ── Runs ────────────────────────────────────────────────────────────────
     server.registerTool("runs_status", {
         title: "Get run status",
@@ -170,7 +372,7 @@ function registerTools(server, conn) {
         inputSchema: {
             run_id: z.string().min(1).describe("Run id."),
         },
-    }, async (args) => callAndReturn(conn, runResourcePath(args.run_id)));
+    }, async (args) => callAndReturn(connectionArgs, runResourcePath(args.run_id)));
     server.registerTool("runs_watch", {
         title: "Read run events",
         description: "Read the events log for one run as a snapshot. Returns the same "
@@ -179,34 +381,33 @@ function registerTools(server, conn) {
         inputSchema: {
             run_id: z.string().min(1).describe("Run id."),
         },
-    }, async (args) => callAndReturn(conn, runSubresourcePath(args.run_id, "events")));
+    }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.buildRuns}/${encodeURIComponent(args.run_id)}/events`));
     server.registerTool("runs_cancel", {
         title: "Cancel a run",
         description: "Request cancellation of an in-flight run.",
         inputSchema: {
             run_id: z.string().min(1).describe("Run id."),
         },
-    }, async (args) => callAndReturn(conn, runSubresourcePath(args.run_id, "cancel"), { method: "POST", body: "{}" }));
+    }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.buildRuns}/${encodeURIComponent(args.run_id)}/cancel`, { method: "POST", body: "{}" }));
     server.registerTool("runs_fetch", {
         title: "Fetch run artifacts",
-        description: "Return the artifact manifest for a finished run (portable context, "
+        description: "Return the artifact manifest for a finished run (verifiable context, "
             + "proof records, logs, run-scoped audit trail).",
         inputSchema: {
             run_id: z.string().min(1).describe("Run id."),
         },
-    }, async (args) => callAndReturn(conn, runSubresourcePath(args.run_id, "artifacts")));
+    }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.buildRuns}/${encodeURIComponent(args.run_id)}/artifacts`));
     // ── Instance ────────────────────────────────────────────────────────────
     server.registerTool("instance_status", {
         title: "Show instance status",
         description: "Return the engine's instance resource: started_at, package "
             + "version, registered preparations, active runs, idle seconds.",
         inputSchema: {},
-    }, async () => callAndReturn(conn, LOCAL_SERVICE_ROUTES.instance));
+    }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.instance));
 }
 async function startStdioServer(args) {
-    const conn = resolveConnection(args);
-    const server = new McpServer({ name: "interf", version: "0.14.0" }, { capabilities: { tools: {} } });
-    registerTools(server, conn);
+    const server = new McpServer({ name: "interf", version: packageVersionFromManifest() }, { capabilities: { tools: {} } });
+    registerTools(server, args);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/cli/commands/prep.js

@@ -2,7 +2,7 @@
  * `interf prep` — preparation CRUD against a connected instance.
  *
  *   interf prep ls
- *   interf prep create <id> --source <path> --method <id> [--about <text>]
+ *   interf prep create <id> --source <path> [--build-plan <id>] [--about <text>]
  *   interf prep show <id>
  *   interf prep rm <id>
  *
@@ -14,6 +14,8 @@ import { resolve } from "node:path";
 import chalk from "chalk";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/engine/connection-config.js";
 import { preparationResourcePath } from "../../packages/engine/routes.js";
+import { requestedArtifactCheckLabel } from "../../packages/engine/requested-artifacts.js";
+import { RequestedArtifactSchema, SourceProfileSchema, } from "../../packages/project/lib/schema.js";
 function requireConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,
@@ -45,6 +47,28 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
+const RequestedArtifactsCliSchema = RequestedArtifactSchema.array();
+function parseJsonOption(label, value, parse) {
+    if (!value)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        console.error(chalk.red(`Invalid JSON for ${label}.`));
+        console.error(chalk.dim(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+    try {
+        return parse(parsed);
+    }
+    catch (error) {
+        console.error(chalk.red(`Invalid ${label}.`));
+        console.error(chalk.dim(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
 function statusColor(status) {
     if (status === "ready")
         return chalk.green;
@@ -57,12 +81,11 @@ function statusColor(status) {
 function renderPreparationSummary(prep) {
     console.log();
     console.log(`  ${chalk.bold(prep.name)}`);
-    if (prep.method_id)
-        console.log(chalk.dim(`    method:  ${prep.method_id}`));
+    console.log(chalk.dim(`    Build Plan: ${prep.build_plan_id ?? "(not selected)"}`));
     if (prep.source_path)
         console.log(chalk.dim(`    source:  ${prep.source_path}`));
-    if (prep.portable_context_path) {
-        console.log(chalk.dim(`    output:  ${prep.portable_context_path}`));
+    if (prep.verifiable_context_path) {
+        console.log(chalk.dim(`    output:  ${prep.verifiable_context_path}`));
     }
     if (prep.readiness?.status) {
         const aggColor = prep.readiness.ready ? chalk.green : chalk.yellow;
@@ -80,12 +103,26 @@ function renderPreparationSummary(prep) {
             console.log(`      ${artifact.artifact_id.padEnd(idWidth)}  ${colored}${stages}`);
         }
     }
-    if (prep.latest_compile_run_id) {
+    if (prep.requested_artifacts && prep.requested_artifacts.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Requested Artifacts"));
+        for (const artifact of prep.requested_artifacts) {
+            console.log(`      ${chalk.bold(artifact.title)}`);
+            if (artifact.purpose ?? artifact.description) {
+                console.log(chalk.dim(`        ${artifact.purpose ?? artifact.description}`));
+            }
+            const checks = artifact.checks ?? [];
+            for (const check of checks.slice(0, 4)) {
+                console.log(chalk.dim(`        - ${requestedArtifactCheckLabel(check)}`));
+            }
+        }
+    }
+    if (prep.latest_build_run_id) {
         console.log();
-        console.log(chalk.dim(`    latest compile run: ${prep.latest_compile_run_id}`));
+        console.log(chalk.dim(`    latest Build run: ${prep.latest_build_run_id}`));
     }
     if (prep.latest_test_run_id) {
-        console.log(chalk.dim(`    latest verify run:  ${prep.latest_test_run_id}`));
+        console.log(chalk.dim(`    latest check run:   ${prep.latest_test_run_id}`));
     }
     console.log();
     console.log(chalk.dim(`  Run with --json for the raw resource record.`));
@@ -108,7 +145,7 @@ export const prepCommand = {
         }
         const preparations = body.preparations ?? [];
         if (preparations.length === 0) {
-            console.log(chalk.dim("  No preparations yet. Create one with `interf prep create <id> --source <path> --method <method-id>`."));
+            console.log(chalk.dim("  No preparations yet. Create one with `interf prep create <id> --source <path>`."));
             return;
         }
         console.log();
@@ -116,26 +153,34 @@ export const prepCommand = {
         console.log();
         for (const prep of preparations) {
             const sourceLabel = prep.source?.locator ?? prep.source_path ?? "(no source)";
-            const method = prep.method_id ?? "(no method)";
+            const buildPlan = prep.build_plan_id ?? "(no Build Plan)";
             const readiness = prep.readiness?.status ?? "—";
+            const requested = prep.requested_artifacts?.length ?? 0;
             console.log(`  ${prep.id}`);
             console.log(chalk.dim(`    source: ${sourceLabel}`));
-            console.log(chalk.dim(`    method: ${method}`));
+            console.log(chalk.dim(`    Build Plan: ${buildPlan}`));
+            console.log(chalk.dim(`    requested Artifacts: ${requested}`));
             console.log(chalk.dim(`    readiness: ${readiness}`));
         }
     })
-        .command("create <prep-id>", "Create a preparation (method binding optional — set later if you don't have one yet)", (y) => y
+        .command("create <prep-id>", "Create a Preparation (Build Plan optional — select or draft it later)", (y) => y
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id (lowercase, dash-separated)" })
-        .option("source", { type: "string", demandOption: true, describe: "Path to the Source Folder" })
-        .option("method", { type: "string", describe: "Method id (e.g. interf-default). Optional — bind later via `interf prep set-method`." })
-        .option("about", { type: "string", describe: "One-line description of the agent work" }), async (args) => {
+        .option("source", { type: "string", demandOption: true, describe: "Path to the Source" })
+        .option("build-plan", { type: "string", describe: "Build Plan id. Optional — select later with `interf build-plan select`." })
+        .option("about", { type: "string", describe: "One-line description of the agent work" })
+        .option("requested-artifacts-json", { type: "string", describe: "JSON array of requested Artifacts for this Preparation" })
+        .option("source-profile-json", { type: "string", describe: "JSON object describing the agent's advisory source profile" }), async (args) => {
         const { url, token } = requireConnection(args);
         const sourceAbs = resolve(process.cwd(), args.source);
+        const requestedArtifacts = parseJsonOption("--requested-artifacts-json", args.requestedArtifactsJson, (input) => RequestedArtifactsCliSchema.parse(input));
+        const sourceProfile = parseJsonOption("--source-profile-json", args.sourceProfileJson, (input) => SourceProfileSchema.parse(input));
         const requestBody = {
             id: args.prepId,
             source: { kind: "local-folder", locator: sourceAbs },
-            ...(args.method ? { method_id: args.method } : {}),
+            ...(args.buildPlan ? { build_plan_id: args.buildPlan } : {}),
             about: args.about,
+            ...(requestedArtifacts ? { requested_artifacts: requestedArtifacts } : {}),
+            ...(sourceProfile ? { source_profile: sourceProfile } : {}),
             checks: [],
         };
         const { status, body, raw } = await callJson(`${url}/v1/preparations`, token, { method: "POST", body: JSON.stringify(requestBody) });
@@ -146,27 +191,14 @@ export const prepCommand = {
             process.exit(1);
         }
         console.log(chalk.green(`Created preparation ${chalk.bold(args.prepId)}.`));
-        if (!args.method) {
-            console.log(chalk.dim(`  no method bound yet — pick or draft one before compiling:`));
-            console.log(chalk.dim(`    interf prep set-method ${args.prepId} <method-id>`));
-            console.log(chalk.dim(`    interf method draft ${args.prepId}`));
-        }
-        if (body?.portable_context?.value) {
-            console.log(chalk.dim(`  portable context (locator): ${body.portable_context.value}`));
+        if (!args.buildPlan) {
+            console.log(chalk.dim(`  no Build Plan selected yet — pick or draft one before building:`));
+            console.log(chalk.dim(`    interf build-plan select ${args.prepId} <build-plan-id>`));
+            console.log(chalk.dim(`    interf build-plan draft ${args.prepId}`));
         }
-    })
-        .command("set-method <prep-id> <method-id>", "Bind a method to a preparation (or change which method it uses)", (y) => y
-        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
-        .positional("method-id", { type: "string", demandOption: true, describe: "Method id to bind" }), async (args) => {
-        const { url, token } = requireConnection(args);
-        const { status, raw } = await callJson(`${url}${preparationResourcePath(args.prepId)}`, token, { method: "PATCH", body: JSON.stringify({ method_id: args.methodId }) });
-        if (status !== 200) {
-            console.error(chalk.red(`Failed to set method (HTTP ${status}).`));
-            if (raw)
-                console.error(raw);
-            process.exit(1);
+        if (body?.build_plan_id && body?.verifiable_context?.value) {
+            console.log(chalk.dim(`  verifiable context (locator): ${body.verifiable_context.value}`));
         }
-        console.log(chalk.green(`Bound ${chalk.bold(args.methodId)} to ${chalk.bold(args.prepId)}.`));
     })
         .command("show <prep-id>", "Show a preparation's full record", (y) => y
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })

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

@@ -1,7 +1,7 @@
 import type { CommandModule } from "yargs";
 interface ResetArgs {
     prepId: string;
-    mode?: "compile" | "all";
+    mode?: "build" | "all";
     url?: string;
     token?: string;
 }