@interf/compiler 0.9.5 → 0.13.0

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

@@ -10,47 +10,69 @@ This snapshot is bundled with the `interf-actions` skill. The installed `interf`
 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> [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 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 list-methods         List Methods available in this Source Folder (built-in + local drafts)
+  interf method <subcommand>  Manage Methods in your user library (install, publish, remove, list)
+  interf runs <subcommand>    Inspect, fetch, or cancel compile runs (status, watch, list, fetch, cancel)
+  interf status               Show deterministic health for the Portable Context agents use
+  interf web [subcommand]     Open Interf Compiler UI; manage the engine instance for this Workspace
+  interf reset <scope>        Reset generated Portable Context state while keeping source files and the local Method package
+  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]
 ```
 
-## interf init
+## interf web
 
 ```text
-interf init
+interf web [subcommand]
+
+Open Interf Compiler UI; manage the engine instance for this Workspace
 
-Set up Interf or open the Preparation wizard
+Commands:
+  interf web stop    Deregister this workspace from the engine instance (and shut it down if last)
+  interf web status  Show engine-instance status: registered workspaces, active runs, idle time
+  interf web         Start (or attach to) the engine instance for this Workspace and open Interf Compiler UI. Other CLI commands auto-start this in the backgrou
+                     nd — running it explicitly is only needed for the UI.                                                                             [default]
 
 Options:
-  --help     Show help                                                                                                                                 [boolean]
-  --version  Show version number                                                                                                                       [boolean]
+  --help           Show help                                                                                                                           [boolean]
+  --version        Show version number                                                                                                                 [boolean]
+  --host           Host for the local Interf service (only when starting a fresh instance)                                                              [string]
+  --port           Port for the local Interf service (only when starting a fresh instance)                                                              [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]
+  --background     Run as the detached background instance the auto-bootstrap path uses; suppresses interactive hints. Set INTERF_WEB_NO_AUTOSTART=1 to disable
+                   auto-start.                                                                                                        [boolean] [default: false]
 ```
 
-## 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
+  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
@@ -63,13 +85,23 @@ Prepare files and write Portable Context agents can use
 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
+  --method             Method id to compile against this Source Folder. Resolves to the saved Preparation that uses this Method, or asks if more than one bindin
+                       g exists.                                                                                                                        [string]
+  --preparation        Saved Preparation id to compile (advanced; use --method for the Method-first form).                                              [string]
+  --max-attempts       Retry the compile 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]
+  --auto-create        When --method has no matching saved Preparation: --auto-create creates one without prompting; --no-auto-create refuses to create. Default
+                       : prompt on TTY, auto-create otherwise.                                                                                         [boolean]
+  --source             Source Folder path the auto-created Preparation should bind to. Relative paths resolve against --workspace. Default: '.'.        [string]
+  --as                 Name to use when auto-creating a Preparation. The portable context lands at <workspace>/<as>/. Default: derived from --method id.[string]
+  --watch              Block until the compile run finishes; tail stage status. Default is async return-with-id (use `interf runs status <id>` to check later).
+                                                                                                                                      [boolean] [default: false]
+  --idempotency-key    Opaque key sent as X-Interf-Idempotency-Key. The local service caches the key for an hour and returns the original run id on retries inst
+                       ead of starting a fresh run.                                                                                                     [string]
 ```
 
 ## interf test
@@ -87,46 +119,58 @@ Options:
                                                                                                            [choices: "both", "source-files", "portable-context"]
 ```
 
-## interf web
+## interf method
 
 ```text
-interf web
+interf method <subcommand>
+
+Manage Methods in your user library (install, publish, remove, list)
 
-Start Interf Compiler UI and the local Interf service
+Commands:
+  interf method install <path>  Copy a Method package from a path into your user library at ~/.interf/methods/<id>/
+  interf method publish <id>    Promote a workspace draft Method to your user library at ~/.interf/methods/<id>/
+  interf method remove <id>     Remove a Method from your user library at ~/.interf/methods/<id>/
+  interf method list            List Methods installed in your user library at ~/.interf/methods/
 
 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]
 ```
 
-## interf doctor
+## interf runs
 
 ```text
