@interf/compiler 0.7.0 → 0.7.2

package/README.md

@@ -2,16 +2,18 @@
 
 Interf prepares portable context for your agents.
 
-Agents now run real work from folders of PDFs, exports, notes, and transcripts. They don't reliably assemble the full picture from them: missed evidence, links lost across files, or answers that sound confident but are wrong. A chart inside one PDF can be obvious to a human analyst and easy for an agent to miss.
+**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.
+You ask your agent to analyze every file, miss nothing. It skims, guesses, answers anyway — often with confident answers that are wrong.
 
-`Interf Compiler` is the local runtime that runs compilation workflows on your files. Your local agent executes each stage. The compiler builds portable context — a local folder your agent reads. If the first build misses your questions, Interf improves the compilation workflow and builds again.
+The fix is a map your agent navigates — the full picture of your files, organized for this work. You tell Interf how to build it, in plain English — that's a compilation workflow.
+
+`Interf Compiler` is the local runtime that runs it. It enforces every stage and records proof of work — what ran, what was read, what was produced. 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.
 
 ```text
 project-root/
   bristol-office-analysis/
-    report.pdf
+    report.md
     notes.md
     exports/
   interf.json                   # main config: works, source paths, questions, workflow choices, and defaults
@@ -24,11 +26,13 @@ project-root/
       bristol-office-analysis/  # saved source-files vs portable-context comparisons
 ```
 
-The project root is the control plane. Your agent starts from `interf/<work>/` when the source files are not enough.
+Your agent starts from `interf/<work>/` when the source files are not enough.
 
 ## What a Run Looks Like
 
-A recent public run — one PDF market report, two questions, two agents on the same setup — produced:
+Same files, same questions. What changes is whether the portable context was prepared first.
+
+A recent public run — one market report, two questions, two agents on the same setup — produced:
 
 <!-- PUBLIC_BENCHMARK_TABLE:START -->
 | Agent | Source files | Portable context |
@@ -41,15 +45,16 @@ Codex passed on the raw files; Claude Code only passed after Interf prepared the
 
 That gives you a readiness signal for the work and a fair comparison on the same files.
 
-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 it on your own files. If you run more than one local agent, one `interf test` pass scores each of them.
 
 ## Design Choices
 
-- `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.
-- `File over app`: the portable context is a local folder next to the source files. Inspect it, diff it, version it.
+- `Per-work`: every portable context is built for one specific piece of agent work, not a generic index over your files.
+- `Deterministic`: the compilation workflow is your method. Interf Compiler enforces every stage and records proof of work — no runtime discovery, no guessing.
+- `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
 
@@ -75,7 +80,7 @@ Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run
 
 ## 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 Compiler builds from your files — a map your agent navigates, not a replacement for your files. For the built-in `interf-default`, it includes:
 
 ```text
 interf/bristol-office-analysis/
@@ -89,11 +94,11 @@ interf/bristol-office-analysis/
 
 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.
+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 compilation workflow is how you tell Interf Compiler to organize and structure your files so your agents can reliably work from them. 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/
@@ -110,17 +115,15 @@ interf/workflows/interf-default/
   improve/              # how Interf revises this compilation workflow if questions still fail
 ```
 
-Think of it as method -> output shape.
-
 - `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.
 
-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 a compilation workflow. Interf Compiler runs it on your files and enforces each stage. The result is a local folder 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.
 
@@ -128,12 +131,7 @@ Interf saves every scored run under `interf/tests/<work>/`. You can inspect what
 
 ## 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.json` names the work and selects the compilation workflow. `Interf Compiler` runs that workflow and writes the portable context — technically, the compiled context — as a local folder next to your source files.
 
 ## interf.json
 
@@ -155,7 +153,7 @@ 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 is the key choice per work. It points to a folder id under `interf/workflows/`. Set it to `interf-default` (the built-in default) 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.
 
 ## Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interf/compiler",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Local, open-source context compiler for agent work. Build portable context from your files with a compilation workflow you define. Check on your own questions.",
   "type": "module",
   "bin": {