@ara-commons/ara-skills 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ara-commons/ara-skills",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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": {

package/skills/compiler/SKILL.md

@@ -16,7 +16,7 @@ allowed-tools: Read, Write, Edit, Bash(python *|git clone *|ls *|mkdir *), Glob,
 metadata:
   author: ara-commons
   category: research-tooling
-  version: "1.2.0"
+  version: "1.2.1"
   tags: [research, compilation, artifacts, knowledge-extraction]
 ---
 
@@ -170,11 +170,19 @@ whichever layer fits best, preserving the source's granularity. Never silently d
 or released form, *distinct from the prose that describes it*. `src/environment.md` is always
 required (reproducibility). Beyond it, one rule decides everything:
 
-> **Represent every concrete artifact losslessly. When it persists in a linkable external store (a
-> run database, a released/versioned repo), point to it — a comprehensive `src/artifacts.md` index,
-> one link per artifact (every run, config, log, script), nothing aggregated or copied. Capture it
-> into `src/execution/` only when it would otherwise be lost — code that lives solely inside the
-> paper, or a source not externally persisted. Never re-encode a prose-only description as code.**
+> **Represent every concrete artifact losslessly, and split it by KIND into the layer it belongs to:**
+> - **Codebase → `src/`.** The experiment's *code* — source files, scripts, configs — in **any
+>   language** (judged by content, **never** by a `.py` suffix: `.c`/`.cu`, `.js`/`.ts`, `.rs`, `.cpp`,
+>   `.jl`, `.go`, notebooks, shell, … all count). When the code persists in a linkable codebase (a
+>   directory of script variants, a released/versioned repo), `src/artifacts.md` is a **pointer index to
+>   that codebase** — one link per code artifact (every script/config/module), nothing aggregated or
+>   copied. Transcribe into `src/execution/` only when the code would otherwise be **lost** (lives solely
+>   inside the paper, or a source not externally persisted).
+> - **Run records → `evidence/`.** The *outputs* of running that code — per-run logs, metrics, run
+>   tables — are empirical **evidence, not code**: they live in `evidence/results/<node>.md` (run tables)
+>   + `evidence/logs/log_pointers.md` (direct per-run log pointers), linked straight from the trace/claims.
+>   **Never index runs or logs in `src/artifacts.md`** — `artifacts.md` is the codebase, not the run store.
+> Never re-encode a prose-only description as code.
 
 A concrete artifact is real content the cognitive layer doesn't already hold — capture it (grounded
 in the real repo/files when provided), in whatever directory fits. But a method conveyed only in
@@ -199,26 +207,7 @@ 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
+You MAY 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
@@ -271,10 +260,6 @@ 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
@@ -322,7 +307,7 @@ key stats (claims, experiments, concepts, tree nodes, evidence tables/figures).
 11. **Visual extraction is honest extraction**: read figures by looking; mark estimates `≈` with extraction method + confidence; never present a digitized estimate as exact, invent points for an unreadable figure, or turn a diagram into a fake data table
 12. **Complete, ordered evidence**: file EVERY numbered table and figure, in order — a systematic sweep, not a lucky sample — each as a markdown transcription PLUS a saved screenshot (`.png`). No early stopping; account for any object you don't file
 13. **Fit the file set to the paper, not the paper to a template**: only PAPER.md + the mandatory core are required. Beyond them, generate the files THIS work actually warrants and nothing it doesn't have. Never force inappropriate files (e.g. model-training configs onto an eval or theory paper)
