@interf/compiler 0.7.2 → 0.9.1

package/README.md

@@ -1,60 +1,67 @@
 # 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.
 
 **Hallucinations aren't an agent problem. They're a data preparation problem.**
 
-You ask your agent to analyze every file, miss nothing. It skims, guesses, answers anyway — often with confident answers that are wrong.
+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.
 
-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.
+Interf replaces that hidden discovery with a visible Preparation: a Source Folder, a Method for processing it, readiness checks, runs, and the portable context agents use. You choose the Source Folder and Interf Workspace, define what the agent work needs, choose or draft a Method, prepare the files, check readiness, and open the portable context. Interf runs the Method 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
+Source Folder                       Portable context agents read
+
+bristol-office-market/              interf/bristol-office-market/
+  q4-market-report.pdf                AGENTS.md
+  lease-comps.xlsx                    raw/
+  planning-notes.md                     q4-market-report.pdf
+  exports/availability.csv             lease-comps.xlsx
+                                       planning-notes.md
+                                       exports/availability.csv
+                                     home.md
+                                     summaries/
+                                     knowledge/
 ```
 
-Your agent starts from `interf/<work>/` when the source files are not enough.
+## What a Preparation Produces
 
-## What a Run Looks Like
+A Preparation produces portable context plus proof of work. The portable context is the folder agents read. The proof shows which files Interf processed, which Method stages ran, what each stage wrote, and whether required outputs exist.
 
-Same files, same questions. What changes is whether the portable context was prepared first.
+For the built-in `interf-default` Method, a prepare run looks like this:
 
-A recent public run — one market report, two questions, two agents on the same setup — produced:
+```text
+Preparation: bristol-office-market
+Method: interf-default
+
+prepare run
+  read Source Folder
+  summarize -> summaries/
+  structure -> knowledge/
+  shape -> home.md and agent entrypoints
+  record proof -> processed files, stage outputs, required artifacts
+
+output
+  portable context -> interf/bristol-office-market/
+```
 
-<!-- PUBLIC_BENCHMARK_TABLE:START -->
-| Agent | Source files | Portable context |
-| --- | --- | --- |
-| Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
-| Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
-<!-- PUBLIC_BENCHMARK_TABLE:END -->
+The output is not an answer. It is a prepared local folder with routes, summaries, linked notes, source snapshots, and agent instructions. Your runtime agent reads that folder when it does the actual agent work.
 
-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.
+## Design Choices
 
-That gives you a readiness signal for the work and a fair comparison on the same files.
+- `Preparation-scoped`: every Preparation is for one specific job agents need to do, not a generic index over your Source Folder.
+- `Deterministic`: Interf runs each stage, an ordered phase of a Method, 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, readiness checks, and agent runs stay on your machine. No cloud, no uploads, no telemetry.
+- `Bring your own AI`: use Claude Code, Codex, or another local agent.
+- `File over app`: the portable context is a local folder in the Interf Workspace — no hidden store, no hidden index. Inspect it, diff it, version it.
+- `Readiness checks you control`: every build can be checked against gates you wrote from the files. If the portable context is `not ready`, `interf test` shows the readiness evidence behind that status.
 
-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.
+## Why Not Just Ask Your Agent?
 
-## Design Choices
+You can. Interf can use Claude Code, Codex, or another local agent while it builds the portable context.
 
-- `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.
-- `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.
+A one-off preprocessing prompt gives you another agent answer to trust. Interf puts that work inside a Method you can inspect: declared stages, required outputs, stage-by-stage proof of work, and readiness checks that decide whether the portable context is `ready` or `not ready`.
+
+The agent can still do the processing. Interf shows what ran, which files were processed, what evidence was produced, and whether the result is ready for the agent work.
 
 ## Install
 
@@ -67,84 +74,103 @@ 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.
-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.
-6. Run `interf compile` to build portable context.
-7. Run `interf test` again to compare source files and portable context on the same questions.
-8. If the portable context does better, point your agent at `interf/<work>/`.
+1. Run `interf` from the Source Folder you want to prepare, or from a parent folder that contains it.
+2. Choose the Source Folder and Interf Workspace.
+3. Create a Preparation by describing what the agent should do with those files.
+4. Choose or draft the Method: autogenerate one with your agent, use the built-in Method, or create your own.
+5. Run `interf compile` to prepare files and build portable context.
+6. Review or edit the readiness checks Interf will use to decide whether the portable context is `ready` or `not ready`.
+7. Run `interf test` to check readiness.
+8. If agents pass more checks with portable context, point your agent at `interf/<preparation>/`.
 
-`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 preparing, run `interf test --target raw`. It is optional proof, not the main path.
+
+`interf init` sets up the local Interf Workspace, saves `interf/interf.json`, and copies the built-in Method to `interf/methods/interf-default/`. It does not create a Preparation until you choose to add one. The Method is stored as a Method package you can inspect, edit, or fork with `interf create method`.
 
 ## Portable Context
 
