@ara-commons/ara-skills 0.3.1 → 0.4.1

package/README.md

@@ -1,12 +1,13 @@
 # @ara-commons/ara-skills
 
-One-command installer for the three **Agent-Native Research Artifact (ARA)** skills:
+One-command installer for the four **Agent-Native Research Artifact (ARA)** skills:
 
 | Skill | Invoke | What it does |
 |-------|--------|--------------|
 | `compiler`         | `/compiler <input>`        | Convert a paper, repo, or notes into a complete ARA artifact |
 | `research-manager` | `/research-manager`        | Post-session recorder that captures decisions, dead ends, and claims |
 | `rigor-reviewer`   | `/rigor-reviewer <dir>`    | ARA Seal Level 2 semantic epistemic review across six dimensions |
+| `research-visualizer` | `/research-visualizer <dir>` | Render an ARA into one interactive, self-contained trajectory.html |
 
 ## Quick start
 
@@ -64,4 +65,4 @@ In dev mode the CLI reads skills from the sibling `../../skills/` directory. On
 
 ## Upstream source of truth
 
-The three skill directories live at the repo root under `skills/`. Edit them there — never edit the copy inside this package, which is created on demand by `prepack`.
+The four skill directories live at the repo root under `skills/`. Edit them there — never edit the copy inside this package, which is created on demand by `prepack`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ara-commons/ara-skills",
-  "version": "0.3.1",
-  "description": "Install Agent-Native Research Artifact (ARA) skills — compiler, research-manager, rigor-reviewer — into Claude Code, Cursor, OpenCode, Gemini CLI, Codex, and more.",
+  "version": "0.4.1",
+  "description": "Install Agent-Native Research Artifact (ARA) skills — compiler, research-manager, rigor-reviewer, research-visualizer — into Claude Code, Cursor, OpenCode, Gemini CLI, Codex, and more.",
   "type": "module",
   "bin": {
     "ara-skills": "./bin/cli.js"
@@ -33,6 +33,7 @@
     "compiler",
     "research-manager",
     "rigor-reviewer",
+    "research-visualizer",
     "llm",
     "cli"
   ],

package/skills/compiler/SKILL.md

@@ -199,6 +199,28 @@ the source actually reveals — but the node count and types are **source-bounde
 never invent a dead end, decision, or experiment to hit a number. A paper that hides its failures
 yields a smaller, honest tree (Rule 9 wins).
 
