@interf/compiler 0.6.5 → 0.6.7

package/README.md

@@ -1,33 +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 accuracy, and build portable context for your agents when the files alone are not enough.
+**Files alone are not automatically ready for agent work.**
 
-Interf Compiler builds portable context in a local folder inside your project.
-Your agents can use it directly. Interf can check it on those same questions.
+Coding agents now run real work from folders of PDFs, exports, notes, and transcripts. Those folders can still be missing the structure that work needs.
 
-Your source files stay the source of truth. Interf builds on them; it does not replace them.
+A chart buried inside a market-report PDF can be obvious to a human analyst and easy for an agent to miss. Interf checks the source files first, then builds portable context when the raw files are not enough.
 
-For the built-in `interf` workflow, a portable context can include:
+`Interf Compiler` is the local, open-source runtime behind that loop. It uses your local agent to organize the files for one piece of work and build portable context next to them. `interf test` scores the source files and the portable context on the same questions.
 
 ```text
-interf/<dataset>/
-  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
+your-folder/
+  market-report/
+    report.pdf
+    notes.md
+    exports/
+  interf.json         # saved setup and questions for this work
+  interf/
+    market-report/    # portable context your agent starts from
+    tests/
+      market-report/  # source-files vs portable-context scores
 ```
 
-That is an example, not a fixed ABI. Different workflows can build different folders. The simple part is that your agent gets one local folder to start from.
-
-This repo includes a small PDF example with questions like:
+## What a run looks 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:
+A recent public run — one PDF market report, two questions, two agents on the same setup — produced:
 
 <!-- PUBLIC_BENCHMARK_TABLE:START -->
 | Agent | Source files | Portable context |
@@ -36,107 +35,78 @@ On those same questions, a recent run in this repo produced:
 | Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
 <!-- PUBLIC_BENCHMARK_TABLE:END -->
 
-That means:
-
-- Codex already passed on the source files.
-- Claude Code needed the portable context to pass.
+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.
 
-Same work. Same questions. Same local setup.
+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.
 
-## How It Works
+## The loop
 
-1. Pick the files for the work.
-2. Tell Interf what you need from them.
-3. Review or edit the questions.
-4. Build the portable context for your agents.
-5. Run `interf test` on the same questions.
+1. Drop the files for one piece of work under a folder.
+2. Run `interf` and describe the work. Interf recommends a few questions you can verify from the files.
+3. `interf test --target raw` scores the source files.
+4. `interf compile` builds portable context next to the files.
+5. `interf test` scores the portable context on the same questions.
+6. Use whichever side did better.
 
-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.
+Step 3 is optional. It is the honest first check: sometimes the files are already enough, and Interf will say so instead of building something you do not need.
 
-## Why It Exists
+## Install
 
-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 builds a local folder for that work and checks whether it helped.
-
-Interf is built around a few simple rules:
-
-- Start from the files you already have.
-- Check source files and portable context on the same questions.
-- Keep the result in a local folder you can inspect, diff, review, and version.
-- Keep source 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 enough, let Interf retry the same workflow or improve the workflow itself.
-
-## What You Get
-
-A small project can stay simple:
-
-```text
-your-project/
-  task-files/
-    report.pdf
-    notes.md
-    exports/
-  interf.json
-  interf/
-    <dataset>/
-    tests/
-      <dataset>/
+```bash
+npm install -g @interf/compiler
+interf            # opens the setup wizard in the current folder
 ```
 
-After Interf runs, point your agents at `interf/<dataset>/` first. Go back to the source files whenever you need to verify something.
-
-## Quick Start
+Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run `interf doctor --live` if the executor is not detected.
 
-Requirements:
+## Core commands
 
-- Node.js 20+
-- a local coding agent such as Claude Code or Codex
+- `interf` or `interf init` — open the wizard for the current folder
+- `interf compile` — build portable context for your agents
+- `interf test` — score source files and portable context on the same questions
+- `interf create workflow` — draft or copy a reusable workflow
+- `interf create dataset` — add another piece of work to this project
+- `interf list` — list the pieces of work in this project
+- `interf status` — show deterministic health
+- `interf doctor` — check the local agent executor
+- `interf verify <check>` — deterministic verification for automation
+- `interf reset <scope>` — reset generated state while keeping source files
 
-Install:
+## Portable context
 
-```bash
-npm install -g @interf/compiler
-```
-
-Then run Interf in a project folder that already contains the files for the work:
+`interf/<work>/` is the folder your agent starts from when the raw files are not enough. For the built-in `interf` workflow, it includes:
 
-```bash
-interf
+```text
+interf/market-report/
+  AGENTS.md       # how to use this folder
+  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
+  knowledge/      # linked notes built from the files
 ```
 
-The first run opens the dataset wizard for that folder. It can:
+Interf builds next to the source files; it does not replace them. The portable context is a sibling folder you can version, inspect line-by-line, or hand to a different agent.
 
