naive-framework 0.0.0-stage → 0.2.0

package/interface/skills/install-mentura/SKILL.md

@@ -0,0 +1,88 @@
+---
+type: knowledge
+tags: [everything-ecosystem, mentura, skills, interface, install, mcp, cli]
+ai-model: claude-opus-5.5
+created: 2026-10-27T20:52:58Z
+source: hybrid
+name: install-mentura
+description: >
+  Install Mentura (the Everything Ecosystem) into a coding agent: the MCP server
+  for Claude Code or Cursor, the CLI, and a first venture, using the whole system
+  or only the layers the builder wants (EE-030).
+  MANDATORY TRIGGERS: install mentura, set up mentura, add the everything
+  ecosystem, use mentura in claude code, use mentura in cursor, mentura mcp,
+  adopt one layer, only the validation kit, start a venture.
+---
+
+# Install Mentura
+
+Interface layer (EE-030). Mentura is a set of records, checks and kits in a git repository. This skill connects an agent harness to it. Every interface (CLI, MCP server, HTTP API) goes through `interface/router.mjs`, so each one has the same routes and gates. The routes are listed in `docs/reference/ROUTES.md`.
+
+## 1. Ask what the builder wants to adopt
+
+Partial adoption is the default. Ask which of these they want, and do not install more:
+
+- **The whole system:** every layer, with the phase defaults.
+- **One layer:** for example `purpose` alone, to state a telos and validate.
+- **One kit inside a layer:** for example the validation kit. Turn on its layer only; the kit's routes need nothing else.
+
+A layer the builder leaves off is written as `false` in `venture.json`. The need-now score then lists that layer's records as "layer off" instead of suggesting them.
+
+## 2. Get the repository and check it runs
+
+```sh
+git clone <the Mentura repository> mentura
+cd mentura && node test.mjs        # Node 20+ and python3 with jsonschema (pip install jsonschema)
+```
+
+## 3. Start a venture, or point at existing ones
+
+```sh
+node interface/cli/mentura.mjs init <folder>/my-venture --id my-venture --layers purpose
+node interface/cli/mentura.mjs system/need-now run --venture my-venture --workspace <folder>
+```
+
+`init` creates new ventures only: it refuses a directory that already has files. To bring an existing project in, create the venture, then run `node interface/cli/naive.mjs port --from <project> --venture <folder>/my-venture`, read the plan it writes, and apply it with `--apply --confirm port`. To have an agent rewrite the project as Naive records instead, use `naive.mjs migrate` with the same flags, have the founder settle each `migrate-<function>` decision, then run `migrate --venture <folder>/my-venture --apply`. Never run `init` on someone's existing project.
+
+To use the whole system, leave out `--layers`. The workspace is the folder that holds the ventures. Set `MENTURA_WORKSPACE` to it so that you do not have to pass `--workspace` each time.
+
+## 4. Connect the harness
+
+**Claude Code** (one command; add `--scope project` to share it in the venture's repo through `.mcp.json`):
+
+```sh
+claude mcp add mentura --env MENTURA_WORKSPACE=<folder> --env MENTURA_HARNESS="Claude Code" -- node <mentura>/interface/mcp/server.mjs
+```
+
+**Cursor** (`.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project):
+
+```json
+{
+  "mcpServers": {
+    "mentura": {
+      "command": "node",
+      "args": ["<mentura>/interface/mcp/server.mjs"],
+      "env": { "MENTURA_WORKSPACE": "<folder>", "MENTURA_HARNESS": "Cursor" }
+    }
+  }
+}
+```
+
+**Any other harness or script:** use the CLI (`node interface/cli/mentura.mjs help`). You can also run `node interface/api/server.mjs`. It listens only on 127.0.0.1:4330 and has no authentication, so keep it on the builder's own machine.
+
+Use absolute paths in both configs. Check the connection by asking the agent to call `mentura_ventures`, then `mentura_view` on `system/overview`. Before an agent acts on a route, it should call `mentura_layout` for that route: it returns the kit's skills, references, template and gate.
+
+## 5. Tell the builder how gates work
+
+- An agent's write to a gated record becomes a draft in `<venture>/_drafts/`. The gated records are ownership, board, founder agreement, exit, telos, decision rights and publication policy. Writes through the MCP server and the API always count as an agent's.
+- A person accepts a draft with `mentura accept <route> --venture <id>`.
+- The CLI cannot tell whether a person or an agent is typing. The real gate is the repository's review: a person merges the pull request.
+- Every write is logged in `<venture>/provenance.jsonl` (EE-031): who wrote it, through which interface, what it came from and the decision it acted under. Set `MENTURA_ACTOR_ID`, `MENTURA_MODEL`, `MENTURA_SESSION` and `MENTURA_HARNESS` in the harness config so that each line names the agent. The MCP server also records the harness name that the client reports. For a venture that existed before the log, run `mentura baseline --venture <id>` once.
+- Every write is checked against the record's schema first. A record that does not match is refused, and nothing changes.
+
+## Sources
+
+- W3C PROV-DM, the provenance data model: https://www.w3.org/TR/prov-dm/ (checked 2026-10-27).
+- Model Context Protocol specification: https://modelcontextprotocol.io/specification/2025-06-18 (checked 2026-10-27).
+- Claude Code MCP setup (`claude mcp add`, scopes): https://docs.claude.com/en/docs/claude-code/mcp (checked 2026-10-27).
+- Cursor MCP configuration (`.cursor/mcp.json`): https://docs.cursor.com/context/model-context-protocol (checked 2026-10-27).

package/interface/skills/naive-setup/SKILL.md

@@ -0,0 +1,71 @@
+---
+type: knowledge
+tags: [everything-ecosystem, naive, skills, interface, setup, artifacts, docket]
+ai-model: claude-opus-5.5
+created: 2026-10-29T06:30:00Z
+source: hybrid
+name: naive-setup
+description: >
+  Walk a founder through setting up a new Naive venture inside the model's own
+  harness: their people and hats, where each function keeps its truth, the
+  strategic foundation and first decisions, and a goal for discovery. Show the
+  progress as a Claude artifact where the harness has artifacts (EE-083).
+  MANDATORY TRIGGERS: set up my venture, naive setup, finish setup, walk me
+  through setup, I just ran create-venture, establish my venture, structure my
+  business, what do I do after create-venture.
+---
+
+# Naive setup
+
+Interface layer (EE-083). `create-venture` scaffolds the venture. This skill finishes the job in conversation. You ask the questions, the founder answers in their own words, and Naive writes each answer as a decision or a source-of-truth pointer, with provenance. The progress is a view the harness renders, not a server Naive runs. In Claude, it is an artifact.
+
+The questions and their order come from Naive, not from you. Read them from `mentura_setup` (MCP) or `node schema/setup.mjs <venture dir> state`, and never invent a question.
+
+## 1. Read the state
+
+Call `mentura_setup` with the venture id. The result has:
+
+- `state`: the people, sources of truth, docket and goal, plus `steps` (which of the four are done), `done`, and `counts`.
+- `artifact`: the state, already rendered into `interface/skills/naive-setup/artifact.html`, as one self-contained HTML page.
+
+Without MCP, run `node schema/setup.mjs <venture dir> state` and `node schema/setup.mjs <venture dir> artifact`.
+
+## 2. Show it
+
+- **Claude (claude.ai, the desktop app, or Claude Code with the Artifact tool):** render `artifact` as an HTML artifact. Do not edit its contents; it is generated. Render it again after every answer, so the founder sees the progress bar move.
+- **A harness without artifacts:** show the four steps as a short checklist in Markdown, with the next open question underneath.
+
+## 3. Ask one question at a time, in order
+
+Work through the first step that is not done, and ask only its next open question:
+
+1. **People and hats.** If `state.people` is missing, ask for the founder's name, role, and whether they are solo or a team. A solo founder wears every hat. These come from `create-venture`. If they are missing, tell the founder to run `npx create-venture` again with `--name`, `--role` and `--team`. Do not write `people/` by hand.
+2. **Sources of truth.** For each function, ask where its truth lives, offering the systems in `state.catalog.functions[<function>]`. Write each answer with `mentura_setup_point` (`function`, `system`, and an `address` such as `acme/app`). If the founder has nothing for a function yet, leave it unpointed and move on. For legal, if there are no documents, say so and name the options in the catalog.
+3. **Foundation and first decisions.** These are the `state.docket` items whose status is not `decided`, taken in order. Ask the question as written. If it has options, offer them, but take the founder's own words. Write the answer with `mentura_setup_answer` (`id` and `answer`).
+4. **A goal for discovery.** Ask what must be true for the venture to leave discovery. Write it with `mentura_setup_answer`, using `id: "discovery-goal"`.
+
+## 4. The founder's words, not yours
+
+- Pass the founder's answer exactly as they wrote it. Do not polish it, summarize it, or fill in an answer they did not give.
+- If an answer is unclear, ask a follow-up question. Do not guess.
+- A foundation statement is the founder's to state. If they ask you to draft one, show the draft and ask them to accept it or rewrite it in their own words. Write it only after they reply, and write what they replied.
+
+## 5. When every step is done
+
+`state.done` is true. Render the artifact one last time: it shows "Your venture is structured." Then tell the founder, in a few lines:
+
+- the venture now has its people, its sources of truth, its foundation and first decisions, and a discovery goal;
+- how many decisions wait for later phases (`state.later`); the docket brings each one up when it matters;
+- each next decision should be oriented around the discovery goal;
+- to operate the business day to day, with a team and agents, they use Mentura. Naive is the structure; Mentura is where it runs, the way a Next.js app is deployed on Vercel.
+
+## Without a model
+
+The same steps run from the command line:
+
+```sh
+node schema/setup.mjs ~/ventures/acme state
+node schema/setup.mjs ~/ventures/acme point finance rho
+node schema/setup.mjs ~/ventures/acme answer discovery-goal "Ten clinic owners confirm the scheduling problem by December"
+node schema/setup.mjs ~/ventures/acme artifact > setup.html
+```

package/interface/skills/naive-setup/artifact.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Venture setup</title>
+<style>
+:root { --bg:#f6f7f4; --panel:#fff; --fg:#1d2320; --muted:#5d675f; --line:#d9ded8; --accent:#2f6b4f; --accent-soft:#e3efe8; --warn:#8a5a00; --warn-soft:#f6ecd8;
+  --body: system-ui, -apple-system, "Segoe UI", sans-serif; --mono: ui-monospace, "SF Mono", Menlo, monospace; color-scheme: light; }
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --bg:#121614; --panel:#1a201d; --fg:#e4e9e5; --muted:#9aa59d; --line:#2b332e; --accent:#86c4a3; --accent-soft:#1d2b24; --warn:#e3b25c; --warn-soft:#2c2414; color-scheme: dark; } }
+:root[data-theme="dark"] { --bg:#121614; --panel:#1a201d; --fg:#e4e9e5; --muted:#9aa59d; --line:#2b332e; --accent:#86c4a3; --accent-soft:#1d2b24; --warn:#e3b25c; --warn-soft:#2c2414; color-scheme: dark; }
+* { box-sizing: border-box }
+body { margin:0; background:var(--bg); color:var(--fg); font:16px/1.55 var(--body); }
+.wrap { max-width: 820px; margin: 0 auto; padding: 28px 16px 64px; display: grid; gap: 22px; }
+header { display:grid; gap:6px } h1 { margin:0; font-size:1.7rem; letter-spacing:-.01em } h2 { margin:0 0 2px; font-size:1.1rem }
+.muted { color: var(--muted) } .mono { font-family: var(--mono); font-size: .86em; overflow-wrap: anywhere }
+.bar { height: 8px; border-radius: 999px; background: var(--line); overflow: hidden } .bar > div { height: 100%; background: var(--accent) }
+.steps { display:flex; gap:6px; flex-wrap:wrap } .step { font:600 .76rem/1 var(--mono); padding:6px 9px; border-radius:999px; border:1px solid var(--line); color:var(--muted) }
+.step.ok { background: var(--accent-soft); color: var(--accent); border-color: transparent } .step.next { border-color: var(--accent); color: var(--accent) }
+section { background: var(--panel); border:1px solid var(--line); border-radius:10px; padding:18px; display:grid; gap:12px; min-width: 0 }
+.table { overflow-x: auto } table { width:100%; border-collapse: collapse; font-size:.93rem }
+td.mono { white-space: nowrap }
+td, th { text-align:left; padding:7px 6px; border-bottom:1px solid var(--line); vertical-align: top }
+th { font: 600 .72rem/1.2 var(--mono); text-transform: uppercase; letter-spacing:.05em; color: var(--muted) }
+.pill { display:inline-block; font:600 .72rem/1.2 var(--mono); padding:4px 7px; border-radius:999px; background: var(--accent-soft); color: var(--accent); margin: 0 4px 4px 0 }
+.pill.pointed { background: var(--line); color: var(--fg) } .pill.none { background: var(--warn-soft); color: var(--warn) }
+.card { border:1px solid var(--line); border-radius:8px; padding:12px; display:grid; gap:6px } .card.done { opacity:.7 } .card.next { border-color: var(--accent) }
+.q { font-weight:600 } .hint { font-size:.88rem; color: var(--muted) }
+.celebrate { text-align:center; padding: 28px 18px; background: var(--accent-soft); border-color: transparent }
+.celebrate .big { font-size: 1.9rem; font-weight: 700; color: var(--accent) } ol { margin:0; padding-left: 1.2em; display:grid; gap:6px; text-align:left }
+</style>
+</head>
+<body>
+<div class="wrap" id="app"></div>
+<script id="naive-setup-state" type="application/json">__NAIVE_SETUP_STATE__</script>
+<script>
+// A view of the venture's setup state, filled in by `node schema/setup.mjs <venture dir> artifact`.
+// It reads nothing from the network and writes nothing: the founder answers in the chat, the model writes
+// each answer through Naive, and renders this page again.
+const S = JSON.parse(document.getElementById("naive-setup-state").textContent);
+const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+const st = S.steps, v = S.venture;
+const order = [["people", "People and hats"], ["truth", "Sources of truth"], ["docket", "Foundation and first decisions"], ["goal", "A goal for discovery"]];
+const next = order.find(([k]) => !st[k])?.[0];
+const doneCount = order.filter(([k]) => st[k]).length;
+const label = ([k, t]) => '<span class="step ' + (st[k] ? "ok" : k === next ? "next" : "") + '">' + (st[k] ? "&#10003; " : "") + t + "</span>";
+
+const people = S.people
+  ? '<div class="table"><table><tr><th>Person</th><th>Role</th><th>Hats</th></tr>' + S.people.people.map((p) => "<tr><td>" + esc(p.name) + '</td><td class="mono">' + esc(p.role) + "</td><td>" + (p.hats.map((h) => '<span class="pill pointed">' + esc(h) + "</span>").join("") || '<span class="muted">none</span>') + "</td></tr>").join("") + "</table></div>"
+  : '<p class="muted">Nobody is listed yet. Tell me your name, your role, and whether you are solo or a team.</p>';
+
+const fns = [...new Set([...Object.keys(S.catalog.functions).filter((f) => f === "legal" || (S.people?.people ?? []).some((p) => p.hats.includes(f))), ...Object.keys(S.functions)])];
+const systemsOf = (f) => { const x = S.functions[f]; return x?.systems?.length ? x.systems.map((s) => '<span class="pill ' + (s.status === "connected" ? "" : "pointed") + '">' + esc(S.catalog.systems[s.system]?.label ?? s.system) + (s.address ? " &middot; " + esc(s.address) : "") + " &middot; " + esc(s.status) + (s.fixture ? " (fixture)" : "") + "</span>").join("") : '<span class="pill none">not pointed yet</span>'; };
+const offered = (f) => (S.catalog.functions[f] ?? []).map((s) => esc(S.catalog.systems[s]?.label ?? s)).join(", ");
+const truth = '<div class="table"><table><tr><th>Function</th><th>Source of truth</th><th>You can point it at</th></tr>' + fns.map((f) => "<tr><td>" + esc(f) + "</td><td>" + systemsOf(f) + '</td><td class="hint">' + offered(f) + "</td></tr>").join("") + "</table></div>";
+
+const open = S.docket.filter((d) => d.status !== "decided");
+const cards = S.docket.map((d) => '<div class="card ' + (d.status === "decided" ? "done" : d === open[0] ? "next" : "") + '"><div class="q">' + esc(d.question) + "</div>"
+  + (d.status === "decided" ? "<div>&#10003; " + esc(d.answer) + "</div>"
+    : d.relayed ? "<div>" + esc(d.answer) + '</div><div class="hint">Your answer, waiting for you to confirm it.</div>'
+
+    : (d.options.length ? '<div class="hint">Options: ' + d.options.map(esc).join(" / ") + "</div>" : "") + '<div class="hint">Answer in the chat, in your own words.</div>')
+  + "</div>").join("");
+
+const goal = S.goal?.status === "decided" ? "<p>&#10003; " + esc(S.goal.answer) + "</p>" : S.goal?.relayed ? "<p>" + esc(S.goal.answer) + '</p><p class="hint">Your answer, waiting for you to confirm it.</p>' : '<p class="muted">What must be true for ' + esc(v.name) + " to leave discovery? For example: ten clinic owners confirm the scheduling problem in interviews by December.</p>";
+
+const done = S.done
+  ? '<section class="celebrate"><div class="big">Your venture is structured.</div><p>' + esc(v.name) + " has its people and their hats, a source of truth for each function, a settled foundation and first decisions, and a goal for discovery. Every decision from here routes through the docket.</p><ol>"
+    + "<li>Orient each next decision around the discovery goal.</li><li>" + (S.later ? S.later + " more decisions wait for later phases; the docket brings each one up when it matters." : "The docket brings up each new decision when it matters.") + "</li><li>To operate the business day to day, with your team and your agents, use Mentura.</li></ol></section>"
+  : "";
+
+document.getElementById("app").innerHTML =
+  '<header><span class="muted mono">' + esc(v.type?.label ?? "venture") + " &middot; " + esc(v.phase) + "</span><h1>Set up " + esc(v.name) + '</h1><p class="muted">The structure of your venture, step by step. Answer in the chat; each answer is saved as a decision, and this page updates.</p>'
+  + '<div class="bar" role="progressbar" aria-valuemin="0" aria-valuemax="4" aria-valuenow="' + doneCount + '"><div style="width:' + doneCount * 25 + '%"></div></div><div class="steps">' + order.map(label).join("") + "</div></header>"
+  + (S.waiting.length ? '<section><h2>' + S.waiting.length + (S.waiting.length === 1 ? " answer waits" : " answers wait") + ' for you</h2><p class="muted">The model wrote these down from your words. They become your decisions when you confirm them yourself: run <span class="mono">npx naive setup confirm</span> in the venture.</p></section>' : "")
+  + done
+  + "<section><h2>1. People and hats</h2>" + people + "</section>"
+  + '<section><h2>2. Sources of truth</h2><p class="muted">Where each function keeps its truth. Naive keeps pointers, never copies.</p>' + truth + "</section>"
+  + '<section><h2>3. Foundation and first decisions</h2><p class="muted">The decision docket: ' + S.counts.settled + " of " + S.counts.of + " settled.</p>" + cards + "</section>"
+  + "<section><h2>4. A goal for discovery</h2>" + goal + "</section>";
+</script>
+</body>
+</html>

package/interface/tooling/integrations.json

@@ -0,0 +1,112 @@
+[
+  {
+    "id": "claude-code",
+    "name": "Claude Code",
+    "layer": "interface",
+    "role": "default interface: agent sessions over the vault, repos, skills and connectors",
+    "interfaces": [
+      "cli",
+      "app"
+    ],
+    "reach": [
+      "purpose",
+      "knowledge",
+      "operations",
+      "evidence",
+      "governance"
+    ],
+    "interface_kind": "agent-harness",
+    "status": "in-use",
+    "reason": "Reads and writes the vault and every repo, runs skills and hooks, reaches Linear, Notion and GitHub through connectors"
+  },
+  {
+    "id": "cursor",
+    "name": "Cursor",
+    "layer": "interface",
+    "role": "editor-centred agent harness over the repos and vault",
+    "interfaces": [
+      "app"
+    ],
+    "reach": [
+      "purpose",
+      "knowledge",
+      "operations",
+      "evidence",
+      "governance"
+    ],
+    "interface_kind": "agent-harness",
+    "status": "in-use",
+    "reason": ".cursor/ rules and agents in the vault and repos"
+  },
+  {
+    "id": "codex",
+    "name": "OpenAI Codex",
+    "layer": "interface",
+    "role": "agent harness (CLI and app)",
+    "interfaces": [
+      "cli",
+      "app"
+    ],
+    "reach": [
+      "knowledge",
+      "operations",
+      "evidence"
+    ],
+    "interface_kind": "agent-harness",
+    "status": "candidate",
+    "reason": "Named by the owner; same shape as Claude Code"
+  },
+  {
+    "id": "hermes-agent",
+    "name": "Hermes Agent",
+    "layer": "interface",
+    "role": "open-source agent harness",
+    "interfaces": [
+      "cli"
+    ],
+    "reach": [
+      "knowledge",
+      "operations",
+      "evidence"
+    ],
+    "interface_kind": "agent-harness",
+    "status": "candidate",
+    "reason": "Named by the owner; reach to confirm"
+  },
+  {
+    "id": "grok",
+    "name": "Grok agent",
+    "layer": "interface",
+    "role": "agent harness",
+    "interfaces": [
+      "app"
+    ],
+    "reach": [
+      "knowledge",
+      "operations",
+      "evidence"
+    ],
+    "interface_kind": "agent-harness",
+    "status": "candidate",
+    "reason": "Named by the owner as Grokbot; which xAI product is meant, and its reach, to confirm"
+  },
+  {
+    "id": "operator-console",
+    "name": "Operator console",
+    "layer": "interface",
+    "role": "local viewer over the records",
+    "interfaces": [
+      "app"
+    ],
+    "status": "candidate",
+    "reason": "interface/operator-console",
+    "reach": [
+      "purpose",
+      "knowledge",
+      "operations",
+      "evidence",
+      "governance"
+    ],
+    "interface_kind": "custom"
+  }
+]

package/interface/vitals.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Agent vitals (N-6): Naive's Core Web Vitals. Where Next.js measures time to first byte and time to
+// interactive, Naive measures what it costs an agent to get work done through the router:
+//
+//   calls_per_task      router calls an agent makes in one session (a task)
+//   tokens_per_call     tokens of context each call sends back
+//   time_to_useful_ms   time from a session's first call to its first useful answer
+//   decision_hours      time from a decision opening to a person deciding it (open ones count their age)
+//
+// Like Web Vitals, each is assessed at the 75th percentile and checked against a threshold (C-15),
+// so vitals are checked, not only measured. Calls and judgments come from the events log that
+// instrumentation writes (interface/instrumentation.mjs); decisions come from provenance.jsonl, so
+// decision latency is measured even with instrumentation off. Thresholds are the defaults below,
+// overridden by "vitals" in the venture's naive.config.json.
+//
+//   node interface/vitals.mjs <venture dir> [--json] [--check]     --check exits 1 when a vital fails
+//   node interface/vitals.mjs <venture dir> --trace [--session <id>] the events as a trace, for
+//                                                                   platform/integrations/langsmith.mjs
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { events } from "./instrumentation.mjs";
+import { entries } from "./provenance.mjs";
+
+export const THRESHOLDS = { calls_per_task: 25, tokens_per_call: 6000, time_to_useful_ms: 10000, decision_hours: 72 };
+const DECISION = /(^|\/)decisions\/[^/]+\.decision\.json$/;
+
+/** The 75th percentile, nearest rank. */
+export const p75 = (xs) => { if (!xs.length) return null; const s = [...xs].sort((a, b) => a - b); return s[Math.ceil(0.75 * s.length) - 1]; };
+const startOf = (e) => Date.parse(e.at) - (e.ms ?? 0);
+const config = (dir) => { const f = join(dir, "naive.config.json"); try { return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : {}; } catch { return {}; } };
+
+/** Top-level calls grouped by session: one task per session. */
+export function tasks(dir) {
+  const calls = events(dir).filter((e) => e.kind === "call" && !e.parent);
+  const judgments = events(dir).filter((e) => e.kind === "judgment");
+  const by = new Map();
+  for (const e of calls) { const k = e.session ?? "(no session)"; if (!by.has(k)) by.set(k, []); by.get(k).push(e); }
+  return [...by.entries()].map(([session, es]) => {
+    const t0 = Math.min(...es.map(startOf));
+    const useful = es.filter((e) => e.useful).sort((a, b) => Date.parse(a.at) - Date.parse(b.at))[0];
+    return { session, calls: es.length, tokens_per_call: Math.round(es.reduce((n, e) => n + (e.tokens ?? 0), 0) / es.length), max_tokens: Math.max(...es.map((e) => e.tokens ?? 0)),
+      time_to_useful_ms: useful ? Date.parse(useful.at) - t0 : null, judgments: judgments.filter((j) => (j.session ?? "(no session)") === session).length };
+  });
+}
+
+/** Each decision the provenance log saw open: when it opened, when a person decided it, and the hours between. */
+export function decisionLatency(dir, now = Date.now()) {
+  const by = new Map();
+  for (const e of entries(dir).filter((x) => DECISION.test(x.entity ?? ""))) {
+    const d = by.get(e.entity) ?? { file: e.entity, opened: null, decided: null };
+    if (!d.opened) d.opened = e.at;
+    if (e.activity === "accept" && !d.decided) d.decided = e.at;
+    by.set(e.entity, d);
+  }
+  return [...by.values()].map((d) => {
+    let id = d.file.split("/").at(-1).replace(/\.decision\.json$/, "");
+    try { id = JSON.parse(readFileSync(join(dir, d.file), "utf8")).id ?? id; } catch {}
+    const end = d.decided ? Date.parse(d.decided) : now;
+    return { id, ...d, open: !d.decided, hours: Math.round(((end - Date.parse(d.opened)) / 36e5) * 100) / 100 };
+  });
+}
+
+/** The venture's vitals, each at p75 against its threshold. */
+export function vitals(dir, now = Date.now()) {
+  const limits = { ...THRESHOLDS, ...(config(dir).vitals ?? {}) };
+  const ts = tasks(dir), ds = decisionLatency(dir, now);
+  const measure = (name, xs, never = 0) => {
+    const v = p75(xs);
+    const n = xs.length + never;
+    const passed = n === 0 ? null : never > 0 && never / n > 0.25 ? false : v === null ? false : v <= limits[name];
+    return { p75: v, threshold: limits[name], n, passed, status: passed === null ? "no data" : passed ? "good" : "needs work", ...(never ? { never_useful: never } : {}) };
+  };
+  const out = {
+    calls_per_task: measure("calls_per_task", ts.map((t) => t.calls)),
+    tokens_per_call: measure("tokens_per_call", ts.map((t) => t.tokens_per_call)),
+    time_to_useful_ms: measure("time_to_useful_ms", ts.filter((t) => t.time_to_useful_ms !== null).map((t) => t.time_to_useful_ms), ts.filter((t) => t.time_to_useful_ms === null).length),
+    decision_hours: measure("decision_hours", ds.map((d) => d.hours)),
+  };
+  const failing = Object.entries(out).filter(([, v]) => v.passed === false).map(([k]) => k);
+  return { events: events(dir).length, tasks: ts, decisions: ds, vitals: out, passed: failing.length === 0, failing,
+    note: events(dir).length ? "p75 of each vital against its threshold (naive.config.json vitals overrides the defaults)" : "no events yet: turn instrumentation on in naive.config.json ({\"instrumentation\": {\"events\": true}}) to measure calls, tokens and time to a useful answer" };
+}
+
+/** The events as one trace (root run per session, a child per call, nested calls under their parent), with the vitals as feedback. */
+export function trace(dir, session) {
+  const es = events(dir).filter((e) => !session || (e.session ?? "(no session)") === session);
+  const calls = es.filter((e) => e.kind === "call");
+  const node = (e) => ({ name: `${e.action} ${e.route}`, run_type: e.action === "run" ? "tool" : "retriever", start: new Date(startOf(e)).toISOString(), end: e.at,
+    inputs: { venture: e.venture, route: e.route, action: e.action }, outputs: { ok: e.ok, useful: e.useful, tokens: e.tokens, ms: e.ms }, ...(e.ok ? {} : { error: "call failed" }),
+    metadata: { via: e.via, actor: e.actor }, children: calls.filter((c) => c.parent === e.id).map(node) });
+  const judged = es.filter((e) => e.kind === "judgment").map((e) => ({ name: `judgment ${e.question ?? e.route ?? ""}`.trim(), run_type: "llm", start: new Date(Date.parse(e.at) - (e.ms ?? 0)).toISOString(), end: e.at,
+    inputs: { question: e.question, route: e.route }, outputs: { score: e.score, threshold: e.threshold, outcome: e.outcome }, metadata: { model: e.model, owner: e.owner } }));
+  const v = vitals(dir);
+  const start = es.length ? new Date(Math.min(...es.map((e) => Date.parse(e.at) - (e.ms ?? 0)))).toISOString() : new Date().toISOString();
+  const end = es.length ? es.at(-1).at : start;
+  return { name: `naive ${JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).id}${session ? ` ${session}` : ""}`, run_type: "chain", start, end,
+    inputs: { session: session ?? null }, outputs: { calls: calls.filter((c) => !c.parent).length, judgments: judged.length },
+    children: [...calls.filter((c) => !c.parent).map(node), ...judged].sort((a, b) => a.start.localeCompare(b.start)),
+    feedback: Object.entries(v.vitals).filter(([, x]) => x.passed !== null).map(([key, x]) => ({ key, score: x.passed ? 1 : 0, comment: `p75 ${x.p75} against ${x.threshold}` })) };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node interface/vitals.mjs <venture dir> [--json] [--check] [--trace [--session <id>]]"); process.exit(2); }
+  const arg = (n) => { const i = process.argv.indexOf(`--${n}`); return i >= 0 ? process.argv[i + 1] : undefined; };
+  if (process.argv.includes("--trace")) { console.log(JSON.stringify(trace(dir, arg("session")), null, 2)); process.exit(0); }
+  const r = vitals(dir);
+  if (process.argv.includes("--json")) console.log(JSON.stringify(r, null, 2));
+  else {
+    console.log(`${r.events} events, ${r.tasks.length} tasks, ${r.decisions.length} decisions. ${r.note}`);
+    for (const [k, x] of Object.entries(r.vitals)) console.log(`  ${k.padEnd(18)} ${x.status.padEnd(10)} p75 ${x.p75 ?? "-"} (threshold ${x.threshold}, n ${x.n})`);
+  }
+  if (process.argv.includes("--check") && !r.passed) { console.error(`vitals failing: ${r.failing.join(", ")}`); process.exit(1); }
+}