+**Optional per-node changed-code (enrichment for the Research Visualizer).** When the work is a
+sequence of code edits and the scripts are resolvable at compile time, you MAY attach to an experiment
+node the **unified diff** it represents — never required, omitted when unclear:
+1. **Resolve node → representative variant — this link does NOT already exist; construct it.** From the
+   node's `source_refs` / its claims' cited `record_configs` → the run index (`runs.csv`/`runs.jsonl`)
+   row(s) whose family+purpose+bin match → the representative submitted script. Where this is empty or
+   ambiguous (most `decision`/`dead_end` nodes, or evidence that is only journal prose), **omit
+   `code_change`** — never guess a script.
+2. **Resolve node → diff base** from the lineage you already reconstruct for `solution/*` (wave baseline
+   or immediate-parent variant).
+3. **Index both scripts in `src/artifacts.md` under a stable anchor** (`A01`, `A02`, …) carrying real
+   path + sha256 + original location; compute the unified diff (variant vs base) and write it to a tracked
+   **`evidence/changes/<node-id>.diff.md`** sidecar (fenced ```diff, `**Source**` header citing the two
+   anchor ids). Set the node's `code_change: {base_artifact, variant_artifact, lang, diff_file}`. The whole
+   scripts stay pointers (Rule 14) — the diff is a derived, grounded view, like a `derived_subset` table.
+4. **Store-absent ⇒ pointers, not a diff.** If the scripts don't resolve on disk (git-ignored store),
+   still record `code_change` with the anchor ids + a `note`, omit `diff_file` — the visualizer shows a
+   pointer chip. Expected, not a failure.
+
+You MAY also attach `node.thinking` — the agent's deliberation — but **only verbatim** grounded
+journal/decision text; never compose new prose. No verbatim rationale ⇒ leave it absent.
+
 ### Step 3: Generate Files
 
 Write the mandatory core, then the additional files the paper warrants. See
@@ -249,6 +271,10 @@ Run ARA Seal Level 1. Check:
   heuristic `Code ref` → a real `src/execution/` file (when both exist); tree `evidence:` → claim IDs
 - Evidence: **every numbered table and figure is filed with BOTH a markdown file and a screenshot
   (.png)**; numbered objects not filed are accounted for in `evidence/README.md` with a reason
+- **Changed-code (only if emitted):** each `evidence/changes/<node>.diff.md` cites two `src/artifacts.md`
+  anchors (`base`/`variant`) that resolve; the diff is verbatim; the node's `code_change` points at the
+  sidecar via `diff_file` (or carries a `note` with no `diff_file` when the store was absent). Optional —
+  absent is fine; never invent a diff or a node→script mapping
 - Evidence files have **Source** fields; figures declare Figure type / Extraction method / Reading
   confidence; estimated readings marked `≈` (not `exact_from_labels`); diagrams/qualitative samples
   carry a visual description, not a fabricated table

package/skills/compiler/references/ara-schema.md

@@ -32,6 +32,7 @@ evidence/
   tables/                           # ✓ every numbered Table: tableN.md + tableN.png
   figures/                          # ✓ every numbered Figure: figureN.md + figureN.png
   proofs/                           # as warranted: derivations / proofs
+  changes/                          # as warranted: per-node code-change unified diffs (Research Visualizer)
 rubric/requirements.md              # (Only if a rubric is provided)
 ```
 
@@ -378,6 +379,8 @@ the winner, or files collapsed into a single directory link) is the failure.
 
 ```markdown
 ## {Artifact name}
+- **Anchor**: {stable short id — `A01`, `A02`, … — so a trace node's `code_change` can reference this artifact by id; optional, but required for the Research Visualizer's changed-code diffs}
+- **sha256**: {content hash of the file, when a code-change diff cites it}
 - **File(s) in repo**: {real path(s), verified to exist}
 - **Nature**: {what it is — tool / library / skill spec / system / dataset}
 - **What it does / contains**: {grounded description}
@@ -423,6 +426,28 @@ Reproducibility for any field. For purely analytical work, state so explicitly.
 
 ---
 
+## evidence/changes/{node-id}.diff.md  (Research Visualizer changed-code diffs)
+
+Per-experiment-node **unified diff** the step represents — a derived, grounded view (the whole scripts
+stay pointers in `src/artifacts.md`; this is NOT a copy of the artifact). One tracked file per node that
+has a resolvable code change:
+
+```markdown
+# Change {node-id}: {short description}
+- **Base**: A01   (→ src/artifacts.md anchor; path + sha256 + original location live there)
+- **Variant**: A07
+- **Language**: python
+
+<unified diff fenced as ```diff … ``` — verbatim from the real scripts>
+```
+
+Rules: cite the two artifacts **by anchor id**, never paste their paths/sha here (those live once in
+`src/artifacts.md`). The diff text is verbatim. If the scripts can't be resolved at compile time
+(git-ignored store), omit this file and set the node's `code_change.note` instead (the visualizer shows a
+pointer chip, no diff). These sidecars MUST be tracked/committed (not swept by any store `.gitignore`).
+
+---
+
 ## evidence/tables/{file}.md (+ screenshot)
 
 Every numbered table gets BOTH this markdown file AND a screenshot `tableN.png` (the rendered
@@ -475,6 +500,9 @@ tree:
     source_refs: ["Table 2", "§4.1"]   # recommended for explicit nodes
     title: "{...}"
     description: "{...}"
+    # OPTIONAL enrichment (Research Visualizer; omit when absent):
+    # thinking: "{verbatim agent deliberation — why it did/branched}"
+    # code_change: { base_artifact: A01, variant_artifact: A07, lang: python, diff_file: evidence/changes/N01.diff.md }
 ```
 
 Rules:

