@interf/compiler 0.1.8

package/templates/interface/README.md

@@ -0,0 +1,158 @@
+# Interf Interface
+
+Focused local context shells on top of your knowledge base. Any coding agent can navigate them.
+
+## Architecture
+
+```text
+source-folder/
+  interf/
+    {knowledge-base-name}/          knowledge base
+      interfaces/
+        {name}/                     interface
+          interf.json               type: interface, workflow, knowledge_base.path
+          compile-plan.md              interface execution plan
+          AGENTS.md                 bootstrap
+          CLAUDE.md                 Claude Code bootstrap mirror
+          workflow/                 local workflow package
+          home.md                   entry point
+          .gitignore
+          .interf/                  hidden runtime state
+          knowledge/                local entities/claims/indexes
+          briefs/                   hero documents
+          summaries/                periodic summaries
+```
+
+Interfaces are usually created by `interf create interface` from the source folder for a knowledge base. The source folder is the human control plane. The interface is the generated workspace for one job.
+
+Contract model:
+- `type` = engine object kind in config/schema (`interface`)
+- `workflow` = user-facing methodology selection
+- `.interf/stage-contract.json` = generated per-run contract for the active stage
+- executor = the agent/runtime that implements the active stage
+
+## Compile flow
+
+```text
+interf compile:
+  Step 1/3: interface/retrieve   scan all summary frontmatter, prove coverage, compute delta
+  Step 2/3: interface/analyze    batch analysis, extract, refine runtime from evidence
+  Step 3/3: interface/compile    create local context shell, validate
+```
+
+State bridges between steps. If step 2 fails, the next run resumes from step 2.
+
+## Workflows
+
+Shipped interface workflows:
+- `briefing`
+- `research`
+- `audit`
+
+The selected workflow is written to `interf.json` and can seed starter local `workflow/` docs.
+Create new reusable workflows from the wizard when you want a named local variation.
+
+## Bundled stage skills
+
+| Skill | Step | What |
+|---|---|---|
+| `interface/create` | — | Create interface, draft the initial runtime hypothesis |
+| `interface/retrieve` | 1/3 | Scan the full knowledge-base summary set, persist retrieval proof, compute delta |
+| `interface/analyze` | 2/3 | Batch analysis, subagents, extract entities/claims |
+| `interface/compile` | 3/3 | Build local outputs, validate, clean up |
+
+## interf.json
+
+Minimal. Source of truth for type and knowledge-base reference.
+
+```json
+{
+  "type": "interface",
+  "name": "weekly-briefing",
+  "workflow": "briefing",
+  "knowledge_base": {
+    "path": "../.."
+  }
+}
+```
+
+`knowledge_base.path` points to the parent knowledge base. All filter criteria, extraction goals, and output specs live in `compile-plan.md`.
+`workflow` records the selected methodology. Interf generates per-run stage contracts from it for this interface.
+
+If you want different retrieval, ontology, or output 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.
+
+`AGENTS.md` is the source of truth. `CLAUDE.md` is a generated mirror so Claude Code picks up the same interface instructions automatically.
+
+`workflow/` is where you can edit interface-local instruction docs:
+- `workflow/README.md`
+- `workflow/create/SKILL.md`
+- `workflow/use/query/SKILL.md`
+- `workflow/compile/stages/retrieve/SKILL.md`
+- `workflow/compile/stages/analyze/SKILL.md`
+- `workflow/compile/stages/compile/SKILL.md`
+
+Simplest pattern:
+- edit `workflow/compile/stages/retrieve/SKILL.md` to change retrieval logic
+- edit `workflow/compile/stages/analyze/SKILL.md` to change ontology/extraction logic
+- edit `workflow/compile/stages/compile/SKILL.md` to change output/navigation logic
+- edit `workflow/use/query/SKILL.md` to change the manual interface query loop
+
+Workflow seeds may already place starter docs in these folders. Treat them as editable local guidance, not as locked system files.
+Use `AGENTS.md` for navigation, command usage, and the manual access checklist. Use `workflow/` for query behavior and stage behavior.
+
+These are the local instruction layer for the interface. Add JSON frontmatter with `mode: extend` or `mode: override` when you want to declare whether a doc should add to or replace the bundled stage instructions for that stage.
+
+Interf still enforces the same coverage proof, artifact schema, and state flow either way.
+If you need a different stage chain, artifact contract, or verifier flow, create a new workflow in the SDK instead of encoding that in local skill docs.
+
+If your coding agent is sandboxed to the current directory tree, launch it from the source folder so the source root, knowledge base, and this interface all stay reachable.
+Use `../../.interf/source-access.json` to verify that raw files are actually reachable before you depend on raw fallback in a manual agent session. `suggested_checks` are canonical absolute file paths so they remain valid from inside the interface folder.
+
+If Obsidian viewer defaults are enabled during `interf init`, newly created interfaces get minimal `.obsidian/graph.json` defaults. They are not registered as standalone vaults by default; browse them from the parent knowledge-base vault so knowledge-base summaries and source links remain navigable.
+
+## Runtime files
+
+Interfaces maintain runtime artifacts under `.interf/`:
+- `state.json` — mutable runtime state
+- `health.json` — computed compile status and key metrics
+- `view-spec.json` — presentation contract for cards, graph scope, and navigation
+- `run.json` — current or last deterministic stage run
+- `stage-contract.json` — machine-readable contract for the active stage
+- `run-history.jsonl` — append-only history of completed runs
+- `relevant.json` — selected files for this interface
+- `coverage.json` — retrieval proof for this run
+
+`interf status` for an interface is read-only and deterministic. It checks config, knowledge-base path resolution, broken wikilinks, and retrieval coverage.
+`interf verify interface-plan --json` is the deterministic referee for the scaffold and `compile-plan.md`.
+`interf verify retrieve --json` is the deterministic referee for interface retrieval proof before analyze/build.
+
+See `docs/runtime-contract.md` for the human-readable contract and `src/lib/schema.ts` for the exact runtime schemas.
+
+## compile-plan.md
+
+Generated by `interface/create`. Defines:
+- Stage 1: filter criteria
+- Stage 2: extraction goals and allowed runtime refinements
+- Stage 3: output specs for the local context shell
+
+This is the initial interface definition. Compile can refine it when the evidence clearly demands better local structure.
+
+## Key principles
+
+**Local outputs only.** The parent knowledge base is read-only. The interface builds its own `knowledge/` and output folders.
+
+**No auto-cascade.** Knowledge-base compile and interface compile are separate commands.
+
+**Delta compile.** On subsequent runs, only changed files are processed.
+
+**Coverage-gated retrieval.** Retrieval is complete only when the system can prove the full summary set was scanned at the routing layer, candidate abstracts were reviewed, and selected plus rejected sets were persisted.
+
+**Local context shell.** The interface is not just a report folder. It should become the easiest place for an agent to enter, navigate, and understand the relevant slice of the knowledge base.
+
+## Reset
+
+```text
+interf reset compile remove knowledge/ + briefs/ + summaries/, keep config
+interf reset all     remove all generated content, preserve config files
+```

