@interf/compiler 0.1.8

package/README.md

@@ -0,0 +1,1008 @@
+# Interf
+
+The open-source knowledge compiler.
+
+Compile any folder into an LLM knowledge base. Create interfaces for specific tasks. Run evals and benchmarks on your machine.
+
+Interf is for skeptical builders. Most "LLM knowledge base" projects claim they work, but few make it easy to prove that on your actual task. Interf keeps your files on disk, compiles them into a knowledge base your agents can actually use, adds focused interfaces for specific jobs, and lets you benchmark what works instead of trusting marketing copy.
+
+Interf's wedge is not "more context." It is coverage-gated retrieval: the agent should be able to prove what it scanned, what it selected, and what it excluded before it synthesizes an answer.
+
+The deeper differentiator is benchmarkability:
+- build multiple knowledge bases over the same folder
+- compare workflows like `interf` vs `karpathy`
+- compare interfaces for the same business task
+- inspect proofs, outputs, and cost locally instead of trusting marketing claims
+
+A useful mental model is: **Karpathy-style LLM knowledge bases plus autoresearch-style eval loops**. Interf gives you the local filesystem contract, proofs, and workflow runtime to create the knowledge base, operate interfaces on top of it, and compare methods over time.
+
+Another useful framing:
+
+- knowledge base = compiled shared context layer
+- interface = task-specific knowledge surface for agents
+- evals + benchmarks = the trust loop that tells you whether the method actually works
+
+Architecture docs:
+- [`docs/architecture.md`](./docs/architecture.md) — fastest way to understand the whole SDK
+- [`docs/workflow-spec.md`](./docs/workflow-spec.md) — workflow package, compile pipeline, and stage-contract spec
+- [`docs/runtime-contract.md`](./docs/runtime-contract.md) — exact runtime artifact contract
+
+Doc roles:
+- `README.md` = public human entrypoint
+- `AGENTS.md` = maintainer and coding-agent operating guide for this repo
+- `CLAUDE.md` = generated mirror of `AGENTS.md` for Claude Code
+- `docs/` = deeper public technical references
+
+## Why Interf
+
+Most LLM knowledge-base repos optimize for a demo. Interf optimizes for proof.
+
+- visible instructions: the compiled KB or interface folder tells the agent what to read and how to work
+- visible proof of work: stages leave runtime state, artifacts, and coverage proof on disk
+- visible comparison: benchmarks run on your folder so you can compare workflows and interfaces instead of trusting a claim
+
+That is the product wedge:
+
+- force the agent to read the right layer before it answers
+- force the workflow to leave evidence of what happened
+- force the method to compete on your evals
+
+## How Interf works
+
+1. Attach a source folder.
+2. Compile a knowledge base over that folder.
+3. Create one or more task-specific interfaces on top.
+4. Run evals and benchmarks to see which workflow or interface actually performs.
+
+## Core idea
+
+- **Source folder**: your real files, unchanged
+- **Knowledge base**: the living compiled layer at `./interf/{name}/`
+- **Interface**: `./interf/{name}/interfaces/{interface-name}/`, a focused workspace on top of that knowledge base for a specific job, perspective, or workflow
+
+The source folder is not copied into a separate managed store. It is attached in place.
+One source folder can host multiple named knowledge bases under `./interf/` when you want to compare workflows over the same folder.
+
+## Top 3 OSS Promises
+
+1. Compile any folder into a structured knowledge base
+2. Create focused interfaces for specific tasks on top of it
+3. Define evals, run benchmarks, and pick the best workflow
+
+That matters because Interf is designed to let you test methodology, not just store files:
+- compare `interf` vs `karpathy` on the same folder
+- compare multiple interfaces for the same task
+- inspect proofs, costs, and outputs locally instead of trusting claims
+
+This is the OSS shape of the project:
+- local workflow engine
+- stage-contract runtime
+- benchmarkable filesystem contract
+
+What Interf is really selling is not "AI knowledge" as a vibe. It is the ability to:
+
+- compile your own folder into a structured knowledge base
+- create task-specific interfaces on top of it
+- define in plain English what an agent should do, then enforce that it actually happened
+- force agents to leave proof-of-work instead of hand-waving
+- benchmark workflows and interfaces on the same data until you find what actually performs
+
+Simple public framing:
+
+- source files stay in place
+- `interf compile` compiles them into a knowledge base
+- interfaces give you focused workspaces on top
+- evals define what good looks like
+- benchmarks run those evals across compiled knowledge bases or interfaces
+
+## Design choices
+
+- filesystem-first: the product surface is the generated folder, not a hidden service
+- workflow packages, not magic prompts: `workflow.json` plus local docs define the method in a readable way
+- contract-checked stages: Interf checks workspace state against the generated stage contract instead of trusting the agent summary
+- benchmark-first: the goal is not to prove Interf is always best; the goal is to make methods explicit and comparable on your task
+
+Manual-agent rule:
+- open the relevant knowledge-base or interface workspace first; that is the agent entrypoint
+- `AGENTS.md` owns the manual access checklist: what layer to check first and which higher-level artifacts must be reachable
+- `workflow/use/query/SKILL.md` owns the exact manual query and raw-preflight procedure for that workspace
+- use `.interf/source-access.json` to verify that raw paths are actually reachable before depending on them
+- on the first substantive manual question, run the raw-access preflight immediately
+- if a permission prompt is needed, ask for it immediately instead of silently staying on summaries
+- after the preflight, start the answer with exactly `Raw access: confirmed` or `Raw access: unavailable`
+- if sandboxing blocks raw fallback, relaunch with the source folder granted too
+- use local `workflow/` docs to refine retrieval/output behavior without changing the engine contract
+
+## Architecture At A Glance
+
+Think of Interf as three visible layers:
+
+```text
+source-folder/                                control plane, real files
+  ...your files...
+  interf/
+    workflows/                               reusable local workflow definitions
+    benchmarks/                              reusable local benchmark specs and saved runs
+    {knowledge-base-name}/                    primary local knowledge layer
+      summaries/                               per-file evidence objects
+      knowledge/                             cross-file knowledge layer
+      workflow/                              knowledge-base method package
+      interfaces/
+        {name}/                              focused workspace for one job
+          knowledge/                         interface-local entities/claims
+          briefs/                            hero outputs
+          summaries/                           interface-local summaries
+          workflow/                          interface method package
+```
+
+Recommended touchpoints:
+
+- **manage from the source folder**
+- **browse the knowledge base** from `./interf/{name}/`
+- **enter an interface** when you want one job-specific layer directly
+
+## What You See In The IDE
+
+When a user or coding agent opens an Interf knowledge base or interface, the important files should already explain the system:
+
+- `interf.json` = what this workspace is and which workflow it uses
+- `AGENTS.md` = the bootstrap/router for how to navigate the workspace, which workflow docs to read, and which commands matter
+- `workflow/` = the editable local method package for this workspace
+- `.interf/state.json` = mutable working state
+- `.interf/health.json` = computed health and status
+- `.interf/stage-contract.json` = the exact contract for the active stage
+- the source folder itself usually has no generated `AGENTS.md` or `CLAUDE.md`; the KB/interface workspace is the agent entrypoint
+
+That is the intended developer experience:
+
+- read the markdown
+- edit the JSON and workflow docs
+- let Interf verify whether the stage actually completed
+- for interfaces, start with local `workflow/use/query/`, then reuse the parent KB `workflow/use/query/` loop before raw source fallback
+- the compiled KB/interface workspace itself is the agent-facing product surface
+
+Two ownership rules matter:
+
+- `workflow/`, `interf.json`, and local workflow files are user-editable
+- `.interf/run.json` and `.interf/view-spec.json` are CLI-owned runtime artifacts
+
+So the system should feel visible and editable without becoming ambiguous about which files are the actual referee surface.
+
+## Instruction Hierarchy
+
+Interf works best when the instruction layers are clear:
+
+- `AGENTS.md` = workspace bootstrap and router
+- `workflow/use/query/SKILL.md` = manual query loop for this workspace
+- `workflow/compile/stages/<stage>/SKILL.md` = stage-specific compile behavior
+- `.interf/stage-contract.json` = the current automated stage contract
+
+For interfaces, manual query should work like this:
+
+1. local interface query guidance
+2. local interface artifacts
+3. parent KB query guidance
+4. parent KB artifacts
+5. raw source only when needed and actually reachable
+
+That keeps the interface layer focused instead of re-implementing parent knowledge-base policy in parallel.
+
+Ownership rule:
+- `AGENTS.md` = router plus first-question access checklist
+- local `workflow/use/query/SKILL.md` = exact manual query loop for this workspace
+- parent KB `workflow/use/query/SKILL.md` = canonical KB-wide retrieval and raw-fallback policy for interfaces
+- compile-stage retrieval skills and `.interf/stage-contract.json` = automated stage execution, not the primary manual chat surface
+
+These local `SKILL.md` files are workspace instruction docs. Interf routes agents to them through `AGENTS.md` and stage contracts; it does not require globally installed slash skills for the workspace method itself.
+
+## Workflow Map
+
+Workflows own the stage graph.
+
+Use this terminology:
+
+- **workflow** = the reusable method package
+- **compile pipeline** = the ordered stage sequence inside that workflow
+- **stage contract** = the generated acceptance boundary for the currently active stage
+
+Built-in knowledge-base workflows currently use:
+
+1. `summarize`
+2. `compile`
+
+Built-in interface workflows currently use:
+
+1. `retrieve`
+2. `analyze`
+3. `compile`
+
+Reusable local workflows can rename or split those stages. The engine still enforces the same contract kinds underneath:
+
+- knowledge base: file-evidence stages, then knowledge-layer stages
+- interface: retrieval stages, then analysis stages, then output stages
+
+The executor can vary. The contract does not.
+
+The key builder idea is:
+
+- a workflow may define 2 stages or 10 stages
+- each stage still maps to a known contract kind
+- each stage may also declare additional declarative acceptance checks in `workflow.json`
+- the generated stage contract carries the current counts, required reads, required writes, and policies for that run
+- the CLI checks current workspace state and artifacts against that contract instead of trusting the agent's own summary
+
+So stage acceptance is deterministic without requiring hardcoded constant numbers in the workflow itself. A stage can say "account for the current discovered source set" or "prove coverage over the current summary set" rather than "always read exactly 100 files."
+
+Interf is also intentionally not married to one retrieval ideology. The workflow layer is where you can encode:
+
+- summarized-knowledge workflows like the built-in `interf` and `karpathy` methods
+- vectorless or structure-aware retrieval ideas
+- migrated external knowledge pipelines
+
+The product promise is not "this retrieval philosophy wins." The promise is: **make the method explicit, verify it, and benchmark it on your task.**
+
+Product shorthand:
+
+- source files = the folder you attached
+- `interf compile` = the static command; the selected workflow defines the staged method underneath
+- `knowledge/` + `home.md` = the compiled knowledge base surface
+- interfaces = focused workspaces on top
+
+Each knowledge base or interface records a **workflow**:
+
+- `type` = engine object kind in config/schema (`knowledge-base` or `interface`)
+- `workflow` = the user-facing methodology you select in the wizard
+- reusable local workflows live under `source-folder/interf/workflows/`
+- each reusable local workflow is defined in a readable `workflow.json` plus starter docs under `workflow/`
+- executor = the agent/runtime that implements the active stage
+- `compile-plan.md` = the interface's current working plan for one job
+- local `workflow/` = the stage and query implementation you can customize
+- `.interf/stage-contract.json` = the generated per-run contract for the active stage
+
+That means users can change how a stage behaves, but Interf still checks the same:
+- stage order
+- required reads
+- required writes
+- runtime schema
+- verifier surface
+- state transitions
+
+In practice:
+
+- `workflow/workflow.json` + local `workflow/` docs = the method
+- `AGENTS.md` = the navigation/bootstrap layer
+- `.interf/stage-contract.json` = the active deterministic contract
+- `interf verify ...` = the self-check surface for agents and tests
+
+Rule of thumb:
+- a workflow seeds starter local workflow docs and determines how `interf compile` is interpreted
+- if you want different stage behavior or domain bias, use a workflow and local `workflow/`
+- if you want a different stage graph, proof model, or required artifacts, that is effectively a new workflow
+
+Shipped workflows:
+- knowledge base: `interf`, `karpathy`
+- interface:
+  - `briefing` = operator brief for what is true now, what changed, and what matters next
+  - `research` = exploratory view for themes, contradictions, and open questions
+  - `audit` = verification view for gaps, inconsistencies, and missing evidence
+
+Local workflows:
+- run `interf create workflow`
+- or choose `Create new workflow...` from the workflow picker
+- Interf saves a reusable workflow under `interf/workflows/knowledge-base/` or `interf/workflows/interface/`
+- those saved workflows show up in the selector next time
+
+- `.interf/stage-contract.json` = canonical stage inputs, required writes, verifier hooks, and policy
+- `.interf/run.json` = current or last run
+- `.interf/logs/` = per-run prompt files, status timelines, and raw agent event streams
+- `interf verify ...` = deterministic referee
+- `docs/workflow-spec.md` = canonical workflow/package/pipeline explanation
+- `src/lib/schema.ts` = canonical runtime schema source of truth
+- `src/lib/workflow-definitions.ts` = canonical public workflow registry
+
+## What To Edit
+
+If you want to customize how a stage works, edit local markdown files under `workflow/`.
+Keep high-level navigation and operating guidance in `AGENTS.md`. `CLAUDE.md` is a generated mirror so Claude Code sees the same instructions automatically.
+
+If you want to reuse the same methodology across multiple knowledge bases or interfaces in one source folder, create a reusable local workflow under `interf/workflows/` instead of copying the same `workflow/` edits around by hand.
+
+Knowledge base:
+
+- manual use: `workflow/use/query/SKILL.md`
+- create-time setup: `workflow/create/SKILL.md`
+- compile stages: `workflow/compile/stages/<stage>/SKILL.md`
+- KB-attached interface templates: `workflow/interfaces/<interface-workflow-id>/`
+
+Interface:
+
+- manual use: `workflow/use/query/SKILL.md`
+  This is the interface-local query layer. When local interface artifacts are insufficient, it should defer to the parent KB query guidance at `../../workflow/use/query/SKILL.md` before any raw fallback.
+- create-time setup: `workflow/create/SKILL.md`
+- compile stages: `workflow/compile/stages/<stage>/SKILL.md`
+
+Each local doc can declare:
+
+```md
+---
+{
+  "mode": "extend"
+}
+---
+```
+
+or:
+
+```md
+---
+{
+  "mode": "override"
+}
+---
+```
+
+Meaning:
+
+- `extend` = keep Interf's built-in stage method and add local rules
+- `override` = replace Interf's built-in stage instructions for that stage
+
+In both modes, Interf still enforces the same runtime schema, state flow, and verifier surface.
+
+Workflows can also seed starter local workflow docs in `workflow/` so the customization path is visible from day one. Edit them freely; they are scaffold defaults, not protocol.
+
+## Quick start
+
+```bash
+npm install -g @interf/compiler
+
+# or install from source while contributing:
+git clone https://github.com/interf-labs/interf.git
+cd interf && npm install
+npm install -g .
+
+interf init
+
+mkdir -p ~/my-notes
+# put files into ~/my-notes however you want
+
+cd ~/my-notes
+interf create knowledge-base
+interf compile
+
+cd interf/my-notes
+# open in Obsidian here
+# for manual coding-agent sessions, stay at ~/my-notes and point the agent at ./interf/my-notes
+```
+
+Create an interface later:
+
+```bash
+cd ~/my-notes
+interf create interface
+interf compile
+```
+
+`interf compile` is the primary flow. It auto-detects whether you are in a source folder, a knowledge base, or an interface.
+
+## User flow
+
+### 1. Set up Interf globally
+
+```bash
+interf init
+```
+
+This chooses your default executor, optionally installs global helper skills for manual use, and optionally enables Obsidian-friendly defaults. Local workspaces and bundled stage instructions remain authoritative either way.
+If you run it inside a normal folder, the wizard can also attach that folder as a knowledge base and immediately compile it.
+
+### 2. Attach Interf to any folder as a knowledge base
+
+```bash
+cd ~/my-notes
+interf create knowledge-base
+```
+
+The wizard records:
+
+- the selected knowledge-base workflow in `interf.json`
+- any starter local workflow docs seeded by that workflow
+
+Interf creates:
+
+```text
+my-notes/
+  ...your files...
+  interf/
+    my-notes/
+```
+
+Recommended touchpoint:
+
+- manage from the source folder
+- browse from `./interf/{name}/`
+- drop into an interface folder only when you want its local outputs directly
+
+### 3. Compile the knowledge base
+
+```bash
+interf compile
+```
+
+Knowledge-base compilation has two steps:
+
+1. Summarize source files into source-grounded evidence objects in `summaries/`
+2. Compile the cross-file knowledge base in `knowledge/` and `home.md`
+
+### 4. Create interfaces when you need a focused workspace for a specific job
+
+```bash
+cd ~/my-notes
+interf create interface
+```
+
+Interfaces live inside the main knowledge base:
+
+```text
+my-notes/
+  interf/
+    my-notes/
+      interfaces/
+        weekly-briefing/
+        research-synthesis/
+        gap-audit/
+```
+
+Each interface has its own `interf.json`, `AGENTS.md`, `CLAUDE.md`, `compile-plan.md`, `home.md`, runtime state, local workflow package, and local outputs.
+
+Recommended flow:
+
+- create interfaces from the source folder
+- let the wizard compile them immediately when possible
+- browse them from the parent knowledge-base vault or by opening `interfaces/{name}/home.md`
+
+## Directory layout
+
+### Knowledge base
+
+```text
+source-folder/
+  ...user files...
+  interf/
+    workflows/
+    benchmarks/
+    {knowledge-base-name}/
+      interf.json
+      AGENTS.md
+      CLAUDE.md
+      home.md
+      .interfignore
+      .gitignore
+      .interf/
+        state.json
+        health.json
+        view-spec.json
+        source-access.json
+        run.json
+        run-history.jsonl
+        stage-contract.json
+        summarize-targets.json
+        inventory.json
+      workflow/
+        workflow.json
+        README.md
+        create/
+          SKILL.md
+        compile/
+          stages/
+            {workflow-stage-1}/
+            {workflow-stage-2}/
+        use/
+          query/
+            SKILL.md
+        interfaces/
+          {interface-workflow-id}/
+      summaries/
+      knowledge/
+        entities/
+        claims/
+        indexes/
+      interfaces/
+        {name}/
+```
+
+### Interface (engine type: `interface`)
+
+```text
+source-folder/
+  interf/
+    {knowledge-base-name}/
+      interfaces/
+        {name}/
+          interf.json
+          compile-plan.md
+          AGENTS.md
+          CLAUDE.md
+          home.md
+          .gitignore
+          .interf/
+            state.json
+            health.json
+            view-spec.json
+            run.json
+            run-history.jsonl
+            stage-contract.json
+            relevant.json
+            coverage.json
+            analysis.json
+          workflow/
+            workflow.json
+            README.md
+            create/
+              SKILL.md
+            compile/
+              stages/
+                {workflow-stage-1}/
+                {workflow-stage-2}/
+                {workflow-stage-3}/
+            use/
+              query/
+                SKILL.md
+          knowledge/
+            entities/
+            claims/
+          briefs/
+          summaries/
+```
+
+## Config
+
+### Knowledge-Base `interf.json`
+
+Knowledge bases use the internal engine type `knowledge-base` in `interf.json` and runtime schemas.
+
+```json
+{
+  "type": "knowledge-base",
+  "name": "my-notes",
+  "workflow": "interf",
+  "source": {
+    "path": "../.."
+  }
+}
+```
+
+### Interface `interf.json`
+
+```json
+{
+  "type": "interface",
+  "name": "weekly-briefing",
+  "workflow": "briefing",
+  "knowledge_base": {
+    "path": "../.."
+  }
+}
+```
+
+- Knowledge-base config points to the source folder with `source.path`
+- Interface config points to the main knowledge base with `knowledge_base.path`
+- `workflow` records the selected methodology
+- Processing logic stays out of config
+- Interface-specific planning lives in `compile-plan.md`
+- Local stage and query implementation lives in `workflow/`
+- `AGENTS.md` is the source of truth for agent bootstrap instructions
+- `CLAUDE.md` is a generated mirror of `AGENTS.md` so Claude Code gets the same knowledge-base instructions automatically
+- `.interf/source-access.json` is the quick-check surface for raw-file accessibility in manual agent sessions
+- `workflow/` holds repo-local instruction docs for create, compile stages, and manual use
+- local `workflow/.../SKILL.md` files are workspace docs, not required global slash skills
+- generated `AGENTS.md` / `CLAUDE.md` live in knowledge bases and interfaces, not the source root
+- local docs can declare `mode: extend` or `mode: override` in JSON frontmatter
+- Interf still guarantees the runtime schema, required writes, verifiers, and state flow even when stage logic is overridden
+
+## Instruction + Enforcement Model
+
+Interf separates:
+
+- **workflow** — the methodology that defines what `interf compile` means for this knowledge base or interface
+- **stage contract** — the generated per-run file with fixed inputs, outputs, required proofs, and state expectations
+- **instructions** — flexible markdown docs that tell an executor how to satisfy that contract
+- **enforcement** — deterministic checks that decide whether the stage actually complied
+- **executor** — Claude Code, Codex, API-backed runner, or your own managed process
+
+That means:
+
+- executors are swappable
+- auth belongs to the executor
+- local stage logic is customizable in files
+- Interf enforces compliance at runtime by checking workspace state and required artifacts against the stage contract
+
+This is the practical "agents do not get to freestyle" layer:
+
+- `AGENTS.md` tells the agent how to enter and navigate the workspace
+- query docs under `workflow/use/query/` tell the agent how to use the compiled KB or interface
+- stage docs under `workflow/compile/stages/` tell the agent how to perform a specific stage
+- the CLI writes `.interf/stage-contract.json` so the executor knows exactly what must be read, written, proved, and left on disk for the current run
+- `.interf/state.json`, `.interf/health.json`, and required stage files show what the agent scanned, selected, analyzed, and wrote
+- deterministic checks decide pass/fail from that runtime state instead of trusting the agent's own summary of its work
+
+That is the proof-of-work story. Interf is not just prompts. It is prompts plus contracts plus enforcement plus persisted traces.
+
+Workflow doc modes:
+
+- `mode: extend` — add local stage rules on top of bundled Interf instructions
+- `mode: override` — replace bundled stage instructions for that stage
+
+In both modes, Interf still requires the same artifact schema and flow.
+
+## CLI commands
+
+Human-facing workflow:
+
+```text
+interf init
+interf create knowledge-base
+interf create interface
+interf compile [type]
+interf benchmark [type]
+interf doctor [--live]
+interf list
+interf status
+interf reset <scope>
+```
+
+Command notes:
+
+- `interf init` handles global setup first; if you run it inside a normal folder, the wizard can also attach and compile a knowledge base there
+- `interf create` opens a chooser when you do not pass a type
+- `interf create knowledge-base` attaches the current folder as a knowledge base, then lets you choose an existing workflow or create a new reusable local workflow
+- `interf create interface` creates a focused interface for the current folder's knowledge base, then lets you choose an existing workflow or create a new reusable local workflow
+- `interf compile` is the primary public verb, auto-detects knowledge base vs interface, and now runs executor preflight automatically before work starts
+- `interf benchmark` compares already-compiled knowledge bases or interfaces using a file-based benchmark spec under `interf/benchmarks/`
+- `interf doctor` checks local executor setup; `--live` exercises the actual configured agent directly when you want to inspect it yourself
+- `interf status` is deterministic and read-only
+- manual query/use is part of the compiled workspace protocol: open the KB/interface folder, read `AGENTS.md`, then follow `workflow/use/query/SKILL.md`
+
+## Evals And Benchmarks
+
+`interf benchmark` assumes the selected knowledge bases or interfaces are already compiled.
+
+V1 intentionally stays simple:
+
+- eval files are human-owned files on disk
+- cases describe what must be true in plain English
+- Interf checks deterministic file outputs instead of using an LLM judge by default
+- if a target is not compiled, it should not be benchmark-eligible
+
+The benchmark input is a small local file under:
+
+- `interf/benchmarks/knowledge-base/*.json`
+- `interf/benchmarks/interface/*.json`
+
+Interf writes benchmark run artifacts under:
+
+- `interf/benchmarks/runs/knowledge-base/*.json`
+- `interf/benchmarks/runs/interface/*.json`
+
+Minimal example:
+
+```json
+{
+  "type": "knowledge-base",
+  "name": "Home Quality",
+  "description": "Check that home.md surfaces the main themes clearly.",
+  "cases": [
+    {
+      "id": "home-overview",
+      "question": "Does home.md explain the main themes and next steps?",
+      "file": "home.md",
+      "expect": {
+        "must_include": ["main themes", "next steps"],
+        "must_not_include": ["TODO"],
+        "min_words": 80
+      }
+    }
+  ]
+}
+```
+
+Why this format:
+
+- the `question` stays plain English and easy to edit
+- the checks stay deterministic and local
+- the same file works for knowledge-base or interface comparisons
+- users can understand and modify it without learning a custom benchmark DSL
+
+Product split:
+
+- `eval` = the criteria file you define
+- `benchmark` = running those evals across compiled knowledge bases or interfaces
+
+The benchmark wizard only offers targets whose current status is `compiled`, so stale or failed targets are visible but not benchmark-eligible.
+
+Why not prompt-plus-expected-answer first:
+
+- exact-answer evals are brittle
+- LLM-judge loops add cost and ambiguity too early
+- artifact checks keep the system inspectable and reproducible
+
+Future versions can add query-based evals, but the default should stay file-first and understandable.
+
+Agent/test harness command:
+
+```text
+interf verify <check>
+```
+
+- `interf verify <check> --json` is mainly for agents, tests, and internal harness checks
+- it exists so agents can call stable deterministic validators via the CLI instead of writing custom verification code
+
+## How compile works
+
+### Knowledge-base compile
+
+`interf compile` in a knowledge base runs the selected workflow's stage graph.
+
+Built-in workflows currently use:
+
+1. `knowledge-base/summarize`
+   - bundled file-evidence contract
+   - discovers source files from `source.path`
+   - compares them to `summaries/`
+   - writes or updates one summary per source file
+2. `knowledge-base/compile`
+   - bundled knowledge-layer contract
+   - scans all files in `summaries/`
+   - turns those summaries into the local LLM wiki layer
+   - builds `knowledge/` with summaries, backlinks, concepts, and linked articles
+   - updates `home.md`
+
+Custom workflows can split or rename those stages, but they still have to satisfy the file-evidence then knowledge-layer pipeline.
+
+### Interface compile
+
+`interf compile` in an interface runs the selected workflow's stage graph.
+
+Built-in workflows currently use:
+
+1. `interface/retrieve`
+   - bundled retrieval contract
+   - scans all knowledge-base `summaries/` frontmatter
+   - reviews candidate abstracts and expands through links when needed
+   - selects the relevant set with proof of coverage
+   - saves `.interf/relevant.json`
+   - saves `.interf/coverage.json`
+2. `interface/analyze`
+   - bundled analysis contract
+   - analyzes the relevant set
+   - extracts interface-local entities and claims
+   - writes temporary analysis artifacts
+3. `interface/compile`
+   - bundled output contract
+   - writes local `knowledge/`, `briefs/`, `summaries/`, and `home.md`
+
+Custom workflows can split or rename those stages, but they still have to satisfy the retrieval then analysis then output pipeline.
+
+Each stage is resumable via durable runtime artifacts:
+- `.interf/state.json` for long-lived summary state
+- `.interf/run.json` for the active or most recent deterministic stage run
+- `.interf/stage-contract.json` for the machine-readable contract the current stage must follow
+- `.interf/run-history.jsonl` for prior completed runs
+- `.interf/logs/` for prompt, status, and raw agent traces from automated runs
+
+## Status and runtime files
+
+Runtime state lives under `.interf/` and is gitignored.
+
+Important files:
+
+- `.interf/state.json`: stage completion, timestamps, counts
+- `.interf/health.json`: computed health and trust surface
+- `.interf/view-spec.json`: viewer-neutral card and graph contract
+- `.interf/run.json`: current or last stage run, with stage, executor, timestamps, counts, and status
+- `.interf/stage-contract.json`: machine-readable stage contract for the active run
+- `.interf/run-history.jsonl`: append-only history of completed or failed runs
+- `.interf/logs/`: one prompt file, one status timeline, and one raw event stream per automated run for later analysis
+- `.interf/relevant.json`: retrieved set for interfaces
+- `.interf/coverage.json`: retrieval proof for interfaces
+- `.interf/analysis.json`: temporary interface analysis handoff
+
+`interf status` computes health from filesystem facts plus runtime state. It does not require a live executor run.
+
+Ownership rule:
+
+- agents may read `.interf/run.json` and `.interf/view-spec.json`
+- the CLI owns writing and normalizing them
+- local workflow docs should update `state.json` and required stage artifacts, not rewrite the run ledger or viewer contract
+
+For the exact schema:
+
+- human-readable contract: [docs/runtime-contract.md](/Users/gedossman/Documents/interf/interf-brain-sdk/docs/runtime-contract.md)
+- TypeScript source of truth: [src/lib/schema.ts](/Users/gedossman/Documents/interf/interf-brain-sdk/src/lib/schema.ts)
+
+## Validation and testing
+
+For repo-level regression coverage:
+
+```bash
+npm test
+```
+
+For a real local acceptance run against your configured coding agent:
+
+```bash
+npm run test:acceptance-live
+```
+
+That live acceptance runner:
+
+- creates a temp source folder with a small real fixture
+- creates one `interf` knowledge base on it
+- asserts the KB scaffold files exist exactly where Interf says they should
+- compiles it with the real configured local executor
+- asserts KB outputs, proofs, run ledgers, and logs exist after compile
+- creates and compiles one briefing interface on top
+- asserts interface scaffold files, retrieve proof, outputs, run ledgers, and logs exist
+- runs a manual KB query exercise from the compiled folder and saves trace files under `.interf/query-acceptance/`
+- runs a manual interface query exercise that must go local interface -> parent KB -> raw source and saves the resulting traces and status logs
+- prints the temp folder path so you can inspect real outputs
+
+For the heavier workflow-comparison path:
+
+```bash
+npm run test:acceptance-compare
+```
+
+That compare mode spins up both `interf` and `karpathy`, compiles interfaces on top, and saves benchmark runs.
+
+For the heavier scenario matrix:
+
+```bash
+npm run test:acceptance-matrix
+```
+
+That matrix mode:
+
+- creates two KBs on the same source folder: `interf` and `karpathy`
+- compiles both KBs and validates their scaffolds, outputs, proofs, and logs
+- creates multiple interface workflows on top of each KB: `briefing`, `research`, `audit`
+- compiles all of them with the real executor
+- runs file-based benchmarks across the compiled KBs and interfaces
+- keeps the temp folder so you can inspect the exact artifact tree and `.interf/logs/`
+
+Current limitation:
+
+- benchmark/eval runs still score compiled outputs on disk
+- query/use traversal is now covered by the live acceptance runner, but not yet by the file-based benchmark runner
+- if we want query-mode evals next, that should be a separate harness layer, not hidden inside the current file-based benchmark runner
+
+Add `--cleanup` if you want a successful run removed afterward:
+
+```bash
+node scripts/acceptance-live.mjs --cleanup
+```
+
+For internal executor/model checks without changing your saved default agent:
+
+```bash
+node scripts/acceptance-live.mjs --agent codex --model gpt-5-codex
+node scripts/acceptance-live.mjs --agent claude-code --effort low
+```
+
+For fast targeted reruns against a cached real fixture:
+
+```bash
+npm run test:acceptance-cache:refresh
+```
+
+That refresh command reruns the real quick acceptance flow and saves the latest compiled source folder at `.interf-test-cache/latest-quick/`.
+
+After that, use the targeted quick checks:
+
+```bash
+npm run test:acceptance-quick:create-interface
+npm run test:acceptance-quick:query-interface
+```
+
+Those quick checks copy the cached fixture to a temp folder and rerun only one focused path:
+
+- `create-interface` = start from a precompiled KB and rerun the real interface-create stage logic without rebuilding the KB first
+- `query-interface` = rerun the manual interface query chain (`local interface -> parent KB -> raw`)
+
+Recommended dev loop:
+
+1. Use the quick targeted scripts while iterating on one stage or one narrow user flow.
+2. After a meaningful runtime or scaffolding change, refresh the cached fixture with `npm run test:acceptance-cache:refresh`.
+3. After bigger changes, rerun the full live acceptance and compare/matrix flows.
+
+For agent/test harness work, use `interf status` plus `interf verify <check> --json` as needed. The exact built-in check names are implementation details of the current referee layer.
+
+Recommended human workflow:
+
+1. `interf create interface`
+2. `interf compile`
+3. inspect `home.md` and `interf status`
+4. only then continue to higher-level QA of the interface outputs
+
+Recommended agent/testing workflow:
+
+1. `interf create interface`
+2. `interf verify interface-plan --json`
+3. `interf compile`
+4. `interf verify retrieve --json`
+5. inspect `home.md`, `.interf/health.json`, `.interf/relevant.json`, and `.interf/coverage.json`
+
+## Obsidian
+
+Obsidian is optional.
+
+If you enable viewer defaults during `interf init`, Interf:
+
+- writes minimal `.obsidian/graph.json` defaults
+- attempts to register the knowledge base with Obsidian
+
+It does **not** rely on Obsidian for runtime logic, and it no longer auto-opens vaults via URI. If the running Obsidian app does not show a newly created knowledge base immediately, restart Obsidian or add the folder once through `Manage vaults`.
+
+Important: Obsidian labels vaults by the registered folder name. With the named knowledge-base contract, the registered folder is `interf/{name}/`, so Obsidian will usually show that knowledge-base name directly.
+
+Open this folder in Obsidian:
+
+- knowledge base: `source-folder/interf/{name}`
+
+Do **not** rely on standalone interface vaults by default. Interfaces live inside the knowledge base and need access to parent `summaries/` and source links. Browse them from the knowledge-base vault at `interfaces/{name}/`.
+
+For sandboxed coding agents, the executor should grant access to both the source folder and the knowledge-base tree. Launching an agent from the knowledge-base directory alone can hide raw files referenced through `source.path`.
+
+For manual agent sessions, the default entrypoint is the relevant knowledge-base or interface workspace. If raw-file fallback is blocked, relaunch with the source folder granted too.
+
+Touchpoints:
+
+- source folder = CLI control plane and raw-access parent when needed
+- knowledge-base root = default semantic/manual session root with Interf bootstrap docs
+- interface root = focused manual session root for one use case
+- `./interf/` = namespace container, not the main session root
+
+In the retrieval proof:
+
+- `proof.scanned` is the full set of knowledge-base summaries scanned at the frontmatter-routing layer
+- `proof.reviewed` is the smaller set of candidate summaries whose abstracts were actually reviewed before selection
+- `proof.retrieved` and `proof.excluded` must partition that scanned summary set before analyze begins
+
+## Naming and retrieval
+
+Interf uses:
+
+- **prose-as-title**: filenames are readable claims, not slugs
+- **wiki-link-as-prose**: links read as sentences
+- **progressive disclosure**: title → frontmatter → abstract → overview → source file
+
+Agents should start in `home.md`, move into `knowledge/`, then fall back to `summaries/`, and only open source files when needed.
+
+## Bring files in
+
+Primary model:
+
+- put files directly into the source folder
+- run `interf compile`
+
+Interf treats the folder itself as the source of truth. Bring files in however you want:
+- save/export them directly into the folder
+- clip articles into markdown
+- download related images locally when they matter for context
+
+For web content, markdown clips plus local images work especially well because the resulting knowledge base stays easy for agents to navigate and cite.
+
+## Principles
+
+- Local-first
+- Source folder stays untouched by compile
+- One visible `interf/{name}/` knowledge base per source folder
+- No duplicated raw store by default
+- Any coding agent
+- Obsidian is a viewer, not a dependency
+- Registry is convenience only; local `interf.json` files are the durable source of truth
+
+## License
+
+Interf SDK is licensed under Apache 2.0. See [LICENSE](./LICENSE).
+
+The `Interf` name and related branding are reserved by Interf, Inc. See [TRADEMARKS.md](./TRADEMARKS.md).