naive-framework 0.0.0-stage → 0.2.0

package/operations/marketing/site/plan.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// The sitemap planner (EE-064): site presence in reverse. Site presence reads a site and rates it;
+// the planner reads the venture's records and plans the site: which information is shown where,
+// how (the MDX component), when (while raising, hiring...) and for whom, with the reason for each.
+// The product decides the audience: the people a product is offered_to are the site's customers,
+// even when they are partners serving customers of their own (B2B2C). Their customer types set what
+// they look for (matrix.json customer_types); the venture's facts weigh the other audiences.
+//
+// Pages follow topics, not audiences (audience-based navigation tends to hurt usability, NN/g), with
+// one exception: an audience with content of its own (candidates, investors, contributors) gets its
+// own page, labelled for it. The plan is a marketing record (operations/marketing/sitemap.json). It
+// names, for each section, the internal record it draws on and the public variant a marketing agent
+// writes (operations/marketing/content/<page>/<item>.mdx), so nothing internal is published as is
+// (check-public.mjs). Planning the sitemap and designing the site are separate agents: this plan is
+// part of the marketing package handed to engineering, which builds the site (EE-065).
+//
+//   node plan.mjs <venture> [--raising] [--hiring] [--contributors] [--write] [--json]
+
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { customerNeeds, factsOf, MATRIX, needs, typesOf, weights } from "./presence.mjs";
+
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+export const SITEMAP = "operations/marketing/sitemap.json";
+export const CONTENT = "operations/marketing/content";
+const LABELS = MATRIX.page_labels;
+const RANK = Object.fromEntries(Object.entries(MATRIX.prominence).map(([k, v]) => [k, v.rank]));
+
+// Which internal record an item draws on, as a venture-relative file where one exists.
+const RECORD_FILE = { venture: "venture.json", icp: "purpose/icp.json", "validation-problem": "purpose/validation/problem.json", "validation-solution": "purpose/validation/solution.json",
+  "validation-pricing": "purpose/validation/pricing.json", "validation-go-to-market": "purpose/validation/go-to-market.json", "validation-team": "purpose/validation/team.json",
+  telos: "purpose/telos.json", alignment: "purpose/alignment.json", "team-plan": "operations/team-plan.json", "business-models": "purpose/business-models.json", "publication-policy": "governance/publication-policy.json", evidence: "evidence/" };
+
+/** The offerings: each product, what kind of offering it is, whom it is offered to and whom it serves through them. */
+export function offeringsOf(dir) {
+  const icp = existsSync(join(dir, "purpose/icp.json")) ? load(join(dir, "purpose/icp.json")) : { profiles: [] };
+  const profiles = new Map(icp.profiles.map((p) => [p.id, p]));
+  const primary = icp.profiles.find((p) => p.primary) ?? icp.profiles[0];
+  const pdir = join(dir, "products");
+  const products = existsSync(pdir) ? readdirSync(pdir).filter((f) => f.endsWith(".json")).map((f) => load(join(pdir, f))).filter((p) => !["retired", "archived", "idea"].includes(p.status)) : [];
+  return { profiles, products: products.map((p) => {
+    // Who it is offered to: the product says so; otherwise the profiles others are reached through
+    // (partners, in a B2B2C venture); otherwise the primary profile.
+    const channel = icp.profiles.filter((x) => icp.profiles.some((y) => y.reached_through?.includes(x.id)));
+    const to = p.offered_to ?? (channel.length ? channel.map((x) => x.id) : primary ? [primary.id] : []);
+    const serves = p.serves ?? icp.profiles.filter((y) => y.reached_through?.some((r) => to.includes(r))).map((y) => y.id);
+    return { id: p.id, name: p.name, offering: p.offering ?? "product", status: p.status ?? null, offered_to: to, serves, from: p.offered_to ? "product record" : channel.length ? "icp reached_through" : primary ? "primary ICP profile" : "nothing: no ICP yet" };
+  }) };
+}
+
+export function plan(dir, { flags = {}, answers = null } = {}) {
+  const venture = load(join(dir, "venture.json"));
+  const facts = factsOf(dir, flags);
+  const { profiles, products } = offeringsOf(dir);
+  // The site's customers are the people the products are offered to. Their customer types come from
+  // the profile when the founder set one, else from Jev's answers, else from the matrix's keywords.
+  const toIds = [...new Set(products.flatMap((p) => p.offered_to))];
+  const to = toIds.map((id) => profiles.get(id)).filter(Boolean);
+  const text = to.map((p) => [p.who, p.short, ...(p.traits ?? [])].filter(Boolean).join(". ")).join(" | ");
+  const set = to.map((p) => p.customer_type).filter((t) => MATRIX.customer_types.types[t]);
+  const types = set.length ? set.map((id) => ({ id, label: MATRIX.customer_types.types[id].label, p: 1 })) : typesOf({ text }, answers);
+  const partnerLed = to.some((p) => profiles.size && [...profiles.values()].some((y) => y.reached_through?.includes(p.id)));
+  const w = weights(facts), need = needs(w, customerNeeds(types));
+
+  const pages = new Map();
+  const page = (type, level, extra = {}) => {
+    const path = type === "home" ? "/" : `/${type}`;
+    if (!pages.has(path)) pages.set(path, { path, parent: type === "home" ? null : "/", label: LABELS[type] ?? type, type, level, sections: [], ...extra });
+    const pg = pages.get(path);
+    if (RANK[level] > RANK[pg.level]) pg.level = level;
+    return pg;
+  };
+  page("home", "home");
+  const omitted = [];
+  for (const [id, it] of Object.entries(MATRIX.items)) {
+    const n = need[id];
+    const top = n.evidence[0];
+    const when = Object.entries(MATRIX.when).find(([k]) => (MATRIX.audiences[top.audience].weight?.[k] != null))?.[1] ?? null;
+    if (n.need < MATRIX.prominence.linked.at_least) { omitted.push({ item: id, label: it.label, why: `${MATRIX.audiences[top.audience].label} are not a priority now (need ${n.need})`, ...(when ? { when: `show it ${when}` } : {}) }); continue; }
+    // Where: the home page when the need says so and the item belongs there; else its own page,
+    // in the navigation or the footer as the need says.
+    const own = it.belongs.find((b) => b !== "home");
+    const target = n.required === "home" && it.belongs.includes("home") ? page("home", "home") : page(own ?? "about", n.required === "home" ? "nav" : n.required === "anywhere" ? "linked" : n.required);
+    const record = it.record;
+    target.sections.push({ item: id, label: it.label, component: it.component, need: n.need, required: n.required, for: n.for.length ? n.for : [top.audience],
+      why: n.evidence.filter((e, k) => k === 0 || e.need >= 0.2).map((e) => `${MATRIX.audiences[e.audience].label}: ${e.why}`),
+      source: { record, file: RECORD_FILE[record] ?? null, exists: RECORD_FILE[record] ? existsSync(join(dir, RECORD_FILE[record])) : false },
+      variant: `${CONTENT}/${target.type}/${id}.mdx`, ...(when && !n.evidence.some((e) => e.audience !== top.audience && e.need >= MATRIX.prominence.linked.at_least) ? { when } : {}) });
+  }
+  // A product page for each product beyond the first, under /product, when there are several.
+  if (products.length > 1) for (const p of products) pages.set(`/product/${p.id}`, { path: `/product/${p.id}`, parent: pages.has("/product") ? "/product" : "/", label: p.name, type: "product", level: "anywhere", sections: [
+    { item: "how", label: `How ${p.name} works`, component: "HowItWorks", need: need.how.need, required: "anywhere", for: ["customers"], why: [`${p.offering} offered to ${p.offered_to.join(", ")}`], source: { record: "product", file: `products/${p.id}.json`, exists: true }, variant: `${CONTENT}/product/${p.id}.mdx` }] });
+  for (const pg of pages.values()) pg.sections.sort((a, b) => b.need - a.need);
+  const list = [...pages.values()].sort((a, b) => RANK[b.level] - RANK[a.level] || b.sections.reduce((s, x) => s + x.need, 0) - a.sections.reduce((s, x) => s + x.need, 0));
+  return { version: MATRIX.version, venture: venture.id, name: venture.name, phase: venture.phase, planned_at: new Date().toISOString().replace(/\.\d+Z$/, "Z"), planned_by: answers ? "jev" : "conventions", facts,
+    offerings: products, audience: { offered_to: to.map((p) => ({ id: p.id, who: p.who })), partner_led: partnerLed, types, weights: w,
+      note: partnerLed ? "The products are offered to partners who serve customers of their own: the partners are this site's customers, and their customers appear as who it ultimately serves." : "The site's customers are the profiles the products are offered to." },
+    pages: list, omitted,
+    handoff: { to: "engineering", note: "Part of the marketing package: engineering builds the site from this plan, the content variants and the brand; it does not decide what goes where (EE-065).", variants: list.flatMap((p) => p.sections.map((s) => s.variant)) } };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node plan.mjs <venture> [--raising] [--hiring] [--contributors] [--write] [--json]"); process.exit(2); }
+  const has = (n) => process.argv.includes(`--${n}`);
+  const r = plan(dir, { flags: Object.fromEntries(["raising", "hiring", "contributors"].filter(has).map((k) => [k, true])) });
+  if (has("write")) { mkdirSync(join(dir, dirname(SITEMAP)), { recursive: true }); writeFileSync(join(dir, SITEMAP), JSON.stringify(r, null, 2) + "\n"); }
+  if (has("json")) console.log(JSON.stringify(r, null, 2));
+  else {
+    console.log(`${r.name}: site planned for ${r.audience.offered_to.map((p) => p.id).join(", ") || "no ICP yet"} (${r.audience.types.map((t) => t.label).join(", ") || "customers in general"})${r.audience.partner_led ? "; partner-led" : ""}`);
+    for (const p of r.pages) {
+      console.log(`${p.path.padEnd(14)} ${p.level.padEnd(8)} ${p.label}`);
+      for (const s of p.sections) console.log(`    <${s.component}> ${s.label} (need ${s.need}${s.when ? `, ${s.when}` : ""}) from ${s.source.record}${s.source.exists ? "" : " (not written yet)"}`);
+    }
+    if (r.omitted.length) console.log(`Not now: ${r.omitted.map((o) => `${o.label}${o.when ? ` (${o.when})` : ""}`).join("; ")}`);
+  }
+}