package/skills/research-visualizer/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: research-visualizer
+description: |
+  Research Visualizer. Renders an existing Agent-Native Research Artifact (ARA) into ONE
+  self-contained, interactive HTML file showing the AI scientist's step-by-step research process:
+  a clickable process map of the exploration tree (branches and dead ends included) on the left,
+  and a per-step drill-down on the right — what the step did, why (the linked claim), the real
+  result (verbatim grounded numbers + inline figures + tables), and the code/artifact pointer.
+  Read-only consumer of the artifact — it never changes how research is done.
+  When the ARA carries them, it also surfaces (each optional, only when present) the related-work
+  dependency graph, the problem framing, a concepts glossary with in-text term popovers, and the
+  solution recipes — reached from header disclosures without leaving the process map.
+  Accepts either an existing ARA or raw research input (a paper, repo, run logs, or notes); when the
+  input is not yet an ARA it is compiled into one first, then visualized.
+
+  TRIGGERS: visualize, visualizer, trajectory view, render the ARA, see the steps, step-by-step view,
+  process map, replay the trajectory, watch the agent work, drill into steps,
+  visualize a paper, visualize a repo, visualize a run
+argument-hint: "[ara-dir] [--output <path>]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(python3 *|base64 *|find *|ls *|open *)
+metadata:
+  author: ara-commons
+  category: research-tooling
+  version: "1.0.0"
+  tags: [research, visualization, trajectory, exploration-tree, html]
+---
+
+# Research Visualizer
+
+You render an existing ARA into a single portable HTML view of the agent's step-by-step process.
+You are a **read-only consumer**: you read the artifact and emit a file; you never edit the ARA.
+
+You operate as a first-class agent — use your native tools directly. The heavy rendering logic is
+**already written** in `references/trajectory-template.html`; you do NOT rewrite it. Your job is to
+parse the ARA into one `ARA_DATA` JSON object, inline the figures, and inject that object into the
+template's data slot.
+
+## What you produce
+
+One self-contained file, default `<ara-dir>/trajectory.html` (override with `--output`):
+- All data, tables, and figures (base64) inlined — no server, no network, no CDN. Double-click to open.
+- Built by populating the canonical scaffold, so every generated view is structurally consistent.
+
+## v1 boundaries (do not exceed)
+
+- **Post-hoc** visualization of a finished/in-progress ARA. No live/real-time mode.
+- **Self-contained from the ARA directory alone.** Do NOT open or inline anything outside the ARA dir.
+  `src/artifacts.md` run-store pointers and node `source_refs` (external journal `file:line`) are shown
+  **as pointers/chips, not resolved**. (External resolution is a planned future extension — out of scope.)
+- **Single ARA.** No cross-ARA comparison.
+
+## Pipeline
+
+1. **Args.** Resolve `<ara-dir>` (default: the ARA in the current working context / most-recently
+   referenced). Resolve `--output` (default `<ara-dir>/trajectory.html`).
+1b. **Precondition — the input must be an ARA; if it is not, compile it first.** Decide with one
+   observable test: does the resolved input expose a parseable `trace/exploration_tree.yaml`
+   (**≥1 node**) — directly, or as a standard ARA directory layout?
+   - **It is an ARA** → continue to Validate unchanged.
+   - **It is not an ARA** — the input is raw research material (a paper/PDF, a code repository, a
+     run/log directory, notes, or any directory with no exploration tree) → **invoke the `compiler`
+     skill on that input to produce an ARA**, then set `<ara-dir>` to the compiler's output artifact
+     and continue. Do not hand-roll an ARA yourself; the compiler is the only path that builds one.
+     Default `--output` to `<compiled-ara-dir>/trajectory.html` unless the user set it.
+   Only if the compiler still yields no exploration tree does the Validate step's "no process" message apply.
+2. **Validate — the exploration tree is the ONLY hard requirement.** Confirm
+   `trace/exploration_tree.yaml` exists and parses to **≥1 node**; if not (and the precondition's
+   compile step has already run), tell the user there is no process to show (this replaces the old
+   `PAPER.md` "is-this-an-ARA?" guard). Everything else —
+   `PAPER.md`, `logic/`, `src/`, `evidence/`, and the four enrichment layers — is **optional
+   enrichment**: glob whatever is present. If `PAPER.md` is absent, synthesize a minimal `meta` (title
+   from a tree-level `title:` or the dir name; empty `abstract` hides the disclosure). This is the
+   **raw-trajectory path**: the skill produces a useful step-by-step view from *just the tree* (a raw
+   agent run), not only a fully-compiled ARA — see `references/parsing.md` §7.
+3. **Parse the trace** into normalized nodes. The field conventions vary across ARAs — follow
+   `references/parsing.md` exactly (handles `tree:` vs `root:`, generic vs type-named fields,
+   `evidence:` routing, `isolated`, `also_depends_on`). Every node must yield a `title` + `body`.
+4. **Parse the hub layers — each only when present (all optional now):** `logic/claims.md` (the
+   binding hub *when it exists*), `logic/experiments.md`, `evidence/README.md` (figure/table ↔ claim
+   reverse index), `src/artifacts.md`, `logic/solution/*`. A missing layer simply contributes nothing;
+   the node still renders from its own `title`/`body`/`thinking`.
+   **Also parse the four OPTIONAL enrichment layers when present, per `references/parsing.md` §8:**
+   `logic/problem.md`→`context`, `logic/concepts.md`→`glossary` (+ build the `lexicon`),
+   `logic/related_work.md`→`dependencies`, `logic/solution/*.md`→`recipes` (role-classify by content, not
+   filename). A missing file/dir omits its key entirely. Reproduce statements/deltas/definitions/relations/
+   headings/quotes/cells **verbatim**.
+5. **Build each node's drill-down.** When `logic/claims.md` exists, follow the claim-hub chain in
+   `references/binding.md` (node → `evidence:[C##]` → claims → {Sources quotes, figures/tables,
+   experiments, artifact pointers}). When it does **not**, the drill-down is just the node's own
+   narrative (`thinking`/`body`) — every claim/result/verified block is empty and omitted.
+5b. **Bind the enrichment layers** per the "four enrichment layers" section of `references/binding.md`:
+   build `claimIds`/`nodeByClaim`/`conceptNames`/`rwIds`; resolve every `refs[].target` (drop danglers,
+   never link off-ARA); derive each node's `built_on`/`rejected_here` (dependency→claim→node, bucketed by
+   `relation_norm`), `concepts` (whole-word name-match), and `recipe_refs` (recipe→claim→node); mark
+   cross-agent entries. All per-node enrichment fields default `[]`.
+6. **Inline figures.** For each referenced figure that has a real raster (`evidence/figures/*.png`),
+   base64-encode it and put the `data:` URI in `figures[].img`. Use Bash, e.g.
+   `python3 -c "import base64,sys;print('data:image/png;base64,'+base64.b64encode(open(sys.argv[1],'rb').read()).decode())" <path>`.
+   For data-only figure markdown (no raster), render its data table instead (as a `tables[]` entry).
+   **Also inline code diffs + the artifact index:** for each node with `code_change.diff_file`, read that
+   tracked `evidence/changes/<id>.diff.md` sidecar and inline its fenced diff text into `code_change.diff`
+   (parallel to figures); build the top-level `artifacts[]` index from `src/artifacts.md` so
+   `base_artifact`/`variant_artifact` ids resolve; carry each node's verbatim `thinking` straight through.
+   Sanitize all three verbatim fields per the Injection contract. The visualizer never computes a diff
+   itself and never opens the external store — it only inlines what the ARA already contains.
+7. **Assemble `ARA_DATA`** (exact schema in `references/binding.md`) and **inject** it: replace ONLY
+   the JSON between `/* __ARA_DATA_BEGIN__ */` and `/* __ARA_DATA_END__ */` in the
+   `<script id="ara-data">` block of a copy of the template. Write the result to the output path.
+   Include `context`/`glossary`/`dependencies`/`recipes` and the per-node `built_on`/`rejected_here`/
+   `recipe_refs`/`concepts` **only when their sources exist** — omit absent keys entirely (no empty
+   stubs). A payload omitting all of them stays byte-compatible with the v1.0 schema.
+8. **Report** the output path. Optionally open it (`open <path>` on macOS). Print a one-line summary
+   (node count, dead ends, figures inlined, which of the four enrichment overlays were emitted with their
+   term/dependency/recipe counts, danglers dropped, any pointers left unresolved).
+
+## Injection contract (critical)
+
+- The injected payload MUST be valid JSON (it is read with `JSON.parse`). The template strips only the
+  two named marker comments before parsing, so the payload is otherwise pure JSON.
+- It must not contain the literal substring `</script>`, nor the literal marker strings
+  `/* __ARA_DATA_BEGIN__ */` / `/* __ARA_DATA_END__ */`. Escape any `<` in inlined markdown/text as `&lt;`
+  (or `<`) — this also neutralizes `</script>`. (A bare `*/` inside a string value is harmless to
+  `JSON.parse`; only the exact marker strings would be stripped.)
+- **The verbatim free-text fields `thinking` and `code_change.diff` are the high-risk carriers** (source
+  code routinely contains `/* … */`). If either marker token would appear in their text, break it (e.g.
+  insert a zero-width space inside `__ARA_DATA_…`) so the global marker-strip can't delete it from inside
+  a value. Re-validate: a node whose `thinking`/`diff` contains a marker token MUST round-trip intact.
+- Do not touch anything else in the template — only the bytes between the two markers.
+- After writing, re-validate: the file still parses (the embedded JSON loads). If a figure pushed the
+  file very large, apply the size guards in `references/binding.md` (truncate logs/tables, keep figures).
+
+## Faithfulness (hard rules)
+
+- Reproduce claim `Statement`s, `Sources` quotes, and table numbers **verbatim** — never paraphrase,
+  never invent. Missing data → set the field empty/omit (the viewer shows "No …"); never fabricate.
+- Provenance, `support_level`, and `status` are shown **only if present** in the source; do not guess.
+- Dead-end nodes and `isolated` subtrees must be carried through faithfully — they are the most
+  valuable things to display, not noise to drop.
+- For the enrichment layers: relation strings, definitions, constraint headings, and footprint citations
+  are reproduced **verbatim**; relation enums are open (compound `bounds / refutes` / transition
+  `extends → quarantined` kept as written; `relation_norm` is for color only). Never normalize a heading
+  or invent a typed sub-field. A `refs[].target` is set only on real in-ARA resolution; dangling refs are
+  flagged, never silently corrected or dropped. `built_on`/`concepts`/"used by" name-matches are
+  best-effort hints (marked "inferred"), never asserted as facts.
+
+## Verify
+
+Run on any ARA and confirm these properties — no named fixtures required:
+- Opens by double-click: no server, no network, no console errors.
+- Full process map: nesting, branches, dead ends marked, any `isolated` subtree boxed, `depends_on` chips.
+- Drill-down renders whichever blocks are present (what / why / result-with-inline-figure / how-verified /
+  code-or-pointer), correctly under **both** field dialects in `references/parsing.md`.
+- Verbatim quotes/numbers; nothing fabricated; self-contained from the ARA dir (no needed external refs).
+- Re-running reproduces the same structure (data differs only as the ARA differs).
+- **Enrichment layers:** a layer's header button appears only when its source exists; an ARA with none of
+  the four layers renders identically to v1.0 (no layer bar, no node chips). Open each emitted overlay and
+  confirm verbatim relations/definitions/recipe cells, ungrounded/dangling/cross-agent markers, and that
+  the `built_on`/`rejected_here` chips + the `⊕/⊘` map marker deep-link into Dependencies. Glossary
+  popovers fire on body terms; inline `$LaTeX$` renders with no network.
+- **Degradation:** a `minimal-artifact` (only `problem.md`) shows only the Context button, others absent,
+  popovers off, per-node chips empty, zero console errors.
+- **Compile-first (non-ARA input):** pointing the skill at raw research material with no exploration
+  tree (a paper, a repo, a run/log dir) triggers the `compiler` skill first, then visualizes the
+  resulting ARA — the output is identical to running the compiler then the visualizer by hand.
+- **Raw trajectory (the decoupled path):** a **tree-only** ARA — just `trace/exploration_tree.yaml`, no
+  `PAPER.md`, no `logic/`, no `evidence/` — still renders the full process map + each step's narrative
+  (`thinking`/`body`), with no layer bar and no claim/result/verified blocks, zero console errors. This
+  is a first-class supported input, not a failure mode.
+
+Cover the variant axes with whatever ARAs you have: both root forms (`tree:`/`root:`), both field
+dialects (generic / type-named), figures present as real raster vs. data-markdown-only, `src/` as a
+pointer index vs. transcribed code, and an `isolated` subtree if any artifact has one.

