@interf/compiler 0.2.4 → 0.3.0

package/skills/interface/analyze/SKILL.md

@@ -1,191 +0,0 @@
----
-{
-  "name": "interface/analyze",
-  "description": "Interface analysis contract. Deep analysis of relevant summaries from the knowledge base. Reads delta files from state, batches them, and extracts entities and claims for this interface's ontology. Use when asked to analyze, extract, or run an analysis stage inside interface compile."
-}
----
-
-# Interface Compile — Analyze
-
-Read `interf.json`, `compile-plan.md`, and `.interf/relevant.json` for the current target set from the preceding retrieval stage.
-
-Local runtime reference:
-- active stage contract: `.interf/stage-contract.json`
-- active run ledger: `.interf/run.json`
-- local config: `interf.json`
-- local plan: `compile-plan.md`
-- local instruction docs: the files listed by `.interf/stage-contract.json`
-
-When this skill is embedded into a generated interface, do not try to open SDK repo docs or source files outside the current workspace. The local contract and local docs are the source of truth for this run.
-
-This skill does the deep analysis — reading summaries and extracting what matters for this interface. It may refine the interface runtime after the requested target set is classified, but bounded audits should close the named task before widening scope.
-If `../../.interf/source-access.json` exists, use it as the quick check for whether raw paths are actually reachable from this session before assuming raw fallback will work.
-If local docs are listed by the stage contract, read them before analyzing. They may `extend` or `override` the bundled workflow instructions for this stage, but they do not bypass coverage proof or the stage contract.
-
-Harness role:
-- This skill is an internal harness step normally invoked by `interf compile` from inside an interface.
-- For standard operation, prefer the CLI or another higher-level tool over calling this skill directly.
-
-## Runtime contract
-
-When invoked by the CLI, honor any explicit execution instructions in the prompt. In particular:
-- if `.interf/stage-contract.json` exists, treat it as the authoritative stage contract for this run
-- if the prompt gives an expected analysis set size, use it for progress reporting
-- use `.interf/relevant.json` as the source of truth for `relevant_files` and `delta_files`
-- require `.interf/coverage.json` and `coverage_complete: true` as proof that retrieve reached retrieval closure
-- only emit user-facing lines that start with `STATUS:`, `DONE:`, `BLOCKED:`, or `ERROR:`
-- the CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after validation; do not treat those files as stage-owned write targets for analyze
-- before any long-running raw inspection, PDF/chart extraction, OCR, or shell-based helper step, emit a `STATUS:` line naming the current subtask
-- do not stay silent for more than about one minute while extraction work is still in progress
-- when you switch page groups, markets, chart families, or extraction methods, emit another `STATUS:` line first
-- do not keep reopening the same large raw PDF once the relevant pages are known; switch to a narrower page-bounded extraction step instead
-- avoid long inline Bash heredocs for extraction helpers; prefer one page-bounded command per step, or write a short scratch script file and run it explicitly
-
-## Prerequisites
-
-`.interf/relevant.json` and `.interf/coverage.json` must exist. If not: "Run the retrieval stage first." Stop.
-
-Before analyzing, prefer running:
-
-```bash
-interf verify retrieve --json
-```
-
-If it fails, stop and fix the retrieval proof instead of continuing.
-
-## Steps
-
-```
-Analyze:
-- [ ] 1. Read retrieve proof and plan
-- [ ] 2. Load summaries in bounded working sets
-- [ ] 3. Extract entities, claims, and relationships
-- [ ] 4. Refine runtime where evidence demands it
-- [ ] 5. Merge results
-- [ ] 6. Write analysis handoff
-```
-
-### 1. Read retrieve proof and plan
-
-- `.interf/relevant.json` → `delta_files[]` (or all `relevant_files[]` when delta is conservative)
-- `.interf/coverage.json` → proof of scanned summary set, abstract review, and expansion passes
-- `compile-plan.md` → this stage's section: what to extract (entity types, claim types, relationships)
-- `../../.interf/source-access.json` → sample raw paths and suggested access checks when raw fallback is needed
-- local instruction docs listed by the stage contract
-- treat the plan as the starting ontology
-- if the plan names a bounded audit target set, treat that set as the hard default scope until every requested value is classified as exact, approximate, or unresolved
-- if the plan includes a target ledger, use it as the primary checklist and record one result per target
-- if the plan depends on exact figures from PDFs, charts, or tables, raw inspection is part of analysis for those items, not an optional afterthought
-- for exact-value PDF work, reading raw pages with `Read` confirms location and context, but it does not by itself satisfy the extraction requirement
-- choose the local extraction path from whatever the current environment actually supports; do not assume a specific binary or hardcode shell recipes into the answer
-- before locking in a machine-readable path, verify that the local method is actually available in this environment; if it is missing or blocked, count that as one failed path and switch to another available local method
-
-### 2. Load summaries in bounded working sets
-
-Read full abstract + overview for each delta file.
-Summaries are the default evidence surface, but if the plan requires exact chart/table values and the summaries do not preserve them, inspect the raw source for those specific items and record how the values were derived.
-Do not treat `the summary was coarse` as proof that the source lacks the number.
-When exact chart values matter, the analysis is not complete until you either recover the value more precisely or record why the local environment blocked a machine-readable attempt.
-Keep raw probing focused. Do not dump large SVG, PDF, or OCR bodies into the run log. Extract the needed values, calibration anchors, and method notes only.
-If the plan names a bounded target set, keep the extraction bounded to that set. Do not widen to every market, page, or entity in the report unless one extra comparator or calibration anchor is required to answer the task correctly.
-For bounded audits, do not widen the ontology, taxonomy, or target set until the requested values are classified or a concrete blocker has been recorded.
-Treat metric plus period as part of the target identity. A nearby exact figure with the wrong period, wrong unit, or wrong chart family does not satisfy the target and must remain separate supporting context.
-As soon as each target row is classified as exact, approximate, or unresolved, stop extraction and move directly to the required file writes. Do not spend extra turns polishing, re-reading, or chasing more precision after the ledger is complete.
-
-### Exact-value escalation for PDFs and charts
-
-If the task asks for exact chart or table values:
-- opening the PDF with `Read` is only the first step; it does not count as the machine-readable extraction attempt
-- a concrete local extraction path is the default path rather than an optional enhancement
-- before each new page group, market batch, or extraction method, emit a short `STATUS:` line so the run ledger shows where extraction is currently focused
-- use `Read` on the raw PDF to confirm location, context, or a narrow page group only; once the page map is known, do not keep reopening the full PDF
-- after the page map is known, switch to a page-bounded local extraction helper or scratch file workflow for that page group instead of rereading the whole PDF
-- keep helper commands single-purpose and short. Avoid long inline Bash heredocs; if you need multiple steps, write a short scratch script file first or run separate bounded commands
-- use this ladder in order and do not stop after a single failed extractor:
-  1. confirm the relevant pages, chart titles, axes, units, time cuts, and left-to-right target order from the raw PDF
-  1a. before locking in values, build a page-level chart map for each target chart: page, chart title, visible axis range/ticks, legend or component series, and whether the chart is stacked
-  2. attempt text or table extraction with a local machine-readable method that you have already verified is available in this environment
-  3. if the text layer still misses the values, switch to another machine-readable path that fits the source structure and is already available in the environment
-  4. if the chart still has no explicit labels, attempt another recoverable extraction path before giving up on exactness
-  4a. try at most two machine-readable extraction paths per target or tightly related page group; if both fail, record the blocker and mark the value unresolved instead of escalating indefinitely
-  5. when the report contains known anchor values elsewhere (for example Key Stats or Q1/YTD tables), use them to validate calibration before finalizing historical chart values
-  6. if the anchor check is materially off, recalibrate or change method instead of locking in a coarse approximation
-  7. only then fall back to a visual estimate
-- if the chart is stacked, recover the total stacked height or area unless the request explicitly names one component series; do not treat one colored segment as the requested total
-- if multiple charts share a page, keep a separate chart map and scale for each chart family; never reuse one chart's scale for another chart on the same page
-- when you use shell commands for scratch extraction, keep them single-purpose and non-destructive. Do not start with `rm`, wildcard cleanup, or chained helpers like `;` and `&&`. Prefer fresh temp filenames or directories instead.
-- if a local extraction path is unavailable, blocked, or missing a dependency, record that explicitly, do not retry the same missing path, and either switch once to another available local path or record the blocker
-- do not call a value approximate or unavailable until you have exhausted the extraction ladder or documented a concrete blocker on the local extraction path
-- if you only have an approximation, keep that precision gap visible in the analysis instead of presenting it as final truth
-- if the task only needs a rounded bin, one-decimal chart read, or other answer-grade approximation, and the rendered chart plus visible axis labels already support that answer, stop there instead of drilling deeper into SVG or PDF internals for pseudo-precision
-- if you record an approximate chart value, also record the scale band that supports it, such as `between 0.5 and 0.6, closer to 0.5`, plus any nearby labeled anchors used to choose the rounded value or `bin_choice`
-- if a chart-derived value sits between adjacent one-decimal bins, set `bin_choice` to the closer supported bin and explain that choice in `scale_band` or the notes; do not default to rounding an uncertain midpoint up
-- for approximate chart reads, make `value_display` the answer-grade value a later weak model should quote; keep any finer-grained midpoint guess in `scale_band` or `notes` instead of promoting it into the main display value
-- if the visible chart scale is coarser than the requested display precision, prefer the nearest clearly supported bin or anchor rather than interpolating a prettier in-between tenth that the chart does not really justify
-- if you cannot state which chart title, scale, and total-vs-component interpretation produced the number, keep the target unresolved instead of emitting a confident approximate answer
-- if you widen beyond the named target set, record why in the extraction ledger and stop once that reason is satisfied
-- once every requested value is classified as exact, approximate, or unresolved, stop exploring. Write `.interf/analysis.json`, emit the required status line, and finish the stage.
-- when using scratch extraction files, keep the command output minimal. Write bulk SVG/OCR/PDF output to temp files and inspect only the relevant slices for the target chart rather than streaming whole blobs into the run log.
-
-Batching strategy:
-- Prefer a working set budget of roughly 35-45% of the model context window per batch
-- For 100+ files: spawn subagents per batch
-
-### 3. Extract entities, claims, and relationships
-
-Each batch (or subagent) extracts:
-- Entities relevant to this interface's ontology goals
-- Claims (patterns, decisions, risks, metrics)
-- Relationships between entities
-- Modality notes when it matters: whether a key numeric claim came from prose, tables, or chart/figure extraction
-- Time-cut notes when it matters: whether a value is annual, quarterly, trailing-twelve-month, or another window
-- Precision notes when it matters: exact, approximate, or unresolved
-- For bounded audits, only extract the entities and claims needed for the named targets plus any narrowly justified comparators or calibration anchors
-- For bounded target ledgers, emit one result per requested item with metric, entity, period, source kind, derivation, value, and precision
-
-Subagent instruction:
-```
-Analyze these summaries for the {interface-name} interface.
-Ontology goals: {from compile-plan.md}
-Return: entities, claims, relationships as structured list.
-Include summary title as evidence reference.
-```
-
-### 4. Refine runtime where evidence demands it
-
-If repeated evidence shows the interface needs better local structure, propose or record:
-- new ontology branches
-- refined taxonomy labels
-- emergent thread clusters
-- stronger relationship groupings
-
-Do not rewrite the runtime gratuitously. Refine only when it helps the interface become a better local context layer for future agents.
-For bounded audit or exact-value tasks, do not widen the runtime before the requested values are classified and the main brief can be written.
-
-### 5. Merge results
-
-Combine all batch/subagent outputs:
-- Deduplicate entities (same person/company from different batches)
-- Merge evidence for existing entities/claims
-- merge runtime refinements
-- Flag conflicts for manual review
-
-### 6. Write analysis handoff
-
-Store the merged extraction results in `.interf/analysis.json` (temporary, consumed by the next output stage). Include runtime refinements when present.
-When exact-value PDF or chart work happened, include a raw extraction ledger in `.interf/analysis.json` with enough detail for the compile stage to judge confidence: source path, pages inspected, methods attempted, result, whether a scratch helper was used, and whether each reported value is exact, approximate, or unresolved.
-For chart-derived approximate values, include enough structure in `.interf/analysis.json` for a later reviewer to reconstruct the judgment without reopening the raw file: chart title, whether the chart was stacked, scale band or nearest labeled anchors, and the reason the chosen `bin_choice` is closer than the neighboring bins.
-For bounded target audits, the final write sequence is strict: write `.interf/analysis.json`, emit `STATUS: wrote analyze outputs`, emit `DONE: analyze complete`, and stop.
-
-The CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after validation.
-
-Report with status-style lines:
-```
-STATUS: loaded analyze plan N files.
-STATUS: inspecting <current subtask>
-STATUS: analyzed N/N
-STATUS: wrote analysis
-DONE: analyze complete
-```
-
-When the analysis artifact is written, emit the required `DONE:` line and stop. The CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after validation. Do not keep exploring after the analyze contract is satisfied.

