@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/actions/form-builders.js

@@ -7,31 +7,36 @@ import { buildPlanAuthoringSchema, buildPlanChangeSchema, createProjectSchema, p
 import { buildPlanAuthoringActionValues, buildPlanChangeActionValues, createProjectActionValues, duplicateProjectActionValues, normalizedBuildPlanActionValues, projectChangeActionValues, selectBuildPlanActionValues, } from "./requests.js";
 export function buildCreateProjectActionDefinition(context) {
     const existingNames = new Set(context.existingNames);
-    const name = uniqueActionId(context.suggestedName, existingNames);
+    // Friendly default name (e.g. the dropped folder's name). Any text is fine;
+    // the durable Project id is slugged from it on submit.
+    const suggestedName = context.suggestedName?.trim() || "My project";
     return {
         id: INTERF_SERVICE_ACTIONS.createProject.id,
         title: INTERF_SERVICE_ACTIONS.createProject.title,
-        description: "Create a Project by binding a Source. Draft or select a Build Plan after the Project exists.",
+        description: "Create a Project from a folder of files. Pick or draft a Build Plan after it's created.",
         submitLabel: "Create Project",
         initialValues: {
-            name,
+            name: suggestedName,
             path: context.projectDataDir,
+            intent: context.suggestedIntent ?? "",
         },
         schema: createProjectSchema(existingNames),
         validateRequest: (values) => packageSchemaFieldErrors(ProjectSetupActionValuesSchema.safeParse(createProjectActionValues(values)), {
             name: "name",
             path: "path",
+            intent: "intent",
             build_plan: "build_plan",
         }),
         valuesPreview: createProjectActionValues,
         buildDraft: (values) => {
             const actionValues = createProjectActionValues(values);
             return {
-                project: inputValue(values, "name"),
+                project: actionValues.name,
                 values: actionValues,
                 message: [
-                    `Create Project ${inputValue(values, "name")}.`,
+                    `Create Project ${actionValues.name}.`,
                     `Source: ${inputValue(values, "path")}`,
+                    `Agent task: ${inputValue(values, "intent")}`,
                     "Draft or select the Build Plan after this Project exists. Do not build yet.",
                     "Use the attached typed action input as the source of truth.",
                 ].filter((line) => Boolean(line)).join("\n"),
@@ -40,20 +45,29 @@ export function buildCreateProjectActionDefinition(context) {
         fields: [
             {
                 name: "name",
-                label: "Project id",
+                label: "Project name",
                 type: "text",
-                help: "Lowercase id for this Project. Use letters, numbers, and dashes.",
-                context: "Saved as the durable Project id.",
-                placeholder: name,
+                help: "Use any name you like.",
+                context: "Saved as this Project's name.",
+                placeholder: suggestedName,
             },
             {
                 name: "path",
                 label: "Source",
                 type: "text",
-                help: "Absolute path to the folder Interf reads from. Files stay where they are; Interf reads them by reference. You can link this later if you don't have a folder yet.",
+                help: "The folder your agent maps into a Source. Your files stay where they are.",
                 context: "Saved as the Project's Source binding.",
                 placeholder: context.projectDataDir || "/Users/you/Documents/your-folder",
             },
+            {
+                name: "intent",
+                label: "Agent task",
+                type: "textarea",
+                rows: 4,
+                help: "What you want your agent to prepare from these files.",
+                context: "Saved as the Project intent and used as the default Build Plan task.",
+                placeholder: "Example: Build a timeline of our team's calls and find recurring themes.",
+            },
         ],
     };
 }
@@ -84,7 +98,7 @@ export function buildBuildRunActionDefinition(context) {
             message: [
                 `Build Context Graph for Project ${inputValue(values, "project")}.`,
                 `Build Plan: ${inputValue(values, "build_plan") || "(saved selection)"}.`,
-                "Build a Context Graph from the saved Source and requested Artifacts.",
+                "Build a Context Graph from the saved Source and requested outputs.",
                 "Use the attached typed action input as the source of truth.",
             ].filter((line) => Boolean(line)).join("\n"),
         }),
@@ -131,6 +145,7 @@ export function buildSelectBuildPlanActionDefinition(context) {
         initialValues: {
             name: context.name,
             path: context.sourceFolderPath,
+            intent: context.intent,
             current_build_plan: context.currentBuildPlanId ?? "",
             build_plan: context.currentBuildPlanId ?? "",
         },
@@ -138,6 +153,7 @@ export function buildSelectBuildPlanActionDefinition(context) {
         validateRequest: (values) => packageSchemaFieldErrors(ProjectSetupActionValuesSchema.safeParse(actionValues(values)), {
             name: "name",
             path: "path",
+            intent: "intent",
             build_plan: "build_plan",
         }),
         valuesPreview: actionValues,
@@ -185,6 +201,16 @@ export function buildSelectBuildPlanActionDefinition(context) {
                 help: "The saved local folder for this Source.",
                 context: "Preserved while updating the selected Build Plan.",
             },
+            {
+                name: "intent",
+                label: "Agent task",
+                type: "textarea",
+                rows: 4,
+                readOnly: true,
+                advanced: true,
+                help: "The Project intent that Build Plan drafting uses by default.",
+                context: "Preserved while updating the selected Build Plan.",
+            },
         ],
     };
 }
@@ -193,16 +219,22 @@ export function buildCreateBuildPlanActionDefinition(context) {
     const defaultSeed = context.defaultProject ? `${context.defaultProject}-build-plan` : context.suggestedBuildPlanId;
     const buildPlanId = uniqueActionId(defaultSeed, existingBuildPlanIds);
     const label = titleFromActionId(buildPlanId);
+    const projectIntent = context.projectIntent?.trim() ?? "";
+    // In a Project the task is already set, so Intent is shown read-only under
+    // The one thing we actually ask is how the user wants their files prepared
+    // into the Context Graph. Outputs are an optional advanced refinement.
+    // Standalone (no Project) keeps Intent as the primary, editable field.
+    const inProject = Boolean(context.defaultProject);
     return {
         id: INTERF_SERVICE_ACTIONS.createBuildPlan.id,
         title: INTERF_SERVICE_ACTIONS.createBuildPlan.title,
-        description: "Describe the Artifacts the agent needs. Interf drafts the Build Plan from this description; the Build later records what was covered.",
+        description: "Describe how you want Interf to prepare and structure your files into a Context Graph. Interf drafts a Build Plan from your task and this description, and shows it to you before building.",
         submitLabel: "Draft Build Plan",
         initialValues: {
             build_plan_id: "",
             label: "",
             hint: "",
-            intent: "",
+            intent: projectIntent,
             requested_artifacts_description: "",
             user_prep_instructions: "",
         },
@@ -234,32 +266,36 @@ export function buildCreateBuildPlanActionDefinition(context) {
             ].join("\n"),
         }),
         fields: [
+            {
+                name: "user_prep_instructions",
+                label: "How should Interf prepare your files?",
+                type: "textarea",
+                rows: 4,
+                help: "Describe how you want your files structured and prepared into the Context Graph — the way you'd tell a colleague. This is the main thing Interf turns into a Build Plan you review before anything runs.",
+                context: "Primary Build Plan authoring instruction — guides how stages prepare and structure the Context Graph.",
+                placeholder: "Example: read each contract and lay it out one page at a time, with the parties, dates, and renewal terms pulled out and linked back to the source file.",
+            },
             {
                 name: "intent",
-                label: "Intent",
+                label: "Agent task",
                 type: "textarea",
                 rows: 4,
-                help: "The agent task this Project should unlock.",
+                ...(inProject ? { advanced: true, readOnly: true } : {}),
+                help: inProject
+                    ? "The Project task this draft builds from — set on the Project."
+                    : "The agent task this plan should unlock.",
                 context: "Used as the main Build Plan authoring instruction.",
                 placeholder: "Example: Analyze every report chart, extract annual take-up by location, and produce a source data file plus markdown summary.",
             },
             {
                 name: "requested_artifacts_description",
-                label: "Requested Artifacts",
+                label: "Specific outputs (optional)",
                 type: "textarea",
                 rows: 3,
-                help: "Files, sections, or evidence agents should receive in the Context Graph.",
-                context: "Guides the requested Artifact shape and Build Plan stages before a Build records Source coverage.",
-                placeholder: "Describe the files or sections agents should receive.",
-            },
-            {
-                name: "user_prep_instructions",
-                label: "Build instructions",
-                type: "textarea",
-                rows: 3,
-                help: "Checks and evidence these Artifacts should satisfy.",
-                context: "Guides Build Plan checks and evidence expectations. Artifact contract checks stay separate.",
-                placeholder: "Describe the evidence that should make these Artifacts ready.",
+                advanced: true,
+                help: "Optional. Call out specific outputs you want, the way you'd tell a colleague. Otherwise Interf infers them from how you want your files prepared.",
+                context: "Guides the requested outputs, Build Plan stages, and coverage metrics.",
+                placeholder: "Example: a summary of each contract with the parties, dates, and renewal terms — each linked back to the original file.",
             },
             {
                 name: "build_plan_id",
@@ -383,7 +419,7 @@ export function buildBuildPlanChangeActionDefinition(context) {
             advanced: true,
             help: "Short Build Plan summary to keep while modifying this Build Plan.",
             context: "Sent to the Build Plan authoring run.",
-            placeholder: context.hint ?? "Build Plan for requested Artifacts and Context Checks.",
+            placeholder: context.hint ?? "Build Plan for source coverage and task knowledge.",
         },
         {
             name: "project",
@@ -439,6 +475,7 @@ export function buildProjectChangeActionDefinition(context) {
             ? {
                 name: context.action === "duplicate" ? duplicateName : context.project,
                 path: context.sourceFolderPath,
+                intent: context.intent,
                 build_plan: context.buildPlanId ?? "",
             }
             : {}),
@@ -451,6 +488,7 @@ export function buildProjectChangeActionDefinition(context) {
                 `Modify Project ${inputValue(values, "project")}.`,
                 maybeActionValue(inputValue(values, "build_plan")) ? `Build Plan: ${inputValue(values, "build_plan")}` : null,
                 `Source: ${inputValue(values, "path")}`,
+                `Agent task: ${inputValue(values, "intent")}`,
                 "Use the attached typed Project setup input as the source of truth.",
             ].filter((line) => Boolean(line)).join("\n");
         }
@@ -459,6 +497,7 @@ export function buildProjectChangeActionDefinition(context) {
                 `Duplicate Project ${inputValue(values, "project")} as ${inputValue(values, "name")}.`,
                 maybeActionValue(inputValue(values, "build_plan")) ? `Build Plan: ${inputValue(values, "build_plan")}` : null,
                 `Source: ${inputValue(values, "path")}`,
+                `Agent task: ${inputValue(values, "intent")}`,
                 "Use the attached typed Project setup input as the source of truth.",
             ].filter((line) => Boolean(line)).join("\n");
         }
@@ -505,6 +544,14 @@ export function buildProjectChangeActionDefinition(context) {
             help: "The local folder for this Project's Source.",
             context: "Saved on this Project.",
         },
+        {
+            name: "intent",
+            label: "Agent task",
+            type: "textarea",
+            rows: 4,
+            help: "What this Project's Context Graph should prepare the Source for.",
+            context: "Saved as the durable Project intent.",
+        },
         {
             name: "confirmation",
             label: "Confirm removal",
@@ -529,6 +576,7 @@ export function buildProjectChangeActionDefinition(context) {
             ? (values) => packageSchemaFieldErrors(ProjectSetupActionValuesSchema.safeParse(duplicateProjectActionValues(values)), {
                 name: "name",
                 path: "path",
+                intent: "intent",
                 build_plan: "build_plan",
             })
             : undefined,
@@ -539,7 +587,7 @@ export function buildProjectChangeActionDefinition(context) {
             message: messageFor(values),
         }),
         fields: fields.filter((field) => {
-            if (field.name === "name" || field.name === "build_plan" || field.name === "path")
+            if (field.name === "name" || field.name === "build_plan" || field.name === "path" || field.name === "intent")
                 return context.action === "modify" || context.action === "duplicate";
             if (field.name === "confirmation")
                 return context.action === "remove";
@@ -609,7 +657,7 @@ export function buildBenchmarkActionDraft(options) {
     }
     return {
         project: options.project,
-        message: `Improve ${options.project} using the latest benchmark results and Build evidence.`,
+        message: `Improve ${options.project} using benchmark results, Graph Manifest metrics, Stage Manifests, and supplemental diagnostics.`,
         values: {
             action_type: INTERF_SERVICE_ACTIONS.improveProject.serviceAction,
             ...(options.buildPlanId ? { build_plan: options.buildPlanId } : {}),

package/dist/packages/runtime/actions/form-validators.js

@@ -1,14 +1,17 @@
 import { z } from "zod";
 import { ActionValueIdPattern, actionIdField, optionalActionIdField, optionalActionText, requiredActionText, } from "./schemas.js";
-import { maybeActionValue } from "./helpers.js";
+import { maybeActionValue, slugForActionId } from "./helpers.js";
 void ActionValueIdPattern;
 export function createProjectSchema(existingNames) {
     return z.object({
-        name: actionIdField("Project name"),
+        // Any text is accepted; the durable id is slugged from it on submit
+        // (see createProjectActionValues). Uniqueness is checked on the slug.
+        name: requiredActionText("Project name"),
         path: requiredActionText("Source"),
+        intent: requiredActionText("Agent task"),
         build_plan: optionalActionIdField("Build Plan").optional(),
     }).strict().superRefine((values, ctx) => {
-        if (existingNames.has(values.name)) {
+        if (existingNames.has(slugForActionId(values.name))) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ["name"],
@@ -28,6 +31,7 @@ export function selectBuildPlanSchema() {
     return z.object({
         name: actionIdField("Project"),
         path: requiredActionText("Source"),
+        intent: requiredActionText("Agent task"),
         current_build_plan: optionalActionIdField("Current Build Plan"),
         build_plan: actionIdField("Build Plan"),
     }).strict();
@@ -94,6 +98,7 @@ export function projectChangeSchema(action, project, existingNames) {
             ...base,
             name: actionIdField("Project id"),
             path: requiredActionText("Source"),
+            intent: requiredActionText("Agent task"),
             build_plan: optionalActionIdField("Build Plan"),
         }).strict().superRefine((values, ctx) => {
             if (values.name !== project && existingNames.has(values.name)) {
@@ -110,6 +115,7 @@ export function projectChangeSchema(action, project, existingNames) {
             ...base,
             name: actionIdField("New Project id"),
             path: requiredActionText("Source"),
+            intent: requiredActionText("Agent task"),
             build_plan: optionalActionIdField("Build Plan"),
         }).strict().superRefine((values, ctx) => {
             if (existingNames.has(values.name)) {

package/dist/packages/runtime/actions/helpers.js

@@ -8,8 +8,8 @@ export function buildPlanAuthoringIntentBrief(values) {
     const prepInstructions = values.user_prep_instructions?.trim();
     return [
         `Intent: ${values.intent}`,
-        requestedArtifacts ? `Requested Artifacts:\n${requestedArtifacts}` : null,
-        requestedArtifactsDescription ? `Requested Artifacts: ${requestedArtifactsDescription}` : null,
+        requestedArtifacts ? `Requested outputs:\n${requestedArtifacts}` : null,
+        requestedArtifactsDescription ? `Requested outputs: ${requestedArtifactsDescription}` : null,
         prepInstructions ? `Build instructions: ${prepInstructions}` : null,
     ].filter((line) => Boolean(line)).join("\n");
 }
@@ -67,7 +67,7 @@ export function buildPlanIntentFromInput(values) {
     const prepInstructions = inputValue(values, "user_prep_instructions");
     return [
         `Intent: ${intent}`,
-        maybeActionValue(requestedArtifactsDescription) ? `Requested Artifacts: ${requestedArtifactsDescription}` : null,
+        maybeActionValue(requestedArtifactsDescription) ? `Requested outputs: ${requestedArtifactsDescription}` : null,
         maybeActionValue(prepInstructions) ? `Build instructions: ${prepInstructions}` : null,
     ].filter((line) => Boolean(line)).join("\n");
 }

package/dist/packages/runtime/actions/registry.d.ts

@@ -57,7 +57,7 @@ export declare const INTERF_SERVICE_ACTIONS: {
         readonly id: "improve-project";
         readonly serviceAction: "build-plan-improvement";
         readonly title: "Improve Build Plan";
-        readonly description: "Use benchmark results and Build evidence to refine the Build Plan this Project uses.";
+        readonly description: "Use benchmark results, Graph Manifest metrics, Stage Manifests, and supplemental diagnostics to refine the Build Plan this Project uses.";
     };
 };
 export type InterfServiceActionKey = keyof typeof INTERF_SERVICE_ACTIONS;

package/dist/packages/runtime/actions/registry.js

@@ -57,6 +57,6 @@ export const INTERF_SERVICE_ACTIONS = {
         id: "improve-project",
         serviceAction: "build-plan-improvement",
         title: "Improve Build Plan",
-        description: "Use benchmark results and Build evidence to refine the Build Plan this Project uses.",
+        description: "Use benchmark results, Graph Manifest metrics, Stage Manifests, and supplemental diagnostics to refine the Build Plan this Project uses.",
     },
 };

package/dist/packages/runtime/actions/requests.d.ts

@@ -8,6 +8,7 @@ export declare function selectBuildPlanActionValues(values: ActionInputValues):
 export declare function projectSetupRequestFromActionValues(input: unknown): {
     project: {
         build_plan?: string;
+        intent: string;
         name: string;
         path: string;
     };
@@ -26,7 +27,6 @@ export declare function buildPlanAuthoringRequestFromActionValues(input: unknown
     hint?: string;
     label: string;
     build_plan_id: string;
-    project?: string;
     reference_build_plan_id?: string;
     requested_artifacts: RequestedArtifact[];
     source_context?: SourceContext | null;

package/dist/packages/runtime/actions/requests.js

@@ -1,6 +1,6 @@
 import { artifactRequirementsFromRequestedArtifacts, } from "../requested-artifacts.js";
 import { BuildPlanAuthoringActionValuesSchema, ProjectSetupActionValuesSchema, } from "./schemas.js";
-import { conciseSummary, inputValue, maybeActionValue, titleFromActionId, uniqueActionId, } from "./helpers.js";
+import { conciseSummary, inputValue, maybeActionValue, slugForActionId, titleFromActionId, uniqueActionId, } from "./helpers.js";
 export function normalizedBuildPlanActionValues(values, existingBuildPlanIds, defaultSeed) {
     const explicitBuildPlanId = maybeActionValue(inputValue(values, "build_plan_id"));
     const intent = inputValue(values, "intent").trim();
@@ -10,15 +10,18 @@ export function normalizedBuildPlanActionValues(values, existingBuildPlanIds, de
         ...values,
         build_plan_id: buildPlanId,
         label: maybeActionValue(inputValue(values, "label")) ?? titleFromActionId(buildPlanId),
-        hint: maybeActionValue(inputValue(values, "hint")) ?? conciseSummary(output ?? intent, "Build Plan for requested Artifacts and Context Checks."),
+        hint: maybeActionValue(inputValue(values, "hint")) ?? conciseSummary(output ?? intent, "Build Plan for requested outputs and coverage."),
         intent,
     };
 }
 export function createProjectActionValues(values) {
     const buildPlan = inputValue(values, "build_plan");
     return {
-        name: inputValue(values, "name"),
+        // Users type any friendly name; the durable Project id is a safe slug
+        // derived from it. Slugged here so both the UI and CLI get the same id.
+        name: slugForActionId(inputValue(values, "name")),
         path: inputValue(values, "path"),
+        intent: inputValue(values, "intent"),
         build_after_setup: false,
         ...(maybeActionValue(buildPlan) ? { build_plan: buildPlan } : {}),
     };
@@ -27,6 +30,7 @@ export function selectBuildPlanActionValues(values) {
     return {
         name: inputValue(values, "name"),
         path: inputValue(values, "path"),
+        intent: inputValue(values, "intent"),
         build_plan: inputValue(values, "build_plan"),
         build_after_setup: false,
         setup_mode: "select-build-plan",
@@ -41,6 +45,7 @@ export function projectSetupRequestFromActionValues(input) {
         project: {
             name: values.name,
             path: values.path,
+            intent: values.intent,
             ...(buildPlan && buildPlan.length > 0 ? { build_plan: buildPlan } : {}),
         },
     };
@@ -56,12 +61,11 @@ export function buildPlanAuthoringRequestFromActionValues(input, context) {
     const baseBuildPlanId = values.base_build_plan_id;
     const referenceBuildPlanId = values.reference_build_plan_id;
     return {
-        ...(context.project ? { project: context.project } : {}),
         ...(baseBuildPlanId ? { base_build_plan_id: baseBuildPlanId } : {}),
         ...(referenceBuildPlanId ? { reference_build_plan_id: referenceBuildPlanId } : {}),
         build_plan_id: buildPlanId,
         label: values.label ?? titleFromActionId(buildPlanId),
-        ...(values.hint ? { hint: values.hint } : { hint: conciseSummary(values.requested_artifacts_description ?? values.intent, "Reusable Build Plan for building Artifacts.") }),
+        ...(values.hint ? { hint: values.hint } : { hint: conciseSummary(values.requested_artifacts_description ?? values.intent, "Reusable Build Plan for prepared outputs.") }),
         intent: values.intent,
         checks: values.checks ?? context.checks ?? [],
         ...(values.user_prep_instructions ? { user_prep_instructions: values.user_prep_instructions } : {}),
@@ -76,7 +80,7 @@ export function buildPlanImprovementActionValues(options) {
         reference_build_plan_id: options.buildPlanId,
         ...(maybeActionValue(options.label ?? "") ? { label: options.label } : {}),
         ...(maybeActionValue(options.hint ?? "") ? { hint: options.hint } : {}),
-        intent: `Improve Build Plan ${options.buildPlanId} using the latest benchmark results and Build evidence for Project ${options.projectName}.`,
+        intent: `Improve Build Plan ${options.buildPlanId} using the latest benchmark results, Graph Manifest metrics, Stage Manifests, and supplemental graph diagnostics for Project ${options.projectName}.`,
     };
 }
 export function buildPlanAuthoringActionValues(values) {
@@ -131,6 +135,7 @@ export function duplicateProjectActionValues(values) {
     return {
         name: inputValue(values, "name"),
         path: inputValue(values, "path"),
+        intent: inputValue(values, "intent"),
         build_after_setup: false,
         setup_mode: "create",
         ...(maybeActionValue(buildPlan) ? { build_plan: buildPlan } : {}),
@@ -142,6 +147,7 @@ export function projectChangeActionValues(action, values) {
         return {
             name: inputValue(values, "project"),
             path: inputValue(values, "path"),
+            intent: inputValue(values, "intent"),
             build_after_setup: false,
             setup_mode: "select-build-plan",
             ...(maybeActionValue(buildPlan) ? { build_plan: buildPlan } : {}),

package/dist/packages/runtime/actions/schemas.d.ts

@@ -37,6 +37,9 @@ export declare const RequestedArtifactActionValueSchema: z.ZodPipe<z.ZodTransfor
                 frontmatter_required_keys: "frontmatter_required_keys";
                 frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                 source_refs_required: "source_refs_required";
+                summary_backlinks_present: "summary_backlinks_present";
+                knowledge_web_connectivity: "knowledge_web_connectivity";
+                graph_notes_connected: "graph_notes_connected";
                 wikilinks_valid: "wikilinks_valid";
                 must_not_contain: "must_not_contain";
                 must_contain: "must_contain";
@@ -64,6 +67,7 @@ export declare const SourceContextActionValueSchema: z.ZodObject<{
 export declare const ProjectSetupActionValuesSchema: z.ZodObject<{
     name: z.ZodString;
     path: z.ZodString;
+    intent: z.ZodString;
     build_plan: z.ZodOptional<z.ZodString>;
     build_after_setup: z.ZodOptional<z.ZodBoolean>;
     setup_mode: z.ZodOptional<z.ZodEnum<{
@@ -110,6 +114,9 @@ export declare const BuildPlanAuthoringActionValuesSchema: z.ZodObject<{
                     frontmatter_required_keys: "frontmatter_required_keys";
                     frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
                     source_refs_required: "source_refs_required";
+                    summary_backlinks_present: "summary_backlinks_present";
+                    knowledge_web_connectivity: "knowledge_web_connectivity";
+                    graph_notes_connected: "graph_notes_connected";
                     wikilinks_valid: "wikilinks_valid";
                     must_not_contain: "must_not_contain";
                     must_contain: "must_contain";

package/dist/packages/runtime/actions/schemas.js

@@ -12,6 +12,7 @@ export const SourceContextActionValueSchema = SourceContextSchema;
 export const ProjectSetupActionValuesSchema = z.object({
     name: ActionValueIdSchema,
     path: z.string().trim().min(1, "Source is required."),
+    intent: z.string().trim().min(1, "Agent task is required."),
     build_plan: OptionalActionValueIdSchema.optional(),
     build_after_setup: z.boolean().optional(),
     setup_mode: z.enum(["create", "select-build-plan"]).optional(),

package/dist/packages/runtime/agent-handoff.js

@@ -10,7 +10,7 @@ export function buildInterfMcpServers(input) {
             label: "Interf MCP",
             command: input.mcpCommand,
             args: input.mcpArgs ?? [],
-            instructions: "Use this with Claude Desktop, Cursor, or another local MCP host while Interf.app is open.",
+            instructions: "Use this with Claude Desktop, Cursor, or another local MCP host while the local Interf service is running.",
         });
     }
     mcpServers.push({
@@ -47,7 +47,7 @@ export function buildInterfMcpInstructions(input) {
         "Interf MCP lets a host such as Claude Desktop or Cursor talk to Interf. Agents listed inside Interf are executors that run Build Plan stages. Do not mix these concepts.",
         "",
         "MCP setup:",
-        "Interf MCP. Keep Interf.app open; the MCP process talks to the app-owned local service and must not start a separate Interf runtime.",
+        "Interf MCP. Keep the local Interf service running; the MCP process talks to that authorized service and must not start a separate Interf runtime.",
         ...(mcpConfig
             ? [
                 "",
@@ -66,18 +66,19 @@ export function buildInterfMcpInstructions(input) {
         "```",
         "",
         "Rules:",
-        "- Default flow: identify the current Source, create a fresh Project for this session unless the user explicitly names an existing Project id, propose Context Checks and requested Artifacts, draft a Build Plan after the user approves those checks and Artifacts, stop for Build Plan approval, build only after that approval, then answer from the prepared Context Graph and traces.",
-        "- Source scope default: when Interf Desktop, MCP, or the user context provides a Source locator or file set, use the whole Source. Do not ask the user to choose individual files or a subset unless they explicitly ask to narrow scope.",
+        "- Default flow: identify the current Source, create a fresh Project for this session unless the user explicitly names an existing Project id, prepare a Build Plan from the Project intent and requested outputs, stop for Build Plan approval, build only after that approval, then read home.md, GraphManifest primary metrics, knowledge/summaries, and source-backed traces.",
+        "- Source scope default: when Interf, MCP, or the user context provides a Source locator or file set, use the whole Source. Do not ask the user to choose individual files or a subset unless they explicitly ask to narrow scope.",
         "- Do not browse existing Projects as a corpus. Reuse an existing Context Graph only when it clearly matches the same Source and task.",
         "- If no Project matches the current Source, create a new Project for this session.",
-        "- If no usable Source locator is available, ask for one Source locator instead of answering from unrelated Projects. In the local Desktop path this may be a folder path. Do not present a file-selection menu.",
+        "- If no usable Source locator is available, ask for one Source locator instead of answering from unrelated Projects. In the local path this may be a folder path. Do not present a file-selection menu.",
         `- Probe only discovery resources before authorization: ${input.serviceUrl}/health, ${input.serviceUrl}/v1, ${input.serviceUrl}/v1/instance, or ${input.serviceUrl}/v1/openapi.json`,
         "- Do not scan ports.",
         "- Send `Authorization: Bearer <auth_token>` on every protected `/v1` request. `/health`, `/v1`, `/v1/instance`, and `/v1/openapi.json` are discovery routes.",
-        "- Do not install npm or npx packages for the Desktop flow.",
-        "- Do not use a global `interf` CLI for the Desktop MCP flow when the app-backed MCP launcher is available.",
+        "- Do not install npm or npx packages for an already-configured local MCP handoff.",
+        "- Do not use a global `interf` CLI when an app-backed MCP launcher is available.",
         "- Project creation is allowed when the user asks Interf to use a Source. Project ids are generated internally. Do not ask for existing Project ids.",
         "- Ask before drafting Build Plans or starting Build runs unless the user grants autonomy.",
+        "- After a Build succeeds, start from home.md. Use GraphManifest primary metrics for coverage, summaries/ for Source coverage proof, knowledge/ for drilldown, and artifacts/ only for focused task entrypoint notes.",
         "- No automatic retries: if a Build Plan draft, Build Plan improvement, Build run, or status poll reaches failed/cancelled, report what failed and ask the user before starting another run.",
     ].join("\n");
 }

package/dist/packages/runtime/agents/lib/execution-profile.d.ts

@@ -11,6 +11,20 @@ type ExecutionProfileArgSource = Record<string, unknown> & {
     "timeout-ms"?: unknown;
 };
 export declare function executionProfileFromArgv(argv: ExecutionProfileArgSource): AgentExecutionProfile;
+/**
+ * Resolve the EFFECTIVE execution profile for an agent: the per-run override
+ * (`executionProfile`) wins, and any field it leaves unset falls back to the
+ * agent's saved prefs (`~/.interf/agents.json` `agent_prefs[name]`). This is
+ * the single merge that used to live inline in `spawnAgent`. It is resolved
+ * ONCE at executor construction so the model the executor REPORTS
+ * (`buildRuntimeExecutorInfo`) is the exact model the executor RUNS
+ * (`buildAgentArgs`) — a session can no longer record `model: null` for a run
+ * whose model came from saved prefs (the common path).
+ *
+ * `profile` / `timeoutMs` are not pref-backed today (prefs only carry
+ * `model` / `effort` / `env_vars`), so they pass through unchanged.
+ */
+export declare function resolveEffectiveAgentExecutionProfile(agent: AgentLike, executionProfile?: AgentExecutionProfile): AgentExecutionProfile;
 export declare function applyInternalAcceptanceExecutionProfileDefaults(agent: AgentLike, overrides?: AgentExecutionProfile): AgentExecutionProfile;
 export declare function hasAgentExecutionProfile(profile: AgentExecutionProfile | null | undefined): boolean;
 export declare function formatAgentExecutionProfile(profile: AgentExecutionProfile | null | undefined): string | null;

package/dist/packages/runtime/agents/lib/execution-profile.js

@@ -1,4 +1,5 @@
 import { getBuiltInProvider } from "../providers/index.js";
+import { loadAgentPrefs } from "../registry.js";
 const INTERNAL_ACCEPTANCE_TIMEOUT_MS = 480000;
 function readAgentName(agent) {
     if (!agent)
@@ -47,6 +48,28 @@ export function executionProfileFromArgv(argv) {
         timeoutMs: normalizeOptionalTimeout(argv.timeoutMs ?? argv["timeout-ms"]),
     };
 }
+/**
+ * Resolve the EFFECTIVE execution profile for an agent: the per-run override
+ * (`executionProfile`) wins, and any field it leaves unset falls back to the
+ * agent's saved prefs (`~/.interf/agents.json` `agent_prefs[name]`). This is
+ * the single merge that used to live inline in `spawnAgent`. It is resolved
+ * ONCE at executor construction so the model the executor REPORTS
+ * (`buildRuntimeExecutorInfo`) is the exact model the executor RUNS
+ * (`buildAgentArgs`) — a session can no longer record `model: null` for a run
+ * whose model came from saved prefs (the common path).
+ *
+ * `profile` / `timeoutMs` are not pref-backed today (prefs only carry
+ * `model` / `effort` / `env_vars`), so they pass through unchanged.
+ */
+export function resolveEffectiveAgentExecutionProfile(agent, executionProfile = {}) {
+    const name = readAgentName(agent);
+    const prefs = name ? loadAgentPrefs()[name] : undefined;
+    return {
+        ...executionProfile,
+        model: executionProfile.model ?? prefs?.model ?? null,
+        effort: executionProfile.effort ?? prefs?.effort ?? null,
+    };
+}
 export function applyInternalAcceptanceExecutionProfileDefaults(agent, overrides = {}) {
     const provider = getBuiltInProvider(readAgentName(agent) ?? "");
     const defaultModel = provider?.defaultModel ?? null;

package/dist/packages/runtime/agents/lib/execution.js

@@ -3,20 +3,20 @@ import chalk from "chalk";
 import { getBuiltInProvider } from "../providers/index.js";
 import { loadAgentPrefs } from "../registry.js";
 import { buildAgentArgs, buildAgentEnv } from "./args.js";
-import { appendAgentEventLog, appendAgentStatusLog } from "./logs.js";
-import { displayAgentEvent, emitVisibleAgentText, summarizeAgentToolActivity, } from "./render.js";
+import { appendAgentEventLog, appendAgentReasoningLog, appendAgentStatusLog } from "./logs.js";
+import { displayAgentEvent, emitVisibleAgentText, extractAgentReasoning, summarizeAgentToolActivity, } from "./render.js";
 import { classifyTerminalVisibleStatus, extractAgentFailureStatus, hasAgentStalled, } from "./status.js";
 const STOP_SIGNAL_GRACE_MS = 1500;
 export function spawnAgent(agent, dirPath, prompt, options = {}) {
     return new Promise((resolve) => {
         const noiseFilters = getBuiltInProvider(agent.name)?.noiseFilters ?? [];
         const prefs = loadAgentPrefs()[agent.name];
-        const mergedProfile = {
-            ...options.executionProfile,
-            model: options.executionProfile?.model ?? prefs?.model ?? null,
-            effort: options.executionProfile?.effort ?? prefs?.effort ?? null,
-        };
-        const args = buildAgentArgs(agent, prompt, mergedProfile);
+        // The execution profile arrives already resolved (per-run override ∨ saved
+        // prefs) from `createLocalAgentExecutor`, so the CLI args built here use the
+        // SAME model/effort the session records via `buildRuntimeExecutorInfo` (F1).
+        // `prefs.env_vars` is still read below — env vars are a spawn concern, not
+        // part of the execution profile, so they are not pre-resolved.
+        const args = buildAgentArgs(agent, prompt, options.executionProfile ?? {});
         appendAgentEventLog(options.eventLogPath, {
             type: "spawn",
             command: agent.command,
@@ -184,6 +184,12 @@ export function spawnAgent(agent, dirPath, prompt, options = {}) {
                     if (toolActivity) {
                         lastToolActivity = toolActivity;
                     }
+                    // Tee reasoning/thinking spans the display path discards to the
+                    // reasoning transcript. Best-effort: the writer swallows errors and
+                    // events without reasoning yield nothing, so the run is never blocked.
+                    for (const span of extractAgentReasoning(event)) {
+                        appendAgentReasoningLog(options.reasoningLogPath, span);
+                    }
                     failureStatus ||= extractAgentFailureStatus(event);
                     if (displayAgentEvent(event, options.statusLogPath, lastVisibleText, options.onStatus)) {
                         sawVisibleEvent = true;