@interf/compiler 0.6.4 → 0.6.6

package/README.md

@@ -1,34 +1,32 @@
 # Interf
 
 Interf prepares context for your agents.
+Use it to check whether your files are ready for the work you want your agents to do.
 
-Start with the files for the work you want to do. Tell Interf what you need, let it suggest a few questions to check later, and build portable context when the files alone are not enough.
-
-It writes the result as a local folder inside your project. Your agents can use that folder directly, and Interf can check it on the same questions to show whether it actually helped.
+Tell Interf what you need from those files. It can compare how your local agents do on the source files. If the files alone are not enough, it builds portable context and keeps improving that context until more questions pass.
 
+Interf Compiler builds that portable context as a local folder next to your files.
 Your source files stay the source of truth. Interf builds on them; it does not replace them.
 
-Interf calls that folder portable context:
+For the built-in `interf` workflow, portable context for your agents includes:
 
 ```text
-interf/<dataset>/
-  AGENTS.md
-  CLAUDE.md
-  raw/
-  <workflow-declared compiled outputs>
-  .interf/
-    interf.json
-    workflow/
-    runtime/
-    tests/
+interf/market-report/
+  AGENTS.md      # how your agent should use this folder
+  CLAUDE.md      # same guidance for Claude Code
+  home.md        # top-level map for the work
+  summaries/     # file-by-file summaries
+  knowledge/     # linked notes built from those files
 ```
 
-For example, this repo tests a PDF market report with questions like:
+That is one example. Different workflows can build different folders. In every case, your agent starts from one local folder.
+
+One public example from a PDF market report uses checks like:
 
 - `What were Bristol's annual take-up values in 2018 and 2016?`
 - `What were Bristol's availability values in 2018 and 2016?`
 
-On those same questions, a recent run in this repo produced:
+On those same checks, one recent public comparison produced:
 
 <!-- PUBLIC_BENCHMARK_TABLE:START -->
 | Agent | Source files | Portable context |
@@ -40,54 +38,59 @@ On those same questions, a recent run in this repo produced:
 That means:
 
 - Codex already passed on the source files.
-- Claude Code failed on the source files.
-- Both passed after Interf built the portable context.
+- Claude Code needed the portable context to pass.
 
-Same work. Same questions. Same local setup.
+That gives you a readiness signal for the work and a fair comparison on the same files.
+
+Same work. Same checks. Same local setup.
 
 ## How It Works
 
-1. Start with the files for the work.
+1. Pick the files for the work.
 2. Tell Interf what you need from them.
-3. Let Interf recommend a few questions to check accuracy later, or edit them yourself.
-4. Build the portable context for that work.
-5. Run `interf test` on the same questions and keep the result only if it helped.
+3. Review or edit the questions.
+4. Run a source-files baseline if you want to check readiness first.
+5. Build the portable context for your agents.
+6. Run `interf test` on the same questions.
 
-Checking the source files first is still important. It shows what already works and which local agent performs best before you spend time improving anything.
+Check the source files first if you want the baseline. If the files already pass, keep them. If the portable context does better, use it.
 
 ## Why It Exists
 
-Local agents can open raw files and still reason badly over them. Reports, decks, transcripts, exports, PDFs, notes, and mixed folders may all be present, but they are often missing the structure a real piece of work needs.
+Raw files are often not enough.
+
+Local agents can open reports, decks, transcripts, exports, PDFs, notes, and mixed folders. They can still miss the structure the work needs.
 
-Interf takes the files for the work, builds a local folder your agents can use, and then checks whether it actually helped.
+Interf checks the source files first. If they are already enough, keep them. If they are not, Interf builds a local context layer next to those files and checks whether it helped.
 
 Interf is built around a few simple rules:
 
