naive-framework 0.0.0-stage → 0.2.0

package/platform/integrations/rho.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// Rho, the founder's bank and spend suite, as the venture's money source (platform, EE-041). Rho stays
+// the system of record for money (EE-070): this writes the venture's money data package as pointers
+// and a summary, never as Naive's own books. It speaks Rho's MCP server over HTTP (JSON-RPC, no
+// dependencies) and calls only tools Rho marks read-only.
+//
+//   node platform/integrations/rho.mjs sync --venture <dir> [--live] [--fixture <file>] [--save-fixture <file>]
+//
+//   default          Rho's sandbox (fictional company, any token, shared by all callers)
+//   --live           the founder's Rho, with RHO_API_TOKEN (scopes accounts:read, transactions:read)
+//   --fixture        replays a saved sync offline (tests, or a demo with no network)
+//   --save-fixture   keeps what Rho answered, for --fixture later
+//
+// The package it writes (data package shape, PR #23 stage C):
+//   money/<rho id>.json                                master record, with a rho:account pointer
+//   money/_streams/transactions/stream.json            sensitive: kept out of git and out of traces
+//   money/_streams/transactions/YYYY/MM/<date>-<id>.json   append-only; a resync never rewrites one
+//   money/_summary.json                                 versioned: cash, net burn, runway, as of when
+//
+// Amounts stay in minor units (cents for USD), as Rho returns them.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const SANDBOX = "https://rhoapi-sandbox.rho.co/mcp/v1";
+export const LIVE = "https://rhoapi.rho.co/mcp/v1";
+const PROTOCOL = "2025-06-18";
+
+// One MCP call over Streamable HTTP. Rho answers either JSON or a one-event SSE stream.
+export function client(url, token) {
+  let id = 0, session = null, tools = null;
+  const rpc = async (method, params) => {
+    const res = await fetch(url, { method: "POST", signal: AbortSignal.timeout(60000), headers: {
+      "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}`,
+      "mcp-protocol-version": PROTOCOL, ...(session ? { "mcp-session-id": session } : {}) }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method, params }) });
+    if (!res.ok) throw new Error(`Rho answered ${res.status} to ${method}`);
+    session = res.headers.get("mcp-session-id") ?? session;
+    const body = await res.text();
+    const msg = JSON.parse(body.trimStart().startsWith("{") ? body : body.split("\n").filter((l) => l.startsWith("data: ")).map((l) => l.slice(6)).join(""));
+    if (msg.error) throw new Error(`Rho ${method}: ${msg.error.message}`);
+    return msg.result;
+  };
+  return {
+    async init() {
+      await rpc("initialize", { protocolVersion: PROTOCOL, capabilities: {}, clientInfo: { name: "naive-money", version: "1" } });
+      tools = new Map((await rpc("tools/list", {})).tools.map((t) => [t.name, t]));
+    },
+    async call(name, args = {}) {
+      const t = tools?.get(name);
+      if (!t) throw new Error(`Rho has no tool ${name}`);
+      if (t.annotations?.readOnlyHint !== true) throw new Error(`${name} is not read-only: Naive never writes to the system of record`);
+      const r = await rpc("tools/call", { name, arguments: args });
+      if (r.isError) throw new Error(`${name}: ${r.content?.[0]?.text ?? "error"}`);
+      return JSON.parse(r.content[0].text);
+    },
+  };
+}
+
+// Every page of a list tool.
+async function all(rho, name, key, args = {}) {
+  const out = [];
+  let token;
+  do {
+    const page = await rho.call(name, { ...args, page_size: 100, ...(token ? { page_token: token } : {}) });
+    out.push(...(page[key] ?? []));
+    token = page.page?.next_page_token;
+  } while (token);
+  return out;
+}
+
+export async function pull({ url, token }) {
+  const rho = client(url, token);
+  await rho.init();
+  const business = await rho.call("getBusiness").catch(() => null);
+  const accounts = await all(rho, "listAccounts", "accounts");
+  const transactions = await all(rho, "listTransactions", "transactions", { order: "asc" });
+  const last = transactions.map((t) => t.posted_at ?? t.initiated_at).filter(Boolean).sort().at(-1);
+  const to = last ?? new Date().toISOString();
+  const from = new Date(Date.parse(to) - 90 * 864e5).toISOString();
+  const cashflow = await rho.call("getCashflow", { from, to, group: "month" });
+  return { source: url === LIVE ? "rho" : "rho-sandbox", business, accounts, transactions, cashflow: { from, to, ...cashflow } };
+}
+
+const CASH = new Set(["checking", "savings"]);
+const usd = (n) => ({ amount: n, currency: "USD" });
+
+// The summary is the only money record that is versioned and the only one an agent or a trace sees.
+// Burn comes from Rho's cash flow (business-level in and out, so moves between the business's own
+// accounts don't count), over the 90 days that end at the latest activity, which the summary names.
+export function summarize(data, syncedAt) {
+  const cash = data.accounts.filter((a) => CASH.has(a.account_type)).reduce((s, a) => s + (a.balance?.amount ?? 0), 0);
+  const buckets = data.cashflow.buckets ?? [];
+  const sum = (k) => buckets.reduce((s, b) => s + (b[k]?.amount ?? 0), 0);
+  const days = Math.max(1, (Date.parse(data.cashflow.to) - Date.parse(data.cashflow.from)) / 864e5);
+  const monthly = (n) => Math.round((n / days) * 30);
+  const net = monthly(sum("net_amount"));
+  return {
+    source: data.source, business: data.business?.name ?? data.business?.legal_name ?? null, synced_at: syncedAt,
+    as_of: data.cashflow.to, window: { from: data.cashflow.from, to: data.cashflow.to },
+    cash: usd(cash), monthly_inflow: usd(monthly(sum("inflow_amount"))), monthly_outflow: usd(monthly(sum("outflow_amount"))), monthly_net: usd(net),
+    runway_months: net < 0 ? Math.round((cash / -net) * 10) / 10 : null,
+    accounts: data.accounts.length, transactions: data.transactions.length,
+    note: net < 0 ? "Runway is cash over the average monthly net outflow in the window." : "Net cash flow is not negative in the window, so runway is not limited by burn.",
+  };
+}
+
+const json = (f, v) => { mkdirSync(join(f, ".."), { recursive: true }); writeFileSync(f, `${JSON.stringify(v, null, 2)}\n`); };
+
+export function write(venture, data, syncedAt = new Date().toISOString()) {
+  const money = join(venture, "money");
+  const pointer = (kind, id) => `${data.source}:${kind}:${id}`;
+  for (const a of data.accounts)
+    json(join(money, `${a.id}.json`), { id: a.id, name: a.account_name, type: a.account_type, last_4: a.account_number_last_4 ?? null, balance: a.balance, source: pointer("account", a.id), synced_at: syncedAt });
+  const stream = join(money, "_streams/transactions");
+  // The stream's declaration, as schema/stream.schema.json has it. Its events are append-only and stay out of git.
+  json(join(stream, "stream.json"), { id: "transactions", sensitive: true,
+    summary: `Every transaction ${data.source} posted, one file each, as Rho returned it; Rho is the system of record. The versioned view is money/_summary.json.` });
+  let added = 0;
+  for (const t of data.transactions) {
+    const at = t.posted_at ?? t.initiated_at;
+    const f = join(stream, at.slice(0, 4), at.slice(5, 7), `${at.slice(0, 10)}-${t.id}.json`);
+    if (existsSync(f)) continue;
+    json(f, { id: t.id, at, amount: t.amount, counterparty: t.counterparty_name ?? null, type: t.transaction_type, status: t.status, account: pointer("account", t.account_id), source: pointer("transaction", t.id), fields: t.fields ?? [] });
+    added++;
+  }
+  // Sensitive streams never reach git (stage C of PR #23 makes this a framework rule).
+  const ignore = join(money, ".gitignore");
+  if (!existsSync(ignore)) writeFileSync(ignore, "_streams/transactions/*/\n");
+  const summary = summarize(data, syncedAt);
+  json(join(money, "_summary.json"), summary);
+  return { added, summary };
+}
+
+const argv = process.argv.slice(2);
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const opt = (n) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] : undefined; };
+  const venture = opt("venture");
+  if (argv[0] !== "sync" || !venture) { console.error("usage: node platform/integrations/rho.mjs sync --venture <dir> [--live] [--fixture <file>] [--save-fixture <file>]"); process.exit(2); }
+  const live = argv.includes("--live");
+  if (live && !process.env.RHO_API_TOKEN) { console.error("RHO_API_TOKEN is not set"); process.exit(3); }
+  const data = opt("fixture") ? JSON.parse(readFileSync(opt("fixture"), "utf8"))
+    : await pull(live ? { url: LIVE, token: process.env.RHO_API_TOKEN } : { url: SANDBOX, token: "sandbox" });
+  if (opt("save-fixture")) json(opt("save-fixture"), data);
+  const { added, summary } = write(venture, data);
+  console.log(JSON.stringify({ venture, added, summary }, null, 2));
+}

