@interf/compiler 0.7.1 → 0.7.3

package/README.md

@@ -1,34 +1,35 @@
 # Interf
 
-Interf prepares portable context for your agents.
+Interf prepares data for agent work. It runs locally, processes your files, shows evidence that your data is ready, and writes portable context: a local folder with verifiable outputs agents can use.
 
-Point an agent at a folder of files. It gets a partial picture. It picks up false hypotheses from a shallow read. Then it carries those into the work — missed evidence, links lost across files, confident answers that are wrong.
+**Hallucinations aren't an agent problem. They're a data preparation problem.**
 
-The fix is structure: summarize the files, organize by category, link what belongs together. You tell Interf Compiler how. That's a compilation workflow.
+When agents start from source files, they have to discover the full picture while they work. That discovery is hidden: you cannot see which files were processed, which evidence was used, or which connections were found.
 
-`Interf Compiler` is a local runtime. It runs your compilation workflow on your files. Your local agent executes each stage. The output is portable context — a local folder your agent reads. If the first build misses your questions, Interf improves the workflow and builds again.
+Interf replaces that hidden discovery with a visible file-processing workflow: how you tell Interf to prepare your files for the job agents need to do. You define how the files should be processed, what outputs agents should get, and what evidence should show the data is ready. Interf runs the workflow locally and writes the portable context: evidence, structure, and cross-file connections for agents.
 
 ```text
-project-root/
-  bristol-office-analysis/
-    report.md
-    notes.md
-    exports/
-  interf.json                   # main config: works, source paths, questions, workflow choices, and defaults
-  interf/
-    bristol-office-analysis/    # portable context your agent starts from
-    workflows/
-      interf-default/           # built-in compilation workflow, copied here on init — inspect, edit, or fork
-      your-custom-workflow/     # optional: your own, via `interf create workflow`
-    tests/
-      bristol-office-analysis/  # saved source-files vs portable-context comparisons
+bristol-office-analysis/
+  report.md
+  notes.md
+  exports/
+interf/
+  interf.json                 # saved setup: source paths, questions, workflow choices, and defaults
+  bristol-office-analysis/    # portable context agents read
+    AGENTS.md                 # agent-facing entry point
+    raw/                      # same source files copied here
+      report.md
+      notes.md
+      exports/
+    home.md                   # overview and routes for agents
+    summaries/                # one note per source file
+    knowledge/                # linked notes built from the files
+  workflows/                  # editable file-processing workflows
 ```
 
-The project root is the control plane. Your agent starts from `interf/<work>/` when the source files are not enough.
-
 ## What a Run Looks Like
 
-Same files, same questions. What changes is whether the context was prepared first.
+`interf test` scores source files and portable context on the same questions: small, verifiable facts from the files. Same files, same questions. What changes is whether Interf prepared the full picture first.
 
 A recent public run — one market report, two questions, two agents on the same setup — produced:
 
@@ -39,20 +40,20 @@ A recent public run — one market report, two questions, two agents on the same
 | Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
 <!-- PUBLIC_BENCHMARK_TABLE:END -->
 
-Codex passed on the raw files; Claude Code only passed after Interf prepared the portable context. Both numbers come from `interf test`, which scores the same questions against the source files and the portable context.
+Codex passed on the raw files; Claude Code only passed after Interf prepared the portable context. Both numbers come from that same scoring pass.
 
-That gives you a readiness signal for the work and a fair comparison on the same files.
+That tells you whether preparation helped on this agent work.
 
-The table is a sample, not a leaderboard. Run it on your own files. If you run more than one local agent, the same pass gives you a fair comparison between them on the same files.
+The table is a sample, not a leaderboard. Run `interf test` on your own files. If you run more than one local agent, one scoring pass can include each of them.
 
 ## Design Choices
 
-- `Local-first`: your files, your questions, and your agent stay on your machine. No cloud, no uploads.
-- `File over app`: the portable context is a local folder next to the source files. Inspect it, diff it, version it.
-- `Check before build`: run `interf test --target raw` first — sometimes the source files already pass on your questions.
-- `Scored on your own questions`: every build is checked against questions you wrote from the files. If the portable context does not help, `interf test` tells you.
+- `Per-work`: every portable context is prepared for one specific job agents need to do, not a generic index over your files.
+- `Deterministic`: Interf runs each stage, an ordered phase of the file-processing workflow, and shows stage-by-stage proof of work: which files were processed, what each stage produced, and whether required outputs exist. Agents do not have to rebuild the full picture while they work.
+- `Local-first and private`: your files, your questions, and your agent runs stay on your machine. No cloud, no uploads, no telemetry.
 - `Bring your own AI`: use Claude Code, Codex, or another local agent.