-- Start from the files you already have.
-- Check the source files and the portable context on the same questions.
-- Keep the result in a local folder you can inspect, diff, review, and version.
-- Keep raw files as the source of truth.
-- Use the portable context manually from Claude Code, Codex, or another local agent. Automated Interf runs currently support Claude Code and Codex.
-- If the first pass is not good enough, let Interf revise the workflow and try again. Retries keep the same workflow variation; loops change the workflow itself.
+- Explicit: the preparation stays on disk in a local folder you can inspect, diff, review, and version.
+- File over app: the result lives next to the source files.
+- Bring your own AI: use Claude Code, Codex, or another local agent. Automated Interf runs currently support Claude Code and Codex.
+- Proof over vibes: check source files and portable context on the same work.
+- Source files stay the source of truth.
 
-## What You Get
+## Folder Layout
 
-A project with one saved setup stays simple:
+If your folder already contains the files for the work, Interf adds a small local structure around them:
 
 ```text
-your-project/
-  task-files/
+your-folder/
+  market-report/
     report.pdf
     notes.md
     exports/
   interf.json
   interf/
-    <dataset>/
+    market-report/
     tests/
-      <dataset>/
+      market-report/
 ```
 
-After Interf runs, point your agents at the portable context first. Go back to the source files whenever you need to verify something.
+`market-report` is just the work name. Interf reuses it under `interf/` and `interf/tests/`.
+
+When Interf finishes, point your agents at `interf/market-report/` first. Go back to the source files whenever you need to verify something.
 
 ## Quick Start
 
@@ -102,18 +105,21 @@ Install:
 npm install -g @interf/compiler
 ```
 
-Start from a project folder that contains one or more source folders for the work.
+Then run Interf in a project folder that already contains the files for the work:
 
-The first run can:
+```bash
+interf
+```
+
+The first run opens the setup wizard for that folder. It can:
 
 - draft `interf.json`
 - let you choose the source folder for the work
-- default the dataset id from that folder name, then let you change it
 - ask what work you need help with
-- recommend questions to check accuracy later, or let you add them manually
-- run a source-files baseline on those questions so you can see what already works
-- build the portable context for that work
-- let you check the portable context on the same questions
+- recommend questions you can verify from the files, or let you add them manually
+- run a source-files baseline so you can see whether the files are already enough
+- build the portable context your agents will use for that work
+- check that portable context on the same questions
 
 If Interf cannot find your local executor setup, run:
 
@@ -121,22 +127,23 @@ If Interf cannot find your local executor setup, run:
 interf doctor --live
 ```
 
-## Questions
-
-Interf uses simple question-and-answer checks to see whether the portable context is good enough for this work.
-
-Each saved check stores a question and the expected answer. In `interf.json`, those definitions live under the technical field `checks[]`.
+## Checks
 
-They are just question-and-answer pairs you can verify from the files you selected for the work.
+Interf uses question-and-answer checks.
+They are small questions that tell you whether the work is actually covered.
 
-You do not need to write them from scratch before you know the data well. Interf can recommend a starting set from the files and the work description, then you can confirm, edit, or replace them. Their job is simple: check accuracy before you trust the portable context.
+Interf runs the same checks on the source files and on the portable context. That gives you a source-files baseline and a portable-context comparison on the same task.
 
-Good first questions are small and practical:
+Good first checks are small and easy to verify from the files:
 
 - one exact number from a chart, table, or filing
 - one short statement that should be true or false
 - one simple comparison across years, files, or sections
 
+Interf can recommend a starting set from the files and the work description. You can confirm, edit, or replace them.
+
+In the CLI, you mostly see them as questions. In `interf.json`, they live under the technical field `checks[]`.
+
 A maintained public test example in this repo stores them like this:
 
 <!-- PUBLIC_TEST_CHECKS:START -->
