lowkey-doc 0.0.0-stage → 1.0.0

package/src/client/live.mjs

@@ -0,0 +1,156 @@
+// live.mjs - the part of the page only `lowkey-doc --watch` serves.
+// Listens for rebuilds, fetches the new documents and hands them to the page,
+// which patches itself (applyUpdate() in app.mjs). A small pill in the corner says
+// what happened: what changed and where, a build that failed and why, or a
+// watcher that has gone away. None of this is in the built index.html.
+
+export const LIVE_CSS = `
+.live{position:fixed;right:16px;bottom:16px;z-index:12;display:flex;align-items:center;gap:7px;
+  max-width:min(520px,calc(100vw - 32px));padding:5px 11px 5px 9px;border:1px solid var(--line);
+  border-radius:999px;background:var(--surface);color:var(--muted);font-size:12px;line-height:1.4;
+  box-shadow:0 4px 16px rgba(0,0,0,.45);opacity:.72;transition:opacity .2s,border-color .2s,color .2s}
+.live:hover,.live.news,.live.bad,.live.off{opacity:1}
+.live-dot{flex:none;width:7px;height:7px;border-radius:50%;background:var(--accent);box-shadow:0 0 8px var(--accent-ring)}
+.live.off .live-dot{background:var(--faint);box-shadow:none}
+.live-msg{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.live.go{cursor:pointer}
+.live.go:hover{color:var(--ink);border-color:var(--line-2)}
+.live.news{color:var(--ink)}
+.live.bad{align-items:flex-start;border-color:rgba(255,110,110,.4);border-radius:14px;color:#ff9a9a}
+.live.bad .live-dot{margin-top:5px;background:#ef4444;box-shadow:none}
+.live.bad .live-msg{white-space:pre-wrap;font-family:var(--mono);font-size:11.5px}
+.dc-changed{animation:dc-changed 2.6s ease-out 1}
+@keyframes dc-changed{
+  0%,30%{background-color:rgba(77,163,255,.2);box-shadow:0 0 0 4px rgba(77,163,255,.2)}
+  100%{background-color:rgba(77,163,255,0);box-shadow:0 0 0 4px rgba(77,163,255,0)}}
+.diagram.dc-redraw .diagram-out{opacity:.45;transition:opacity .2s}
+@media print{.live{display:none}}
+`;
+
+export const LIVE_JS = String.raw`
+(function(){
+  var LIVE = window.__LOWKEY_DOC_LIVE__ || {};
+  var app = window.__lowkey_doc;
+  var version = LIVE.version, shell = LIVE.shell;
+
+  /* ---------------- the pill ---------------- */
+
+  var pill = document.createElement('div');
+  pill.className = 'live';
+  pill.innerHTML = '<span class="live-dot"></span><span class="live-msg"></span>';
+  document.body.appendChild(pill);
+  var msg = pill.querySelector('.live-msg');
+  var action = null, calm = 0, failing = false, down = false;
+
+  function say(text, cls, onClick, ms){
+    pill.className = 'live' + (cls ? ' ' + cls : '') + (onClick ? ' go' : '');
+    msg.textContent = text;
+    pill.title = onClick ? 'Show me' : (cls === 'bad' ? '' : 'Rebuilt on every save');
+    action = onClick || null;
+    clearTimeout(calm);
+    if (ms) calm = setTimeout(idle, ms);
+  }
+  function idle(){ say('Live', '', null, 0); }
+  idle();
+
+  pill.addEventListener('click', function(){
+    if (!action) return;
+    var go = action;
+    idle();
+    go();
+  });
+
+  // a block marked as changed loses the mark once it has faded, so the next
+  // edit to the same block can flash again
+  document.addEventListener('animationend', function(e){
+    if (e.animationName === 'dc-changed') e.target.classList.remove('dc-changed');
+  });
+
+  /* ---------------- pulling ---------------- */
+
+  var pulling = false, again = false;
+
+  function pull(){
+    if (pulling){ again = true; return; }
+    pulling = true;
+    fetch('/__lowkey-doc/data.json', { cache: 'no-store' }).then(function(r){
+      if (!r.ok) throw new Error('HTTP ' + r.status);
+      return r.json();
+    }).then(function(data){
+      if (!app) return location.reload();
+      version = data.version;
+      tell(app.apply(data.docs));
+    }).catch(function(err){
+      say('Could not load the update: ' + (err && err.message || err), 'bad', null, 0);
+    }).then(function(){
+      pulling = false;
+      if (again){ again = false; pull(); }
+    });
+  }
+
+  function plural(n, one){ return n + ' ' + one + (n === 1 ? '' : 's'); }
+
+  function tell(r){
+    if (!r || failing) return;
+    if (r.moved) return say('Renamed or removed — now showing ' + titleOf(r.current), 'news', null, 5000);
+    var here = r.changed.indexOf(r.current) >= 0;
+    var others = r.changed.filter(function(id){ return id !== r.current; });
+    if (here && r.first){
+      var first = r.first;
+      return say('Updated · ' + plural(r.count, 'change') + ' ↓', 'news', function(){ app.bring(first); }, 6000);
+    }
+    if (others.length === 1){
+      var id = others[0];
+      return say('Updated: ' + titleOf(id) + ' →', 'news', function(){ location.hash = '#/' + id; }, 6000);
+    }
+    if (others.length) return say(plural(others.length, 'document') + ' updated', 'news', null, 4000);
+    if (r.removed.length) return say(plural(r.removed.length, 'document') + ' removed', 'news', null, 4000);
+    if (here) return say('Updated', 'news', null, 2500);
+  }
+
+  function titleOf(id){ var d = app && app.doc(id); return d ? d.title : id; }
+
+  /* ---------------- saving settings ---------------- */
+
+  // The settings panel keeps its changes through here. Saving renders the page
+  // again, which changes the shell: this page already shows the new settings,
+  // so it takes the shell it is sent instead of reloading like the others.
+  var saving = 0;
+  if (app) app.save = function(settings){
+    saving++;
+    return fetch('/__lowkey-doc/settings', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(settings)
+    }).then(function(r){
+      return r.json().catch(function(){ return {}; }).then(function(body){
+        if (!r.ok) throw new Error(body.error || 'HTTP ' + r.status);
+        if (body.shell) shell = body.shell;
+      });
+    }).then(function(){ saving--; }, function(err){ saving--; throw err; });
+  };
+
+  /* ---------------- listening ---------------- */
+
+  if (!window.EventSource) return say('Live updates need a newer browser', 'off', null, 0);
+
+  var es = new EventSource('/__lowkey-doc/events');
+  es.addEventListener('state', function(e){
+    var s;
+    try { s = JSON.parse(e.data); } catch (x) { return; }
+    if (s.shell !== shell && !saving) return location.reload();
+    if (s.error){
+      failing = true;
+      say('Build failed — the page shows the last good version.\n' + s.error, 'bad', null, 0);
+    } else if (failing || down){
+      failing = false;
+      idle();
+    }
+    down = false;
+    if (s.version !== version) pull();
+  });
+  es.onerror = function(){
+    if (es.readyState === EventSource.CLOSED) return say('Live updates stopped — reload the page', 'off', null, 0);
+    down = true;
+    say('Disconnected — is lowkey-doc --watch still running?', 'off', null, 0);
+  };
+})();
+`;

