omkit 0.8.10 → 0.8.12

package/README.md

@@ -185,11 +185,11 @@ flakyBackgroundJob().result.catch((e) => console.warn("job failed, carrying on",
 
 Every action's output, events, asserts, snapshots, and lifecycle land on **one timeline** — streamed live to the terminal (curated milestones) and written to a per-run folder:
 
-- `result.json` — the run's tree, per-node status, verdict, and curated artifacts.
+- `result.json` — the run's tree, per-node status, verdict, and curated artifacts. Each node also carries what its definition declared about itself: the `.describe()` summary, the `.mcp()` exposure, and the `.args()` schema as JSON Schema.
 - `raw.jsonl` — every entry, machine-readable.
 - `main.log` + one `.log` per action — the human-readable timelines.
 - `events.log` / `asserts.log` / `snapshots.log` / `artifacts.log` — cross-cutting rollups.
-- `report.html` — the whole run as one self-contained page: a timeline of every action with its events, a flame graph, a flow graph of the tree, per-action details, logs, assertions, and the run's snapshots and images. Everything is inlined (data, base64 images, d3), so it opens straight from disk and survives being zipped or attached.
+- `report.html` — the whole run as one self-contained page: a timeline of every action with its events, a flame graph, a flow graph of the tree, per-action details, logs, assertions, the run's snapshots and images, and each action's source (the `<>` button next to a block). Everything is inlined (data, base64 images, d3), so it opens straight from disk and survives being zipped or attached.
 
 `ctx` also gives each action `assert(cond, msg)` (tallies into the run's verdict), `snapshot(name, value)` (captures JSON state to the run folder), and `artifact(name, file, opts?)` (labels a file the action wrote — name, optional description, MIME inferred from the extension — and returns its absolute path) — so a run is an inspectable artifact, not just an exit code. Write the files you label under `ctx.artifactsFolder`, the run's own output folder.
 

package/dist/core/ActionRun.d.ts

@@ -3,7 +3,7 @@ import type { ActionRef } from "../foundation/ActionRef.ts";
 import type { LogStore } from "../output/log/LogStore.ts";
 import type { SnapshotStore } from "../output/snapshot/SnapshotStore.ts";
 import type { ArtifactStore } from "../output/artifact/ArtifactStore.ts";
-import type { Activity, Exec, InstanceEvents, NodeStatus } from "./types.ts";
+import type { ActionMeta, Activity, Exec, InstanceEvents, NodeStatus } from "./types.ts";
 /** Everything a node needs to exist, minus its behavior. */
 export interface NodeInit {
     readonly store: LogStore;
@@ -45,6 +45,8 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     readonly path: string;
     readonly parentId: string | null;
     readonly tags: string[];
+    /** What the definition said about itself (`.describe()`, `.mcp()`, `.args()`); for the record. */
+    meta: ActionMeta | undefined;
     /** The captured args this node ran with (for the log header); set at run start. */
     args: readonly unknown[];
     readonly children: ActionRun[];

package/dist/core/ActionRun.js

@@ -18,6 +18,8 @@ export class ActionRun {
     path;
     parentId;
     tags = [];
+    /** What the definition said about itself (`.describe()`, `.mcp()`, `.args()`); for the record. */
+    meta;
     /** The captured args this node ran with (for the log header); set at run start. */
     args = [];
     children = [];

package/dist/core/ExecutionTree.d.ts

@@ -41,6 +41,7 @@ export declare class ExecutionTree {
     private readonly snapshotStore;
     private readonly artifactStore;
     private readonly registry;
+    private readonly schemaCache;
     private readonly unsettled;
     private readonly originalLog;
     private streaming;
@@ -101,6 +102,12 @@ export declare class ExecutionTree {
     private printSummary;
     private verdictOk;
     private nodeView;
+    /**
+     * The node's self-description, projected for the record. The root's comes from the om
+     * builder; a child's from its action definition. The args schema is converted here, once per
+     * definition, so a step launched a thousand times converts its schema once.
+     */
+    private metaView;
     /** Test seam: the projected run view (same object written to result.json). */
     runViewForTest(): RunView;
     /** Test seam: the run's curated artifacts. */

package/dist/core/ExecutionTree.js

@@ -61,6 +61,7 @@ export class ExecutionTree {
     snapshotStore;
     artifactStore = new ArtifactStore();
     registry = [];
+    schemaCache = new Map();
     unsettled = new Set();
     originalLog = console.log.bind(console);
     streaming;
@@ -137,6 +138,7 @@ export class ExecutionTree {
             // into the parent's log, attributed to this child's id.
             bubble: (message) => this.append(parent, "child", id, message),
         });
+        node.meta = spec.meta;
         parent.children.push(node);
         this.registry.push(node);
         // Launch reference — the parent's pointer to the child's own (absolute) log, plus where
@@ -386,9 +388,34 @@ export class ExecutionTree {
             endedAt: node.endedAt,
             duration: node.duration,
             logFile: this.logFile(node.path),
+            ...this.metaView(node),
             children: node.children.map((child) => this.nodeView(child)),
         };
     }
+    /**
+     * The node's self-description, projected for the record. The root's comes from the om
+     * builder; a child's from its action definition. The args schema is converted here, once per
+     * definition, so a step launched a thousand times converts its schema once.
+     */
+    metaView(node) {
+        const meta = node.parentId === null
+            ? { description: this.description, mcp: this.mcp, describeArgs: node.meta?.describeArgs }
+            : node.meta;
+        if (!meta)
+            return {};
+        let inputSchema;
+        if (meta.describeArgs) {
+            if (!this.schemaCache.has(meta.describeArgs)) {
+                this.schemaCache.set(meta.describeArgs, meta.describeArgs().inputSchema);
+            }
+            inputSchema = this.schemaCache.get(meta.describeArgs);
+        }
+        return {
+            ...(meta.description === undefined ? {} : { description: { ...meta.description } }),
+            ...(meta.mcp === undefined ? {} : { mcp: { ...meta.mcp } }),
+            ...(inputSchema === undefined ? {} : { inputSchema }),
+        };
+    }
     /** Test seam: the projected run view (same object written to result.json). */
     runViewForTest() {
         return this.runView();

package/dist/core/action.js

@@ -49,9 +49,13 @@ class Builder {
         // No `.args()` on this path, so there is nothing to describe — or to resolve against.
         const describeArgs = () => describeSchema(undefined);
         const parseArgs = (supplied) => supplied;
+        const meta = {
+            ...(description === undefined ? {} : { description }),
+            ...(mcp === undefined ? {} : { mcp }),
+        };
         const exec = body;
         const create = (...args) => {
-            const spec = { name, args, tags: [], body: exec, definedAt };
+            const spec = { name, args, tags: [], body: exec, definedAt, meta };
             return ExecutionTree.require().launch(spec);
         };
         return Object.assign(create, {
@@ -102,6 +106,11 @@ class ArgsBuilder {
         // that built it — rather than in whichever copy the discovery child is running.
         const schema = this.schema;
         const describeArgs = () => describeSchema(schema);
+        const meta = {
+            ...(description === undefined ? {} : { description }),
+            ...(mcp === undefined ? {} : { mcp }),
+            describeArgs,
+        };
         // `safeParse` is what applies `.default()`s, so this is where an advertised default
         // becomes the effective one. A refusal names the action and every failing field.
         const parseArgs = (supplied) => {
@@ -112,7 +121,7 @@ class ArgsBuilder {
         };
         const exec = body;
         const create = (...args) => {
-            const spec = { name, args, tags: [], body: exec, definedAt };
+            const spec = { name, args, tags: [], body: exec, definedAt, meta };
             return ExecutionTree.require().launch(spec);
         };
         return Object.assign(create, {

package/dist/core/om.js

@@ -37,6 +37,9 @@ function launch(name, site, description, exposure, body, schema) {
     }
     const tree = new ExecutionTree(name, site, description, exposure);
     ExecutionTree.current = tree;
+    // The root's description and exposure live on the tree; its schema rides on the node.
+    if (schema !== undefined)
+        tree.root.meta = { describeArgs: () => describeSchema(schema) };
     const rootBody = (ctx) => body({
         signal: ctx.signal,
         logs: ctx.logs,

package/dist/core/types.d.ts

@@ -239,4 +239,17 @@ export interface LaunchSpec {
     readonly body: Exec<object, unknown, unknown>;
     /** `file:line` where the action was defined; carried onto the node for its log header. */
     readonly definedAt: string | undefined;
+    /** What the definition declared about itself — carried onto the node for the run record. */
+    readonly meta?: ActionMeta;
+}
+/**
+ * A definition's self-description, as it travels onto each node it launches: what
+ * `.describe()` and `.mcp()` said, and the `.args()` schema as JSON Schema. Read only by the
+ * run record (`result.json`, `report.html`) — the runtime never branches on it.
+ */
+export interface ActionMeta {
+    readonly description?: OmDescription;
+    readonly mcp?: ResolvedMcpExposure;
+    /** Converts the declared args schema; called once, at finalize. */
+    readonly describeArgs?: () => DescribedArgs;
 }

package/dist/output/writers/ReportWriter.js

@@ -33,10 +33,14 @@ export async function writeReport(file, input) {
     const assets = [];
     const files = await collectFiles(input, assets);
     const snapshots = await collectSnapshots(input);
+    const root = await projectRoot(input.folder);
     const payload = {
         version: 1,
         name: input.name,
         folder: input.folder,
+        projectRoot: root,
+        sources: definitionSources(input.run.root, root),
+        code: await definitionCode(input.run.root),
         generatedAt: Date.now(),
         run: input.run,
         entries: input.entries,
@@ -55,29 +59,29 @@ function renderPage(input, payload, assets, code) {
     const blobs = assets
         .map((a) => `<script type="text/plain" id="${a.id}" data-mime="${a.mime}">${a.data}</script>`)
         .join("\n");
-    return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtml(title)}</title>
-<style>${code.css}</style>
-</head>
-<body>
-<div id="loader" role="status" aria-live="polite">
-  <div class="loader-card">
-    <div class="loader-spin"></div>
-    <div class="loader-title">${escapeHtml(title)}</div>
-    <div class="loader-step" id="loader-step">Loading the run record…</div>
-  </div>
-</div>
-<div id="app" hidden></div>
-<script id="omkit-data" type="application/json">${inertJson(payload)}</script>
-${blobs}
-<script>${inertScript(code.d3)}</script>
-<script>${inertScript(code.client)}</script>
-</body>
-</html>
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>${code.css}</style>
+</head>
+<body>
+<div id="loader" role="status" aria-live="polite">
+  <div class="loader-card">
+    <div class="loader-spin"></div>
+    <div class="loader-title">${escapeHtml(title)}</div>
+    <div class="loader-step" id="loader-step">Loading the run record…</div>
+  </div>
+</div>
+<div id="app" hidden></div>
+<script id="omkit-data" type="application/json">${inertJson(payload)}</script>
+${blobs}
+<script>${inertScript(code.d3)}</script>
+<script>${inertScript(code.client)}</script>
+</body>
+</html>
 `;
 }
 async function collectFiles(input, assets) {
@@ -117,7 +121,11 @@ async function collectFiles(input, assets) {
             out.push({ ...base, size, text: await readFile(abs, "utf8") });
         }
         else {
-            out.push({ ...base, size, omitted: isText(meta.mime) ? `larger than ${mb(TEXT_CAP)}` : "binary" });
+            out.push({
+                ...base,
+                size,
+                omitted: isText(meta.mime) ? `larger than ${mb(TEXT_CAP)}` : "binary",
+            });
         }
     };
     for (const a of input.artifacts) {
@@ -150,7 +158,14 @@ async function collectSnapshots(input) {
             continue;
         const name = e.message.slice(0, split);
         const abs = e.message.slice(split + 3);
-        const base = { seq: ++seq, name, nodeId: e.nodeId, ts: e.ts, file: abs, rel: relTo(input.folder, abs) };
+        const base = {
+            seq: ++seq,
+            name,
+            nodeId: e.nodeId,
+            ts: e.ts,
+            file: abs,
+            rel: relTo(input.folder, abs),
+        };
         try {
             const raw = await readFile(abs, "utf8");
             if (raw.length > SNAPSHOT_CAP) {
@@ -183,6 +198,100 @@ function artifactTimes(entries) {
     }
     return out;
 }
+/**
+ * The project the run belongs to, for project-relative paths: the nearest ancestor of the run
+ * folder holding `.git`, else the folder `logs/` sits in (the root omkit was given), else cwd.
+ */
+async function projectRoot(folder) {
+    let dir = path.resolve(folder);
+    for (;;) {
+        try {
+            await stat(path.join(dir, ".git"));
+            return dir;
+        }
+        catch {
+            /* keep climbing */
+        }
+        const up = path.dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    return process.env.OMKIT_ROOT ? path.resolve(process.env.OMKIT_ROOT) : process.cwd();
+}
+/** Each distinct `definedAt` site → its file, relative to the project root, forward-slashed, no line. */
+function definitionSources(root, projectDir) {
+    const out = {};
+    const visit = (n) => {
+        if (n.definedAt && !(n.definedAt in out)) {
+            const file = n.definedAt.replace(/:\d+(:\d+)?$/, "");
+            out[n.definedAt] = path.relative(projectDir, file).split(path.sep).join("/") || file;
+        }
+        n.children.forEach(visit);
+    };
+    visit(root);
+    return out;
+}
+/** Longest excerpt shown per definition; a body past this is cut, and says so. */
+const CODE_LINES = 300;
+/**
+ * Each distinct `definedAt` site → the source of the definition there: the whole top-level
+ * statement holding that line (`export const x = action(…)…run(…)`, or the `om(…).run(…)` call),
+ * found with the TypeScript parser so it is the real extent, not a guess at one. A site whose
+ * file is gone or unparseable gets a window of lines around it instead, or nothing.
+ */
+async function definitionCode(root) {
+    const sites = new Set();
+    const visit = (n) => {
+        if (n.definedAt)
+            sites.add(n.definedAt);
+        n.children.forEach(visit);
+    };
+    visit(root);
+    if (sites.size === 0)
+        return {};
+    // Loaded only here: the parser is heavy, and a run that never writes a report never pays for it.
+    const ts = (await import("typescript")).default;
+    const out = {};
+    const texts = new Map();
+    for (const site of sites) {
+        const m = /^(.*):(\d+)(?::\d+)?$/.exec(site);
+        if (!m)
+            continue;
+        const file = m[1];
+        const line = Number(m[2]);
+        if (!texts.has(file))
+            texts.set(file, await readFile(file, "utf8").catch(() => null));
+        const text = texts.get(file);
+        if (!text)
+            continue;
+        const lang = /\.[cm]?tsx?$/i.test(file) ? "ts" : "js";
+        const lines = text.split(/\r?\n/);
+        let from = Math.max(1, line - 10);
+        let to = Math.min(lines.length, line + 20);
+        try {
+            const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+            const pos = sf.getPositionOfLineAndCharacter(Math.min(line, sf.getLineStarts().length) - 1, 0);
+            const stmt = sf.statements.find((s) => s.getStart(sf) <= pos && pos < s.getEnd()) ??
+                sf.statements.find((s) => s.getFullStart() <= pos && pos < s.getEnd());
+            if (stmt) {
+                from = sf.getLineAndCharacterOfPosition(stmt.getStart(sf, true)).line + 1;
+                to = sf.getLineAndCharacterOfPosition(stmt.getEnd()).line + 1;
+            }
+        }
+        catch {
+            /* fall back to the window around the line */
+        }
+        const truncated = to - from + 1 > CODE_LINES;
+        out[site] = {
+            start: from,
+            text: lines.slice(from - 1, truncated ? from - 1 + CODE_LINES : to).join("\n"),
+            lang,
+            ...(truncated ? { truncated } : {}),
+        };
+    }
+    return out;
+}
 async function walk(dir, depth = 0) {
     if (depth > 4)
         return [];

package/dist/output/writers/report/report.css

@@ -153,10 +153,13 @@ button { font: inherit; color: inherit; }
 .guide::before { content: ""; position: absolute; left: 7px; top: 0; bottom: 0; border-left: 1px solid var(--line); }
 
 .chart { position: relative; min-width: 0; }
-.chart svg { display: block; }
-.chart .bar-label { font-size: 12px; fill: var(--bar-text); font-weight: 500; pointer-events: none; }
+.chart svg { display: block; overflow: hidden; }
+.chart .bar-label { font-size: 12px; fill: var(--bar-text); font-weight: 500; cursor: pointer; }
+.chart .hit { fill: transparent; cursor: pointer; }
+.chart .hit:hover + .bar { filter: brightness(1.15); }
 .chart .bar-label.outside { fill: var(--text); }
-.chart .mark-label { font-size: 11px; fill: var(--text-2); pointer-events: none; }
+.chart .mark-label { font-size: 11px; fill: var(--text-2); cursor: pointer; }
+.chart .mark-label:hover { fill: var(--text); }
 .chart .grid line { stroke: var(--line-soft); }
 .chart .cursor { stroke: var(--text-2); stroke-dasharray: 3 3; pointer-events: none; }
 .chart .link { fill: none; stroke: var(--text-3); stroke-width: 1.2; }
@@ -175,7 +178,7 @@ button { font: inherit; color: inherit; }
 .flow-link { fill: none; stroke: var(--text-3); stroke-width: 1.3; }
 .flame-rect { cursor: pointer; stroke: var(--panel); stroke-width: 1; }
 .flame-rect.selected { stroke: var(--text); stroke-width: 2; }
-.flame-text { font-size: 11px; fill: var(--bar-text); pointer-events: none; }
+.flame-text { font-size: 11px; fill: var(--bar-text); cursor: pointer; }
 
 /* ── details ────────────────────────────────────────────── */
 .details { display: grid; grid-template-rows: auto auto minmax(0, 1fr); overflow: hidden; }
@@ -252,6 +255,31 @@ table.list tr:hover td { background: var(--raise); }
 }
 .tip .tt { font-weight: 600; margin-bottom: 2px; }
 .tip .ts { color: var(--text-2); }
+.tip.wide { max-width: 420px; min-width: 260px; }
+.tip .mono { font-family: var(--mono); font-size: 11px; overflow-wrap: anywhere; }
+.tip .small { color: var(--text-2); }
+.tip .badges { display: flex; flex-wrap: wrap; gap: 5px; margin: 6px 0; }
+.tip .badge { display: inline-flex; align-items: center; gap: 5px; padding: 1px 8px; border-radius: 999px; background: var(--raise); font-size: 11px; color: var(--text-2); }
+.tip .badge.mcp { background: var(--accent-soft); color: var(--accent); font-weight: 600; }
+.tip .summary { margin: 4px 0 8px; line-height: 1.45; }
+.tip .tkv { display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 2px 10px; font-variant-numeric: tabular-nums; }
+.tip .tkv .k, .tip .sec { color: var(--text-3); }
+.tip .sec { margin: 8px 0 3px; font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; }
+.tip .sec.fail { color: var(--fail); }
+.params { display: grid; gap: 3px; }
+.param { font: 11px/1.4 var(--mono); }
+.param .pn { color: var(--text); }
+.param .pt { color: var(--accent); margin-left: 6px; }
+.param .pd { color: var(--text-3); margin-left: 6px; }
+.param .pdesc { font-family: var(--sans); color: var(--text-2); margin-left: 10px; }
+.kv .v.defined { display: flex; align-items: center; gap: 6px; }
+.kv .v.defined a { min-width: 0; overflow-wrap: anywhere; font-family: var(--mono); font-size: 12px; }
+.icon-btn { flex: none; border: 1px solid var(--line); background: var(--panel-2); color: var(--text-2); border-radius: 6px; width: 24px; height: 22px; display: grid; place-items: center; cursor: pointer; padding: 0; }
+.icon-btn:hover { color: var(--text); border-color: var(--accent); }
+.icon-btn svg { width: 13px; height: 13px; }
+.tip .hint { margin-top: 8px; color: var(--text-3); font-size: 11px; }
+.tip kbd { font: 600 10px var(--mono); border: 1px solid var(--line); border-bottom-width: 2px; border-radius: 4px; padding: 0 4px; color: var(--text-2); }
+.badge-inline { display: inline-block; padding: 0 7px; border-radius: 999px; background: var(--accent-soft); color: var(--accent); font-size: 11px; font-weight: 600; }
 .tip img { display: block; max-width: 240px; max-height: 150px; border-radius: 4px; margin: 6px 0; border: 1px solid var(--line); }
 .modal { position: fixed; inset: 0; background: rgba(5, 8, 18, 0.72); z-index: 60; display: grid; place-items: center; padding: 28px; }
 .modal .box { background: var(--panel); border: 1px solid var(--line); border-radius: 12px; box-shadow: var(--shadow); max-width: min(1200px, 100%); max-height: 100%; display: grid; grid-template-rows: auto minmax(0, 1fr); overflow: hidden; }
@@ -264,6 +292,52 @@ table.list tr:hover td { background: var(--raise); }
 .menu button:hover { background: var(--raise); }
 .toast { position: fixed; bottom: 18px; left: 50%; transform: translateX(-50%); background: var(--raise); border: 1px solid var(--line); padding: 7px 14px; border-radius: 8px; z-index: 70; }
 
+/* ── title info, locate, defined-at, code popover ───────── */
+.title-row { display: flex; align-items: center; gap: 8px; min-width: 0; }
+.title-row h1 { min-width: 0; }
+.info-btn { flex: none; width: 22px; height: 22px; border: 0; border-radius: 50%; background: none; color: var(--text-3); display: grid; place-items: center; cursor: help; padding: 0; }
+.info-btn:hover, .info-btn:focus-visible { color: var(--accent); background: var(--accent-soft); }
+.info-btn svg { width: 17px; height: 17px; }
+.gal-item .cap .locate { margin-left: auto; width: 22px; height: 20px; }
+.kv .v.defined { flex-wrap: wrap; }
+.kv .v.defined .defined-name { color: var(--text-2); font-family: var(--mono); font-size: 12px; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+a.icon-btn { text-decoration: none; }
+.chart .code-btn, .flow-card .code-btn { cursor: pointer; opacity: 0; transition: opacity 0.12s; }
+.chart g.r:hover .code-btn, .chart g.r.sel .code-btn, .flow-card:hover .code-btn, .flow-card.selected .code-btn { opacity: 1; }
+.code-btn circle { fill: var(--panel); stroke: var(--text-3); stroke-width: 1.2; }
+.code-btn text { fill: var(--text-2); font: 700 9px var(--mono); pointer-events: none; }
+.code-btn:hover circle { stroke: var(--accent); }
+.code-btn:hover text { fill: var(--accent); }
+.chart line.pin.flash, .flame-view line.pin.flash { animation: pin-flash 0.6s ease-in-out 3; }
+.chart circle.mark.flash { animation: mark-flash 0.6s ease-in-out 3; transform-box: fill-box; transform-origin: center; }
+@keyframes pin-flash { 50% { stroke-width: 5; } }
+@keyframes mark-flash { 50% { transform: scale(1.9); } }
+.code-pop {
+  position: fixed; z-index: 58; width: 640px; max-width: 92vw; max-height: 70vh; display: flex; flex-direction: column;
+  background: var(--panel); border: 1px solid var(--line); border-radius: 10px; box-shadow: var(--shadow); overflow: hidden;
+}
+.code-pop .cp-head { display: flex; align-items: center; gap: 6px; padding: 6px 8px 6px 12px; background: var(--panel-2); border-bottom: 1px solid var(--line); }
+.code-pop .cp-path { font: 12px var(--mono); color: var(--text-2); min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.code-pop .cp-name { flex: 1; text-align: right; color: var(--text-3); font-size: 12px; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.code-pop .cp-body { overflow: auto; min-height: 0; }
+.code-pop .cp-code { font: 11.5px/1.65 var(--mono); padding: 8px 0; min-width: max-content; }
+.code-pop .cl { display: grid; grid-template-columns: 48px auto; white-space: pre; }
+.code-pop .cl.at { background: var(--accent-soft); }
+.code-pop .ln { color: var(--text-3); text-align: right; padding-right: 14px; user-select: none; }
+.code-pop .lc { padding-right: 16px; }
+.code-pop .cp-more { padding: 6px 14px 10px; font-size: 12px; }
+:root { --tk-c: #6f7a99; --tk-s: #7ee0a3; --tk-n: #f0b26b; --tk-k: #c792ea; --tk-f: #82aaff; --tk-t: #ffcb6b; }
+:root[data-theme="light"] { --tk-c: #6a737d; --tk-s: #116329; --tk-n: #b35900; --tk-k: #cf222e; --tk-f: #6639ba; --tk-t: #953800; }
+@media (prefers-color-scheme: light) {
+  :root:not([data-theme="dark"]) { --tk-c: #6a737d; --tk-s: #116329; --tk-n: #b35900; --tk-k: #cf222e; --tk-f: #6639ba; --tk-t: #953800; }
+}
+.tk-c { color: var(--tk-c); font-style: italic; }
+.tk-s { color: var(--tk-s); }
+.tk-n { color: var(--tk-n); }
+.tk-k { color: var(--tk-k); }
+.tk-f { color: var(--tk-f); }
+.tk-t { color: var(--tk-t); }
+
 @media (max-width: 1100px) {
   .bottom { grid-template-columns: minmax(0, 1fr); }
   .legend, .overview { display: none; }

package/dist/output/writers/report/report.js

@@ -40,6 +40,10 @@
     download: "M12 4v11M7 10l5 5 5-5M5 20h14",
     copy: "M9 9h11v11H9zM5 15V4h11",
     stop: "M6 6h12v12H6z",
+    info: "M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18zM12 11v5M12 8h.01",
+    locate: "M12 5a7 7 0 1 0 0 14 7 7 0 0 0 0-14zM12 2v3M12 19v3M2 12h3M19 12h3M12 10.5a1.5 1.5 0 1 0 0 3 1.5 1.5 0 0 0 0-3z",
+    code: "M8 7l-5 5 5 5M16 7l5 5-5 5",
+    external: "M14 4h6v6M20 4l-9 9M18 14v6H4V6h6",
   };
   const svgIcon = (name, extra) =>
     `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"${
@@ -297,6 +301,11 @@
       zoomToDomain(Math.max(0, d0), Math.max(0, d0) + ms);
     });
     app.querySelector("#more").addEventListener("click", (ev) => openMenu(ev.currentTarget));
+    const info = app.querySelector("#om-info");
+    info.addEventListener("mouseenter", (ev) => showTip(ev, omTip(), true));
+    info.addEventListener("mousemove", (ev) => moveTip(ev));
+    info.addEventListener("mouseleave", hideTip);
+    info.addEventListener("click", () => select(model.root.id));
 
     // ── zoom behaviours ──
     const chartZoom = d3
@@ -393,6 +402,9 @@
           select(n.id);
         });
         r.addEventListener("dblclick", () => focusNode(n));
+        r.addEventListener("mouseenter", (ev) => showTip(ev, nodeTip(n), true, 280));
+        r.addEventListener("mousemove", (ev) => moveTip(ev));
+        r.addEventListener("mouseleave", hideTip);
       });
     }
     function treeRowHtml(n) {
@@ -488,12 +500,18 @@
         .data(rowsNow, (n) => n.id)
         .join((enter) => {
           const r = enter.append("g").attr("class", "r");
+          // A transparent target spanning the bar *and* its label, so a 2px bar is still hoverable.
+          r.append("rect").attr("class", "hit").attr("y", BAR_Y - 4).attr("height", BAR_H + 8);
           r.append("rect").attr("class", "bar").attr("rx", 5).attr("y", BAR_Y).attr("height", BAR_H);
           r.append("text").attr("class", "bar-label").attr("y", BAR_Y + BAR_H / 2 + 4);
           r.append("g").attr("class", "marks");
+          const cb = r.append("g").attr("class", "code-btn");
+          cb.append("circle").attr("r", 9);
+          cb.append("text").attr("text-anchor", "middle").attr("y", 3.5).text("<>");
           return r;
         })
-        .attr("transform", (_n, i) => `translate(0,${i * ROW_H})`);
+        .attr("transform", (_n, i) => `translate(0,${i * ROW_H})`)
+        .classed("sel", (n) => n.id === state.selected);
 
       g.select("rect.bar")
         .attr("x", (n) => x(n.start))
@@ -504,17 +522,7 @@
         .attr("stroke-width", (n) => (n.status === "failed" ? 2 : null))
         .attr("stroke-dasharray", (n) => (n.status === "cancelled" ? "4 3" : null))
         .classed("selected", (n) => n.id === state.selected)
-        .on("click", (ev, n) => {
-          ev.stopPropagation();
-          select(n.id);
-        })
-        .on("dblclick", (ev, n) => {
-          ev.stopPropagation();
-          focusNode(n);
-        })
-        .on("mouseenter", (ev, n) => showTip(ev, nodeTip(n)))
-        .on("mousemove", (ev) => moveTip(ev))
-        .on("mouseleave", hideTip);
+        .call(bindNode);
 
       g.select("text.bar-label").each(function (n) {
         const t = d3.select(this);
@@ -524,10 +532,34 @@
         const need = text.length * 6.6 + 14;
         const inside = w >= need;
         const clipX = Math.max(x0, 0);
-        t.text(inside ? text : w > 60 ? truncate(text, (w - 14) / 6.6) : text)
-          .classed("outside", !inside && w <= 60)
-          .attr("x", !inside && w <= 60 ? x0 + Math.max(w, 3) + 6 : Math.min(clipX + 8, x0 + w - 20));
+        const outside = !inside && w <= 60;
+        const shown = inside || outside ? text : truncate(text, (w - 14) / 6.6);
+        const tw = shown.length * 6.6;
+        // an outside label that would run off the chart hangs left of its bar instead
+        const flip = outside && x0 + Math.max(w, 3) + 6 + tw > W;
+        const lx = flip ? x0 - 6 : outside ? x0 + Math.max(w, 3) + 6 : Math.min(clipX + 8, x0 + w - 20);
+        t.text(shown).classed("outside", outside).attr("x", lx).attr("text-anchor", flip ? "end" : "start");
+        // the hit target covers bar + label, padded so a sliver of a bar is still easy to reach
+        const left = Math.min(x0, flip ? lx - tw : lx) - 6;
+        const right = Math.max(x0 + Math.max(w, 3), flip ? x0 : lx + tw) + 6;
+        d3.select(this.parentNode).select("rect.hit").attr("x", left).attr("width", Math.max(16, right - left));
+        // the <> sits just past the block (or just before it, when that would leave the chart)
+        // …and, for a block spanning the chart, inside it right after its label
+        const cx =
+          right + 8 <= W - 10 ? right + 8 : left - 8 >= 10 ? left - 8 : Math.min(W - 12, (flip ? x0 : lx + tw) + 14);
+        d3.select(this.parentNode)
+          .select("g.code-btn")
+          .style("display", hasCode(n) ? null : "none")
+          .attr("transform", `translate(${cx},${BAR_Y + BAR_H / 2})`);
       });
+      g.select("g.code-btn")
+        .on("click", (ev, n) => {
+          ev.stopPropagation();
+          toggleCode(n, ev);
+        })
+        .on("mouseenter", (ev) => showTip(ev, "Show source"))
+        .on("mouseleave", hideTip);
+      g.selectAll("rect.hit, text.bar-label").call(bindNode);
 
       g.select("g.marks").each(function (n) {
         drawMarks(d3.select(this), n, x);
@@ -584,7 +616,14 @@
         .attr("x", (l) => (flip(l) ? l.d.px + 4 : l.d.px - 4))
         .attr("text-anchor", (l) => (flip(l) ? "end" : "start"))
         .attr("y", BAR_Y + BAR_H + 13)
-        .text((l) => l.text);
+        .text((l) => l.text)
+        .on("click", (ev, l) => {
+          ev.stopPropagation();
+          openItem(l.d.m);
+        })
+        .on("mouseenter", (ev, l) => showTip(ev, markTip(l.d)))
+        .on("mousemove", (ev) => moveTip(ev))
+        .on("mouseleave", hideTip);
     }
     function worst(d) {
       const all = [d.m, ...d.more].map((m) => m.kind);
@@ -634,12 +673,15 @@
         .on("mouseleave", () => moveCursor(null));
       flameSvg.append("g").attr("class", "grid");
       flameSvg.append("g").attr("class", "cells");
+      flameSvg.append("line").attr("class", "pin").attr("stroke", css("--accent")).attr("stroke-width", 1.5).attr("y1", 0).attr("y2", 4000);
       flameSvg.append("line").attr("class", "cursor").attr("y1", 0).attr("y2", 4000).attr("visibility", "hidden");
       flameSvg.call(flameZoom).call(flameZoom.transform, state.zoom);
       redrawX();
     }
     function drawFlame(x) {
       if (!flameSvg) return;
+      const px = state.pin != null ? x(state.pin) : -10;
+      flameSvg.select("line.pin").attr("x1", px).attr("x2", px);
       const H = el.flame.clientHeight;
       const ticks = x.ticks(Math.max(2, Math.floor(W / 90)));
       flameSvg
@@ -669,25 +711,20 @@
         .attr("fill", (n) => colorOf(n))
         .attr("fill-opacity", (n) => (n.status === "cancelled" ? 0.55 : 0.92))
         .classed("selected", (n) => n.id === state.selected)
-        .on("click", (ev, n) => select(n.id))
-        .on("dblclick", (ev, n) => {
-          ev.stopPropagation();
-          focusNode(n);
-        })
-        .on("mouseenter", (ev, n) => showTip(ev, nodeTip(n)))
-        .on("mousemove", (ev) => moveTip(ev))
-        .on("mouseleave", hideTip);
+        .call(bindNode);
       cells
         .select("text")
         .attr("x", (n) => Math.max(x(n.start), 0) + 5)
         .text((n) => {
           const w = x(n.end) - Math.max(x(n.start), 0);
           return w < 34 ? "" : truncate(`${displayName(n)} ${fmtDur(n.duration)}`, (w - 10) / 6.2);
-        });
+        })
+        .call(bindNode);
     }
 
     // ── flow view ──
     let flowG = null;
+    let flowPos = new Map();
     let flowBounds = null;
     function renderFlow() {
       d3.select(el.flow).selectAll("svg").remove();
@@ -747,6 +784,22 @@
         .attr("cy", 14)
         .attr("r", 4)
         .attr("fill", (d) => css(statusVar(d.data.status)));
+      const fcb = card
+        .filter((d) => hasCode(d.data))
+        .append("g")
+        .attr("class", "code-btn")
+        .attr("transform", `translate(${CW / 2},0)`)
+        .on("click", (ev, d) => {
+          ev.stopPropagation();
+          toggleCode(d.data, ev);
+        })
+        .on("mouseenter", (ev) => {
+          ev.stopPropagation();
+          showTip(ev, "Show source");
+        });
+      fcb.append("circle").attr("r", 9);
+      fcb.append("text").attr("text-anchor", "middle").attr("y", 3.5).text("<>");
+      flowPos = new Map(h.descendants().map((d) => [d.data.id, { x: d.y + CW / 2, y: d.x }]));
       svg.call(flowZoom);
       fitFlow(true);
     }
@@ -815,7 +868,10 @@
       state.details = true;
       el.main.classList.remove("no-details");
       el.tree.querySelectorAll(".row").forEach((r) => r.classList.toggle("selected", r.dataset.id === id));
-      if (chartSvg) chartSvg.selectAll("rect.bar").classed("selected", (n) => n.id === id);
+      if (chartSvg) {
+        chartSvg.selectAll("rect.bar").classed("selected", (n) => n.id === id);
+        chartSvg.selectAll("g.r").classed("sel", (n) => n.id === id);
+      }
       if (flameSvg) flameSvg.selectAll("rect.flame-rect").classed("selected", (n) => n.id === id);
       d3.select(el.flow).selectAll("g.flow-card").classed("selected", (d) => d.data.id === id);
       renderDetails();
@@ -824,7 +880,7 @@
       const pad = Math.max(n.end - n.start, 50) * 0.08;
       zoomToDomain(n.start - pad, n.end + pad);
     }
-    function revealRow(n) {
+    function revealRow(n, block) {
       let p = n.parent;
       let changed = false;
       while (p) {
@@ -833,7 +889,55 @@
       }
       if (changed && state.view === "timeline") renderTimeline();
       const row = el.tree.querySelector(`.row[data-id="${CSS.escape(n.id)}"]`);
-      if (row) row.scrollIntoView({ block: "nearest" });
+      if (row) row.scrollIntoView({ block: block || "nearest" });
+    }
+
+    /**
+     * Bring a gallery item into view in whichever graph is showing: select its node, pin its
+     * time, pan (keeping the zoom) so that time is on screen, and pulse its mark.
+     */
+    function locate(g) {
+      if (!g) return;
+      if (g.node) select(g.node.id, "snapshots");
+      if (state.view === "flow") {
+        if (g.node) centerFlowOn(g.node);
+        return;
+      }
+      if (g.t != null) {
+        state.pin = g.t;
+        const [a, b] = xz().domain();
+        if (g.t < a || g.t > b) {
+          const k = state.zoom.k;
+          const t = d3.zoomIdentity.translate(W / 2 - k * baseX(g.t), 0).scale(k);
+          const { z, sel } = activeZoom();
+          sel.call(z.transform, t);
+        } else redrawX();
+      }
+      if (g.node && state.view === "timeline") revealRow(g.node, "center");
+      flash(g);
+    }
+    function flash(g) {
+      const svgs = [chartSvg, flameSvg].filter(Boolean);
+      for (const s of svgs) {
+        s.selectAll("line.pin").classed("flash", false).node()?.getBoundingClientRect();
+        s.selectAll("line.pin").classed("flash", true);
+      }
+      if (chartSvg) {
+        const hit = chartSvg
+          .selectAll("circle.mark")
+          .filter((d) => d.m.gallery === g || d.more.some((m) => m.gallery === g));
+        hit.classed("flash", false).node()?.getBoundingClientRect();
+        hit.classed("flash", true);
+      }
+      setTimeout(() => d3.selectAll(".flash").classed("flash", false), 1800);
+    }
+    function centerFlowOn(n) {
+      const svg = d3.select(el.flow).select("svg");
+      const p = flowPos.get(n.id);
+      if (svg.empty() || !p) return;
+      const k = Math.max(0.8, d3.zoomTransform(svg.node()).k);
+      const t = d3.zoomIdentity.translate(el.flow.clientWidth / 2 - k * p.x, el.flow.clientHeight / 2 - k * p.y).scale(k);
+      svg.transition().duration(300).call(flowZoom.transform, t);
     }
 
     function renderDetails() {
@@ -858,14 +962,40 @@
             <div class="k">Duration</div><div class="v">${fmtDur(n.duration)}</div>
             <div class="k">Start</div><div class="v">${fmtRel(n.start)} (${fmtClock(n.startAbs)})</div>
             <div class="k">End</div><div class="v">${fmtRel(n.end)} (${fmtClock(n.endAbs)})</div>
+            ${n.v.description ? `<div class="k">Summary</div><div class="v">${esc(n.v.description.summary)}</div>` : ""}
+            ${n.v.mcp ? `<div class="k">MCP</div><div class="v"><span class="badge-inline">${esc(n.v.mcp.mode)}</span></div>` : ""}
             <div class="k">Path</div><div class="v">${esc(n.v.path)}</div>
-            ${n.v.definedAt ? `<div class="k">Defined at</div><div class="v"><a href="${esc(editorUrl(n.v.definedAt))}" title="${esc(n.v.definedAt)}">${esc(basename(n.v.definedAt))}</a></div>` : ""}
+            ${n.v.definedAt ? `<div class="k">Defined at</div><div class="v defined">
+              <button class="icon-btn" data-copy-source aria-label="Copy relative path">${svgIcon("copy")}</button>
+              ${hasCode(n) ? `<button class="icon-btn" data-show-code aria-label="Show source">${svgIcon("code")}</button>` : ""}
+              <a class="icon-btn" href="${esc(editorUrl(n.v.definedAt))}" aria-label="Open in VS Code" data-tip-text="Open in VS Code">${svgIcon("external")}</a>
+              <span class="defined-name" >${esc(basename(sourceOf(n)))}</span>
+            </div>` : ""}
           </div>
           <div class="tabs">${tabs
             .map(([k, l]) => `<button class="tab ${state.detailTab === k ? "active" : ""}" data-tab="${k}">${l}</button>`)
             .join("")}</div>
           <div class="tabbody">${detailTabHtml(n)}</div>
         </div>`;
+      const copySrc = el.details.querySelector("[data-copy-source]");
+      if (copySrc) {
+        copySrc.addEventListener("click", () => copySource(n));
+        copySrc.addEventListener("mouseenter", (ev) =>
+          showTip(ev, `<div class="mono">${esc(sourceOf(n))}</div><div class="hint">Click (or press <kbd>C</kbd>) to copy</div>`)
+        );
+        copySrc.addEventListener("mousemove", (ev) => moveTip(ev));
+        copySrc.addEventListener("mouseleave", hideTip);
+      }
+      const showCode = el.details.querySelector("[data-show-code]");
+      if (showCode) {
+        showCode.addEventListener("click", (ev) => toggleCode(n, ev));
+        showCode.addEventListener("mouseenter", (ev) => showTip(ev, "Show source"));
+        showCode.addEventListener("mouseleave", hideTip);
+      }
+      el.details.querySelectorAll("[data-tip-text]").forEach((a) => {
+        a.addEventListener("mouseenter", (ev) => showTip(ev, esc(a.dataset.tipText)));
+        a.addEventListener("mouseleave", hideTip);
+      });
       el.details.querySelector(".x").addEventListener("click", () => {
         state.details = false;
         el.main.classList.add("no-details");
@@ -883,7 +1013,9 @@
     function detailTabHtml(n) {
       const tab = state.detailTab;
       if (tab === "args") {
-        return n.v.args && n.v.args.length ? `<pre class="code">${esc(json(n.v.args.length === 1 ? n.v.args[0] : n.v.args))}</pre>` : '<div class="muted">No arguments.</div>';
+        const params = schemaFields(n.v.inputSchema);
+        const schema = params.length ? `<div class="section-title">Schema</div><div class="params">${params.map(paramHtml).join("")}</div><div class="section-title">Values</div>` : "";
+        return schema + (n.v.args && n.v.args.length ? `<pre class="code">${esc(json(n.v.args.length === 1 ? n.v.args[0] : n.v.args))}</pre>` : '<div class="muted">No arguments.</div>');
       }
       if (tab === "events") {
         const evs = n.entries.filter((i) => i.kind !== "info");
@@ -991,6 +1123,14 @@
       body.querySelectorAll("tr[data-row]").forEach((tr) =>
         tr.addEventListener("click", () => openItem(model.items[+tr.dataset.row]))
       );
+      body.querySelectorAll("[data-locate]").forEach((b) => {
+        b.addEventListener("click", (ev) => {
+          ev.stopPropagation();
+          locate(model.gallery[+b.dataset.locate]);
+        });
+        b.addEventListener("mouseenter", (ev) => showTip(ev, `Show in the ${state.view === "flow" ? "flow" : "graph"}`));
+        b.addEventListener("mouseleave", hideTip);
+      });
     }
     function matches(...parts) {
       const q = state.filter.trim().toLowerCase();
@@ -1004,7 +1144,8 @@
         return `<div class="gallery">${g
           .map((x) => {
             const sub = x.type === "snapshot" ? `snapshot · ${x.node ? esc(displayName(x.node)) : ""}` : `${esc(x.f.mime)} · ${fmtSize(x.f.size)}${x.f.omitted ? " · not embedded" : ""}`;
-            return `<div class="gal-item">${thumbHtml(x)}<div class="cap"><span class="t">${x.t == null ? "–" : fmtTick(x.t)}</span><span class="n" title="${esc(x.name)}">${esc(x.name)}</span></div><div class="sz">${sub}</div></div>`;
+            const at = x.t != null || x.node ? `<button class="icon-btn locate" data-locate="${model.gallery.indexOf(x)}" aria-label="Show in graph">${svgIcon("locate")}</button>` : "";
+            return `<div class="gal-item">${thumbHtml(x)}<div class="cap"><span class="t">${x.t == null ? "–" : fmtTick(x.t)}</span><span class="n" title="${esc(x.name)}">${esc(x.name)}</span>${at}</div><div class="sz">${sub}</div></div>`;
           })
           .join("")}</div>`;
       }
@@ -1115,11 +1256,54 @@
     }
 
     // ── tooltips ──
+    /** Click selects, double-click focuses, hover explains — the same on every node mark. */
+    function bindNode(sel) {
+      sel
+        .on("click", (ev, n) => {
+          ev.stopPropagation();
+          select(n.id);
+        })
+        .on("dblclick", (ev, n) => {
+          ev.stopPropagation();
+          focusNode(n);
+        })
+        .on("mouseenter", (ev, n) => showTip(ev, nodeTip(n), true))
+        .on("mousemove", (ev) => moveTip(ev))
+        .on("mouseleave", hideTip);
+    }
     function nodeTip(n) {
-      return `<div class="tt">${esc(n.name)}</div>
-        <div class="ts"><span class="dot ${n.status}"></span> ${esc(n.status)} · ${fmtDur(n.duration)}</div>
-        <div class="ts">${fmtRel(n.start)} → ${fmtRel(n.end)}</div>
-        ${n.v.tags.length ? `<div class="ts">${esc(n.v.tags.join(" · "))}</div>` : ""}`;
+      hovered = n; // the node `C` copies while its tooltip is up
+      const v = n.v;
+      const shown = n.depth === 0 ? model.data.name : displayName(n);
+      const badges = [
+        `<span class="badge"><span class="dot ${n.status}"></span>${esc(n.status)}</span>`,
+        v.mcp ? `<span class="badge mcp" title="Exposed over MCP">MCP · ${esc(v.mcp.mode)}</span>` : "",
+        n.depth === 0 ? '<span class="badge">om</span>' : "",
+      ].join("");
+      const rows = [
+        ["Duration", fmtDur(n.duration)],
+        ["When", `${fmtRel(n.start)} → ${fmtRel(n.end)}`],
+        v.tags.length ? ["Tags", esc(v.tags.join(" · "))] : null,
+        v.definedAt ? ["Defined", `<span class="mono">${esc(sourceOf(n))}</span>`] : null,
+        n.children.length ? ["Children", String(n.children.length)] : null,
+        n.marks.length ? ["Events", String(n.marks.length)] : null,
+      ].filter(Boolean);
+      const args = v.args && v.args.length ? truncate(oneLine(v.args.length === 1 ? v.args[0] : v.args), 220) : "";
+      const params = schemaFields(v.inputSchema);
+      const fails = model.run.failures.filter((f) => f.action === n.id || f.action === n.name || f.action === v.path);
+      return `<div class="tt">${esc(shown)}</div>
+        ${shown !== n.name ? `<div class="ts mono">${esc(truncate(n.name, 140))}</div>` : ""}
+        <div class="badges">${badges}</div>
+        ${v.description ? `<div class="summary">${esc(v.description.summary)}</div>` : '<div class="summary muted">No description.</div>'}
+        <div class="tkv">${rows.map(([k, val]) => `<span class="k">${k}</span><span>${val}</span>`).join("")}</div>
+        ${params.length ? `<div class="sec">Args schema</div><div class="params">${params.map(paramHtml).join("")}</div>` : ""}
+        ${args ? `<div class="sec">Args</div><div class="mono small">${esc(args)}</div>` : ""}
+        ${v.definedAt ? '<div class="hint">Press <kbd>C</kbd> to copy the path</div>' : ""}
+        ${fails.length ? `<div class="sec fail">Failed</div><div class="mono small">${esc(truncate(String(fails[0].error).split(String.fromCharCode(10))[0], 200))}</div>` : ""}`;
+    }
+    /** The om itself: its node tooltip, plus where the run's record lives. */
+    function omTip() {
+      return `${nodeTip(model.root)}<div class="sec">Run folder</div><div class="mono small">${esc(model.data.folder)}</div>`;
     }
     function markTip(d) {
       const m = d.m;
@@ -1129,12 +1313,91 @@
       const extra = m.gallery && m.gallery.image ? `<div class="ts">${esc(m.gallery.f.rel)} · ${fmtSize(m.gallery.f.size)}</div>` : "";
       return `<div class="tt">${esc(mk.label)} · ${fmtRel(m.t)}</div>${img}<div>${esc(truncate(m.kind === "snapshot" || m.kind === "artifact" ? m.label : m.e.message, 260))}</div>${extra}${more}`;
     }
-    function showTip(ev, html) {
-      tip.innerHTML = html;
-      tip.hidden = false;
-      moveTip(ev);
+    // ── source popover (the <> buttons) — click-toggled, like the tskb explorer's ──
+    const codeEl = document.createElement("div");
+    codeEl.className = "code-pop";
+    codeEl.hidden = true;
+    document.body.appendChild(codeEl);
+    let codeFor = null;
+    let codeAway = null;
+    function hasCode(n) {
+      return !!(n.v.definedAt && model.data.code && model.data.code[n.v.definedAt]);
+    }
+    function toggleCode(n, ev) {
+      if (codeFor === n.id) return closeCode();
+      const site = n.v.definedAt;
+      const c = model.data.code && model.data.code[site];
+      if (!c) return;
+      hideTip();
+      codeFor = n.id;
+      const line = Number((/:(\d+)(?::\d+)?$/.exec(site) || [])[1]);
+      const rel = sourceOf(n);
+      const lines = highlight(c.text).map(
+        (html, i) => `<div class="cl${c.start + i === line ? " at" : ""}"><span class="ln">${c.start + i}</span><span class="lc">${html || " "}</span></div>`
+      );
+      codeEl.innerHTML = `<div class="cp-head">
+          <span class="cp-path" title="${esc(site)}">${esc(rel)}<span class="muted">:${line || c.start}</span></span>
+          <button class="icon-btn" data-a="copy" aria-label="Copy path">${svgIcon("copy")}</button>
+          <a class="icon-btn" href="${esc(editorUrl(site))}" aria-label="Open in VS Code">${svgIcon("external")}</a>
+          <span class="cp-name">${esc(displayName(n))}</span>
+          <button class="icon-btn" data-a="close" aria-label="Close">${svgIcon("close")}</button>
+        </div>
+        <div class="cp-body"><div class="cp-code">${lines.join("")}</div>${
+          c.truncated ? '<div class="muted cp-more">Cut short — open the file for the rest.</div>' : ""
+        }</div>`;
+      codeEl.querySelector('[data-a="copy"]').addEventListener("click", () => copy(rel, `Copied ${rel}`));
+      codeEl.querySelector('[data-a="close"]').addEventListener("click", closeCode);
+      codeEl.hidden = false;
+      const x = ev && ev.clientX != null ? ev.clientX : window.innerWidth / 2;
+      const y = ev && ev.clientY != null ? ev.clientY : window.innerHeight / 3;
+      const w = codeEl.offsetWidth;
+      const h = codeEl.offsetHeight;
+      const left = x + 14 + w > window.innerWidth - 8 ? x - w - 14 : x + 14;
+      const top = y + 14 + h > window.innerHeight - 8 ? y - h - 14 : y + 14;
+      codeEl.style.left = `${Math.max(8, left)}px`;
+      codeEl.style.top = `${Math.max(8, top)}px`;
+      const at = codeEl.querySelector(".cl.at");
+      if (at) at.scrollIntoView({ block: "center" });
+      if (codeAway) document.removeEventListener("mousedown", codeAway, true);
+      codeAway = (e) => {
+        if (!codeEl.contains(e.target) && !e.target.closest(".code-btn, [data-show-code]")) closeCode();
+      };
+      setTimeout(() => codeAway && document.addEventListener("mousedown", codeAway, true), 0);
+    }
+    function closeCode() {
+      codeFor = null;
+      codeEl.hidden = true;
+      if (codeAway) document.removeEventListener("mousedown", codeAway, true);
+      codeAway = null;
+    }
+    let tipTimer = 0;
+    let hovered = null;
+    /** The file where `n` is defined, relative to the project root — no line. */
+    function sourceOf(n) {
+      const site = n.v.definedAt;
+      if (!site) return "";
+      return (model.data.sources && model.data.sources[site]) || site.replace(/:\d+(:\d+)?$/, "");
+    }
+    function copySource(n) {
+      const src = n && sourceOf(n);
+      if (src) copy(src, `Copied ${src}`);
+    }
+    let lastEv = null;
+    function showTip(ev, html, wide, delay) {
+      clearTimeout(tipTimer);
+      lastEv = ev;
+      const open = () => {
+        tip.innerHTML = html;
+        tip.classList.toggle("wide", !!wide);
+        tip.hidden = false;
+        moveTip(lastEv);
+      };
+      if (delay && tip.hidden) tipTimer = setTimeout(open, delay);
+      else open();
     }
     function moveTip(ev) {
+      lastEv = ev;
+      if (tip.hidden) return;
       const pad = 14;
       const r = tip.getBoundingClientRect();
       let x = ev.clientX + pad;
@@ -1145,6 +1408,8 @@
       tip.style.top = `${y}px`;
     }
     function hideTip() {
+      hovered = null;
+      clearTimeout(tipTimer);
       tip.hidden = true;
     }
 
@@ -1168,10 +1433,14 @@
       resizeTimer = setTimeout(relayout, 120);
     });
     document.addEventListener("keydown", (e) => {
+      if (e.key === "Escape" && codeFor) return closeCode();
       if (e.target.closest && e.target.closest("input")) return;
       if (e.key === "+" || e.key === "=") zoomBy(1.6);
       else if (e.key === "-") zoomBy(1 / 1.6);
       else if (e.key === "0") fit();
+      else if ((e.key === "c" || e.key === "C") && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        copySource(hovered || model.byId.get(state.selected));
+      }
       else if (e.key === "ArrowDown" || e.key === "ArrowUp") {
         const rows = visible();
         const i = rows.findIndex((n) => n.id === state.selected);
@@ -1201,7 +1470,10 @@
     return `
       <header class="top">
         <div class="titles">
-          <h1 title="${esc(model.data.folder)}">Run: ${esc(model.data.name)}</h1>
+          <div class="title-row">
+            <h1 title="${esc(model.data.folder)}">Run: ${esc(model.data.name)}</h1>
+            <button class="info-btn" id="om-info" aria-label="About this om">${svgIcon("info")}</button>
+          </div>
           <div class="meta"><span class="dot ${ok ? "ok" : "failed"}"></span><span>${ok ? "passed" : "failed"}</span>
             <span class="sep">•</span><span>${fmtDate(run.startedAt)}</span>
             <span class="sep">•</span><span title="body ${fmtDur(run.duration)} · record ${fmtDur(model.span)}">${fmtDur(run.duration)}</span>
@@ -1281,6 +1553,75 @@
     c.opacity = a;
     return c.formatRgb();
   }
+  const KEYWORDS = new Set(
+    "abstract as async await break case catch class const continue default delete do else enum export extends false finally for from function get if implements import in instanceof interface keyof let new null of private protected public readonly return satisfies set static super switch this throw true try type typeof undefined var void while yield".split(" ")
+  );
+  const TOKEN =
+    /(\/\/[^\n]*|\/\*[\s\S]*?\*\/)|(`(?:\\[\s\S]|[^`\\])*`|"(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*')|(\b\d[\d_]*(?:\.\d+)?(?:[eE][+-]?\d+)?n?\b)|([A-Za-z_$][\w$]*)/g;
+  /** Highlighted HTML per source line. Tokens that span lines are closed and reopened at each break. */
+  function highlight(text) {
+    const parts = [];
+    let last = 0;
+    let m;
+    TOKEN.lastIndex = 0;
+    while ((m = TOKEN.exec(text))) {
+      if (m.index > last) parts.push([null, text.slice(last, m.index)]);
+      let cls = null;
+      if (m[1]) cls = "tk-c";
+      else if (m[2]) cls = "tk-s";
+      else if (m[3]) cls = "tk-n";
+      else if (m[4]) {
+        if (KEYWORDS.has(m[4])) cls = "tk-k";
+        else if (/^\s*\(/.test(text.slice(TOKEN.lastIndex, TOKEN.lastIndex + 40))) cls = "tk-f";
+        else if (/^[A-Z]/.test(m[4])) cls = "tk-t";
+      }
+      parts.push([cls, m[0]]);
+      last = TOKEN.lastIndex;
+    }
+    if (last < text.length) parts.push([null, text.slice(last)]);
+    const lines = [""];
+    for (const [cls, chunk] of parts) {
+      chunk.split("\n").forEach((piece, i) => {
+        if (i > 0) lines.push("");
+        if (piece) lines[lines.length - 1] += cls ? `<span class="${cls}">${esc(piece)}</span>` : esc(piece);
+      });
+    }
+    return lines;
+  }
+  function oneLine(v) {
+    try {
+      return typeof v === "string" ? v : JSON.stringify(v);
+    } catch {
+      return String(v);
+    }
+  }
+  /** Top-level fields of a JSON Schema object: name, type, required, default, description. */
+  function schemaFields(schema) {
+    if (!schema || typeof schema !== "object" || !schema.properties) return [];
+    const req = new Set(schema.required || []);
+    return Object.entries(schema.properties).map(([name, p]) => ({
+      name,
+      type: typeOf(p),
+      required: req.has(name) && !(p && "default" in p),
+      def: p && "default" in p ? oneLine(p.default) : undefined,
+      desc: p && p.description,
+    }));
+  }
+  function typeOf(p) {
+    if (!p || typeof p !== "object") return "any";
+    if (p.enum) return p.enum.map((e) => JSON.stringify(e)).join(" | ");
+    if (p.const !== undefined) return JSON.stringify(p.const);
+    if (Array.isArray(p.type)) return p.type.join(" | ");
+    if (p.type === "array") return `${typeOf(p.items)}[]`;
+    if (p.type) return p.type;
+    if (p.anyOf || p.oneOf) return (p.anyOf || p.oneOf).map(typeOf).join(" | ");
+    return "any";
+  }
+  function paramHtml(f) {
+    return `<div class="param"><span class="pn">${esc(f.name)}${f.required ? "" : "?"}</span><span class="pt">${esc(truncate(f.type, 40))}</span>${
+      f.def !== undefined ? `<span class="pd">= ${esc(truncate(f.def, 24))}</span>` : ""
+    }${f.desc ? `<div class="pdesc">${esc(f.desc)}</div>` : ""}</div>`;
+  }
   function truncate(s, n) {
     n = Math.max(1, Math.floor(n));
     return s.length > n ? `${s.slice(0, Math.max(1, n - 1))}…` : s;
@@ -1306,19 +1647,19 @@
     if (/build|compile|bundle/.test(s)) return "box";
     return "play";
   }
-  function copy(text) {
-    const done = () => toast("Copied");
-    if (navigator.clipboard && window.isSecureContext) navigator.clipboard.writeText(text).then(done, () => fallbackCopy(text));
-    else fallbackCopy(text);
+  function copy(text, message) {
+    const done = () => toast(message || "Copied");
+    if (navigator.clipboard && window.isSecureContext) navigator.clipboard.writeText(text).then(done, () => fallbackCopy(text, message));
+    else fallbackCopy(text, message);
   }
-  function fallbackCopy(text) {
+  function fallbackCopy(text, message) {
     const t = document.createElement("textarea");
     t.value = text;
     document.body.appendChild(t);
     t.select();
     try {
       document.execCommand("copy");
-      toast("Copied");
+      toast(message || "Copied");
     } catch {
       toast(text);
     }

package/dist/output/writers/views.d.ts

@@ -19,6 +19,16 @@ export interface NodeView {
     readonly duration: number;
     /** Absolute path to this node's own `.log`. */
     readonly logFile: string;
+    /** What the definition's `.describe()` said; absent when it said nothing. */
+    readonly description?: {
+        readonly summary: string;
+    };
+    /** The definition's `.mcp()` exposure; absent when it is not exposed. */
+    readonly mcp?: {
+        readonly mode: string;
+    };
+    /** The definition's `.args()` schema as JSON Schema; absent without one. */
+    readonly inputSchema?: unknown;
     readonly children: readonly NodeView[];
 }
 /** A curated artifact, as projected into `result.json`. Data-only — no core import. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",