brainjar 0.3.976 → 0.3.977

package/brainjar.js

@@ -107,7 +107,7 @@ var CLI_VERSION, CACHE, DAY;
 var init_version_check = __esm({
   "packages/cli/src/version-check.ts"() {
     "use strict";
-    CLI_VERSION = "0.3.976";
+    CLI_VERSION = "0.3.977";
     CACHE = path.join(os.homedir(), ".brainjar", "version-check.json");
     DAY = 864e5;
   }
@@ -5926,7 +5926,9 @@ var init_config = __esm({
       // Launch pricing made permanent (official pricing page, checked 2026-08-18).
       "claude-sonnet-5": { input: 2, cachedInput: 0.2, output: 10 },
       "claude-haiku-4-5": { input: 1, cachedInput: 0.1, output: 5 },
-      "gpt-5.6-luna": { input: 0.2, cachedInput: 0.02, output: 1.2 }
+      "gpt-5.6-luna": { input: 0.2, cachedInput: 0.02, output: 1.2 },
+      // Released 2026-09-22 (official pricing page, checked 2026-09-25).
+      "gpt-6-luna": { input: 0.1, cachedInput: 0.01, output: 0.5 }
     };
     DEFAULT_TENANT_ID = "00000000-0000-0000-0000-000000000002";
     SECRETS = {
@@ -6083,7 +6085,7 @@ function validateFlowDiagram(d) {
       if (n2.evidence.length > 12)
         errs.push(`nodes: ${n2.id} too many evidence entries`);
       for (const ev of n2.evidence)
-        if (!short(ev, 200) || /[-]/.test(ev))
+        if (!short(ev, 200) || /[\x00-\x1f]/.test(ev))
           errs.push(`nodes: ${n2.id} evidence entry is not a short string`);
     }
     if (n2.description !== void 0 && !short(n2.description, 600))
@@ -13182,42 +13184,280 @@ function resolveSpecifier(fromFile, spec, known) {
     for (const probe of [
       clean,
       c,
-      ...SOURCE_EXTS.map((e) => clean + e),
-      ...SOURCE_EXTS.map((e) => `${clean}/index${e}`)
+      ...JS_EXTS.map((e) => clean + e),
+      ...JS_EXTS.map((e) => `${clean}/index${e}`)
     ]) {
       if (known.has(probe)) return probe;
     }
   }
   return null;
 }
+function resolveBySuffix(segments, exts, fromFile, idx, inits = []) {
+  if (segments.length === 0) return null;
+  const want = segments.join("/");
+  const last = segments[segments.length - 1];
+  const hits = [
+    ...(idx.byName.get(last) ?? []).filter(
+      (f) => exts.includes(ext(f)) && (stem(f) === want || stem(f).endsWith(`/${want}`))
+    ),
+    ...inits.flatMap(
+      (init2) => (idx.byName.get(stem(init2)) ?? []).filter(
+        (f) => f.endsWith(`/${want}/${init2}`) || f === `${want}/${init2}`
+      )
+    )
+  ];
+  if (hits.length === 0) return null;
+  return hits.sort(
+    (a, b) => nearness(b, fromFile) - nearness(a, fromFile) || a.length - b.length
+  )[0];
+}
+function pythonTargets(file, src, idx) {
+  const out = [];
+  const mod = (base, segs) => resolveBySuffix([...base, ...segs], [".py"], file, idx, ["__init__.py"]);
+  for (const m of src.matchAll(PY_FROM)) {
+    const dots = m[1].length;
+    const segs = m[2] ? m[2].split(".") : [];
+    const names = m[3].split(",").map((n2) => n2.trim().split(/\s+/)[0]);
+    if (dots > 0) {
+      let dir = path4.posix.dirname(file);
+      for (let i = 1; i < dots; i++) dir = path4.posix.dirname(dir);
+      const base = dir === "." ? [] : dir.split("/");
+      const exact = (s) => {
+        const p = [...base, ...s].join("/");
+        return idx.known.has(`${p}.py`) ? `${p}.py` : idx.known.has(`${p}/__init__.py`) ? `${p}/__init__.py` : null;
+      };
+      const target = segs.length ? exact(segs) : null;
+      if (target) out.push(target);
+      for (const n2 of names) {
+        const sub = exact([...segs, n2]);
+        if (sub) out.push(sub);
+      }
+    } else if (segs.length) {
+      const sub = names.map((n2) => mod([], [...segs, n2])).filter(Boolean);
+      const target = resolveLongest(segs, (s) => mod([], s));
+      out.push(...sub, ...target ? [target] : []);
+    }
+  }
+  for (const m of src.matchAll(PY_IMPORT))
+    for (const spec of m[1].split(",")) {
+      const target = resolveLongest(spec.trim().split("."), (s) => mod([], s));
+      if (target) out.push(target);
+    }
+  return out;
+}
+function rustTargets(file, src, idx) {
+  const out = [];
+  const dir = path4.posix.dirname(file);
+  const base = path4.posix.basename(file, ".rs");
+  const own = ["lib", "main", "mod"].includes(base) ? dir : `${dir}/${base}`;
+  const crateSrc = [...idx.crates.values()].filter((s) => file.startsWith(`${s}/`)).sort((a, b) => b.length - a.length)[0];
+  const inDir = (d, segs) => {
+    const p = [d, ...segs].join("/");
+    return idx.known.has(`${p}.rs`) ? `${p}.rs` : idx.known.has(`${p}/mod.rs`) ? `${p}/mod.rs` : null;
+  };
+  for (const m of src.matchAll(RS_MOD)) {
+    const hit = inDir(own, [m[1]]);
+    if (hit) out.push(hit);
+  }
+  for (const m of src.matchAll(RS_USE))
+    for (const use of expandUse(m[1])) {
+      const [head, ...rest] = use.replace(/^::/, "").split("::");
+      let root;
+      if (head === "crate") root = crateSrc;
+      else if (head === "self") root = own;
+      else if (head === "super")
+        root = ["lib", "main", "mod"].includes(base) ? path4.posix.dirname(dir) : dir;
+      else if (head && idx.crates.has(head)) {
+        root = idx.crates.get(head);
+        if (rest.length === 0) {
+          const lib = `${root}/lib.rs`;
+          if (idx.known.has(lib)) out.push(lib);
+          continue;
+        }
+      }
+      if (!root) continue;
+      const hit = resolveLongest(rest, (s) => inDir(root, s));
+      if (hit) out.push(hit);
+      else if (head !== "self" && head !== "super") {
+        const lib = `${root}/lib.rs`;
+        if (idx.known.has(lib)) out.push(lib);
+      }
+    }
+  return out;
+}
+function goTargets(file, src, idx) {
+  const specs = [
+    ...[...src.matchAll(GO_BLOCK)].flatMap(
+      (m) => [...m[1].matchAll(/"([^"]+)"/g)].map((x) => x[1])
+    ),
+    ...[...src.matchAll(GO_ONE)].map((m) => m[1])
+  ];
+  const out = [];
+  for (const spec of specs)
+    for (const [mod, dir] of idx.goModules) {
+      if (spec !== mod && !spec.startsWith(`${mod}/`)) continue;
+      const pkgDir = [dir === "." ? "" : dir, spec.slice(mod.length + 1)].filter(Boolean).join("/");
+      const rep = (idx.byDir.get(pkgDir) ?? []).find(
+        (f) => f.endsWith(".go") && !f.endsWith("_test.go")
+      );
+      if (rep) out.push(rep);
+    }
+  return out;
+}
+function swiftTargets(src, idx) {
+  const out = [];
+  for (const m of src.matchAll(
+    /^[ \t]*(?:@\w+[ \t]+)*import[ \t]+(?:\w+[ \t]+)?(\w+)/gm
+  )) {
+    for (const [dir, files] of idx.byDir) {
+      if (!(dir === `Sources/${m[1]}` || dir.endsWith(`/Sources/${m[1]}`) || dir.includes(`/Sources/${m[1]}/`)))
+        continue;
+      const rep = files.find((f) => f.endsWith(".swift") || f.endsWith(".h"));
+      if (rep) {
+        out.push(rep);
+        break;
+      }
+    }
+  }
+  return out;
+}
+function jvmTargets(file, src, idx) {
+  const out = [];
+  for (const m of src.matchAll(
+    /^[ \t]*import[ \t]+(?:static[ \t]+)?([\w.]+)/gm
+  )) {
+    const hit = resolveLongest(
+      m[1].split("."),
+      (s) => resolveBySuffix(s, [".java", ".kt"], file, idx)
+    );
+    if (hit) out.push(hit);
+  }
+  return out;
+}
+function cTargets(file, src, idx) {
+  const out = [];
+  for (const m of src.matchAll(
+    /^[ \t]*#[ \t]*(?:include|import)[ \t]*"([^"]+)"/gm
+  )) {
+    const rel = path4.posix.normalize(
+      path4.posix.join(path4.posix.dirname(file), m[1])
+    );
+    if (idx.known.has(rel)) out.push(rel);
+    else {
+      const hit = resolveBySuffix(
+        stem(m[1]).split("/"),
+        [ext(m[1])],
+        file,
+        idx
+      );
+      if (hit) out.push(hit);
+    }
+  }
+  return out;
+}
 async function scanStructure(root) {
   const entries = await readdir(root, { recursive: true, withFileTypes: true });
   const files = [];
+  const cargo = [];
+  const gomod = [];
   for (const e of entries) {
     if (!e.isFile()) continue;
     const parent = e.parentPath ?? e.path ?? root;
     const rel = toPosix(path4.relative(root, path4.join(parent, e.name)));
     if (rel.split("/").some((seg) => SKIP_DIRS.has(seg))) continue;
-    if (SOURCE_EXTS.some((ext) => rel.endsWith(ext))) files.push(rel);
+    if (SOURCE_EXTS.some((x) => rel.endsWith(x))) files.push(rel);
+    else if (e.name === "Cargo.toml") cargo.push(rel);
+    else if (e.name === "go.mod") gomod.push(rel);
+  }
+  const read = (f) => readFile(path4.join(root, f), "utf8");
+  const idx = {
+    known: new Set(files),
+    byName: /* @__PURE__ */ new Map(),
+    byDir: /* @__PURE__ */ new Map(),
+    crates: /* @__PURE__ */ new Map(),
+    goModules: /* @__PURE__ */ new Map()
+  };
+  for (const f of [...files].sort()) {
+    const name = path4.posix.basename(stem(f));
+    idx.byName.set(name, [...idx.byName.get(name) ?? [], f]);
+    const d = path4.posix.dirname(f);
+    idx.byDir.set(d, [...idx.byDir.get(d) ?? [], f]);
+  }
+  for (const c of cargo) {
+    const pkg = (await read(c)).match(
+      /\[package\][^[]*?\bname\s*=\s*"([^"]+)"/
+    );
+    const dir = path4.posix.dirname(c);
+    if (pkg)
+      idx.crates.set(
+        pkg[1].replace(/-/g, "_"),
+        `${dir === "." ? "" : `${dir}/`}src`.replace(/^\//, "")
+      );
   }
-  const known = new Set(files);
+  for (const g of gomod) {
+    const mod = (await read(g)).match(/^module\s+(\S+)/m);
+    if (mod) idx.goModules.set(mod[1], path4.posix.dirname(g));
+  }
+  const exported = /* @__PURE__ */ new Map();
+  for (const f of files.filter((x) => x.endsWith(".rs")))
+    for (const m of (await read(f)).matchAll(RS_EXPORT))
+      if (!exported.has(m[1])) exported.set(m[1], f);
+  const names = [...exported.keys()].slice(0, 2e3);
+  const callRe = names.length ? new RegExp(
+    `\\b(${names.map((n2) => n2.replace(/[^\w]/g, "")).join("|")})\\s*\\(`,
+    "g"
+  ) : null;
+  const seen = /* @__PURE__ */ new Set();
   const edges = [];
+  const add = (from, to) => {
+    if (!to || to === from || !idx.known.has(to)) return;
+    const k = JSON.stringify([from, to]);
+    if (seen.has(k)) return;
+    seen.add(k);
+    edges.push({ from, to });
+  };
   for (const file of files) {
-    const source = await readFile(path4.join(root, file), "utf8");
-    for (const spec of extractImports(source)) {
-      const to = resolveSpecifier(file, spec, known);
-      if (to && to !== file) edges.push({ from: file, to });
-    }
+    const src = await read(file);
+    const x = ext(file);
+    if (JS_EXTS.includes(x))
+      for (const spec of extractImports(src))
+        add(file, resolveSpecifier(file, spec, idx.known));
+    else if (x === ".py")
+      for (const t of pythonTargets(file, src, idx)) add(file, t);
+    else if (x === ".rs")
+      for (const t of rustTargets(file, src, idx)) add(file, t);
+    else if (x === ".go")
+      for (const t of goTargets(file, src, idx)) add(file, t);
+    else if (x === ".swift")
+      for (const t of swiftTargets(src, idx)) add(file, t);
+    else if (x === ".java" || x === ".kt")
+      for (const t of jvmTargets(file, src, idx)) add(file, t);
+    else if (C_EXTS.includes(x))
+      for (const t of cTargets(file, src, idx)) add(file, t);
+    if (callRe && x !== ".rs")
+      for (const m of src.matchAll(callRe))
+        add(file, exported.get(m[1]) ?? null);
   }
   return { modules: files.sort(), edges };
 }
-var SOURCE_EXTS, SKIP_DIRS, IMPORT_RE, toPosix;
+var JS_EXTS, C_EXTS, SOURCE_EXTS, SKIP_DIRS, IMPORT_RE, toPosix, ext, stem, nearness, resolveLongest, PY_FROM, PY_IMPORT, RS_MOD, RS_USE, expandUse, GO_BLOCK, GO_ONE, RS_EXPORT;
 var init_structure = __esm({
   "packages/ingest/src/structure.ts"() {
     "use strict";
     init_src2();
     init_entities();
-    SOURCE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+    JS_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+    C_EXTS = [".c", ".h", ".cc", ".cpp", ".hpp", ".m", ".mm"];
+    SOURCE_EXTS = [
+      ...JS_EXTS,
+      ".py",
+      ".rs",
+      ".go",
+      ".swift",
+      ".java",
+      ".kt",
+      ...C_EXTS
+    ];
     SKIP_DIRS = /* @__PURE__ */ new Set([
       "node_modules",
       ".git",
@@ -13227,10 +13467,51 @@ var init_structure = __esm({
       ".next",
       "dist",
       "build",
-      "coverage"
+      "coverage",
+      // Build output and dependency caches of the other languages.
+      "target",
+      ".build",
+      "__pycache__",
+      ".venv",
+      "venv",
+      "vendor",
+      "Pods",
+      "DerivedData",
+      ".gradle"
     ]);
     IMPORT_RE = /(?:import|export)\s+[^'"]*?from\s+['"]([^'"]+)['"]|import\s*\(\s*['"]([^'"]+)['"]\s*\)|require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
     toPosix = (p) => p.split(path4.sep).join("/");
+    ext = (f) => path4.posix.extname(f);
+    stem = (f) => f.slice(0, f.length - ext(f).length);
+    nearness = (a, b) => {
+      const x = a.split("/");
+      const y = b.split("/");
+      let i = 0;
+      while (i < x.length && i < y.length && x[i] === y[i]) i++;
+      return i;
+    };
+    resolveLongest = (segments, resolve) => {
+      for (let n2 = segments.length; n2 > 0; n2--) {
+        const hit = resolve(segments.slice(0, n2));
+        if (hit) return hit;
+      }
+      return null;
+    };
+    PY_FROM = /^[ \t]*from[ \t]+(\.*)([\w.]*)[ \t]+import[ \t]+\(?([^\n#)]+)/gm;
+    PY_IMPORT = /^[ \t]*import[ \t]+([\w.]+(?:[ \t]*,[ \t]*[\w.]+)*)/gm;
+    RS_MOD = /^[ \t]*(?:pub(?:\([^)]*\))?[ \t]+)?mod[ \t]+(\w+)[ \t]*;/gm;
+    RS_USE = /\buse[ \t]+([^;]+);/g;
+    expandUse = (use) => {
+      const clean = use.replace(/\s+/g, "");
+      const brace = clean.match(/^(.*?)::\{(.*)\}$/);
+      if (!brace) return [clean.replace(/::\*$/, "")];
+      return brace[2].split(",").filter(Boolean).map(
+        (part) => part === "self" ? brace[1] : `${brace[1]}::${part.replace(/::\*$/, "")}`
+      );
+    };
+    GO_BLOCK = /\bimport[ \t]*\(([\s\S]*?)\)/g;
+    GO_ONE = /\bimport[ \t]+(?:[\w.]+[ \t]+)?"([^"]+)"/g;
+    RS_EXPORT = /extern[ \t]+"C"[ \t]+fn[ \t]+([A-Za-z_]\w{2,})/g;
   }
 });
 
@@ -15456,6 +15737,45 @@ function aiState(m) {
     aiAttempts: typeof m?.aiAttempts === "number" ? m.aiAttempts : 0
   };
 }
+function aiFacts(kind, m) {
+  if (!m) return null;
+  if (kind === "feature") {
+    const f = m;
+    return JSON.stringify([
+      f.title,
+      f.what,
+      f.behavior ?? null,
+      f.config ?? [],
+      f.locations ?? [],
+      f.why ?? null
+    ]);
+  }
+  if (kind === "entry") {
+    const e = m;
+    return JSON.stringify([
+      e.brainName,
+      e.description ?? null,
+      (e.architecture?.groups ?? []).map((g) => g.name),
+      // Tuples, never objects: a stored model comes back from jsonb with its keys reordered.
+      (e.architecture?.edges ?? []).map((x) => [x.from, x.to]),
+      (e.features ?? []).map((f) => [f.slug, f.title, f.area, f.what])
+    ]);
+  }
+  return null;
+}
+function withStoredAi(model, stored) {
+  const s = stored;
+  const fresh = model;
+  return {
+    ...model,
+    ...s.presentation ? { presentation: s.presentation } : {},
+    body: s.body ?? null,
+    docTitle: s.docTitle ?? null,
+    category: s.category ?? null,
+    ...!fresh.flow && s.flow ? { flow: s.flow } : {},
+    ...!fresh.flowDiagram && s.flowDiagram ? { flowDiagram: s.flowDiagram } : {}
+  };
+}
 function aiComplete(kind, m) {
   if (!m) return false;
   const text = (v) => typeof v === "string" && v.trim().length > 0;
@@ -15471,6 +15791,28 @@ function aiComplete(kind, m) {
       return true;
   }
 }
+function pagePrompt(input) {
+  const { categories, flowDiagramTitle, hasFlow, sharedLines = [] } = input;
+  return [
+    "Categories (pick exactly one key):",
+    ...categories.length ? categories.map((c) => `- ${c.key}: ${c.name} (${c.description})`) : ["- general: General (everything)"],
+    "",
+    "Available diagrams (the only allowed flow block sources):",
+    ...flowDiagramTitle ? [
+      `- flowDiagram: "${flowDiagramTitle}" (the feature's runtime flow, lanes and stations)`
+    ] : [],
+    ...hasFlow && !flowDiagramTitle ? ["- flow: the feature's runtime steps as a simple chain"] : [],
+    ...!flowDiagramTitle && !hasFlow ? ["- (none)"] : [],
+    "",
+    ...sharedLines.length ? [
+      "Documented elsewhere for the same endpoint (proven facts; reuse them, link the page):",
+      ...sharedLines,
+      ""
+    ] : [],
+    "Fact sheet:",
+    input.factSheet
+  ].join("\n");
+}
 function parseDocPage(raw, categoryKeys, ctx) {
   const bad = (error2) => ({ page: null, error: error2, dropped: [] });
   const match = raw.match(/\{[\s\S]*\}/);
@@ -15614,16 +15956,32 @@ function parseArchNotes(raw, groups) {
   };
 }
 function archFlowsInput(model) {
+  const modules = (model.raw?.modules ?? []).filter(
+    (m) => !/\.test\.[a-z]+$/.test(m)
+  );
+  const cited = new Set(model.features.flatMap((f) => f.locations));
   const files = /* @__PURE__ */ new Map();
-  for (const m of model.raw?.modules ?? []) {
-    if (/\.test\.[a-z]+$/.test(m)) continue;
+  for (const m of [
+    ...modules.filter((m2) => cited.has(m2)),
+    ...modules.filter((m2) => !cited.has(m2))
+  ]) {
     const g = moduleGroup(m);
     const list = files.get(g) ?? [];
-    if (list.length < 8) list.push(m);
+    if (list.length < 12) list.push(m);
     files.set(g, list);
   }
+  const spanning = model.features.flatMap((f) => {
+    const groups = [...new Set(f.locations.map(moduleGroup))];
+    return groups.length >= 2 ? [`- ${f.title}: ${groups.join(", ")}`] : [];
+  });
   return [
     archNotesInput(model),
+    ...spanning.length ? [
+      "",
+      "## Features spanning groups (each feature's code lives in all of these groups)",
+      "",
+      ...spanning
+    ] : [],
     "",
     "## Files (the ONLY paths you may cite as evidence, copied exactly)",
     ...[...files.entries()].flatMap(([g, list]) => [
@@ -15888,45 +16246,69 @@ async function generateDokuInner(brainId, opts = {}) {
       }
       continue;
     }
-    const sameFacts = stored !== void 0 && state.factHash === factHash;
+    const facts = aiFacts(page.kind, page.model);
+    const sameFacts = stored !== void 0 && (facts !== null ? aiFacts(page.kind, stored) === facts : state.factHash === factHash);
     let markdown = page.markdown;
     let model = page.model;
     let icon = null;
     let ok2 = !required;
-    if (opts.llm && page.polishable && page.kind === "architecture") {
-      try {
-        const { notes } = parseArchNotes(
-          await opts.llm.complete({
-            system: ARCH_SYSTEM,
-            prompt: archNotesInput(doku),
-            maxTokens: 800
-          }),
-          doku.architecture.groups.map((g) => g.name)
-        );
-        if (notes) {
-          model = { ...model, narrative: notes.narrative, roles: notes.roles };
-          polished = true;
-          ok2 = true;
+    if (page.polishable && page.kind === "architecture") {
+      const inputs = {
+        notes: sha1(archNotesInput(doku)),
+        flows: sha1(archFlowsInput(doku))
+      };
+      const s = stored ?? {};
+      let notesFor;
+      let flowsFor;
+      if (typeof s.narrative === "string" && s.aiInputs?.notes === inputs.notes) {
+        model = { ...model, narrative: s.narrative, roles: s.roles };
+        notesFor = inputs.notes;
+        ok2 = true;
+      } else if (opts.llm) {
+        try {
+          const { notes } = parseArchNotes(
+            await opts.llm.complete({
+              system: ARCH_SYSTEM,
+              prompt: archNotesInput(doku),
+              maxTokens: 800
+            }),
+            doku.architecture.groups.map((g) => g.name)
+          );
+          if (notes) {
+            model = {
+              ...model,
+              narrative: notes.narrative,
+              roles: notes.roles
+            };
+            notesFor = inputs.notes;
+            polished = true;
+            ok2 = true;
+          }
+        } catch {
         }
-      } catch {
       }
-      try {
-        const { flows } = parseArchFlows(
-          await opts.llm.complete({
-            system: ARCH_FLOWS_SYSTEM,
-            prompt: archFlowsInput(doku),
-            maxTokens: 4500
-          }),
-          new Set(doku.raw?.modules ?? [])
-        );
-        if (flows.length > 0) {
-          model = { ...model, flows };
-          polished = true;
+      if (Array.isArray(s.flows) && s.flows.length > 0 && s.aiInputs?.flows === inputs.flows) {
+        model = { ...model, flows: s.flows };
+        flowsFor = inputs.flows;
+      } else if (opts.llm) {
+        try {
+          const { flows } = parseArchFlows(
+            await opts.llm.complete({
+              system: ARCH_FLOWS_SYSTEM,
+              prompt: archFlowsInput(doku),
+              maxTokens: 4500
+            }),
+            new Set(doku.raw?.modules ?? [])
+          );
+          if (flows.length > 0) {
+            model = { ...model, flows };
+            flowsFor = inputs.flows;
+            polished = true;
+          }
+        } catch {
         }
-      } catch {
       }
       if (!ok2 && sameFacts) {
-        const s = stored;
         const kept = model;
         model = {
           ...model,
@@ -15934,6 +16316,14 @@ async function generateDokuInner(brainId, opts = {}) {
           ...!kept.flows && Array.isArray(s.flows) ? { flows: s.flows } : {}
         };
       }
+      const present = model;
+      model = {
+        ...model,
+        aiInputs: {
+          ...typeof present.narrative === "string" ? { notes: notesFor ?? s.aiInputs?.notes } : {},
+          ...Array.isArray(present.flows) ? { flows: flowsFor ?? s.aiInputs?.flows } : {}
+        }
+      };
       const arch = model;
       if (arch.narrative || arch.flows?.length)
         markdown = renderArchitecturePage(doku, {
@@ -15942,7 +16332,11 @@ async function generateDokuInner(brainId, opts = {}) {
         });
     } else if (page.kind === "entry") {
       model = { ...page.model, categories };
-      if (opts.llm && page.polishable) {
+      const s = stored;
+      if (sameFacts && typeof s?.narrative === "string" && s.narrative.trim()) {
+        model = { ...model, narrative: s.narrative };
+        ok2 = true;
+      } else if (opts.llm && page.polishable) {
         try {
           const narrative2 = (await opts.llm.complete({
             system: ENTRY_NARRATIVE_SYSTEM,
@@ -15956,15 +16350,16 @@ async function generateDokuInner(brainId, opts = {}) {
           }
         } catch {
         }
-        if (!ok2 && sameFacts) {
-          const s = stored;
-          if (typeof s.narrative === "string" && s.narrative.trim())
-            model = { ...model, narrative: s.narrative };
-        }
       }
       const narrative = model.narrative;
       if (narrative)
         markdown = renderEntryPage(doku, "brainjar-doku/", narrative);
+    } else if (page.kind === "feature" && sameFacts && !storedCollisions.has(page.slug) && aiComplete("feature", stored)) {
+      const f = withStoredAi(page.model, stored);
+      model = f;
+      markdown = renderFeaturePage(f);
+      if (f.docTitle) page.title = f.docTitle;
+      ok2 = true;
     } else if (opts.llm && page.polishable) {
       try {
         const { flow } = parseFlow(
@@ -16018,25 +16413,13 @@ async function generateDokuInner(brainId, opts = {}) {
           hasFlowDiagram: Boolean(diagrams.flowDiagram),
           hasFlow: Boolean(diagrams.flow)
         };
-        const prompt = [
-          "Categories (pick exactly one key):",
-          ...categories.length ? categories.map((c) => `- ${c.key}: ${c.name} (${c.description})`) : ["- general: General (everything)"],
-          "",
-          "Available diagrams (the only allowed flow block sources):",
-          ...ctx.hasFlowDiagram ? [
-            `- flowDiagram: "${diagrams.flowDiagram.title}" (the feature's runtime flow, lanes and stations)`
-          ] : [],
-          ...ctx.hasFlow && !ctx.hasFlowDiagram ? ["- flow: the feature's runtime steps as a simple chain"] : [],
-          ...!ctx.hasFlowDiagram && !ctx.hasFlow ? ["- (none)"] : [],
-          "",
-          ...sharedLines.length ? [
-            "Documented elsewhere for the same endpoint (proven facts; reuse them, link the page):",
-            ...sharedLines,
-            ""
-          ] : [],
-          "Fact sheet:",
-          page.markdown
-        ].join("\n");
+        const prompt = pagePrompt({
+          categories,
+          factSheet: page.markdown,
+          flowDiagramTitle: diagrams.flowDiagram?.title ?? null,
+          hasFlow: ctx.hasFlow,
+          sharedLines
+        });
         const keys = categoryKeys.length ? categoryKeys : ["general"];
         let synth = parseDocPage(
           await opts.llm.complete({
@@ -16066,17 +16449,20 @@ async function generateDokuInner(brainId, opts = {}) {
             `doku: blocks dropped (${page.slug}): ${synth.dropped.join("; ")}`
           );
         if (synth.page) {
-          const title = pickDocTitle(
+          const s = stored;
+          const same = s?.title === page.model.title && !storedCollisions.has(page.slug);
+          const title = same && s?.docTitle ? s.docTitle : pickDocTitle(
             synth.page.title,
             page.title,
             page.slug,
             takenTitle
           );
+          const category = same && s?.category && categoryKeys.includes(s.category) ? s.category : synth.page.category;
           const f = {
             ...model,
             presentation: synth.page.presentation,
             docTitle: title,
-            category: synth.page.category
+            category
           };
           f.body = pageBody(f);
           model = f;
@@ -16094,17 +16480,7 @@ async function generateDokuInner(brainId, opts = {}) {
         console.warn(`doku: page synthesis failed (${page.slug}):`, e);
       }
       if (!ok2 && sameFacts && aiComplete("feature", stored)) {
-        const s = stored;
-        const fresh = model;
-        const f = {
-          ...model,
-          ...s.presentation ? { presentation: s.presentation } : {},
-          body: s.body ?? null,
-          docTitle: s.docTitle ?? null,
-          category: s.category ?? null,
-          ...!fresh.flow && s.flow ? { flow: s.flow } : {},
-          ...!fresh.flowDiagram && s.flowDiagram ? { flowDiagram: s.flowDiagram } : {}
-        };
+        const f = withStoredAi(model, stored);
         model = f;
         markdown = renderFeaturePage(f);
         if (f.docTitle) page.title = f.docTitle;
@@ -16377,7 +16753,7 @@ var init_doku = __esm({
       `{"kind":"flow","title":"...","source":"flowDiagram"}: places the feature's existing runtime diagram where it helps the explanation; allowed only when the input lists that diagram as available, at most once.`,
       "Composition: explanation and outcome before technical detail. A feature exposing an API documents what it is, why you need it, and each endpoint with its parameters, request and response shape, and error cases, all from the facts only. A user-facing feature explains what is shown and how to use it, with steps only for a real action sequence. A pipeline explains what goes in, what comes out, and when it runs. A configuration-heavy feature tabulates its settings and explains precedence and effects. A feature containing several of these covers each. Mix kinds freely; there is no fixed template and no fixed number of blocks.",
       "Length follows the subject: an extensive feature gets several text sections with subheadings, the relationships, prerequisites, special cases, and reasons explained, and a concrete example; a small feature stays short. Never break a coherent explanation into bullet points for layout reasons and never cut it short. Explain a term at its first use; state the concrete consequence for the reader.",
-      "Keep every fact; invent nothing. Missing facts stay missing: leave optional blocks out, and when an indispensable piece of information is not available, say so in one plain sentence addressed to the reader (for example: The exact request path is not documented yet.), never mentioning a fact sheet, an input, or a model. Do not repeat the change history or the decision list (both are shown separately). No H1 heading (the title renders above).",
+      "Keep every fact; invent nothing. Missing facts stay missing: leave optional blocks out, and when an indispensable piece of information is not available, say so in one plain sentence addressed to the reader (for example: The exact request path is not documented yet.), never mentioning a fact sheet, an input, or a model. The change history and the decision list are shown separately below the page: never reproduce them as a list or table. Their content still counts as facts. The page describes the CURRENT state: where a newer history entry or decision added, changed, replaced, or removed something, the text states the current state (for example that a capability no longer exists, or which mechanism replaced another), and the reasons that explain the current design belong in the explanation. When facts conflict, the newer one wins. Never replace a stated fact with what is usual elsewhere. No H1 heading (the title renders above).",
       "When the input lists facts documented elsewhere for the SAME endpoint or interface, use them: they are proven, so the endpoint may be shown here as well, and the other page may be linked with a short readable link text in the form [text](page:slug), copying the slug exactly. Never merge pages because their titles look alike.",
       PROSE_STYLE
     ].join(" ");
@@ -16433,11 +16809,12 @@ var init_doku = __esm({
       "You read one architecture overview of a software system (module groups with their features and dependencies, plus real file paths) and produce the system's main RUNTIME flows: how a request, session, or piece of data actually moves through the system.",
       'Respond ONLY with JSON of exactly this shape: {"flows": [{"slug": "...", "title": "...", "summary": "...", "explanation": "...", "lanes": [{"key": "...", "title": "..."}], "nodes": [{"id": "...", "lane": "...", "title": "...", "subtitle": "...", "kind": "...", "evidence": ["path"]}], "edges": [{"from": "...", "to": "...", "label": "...", "kind": "..."}]}]}. Nothing outside the JSON.',
       '"explanation" walks a reader through THIS flow in markdown (2-5 short paragraphs, ### subheadings where they help, at most 3500 characters): what starts it, what each phase does, what comes out. Describe an order only where the edges show it; where paths run in parallel or depend on a gate, say so instead of inventing a sequence. Name the same stations as the nodes.',
-      "Produce 2 to 4 flows, one per MAIN runtime path a newcomer must understand (for example: how input becomes stored data, how a query becomes an answer, how an external agent connects, how background verification runs). Cover every major path the features support; do not stop at two when the system clearly has more.",
+      'Produce up to 4 flows, one per MAIN runtime path a newcomer must understand (for example: how input becomes stored data, how a query becomes an answer, how an external agent connects, how background verification runs). Cover every major path the listed features describe and no path they do not: when they describe fewer paths, produce fewer flows, and when no feature is documented at all, respond {"flows": []}.',
       "lanes are 3-5 PHASES of the flow in order (intake, processing, storage, ...), titled in plain words. Never folder names.",
       "nodes are the runtime components in those phases: 4-10 per flow. kind is exactly one of: actor (human or external agent), surface (UI or endpoint), logic (application work), policy (a gate: auth, quota, validation), action (an outward call such as an LLM or external API), data (a store). title at most 3 words; subtitle at most 3 words (under 24 characters).",
       "evidence lists 1-3 file paths copied EXACTLY from the Files section that implement the node. Never invent or modify a path; omit evidence rather than guess.",
       'edges carry meaning: label with WHAT flows (at most 3 words, under 20 characters, never counts). kind is "primary" for the main path, "return" for a reply going back, "policy" for a gate outcome, "async" for background work.',
+      "Draw an edge only where the input shows the connection: a listed dependency between the two groups, a feature whose code spans both groups (Features spanning groups), or one feature describing both steps. Never connect components because such systems usually are connected; a path the input does not show stays out of the flow.",
       "Ground everything in the listed features and dependencies. Invent nothing."
     ].join(" ");
     FEATURE_FLOW_SYSTEM = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainjar",
-  "version": "0.3.976",
+  "version": "0.3.977",
   "description": "BrainJar CLI: turn a repository into a live, self-documenting Brain.",
   "type": "module",
   "bin": {