package/src/collect.mjs

@@ -0,0 +1,154 @@
+// collect.mjs
+// ------------------------------------------------------------------
+// Turn a folder of files into the ordered, grouped list the sidebar shows,
+// then render each one.
+//
+// Ordering: a leading number wins ("2. CATALOG.md" before "10. TESTS.md",
+// which a plain sort gets backwards); everything else follows alphabetically.
+// Grouping: files sitting in the folder itself are one group, each sub-folder
+// is another named after itself, and anything that is not Markdown is grouped
+// by what it is (a schema dump, a data file) rather than shown as prose.
+// ------------------------------------------------------------------
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { esc, plain, slugify, inline, parkFences, renderBlocks } from './markdown.mjs';
+import { nestSections, SECNUM_RE } from './sections.mjs';
+import { titleCase } from './config.mjs';
+
+function orderKey(name) {
+  const m = name.match(/^(\d+)/);
+  return m ? String(+m[1]).padStart(4, '0') : 'zzz' + name.toLowerCase();
+}
+
+const extOf = (f) => (f.match(/\.[^.]+$/) || [''])[0].toLowerCase();
+
+function readDir(dir) {
+  if (!fs.existsSync(dir)) return { files: [], dirs: [] };
+  const entries = fs.readdirSync(dir, { withFileTypes: true }).filter((e) => !e.name.startsWith('.'));
+  return {
+    files: entries.filter((e) => e.isFile()).map((e) => e.name),
+    dirs: entries.filter((e) => e.isDirectory()).map((e) => e.name),
+  };
+}
+
+export function listDocs(cfg) {
+  const known = new Set([...cfg.extensions, ...Object.keys(cfg.verbatim)].map((e) => e.toLowerCase()));
+  const isDoc = (f) => cfg.extensions.includes(extOf(f));
+  const pick = (dir, rel) => readDir(dir).files
+    .filter((f) => known.has(extOf(f)))
+    .map((f) => ({ file: f, abs: path.join(dir, f), rel: rel ? rel + '/' + f : f }))
+    .sort((a, b) => orderKey(a.file).localeCompare(orderKey(b.file)));
+
+  const { dirs } = readDir(cfg.docsDir);
+  const root = pick(cfg.docsDir, '');
+
+  const out = [];
+  // 1. the documents themselves
+  for (const d of root.filter((d) => isDoc(d.file))) out.push({ ...d, group: cfg.rootGroup });
+
+  // 2. one group per sub-folder, in the configured order then alphabetically
+  const rank = (name) => {
+    const i = cfg.groupOrder.findIndex((g) => g.toLowerCase() === name.toLowerCase());
+    return i < 0 ? cfg.groupOrder.length : i;
+  };
+  const subs = dirs.slice().sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+  for (const sub of subs) {
+    const label = titleCase(sub);
+    for (const d of pick(path.join(cfg.docsDir, sub), sub)) out.push({ ...d, group: label });
+  }
+
+  // 3. whatever is not a document, grouped by what it is
+  for (const d of root.filter((d) => !isDoc(d.file))) {
+    out.push({ ...d, group: cfg.verbatim[extOf(d.file)] || 'Files' });
+  }
+  return out;
+}
+
+// Documents are addressed two ways: by the path a link actually writes
+// ("./audits/one.md") and, for convenience, by bare filename ("one.md") - the
+// second only where it is unambiguous, so two files called the same thing in
+// different folders never silently resolve to each other.
+export function assignIds(entries) {
+  const taken = new Set();
+  const map = new Map();
+  const seenName = new Map();
+  for (const e of entries) seenName.set(e.file, (seenName.get(e.file) || 0) + 1);
+
+  for (const e of entries) {
+    const stem = (seenName.get(e.file) > 1 ? e.rel : e.file).replace(/\.[^.]+$/, '');
+    let id = slugify(stem.replace(/\//g, '-')) || 'doc';
+    let n = 2;
+    const base = id;
+    while (taken.has(id)) id = base + '-' + n++;
+    taken.add(id);
+    map.set(e.rel, id);
+    if (seenName.get(e.file) === 1) map.set(e.file, id);
+  }
+  return map;
+}
+
+export function buildDoc(entry, byFile, cfg, raw = fs.readFileSync(entry.abs, 'utf8')) {
+  const name = entry.file.replace(/\.[^.]+$/, '');
+  const id = byFile.get(entry.file);
+  const seen = new Map();
+  const ctx = {
+    blocks: [], headings: [], byFile, numbers: new Map(),
+    uniqueSlug(base) {
+      const key = base || 'section';
+      const n = seen.get(key) || 0;
+      seen.set(key, n + 1);
+      return n ? key + '-' + n : key;
+    },
+  };
+
+  let title = name, subtitle = '', html;
+
+  if (cfg.extensions.includes(extOf(entry.file))) {
+    const lines = parkFences(raw, ctx);
+
+    // H1 becomes the page title
+    const h1 = lines.findIndex((l) => /^# +\S/.test(l));
+    if (h1 >= 0) {
+      title = plain(lines[h1].replace(/^# +/, ''));
+      lines.splice(h1, 1);
+    }
+
+    // the lede paragraph of the blockquote under it becomes the subtitle
+    let j = 0;
+    while (j < lines.length && !lines[j].trim()) j++;
+    if (j < lines.length && /^ {0,3}>/.test(lines[j])) {
+      const lede = [];
+      while (j < lines.length && /^ {0,3}>/.test(lines[j]) && lines[j].replace(/^ {0,3}> ?/, '').trim()) {
+        lede.push(lines[j].replace(/^ {0,3}> ?/, '').trim());
+        j++;
+      }
+      subtitle = inline(lede.join(' '), ctx);
+      lines.splice(0, j);
+    }
+
+    html = nestSections(renderBlocks(lines, ctx, true), ctx);
+  } else {
+    const kind = extOf(entry.file).slice(1);
+    subtitle = 'Kept verbatim as <code>' + esc(kind) + '</code>.';
+    html = '<div class="code-wrap"><span class="code-lang">' + esc(kind) +
+      '</span><pre class="code"><code>' + esc(raw) + '</code></pre></div>';
+  }
+
+  const badge = (name.match(/^(\d+)/) || [])[1] || (name.trim()[0] || '?').toUpperCase();
+
+  return {
+    id, title, subtitle, html, badge,
+    group: entry.group,
+    file: entry.rel || entry.file,
+    words: raw.split(/\s+/).filter(Boolean).length,
+    // counted from the rendered page, not from the fences found: a diagram
+    // inside an HTML comment is parked like any other but never emitted
+    diagrams: (html.match(/data-diagram/g) || []).length,
+    sections: ctx.headings.filter((h) => h.level <= 2).map((h) => {
+      const num = ctx.numbers.get(h.id) || '';
+      const own = h.text.match(SECNUM_RE);
+      return { id: h.id, num, text: own && own[1] === num ? h.text.slice(own[0].length) : h.text };
+    }),
+  };
+}

package/src/config.mjs

@@ -0,0 +1,166 @@
+// config.mjs
+// ------------------------------------------------------------------
+// Everything the builder needs to know about one project, resolved from
+// (in increasing priority): the defaults below, a docs.config.json found
+// next to the documents or at the project root, and the command line.
+//
+// Zero configuration is a supported way to run: point the tool at a folder
+// of Markdown and it renders.
+// ------------------------------------------------------------------
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// the range layout.margin can take, and the page's slider with it
+export const MARGIN_MIN = 20, MARGIN_MAX = 480;
+
+export const CONFIG_NAMES = ['docs.config.json', '.lowkey-doc.json'];
+
+export const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+// What to tell people to type: npm sets npm_command to "exec" under npx, and
+// someone running it that way has no lowkey-doc on their PATH.
+export const CLI = process.env.npm_command === 'exec' ? 'npx lowkey-doc' : 'lowkey-doc';
+
+const DEFAULTS = {
+  // Shown in the sidebar, the browser tab, and used to namespace the
+  // per-reader state (which document was open, folded sections, comments).
+  title: null,                       // null -> derived from the project folder
+  // Where the documents are, relative to the project root.
+  docs: 'docs',
+  // Where the built page goes, relative to the project root.
+  out: '.lowkey-doc',
+  // Files taken as documents. Markdown is rendered; everything else is shown
+  // verbatim in a code block, which is how schema dumps stay readable.
+  extensions: ['.md', '.markdown'],
+  verbatim: {
+    '.dbml': 'Schema',
+    '.dbdiagram': 'Schema',
+    '.sql': 'Schema',
+    '.json': 'Data',
+    '.yaml': 'Data',
+    '.yml': 'Data',
+    '.tsv': 'Data',
+    '.csv': 'Data',
+  },
+  // The sidebar heading for documents sitting directly in the docs folder.
+  rootGroup: 'Documents',
+  // Sub-folders become their own group, named after the folder. List them here
+  // to fix the order; anything not listed follows, alphabetically.
+  groupOrder: [],
+  diagrams: {
+    // 'clean'   - re-lay flowcharts and ER diagrams out with ELK: right-angled
+    //             routes, every edge label given its own reserved space and tied
+    //             to its arc, and entities drawn as tables rather than grids.
+    // 'mermaid' - mermaid's own renderer for everything.
+    // Either way the reader can switch per diagram from the page.
+    engine: 'clean',
+    // Cap on how wide a node's text runs before it wraps, in pixels.
+    nodeTextWidth: 210,
+    edgeTextWidth: 200,
+  },
+  layout: {
+    // The room either side of the text, from the edge of the reading area to
+    // where the text starts, in pixels. null keeps the column at its reading
+    // width and centres it, so the room either side is whatever is left over.
+    // Set from the page itself too: the settings button in the sidebar.
+    margin: null,
+  },
+  // Reader features. Turn off what a given project does not want.
+  comments: true,
+  search: true,
+};
+
+const titleCase = (s) => s
+  .replace(/[-_]+/g, ' ')
+  .replace(/\s+/g, ' ')
+  .trim()
+  .replace(/^\p{Ll}/u, (c) => c.toUpperCase());
+
+function deepMerge(base, over) {
+  if (!over || typeof over !== 'object' || Array.isArray(over)) return over === undefined ? base : over;
+  const out = Array.isArray(base) ? base.slice() : { ...base };
+  for (const [k, v] of Object.entries(over)) {
+    out[k] = (v && typeof v === 'object' && !Array.isArray(v) && base && typeof base[k] === 'object')
+      ? deepMerge(base[k], v)
+      : v;
+  }
+  return out;
+}
+
+// Look for a config file next to the documents, then up the tree from there.
+export function findConfig(startDir) {
+  let dir = path.resolve(startDir);
+  for (let hop = 0; hop < 12; hop++) {
+    for (const name of CONFIG_NAMES) {
+      const file = path.join(dir, name);
+      if (fs.existsSync(file)) return file;
+    }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// `folder` is a documents folder named on the command line. It replaces the
+// configured `docs` and nothing else: the config is still looked for, from
+// that folder upwards, and the page still goes to the project root - the
+// config's folder, or else wherever the command was run.
+export function loadConfig({ root, docs, folder, out, title, configPath, engine }) {
+  let file = configPath ? path.resolve(configPath) : null;
+  if (file && !fs.existsSync(file)) throw new Error('No config file at ' + file);
+  if (!file) file = findConfig(folder || root || process.cwd());
+
+  let fromFile = {};
+  if (file) {
+    try {
+      fromFile = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (err) {
+      throw new Error('Could not read ' + file + ': ' + err.message);
+    }
+  }
+
+  // The project root is the config file's folder, or wherever we were pointed.
+  const projectRoot = path.resolve(root || (file ? path.dirname(file) : process.cwd()));
+
+  const cfg = deepMerge(DEFAULTS, fromFile);
+  // `verbatim` is a list of what to include, not a bag of settings: writing one
+  // replaces the defaults, so a project can narrow it rather than only add to it.
+  if (fromFile.verbatim) cfg.verbatim = fromFile.verbatim;
+  if (docs) cfg.docs = docs;
+  if (folder) cfg.docs = path.relative(projectRoot, folder) || '.';
+  if (out) cfg.out = out;
+  if (title) cfg.title = title;
+  if (engine) cfg.diagrams = { ...cfg.diagrams, engine };
+
+  cfg.root = projectRoot;
+  cfg.docsDir = path.resolve(projectRoot, cfg.docs);
+  cfg.outDir = path.resolve(projectRoot, cfg.out);
+  cfg.configFile = file;
+  if (!cfg.title) cfg.title = titleCase(path.basename(projectRoot)) + ' Docs';
+
+  // Namespace for everything the reader's browser remembers. Two dashboards
+  // opened from file:// can otherwise land in the same storage bucket.
+  cfg.ns = 'lowkey-doc:' + cfg.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+  const margin = cfg.layout && cfg.layout.margin;
+  if (margin != null && !(Number.isFinite(margin) && margin >= MARGIN_MIN && margin <= MARGIN_MAX)) {
+    throw new Error('layout.margin must be null or a number of pixels from ' + MARGIN_MIN + ' to ' +
+      MARGIN_MAX + ', got: ' + JSON.stringify(margin));
+  }
+  if (!['clean', 'mermaid'].includes(cfg.diagrams.engine)) {
+    throw new Error("diagrams.engine must be 'clean' or 'mermaid', got: " + cfg.diagrams.engine);
+  }
+  return cfg;
+}
+
+// A config object as text, written the way the file already was: its indent,
+// its line endings. `before` is the file's old text, or null for a new file.
+export function jsonLike(before, obj) {
+  const indent = (before && (before.match(/\n([ \t]+)"/) || [])[1]) || 2;
+  const eol = before && before.includes('\r\n') ? '\r\n' : '\n';
+  return (JSON.stringify(obj, null, indent) + '\n').replace(/\n/g, eol);
+}
+
+export { DEFAULTS, titleCase };

package/src/init.mjs

@@ -0,0 +1,103 @@
+// init.mjs - wire an existing project up to the dashboard.
+//
+// Writes a docs.config.json if there isn't one, creates the documents folder
+// it names, and installs the Claude Code command and skills into the
+// project's .claude/ folder so the agent working in that repo knows how to
+// write and render its documents.
+//
+// A config that already exists is never replaced: --docs and --title edit just
+// those fields in it. --force is about the Claude files only - it replaces
+// them with this version's copies.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_NAMES, DEFAULTS, VERSION, jsonLike, titleCase } from './config.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG = path.resolve(HERE, '..');
+
+// The Claude files run the version that installed them, never whatever is
+// newest on npm: a new release reaches a project when someone there runs
+// init --force, not the next time an agent renders the docs.
+function copyPinned(from, to) {
+  if (!from.endsWith('.md')) return fs.copyFileSync(from, to);
+  fs.writeFileSync(to, fs.readFileSync(from, 'utf8').replace(/npx lowkey-doc(?!@)/g, 'npx lowkey-doc@' + VERSION));
+}
+
+function copyTree(from, to) {
+  fs.mkdirSync(to, { recursive: true });
+  for (const e of fs.readdirSync(from, { withFileTypes: true })) {
+    const a = path.join(from, e.name), b = path.join(to, e.name);
+    if (e.isDirectory()) copyTree(a, b);
+    else copyPinned(a, b);
+  }
+}
+
+export function init(target, { docs = null, title = null, force = false } = {}) {
+  const root = path.resolve(target || process.cwd());
+  const done = [];
+  const skipped = [];
+  let kept = false;   // a Claude file was left as it was
+
+  if (!fs.existsSync(root)) {
+    fs.mkdirSync(root, { recursive: true });
+    done.push(path.relative(process.cwd(), root) + '/');
+  } else if (!fs.statSync(root).isDirectory()) {
+    throw new Error('Not a folder: ' + root);
+  }
+
+  const existing = CONFIG_NAMES.map((n) => path.join(root, n)).find((f) => fs.existsSync(f));
+  let config;
+  if (existing) {
+    const before = fs.readFileSync(existing, 'utf8');
+    try {
+      config = JSON.parse(before);
+    } catch (err) {
+      throw new Error('Could not read ' + existing + ': ' + err.message);
+    }
+    const changed = Object.entries({ docs, title }).filter(([k, v]) => v != null && config[k] !== v);
+    for (const [k, v] of changed) config[k] = v;
+    if (changed.length) {
+      fs.writeFileSync(existing, jsonLike(before, config));
+      done.push(path.basename(existing) + ' (' + changed.map(([k, v]) => k + ': ' + JSON.stringify(v)).join(', ') + ')');
+    } else {
+      skipped.push(path.basename(existing) + ' (already there)');
+    }
+  } else {
+    config = {
+      title: title || titleCase(path.basename(root)) + ' Docs',
+      docs: docs || DEFAULTS.docs,
+      out: DEFAULTS.out,
+    };
+    fs.writeFileSync(path.join(root, CONFIG_NAMES[0]), jsonLike(null, config));
+    done.push(CONFIG_NAMES[0]);
+  }
+
+  // the folder the config names, so the next build has somewhere to read
+  const docsDir = path.resolve(root, config.docs || DEFAULTS.docs);
+  if (!fs.existsSync(docsDir)) {
+    fs.mkdirSync(docsDir, { recursive: true });
+    fs.writeFileSync(path.join(docsDir, '0. ABOUT.md'),
+      '# ABOUT\n\n> What this project is, in plain language.\n\n---\n\n## Start here\n\nReplace this file with the real thing.\n');
+    done.push(path.relative(root, docsDir) + '/');
+  }
+
+  // the agent-facing half: one command to render, two skills to write and audit
+  const claude = path.join(root, '.claude');
+  for (const [src, dest] of [
+    [path.join(PKG, 'commands', 'docs.md'), path.join(claude, 'commands', 'docs.md')],
+    [path.join(PKG, 'skills', 'write-doc'), path.join(claude, 'skills', 'write-doc')],
+    [path.join(PKG, 'skills', 'audit-docs'), path.join(claude, 'skills', 'audit-docs')],
+  ]) {
+    if (!fs.existsSync(src)) continue;
+    const there = fs.existsSync(dest);
+    if (there && !force) { skipped.push(path.relative(root, dest) + ' (already there)'); kept = true; continue; }
+    // replaced whole, so a file an older version shipped does not linger
+    if (fs.statSync(src).isDirectory()) { fs.rmSync(dest, { recursive: true, force: true }); copyTree(src, dest); }
+    else { fs.mkdirSync(path.dirname(dest), { recursive: true }); copyPinned(src, dest); }
+    done.push(path.relative(root, dest) + (there ? ' (replaced)' : ''));
+  }
+
+  return { root, done, skipped, kept };
+}