-`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:
+`interf/<preparation>/` 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
+interf/bristol-office-market/
+  AGENTS.md       # agent-facing entry point and source-checking 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
+    q4-market-report.pdf
+    lease-comps.xlsx
+    planning-notes.md
+    exports/availability.csv
+  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 source files stay the source of truth. Interf writes portable context in the Interf Workspace; it does not modify the Source Folder.
+
+`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
+## Methods
 
-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.
+A Method 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 Source Folder, what the portable context should contain, and what evidence should show the portable context is `ready`. The built-in `interf-default` Method lives at `interf/methods/interf-default/`. Fork it with `interf create method` 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
+interf/methods/interf-default/
+  workflow.json         # Method: source data, stages, and processing rules
+  workflow.schema.json  # output contract: required portable-context files and folders
+  README.md             # what this Method 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 Method if readiness checks 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. Interf enforces it 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 agent work.
+- `improve/` holds the instructions Interf follows when the first build misses and the Method itself needs editing.
 
-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.
+A Method defines the stages, output contract, proof requirements, and improvement instructions Interf runs on your files. Technically, each Method is stored as a Method package with `workflow.json` and `workflow.schema.json`. The result is portable context your agents can read.
 
-## Workflow Improvement
+## Method 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 prepare run still misses readiness checks, Interf edits the Method itself and compiles again. Same files, same checks, 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 readiness-check run under `interf/<preparation>/.interf/tests/`. You can inspect what changed and why a later prepare run did better.
 
 ## How the Pieces Fit
 
-`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/interf.json` stores the Source Folder binding and saved Preparations: readiness checks, selected Method, and defaults. A prepare run processes the Source Folder and writes portable context under `interf/<preparation>/`. `interf test` checks Source Folder files and portable context against the same readiness checks.
+
+Readiness is one `ready` / `not ready` status, not a separate score. Interf builds it from evidence primitives: stage/Method acceptance criteria, proof records, file coverage, artifact validation, and readiness checks.
+
+`interf web` starts the local Interf service and serves Interf UI. The UI reads local-service resources: Preparations, Methods, runs, stages, proof, artifacts, readiness checks, and whether portable context is `ready` or `not ready`. It renders local compiler state; it does not own compiler, Method, or readiness semantics.
+
+Maintainer package boundaries live in [src/packages/README.md](./src/packages/README.md).
 