package/skills/research-visualizer/references/binding.md

@@ -0,0 +1,245 @@
+# Binding — the claim-hub drill-down chain + the `ARA_DATA` schema
+
+This is the read step. For each normalized trace node you build one drill-down bundle by following
+the artifact's **claim-mediated** cross-layer links, then you emit the whole thing as one `ARA_DATA`
+object that the scaffold renders.
+
+> **The claim hub is OPTIONAL — the tree is the only hard requirement.** Every layer this file binds
+> (`logic/claims.md`, `logic/experiments.md`, `evidence/`, `src/artifacts.md`, the four enrichment
+> layers) is enrichment: when its dir/file is absent, that binding step **no-ops** and the
+> corresponding `ARA_DATA` arrays stay `[]` (omitted by the renderer). A node ALWAYS renders from its
+> own normalized `title` / `body` / `thinking` (parsing.md §3, §7a) — so a **raw, tree-only
+> trajectory** with no `logic/` and no `evidence/` produces a complete process map + per-step
+> narrative. The chain below is what runs *when the hub exists*; nothing here may hard-fail on an
+> absent layer.
+
+## Why claim-mediated (and not node → `.py` + table)
+
+Current ARAs usually have **no per-step source file**: `src/` is `artifacts.md` (a pointer index into
+an external run store) + `environment.md`. The binding hub is `logic/claims.md`. A trace node points
+at claims via `evidence: [C##]`; the claim carries the *why*, the grounded *result* (verbatim
+`Sources` quotes with `file:line`), the verification (`Proof: [E##]`), and the figures/tables that
+cite it. So the real grounded numbers are **already inside the ARA** — you do not need the external
+store (v1 leaves those as pointers).
+
+## Resolution chain (per node)
+
+```
+NODE (type, content+outcome, support_level, source_refs, evidence:[C##], also_depends_on, isolated)
+  ├─ WHAT        → node title + body (+ outcome) ............................ → node.title / node.body
+  ├─ WHY         → evidence:[C##] → logic/claims.md ......................... → node.why[]
+  │                 each claim: Statement, Status, Conditions, Falsification,
+  │                 Dependencies, provenance
+  ├─ HOW VERIFIED→ claim.Proof:[E##] → logic/experiments.md ................. → node.verified_by[]
+  │                 each experiment: Run (pointer), Setup, Metrics
+  ├─ RESULT      → claim.Sources «quote ← file:line» + Evidence basis ....... → node.result.sources[]
+  │              + evidence/README.md reverse-lookup: figures/tables citing C## → node.result.figures[]/tables[]
+  │              + evidence/data/*.json (raw, in-artifact) .................. → node.result.data[]
+  └─ CODE/ARTIFACT→ src/artifacts.md pointer(s) + logic/solution/* recipe ... → node.artifact[]
+```
+
+### evidence/README.md reverse-lookup
+`evidence/README.md` has a `Claims` column mapping each figure/table file → the `C##` it grounds.
+Build a map `claim_id → [evidence files]` once. For a node, union the evidence of all its claims.
+Fallback if no README row: scan the figure/table `.md` for an inline `Supports C##` / `grounds C##`.
+
+### Figures
+- Real raster (`evidence/figures/<name>.png` beside the `.md`) → base64-inline into `figures[].img`.
+- Data-only figure markdown (no raster) → render its data table as a `tables[]` entry instead.
+- A figure's caption/title comes from the first heading or the `What it shows` section of its `.md`.
+
+### What counts as "code" now
+There is usually no `src/execution/*.py`. Populate `artifact[]` from `src/artifacts.md` (the run-index
+row / `record_configs/` path / named submitted variant file) plus the relevant
+`logic/solution/*.md` recipe section. Only when a real transcribed `src/execution/*.py` exists
+(legacy / paper-only code) do you point at that file. **Never resolve the external store in v1** —
+the pointer text is the value.
+
+### The changed-code diff (`node.code_change`) — compiler-produced, visualizer-rendered
+A full ARA may carry, per experiment node, the **unified diff** the step represents. The addresses
+live in ONE place and are referenced by id (weak coupling):
+
+`node.code_change` → `evidence/changes/<node-id>.diff.md` (the diff **text**) → `artifacts[]` /
+`src/artifacts.md` entry (path + sha256 + original location) → the original repo.
+
+- The diff **text** is grounded by citing the two **artifact ids** (`base_artifact`, `variant_artifact`),
+  never an embedded path. Whole scripts stay pointers in `src/artifacts.md` (Rule 14) — the diff is a
+  derived, grounded view (≈ a `derived_subset` table), not a copy of the artifact.
+- **`diff_file` → `diff` inlining** (parallel to figures' `.md`→base64 `img`): on disk the node carries
+  `code_change.diff_file: "evidence/changes/<id>.diff.md"`; the visualizer reads that **tracked** sidecar
+  and inlines its fenced diff text into `code_change.diff` in `ARA_DATA`, so the rendered HTML stays
+  self-contained (the sidecar lives inside the ARA dir).
+- **`artifactById`**: the visualizer builds an `id → artifacts[] entry` map (parallel to `nodeByClaim`)
+  and resolves `base_artifact`/`variant_artifact` into the shown-not-resolved pointer chip under the diff.
+- **Degrade**: when the scripts don't resolve at compile time (store absent), the compiler emits
+  `code_change` with the artifact ids + a `note` but no diff; the viewer shows a pointer chip, not a diff.
+- **Marker safety**: `diff` and `thinking` are verbatim, so the producer MUST ensure neither the literal
+  `/* __ARA_DATA_BEGIN__ */` / `/* __ARA_DATA_END__ */` tokens nor `</script>` appears in any inlined
+  string (escape `<`→`&lt;`; break the marker tokens). See SKILL.md "Injection contract".
+
+## The `ARA_DATA` object (exact schema the scaffold reads)
+
+```jsonc
+{
+  "meta": {
+    "title":  "<PAPER.md frontmatter title>",
+    "authors": ["..."],            // [] if none
+    "year":   "", "venue": "", "ara_dir": "<dir name>",
+    "abstract": "<PAPER.md abstract>"   // "" to hide the Abstract disclosure
+  },
+
+  // Traversal order for Replay and ← →. A flat list of node ids in the order to step through
+  // (typically a pre-order DFS of the tree). If omitted, the scaffold derives a DFS from `parent`.
+  "order": ["N01", "N02", "N03", "..."],
+
+  // OPTIONAL addressable artifact index (from src/artifacts.md). Each script the compiler points at
+  // gets a stable id so a node's code_change can reference it BY ID (no embedded path). Omit if absent.
+  "artifacts": [
+    { "id":"A01", "name":"<artifact name>", "path":"<repo-relative path>", "sha256":"<...>",
+      "original_location":"<store/repo ref>", "pointer":"<src/artifacts.md pointer text>" }
+  ],
+
+  "nodes": [
+    {
+      "id": "N02",
+      "type": "experiment",        // question|experiment|decision|dead_end|pivot|insight|<other ok>
+      "parent": "N01",             // id of the nesting parent, or null for a root
+      "title": "<normalized step title>",            // see parsing.md
+      "body":  "<what the step did / its outcome>",
+      "thinking": "<verbatim agent deliberation — why it did/branched; OPTIONAL>", // primary block; falls back to body
+      "support_level": "explicit", // "explicit"|"inferred"|null
+      "isolated": false,           // true → rendered in a separated dashed box
+      "depends_on": ["N00"],       // also_depends_on cross-edges (ids); [] if none
+      "source_refs": ["<external path:line — shown as a chip, NOT resolved>"],
+
+      "why": [                     // from evidence:[C##] → claims.md
+        { "id":"C01", "title":"...", "statement":"<verbatim Statement>",
+          "status":"supported", "conditions":"...", "falsification":"...",
+          "dependencies":["C00"], "provenance":"<as stated in source, else null>" }
+      ],
+
+      "result": {
+        "sources": [ { "quote":"<verbatim Sources quote>", "ref":"<file:line>" } ],
+        "figures": [ { "id":"<figure id>", "caption":"...", "kind":"quantitative_plot",
+                       "img":"data:image/png;base64,<...>" } ],
+        "tables":  [ { "id":"<table id>", "caption":"...", "markdown":"| col | ... |\n|---|...|" } ],
+        "data":    [ { "id":"<data id>", "path":"evidence/data/<name>.json", "note":"raw" } ]
+      },
+
+      "verified_by": [             // from claim.Proof:[E##] → experiments.md
+        { "id":"E01", "title":"...", "run":"<Run pointer text>", "setup":"...", "metrics":"..." }
+      ],
+
+      "artifact": [                // src/artifacts.md pointers + solution recipe refs (pointer text only)
+        { "name":"<artifact / family name>", "pointer":"<src/artifacts.md pointer text>", "what":"pointer index entry" }
+      ],
+
+      "code_change": {             // OPTIONAL — the changed-code diff for this step (compiler-produced)
+        "base_artifact":"A01",     // → artifacts[].id (holds path+sha+original_location)
+        "variant_artifact":"A07",  // → artifacts[].id
+        "lang":"python",
+        "diff":"<unified-diff text, inlined by the visualizer from evidence/changes/<id>.diff.md>",
+        "note":""                  // set (with diff absent) when the scripts didn't resolve → pointer-only chip
+      }
+    }
+    // ... one object per trace node
+  ]
+}
+```
+
+### Field rules
+- Every node MUST have `id`, `type`, `title`, `parent` (or null). All other arrays default to `[]`,
+  scalars to `null`/`""`. The scaffold tolerates missing optional fields.
+- Put **only what the source contains**. Empty `why`/`result`/`verified_by`/`artifact` is fine and
+  common (e.g. a bare `decision` node) — the viewer simply omits those blocks. `thinking` and
+  `code_change` are likewise optional; omit when absent (a payload without them is byte-compatible).
+- `status` is lower-cased by the viewer for styling; pass it as written (`Supported`, `hypothesis`, …).
+
+### Size guards
+- Inline every figure (they are the point), but cap a single inlined table/log render at a few hundred
+  lines; if longer, truncate and append a final row/line `… +N more (truncated)`.
+- If the assembled file would be very large, prefer truncating `tables`/`data` text over dropping
+  figures, and never drop nodes.
+
+---
+
+# The four enrichment layers — schema additions + cross-linking
+
+These surface `logic/problem.md` / `logic/concepts.md` / `logic/related_work.md` / `logic/solution/*`
+(parsed per `parsing.md` §8). **Everything here is OPTIONAL and additive** — omit any key whose source
+is absent; a payload with none of these stays byte-compatible with the prior schema and the renderer is
+inert for any key it doesn't see.
+
+## Schema additions
+
+A shared **typed-ref** primitive (used by every layer's `refs`/`grounding`):
+```jsonc
+{ "raw": "<verbatim token, always shown>",
+  "kind": "claim|concept|related_work|observation|gap|assumption|experiment|node|source|figure|pr|arxiv|doi|url|unknown",
+  "target": "<in-ARA anchor id, or null>" }   // non-null ONLY when it resolves inside THIS ARA
+```
+
+Four OPTIONAL top-level keys:
+```jsonc
+"context": {                 // logic/problem.md ; omit if absent
+  "title":"Problem", "summary":"",
+  "sections":[ { "role":"setting|observations|gaps|insight|assumptions|other", "heading":"<verbatim H2>",
+    "present":true,           // false ⇒ greyed "(not specified)" stub for an expected-but-absent role
+    "entries":[ { "ent_id":"O2", "inferred_id":false, "ent_title":"", "text":"<verbatim>",
+                  "unstructured":false, "fields":[{"label":"<verbatim>","value":"<verbatim>"}], "refs":[/*typed-ref*/] } ] } ] },
+"glossary": {                // logic/concepts.md ; omit ⇒ popovers disabled
+  "title":"Concepts", "groups":[{"name":"","term_ids":["G07"]}],
+  "terms":[ { "term_id":"G07", "name":"<verbatim, the match key>", "aliases":[], "group":"",
+              "definition":"<verbatim, may hold $LaTeX$>", "fields":[{"label":"","value":""}], "related":["G08"], "refs":[] } ],
+  "lexicon": { "<lowercased surface>":"G07" } },   // precomputed surface→term_id for popovers
+"dependencies": {            // logic/related_work.md ; omit if absent
+  "title":"Related Work / Dependencies", "preamble":"", "legend":[{"type":"extends","gloss":""}], "attribution":"",
+  "entries":[ { "rw_id":"RW02", "inferred_id":false, "name":"", "relation_raw":"<verbatim, compound/transition kept>",
+                "relation_norm":"baseline|imports|extends|bounds|refutes|", "delta":"", "adopted":"",
+                "grounding":[/*typed-ref: pr|arxiv|doi|source|url*/], "claims":["C03"], "cross_agent":false, "is_footprint":false } ],
+  "footprint":[ {"ref_id":"16","citation":"<verbatim one-liner>"} ] },
+"recipes": {                 // logic/solution/* ; omit if dir absent
+  "title":"Solution",
+  "files":[ { "file":"method.md", "role":"constraints|method|heuristics|algorithm|architecture|recipe", "file_title":"",
+    "sections":[ { "sec_id":"", "heading":"<verbatim, never normalized>", "kind":"table|steps|kv|code|math|prose",
+                   "markdown":"", "steps":[], "fields":[], "code":"", "text":"<verbatim fallback>", "warn":"", "refs":[] } ] } ] }
+```
+
+Four OPTIONAL per-NODE fields (default `[]`):
+```jsonc
+"built_on":     [ {"rw_id":"RW02","name":"","relation_raw":""} ],   // baseline/imports/extends deps a node's claims cite
+"rejected_here":[ {"rw_id":"RW10","name":"","relation_raw":""} ],   // bounds/refutes deps
+"recipe_refs":  [ {"file":"","sec_id":"","heading":"","role":""} ], // recipe sections a node's claims cite
+"concepts":     [ "<verbatim term name>" ]                          // glossary terms mentioned in this node (popover anchors)
+```
+Field rules: every new key omittable; `text`/`definition`/`delta`/`value`/relations/headings/quotes/cells
+**verbatim**; `relation_raw` always preserved (compound/transition survive), `relation_norm` is color-only
+and may be `""`; `target` non-null only on in-ARA resolution (off-ARA `pr`/`arxiv`/`doi`/`§`/file:line stay
+`null` → inert chip); no fabrication.
+
+## Cross-linking (the binder runs AFTER nodes + claims are parsed)
+
+The hub stays `logic/claims.md`. All linking is best-effort, computed once into lookup maps, then attached.
+
+- **B.0 anchors:** `claimIds` (the `## C\d+` set), `nodeIds`, `nodeByClaim` (invert each node's `why[].id`),
+  `conceptNames` (lowercased `glossary` names+aliases), `rwIds`.
+- **B.1 claim-ref resolution (single pass over all layers' refs):** `kind:"claim"` ref → `target` if
+  `∈ claimIds`, else `target:null` and **flag dangling** (renderer greys it "broken link" — never a live
+  dead link). Same for `related_work`/`concept`/`node` targets against their id sets.
+- **B.2 dependencies ↔ claims/nodes:** forward edge is in-data (`entries[].claims[]`). Build the reverse
+  `claim_id → [rw_id]`; also harvest `claims.md`'s own `**Dependencies.**` lines as extra rw-edges (so the
+  edge exists even when related_work omits the back-ref).
+- **B.3 per-node `built_on` / `rejected_here` (the chips):** `rwSet = ⋃ over n.why[].id of reverse(claim→rw)`.
+  For each rw, bucket by `relation_norm`: `∈{baseline,imports,extends}` → `built_on`; `∈{bounds,refutes}` →
+  `rejected_here`; `""`/transition → first keyword, default `built_on`, **keep `relation_raw` literal**.
+  Dedupe by `rw_id`; empty buckets stay `[]` (no chip row). Cross-agent deps render a distinct "↔ other-agent"
+  ribbon.
+- **B.4 concepts ↔ everything:** concepts are leaf provenance (no `trace:N` refs). Build `node.concepts[]` by
+  **sideways name-match** — whole-word, case-insensitive scan of each node's `title`+`body`+claim statements
+  against `conceptNames`. The Concept overlay's "used by" is that scan inverted, marked **"mentions
+  (inferred)"** and visually distinct from id-resolved links. Outbound concept `refs` resolve normally.
+- **B.5 recipes ↔ claims/nodes (`recipe_refs[]`):** a node's `recipe_refs` = recipe sections whose `refs[]`
+  cite one of the node's `why` claims (∪ sections a node's claim cites back); dedupe by `(file,sec_id)`.
+  Unresolvable `C##` ⇒ inert muted chip ("referenced but not linked"), never dropped.
+- **B.6 determinism & cost:** all maps built once, O(nodes+claims+refs); stable source order; a wrong/no
+  match never blocks rendering. The browser-side `lexicon` is precomputed so no source regex runs at runtime.