@interf/compiler 0.9.5 → 0.16.0

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

@@ -9,124 +9,165 @@ This snapshot is bundled with the `interf-actions` skill. The installed `interf`
 ```text
 interf
 
+Open the interactive wizard (default when no subcommand is given)
+
 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> [stageId]  Run deterministic verification checks
-  interf web                       Start Interf Compiler UI and the local Interf service
-  interf reset <scope>             Reset generated Portable Context state while keeping source files and the local Method package
+  interf                      Open the interactive wizard (default when no subcommand is given)                                                        [default]
+  interf init                 Open the interactive wizard
+  interf compile <prep-id>    Start a compile run for a preparation
+  interf verify <prep-id>     Verify a preparation's claim-checks against its portable context
+  interf agents <subcommand>  Manage connected agents and role mapping
+  interf doctor               Check local executor configuration before a real local run
+  interf method <subcommand>  Manage methods on the connected instance
+  interf mcp                  Run the Interf Model Context Protocol server (stdio by default).
+  interf runs <subcommand>    Inspect runs on the connected instance
+  interf status               Show connection + preparation summary
+  interf web [subcommand]     Start / stop / inspect the Interf engine
+  interf reset <prep-id>      Reset a preparation's compile output
+  interf prep <subcommand>    Manage preparations on the connected instance
+  interf login                Set the active Interf instance connection (URL + optional bearer token)
+  interf logout               Clear the active Interf instance connection
 
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
-## interf init
+## interf web
 
 ```text
-interf init
+interf web [subcommand]
 
-Set up Interf or open the Preparation wizard
+Start / stop / inspect the Interf engine
+
+Commands:
+  interf web stop    Stop the connected engine
+  interf web status  Show engine status via the connected URL
+  interf web         Start the engine in the foreground (default)                                                                                      [default]
 
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
+  --host     Host to bind                                                                                                        [string] [default: "127.0.0.1"]
+  --port     Port to bind                                                                                                               [number] [default: 4873]
 ```
 
-## interf create
+## interf prep
 
 ```text
-interf create [type]
+interf prep <subcommand>
 
-Create a Preparation or reusable Method
+Manage preparations on the connected instance
 
-Positionals:
-  type  Type to create (`preparation` or `method`)                                                                                                      [string]
+Commands:
+  interf prep ls                                List preparations
+  interf prep create <prep-id>                  Create a preparation (method binding optional — set later if you don't have one yet)
+  interf prep set-method <prep-id> <method-id>  Bind a method to a preparation (or change which method it uses)
+  interf prep show <prep-id>                    Show a preparation's full record
+  interf prep rm <prep-id>                      Delete a preparation
 
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
 ## interf compile
 
 ```text
-interf compile
+interf compile <prep-id>
 
-Prepare files and write Portable Context agents can use
+Start a compile run for a preparation
+
+Positionals:
+  prep-id  Preparation id                                                                                                                    [string] [required]
 
 Options:
-  --help               Show help                                                                                                                       [boolean]
-  --version            Show version number                                                                                                             [boolean]
-  --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]
+  --help             Show help                                                                                                                         [boolean]
+  --version          Show version number                                                                                                               [boolean]
+  --watch            Stream run events                                                                                                [boolean] [default: false]
+  --quiet            Print only the portable-context locator on success                                                               [boolean] [default: false]
+  --idempotency-key  Client-supplied dedupe key                                                                                                         [string]
+  --url              Override the active connection URL                                                                                                 [string]
+  --token            Override the active bearer token                                                                                                   [string]
 ```
 
-## interf test
+## interf verify
 
 ```text
-interf test
+interf verify <prep-id>
+
+Verify a preparation's claim-checks against its portable context
 
-Run readiness checks against source files and Portable Context
+Positionals:
+  prep-id  Preparation id                                                                                                                    [string] [required]
 
 Options:
-  --help         Show help                                                                                                                             [boolean]
-  --version      Show version number                                                                                                                   [boolean]
-  --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", "source-files", "portable-context"]
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
-## interf web
+## interf method
 
 ```text
-interf web
+interf method <subcommand>
+
+Manage methods on the connected instance
 
-Start Interf Compiler UI and the local Interf service
+Commands:
+  interf method ls                 List methods on the instance
+  interf method install <path>     Install a method package from a local folder
+  interf method draft <prep-id>    Start a method-authoring run for a preparation
+  interf method improve <prep-id>  Start a method-improvement run for a preparation
 
 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]
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
-## interf doctor
+## interf runs
 
 ```text
-interf doctor
+interf runs <subcommand>
 
-Check local executor configuration before a real local run
+Inspect runs on the connected instance
+
+Commands:
+  interf runs ls               List runs (optionally filtered by preparation)
+  interf runs status <run-id>  Show full record for a run
+  interf runs cancel <run-id>  Cancel a running run
+  interf runs fetch <run-id>   Download a run's portable context
 
 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]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
-## interf list
+## interf runs fetch
 
 ```text