-## 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 local Interf Workspace. It lives under `interf/` with Method packages, run state, snapshots, and portable-context outputs. By default, Interf stores that workspace outside the Source Folder so source files stay clean. It prefers the parent folder when the sibling `interf/` path is available and falls back to `~/.interf/<source-folder>` when that path is already occupied. `source_folder.path` records the Source Folder before any Preparation exists. Each `preparations[]` entry describes one Preparation: the source path, the saved readiness checks, the Method that prepares the portable context, and optional defaults.
 
 ```text
 {
-  "datasets": [
+  "source_folder": {
+    "path": "./bristol-office-market"
+  },
+  "preparations": [
     {
-      "name": "bristol-office-analysis",
-      "path": "./bristol-office-analysis",
-      "about": "Read the report and answer the saved questions.",
-      "workflow": "interf-default",
+      "name": "bristol-office-market",
+      "path": "./bristol-office-market",
+      "about": "Answer Bristol office-market questions from the report, comps, notes, and exports.",
+      "method": "interf-default",
       "checks": [
         { "question": "...", "answer": "..." }
       ]
@@ -153,26 +179,41 @@ 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) 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 `method` field selects the Method for that Preparation. It points to a folder id under `interf/methods/`. Set it to `interf-default` (the built-in default) or to a Method you have authored. A different Method is different processing and a different output. Same files, different portable context.
 
-## Questions
+## Readiness Checks
 
-In the flow, they look like plain questions. In `interf.json`, they live under `checks[]`.
+There are two checks in the system, and they answer different questions.
 
-They should be small, verifiable facts you already know from the files:
+Method acceptance criteria check the build: did the Method produce the files, folders, artifacts, and stage outputs it promised? Interf checks those while it compiles.
+
+Readiness checks check the Preparation: is this portable context good enough for the specific agent work? They are the confidence layer on top of the portable context, not the product output.
+
+In the setup flow, readiness checks often look like plain question-and-answer pairs. In `interf/interf.json`, they live under `checks[]`. They help define whether the portable context is `ready` or `not ready`. A check should be a small, verifiable fact or condition 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 comparison across years, files, or sections
 
-Interf proposes an initial set from the files and the work description. You confirm, edit, or replace them.
+Interf proposes an initial set from the files and the description of the job agents need to do. You confirm, edit, or replace them. `interf test` runs those checks through the configured local agent against Source Folder files, portable context, or both. The portable context itself does not answer; the agent answers while using it.
+
+A maintained readiness example in this repo uses one market report, two readiness checks, and two agents:
+
+<!-- PUBLIC_BENCHMARK_TABLE:START -->
+| Agent | Source files | Portable context |
+| --- | --- | --- |
+| Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
+| Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
+<!-- PUBLIC_BENCHMARK_TABLE:END -->
+
+Codex passed from the raw files; Claude Code only passed when working from Interf's portable context. Both numbers come from the same readiness-check pass. That is evidence about whether this Preparation is `ready` for this agent work.
 
 A maintained public test example in this repo stores them like this:
 
 <!-- PUBLIC_TEST_CHECKS:START -->
 ```text
 {
-  "datasets": [
+  "preparations": [
     {
       "name": "cbre-chart-sanity",
       "path": "./task-files",
@@ -195,26 +236,27 @@ 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.
 
 ## Useful Commands
 
-- `interf` or `interf init` — open the wizard and save the first setup
-- `interf compile` — build portable context for your agents
-- `interf test` — compare source files and portable context on the same questions
-- `interf create workflow` — draft a reusable workflow package
+- `interf` or `interf init` — set up the Interf Workspace or manage Preparations
+- `interf web` — start Interf UI and the local API for this Workspace
+- `interf compile` — build portable context agents can use
+- `interf test` — run readiness checks against source files and/or portable context
+- `interf create method` — draft a reusable Method
 - `interf doctor --live` — verify the local executor
 
-## Docs
+## Maintainer 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/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
+- [src/packages/README.md](./src/packages/README.md) - package boundaries
+- [src/cli/README.md](./src/cli/README.md) - CLI orchestration
+- [apps/compiler-ui/README.md](./apps/compiler-ui/README.md) - Interf Compiler UI
+- [apps/compiler-ui/DESIGN.md](./apps/compiler-ui/DESIGN.md) - UI design source of truth
+- [scripts/README.md](./scripts/README.md) - maintainer automation
 
 Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md).
 

package/TRADEMARKS.md

@@ -7,7 +7,7 @@ This repository's code is available under the Apache 2.0 license in [LICENSE](./
 You may:
 
 - describe this project factually as a fork or derivative of Interf
-- state that your project is based on or compatible with Interf
+- state that your project is based on Interf or integrates with Interf
 - reproduce the name where required by the Apache 2.0 license for attribution
 
 You may not:

package/agent-skills/interf-actions/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: interf-actions
+description: Use when an agent needs to operate Interf from natural language: inspect the local Interf Workspace, propose safe CLI commands, run approved Interf commands, or prepare action proposals for Interf Compiler UI.
+---
+
+# Interf Actions
+
+Interf prepares data for agent work. It runs locally, processes source files, shows evidence that the data is ready, and writes portable context: a local folder with verifiable outputs agents can use.
+
+Use the installed CLI as the source of truth. Outside Interf Compiler UI proposal mode, inspect the current command surface when needed:
+
+```sh
+interf --help
+interf list
+interf status
+interf doctor
+```
+
+For command-specific flags, run `interf <command> --help`.
+
+In Interf Compiler UI proposal mode, do not run CLI commands. Use `references/cli.md` instead. It is a generated snapshot of the current Interf CLI help and is checked against the built package in the repo test suite.
+
+## Operating Rules
+
+- Use exact Preparation ids from `interf list` or `interf/interf.json`.
+- Prefer the selected Preparation only when it is explicit or there is one obvious Preparation.
+- Do not invent readiness checks, Method ids, paths, or executor names.
+- If the local service is running, `interf compile` and `interf test` submit visible runs to Interf Compiler UI.
+- Propose the command first and wait for approval before running commands that write files, start runs, create Method packages, build portable context, or run readiness checks.
+- If the request is ambiguous, ask one concise clarification instead of guessing.
+
+## Interf Compiler UI Proposal Mode
+
+When Interf Compiler UI asks for a proposal, do not run CLI commands. Write a single JSON object to the requested output path.
+
+Use these action types:
+
+- `preparation-setup`
+- `compile`
+- `test`
+- `readiness-check-draft`
+- `method-authoring`
+- `clarification`
+
+Use `preparation-setup` when no Preparation is saved yet or when the user asks to initialize/add a source folder. Set `values.path` to a visible source folder path such as `./Reports`, set `preparation` or `values.name` to the Preparation id, and set `values.about` to the agent work the source folder should support. CLI equivalent: `interf init` or `interf create preparation`.
+
+For a readiness-check proposal, set `values.mode` to:
+
+- `raw` for source files only
+- `compiled` for portable context only
+- `both` for source files and portable context
+
+Return this shape:
+
+```json
+{
+  "action_type": "preparation-setup",
+  "preparation": "preparation-id",
+  "method": "method-id if applicable",
+  "values": {
+    "path": "./source-folder",
+    "about": "agent work this source folder should support"
+  },
+  "title": "short approval card title",
+  "summary": "one sentence describing what will run",
+  "assistant_message": "concise explanation for the user",
+  "command_preview": "interf init # source: ./source-folder"
+}
+```
+
+Use `clarification` only when the request cannot be mapped safely to one Interf action.

package/agent-skills/interf-actions/references/cli.md

@@ -0,0 +1,190 @@
+# Interf CLI Reference Snapshot
+
+<!-- Generated from the built CLI help by scripts/docs/sync-agent-skill-cli-reference.mjs. Do not edit by hand. -->
+
+This snapshot is bundled with the `interf-actions` skill. The installed `interf` command remains the source of truth when available.
+
+## interf
+
+```text
+interf
+
+Commands:
+  interf init            Set up Interf or open the Preparation wizard
+  interf compile         Prepare files and write Portable Context agents can use
+  interf test            Run readiness checks against source files and Portable Context
+  interf create [type]   Create a Preparation or reusable Method
+  interf doctor          Check local executor configuration before a real local run
+  interf list            List saved Preparations in this Source Folder
+  interf status          Show deterministic health for the Portable Context agents use
+  interf verify <check>  Run deterministic verification checks
+  interf web             Start Interf UI and the local Interf API
+  interf reset <scope>   Reset generated Portable Context state while keeping source files and the local Method package
+
+Options:
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+```
+
+## interf init
+
+```text
+interf init
+
+Set up Interf or open the Preparation wizard
+
+Options:
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+```
+
+## interf create
+
+```text
+interf create [type]
+
+Create a Preparation or reusable Method
+
+Positionals:
+  type  Type to create (`preparation` or `method`)                                                                                                      [string]
+
+Options:
+  --help        Show help                                                                                                                              [boolean]
+  --version     Show version number                                                                                                                    [boolean]
+  --model       Override the local executor model for this run                                                                                          [string]
+  --profile     Executor-specific profile override for this run                                                                                         [string]
+  --effort      Override the model reasoning effort for this run                                                                                        [string]
+  --timeout-ms  Interrupt the local executor after this much inactivity                                                                                 [number]
+```
+
+## interf compile
+
+```text
+interf compile
+
+Prepare files and write Portable Context agents can use
+
+Options:
+  --help               Show help                                                                                                                       [boolean]
+  --version            Show version number                                                                                                             [boolean]
+  --model              Override the local executor model for this run                                                                                   [string]
+  --profile            Executor-specific profile override for this run                                                                                  [string]
+  --effort             Override the model reasoning effort for this run                                                                                 [string]
+  --timeout-ms         Interrupt the local executor after this much inactivity                                                                          [number]
+  --preparation        Preparation id to compile when this Source Folder has more than one Preparation                                                  [string]
+  --max-attempts       Retry the prepare run and run saved readiness checks with the same Method until the Preparation is ready or reaches this total attempt li
+                       mit                                                                                                                              [number]
+  --max-loops          After retries fail, let Interf edit the Method and run saved readiness checks on new Method variations for this Preparation up to this lo
+                       op limit                                                                                                                         [number]
+  --keep-stage-shells  Keep every executed stage shell under .interf/runtime/execution-shells for review instead of pruning successful shells
+                                                                                                                                      [boolean] [default: false]
+```
+
+## interf test
+
+```text
+interf test
+
+Run readiness checks against source files and Portable Context
+
+Options:
+  --help            Show help                                                                                                                          [boolean]
+  --version         Show version number                                                                                                                [boolean]
+  --model           Override the local executor model for this run                                                                                      [string]
+  --profile         Executor-specific profile override for this run                                                                                     [string]
+  --effort          Override the model reasoning effort for this run                                                                                    [string]
+  --timeout-ms      Interrupt the local executor after this much inactivity                                                                             [number]
+  --preparation     Preparation id to check when this Source Folder has more than one Preparation                                                       [string]
+  --target          Check source files, Portable Context, or both. Default: both when Portable Context exists, otherwise source files.
+                                                                                                                            [choices: "both", "raw", "compiled"]
+  --keep-sandboxes  Keep every readiness-check sandbox for review instead of pruning successful ones                                  [boolean] [default: false]
+  --agents          Comma-separated local agents to use for readiness checks, or `all`. Example: --agents claude-code,codex                             [string]
+```
+
+## interf web
+
+```text
+interf web
+
+Start Interf UI and the local Interf API
+
+Options:
+  --help           Show help                                                                                                                           [boolean]
+  --version        Show version number                                                                                                                 [boolean]
+  --host           Host for the local Interf service                                                                                                    [string]
+  --port           Port for the local Interf service                                                                                                    [number]
+  --control-path   Folder where Interf stores local config, Methods, runs, and portable context                                                         [string]
+  --source-folder  Source Folder to prepare when initializing a new Interf Workspace                                                                    [string]
+```
+
+## interf doctor
+
+```text
+interf doctor
+
+Check local executor configuration before a real local run
+
+Options:
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+  --live     Run a real executor preflight against the configured local agent                                                         [boolean] [default: false]
+  --json     Print machine-readable doctor output                                                                                     [boolean] [default: false]
+```
+
+## interf list
+
+```text
+interf list
+
+List saved Preparations in this Source Folder
+
+Options:
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+```
+
+## interf status
+
+```text
+interf status
+
+Show deterministic health for the Portable Context agents use
+
+Options:
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+  --watch    Poll the local Interf service for live run status                                                                        [boolean] [default: false]
+```
+
+## interf verify
+
+```text
+interf verify <check>
+
+Run deterministic verification checks
+
+Positionals:
+  check    Check to run (`stage`, `compiled`, or `method`)                                                                                   [string] [required]
+  stageId  Stage id when using `verify stage <stage-id>`                                                                                                [string]
+
+Options:
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+  --path     Path to a Method package when using `verify method`                                                                                        [string]
+  --json     Print JSON output                                                                                                        [boolean] [default: false]
+```
+
+## interf reset
+
+```text
+interf reset <scope>
+
+Reset generated Portable Context state while keeping source files and the local Method package
+
+Positionals:
+  scope                                                                                                          [string] [required] [choices: "compile", "all"]
+
+Options:
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+```