npm - @interf/compiler - Versions diffs - 0.6.6 → 0.6.7 - Mend

@interf/compiler 0.6.6 → 0.6.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +85 -192
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -3,30 +3,30 @@
 Interf prepares context for your agents.
 Use it to check whether your files are ready for the work you want your agents to do.
-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.
+**Files alone are not automatically ready for agent work.**
-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.
+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.
-For the built-in `interf` workflow, portable context for your agents includes:
+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.
+`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/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
+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 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 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 checks, one recent public comparison 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 |
@@ -35,114 +35,78 @@ On those same checks, one recent public comparison 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.
-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. Pick the files for the work.
-2. Tell Interf what you need from them.
-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.
-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
-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.
+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.
-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.
+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.
-Interf is built around a few simple rules:
+## The loop
-- 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.
+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.
-## Folder Layout
+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.
-If your folder already contains the files for the work, Interf adds a small local structure around them:
+## Install
-```text
-your-folder/
-  market-report/
-    report.pdf
-    notes.md
-    exports/
-  interf.json
-  interf/
-    market-report/
-    tests/
-      market-report/
+```bash
+npm install -g @interf/compiler
+interf            # opens the setup wizard in the current folder
 ```
-`market-report` is just the work name. Interf reuses it under `interf/` and `interf/tests/`.
+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.
-When Interf finishes, point your agents at `interf/market-report/` first. Go back to the source files whenever you need to verify something.
+## Core commands
-## Quick Start
+- `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
-Requirements:
+## Portable context
-- Node.js 20+
-- a local coding agent such as Claude Code or Codex
+`interf/<work>/` is the folder your agent starts from when the raw files are not enough. For the built-in `interf` workflow, it includes:
-Install:
-```bash
-npm install -g @interf/compiler
+```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
 ```
-Then run Interf in a project folder that already contains the files for the work:
+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.
-```bash
-interf
-```
+It carries its own `raw/` snapshot for verification. Any CLI that reads a local directory — Claude Code, Codex, your own — can work from it.
-The first run opens the setup wizard for that folder. It can:
+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.
-- draft `interf.json`
-- let you choose the source folder for the work
-- ask what work you need help with
-- 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
+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>/`.
-If Interf cannot find your local executor setup, run:
+## Questions
-```bash
-interf doctor --live
-```
+Interf runs question-and-answer checks.
-## Checks
+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.
-Interf uses question-and-answer checks.
-They are small questions that tell you whether the work is actually covered.
-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 checks are small and easy to verify from the files:
+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
-In the CLI, you mostly see them as questions. In `interf.json`, they 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:
@@ -170,106 +134,35 @@ A maintained public test example in this repo stores them like this:
 ```
 <!-- PUBLIC_TEST_CHECKS:END -->
-## What `interf test` Measures
-`interf test` compares the source files and the portable context your agents would use on the same questions.
-That makes it a small benchmark for the work at hand:
-- same work
-- same checks
-- same local agent setup
-- source files on one side
-- 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 Compile And Check Loop
-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.
-`interf.json` stores the saved setup and checks. Technically, that portable context is the compiled context Interf reuses for repeat runs.
-## Workflows
-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.
-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.
+## Self-improving loops
-Publicly, you mostly care about the portable context it produces. Technically, that portable context is the compiled context.
+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.
-Interf ships with a built-in `interf` workflow for the common case. If you need a different method, create one locally:
+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.
-```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.
-## Self-Improving Loops
-Interf can do more than one compile pass.
-If the first portable context is still weak, Interf can revise the workflow and compile again.
-Each loop keeps the work and the checks fixed. The thing that changes is the preparation method.
-If self-improving loops are enabled, Interf can:
+## Design choices
-- build the current portable context
-- run the same checks
-- inspect failures and traces
-- revise the workflow
-- build and test the next version
+- `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.
-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, 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 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
+## 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 CHANGED Viewed

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