-- `Explicit`: no hidden store, no hidden index. The portable context is plain files on disk.
+- `File over app`: the portable context is a local folder next to the source files — no hidden store, no hidden index. Inspect it, diff it, version it.
+- `Scored on your own questions`: every build is checked against questions you wrote from the files. If the portable context does not help, `interf test` tells you.
 
 ## Install
 
@@ -66,79 +67,83 @@ Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run
 ## Quick Start
 
 1. Run `interf` in the project root.
-2. Pick the source folder for one piece of agent work.
+2. Pick the source folder for the job agents need to do.
 3. Describe what the agent should do with those files.
-4. Review the suggested questions.
-5. Run `interf test --target raw` to score the source files.
+4. Review the suggested questions Interf will use to compare source files and portable context.
+5. Choose the file-processing workflow, or create one by describing the source data, outputs, and proof you need.
 6. Run `interf compile` to build portable context.
-7. Run `interf test` again to compare source files and portable context on the same questions.
+7. Run `interf test` to compare source files and portable context on the same questions.
 8. If the portable context does better, point your agent at `interf/<work>/`.
 
-`interf init` copies the built-in compilation workflow to `interf/workflows/interf-default/`. That folder is yours — inspect it, edit it, or fork it into a new compilation workflow with `interf create workflow`.
+If you want a baseline before building, run `interf test --target raw`. It is optional proof, not the main path.
+
+`interf init` saves setup in `interf/interf.json` and copies the built-in file-processing workflow to `interf/workflows/interf-default/`. That workflow package is yours — inspect it, edit it, or fork it with `interf create workflow`.
 
 ## Portable Context
 
-`interf/<work>/` is the local folder Interf Compiler builds from your files — a context layer your agents navigate, not a replacement for your files. For the built-in `interf-default`, it includes:
+`interf/<work>/` is the local folder Interf writes from your files. It gives agents evidence, structure, and cross-file connections for navigating the files. It is not a replacement for your files. For the built-in `interf-default`, it includes:
 
 ```text
 interf/bristol-office-analysis/
-  AGENTS.md       # how to use this folder
+  AGENTS.md       # agent-facing entry point and retrieval rules
   CLAUDE.md       # same guidance for Claude Code
-  raw/            # snapshot of the source files for this work
-  home.md         # top-level map for the work
-  summaries/      # per-file summaries
+  raw/            # same source files copied here
+    report.md
+    notes.md
+    exports/
+  home.md         # overview and routes for agents
+  summaries/      # one note per source file
   knowledge/      # linked notes built from the files
 ```
 
 The source files stay the source of truth. Interf builds next to them; it does not replace them.
 
-The portable context is a folder you can inspect, diff, version, or hand to a different agent. The portable context carries its own `raw/` snapshot, so the evidence the agent works from stays attached to the result.
+`AGENTS.md` tells agents how to use the portable context: start from the prepared outputs, follow the prepared routes, and verify against `raw/` when exact source evidence matters.
+
+Interf also records stage-by-stage proof of work: which files were processed, what each stage produced, and whether required outputs were created.
+
+The portable context is self-contained — it carries its own `raw/` snapshot, so the evidence the agent works from stays attached to the result. Hand it to a different agent and the folder stands on its own.
 
 ## Workflow Packages
 
-A compilation workflow is how you tell Interf Compiler to organize and structure your files so your agents can reliably work from them. `interf init` copies the built-in `interf-default` into your project at `interf/workflows/interf-default/` — it is a real folder you can inspect and edit. Fork it with `interf create workflow` when you need a different method, a different output, or both.
+A workflow package tells Interf how to process your files for the job agents need to do. When you create one, describe three things: what data is in the folder, what the portable context should contain, and what evidence should show your data is ready. The built-in `interf-default` lives at `interf/workflows/interf-default/`. Fork it with `interf create workflow` when you need a different method, a different output, or both.
 
 ```text
 interf/workflows/interf-default/
-  workflow.json         # method: how to process and organize the files
-  workflow.schema.json  # output contract: what files and folders the output must contain
-  README.md             # what this compilation workflow is for, for humans and agents
+  workflow.json         # method: source data, stages, and processing rules
+  workflow.schema.json  # output contract: required portable-context files and folders
+  README.md             # what this workflow package is for, for humans and agents
   compile/
     stages/
-      summarize/        # stage instructions the compiler runs with your local agent
+      summarize/        # stage instructions Interf runs during compile
       structure/
       shape/
   use/
-    query/              # how your agent reads the portable context
-  improve/              # how Interf revises this compilation workflow if questions still fail
+    query/              # how agents read the portable context
+  improve/              # how Interf revises this workflow package if questions still fail
 ```
 
