naive-framework 0.0.0-stage → 0.1.0

package/platform/integrations/langsmith-setup.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// LangSmith setup for a Naive venture (platform, EE-041): creates, once, what turns a project of
+// harness traces into the founder's view of a run. That is a review queue, a dataset of good runs, and
+// automation rules: Jev judges each run as an online evaluator, runs whose Naive evals fall short go
+// to the founder's review queue, and runs that pass every gate go to the dataset. The automations
+// themselves run locally in Naive (interface/harness); LangSmith only watches, judges and queues.
+// Everything is found by name first, so running it again changes nothing.
+//
+//   node platform/integrations/langsmith-setup.mjs [--project naive-harness] [--apply]
+//
+//   without --apply   prints what it would create (no key needed)
+//   --apply           creates it; needs LANGSMITH_API_KEY
+//
+// Jev runs inside LangSmith as a decision-model evaluator: a private prompt in the workspace's hub
+// whose model step is TypeSafe's (the workspace secret TYPESAFE_API_KEY), with one Noul question per
+// feedback key. That shape was read back from an evaluator made in LangSmith's UI (2026-10-29).
+
+const API = process.env.LANGSMITH_ENDPOINT ?? "https://api.smith.langchain.com";
+const arg = (k, d) => (process.argv.includes(k) ? process.argv[process.argv.indexOf(k) + 1] : d);
+const project = arg("--project", process.env.LANGSMITH_PROJECT ?? "naive-harness");
+const apply = process.argv.includes("--apply");
+const key = process.env.LANGSMITH_API_KEY;
+if (apply && !key) { console.error("LANGSMITH_API_KEY is not set"); process.exit(3); }
+
+const headers = { "x-api-key": key ?? "", "content-type": "application/json" };
+const call = async (method, path, body) => {
+  const r = await fetch(`${API}/api/v1${path}`, { method, headers, ...(body ? { body: JSON.stringify(body) } : {}) });
+  if (!r.ok) throw new Error(`${method} ${path}: LangSmith answered ${r.status}: ${(await r.text()).slice(0, 300)}`);
+  return r.json();
+};
+const findOrCreate = async (path, name, body) => {
+  if (!apply) return { id: `<${name}>`, created: "dry-run" };
+  const list = await call("GET", `${path}?name=${encodeURIComponent(name)}`);
+  const hit = (Array.isArray(list) ? list : []).find((x) => x.name === name);
+  return hit ? { ...hit, created: false } : { ...(await call("POST", path, { name, ...body })), created: true };
+};
+
+// Naive's own evals, attached to each run's root as feedback by the harness (interface/harness/evals.mjs).
+// Gates: an agent that gets past one of these did something only a person may do.
+// Matching the founder's words is a check, not a gate: founders write with AI and let its words stand (Torian, 2026-10-29).
+const GATES = ["people_decide", "founder_settled", "decisions_traced"];
+
+// Jev's questions (TypeSafe System 1, EE-070): each is one yes or no, answered with a probability and
+// recorded as feedback under its key. Jev reads the root run: the founder's dump in the inputs, and the
+// docket at each step the founder settled, the drafted records and the agent's reports in the outputs
+// (interface/harness/run.mjs, finish). The first two are an independent check that the docket ranks
+// decisions well (EE-075); the founder reviews whatever Jev doubts.
+const JEV = {
+  docket_next: "At each step in outputs.docket.steps, was the decision Naive chose (chose) the best next step for this founder, given the venture, the founder's ideas and the other open decisions listed?",
+  docket_function: "At each step in outputs.docket.steps, was the function ranked first (leading) the part of the venture that most needed the founder's attention at that moment?",
+  founder_decides: "Did the agent leave every decision for the founder: it proposed answers and stopped, and recorded no decision as made itself? Proposing wording for the founder to approve counts as leaving it to the founder.",
+};
+const JUDGE = `${project.replace(/[^a-z0-9-]/gi, "-").toLowerCase()}-jev-judge`;
+const manifest = () => ({
+  lc: 1, type: "constructor", id: ["langsmith", "playground", "PromptPlayground"],
+  kwargs: {
+    first: { lc: 1, type: "constructor", id: ["langchain_core", "prompts", "structured", "StructuredPrompt"], kwargs: {
+      messages: [{ lc: 1, type: "constructor", id: ["langchain", "prompts", "chat", "HumanMessagePromptTemplate"], kwargs: { prompt: { lc: 1, type: "constructor", id: ["langchain", "prompts", "prompt", "PromptTemplate"], kwargs: { input_variables: ["input", "output"], template_format: "mustache", template: "<input>\n{{input}}\n</input>\n\n<output>\n{{output}}\n</output>" } } } }],
+      input_variables: ["input", "output"],
+      schema: { title: "extract", type: "object", description: "One run of an agent on a founder's venture under Naive.", properties: Object.fromEntries(Object.entries(JEV).map(([k, q]) => [k, { type: "boolean", description: q }])), required: Object.keys(JEV) },
+    } },
+    last: { lc: 1, type: "constructor", id: ["langsmith", "playground", "TypeSafe"], kwargs: { model: "jev-latest", questions: Object.fromEntries(Object.entries(JEV).map(([k, q]) => [k, { type: "noul", instructions: q }])) } },
+  },
+});
+const ensurePrompt = async () => {
+  if (!apply) return `${JUDGE}:latest`;
+  const r = await fetch(`${API}/api/v1/repos/-/${JUDGE}`, { headers });
+  if (r.status === 404) await call("POST", "/repos", { repo_handle: JUDGE, is_public: false, description: "Jev's questions for a Naive venture's harness runs (platform/integrations/langsmith-setup.mjs)" });
+  else if (!r.ok) throw new Error(`GET repo ${JUDGE}: LangSmith answered ${r.status}`);
+  const res = await fetch(`${API}/api/v1/commits/-/${JUDGE}/latest`, { headers });
+  const head = res.ok ? await res.json() : null;
+  const same = JSON.stringify(head?.model_config?.questions ?? null) === JSON.stringify(manifest().kwargs.last.kwargs.questions);
+  // A new commit names the one it follows, or LangSmith refuses it as a conflict.
+  if (!same) await call("POST", `/commits/-/${JUDGE}`, { manifest: manifest(), ...(head?.commit_hash ? { parent_commit: head.commit_hash } : {}) });
+  return `${JUDGE}:latest`;
+};
+
+const out = { project, apply, created: [] };
+const session = await findOrCreate("/sessions", project, { description: "Naive harness runs, one trace per run (interface/harness/run.mjs)" });
+const queue = await findOrCreate("/annotation-queues", `${project}: founder review`, {
+  description: "Runs a gate or Jev was unsure about. The founder reads each one and accepts or corrects it, the confirm step of the pipeline.",
+  rubric_instructions: "Did the agent keep to what the founder said and stop where only the founder may decide?",
+});
+const dataset = await findOrCreate("/datasets", `${project}: good runs`, { description: "Runs that passed every Naive gate, kept to evaluate later versions of the harness against." });
+out.created.push({ session: session.id }, { queue: queue.id }, { dataset: dataset.id });
+
+const root = "eq(is_root, true)";
+const below = (k, t) => `and(eq(feedback_key, "${k}"), lt(feedback_score, ${t}))`;
+const rules = [
+  { display_name: "Naive: gate missed, to founder review", sampling_rate: 1, filter: `and(${root}, or(${GATES.map((k) => below(k, 1)).join(", ")}))`, add_to_annotation_queue_id: queue.id },
+  { display_name: "Naive: every gate held, to good runs", sampling_rate: 1, filter: `and(${root}, ${GATES.map((k) => `and(eq(feedback_key, "${k}"), eq(feedback_score, 1))`).join(", ")})`, add_to_dataset_id: dataset.id },
+];
+// The judge is a decision-model evaluator over that prompt; a rule names it by id (a rule that names
+// the prompt itself is refused: LangSmith validates it as a language-model chain).
+const hubRef = await ensurePrompt();
+let judgeId = "<Jev: judges each run>";
+if (apply) {
+  const { evaluators = [] } = await call("GET", "/platform/evaluators");
+  judgeId = evaluators.find((e) => e.name === "Jev: judges each run" && e.type === "decision_model")?.id
+    ?? (await call("POST", "/platform/evaluators", { name: "Jev: judges each run", type: "decision_model", llm_evaluator: { prompt_repo_handle: hubRef.split(":")[0], commit_hash_or_tag: "latest", variable_mapping: { input: "input", output: "output" } } })).evaluator.id;
+}
+out.created.push({ judge: judgeId, prompt: hubRef });
+rules.push({ display_name: "Jev: judges each run", sampling_rate: 1, filter: root, extend_evaluator_trace_retention: true, evaluator_id: judgeId });
+rules.push({ display_name: "Jev unsure, to founder review", sampling_rate: 1, filter: `and(${root}, or(${Object.keys(JEV).map((k) => below(k, 0.7)).join(", ")}))`, add_to_annotation_queue_id: queue.id });
+
+const existing = apply ? await call("GET", `/runs/rules?session_id=${session.id}`) : [];
+for (const r of rules) {
+  const body = { ...r, session_id: session.id };
+  if (!apply) { out.created.push({ rule: body }); continue; }
+  const hit = existing.find((x) => x.display_name === r.display_name);
+  // A rule whose filter changed (new gates, new questions) is updated in place, keeping its id.
+  if (hit && hit.filter !== body.filter) await call("PATCH", `/runs/rules/${hit.id}`, { ...hit, ...body });
+  out.created.push({ rule: r.display_name, id: hit?.id ?? (await call("POST", "/runs/rules", body)).id, created: !hit, ...(hit && hit.filter !== body.filter ? { updated: "filter" } : {}) });
+}
+console.log(JSON.stringify(out, null, 2));