package/operations/marketing/site/presence.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// Site presence (EE-062, EE-063): how present a venture's public records are on its marketing site,
+// weighed by who the site has to speak to now, with the evidence for every weight. The marketing
+// matrix (matrix.json) names the audiences, what each needs to learn and why, and the record each
+// piece of information comes from. What customers look for depends on who they are: Jev places the
+// venture's ICP into customer types (consumers, small-business owners, enterprise buyers, developers,
+// regulated professionals...), and each type says how much each item matters to it and why. The ICP
+// comes from the venture's ICP record, from the founder's own sentence, or, failing both, is inferred
+// from the home page and marked so. The venture's facts (raising, hiring, inviting contributors) weigh
+// the other audiences. Each item's need sets how prominent it must be: on the home page, in the
+// navigation, linked from the home page, or anywhere. The site is shown as its sitemap, each route
+// rated on the items that belong there, with the pages the venture's priorities call for and the site
+// lacks. Ours, version 0.x and unevaluated: the reasons are claims to test with real customers.
+//
+// Whether a page says something, and which customer types the ICP is, are judged by Jev when the
+// platform hands over its answers; otherwise by the matrix's keywords, which is rougher.
+//
+//   node presence.mjs request <site.json>   the Jev request
+//   node presence.mjs score <site.json> [--answers <jev.json>] [--venture <dir>] [--raising] [--hiring] [--contributors]
+//   node presence.mjs <venture> [--json]                                      the saved result
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+export const MATRIX = load(join(here, "matrix.json"));
+export const PRESENCE = "operations/marketing/site-presence.json";
+const LEVELS = Object.entries(MATRIX.prominence).sort(([, a], [, b]) => b.at_least - a.at_least);
+const TYPES = MATRIX.customer_types;
+const r2 = (x) => Math.round(x * 100) / 100;
+
+/** The venture's facts: flags the founder gave, else what its ICP record says about who it courts. */
+export function factsOf(dir, flags = {}) {
+  const f = { raising: false, hiring: false, contributors: false };
+  const icpFile = dir && join(dir, "purpose/icp.json");
+  if (icpFile && existsSync(icpFile)) {
+    const said = JSON.stringify(load(icpFile)).toLowerCase();
+    if (/investor|angel|\bvc\b/.test(said)) f.raising = true;
+    if (/candidate|hire|recruit/.test(said)) f.hiring = true;
+    if (/contributor|open source|volunteer/.test(said)) f.contributors = true;
+  }
+  for (const k of ["raising", "hiring", "contributors"]) if (flags[k] != null) f[k] = !!flags[k];
+  return f;
+}
+
+/** Who the customers are, and where that comes from: the founder's words, the ICP record, or the home page. */
+// Who the site is for, read from the site itself (2026-10-28): what it says outright ("for clinics",
+// "built for teams", "trusted by") and, failing that, what its opening implies. The founder does not
+// type it. The ICP the venture's records state is kept beside it, unscored, for a later clarity check
+// (stated versus seen).
+const SAYS = /\b(?:built for|made for|designed for|for (?:teams|companies|businesses|developers|founders|clinics|owners|people|creators|agencies|startups|enterprises|schools|families)|trusted by|helps?|serving|used by|loved by)\b[^.\n]{0,140}/gi;
+export function icpOf(dir, site) {
+  const ok = (site?.pages ?? []).filter((p) => !p.error);
+  const home = ok.find((p) => p.depth === 0);
+  const who = ok.filter((p) => /customer|solution|who|industr|use-case|about|for-/i.test(p.path));
+  const says = [...new Set([home, ...who].filter(Boolean).flatMap((p) => (p.text ?? "").match(SAYS) ?? []).map((x) => x.trim()))].slice(0, 8);
+  const opening = (home?.text ?? "").slice(0, 500);
+  const icpFile = dir && join(dir, "purpose/icp.json");
+  const stated = icpFile && existsSync(icpFile) ? (load(icpFile).profiles ?? []).map((p) => p.who ?? p.description ?? p.name).filter(Boolean) : null;
+  return { text: [says.join(" | "), opening].filter(Boolean).join(" || "), source: says.length ? "site" : "inferred", says,
+    cite: says.length ? `what the site says about who it is for (${says.length} phrase${says.length > 1 ? "s" : ""}), with the home page's opening` : "the home page's opening text (inferred: the site does not say outright who it is for)",
+    ...(stated?.length ? { stated } : {}) };
+}
+
+/** Which customer types the ICP is: Jev's answers when given, else the matrix's keywords. */
+export function typesOf(icp, answers) {
+  const out = Object.entries(TYPES.types).map(([id, t]) => ({ id, label: t.label,
+    p: answers ? r2(answers[`type:${id}`]?.noul ?? 0) : new RegExp(`\\b(?:${t.match})`, "i").test(icp.text) ? 1 : 0 }));
+  // Jev answers "mainly" conservatively: a type counts at the floor or above and within 0.6 of the strongest.
+  const top = Math.max(0, ...out.map((t) => t.p));
+  return out.filter((t) => t.p >= TYPES.floor && t.p >= 0.6 * top).sort((a, b) => b.p - a.p);
+}
+
+/** How much each item matters to the venture's customers, and why: the strongest of its customer types. */
+export function customerNeeds(types) {
+  const rows = types.length ? types : [{ id: "default", label: TYPES.default.label, p: 1 }];
+  return Object.fromEntries(Object.keys(TYPES.default.why).map((item) => {
+    const per = rows.map((t) => { const [imp, why] = (t.id !== "default" && TYPES.types[t.id].why[item]) || TYPES.default.why[item]; return { type: t.label, p: t.p, importance: imp, why }; });
+    // A customer who is several types at once (a clinic owner is a small-business owner and a regulated
+    // professional) needs what the most demanding of them needs.
+    return [item, { importance: Math.max(...per.map((x) => x.importance)), per }];
+  }));
+}
+
+// One reason per distinct claim: types that share the general reason are named together.
+const whyOf = (per) => [...per.reduce((m, x) => m.set(x.why, [...(m.get(x.why) ?? []), `${x.type} (${x.importance})`]), new Map())].map(([why, ts]) => `${ts.join(", ")}: ${why}`).join("; ");
+
+/** Each audience's weight from the facts: the ICP priority matrix in its simplest form. */
+export function weights(facts) {
+  return Object.fromEntries(Object.entries(MATRIX.audiences).map(([a, x]) => {
+    const w = typeof x.weight === "number" ? x.weight : (Object.entries(x.weight).find(([k]) => k !== "default" && facts[k])?.[1] ?? x.weight.default);
+    return [a, w];
+  }));
+}
+
+/** How much the site needs each item now, how prominent it must be, and the evidence: who needs it and why. */
+export function needs(w, cust = customerNeeds([])) {
+  return Object.fromEntries(Object.entries(MATRIX.items).map(([id, it]) => {
+    const evidence = Object.entries(it.audiences).map(([a, imp]) => {
+      const c = a === "customers" && cust[id];
+      const importance = c ? c.importance : imp;
+      return { audience: a, weight: w[a], importance, need: r2(w[a] * importance),
+        why: c ? whyOf(c.per) : it.why?.[a] ?? MATRIX.audiences[a].why, source: c ? "customer types" : "matrix" };
+    }).sort((x, y) => y.need - x.need);
+    const need = evidence[0]?.need ?? 0;
+    // An item whose place is its own page (pricing, careers) needs that page in the navigation at most.
+    let required = LEVELS.find(([, l]) => need >= l.at_least)[0];
+    if (required === "home" && !it.belongs.includes("home")) required = "nav";
+    return [id, { need, required, for: evidence.filter((e) => e.need >= 0.3).map((e) => e.audience), evidence }];
+  }));
+}
+
+export function pageType(p) {
+  if (p.depth === 0 || p.path === "/") return "home";
+  const s = `${p.path} ${p.title ?? ""} ${p.label ?? ""}`.toLowerCase();
+  return Object.entries(MATRIX.pages).find(([k, re]) => k !== "home" && new RegExp(re, "i").test(s))?.[0] ?? "other";
+}
+
+const pageText = (p) => `[${p.path}] ${p.title}\n${(p.text ?? "").slice(0, 3000)}`;
+
+/** The Jev request: does each page tell a visitor each item, and which customer types the ICP is. */
+export function request(site, icp = icpOf(null, site)) {
+  const pages = site.pages.filter((p) => !p.error);
+  const questions = {};
+  pages.forEach((p, i) => { for (const [id, it] of Object.entries(MATRIX.items))
+    questions[`has:${id}:p${i}`] = { type: "noul", instructions: `Does the web page in \`pages.p${i}\` tell a visitor ${it.question}? Judge what the page itself states, not what the venture might do.`,
+      criteria: { true: "Yes: the page states it", false: "No: the page does not state it" } }; });
+  for (const [id, t] of Object.entries(TYPES.types))
+    questions[`type:${id}`] = { type: "noul", instructions: `Are the customers described in \`icp\` mainly ${t.label.toLowerCase()} (${t.about})?`, criteria: { true: `Yes: they are ${t.label.toLowerCase()}`, false: "No" } };
+  return { state: { site: site.site, icp: icp.text, guidelines: "Each page is a venture's public marketing page. Answer from the page's own words only.", pages: Object.fromEntries(pages.map((p, i) => [`p${i}`, pageText(p)])) }, model: "jev-latest", questions };
+}
+
+// Without a judge: the matrix's keywords, matched in the page's text.
+function byKeywords(p, id, it) {
+  if (id === "what") return p.depth === 0 && (p.text ?? "").length > 80;
+  const t = `${p.path} ${p.title} ${p.text ?? ""}`.toLowerCase();
+  const hits = it.keywords.filter((k) => t.includes(k.toLowerCase())).length;
+  return hits >= (it.keywords.length >= 5 ? 2 : 1);
+}
+
+const norm = (path) => path.replace(/\/$/, "") || "/";
+
+/** The sitemap as a tree of routes, each rated on the items that belong there, with the missing pages. */
+export function sitemap(site, pages, items) {
+  const byPath = new Map();
+  const add = (path, x) => {
+    const k = norm(path);
+    if (!byPath.has(k)) byPath.set(k, { path: k, label: "", in_nav: false, read: false, ...x });
+    else Object.assign(byPath.get(k), Object.fromEntries(Object.entries(x).filter(([, v]) => v)));
+  };
+  add("/", { label: "Home", in_nav: true });
+  for (const l of site.links ?? []) add(l.path, { label: l.label, in_nav: l.in_nav });
+  for (const p of pages) add(p.path, { title: p.title, read: true, label: p.label || p.title });
+  const need = Object.fromEntries(items.map((x) => [x.id, x.need]));
+  const nodes = [...byPath.values()].map((n) => {
+    const segs = n.path.split("/").filter(Boolean);
+    let parent = n.path === "/" ? null : "/";
+    for (let k = segs.length - 1; k >= 1; k--) { const up = "/" + segs.slice(0, k).join("/"); if (byPath.has(up)) { parent = up; break; } }
+    const type = pageType({ depth: n.path === "/" ? 0 : 1, path: n.path, title: n.title, label: n.label });
+    const level = n.path === "/" ? "home" : segs.length === 1 && n.in_nav ? "nav" : segs.length === 1 ? "linked" : "anywhere";
+    const found = n.read ? items.filter((x) => x.found.some((f) => norm(f.path) === n.path)).map((x) => x.id) : [];
+    // What belongs on this route: on the home page, what must be there; elsewhere, the items whose place is this page type.
+    const expected = items.filter((x) => x.need >= 0.2 && (type === "home" ? x.required === "home" : MATRIX.items[x.id].belongs.includes(type))).map((x) => x.id);
+    const total = expected.reduce((a, id) => a + need[id], 0);
+    const rating = n.read && total ? Math.round((100 * expected.filter((id) => found.includes(id)).reduce((a, id) => a + need[id], 0)) / total) : null;
+    // A short name: the page's title before its site name, a short link text, or the path's last segment.
+    const seg = segs.at(-1)?.replace(/[-_]+/g, " ") ?? "Home";
+    const titled = n.title?.split(/\s[–|·-]\s/)[0]?.trim();
+    const name = n.path === "/" ? "Home" : titled && titled.length <= 32 ? titled : n.label && n.label.length <= 24 ? n.label : seg[0].toUpperCase() + seg.slice(1);
+    return { path: n.path, parent, label: name, type, level, read: n.read, rating, expected, found, missing: n.read ? expected.filter((id) => !found.includes(id)) : [] };
+  });
+  // Pages the venture's priorities call for that the site lacks: an item needed one click away or
+  // closer, missing everywhere, whose place is a page type the site has no route for.
+  const types = new Set(nodes.map((n) => n.type));
+  const ghosts = new Map();
+  for (const x of items) {
+    if (x.score > 0 || x.need < 0.4) continue;
+    const t = MATRIX.items[x.id].belongs.find((b) => b !== "home");
+    if (!t || types.has(t)) continue;
+    const g = ghosts.get(t) ?? { path: `/${t}`, parent: "/", label: `${t[0].toUpperCase()}${t.slice(1)} (suggested)`, type: t, level: x.required === "nav" ? "nav" : "linked", read: false, rating: 0, expected: [], found: [], missing: [], ghost: true };
+    g.expected.push(x.id); g.missing.push(x.id); ghosts.set(t, g);
+  }
+  return [...nodes, ...ghosts.values()];
+}
+
+export function score(site, { answers = null, facts = {}, venture = null, icp = null } = {}) {
+  icp ??= icpOf(null, site);
+  const types = typesOf(icp, answers);
+  const w = weights(facts), need = needs(w, customerNeeds(types));
+  const pages = site.pages.filter((p) => !p.error).map((p, i) => ({ ...p, i, type: pageType(p), level: p.depth === 0 ? "home" : p.in_nav ? "nav" : p.depth === 1 ? "linked" : "anywhere" }));
+  const rankOf = (l) => MATRIX.prominence[l]?.rank ?? 0;
+  const siteTypes = new Set(pages.map((p) => p.type));
+  const label = (a) => MATRIX.audiences[a].label.toLowerCase();
+  const list = (xs) => xs.length > 1 ? `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}` : xs[0];
+  const items = Object.entries(MATRIX.items).map(([id, it]) => {
+    const n = need[id];
+    const found = pages.filter((p) => answers ? (answers[`has:${id}:p${p.i}`]?.noul ?? 0) >= MATRIX.threshold : byKeywords(p, id, it));
+    const at = found.map((p) => p.level).sort((a, b) => rankOf(b) - rankOf(a))[0] ?? null;
+    const s = !at ? 0 : rankOf(at) >= rankOf(n.required) ? 1 : 0.5;
+    const who = list(n.for.map(label));
+    const req = MATRIX.prominence[n.required].means;
+    const page = it.belongs.find((b) => b !== "home");
+    const note = !at && !n.for.length ? `Not on the pages read, which is fine while ${list(Object.keys(it.audiences).map(label))} are not a priority.`
+      : !at ? `Not on the pages read. ${who[0].toUpperCase() + who.slice(1)} need it ${req}${page && !siteTypes.has(page) ? `; there is no ${page} page` : ""}.`
+      : s < 1 ? `Found on ${found.map((p) => p.path).slice(0, 2).join(", ")}, but ${who} need it ${req}.`
+      : n.need < 0.4 && at === "home" ? `On the home page, though ${list(Object.keys(it.audiences).map(label))} are not a priority now.`
+      : `Present ${MATRIX.prominence[at].means}.`;
+    return { id, label: it.label, record: it.record, need: n.need, required: n.required, for: n.for, at, score: s, found: found.map((p) => ({ path: p.path, type: p.type })), note,
+      evidence: n.evidence.filter((e, k) => k === 0 || e.need >= 0.1) };
+  });
+  const total = items.reduce((a, x) => a + x.need, 0);
+  const audiences = Object.fromEntries(Object.keys(MATRIX.audiences).map((a) => {
+    const xs = items.map((x) => [x, MATRIX.items[x.id].audiences[a] == null ? 0 : (need[x.id].evidence.find((e) => e.audience === a)?.importance ?? 0)]).filter(([, imp]) => imp);
+    const t = xs.reduce((s, [, imp]) => s + imp, 0);
+    return [a, { weight: w[a], score: t ? Math.round((100 * xs.reduce((s, [x, imp]) => s + imp * x.score, 0)) / t) : null }];
+  }));
+  const fix = items.filter((x) => x.score < 1 && x.need >= 0.4).sort((a, b) => b.need * (1 - b.score) - a.need * (1 - a.score)).slice(0, 3).map((x) => x.id);
+  return { version: MATRIX.version, site: site.site, venture, read_via: site.via, read_at: site.read_at, judged_by: answers ? "jev" : "keywords", facts,
+    icp: { ...icp, types: types.length ? types : [{ id: "default", label: TYPES.default.label, p: null }] },
+    score: Math.round((100 * items.reduce((a, x) => a + x.need * x.score, 0)) / total), audiences,
+    pages: pages.map((p) => ({ path: p.path, title: p.title, type: p.type, level: p.level })),
+    sitemap: sitemap(site, pages, items),
+    items: items.sort((a, b) => b.need * (1 - b.score) - a.need * (1 - a.score) || b.need - a.need),
+    fix_first: fix };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [a, b] = process.argv.slice(2);
+  const opt = (n) => { const i = process.argv.indexOf(`--${n}`); return i > 0 ? process.argv[i + 1] : null; };
+  const has = (n) => process.argv.includes(`--${n}`);
+  const siteOf = (p) => load(p === "-" ? 0 : p);
+  if (a === "request") { const site = siteOf(b); console.log(JSON.stringify(request(site, icpOf(opt("venture"), site)))); }
+  else if (a === "score") {
+    const dir = opt("venture"), site = siteOf(b);
+    const answers = opt("answers") ? (load(opt("answers")).answers ?? load(opt("answers"))) : null;
+    const facts = factsOf(dir, Object.fromEntries(["raising", "hiring", "contributors"].filter(has).map((k) => [k, true])));
+    const r = score(site, { answers, facts, icp: icpOf(dir, site), venture: dir ? load(join(dir, "venture.json")).id : null });
+    if (dir) { mkdirSync(join(dir, dirname(PRESENCE)), { recursive: true }); writeFileSync(join(dir, PRESENCE), JSON.stringify(r, null, 2) + "\n"); }
+    console.log(JSON.stringify(r, null, 2));
+  } else if (a && existsSync(join(a, "venture.json"))) {
+    if (!existsSync(join(a, PRESENCE))) { console.error(`${PRESENCE} does not exist yet: read the site first (node interface/harness/site.mjs <url> --venture <dir>)`); process.exit(1); }
+    const r = load(join(a, PRESENCE));
+    if (has("json")) console.log(JSON.stringify(r, null, 2));
+    else {
+      console.log(`${r.site}: site presence ${r.score}/100 (${r.judged_by}); customers: ${r.icp.types.map((t) => t.label).join(", ")} (ICP ${r.icp.source})`);
+      for (const n of r.sitemap) console.log(`  ${n.ghost ? "+" : " "} ${n.path.padEnd(28)} ${n.type.padEnd(9)} ${n.rating == null ? (n.read ? "-" : "not read") : n.rating}${n.missing.length ? `  missing: ${n.missing.join(", ")}` : ""}`);
+      for (const x of r.items) console.log(`${x.score === 1 ? "ok  " : x.score ? "low " : "miss"} ${x.label.padEnd(28)} ${x.note}`);
+    }
+  } else { console.error("usage: node presence.mjs request <site.json> | score <site.json> [--answers f] [--venture d] [--raising] [--hiring] [--contributors] | <venture> [--json]"); process.exit(2); }
+}