-- `workflow.json` describes the method: expected inputs, stages, and how the files should be processed.
-- `workflow.schema.json` describes the output contract: what files and folders the output must contain. Technically, this is the `context interface`, declared in `workflow.schema.json` and enforced by the compiler.
-- `compile/stages/<stage>/` is where you author one folder per stage — a small, specific phase like `summarize` or `structure`. You write the instructions; the compiler runs them with your local agent.
-- `use/query/` holds the instructions your agent follows when it reads the portable context for live work.
-- `improve/` holds the instructions Interf follows when the first build misses and the compilation workflow itself needs editing.
+- `workflow.json` describes the method: source data, stages, and how the files should be processed.
+- `workflow.schema.json` describes the output contract: what the portable context must contain. Technically, this is the `context interface`, declared in `workflow.schema.json` and enforced when you run `interf compile`.
+- `compile/stages/<stage>/` is where you author one folder per stage — a small, specific phase like `summarize` or `structure`. You write the instructions; Interf runs them during compile.
+- `use/query/` holds the instructions agents follow when they read the portable context for live work.
+- `improve/` holds the instructions Interf follows when the first build misses and the workflow package itself needs editing.
 
-A workflow package bundles a compilation workflow. Interf Compiler runs it on your files. Your local agent runs each stage. The result is a local folder your agents can read.
+A workflow package bundles the method Interf runs on your files. It defines the stages, output contract, proof requirements, and improvement instructions. The result is portable context your agents can read.
 
-## Self-Improving Workflows
+## Workflow Improvement
 
-When the first build still misses questions, Interf edits the workflow package itself and compiles again. Same files, same questions, different preparation.
+When the first portable-context build still misses questions, Interf edits the workflow package itself and compiles again. Same files, same questions, different preparation.
 
-Interf saves every scored run under `interf/tests/<work>/`. You can inspect what changed and why a later build did better.
+Interf saves every scored run under `interf/<work>/.interf/tests/`. You can inspect what changed and why a later build did better.
 
 ## How the Pieces Fit
 
-- `interf.json` is the project control file. It names the work, points at the source files, saves the questions, and selects the compilation workflow.
-- A workflow package bundles a compilation workflow.
-- `workflow.json` defines the method.
-- `workflow.schema.json` defines the output contract, or context interface, the compiler must build.
-- `Interf Compiler` is the local runtime. It runs the compilation workflow, your agent runs each stage, and the portable context lands next to the source files.
-- The portable context is the local folder built for your agents. Technically, that folder is the compiled context.
+`interf/interf.json` names the agent work and selects the workflow package. Interf runs it and writes the portable context as a local folder next to your source files.
 
-## interf.json
+## interf/interf.json
 
-`interf.json` is the main config file in the project root. Each entry describes one piece of agent work: the source path, the saved questions, the compilation workflow that prepares the context, and optional defaults.
+`interf/interf.json` is the main config file for the project. It lives under `interf/` with workflow packages and portable contexts, so the project root stays clean. Each entry describes one agent work setup: the source path, the saved questions, the workflow package that prepares the portable context, and optional defaults.
 
 ```text
 {
@@ -156,11 +161,11 @@ Interf saves every scored run under `interf/tests/<work>/`. You can inspect what
 }
 ```
 
-The `workflow` field is the key choice per work. It points to a folder id under `interf/workflows/`. Set it to `interf-default` (the built-in default, copied locally on init) or to a compilation workflow you have authored. A different compilation workflow is a different method and a different output. Same files, different portable context.
+The `workflow` field selects the workflow package for that job. It points to a folder id under `interf/workflows/`. Set it to `interf-default` (the built-in default) or to a workflow package you have authored. A different workflow package is a different method and a different output. Same files, different portable context.
 
 ## Questions
 
-In the flow, they look like plain questions. In `interf.json`, they live under `checks[]`.
+In the setup flow, they look like plain questions. In `interf/interf.json`, they live under `checks[]`.
 
 They should be small, verifiable facts you already know from the files:
 
@@ -198,24 +203,24 @@ A maintained public test example in this repo stores them like this:
 
 ## What Interf Is Not
 
