@interf/compiler 0.1.11 → 0.2.0

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

@@ -52,58 +52,58 @@ Status: {counts, last compile}
 Agent navigation: {how an agent should move from AGENTS.md into the rest of this interface}
 ```
 
-## Example: Research Briefing interface
+## Example: Task-Specific interface
 
 ```markdown
-# Research Briefing — Compile Plan
+# {Interface Name} — Compile Plan
 
 ## Stage 1: Retrieve
 
 Filter criteria for knowledge-base summaries/:
-- Categories: papers, notes, repos, datasets, experiments
-- Priority evidence tiers: tier_1_authoritative, tier_2_direct_record, tier_3_working_material
-- Truth modes to prioritize or downweight: prioritize fact/reported_fact/measurement, downweight brainstorm and speculation
-- Key entities: methods, datasets, benchmarks, authors, projects
-- Date range: all (for landscape), last 90 days (for recent developments)
+- 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: ~220 of 900
+Expected relevant file count: ~{estimate} of {knowledge_base_summary_total}
 Coverage loop:
-- scan all 900 summary frontmatter blocks
+- scan all {knowledge_base_summary_total} summary frontmatter blocks
 - read abstracts for the full candidate set
-- follow adjacency links for methods, datasets, and benchmark clusters until retrieval closure
+- 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:
-- Methods: goals, assumptions, strengths, weaknesses
-- Datasets: scope, quality issues, benchmark relevance
-- Claims: what is being asserted and with what level of support
-- Contradictions: disagreements across sources, benchmarks, or interpretations
-- Open questions: what the knowledge base still does not explain well
-- Runtime refinements: add missing method families, benchmark clusters, and claim groupings when evidence supports them
+- {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: ~40% of model context window per batch.
-Subagent instruction: "Extract entities, claims, contradictions, and open questions relevant to this research briefing. Return structured JSON."
+Working-set budget: ~{fraction} of model context window per batch.
+Subagent instruction: "{what each subagent should extract and return}"
 
 ## Stage 3: Compile
 
-### briefs/Themes.md
-Purpose: "What themes define this knowledge base right now?"
-Sections: major themes, strongest evidence, changes over time
-Evidence: prefer primary and direct-record sources
+### briefs/{Primary Brief}.md
+Purpose: "{what question this brief answers}"
+Sections: {section structure}
+Evidence: {what evidence to prefer}
 
-### briefs/Contradictions.md
-Purpose: "Where do sources disagree or look unresolved?"
-Sections: contradiction, supporting evidence, counterevidence, next check
-Evidence: cite both sides explicitly
+### briefs/{Secondary Brief}.md
+Purpose: "{what this note clarifies}"
+Sections: {section structure}
+Evidence: {what evidence to cite}
 
-### briefs/Open-Questions.md
-Purpose: "What should we read or verify next?"
-Sections: question, why it matters, missing evidence, suggested next sources
-Evidence: link back to the gaps in the reviewed set
+### 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: all briefs notes, latest summary, entity/claim counts
+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,46 +1,31 @@
 # Interface Workflows
 
-Pre-designed interface methodologies. Use them as starting points and adapt them to the actual knowledge-base data.
+Interf now ships one built-in interface workflow: `interf`.
 
-## briefing
+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.
 
-Current-state briefing. Best when the agent needs the latest truth, recent changes, and immediate next steps.
+## interf
 
-**Questions it answers:**
-- What is true right now?
-- What changed recently?
-- What should happen next?
-
-**Filter:** current-state docs, changelogs, decisions, updates
-**Outputs:** Current-State.md, Changes.md, Next-Steps.md
-
-## research
-
-Research synthesis. Best when the agent needs themes, claims, contradictions, and open questions from a dense knowledge base.
-
-**Questions it answers:**
-- What are the strongest recurring themes?
-- Where do sources agree or disagree?
-- What questions still need more evidence?
-
-**Filter:** primary sources, papers, notes, datasets, experiments, repos
-**Outputs:** Themes.md, Contradictions.md, Open-Questions.md
-
-## audit
-
-Audit and gap-finding. Best when the agent needs to improve knowledge-base quality, surface contradictions, and plan follow-up work.
+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 is missing or weakly covered?
-- Which facts or claims look inconsistent?
-- What should be verified or added next?
+- 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?
 
-**Filter:** canonical records, requirements, policies, status docs, recent changes
-**Outputs:** Gaps.md, Contradictions.md, Follow-Ups.md
+**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 new reusable local workflow from the wizard when the shipped workflows are not enough.
+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?

package/skills/interface/query/SKILL.md

@@ -21,11 +21,25 @@ Default loop:
 - follow wikilinks and backlinks outward before treating one note as complete
 - climb to parent knowledge-base summaries in `../../summaries/` when you need stronger evidence
 - use raw source files only when needed for verification, direct quotes, ambiguity, or missing context
+- if the user asks for exact chart or table values from a named report, use local outputs only to locate the source and relevant pages, then go straight to the raw PDF and a concrete local extraction path
+- when a caller asks for a trace, audit log, or `artifacts_consulted` list, record local `workflow/use/query/SKILL.md` after you inspect it
+- when you climb to the parent knowledge-base query loop, record `../../workflow/use/query/SKILL.md` after you inspect it
 
 Raw-source gate:
 - inspect `../../.interf/source-access.json`
-- verify one `suggested_checks` path is actually readable from this session before claiming raw-file verification
+- actually open and inspect at least one `suggested_checks` path before claiming raw-file verification; a plain existence check is not enough
+- when a caller asks for a trace, audit log, or `artifacts_consulted` list, record `../../.interf/source-access.json` after you inspect it
 - if the path is not reachable or permission is not granted, say the answer is based on interface and parent knowledge-base artifacts only
+- when the question depends on exact figures, direct quotes, chart values, table values, or image-derived evidence, raw inspection is required before answering confidently
+
+PDF / chart rule:
+- if the parent source is a PDF, deck, or report and the needed evidence may live in charts, tables, or figures, do not assume the default text layer or existing notes captured everything
+- if local outputs and parent summaries do not preserve the needed numeric detail, inspect the raw source and say whether the value was text-derived, table-derived, or chart-derived
+- opening the PDF with `Read` is not enough for an exact-value chart question; you must take a machine-readable extraction path before answering
+- if the first local extraction method misses the number, continue down another local recovery path instead of settling early for a visual estimate
+- if the default local extraction path still cannot reach the value, switch methods before stopping early; a temporary scratch helper outside the workspace is allowed when needed
+- if the chart does not expose exact numbers as text, say that clearly instead of pretending the interface already captured them
+- if you can only estimate from the chart after exhausting the local extraction path, label the answer `approximate` and keep the precision gap explicit
 
 When confidence is low:
 - expand outward through linked briefs, claims, entities, and parent summaries

package/skills/interface/retrieve/SKILL.md

@@ -43,8 +43,10 @@ When invoked by the CLI, honor any explicit execution instructions in the prompt
 - if `.interf/stage-contract.json` exists, treat it as the authoritative stage contract for this run
 - if the prompt gives an expected summary-set size, use it as the source of truth for progress reporting
 - if the prompt requires `.interf/relevant.json`, write it
-- 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:`
+- when updating `.interf/relevant.json` or `.interf/coverage.json`, read the current file first and then rewrite the full JSON document; do not depend on anchored patch edits against stale runtime files
+- the CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after validation; do not treat those files as stage-owned write targets for retrieve
+- once the selected set is final, write the proof artifacts immediately, emit the `DONE:` line, and stop; do not reopen manual query docs or raw files after selection is settled
 
 ## Steps
 
@@ -55,14 +57,14 @@ Retrieve:
 - [ ] 3. Review candidate abstracts
 - [ ] 4. Expand through links if needed
 - [ ] 5. Compute delta
-- [ ] 6. Update state
+- [ ] 6. Write retrieval proof
 ```
 
 ### 1. Read config and plan
 
 - `interf.json` → `knowledge_base.path` to locate the knowledge base
 - `compile-plan.md` → this stage's section: categories, priority evidence tiers, truth modes, key entities, date range
-- `.interf/state.json` → `last_compile`, `knowledge_base_summary_count_at_last_compile`
+- if the plan depends on exact figures from PDFs, charts, or tables, keep that modality requirement visible during retrieval
 - `../../.interf/source-access.json` → sample raw paths and suggested access checks when raw fallback is needed
 - local instruction docs listed by the stage contract
 
@@ -81,86 +83,51 @@ Build a summary-set map: total files, source-kind distribution, evidence distrib
 ### 3. Review candidate abstracts
 
 From compile-plan.md filter criteria, identify a candidate set. Then read the abstract block for every candidate file before final selection.
+If the use case depends on exact numeric comparisons from charts or tables, do not exclude a candidate just because the summary abstract is coarse. Keep files whose key evidence may still live in raw visuals.
 
 ### 4. Expand through links if needed
 
 If candidate abstracts point to adjacent summaries that may materially change the answer, follow those links, review their abstracts, and repeat until the retrieved set is coverage-complete for the interface question.
 Track emergent clusters that suggest the initial interface runtime is missing concepts, relationships, or taxonomy branches.
+When chart-heavy PDFs or report pages are likely to hold the decisive evidence, preserve that signal for later stages instead of routing the interface toward prose-only summaries.
+If exact numbers will require a local extraction path against the raw PDF, carry that requirement forward explicitly instead of assuming the analysis stage can infer it from a coarse abstract.
 
 ### 5. Compute delta
 
-- First run (`last_compile` is null): ALL relevant files are new
-- Subsequent runs: compare `knowledge_base_summary_count_at_last_compile` vs current count, identify new files by date
+- If the current workspace already makes the delta obvious, keep `delta_files` limited to the newly relevant or newly changed files.
+- If the prior compile boundary is not obvious from the current workspace, use the conservative fallback: set `delta_files` equal to the selected relevant set for this run.
 
-### 6. Update state
+### 6. Write retrieval proof
 
-Write the full retrieved set to `.interf/relevant.json`:
+Write the full retrieved set to `.interf/relevant.json` in the current runtime shape. At minimum include:
+- `generated_at`
+- `knowledge_base_summary_count` derived from the current knowledge-base summary total
+- `relevant_files` with the actual knowledge-base-relative summary paths selected in this run
+- `delta_files` with the actual knowledge-base-relative summary paths that are new or changed for this run
 
-```json
-{
-  "version": 1,
-  "generated_at": "2026-03-30T20:00:00Z",
-  "knowledge_base_summary_count": 2500,
-  "relevant_files": ["summaries/file1.md", "summaries/file2.md"],
-  "delta_files": ["summaries/file1.md", "summaries/file2.md"]
-}
-```
-
-File paths in `relevant_files` and `delta_files` are relative to the knowledge base.
-
-Write retrieval proof to `.interf/coverage.json`:
-
-```json
-{
-  "version": 1,
-  "run_id": "run_abc123",
-  "interface": "briefing",
-  "generated_at": "2026-03-30T20:00:00Z",
-  "knowledge_base_summary_total": 3,
-  "frontmatter_scanned": 3,
-  "candidates_after_frontmatter": 2,
-  "abstracts_reviewed": 2,
-  "expansion_passes": 2,
-  "relevant_selected": 1,
-  "rejected": 2,
-  "coverage_complete": true,
-  "proof": {
-    "scanned": ["summaries/file1.md", "summaries/file2.md", "summaries/file3.md"],
-    "reviewed": ["summaries/file1.md", "summaries/file2.md"],
-    "retrieved": ["summaries/file1.md"],
-    "excluded": ["summaries/file2.md", "summaries/file3.md"]
-  }
-}
-```
+Do not paste placeholder filenames, canned totals, or copied sample counters into the runtime artifact.
+If `.interf/relevant.json` does not exist yet, create it in one complete write rather than trying to patch a missing file.
 
-Write retrieve results to `.interf/state.json`:
+Write retrieval proof to `.interf/coverage.json` in the current verifier shape. Include:
+- top-level `generated_at`
+- top-level counts derived from this run: `knowledge_base_summary_total`, `frontmatter_scanned`, `candidates_after_frontmatter`, `abstracts_reviewed`, `expansion_passes`, `relevant_selected`, `rejected`, `coverage_complete`
+- `proof.scanned` for the full scanned summary set
+- `proof.reviewed` for the candidate abstracts actually reviewed
+- `proof.retrieved` for the selected relevant set
+- `proof.excluded` for the excluded set
 
-```json
-{
-  "retrieve_complete": true,
-  "coverage_complete": true,
-  "frontmatter_scanned": 2500,
-  "candidate_count": 1200,
-  "abstracts_read": 1200,
-  "expansion_passes": 2,
-  "relevant_count": 1200,
-  "rejected_count": 1300,
-  "delta_count": 12,
-  "delta_files": ["summaries/file1.md", "summaries/file2.md"],
-  "last_retrieve": "2026-03-30T20:00:00Z"
-}
-```
+`proof.retrieved` plus `proof.excluded` must partition the scanned set for this run.
 
-Refresh `.interf/health.json` after state is updated. The health file is a computed verification surface for compile status and key metrics, not a prose summary.
+If `.interf/coverage.json` already exists, read it and then rewrite the complete JSON document. Do not patch old counters or timestamps line-by-line.
 If the retrieve stage reveals clear runtime gaps, preserve that signal for later stages via `.interf/analysis.json` or the next stage handoff rather than silently discarding it.
 
 Report to user with status-style lines:
 ```
-STATUS: loaded retrieve plan 2500 summary files.
-STATUS: scanned 2500/2500
-STATUS: reviewed 1200 abstracts, 2 expansion passes
-STATUS: selected 1200 relevant, 1300 rejected, 12 delta
+STATUS: loaded retrieve plan N summary files.
+STATUS: scanned N/N
+STATUS: reviewed M abstracts, P expansion passes
+STATUS: selected R relevant, X rejected, D delta
 DONE: retrieve complete
 ```
 
-When the retrieval proof, relevant set, state, and health files are written, emit the required `DONE:` line and stop. Do not keep exploring once retrieval closure is recorded.
+When the retrieval proof and relevant set 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 once retrieval closure is recorded.

package/skills/knowledge-base/compile/SKILL.md

@@ -32,33 +32,42 @@ If `.interf/stage-contract.json` exists, treat it as the authoritative stage con
 
 Use this sequence:
 - `STATUS: loaded compile plan N summary files`
-- `STATUS: inventoried N/N` after the inventory pass is complete
-- `STATUS: read X/N` after each deep-read batch or every 25 files, whichever comes first
-- `STATUS: wrote graph outputs` after `knowledge/` and `home.md` are updated
-- `DONE: compiled N/N` when `.interf/state.json` is updated successfully
+- `STATUS: inventoried summaries N/N` after the inventory pass is complete
+- `STATUS: read summary files X/N` after each deep-read batch or every 25 files, whichever comes first
+- `STATUS: wrote compile outputs` after `knowledge/` and `home.md` are updated
+- `DONE: compile complete N/N` when the required outputs are on disk
 
 If you are blocked or hit an unrecoverable issue, emit `BLOCKED:` or `ERROR:` once with the concrete reason.
+Keep scratch commands single-purpose and non-destructive. Do not start by deleting old outputs with `rm`, wildcard cleanup, `;`, or `&&` chains.
 
 ## Prerequisites check
 
-Read `.interf/state.json`. Compare `summarized` vs `compiled`.
+Read the stage contract, inventory, and summaries.
 
-- If `summarized == compiled` and both are current: "Knowledge base is up to date. Nothing to do." Stop.
-- If `summarized == 0` or source folder has unprocessed files: "File-evidence stage not ready yet." Stop.
+- If `summaries/` is missing or empty: "File-evidence stage not ready yet." Stop.
 - Otherwise: proceed.
 
+## Execution bias
+
+This stage builds a reusable substrate, not a full task-specific intelligence layer.
+
+- for small knowledge bases, prefer the smallest useful retrieval surface over graph sprawl
+- for a single report or small folder, do not invent dozens of entities or claims just because the source is rich
+- create only the entities, claims, and indexes that materially help later interface retrieval
+- if `.interf/stage-contract.json` says `summary_total <= 3`, treat the run as a tiny compile: read every summary overview, write the smallest truthful substrate, and stop
+- for a tiny compile, do not spend time designing an elaborate ontology or widening into raw-source exploration
+- a tiny compile is successful when it leaves a grounded home page plus a compact retrieval surface in `knowledge/` that later interfaces can build on
+- stop once the stable substrate exists; do not keep expanding the ontology out of curiosity
+
 ## Execution checklist
 
 ```
 Knowledge-base compile:
 - [ ] 1. Read interf.json
-- [ ] 2a. Inventory — scan ALL frontmatter, write .interf/inventory.json
-- [ ] 2b. Local evidence reading — batch-read abstracts/overviews, update inventory per file
-- [ ] 3. Canonicalize entities, threads, and aliases
-- [ ] 4. Extract cross-file claims and relationships
-- [ ] 5. Build retrieval indexes and navigation
-- [ ] 6. Update state (.interf/state.json)
-- [ ] 7. Validate
+- [ ] 2. Scan ALL summary frontmatter and write .interf/inventory.json
+- [ ] 3. Read the summary overviews needed for a minimal compile
+- [ ] 4. Write canonical entities, claims, indexes, and home.md
+- [ ] 5. Validate
 ```
 
 ### 1. Read interf.json + local stage docs
@@ -75,111 +84,76 @@ This is what you're working with. Every summary has:
 - `overview` / `key claims` → source-grounded detail for deeper reads
 
 The compile job is to turn these file-level evidence objects into a retrieval-ready knowledge base. Use the active stage contract plus any local docs listed by it for entity discovery rules, claim derivation logic, and quality requirements.
+Prefer source-domain entities over document-shell entities. A report PDF is evidence, not the main ontology. If a market report summary names covered markets, segments, publishers, or themes, compile those as the primary retrieval surface instead of centering the document title alone.
 
 ### 2. Scan summaries and create inventory
 
-This step has two phases — inventory (deterministic, must be complete) then analysis (can span sessions).
-
-**Phase A: Inventory (MUST be complete before any analysis)**
-
-Scan ALL summaries/ frontmatter. Every file. Write `.interf/inventory.json`:
-
-```json
-{
-  "total": 2460,
-  "files": [
-    {
-      "file": "summaries/readiness assessment language.md",
-      "source": "notes/readiness.md",
-      "source_kind": "note",
-      "evidence_tier": "primary",
-      "truth_mode": "stated",
-      "state": "active",
-      "frontmatter_scanned": true,
-      "abstract_read": false,
-      "full_read": false
-    }
-  ],
-  "summary_map": {
-    "source_kind": {"note": 340, "plan": 280},
-    "evidence_tier": {"primary": 600, "secondary": 400},
-    "truth_mode": {"stated": 700, "reported": 120},
-    "state": {"active": 640, "draft": 80}
-  }
-}
-```
-
-Verify: `total` in inventory MUST equal actual summaries/ file count. If not, stop.
+Scan ALL summaries/ frontmatter once. This step is deterministic and must complete before synthesis.
 
-This is deterministic — read frontmatter from every file, write the inventory. No analysis, no interpretation. Fast.
+Write `.interf/inventory.json`:
 
-**Phase B: Deep read (batched, resumable across sessions)**
+Write a full inventory ledger in the current runtime shape. At minimum:
+- `total` must equal the actual `summaries/` file count for this run
+- every summary must have a corresponding inventory entry
+- prefer the current `entries[]` runtime shape over legacy `files[]`
+- for current `entries[]` inventory entries, include at least `source`, `summary`, `frontmatter_scanned: true`, and the overview-read proof the validators use (`abstract`, `abstract_read: true`, or an equivalent current-state field)
+- per-summary entries should preserve the fields the runtime and validators use, such as file path, source path, source metadata, and whether frontmatter or deeper reads were completed
+- for legacy `files[]` inventory entries, use `frontmatter_scanned: true` after the frontmatter pass and `abstract_read: true` after the summary overview read
+- do not invent alternate flag names for those validator-facing fields
+- if you include `summary_map`, derive it from the current inventory instead of copying sample aggregates from docs
 
-Work through inventory.json. For each file where `abstract_read: false`:
-- Read the abstract section
-- Update inventory: `abstract_read: true`
-- Extract entity mentions, thread markers, and potential claims
+Verify: `total` in inventory MUST equal the actual summaries/ file count. If not, stop.
 
-For higher-weight files (`tier_1_authoritative`, `tier_2_direct_record`, or otherwise critical) where `full_read: false`:
-- Read the full overview
-- Update inventory: `full_read: true`
-- Extract deeper evidence
+Then read the summary overviews needed for synthesis:
 
-**Batching:** Process ~200 files per batch. After each batch:
-- Write updated inventory.json
-- Report progress: "Abstract read: 400/2460 (16%)"
+- if `N <= 25`, read every summary overview
+- if `N > 25`, read all high-signal summaries plus enough additional summaries to build a stable substrate
+- if `N <= 3`, move directly from those overview reads into the smallest honest compile outputs; do not turn a tiny knowledge base into an open-ended graph-design pass
 
-If the session ends mid-batch, the next run reads inventory.json and continues from where it left off. No work is lost.
+Do not turn this into an open-ended archival pass. The compile stage should finish in one run for normal small knowledge bases.
 
 ### 3. Canonicalize entities, threads, and aliases
 
-**Prerequisite:** inventory.json must have ALL files scanned (frontmatter_scanned: true). Deep reads (abstract_read) should be substantially complete — at least 80% of files. If not, continue Phase B first.
+**Prerequisite:** inventory.json must cover all summaries, and the overview reads above must be complete for the working set.
 
 Use the inventory summary_map plus deep-read evidence to identify canonical entities and recurring threads. Create canonical notes in knowledge/entities/ for recurring actors:
 - people, companies, products, concepts, projects, and durable threads
+- for reports, datasets, and decks, create entities for the covered domain objects when the summary makes them explicit (for example markets, publishers, regions, products, or benchmark topics)
 - Resolve aliases to one canonical note
 - Include: summary, evidence links, related entities, first/last seen
 - Prefer explicit wikilinks to related summaries, entities, and claims so future agents can climb outward through backlinks instead of rereading from scratch
+- For a single report or other small KB, prefer a compact set of 2-6 high-signal entities over exhaustive decomposition.
 
 ### 4. Extract cross-file claims and relationships
 
-**Prerequisite:** Same as entities — inventory must be complete.
+**Prerequisite:** Same as entities.
 
 Use inventory data plus deep reads to identify patterns across files. Create notes in knowledge/claims/ for cross-file observations:
 - Must have 2+ supporting sources unless explicitly marked unresolved or exploratory
 - Use prose-as-title: filename IS the claim
 - Include: the claim, why it matters, evidence links, and a clear sense of evidence strength
 - Link claims back to the supporting summaries and related entities so navigation can move claim -> evidence -> source trail cleanly
+- For a single report or small KB, 1-4 strong claims are enough when they capture the main retrieval surface.
 
 ### 5. Build retrieval indexes and navigation
 
 Create aggregate navigation in knowledge/indexes/:
-- People.md, Companies.md, Timeline.md, Themes.md, Projects.md, Threads.md
+- Keep a stable core set first: Companies.md, Markets.md, Themes.md
+- Add extra indexes only when the source base clearly supports them and they do not replace the stable core set
+- For a single report or dataset, prefer report-shaped indexes over generic People/Projects/Timeline scaffolding
 - Link to canonical entities, high-signal summaries, and major claims
 - Make the result useful for interface creation and retrieve, not just for human browsing
 - Treat backlinks as part of the retrieval surface: notes should make it obvious how to move from a high-level concept to the supporting summaries and back again
+- If the KB is very small, keep the indexes short and direct instead of expanding them into standalone essays.
+- For a tiny compile, it is enough for the stable core indexes to be short landing notes that route later interface stages toward the real evidence.
 
 Update `home.md` every compile run so it becomes the knowledge-base landing layer for agents.
+Include the source count, the high-signal scope of the knowledge base, and links to the stable core indexes.
 
-### 6. Update state
-
-Update `.interf/state.json` with proof of work:
-
-```json
-{
-  "compiled": 2460,
-  "last_compile": "2026-03-30T18:10:00Z",
-  "entity_count": 85,
-  "claim_count": 142,
-  "inventory_complete": true,
-  "abstracts_read": 2460,
-  "full_reads": 400
-}
-```
-
-The inventory at `.interf/inventory.json` has per-file detail. State.json has the summary. Both must be consistent. If `abstracts_read` < total, the compile is incomplete — next run continues.
+### 6. Runtime reconciliation
 
-Refresh `.interf/health.json` after state is updated. The CLI refreshes `.interf/view-spec.json` after stage completion so viewers keep a stable knowledge-base-level presentation contract.
+The CLI reconciles `.interf/state.json`, refreshes `.interf/health.json`, and refreshes `.interf/view-spec.json` after stage validation so viewers keep a stable knowledge-base-level presentation contract.
+Rewrite outputs directly instead of clearing `knowledge/` or `.interf/` first. If a stale artifact truly must go away, remove only that explicit path after the replacement files are already written.
 
 ### 7. Validate
 
@@ -188,6 +162,7 @@ Refresh `.interf/health.json` after state is updated. The CLI refreshes `.interf
 - [ ] Claims preserve evidence strength and do not overstate exploratory material
 - [ ] No wikilinks to nonexistent files
 - [ ] home.md is current
+- [ ] The result is compact enough that an interface stage can reuse it without re-reading a bloated local graph
 
 ## Graph quality rules
 
@@ -196,6 +171,7 @@ Refresh `.interf/health.json` after state is updated. The CLI refreshes `.interf
 - Repair broken wikilinks
 - Prefer explicit wikilinks over vague prose
 - Use properties for machine filtering, tags for Obsidian surfacing
+- Prefer a small stable graph over speculative expansion
 
 After compile, prefer running:
 
@@ -208,11 +184,11 @@ If it fails, fix inventory/state/output consistency before treating the knowledg
 Report:
 ```
 Step 2/2 complete — Knowledge-base compile
-Entities: 85, Claims: 142
+Entities: <entity_count>, Claims: <claim_count>
 home.md updated.
 ```
 
-When the required outputs, state, and health files are written, emit the required `DONE:` line and stop. Do not keep browsing or auditing after the compile contract is satisfied.
+When the required outputs and inventory are written, emit the required `DONE:` line and stop. Do not keep browsing or auditing after the compile contract is satisfied.
 
 ## What this skill does NOT do
 

package/skills/knowledge-base/compile/references/stage-claims.md

@@ -22,7 +22,7 @@ Do NOT create claims from single observations unless marked as unresolved/hypoth
 
 Use prose-as-title: the filename IS the claim.
 
-Example filename: `GATHR and Aon act as paid R&D for the product thesis.md`
+Example filename: `{subject} acts as {relationship} for {entity}.md`
 
 ```markdown
 ---

package/skills/knowledge-base/compile/references/stage-entities.md

@@ -8,7 +8,7 @@ Create canonical notes in knowledge/entities/ for recurring actors in the knowle
 2. Scan overviews for company names, product names, concepts
 3. For each actor appearing 3+ times:
    - Create a canonical entity note
-   - Resolve aliases (e.g., "Matt" and "Matteo" → one note)
+   - Resolve aliases (e.g., "{Short name}" and "{Full name}" -> one note)
    - Link to all supporting summaries/ files via wikilinks
 
 ## Entity note format
@@ -41,6 +41,6 @@ Create canonical notes in knowledge/entities/ for recurring actors in the knowle
 ## Alias resolution
 
 When multiple names refer to the same actor:
-- Pick the most complete name as canonical (e.g., "Matteo Cassese" not "Matt")
+- Pick the most complete name as canonical (e.g., "{Full Name}" not "{Nickname}")
 - Mention aliases in the summary
 - All evidence links point to the one canonical note

package/skills/knowledge-base/query/SKILL.md

@@ -20,11 +20,23 @@ Default loop:
 - follow wikilinks and backlinks outward before treating one note as complete
 - use `summaries/` for deeper evidence
 - use raw source files only when needed for verification, direct quotes, ambiguity, or missing context
+- when a caller asks for a trace, audit log, or `artifacts_consulted` list, record `workflow/use/query/SKILL.md` after you inspect it
 
 Raw-source gate:
 - inspect `.interf/source-access.json`
-- verify one `suggested_checks` path is actually readable from this session before claiming raw-file verification
+- actually open and inspect at least one `suggested_checks` path before claiming raw-file verification; a plain existence check is not enough
+- when a caller asks for a trace, audit log, or `artifacts_consulted` list, record `.interf/source-access.json` after you inspect it
 - if the path is not reachable or permission is not granted, say the answer is based on compiled knowledge-base artifacts only
+- when the question depends on exact figures, direct quotes, chart values, table values, or image-derived evidence, raw inspection is required before answering confidently
+
+PDF / chart rule:
+- if the source is a PDF, deck, or report and the needed evidence may live in charts, tables, or figures, do not assume the default text layer or existing notes captured everything
+- if summaries do not preserve the needed numeric detail, inspect the raw source and say whether the value was text-derived, table-derived, or chart-derived
+- opening the PDF with `Read` is not enough for an exact-value chart question; take a machine-readable extraction path before answering
+- if the first local extraction method misses the number, attempt another local recovery path before settling for a visual estimate
+- if the default local extraction path still cannot reach the value, switch methods before stopping early; a temporary scratch helper outside the workspace is allowed when needed
+- if the chart does not expose exact numbers as text, say that clearly instead of pretending the compiled notes were sufficient
+- if you can only estimate from the chart, label the answer `approximate` and keep the precision gap explicit
 
 When confidence is low:
 - expand outward through linked claims, entities, indexes, and summaries