@interf/compiler 0.22.0 → 0.33.0

package/public-repo/build-plans/interf-default/build/stages/shape/SKILL.md

@@ -1,27 +1,34 @@
 # Shape
 
-Shape the final verifiable context around the saved task focus and readiness checks.
+Shape the task-specific Artifact handoff and final Context Graph index
+around the saved task focus and Checks.
 
 Contract type: `build-query-shape`
 
 ## Requirements
 
-- Use the Build run task focus plus saved readiness-check text to shape `home.md` and retrieval routes.
-- Rewrite `home.md` into a real entrypoint note. Do not leave the scaffold `Not yet built.` placeholder in place.
-- When you add wikilinks, target real verifiable-context notes by exact basename or explicit relative path.
+- Use the Build task focus plus saved Check text to shape `artifacts/` handoffs and supporting graph routes.
+- Write at least one task-specific handoff note under `artifacts/`.
+- Each Artifact handoff must start with JSON frontmatter containing non-empty `task`, `source_refs`, `handoff_type`, `truth_mode`, `verification_state`, and `caveats`.
+- `source_refs` must point to original Source locations, not just generated summaries or knowledge notes.
+- Artifact handoff notes should tell the downstream agent which original Source files, pages, figures, tables, sections, units, periods, series, and caveats matter for the task.
+- Artifact handoff notes should route the downstream agent to original Source refs for exact claims. Do not present generated summaries or knowledge notes as the dataset or source of truth.
+- Rewrite `home.md` into a real graph index note. Do not leave the scaffold `Not yet built.` placeholder in place, and do not make `home.md` the answer surface.
+- When you add wikilinks, target real Context Graph notes by exact basename or explicit relative path.
 - If you introduce a new note name in `home.md` or another shaped output, the same stage must also create that note file.
 - Prefer direct file-reading and search tools over shell commands for routine file inspection.
 - When a source value is approximate, preserve it as a bounded range and say why it is approximate.
 - Do not invent finer precision than the source supports.
+- For unlabeled charts, screenshots, diagrams, or visual marks, either create a measurement note with source-grounded visual reference, calibration, method, and uncertainty, or tell the downstream agent to inspect the original Source before answering.
 - Keep approximate values consistent across `home.md`, focused indexes, and claim/entity notes.
-- Do not copy expected answers into the verifiable context.
+- Do not copy expected answers into the Context Graph.
 
 ## Notes
 
-- Use the saved task focus and readiness checks to bias the final verifiable context toward the job it should be especially good at.
-- Do not copy expected answers into the final verifiable context just because the checks imply them.
-- Prefer the saved summary evidence and structured notes when they already preserve the bounded chart/table reads plus provenance you need.
-- Reopen source references during shaping only when the verifiable context is missing the needed value, the metric family is ambiguous, or the earlier bounded read is clearly inconsistent.
-- If a saved readiness check depends on source-derived values, carry the final bounded values into focused notes with provenance instead of repeatedly recomputing them from source files.
+- Use the saved task focus and Checks to bias the final Context Graph toward the job it should be especially good at.
+- Do not copy benchmark expected answers into the final Context Graph.
+- Prefer the saved summary evidence and structured notes when they already preserve routing, source refs, and caveats.
+- Reopen source references during shaping when exact wording, table values, chart reads, or provenance-sensitive claims matter.
+- If a saved Check depends on source-derived values, route the handoff to source refs and preserve source granularity instead of fabricating precision.
 - Prefer better routing, prioritization, and focused navigation over speculative synthesis.
-- Any wikilinks you add to `home.md` or indexes must resolve to real verifiable-context note basenames or explicit relative paths.
+- Any wikilinks you add to `home.md` or indexes must resolve to real Context Graph note basenames or explicit relative paths.

package/public-repo/build-plans/interf-default/build/stages/structure/SKILL.md

@@ -1,13 +1,19 @@
 # Structure
 