-- Not a second brain or memory product. One local folder per piece of agent work; nothing global.
+- Not a second brain or memory product. One local folder per agent job; nothing global.
 - Not a vector store or RAG server. The portable context is plain files.
-- Not a hosted context layer. Interf runs locally and `interf/` is yours.
-- Not an agent harness. Interf prepares the folder; your existing agent reads it.
-- Not a public leaderboard. Every score comes from your files, your questions, and your agent.
+- Not a hosted data platform. Interf runs locally and `interf/` is yours.
+- Not an agent harness. Interf prepares the data; your existing agent reads the portable context.
+- Not a public leaderboard. Every score comes from your files, your questions, and your agent runs.
 
 ## Useful Commands
 
 - `interf` or `interf init` — open the wizard and save the first setup
-- `interf compile` — build portable context for your agents
+- `interf compile` — build portable context agents can use
 - `interf test` — compare source files and portable context on the same questions
 - `interf create workflow` — draft a reusable workflow package
 - `interf doctor --live` — verify the local executor
 
 ## Docs
 
-- [src/packages/README.md](./src/packages/README.md) — system map
-- [src/packages/compiler/PACKAGE.md](./src/packages/compiler/PACKAGE.md) — compiler primitives and runtime contract
+- [src/packages/README.md](./src/packages/README.md) — package boundaries
+- [src/packages/compiler/PACKAGE.md](./src/packages/compiler/PACKAGE.md) — local engine primitives and runtime contract
 - [src/packages/workflow-package/PACKAGE.md](./src/packages/workflow-package/PACKAGE.md) — workflow package model
 - [src/packages/workflow-authoring/PACKAGE.md](./src/packages/workflow-authoring/PACKAGE.md) — workflow authoring and workflow improvement
 

package/builtin-workflows/interf/README.md

@@ -1,10 +1,10 @@
 # Interf (Built-in Workflow)
 
-Interf's built-in workflow: summarize source-grounded evidence, structure the cross-file layer, then shape the final context folder around its task focus and checks.
+Interf's built-in workflow: summarize source-grounded evidence, structure the cross-file layer, then shape the final portable context around its task focus and checks.
 
 ## Purpose
 
-- General compiled context workflow for agent use
+- General portable-context workflow for agent use
 - Compile mixed raw files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents answering the questions this task depends on.
 
 ## Zones
@@ -21,11 +21,11 @@ Interf's built-in workflow: summarize source-grounded evidence, structure the cr
 
 - `summarize` — Turn source files into per-file summaries. (compiled-file-evidence; reads: raw, runtime; writes: summaries)
 - `structure` — Build the cross-file knowledge structure from the summaries. (compiled-knowledge-structure; reads: summaries, runtime; writes: knowledge-entities, knowledge-claims, knowledge-indexes)
-- `shape` — Shape the final context folder around the saved task focus and checks. (compiled-query-shape; reads: raw, summaries, knowledge-entities, knowledge-claims, knowledge-indexes, runtime; writes: knowledge-indexes, home)
+- `shape` — Shape the final portable context around the saved task focus and checks. (compiled-query-shape; reads: raw, summaries, knowledge-entities, knowledge-claims, knowledge-indexes, runtime; writes: knowledge-indexes, home)
 
 ## Why `home.md` exists here
 
-This built-in workflow creates `home.md` as the main agent entrypoint for the context folder.
+This built-in workflow creates `home.md` as the main agent entrypoint for the portable context.
 That is behavior of the `interf` workflow, not a compiler-wide rule.
 
 This package is the built-in seed for `interf`.

package/builtin-workflows/interf/compile/stages/shape/SKILL.md

@@ -1,6 +1,6 @@
 # Shape
 
-Shape the final context folder around the saved task focus and checks.
+Shape the final portable context around the saved task focus and checks.
 
 Contract type: `compiled-query-shape`
 
@@ -18,12 +18,12 @@ Contract type: `compiled-query-shape`
 - If a mark touches or nearly touches a labeled gridline, anchor the answer at that gridline or the immediately adjacent half-band.
 - Do not widen a chart-derived range across multiple visible bands unless the chart genuinely supports that uncertainty.
 - When you settle on a bounded chart read, keep that same band consistent across `home.md`, focused indexes, and claim/entity notes for that metric and year.
-- Do not copy expected answers into the context folder.
+- Do not copy expected answers into the portable context.
 
 ## Notes
 