package/templates/interface/interfaces.md

@@ -0,0 +1,99 @@
+# Interface Workflows
+
+Pre-designed interface workflows. Each defines a use case, guiding questions, filter criteria, output inventory, and benchmark queries for validation.
+
+When `interf create interface` builds an interface, it starts from one of these workflows and adapts it to the selected knowledge-base data.
+
+Benchmark queries exist today as validation prompts and expected behaviors. The automated benchmark runner and score logging loop are planned, not yet implemented in the engine.
+
+---
+
+## briefing
+
+Current-state briefing. Best when you want the latest truth, recent changes, and immediate next steps.
+
+**Questions this interface answers:**
+- What is true right now?
+- What changed recently?
+- What should I focus on next?
+- Which decisions or risks are active?
+
+**Filter:** categories include current-state docs, changelogs, plans, updates, decisions
+
+**Outputs:**
+- Current-State.md — current truth with citations
+- Changes.md — recent changes and trend lines
+- Next-Steps.md — action-oriented follow-through
+
+**Summaries:** weekly, monthly, or milestone-based
+
+**Benchmark queries:**
+- "What is true right now?" — should prefer current, confirmed signals over stale material
+- "What changed recently?" — should compare recent vs prior, not show random old notes
+- "What should happen next?" — should surface evidence-linked actions, not generic advice
+
+---
+
+## research
+
+Research synthesis. Best when you want themes, contradictions, evidence strength, and open questions from a dense knowledge base.
+
+**Questions this interface answers:**
+- What are the dominant themes?
+- Which claims are well-supported?
+- Where do sources disagree?
+- What questions still need more evidence?
+
+**Filter:** categories include primary sources, papers, notes, experiments, datasets, repos
+
+**Outputs:**
+- Themes.md — recurring themes with evidence
+- Contradictions.md — disagreements, caveats, counterevidence
+- Open-Questions.md — unresolved questions and next reads
+
+**Summaries:** by topic cluster or period
+
+**Benchmark queries:**
+- "What are the strongest themes?" — should show themes with citations, not loose impressions
+- "Where do sources disagree?" — should show both sides and the evidence basis
+- "What should I read next?" — should turn gaps into concrete next-source suggestions
+
+---
+
+## audit
+
+Audit and gap-finding. Best when you want to improve knowledge-base quality, spot stale areas, and surface missing or contradictory evidence.
+
+**Questions this interface answers:**
+- What is missing or weakly covered?
+- Which facts or claims look inconsistent?
+- Which outputs need verification or refresh?
+- What should be added to the knowledge base next?
+
+**Filter:** categories include canonical records, requirements, policies, status docs, recent changes
+
+**Outputs:**
+- Gaps.md — missing areas and thin coverage
+- Contradictions.md — inconsistent facts or claims
+- Follow-Ups.md — concrete verification or ingestion work
+
+**Benchmark queries:**
+- "What is missing?" — should identify concrete gaps, not generic advice
+- "What looks inconsistent?" — should cite the conflicting evidence explicitly
+- "What should we verify next?" — should turn issues into concrete follow-up work
+
+---
+
+## Self-improving loop (planned runner)
+
+Every interface workflow includes benchmark queries. The intended validation cycle is:
+
+1. Build the interface from its config
+2. Run benchmark queries against the vault
+3. Score: did each query return expected behavior?
+4. If score is below threshold:
+   - Analyze failures
+   - Adjust the interface plan and ontology in `compile-plan.md`
+   - Re-compile
+   - Re-benchmark
+5. Log scores per model per interface for comparison