package/platform/integrations/site.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Read a venture's website (platform, EE-041; EE-062): the home page and the pages it links to, as
+// text, with where each page sits (the home page, one click away in the header or nav, or one click
+// away elsewhere). Firecrawl renders the pages when FIRECRAWL_API_KEY is set; otherwise a plain fetch
+// reads the HTML, which misses sites that render only in the browser. It reads public pages only,
+// stays on the site's own origin, and sends nothing but the requests themselves.
+//
+//   node platform/integrations/site.mjs <url> [--pages 10]     prints {site, via, pages:[...]}
+
+const UA = "Mozilla/5.0 (compatible; NaiveSiteReader/0.1; +https://github.com/tchjhnsn/everything-ecosystem)";
+const FIRECRAWL = "https://api.firecrawl.dev/v1";
+// Pages a marketing site usually has; a link whose path or text names one is read first.
+const LIKELY = /about|team|company|story|mission|pricing|plans|careers|jobs|hiring|join|investor|ir\b|community|contribut|open-source|press|news|media|blog|contact|security|privacy|trust|product|features|how-it-works|customers|case-stud|faq/i;
+
+const decode = (s) => s.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;|&#x27;|&rsquo;/g, "'").replace(/&#(\d+);/g, (_, n) => String.fromCharCode(+n));
+export function text(html) {
+  return decode(html.replace(/<(script|style|noscript|svg|template)[\s\S]*?<\/\1>/gi, " ").replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<\/(p|div|li|h[1-6]|section|article|br|tr|header|footer|nav)>/gi, "\n").replace(/<br\s*\/?>/gi, "\n").replace(/<[^>]+>/g, " "))
+    .replace(/[ \t]+/g, " ").replace(/\n\s*\n+/g, "\n").trim();
+}
+export function links(html, base) {
+  const out = [], seen = new Set();
+  const navHtml = (html.match(/<(nav|header)[\s\S]*?<\/\1>/gi) ?? []).join(" ");
+  const navHrefs = new Set([...navHtml.matchAll(/href\s*=\s*["']([^"'#]+)/gi)].map((m) => m[1]));
+  for (const m of html.matchAll(/<a\b[^>]*href\s*=\s*["']([^"'#]+)[^"']*["'][^>]*>([\s\S]*?)<\/a>/gi)) {
+    let u;
+    try { u = new URL(m[1], base); } catch { continue; }
+    if (u.origin !== new URL(base).origin || /^\/(log-?in|sign-?in|sign-?up|register|auth|app|dashboard|homepage)\b/i.test(u.pathname) || /\.(png|jpe?g|gif|svg|webp|pdf|zip|mp4|css|js|xml|ico)$/i.test(u.pathname)) continue;
+    u.hash = ""; u.search = "";
+    const key = u.href.replace(/\/$/, "");
+    if (seen.has(key) || key === new URL(base).href.replace(/\/$/, "")) continue;
+    seen.add(key);
+    out.push({ url: u.href, label: text(m[2]).slice(0, 60), in_nav: navHrefs.has(m[1]) });
+  }
+  return out;
+}
+
+async function plain(url) {
+  const r = await fetch(url, { headers: { "user-agent": UA, accept: "text/html" }, redirect: "follow", signal: AbortSignal.timeout(15000) });
+  if (!r.ok) throw new Error(`${url} answered ${r.status}`);
+  const html = await r.text();
+  return { url: r.url, html, title: decode((html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] ?? "").trim()), text: text(html) };
+}
+async function firecrawl(url) {
+  const r = await fetch(`${FIRECRAWL}/scrape`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${process.env.FIRECRAWL_API_KEY}` },
+    body: JSON.stringify({ url, formats: ["markdown", "html"], onlyMainContent: false }), signal: AbortSignal.timeout(60000) });
+  if (!r.ok) throw new Error(`Firecrawl answered ${r.status} for ${url}`);
+  const d = (await r.json()).data ?? {};
+  return { url: d.metadata?.sourceURL ?? url, html: d.html ?? "", title: d.metadata?.title ?? "", text: d.markdown ?? text(d.html ?? "") };
+}
+
+export async function read(site, { pages = 10, chars = 6000 } = {}) {
+  const url = /^https?:\/\//.test(site) ? site : `https://${site}`;
+  const via = process.env.FIRECRAWL_API_KEY ? "firecrawl" : "fetch";
+  const get = via === "firecrawl" ? firecrawl : plain;
+  const home = await get(url);
+  const ls = links(home.html, home.url);
+  // Links that name a page marketing sites usually have first (about, careers, pricing...), header and nav links next, then the rest.
+  const score = (l) => (LIKELY.test(`${new URL(l.url).pathname} ${l.label}`) ? 2 : 0) + (l.in_nav ? 1 : 0);
+  // One page per section first (/customers, not every /customers/<name>), then the rest if room is left.
+  const ranked = ls.map((l, i) => [l, i]).sort(([a, i], [b, j]) => score(b) - score(a) || i - j).map(([l]) => l);
+  const section = (l) => new URL(l.url).pathname.split("/")[1];
+  const firsts = ranked.filter((l, k) => ranked.findIndex((m) => section(m) === section(l)) === k);
+  const pick = [...firsts, ...ranked.filter((l) => !firsts.includes(l))].slice(0, pages - 1);
+  const rest = await Promise.all(pick.map(async (l) => { try { return { ...(await get(l.url)), link: l }; } catch (e) { return { url: l.url, error: e.message, link: l }; } }));
+  const page = (p, depth) => ({ url: p.url, path: new URL(p.url).pathname, title: p.title ?? "", depth, in_nav: depth === 0 ? true : !!p.link?.in_nav, label: p.link?.label ?? "", ...(p.error ? { error: p.error } : { text: p.text.slice(0, chars) }) });
+  return { site: new URL(home.url).origin, via, read_at: new Date().toISOString().replace(/\.\d+Z$/, "Z"), links_found: ls.length, links: ls.map((l) => ({ path: new URL(l.url).pathname, label: l.label, in_nav: l.in_nav })), pages: [page(home, 0), ...rest.map((p) => page(p, 1))] };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const site = process.argv[2];
+  if (!site) { console.error("usage: node platform/integrations/site.mjs <url> [--pages 10]"); process.exit(2); }
+  const i = process.argv.indexOf("--pages");
+  read(site, { pages: i > 0 ? Number(process.argv[i + 1]) : 10 }).then((r) => console.log(JSON.stringify(r)), (e) => { console.error(e.message); process.exit(1); });
+}

package/platform/kits/README.md

@@ -0,0 +1,14 @@
+# Kits
+
+A kit belongs to Mentura. It is an enhanced package: automations, agent workflows, richer skills and connectors, on top of one Naive package.
+
+A kit lives at `platform/kits/<name>/kit.json`. It names the one package it extends (`package`) and never replaces that package. The package at `packages/<name>/package.json` works with no kit installed: schemas, templates, deterministic checks and at most one skill, offline, naming no vendor (EE-071).
+
+A kit can also extend a framework command (`extends.command`), and bring automations: triggers that name the package they need and run only once it is complete (`schema/kit.schema.json`). A venture turns kits on with `kits` in its `naive.config.json`.
+
+| Kit | What it does |
+|---|---|
+| `agent-upgrade/` | Runs `naive upgrade --agent`: an agent does the guides' by-hand steps on a staged copy; the framework's checks and a typed confirmation decide what lands (U-3) |
+| `validation-kickoff/` | Proposes the decision to start validating once the foundation is complete (M-12) |
+
+`node platform/kits/test.mjs` tests them offline.

package/platform/kits/agent-upgrade/kit.json

@@ -0,0 +1,15 @@
+{
+  "name": "agent-upgrade",
+  "title": "Agent-run upgrade",
+  "purpose": "An agent works the upgrade of a venture (U-3, I-29): the framework's migrations run on a copy, the agent does what the version guides leave to a person (prose such as AGENTS.md), and the framework's checks decide. Nothing lands until the checks pass and the founder types the confirmation.",
+  "extends": { "command": "upgrade --agent" },
+  "entry": "run.mjs",
+  "agent": {
+    "command": ["claude", "-p", "--output-format", "json", "--permission-mode", "acceptEdits", "--allowedTools", "Read,Edit,Write,Glob,Grep", "--strict-mcp-config"],
+    "env": ["MENTURA_AGENT_CMD"]
+  },
+  "use_model": ["the agent edits the staged copy by the version guides' by-hand steps"],
+  "checks": ["schema/upgrades.mjs"],
+  "status": "built",
+  "note": "The agent sees only the staged copy, never _private/, and its claims are not trusted: every file it changed is found by hash and logged as an agent's write, and the framework's checks run after it. MENTURA_AGENT_CMD replaces the default agent (platform/kits/agent-upgrade/stand-in-agent.mjs is the offline stand-in the tests use)."
+}

package/platform/kits/agent-upgrade/run.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// The agent-run upgrade (U-3, I-29), a Mentura kit over the framework's staged upgrade. Next.js's
+// `next upgrade --agent` has a coding agent perform and verify the upgrade; here the work is split the
+// System 1 way. Code runs the migrations on a copy (schema/upgrades.mjs stage). The agent does only what
+// the version guides leave to a person, in the copy. Code then finds every file the agent changed (by
+// hash, not by its word), logs each as an agent's write, and runs the framework's checks. The upgrade
+// stays a draft until the checks pass and the founder types the confirmation:
+//
+//   node platform/kits/agent-upgrade/run.mjs <venture dir> [--json]      (naive upgrade <dir> --agent)
+//   node interface/cli/naive.mjs upgrade <dir> --accept --confirm upgrade
+//
+// The agent is `claude -p` with file tools only, working in the copy, or MENTURA_AGENT_CMD (a command that
+// reads the prompt on stdin, works in its current directory and answers as claude -p --output-format json).
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { agentFromEnv, record } from "../../../interface/provenance.mjs";
+import { annotate, check, CONFIRM, snapshot, stage, STAGED } from "../../../schema/upgrades.mjs";
+
+const repo = new URL("../../..", import.meta.url).pathname;
+const kit = JSON.parse(readFileSync(new URL("./kit.json", import.meta.url), "utf8"));
+const dirArg = process.argv[2];
+const json = process.argv.includes("--json");
+if (!dirArg || !existsSync(join(dirArg, "venture.json"))) { console.error("usage: node platform/kits/agent-upgrade/run.mjs <venture dir> [--json]"); process.exit(2); }
+const dir = resolve(dirArg);
+
+/** Runs the agent in the staged copy and returns its answer (an object), or throws saying why. */
+export function runAgent(prompt, cwd) {
+  const cmd = process.env.MENTURA_AGENT_CMD ? process.env.MENTURA_AGENT_CMD.split(" ") : kit.agent.command;
+  // A relative program path in MENTURA_AGENT_CMD is relative to where naive was run, not to the copy.
+  const args = cmd.slice(1).map((a) => (/\.m?js$/.test(a) && !a.startsWith("/") && existsSync(resolve(a)) ? resolve(a) : a));
+  const p = spawnSync(cmd[0], args, { cwd, input: prompt, encoding: "utf8", maxBuffer: 1 << 26, env: { ...process.env, NAIVE_STAGE: cwd, NAIVE_TRIGGERS_ACTIVE: "upgrade" } });
+  if (p.error) throw new Error(`could not run the agent (${cmd[0]}): ${p.error.message}`);
+  let text = p.stdout;
+  try { const r = JSON.parse(p.stdout); if (r && typeof r.result === "string") { if (r.is_error) throw new Error(`the agent stopped: ${r.result}`); text = r.result; } }
+  catch (e) { if (e.message.startsWith("the agent stopped")) throw e; }
+  if (p.status !== 0) throw new Error(`the agent stopped with status ${p.status}: ${(p.stderr || text).trim().slice(0, 500)}${/login/i.test(p.stderr + text) ? " (run claude, then /login)" : ""}`);
+  const m = text.match(/\{[\s\S]*\}/);
+  try { return m ? JSON.parse(m[0]) : { summary: text.trim() }; } catch { return { summary: text.trim().slice(0, 2000) }; }
+}
+
+const staged = await stage(dir, { by: kit.name }).catch((e) => { console.error(e.message); process.exit(1); });
+const copy = join(dir, STAGED);
+const guides = staged.guides.map((g) => `--- ${g}\n${readFileSync(join(repo, g), "utf8")}`).join("\n\n");
+const prompt = [
+  `You are upgrading the venture in your current directory from Naive ${staged.from} to ${staged.to}. It is a copy: nothing you do reaches the venture until its founder accepts it.`,
+  "The framework's migrations have already run. Do only what the guides below leave to a person (their \"By hand\" sections) and what the migrations escalated, by editing files in this directory.",
+  "Rules: never open anything under _private/. Do not edit provenance.jsonl, naive.config.json, or anything under .release/ or .naive/. Do not delete files. Keep every JSON record valid against its schema. When something needs the founder's judgment, leave it and say so.",
+  `Escalated by the migrations:\n${staged.escalated.length ? staged.escalated.map((e) => `- ${e}`).join("\n") : "- nothing"}`,
+  `The guides:\n\n${guides || "(none)"}`,
+  'When you are done, answer with JSON only: {"summary": "<one sentence>", "edits": [{"path": "<file>", "why": "<the guide step>"}], "left": [{"what": "<item>", "why": "<why it needs the founder>"}]}',
+].join("\n\n");
+
+const before = snapshot(copy);
+let answer;
+try { answer = runAgent(prompt, copy); }
+catch (e) {
+  annotate(dir, { agent: { kit: kit.name, error: e.message } });
+  const d = check(dir);
+  console.error(`${e.message}\nThe migrations' copy is staged without the agent's work (${d.status}). Accept it with --accept --confirm ${CONFIRM}, or --reject.`);
+  process.exit(1);
+}
+// What the agent changed, by hash. Each change is an agent's write in the copy's provenance.
+const after = snapshot(copy);
+const changed = Object.keys(after).filter((f) => f !== "provenance.jsonl" && after[f] !== before[f]).sort();
+const deleted = Object.keys(before).filter((f) => !(f in after)).sort();
+const who = agentFromEnv("agent", "cli", { id: kit.name, ...(process.env.MENTURA_AGENT_CMD ? {} : { harness: "Claude Code" }) });
+const why = new Map((answer.edits ?? []).map((e) => [e.path, e.why]));
+for (const f of changed) record(copy, { entity: f, activity: "write", agent: who, note: `agent-run upgrade to Naive ${staged.to}: ${why.get(f) ?? "changed by the agent (it did not say why)"}` });
+annotate(dir, { agent: { kit: kit.name, summary: answer.summary ?? null, changed, deleted, reported: [...why.keys()], left: answer.left ?? [] } });
+const d = check(dir);
+
+if (json) { console.log(JSON.stringify(d, null, 2)); process.exit(d.status === "ready" ? 0 : 1); }
+console.log(`staged upgrade of ${staged.from} to ${staged.to}, worked by an agent: ${d.status}`);
+if (answer.summary) console.log(`agent     ${answer.summary}`);
+for (const f of changed) console.log(`edited    ${f}${why.has(f) ? `: ${why.get(f)}` : " (not reported by the agent)"}`);
+for (const f of deleted) console.log(`deleted   ${f} (the agent was told not to delete; the founder decides)`);
+for (const l of answer.left ?? []) console.log(`left      ${l.what}: ${l.why}`);
+for (const c of d.checks) console.log(`${c.passed ? "pass" : "FAIL"}      ${c.check}${c.passed ? "" : `: ${c.output.split("\n").slice(-2).join(" / ")}`}`);
+console.log(d.status === "ready" ? `Nothing has landed. To land it: node interface/cli/naive.mjs upgrade ${dirArg} --accept --confirm ${CONFIRM}` : `Nothing has landed, and it cannot until the checks pass. Fix the copy in ${dirArg}/${STAGED}, then run --status; or --reject.`);
+process.exit(d.status === "ready" ? 0 : 1);

package/platform/kits/agent-upgrade/stand-in-agent.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// A stand-in for the upgrade agent, for tests and docs that run offline
+// (MENTURA_AGENT_CMD="node platform/kits/agent-upgrade/stand-in-agent.mjs"). It does the 0.3.0 guide's
+// by-hand step the way an agent would: in every AGENTS.md of the copy it is working in (its current
+// directory), it says package where the text says kit. It answers as claude -p --output-format json does.
+// STAND_IN_BREAK=1 also breaks a record, so tests can show the checks stop a bad upgrade.
+
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+let prompt = "";
+for await (const c of process.stdin) prompt += c;
+const cwd = process.cwd();
+const edits = [];
+const walk = (rel) => {
+  for (const e of readdirSync(join(cwd, rel), { withFileTypes: true })) {
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) { if (!e.name.startsWith(".") && e.name !== "_private") walk(r); continue; }
+    if (e.name !== "AGENTS.md") continue;
+    const text = readFileSync(join(cwd, r), "utf8");
+    const next = text.replace(/\bkits\b/g, "packages").replace(/\bkit\b/g, "package");
+    if (next !== text) { writeFileSync(join(cwd, r), next); edits.push({ path: r, why: "0.3.0 by hand: say package where the text says kit" }); }
+  }
+};
+if (/say package where you wrote kit/.test(prompt)) walk("");
+if (process.env.STAND_IN_BREAK === "1") {
+  mkdirSync(join(cwd, "foundation"), { recursive: true });
+  writeFileSync(join(cwd, "foundation/icp.json"), JSON.stringify({ broken: true }) + "\n");
+  edits.push({ path: "foundation/icp.json", why: "rewrote the ICP" });
+}
+const answer = { summary: edits.length ? `Updated ${edits.length} file(s) by the guides' by-hand steps.` : "Nothing in the guides' by-hand steps applied to this venture.", edits, left: [] };
+console.log(JSON.stringify({ type: "result", is_error: false, result: JSON.stringify(answer) }));

package/platform/kits/validation-kickoff/kit.json

@@ -0,0 +1,29 @@
+{
+  "name": "validation-kickoff",
+  "title": "Validation kickoff",
+  "purpose": "When the foundation is settled, start the next step: put the decision to begin validating in front of the founder (M-12). An automation over the validation package, so it waits until the foundation package it needs is complete.",
+  "extends": { "package": "validation" },
+  "automations": [
+    {
+      "id": "start",
+      "on": { "activity": ["write", "accept", "confirm"], "route": "foundation/**", "by": "person" },
+      "needs": "foundation",
+      "once": true,
+      "run": {
+        "propose": {
+          "id": "start-validation",
+          "question": "The foundation is settled. Start validating the solution now: write the solution record and plan the first problem interviews?",
+          "options": ["Yes: start validation now", "Not yet: keep working the foundation"],
+          "layer": "purpose",
+          "boundary": "fail-open",
+          "decides": { "record": "validation-solution", "path": "validation/solution.json" },
+          "unlocks": [{ "activity": "Draft the solution record and the interview plan", "routes": ["validation/solution"] }]
+        }
+      },
+      "note": "Proposes a decision rather than writing records: the founder decides whether validation starts."
+    }
+  ],
+  "use_model": [],
+  "status": "built",
+  "note": "Turn it on with \"kits\": [\"validation-kickoff\"] in the venture's naive.config.json. The framework's trigger runner (schema/triggers.mjs) runs it; this kit holds no code."
+}

package/platform/mcp/research.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Market research for agents, through Firecrawl (platform, EE-041): an MCP server, stdio, no
+// dependencies. It names a vendor and needs a credential, so it lives on the platform side; the
+// Naive harness hands it to an agent next to Naive's own MCP server. Every result carries its URL,
+// so an agent can cite it as evidence (EE-050) and nothing it reports is unsourced.
+//
+//   FIRECRAWL_API_KEY=... node platform/mcp/research.mjs
+//
+// Tools: research_search searches the web (Firecrawl /v1/search); research_read reads one page as
+// Markdown (Firecrawl /v1/scrape), for quoting what a result says.
+
+import { createInterface } from "node:readline";
+
+const API = "https://api.firecrawl.dev/v1";
+export const TOOLS = [
+  { name: "research_search", description: "Search the web for market research (competitors, existing alternatives, prices, complaints, market size) through Firecrawl. Returns each result's title, URL and snippet. Cite the URL of anything you use as evidence; never state a finding without one.",
+    inputSchema: { type: "object", properties: { queries: { type: "array", items: { type: "string" }, maxItems: 5, description: "Up to five search queries" }, results: { type: "integer", minimum: 1, maximum: 10, description: "Results per query (default 5)" } }, required: ["queries"] } },
+  { name: "research_read", description: "Read one web page as Markdown through Firecrawl, to quote what it says. Use it on a URL research_search returned.",
+    inputSchema: { type: "object", properties: { url: { type: "string" }, chars: { type: "integer", minimum: 500, maximum: 20000, description: "Characters to return (default 6000)" } }, required: ["url"] } },
+];
+
+const key = () => {
+  const k = process.env.FIRECRAWL_API_KEY;
+  if (!k) throw new Error("FIRECRAWL_API_KEY is not set: research is unavailable, so say so rather than guessing");
+  return k;
+};
+async function post(path, body) {
+  const res = await fetch(`${API}${path}`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${key()}` }, body: JSON.stringify(body), signal: AbortSignal.timeout(60000) });
+  if (!res.ok) throw new Error(`Firecrawl answered ${res.status}: ${(await res.text()).slice(0, 300)}`);
+  return res.json();
+}
+
+export async function search({ queries, results = 5 }) {
+  const pages = await Promise.all(queries.slice(0, 5).map(async (q) => ({ q, r: await post("/search", { query: q, limit: results }) })));
+  return pages.flatMap(({ q, r }) => (r.data ?? []).slice(0, results).map((x) => ({ query: q, title: x.title ?? x.metadata?.title ?? null, url: x.url, snippet: x.description ?? x.metadata?.description ?? null })));
+}
+
+export async function read({ url, chars = 6000 }) {
+  const r = await post("/scrape", { url, formats: ["markdown"], onlyMainContent: true });
+  return { url, title: r.data?.metadata?.title ?? null, markdown: (r.data?.markdown ?? "").slice(0, chars) };
+}
+
+export async function handle({ id, method, params = {} }) {
+  const reply = (result) => ({ jsonrpc: "2.0", id, result });
+  switch (method) {
+    case "initialize": return reply({ protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "research", version: "0.1.0" }, instructions: "Research the market with research_search (and research_read to quote a page) and cite every URL you use." });
+    case "notifications/initialized": case "notifications/cancelled": return null;
+    case "ping": return reply({});
+    case "tools/list": return reply({ tools: TOOLS });
+    case "tools/call": {
+      const fn = { research_search: search, research_read: read }[params.name];
+      if (!fn) return { jsonrpc: "2.0", id, error: { code: -32602, message: `unknown tool ${params.name}` } };
+      try { return reply({ content: [{ type: "text", text: JSON.stringify(await fn(params.arguments ?? {}), null, 2) }], isError: false }); }
+      catch (e) { return reply({ content: [{ type: "text", text: String(e.message ?? e) }], isError: true }); }
+    }
+    default: return id === undefined ? null : { jsonrpc: "2.0", id, error: { code: -32601, message: `method not found: ${method}` } };
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const rl = createInterface({ input: process.stdin });
+  let chain = Promise.resolve();
+  rl.on("line", (line) => { chain = chain.then(async () => { if (!line.trim()) return; const out = await handle(JSON.parse(line)); if (out) process.stdout.write(JSON.stringify(out) + "\n"); }); });
+}

package/platform/webhooks/server.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Webhooks from systems of record (V-9, platform): a CRM, a bank or a spend tool calls Mentura when
+// something it holds changes, the way a CMS calls a Next.js revalidation webhook. The request is checked
+// (an HMAC-SHA256 signature of the raw body with the source's shared secret), and the framework marks
+// every summary that reads the changed items stale (schema/stale.mjs notify). Nothing is fetched and no
+// record is rewritten here: the next write of each summary makes it fresh.
+//
+//   node platform/webhooks/server.mjs [--port 4330] [--host 127.0.0.1] [--workspace <dir>]
+//
+//   POST /webhooks/<venture id>/<source id>
+//     header  x-naive-signature: sha256=<hex HMAC-SHA256 of the raw body>
+//     body    { "paths": ["customers/acme.json"], "version": "<the source's version, optional>", "at": "<when, optional>" }
+//     202     { "venture", "source", "paths", "stale": [the files marked stale] }
+//
+// The secret is NAIVE_WEBHOOK_SECRET_<SOURCE> (the source id upper-cased, hyphens as underscores), else
+// NAIVE_WEBHOOK_SECRET; with neither set every request is refused. A source must be in the venture's
+// knowledge/sources.json. It binds to 127.0.0.1 by default; put it behind the platform's TLS to expose it.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { resolve } from "node:path";
+import { ventureDir } from "../../interface/router.mjs";
+import { notify } from "../../schema/stale.mjs";
+
+const MAX = 256 * 1024;
+export const secretFor = (source, env = process.env) => env[`NAIVE_WEBHOOK_SECRET_${source.toUpperCase().replace(/-/g, "_")}`] ?? env.NAIVE_WEBHOOK_SECRET ?? null;
+export const sign = (secret, body) => `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
+
+function verified(secret, body, header) {
+  if (!secret || typeof header !== "string") return false;
+  const want = Buffer.from(sign(secret, body)), got = Buffer.from(header);
+  return want.length === got.length && timingSafeEqual(want, got);
+}
+
+/** The webhook server over a workspace. env supplies the secrets (default process.env). */
+export function webhooks({ workspace = process.env.MENTURA_WORKSPACE, env = process.env } = {}) {
+  return createServer((req, res) => {
+    const send = (code, body) => { res.writeHead(code, { "content-type": "application/json" }); res.end(JSON.stringify(body) + "\n"); };
+    const m = req.url?.match(/^\/webhooks\/([a-z0-9][a-z0-9-]*)\/([a-z][a-z0-9-]*)\/?$/);
+    if (!m) return send(404, { error: "POST /webhooks/<venture id>/<source id>" });
+    if (req.method !== "POST") return send(405, { error: "webhooks are POST" });
+    const chunks = [];
+    let size = 0;
+    req.on("data", (c) => { size += c.length; if (size > MAX) { send(413, { error: `a notification is at most ${MAX / 1024} KB` }); req.destroy(); } else chunks.push(c); });
+    req.on("end", () => {
+      if (size > MAX) return;
+      const raw = Buffer.concat(chunks);
+      const [, venture, source] = m;
+      if (!verified(secretFor(source, env), raw, req.headers["x-naive-signature"])) return send(401, { error: "the signature does not match this source's secret" });
+      const dir = ventureDir(venture, workspace);
+      if (!dir) return send(404, { error: `no venture ${venture}` });
+      let body;
+      try { body = JSON.parse(raw.toString("utf8")); } catch { return send(400, { error: "the body is not JSON" }); }
+      const paths = [body.paths ?? body.path].flat().filter((p) => typeof p === "string" && p && !p.startsWith("/") && !p.split("/").includes(".."));
+      if (!paths.length) return send(400, { error: "name the changed items in paths" });
+      try {
+        const r = notify(dir, { source, paths, version: typeof body.version === "string" ? body.version : undefined, at: typeof body.at === "string" ? body.at : undefined, via: "webhook" });
+        return send(202, { venture, ...r });
+      } catch (e) { return send(/no source/.test(e.message) ? 404 : 400, { error: e.message }); }
+    });
+  });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const a = process.argv.slice(2);
+  const opt = (n, d) => { const i = a.indexOf(`--${n}`); return i >= 0 ? a[i + 1] : d; };
+  const workspace = opt("workspace") ? resolve(opt("workspace")) : process.env.MENTURA_WORKSPACE;
+  const s = webhooks({ workspace });
+  s.listen(Number(opt("port", 4330)), opt("host", "127.0.0.1"), () => console.log(`webhooks on http://${opt("host", "127.0.0.1")}:${s.address().port}/webhooks/<venture>/<source> for ${workspace ?? "this repository's instance/"}`));
+}