-- Use the saved task focus and checks to bias the final context folder toward the job it should be especially good at.
-- Do not copy expected answers into the final context folder just because the checks imply them.
+- Use the saved task focus and checks to bias the final portable context toward the job it should be especially good at.
+- Do not copy expected answers into the final portable context just because the checks imply them.
 - Prefer the saved summary evidence and structured notes when they already preserve the bounded chart/table reads plus provenance you need.
 - Reopen `raw/` during shaping only when the compiled layer is missing the needed value, the metric family is ambiguous, or the earlier bounded read is clearly inconsistent.
 - If a saved truth check depends on chart-derived or table-derived values, carry the final bounded reads forward into focused notes with provenance instead of repeatedly recomputing them from raw.

package/builtin-workflows/interf/improve/SKILL.md

@@ -8,7 +8,7 @@ The improver edits this local package directly.
 Default loop:
 1. Read the loop context first.
 2. Review preserved stage shells, runtime logs, and saved test runs from failed attempts.
-3. Edit only the local workflow package for this context folder to create a better workflow variation for this task.
+3. Edit only the local workflow package for this compiled context to create a better workflow variation for this task.
 4. Keep `workflow.json`, `workflow.schema.json`, and any changed stage docs aligned.
 
 Guardrails:

package/builtin-workflows/interf/use/query/SKILL.md

@@ -25,4 +25,4 @@ Answering rule:
 - if multiple compiled notes mention the same chart read, keep the answer consistent with the most focused compiled note rather than synthesizing a new midpoint or shifted band
 - when the compiled layer is insufficient, verify in `raw/` and then answer
 
-You can edit this file to bias manual question-answering behavior for this context folder.
+You can edit this file to bias manual question-answering behavior for this portable context.

package/builtin-workflows/interf/workflow.json

@@ -10,7 +10,7 @@
     "task_hint": "Compile mixed raw files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents answering the questions this task depends on."
   },
   "label": "Interf (Built-in)",
