naive-framework 0.1.0 → 0.2.0

package/interface/gate-hooks.mjs

@@ -0,0 +1,36 @@
+// The router's hooks into the gate group (X-1 to X-6, P-2, P-7, U-4). Each is called from one
+// marked line in interface/router.mjs, so the router stays the route table and the logic stays in
+// schema/gate.mjs (the verdict), schema/gate-drafts.mjs (held drafts) and schema/naive-config.mjs
+// (the venture's overrides).
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { evaluate } from "../schema/gate.mjs";
+import { writeHeld } from "../schema/gate-drafts.mjs";
+import { checksFor, configFor } from "../schema/naive-config.mjs";
+
+/**
+ * The gate's verdict on a local write, or null when it passes. A person is never held, only
+ * refused. A naive.config.json that is not valid JSON fails closed: an agent's write is held.
+ */
+export function gateWrite({ dir, r, route, requested, file, actor, actor_id, provenance = {}, gate }) {
+  let config;
+  try { config = configFor(dir); }
+  catch (e) { return actor === "person" ? null : { then: "draft", rule: "naive.config.json", source: "naive.config.json", why: `${e.message}: the gate fails closed, written as a draft for a person to accept` }; }
+  const confidence = provenance.confidence === undefined || provenance.confidence === null || provenance.confidence === "" ? undefined : Number(provenance.confidence);
+  const v = evaluate({ config, dir, route, table: r.route, requested, record: r.record, actor, role: actor_id, confidence: Number.isNaN(confidence) ? undefined : confidence,
+    exists: existsSync(join(dir, file)), decisionOwner: gate?.owner ?? undefined });
+  if (v.then === "pass") return null;
+  if (actor === "person" && v.then !== "refuse") return null;
+  return v;
+}
+
+/** Stores an agent's held draft: its sidecar, the owner it was sent to, and variants side by side. */
+export function heldDraft(dir, { draft, file, text, verdict, route, agent }) {
+  return writeHeld(dir, { draft, file, text, verdict, route, agent });
+}
+
+/** A route's checks with their mode from naive.config.json: run, warn or off. A broken config runs them all. */
+export function checkPlan(dir, checks) {
+  try { return checksFor(configFor(dir), checks); } catch { return checks.map((check) => ({ check, mode: "run" })); }
+}

package/interface/harness/evals.mjs