package/templates/knowledge-base/README.md

@@ -0,0 +1,138 @@
+# Interf Knowledge Base
+
+Your local knowledge base for agents. Attach to any folder, then let Interf compile source files into summaries plus a cross-file knowledge layer.
+
+## Architecture
+
+```text
+source-folder/                  user's files (untouched)
+└── interf/
+    └── {knowledge-base-name}/  knowledge base
+        ├── interf.json         type: knowledge-base, workflow, name, source.path
+        ├── AGENTS.md           bootstrap
+        ├── CLAUDE.md           Claude Code bootstrap mirror
+        ├── workflow/           local workflow package
+        ├── home.md             entry point
+        ├── .interfignore       source exclusion patterns
+        ├── .gitignore
+        ├── .interf/            hidden runtime state
+        │   ├── state.json
+        │   ├── health.json
+        │   ├── source-access.json
+        │   └── view-spec.json
+        ├── summaries/          per-file evidence objects
+        ├── knowledge/
+        │   ├── entities/
+        │   ├── claims/
+        │   └── indexes/
+        └── interfaces/
+            └── {name}/         focused workspaces for specific jobs
+```
+
+Knowledge bases are created by `interf create knowledge-base` from the source folder. The source folder is the human control plane. The knowledge base is the generated workspace. One source folder can host multiple named knowledge bases under `interf/` when you want to compare workflows over the same folder.
+
+Contract model:
+- `type` = engine object kind in config/schema (`knowledge-base`)
+- `workflow` = user-facing methodology selection
+- `.interf/stage-contract.json` = generated per-run contract for the active stage
+- executor = the agent/runtime that implements the active stage
+
+## Processing flow
+
+```text
+cd source-folder
+interf create knowledge-base   → creates ./interf/<knowledge-base-name>/
+interf compile:
+  Step 1/2: summarize source files into evidence objects → summaries/
+  Step 2/2: compile cross-file knowledge + retrieval     → knowledge/ + home.md
+```
+
+## Workflows
+
+Shipped knowledge-base workflows:
+- `interf`
+- `karpathy`
+
+Create new reusable workflows from the wizard when you want a named local variation.
+
+The selected workflow is written to `interf.json` and can seed starter local `workflow/` docs.
+
+## Bundled stage skills
+
+| Skill | Step | What |
+|---|---|---|
+| `knowledge-base/summarize` | 1/2 | Generate source-grounded evidence objects for unprocessed source files |
+| `knowledge-base/compile` | 2/2 | Build the cross-file knowledge layer and retrieval structures |
+
+## interf.json
+
+Minimal config. Points to the source folder:
+
+```json
+{
+  "type": "knowledge-base",
+  "name": "my-notes",
+  "workflow": "interf",
+  "source": {
+    "path": "../.."
+  }
+}
+```
+
+`workflow` records the selected methodology. Interf generates per-run stage contracts from it for this knowledge base.
+
+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.
+
+`AGENTS.md` is the source of truth. `CLAUDE.md` is a generated mirror so Claude Code picks up the same knowledge-base instructions automatically.
+
+`workflow/` is where you can edit knowledge-base-local instruction docs:
+- `workflow/README.md`
+- `workflow/create/SKILL.md`
+- `workflow/use/query/SKILL.md`
+- `workflow/compile/stages/summarize/SKILL.md`
+- `workflow/compile/stages/compile/SKILL.md`
+
+Simplest pattern:
+- edit `workflow/compile/stages/summarize/SKILL.md` to change summarize logic
+- edit `workflow/compile/stages/compile/SKILL.md` to change knowledge-base compile logic
+- edit `workflow/use/query/SKILL.md` to change the manual query loop
+
+Workflow seeds may already place starter docs in these folders. Treat them as editable local guidance, not as locked system files.
+Use `AGENTS.md` for navigation, command usage, and the manual access checklist. Use `workflow/` for query behavior and stage behavior.
+
+These are the local instruction layer for the knowledge base. Add JSON frontmatter with `mode: extend` or `mode: override` when you want to declare whether a doc should add to or replace the bundled stage instructions for that stage.
+
+Interf still enforces the same proof contract, artifact schema, and state flow either way.
+If you need a different stage chain, artifact contract, or verifier flow, create a new workflow in the SDK instead of encoding that in local skill docs.
+
+If your coding agent is sandboxed to the current directory tree, launch it from the source folder so both raw files and this knowledge base stay reachable.
+Use `.interf/source-access.json` to verify that raw files are actually reachable before you depend on raw fallback in a manual agent session. `suggested_checks` are canonical absolute file paths so they still work from nested interface folders.
+
+## Status
+
+Knowledge bases maintain runtime artifacts under `.interf/`:
+- `state.json` — mutable runtime state
+- `health.json` — computed trust surface for summarize/compile status
+- `source-access.json` — raw-file access quick check for manual sessions
+- `run.json` — current or last deterministic stage run
+- `stage-contract.json` — machine-readable contract for the active stage
+- `run-history.jsonl` — append-only history of completed runs
+- `view-spec.json` — viewer-neutral layout contract
+
+`interf status` is read-only and deterministic. It runs source discovery, checks config, summary frontmatter, abstract minimums, and broken wikilinks.
+Use `interf verify summarize --json` after summary generation and `interf verify compile --json` after knowledge-base compilation for explicit pass/fail checks when testing the workflow or driving it from an agent.
+
+See `docs/runtime-contract.md` for the human-readable contract and `src/lib/schema.ts` for the exact runtime schemas.
+
+## Scan accountability
+
+`knowledge-base/compile` writes an inventory of all `summaries/` files before scanning. The scanned count must equal the inventory count. If it does not, the skill stops and reports the gap.
+
+## Reset
+
+```text
+interf reset compile   remove knowledge/, keep summaries/
+interf reset summarize remove summaries/
+interf reset all       remove all generated content, preserve source files
+```

