@interf/compiler 0.1.11 → 0.2.0

package/skills/interface/analyze/SKILL.md

@@ -7,7 +7,7 @@
 
 # Interface Compile — Analyze
 
-Read `interf.json` and `compile-plan.md` for ontology goals. Read `.interf/state.json` for the delta file list from the preceding retrieval stage.
+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`
@@ -18,7 +18,7 @@ Local runtime reference:
 
 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 can also refine the interface runtime when evidence shows the initial ontology or taxonomy is incomplete.
+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.
 
@@ -33,12 +33,17 @@ When invoked by the CLI, honor any explicit execution instructions in the prompt
 - 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
-- keep `.interf/health.json` consistent with the latest `.interf/state.json` if you update state directly
 - 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/state.json` must have `retrieve_complete: true`, `coverage_complete: true`, and `.interf/relevant.json` plus `.interf/coverage.json` must exist. If not: "Run the retrieval stage first." Stop.
+`.interf/relevant.json` and `.interf/coverage.json` must exist. If not: "Run the retrieval stage first." Stop.
 
 Before analyzing, prefer running:
 
@@ -52,27 +57,75 @@ If it fails, stop and fix the retrieval proof instead of continuing.
 
 ```
 Analyze:
-- [ ] 1. Read state and plan
+- [ ] 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. Update state
+- [ ] 6. Write analysis handoff
 ```
 
-### 1. Read state and plan
+### 1. Read retrieve proof and plan
 
-- `.interf/state.json` → counts and compile markers
-- `.interf/relevant.json` → `delta_files[]` (or all `relevant_files[]` on first run)
+- `.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, not a hard cap
+- 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 (not raw — summaries are sufficient).
+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
@@ -84,6 +137,11 @@ 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:
 ```
@@ -102,6 +160,7 @@ If repeated evidence shows the interface needs better local structure, propose o
 - 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
 
@@ -111,30 +170,22 @@ Combine all batch/subagent outputs:
 - merge runtime refinements
 - Flag conflicts for manual review
 
-### 6. Update state
-
-Write analysis results to `.interf/state.json`:
-
-```json
-{
-  "retrieve_complete": true,
-  "analyze_complete": true,
-  "extracted_entities": 15,
-  "extracted_claims": 23,
-  "last_analyze": "2026-03-30T20:10:00Z"
-}
-```
+### 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.
 
-Refresh `.interf/health.json` after state is updated. Do not invent counts; derive them from state and filesystem facts.
+The CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after validation.
 
 Report with status-style lines:
 ```
-STATUS: loaded analyze plan 120 files.
-STATUS: analyzed 120/120
+STATUS: loaded analyze plan N files.
+STATUS: inspecting <current subtask>
+STATUS: analyzed N/N
 STATUS: wrote analysis
 DONE: analyze complete
 ```
 
-When the analysis artifact, state, and health files are written, emit the required `DONE:` line and stop. Do not keep exploring after the analyze contract is satisfied.
+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

@@ -31,13 +31,13 @@ Harness role:
 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
-- keep `.interf/health.json` consistent with the latest `.interf/state.json` if you update state directly
 - 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
 
-`.interf/state.json` must have `analyze_complete: true`. If not: "Run the analysis stage first." Stop.
+If `.interf/analysis.json` is missing or unreadable: emit `BLOCKED: missing analysis handoff (.interf/analysis.json)` and stop.
 
 Before compiling, prefer running:
 
@@ -58,9 +58,8 @@ Compile:
 - [ ] 3. Compile claims
 - [ ] 4. Compile interface-specific outputs
 - [ ] 5. Compile navigation