-14. **`src/` holds concrete artifacts, not re-encoded prose**: capture every concrete artifact the source actually contains, in its native form, grounded in real files. Three sides: (a) never fabricate a code stub from a prose-only method — it already lives in `logic/`, so a `.py` just duplicates it; (b) never drop a concrete artifact that does exist — a lone `environment.md` is wrong when the work has one; (c) when the work's artifacts **persist in a linkable external store** (a run database, a released or versioned repo), represent them as a **comprehensive pointer index** in `src/artifacts.md` — one link per artifact (every run, config, log, script), nothing aggregated into a vague bucket, nothing copied; a lossy subset-copy is the failure. **Transcribe real source into `src/execution/` only when it would otherwise be lost** — code that lives solely inside the paper, or a source not externally persisted (then `# Grounding: transcribed`, cite path). No implementation in the input → neither applies.
+14. **`src/` holds the codebase (code), not run records and not re-encoded prose**: capture every concrete code artifact the source contains, in its native form — **any language, judged by content not by a `.py` extension** (`.c`/`.cu`, `.js`/`.ts`, `.rs`, `.cpp`, `.jl`, `.go`, notebooks, shell, … all count) — grounded in real files. Four sides: (a) never fabricate a code stub from a prose-only method — it already lives in `logic/`, so a stub just duplicates it; (b) never drop a concrete artifact that does exist — a lone `environment.md` is wrong when the work has one; (c) when the work's **codebase** persists in a linkable store (a directory of script variants, a released or versioned repo), index it as a **comprehensive pointer index** in `src/artifacts.md` — one link per code artifact (every script/config/module), nothing aggregated into a vague bucket, nothing copied; a lossy subset-copy is the failure; (d) **run records are NOT code** — per-run logs, metrics, and run tables are empirical evidence and live in `evidence/` (`evidence/results/<node>.md`, `evidence/logs/log_pointers.md`), linked straight from trace/claims, **never in `src/artifacts.md`**. **Transcribe real source into `src/execution/` only when it would otherwise be lost** — code that lives solely inside the paper, or a source not externally persisted (then `# Grounding: transcribed`, cite path). No implementation in the input → none applies.
 15. **Source-bounded minimums**: any count or required field is a target, never a license to invent. If the source supports fewer, produce what is real and note the shortfall; for an unstated field write "Not specified in paper" rather than guessing
 16. **Cite by verification, and ask on conflict**: a source reference (evidence `Source`, trace `source_refs`, claim `Proof`, a repo `file:line`/path) promises the cited location actually contains the claim — open it and confirm. Never transcribe a *description* of an artifact as a verified fact about it. **When the code repo and the paper disagree on a fact (line count, path, value, behavior), do NOT pick one silently — surface the conflict to the user and ask which source to follow.** If unverifiable and the user is unavailable, attribute it ("per §X") or omit. Carry a statistic's scope/denominator in its `Source`. **This extends to every load-bearing number in a claim/heuristic `Statement`/`Rationale`: it carries a `**Sources**` entry whose verbatim «quote» you opened and confirmed contains that value — a memory-filled value or a bare path is fabrication; use `[pending]` when you cannot open the source**
 

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

@@ -19,20 +19,22 @@ logic/
                                     #   study_design / formalization / results / proofs /
                                     #   design / heuristics … — whatever fits THIS work
   related_work.md                   # ✓ Typed dependency graph (RDO)
-src/
+src/                                # the CODEBASE (code in ANY language — never judged by a .py suffix)
   environment.md                    # ✓ Data/software/hardware/protocols/seeds
+  artifacts.md                      # as warranted: pointer index to the codebase (every script/config/module)
   configs/                          # as warranted: hyperparameters / inference / deployment
-  execution/{module}.py             # as warranted: grounded code stub (or absent — see below)
+  execution/{module}.{ext}          # as warranted: transcribed/grounded code, any language (or absent — see below)
   prompts/, ...                     # as warranted: prompt templates, etc.
 data/                               # as warranted: dataset.md + preprocessing.md
 trace/
   exploration_tree.yaml             # ✓ Research DAG: nested YAML tree with typed nodes
-evidence/
+evidence/                           # derived + observed: diffs, run records, results, logs, tables, figures
   README.md                         # ✓ Index mapping every evidence file to claims
   tables/                           # ✓ every numbered Table: tableN.md + tableN.png
   figures/                          # ✓ every numbered Figure: figureN.md + figureN.png