@@ -163,37 +170,49 @@ A maintained public test example in this repo stores them like this:
 ```
 <!-- PUBLIC_TEST_CHECKS:END -->
 
-## What `interf test` Proves
+## What `interf test` Measures
 
-`interf test` compares the source files and the portable context on the same questions.
+`interf test` compares the source files and the portable context your agents would use on the same questions.
 
-That comparison is the proof:
+That makes it a small benchmark for the work at hand:
 
 - same work
-- same questions
+- same checks
 - same local agent setup
 - source files on one side
-- portable context on the other
+- portable context your agents use on the other
+
+If you run more than one local agent, it also gives you a fair comparison between them on the same files.
+
+If the portable context does not help, keep the source files.
 
 Use `interf test` on your own files instead of trusting a frozen benchmark snapshot in the docs.
 
 Interf saves the latest comparison plus the underlying source-files and portable-context runs under `interf/tests/` in the same project.
 
-## The Core Loop
+## The Compile And Check Loop
 
-1. Save a few questions for the work in `interf.json`.
-2. Optionally run `interf test` to see how the source files do first.
-3. Run `interf compile` to build the portable context your agent can use.
-4. Run `interf test` again on the same questions.
-5. If loops are enabled, let Interf retry the same workflow variation or edit the workflow and test the new variation.
+1. Save a few checks for the work in `interf.json`.
+2. Run `interf test --target raw` if you want the source-files baseline.
+3. Run `interf compile`.
+4. Run `interf test`.
+5. If self-improving loops are enabled, let Interf revise the workflow and try again on the same work and checks.
 
-The project root stores the source-folder setup and saved questions. Technically, that portable context is the compiled context used for repeat runs.
+`interf.json` stores the saved setup and checks. Technically, that portable context is the compiled context Interf reuses for repeat runs.
 
 ## Workflows
 
-A workflow tells Interf how to prepare and structure the files for a kind of work before your agent uses them.
+A workflow is the preparation method Interf runs on your files.
+
+In plain language, it is the method that organizes and structures those files for agent use.
 
-Technically, a workflow package defines the context interface: the zones, paths, and stage ownership of the compiled context Interf will build for that work.
+It can summarize files, extract structure, and build the local context layer your agent starts from.
+
+Interf runs that method with your local coding agent and builds the result on disk as portable context.
+
+The folder shape it produces for the agent is the context interface. The reusable method itself is the workflow package.
+
+Publicly, you mostly care about the portable context it produces. Technically, that portable context is the compiled context.
 
 Interf ships with a built-in `interf` workflow for the common case. If you need a different method, create one locally:
 
@@ -206,53 +225,46 @@ Workflow creation supports two paths:
 - draft a workflow from the current project with a local agent
 - copy an existing workflow and edit stage guidance directly
 
-After assignment, build the portable context with `interf compile` and run `interf test` on the same questions.
-
-## Compile Loops
-
-`max_attempts` is a retry budget for the same workflow variation.
+After assignment, build the portable context for your agents with `interf compile` and run `interf test` on the same questions.
 
-Retries keep the target fixed:
+## Self-Improving Loops
 
-- same configured dataset
-- same workflow variation
-- same questions
-- same measurement
+Interf can do more than one compile pass.
 
-`max_loops` enables self-improving workflow edits in the normal `interf compile` path.
+If the first portable context is still weak, Interf can revise the workflow and compile again.
 
-In that loop, the thing that changes is the workflow itself.
+Each loop keeps the work and the checks fixed. The thing that changes is the preparation method.
 
-Each loop can:
+If self-improving loops are enabled, Interf can:
 
-- run the current workflow variation on the same configured dataset
-- test it on the same questions
-- inspect failed traces, preserved stage shells, and test artifacts
-- edit the workflow
-- build and test the next workflow variation
+- build the current portable context
+- run the same checks
+- inspect failures and traces
+- revise the workflow
+- build and test the next version
 
-Interf preserves workflow-improvement shells, workflow-before / workflow-after snapshots, failed stage shells, and test runs from each loop so you can inspect exactly what changed.
+Lower-level retry budgets live in `interf.json` and the technical package docs.
 
 ## Use It With Your Agent
 
-If you already work through a local coding agent, it can run this process for you.
+If you already work through a local coding agent, hand it the whole flow:
 
 Paste something like this into your agent:
 
 ```text
 Install `@interf/compiler`, run `interf` in this folder, and use the local agent executor.
 
