@interf/compiler 0.7.3 → 0.9.1

package/README.md

@@ -6,54 +6,62 @@ Interf prepares data for agent work. It runs locally, processes your files, show
 
 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.
 
-Interf replaces that hidden discovery with a visible file-processing workflow: how you tell Interf to prepare your files for the job agents need to do. You define how the files should be processed, what outputs agents should get, and what evidence should show the data is ready. Interf runs the workflow locally and writes the portable context: evidence, structure, and cross-file connections for agents.
+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
-bristol-office-analysis/
-  report.md
-  notes.md
-  exports/
-interf/
-  interf.json                 # saved setup: source paths, questions, workflow choices, and defaults
-  bristol-office-analysis/    # portable context agents read
-    AGENTS.md                 # agent-facing entry point
-    raw/                      # same source files copied here
-      report.md
-      notes.md
-      exports/
-    home.md                   # overview and routes for agents
-    summaries/                # one note per source file
-    knowledge/                # linked notes built from the files
-  workflows/                  # editable file-processing workflows
+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/
 ```
 
-## What a Run Looks Like
+## What a Preparation Produces
 
-`interf test` scores source files and portable context on the same questions: small, verifiable facts from the files. Same files, same questions. What changes is whether Interf prepared the full picture first.
+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.
 
-A recent public run — one market report, two questions, two agents on the same setup — produced:
+For the built-in `interf-default` Method, a prepare run looks like this:
 
-<!-- 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 on the raw files; Claude Code only passed after Interf prepared the portable context. Both numbers come from that same scoring pass.
-
-That tells you whether preparation helped on this agent work.
+```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/
+```
 
-The table is a sample, not a leaderboard. Run `interf test` on your own files. If you run more than one local agent, one scoring pass can include each of them.
+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.
 
 ## Design Choices
 
-- `Per-work`: every portable context is prepared for one specific job agents need to do, not a generic index over your files.
-- `Deterministic`: Interf runs each stage, an ordered phase of the file-processing workflow, 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, your questions, and your agent runs stay on your machine. No cloud, no uploads, no telemetry.
+- `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 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.
+- `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.
+
+## Why Not Just Ask Your Agent?
+
+You can. Interf can use Claude Code, Codex, or another local agent while it builds the portable context.
+
+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
 
@@ -66,37 +74,38 @@ 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 the job agents need to do.
-3. Describe what the agent should do with those files.
-4. Review the suggested questions Interf will use to compare source files and portable context.
-5. Choose the file-processing workflow, or create one by describing the source data, outputs, and proof you need.
-6. Run `interf compile` to build portable context.
-7. Run `interf test` 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>/`.
 
-If you want a baseline before building, run `interf test --target raw`. It is optional proof, not the main path.
+If you want a baseline before preparing, run `interf test --target raw`. It is optional proof, not the main path.
 
-`interf init` saves setup in `interf/interf.json` and copies the built-in file-processing workflow to `interf/workflows/interf-default/`. That workflow package is yours — inspect it, edit it, or fork it with `interf create workflow`.
+`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 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:
+`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       # agent-facing entry point and retrieval rules
+interf/bristol-office-market/
+  AGENTS.md       # agent-facing entry point and source-checking rules
   CLAUDE.md       # same guidance for Claude Code
   raw/            # same source files copied here
-    report.md
-    notes.md
-    exports/
+    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.
 
@@ -104,15 +113,15 @@ Interf also records stage-by-stage proof of work: which files were processed, wh
 
 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 workflow package 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 folder, what the portable context should contain, and what evidence should show your data is ready. 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: source data, stages, and processing rules
+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 workflow package is for, for humans and agents
+  README.md             # what this Method is for, for humans and agents
   compile/
     stages/
       summarize/        # stage instructions Interf runs during compile
@@ -120,39 +129,48 @@ interf/workflows/interf-default/
       shape/
   use/
     query/              # how agents read the portable context
-  improve/              # how Interf revises this workflow package if questions still fail
+  improve/              # how Interf revises this Method if readiness checks still fail
 ```
 
-- `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. Technically, this is the `context interface`, declared in `workflow.schema.json` and enforced when you run `interf compile`.
+- `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 work.
-- `improve/` holds the instructions Interf follows when the first build misses and the workflow package itself needs editing.
+- `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 the method Interf runs on your files. It defines the stages, output contract, proof requirements, and improvement instructions. The result is portable context 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 portable-context 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/<work>/.interf/tests/`. 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/interf.json` names the agent work and selects the workflow package. Interf runs it and writes the portable 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/interf.json
 
-`interf/interf.json` is the main config file for the project. It lives under `interf/` with workflow packages and portable contexts, so the project root stays clean. Each entry describes one agent work setup: the source path, the saved questions, the workflow package that prepares the portable 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": "..." }
       ]
@@ -161,26 +179,41 @@ Interf saves every scored run under `interf/<work>/.interf/tests/`. You can insp
 }
 ```
 
-The `workflow` field selects the workflow package for that job. It points to a folder id under `interf/workflows/`. Set it to `interf-default` (the built-in default) or to a workflow package you have authored. A different workflow package 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.
+
+## Readiness Checks
 
-## Questions
+There are two checks in the system, and they answer different questions.
 
-In the setup flow, they look like plain questions. In `interf/interf.json`, they live under `checks[]`.
+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.
 
-They should be small, verifiable facts you already know from the files:
+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",
@@ -207,22 +240,23 @@ A maintained public test example in this repo stores them like this:
 - Not a vector store or RAG server. The portable context is plain files.
 - 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.
-- Not a public leaderboard. Every score comes from your files, your questions, and your agent runs.
 
 ## Useful Commands
 
-- `interf` or `interf init` — open the wizard and save the first setup
+- `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` — compare source files and portable context on the same questions
-- `interf create workflow` — draft a reusable workflow package
+- `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) — package boundaries
-- [src/packages/compiler/PACKAGE.md](./src/packages/compiler/PACKAGE.md) — local engine 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]
+```