package/skills/interface/compile/SKILL.md

@@ -1,152 +0,0 @@
----
-{
-  "name": "interface/compile",
-  "description": "Interface output contract. Creates or updates local output files from the analysis. Writes knowledge/, briefs/, and home.md with evidence-linked notes. Use when asked to compile outputs, create notes, or run an output stage inside interface compile."
-}
----
-
-# Interface Compile — Output
-
-Read `interf.json` for output definitions and `compile-plan.md` Stage 3 for output specs.
-
-Local runtime reference:
-- active stage contract: `.interf/stage-contract.json`
-- active run ledger: `.interf/run.json`
-- local config: `interf.json`
-- local plan: `compile-plan.md`
-- local instruction docs: the files listed by `.interf/stage-contract.json`
-
-When this skill is embedded into a generated interface, do not try to open SDK repo docs or source files outside the current workspace. The local contract and local docs are the source of truth for this run.
-
-This skill creates the actual files that make the interface queryable. All outputs are LOCAL — do not write to the knowledge base. The interface should become a local context shell that future agents can enter and navigate easily.
-If `../../.interf/source-access.json` exists, use it as the quick check for whether raw paths are actually reachable from this session before assuming raw fallback will work.
-If local docs are listed by the stage contract, read them before compiling. They may `extend` or `override` the bundled workflow instructions for this stage, but they do not bypass coverage proof or the stage contract.
-
-Harness role:
-- This skill is an internal harness step normally invoked by `interf compile` from inside an interface.
-- For standard operation, prefer the CLI or another higher-level tool over calling this skill directly.
-
-## Runtime contract
-
-When invoked by the CLI, honor any explicit execution instructions in the prompt. In particular:
-- if `.interf/stage-contract.json` exists, treat it as the authoritative stage contract for this run
-- if the prompt gives a retrieved set size, use it for progress framing
-- do not create or edit `.interf/view-spec.json`; the CLI refreshes it after stage completion
-- only emit user-facing lines that start with `STATUS:`, `DONE:`, `BLOCKED:`, or `ERROR:`
-- the CLI reconciles `.interf/state.json`, refreshes `.interf/health.json`, and refreshes `.interf/view-spec.json` after validation; do not treat those files as stage-owned write targets for compile
-
-## Prerequisites
-
-If `.interf/analysis.json` is missing or unreadable: emit `BLOCKED: missing analysis handoff (.interf/analysis.json)` and stop.
-
-Before compiling, prefer running:
-
-```bash
-interf verify retrieve --json
-```
-
-If it fails, stop and fix the retrieval proof instead of continuing.
-
-Read `.interf/analysis.json` for the extracted entities, claims, and relationships from the preceding analysis stage.
-
-## Steps
-
-```
-Compile:
-- [ ] 1. Read analysis results and output spec
-- [ ] 2. Compile entities
-- [ ] 3. Compile claims
-- [ ] 4. Compile interface-specific outputs
-- [ ] 5. Compile navigation
-- [ ] 6. Validate
-- [ ] 7. Clean up
-```
-
-### 1. Read analysis results and output spec
-
-- `.interf/analysis.json` → extracted entities, claims, relationships, runtime refinements
-- `compile-plan.md` → this stage's section: what files to create, in what format
-- Existing `knowledge/` → what already exists (for delta: update, don't recreate)
-- `../../.interf/source-access.json` → sample raw paths and suggested access checks when raw fallback is needed
-- local instruction docs listed by the stage contract
-- if the plan asked for exact values from PDFs, charts, or tables, check whether `.interf/analysis.json` includes a raw extraction ledger or equivalent method notes before treating approximations as closed findings
-
-### 2. Compile entities
-
-Create/update `knowledge/entities/` notes. Each entity gets:
-- Summary, evidence links, related entities
-- Properties for filtering (entity_type, status, confidence)
-- Tags for Obsidian surfacing
-- Clear wikilinks back to supporting parent summaries so an agent can move entity -> evidence -> source trail without guessing
-
-### 3. Compile claims
-
-Create/update `knowledge/claims/` notes. Prose-as-title: filename IS the claim.
-- The claim, why it matters, evidence links
-- 2+ sources required for broad synthesis work
-- single-source claims are allowed for bounded audit or extraction workflows when provenance includes source path/page, extraction method, and precision (`exact`, `approximate`, or `unresolved`)
-- Link claims to related entities, briefs, and parent summaries so backlinks become a real navigation surface
-
-### 4. Compile interface-specific outputs
-
-From `compile-plan.md`: create whatever this output stage defines.
-- Treat `compile-plan.md` Stage 3 as the output contract. Follow the exact filenames and folders named there.
-- briefs/ hero documents
-- summaries/ interface-local temporal views when needed
-- Any other outputs defined in the compile plan
-- if this is a bounded audit, prefer one focused hero brief plus the smallest supporting note set that makes the target answers easy to retrieve
-- do not mirror the whole parent report into the interface unless the compile plan explicitly asks for full-report coverage
-- if the plan includes a target ledger, the hero brief must cover every requested target explicitly and unresolved targets must stay unresolved instead of being replaced by nearby exact figures
-- Preserve `value_display`, `bin_choice`, `precision`, `source_kind`, and page metadata from `.interf/analysis.json`. Compile is a render pass, not a second chart-reading pass.
-- If an approximate chart-derived target includes both `value_display` and `bin_choice`, prefer the conservative answer-grade value for the main hero surface unless the notes explicitly justify a finer display. Keep extra granularity in supporting prose, `scale_band`, or notes rather than upgrading the main answer.
-- Do not invent fixed hero-brief filenames or generic claim-folder patterns unless the compile plan explicitly asks for them.
-
-For delta compiles: update existing files surgically. Do NOT regenerate everything.
-
-When a local output cites evidence from the main knowledge base, use the parent knowledge-base summary path (`../../summaries/...`). Do not point `source:` or evidence links at the interface-local `summaries/` folder unless that interface actually created the cited file.
-When an output depends on exact numbers from PDFs, tables, or charts, say whether the value was text-derived, table-derived, or chart-derived. Do not present chart-extracted values as if they were already explicit in the compiled summaries.
-Do not write `data unavailable` or `gap` when the real state is `not yet extracted from the raw source`.
-If the analysis only opened raw pages but did not log a machine-readable extraction attempt for an exact-value task, keep the result unresolved instead of upgrading it to a verified finding.
-If the analysis logged anchor cross-checks with material drift, keep the finding approximate or unresolved instead of presenting it as settled.
-If the question asked for exact values and you only recovered a visual estimate, say `approximate` explicitly and keep the remaining precision gap in the output.
-Do not substitute a requested `annual`, `quarterly`, `trailing-12-month`, `availability`, `take-up`, or similar target with another metric or period just because the substitute is exact and easier to quote.
-
-### 5. Compile navigation
-
-- `home.md` — links to all key outputs, counts, last compile
-- `knowledge/indexes/` or equivalent local maps when the interface needs better navigation
-- make the order of use obvious: AGENTS.md -> home.md -> local knowledge/briefs/summaries -> knowledge-base summaries -> raw if needed
-- make upward navigation obvious too: local outputs should link out to parent summaries so an agent can follow backlinks and climb toward stronger evidence
-- if Obsidian is mentioned, assume the interface is being browsed from the parent knowledge-base vault rather than as a standalone vault
-- Update every compile run
-
-### 6. Runtime reconciliation
-
-Do not reset retrieve/analyze coverage markers manually. The CLI reconciles `.interf/state.json`, refreshes `.interf/health.json`, and refreshes `.interf/view-spec.json` after stage validation so viewers keep a stable presentation contract.
-
-### 7. Validate
-
-- [ ] All outputs from compile-plan.md exist and are non-empty
-- [ ] Entity notes have evidence links
-- [ ] Claims meet the workflow provenance rule: either 2+ sources or a bounded-audit single-source record with explicit provenance
-- [ ] No broken wikilinks
-- [ ] home.md is current
-
-### 8. Clean up
-
-Delete `.interf/analysis.json` — it was temporary between stages.
-
-Report with status-style lines:
-```
-STATUS: loaded compile plan N relevant files.
-STATUS: wrote entities E
-STATUS: wrote claims C
-STATUS: wrote interface outputs
-DONE: compile complete
-```
-
-When the required outputs are written, emit the required `DONE:` line and stop. The CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after validation. Do not keep exploring after the compile contract is satisfied.
-
-## Key principle
-
-**Local outputs only.** Everything this skill creates lives in this interface. The connected knowledge base (at `knowledge_base.path`) is read-only. The interface graph is distilled and focused, not a mirror of the knowledge base. The goal is to make future agent navigation easier, not just to dump another layer of summaries.

package/skills/interface/compile/references/output-format.md

@@ -1,48 +0,0 @@
-# Output Format Guide
-
-All outputs are plain markdown. They work standalone for any agent and render well in Obsidian. Obsidian is supported but not required.
-
-## Properties (JSON frontmatter)
-
-Use Obsidian-compatible properties for filtering:
-
-```md
----
-{
-  "entity_type": "person",
-  "status": "active",
-  "confidence": "high",
-  "tags": ["type/entity", "entity/person"]
-}
----
-```
-
-Properties = machine filtering. Tags = human browsing.
-
-## Wikilinks
-
-Use `[[wikilinks]]` for all internal references. Never raw file paths.
-
-## Wiki-link-as-prose
-
-Links read as sentences:
-> This note is where [[readiness assessment language first appears in the knowledge base]]
-
-## home.md
-
-Entry point. Links to key sections, current counts, last compile date. Update every compile.
-
-## .base files
-
-Optional Obsidian-specific JSON files for filterable table/card views. The interface works without them.
-
-## Graph optimization
-
-- Wikilinks consistently (every link = edge)
-- One canonical note per entity (no duplicates)
-- Home.md and indexes as high-connectivity hubs
-- Tags for color-coding in graph view
-
-## Independence
-
-Everything works without Obsidian. Wikilinks are `[[plain text]]`. Properties use JSON frontmatter. Tags are strings. Any agent can read the files directly.

package/skills/interface/create/SKILL.md

@@ -1,87 +0,0 @@
----
-{
-  "name": "interface/create",
-  "description": "Create a new Interf interface. Analyzes a knowledge base to generate an interf.json config and execution plan (compile-plan.md). Use when asked to create an interface, new interface, or build a task-specific view."
-}
----
-
-# Create Interface
-
-This stage drafts the initial interface runtime hypothesis from the parent knowledge base.
-
-## Stage role
-
-- planning only
-- no raw-source inspection
-- no chart/table extraction
-- no registry edits
-
-Read `.interf/stage-contract.json` first and treat it as authoritative.
-
-## Minimal completion target
-
-For automated runs, the primary deliverable is a correct `compile-plan.md`.
-
-- If scaffolded `interf.json` already matches the stage contract, leave it unchanged.
-- If scaffolded `AGENTS.md` already preserves the router, checklist, and parent handoff, leave it unchanged.
-- Do not spend the run rewriting scaffold files that already validate.
-- After the knowledge-base review, the next action should usually be to rewrite `compile-plan.md` in one full write and stop.
-
-## Bounded analysis
-
-Build the plan from the parent knowledge-base surface only:
-
-- `../../home.md`
-- `../../knowledge/`
-- `../../summaries/`
-
-Read only enough to plan the interface:
-
-- the primary summary or summaries that anchor the task
-- the highest-signal parent knowledge notes that clarify scope
-- the local scaffold files you may update
-
-Do not widen into broad research. If later stages need raw/chart work, encode that in `compile-plan.md` and leave the actual extraction to retrieve/analyze.
-
-## Plan requirements
-
-`compile-plan.md` must:
-
-- preserve the exact requested use case line in `## Interface Goal`
-- keep the existing workflow stage headings and required subsection labels
-- translate the task into a concrete target ledger when the task names specific values, periods, entities, metrics, units, or chart/table families
-- keep different time cuts and metric families separate, and say when later stages must inspect raw visuals
-- require a concrete local extraction path plus exact/approximate/unresolved labeling when precision matters
-- require a durable output surface, usually one focused hero brief for bounded audits
-
-## AGENTS handling
-
-`AGENTS.md` is a scaffold router for later agents, not the main output of this stage.
-
-- Preserve the scaffold router and checklist.
-- preserve the `## Manual access checklist`, raw-source gate, and parent knowledge-base handoff
-- preserve the router to `workflow/use/query/` and later compile-stage docs
-- do not execute those instructions during create
-- only rewrite `AGENTS.md` if the existing scaffold is materially wrong for this interface
-
-## Finish rule
-
-Once `compile-plan.md` is correct and the scaffold still validates:
-
-1. update `interf.json` only if needed
-2. update `AGENTS.md` only if needed
-3. emit the required status lines
-4. stop
-
-Do not keep researching after the durable plan is written.
-
-## Status contract
-
-For automated runs, these canonical `STATUS:` lines are mandatory and must appear verbatim on their own lines:
-
-- `STATUS: loaded interface creation contract.`
-- `STATUS: analyzed knowledge-base.`
-- `STATUS: wrote compile plan.`
-
-You may emit `DONE: interface create complete.` as a final progress line, but the CLI validates completion from the scaffold files rather than trusting that line.
-Additional `STATUS:` lines are allowed between them, but do not replace or rewrite these canonical markers.

package/skills/interface/create/references/compile-plan-format.md

@@ -1,109 +0,0 @@
-# Interface Compile Plan Format
-
-When creating an interface, generate a `compile-plan.md` that follows the selected workflow's stage graph. The examples below show the built-in `Retrieve -> Analyze -> Compile` shape. For custom workflows, repeat the same section pattern for each workflow-defined stage label and contract type. This file lives in the interface root and is git-tracked.
-
-## Format
-
-```markdown
-# {Interface Name} — Compile Plan
-
-## Stage 1: Retrieve
-
-Filter criteria for knowledge-base summaries/:
-- Categories: {list of relevant categories}
-- Priority evidence tiers: {which source/evidence tiers matter most}
-- Truth modes to prioritize or downweight: {fact vs proposal vs brainstorm etc.}
-- Key entities: {people/companies to prioritize}
-- Date range: {if relevant}
-
-Expected relevant file count: ~{estimate}
-Coverage loop:
-- scan all summary frontmatter
-- read abstracts for every candidate file
-- expand through links until the selected set is stable
-- persist selected and rejected files with reasons
-
-## Stage 2: Analyze
-
-For each relevant summary, extract:
-- {entity type 1}: {what to look for}
-- {entity type 2}: {what to look for}
-- Claims: {what patterns/decisions/risks to detect}
-- Runtime refinements: {when to add missing ontology/taxonomy/relationship structure}
-
-Working-set budget: ~{fraction or token budget} of model context window per batch.
-Subagent instruction: "{what each subagent should return}"
-
-## Stage 3: Compile
-
-Output files to create/update:
-
-### {Output 1, e.g., briefs/Company.md}
-Purpose: {what question this answers}
-Sections: {structure}
-Evidence: {what sources to cite}
-
-### {Output 2, e.g., knowledge/entities/*.md}
-{same format}
-
-### home.md
-Links to: {key outputs}
-Status: {counts, last compile}
-Agent navigation: {how an agent should move from AGENTS.md into the rest of this interface}
-```
-
-## Example: Task-Specific interface
-
-```markdown
-# {Interface Name} — Compile Plan
-
-## Stage 1: Retrieve
-
-Filter criteria for knowledge-base summaries/:
-- Categories: {documents, notes, datasets, reports, experiments, or other relevant categories}
-- Priority evidence tiers: {which evidence tiers matter most for this task}
-- Truth modes to prioritize or downweight: {which truth modes to favor or downweight}
-- Key entities: {entities, systems, products, markets, or themes to prioritize}
-- Date range: {all time, a recent window, or another task-specific cutoff}
-
-Expected relevant file count: ~{estimate} of {knowledge_base_summary_total}
-Coverage loop:
-- scan all {knowledge_base_summary_total} summary frontmatter blocks
-- read abstracts for the full candidate set
-- follow adjacency links for the relevant clusters until retrieval closure
-- persist selected and rejected files with reasons in coverage proof
-
-## Stage 2: Analyze
-
-For each relevant summary, extract:
-- {Entity type 1}: {what to extract}
-- {Entity type 2}: {what to extract}
-- Claims: {what is being asserted and with what level of support}
-- Contradictions: {what disagreements matter}
-- Open questions: {what remains unresolved}
-- Runtime refinements: {what missing structure to add when evidence supports it}
-
-Working-set budget: ~{fraction} of model context window per batch.
-Subagent instruction: "{what each subagent should extract and return}"
-
-## Stage 3: Compile
-
-### briefs/{Primary Brief}.md
-Purpose: "{what question this brief answers}"
-Sections: {section structure}
-Evidence: {what evidence to prefer}
-
-### briefs/{Secondary Brief}.md
-Purpose: "{what this note clarifies}"
-Sections: {section structure}
-Evidence: {what evidence to cite}
-
-### briefs/{Follow-up Brief}.md
-Purpose: "{what should be checked next}"
-Sections: {section structure}
-Evidence: {how to link back to gaps or follow-up needs}
-
-### home.md
-Links to: {key briefs and local outputs}
-Agent navigation: AGENTS.md -> home.md -> briefs/ -> knowledge/ -> knowledge-base summaries
-```

package/skills/interface/create/references/workflows.md

@@ -1,35 +0,0 @@
-# Interface Workflows
-
-Interf now ships one built-in interface workflow: `interf`.
-
-Use it as the default task-specific method on top of a knowledge base. If you need a different bias, create a reusable local workflow under `interf/workflows/interface/` and benchmark it.
-
-## interf
-
-Task-specific evidence distillation. Best when the agent needs a bounded workspace that:
-- proves what was scanned and selected
-- preserves the exact task nouns the user cares about
-- compiles minimal answer-ready artifacts for later retrieval
-
-**Questions it answers:**
-- What exactly is this interface trying to help an agent do?
-- Which entities, periods, metrics, comparators, or source families matter?
-- What compiled brief or notes should a weaker model rely on instead of rediscovering the raw data?
-
-**Default bias:**
-- narrow retrieval to the requested task before widening scope
-- turn the request into a target ledger when the task is bounded
-- preserve time periods, units, metric families, and provenance
-- when exact values matter, inspect the raw source and classify the result as text-derived, table-derived, or chart-derived
-- compile one concise hero brief plus the minimum supporting notes needed for reliable retrieval
-
-## Create new workflow
-
-Create a reusable local interface workflow when the built-in `interf` method is not enough.
-
-The wizard asks:
-1. What questions should this interface answer?
-2. What categories or entities matter?
-3. What output documents should it maintain?
-
-Then it saves a named local workflow under `interf/workflows/interface/` and generates `interf.json` plus `compile-plan.md` from knowledge-base analysis.