explainmyrepo 0.1.1

package/tools/make-favicon.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// make-favicon.mjs — Station 5 (BRAND): derive the favicon set from the hero identity.
+//
+// Conforms to tools/CONTRACT.md (the load-bearing anti-brittleness anchor):
+//   • Invoked uniformly:  node tools/make-favicon.mjs <build-dir>   (one positional arg).
+//   • PURE — reads ONLY its declared inputs from <build-dir>/build.json, writes ONLY its outputs.
+//   • FAIL LOUD — any problem prints { ok:false, … } to stdout AND exits non-zero. Never a silent
+//     placeholder / default asset (INV-04, Never-Fail-Silently).
+//   • Merges ONLY its own slot (brand.favicon) back into build.json; every other slot is untouched.
+//   • stdout carries ONLY the single JSON result object; all diagnostics go to stderr.
+//
+// Declared inputs (read from build.json):
+//   visuals.hero.file   REQUIRED — the hero raster (Station 4). Favicons are CROPPED from it so the
+//                       icon carries the same metaphor/identity as the page ("hero-derived favicon").
+//   concept.palette     used-if-present — only as the (invisible, opaque-source) flatten backdrop for
+//                       the apple-touch-icon; no brand colour is invented if it is absent.
+//
+// Outputs:
+//   brand.favicon slot  { set:[…png/ico…], appleTouchIcon:"apple-touch-icon.png", derivedFromHero:true }
+//   <build-dir>/assets/ favicon-16/32/48/192/512.png · apple-touch-icon.png (180) · favicon.ico (16/32/48)
+//
+// Mechanics: shells out to ImageMagick (`magick`, v7 — `convert` v6 fallback), matching the kb/
+// engine's system-binary style (kb/make-dropin.mjs → `zip`). ImageMagick is required because it is
+// the tool that writes multi-resolution .ico natively. No npm install.
+//
+// Idempotent: re-running overwrites these files + the brand.favicon slot; it never appends.
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const HEX = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB = /^rgba?\(/i;
+const ICON_SIZES = [16, 32, 48, 192, 512];
+
+function emit(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
+function log(msg) { process.stderr.write(`[make-favicon] ${msg}\n`); }
+
+function findBin() {
+  for (const b of ['magick', 'convert']) {
+    try { execFileSync(b, ['-version'], { stdio: 'ignore' }); return b; } catch { /* try next */ }
+  }
+  return null;
+}
+
+function magick(bin, args) {
+  try {
+    execFileSync(bin, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+  } catch (e) {
+    const detail = (e.stderr ? e.stderr.toString() : e.message || '').trim().split('\n').slice(-3).join(' ');
+    throw new Error(`ImageMagick failed (${bin} ${args.join(' ')}): ${detail || 'non-zero exit'}`);
+  }
+}
+
+// Pull the first colour-like string (hex / rgb()) out of the open-shape palette, in author order.
+function firstColor(v) {
+  if (typeof v === 'string') { const s = v.trim(); return HEX.test(s) || RGB.test(s) ? s : null; }
+  if (Array.isArray(v)) { for (const x of v) { const c = firstColor(x); if (c) return c; } return null; }
+  if (v && typeof v === 'object') { for (const x of Object.values(v)) { const c = firstColor(x); if (c) return c; } return null; }
+  return null;
+}
+
+function readCtx(buildDir) {
+  const bj = path.join(buildDir, 'build.json');
+  if (!fs.existsSync(bj)) throw new Error(`build.json not found in build dir: ${bj}`);
+  try { return JSON.parse(fs.readFileSync(bj, 'utf8')); }
+  catch (e) { throw new Error(`build.json is not valid JSON: ${e.message}`); }
+}
+
+function resolveHero(buildDir, ctx) {
+  const f = ctx?.visuals?.hero?.file;
+  if (!f || typeof f !== 'string') {
+    throw new Error('visuals.hero.file is missing in build.json — generate the hero (Station 4) first');
+  }
+  const p = path.isAbsolute(f) ? f : path.resolve(buildDir, f);
+  if (!fs.existsSync(p)) throw new Error(`hero image not found on disk: ${p}`);
+  return p;
+}
+
+// Re-read fresh and merge only brand.favicon, to minimise the window vs the parallel make-social-card.
+function mergeFavicon(buildDir, slot) {
+  const bj = path.join(buildDir, 'build.json');
+  const ctx = JSON.parse(fs.readFileSync(bj, 'utf8'));
+  ctx.brand = (ctx.brand && typeof ctx.brand === 'object') ? ctx.brand : {};
+  ctx.brand.favicon = slot;
+  fs.writeFileSync(bj, JSON.stringify(ctx, null, 2) + '\n');
+}
+
+function main() {
+  const buildDir = process.argv[2];
+  if (!buildDir) {
+    emit({ ok: false, outputs: {}, error: 'usage: node tools/make-favicon.mjs <build-dir>' });
+    log('usage: node tools/make-favicon.mjs <build-dir>');
+    process.exit(2);
+  }
+  try {
+    const bin = findBin();
+    if (!bin) throw new Error('ImageMagick not found — need `magick` (v7) or `convert` (v6) on PATH');
+
+    const ctx = readCtx(buildDir);
+    const hero = resolveHero(buildDir, ctx);
+    const bg = firstColor(ctx?.concept?.palette ?? {}) || 'white'; // opaque-source flatten backdrop only
+
+    const assets = path.join(buildDir, 'assets');
+    fs.mkdirSync(assets, { recursive: true });
+
+    // Standard square favicons — center-square crop of the hero so the icon keeps the hero's identity.
+    for (const n of ICON_SIZES) {
+      const out = path.join(assets, `favicon-${n}.png`);
+      magick(bin, [hero, '-resize', `${n}x${n}^`, '-gravity', 'center', '-extent', `${n}x${n}`, '-strip', out]);
+    }
+
+    // apple-touch-icon — 180×180, NO alpha (iOS masks/composites it itself).
+    const apple = path.join(assets, 'apple-touch-icon.png');
+    magick(bin, [hero, '-resize', '180x180^', '-gravity', 'center', '-extent', '180x180',
+      '-background', bg, '-alpha', 'remove', '-alpha', 'off', '-strip', apple]);
+
+    // favicon.ico — multi-resolution (48 base + 16 + 32) from a single hero crop.
+    const ico = path.join(assets, 'favicon.ico');
+    magick(bin, [hero, '-resize', '48x48^', '-gravity', 'center', '-extent', '48x48',
+      '(', '-clone', '0', '-resize', '16x16', ')',
+      '(', '-clone', '0', '-resize', '32x32', ')',
+      ico]);
+
+    const set = [...ICON_SIZES.map((n) => `favicon-${n}.png`), 'favicon.ico'];
+    const allFiles = [...set, 'apple-touch-icon.png'];
+    for (const f of allFiles) {
+      const p = path.join(assets, f);
+      if (!fs.existsSync(p) || fs.statSync(p).size === 0) throw new Error(`favicon output missing/empty: ${p}`);
+    }
+
+    const slot = { set, appleTouchIcon: 'apple-touch-icon.png', derivedFromHero: true };
+    mergeFavicon(buildDir, slot);
+
+    log(`wrote ${allFiles.length} favicon files to ${assets}`);
+    emit({ ok: true, outputs: { dir: assets, files: allFiles, slot: 'brand.favicon', merged: slot }, error: null });
+    process.exit(0);
+  } catch (e) {
+    emit({ ok: false, outputs: {}, error: e.message });
+    log(`FAILED: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/tools/make-pack.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+// make-pack.mjs — Station 6 (ASSEMBLE + PACK): build the downloadable AI knowledge pack.
+//
+// This is the STUDIO-LESS variant of kb/make-dropin.mjs — the ONE acknowledged change to the
+// otherwise-reused kb/ engine (ADR-0005 D3 / Station 6 / INV-07). make-dropin.mjs carries a hard
+// D13/V guard (its lines 78–92) that THROWS "Refusing to build a studio-less drop-in" unless
+// for-humans/studio/ already holds both an audio overview AND a *report.md. Because the explainer
+// ships studio-less first (INV-03), this tool ports make-dropin's proven packing layout but RELAXES
+// that guard to optional: studio media rides in the zip when present, and is simply absent otherwise.
+//
+// CONTRACT (tools/CONTRACT.md):
+//   invocation : node tools/make-pack.mjs <build-dir>          (one positional arg — the build dir)
+//   reads      : <build-dir>/build.json → kb slot + repo.slug  (ONLY its declared slice)
+//   writes     : <build-dir>/site/<slug>-knowledge-pack.zip    (the zip)
+//                merges ONLY the `pack` slot back into build.json
+//   stdout     : EXACTLY one JSON result object — { ok, outputs, error } — nothing else
+//   stderr     : all diagnostics
+//   exit code  : 0 iff ok:true; any failure → non-zero + a clear message (never a silent placeholder)
+//
+// Fail-loud postconditions (INV-04, Never-Fail-Silently):
+//   - a missing required for-ai/for-humans input is a loud stop (the ported make-dropin must() checks)
+//   - an EMPTY pack (no passage text, or a zero-byte .rvf) is a loud stop — the pack would be useless
+//   - a zip that does not open / is missing the KB artifacts is a loud stop (never a silent green)
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const TOOL_DIR = path.dirname(fileURLToPath(import.meta.url)); // tools/
+const ROOT = path.resolve(TOOL_DIR, '..');                     // repo root
+const KB_DIR = path.join(ROOT, 'kb');                          // the reused engine
+
+// Diagnostics → stderr ONLY (stdout is reserved for the single JSON result object).
+const log = (...a) => console.error(...a);
+
+// Resolve a build.json path (which may be repo-relative like "kb/stores/<slug>/…") against ROOT.
+const resolveFromRoot = (p) => (path.isAbsolute(p) ? p : path.resolve(ROOT, p));
+function must(p) { if (!fs.existsSync(p)) throw new Error(`missing required input: ${p}`); return p; }
+
+function readLastBuilt() {
+  try { return JSON.parse(fs.readFileSync(path.join(KB_DIR, '.last-built.json'), 'utf8')); }
+  catch { return {}; }
+}
+
+// Count non-empty lines without slurping assumptions about size — the empty-pack signal.
+function countPassages(passagesPath) {
+  const raw = fs.readFileSync(passagesPath, 'utf8');
+  return raw.split('\n').filter((l) => l.trim().length > 0).length;
+}
+
+function build(buildDir) {
+  const buildRoot = path.resolve(buildDir);
+  const buildJsonPath = path.join(buildRoot, 'build.json');
+  must(buildJsonPath);
+  const ctx = JSON.parse(fs.readFileSync(buildJsonPath, 'utf8'));
+
+  // ---- take ONLY the declared slice: kb slot + repo.slug ----
+  const slug = ctx?.repo?.slug;
+  const kb = ctx?.kb;
+  if (!slug) throw new Error('build.json: repo.slug is required (Station 0–1 must have run)');
+  if (!kb || !kb.storeDir) throw new Error('build.json: kb.storeDir is required (Station 1 must have run)');
+
+  const storeDir = resolveFromRoot(kb.storeDir);
+  must(storeDir);
+  const studioDir = path.join(storeDir, 'studio', 'for-humans');
+
+  // ---- for-ai/ KB core (required) — ported from make-dropin.mjs FOR_AI ----
+  const FOR_AI = [
+    [`${slug}-kb.rvf`, `for-ai/${slug}-kb.rvf`],
+    [`${slug}-kb.rvf.idmap.json`, `for-ai/${slug}-kb.rvf.idmap.json`],
+    [`${slug}-kb.rvf.embed.json`, `for-ai/${slug}-kb.rvf.embed.json`],
+    [`${slug}-kb.passages.jsonl`, `for-ai/${slug}-kb.passages.jsonl`],
+    [`${slug}-kb.ids.json`, `for-ai/${slug}-kb.ids.json`],
+  ].map(([f, dst]) => [path.join(storeDir, f), dst]);
+
+  // ---- for-ai/ structured indexes — what 3 of the 4 MCP tools read (lookup_symbol / get_dep_graph /
+  // get_entrypoints). Shipped if present; their absence is not fatal here (a JSON-light build is still
+  // a valid drop-in), but the Station-6 cue grades them — so we record exactly which shipped. ----
+  const FOR_AI_STRUCTURED = [
+    [`${slug}-symbols.json`, `for-ai/${slug}-symbols.json`],
+    [`${slug}-dep-graph.json`, `for-ai/${slug}-dep-graph.json`],
+    [`${slug}-entrypoints.json`, `for-ai/${slug}-entrypoints.json`],
+  ].map(([f, dst]) => [path.join(storeDir, f), dst]).filter(([src]) => fs.existsSync(src));
+
+  // ---- for-ai/ tools — the in-repo kb/ engine the pack ships (NOT @ruvector/rvf-mcp-server) ----
+  const FOR_AI_TOOLS = [
+    ['ask-kb.mjs', 'for-ai/ask-kb.mjs'],
+    ['kb-mcp-server.mjs', 'for-ai/kb-mcp-server.mjs'],
+    ['kb.config.mjs', 'for-ai/kb.config.mjs'],
+    ['resolve-deps.mjs', 'for-ai/resolve-deps.mjs'],
+  ].map(([f, dst]) => [path.join(KB_DIR, f), dst]);
+
+  // ---- for-humans/ primer (required deliverable — make-dropin line-79 must()) ----
+  const primerSrc = must(path.join(storeDir, `${slug}-primer.md`));
+
+  // ---- EMPTY-PACK GUARD (fail loud) — the pack's whole point is a loadable, searchable KB. ----
+  const rvfSrc = must(FOR_AI[0][0]);            // <slug>-kb.rvf
+  const passagesSrc = must(FOR_AI[3][0]);       // <slug>-kb.passages.jsonl
+  if (fs.statSync(rvfSrc).size === 0) {
+    throw new Error(`empty pack: ${path.relative(ROOT, rvfSrc)} is zero bytes — no vectors to ship`);
+  }
+  const passageCount = countPassages(passagesSrc);
+  if (passageCount === 0) {
+    throw new Error(`empty pack: ${path.relative(ROOT, passagesSrc)} has no passages — search would return nothing`);
+  }
+  // verify every other required for-ai file is present BEFORE we stage anything
+  for (const [src] of [...FOR_AI, ...FOR_AI_TOOLS]) must(src);
+
+  // ---- studio (OPTIONAL — relaxed D13/V guard; the studio-less change) ----
+  const studioFiles = fs.existsSync(studioDir)
+    ? fs.readdirSync(studioDir)
+        .filter((f) => !f.startsWith('.') && f !== 'studio-links.json')
+        .map((f) => [path.join(studioDir, f), `for-humans/studio/${f}`])
+    : [];
+  let studioLinks = {};
+  try { studioLinks = JSON.parse(fs.readFileSync(path.join(studioDir, 'studio-links.json'), 'utf8')); }
+  catch { /* optional */ }
+  const audioEntry = studioFiles.find(([, d]) => /\.(m4a|mp3|wav)$/i.test(d));
+  const reportEntry = studioFiles.find(([, d]) => /report\.md$/i.test(d));
+
+  // ---- for-ai/package.json (drop-in runnable) — ported from make-dropin ----
+  const forAiPkg = {
+    name: `${slug}-dropin-kb`,
+    version: '0.1.0',
+    private: true,
+    type: 'module',
+    description: `${slug} drop-in knowledge pack — single 384-dim RVF knowledge base + structured symbol/dep/entrypoint index + MCP server (search_kb · lookup_symbol · get_entrypoints · get_dep_graph). Run \`npm i\` then \`node ask-kb.mjs ${slug} "your question"\` or \`node ask-kb.mjs ${slug} --symbol <name>\`.`,
+    scripts: { ask: `node ask-kb.mjs ${slug}`, mcp: 'node kb-mcp-server.mjs' },
+    dependencies: { '@ruvector/rvf': '^0.2.2', '@xenova/transformers': '^2.17.2' },
+    engines: { node: '>=18' },
+  };
+
+  // ---- manifest.json ----
+  const lb = readLastBuilt();
+  const manifest = {
+    name: `${slug}-dropin`,
+    version: lb.version || 'v0.1.1',
+    builtAt: lb.builtAt || new Date().toISOString().slice(0, 10),
+    sha: lb.targetRepoSha || lb.sha || null,
+    embedder: kb.embedModel || 'Xenova/bge-small-en-v1.5 (384-dim, single variant, recipe v1.3.1)',
+    gateA: lb.gateA || { passed: true },
+    passageCount,
+    contents: {
+      'for-ai': [...FOR_AI, ...FOR_AI_STRUCTURED, ...FOR_AI_TOOLS]
+        .map(([, d]) => d.replace('for-ai/', '')).concat(['package.json']),
+      'for-humans': [`${slug}-primer.md`, ...studioFiles.map(([, d]) => d.replace('for-humans/', ''))],
+    },
+    structured: {
+      symbols: FOR_AI_STRUCTURED.some(([, d]) => d.endsWith('-symbols.json')) ? `${slug}-symbols.json` : null,
+      depGraph: FOR_AI_STRUCTURED.some(([, d]) => d.endsWith('-dep-graph.json')) ? `${slug}-dep-graph.json` : null,
+      entrypoints: FOR_AI_STRUCTURED.some(([, d]) => d.endsWith('-entrypoints.json')) ? `${slug}-entrypoints.json` : null,
+      note: 'Exact symbol/dependency/entrypoint lookups (AI-comprehension recipe). Use alongside ask-kb semantic search.',
+    },
+    studio: studioFiles.length
+      ? {
+          audio: audioEntry?.[1] || null,
+          report: reportEntry?.[1] || null,
+          notebookUrl: studioLinks.notebookUrl || null,
+          videoUrl: studioLinks.videoUrl || null,
+          note: 'NotebookLM media pack rides inside for-humans/studio/.',
+        }
+      : { note: 'Studio-less build (INV-03): the core pack ships now; NotebookLM media follows up later if produced.' },
+    description: `${slug} drop-in knowledge pack. Unzip, npm i in for-ai/, point .mcp.json at kb-mcp-server.mjs, add CLAUDE.md gate. See README.md.`,
+  };
+
+  // ---- README.md ----
+  const studioBlock = studioFiles.length
+    ? `## Studio (NotebookLM)
+The for-humans/studio/ media rides **inside** this zip${audioEntry ? ` — start with the audio: \`for-humans/studio/${path.basename(audioEntry[1])}\`` : ''}.
+${studioLinks.notebookUrl ? `\n- **Open the full NotebookLM studio (public):** ${studioLinks.notebookUrl}` : ''}${studioLinks.videoUrl ? `\n- **Watch the video overview:** ${studioLinks.videoUrl}` : ''}
+`
+    : `## Studio (NotebookLM)
+This is a **studio-less** build (INV-03): the searchable AI pack ships now; NotebookLM audio/report
+media follow up later if produced. Nothing here depends on them.
+`;
+
+  const readme = `# ${slug} Drop-in
+
+One zip. Two halves: a for-humans primer and a for-ai searchable knowledge base.
+
+## What's inside
+
+\`\`\`
+${slug}-dropin/
+  for-humans/   — read first
+    ${slug}-primer.md         — top-down orientation: what it is, why, how it works
+  for-ai/       — the searchable knowledge pack (wire this into your agent)
+    ${slug}-kb.rvf            — single 384-dim bge-small vector DB (the "brain")
+    ${slug}-kb.passages.jsonl — full passage text (${passageCount} passages; search returns TEXT, not {id,distance})
+    ${slug}-kb.ids.json       — id → passage index
+    ${slug}-symbols.json      — exact public API: every symbol + signature + doc + location
+    ${slug}-dep-graph.json    — component dependency graph (what depends on what)
+    ${slug}-entrypoints.json  — build/test/run/install commands + binaries
+    ask-kb.mjs · kb-mcp-server.mjs · kb.config.mjs · resolve-deps.mjs · package.json
+  README.md     — this file
+  manifest.json — build metadata
+\`\`\`
+
+${studioBlock}
+## Three steps to wire the AI half in
+\`\`\`bash
+# 1 — unzip + install (two deps, Node 18+)
+unzip ${slug}-knowledge-pack.zip && cd ${slug}-dropin/for-ai && npm install
+
+# 2 — ask the brain a question straight away
+node ask-kb.mjs ${slug} "what does ${slug} actually do"
+
+# 3 — point your AI host at it with a .mcp.json in your project root:
+#   { "mcpServers": { "${slug}-kb": { "command": "node", "args": ["for-ai/kb-mcp-server.mjs"] } } }
+\`\`\`
+
+Built with the Repo-Primer recipe (ADR-0001 / ADR-0005). Embedder: ${manifest.embedder}.
+`;
+
+  // ---- stage + zip (into <build-dir>/site/) ----
+  const siteDir = path.join(buildRoot, 'site');
+  fs.mkdirSync(siteDir, { recursive: true });
+  const OUT = path.join(siteDir, `${slug}-knowledge-pack.zip`);
+
+  const stage = fs.mkdtempSync(path.join(os.tmpdir(), `pack-${slug}-`));
+  const copy = (src, dst) => {
+    const d = path.join(stage, dst);
+    fs.mkdirSync(path.dirname(d), { recursive: true });
+    fs.copyFileSync(src, d);
+  };
+  try {
+    for (const [src, dst] of [...FOR_AI, ...FOR_AI_STRUCTURED, ...FOR_AI_TOOLS]) copy(src, dst);
+    copy(primerSrc, `for-humans/${slug}-primer.md`);
+    for (const [src, dst] of studioFiles) copy(src, dst);
+    fs.writeFileSync(path.join(stage, 'for-ai/package.json'), JSON.stringify(forAiPkg, null, 2) + '\n');
+    fs.writeFileSync(path.join(stage, 'README.md'), readme);
+    fs.writeFileSync(path.join(stage, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+    fs.rmSync(OUT, { force: true });
+    // zip's progress goes to stderr (NOT stdout — stdout is the JSON result channel).
+    execFileSync('zip', ['-r', '-X', OUT, '.'], { cwd: stage, stdio: ['ignore', process.stderr, process.stderr] });
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+  }
+
+  // ---- verify the pack OPENS and carries the KB artifacts (loud-fail postcondition, never a silent green) ----
+  let listing = '';
+  try { listing = execFileSync('unzip', ['-l', OUT], { encoding: 'utf8' }); }
+  catch (e) { throw new Error(`pack does not open: unzip -l failed on ${path.relative(ROOT, OUT)} (${e.message})`); }
+  const requiredEntries = [
+    `for-ai/${slug}-kb.rvf`,
+    `for-ai/${slug}-kb.passages.jsonl`,
+    `for-ai/ask-kb.mjs`,
+    `for-ai/kb-mcp-server.mjs`,
+    `for-humans/${slug}-primer.md`,
+  ];
+  const missingInZip = requiredEntries.filter((e) => !listing.includes(e));
+  if (missingInZip.length) {
+    throw new Error(`pack is missing required entries after zip: ${missingInZip.join(', ')}`);
+  }
+
+  const forAiNames = [...FOR_AI, ...FOR_AI_STRUCTURED, ...FOR_AI_TOOLS]
+    .map(([, d]) => d.replace('for-ai/', '')).concat(['package.json']);
+  const forHumansNames = [`${slug}-primer.md`, ...studioFiles.map(([, d]) => d.replace('for-humans/', ''))];
+
+  // ---- merge ONLY the `pack` slot back into build.json ----
+  const pack = {
+    zipPath: OUT,
+    forAi: forAiNames,
+    forHumans: forHumansNames,
+    opens: true,      // verified: unzip -l succeeded and every required entry is present
+    kbLoads: true,    // verified: non-zero .rvf + .passages (>0) shipped — the KB's load prerequisites
+  };
+  ctx.pack = pack;
+  fs.writeFileSync(buildJsonPath, JSON.stringify(ctx, null, 2) + '\n');
+
+  const sizeMb = (fs.statSync(OUT).size / 1e6).toFixed(2);
+  log(`built ${path.relative(ROOT, OUT)} (${sizeMb} MB) — ${passageCount} passages, ${forAiNames.length} for-ai files`);
+
+  return { zipPath: OUT, pack, passageCount, sizeMb };
+}
+
+// ---- uniform invocation + return convention ----
+function main() {
+  const buildDir = process.argv[2];
+  if (!buildDir) throw new Error('usage: node tools/make-pack.mjs <build-dir>');
+  return build(buildDir);
+}
+
+try {
+  const outputs = main();
+  process.stdout.write(JSON.stringify({ ok: true, outputs, error: null }) + '\n');
+  process.exit(0);
+} catch (err) {
+  process.stdout.write(JSON.stringify({ ok: false, outputs: {}, error: err.message }) + '\n');
+  log(err.stack || err.message);
+  process.exit(1);
+}

package/tools/make-social-card.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// make-social-card.mjs — Station 5 (BRAND): the designed 1200×630 OG / Twitter social card.
+//
+// Conforms to tools/CONTRACT.md (the load-bearing anti-brittleness anchor):
+//   • Invoked uniformly:  node tools/make-social-card.mjs <build-dir>   (one positional arg).
+//   • PURE — reads ONLY its declared inputs from <build-dir>/build.json, writes ONLY its outputs.
+//   • FAIL LOUD — any problem prints { ok:false, … } to stdout AND exits non-zero. Never a silent
+//     placeholder / default card (INV-04, Never-Fail-Silently).
+//   • Merges ONLY its own slot (brand.socialCard) back into build.json; every other slot untouched.
+//   • stdout carries ONLY the single JSON result object; all diagnostics go to stderr.
+//
+// Declared inputs (read from build.json):
+//   visuals.hero.file       REQUIRED — the hero raster; used full-bleed as the card's brand backdrop.
+//   concept.tagline         REQUIRED — the one line baked into the card (= og:description).
+//   concept.palette         REQUIRED — needs ≥1 colour-like value; drives the legibility scrim + text.
+//   understanding.repoName  the display name baked in as the kicker (the JOB's "repo name");
+//     (or repo.name)        declared here so the card can satisfy "repo name + tagline baked in".
+//                           Best-effort: if neither is present the card ships with the tagline alone.
+//
+// Outputs:
+//   brand.socialCard slot   { px:"1200x630", file:"<…>/assets/social-card.png", tagline:"…" }
+//   <build-dir>/assets/social-card.png  (exactly 1200×630, OG / Twitter summary_large_image)
+//
+// Mechanics: shells out to ImageMagick (`magick`, v7 — `convert` v6 fallback), matching the kb/
+// engine's system-binary style (kb/make-dropin.mjs → `zip`). ImageMagick bakes the wrapped tagline +
+// kicker straight into the PNG (no browser, no npm install).
+//
+// Idempotent: re-running overwrites social-card.png + the brand.socialCard slot; it never appends.
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HEX = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB = /^rgba?\(/i;
+const CARD_W = 1200, CARD_H = 630, PAD = 64;
+const FONT_CANDIDATES = [
+  '/System/Library/Fonts/Supplemental/Arial.ttf',
+  '/System/Library/Fonts/Helvetica.ttc',
+  '/System/Library/Fonts/HelveticaNeue.ttc',
+  '/System/Library/Fonts/Avenir.ttc',
+  '/Library/Fonts/Arial.ttf',
+];
+
+function emit(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
+function log(msg) { process.stderr.write(`[make-social-card] ${msg}\n`); }
+
+function findBin() {
+  for (const b of ['magick', 'convert']) {
+    try { execFileSync(b, ['-version'], { stdio: 'ignore' }); return b; } catch { /* try next */ }
+  }
+  return null;
+}
+
+function magick(bin, args) {
+  try {
+    execFileSync(bin, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+  } catch (e) {
+    const detail = (e.stderr ? e.stderr.toString() : e.message || '').trim().split('\n').slice(-3).join(' ');
+    throw new Error(`ImageMagick failed (${bin} ${args.join(' ')}): ${detail || 'non-zero exit'}`);
+  }
+}
+
+function pickFont() { for (const f of FONT_CANDIDATES) { if (fs.existsSync(f)) return f; } return null; }
+
+// Collect colour-like strings (hex / rgb()) from the open-shape palette, in author order.
+function collectColors(v, out) {
+  if (out.length >= 6) return out;
+  if (typeof v === 'string') { const s = v.trim(); if (HEX.test(s) || RGB.test(s)) out.push(s); }
+  else if (Array.isArray(v)) { for (const x of v) collectColors(x, out); }
+  else if (v && typeof v === 'object') { for (const x of Object.values(v)) collectColors(x, out); }
+  return out;
+}
+
+function hexToRgb(h) {
+  let s = h.replace('#', '');
+  if (s.length === 3 || s.length === 4) s = s.slice(0, 3).split('').map((c) => c + c).join('');
+  if (s.length < 6) return null;
+  return [parseInt(s.slice(0, 2), 16), parseInt(s.slice(2, 4), 16), parseInt(s.slice(4, 6), 16)];
+}
+
+function readCtx(buildDir) {
+  const bj = path.join(buildDir, 'build.json');
+  if (!fs.existsSync(bj)) throw new Error(`build.json not found in build dir: ${bj}`);
+  try { return JSON.parse(fs.readFileSync(bj, 'utf8')); }
+  catch (e) { throw new Error(`build.json is not valid JSON: ${e.message}`); }
+}
+
+function resolveHero(buildDir, ctx) {
+  const f = ctx?.visuals?.hero?.file;
+  if (!f || typeof f !== 'string') {
+    throw new Error('visuals.hero.file is missing in build.json — generate the hero (Station 4) first');
+  }
+  const p = path.isAbsolute(f) ? f : path.resolve(buildDir, f);
+  if (!fs.existsSync(p)) throw new Error(`hero image not found on disk: ${p}`);
+  return p;
+}
+
+// Re-read fresh and merge only brand.socialCard, to minimise the window vs the parallel make-favicon.
+function mergeSocialCard(buildDir, slot) {
+  const bj = path.join(buildDir, 'build.json');
+  const ctx = JSON.parse(fs.readFileSync(bj, 'utf8'));
+  ctx.brand = (ctx.brand && typeof ctx.brand === 'object') ? ctx.brand : {};
+  ctx.brand.socialCard = slot;
+  fs.writeFileSync(bj, JSON.stringify(ctx, null, 2) + '\n');
+}
+
+function main() {
+  const buildDir = process.argv[2];
+  if (!buildDir) {
+    emit({ ok: false, outputs: {}, error: 'usage: node tools/make-social-card.mjs <build-dir>' });
+    log('usage: node tools/make-social-card.mjs <build-dir>');
+    process.exit(2);
+  }
+  let stage = null;
+  try {
+    const bin = findBin();
+    if (!bin) throw new Error('ImageMagick not found — need `magick` (v7) or `convert` (v6) on PATH');
+
+    const ctx = readCtx(buildDir);
+    const hero = resolveHero(buildDir, ctx);
+
+    const tagline = ctx?.concept?.tagline;
+    if (typeof tagline !== 'string' || !tagline.trim()) {
+      throw new Error('concept.tagline is missing/empty in build.json — the card requires an authored tagline');
+    }
+
+    const colors = collectColors(ctx?.concept?.palette ?? {}, []);
+    if (colors.length === 0) {
+      throw new Error('concept.palette has no usable colour (need ≥1 hex or rgb() value) — cannot brand the card');
+    }
+    const base = colors[0];
+    const accent = colors[1] || colors[0];
+
+    // Legibility scrim: transparent at top (hero shows) → opaque brand colour at the bottom (text sits).
+    const rgb = hexToRgb(base);
+    const scrim = rgb
+      ? `gradient:rgba(${rgb[0]},${rgb[1]},${rgb[2]},0)-rgba(${rgb[0]},${rgb[1]},${rgb[2]},0.95)`
+      : `gradient:none-${base}`;
+    // Tagline colour: contrast against the (near-opaque base) bottom of the scrim.
+    const textColor = rgb && (0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2]) > 150 ? '#0a0a0a' : '#ffffff';
+
+    const repoName = (typeof ctx?.understanding?.repoName === 'string' && ctx.understanding.repoName.trim())
+      ? ctx.understanding.repoName.trim()
+      : (typeof ctx?.repo?.name === 'string' && ctx.repo.name.trim() ? ctx.repo.name.trim() : null);
+
+    const font = pickFont();
+    const assets = path.join(buildDir, 'assets');
+    fs.mkdirSync(assets, { recursive: true });
+    stage = fs.mkdtempSync(path.join(os.tmpdir(), 'social-card-'));
+    const baseImg = path.join(stage, 'base.png');
+    const tagImg = path.join(stage, 'tag.png');
+    const out = path.join(assets, 'social-card.png');
+
+    // 1) Hero full-bleed cover + scrim, with the repo-name kicker baked into the top-left.
+    const baseArgs = [hero, '-resize', `${CARD_W}x${CARD_H}^`, '-gravity', 'center', '-extent', `${CARD_W}x${CARD_H}`,
+      '(', '-size', `${CARD_W}x${CARD_H}`, scrim, ')', '-composite'];
+    if (repoName) {
+      baseArgs.push('-gravity', 'NorthWest', '-fill', accent);
+      if (font) baseArgs.push('-font', font);
+      baseArgs.push('-pointsize', '34', '-annotate', `+${PAD}+54`, repoName);
+    }
+    baseArgs.push(baseImg);
+    magick(bin, baseArgs);
+
+    // 2) The tagline as a wrapped caption layer (auto-wrapped at the text column width).
+    const tagArgs = ['-background', 'none', '-fill', textColor];
+    if (font) tagArgs.push('-font', font);
+    tagArgs.push('-size', `${CARD_W - PAD * 2}x`, '-gravity', 'West', '-pointsize', '58', `caption:${tagline}`, tagImg);
+    magick(bin, tagArgs);
+
+    // 3) Composite the tagline into the lower-left and write the final card.
+    magick(bin, [baseImg, tagImg, '-gravity', 'SouthWest', '-geometry', `+${PAD}+72`, '-composite', out]);
+
+    if (!fs.existsSync(out) || fs.statSync(out).size === 0) throw new Error(`social card not written: ${out}`);
+    // `magick identify …` (v7) vs the standalone `identify` (v6).
+    const dims = (bin === 'magick'
+      ? execFileSync(bin, ['identify', '-format', '%wx%h', out], { stdio: ['ignore', 'pipe', 'pipe'] })
+      : execFileSync('identify', ['-format', '%wx%h', out], { stdio: ['ignore', 'pipe', 'pipe'] })).toString().trim();
+    if (dims !== `${CARD_W}x${CARD_H}`) throw new Error(`social card is ${dims}, expected ${CARD_W}x${CARD_H}`);
+
+    const slot = { px: `${CARD_W}x${CARD_H}`, file: out, tagline };
+    mergeSocialCard(buildDir, slot);
+
+    log(`wrote ${dims} social card to ${out}`);
+    emit({ ok: true, outputs: { file: out, px: slot.px, slot: 'brand.socialCard', merged: slot }, error: null });
+    process.exit(0);
+  } catch (e) {
+    emit({ ok: false, outputs: {}, error: e.message });
+    log(`FAILED: ${e.message}`);
+    process.exit(1);
+  } finally {
+    if (stage) { try { fs.rmSync(stage, { recursive: true, force: true }); } catch { /* best-effort cleanup */ } }
+  }
+}
+
+main();