-Build the cross-file knowledge structure from the summaries.
+Build the task-aware Context Graph structure from the summaries.
 
 Contract type: `build-knowledge-structure`
 
 ## Requirements
 
-- Treat the knowledge layer as retrieval structure, not final truth.
+- Treat the Context Graph structure as retrieval support, not final truth.
 - Prefer durable entity, claim, and index notes over one giant catch-all file.
+- Write those notes as flat markdown files under `knowledge/` unless this
+  Build Plan explicitly declares typed child folders.
+- Keep claims connected to the summaries and original source references that
+  support them, so users can follow links back to sources.
+- Use knowledge notes as navigation and assurance. They are not the authority
+  for exact wording, table values, chart reads, or provenance-sensitive claims.
 - Keep structure-stage links stage-local: prefer linking only to summaries or knowledge notes that are already meaningful by the end of this stage. Avoid relying on `home.md` or other shape-stage routes as the main navigation surface.
 - Prefer direct file-reading and search tools over shell commands for routine file inspection.
 
@@ -15,7 +21,8 @@ Contract type: `build-knowledge-structure`
 
 - Bias structure toward canonical entities, claims, timelines, and stable indexes.
 - Use taxonomy and ontology only as means to improve retrieval, navigation, and evidence tracking.
-- For small source folders, prefer a minimal stable substrate over exhaustive graph sprawl.
-- When you add wikilinks, target real verifiable-context notes by exact basename or explicit relative path. Do not invent title-style links unless that exact title is also a declared note label or alias.
+- For small Sources, prefer a minimal stable substrate over exhaustive flow sprawl.
+- When you add wikilinks, target real Context Graph notes by exact basename or explicit relative path. Do not invent title-style links unless that exact title is also a declared note label or alias.
 - Do not add wikilinks in structure outputs to files that the shape stage creates later. If a route belongs in `home.md` or a later shaped note, leave plain text now and let the later stage add the link.
-- For summary references, prefer explicit links like `[[summaries/<file-stem>]]` or plain code paths. For knowledge notes, prefer the final filename stem under `knowledge/`.
+- Build task-aware claims, entities, topics, and indexes from the summaries and their source refs. Use clear filenames such as `knowledge/rent-growth-claims.md`, `knowledge/market-entities.md`, or `knowledge/index.md`.
+- For summary references, prefer explicit links like `[[summaries/<source-name>/summary]]`, `[[summaries/<source-name>/manifest]]`, page note links, or plain source refs. For knowledge notes, prefer the final filename stem under `knowledge/`.

package/public-repo/build-plans/interf-default/build/stages/summarize/SKILL.md

@@ -1,6 +1,6 @@
 # Summarize
 
-Turn source files into per-file summaries.
+Turn source files into source-named coverage folders with source metadata.
 
 Contract type: `build-file-evidence`
 
@@ -10,7 +10,10 @@ Contract type: `build-file-evidence`
 - Required opening shape:
 - `---`
 - `{`
+- `  "source_file_id": "file-example",`
 - `  "source": "example.md",`
+- `  "source_path": "example.md",`
+- `  "source_locator": "agent-readable/source/ref",`
 - `  "source_kind": "markdown",`
 - `  "evidence_tier": "primary",`
 - `  "truth_mode": "source-grounded",`
@@ -25,11 +28,20 @@ Contract type: `build-file-evidence`
 - a markdown heading `## Abstract` followed by at least one sentence
 - A bare `Abstract` label without markdown heading syntax does not count.
 - Do not skip the abstract just because the overview section is present.