-  "hint": "Interf's built-in workflow: summarize source-grounded evidence, structure the cross-file layer, then shape the final context folder around its task focus and checks.",
+  "hint": "Interf's built-in workflow: summarize source-grounded evidence, structure the cross-file layer, then shape the final portable context around its task focus and checks.",
   "stages": [
     {
       "id": "summarize",
@@ -82,7 +82,7 @@
     {
       "id": "shape",
       "label": "Shape",
-      "description": "Shape the final context folder around the saved task focus and checks.",
+      "description": "Shape the final portable context around the saved task focus and checks.",
       "contract_type": "compiled-query-shape",
       "skill_dir": "shape",
       "reads": [
@@ -135,8 +135,8 @@
       "For summary references, prefer explicit links like `[[summaries/<file-stem>]]` or plain code paths. For knowledge notes, prefer the final filename stem under `knowledge/`."
     ],
     "shape": [
-      "Use the saved task focus and checks to bias the final context folder toward the job it should be especially good at.",
-      "Do not copy expected answers into the final context folder just because the checks imply them.",
+      "Use the saved task focus and checks to bias the final portable context toward the job it should be especially good at.",
+      "Do not copy expected answers into the final portable context just because the checks imply them.",
       "If a saved truth check depends on chart-derived or table-derived values, verify the needed evidence in `raw/` while shaping and write focused notes that preserve bounded values plus provenance.",
       "Prefer better routing, prioritization, and focused navigation over speculative synthesis.",
       "Any wikilinks you add to `home.md` or indexes must resolve to real compiled note basenames or explicit relative paths."

package/builtin-workflows/interf/workflow.schema.json

@@ -67,7 +67,7 @@
       "owned_by": [
         "shape"
       ],
-      "description": "Primary entrypoint note for agents using the context folder."
+      "description": "Primary entrypoint note for agents using the portable context."
     },
     {
       "id": "runtime",

package/dist/cli/commands/compile-controller.js

@@ -219,10 +219,10 @@ function printPostCompileNextStep(options) {
         return;
     }
     if (options.testedDuringCompile) {
-        console.log(chalk.dim("  Next: inspect the portable context your agents will use, or run `interf test` if you also want a source-files-versus-portable-context comparison."));
+        console.log(chalk.dim("  Next: inspect the portable context agents will use, or run `interf test` if you also want a source-files-versus-portable-context comparison."));
         return;
     }
-    console.log(chalk.dim("  Next: run `interf test` to compare the source files and the portable context your agents would use."));
+    console.log(chalk.dim("  Next: run `interf test` to compare source files and portable context."));
 }
 function formatVariationQuestionSummary(summary) {
     return `${summary.passed_questions}/${summary.total_questions}`;
@@ -260,7 +260,7 @@ export async function runConfiguredCompiledCompile(options) {
     else if (loopEnabled) {
         if (maxAttempts > 1) {
             console.log(chalk.dim(`  Retry mode: up to ${maxAttempts} compile attempts.`));
-            console.log(chalk.dim("  Interf will rerun the same workflow variation, check the portable context for your agents, and stop early if it passes."));
+            console.log(chalk.dim("  Interf will rerun the same workflow variation, check the portable context agents can use, and stop early if it passes."));
         }
         else {
             console.log(chalk.dim("  Compile mode: 1 attempt per workflow variation."));
@@ -421,10 +421,10 @@ export async function runConfiguredCompiledCompile(options) {
         printWorkflowVariationSummary(previousVariations);
         printCompiledLocalWorkflowOwnership(options.compiledPath, bestVariation);
         if (maxLoops != null) {
-            console.log(chalk.red(`  Context folder did not pass after ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"} per variation and ${maxLoops} workflow-improvement loop${maxLoops === 1 ? "" : "s"}.`));
+            console.log(chalk.red(`  Portable context did not pass after ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"} per variation and ${maxLoops} workflow-improvement loop${maxLoops === 1 ? "" : "s"}.`));
         }
         else {
-            console.log(chalk.red(`  Context folder did not pass within ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"}.`));
+            console.log(chalk.red(`  Portable context did not pass within ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"}.`));
         }
         if (bestOutcome) {
             console.log(chalk.dim(`  Best attempt test pass rate: ${questionPassRate(bestOutcome)}%.`));

package/dist/cli/commands/compile.js

@@ -11,7 +11,7 @@ import { runConfiguredCompiledCompile } from "./compile-controller.js";
 export { runConfiguredCompiledCompile } from "./compile-controller.js";
 export const compileCommand = {
     command: "compile",
-    describe: "Build portable context for your agents and optionally run retry or self-improving compile loops",
+    describe: "Build portable context agents can use and optionally run retry or self-improving compile loops",
     builder: (yargs) => addExecutionProfileOptions(yargs).option("max-attempts", {
         type: "number",
         describe: "Retry compile and test the same workflow until the dataset passes or reaches this total attempt limit",

package/dist/cli/commands/create-workflow-wizard.d.ts

@@ -48,6 +48,12 @@ export declare function chooseCompiledWorkflow(sourcePath: string, options?: {
     currentWorkflowId?: string;
     message?: string;
 }): Promise<string | symbol>;
+export declare function chooseOrCreateCompiledWorkflowForDataset(sourcePath: string, datasetConfig: SourceDatasetConfig, options?: {
+    currentWorkflowId?: string;
+    executionProfile?: WorkflowExecutionProfile;
+    resolveExecutor?: typeof resolveOrConfigureLocalExecutor;
+    runDraft?: typeof runWorkflowAuthoringDraft;
+}, prompts?: WorkflowWizardPrompts): Promise<string | symbol | null>;
 export declare function createWorkflowWizard(options?: {
     intro?: boolean;
     sourcePath?: string;

package/dist/cli/commands/create-workflow-wizard.js

@@ -4,7 +4,7 @@ import { resolve } from "node:path";
 import { listCompiledWorkflowChoices, getCompiledWorkflow, } from "../../packages/workflow-package/workflow-definitions.js";
 import { createLocalWorkflowPackageFromTemplate } from "../../packages/workflow-package/interf-workflow-package.js";
 import { rmSync } from "node:fs";
-import { isWorkflowId, loadWorkflowDefinitionFromDir, } from "../../packages/workflow-package/local-workflows.js";
+import { isWorkflowId, loadWorkflowDefinitionFromDir, seedLocalDefaultWorkflow, } from "../../packages/workflow-package/local-workflows.js";
 import { resolveOrConfigureLocalExecutor } from "./executor-flow.js";
 import { runWorkflowAuthoringDraft } from "../../packages/workflow-authoring/workflow-authoring.js";
 import { listSourceDatasetConfigs, loadSourceFolderConfig, resolveSourceDatasetPath, } from "../../packages/project-model/source-config.js";
@@ -111,6 +111,58 @@ export async function chooseCompiledWorkflow(sourcePath, options = {}) {
         options: orderedOptions,
     });
 }
+export async function chooseOrCreateCompiledWorkflowForDataset(sourcePath, datasetConfig, options = {}, prompts = clackWorkflowPrompts) {
+    seedLocalDefaultWorkflow({ sourcePath });
+    const currentWorkflowId = options.currentWorkflowId ?? datasetConfig.workflow ?? "interf-default";
+    const workflowOptions = buildCompiledWorkflowOptions(sourcePath)
+        .filter((workflow) => workflow.value !== "interf");
+    const currentWorkflow = workflowOptions.find((workflow) => workflow.value === currentWorkflowId) ??
+        workflowOptions.find((workflow) => workflow.value === "interf-default") ??
+        workflowOptions[0];
+    const selected = await prompts.select({
+        message: "Choose the file-processing workflow",
+        options: [
+            ...(currentWorkflow
+                ? [{
+                        value: "__current__",
+                        label: `Use ${currentWorkflow.label} (Recommended)`,
+                        hint: currentWorkflow.hint,
+                    }]
+                : []),
+            {
+                value: "__create__",
+                label: "Create a workflow for this setup",
+                hint: "Draft a file-processing workflow from this source folder, work description, and questions",
+            },
+            ...workflowOptions
+                .filter((workflow) => workflow.value !== currentWorkflow?.value)
+                .map((workflow) => ({
+                ...workflow,
+                label: `Use ${workflow.label}`,
+            })),
+        ],
+    });
+    if (prompts.isCancel(selected))
+        return selected;
+    if (selected === "__current__") {
+        return currentWorkflow?.value ?? currentWorkflowId;
+    }
+    if (selected === "__create__") {
+        const workflowId = await createWorkflowWizard({
+            intro: false,
+            sourcePath,
+            executionProfile: options.executionProfile,
+            resolveExecutor: options.resolveExecutor,
+            runDraft: options.runDraft,
+            datasetContext: {
+                config: datasetConfig,
+                datasetPath: resolveSourceDatasetPath(sourcePath, datasetConfig),
+            },
+        }, prompts);
+        return workflowId;
+    }
+    return String(selected);
+}
 export async function createWorkflowWizard(options = {}, prompts = clackWorkflowPrompts) {
     if (options.intro !== false) {
         prompts.intro(chalk.bold("Create a workflow"));
@@ -150,7 +202,7 @@ export async function createCompiledWorkflowWizard(sourcePath, prompts = clackWo
         return creationMode;
     const rawName = await prompts.text({
         message: "New workflow name?",
-        placeholder: "founder-research",
+        placeholder: "customer-research",
         validate: (value) => {
             if (value.trim().length === 0)
                 return "Name is required";
@@ -215,8 +267,8 @@ export async function createCompiledWorkflowWizard(sourcePath, prompts = clackWo
             matchedDataset = matchedDataset ?? findMatchingDatasetConfig(sourcePath, datasetPath);
         }
         const taskPrompt = await prompts.text({
-            message: "How do you want to organize your files?",
-            placeholder: "Research interview transcripts. Agent produces per-interview summaries and a themes list with supporting quotes. Flow: summarize each, group by theme, collect evidence across interviews.",
+            message: "What should this file-processing workflow produce and prove?",
+            placeholder: "Data: research interviews. Output: per-file summaries, themes, entities, claims, and source links. Proof: every file processed, evidence linked to sources, required outputs created.",
             validate: (value) => (value.trim().length === 0 ? "A description is required" : undefined),
         });
         if (prompts.isCancel(taskPrompt))
@@ -266,7 +318,7 @@ export async function createCompiledWorkflowWizard(sourcePath, prompts = clackWo
             const confirmChoice = await prompts.select({
                 message: "Save this workflow?",
                 options: [
-                    { value: "save", label: "Save", hint: "Keep the draft as your new compilation workflow" },
+                    { value: "save", label: "Save", hint: "Keep the draft as your new workflow package" },
                     { value: "cancel", label: "Discard", hint: "Remove the draft folder and exit without saving" },
                 ],
             });

package/dist/cli/commands/create.js

@@ -1,9 +1,9 @@
 import chalk from "chalk";
 import * as p from "@clack/prompts";
-import { detectInterf, resolveSourceControlPath, } from "../../packages/project-model/interf.js";
+import { detectInterf, ensurePortableContextScaffold, resolveSourceControlPath, } from "../../packages/project-model/interf.js";
 import { addExecutionProfileOptions, executionProfileFromArgv, } from "../../packages/agents/lib/execution-profile.js";
-import { listSourceDatasetConfigs, loadSourceFolderConfig, syncCompiledInterfConfigFromSourceDatasetConfig, upsertSourceDatasetConfig, } from "../../packages/project-model/source-config.js";
-import { createWorkflowWizard, } from "./create-workflow-wizard.js";
+import { SOURCE_FOLDER_CONFIG_PATH, listSourceDatasetConfigs, loadSourceFolderConfig, syncCompiledInterfConfigFromSourceDatasetConfig, upsertSourceDatasetConfig, } from "../../packages/project-model/source-config.js";
+import { chooseOrCreateCompiledWorkflowForDataset, createWorkflowWizard, } from "./create-workflow-wizard.js";
 import { findBuiltCompiledPath, } from "./compiled-flow.js";
 import { DEFAULT_COMPILED_NAME, promptSingleCompiledConfig, } from "./source-config-wizard.js";
 function normalizeCreateTarget(value) {
@@ -81,6 +81,9 @@ async function maybeAssignWorkflowToDataset(sourcePath, workflowId) {
     if (builtCompiledPath) {
         syncCompiledInterfConfigFromSourceDatasetConfig(builtCompiledPath, nextConfig);
     }
+    else {
+        ensurePortableContextScaffold(sourcePath, nextConfig.name, nextConfig.workflow ?? "interf-default");
+    }
     p.log.info(`Assigned workflow "${workflowId}" to dataset "${targetDataset.name}".`);
     if (builtCompiledPath) {
         p.log.info("The active local workflow copy for that portable context lives under `.interf/workflow/`.");
@@ -137,9 +140,9 @@ export async function createCompiledWizard(options = {}) {
     }
     const savedDatasets = listSourceDatasetConfigs(loadSourceFolderConfig(cwd));
     if (savedDatasets.length > 0) {
-        p.log.info(`This project already has ${savedDatasets.length} saved setup${savedDatasets.length === 1 ? "" : "s"} in interf.json. Add another only when you need a separate folder, focus, or question set.`);
+        p.log.info(`This project already has ${savedDatasets.length} saved setup${savedDatasets.length === 1 ? "" : "s"} in ${SOURCE_FOLDER_CONFIG_PATH}. Add another only when you need a separate folder, focus, or question set.`);
     }
-    p.log.info("Interf works one source-folder setup at a time. Start with the work, the relevant files, and a few questions, then build portable context for your agents when the files alone are not enough.");
+    p.log.info("Interf works one source-folder setup at a time. Start with the work, the relevant files, and a few questions, then build portable context when you need evidence that the data is ready for agents.");
     const existingConfig = loadSourceFolderConfig(cwd);
     const draft = await promptSingleCompiledConfig({
         projectPath: cwd,
@@ -148,17 +151,24 @@ export async function createCompiledWizard(options = {}) {
     });
     if (!draft)
         return;
-    const configToSave = {
-        ...draft,
-        workflow: "interf",
-    };
     const existingNames = new Set(listSourceDatasetConfigs(existingConfig).map((dataset) => dataset.name));
-    if (existingNames.has(configToSave.name)) {
+    if (existingNames.has(draft.name)) {
         process.exitCode = 1;
-        p.log.error(`Setup "${configToSave.name}" already exists. Use \`interf\` or \`interf init\` to edit it.`);
+        p.log.error(`Setup "${draft.name}" already exists. Use \`interf\` or \`interf init\` to edit it.`);
         return;
     }
+    const workflowChoice = await chooseOrCreateCompiledWorkflowForDataset(cwd, draft, {
+        currentWorkflowId: "interf-default",
+        executionProfile: options.executionProfile,
+    });
+    if (!workflowChoice || p.isCancel(workflowChoice))
+        return;
+    const configToSave = {
+        ...draft,
+        workflow: String(workflowChoice),
+    };
     upsertSourceDatasetConfig(cwd, configToSave);
+    ensurePortableContextScaffold(cwd, configToSave.name, configToSave.workflow);
     p.outro(configToSave.checks.length > 0
         ? "Saved dataset.\nNext:\n  interf test\n  interf compile"
         : "Saved dataset.\nNext:\n  interf or interf init");

package/dist/cli/commands/default.js

@@ -5,7 +5,8 @@ function printStaticLanding() {
     const config = userConfig.loadUserConfig();
     console.log();
     console.log(chalk.bold("  Interf"));
-    console.log(chalk.dim("  Prepare context for your agents from the files you already have, then run `interf test` and use self-improving loops until more questions pass."));
+    console.log(chalk.dim("  Prepare data for agent work."));
+    console.log(chalk.dim("  Run locally, process files, show evidence that your data is ready, and write verifiable outputs as portable context for agents."));
     console.log();
     if (config) {
         console.log(chalk.dim(`  Agent: ${config.agent}`));