package/templates/knowledge-base/interfignore

@@ -0,0 +1,19 @@
+# Files and directories to exclude from interf source discovery.
+# Same syntax as .gitignore.
+
+# Build artifacts
+dist/
+build/
+out/
+
+# Logs and temp files
+*.log
+*.tmp
+
+# Environment and secrets
+.env
+.env.*
+
+# OS files
+.DS_Store
+Thumbs.db

package/templates/knowledge-base/registry.md

@@ -0,0 +1,118 @@
+# Interf Registry
+
+The registry at `~/.interf/registry.json` tracks all knowledge bases and interfaces on this machine. The CLI and skills read it to list knowledge bases, show status, and navigate between them.
+
+## Format
+
+```json
+{
+  "version": 5,
+  "knowledgeBases": [
+    {
+      "name": "research",
+      "path": "/path/to/research",
+      "workflow": "interf",
+      "created": "2026-03-30T14:00:00Z"
+    },
+    {
+      "name": "ops",
+      "path": "/path/to/ops",
+      "workflow": "karpathy",
+      "created": "2026-03-30T15:00:00Z"
+    }
+  ],
+  "interfaces": [
+    {
+      "name": "weekly-briefing",
+      "path": "/path/to/weekly-briefing",
+      "knowledgeBase": "ops",
+      "knowledgeBasePath": "/path/to/ops",
+      "workflow": "briefing",
+      "created": "2026-03-30T16:00:00Z"
+    },
+    {
+      "name": "gap-audit",
+      "path": "/path/to/gap-audit",
+      "knowledgeBase": "research",
+      "knowledgeBasePath": "/path/to/research",
+      "workflow": "audit",
+      "created": "2026-03-30T16:30:00Z"
+    }
+  ]
+}
+```
+
+## Fields
+
+**Knowledge-base entry:**
+- `name` — short identifier
+- `path` — absolute path to knowledge-base root
+- `workflow` — selected methodology
+- `created` — ISO timestamp
+
+**Interface entry:**
+- `name` — short identifier
+- `path` — absolute path to interface root
+- `knowledgeBase` — name of the connected knowledge base
+- `knowledgeBasePath` — absolute path to the connected knowledge base
+- `workflow` — selected methodology
+- `created` — ISO timestamp
+
+## When it's updated
+
+| Action | Registry change |
+|---|---|
+| `interf create knowledge-base` | Adds a knowledge-base entry |
+| `interf create interface` | Adds an interface entry |
+| `interf compile` | Does NOT update registry |
+| manual cleanup / future remove command | Removes entry (does not delete files) |
+
+The registry stores static info only: names, paths, connections. It never stores processing status.
+
+## How status is computed (live, not stored)
+
+Processing status is always computed on demand from the filesystem:
+
+```
+For each knowledge base:
+  source_count = discover source files from source.path
+  summary_count  = count files in {path}/summaries/
+  pending      = source_count - summary_count
+  status       = pending > 0 ? "pending" : "compiled"
+
+For each interface:
+  state       = read {path}/.interf/state.json
+  knowledge_base_summary = count files in {knowledgeBasePath}/summaries/
+  stale           = knowledge_base_summary > state.knowledge_base_summary_count_at_last_compile
+  status      = stale ? "stale" : "compiled"
+```
+
+This avoids cached status going stale. Always compute fresh.
+
+## CLI output
+
+```
+$ interf list
+
+  Knowledge Bases
+  ─────────────────────────────────
+  research    1,240 files    compiled
+  ops           892 files    3 pending
+
+  Interfaces
+  ─────────────────────────────────
+  weekly-briefing   → ops         compiled
+  gap-audit         → research    stale (12 new)
+```
+
+## Creation
+
+`interf create knowledge-base` or `interf create interface` creates `~/.interf/` and `registry.json` if they don't exist yet. The initial registry:
+
+```json
+{
+  "version": 5,
+  "knowledgeBases": [],
+  "interfaces": []
+}
+```