+  results/                          # as warranted: per-node run records (run tables: run_id, params, metrics, export_id)
+  logs/                             # as warranted: log_pointers.md — direct per-run log pointers (by export_id)
   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)
 ```
 
@@ -364,13 +366,15 @@ pseudo-code — that information already lives in `logic/solution/`, and re-enco
 duplicates it.** A concrete artifact that IS raw "code" — e.g. a prompt or template — is different:
 store it verbatim in `src/prompts/`, don't paraphrase it. A hollow invented API is a hallucination.
 
-## src/artifacts.md  (the artifact index — comprehensive pointer file when the source persists externally)
+## src/artifacts.md  (the CODEBASE pointer index — code only, any language)
 
-`src/` must represent the implementation **losslessly**. When the work's artifacts **persist in a
-linkable external store** (a repo, a run database, a released tool/dataset), `artifacts.md` is the
-**comprehensive pointer index** — a link to **every** artifact (every run, config, log, script,
-released binary, dataset), grounded in the real files, nothing aggregated into a vague bucket and
-nothing copied. One block (or row) per artifact:
+`src/artifacts.md` is the **pointer index to the experiment's codebase** — the *code*: every script,
+config, and module, in **any language** (judged by content, never by a `.py` suffix). When the codebase
+persists in a linkable store (a directory of script variants, a released/versioned repo), point at every
+code artifact, grounded in the real files, nothing aggregated into a vague bucket and nothing copied.
+**Run records do NOT belong here** — per-run logs, metrics, and run tables are evidence
+(`evidence/results/`, `evidence/logs/log_pointers.md`), linked straight from trace/claims, not indexed in
+`artifacts.md`. One block (or row) per **code** artifact:
 
 **Capture is the fallback, not the default.** Transcribe a file into `src/execution/` only when it
 would otherwise be **lost** — code that lives solely inside the paper, or a source not externally
@@ -379,8 +383,6 @@ 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}
@@ -426,25 +428,31 @@ Reproducibility for any field. For purely analytical work, state so explicitly.
 
 ---
 
-## evidence/changes/{node-id}.diff.md  (Research Visualizer changed-code diffs)
+## evidence/results/{node-or-name}.md  (run records — the outputs of running the code)
 
-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:
+Per-experiment **run records**: the run table(s) a node produced. **This is where runs live**, not in
+`src/artifacts.md`. One file per experiment node (or per result group):
 
 ```markdown
-# Change {node-id}: {short description}
-- **Base**: A01   (→ src/artifacts.md anchor; path + sha256 + original location live there)
-- **Variant**: A07
-- **Language**: python
+# {Node/result}: {short description}
+- **Trace node**: N22
+- **Claim**: C04
 
-<unified diff fenced as ```diff … ``` — verbatim from the real scripts>
+| run_id | {params…} | metric | export_id |
+|--------|-----------|--------|-----------|
+| …      | …         | …      | …         |
 ```
 
-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/logs/log_pointers.md  (direct per-run log pointers)
+
+A single index of **direct pointers to each run's log**, grouped by node — `<store>/<export_id>/<log>`
+(e.g. `train.log`, or the field's equivalent). Pointer-resolution only; do not transcribe logs:
+
+```markdown
+## N22: WD sweep (C04)
+- `data/train/00023-…/train.log`   — winning run
+- packet: v1-008
+```
 
 ---
 
@@ -502,7 +510,6 @@ tree:
     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

@@ -4,8 +4,9 @@ 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.
+  and a per-step drill-down on the right — what the step did (its narrative written in plain language a
+  person can follow), 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
@@ -21,7 +22,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash(python3 *|base64 *|find *|ls
 metadata:
   author: ara-commons
   category: research-tooling
-  version: "1.0.0"
+  version: "1.0.1"
   tags: [research, visualization, trajectory, exploration-tree, html]
 ---
 
@@ -93,16 +94,22 @@ One self-contained file, default `<ara-dir>/trajectory.html` (override with `--o
    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 `[]`.
+5c. **Write each step's narrative as plain language (same layout, human words).** The trace's notes are
+   written for an agent; rendered as-is they read like a log and a person can't follow what happened or
+   why it mattered. For each node, write its narrative — `thinking`, and `body` if used — in plain
+   language a reader who has NOT seen the ARA can follow: your own words, translating the trace's
+   agent-facing deliberation, **not** a verbatim paste; expand jargon on first use and state the point,
+   not the log line. This changes ONLY the prose that fills the existing reasoning block — keep every
+   block and the layout exactly as they are. Stay grounded: introduce no number, name, or claim that is
+   not already in that node, and keep claim `Statement`s, `Sources` quotes and table numbers **verbatim**
+   in the why/result blocks — those are the receipts.
 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.