-interf doctor
+interf runs <subcommand>
 
-Check local executor configuration before a real local run
+Inspect, fetch, or cancel compile runs (status, watch, list, fetch, cancel)
+
+Commands:
+  interf runs status <run-id>  Show the current state of a compile run by id
+  interf runs watch <run-id>   Block until the named compile run finishes; tail stage status
+  interf runs list             List recent compile runs in this Workspace
+  interf runs fetch <run-id>   Copy the portable context produced by a compile run to <abs-path>
+  interf runs cancel <run-id>  Cancel an in-flight compile 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
+## interf runs fetch
 
 ```text
-interf list
+interf runs fetch <run-id>
 
-List saved Preparations in this Source Folder
+Copy the portable context produced by a compile run to <abs-path>
+
+Positionals:
+  run-id  Compile run id to fetch                                                                                                            [string] [required]
 
 Options:
-  --help     Show help                                                                                                                                 [boolean]
-  --version  Show version number                                                                                                                       [boolean]
+  --help       Show help                                                                                                                               [boolean]
+  --version    Show version number                                                                                                                     [boolean]
+  --to         Absolute destination path. Must be empty or non-existent unless --overwrite is set.                                           [string] [required]
+  --overwrite  Allow copying into a destination that already has files.                                                               [boolean] [default: false]
 ```
 
 ## interf status
@@ -136,28 +180,37 @@ 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]
+  --instance  Show only engine-instance status (workspaces, runs, idle); skip workspace details                                       [boolean] [default: false]
+```
+
+## interf login
+
+```text
+interf login
+
+Set the active Interf instance connection (URL + optional bearer token)
+
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
-  --watch    Poll the local Interf service for live run status                                                                        [boolean] [default: false]
+  --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 verify
+## interf logout
 
 ```text
-interf verify <check> [stageId]
+interf logout
 
-Run deterministic verification checks
-
-Positionals:
-  check    Check to run (`stage`, `portable-context`, or `method`)                                                                           [string] [required]
-  stageId  Stage id when using `verify stage <stage-id>`                                                                                                [string]
+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
@@ -174,3 +227,17 @@ Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
 ```
+
+## 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/compile.d.ts

@@ -1,28 +1,11 @@
-import * as p from "@clack/prompts";
-import { detectInterf } from "../../packages/project-model/interf.js";
-import type { SourcePreparationConfig } from "../../packages/project-model/lib/schema.js";
 import type { CommandModule } from "yargs";
-import { choosePreparationConfig } from "./preparation-picker.js";
-export declare const compileCommand: CommandModule;
-interface CompileCommandDeps {
-    choosePreparationConfig: typeof choosePreparationConfig;
-    confirm: typeof p.confirm;
-    detectInterf: typeof detectInterf;
-    resolveInteractiveCompileLoopOverrides: typeof resolveInteractiveCompileLoopOverrides;
+interface CompileArgs {
+    prepId: string;
+    watch?: boolean;
+    quiet?: boolean;
+    idempotencyKey?: string;
+    url?: string;
+    token?: string;
 }
-export interface CompileCommandResult {
-    compiledPath: string;
-    testedDuringCompile: boolean;
-}
-export declare function runCompileCommand(argv?: Record<string, unknown>, deps?: Partial<CompileCommandDeps>): Promise<CompileCommandResult | null>;
-export declare function resolveInteractiveCompileLoopOverrides(options: {
-    compiledPath: string;
-    compiledConfig: SourcePreparationConfig | null;
-    maxAttemptsOverride: number | null;
-    maxLoopsOverride: number | null;
-}): Promise<{
-    compiledConfig: SourcePreparationConfig | null;
-    maxAttemptsOverride: number | null;
-    maxLoopsOverride: number | null;
-} | null>;
+export declare const compileCommand: CommandModule<unknown, CompileArgs>;
 export {};