flowviant 0.96.0 → 0.99.0

package/bin/lib/knowledge.mjs

@@ -54,6 +54,31 @@
  * ten seconds. A file refused on SIZE is not a failure to retry: it is
  * permanent for that rev, skipped with a warning, and the rest of the library
  * is written.
+ *
+ * ── THE KEPT LIBRARY (2026-09-23, 0.97.0) ──
+ *
+ * The manifest may carry `library: { items: [...] }` — the designs and
+ * write-ups the project KEPT when a person accepted them — and each item lands
+ * at its own relative path, `designs/<slug>-v<N>.html` or
+ * `research/<slug>-v<N>.md`, with a generated `LIBRARY.md` at the root naming
+ * every one (path, title, kind, the card that asked for it, the date, what it
+ * supersedes). So "implement design A" is an agent opening LIBRARY.md, finding
+ * design A, and reading the page. At 0.99.0 a kept design is one folder,
+ * including its original relative sidecar paths and measured preview.
+ *
+ * SUBDIRECTORIES, AND EXACTLY TWO. The safe-name rule for a knowledge file
+ * forbids every separator; a library item is the one thing allowed ONE, and
+ * only after one of the two literal prefixes, with a stem that is already
+ * safe and the extension its kind hands back. `..`, a third segment, another
+ * prefix, a leading dot — refused, never rewritten, because a rewritten path
+ * could collide with another item's real one. The two directories are OURS the
+ * way the library directory is: a symlink or a file planted there is removed
+ * (the link, never its target) and a real directory made.
+ *
+ * ABSENT MEANS "LEAVE IT ALONE", the same rule the whole key keeps: a manifest
+ * with no `library` key is an older server, and `designs/`, `research/` and
+ * `LIBRARY.md` are neither synced nor swept. `library: { items: [] }` is the
+ * emptied catalog, SAID — both directories and the catalog go.
  */
 
 import {
@@ -102,6 +127,16 @@ export const FLOWVIANT_OWN_PATHS = [
   '.flowviant/artifacts/',
   '.flowviant/uploads/',
 ];
+/** The generated catalog of the kept library, at the knowledge root. Reserved
+ *  like INSTRUCTIONS.md: a person's file of that name is suffixed, because the
+ *  prompt tells the CLI this one is the catalog. */
+export const LIBRARY_FILE = 'LIBRARY.md';
+/** The two subdirectories a kept item may live in, by kind. */
+export const LIBRARY_DIRS = { design: 'designs', research: 'research' };
+const LIBRARY_EXT = { design: ['.html', '.htm', '.gltf', '.obj', '.glb', '.bin'], research: ['.md'] };
+/** The server caps a library at 200 items; a longer manifest is cut. */
+const MAX_LIBRARY_ITEMS = 256;
+
 /** The person's standing brief, written from the manifest's `instructions`.
  *  A RESERVED name: a library FILE called this gets a suffix, because the
  *  prompt tells the CLI to read this one first and a stranger's file must
@@ -114,23 +149,55 @@ const MARKER = '.flowviant/knowledge.rev';
  *  this is somebody's disk, and one place checking is one deploy away from
  *  zero places — the attachment fetch's own rule. */
 export const KNOWLEDGE_FILE_MAX_BYTES = 10 * 1024 * 1024;
+export const KNOWLEDGE_BINARY_MODEL_MAX_BYTES = 20 * 1024 * 1024;
+const knowledgeMaxFor = (name, base) => /\.(glb|bin)$/i.test(name)
+  ? Math.max(base, KNOWLEDGE_BINARY_MODEL_MAX_BYTES) : base;
 /** The manifest is capped at the server (25 files); a manifest longer than
  *  this is not one the product produced, and is cut rather than trusted. */
 const MAX_FILES = 64;
 
+/** FNV-1a, 32-bit, as 8 hex — deterministic, so the same long name always maps
+ *  to the same stored name. Verbatim against the server's `fnv1a8`
+ *  (apps/api/src/routes/sessionsAttachments.routes.ts). */
+function fnv1a8(s) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+/** What counts as an extension worth keeping through a cut. */
+const SAFE_EXT_RE = /^[A-Za-z0-9]{1,10}$/;
+const SAFE_NAME_MAX = 80;
+
 /**
- * `safeUploadName`, verbatim in effect (work.mjs): keeps the extension, drops
- * every path separator, never starts with a dot or a dash. Re-applied here
- * although the server did it, because this string becomes a path on this box.
+ * `safeFileName`, verbatim (apps/api/src/routes/sessionsAttachments.routes.ts):
+ * drops every path separator, never starts with a dot or a dash, and — since
+ * 2026-09-24 — THE EXTENSION SURVIVES A CUT. A bare `slice(0, 80)` truncated
+ * an over-long name mid-extension (an 84-character `….html` mockup stored as
+ * `….` with an unrecognised type and its bytes discarded), so a long name's
+ * stem is now cut and an 8-hex FNV-1a hash of the WHOLE sanitised name is
+ * appended before the extension: stable across calls, at most 80 characters,
+ * idempotent over its own output, and — the reason it is re-applied here
+ * rather than trusted to the server's own pass — byte-identical to what
+ * `safeFileName` computes there, so a knowledge file synced under this name
+ * and one requested by name later never disagree over the cut.
  */
 export function safeKnowledgeName(raw) {
-  const base = String(raw ?? '')
+  const clean = String(raw ?? '')
     .split(/[\\/]/)
     .pop()
     .replace(/[^A-Za-z0-9._-]/g, '_')
-    .replace(/^[.-]+/, '')
-    .slice(0, 80);
-  return base || 'file';
+    .replace(/^[.-]+/, '');
+  if (!clean) return 'file';
+  if (clean.length <= SAFE_NAME_MAX) return clean;
+  const dot = clean.lastIndexOf('.');
+  const ext = dot > 0 && SAFE_EXT_RE.test(clean.slice(dot + 1)) ? clean.slice(dot + 1) : '';
+  const stem = ext ? clean.slice(0, dot) : clean;
+  const tag = `-${fnv1a8(clean)}`;
+  const room = SAFE_NAME_MAX - tag.length - (ext ? ext.length + 1 : 0);
+  return `${stem.slice(0, room)}${tag}${ext ? `.${ext}` : ''}`;
 }
 
 /**
@@ -143,7 +210,14 @@ export function safeKnowledgeName(raw) {
  * Windows disks are).
  */
 export function planKnowledgeNames(files) {
-  const taken = new Set([INSTRUCTIONS_FILE.toLowerCase()]);
+  // The catalog's name and the two library directories are reserved beside
+  // the brief (0.97.0): a person's `LIBRARY.md` or a file called `designs`
+  // must never stand where the catalog or a directory has to.
+  const taken = new Set([
+    INSTRUCTIONS_FILE.toLowerCase(),
+    LIBRARY_FILE.toLowerCase(),
+    ...Object.values(LIBRARY_DIRS),
+  ]);
   const out = [];
   for (const f of files) {
     const name = safeKnowledgeName(f.name);
@@ -232,25 +306,192 @@ function ensureDir(checkoutDir) {
   return dir;
 }
 
-export function readKnowledgeMarker(checkoutDir) {
+/**
+ * THE MARKER SAYS WHICH REV WAS WRITTEN, AND WHETHER THE LIBRARY WAS PART OF
+ * IT (2026-09-23): `<rev>` or `<rev>:lib`.
+ *
+ * The rev alone could not tell an upgrade from a sync. A 0.96.0 box wrote the
+ * marker for rev N while ignoring the manifest's `library` key (it did not
+ * know one); updated to 0.97.0 with `knowledge_rev` still N, it read "N",
+ * matched the roster, and never synced the library — then the server handed
+ * `task.references` naming `designs/x-v1.html` and the agent was told to read
+ * a file that was not there. `:lib` records that THIS rev's sync carried a
+ * library key, so the upgrade case is one string compare and re-syncs at
+ * once. An older daemon reading `N:lib` sees NaN and re-syncs once, which is
+ * the harmless direction.
+ */
+function parseMarker(checkoutDir) {
   try {
-    const n = Number(readFileSync(join(checkoutDir, MARKER), 'utf8').trim());
-    return Number.isInteger(n) && n >= 0 ? n : null;
+    const m = /^(\d+)(:lib)?$/.exec(readFileSync(join(checkoutDir, MARKER), 'utf8').trim());
+    if (!m) return null;
+    const n = Number(m[1]);
+    return Number.isSafeInteger(n) ? { rev: n, lib: Boolean(m[2]) } : null;
   } catch {
     return null;
   }
 }
 
-function writeKnowledgeMarker(checkoutDir, rev) {
+export function readKnowledgeMarker(checkoutDir) {
+  return parseMarker(checkoutDir)?.rev ?? null;
+}
+
+/** Did the sync that wrote the marker carry a `library` key? */
+export function knowledgeMarkerHasLibrary(checkoutDir) {
+  return parseMarker(checkoutDir)?.lib ?? false;
+}
+
+function writeKnowledgeMarker(checkoutDir, rev, lib = false) {
   try {
     mkdirSync(join(checkoutDir, '.flowviant'), { recursive: true });
-    writeAtomic(join(checkoutDir, MARKER), `${rev}\n`);
+    writeAtomic(join(checkoutDir, MARKER), `${rev}${lib ? ':lib' : ''}\n`);
   } catch {
     /* a lost marker costs one re-sync after a restart — every file already on
        disk matches by sha and is not downloaded again */
   }
 }
 
+/**
+ * A kept item's relative path, or null when it is not EXACTLY
+ * `<designs|research>/<safe stem>.<its kind's extension>` — see the header.
+ * Refused rather than rewritten: a rewritten path is one the server never
+ * named, and it could land on another item's real one.
+ */
+export function safeLibraryPath(name, kind) {
+  if (typeof name !== 'string' || !(kind in LIBRARY_DIRS)) return null;
+  const parts = name.split('/');
+  if (parts.length !== 2 && !(kind === 'design' && parts.length >= 3 && parts.length <= 7)) return null;
+  const [dir, ...rest] = parts;
+  const file = rest.at(-1);
+  if (dir !== LIBRARY_DIRS[kind]) return null;
+  if (rest.length >= 2 && !/^[a-z0-9-]+-v[1-9][0-9]*$/.test(rest[0])) return null;
+  if (rest.slice(1, -1).some((p) => !safeBundleSegment(p))) return null;
+  if (!file || (rest.length === 1 ? file !== safeKnowledgeName(file) : !safeBundleSegment(file))) return null;
+  if (!LIBRARY_EXT[kind].some((ext) => file.toLowerCase().endsWith(ext) && file.length > ext.length)) return null;
+  return name;
+}
+
+function safeBundleSegment(part) {
+  return typeof part === 'string' && part.length > 0 && part.length <= 80 &&
+    /^[A-Za-z0-9][A-Za-z0-9._ -]*$/.test(part) && !part.endsWith('.');
+}
+
+function safeBundleFile(path, rootDir) {
+  if (typeof path !== 'string' || !path.startsWith(`${rootDir}/`)) return null;
+  const relative = path.slice(rootDir.length + 1);
+  if (relative === 'preview.png') return null;
+  const parts = relative.split('/');
+  if (!parts.length || parts.some((p) => !safeBundleSegment(p))) return null;
+  if (!/\.(gltf|obj|glb|bin|png|jpg|jpeg|gif|webp|svg|json)$/i.test(relative)) return null;
+  return path;
+}
+
+/** The manifest's library items that are safe to write, in manifest order, or
+ *  null when the key is ABSENT (an older server — leave everything alone). */
+function libraryItemsOf(manifest) {
+  const lib = manifest?.library;
+  if (lib === undefined || lib === null) return null;
+  if (typeof lib !== 'object' || !Array.isArray(lib.items)) return null;
+  const out = [];
+  const seen = new Set();
+  for (const it of lib.items.slice(0, MAX_LIBRARY_ITEMS)) {
+    if (!it || typeof it.id !== 'string' || !/^[0-9a-f-]{8,64}$/i.test(it.id)) continue;
+    const path = safeLibraryPath(it.name, it.kind);
+    if (!path || seen.has(path.toLowerCase())) continue;
+    seen.add(path.toLowerCase());
+    const bundleDir = path.split('/').length >= 3 ? path.split('/').slice(0, 2).join('/') : null;
+    const expectedPreview = bundleDir ? `${bundleDir}/preview.png` : it.name.replace(/\.html$/, '.png');
+    const previewPath = it.kind === 'design' && it.preview && it.preview.name === expectedPreview ? expectedPreview : null;
+    const files = bundleDir && Array.isArray(it.files) ? it.files.map((f, index) => ({ ...f,
+      index, path: safeBundleFile(f.name, bundleDir),
+    })).filter((f) => f.path && !seen.has(f.path.toLowerCase())) : [];
+    for (const f of files) seen.add(f.path.toLowerCase());
+    out.push({ ...it, path, files, previewPath, previewUnknown: it.kind === 'design' && path.endsWith('.html') && it.preview === undefined });
+  }
+  return out;
+}
+
+/** One line of the catalog: server strings are made single-line and capped —
+ *  they are a person's card title and an artifact's name, headed into a file
+ *  an agent reads, so they may not carry a line break that forges a second
+ *  entry. */
+const catalogText = (v, max) =>
+  String(v ?? '')
+    .replace(/[\r\n\t]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+
+/**
+ * THE CATALOG, generated whole from the manifest on every sync:
+ *
+ *   - designs/landing-v2.html — Landing mockup (design, from card "Redesign
+ *     landing page", 2026-09-23, supersedes designs/landing-v1.html)
+ *
+ * (one line per item, oldest first — the server's order — so a sync that adds
+ * one item adds one line and moves nothing). Null when there are no items, in
+ * which case the file is removed rather than written empty.
+ */
+export function renderLibraryCatalog(items) {
+  if (!items || items.length === 0) return null;
+  const lines = items.map((it) => {
+    const facts = [it.kind === 'research' ? 'research' : 'design'];
+    const card = catalogText(it.taskTitle, 200);
+    if (card) facts.push(`from card "${card.replace(/"/g, "'")}"`);
+    const day = typeof it.createdAt === 'string' ? it.createdAt.slice(0, 10) : '';
+    if (/^\d{4}-\d{2}-\d{2}$/.test(day)) facts.push(day);
+    const sup = typeof it.supersedes === 'string' ? catalogText(it.supersedes, 200) : '';
+    if (sup) facts.push(`supersedes ${sup}`);
+    const title = catalogText(it.title, 200) || it.path;
+    return `- ${it.path} — ${title} (${facts.join(', ')})`;
+  });
+  return (
+    '# Library\n\n' +
+    'The designs and research this project kept. Paths are relative to this directory;\n' +
+    'a newer version supersedes an older one of the same name.\n\n' +
+    `${lines.join('\n')}\n`
+  );
+}
+
+/** A library subdirectory as a real directory — ours, like the library's own
+ *  path: a symlink or a file planted there is removed, never followed. */
+function ensureSubdir(dir, name) {
+  const path = join(dir, name);
+  try {
+    const st = lstatSync(path);
+    if (st.isSymbolicLink() || !st.isDirectory()) unlinkSync(path);
+  } catch {
+    /* absent */
+  }
+  mkdirSync(path, { recursive: true });
+  return path;
+}
+
+function ensureLibraryParents(dir, relativePath) {
+  const parts = relativePath.split('/');
+  let at = dir;
+  for (const part of parts.slice(0, -1)) at = ensureSubdir(at, part);
+}
+
+function sweepLibraryTree(dir, sub, wanted, result) {
+  const walk = (at, prefix = '') => {
+    let entries;
+    try { entries = readdirSync(at); } catch { return; }
+    for (const name of entries) {
+      const rel = prefix ? `${prefix}/${name}` : name;
+      const path = join(at, name);
+      let st;
+      try { st = lstatSync(path); } catch { continue; }
+      if (st.isDirectory() && !st.isSymbolicLink()) {
+        walk(path, rel);
+        try { if (readdirSync(path).length === 0) rmSync(path, { recursive: true, force: true }); } catch { /* next sync */ }
+      } else if (!wanted.has(rel)) {
+        try { rmSync(path, { recursive: true, force: true }); result.removed.push(`${sub}/${rel}`); } catch { /* next sync */ }
+      }
+    }
+  };
+  walk(join(dir, sub));
+};
+
 /** Does this manifest look like one the server produced? Anything else is
  *  ignored whole rather than half-applied. */
 export function isKnowledgeManifest(k) {
@@ -285,6 +526,8 @@ export async function syncKnowledge({ checkoutDir, manifest, fetchFile, maxBytes
     typeof manifest.instructions === 'string' && manifest.instructions.trim()
       ? manifest.instructions
       : null;
+  // null = the key is ABSENT (leave the library's paths alone); [] = emptied.
+  const library = libraryItemsOf(manifest);
 
   if (!flowviantDirOk(checkoutDir)) {
     // Not a failure to retry every poll — nothing changes until a person
@@ -295,8 +538,13 @@ export async function syncKnowledge({ checkoutDir, manifest, fetchFile, maxBytes
     return result;
   }
 
-  // EMPTIED: the directory goes, and the prompt paragraph with it.
-  if (files.length === 0 && !instructions) {
+  // EMPTIED: the directory goes, and the prompt paragraph with it — unless the
+  // library key is ABSENT and a synced library is on disk, which an older
+  // server's emptied shelf has no say over.
+  const libraryOnDisk =
+    library === null &&
+    [LIBRARY_FILE, ...Object.values(LIBRARY_DIRS)].some((n) => existsSync(join(dirPath, n)));
+  if (files.length === 0 && !instructions && (library === null ? !libraryOnDisk : library.length === 0)) {
     if (existsSync(dirPath)) {
       try {
         const st = lstatSync(dirPath);
@@ -314,10 +562,16 @@ export async function syncKnowledge({ checkoutDir, manifest, fetchFile, maxBytes
   const planned = planKnowledgeNames(files);
   const keep = new Set(planned.map((p) => p.local));
   if (instructions) keep.add(INSTRUCTIONS_FILE);
+  // ABSENT library key: its paths are neither synced nor swept.
+  if (library === null) {
+    keep.add(LIBRARY_FILE);
+    for (const d of Object.values(LIBRARY_DIRS)) keep.add(d);
+  }
 
   for (const f of planned) {
     const path = join(dir, f.local);
-    if (Number(f.bytes) > maxBytes) {
+    const fileMax = knowledgeMaxFor(f.name, maxBytes);
+    if (Number(f.bytes) > fileMax) {
       // Permanent for this rev, and NOT a reason to delete the rest. Any stale
       // local copy under this name goes, because it is not the file the
       // manifest now names.
@@ -328,7 +582,7 @@ export async function syncKnowledge({ checkoutDir, manifest, fetchFile, maxBytes
     if (typeof f.sha256 === 'string' && localSha(path) === f.sha256.toLowerCase()) continue;
     try {
       const buf = await fetchFile(f.id);
-      if (!Buffer.isBuffer(buf) || buf.byteLength > maxBytes) {
+      if (!Buffer.isBuffer(buf) || buf.byteLength > fileMax) {
         result.refused.push(f.local);
         keep.delete(f.local);
         continue;
@@ -363,6 +617,10 @@ export async function syncKnowledge({ checkoutDir, manifest, fetchFile, maxBytes
     }
   }
 
+  if (library !== null) {
+    await syncLibrary({ dir, items: library, fetchFile, maxBytes, keep, result });
+  }
+
   // Everything the manifest no longer names — files, stray temp names, and
   // anything that is not a regular file — leaves.
   let entries = [];
@@ -383,6 +641,122 @@ export async function syncKnowledge({ checkoutDir, manifest, fetchFile, maxBytes
   return result;
 }
 
+/**
+ * THE KEPT LIBRARY'S HALF OF A SYNC: each item into its subdirectory (fetched
+ * only when its sha differs, written atomically, the bytes checked against the
+ * manifest), every other entry in the two subdirectories removed, and
+ * `LIBRARY.md` regenerated from the items that are on disk. A download that
+ * fails keeps whatever copy was there and clears `ok`, the file rule; an item
+ * over the cap is refused for this rev and left out of the catalog.
+ */
+async function syncLibrary({ dir, items, fetchFile, maxBytes, keep, result }) {
+  const wanted = { designs: new Set(), research: new Set() };
+  const onDisk = [];
+  for (const kind of Object.keys(LIBRARY_DIRS)) {
+    if (items.some((it) => it.kind === kind)) {
+      ensureSubdir(dir, LIBRARY_DIRS[kind]);
+      keep.add(LIBRARY_DIRS[kind]);
+    }
+  }
+  for (const it of items) {
+    const [sub, ...tail] = it.path.split('/');
+    const file = tail.join('/');
+    const path = join(dir, ...it.path.split('/'));
+    ensureLibraryParents(dir, it.path);
+    const itemMax = knowledgeMaxFor(it.path, maxBytes);
+    wanted[sub].add(file);
+    if (it.previewPath) wanted[sub].add(it.previewPath.split('/').slice(1).join('/'));
+    if (it.previewUnknown) {
+      const oldPng = file.includes('/') ? `${file.slice(0, file.lastIndexOf('/'))}/preview.png` : file.replace(/\.html$/, '.png');
+      if (localSha(join(dir, sub, ...oldPng.split('/'))) !== null) wanted[sub].add(oldPng);
+    }
+    if (Number(it.bytes) > itemMax) {
+      result.refused.push(it.path);
+      wanted[sub].delete(file);
+      continue;
+    }
+    if (typeof it.sha256 === 'string' && localSha(path) === it.sha256.toLowerCase()) {
+      onDisk.push(it);
+    } else {
+      try {
+        const buf = await fetchFile(it.id, { library: true });
+        if (!Buffer.isBuffer(buf) || buf.byteLength > itemMax) {
+          result.refused.push(it.path);
+          wanted[sub].delete(file);
+          continue;
+        }
+        if (typeof it.sha256 === 'string' && sha256Of(buf) !== it.sha256.toLowerCase()) {
+          throw new Error('sha256 mismatch');
+        }
+        ensureLibraryParents(dir, it.path);
+        writeAtomic(path, buf);
+        result.wrote.push(it.path);
+        onDisk.push(it);
+      } catch {
+        result.ok = false;
+        result.failed.push(it.path);
+        if (localSha(path) !== null) onDisk.push(it);
+      }
+    }
+    if (it.previewPath && it.preview?.sha256) {
+      ensureLibraryParents(dir, it.previewPath);
+      const previewFile = join(dir, ...it.previewPath.split('/'));
+      if (localSha(previewFile) !== it.preview.sha256.toLowerCase()) {
+        try {
+          const buf = await fetchFile(it.id, { library: true, preview: true });
+          if (!Buffer.isBuffer(buf) || buf.byteLength > 2 * 1024 * 1024 || sha256Of(buf) !== it.preview.sha256.toLowerCase()) throw new Error('preview mismatch');
+          ensureLibraryParents(dir, it.previewPath);
+          writeAtomic(previewFile, buf);
+          result.wrote.push(it.previewPath);
+        } catch {
+          result.ok = false;
+          result.failed.push(it.previewPath);
+        }
+      }
+    }
+    for (const f of it.files ?? []) {
+      ensureLibraryParents(dir, f.path);
+      const rel = f.path.split('/').slice(1).join('/');
+      wanted[sub].add(rel);
+      const filePath = join(dir, ...f.path.split('/'));
+      const fileMax = knowledgeMaxFor(f.path, maxBytes);
+      if (Number(f.bytes) > fileMax) { result.refused.push(f.path); wanted[sub].delete(rel); continue; }
+      if (localSha(filePath) === String(f.sha256).toLowerCase()) continue;
+      try {
+        const buf = await fetchFile(it.id, { library: true, fileIndex: f.index });
+        if (!Buffer.isBuffer(buf) || buf.byteLength > fileMax) { result.refused.push(f.path); wanted[sub].delete(rel); continue; }
+        if (sha256Of(buf) !== String(f.sha256).toLowerCase()) throw new Error('sha256 mismatch');
+        ensureLibraryParents(dir, f.path);
+        writeAtomic(filePath, buf);
+        result.wrote.push(f.path);
+      } catch { result.ok = false; result.failed.push(f.path); }
+    }
+  }
+  // Each subdirectory holds exactly what the manifest names.
+  for (const sub of Object.values(LIBRARY_DIRS)) {
+    const subPath = join(dir, sub);
+    try { if (!lstatSync(subPath).isDirectory()) continue; } catch { continue; }
+    sweepLibraryTree(dir, sub, wanted[sub], result);
+    // An emptied subdirectory leaves with its last item.
+    if (wanted[sub].size === 0) keep.delete(sub);
+  }
+  const catalog = renderLibraryCatalog(onDisk);
+  if (catalog) {
+    keep.add(LIBRARY_FILE);
+    const path = join(dir, LIBRARY_FILE);
+    let same = false;
+    try {
+      same = lstatSync(path).isFile() && readFileSync(path, 'utf8') === catalog;
+    } catch {
+      /* absent */
+    }
+    if (!same) {
+      writeAtomic(path, catalog);
+      result.wrote.push(LIBRARY_FILE);
+    }
+  }
+}
+
 /**
  * The absolute library path, or null when there is nothing there for a turn
  * to read. The prompt paragraph is rendered only when this is non-null, so a
@@ -404,7 +778,8 @@ export function knowledgeDirFor(checkoutDir) {
 function libraryMissing(checkoutDir, manifest) {
   const named =
     (Array.isArray(manifest.files) && manifest.files.length > 0) ||
-    (typeof manifest.instructions === 'string' && manifest.instructions.trim() !== '');
+    (typeof manifest.instructions === 'string' && manifest.instructions.trim() !== '') ||
+    (Array.isArray(manifest.library?.items) && manifest.library.items.length > 0);
   if (!named) return false;
   try {
     lstatSync(join(checkoutDir, KNOWLEDGE_DIR));
@@ -414,6 +789,47 @@ function libraryMissing(checkoutDir, manifest) {
   }
 }
 
+/**
+ * Does the manifest name LIBRARY items the disk no longer holds — or a library
+ * this box never synced at all? The same-rev skip's second question, beside
+ * `libraryMissing`'s "is the directory there".
+ *
+ * `synced` is the marker's `:lib` (or the driver's memory of it): false means
+ * the rev on the marker was written by a sync that ignored the library, the
+ * 0.96.0-to-0.97.0 upgrade. Otherwise every named item's path AND `LIBRARY.md`
+ * must be regular files — a hand-deleted `designs/`, or one item removed, is a
+ * re-sync, and the files still on disk match by hash and are not fetched
+ * again. Items the manifest itself puts over the cap, and items this driver
+ * already saw refused for this rev, are not expected: a refusal is permanent
+ * for the rev, and expecting it would re-fetch ten megabytes every poll.
+ * An ABSENT `library` key expects nothing (an older server has no say).
+ */
+function libraryStale(checkoutDir, manifest, { synced, refused }) {
+  const items = libraryItemsOf(manifest);
+  if (items === null) return false;
+  if (!synced) return true;
+  const expected = items.filter((it) => !(Number(it.bytes) > knowledgeMaxFor(it.path, KNOWLEDGE_FILE_MAX_BYTES)) && !refused.has(it.path));
+  if (expected.length === 0) return false;
+  const dir = join(checkoutDir, KNOWLEDGE_DIR);
+  const isFile = (p) => {
+    try {
+      let parent = dir;
+      for (const part of p.slice(dir.length + 1).split('/').slice(0, -1)) {
+        parent = join(parent, part);
+        const st = lstatSync(parent);
+        if (st.isSymbolicLink() || !st.isDirectory()) return false;
+      }
+      return lstatSync(p).isFile();
+    } catch {
+      return false;
+    }
+  };
+  if (!isFile(join(dir, LIBRARY_FILE))) return true;
+  return expected.some((it) => !isFile(join(dir, ...it.path.split('/'))) ||
+    (it.previewPath && !refused.has(it.previewPath) && !isFile(join(dir, ...it.previewPath.split('/')))) ||
+    (it.files ?? []).some((f) => !refused.has(f.path) && !isFile(join(dir, ...f.path.split('/')))));
+}
+
 /**
  * The per-process driver: called with every roster's `knowledge` key.
  *
@@ -430,6 +846,11 @@ export function createKnowledgeSync({
   now = () => Date.now(),
 }) {
   let rev = readKnowledgeMarker(checkoutDir);
+  /** Whether the sync that wrote `rev` carried a library key — the marker's
+   *  `:lib`, then this process's own memory. */
+  let libSynced = knowledgeMarkerHasLibrary(checkoutDir);
+  /** Library paths refused for size at `rev` — not expected on disk. */
+  let libRefused = new Set();
   let busy = false;
   let failures = 0;
   let retryAt = 0;
@@ -459,7 +880,17 @@ export function createKnowledgeSync({
        * something over a directory that does not exist is re-synced; files
        * already on disk match by hash and are not fetched again.
        */
-      if (knowledge.rev === rev && !libraryMissing(checkoutDir, knowledge)) return null;
+      //
+      // …AND THE SAME REV IS NOT ALWAYS THE SAME LIBRARY: an upgrade from a
+      // daemon that ignored the `library` key, or a hand-deleted `designs/`,
+      // leaves the marker current over files a card's references name. See
+      // `libraryStale`.
+      if (
+        knowledge.rev === rev &&
+        !libraryMissing(checkoutDir, knowledge) &&
+        !libraryStale(checkoutDir, knowledge, { synced: libSynced, refused: libRefused })
+      )
+        return null;
       if (busy) return null;
       if (knowledge.rev === failedRev && now() < retryAt) return null;
       busy = true;
@@ -472,10 +903,12 @@ export function createKnowledgeSync({
         const r = await syncKnowledge({ checkoutDir, manifest: knowledge, fetchFile });
         if (r.ok) {
           rev = knowledge.rev;
+          libSynced = libraryItemsOf(knowledge) !== null;
+          libRefused = new Set(r.refused);
           failures = 0;
           retryAt = 0;
           failedRev = null;
-          writeKnowledgeMarker(checkoutDir, rev);
+          writeKnowledgeMarker(checkoutDir, rev, libSynced);
           if (r.wrote.length || r.removed.length) {
             log(
               `knowledge · synced rev ${rev}` +
@@ -513,10 +946,14 @@ export function createKnowledgeSync({
  * URL is derived from the roster URL the way every `/fleet/*` path is, so a
  * self-hosted `FLOWVIANT_FLEET_URL` is honoured.
  */
-export function knowledgeFetcher({ fleetUrl, token, userAgent, maxBytes = KNOWLEDGE_FILE_MAX_BYTES }) {
+export function knowledgeFetcher({ fleetUrl, token, userAgent, maxBytes = KNOWLEDGE_BINARY_MODEL_MAX_BYTES }) {
   const base = String(fleetUrl).replace(/\/agents\/?$/, '/knowledge');
-  return async (id) => {
-    const res = await fetch(`${base}/${encodeURIComponent(id)}`, {
+  // A kept library item (0.97.0) is its sibling, `GET /fleet/library/:id` —
+  // the same credential, the same shape, the same caps.
+  const libraryBase = String(fleetUrl).replace(/\/agents\/?$/, '/library');
+  return async (id, { library = false, preview = false, fileIndex = null } = {}) => {
+    const suffix = preview ? '/preview' : Number.isSafeInteger(fileIndex) && fileIndex >= 0 ? `/file/${fileIndex}` : '';
+    const res = await fetch(`${library ? libraryBase : base}/${encodeURIComponent(id)}${suffix}`, {
       headers: { Authorization: `Bearer ${token}`, 'User-Agent': userAgent },
       signal: AbortSignal.timeout(60_000),
     });