-If `interf.json` is missing, draft one dataset entry for this work. Ask what I need from the selected files, recommend a few questions to check accuracy from those files, and add the expected answers for me to confirm. Store those checks under `checks[]`.
+If `interf.json` is missing, draft one dataset entry for this work. Ask what I need from the selected files. Recommend a few questions I can verify from those files, and add the expected answers for me to confirm under `checks[]`.
 
-Then run a source-files baseline if helpful, build the portable context for that work, and run `interf test`.
+Run a source-files baseline if useful. Build the portable context for my agents for that work. Then run `interf test` on the same questions.
 
-Tell me whether the portable context passes those questions, and only recommend it if it does.
+Only recommend the portable context if it passes those questions. If you also ran the source-files baseline, tell me whether it did better than the source files.
 ```
 
 ## More Docs
 
 - [src/packages/README.md](./src/packages/README.md) for the short system map
-- [src/packages/compiler/PACKAGE.md](./src/packages/compiler/PACKAGE.md) for compiler primitives and the runtime ABI
+- [src/packages/compiler/PACKAGE.md](./src/packages/compiler/PACKAGE.md) for compiler primitives and the runtime contract
 - [src/packages/workflow-package/PACKAGE.md](./src/packages/workflow-package/PACKAGE.md) for the workflow package model
 - [src/packages/workflow-authoring/PACKAGE.md](./src/packages/workflow-authoring/PACKAGE.md) for workflow authoring and self-improving loops
 

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, or run `interf test` if you also want a source-files-versus-portable-context comparison."));
+        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."));
         return;
     }
-    console.log(chalk.dim("  Next: run `interf test` to compare the source files and the portable context."));
+    console.log(chalk.dim("  Next: run `interf test` to compare the source files and the portable context your agents would use."));
 }
 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, and stop early if it passes."));
+            console.log(chalk.dim("  Interf will rerun the same workflow variation, check the portable context for your agents, and stop early if it passes."));
         }
         else {
             console.log(chalk.dim("  Compile mode: 1 attempt per workflow variation."));

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 and optionally run retry or self-improving compile loops",
+    describe: "Build portable context for your agents 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.js

@@ -139,7 +139,7 @@ export async function createCompiledWizard(options = {}) {
     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("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 want to prepare context your agents can work from.");
+    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.");
     const existingConfig = loadSourceFolderConfig(cwd);
     const draft = await promptSingleCompiledConfig({
         projectPath: cwd,

package/dist/cli/commands/init.js

@@ -46,7 +46,7 @@ function printDatasetSummary(options) {
     p.log.info(describeSavedQuestions(options.dataset));
     p.log.info(options.built ? "Portable context is available." : "Portable context has not been built yet.");
     if (options.latestComparison?.raw && options.latestComparison?.compiled) {
-        p.log.info(`Latest saved comparison: source files ${options.latestComparison.raw.passed_cases}/${options.latestComparison.raw.total_cases}, portable context ${options.latestComparison.compiled.passed_cases}/${options.latestComparison.compiled.total_cases}.`);
+        p.log.info(`Latest saved comparison: source files ${options.latestComparison.raw.passed_cases}/${options.latestComparison.raw.total_cases}, portable context for your agents ${options.latestComparison.compiled.passed_cases}/${options.latestComparison.compiled.total_cases}.`);
     }
     else if (options.latestComparison?.raw) {
         p.log.info(`Latest saved source-files run: ${options.latestComparison.raw.passed_cases}/${options.latestComparison.raw.total_cases}.`);
@@ -70,12 +70,12 @@ async function promptDatasetAction(dataset, built, latestComparison) {
         options.push({
             value: "test",
             label: built
-                ? "Compare source files and portable context (Recommended)"
+                ? "Compare source files and the portable context your agents would use (Recommended)"
                 : hasSavedRawBaseline
                     ? "Rerun the source-files baseline"
                     : "Measure the source-files baseline (Recommended)",
             hint: built
-                ? "See whether the portable context helps on the saved questions"
+                ? "See whether the portable context helps your agents on the saved questions"
                 : hasSavedRawBaseline
                     ? "Refresh the saved source-files baseline on the current questions"
                     : "See whether the source files are already good enough before compiling",
@@ -83,16 +83,16 @@ async function promptDatasetAction(dataset, built, latestComparison) {
     }
     options.push({
         value: "compile",
-        label: built ? "Rebuild portable context" : "Build portable context",
+        label: built ? "Rebuild portable context for your agents" : "Build portable context for your agents",
         hint: built
             ? "Refresh it from the current source files"
             : dataset.checks.length > 0
                 ? latestRawPasses
-                    ? "Optional: build portable context for a side-by-side comparison with the latest saved source-files run"
+                    ? "Optional: build portable context for your agents for a side-by-side comparison with the latest saved source-files run"
                     : hasSavedRawBaseline
-                        ? "Some questions still fail on the source files. Build portable context and compare it on the same questions"
-                        : "Build portable context and compare it on the same questions"
-                : "Build it first, then measure it later",
+                        ? "Some questions still fail on the source files. Build portable context for your agents and compare it on the same questions"
+                        : "Build portable context for your agents and compare it on the same questions"
+                : "Build it for your agents first, then measure it",
     }, {
         value: "dataset",
         label: "Add another setup",
@@ -126,14 +126,14 @@ function printDatasetRecommendation(dataset, built, latestComparison) {
     if (!built) {
         if (latestComparison?.raw) {
             p.log.info(latestComparison.raw.passed_cases === latestComparison.raw.total_cases
-                ? `Latest source-files run: ${latestComparison.raw.passed_cases}/${latestComparison.raw.total_cases}. Rerun the baseline if you want current numbers for a different agent set, or build portable context if you want a side-by-side comparison.`
-                : `Latest source-files run: ${latestComparison.raw.passed_cases}/${latestComparison.raw.total_cases}. Some questions still fail on the source files. Build portable context if you want Interf to prepare context for this work and compare it on the same questions.`);
+                ? `Latest source-files run: ${latestComparison.raw.passed_cases}/${latestComparison.raw.total_cases}. Rerun the baseline if you want current numbers for a different agent set, or build portable context for your agents if you want a side-by-side comparison.`
+                : `Latest source-files run: ${latestComparison.raw.passed_cases}/${latestComparison.raw.total_cases}. Some questions still fail on the source files. Build portable context for your agents if you want Interf to prepare context for this work and compare it on the same questions.`);
             return;
         }
         p.log.info("Recommended first step: measure the source-files baseline before compiling.");
         return;
     }
-    p.log.info("Recommended first step: compare the source-files baseline and the portable context.");
+    p.log.info("Recommended first step: compare the source-files baseline and the portable context your agents would use.");
 }
 async function promptPostBaselineAction(rows) {
     const status = currentRunTargetStatus(rows, "raw");
@@ -154,13 +154,13 @@ async function promptPostBaselineAction(rows) {
             {
                 value: "compile",
                 label: compileRecommended
-                    ? "Build portable context (Recommended)"
-                    : "Build portable context",
+                    ? "Build portable context for your agents (Recommended)"
+                    : "Build portable context for your agents",
                 hint: compileRecommended
                     ? status === "mixed"
-                        ? "Some selected agents still failed on the source files. Build portable context and compare it on the same questions"
-                        : "Build portable context and compare it on the same questions"
-                    : "Build portable context and compare it on the same questions",
+                        ? "Some selected agents still failed on the source files. Build portable context for your agents and compare it on the same questions"
+                        : "Build portable context for your agents and compare it on the same questions"
+                    : "Build portable context for your agents and compare it on the same questions",
             },
             {
                 value: "edit",
@@ -407,7 +407,7 @@ async function runCompiledActionMenu(sourcePath, compiledConfig, options = {}) {
             return;
         }
         if (compileResult.testedDuringCompile) {
-            p.log.info("This compile run already checked the portable context on the saved questions.");
+            p.log.info("This compile run already checked the portable context for your agents on the saved questions.");
             p.log.info("Run `interf test` later if you want a fresh side-by-side comparison summary.");
             return;
         }
@@ -426,14 +426,14 @@ async function runCompiledActionMenu(sourcePath, compiledConfig, options = {}) {
         if (compiledConfig.checks.length === 0)
             return;
         if (compileResult.testedDuringCompile) {
-            p.log.info("This compile run already checked the portable context on the compile agent.");
+            p.log.info("This compile run already checked the portable context for your agents on the compile agent.");
         }
         const runCompiledTest = await p.confirm({
             message: compileResult.testedDuringCompile
                 ? "Run a fresh source-files versus portable-context comparison now?"
                 : builtCompiledPath
-                    ? "Run source files and portable context on the saved questions now?"
-                    : "Compare source files and portable context on the saved questions now?",
+                    ? "Run source files and the portable context your agents would use on the saved questions now?"
+                    : "Compare source files and the portable context your agents would use on the saved questions now?",
             initialValue: true,
         });
         if (p.isCancel(runCompiledTest) || !runCompiledTest)

package/dist/cli/commands/source-config-wizard.js

@@ -370,7 +370,7 @@ async function promptCompiledChecks(options) {
         if (options.initialAbout) {
             p.log.info(`About: ${options.initialAbout}`);
         }
-        p.log.info("Questions are simple question-and-answer pairs Interf uses to check accuracy later, so you can decide whether to trust the portable context.");
+        p.log.info("Questions are simple question-and-answer pairs Interf uses to check accuracy, so you can decide whether to trust the portable context.");
         const mode = await p.select({
             message: "How should Interf create them?",
             options: [
@@ -544,7 +544,7 @@ export async function promptCompileLoopSelection(options) {
         once: {
             value: "once",
             label: "Compile once",
-            hint: "Build portable context once with the selected workflow",
+            hint: "Build portable context for your agents once with the selected workflow",
         },
         "self-improving": {
             value: "self-improving",

package/dist/cli/commands/status.js

@@ -18,7 +18,7 @@ function statusColor(status) {
 }
 export const statusCommand = {
     command: "status",
-    describe: "Show deterministic health for portable context",
+    describe: "Show deterministic health for the portable context your agents use",
     handler: async () => {
         let compiledPath = null;
         const detected = detectInterf(process.cwd());
@@ -34,7 +34,7 @@ export const statusCommand = {
             if (local.length === 0) {
                 process.exitCode = 1;
                 console.log(chalk.red("  No portable contexts found."));
-                console.log(chalk.dim("  Run `interf`, save questions, and compile portable context first."));
+                console.log(chalk.dim("  Run `interf`, save questions, and compile portable context for your agents first."));
                 return;
             }
             if (local.length === 1) {
@@ -75,7 +75,7 @@ export const statusCommand = {
             console.log();
             console.log(chalk.dim(latestComparisonState.stale
                 ? "  Saved test results are stale for the current questions. Run `interf test` again."
-                : "  No saved comparison yet. Run `interf test` to measure source files and the portable context."));
+                : "  No saved comparison yet. Run `interf test` to measure source files and the portable context your agents would use."));
         }
         console.log();
         const metricOrder = [

package/dist/cli/commands/test.js

@@ -9,7 +9,7 @@ import { printAgentTestFailures, printAgentTestMatrix, printSavedTestComparisonS
 import { listRunAgentOptions, promptForTestAgents, resolveNamedLocalExecutor, resolveOrConfigureLocalExecutor, } from "./executor-flow.js";
 export const testCommand = {
     command: "test",
-    describe: "Compare source files and portable context on saved questions",
+    describe: "Compare source files and the portable context your agents would use on saved questions",
     builder: (yargs) => addExecutionProfileOptions(yargs)
         .option("dataset", {
         type: "string",
@@ -17,7 +17,7 @@ export const testCommand = {
     })
         .option("target", {
         choices: ["both", "raw", "compiled"],
-        describe: "Test source files, the portable context, or both. Default: both when portable context exists, otherwise source files.",
+        describe: "Test source files, the portable context your agents would use, or both. Default: both when portable context exists, otherwise source files.",
     })
         .option("keep-sandboxes", {
         type: "boolean",
@@ -49,8 +49,8 @@ async function promptTestMode(hasBuiltCompiled) {
         options: [
             {
                 value: "both",
-                label: "Compare source files and portable context (Recommended)",
-                hint: "Measure whether the portable context helps on the saved questions",
+                label: "Compare source files and the portable context your agents would use (Recommended)",
+                hint: "Measure whether the portable context helps your agents on the saved questions",
             },
             {
                 value: "raw",
@@ -60,7 +60,7 @@ async function promptTestMode(hasBuiltCompiled) {
             {
                 value: "compiled",
                 label: "Portable context only",
-                hint: "Measure the current portable context on the saved questions",
+                hint: "Measure the current portable context for your agents on the saved questions",
             },
         ],
     });
@@ -240,13 +240,13 @@ export async function runTestCommand(argv = {}) {
         return false;
     if (selectedMode === "compiled" && !hasBuiltCompiled) {
         process.exitCode = 1;
-        console.log(chalk.red(`  Setup "${selectedCompiled.name}" does not have portable context yet.`));
+        console.log(chalk.red(`  Setup "${selectedCompiled.name}" does not have portable context for your agents yet.`));
         console.log(chalk.dim("  Run `interf compile` first."));
         return false;
     }
     if (selectedMode === "both" && !hasBuiltCompiled) {
         process.exitCode = 1;
-        console.log(chalk.red(`  Setup "${selectedCompiled.name}" does not have portable context yet, so Interf cannot compare source files and the portable context.`));
+        console.log(chalk.red(`  Setup "${selectedCompiled.name}" does not have portable context for your agents yet, so Interf cannot compare source files and the portable context your agents would use.`));
         console.log(chalk.dim("  Run `interf compile` first, or rerun with `--target raw`."));
         return false;
     }
@@ -268,7 +268,7 @@ export async function runTestCommand(argv = {}) {
     })));
     if ((mode === "compiled" || mode === "both") && rows.some((row) => !row.compiledOutcome)) {
         process.exitCode = 1;
-        console.log(chalk.red(`  Setup "${selectedCompiled.name}" does not have portable context yet.`));
+        console.log(chalk.red(`  Setup "${selectedCompiled.name}" does not have portable context for your agents yet.`));
         console.log(chalk.dim("  Run `interf compile` first."));
         return false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interf/compiler",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Interf prepares context for your agents by checking your files first, building a local folder when needed, and using self-improving loops until more questions pass.",
   "type": "module",
   "bin": {
@@ -43,7 +43,9 @@
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc && chmod 755 dist/bin.js",
     "dev": "tsc --watch",
+    "setup:local-skills": "bash scripts/setup-local-skills.sh",
     "refresh:bootstrap-mirror": "node scripts/docs/sync-bootstrap-mirror.mjs",
+    "docs:sync-public-test-example": "npm run build && node scripts/docs/sync-public-test-example.mjs",
     "test:matrix": "npm run build && node scripts/matrix/run.mjs",
     "test:smoke": "npm run build && node --test test/**/*.test.mjs",
     "test": "npm run test:smoke",