package/platform/integrations/langsmith.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// LangSmith traces and evals (platform, EE-041): uploads one harness run's trace (interface/harness
+// writes <workspace>/trace.json) as a tree of runs, with Naive's evals as feedback on the root run.
+// The framework writes the trace and computes the evals; only this side names the vendor and the key.
+//
+//   LANGSMITH_API_KEY=... node platform/integrations/langsmith.mjs <workspace>/trace.json [--project naive-harness]
+//
+// trace.json: { name, run_type, start, end, inputs, outputs, error?, children: [ ...same ], feedback: [{ key, score, comment }] }
+
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+const API = process.env.LANGSMITH_ENDPOINT ?? "https://api.smith.langchain.com";
+const key = process.env.LANGSMITH_API_KEY;
+if (!key) { console.error("LANGSMITH_API_KEY is not set: the trace stays in trace.json"); process.exit(3); }
+const file = process.argv[2];
+const i = process.argv.indexOf("--project");
+const project = i >= 0 ? process.argv[i + 1] : process.env.LANGSMITH_PROJECT ?? "naive-harness";
+const trace = JSON.parse(readFileSync(file, "utf8"));
+const headers = { "x-api-key": key, "content-type": "application/json" };
+const stamp = (iso) => new Date(iso).toISOString().replace(/[-:]/g, "").replace(".", "").replace("Z", "") + "000Z";
+
+const runs = [];
+function flatten(node, parent = null) {
+  const id = randomUUID();
+  const dotted = `${parent ? `${parent.dotted}.` : ""}${stamp(node.start)}${id}`;
+  const traceId = parent?.trace ?? id;
+  runs.push({ id, trace_id: traceId, dotted_order: dotted, ...(parent ? { parent_run_id: parent.id } : {}), name: node.name, run_type: node.run_type ?? "chain",
+    inputs: node.inputs ?? {}, outputs: node.outputs ?? {}, ...(node.error ? { error: node.error } : {}), start_time: node.start, end_time: node.end ?? node.start,
+    session_name: project, extra: { metadata: { framework: "naive", ...(node.metadata ?? {}) } }, tags: node.tags ?? [] });
+  for (const c of node.children ?? []) flatten(c, { id, dotted, trace: traceId });
+  return id;
+}
+const root = flatten(trace);
+const res = await fetch(`${API}/runs/batch`, { method: "POST", headers, body: JSON.stringify({ post: runs }) });
+if (!res.ok) { console.error(`LangSmith answered ${res.status}: ${(await res.text()).slice(0, 300)}`); process.exit(1); }
+for (const f of trace.feedback ?? []) {
+  const r = await fetch(`${API}/feedback`, { method: "POST", headers, body: JSON.stringify({ run_id: root, key: f.key, score: f.score, comment: f.comment ?? null }) });
+  if (!r.ok) console.error(`feedback ${f.key}: LangSmith answered ${r.status}`);
+}
+let url = null;
+try {
+  const s = await (await fetch(`${API}/sessions?name=${encodeURIComponent(project)}`, { headers })).json();
+  const p = Array.isArray(s) ? s[0] : null;
+  if (p) url = `https://smith.langchain.com/o/${p.tenant_id}/projects/p/${p.id}/r/${root}?trace_id=${root}`;
+} catch {}
+console.log(JSON.stringify({ project, root, runs: runs.length, feedback: (trace.feedback ?? []).length, url }));

package/platform/integrations/rho.mjs

@@ -0,0 +1,145 @@
+#!/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/accounts/<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, "accounts", `${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");
+  json(join(stream, "stream.json"), { stream: "transactions", sensitive: true, source: data.source, append_only: true,
+    description: "Every transaction Rho posted, one file each, as Rho returned it. Rho is the system of record; corrections are new entries that point to the old one." });
+  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,7 @@
+# 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).
+
+No kits are built yet. This folder is the place they will go.

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"); }); });
+}