+- Build `summaries/` as a coverage layer:
+  - one folder per source file, named so a human can match it to the original source file
+  - non-paginated sources: `summaries/<source-name>/summary.md`
+  - PDFs, decks, images, or paginated/visual reports: `summaries/<source-name>/manifest.md` plus `pages/001/summary.md`, `pages/002/summary.md`, etc. for every page/slide that can be inspected
+  - if a page/slide cannot be extracted, record `not_extracted_reason` in the manifest instead of silently skipping it
+  - optional `screenshot.png` or visual trace paths only when useful and available
+- Preserve links back to sources through the `source_file_id`, `source`, `source_path`, `source_locator`, page,
+  section, table, chart, figure, or region references the source provides.
+- Do not copy source files into the Context Graph. Store source references.
 
 ## Notes
 
 - Favor conservative, source-grounded summaries that preserve evidence tiers and leave broader synthesis for later stages.
-- Read `runtime/stage-inputs.json` for the exact source references assigned to this stage.
-- For large reports or decks, capture scope, headline evidence, and chart/table routing in one light pass.
-- As soon as one report summary can state scope, headline metrics, and chart/table routing, stop reading and write the summary batch plus runtime artifacts immediately.
+- Read `runtime/source-manifest.json` for the authoritative Source inventory and `runtime/stage-inputs.json` for the exact source references assigned to this stage.
+- For large reports or decks, capture page coverage, scope, headline evidence, and chart/table routing in one light pass. Prefer explicit page records over one loose file summary.
+- Summaries prove coverage; they do not need to answer the final task.
 - Keep scratch extraction commands single-purpose and non-destructive.

package/public-repo/build-plans/interf-default/build-plan.json