-- draft `interf.json`
-- let you choose the source folder for the work
-- ask what work you need help with
-- recommend questions to check accuracy, or let you add them manually
-- run a source-files baseline so you can see what already works
-- build the portable context your agents will use for that work
-- check that portable context on the same questions
+It carries its own `raw/` snapshot for verification. Any CLI that reads a local directory — Claude Code, Codex, your own — can work from it.
 
-If Interf cannot find your local executor setup, run:
+The method that builds the portable context is a workflow. In plain language, it is how Interf summarizes the files, extracts structure, and links notes for agent use.
 
-```bash
-interf doctor --live
-```
+Technically, the workflow is a workflow package; the folder shape it writes is the context interface; the built folder is the compiled context. Run `interf create workflow` if the built-in method is not enough for your work. Most users only touch `interf/<work>/`.
 
 ## Questions
 
-Interf uses simple questions to check whether the portable context is good enough for your agents on this work.
+Interf runs question-and-answer checks.
 
-Good first questions are small and easy to verify from the files:
+In the flow, they feel like plain questions. In `interf.json`, they live under `checks[]` — small facts that define what "good enough" means for this work.
+
+They should be small, verifiable facts you already know 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.
+- one comparison across years, files, or sections
 
-Each saved question includes the expected answer. In `interf.json`, those definitions live under the technical field `checks[]`.
+Interf proposes an initial set from the files and the work description. You confirm, edit, or replace them.
 
 A maintained public test example in this repo stores them like this:
 
@@ -164,92 +134,35 @@ A maintained public test example in this repo stores them like this:
 ```
 <!-- PUBLIC_TEST_CHECKS:END -->
 
-## What `interf test` Proves
-
-`interf test` compares the source files and the portable context your agents would use on the same questions.
-
-That comparison is the proof step:
-
-- same work
-- same questions
-- same local agent setup
-- source files on one side
-- portable context your agents use on the other
-
-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
-
-1. Save a few questions for the work in `interf.json`.
-2. Check the source files first if you want the baseline.
-3. Run `interf compile` to build the portable context your agents can use.
-4. Run `interf test` on the same questions.
-5. If loops are enabled, let Interf retry the same workflow variation or improve the workflow and test again.
-
-The project root stores the source-folder setup and saved questions. Technically, that portable context is the compiled context Interf reuses for repeat runs.
-
-## Workflows
-
-A workflow is the method Interf uses to prepare files for a kind of work.
-
-A context interface is the folder shape that workflow builds for your agent.
-
-Technically, a workflow package defines that context interface: the zones, paths, and stage ownership of the compiled context Interf will build for that work.
-
-Interf ships with a built-in `interf` workflow for the common case. If you need a different method, create one locally:
+## Self-improving loops
 
-```bash
-interf create workflow
-```
-
-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 for your agents with `interf compile` and run `interf test` on the same questions.
-
-## Compile Loops
-
-`max_attempts` is a retry budget for the same workflow variation.
-
-`max_loops` lets Interf improve the workflow itself between retry batches.
+One compile pass is not always enough. If the portable context still fails some questions, Interf can revise the workflow and compile again: same files, same questions, different preparation.
 
-With `max_attempts`, the dataset, questions, and workflow stay fixed.
+Each loop edits the workflow between attempts. Interf keeps every scored run under `interf/tests/<work>/`, so you can diff why one version did better than the next.
 
-With `max_loops`, Interf can edit the workflow, build the next variation, and test it again on the same dataset and questions.
+## Design choices
 
-Interf preserves workflow snapshots, failed stage shells, and test runs from each loop so you can inspect what changed.
+- `Explicit`: portable context is a folder on disk you can inspect, diff, and version.
+- `File over app`: Interf builds next to the source files.
+- `Bring your own AI`: use Claude Code, Codex, or another local agent.
+- `Proof over vibes`: `interf test` scores source files and portable context on the same questions.
+- `Source files stay the source of truth`: Interf builds next to them; it does not replace them.
 
-## Use It With Your Agent
-
-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 I can verify from those files, and add the expected answers for me to confirm under `checks[]`.
-
-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.
-
-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.
-```
+## What Interf is not
 
-## More Docs
+- Not a second brain or memory product. One folder per piece of work; 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.
 
-- [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/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
+## Docs
 
-Maintainers should use [CONTRIBUTING.md](./CONTRIBUTING.md) for test and release gates.
+- [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/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 self-improving loops
 
-## License
+Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-Code is licensed under Apache 2.0. The `Interf` name and branding are reserved; see [TRADEMARKS.md](./TRADEMARKS.md).
+Code: Apache 2.0. Name and branding: see [TRADEMARKS.md](./TRADEMARKS.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interf/compiler",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "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,6 +43,7 @@
   "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",