package/operations/references/references.json

@@ -0,0 +1,45 @@
+{
+  "layer": "operations",
+  "references": [
+    {
+      "id": "porter-1985-competitive-advantage",
+      "title": "Competitive Advantage: Creating and Sustaining Superior Performance",
+      "authors": [
+        "Michael E. Porter"
+      ],
+      "year": 1985,
+      "kind": "book",
+      "summary": "The value chain: primary activities (inbound logistics, operations, outbound logistics, marketing and sales, service) and support activities (firm infrastructure, human resource management, technology development, procurement).",
+      "url": "https://umbrex.com/resources/frameworks/organization-frameworks/porter-value-chain/",
+      "checked": "2026-10-28",
+      "informs": [
+        "field:department.value_chain",
+        "rule:department-grouping"
+      ],
+      "stance": {
+        "is": "adopted",
+        "why": "Each department is tagged primary or support by Porter's activities, and the optional grouping folders take those names; product development is filed as primary for a venture whose product is its work."
+      }
+    },
+    {
+      "id": "apqc-pcf-cross-industry",
+      "title": "APQC Process Classification Framework (PCF), cross-industry and industry-specific versions",
+      "authors": [
+        "APQC"
+      ],
+      "year": 2025,
+      "kind": "standard",
+      "summary": "A hierarchical taxonomy of business processes with 13 top-level categories (from Develop Vision and Strategy to Develop and Manage Business Capabilities), published cross-industry and in industry-specific versions.",
+      "url": "https://www.apqc.org/process-frameworks/industry-specific-process-frameworks",
+      "checked": "2026-10-28",
+      "informs": [
+        "field:venture.departments",
+        "field:department.apqc"
+      ],
+      "stance": {
+        "is": "adopted",
+        "why": "A venture's departments are the PCF's top-level categories under short ids; the catalog maps to them and cites them rather than copying the framework's text, which carries licence terms."
+      }
+    }
+  ]
+}

