@interf/compiler 0.22.2 → 0.33.0

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

@@ -1,19 +1,22 @@
 /**
- * `interf build-plan` — manage Build Plans on the connected instance.
+ * `interf 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
+ *   interf plan list                         # list Build Plans
+ *   interf plan show <plan-id>               # show a Build Plan summary
+ *   interf plan select <project-id> <id>     # select a Build Plan for a Project
+ *   interf plan save <path-or-id>            # save/promote a reusable Build Plan
+ *   interf plan draft <project-id>           # start a Build Plan draft run
+ *   interf plan improve <project-id>         # start a Build Plan improvement run
+ *
+ * The command name stays short for CLI ergonomics; user-facing copy says
+ * Build Plan.
  */
 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 { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.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({
@@ -45,10 +48,9 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
-function asArray(value) {
-    return Array.isArray(value) ? value : [];
-}
 const BuildPlanAuthoringArtifactRequirementsCliSchema = BuildPlanAuthoringArtifactRequirementSchema.array();
+const BuildPlanChecksCliSchema = BuildPlanContextCheckDraftSchema.array();
+const RequestedArtifactsCliSchema = RequestedArtifactSchema.array();
 function parseJsonOption(label, value, parse) {
     if (!value)
         return undefined;
@@ -70,16 +72,16 @@ function parseJsonOption(label, value, parse) {
         process.exit(1);
     }
 }
-function buildPreparationReviewUrl(url, prepId) {
-    return `${url}/?section=preparations&preparation=${encodeURIComponent(prepId)}&preparationTab=build-plan`;
+function buildProjectReviewUrl(url, projectId) {
+    return `${url}/?section=projects&project=${encodeURIComponent(projectId)}&projectTab=build-plan`;
 }
-function buildRunUrl(url, prepId, runId) {
+function buildRunUrl(url, projectId, runId) {
     if (!runId)
         return null;
-    return `${url}/?section=preparations&preparation=${encodeURIComponent(prepId)}&preparationTab=runs&run=${encodeURIComponent(runId)}`;
+    return `${url}/?section=projects&project=${encodeURIComponent(projectId)}&projectTab=runs&run=${encodeURIComponent(runId)}`;
 }
-function defaultBuildPlanIdForPreparation(prepId) {
-    return slugify(`${prepId}-build-plan`) || "build-plan";
+function defaultBuildPlanIdForProject(projectId) {
+    return slugify(`${projectId}-build-plan`) || "build-plan";
 }
 function labelFromBuildPlanId(buildPlanId) {
     const label = buildPlanId
@@ -132,121 +134,104 @@ function renderBuildPlanSummary(buildPlan) {
             console.log(chalk.dim(`        writes: ${writes}`));
         }
     }
-    if (buildPlan.active_for_preparations?.length) {
+    if (buildPlan.active_for_projects?.length) {
         console.log();
-        console.log(chalk.dim(`    used by: ${buildPlan.active_for_preparations.join(", ")}`));
+        console.log(chalk.dim(`    used by: ${buildPlan.active_for_projects.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;
+async function selectedBuildPlanRequestedArtifacts(url, token, buildPlanId) {
+    if (!buildPlanId)
+        return [];
+    const fetched = await callJson(`${url}${buildPlanResourcePath(buildPlanId)}`, token);
+    if (fetched.status !== 200 || !fetched.body)
+        return [];
+    return requestedArtifactsFromPlanArtifacts(fetched.body.artifacts ?? []);
 }
-function selectedBuildPlanId(preparation) {
-    return preparation.build_plan_id ?? preparation.preparation?.build_plan ?? null;
+function selectedBuildPlanId(project) {
+    return project.build_plan_id;
 }
-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));
+function buildTaskPrompt(args, requestedArtifacts, projectId, mode) {
+    const requestedArtifactsText = formatRequestedArtifactsForPrompt(requestedArtifacts);
     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,
+        `${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() ? `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.",
+        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.",
     ].filter((section) => Boolean(section));
     return sections.join("\n\n");
 }
-async function readPreparationContext(url, token, prepId) {
-    const fetched = await callJson(`${url}${preparationResourcePath(prepId)}`, token);
+async function readProjectContext(url, token, projectId) {
+    const fetched = await callJson(`${url}${projectResourcePath(projectId)}`, token);
     if (fetched.status !== 200 || !fetched.body) {
-        console.error(chalk.red(`Failed to read Preparation ${prepId} (HTTP ${fetched.status}).`));
+        console.error(chalk.red(`Failed to read Project ${projectId} (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),
+        project: 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 { project } = await readProjectContext(url, token, args.projectId);
+    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));
+    const requestedArtifacts = explicitRequestedArtifacts
+        ?? await selectedBuildPlanRequestedArtifacts(url, token, existingBuildPlan);
     const explicitArtifactRequirements = parseJsonOption("--artifact-requirements-json", args.artifactRequirementsJson, (input) => BuildPlanAuthoringArtifactRequirementsCliSchema.parse(input));
     const artifactRequirements = explicitArtifactRequirements
         ?? artifactRequirementsFromRequestedArtifacts(requestedArtifacts);
+    const explicitChecks = parseJsonOption("--checks-json", args.checksJson, (input) => BuildPlanChecksCliSchema.parse(input));
+    const sourceContext = parseJsonOption("--source-context-json", args.sourceContextJson, (input) => SourceContextSchema.parse(input));
+    const buildPlanChecks = explicitChecks
+        ?? (args.readyWhen?.trim()
+            ? [{
+                    label: args.readyWhen.trim(),
+                    backed_by_artifact_ids: artifactRequirements.map((artifact) => artifact.id),
+                    required: true,
+                }]
+            : []);
     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 "..."`));
+        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 "..."`));
         process.exit(1);
     }
     const body = {
-        preparation: args.prepId,
-        source_folder_path: sourceFolderPath,
+        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 Preparation ${args.prepId}.`,
-        task_prompt: buildTaskPrompt(args, preparation, args.prepId, mode),
-        checks,
+        hint: args.hint ?? `Build Plan for Project ${args.projectId}.`,
+        intent: buildTaskPrompt(args, requestedArtifacts, args.projectId, mode),
+        checks: buildPlanChecks,
         requested_artifacts: requestedArtifacts,
-        source_profile: preparationSourceProfile(preparation),
         artifact_requirements: artifactRequirements,
+        ...(sourceContext !== undefined ? { source_context: sourceContext } : {}),
     };
     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) });
+    const { status, body: run, raw } = await callJson(`${url}${projectSubresourcePath(args.projectId, 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);
+    const runUrl = buildRunUrl(url, args.projectId, run?.run_id);
+    const reviewUrl = buildProjectReviewUrl(url, args.projectId);
     if (args.json) {
         console.log(JSON.stringify({
             run_id: run?.run_id ?? null,
             status: run?.status ?? null,
-            preparation: args.prepId,
+            project: args.projectId,
             build_plan_id: buildPlanId,
             run_url: runUrl,
             review_url: reviewUrl,
@@ -260,8 +245,9 @@ async function startBuildPlanRun(args, mode) {
     console.log(chalk.dim(`  review after it finishes: ${reviewUrl}`));
 }
 export const buildPlanCommand = {
-    command: "build-plan <subcommand>",
+    command: "plan <subcommand>",
     describe: "Manage Build Plans on the connected instance",
+    aliases: [],
     builder: (yargs) => yargs
         .option("url", { type: "string", describe: "Override the active connection URL" })
         .option("token", { type: "string", describe: "Override the active bearer token" })
@@ -285,8 +271,8 @@ export const buildPlanCommand = {
             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(", ")}`));
+            if (buildPlan.active_for_projects?.length) {
+                console.log(chalk.dim(`    used by: ${buildPlan.active_for_projects.join(", ")}`));
             }
         }
         console.log();
@@ -327,42 +313,48 @@ export const buildPlanCommand = {
         }
         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" })
+        .command("select <project-id> <build-plan-id>", "Select a Build Plan for a Project", (y) => y
+        .positional("project-id", { type: "string", demandOption: true, describe: "Project 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 }) });
+        const { status, raw } = await callJson(`${url}${projectResourcePath(args.projectId)}`, 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)}.`));
+        console.log(chalk.green(`Selected Build Plan ${chalk.bold(args.buildPlanId)} for ${chalk.bold(args.projectId)}.`));
     })
-        .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" })
+        .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("ready-when", { type: "string", describe: "Proof or readiness expectations 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("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("hint", { type: "string", describe: "Short Build Plan summary for review" })
         .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" })
+        .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("ready-when", { type: "string", describe: "Proof or readiness expectations to add or change" })
+        .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("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("hint", { type: "string", describe: "Short Build Plan summary for review" })
         .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) => {

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

@@ -1,6 +1,6 @@
 import type { CommandModule } from "yargs";
 interface BuildArgs {
-    prepId: string;
+    projectId: string;
     watch?: boolean;
     quiet?: boolean;
     idempotencyKey?: string;

package/dist/cli/commands/build.js

@@ -5,10 +5,11 @@
  *   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>/build-runs.
+ * Requires an active connection. Hits POST /v1/projects/<id>/build-runs.
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.js";
+import { projectSubresourcePath } from "../../packages/runtime/service/routes.js";
 function resolveConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,
@@ -40,19 +41,19 @@ async function callJson(url, token, init = {}) {
     return { status: response.status, body, raw };
 }
 export const buildCommand = {
-    command: "build <prep-id>",
-    describe: "Run the selected Build Plan for a Preparation",
+    command: "build <project-id>",
+    describe: "Build Context Graph for a Project",
     builder: (yargs) => yargs
-        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
-        .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" })
+        .positional("project-id", { type: "string", demandOption: true, describe: "Project id" })
+        .option("watch", { type: "boolean", default: false, describe: "Stream Run events" })
+        .option("quiet", { type: "boolean", default: false, describe: "Print only the Context Graph 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 build if the engine has zero
-        // connected agents — the build pipeline can't run without one.
+        // hard-error: refuse to start a Build if the local service has zero
+        // execution 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 build — no agents available."));
@@ -63,26 +64,26 @@ export const buildCommand = {
         const headers = {};
         if (args.idempotencyKey)
             headers["x-interf-idempotency-key"] = args.idempotencyKey;
-        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/build-runs`, token, { method: "POST", headers, body: JSON.stringify({}) });
+        const { status, body, raw } = await callJson(`${url}${projectSubresourcePath(args.projectId, "buildRuns")}`, token, { method: "POST", headers, body: JSON.stringify({}) });
         if (status !== 201 && status !== 200 && status !== 202) {
-            console.error(chalk.red(`Failed to start build run for ${args.prepId} (HTTP ${status}).`));
+            console.error(chalk.red(`Failed to build Context Graph for ${args.projectId} (HTTP ${status}).`));
             if (raw)
                 console.error(raw);
             process.exit(1);
         }
         const run = body?.run;
         const runId = run?.run_id ?? "(unknown run)";
-        const locator = run?.verifiable_context_path ?? "(no locator)";
+        const locator = run?.context_graph_path ?? "(no locator)";
         if (args.quiet) {
             console.log(locator);
             return;
         }
         console.log();
         console.log(`  Build run ${chalk.bold(runId)} ${chalk.dim(`(${run?.status ?? "started"})`)}`);
-        console.log(`  Verifiable context: ${locator}`);
+        console.log(`  Context Graph: ${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;
+            const projectResp = await callJson(`${url}/v1/projects/${encodeURIComponent(args.projectId)}`, token);
+            const readiness = projectResp.body?.readiness?.status;
             if (readiness)
                 console.log(`  Readiness: ${readiness}`);
         }

package/dist/cli/commands/doctor.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { agents, userConfig } from "../../packages/engine/agents/index.js";
+import { agents, userConfig } from "../../packages/runtime/agents/index.js";
 function iconFor(status) {
     if (status === "pass")
         return chalk.green("✓");
@@ -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, Build Plan authoring, a readiness check, or a Build run.",
+                message: "Skipped. Run `interf doctor --live` to exercise the real local agent before drafting benchmark questions, Build Plan authoring, a benchmark pass, or a Build.",
             });
         }
         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 build 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/graphs.d.ts

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

package/dist/cli/commands/graphs.js

@@ -0,0 +1,199 @@
+/**
+ * `interf graphs` — inspect Context Graphs on the connected instance.
+ *
+ *   interf graphs ls --project <id>
+ *   interf graphs show <graphId> --project <id>
+ *   interf graphs open <graphId> --project <id>
+ */
+import chalk from "chalk";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/runtime/connection-config.js";
+import { ContextGraphListResponseSchema, ContextGraphResourceSchema, } from "../../packages/runtime/schemas/index.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 graphUrl(baseUrl, projectId, graphId) {
+    const root = `${baseUrl}/v1/projects/${encodeURIComponent(projectId)}/graphs`;
+    return graphId ? `${root}/${encodeURIComponent(graphId)}` : root;
+}
+function statusColor(graph) {
+    const status = graph.readiness?.status;
+    if (graph.readiness?.ready || status === "ready")
+        return chalk.green;
+    if (status === "failed" || status === "not-ready")
+        return chalk.red;
+    return chalk.yellow;
+}
+function renderGraph(graph) {
+    const color = statusColor(graph);
+    const graphId = graph.graph_id ?? graph.latest_build_run_id ?? `${graph.project}-latest`;
+    const status = graph.readiness?.status ?? "unknown";
+    console.log();
+    console.log(`  ${chalk.bold(graphId)} ${color(`(${status})`)}`);
+    console.log(chalk.dim(`    project: ${graph.project_id ?? graph.project}`));
+    if (graph.build_run_id ?? graph.latest_build_run_id) {
+        console.log(chalk.dim(`    run: ${graph.build_run_id ?? graph.latest_build_run_id}`));
+    }
+    if (graph.build_plan)
+        console.log(chalk.dim(`    Build Plan: ${graph.build_plan}`));
+    if (graph.created_at)
+        console.log(chalk.dim(`    created: ${graph.created_at}`));
+    console.log(chalk.dim(`    path: ${graph.path}`));
+    if (graph.build_evidence?.summary)
+        console.log(chalk.dim(`    evidence: ${graph.build_evidence.summary}`));
+    console.log();
+}
+export const graphsCommand = {
+    command: "graphs <subcommand>",
+    describe: "Inspect Context Graphs produced for a Project",
+    builder: (yargs) => yargs
+        .option("url", { type: "string", describe: "Override the active connection URL" })
+        .option("token", { type: "string", describe: "Override the active bearer token" })
+        .command("ls", "List Context Graphs for a Project", (y) => y.option("project", {
+        type: "string",
+        demandOption: true,
+        describe: "Project id",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(graphUrl(url, args.project), token);
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to list Context Graphs (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        const parsed = ContextGraphListResponseSchema.safeParse(body);
+        if (!parsed.success) {
+            console.error(chalk.red("Failed to parse Context Graph list."));
+            process.exit(1);
+        }
+        const graphs = parsed.data.graphs;
+        if (graphs.length === 0) {
+            console.log(chalk.dim("  No Context Graphs."));
+            return;
+        }
+        console.log();
+        for (const graph of graphs) {
+            const marker = graph.is_latest ? " latest" : "";
+            const statusLabel = graph.readiness?.status ?? "unknown";
+            const graphId = graph.graph_id ?? graph.latest_build_run_id ?? `${graph.project}-latest`;
+            console.log(`  ${chalk.bold(graphId)} ${chalk.dim(`(${statusLabel}${marker})`)}`);
+            console.log(chalk.dim(`    path: ${graph.path}`));
+        }
+        console.log();
+    })
+        .command("show <graphId>", "Show one Context Graph", (y) => y
+        .positional("graphId", {
+        type: "string",
+        demandOption: true,
+        describe: "Context Graph id, or latest",
+    })
+        .option("project", {
+        type: "string",
+        demandOption: true,
+        describe: "Project id",
+    })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw JSON record",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const resource = await readGraph(url, token, args.project, args.graphId);
+        if (args.json) {
+            console.log(JSON.stringify(resource, null, 2));
+            return;
+        }
+        renderGraph(resource);
+    })
+        .command("open <graphId>", "Open a Context Graph folder", (y) => y
+        .positional("graphId", {
+        type: "string",
+        demandOption: true,
+        describe: "Context Graph id, or latest",
+    })
+        .option("project", {
+        type: "string",
+        demandOption: true,
+        describe: "Project id",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const resource = await readGraph(url, token, args.project, args.graphId);
+        const { status, raw } = await callJson(`${url}/v1/open-path`, token, {
+            method: "POST",
+            body: JSON.stringify({ path: resource.path }),
+        });
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to open Context Graph (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.dim(`  Opened ${resource.path}`));
+    })
+        .demandCommand(1, "Choose a graphs subcommand."),
+    handler: () => {
+        // Subcommands own all behavior.
+    },
+};
+async function readGraph(url, token, projectId, graphId) {
+    if (graphId === "latest") {
+        const { status, body, raw } = await callJson(graphUrl(url, projectId), token);
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to read latest Context Graph (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        const parsed = ContextGraphListResponseSchema.safeParse(body);
+        if (!parsed.success) {
+            console.error(chalk.red("Failed to parse Context Graph list."));
+            process.exit(1);
+        }
+        const latest = parsed.data.graphs.find((graph) => graph.is_latest) ?? parsed.data.graphs[0] ?? null;
+        if (!latest) {
+            console.error(chalk.red(`Project ${projectId} has no Context Graph.`));
+            process.exit(1);
+        }
+        return latest;
+    }
+    const { status, body, raw } = await callJson(graphUrl(url, projectId, graphId), token);
+    if (status !== 200 || !body) {
+        console.error(chalk.red(`Failed to read Context Graph ${graphId} (HTTP ${status}).`));
+        if (raw)
+            console.error(raw);
+        process.exit(1);
+    }
+    const parsed = ContextGraphResourceSchema.safeParse(body);
+    if (!parsed.success) {
+        console.error(chalk.red(`Failed to parse Context Graph ${graphId}.`));
+        process.exit(1);
+    }
+    return parsed.data;
+}