-- [ ] 6. Update state
-- [ ] 7. Validate
-- [ ] 8. Clean up
+- [ ] 6. Validate
+- [ ] 7. Clean up
 ```
 
 ### 1. Read analysis results and output spec
@@ -70,6 +69,7 @@ Compile:
 - 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
 
@@ -83,19 +83,33 @@ Create/update `knowledge/entities/` notes. Each entity gets:
 
 Create/update `knowledge/claims/` notes. Prose-as-title: filename IS the claim.
 - The claim, why it matters, evidence links
-- 2+ sources required (unless marked unresolved)
+- 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
 
@@ -106,30 +120,15 @@ When a local output cites evidence from the main knowledge base, use the parent
 - 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. Update state
+### 6. Runtime reconciliation
 
-```json
-{
-  "retrieve_complete": true,
-  "coverage_complete": true,
-  "analyze_complete": true,
-  "compile_complete": true,
-  "last_compile": "2026-03-30T20:15:00Z",
-  "knowledge_base_summary_count_at_last_compile": 1242,
-  "entity_count": 15,
-  "claim_count": 23
-}
-```
-
-Do not reset retrieve/analyze coverage markers after a successful compile. The next compile starts fresh because the next retrieve run rewrites the retrieval artifacts and updates timestamps, not because state is zeroed out.
-
-Refresh `.interf/health.json` after state is updated. The CLI refreshes `.interf/view-spec.json` after stage completion so viewers keep a stable presentation contract.
+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 have 2+ sources
+- [ ] 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
 
@@ -139,14 +138,14 @@ Delete `.interf/analysis.json` — it was temporary between stages.
 
 Report with status-style lines:
 ```
-STATUS: loaded compile plan 120 relevant files.
-STATUS: wrote entities 15
-STATUS: wrote claims 23
+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, state, and health files are written, emit the required `DONE:` line and stop. Do not keep exploring after the compile contract is satisfied.
+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
 

package/skills/interface/create/SKILL.md