-interf list
+interf runs fetch <run-id>
 
-List saved Preparations in this Source Folder
+Download a run's portable context
+
+Positionals:
+  run-id  Run id                                                                                                                             [string] [required]
 
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
+  --to       Target path                                                                                                                     [string] [required]
 ```
 
 ## interf status
@@ -134,43 +175,69 @@ Options:
 ```text
 interf status
 
-Show deterministic health for the Portable Context agents use
+Show connection + preparation summary
 
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
-  --watch    Poll the local Interf service for live run status                                                                        [boolean] [default: false]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
-## interf verify
+## interf login
 
 ```text
-interf verify <check> [stageId]
+interf login
 
-Run deterministic verification checks
+Set the active Interf instance connection (URL + optional bearer token)
 
-Positionals:
-  check    Check to run (`stage`, `portable-context`, or `method`)                                                                           [string] [required]
-  stageId  Stage id when using `verify stage <stage-id>`                                                                                                [string]
+Options:
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+  --url      Engine URL, e.g. https://api.interf.cloud or http://127.0.0.1:4873                                                              [string] [required]
+  --token    Bearer token for non-loopback connections                                                                                                  [string]
+```
+
+## interf logout
+
+```text
+interf logout
+
+Clear the active Interf instance connection
 
 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>
+interf reset <prep-id>
 
-Reset generated Portable Context state while keeping source files and the local Method package
+Reset a preparation's compile output
 
 Positionals:
-  scope                                                                                                          [string] [required] [choices: "compile", "all"]
+  prep-id  Preparation id                                                                                                                    [string] [required]
 
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
+  --mode     Scope of the reset                                                                        [string] [choices: "compile", "all"] [default: "compile"]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [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]
 ```

package/builtin-methods/interf-default/README.md

@@ -5,11 +5,10 @@ Built-in file-processing Method: summarize source-grounded evidence, structure c
 ## Purpose
 
 - General portable-context Method for agent use
-- Compile mixed raw files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents running the readiness checks this task depends on.
+- Compile mixed source files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents running the readiness checks this task depends on.
 
 ## Zones
 
-- `raw` — input directory at `raw`
 - `summaries` — working directory at `summaries`
 - `knowledge-entities` — output directory at `knowledge/entities`
 - `knowledge-claims` — output directory at `knowledge/claims`
@@ -19,9 +18,9 @@ Built-in file-processing Method: summarize source-grounded evidence, structure c
 
 ## Stages
 
-- `summarize` — Turn source files into per-file summaries. (compiled-file-evidence; reads: raw, runtime; writes: summaries)
+- `summarize` — Turn source files into per-file summaries. (compiled-file-evidence; reads: runtime; writes: summaries)
 - `structure` — Build the cross-file knowledge structure from the summaries. (compiled-knowledge-structure; reads: summaries, runtime; writes: knowledge-entities, knowledge-claims, knowledge-indexes)