+   Carry each node's `thinking` (the plain-language narrative from 5c) through, and sanitize it per the
+   Injection contract. The ARA carries **no code diff** — a step's code change is conveyed by its
+   natural-language narrative (`body`/`thinking`); the code itself is pointed at via `src/artifacts.md`.
 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.
@@ -121,16 +128,17 @@ One self-contained file, default `<ara-dir>/trajectory.html` (override with `--o
   `/* __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)
 
+- **Speak human in the narrative, quote the evidence.** A node's narrative (`thinking`/`body`) is plain
+  language — your own words, a grounded translation (5c), not a verbatim paste. Everything that is
+  *evidence* — claim `Statement`s, `Sources` quotes, table cells/numbers, relations, definitions — is
+  reproduced **verbatim** in the why/result/overlay blocks. The narrative explains; the receipts prove. A
+  narrative that states a number absent from the node fails; so does an evidence block that paraphrases.
 - 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.

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

@@ -49,33 +49,12 @@ Fallback if no README row: scan the figure/table `.md` for an inline `Supports C
 - 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".
+`src/artifacts.md` is the **codebase** pointer index — the code (scripts/configs/modules) in **any
+language** (never assume `.py`). Populate `artifact[]` from it plus the relevant `logic/solution/*.md`
+recipe section. The **run records** a node produced are NOT code — they arrive via `result` (from
+`evidence/results/` run tables + `evidence/logs/log_pointers.md`), never via `artifact[]`. Only when a
+real transcribed `src/execution/` file exists (legacy / paper-only code) do you point at it.
+**Never resolve the external store in v1** — the pointer text is the value.
 
 ## The `ARA_DATA` object (exact schema the scaffold reads)
 
@@ -92,13 +71,6 @@ live in ONE place and are referenced by id (weak coupling):
   // (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",
@@ -106,7 +78,7 @@ live in ONE place and are referenced by id (weak coupling):
       "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
+      "thinking": "<the step's narrative in PLAIN, human language — a grounded translation, NOT a verbatim paste (SKILL.md 5c); 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
@@ -132,15 +104,7 @@ live in ONE place and are referenced by id (weak coupling):
 
       "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
   ]
@@ -151,8 +115,8 @@ live in ONE place and are referenced by id (weak coupling):
 - 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).
+  common (e.g. a bare `decision` node) — the viewer simply omits those blocks. `thinking` is likewise
+  optional; omit when absent (a payload without it is byte-compatible).
 - `status` is lower-cased by the viewer for styling; pass it as written (`Supported`, `hypothesis`, …).
 
 ### Size guards

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

@@ -25,10 +25,6 @@ top-level nodes have `parent: null`.
 - `also_depends_on: [ids]` → emit as `depends_on` (DAG cross-edges).
 - `thinking` — verbatim agent deliberation, **passed straight through** (the primary reasoning block).
   Absent ⇒ omit. Never paraphrase or synthesize it.
-- `code_change` — when the compiler wrote one onto the node (`base_artifact` / `variant_artifact` /
-  `lang` / `diff_file`), **pass it through**. The `diff_file`→`diff` inlining and the top-level
-  `artifacts[]` index are done in the binding/inline step (binding.md); the visualizer never computes a
-  diff itself. Absent ⇒ omit.
 
 ## 3. Title + body normalization (the dialect bridge)
 
@@ -107,9 +103,6 @@ a `{thought, action, observation/result}`. Map it onto the tree:
 - `source_refs` = a pointer back to the log line(s) (shown, never resolved).
 - nesting via `children`; convergence via `also_depends_on`; a discarded branch via `isolated`.
 
-No `logic/` or `evidence/` is required; enrich the same tree later (via the compiler) to add claims,
-evidence, and per-node `code_change` diffs.
-
 # 8. The four `logic/` enrichment layers (all optional)
 
 These produce the OPTIONAL `context` / `glossary` / `dependencies` / `recipes` keys (and the per-node

package/skills/research-visualizer/references/trajectory-template.html

@@ -151,15 +151,6 @@
   table.md th{background:var(--panel2);color:var(--ink);font-weight:700;text-transform:uppercase;font-size:10.5px;letter-spacing:.04em}
   pre.snip{background:var(--code-bg);border:1px solid var(--line);border-radius:6px;padding:10px 12px;overflow:auto;font-size:12px;color:var(--ink);white-space:pre-wrap}
 
-  /* changed-code diff block */
-  pre.diff{background:var(--code-bg);border:1px solid var(--line);border-radius:6px;padding:8px 0;overflow:auto;font-size:12px;margin:11px 0;white-space:pre}
-  pre.diff .dl{display:block;padding:0 12px;border-left:3px solid transparent}
-  pre.diff .dl.add{background:var(--add-bg);color:var(--add-ink);border-left-color:var(--ok)}
-  pre.diff .dl.del{background:var(--del-bg);color:var(--del-ink);border-left-color:var(--warn)}
-  pre.diff .dl.hunk{color:var(--hunk);background:var(--panel2)}
-  pre.diff .dl.meta{color:var(--muted)}
-  pre.diff .dl.ctx{color:#3a423c}
-
   .ptr{font-size:13px;margin:7px 0}
   .ptr .path{font-family:var(--mono);color:#46504a}
   .truncated{color:var(--muted);font-size:11.5px;font-style:italic}
@@ -267,18 +258,13 @@
     "title": "Research Visualizer — template demo",
     "authors": ["(demo data — replaced by the research-visualizer skill)"],
     "year": "", "venue": "", "ara_dir": "",
-    "abstract": "This bare template ships with demo nodes so it opens standalone and shows the reasoning-first layout, a changed-code diff, an experiment, a dead end, and an isolated subtree. Running /research-visualizer on a real ARA overwrites this block."
+    "abstract": "This bare template ships with demo nodes so it opens standalone and shows the reasoning-first layout, an experiment, a dead end, and an isolated subtree. Running /research-visualizer on a real ARA overwrites this block."
   },
   "order": ["N01", "N02", "N03", "NV1"],
-  "artifacts": [
-    { "id":"A01","name":"encode.py @ baseline","path":"src/encode.py","sha256":"0000…base","original_location":"repo@main:src/encode.py" },
-    { "id":"A02","name":"encode.py @ variant","path":"src/encode.py","sha256":"1111…var","original_location":"repo@feat:src/encode.py" }
-  ],
   "nodes": [
-    { "id":"N01","type":"question","parent":null,"title":"Is this template wired correctly end to end?","body":"","thinking":"Before trusting the renderer on real data, prove every node state (reasoning, diff, result, dead end, isolated) shows up from one fixed scaffold.","support_level":"explicit","isolated":false,"depends_on":[],"source_refs":["notes.md:1-4"],
+    { "id":"N01","type":"question","parent":null,"title":"Is this template wired correctly end to end?","body":"","thinking":"Before trusting the renderer on real data, prove every node state (reasoning, result, dead end, isolated) shows up from one fixed scaffold.","support_level":"explicit","isolated":false,"depends_on":[],"source_refs":["notes.md:1-4"],
       "why":[], "result":{"sources":[],"figures":[],"tables":[],"data":[]}, "verified_by":[], "artifact":[] },
     { "id":"N02","type":"experiment","parent":"N01","title":"Precompute the field encoder once per type","body":"Replaced the per-call json.dumps path with a cached per-type encoder; output byte-identical.","thinking":"The profile said serialization dominates, and the dead end showed per-field reflection is the trap — so keep the hand-written encoding but pay its setup cost once, not per request.","support_level":"explicit","isolated":false,"depends_on":[],"source_refs":["notes.md:10-22"],
-      "code_change":{ "base_artifact":"A01","variant_artifact":"A02","lang":"python","diff":"@@ -1,4 +1,5 @@\n def encode(rec):\n-    return json.dumps(rec)\n+    enc = encoder_for(type(rec))\n+    return enc(rec)" },
       "why":[{"id":"C01","statement":"Paying per-type setup once instead of per call removes the hot-path cost without changing output.","status":"supported","conditions":"Holds when the type set is small and stable across calls.","falsification":"If amortized setup ever exceeds the per-call cost it replaces.","provenance":"ai-executed","dependencies":[]}],
       "result":{
         "sources":[{"quote":"p99 down 38%; output byte-identical to the baseline","ref":"figures/demo.md:14"}],
@@ -320,7 +306,6 @@
 
   const nodes = DATA.nodes || [];
   const byId = new Map(nodes.map(n => [n.id, n]));
-  const artifactById = new Map((DATA.artifacts||[]).map(a => [a.id, a]));
   const kids = new Map();
   nodes.forEach(n => kids.set(n.id, []));
   let roots = [];
@@ -373,23 +358,6 @@
   }
   function chips(arr, klass){ return arr&&arr.length ? '<div class="chips">'+arr.map(x=>'<span class="chip '+(klass||"")+'">'+esc(x)+'</span>').join("")+'</div>' : ""; }
 
-  // resolve an artifact id (src/artifacts.md) to a label + a shown-not-resolved pointer tooltip
-  function artLabel(id){ const a=artifactById.get(id); return a ? (a.name||a.path||id) : id; }
-  function artTip(id){ const a=artifactById.get(id); return a ? [a.path,a.sha256,a.original_location||a.original_path].filter(Boolean).join("  ·  ") : ""; }
-  function renderDiff(cc){
-    const head=[];
-    if(cc.base_artifact)    head.push('<span class="chip" title="'+esc(artTip(cc.base_artifact))+'">base: '+esc(artLabel(cc.base_artifact))+'</span>');
-    if(cc.variant_artifact) head.push('<span class="chip" title="'+esc(artTip(cc.variant_artifact))+'">variant: '+esc(artLabel(cc.variant_artifact))+'</span>');
-    if(cc.lang)             head.push('<span class="chip ext">'+esc(cc.lang)+'</span>');
-    const chiprow = head.length?'<div class="chips">'+head.join("")+'</div>':"";
-    if(cc.diff){
-      const lc = L => /^(\+\+\+|---|diff |index )/.test(L) ? "meta" : (L[0]==="+" ? "add" : (L[0]==="-" ? "del" : (/^@@/.test(L) ? "hunk" : "ctx")));
-      const body = String(cc.diff).split("\n").map(L=>'<span class="dl '+lc(L)+'">'+esc(L||" ")+'</span>').join("");
-      return chiprow+'<pre class="diff">'+body+'</pre>';
-    }
-    return chiprow+'<div class="empty">'+esc(cc.note||"Diff not available in this checkout — base/variant scripts not present; pointers only.")+'</div>';
-  }
-
   function renderDetail(n){
     const d = document.getElementById("detail");
     let h = '<div class="dhead"><span class="badge '+cls(n.type)+'">'+esc(n.type)+'</span>'+
@@ -413,11 +381,6 @@
     if(n.recipe_refs&&n.recipe_refs.length) reason += recipeChips(n.recipe_refs);
     h += block(n.thinking?"reasoning":"what", n.type, reason, true, "reason");
 
-    // changed code (unified diff) — open when present
-    if(n.code_change && (n.code_change.diff || n.code_change.base_artifact || n.code_change.variant_artifact || n.code_change.note)){
-      h += block("changed code", n.code_change.lang||"diff", renderDiff(n.code_change), true);
-    }
-
     // result (the grounded payload) — open
     const r = n.result||{};
     if((r.sources&&r.sources.length)||(r.figures&&r.figures.length)||(r.tables&&r.tables.length)||(r.data&&r.data.length)){

package/src/installer.js

@@ -143,7 +143,11 @@ export function uninstall(opts) {
 }
 
 /**
- * "Update" = re-install (overwrite) every currently tracked skill.
+ * "Update" = reconcile this agent against the FULL bundled skill set:
+ * re-install (overwrite) every tracked skill AND pull in any skills that
+ * were added to the package since the last install. Skips agents that have
+ * nothing installed — update should refresh an existing setup, not bootstrap
+ * a fresh one (use `install` for that).
  */
 export function update(opts) {
   const { agentId, local = false, cwd, quiet = false } = opts;
@@ -157,7 +161,8 @@ export function update(opts) {
     if (!quiet) console.log(`  (no skills tracked at ${targetDir})`);
     return { agent: agent.id, targetDir, results: [] };
   }
-  return install({ agentId, skillIds: ids, local, cwd, force: true, quiet });
+  // skillIds: [] => all bundled skills; force => overwrite the tracked ones.
+  return install({ agentId, skillIds: [], local, cwd, force: true, quiet });
 }
 
 /**