package/operations/skills/recruiting/SKILL.md

@@ -0,0 +1,32 @@
+---
+type: knowledge
+tags: [everything-ecosystem, skills, operations, recruiting, cofounder, hiring, investors]
+ai-model: claude-opus-5.5
+created: 2026-10-27T20:45:13Z
+source: hybrid
+name: recruiting
+description: >
+  Recruit the people the team plan says the venture needs now (cofounders,
+  hires, contractors, advisors, investors): write a brief that says what the
+  role is for and why a person, find and screen candidates with an agent's help,
+  and leave contact and the decision to a person (EE-029).
+  MANDATORY TRIGGERS: recruit, hire, hiring, find a cofounder, cofounder search,
+  job description, recruiting brief, contractor, find investors, advisor search.
+---
+
+# Recruiting
+
+Operations layer, governance tier (EE-029). Reads `operations/team-plan.json`; writes a brief per open role from `operations/templates/recruiting-brief.md` and the plan's `recruiting` entry.
+
+## Steps
+
+1. **Only roles needed now.** `check-team.mjs` lists them ("recruit now"). A role for a later phase waits.
+2. **Write the brief.** It says why a person is needed (the capability register), what they bring (the validation team record's gaps), and what they get (ownership and the option pool).
+3. **Agent's part:** search public profiles and communities, draft outreach, schedule, screen against the must-haves, and keep notes. The register lists sourcing candidates as `unknown`, so a person reviews every shortlist.
+4. **Person's part:** contact, interviews, the decision, and any offer. Offers of equity are `ownership-or-control`; offers of pay are `spend-money`. Both escalate.
+5. **Cofounders** go on to the governance kit's `cofounder-structure` skill before anyone commits. Investors go to `financing-and-investor-rights`.
+
+## Guardrails
+
+- Candidates' personal data stays out of public repositories.
+- No automated outreach in a person's name without their approval of the message (`public-commitment`).

package/operations/skills/team-design/SKILL.md

@@ -0,0 +1,36 @@
+---
+type: knowledge
+tags: [everything-ecosystem, skills, operations, team, agents, human-in-the-loop]
+ai-model: claude-opus-5.5
+created: 2026-10-27T20:45:13Z
+source: hybrid
+name: team-design
+description: >
+  Decide who the venture needs, agent or person, and when: which roles agents
+  fill, what authority each gets, where a human stays in the loop, and which
+  person roles to recruit. Records operations/team-plan.json against the agent
+  capability register and decision rights; schema/check-team.mjs checks it (EE-029).
+  MANDATORY TRIGGERS: team design, who do we need, hire or agent, can an agent
+  do this, human in the loop, delegate to agents, agent roles, org design,
+  what authority should the agent have, when do we need a person.
+---
+
+# Team design
+
+Operations layer, governance tier (EE-029). Writes `operations/team-plan.json`; `node schema/check-team.mjs <dir>` checks it.
+
+## Push agents to their limit, and find the loops that need a person
+
+1. **List the work** the current and next phase need, from the need-now score (`node schema/need-now.mjs <venture>`) and the validation team record's skills.
+2. **Look up each task** in the capability register (`evidence/capabilities/agent-capabilities.json`):
+   - `can`: an agent role does it.
+   - `can-with-review`: an agent does it; name the person who reviews (`human_loop`).
+   - `cannot` or `not-allowed`: an agent prepares; a person does or decides it.
+   - `unknown`: a person stays in the loop, and the task becomes an eval. Record the result in the register.
+   - Not in the register: add it as `unknown` with what you know.
+3. **Delegate authority** by decision class. An agent role may hold only classes that decision rights give to it, never an escalate class.
+4. **Open person roles** needed by the current phase are recruited now (`recruiting` skill). Roles for later phases stay `planned`, not recruited early.
+
+## Don't overbuild the team
+
+A role is added when the work exists, not when an org chart would have one. Re-run at each phase gate.

package/operations/skills/tool-selection/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: tool-selection
+description: "Help someone choose the tools for a layer (knowledge, operations, execution, evidence, governance, interface, purpose) by offering situation questions, only when they want help. Triggers: which tool should I use, Obsidian or Notion, what should we use for, compare tools, I'm not sure what to use, switching tools. Do not trigger when the person already names their tools."
+type: skill
+source: hybrid
+created: 2026-10-26T21:57:48Z
+ai-model: claude-opus-5.5
+tags: [skill, everything-ecosystem, tooling, tool-selection, typesafe]
+---
+
+# tool-selection
+
+Every layer has a tooling record (`<layer>/tooling/integrations.json`). This skill helps fill it when someone wants help deciding. It is opt-in: most people arrive knowing their tools, and for them the job is only to record what they use.
+
+## When to run
+
+- **Run** when the person asks for help choosing, compares tools, says they are unsure, or is about to switch.
+- **Offer once** (one line, easy to decline) when a choice looks hard to reverse: data would move into a proprietary format, many people or agents would depend on it, or it holds sensitive material.
+- **Do not run** when the person names their tools. Record them as `in-use` and move on. If they name a tool and ask for nothing else, do not second-guess it.
+
+## Principles for the questions
+
+The questions are for the person, to help them decide. They are not a form. Each layer's `tooling/questions.md` gives the dimensions that matter for that layer and example questions. The examples show the kind of question to ask; they are not a script, and the agent should ask others when the situation calls for it.
+
+1. **Ask about the situation, not the tools.** "Who edits this?" beats "Do you want real-time collaboration?". Tool features come in only when the presets are compared.
+2. **Ask only what can change the answer.** If every remaining candidate answers a question the same way, skip it. Stop when the ranking is clear.
+3. **Start from what exists.** Ask what they use today and what it would cost to move. Current tools are candidates like any other, and switching cost counts.
+4. **One narrow judgment per question.** Each question is a choice from a set (with "none of these"), a score on described levels, or a yes/no likelihood. That keeps answers scoreable and comparable.
+5. **Separate must-haves from preferences.** A must-have ("must stay on my machine", "agents must be able to write to it") rules a tool out. Preferences are weighted. Never let strong preferences buy back a failed must-have.
+6. **Weigh risk separately from fit.** For each leading candidate, ask how costly it is to be wrong and how hard to undo: lock-in, export quality, who else depends on it. A close fit on a hard-to-reverse choice is worth a pause; a close fit on an easy one is not.
+7. **More than one tool per layer is normal.** A vault for working notes and a repo for docs as code is a combination, not a failure to choose. Say which job each tool does.
+8. **Say what the person gave up.** The result names the tool, the reasons, the runner-up and what would make the runner-up the better pick.
+
+## How to score
+
+Recommended: **Jev plus a reasoning model**, each doing what it is good at.
+
+- The **reasoning model** reads the situation, picks which questions to ask (using the principles and the layer's dimensions), turns the person's answers into the typed judgments, checks must-haves, judges risk, and writes the explanation.
+- **Jev** (TypeSafe) scores the typed judgments for each candidate against the layer's presets and returns probabilities. It is fast, cheap and consistent, but gives no reasons and jitters by a few hundredths, so near-equal scores are reported as a tie band, not an order.
+- Without `TYPESAFE_API_KEY`, the reasoning model scores alone and says so. Sending project details to TypeSafe is something the person turns on.
+
+This follows MAD's scoring contract (MAD requirements 13 and 14: typed judgments, weights kept separate, must-holds checked apart from weighted sums).
+
+## Recording the result
+
+Update `<layer>/tooling/integrations.json`: chosen tools `in-use` with a `reason`, serious alternatives `candidate`, and ruled-out tools `rejected` with the must-have they failed. Credentials are named by environment variable only.

package/operations/templates/marketing-brand.md

@@ -0,0 +1,46 @@
+---
+type: template
+tags: [everything-ecosystem, operations, marketing, brand, template]
+ai-model: claude-opus-5.5
+created: 2026-10-29T06:04:07Z
+source: hybrid
+---
+
+# Template: brand
+
+Fills `<venture>/marketing/brand.json` (`schema/marketing-brand.schema.json`). The brand is the venture's global stylesheet: every agent's layout carries its voice and fonts, and `marketing/brand/tokens` renders it as design tokens and CSS for any interface. Check it with `mentura marketing/brand check`.
+
+```json
+{
+  "version": "0.1.0",
+  "venture": "<venture id>",
+  "name": "<the name as the brand writes it>",
+  "colors": { "accent": "#1d4e89", "ink": "#111111", "paper": "#ffffff" },
+  "typefaces": [
+    { "id": "inter", "family": "Inter", "source": "self-hosted", "license": "OFL-1.1", "files": ["public/fonts/inter.woff2"], "fallback": ["system-ui", "sans-serif"] }
+  ],
+  "fonts": { "body": "inter", "heading": "inter" },
+  "voice": {
+    "tone": ["plain", "warm"],
+    "rules": [{ "id": "no-jargon", "avoid": ["synergy", "leverage"], "use": "work with", "why": "our customers do not talk like this" }]
+  },
+  "marks": [
+    { "kind": "logo", "asset": "public/logo.svg" },
+    { "kind": "icon", "asset": "public/icon.svg" },
+    { "kind": "apple-icon", "asset": "public/apple-icon.png" },
+    { "kind": "favicon", "asset": "public/favicon.ico" }
+  ],
+  "design_systems": [{ "id": "radix", "name": "Radix Colors", "url": "https://www.radix-ui.com/colors", "version": "3.0.0", "license": "MIT", "uses": ["the blue scale"] }],
+  "scopes": [{ "for": "investors", "colors": { "accent": "#000000" }, "voice": { "tone": ["direct"] } }]
+}
+```
+
+## What each part means
+
+- **Colors** are hex values by token name.
+- **Typefaces** are defined once, each with its license. A self-hosted face names its files in `public/`, each registered in `public/assets.json` under the same license. A remote face fails the check: every reader's browser would call another host.
+- **Fonts** assign a typeface to a role everywhere. A scope can assign a different one under a route prefix.
+- **Voice** is the stylesheet for words: the tone, and phrases the venture never uses, with what to use instead.
+- **Marks** are the logo and icons. An apple-icon is a 180x180 PNG, an icon is square, a favicon is an ICO.
+- **Design systems** are linked, never copied in.
+- **Scopes** override the brand for a route prefix. The nearer scope wins.

package/operations/templates/public-assets.md

@@ -0,0 +1,39 @@
+---
+type: template
+tags: [everything-ecosystem, operations, marketing, assets, template]
+ai-model: claude-opus-5.5
+created: 2026-10-29T06:04:07Z
+source: hybrid
+---
+
+# Template: public assets
+
+Fills `<venture>/public/assets.json` (`schema/public-assets.schema.json`), the register of what the venture ships as it is. Do not write it by hand: `mentura assets add` registers a file and code fills its facts; `mentura assets fill` refreshes them. Check it with `mentura public/assets check`.
+
+```json
+{
+  "version": "0.1.0",
+  "remote_hosts": ["images.example.com"],
+  "assets": [
+    {
+      "path": "public/logo.svg",
+      "source": "Acme design",
+      "license": "owned",
+      "credit": "Acme",
+      "alt": { "text": "Acme wordmark", "by": "agent" },
+      "facts": { "type": "svg", "width": 200, "height": 60, "bytes": 812, "sha256": "<filled by code>" }
+    }
+  ],
+  "remote": [
+    { "id": "images-example-com-clinic", "url": "https://images.example.com/clinic.jpg", "license": "all-rights-reserved", "credit": "Ana Photo" }
+  ]
+}
+```
+
+## The rules the check holds
+
+- Every file in `public/` has an entry with a source, a license and a credit.
+- Facts are read from the file by code. An entry whose facts differ from the file fails.
+- An image needs alt text unless it is marked decorative. Alt text an agent wrote is pending until a person confirms it with `mentura assets confirm`.
+- A remote image is a link with a note in `raw/sources/<id>/`. A full copy in `public/` needs a license that allows one.
+- `remote_hosts` lists the hosts an agent may fetch from.