-- `shape` — Shape the final portable context around the saved task focus and readiness checks. (compiled-query-shape; reads: raw, summaries, knowledge-entities, knowledge-claims, knowledge-indexes, runtime; writes: knowledge-indexes, home)
+- `shape` — Shape the final portable context around the saved task focus and readiness checks. (compiled-query-shape; reads: summaries, knowledge-entities, knowledge-claims, knowledge-indexes, runtime; writes: knowledge-indexes, home)
 
 ## Why `home.md` exists here
 

package/builtin-methods/interf-default/compile/stages/shape/SKILL.md

@@ -25,7 +25,7 @@ Contract type: `compiled-query-shape`
 - Use the saved task focus and readiness checks to bias the final portable context toward the job it should be especially good at.
 - Do not copy expected answers into the final portable context just because the checks imply them.
 - Prefer the saved summary evidence and structured notes when they already preserve the bounded chart/table reads plus provenance you need.
-- Reopen `raw/` during shaping only when the compiled layer is missing the needed value, the metric family is ambiguous, or the earlier bounded read is clearly inconsistent.
-- If a saved readiness check depends on chart-derived or table-derived values, carry the final bounded reads forward into focused notes with provenance instead of repeatedly recomputing them from raw.
+- Reopen source references during shaping only when the compiled layer is missing the needed value, the metric family is ambiguous, or the earlier bounded read is clearly inconsistent.
+- If a saved readiness check depends on chart-derived or table-derived values, carry the final bounded reads forward into focused notes with provenance instead of repeatedly recomputing them from source files.
 - Prefer better routing, prioritization, and focused navigation over speculative synthesis.
 - Any wikilinks you add to `home.md` or indexes must resolve to real compiled note basenames or explicit relative paths.

package/builtin-methods/interf-default/compile/stages/summarize/SKILL.md

@@ -10,7 +10,7 @@ Contract type: `compiled-file-evidence`
 - Required opening shape:
 - `---`
 - `{`
-- `  "source": "raw/example.md",`
+- `  "source": "example.md",`
 - `  "source_kind": "markdown",`
 - `  "evidence_tier": "primary",`
 - `  "truth_mode": "source-grounded",`
@@ -29,6 +29,7 @@ Contract type: `compiled-file-evidence`
 ## Notes
 
 - Favor conservative, source-grounded summaries that preserve evidence tiers and leave broader synthesis for later stages.
+- Read `runtime/stage-inputs.json` for the exact source references assigned to this stage.
 - For large reports or decks, capture scope, headline evidence, and chart/table routing in one light pass.
 - As soon as one report summary can state scope, headline metrics, and chart/table routing, stop reading and write the summary batch plus runtime artifacts immediately.
 - Keep scratch extraction commands single-purpose and non-destructive.

package/builtin-methods/interf-default/improve/SKILL.md

@@ -12,7 +12,7 @@ Default loop:
 4. Keep `method.json`, `method.schema.json`, and any changed stage docs aligned.
 
 Guardrails:
-- do not edit checks, test specs, or raw source files
+- do not edit checks, test specs, or source files
 - do not hardcode expected answers into Method docs
 - keep this package standalone; do not rely on runtime inheritance
 - prefer small, defensible Method changes over random churn

package/builtin-methods/interf-default/method.json

@@ -7,8 +7,16 @@
   },
   "purpose": {
     "label": "Built-in portable-context Method for agent use",
-    "task_hint": "Compile mixed raw files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents running the readiness checks this task depends on."
+    "task_hint": "Compile mixed source files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents running the readiness checks this task depends on."
   },