@@ -1,264 +1,87 @@
 ---
 {
   "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, build a view, or set up a briefing, research, or audit interface."
+  "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
 
-Creates a new interface connected to an existing knowledge base. The LLM analyzes the knowledge base to draft the initial runtime hypothesis for the use case: ontology, taxonomy, retrieval strategy, and output shape.
+This stage drafts the initial interface runtime hypothesis from the parent knowledge base.
 
-Local runtime reference:
-- active stage contract: `.interf/stage-contract.json`
-- active run ledger: `.interf/run.json`
-- local config: `interf.json`
-- local plan target: `compile-plan.md`
-- local instruction docs: the files listed by `.interf/stage-contract.json`
+## Stage role
 
-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.
+- planning only
+- no raw-source inspection
+- no chart/table extraction
+- no registry edits
 
-Harness role:
-- This skill is an internal harness step normally invoked by `interf create interface`.
-- For standard operation, prefer the CLI or another higher-level tool over calling this skill directly.
+Read `.interf/stage-contract.json` first and treat it as authoritative.
 
-If `.interf/stage-contract.json` exists, treat it as the authoritative stage contract for this run. It defines the interface use case, knowledge-base connection, and which files the harness expects this step to update.
+## Minimal completion target
 
-## Wizard checklist
+For automated runs, the primary deliverable is a correct `compile-plan.md`.
 
-```
-Create interface:
-- [ ] 1. Select knowledge base
-- [ ] 2. Define use case
-- [ ] 3. Analyze knowledge base
-- [ ] 4. Update interf.json
-- [ ] 5. Generate compile-plan.md
-- [ ] 6. Update interface structure
-- [ ] 7. Register
-- [ ] 8. Show next steps
-```
+- 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.
 
-### 1. Select knowledge base
+## Bounded analysis
 
-Ask: which knowledge base should this interface read from?
+Build the plan from the parent knowledge-base surface only:
 
-Read `~/.interf/registry.json` for available knowledge bases. If only one knowledge base exists, confirm it.
+- `../../home.md`
+- `../../knowledge/`
+- `../../summaries/`
 
-### 2. Define use case
+Read only enough to plan the interface:
 
-If the caller already provided `Selected workflow: ...`, treat that as the chosen workflow and do not re-decide it.
+- 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
 
-If a known workflow exists: use it as the starting point and adapt it to the actual knowledge base.
-If no known workflow fits: ask the user:
-- What questions should this interface answer?
-- What's the use case? (briefing, research, audit, etc.)
+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.
 
-### 3. Analyze knowledge base
+## Plan requirements
 
-Read the knowledge base's `summaries/` frontmatter and high-level `knowledge/` layer to understand available data:
-- Category distribution
-- People mentioned
-- Date range
-- Evidence-tier / truth-mode distribution
-- Entity and claim coverage in knowledge/
+`compile-plan.md` must:
 
-The knowledge base is at `knowledge_base.path` from `interf.json` (typically `../..`). Knowledge-base summaries are at `{knowledge_base.path}/summaries/`.
-If a coding agent is sandboxed to its current working tree, prefer launching it from the source folder or another root that can reach both the knowledge base and the source folder.
-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.
+- 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
 
-This analysis informs the config and compile plan.
+## AGENTS handling
 
-### 4. Update interf.json
+`AGENTS.md` is a scaffold router for later agents, not the main output of this stage.
 
-`interf.json` is minimal. It stores only `type`, `name`, `workflow`, and the knowledge-base path (`knowledge_base.path`). No filter criteria, no output specs, no validation rules — all of that belongs in `compile-plan.md`.
+- 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
 
-If the CLI already created the scaffold, confirm the existing `interf.json` is correct:
+## Finish rule
 
-```json
-{
-  "type": "interface",
-  "name": "{name}",
-  "workflow": "{workflow}",
-  "knowledge_base": {
-    "path": "../.."
-  }
-}
-```
-
-Do not add `filter:`, `outputs:`, or `validation:` sections to `interf.json`. Those belong in `compile-plan.md`.
-
-### 5. Generate compile-plan.md
-
-This is the execution plan for compiling THIS interface. The LLM writes it based on the knowledge-base analysis and use case.
-
-The plan defines the initial runtime hypothesis for the selected workflow stage graph.
-Start from the existing scaffolded `compile-plan.md`. Preserve the workflow stage headings and required subsection labels already present in that starter plan, then refine the bullet contents and wording for the actual use case.
-For each workflow stage:
-- name the stage exactly as the workflow labels it
-- explain what that stage must accomplish for this use case
-- include contract-appropriate detail for retrieval, analysis, or output stages
-
-### 6. Update interface structure
-
-The CLI creates the scaffold before invoking this skill. The expected structure is:
-
-```
-{name}/
-├── interf.json
-├── compile-plan.md              execution plan (git-tracked)
-├── AGENTS.md
-├── CLAUDE.md
-├── workflow/
-│   ├── workflow.json
-│   ├── README.md
-│   ├── create/
-│   │   └── SKILL.md
-│   ├── use/
-│   │   └── query/
-│   │       └── SKILL.md
-│   └── compile/
-│       └── stages/
-│           └── {workflow stage folders}/
-├── .gitignore
-├── .interf/state.json        runtime only (gitignored)
-└── home.md
-```
-
-**AGENTS.md:**
-```markdown
-# {Name}
-
-{One-line description: what this interface is for and what questions it answers.}
-
-## How this interface works
-
-This is an Interf interface — a focused local context shell built on top of a knowledge base.
-
-- `interf.json` — minimal config. Defines type, name, and knowledge-base path only.
-- `compile-plan.md` — execution plan. Defines the selected workflow's compile stages. Generated by LLM, customized for this specific interface. This is the initial runtime hypothesis, not the final word.
-- `knowledge/` — this interface's local entities, claims, and indexes. Built during compile.
-- `briefs/` — hero documents for this use case.
-- `summaries/` — periodic summaries.
-- `workflow/` — local workflow package for create, query, and compile-stage docs.
-- `workflow/use/query/` — interface-local manual query rules. If local artifacts are insufficient, this should defer to the parent KB query loop at `../../workflow/use/query/SKILL.md`.
-- `home.md` — start here. Overview of what's built.
-- The knowledge base is at `../../`. Knowledge-base summaries are at `../../summaries/`.
-- The knowledge-base raw-file quick check is at `../../.interf/source-access.json`.
-- Agent access hierarchy for this interface is: local interface artifacts -> parent knowledge-base artifacts -> raw source files only when needed.
-- If your coding agent is sandboxed, prefer opening the source folder as the session root, then navigate to this interface from there.
-- In Obsidian, browse this interface from the parent knowledge-base vault. Do not assume a standalone interface vault can resolve parent links.
-
-## Manual access checklist
-
-Use this checklist on the first substantive manual question so you do not get stuck later in the session:
-
-1. Read this `AGENTS.md` and then local `workflow/use/query/SKILL.md`.
-2. Confirm the local interface surface is reachable: `home.md`, `knowledge/`, `briefs/`, and any local `summaries/`.
-3. Confirm the parent knowledge base is reachable: `../../AGENTS.md`, `../../home.md`, and parent summaries.
-4. Run the raw-source preflight through `../../.interf/source-access.json` immediately. If the environment asks for permission, request it right away.
-5. After that preflight, start the answer with exactly `Raw access: confirmed` or `Raw access: unavailable`.
-
-## Preferred operation
-
-Use the Interf CLI:
-```
-interf verify interface-plan --json   # immediately after scaffold creation
-interf compile
-interf verify retrieve --json        # after retrieve before analyze/compile
-```
-
-## Raw skills (fallback / internal harness)
-
-Run the compile chain:
-```
-interface/retrieve      retrieval contract: prove coverage and select relevant files
-interface/analyze       analysis contract: extract entities, claims, and refinements
-interface/compile       output contract: create local outputs and validate them
-```
-
-## For agents without bundled skills
-
-Read `AGENTS.md` first. Then read `workflow/use/query/SKILL.md` for manual questions or the relevant `workflow/compile/stages/<stage>/SKILL.md` when doing compile work. `interf.json` and `compile-plan.md` provide the config and execution plan.
-
-To answer questions: start with `home.md`, follow wikilinks to local entities, claims, and indexes in `knowledge/`, then use `briefs/` and local `summaries/` for high-level entry points. If you need deeper evidence, follow links into knowledge-base summaries at `../../summaries/`, then raw files only when necessary.
-Preserve the scaffold router and checklist. Do not replace this file with a shorter template that drops the manual access checklist, raw-source gate, or parent knowledge-base handoff.
-If local docs are listed by the stage contract, read them before creating the interface. They may `extend` or `override` the bundled workflow instructions for later stages, but they do not bypass the stage contract.
-Do not answer from the knowledge base until retrieval coverage is proved via `.interf/coverage.json` and `.interf/relevant.json`.
-
-## Rules
-
-- Do not modify anything in the knowledge base — it is read-only.
-- All outputs are local to this interface.
-- Follow prose-as-title: filenames are claims, not slugs.
-- Follow wiki-link-as-prose: links read as sentences.
-```
-
-When updating `AGENTS.md`, edit the existing scaffold in place. Keep the manual access checklist, router guidance, and parent knowledge-base handoff sections. Only refine the interface-specific description and lines that need to reflect this use case.
-
-**.gitignore:**
-```
-knowledge/
-briefs/
-summaries/
-.interf/
-```
-Add any output directories from compile-plan.md.
-
-**CLAUDE.md:**
-- Generate it from the final `AGENTS.md` content so Claude Code picks up the same interface instructions automatically.
-- Add a short header telling users to edit `AGENTS.md`, not `CLAUDE.md`.
-
-**.interf/state.json:**
-```json
-{
-  "version": 1,
-  "retrieve_complete": false,
-  "analyze_complete": false,
-  "compile_complete": false,
-  "coverage_complete": false,
-  "frontmatter_scanned": 0,
-  "candidate_count": 0,
-  "abstracts_read": 0,
-  "expansion_passes": 0,
-  "relevant_count": 0,
-  "rejected_count": 0,
-  "delta_count": 0,
-  "delta_files": [],
-  "last_retrieve": null,
-  "last_analyze": null,
-  "last_compile": null,
-  "knowledge_base_summary_count_at_last_compile": 0,
-  "extracted_entities": 0,
-  "extracted_claims": 0,
-  "entity_count": 0,
-  "claim_count": 0,
-  "output_count": 0,
-  "warning_count": 0,
-  "error_count": 0
-}
-```
-
-**home.md:**
-```markdown
-# {Name} — Home
-
-Not yet compiled. Run `interf compile` to start interface compilation.
-```
-
-### 7. Register
+Once `compile-plan.md` is correct and the scaffold still validates:
 
-Add to `~/.interf/registry.json` interfaces[]. Create registry if it doesn't exist.
+1. update `interf.json` only if needed
+2. update `AGENTS.md` only if needed
+3. emit the required status lines
+4. stop
 
-### 8. Show next steps
+Do not keep researching after the durable plan is written.
 
-```
-Done — interface "{name}" created at {path}
-Connected to knowledge base "{knowledge-base-name}"
+## Status contract
 
-Next: cd {path} && interf compile
-```
+For automated runs, these canonical `STATUS:` lines are mandatory and must appear verbatim on their own lines:
 
-## What this skill does NOT do
+- `STATUS: loaded interface creation contract.`
+- `STATUS: analyzed knowledge-base.`
+- `STATUS: wrote compile plan.`
 
-- Does not compile the interface (use `interf compile` from inside the interface, or the raw stage skills)
-- Does not create knowledge bases (use CLI `interf create knowledge-base`)
+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.