@@ -72,7 +72,7 @@ export function evaluate(dir, { researched = [], settled = [] } = {}) {
   add("founder_settled", settled.length ? 1 : 0, settled.length ? `settled: ${settled.join(", ")}` : "the founder settled nothing");
   // Money (EE-070): when the venture has a money summary, it is fresh, the agent cites it, and no raw
   // transaction leaves its sensitive stream for another record.
-  const summaryFile = join(dir, "money/summary.json");
+  const summaryFile = join(dir, "money/_summary.json");
   if (existsSync(summaryFile)) {
     const m = load(summaryFile);
     const age = (Date.now() - Date.parse(m.synced_at)) / 864e5;
@@ -80,8 +80,8 @@ export function evaluate(dir, { researched = [], settled = [] } = {}) {
     // Only what touches money has to cite it: pricing, spend, hiring, runway, fundraising, cash.
     const records = [...agentDrafted, ...(problem ? [{ problem: load(problem) }] : [])].map((d) => JSON.stringify(d));
     const touching = records.filter((x) => /money\/summary|\b(pric(e|ing)|spend|budget|hir(e|ing)|runway|burn|fundrais|cash|revenue)\b/i.test(x));
-    const citing = touching.filter((x) => x.includes("money/summary"));
-    add("money_cited", frac(citing.length, touching.length), touching.length ? `${citing.length} of ${touching.length} agent records that touch money cite money/summary.json` : "no agent record touches money, so none needs to cite it");
+    const citing = touching.filter((x) => x.includes("money/_summary"));
+    add("money_cited", frac(citing.length, touching.length), touching.length ? `${citing.length} of ${touching.length} agent records that touch money cite money/_summary.json` : "no agent record touches money, so none needs to cite it");
     const leaked = walk(dir).filter((f) => !f.includes("/money/_streams/") && f.endsWith(".json") && /:transaction:/.test(readFileSync(f, "utf8")));
     add("money_private", leaked.length ? 0 : 1, leaked.length ? `transaction pointers outside the money stream: ${leaked.map((f) => f.slice(dir.length + 1)).join(", ")}` : "transactions stay in their sensitive stream");
   }

package/interface/harness/run.mjs

@@ -83,9 +83,9 @@ if (opt("money")) {
   const m = opt("money");
   const src = m === "live" ? ["--live"] : m === "sandbox" ? [] : ["--fixture", resolve(m)];
   const p = spawnSync("node", [join(repo, "platform/integrations/rho.mjs"), "sync", "--venture", dir, ...src], { encoding: "utf8" });
-  if (p.status === 0 && existsSync(join(dir, "money/summary.json"))) {
-    money = JSON.parse(readFileSync(join(dir, "money/summary.json"), "utf8"));
-    prov(dir, { entity: "money/summary.json", route: "money/summary", activity: "create", agent: agentFromEnv("agent", "harness", { id: "naive-money" }), note: `synced from ${money.source}; ${money.transactions} transactions kept as pointers in a sensitive stream` });
+  if (p.status === 0 && existsSync(join(dir, "money/_summary.json"))) {
+    money = JSON.parse(readFileSync(join(dir, "money/_summary.json"), "utf8"));
+    prov(dir, { entity: "money/_summary.json", route: "money/_summary", activity: "create", agent: agentFromEnv("agent", "harness", { id: "naive-money" }), note: `synced from ${money.source}; ${money.transactions} transactions kept as pointers in a sensitive stream` });
     lap(`money synced from ${money.source}${money.business ? ` (${money.business})` : ""}: cash ${(money.cash.amount / 100).toFixed(2)} ${money.cash.currency}, monthly net ${(money.monthly_net.amount / 100).toFixed(2)}, runway ${money.runway_months ?? "not limited by burn"}, as of ${money.as_of}`);
   } else console.log(`   money sync failed, so the run goes on without it: ${(p.stderr || p.stdout).trim().slice(0, 300)}`);
 }
@@ -236,7 +236,7 @@ lap("the founder confirmed Mentura's understanding of the ideas; routing them");
 
 const rules = `You are the builder agent (agent_id builder) for the venture ${id}. Work only through the naive MCP tools${research ? " and the research tools" : ""}; pass agent_id "builder" on every naive call.
 Rules: the founder's idea dump is theirs. Quote it, cite ideas by id (i-01...), never put words in their mouth. Never invent evidence: every evidence item cites a URL a research result gave you${research ? "" : " (you have no research tool in this run, so leave evidence empty and say so)"}. Records Naive treats as the founder's are written as drafts for the founder to accept; that is expected. You never decide; you propose. knowledge/venture-profile cannot be written over MCP; skip it.${money ? `
-Money: Naive synced the venture's money summary from ${money.source}, the system of record (money/summary.json): ${JSON.stringify(money)}. Amounts are in minor units (cents). Any proposal or record that touches money (pricing, spend, hiring, runway, fundraising) cites "money/summary.json as of ${money.as_of}" and uses only the figures the summary gives; never estimate the founder's finances.` : ""}`;
+Money: Naive synced the venture's money summary from ${money.source}, the system of record (money/_summary.json): ${JSON.stringify(money)}. Amounts are in minor units (cents). Any proposal or record that touches money (pricing, spend, hiring, runway, fundraising) cites "money/_summary.json as of ${money.as_of}" and uses only the figures the summary gives; never estimate the founder's finances.` : ""}`;
 
 await agent(`${rules}
 The founder has just submitted an idea dump. Naive mapped it onto its conventions.

package/interface/instrumentation.mjs

@@ -0,0 +1,86 @@
+// Instrumentation (Naive's instrumentation.ts, P-4; logging fetches in development, F-4). One hook
+// where every router call, every judgment and every provenance entry (write, draft, accept,
+// confirm, decision) emits an event. Listeners registered in-process get every event. When a venture
+// turns instrumentation on, events are also appended to <venture>/.naive/events.jsonl, which agent
+// vitals read (interface/vitals.mjs, N-6). Provenance stays the record of what changed; events are
+// what it cost. A platform exporter (platform/integrations/langsmith.mjs) can ship a trace made from
+// the events; the framework names no vendor.
+//
+// Turn it on in the venture's naive.config.json, like adding instrumentation.ts to a Next.js app:
+//
+//   { "instrumentation": { "events": true } }
+//
+// NAIVE_INSTRUMENT=1 turns it on for every venture in this process, and NAIVE_INSTRUMENT=0 off.
+// No dependencies and no network. An event holds routes, sizes and times, never record content.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const EVENTS = ".naive/events.jsonl";
+const listeners = new Set();
+const scope = new AsyncLocalStorage();
+
+/** Tokens a payload costs an agent, estimated as characters / 4 (the common rule of thumb). */
+export const tokens = (x) => Math.ceil((x === undefined ? 0 : typeof x === "string" ? x.length : (JSON.stringify(x) ?? "").length) / 4);
+
+/** Registers a listener for every event, like register() in instrumentation.ts. Returns the unregister. */
+export function register(fn) { listeners.add(fn); return () => listeners.delete(fn); }
+
+const configOf = (dir) => {
+  const f = dir && join(dir, "naive.config.json");
+  if (!f || !existsSync(f)) return {};
+  try { return JSON.parse(readFileSync(f, "utf8")); } catch { return {}; }
+};
+
+/** Whether a venture writes its events log. */
+export function enabled(dir) {
+  if (process.env.NAIVE_INSTRUMENT === "0") return false;
+  if (process.env.NAIVE_INSTRUMENT === "1") return !!dir;
+  const i = configOf(dir).instrumentation;
+  return i === true || i?.events === true;
+}
+
+/** Emits one event: to every listener, and to the venture's events log when it is on. */
+export function emit(dir, event) {
+  const e = { at: new Date().toISOString(), id: randomUUID(), session: process.env.MENTURA_SESSION ?? null, ...event };
+  for (const k of Object.keys(e)) if (e[k] === undefined) delete e[k];
+  for (const fn of listeners) { try { fn(e, dir); } catch {} }
+  if (dir && enabled(dir)) {
+    try { mkdirSync(join(dir, ".naive"), { recursive: true }); appendFileSync(join(dir, EVENTS), JSON.stringify(e) + "\n"); } catch {}
+  }
+  return e;
+}
+
+/** The venture's events, oldest first. */
+export function events(dir) {
+  const f = join(dir, EVENTS);
+  if (!existsSync(f)) return [];
+  return readFileSync(f, "utf8").split("\n").filter((l) => l.trim()).flatMap((l) => { try { return [JSON.parse(l)]; } catch { return []; } });
+}
+
+/**
+ * Wraps one router call: times it, measures what it sends back, and emits a call event. A call made
+ * inside another (a view reads its record, the overview runs its slots) carries its parent's id, so
+ * vitals count only what the agent asked for. dirOf resolves the venture folder.
+ */
+export async function instrumented(args, fn, dirOf) {
+  const parent = scope.getStore() ?? null;
+  const id = randomUUID();
+  const t0 = performance.now();
+  const r = await scope.run(id, () => fn(args));
+  if (process.env.NAIVE_INSTRUMENT === "0" && !listeners.size) return r;
+  let dir = null;
+  try { dir = args.venture ? dirOf(args.venture, args.workspace) : null; } catch {}
+  if (!dir && !listeners.size) return r;
+  const useful = !!r?.ok && r.result !== null && r.result !== undefined && !r.needs_input;
+  emit(dir, { kind: "call", id, parent, session: args.session ?? args.input?.session ?? process.env.MENTURA_SESSION ?? null, venture: args.venture ?? null, route: args.route, action: args.action,
+    ok: !!r?.ok, useful, ms: Math.round(performance.now() - t0), tokens: tokens(r?.result ?? r?.error), actor: args.actor ?? "agent", via: args.via ?? "router" });
+  return r;
+}
+
+/** Records one judgment (a System 1 call or a scored check): what was asked, the score and the outcome. */
+export function judgment(dir, { question, score, threshold, outcome, owner, model, route, ms }) {
+  return emit(dir, { kind: "judgment", question, score, threshold, outcome, owner, model, route, ms });
+}

package/interface/kit-boundary.mjs

@@ -0,0 +1,73 @@
+// The boundary around a kit's agent workflow (S-15): the Next.js advice to wrap a third-party component
+// that uses client features, with the library author declaring "use client". A kit (Mentura's enhanced
+// package, platform/kits/<name>/kit.json) declares, under boundary, what its workflow reads, what it
+// writes and which of its steps use a model:
+//
+//   { "name": "...", "package": "<the package it extends>",
+//     "boundary": { "reads": [<route globs>], "writes": [<route globs>], "use_model": [<model steps>] } }
+//
+// wrap(kit) returns the router's call with that boundary around it: a read outside reads or writes, a
+// write outside writes, or a command it does not read is refused as an expected error, and every call
+// acts as the kit's agent, never as a person. A kit that uses a model writes judgments, so it declares
+// knowledge/judgment/** in writes. This module reads kit.json as data and never imports from platform/.
+//
+//   node interface/kit-boundary.mjs <kit.json>      check one kit's boundary
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { call as routerCall, glob, repo, routes } from "./router.mjs";
+// schema/model-steps.mjs is imported inside checkKit, not here, because it imports wrap from this module.
+
+const ID = /^[a-z0-9][a-z0-9-]*$/;
+export const actorOf = (kit) => `kit-${kit.name}`;
+const any = (globs, route) => (globs ?? []).some((g) => glob(g).test(route));
+const reachable = (b, route) => any(b.reads, route) || any(b.writes, route);
+
+/** Errors in a kit's declared boundary, its model steps included. */
+export async function checkKit(kit) {
+  const { checkSteps, inputOf } = await import("../schema/model-steps.mjs");
+  const e = [];
+  if (!kit || typeof kit !== "object") return ["a kit.json is an object"];
+  if (typeof kit.name !== "string" || !ID.test(kit.name)) e.push("a kit has a name of lowercase letters, digits and hyphens");
+  if (typeof kit.package !== "string" || !existsSync(join(repo, "packages", kit.package, "package.json"))) e.push(`kit ${kit.name}: package ${kit.package} is not a package in packages/ (a kit extends one package and never replaces it)`);
+  const b = kit.boundary;
+  if (!b || typeof b !== "object") { e.push(`kit ${kit.name}: declares a boundary: what it reads, what it writes, which steps use a model`); return e; }
+  for (const k of ["reads", "writes", "use_model"]) if (!Array.isArray(b[k])) e.push(`kit ${kit.name}: boundary.${k} is an array${k === "use_model" ? ", empty when it calls no model" : ""}`);
+  if (e.length) return e;
+  const all = routes().map((r) => r.route);
+  for (const g of [...b.reads, ...b.writes]) if (!all.some((r) => glob(g).test(r) || glob(g).test(r.replace("[id]", "x")))) e.push(`kit ${kit.name}: ${g} matches no route`);
+  const steps = b.use_model.map((s) => ({ ...s, package: kit.name }));
+  e.push(...(await checkSteps(steps)).map((x) => `kit ${x}`));
+  for (const s of steps) {
+    if (s.for_each && !reachable(b, s.for_each)) e.push(`kit ${kit.name}/${s.step}: reads ${s.for_each}, outside the kit's reads`);
+    for (const i of s.inputs ?? []) { const p = inputOf(i); if (p.form === "route" && !reachable(b, p.route)) e.push(`kit ${kit.name}/${s.step}: input ${i} is outside the kit's reads`); }
+    for (const spec of Object.values(s.computed ?? {})) {
+      const route = spec?.count ?? (spec?.read ? String(spec.read).split("#")[0] : null);
+      if (route && !reachable(b, route)) e.push(`kit ${kit.name}/${s.step}: computes from ${route}, outside the kit's reads`);
+    }
+  }
+  if (steps.length && !any(b.writes, "knowledge/judgment/x")) e.push(`kit ${kit.name}: uses a model, so it writes judgments: declare knowledge/judgment/** in boundary.writes`);
+  return e;
+}
+
+/** The router's call, wrapped in the kit's boundary. */
+export function wrap(kit, call = routerCall) {
+  const b = kit.boundary ?? { reads: [], writes: [], use_model: [] };
+  return async (args) => {
+    const route = args.route;
+    const act = args.action === "write" ? "write" : "read";
+    const ok = act === "write" ? any(b.writes, route) : reachable(b, route);
+    if (!ok) return { ok: false, outcome: "expected", error: `kit ${kit.name} declares no ${act} of ${route} (boundary.${act === "write" ? "writes" : "reads"} in its kit.json)` };
+    // The kit's workflow is an agent, whatever the caller passed.
+    return call({ ...args, actor: "agent", actor_id: actorOf(kit), provenance: { ...(args.provenance ?? {}), note: `kit ${kit.name}${args.provenance?.note ? `: ${args.provenance.note}` : ""}` } });
+  };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const f = process.argv[2];
+  if (!f) { console.error("usage: node interface/kit-boundary.mjs <kit.json>"); process.exit(2); }
+  const kit = JSON.parse(readFileSync(f, "utf8"));
+  const e = await checkKit(kit);
+  if (e.length) { console.error(e.join("\n")); process.exit(1); }
+  console.log(`kit ${kit.name}: reads ${kit.boundary.reads.length} route patterns, writes ${kit.boundary.writes.length}, ${kit.boundary.use_model.length} model steps, inside its boundary.`);
+}

package/interface/layer.json

@@ -6,10 +6,15 @@
     {
       "id": "install-mentura",
       "path": "interface/skills/install-mentura/SKILL.md"
+    },
+    {
+      "id": "naive-setup",
+      "path": "interface/skills/naive-setup/SKILL.md"
     }
   ],
   "records": [
-    "route-aliases"
+    "route-aliases",
+    "adapter"
   ],
   "reads": [
     "integration"
@@ -17,7 +22,8 @@
   "writes": [],
   "checks": [
     "schema/check-integrations.mjs",
-    "interface/test.mjs"
+    "interface/test.mjs",
+    "interface/adapters.mjs"
   ],
   "gaps": [
     "The operator console is a folder, not part of the layer yet",

package/interface/mcp/server.mjs

@@ -10,6 +10,7 @@
 
 import { createInterface } from "node:readline";
 import { call, routes, routesMd, ventureDir, ventures } from "../router.mjs";
+import { runStreaming } from "../context.mjs";
 import { propose } from "../../schema/decisions.mjs";
 
 const PROTOCOL = "2025-06-18";
@@ -20,17 +21,42 @@ export const TOOLS = [
   { name: "mentura_layout", description: "The context for a route before you act on it: the system, layer and kit purpose, skills and references, the schema and template, the gate, and what need-now says about the record.", inputSchema: { type: "object", properties: { venture, route }, required: ["route"] } },
   { name: "mentura_view", description: "A route as a Markdown page for a person. system/overview shows the venture at a glance.", inputSchema: { type: "object", properties: { venture, route }, required: ["venture", "route"] } },
   { name: "mentura_ventures", description: "The ventures in the workspace, with their phase.", inputSchema: { type: "object", properties: {} } },
-  { name: "mentura_read", description: "Read one record of a venture. Returns null when the venture has no such record yet.", inputSchema: { type: "object", properties: { venture, route }, required: ["venture", "route"] } },
+  { name: "mentura_read", description: "Read one record of a venture, header first: the header (what it is, its state, owner and size in tokens), the budget, the layout (in a session, only the parts you have not seen), the template (need-now and open decisions, fresh), the record as result (null when the venture has no such record yet), and prefetch: short summaries of the routes you are likely to need next. Pass header_only to stop after the header. A list returns only the items your role may read.", inputSchema: { type: "object", properties: { venture, route,
+    session: { type: "string", description: "Your session id: the layout is sent once per session, then only the parts that changed" },
+    task: { type: "string", description: "What you are doing; a route it names is prefetched in full" },
+    prefetch: { description: "false turns prefetch off; a list of routes prefetches those in full", oneOf: [{ type: "boolean" }, { type: "array", items: { type: "string" } }] },
+    header_only: { type: "boolean", description: "Return only the header, to decide whether to read on" },
+    where: { type: "object", description: "For a list: keep only records whose fields match these values" },
+    agent_id: { type: "string", description: "Your role in the team plan, so its read routes apply" } }, required: ["venture", "route"] } },
   { name: "mentura_write", description: "Write one record of a venture. The record must match its schema. A gated record is written as a draft under _drafts/ for a person to accept. Every write is logged in the venture's provenance log: say what the content came from and the decision it acts under.", inputSchema: { type: "object", properties: { venture, route, record: { type: "object", description: "The whole record" },
     derived_from: { type: "array", items: { type: "string" }, description: "What the content came from: venture-relative paths, URLs or decision ids" },
     decision: { type: "string", description: "The decision the write acts under, such as EE-026" },
     model: { type: "string", description: "Your model, for the provenance log" }, note: { type: "string" },
-    agent_id: { type: "string", description: "Your role in the team plan, so its routes and unlocks apply" } }, required: ["venture", "route", "record"] } },
+    agent_id: { type: "string", description: "Your role in the team plan, so its routes and unlocks apply" },
+    // Gate group hook (X-4): a score computed before the write; the gate's confidence rules read it and never compute one.
+    confidence: { type: "number", description: "Your confidence in this record, 0 to 1, if you computed one. Below the venture's threshold, a gate rule may send the write to its function owner" } }, required: ["venture", "route", "record"] } },
   { name: "mentura_decisions", description: "The decisions a venture owes (EE-054): each with its parent, boundary, phase, due time and whether it renders now, is overdue, waits, comes later, is stale or deferred. Work on what renders now or overdue; a decision that waits is held by an open fail-closed decision above it. A route a pending decision unlocks is refused until a person decides it.", inputSchema: { type: "object", properties: { venture,
     render: { type: "array", items: { type: "string" }, description: "Only these states, such as [\"overdue\", \"now\"]" } }, required: ["venture"] } },
   { name: "mentura_propose_decision", description: "Propose a decision, or new wording for an open one. It stays open until a person approves it in the CLI (mentura decide); you can never mark a decision decided. Put it beside what it decides with at (a venture folder such as operations) and name (<record>[.<topic>]).", inputSchema: { type: "object", properties: { venture,
     decision: { type: "object", description: "id, question, and optionally answer (your proposed wording), decides, layer, parent, needed_in, due, outcomes, unlocks, note, plus at and name for where it goes" },
     agent_id: { type: "string", description: "Your role in the team plan" }, model: { type: "string" } }, required: ["venture", "decision"] } },
+  // Setup (EE-083, interface/skills/naive-setup): the questions that establish a new venture, in order, and an artifact of the progress.
+  { name: "mentura_setup", description: "Where a new venture's setup stands: its people and hats, the source of truth for each function, the foundation and first decisions (the docket), the goal for discovery, and which steps are done. artifact is that state as one self-contained HTML page: render it as an artifact where your harness has artifacts, and again after every answer. Ask the founder the next open question, one at a time, in order.", inputSchema: { type: "object", properties: { venture }, required: ["venture"] } },
+  { name: "mentura_setup_answer", description: "Write down the founder's answer to one setup question (a docket id from mentura_setup, or discovery-goal), exactly in their words. It is proposed with their words as its wording and stays open until the founder confirms it at the keyboard (naive setup confirm): you never decide for them.", inputSchema: { type: "object", properties: { venture,
+    id: { type: "string", description: "The question's id from mentura_setup's docket, or discovery-goal" },
+    answer: { type: "string", description: "The founder's answer, verbatim" },
+    agent_id: { type: "string", description: "Your role in the team plan" }, model: { type: "string" } }, required: ["venture", "id", "answer"] } },
+  { name: "mentura_setup_point", description: "Point one function of the venture at the system that holds its truth (from mentura_setup's catalog), as the founder said, such as finance at rho or products at github with address acme/app. Naive keeps a pointer, never a copy; Rho is synced at once.", inputSchema: { type: "object", properties: { venture,
+    function: { type: "string", description: "A function, such as products, finance or legal" },
+    system: { type: "string", description: "A system the catalog offers for that function" },
+    address: { type: "string", description: "Where in that system, such as acme/app" },
+    agent_id: { type: "string", description: "Your role in the team plan" } }, required: ["venture", "function", "system"] } },
+  // The decision library (schema/frames.mjs): a founder's problem matched to a frame, its premises judged, its decisions proposed.
+  { name: "mentura_frame", description: "When the founder states a problem in their own words (\"I need investors to scale but I don't want to give up control\"), match it to a frame in the decision library, judge the premises their sentence assumes against the venture's records, and propose the decisions hidden in it, open, with options. The result says which premises hold, whether the trade is false, real or a sequence, and the better question to ask. Never pick an option for the founder, and never name an instrument as the answer: options for how to do something come from a dated, cited lookup.", inputSchema: { type: "object", properties: { venture,
+    text: { type: "string", description: "The founder's words, verbatim" },
+    frame: { type: "string", description: "A frame id, when you already know it; otherwise the founder's words pick one" },
+    lookup: { type: "object", description: "Options a lookup found: { options: [{ option, source, as_of }] }; only dated, cited options within the frame's freshness are kept" },
+    agent_id: { type: "string", description: "Your role in the team plan" }, model: { type: "string" } } } },
   { name: "mentura_check", description: "Run the checks for one record of a venture.", inputSchema: { type: "object", properties: { venture, route }, required: ["venture", "route"] } },
   { name: "mentura_template", description: "The fill-in template for a record, where its kit has one.", inputSchema: { type: "object", properties: { route }, required: ["route"] } },
   { name: "mentura_run", description: "Run a command route for a venture: system/need-now (what to work on now), system/time-to-ready, purpose/validation/assess (what the problem's evidence is strong enough for), governance/payouts, knowledge/catalog (index every source the venture keeps records in), knowledge/search (find items in any of them). A result with needs_input lists what is missing: ask the person whether to fill it in or run as is, and only then call again with as_is.", inputSchema: { type: "object", properties: { venture, route, value: { type: ["number", "string"], description: "governance/payouts: a sale value; knowledge/search: the query" },
@@ -40,7 +66,8 @@ export const TOOLS = [
 
 let client = null; // the harness, as it named itself at initialize
 
-export async function handle(msg) {
+// notify sends a notification to the client; progress for a call that carries _meta.progressToken (N-5).
+export async function handle(msg, notify = () => {}) {
   const { id, method, params = {} } = msg;
   const reply = (result) => ({ jsonrpc: "2.0", id, result });
   const fail = (code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
@@ -54,15 +81,26 @@ export async function handle(msg) {
     case "tools/list": return reply({ tools: TOOLS });
     case "tools/call": {
       const a = params.arguments ?? {};
+      const token = params._meta?.progressToken;
+      let step = 0;
+      const progress = token === undefined ? null : ({ progress: p, total, message }) => notify({ jsonrpc: "2.0", method: "notifications/progress", params: { progressToken: token, progress: Math.max(p ?? 0, ++step), ...(total ? { total } : {}), message } });
       let r;
       switch (params.name) {
         case "mentura_routes": r = { ok: true, result: a.group ? routes().filter((x) => x.groups.includes(`(${a.group})`)) : routes() }; break;
         case "mentura_ventures": r = { ok: true, result: ventures().map(({ id, name, phase, path }) => ({ id, name, phase, path })) }; break;
         case "mentura_layout": r = await call({ venture: a.venture, route: a.route, action: "layout" }); break;
         case "mentura_view": r = await call({ venture: a.venture, route: a.route, action: "view" }); break;
-        case "mentura_read": r = await call({ venture: a.venture, route: a.route, action: "read" }); break;
+        // Context hook (interface/context.mjs): a read is a navigation, header first, its parts streamed as progress.
+        // A filtered list (where) is a plain read (interface/writes.mjs); anything else is a navigation.
+        case "mentura_read": r = a.where ? await call({ venture: a.venture, route: a.route, action: "read", actor_id: a.agent_id, via: "mcp", input: { where: a.where } }) : await call({ venture: a.venture, route: a.route, action: "navigate", actor_id: a.agent_id, via: "mcp",
+          input: { session: a.session, task: a.task, prefetch: a.prefetch, header_only: a.header_only, ...(progress ? { onPart: ({ part, data }) => progress({ message: `${part}: ${JSON.stringify(data)}` }) } : {}) } }); break;
         case "mentura_write": r = await call({ venture: a.venture, route: a.route, action: "write", input: a.record, actor: "agent", actor_id: a.agent_id, via: "mcp",
-          provenance: { derived_from: a.derived_from, decision: a.decision, note: a.note, agent: Object.fromEntries(Object.entries({ harness: client, model: a.model }).filter(([, v]) => v)) } }); break;
+          provenance: { derived_from: a.derived_from, decision: a.decision, note: a.note, confidence: a.confidence, agent: Object.fromEntries(Object.entries({ harness: client, model: a.model }).filter(([, v]) => v)) } }); break;
+        // Setup (EE-083): schema/setup.mjs holds the questions; answers are proposals the founder confirms.
+        case "mentura_setup": { const m = await import("../../schema/setup.mjs"); const dir = ventureDir(a.venture); r = { ok: true, result: { state: await m.state(dir), artifact: await m.artifact(dir) } }; break; }
+        case "mentura_setup_answer": r = await (await import("../../schema/setup.mjs")).relay(ventureDir(a.venture), { id: a.id, answer: a.answer, agentId: a.agent_id, harness: client, model: a.model }); break;
+        case "mentura_setup_point": r = await (await import("../../schema/setup.mjs")).point(ventureDir(a.venture), { fn: a.function, system: a.system, address: a.address, via: "mcp", actor: "agent", agentId: a.agent_id }); break;
+        case "mentura_frame": r = await (await import("../../schema/frames.mjs")).run(ventureDir(a.venture), { id: a.frame, text: a.text, lookup: a.lookup, agentId: a.agent_id ?? "frames", harness: client, model: a.model }); break;
         case "mentura_decisions": {
           r = await call({ venture: a.venture, route: "governance/decisions", action: "run", actor_id: a.agent_id });
           if (r.ok && a.render?.length) r.result = { ...r.result, decisions: r.result.decisions.filter((d) => a.render.includes(d.render)) };
@@ -75,7 +113,9 @@ export async function handle(msg) {
         }
         case "mentura_check": r = await call({ venture: a.venture, route: a.route, action: "check" }); break;
         case "mentura_template": r = await call({ route: a.route, action: "template" }); break;
-        case "mentura_run": r = await call({ venture: a.venture, route: a.route, action: "run", actor_id: a.agent_id, input: a.value !== undefined || a.as_is ? { ...(a.value !== undefined ? { value: a.value } : {}), ...(a.as_is ? { as_is: true } : {}) } : undefined }); break;
+        case "mentura_run": r = progress && a.route !== "system/overview" && a.route !== "system/robots"
+          ? await runStreaming({ venture: a.venture, route: a.route, input: { value: a.value, as_is: a.as_is }, actor_id: a.agent_id }, progress)
+          : await call({ venture: a.venture, route: a.route, action: "run", actor_id: a.agent_id, input: a.value !== undefined || a.as_is ? { ...(a.value !== undefined ? { value: a.value } : {}), ...(a.as_is ? { as_is: true } : {}) } : undefined }); break;
         default: return fail(-32602, `unknown tool ${params.name}`);
       }
       if (r.ok && r.needs_input) return reply({ content: [{ type: "text", text: `Ask the person before running. ${r.needs_input.ask}\n${JSON.stringify(r.needs_input, null, 2)}` }], isError: false });
@@ -115,7 +155,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
       let msg;
       try { msg = JSON.parse(line); } catch { process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } }) + "\n"); return; }
       let res;
-      try { res = await handle(msg); } catch (e) { res = { jsonrpc: "2.0", id: msg.id ?? null, error: { code: -32603, message: String(e.message ?? e) } }; }
+      try { res = await handle(msg, (n) => process.stdout.write(JSON.stringify(n) + "\n")); } catch (e) { res = { jsonrpc: "2.0", id: msg.id ?? null, error: { code: -32603, message: String(e.message ?? e) } }; }
       if (res) process.stdout.write(JSON.stringify(res) + "\n");
     });
   });

package/interface/package-routes.mjs

@@ -0,0 +1,196 @@
+// Package routes, route groups and slot defaults (Next.js translation L-6, P-17, P-36, P-37, and the
+// venture route for P-3). The router reaches these when a route is not in the route table, so the
+// table, generated from the data model, stays as it is.
+//
+//   <package>            a package's own route (validation, foundation, marketing; packages/<name> works
+//                        for every package, even one whose name is also a record route such as product).
+//                        read returns its records and their state: progress, what moves now, what waits,
+//                        and the drafts pending in it (its loading state, P-37). check runs its boundary
+//                        (E-5). view is the same as a page. layout is its group's and its own context.
+//   (<group>)            a route group (P-36): packages that share a layout, so they share context. The
+//                        framework defines (go-to-market) for marketing, relationships and customers; a
+//                        venture adds or changes groups in naive.config.json "groups", and may keep the
+//                        group's own AGENTS.md in a (<group>)/ folder at its root. Only the packages in a
+//                        group get its layout: the layout is opt-in.
+//   venture              the venture's own route: read is the manifest venture.json declares (P-3), check
+//                        runs every boundary (E-5).
+//   @packages            the system/overview slot: each package in use, and for a package with nothing in
+//                        it, its default: what to write first and where to start (P-17).
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+
+/** The framework's route groups (P-36). A venture's naive.config.json "groups" adds to or replaces these. */
+export const GROUPS = {
+  "go-to-market": { packages: ["marketing", "relationships", "customers"], context: "Who the venture sells to and how it reaches them. Marketing and sales share the ICP, the offer and the accounts, so they share one layout." },
+};
+
+export const packageNames = () => existsSync(join(repo, "packages")) ? readdirSync(join(repo, "packages")).filter((n) => existsSync(join(repo, "packages", n, "package.json"))) : [];
+export const packageDef = (n) => load(join(repo, "packages", n, "package.json"));
+
+/** The venture's route groups: the framework's, then its own from naive.config.json. */
+export function groupsOf(dir) {
+  const f = dir && join(dir, "naive.config.json");
+  const own = f && existsSync(f) ? load(f).groups ?? {} : {};
+  return { ...GROUPS, ...own };
+}
+
+/** The package a record type lives in: its core home first, else the data or folder package that declares it. */
+export function packageOfRecord(type) {
+  if (!type) return null;
+  const names = packageNames();
+  const core = names.find((n) => { const p = packageDef(n); return p.kind === "core" && [...(p.required ?? []), ...(p.optional ?? [])].includes(type); });
+  if (core) return core;
+  return names.find((n) => { const p = packageDef(n); return p.kind !== "handoff" && (p.records ?? []).includes(type); }) ?? null;
+}
+
+/** The group layout a package gets (P-36), or null when it is in no group. */
+export function groupLayout(pkg, dir) {
+  const gs = groupsOf(dir);
+  const id = Object.keys(gs).find((g) => (gs[g].packages ?? []).includes(pkg));
+  if (!id) return null;
+  const g = gs[id];
+  const agents = dir && existsSync(join(dir, `(${id})`, "AGENTS.md")) ? `(${id})/AGENTS.md` : null;
+  const shares = [...new Set(g.packages.filter((n) => packageNames().includes(n)).flatMap((n) => packageDef(n).refs ?? []))];
+  return { group: `(${id})`, packages: g.packages, context: g.context ?? null, shares, agents };
+}
+
+/** Which special route a name is: a package, a group or the venture. */
+export function special(route) {
+  if (route === "venture") return { kind: "venture" };
+  const g = route.match(/^\(([a-z0-9-]+)\)$/);
+  if (g) return { kind: "group", id: g[1] };
+  const name = route.startsWith("packages/") ? route.slice("packages/".length) : route;
+  return packageNames().includes(name) ? { kind: "package", name } : null;
+}
+
+/** The route of a record type: its item or single route, else its list route. */
+export const routeOfType = async (type) => {
+  const { routes } = await import("./router.mjs");
+  const rs = routes().filter((r) => r.record === type);
+  return (rs.find((r) => r.collection !== "list") ?? rs[0])?.route ?? null;
+};
+
+// The drafts waiting in a package's records (P-37): its pending state.
+async function pendingIn(dir, types, venture) {
+  const { recordOf } = await import("../schema/decisions.mjs");
+  const { entries } = await import("./provenance.mjs");
+  const d = join(dir, "_drafts");
+  if (!existsSync(d)) return [];
+  const log = entries(dir);
+  const out = [];
+  for (const f of readdirSync(d).filter((x) => x.endsWith(".draft"))) {
+    const file = f.slice(0, -".draft".length).replace(/__/g, "/");
+    const type = recordOf(file);
+    if (!types.includes(type)) continue;
+    const route = await routeOfType(type);
+    const id = route?.endsWith("[id]") ? file.split("/").at(-1).replace(/\.json$/, "") : null;
+    const concrete = id ? route.replace("[id]", id) : route;
+    out.push({ record: type, route: concrete, draft: `_drafts/${f}`, since: log.filter((e) => e.entity === `_drafts/${f}`).at(-1)?.at ?? null, accept: `mentura accept ${concrete} --venture ${venture}` });
+  }
+  return out;
+}
+
+/** A package's own route read (L-6, P-37): its records and their state, what moves now, what waits, what is pending. */
+export async function packageState(dir, name, venture) {
+  const def = packageDef(name);
+  const { packages } = await import("../schema/packages.mjs");
+  const all = packages(dir);
+  const p = [...all.core, ...all.handoff].find((x) => x.id === name);
+  if (p?.kind === "core") {
+    const records = await Promise.all(p.records.map(async (r) => ({ record: r.record, title: r.title, role: r.role, route: await routeOfType(r.record), status: r.status, moves: r.moves, ...(r.waits_on ? { waits_on: r.waits_on } : {}), files: r.files })));
+    const pending = await pendingIn(dir, p.records.filter((r) => r.role !== "reads").map((r) => r.record), venture);
+    return { package: name, kind: "core", title: p.title, purpose: p.purpose, function: def.function ?? def.department ?? null, fit: p.fit, in: p.in, state: p.state, progress: p.progress,
+      records, moves_now: records.filter((r) => r.moves === "now" && r.role !== "reads").map((r) => r.route), waits: records.filter((r) => r.moves === "waits").map((r) => ({ route: r.route, on: r.waits_on })),
+      loading: pending.length ? { drafts: pending, note: `${pending.length} draft${pending.length > 1 ? "s" : ""} waiting for a person to accept` } : null, unlocks: p.unlocks, missing: p.missing, to_review: p.to_review };
+  }
+  if (p?.kind === "handoff") return { package: name, kind: "handoff", title: p.title, for: p.for, from: p.from, fit: p.fit, in: p.in, state: p.state, progress: p.progress, waits_on: p.waits_on, unlocks: p.unlocks, loading: null };
+  // Data, folder and raw packages: never complete; their state is what they hold.
+  const { routes, glob } = await import("./router.mjs");
+  const { files } = await import("./router.mjs");
+  const here = files(dir);
+  const records = await Promise.all((def.records ?? []).map(async (t) => {
+    const r = routes().find((x) => x.record === t);
+    const held = r ? here.filter((f) => r.files.some((g) => glob(g).test(f))) : [];
+    return { record: t, route: await routeOfType(t), items: held.length, files: held };
+  }));
+  const pending = await pendingIn(dir, def.records ?? [], venture);
+  return { package: name, kind: def.kind, title: def.title, purpose: def.purpose, state: records.some((r) => r.items) ? "holding" : "empty", records, gates: def.gates ?? [],
+    loading: pending.length ? { drafts: pending, note: `${pending.length} draft${pending.length > 1 ? "s" : ""} waiting for a person to accept` } : null };
+}
+
+/** The overview's @packages slot (P-17): each package in use, and the default a package with nothing in it shows. */
+export async function packageSlots(dir, venture) {
+  const { manifest } = await import("../schema/structure.mjs");
+  const m = await manifest(dir);
+  const out = [];
+  for (const { name, known } of m.packages.list) {
+    if (!known) { out.push({ package: name, shows: "not a Naive package: check venture.json packages" }); continue; }
+    const s = await packageState(dir, name, venture);
+    const empty = s.kind === "core" ? s.records.filter((r) => r.role !== "reads").every((r) => r.status === "missing") : s.kind === "handoff" ? false : s.state === "empty";
+    if (!empty) { out.push({ package: name, title: s.title, state: s.state, progress: s.progress ?? null, moving: (s.moves_now ?? []).join(", ") || "none" }); continue; }
+    // The default: nothing written yet, and where to start.
+    const first = s.kind === "core" ? s.records.find((r) => r.role === "required" && r.moves === "now") ?? s.records.find((r) => r.role !== "reads") : s.records[0];
+    const route = first?.route ?? null;
+    const concrete = route?.endsWith("[id]") ? route.replace("[id]", "<id>") : route;
+    const { routes } = await import("./router.mjs");
+    const acts = routes().find((x) => x.route === route)?.actions ?? [];
+    const write = acts.includes("write") ? `mentura ${concrete} write --venture ${venture} --input <file>` : null;
+    const start = !concrete ? null : acts.includes("template") ? `mentura ${concrete} template${write ? `, then ${write}` : ""}` : write ?? `mentura ${concrete} layout --venture ${venture}`;
+    out.push({ package: name, title: s.title, default: true, shows: `${s.title}: nothing written yet`, start });
+  }
+  return out;
+}
+
+const pageOf = (s) => {
+  const lines = [`# ${s.title ?? s.package}`, "", s.purpose ?? "", ""];
+  if (s.state) lines.push(`State: ${s.state}${s.progress != null ? ` (${Math.round(s.progress * 100)}%)` : ""}.`, "");
+  if (s.loading) lines.push(`> ${s.loading.note}: ${s.loading.drafts.map((d) => `\`${d.accept}\``).join(", ")}`, "");
+  if (s.records?.length) {
+    const cols = s.kind === "core" ? ["route", "role", "status", "moves"] : ["route", "items"];
+    lines.push(`| ${cols.join(" | ")} |`, `| ${cols.map(() => "---").join(" | ")} |`, ...s.records.map((r) => `| ${cols.map((c) => String(r[c] ?? "")).join(" | ")} |`), "");
+  }
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+};
+
+/** Answers a call to a package, group or venture route; null when the route is none of them. */
+export async function specialCall({ venture, route, action, workspace }) {
+  const sp = special(route);
+  if (!sp) return null;
+  const { ventureDir } = await import("./router.mjs");
+  const actions = sp.kind === "group" ? ["read", "view", "layout"] : ["read", "view", "check", "layout"];
+  if (!actions.includes(action)) return { ok: false, error: `${route} has no action ${action} (it has ${actions.join(", ")})` };
+  const dir = venture ? ventureDir(venture, workspace) : null;
+  if (!dir && !(action === "layout" && sp.kind !== "venture")) return { ok: false, error: `no venture ${venture}` };
+  if (sp.kind === "venture") {
+    const { manifest } = await import("../schema/structure.mjs");
+    const { boundaries } = await import("./boundaries.mjs");
+    if (action === "check") { const b = await boundaries(dir); return { ok: b.ok, result: b }; }
+    const m = await manifest(dir);
+    if (action === "view") return { ok: true, result: `# ${m.identity.name}\n\nPhase: ${m.phase}. Packages: ${m.packages.list.map((p) => p.name).join(", ")}.\n\n| Function | Owner | Packages |\n| --- | --- | --- |\n${m.functions.map((f) => `| ${f.function} | ${f.owner ?? "nobody yet"} | ${f.packages.join(", ")} |`).join("\n")}\n` };
+    if (action === "layout") return { ok: true, result: { route: "venture", manifest: m } };
+    return { ok: true, result: m };
+  }
+  if (sp.kind === "group") {
+    const gs = groupsOf(dir);
+    const g = gs[sp.id];
+    if (!g) return { ok: false, error: `no route group (${sp.id}): the groups are ${Object.keys(gs).map((x) => `(${x})`).join(", ")}` };
+    const lay = groupLayout(g.packages[0], dir);
+    if (action === "layout" || !dir) return { ok: true, result: { ...lay, chain: lay.agents && dir ? [{ path: lay.agents, text: readFileSync(join(dir, lay.agents), "utf8") }] : [] } };
+    const states = [];
+    for (const n of g.packages.filter((x) => packageNames().includes(x))) states.push(await packageState(dir, n, venture));
+    const res = { group: `(${sp.id})`, context: g.context ?? null, packages: states.map((s) => ({ package: s.package, state: s.state, progress: s.progress ?? null, pending: s.loading?.drafts.length ?? 0 })) };
+    return { ok: true, result: action === "view" ? `# (${sp.id})\n\n${res.context ?? ""}\n\n${res.packages.map((p) => `- ${p.package}: ${p.state}${p.progress != null ? ` (${Math.round(p.progress * 100)}%)` : ""}${p.pending ? `, ${p.pending} pending` : ""}`).join("\n")}\n` : res };
+  }
+  const name = sp.name;
+  if (action === "layout") {
+    const def = packageDef(name);
+    return { ok: true, result: { route: name, package: { name, title: def.title, purpose: def.purpose, function: def.function ?? def.department ?? null, skill: def.skill?.path ?? null, gates: def.gates ?? [] }, group: groupLayout(name, dir) } };
+  }
+  if (action === "check") { const { boundaries } = await import("./boundaries.mjs"); const b = await boundaries(dir, { only: [name] }); return { ok: b.packages.every((p) => p.ok), result: b.packages[0] ?? { package: name, ok: true, note: "not in use by this venture" } }; }
+  const s = await packageState(dir, name, venture);
+  return action === "view" ? { ok: true, result: pageOf(s) } : { ok: true, result: s, ...(s.loading ? { pending_drafts: s.loading.drafts } : {}) };
+}