@@ -1,13 +1,13 @@
 {
   "id": "interf-default",
   "type": "build-plan",
-  "engine_api": {
+  "runtime_api": {
     "kind": "build",
     "version": 1
   },
   "purpose": {
-    "label": "Built-in Build Plan for verifiable context",
-    "task_hint": "Build mixed source files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents running the readiness checks this agent work depends on."
+    "label": "Build Context Graph",
+    "task_hint": "Build mixed source files into a three-layer Context Graph: summaries for coverage, knowledge for task-aware structure, and artifacts for downstream agent handoff with links back to original sources."
   },
   "inputs": [
     {
@@ -18,13 +18,14 @@
     }
   ],
   "label": "Built-in Interf Build Plan",
-  "hint": "Built-in file-processing Build Plan: build traceable artifacts with proof by summarizing source-grounded evidence, structuring cross-file connections, and shaping verifiable context around the saved readiness checks.",
+  "hint": "Built-in Build Plan that builds a Context Graph with source coverage summaries, task-aware knowledge, requested Artifact handoffs, links back to sources, Build evidence, and traces.",
   "stages": [
     {
       "id": "summarize",
       "label": "Summarize",
-      "description": "Turn source files into per-file summaries.",
+      "description": "Turn source files into source-named coverage folders under summaries/, with summary.md or manifest.md plus page/slide notes for every inspectable paginated or visual source page.",
       "contract_type": "build-file-evidence",
+      "role": "summarizer",
       "skill_dir": "summarize",
       "reads": [],
       "writes": [
@@ -34,57 +35,62 @@
     {
       "id": "structure",
       "label": "Structure",
-      "description": "Build the cross-file knowledge structure from the summaries.",
+      "description": "Build the task-aware knowledge graph from summaries as flat knowledge/*.md notes, including claims, entities, topics, indexes, and links back to source refs.",
       "contract_type": "build-knowledge-structure",
+      "role": "structurer",
       "skill_dir": "structure",
       "reads": [
         "summaries"
       ],
       "writes": [
-        "knowledge-entities",
-        "knowledge-claims",
-        "knowledge-indexes"
+        "knowledge"
       ]
     },
     {
       "id": "shape",
       "label": "Shape",
-      "description": "Shape the final verifiable context around the saved task focus and readiness checks.",
+      "description": "Shape task-specific Artifact handoffs and the Context Graph index around the saved task focus and Context Checks.",
       "contract_type": "build-query-shape",
+      "role": "structurer",
       "skill_dir": "shape",
       "reads": [
         "summaries",
-        "knowledge-entities",
-        "knowledge-claims",
-        "knowledge-indexes"
+        "knowledge"
       ],
       "writes": [
-        "knowledge-indexes",
-        "atlas"
+        "knowledge",
+        "artifacts",
+        "home"
       ]
     }
   ],
   "stage_policy_notes": {
     "summarize": [
-      "Favor conservative, source-grounded summaries that preserve evidence tiers and leave broader synthesis for later stages.",
-      "For large reports or decks, capture scope, headline evidence, and chart/table routing in one light pass.",
-      "As soon as one report summary can state scope, headline metrics, and chart/table routing, stop reading and write the summary batch plus runtime artifacts immediately.",
+      "Favor conservative, source-grounded summaries that prove coverage and preserve evidence tiers; leave broader synthesis for later stages.",
+      "Create one folder under `summaries/` per source file, named so a human can match it to the original source file.",
+      "For non-paginated sources, write `summaries/<source-name>/summary.md`.",
+      "For PDFs, decks, images, or paginated/visual reports, write `summaries/<source-name>/manifest.md` and page or slide folders such as `pages/001/summary.md` for every page/slide that can be inspected. If a page/slide cannot be extracted, record `not_extracted_reason` in the manifest instead of silently skipping it. Include optional screenshots or visual trace paths only when useful and available.",
+      "Every summary or page note must link back to the original Source path and the relevant page, section, figure, table, or region. Do not copy source files into the Context Graph.",
       "Keep scratch extraction commands single-purpose and non-destructive."
     ],
     "structure": [
-      "Bias structure toward canonical entities, claims, timelines, and stable indexes.",
-      "Use taxonomy and ontology only as means to improve retrieval, navigation, and evidence tracking.",
-      "For small Source Folders, prefer a minimal stable substrate over exhaustive graph sprawl.",
-      "When you add wikilinks, target real verifiable-context notes by exact basename or explicit relative path. Do not invent title-style links unless that exact title is also a declared note label or alias.",
+      "Build task-aware claims, entities, topics, and indexes from the summaries and their source refs as flat markdown notes under `knowledge/`.",
+      "Use taxonomy and ontology only when it improves retrieval, navigation, and evidence tracking.",
+      "Treat knowledge notes as navigation and assurance, not as the authority for exact wording, table values, chart reads, or provenance-sensitive claims.",
+      "For small Sources, prefer a minimal stable graph over exhaustive note sprawl.",
+      "When you add wikilinks, target real Context Graph notes by exact basename or explicit relative path. Do not invent title-style links unless that exact title is also a declared note label or alias.",
       "Do not add wikilinks in structure outputs to files that the shape stage creates later. If a route belongs in `home.md` or a later shaped note, leave plain text now and let the later stage add the link.",
-      "For summary references, prefer explicit links like `[[summaries/<file-stem>]]` or plain code paths. For knowledge notes, prefer the final filename stem under `knowledge/`."
+      "For summary references, prefer explicit links like `[[summaries/<source-name>/summary]]`, `[[summaries/<source-name>/manifest]]`, or plain source refs. For knowledge notes, prefer final filenames under `knowledge/`."
     ],
     "shape": [
-      "Use the saved task focus and readiness checks to bias the final verifiable context toward the job it should be especially good at.",
-      "Do not copy expected answers into the final verifiable context just because the checks imply them.",
-      "If a saved readiness check depends on source-derived values that may be approximate, preserve the stated range, limits, and provenance.",
-      "Prefer better routing, prioritization, and focused navigation over speculative synthesis.",
-      "Any wikilinks you add to `home.md` or indexes must resolve to real verifiable-context note basenames or explicit relative paths."
+      "Use the saved task focus and Context Checks to bias the final Context Graph toward the agent task it should be especially good at.",
+      "Do not copy benchmark expected answers into the final Context Graph.",
+      "Write one or more notes under `artifacts/` as the downstream agent handoff. These notes should tell the agent which original Source files, pages, figures, tables, sections, units, periods, series, and caveats matter.",
+      "Artifacts should route the agent to original Source refs for exact claims. Do not present generated summaries or knowledge notes as the dataset or source of truth.",
+      "If a saved Context Check depends on source-derived values that may be approximate, preserve the stated range, limits, evidence tier, and source inspection requirement.",
+      "For unlabeled charts or visual marks, either create a measurement note with visual reference, calibration, method, and uncertainty, or tell the downstream agent to inspect the original Source before answering.",
+      "Prefer better routing, prioritization, and focused navigation over speculative synthesis or answer-only notes.",
+      "Any wikilinks you add to `home.md` or indexes must resolve to real Context Graph note basenames or explicit relative paths."
     ]
   }
 }

package/public-repo/build-plans/interf-default/build-plan.schema.json

@@ -1,75 +1,97 @@
 {
   "kind": "build-plan-schema",
   "version": 1,
-  "target_type": "verifiable-context",
+  "target_type": "context-graph",
   "label": "Interf built-in Build Plan schema",
   "artifacts": [
     {
-      "id": "atlas",
-      "description": "Primary entrypoint note that agents read first. Routes to summaries, knowledge entities, claims, and indexes.",
+      "id": "home",
+      "description": "Context Graph index note. Routes to the summaries coverage layer, knowledge graph layer, and task-specific Artifact handoffs; downstream agents should start from artifacts/ for task work.",
       "shape": { "kind": "path", "path": "home.md", "artifact_kind": "file" },
       "checks": [
-        { "id": "exists", "kind": "file_exists", "required": true },
+        { "id": "exists", "kind": "file_exists", "description": "The graph index note exists.", "required": true },
         {
           "id": "no-placeholder",
           "kind": "must_not_contain",
+          "description": "The graph index note does not contain placeholder text.",
           "required": true,
           "params": { "phrases": ["Not yet built."] }
         },
-        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
+        { "id": "wikilinks", "kind": "wikilinks_valid", "description": "Every graph index wikilink resolves.", "required": true }
       ],
       "built_by_stages": ["shape"]
     },
     {
       "id": "summaries",
-      "description": "Per-file evidence notes that preserve the source-grounded synthesis agents quote against.",
+      "description": "Coverage layer with one source-named folder per source file. Non-paginated sources have summary.md. PDFs, decks, and visual/paginated sources include manifest.md plus page/slide folders for every inspected page/slide; uninspected pages/slides must be called out with not_extracted_reason. Every note links back to the original Source path and page/section/figure/table refs instead of copying source files.",
       "shape": { "kind": "path", "path": "summaries", "artifact_kind": "directory" },
       "checks": [
         {
-          "id": "all-files-summarized",
-          "kind": "min_file_count_matches_source",
+          "id": "source-summary-folders",
+          "kind": "source_summary_folders",
+          "description": "Every source file has a source-named folder with summary.md or manifest.md.",
           "required": true,
           "params": { "match": "source_total" }
         },
-        { "id": "frontmatter-valid", "kind": "frontmatter_valid", "required": true },
+        { "id": "frontmatter-valid", "kind": "frontmatter_valid", "description": "Every summary note has valid frontmatter.", "required": true },
         {
           "id": "evidence-keys",
           "kind": "frontmatter_required_keys",
+          "description": "Every summary note records source and evidence metadata.",
           "required": true,
-          "params": { "keys": ["source", "source_kind", "evidence_tier", "truth_mode", "state"] }
+          "params": { "keys": ["source", "source_file_id", "source_path", "source_locator", "source_kind", "evidence_tier", "truth_mode", "state"] }
         }
       ],
       "built_by_stages": ["summarize"]
     },
     {
-      "id": "knowledge-entities",
-      "description": "Canonical entity notes that anchor the cross-file knowledge structure.",
-      "shape": { "kind": "path", "path": "knowledge/entities", "artifact_kind": "directory" },
+      "id": "knowledge",
+      "description": "Task-aware Context Graph layer built from summaries and source refs. Current default is flat knowledge/*.md notes. Notes may contain claims, entities, topics, and indexes, but remain navigation and assurance rather than the authority for exact source claims.",
+      "shape": { "kind": "path", "path": "knowledge", "artifact_kind": "directory" },
       "checks": [
-        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
-        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
+        { "id": "exists", "kind": "min_file_count", "description": "Knowledge layer contains notes for task-aware navigation.", "required": true, "params": { "min": 3 } },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "description": "Every knowledge wikilink resolves.", "required": true }
       ],
-      "built_by_stages": ["structure"]
-    },
-    {
-      "id": "knowledge-claims",
-      "description": "Claim notes extracted from summaries with evidence references.",
-      "shape": { "kind": "path", "path": "knowledge/claims", "artifact_kind": "directory" },
-      "checks": [
-        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
-        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
-      ],
-      "built_by_stages": ["structure"]
+      "built_by_stages": ["structure", "shape"]
     },
     {
-      "id": "knowledge-indexes",
-      "description": "Retrieval indexes and navigation notes for the knowledge structure.",
-      "shape": { "kind": "path", "path": "knowledge/indexes", "artifact_kind": "directory" },
+      "id": "artifacts",
+      "description": "Task-specific requested Artifact handoffs for downstream agents. These notes point to original Source files, pages, figures, tables, sections, units, periods, and caveats; they may link to summaries or knowledge notes for drilldown, but source files remain the authority for exact claims.",
+      "shape": { "kind": "path", "path": "artifacts", "artifact_kind": "directory" },
       "checks": [
-        { "id": "exists", "kind": "min_file_count", "required": true, "params": { "min": 1 } },
-        { "id": "wikilinks", "kind": "wikilinks_valid", "required": true }
+        { "id": "exists", "kind": "min_file_count", "description": "At least one task-specific Artifact handoff note exists.", "required": true, "params": { "min": 1 } },
+        { "id": "frontmatter-valid", "kind": "frontmatter_valid", "description": "Every Artifact handoff note has valid frontmatter.", "required": true },
+        {
+          "id": "handoff-frontmatter",
+          "kind": "frontmatter_required_keys",
+          "description": "Every Artifact handoff records task, source reference, and verification posture.",
+          "required": true,
+          "params": { "keys": ["task", "source_refs", "handoff_type", "truth_mode", "verification_state", "caveats"] }
+        },
+        {
+          "id": "handoff-source-refs",
+          "kind": "source_refs_required",
+          "description": "Every Artifact handoff has non-empty source refs.",
+          "required": true,
+          "params": { "keys": ["source_refs"] }
+        },
+        {
+          "id": "handoff-nonempty-fields",
+          "kind": "frontmatter_nonempty_keys",
+          "description": "Every Artifact handoff has non-empty task, source refs, verification state, and caveats.",
+          "required": true,
+          "params": { "keys": ["task", "source_refs", "verification_state", "caveats"] }
+        },
+        {
+          "id": "source-authority-caveat",
+          "kind": "must_contain",
+          "description": "Artifact handoffs tell agents to follow original Source refs for exact claims.",
+          "required": true,
+          "params": { "phrases": ["original Source", "source refs"] }
+        },
+        { "id": "wikilinks", "kind": "wikilinks_valid", "description": "Every Artifact handoff wikilink resolves.", "required": true }
       ],
-      "built_by_stages": ["structure", "shape"]
+      "built_by_stages": ["shape"]
     }
   ]
 }

package/public-repo/build-plans/interf-default/improve/SKILL.md

@@ -7,12 +7,12 @@ The improver edits this local Build Plan directly.
 
 Default loop:
 1. Read the loop context first.
-2. Review preserved stage shells, runtime logs, and saved test runs from failed attempts.
-3. Edit only the local Build Plan for this verifiable context to create a better implementation for this agent work.
+2. Review preserved stage shells, runtime logs, and saved benchmark runs from failed attempts.
+3. Edit only the local Build Plan for this Context Graph to create a better implementation for this agent task.
 4. Keep `build-plan.json`, `build-plan.schema.json`, and any changed stage docs aligned.
 
 Guardrails:
-- do not edit checks, test specs, or source files
+- do not edit checks, benchmark specs, or source files
 - do not hardcode expected answers into Build Plan docs
 - keep this package standalone; do not rely on runtime inheritance
 - prefer small, defensible Build Plan changes over random churn

package/public-repo/build-plans/interf-default/use/query/SKILL.md

@@ -3,21 +3,27 @@
 This file is the editable authoring source for the generated native local `interf-query` skill.
 
 Default loop:
-1. Read `home.md` first.
-2. Browse `knowledge/` before source re-checks.
-3. Use `summaries/` for source-grounded evidence.
-4. Use `.interf/runtime/source-snapshot.json` for direct quotes, verification, and exact source lookups.
+1. Read `.interf/build-plan/README.md` and this file first.
+2. Read the relevant notes under `artifacts/` first. Artifact handoffs are the default task handoff surface for the agent.
+3. Use `home.md` only when you need a graph index to find the right Artifact handoff.
+4. Browse `knowledge/` and `summaries/` only when the Artifact handoff needs drilldown, broader context, or debugging.
+5. Use `.interf/runtime/source-manifest.json` and Artifact source refs to follow graph-provided source references for direct quotes, exact values, visual/table verification, and provenance-sensitive claims.
 
 Answering rule:
 - do not modify source files while answering
+- use the Context Graph as the knowledge map, not as a raw-source replacement
+- do not bypass the graph with ad hoc source browsing; drill into source only through graph-provided source references, traces, requested Artifacts, or the recorded Source Manifest
+- start from `artifacts/`; treat Artifact handoffs as routing and source-evidence maps, not as a replacement dataset
+- use `summaries/` for coverage proof and `knowledge/` for navigation/drilldown; do not treat generated knowledge notes as the authority for exact claims
+- when exact wording, table values, chart positions, visual ranges, or provenance matter, follow the cited source reference before making a strong claim
 - when a number is approximate or source-derived from a visual, say that explicitly
-- if the verifiable context already contains a bounded value for the exact metric and period the user asked about, answer from that value first
-- use source references to confirm the source page, metric family, or provenance, not to replace a good bounded read with a mismatched range
-- when the verifiable context preserves a bounded range, keep that bounded range in the answer instead of collapsing it to a midpoint or pseudo-exact single value
+- if the Context Graph already contains a bounded value for the exact metric and period the user asked about, verify the cited source reference when precision matters, then answer from that bounded value
+- use source references to confirm the source page, metric family, visual series, axis/range, period, unit, and provenance
+- when the Context Graph preserves a bounded range, keep that bounded range in the answer instead of collapsing it to a midpoint or pseudo-exact single value
 - match the source granularity and do not invent finer precision than the source supports
-- when reading visuals, verify you are on the correct metric family and period before answering
-- keep annual, quarterly, sector, and snapshot metrics separate unless the source explicitly connects them
+- when reading visuals, verify you are on the correct metric family and period before making a claim
+- keep annual, quarterly, sector, and point-in-time metrics separate unless the source explicitly connects them
 - if multiple notes mention the same value, keep the answer consistent with the most focused note rather than synthesizing a new midpoint or shifted range
-- when the verifiable context is insufficient, verify against source references and then answer
+- when the Context Graph is insufficient but points to the right source evidence, improve or rebuild if the missing semantics are part of the requested Artifact contract; do not present a blurry artifact as ready
 
-You can edit this file to bias manual question-answering behavior for this verifiable context.
+You can edit this file to bias manual question-answering behavior for this Context Graph.