@interf/compiler 0.18.0 → 0.22.0

package/dist/cli/commands/build-plan.d.ts

@@ -0,0 +1,2 @@
+import type { CommandModule } from "yargs";
+export declare const buildPlanCommand: CommandModule;

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

@@ -0,0 +1,376 @@
+/**
+ * `interf build-plan` — manage Build Plans on the connected instance.
+ *
+ *   interf build-plan list                         # list Build Plans
+ *   interf build-plan show <build-plan-id>          # show a Build Plan summary
+ *   interf build-plan select <prep-id> <id>         # select a Build Plan for a Preparation
+ *   interf build-plan save <path-or-id>             # save/promote a reusable Build Plan
+ *   interf build-plan draft <prep-id>               # start a Build Plan draft run
+ *   interf build-plan improve <prep-id>             # start a Build Plan improvement run
+ */
+import chalk from "chalk";
+import { resolve } from "node:path";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
+import { buildPlanResourcePath, preparationResourcePath, preparationSubresourcePath, } from "../../packages/engine/routes.js";
+import { BuildPlanAuthoringArtifactRequirementSchema, } from "../../packages/engine/lib/schema.js";
+import { artifactRequirementsFromRequestedArtifacts, formatRequestedArtifactsForPrompt, } from "../../packages/engine/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 };
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+const BuildPlanAuthoringArtifactRequirementsCliSchema = BuildPlanAuthoringArtifactRequirementSchema.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 buildPreparationReviewUrl(url, prepId) {
+    return `${url}/?section=preparations&preparation=${encodeURIComponent(prepId)}&preparationTab=build-plan`;
+}
+function buildRunUrl(url, prepId, runId) {
+    if (!runId)
+        return null;
+    return `${url}/?section=preparations&preparation=${encodeURIComponent(prepId)}&preparationTab=runs&run=${encodeURIComponent(runId)}`;
+}
+function defaultBuildPlanIdForPreparation(prepId) {
+    return slugify(`${prepId}-build-plan`) || "build-plan";
+}
+function labelFromBuildPlanId(buildPlanId) {
+    const label = buildPlanId
+        .split("-")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+    return label || "Build Plan";
+}
+function renderBuildPlanSummary(buildPlan) {
+    const id = buildPlan.build_plan_id ?? buildPlan.id ?? "(?)";
+    console.log();
+    console.log(`  ${chalk.bold(buildPlan.label ?? id)}`);
+    console.log(chalk.dim(`    id: ${id}`));
+    if (buildPlan.hint)
+        console.log(chalk.dim(`    hint: ${buildPlan.hint}`));
+    if (buildPlan.purpose?.task_hint)
+        console.log(chalk.dim(`    purpose: ${buildPlan.purpose.task_hint}`));
+    if (buildPlan.source_kind)
+        console.log(chalk.dim(`    source: ${buildPlan.source_kind}`));
+    const artifacts = buildPlan.artifacts ?? [];
+    if (artifacts.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Artifacts"));
+        for (const artifact of artifacts) {
+            const shape = artifact.shape?.path
+                ? chalk.dim(` -> ${artifact.shape.path}`)
+                : "";
+            console.log(`      ${chalk.bold(artifact.id)}${shape}`);
+            console.log(chalk.dim(`        ${artifact.description}`));
+            const checks = artifact.checks ?? [];
+            for (const check of checks.slice(0, 3)) {
+                const required = check.required === false ? "soft" : "required";
+                console.log(chalk.dim(`        - ${check.description ?? check.kind} (${required})`));
+            }
+        }
+    }
+    const stages = buildPlan.stages ?? [];
+    if (stages.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Stages"));
+        for (const stage of stages) {
+            const role = stage.role ? chalk.dim(` [${stage.role}]`) : "";
+            console.log(`      ${chalk.bold(stage.label)}${role}`);
+            if (stage.description)
+                console.log(chalk.dim(`        ${stage.description}`));
+            const reads = stage.reads?.length ? stage.reads.join(", ") : "source";
+            const writes = stage.writes?.length ? stage.writes.join(", ") : "(none declared)";
+            console.log(chalk.dim(`        reads: ${reads}`));
+            console.log(chalk.dim(`        writes: ${writes}`));
+        }
+    }
+    if (buildPlan.active_for_preparations?.length) {
+        console.log();
+        console.log(chalk.dim(`    used by: ${buildPlan.active_for_preparations.join(", ")}`));
+    }
+    console.log();
+    console.log(chalk.dim("  Run with --json for the raw Build Plan record."));
+    console.log();
+}
+function preparationChecks(preparation) {
+    return asArray(preparation.checks).length
+        ? asArray(preparation.checks)
+        : asArray(preparation.preparation?.checks);
+}
+function preparationRequestedArtifacts(preparation) {
+    return preparation.requested_artifacts?.length
+        ? preparation.requested_artifacts
+        : preparation.preparation?.requested_artifacts ?? [];
+}
+function preparationSourceProfile(preparation) {
+    return preparation.source_profile ?? preparation.preparation?.source_profile ?? null;
+}
+function selectedBuildPlanId(preparation) {
+    return preparation.build_plan_id ?? preparation.preparation?.build_plan ?? null;
+}
+function sourceFolderPathFromPreparation(preparation, sourceFiles) {
+    if (preparation.source?.kind === "local-folder" && preparation.source.locator)
+        return preparation.source.locator;
+    if (sourceFiles?.source_files?.[0]?.source_folder_path)
+        return sourceFiles.source_files[0].source_folder_path;
+    return preparation.source_path ?? null;
+}
+function buildTaskPrompt(args, preparation, prepId, mode) {
+    const about = (preparation.about ?? preparation.preparation?.about)?.trim();
+    const requestedArtifacts = formatRequestedArtifactsForPrompt(preparationRequestedArtifacts(preparation));
+    const sections = [
+        `${mode === "improve" ? "Improve" : "Draft"} a Build Plan for Preparation "${prepId}".`,
+        args.task?.trim() ? `Agent job:\n${args.task.trim()}` : null,
+        about ? `Preparation context:\n${about}` : null,
+        requestedArtifacts ? `Requested Artifacts saved on the Preparation:\n${requestedArtifacts}` : null,
+        args.artifacts?.trim() ? `Additional Artifact notes:\n${args.artifacts.trim()}` : null,
+        args.readyWhen?.trim() ? `Ready when:\n${args.readyWhen.trim()}` : null,
+        "Return a Build Plan definition that declares the verifiable Artifacts, the stages that build them, and the checks that prove the verifiable context is ready for agent work.",
+    ].filter((section) => Boolean(section));
+    return sections.join("\n\n");
+}
+async function readPreparationContext(url, token, prepId) {
+    const fetched = await callJson(`${url}${preparationResourcePath(prepId)}`, token);
+    if (fetched.status !== 200 || !fetched.body) {
+        console.error(chalk.red(`Failed to read Preparation ${prepId} (HTTP ${fetched.status}).`));
+        if (fetched.raw)
+            console.error(fetched.raw);
+        process.exit(1);
+    }
+    let sourceFiles = null;
+    const sourcePath = sourceFolderPathFromPreparation(fetched.body, sourceFiles);
+    if (!sourcePath) {
+        const listed = await callJson(`${url}${preparationSubresourcePath(prepId, "sourceFiles")}`, token);
+        if (listed.status === 200)
+            sourceFiles = listed.body;
+    }
+    const sourceFolderPath = sourceFolderPathFromPreparation(fetched.body, sourceFiles);
+    if (!sourceFolderPath) {
+        console.error(chalk.red(`Preparation ${prepId} has no readable local Source binding.`));
+        process.exit(1);
+    }
+    return {
+        preparation: fetched.body,
+        sourceFolderPath,
+        checks: preparationChecks(fetched.body),
+    };
+}
+async function startBuildPlanRun(args, mode) {
+    const { url, token } = resolveConnection(args);
+    const { preparation, sourceFolderPath, checks } = await readPreparationContext(url, token, args.prepId);
+    const existingBuildPlan = selectedBuildPlanId(preparation);
+    const buildPlanId = args.buildPlan ?? (mode === "improve" ? existingBuildPlan : defaultBuildPlanIdForPreparation(args.prepId));
+    const requestedArtifacts = preparationRequestedArtifacts(preparation);
+    const explicitArtifactRequirements = parseJsonOption("--artifact-requirements-json", args.artifactRequirementsJson, (input) => BuildPlanAuthoringArtifactRequirementsCliSchema.parse(input));
+    const artifactRequirements = explicitArtifactRequirements
+        ?? artifactRequirementsFromRequestedArtifacts(requestedArtifacts);
+    if (!buildPlanId) {
+        console.error(chalk.red(`Preparation ${args.prepId} has no selected Build Plan to improve.`));
+        console.error(chalk.dim(`Draft one first: interf build-plan draft ${args.prepId} --task "..."`));
+        process.exit(1);
+    }
+    const body = {
+        preparation: args.prepId,
+        source_folder_path: sourceFolderPath,
+        ...(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 Preparation ${args.prepId}.`,
+        task_prompt: buildTaskPrompt(args, preparation, args.prepId, mode),
+        checks,
+        requested_artifacts: requestedArtifacts,
+        source_profile: preparationSourceProfile(preparation),
+        artifact_requirements: artifactRequirements,
+    };
+    const endpoint = mode === "improve" ? "buildPlanImprovementRuns" : "buildPlanDraftRuns";
+    const { status, body: run, raw } = await callJson(`${url}${preparationSubresourcePath(args.prepId, endpoint)}`, token, { method: "POST", body: JSON.stringify(body) });
+    if (status !== 202 && status !== 201 && status !== 200) {
+        console.error(chalk.red(`Failed to start Build Plan ${mode} run (HTTP ${status}).`));
+        if (raw)
+            console.error(raw);
+        process.exit(1);
+    }
+    const runUrl = buildRunUrl(url, args.prepId, run?.run_id);
+    const reviewUrl = buildPreparationReviewUrl(url, args.prepId);
+    if (args.json) {
+        console.log(JSON.stringify({
+            run_id: run?.run_id ?? null,
+            status: run?.status ?? null,
+            preparation: args.prepId,
+            build_plan_id: buildPlanId,
+            run_url: runUrl,
+            review_url: reviewUrl,
+        }, null, 2));
+        return;
+    }
+    console.log(chalk.green(`Build Plan ${mode} run ${chalk.bold(run?.run_id ?? "(?)")} started.`));
+    console.log(chalk.dim(`  Build Plan: ${buildPlanId}`));
+    if (runUrl)
+        console.log(chalk.dim(`  watch: ${runUrl}`));
+    console.log(chalk.dim(`  review after it finishes: ${reviewUrl}`));
+}
+export const buildPlanCommand = {
+    command: "build-plan <subcommand>",
+    describe: "Manage Build Plans on the connected instance",
+    builder: (yargs) => yargs
+        .option("url", { type: "string", describe: "Override the active connection URL" })
+        .option("token", { type: "string", describe: "Override the active bearer token" })
+        .command("list", "List Build Plans on the instance", (y) => y, async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/build-plans`, token);
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to list Build Plans (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        const buildPlans = body?.build_plans ?? [];
+        if (buildPlans.length === 0) {
+            console.log(chalk.dim("  No Build Plans on this instance."));
+            return;
+        }
+        console.log();
+        for (const buildPlan of buildPlans) {
+            const id = buildPlan.build_plan_id ?? buildPlan.id ?? "(?)";
+            const label = buildPlan.label ? ` ${chalk.dim(buildPlan.label)}` : "";
+            const kind = buildPlan.source_kind ? chalk.dim(`[${buildPlan.source_kind}]`) : "";
+            console.log(`  ${chalk.bold(id)} ${kind}${label}`);
+            if (buildPlan.active_for_preparations?.length) {
+                console.log(chalk.dim(`    used by: ${buildPlan.active_for_preparations.join(", ")}`));
+            }
+        }
+        console.log();
+    })
+        .command("save <source>", "Save a Build Plan definition from a local folder", (y) => y
+        .positional("source", { type: "string", demandOption: true, describe: "Path to the Build Plan definition folder" })
+        .option("as", { type: "string", describe: "Build Plan id to save as" })
+        .option("overwrite", { type: "boolean", default: false, describe: "Replace an existing Build Plan with the same id" }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const absolute = resolve(process.cwd(), args.source);
+        const { status, raw } = await callJson(`${url}/v1/build-plans`, token, { method: "POST", body: JSON.stringify({ source_path: absolute, id: args.as, overwrite: args.overwrite }) });
+        if (status !== 201 && status !== 200) {
+            console.error(chalk.red(`Failed to save Build Plan (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`Saved Build Plan from ${absolute}.`));
+    })
+        .command("show <build-plan-id>", "Show a Build Plan", (y) => y
+        .positional("build-plan-id", { type: "string", demandOption: true, describe: "Build Plan id" })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw JSON record instead of the formatted summary",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}${buildPlanResourcePath(args.buildPlanId)}`, token);
+        if (status !== 200 || !body) {
+            console.error(chalk.red(`Failed to read Build Plan ${args.buildPlanId} (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        if (args.json) {
+            console.log(JSON.stringify(body, null, 2));
+            return;
+        }
+        renderBuildPlanSummary(body);
+    })
+        .command("select <prep-id> <build-plan-id>", "Select a Build Plan for a Preparation", (y) => y
+        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .positional("build-plan-id", { type: "string", demandOption: true, describe: "Build Plan id" }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, raw } = await callJson(`${url}${preparationResourcePath(args.prepId)}`, token, { method: "PATCH", body: JSON.stringify({ build_plan_id: args.buildPlanId }) });
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to select Build Plan (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`Selected Build Plan ${chalk.bold(args.buildPlanId)} for ${chalk.bold(args.prepId)}.`));
+    })
+        .command("draft <prep-id>", "Start a Build Plan draft run for a preparation", (y) => y
+        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .option("task", { type: "string", describe: "Agent job this Build Plan should support" })
+        .option("artifacts", { type: "string", describe: "Requested Artifacts and why the agent needs them" })
+        .option("artifact-requirements-json", { type: "string", describe: "JSON array of exact Artifact output requirements for the Build Plan" })
+        .option("ready-when", { type: "string", describe: "Proof or readiness expectations for the Build Plan" })
+        .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 hint for reviewers" })
+        .option("base-build-plan", { type: "string", describe: "Existing Build Plan id to use as a starting point" })
+        .option("reference-build-plan", { type: "string", describe: "Existing Build Plan id to reference while drafting" })
+        .option("json", { type: "boolean", default: false, describe: "Print machine-readable run metadata" }), async (args) => {
+        await startBuildPlanRun(args, "draft");
+    })
+        .command("improve <prep-id>", "Start a Build Plan improvement run for a preparation", (y) => y
+        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .option("task", { type: "string", describe: "Change request for the selected Build Plan" })
+        .option("artifacts", { type: "string", describe: "Requested Artifact changes and why they matter" })
+        .option("artifact-requirements-json", { type: "string", describe: "JSON array of exact Artifact output requirements for the Build Plan" })
+        .option("ready-when", { type: "string", describe: "Proof or readiness expectations 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 hint for reviewers" })
+        .option("base-build-plan", { type: "string", describe: "Existing Build Plan id to use as a starting point" })
+        .option("reference-build-plan", { type: "string", describe: "Existing Build Plan id to reference while improving" })
+        .option("json", { type: "boolean", default: false, describe: "Print machine-readable run metadata" }), async (args) => {
+        await startBuildPlanRun(args, "improve");
+    })
+        .demandCommand(1)
+        .strict(),
+    handler: () => {
+        /* yargs subcommand handlers do the work */
+    },
+};

package/dist/cli/commands/{compile.d.ts → build.d.ts}

@@ -1,5 +1,5 @@
 import type { CommandModule } from "yargs";
-interface CompileArgs {
+interface BuildArgs {
     prepId: string;
     watch?: boolean;
     quiet?: boolean;
@@ -7,5 +7,5 @@ interface CompileArgs {
     url?: string;
     token?: string;
 }
-export declare const compileCommand: CommandModule<unknown, CompileArgs>;
+export declare const buildCommand: CommandModule<unknown, BuildArgs>;
 export {};

package/dist/cli/commands/{compile.js → build.js}

@@ -1,11 +1,11 @@
 /**
- * `interf compile <prep-id>` — start a compile run for a preparation.
+ * Build command stack.
  *
- *   interf compile bristol
- *   interf compile bristol --quiet      # only the locator on stdout (scripting)
- *   interf compile bristol --watch      # stream events
+ *   interf build bristol
+ *   interf build bristol --quiet      # only the locator on stdout (scripting)
+ *   interf build bristol --watch      # stream events
  *
- * Requires an active connection. Hits POST /v1/preparations/<id>/compile-runs.
+ * Requires an active connection. Hits POST /v1/preparations/<id>/build-runs.
  */
 import chalk from "chalk";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
@@ -39,23 +39,23 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
-export const compileCommand = {
-    command: "compile <prep-id>",
-    describe: "Start a compile run for a preparation",
+export const buildCommand = {
+    command: "build <prep-id>",
+    describe: "Run the selected Build Plan for a Preparation",
     builder: (yargs) => yargs
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
-        .option("watch", { type: "boolean", default: false, describe: "Stream run events" })
-        .option("quiet", { type: "boolean", default: false, describe: "Print only the portable-context locator on success" })
+        .option("watch", { type: "boolean", default: false, describe: "Stream build-run events" })
+        .option("quiet", { type: "boolean", default: false, describe: "Print only the context locator on success" })
         .option("idempotency-key", { type: "string", describe: "Client-supplied dedupe key" })
         .option("url", { type: "string", describe: "Override the active connection URL" })
         .option("token", { type: "string", describe: "Override the active bearer token" }),
     handler: async (args) => {
         const { url, token } = resolveConnection(args);
-        // 0.15 hard-error: refuse to start a compile if the engine has zero
-        // connected agents — the compile pipeline can't run without one.
+        // 0.15 hard-error: refuse to start a build if the engine has zero
+        // connected agents — the build pipeline can't run without one.
         const instance = await callJson(`${url}/v1/instance`, token);
         if (instance.body && instance.body.agent_count === 0) {
-            console.error(chalk.red("  Cannot compile — no agents available."));
+            console.error(chalk.red("  Cannot build — no agents available."));
             console.error("  Install Claude Code, Codex, Gemini, or another agent CLI, or");
             console.error("  register a custom CLI: `interf agents register <name> --command <cmd>`.");
             process.exit(1);
@@ -63,23 +63,23 @@ export const compileCommand = {
         const headers = {};
         if (args.idempotencyKey)
             headers["x-interf-idempotency-key"] = args.idempotencyKey;
-        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/compile-runs`, token, { method: "POST", headers, body: JSON.stringify({}) });
+        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/build-runs`, token, { method: "POST", headers, body: JSON.stringify({}) });
         if (status !== 201 && status !== 200 && status !== 202) {
-            console.error(chalk.red(`Failed to start compile run for ${args.prepId} (HTTP ${status}).`));
+            console.error(chalk.red(`Failed to start build run for ${args.prepId} (HTTP ${status}).`));
             if (raw)
                 console.error(raw);
             process.exit(1);
         }
         const run = body?.run;
         const runId = run?.run_id ?? "(unknown run)";
-        const locator = run?.portable_context_path ?? "(no locator)";
+        const locator = run?.verifiable_context_path ?? "(no locator)";
         if (args.quiet) {
             console.log(locator);
             return;
         }
         console.log();
-        console.log(`  Run ${chalk.bold(runId)} ${chalk.dim(`(${run?.status ?? "started"})`)}`);
-        console.log(`  Portable context: ${locator}`);
+        console.log(`  Build run ${chalk.bold(runId)} ${chalk.dim(`(${run?.status ?? "started"})`)}`);
+        console.log(`  Verifiable context: ${locator}`);
         if (run?.status === "succeeded" || run?.finished_at) {
             const prepResp = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}`, token);
             const readiness = prepResp.body?.readiness?.status;

package/dist/cli/commands/doctor.js

@@ -97,7 +97,7 @@ export const doctorCommand = {
                 id: "live",
                 label: "Live executor preflight",
                 status: "skipped",
-                message: "Skipped. Run `interf doctor --live` to exercise the real local agent before drafting readiness checks, Method authoring, a readiness check, or a compile run.",
+                message: "Skipped. Run `interf doctor --live` to exercise the real local agent before drafting readiness checks, Build Plan authoring, a readiness check, or a Build run.",
             });
         }
         const ok = checks.every((check) => check.status !== "fail");
@@ -121,7 +121,7 @@ export const doctorCommand = {
             }
             console.log();
             if (!argv.live) {
-                console.log(chalk.dim("  Tip: run `interf doctor --live` before a first compile on a new machine."));
+                console.log(chalk.dim("  Tip: run `interf doctor --live` before a first build on a new machine."));
                 console.log();
             }
         }

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

@@ -1,37 +1,3 @@
-/**
- * `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
- *
- * The server reads `~/.interf/connection.json` (the same file every other
- * client uses) and exits non-zero with the connect-or-error hint if no
- * instance is reachable. Tools call straight through to the API; the
- * server itself holds no state. The transport options are intentionally
- * minimal — agents speaking MCP today are stdio-first.
- *
- * Tool list mirrors the API verbatim:
- *   prep_list           GET /v1/preparations
- *   prep_create         POST /v1/preparations
- *   prep_show           GET /v1/preparations/{id}
- *   prep_set_method     PATCH /v1/preparations/{id}
- *   prep_remove         DELETE /v1/preparations/{id}
- *   prep_compile        POST /v1/preparations/{id}/compile-runs
- *   prep_verify         POST /v1/preparations/{id}/verify-runs
- *   method_list         GET /v1/methods
- *   method_install      POST /v1/methods (preparation-scoped via `prep_id`)
- *   method_draft        POST /v1/preparations/{id}/method-authoring-runs
- *   method_improve      POST /v1/preparations/{id}/method-improvement-runs
- *   runs_status         GET /v1/runs/{run-id}
- *   runs_watch          GET /v1/runs/{run-id}/events  (snapshot, not SSE)
- *   runs_cancel         POST /v1/runs/{run-id}/cancel
- *   runs_fetch          GET /v1/runs/{run-id}/artifacts
- *   instance_status     GET /v1/instance
- */
 import type { CommandModule } from "yargs";
 interface McpArgs {
     transport?: "stdio" | "http";