+  "inputs": [
+    {
+      "id": "source",
+      "label": "Source",
+      "description": "Source references assigned to each stage by Interf runtime.",
+      "required": true
+    }
+  ],
   "label": "Built-in Interf Method",
   "hint": "Built-in file-processing Method: summarize source-grounded evidence, structure cross-file connections, and shape portable context around the saved readiness checks.",
   "stages": [
@@ -19,7 +27,6 @@
       "contract_type": "compiled-file-evidence",
       "skill_dir": "summarize",
       "reads": [
-        "raw",
         "runtime"
       ],
       "writes": [
@@ -86,7 +93,6 @@
       "contract_type": "compiled-query-shape",
       "skill_dir": "shape",
       "reads": [
-        "raw",
         "summaries",
         "knowledge-entities",
         "knowledge-claims",
@@ -137,7 +143,7 @@
     "shape": [
       "Use the saved task focus and readiness checks to bias the final portable context toward the job it should be especially good at.",
       "Do not copy expected answers into the final portable context just because the checks imply them.",
-      "If a saved readiness check depends on chart-derived or table-derived values, verify the needed evidence in `raw/` while shaping and write focused notes that preserve bounded values plus provenance.",
+      "If a saved readiness check depends on chart-derived or table-derived values, verify the needed evidence through source references while shaping and write focused notes that preserve bounded values plus provenance.",
       "Prefer better routing, prioritization, and focused navigation over speculative synthesis.",
       "Any wikilinks you add to `home.md` or indexes must resolve to real compiled note basenames or explicit relative paths."
     ]

package/builtin-methods/interf-default/method.schema.json

@@ -4,15 +4,6 @@
   "target_type": "compiled",
   "label": "Interf built-in Method schema",
   "zones": [
-    {
-      "id": "raw",
-      "role": "input",
-      "path": "raw",
-      "kind": "directory",
-      "required": true,
-      "owned_by": [],
-      "description": "Preparation-local raw snapshot copied from the source folder for direct evidence and verification."
-    },
     {
       "id": "summaries",
       "role": "working",

package/builtin-methods/interf-default/use/query/SKILL.md

@@ -4,15 +4,15 @@ This file is the editable authoring source for the generated native local `inter
 
 Default loop:
 1. Read `home.md` first.
-2. Browse `knowledge/` before `raw/`.
+2. Browse `knowledge/` before source re-checks.
 3. Use `summaries/` for source-grounded evidence.
-4. Use `raw/` for direct quotes, verification, exact table lookups, and chart-derived values.
+4. Use `.interf/runtime/source-snapshot.json` for direct quotes, verification, exact table lookups, and chart-derived values.
 
 Answering rule:
-- do not modify files under `raw/`
+- do not modify source files while answering
 - when a number is chart-derived, say that explicitly
 - if the compiled layer already contains a bounded chart-derived read for the exact metric and year the user asked about, answer from that compiled read first
-- use `raw/` to confirm the source page, metric family, or provenance, not to replace a good compiled bounded read with a mismatched range
+- use source references to confirm the source page, metric family, or provenance, not to replace a good compiled bounded read with a mismatched range
 - when the compiled layer preserves a bounded chart-derived range, keep that bounded range in the answer instead of collapsing it to a midpoint or pseudo-exact single value
 - match the granularity of the visible axis labels or bands and do not invent finer precision than the chart supports
 - when reading charts, verify you are on the correct metric family and year before answering
@@ -23,6 +23,6 @@ Answering rule:
 - if a mark touches or nearly touches a labeled gridline, anchor the answer at that gridline or the immediately adjacent half-band.
 - do not widen a chart-derived range across multiple visible bands unless the chart genuinely supports that uncertainty.
 - if multiple compiled notes mention the same chart read, keep the answer consistent with the most focused compiled note rather than synthesizing a new midpoint or shifted band
-- when the compiled layer is insufficient, verify in `raw/` and then answer
+- when the compiled layer is insufficient, verify against source references and then answer
 
 You can edit this file to bias manual question-answering behavior for this portable context.

package/dist/cli/commands/agents.d.ts

@@ -0,0 +1,2 @@
+import type { CommandModule } from "yargs";
+export declare const agentsCommand: CommandModule;