@cr8rcho/alkahest 0.1.92 → 0.1.94

package/presets/as-built/history/c8301f8ce329dd96

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// alkahest as-built preset — docs sync ENGINE. Do not edit this file: `alkahest preset update`
+// replaces it with the preset's current version. Everything repo-specific (project, which docs
+// go to which map, title rules, extra files) lives in scripts/sync-docs-maps.config.mjs, which
+// the update never touches.
+//
+// Mirrors docs/ into the project's note maps:
+//   docs/decisions/NNN-*.md                        → note map `adr`      (flat)
+//   docs/{system,components,features,modules}/*.md → note map `as-built` (folder = category)
+//
+// Staging (the importer's rules: filename = title, frontmatter passes through):
+//   - title from the first H1 ("ADR-NNN: rest — tail" → "ADR-NNN rest"; as-built strips a
+//     "System|Component|Feature|Module — " class prefix and a " — " tail), sanitized — or the
+//     config's `title()` when it returns one;
+//   - the H1 line is dropped from the body (the note title renders it);
+//   - relative .md links to another synced doc become [[wikilinks]] (within the same map by
+//     default; `links: "all"` also across maps);
+//   - the ORIGINAL repo path rides in as `source_path:` frontmatter, which keeps identity through
+//     a retitle (the importer matches source_path before title and renames the note in place).
+//
+// Re-running is safe: import is idempotent by source_path, then title.
+// Usage: node scripts/sync-docs-maps.mjs [--stage-only | --dry-run]
+//   --stage-only  write the staged files and stop (the dir is kept and printed)
+//   --dry-run     stage, then ask the importer for its plan without writing anything
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(HERE, "..");
+const CONFIG_FILE = join(HERE, "sync-docs-maps.config.mjs");
+const config = existsSync(CONFIG_FILE) ? ((await import(pathToFileURL(CONFIG_FILE).href)).default ?? {}) : {};
+
+const DOCS = join(ROOT, config.docsDir ?? "docs");
+const PROJECT = config.project ?? process.env.ALKAHEST_PROJECT;
+const STAGE_ONLY = process.argv.includes("--stage-only");
+const DRY_RUN = process.argv.includes("--dry-run");
+const LINKS = config.links ?? "set";
+const SETS = config.sets ?? [
+  { map: "adr", kind: "adr", dirs: ["decisions"], match: /^\d{3}-.*\.md$/, folders: false },
+  { map: "as-built", kind: "as-built", dirs: ["system", "components", "features", "modules"], folders: true },
+];
+
+// ---- helpers -----------------------------------------------------------------
+const sanitize = (t) =>
+  t.replace(/\(\//g, "(").replace(/[/\\:]/g, "-").replace(/`/g, "").replace(/\s+/g, " ").trim();
+// A config title is kept as written — only what can't live in a filename is replaced.
+const fileSafe = (t) => t.replace(/[/\\]/g, "-").trim();
+const posix = (p) => p.split(sep).join("/");
+const firstH1 = (src) => (src.match(/^#\s+(.+)$/m) ?? [null, ""])[1].trim();
+// Frontmatter rides through to the staged file — the importer strips it from the stored body
+// and harvests its keys into note props (`tags:` is the reserved one). Split it off first so
+// stripH1 still sees the H1 at the head of what's left.
+const splitFm = (src) => {
+  const m = src.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n+/);
+  return m ? [m[0], src.slice(m[0].length)] : ["", src];
+};
+const stripH1 = (src) => {
+  const [fm, body] = splitFm(src);
+  return fm + body.replace(/^#\s+.+\n+/, "");
+};
+const withSource = (staged, rel) => {
+  const [fm, body] = splitFm(staged);
+  const line = `source_path: ${rel}\n`;
+  return fm ? fm.replace(/---\r?\n*$/, (close) => line + close) + body : `---\n${line}---\n\n${staged}`;
+};
+
+/** The preset's own title rules, per set kind. */
+function defaultTitle(kind, file, h1) {
+  if (kind === "adr") {
+    // Convention "ADR-NNN: title — tail"; the em-dash variant "ADR-NNN — title" also parses.
+    const m = h1.match(/^ADR-(\d{3})(?::|\s+—)\s*(.+)$/);
+    const num = m ? m[1] : basename(file).slice(0, 3);
+    return sanitize(`ADR-${num} ${(m ? m[2] : h1).split(" — ")[0].trim()}`);
+  }
+  if (kind === "as-built") {
+    const t = h1.replace(/^(System|Component|Feature|Module)\s*—\s*/i, "").split(" — ")[0].trim();
+    return sanitize(t || h1);
+  }
+  return sanitize(h1 || basename(file, ".md"));
+}
+
+// ---- collect -----------------------------------------------------------------
+const docs = []; // { rel (to DOCS), map, folder, src, title }
+for (const set of SETS) {
+  for (const d of set.dirs ?? []) {
+    const dir = join(DOCS, d);
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir).sort()) {
+      if (!f.endsWith(".md") || (set.match && !set.match.test(f))) continue;
+      docs.push({ rel: posix(join(d, f)), map: set.map, kind: set.kind, folder: set.folders ? d : null });
+    }
+  }
+  for (const f of config.extra?.[set.map] ?? []) {
+    if (existsSync(join(DOCS, f))) docs.push({ rel: posix(f), map: set.map, kind: set.kind, folder: null });
+  }
+}
+for (const doc of docs) {
+  doc.src = readFileSync(join(DOCS, doc.rel), "utf8");
+  const h1 = firstH1(doc.src);
+  const fallback = defaultTitle(doc.kind, doc.rel, h1);
+  const custom = config.title?.({ map: doc.map, kind: doc.kind, path: doc.rel, h1, defaultTitle: fallback });
+  doc.title = custom ? fileSafe(custom) : fallback;
+}
+
+// ---- links → [[wikilinks]] -----------------------------------------------------
+const byRel = new Map(docs.map((d) => [d.rel, d]));
+const byName = new Map(); // `${map}/${basename}` → docs (the fallback for bare `name.md` links)
+for (const d of docs) {
+  const k = `${d.map}/${basename(d.rel)}`;
+  byName.set(k, [...(byName.get(k) ?? []), d]);
+}
+const LINK = /\[([^\]]*)\]\(([^)\s]+\.md)(#[^)\s]*)?\)/g;
+function linkify(doc, body) {
+  return body.replace(LINK, (whole, _label, href) => {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("/")) return whole;
+    const rel = posix(relative(DOCS, resolve(DOCS, dirname(doc.rel), href)));
+    let target = byRel.get(rel);
+    if (!target) {
+      const same = byName.get(`${doc.map}/${basename(href)}`);
+      if (same?.length === 1) target = same[0];
+    }
+    // ADRs are addressed by number: a link whose slug went stale after a retitle still names
+    // the right record (`./030-old-slug.md` → ADR-030).
+    const num = !target && /^(\d{3})-/.exec(basename(href))?.[1];
+    if (num) {
+      const adr = docs.filter((d) => d.kind === "adr" && basename(d.rel).startsWith(`${num}-`));
+      if (adr.length === 1) target = adr[0];
+    }
+    if (!target || (LINKS !== "all" && target.map !== doc.map)) return whole;
+    return `[[${target.title}]]`;
+  });
+}
+
+// ---- stage -----------------------------------------------------------------------
+// A fresh dir per run: a fixed shared path let another repo's copy of this script, running at the
+// same time, restage its own docs under us, and our import pushed them into this project's maps.
+const OUT = mkdtempSync(join(tmpdir(), "alkahest-docs-staging-"));
+const maps = [...new Set(SETS.map((s) => s.map))];
+for (const doc of docs) {
+  const dir = join(OUT, doc.map, ...(doc.folder ? doc.folder.split("/") : []));
+  mkdirSync(dir, { recursive: true });
+  const docsRel = posix(relative(ROOT, join(DOCS, doc.rel)));
+  writeFileSync(join(dir, `${doc.title}.md`), withSource(linkify(doc, stripH1(doc.src)), docsRel));
+}
+for (const m of maps) mkdirSync(join(OUT, m), { recursive: true });
+console.log(`staged ${maps.map((m) => `${docs.filter((d) => d.map === m).length} ${m}`).join(" + ")} docs → ${OUT}`);
+if (STAGE_ONLY) process.exit(0);
+
+// ---- import ------------------------------------------------------------------------
+const scope = ["--path", ROOT, ...(PROJECT ? ["--slug", PROJECT] : [])];
+if (PROJECT) console.log(`project: ${PROJECT}`);
+
+// A note map that doesn't exist yet is created (the preset install makes them, but a repo can
+// add a set or move projects). Skipped on --dry-run: a plan must not create anything.
+if (!DRY_RUN && config.createMaps !== false) {
+  const list = spawnSync("alkahest", ["maps", "list", ROOT, ...(PROJECT ? ["--slug", PROJECT] : [])], { encoding: "utf8" });
+  const have = list.status === 0 ? list.stdout : null;
+  for (const m of maps) {
+    if (have === null || new RegExp(`(^|[^\\w-])${m.replace(/[-]/g, "\\-")}([^\\w-]|$)`, "m").test(have)) continue;
+    console.log(`[sync] creating note map '${m}'`);
+    spawnSync("alkahest", ["maps", "create", m, "--type", "note", ...scope], { stdio: "inherit" });
+  }
+}
+
+// A full mirror is many sequential POSTs, so a transient failure is a question of when, not
+// if. The CLI handles it per file (keeps going, prints `✗ <file>: <message>`, exits 1) — act
+// on the exit code and retry the whole set: rows that already landed come back as updates.
+const ATTEMPTS = DRY_RUN ? 1 : 3;
+const failed = [];
+for (const m of maps) {
+  let ok = false;
+  for (let attempt = 1; attempt <= ATTEMPTS && !ok; attempt++) {
+    console.log(`\n== notes import ${m} → map ${m}${DRY_RUN ? " (dry run)" : ""}${attempt > 1 ? ` (retry ${attempt - 1})` : ""} ==`);
+    const run = spawnSync("alkahest", ["notes", "import", join(OUT, m), "--map", m, ...scope, ...(DRY_RUN ? ["--dry-run"] : [])], {
+      stdio: "inherit",
+    });
+    if (run.error) console.error(`[sync] could not run alkahest: ${run.error.message}`);
+    ok = !run.error && run.status === 0;
+    if (!ok && attempt < ATTEMPTS) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5000);
+  }
+  if (!ok) failed.push(m);
+}
+
+if (failed.length) {
+  console.error(`\n[sync] FAILED after ${ATTEMPTS} attempt(s): ${failed.join(", ")}`);
+  console.error("[sync] scroll up for the per-file '✗ <file>: <message>' lines from the importer.");
+  console.error(`[sync] staged files kept for inspection: ${OUT}`);
+  process.exit(1);
+}
+// The staging dir is this run's own, so removing it touches no other sync. Kept on
+// --stage-only (that's what it's for) and on failure (above).
+rmSync(OUT, { recursive: true, force: true });
+console.log(DRY_RUN ? "\n[sync] dry run done — nothing written." : `\n[sync] ${maps.join(" + ")} up to date.`);

package/presets/as-built/history/fa58e822a0e3f4f4

@@ -0,0 +1,26 @@
+<!-- alkahest as-built preset — installed by `alkahest preset install as-built`. Owned by this repo: edit freely; `alkahest preset update` merges later preset changes into your edits. -->
+## Documentation — as-built docs + ADR
+
+This repo keeps **as-built documentation** under `docs/` (four layers: system / components /
+features / modules — see docs/README.md) and **ADRs** under `docs/decisions/`. The writing
+instructions live in the account skills `alkahest/as-built-docs` and `alkahest/adr` — read them via the
+alkahest MCP `skills` tool before writing docs.
+
+1. **After finishing any code change, update the affected docs in the same session.**
+   The layer mapping and the update checklist are in the `alkahest/as-built-docs` skill. Write an
+   ADR only for decisions whose "why" a code diff cannot reconstruct (criteria and the
+   template are in the `alkahest/adr` skill).
+2. **First documentation pass (repo has no docs yet)?** Follow the bootstrap protocol in
+   the `alkahest/as-built-docs` skill: one system map + 2–3 core modules + ADR-001 (architecture
+   snapshot) — small first, then mirror and hand the user the note-map link. Grow the rest
+   incrementally with later work.
+3. **After changing `docs/`, mirror it to the hosted note maps** by running
+   `node scripts/sync-docs-maps.mjs` (background recommended — one POST per document).
+   The script stages the docs (title from the first H1, H1 line stripped, intra-set
+   relative links → `[[wikilinks]]`, the original repo path injected as `source_path:`
+   frontmatter) and uploads with `alkahest notes import --map <adr|as-built>`. The import
+   is idempotent by source_path first, title second — re-runs and retitles update notes in
+   place. The script is the preset's engine — don't edit it (`alkahest preset update` replaces
+   it). This repo's settings (project, extra files, title rules, which folders go to which map)
+   live in `scripts/sync-docs-maps.config.mjs`, which updates never touch.
+<!-- /alkahest as-built preset -->

package/presets/as-built/history.json

@@ -40,6 +40,10 @@
       {
         "sha": "2eb353c13db7e5a7",
         "since": "0.1.92"
+      },
+      {
+        "sha": "c8301f8ce329dd96",
+        "since": "0.1.94"
       }
     ],
     "CLAUDE-snippet.md": [
@@ -54,6 +58,10 @@
       {
         "sha": "96497831c905de56",
         "since": "0.1.91"
+      },
+      {
+        "sha": "fa58e822a0e3f4f4",
+        "since": "0.1.94"
       }
     ]
   }

package/presets/as-built/preset.json

@@ -17,7 +17,13 @@
   "scripts": [
     {
       "file": "sync-docs-maps.mjs",
-      "dest": "scripts/sync-docs-maps.mjs"
+      "dest": "scripts/sync-docs-maps.mjs",
+      "owner": "preset"
+    },
+    {
+      "file": "sync-docs-maps.config.mjs",
+      "dest": "scripts/sync-docs-maps.config.mjs",
+      "owner": "repo"
     }
   ],
   "maps": [

package/presets/as-built/sync-docs-maps.config.mjs

@@ -0,0 +1,31 @@
+// Settings for scripts/sync-docs-maps.mjs (alkahest as-built preset) — this file is the REPO'S.
+// `alkahest preset update` replaces the sync engine next to it but never touches this file, so
+// everything that makes this repo's docs sync its own goes here. Every key is optional: an empty
+// object is the preset's default behaviour.
+export default {
+  // The alkahest project to sync into. Default: the project this folder is linked to
+  // (`.alkahest/project.json`), or the ALKAHEST_PROJECT environment variable.
+  // project: "my-project-1a2b3c",
+
+  // Where the docs live, relative to the repo root.
+  // docsDir: "docs",
+
+  // Extra files (relative to docsDir) to mirror into a map, beyond its folders.
+  // extra: { "as-built": ["README.md"] },
+
+  // Note titles. Return a string to replace the preset's title for a doc, or nothing to keep it.
+  // Titles are how existing notes are matched, so change them deliberately (then run --stage-only).
+  // title: ({ map, kind, path, h1, defaultTitle }) => (map === "adr" ? h1 : undefined),
+
+  // Relative .md links become [[wikilinks]] within each map ("set", default) or across maps ("all").
+  // links: "set",
+
+  // Which folders go to which note map. Default:
+  // sets: [
+  //   { map: "adr", kind: "adr", dirs: ["decisions"], match: /^\d{3}-.*\.md$/, folders: false },
+  //   { map: "as-built", kind: "as-built", dirs: ["system", "components", "features", "modules"], folders: true },
+  // ],
+
+  // Create a missing note map before importing (default true).
+  // createMaps: true,
+};

package/presets/as-built/sync-docs-maps.mjs

@@ -1,36 +1,54 @@
 #!/usr/bin/env node
-// Reference implementation (alkahest as-built preset) — mirror this repo's docs into the
-// project's note maps:
+// alkahest as-built preset — docs sync ENGINE. Do not edit this file: `alkahest preset update`
+// replaces it with the preset's current version. Everything repo-specific (project, which docs
+// go to which map, title rules, extra files) lives in scripts/sync-docs-maps.config.mjs, which
+// the update never touches.
+//
+// Mirrors docs/ into the project's note maps:
 //   docs/decisions/NNN-*.md                        → note map `adr`      (flat)
 //   docs/{system,components,features,modules}/*.md → note map `as-built` (folder = category)
 //
-// Staging transforms (the importer's rules: filename = title, frontmatter passes through):
+// Staging (the importer's rules: filename = title, frontmatter passes through):
 //   - title from the first H1 ("ADR-NNN: rest — tail" → "ADR-NNN rest"; as-built strips a
-//     "System|Component|Feature|Module — " class prefix and a " — " tail), sanitized;
+//     "System|Component|Feature|Module — " class prefix and a " — " tail), sanitized — or the
+//     config's `title()` when it returns one;
 //   - the H1 line is dropped from the body (the note title renders it);
-//   - relative .md links WITHIN each set become [[wikilinks]] so the graph connects
-//     (cross-set links stay plain markdown);
-//   - the ORIGINAL repo path rides in as `source_path:` frontmatter — the staged filename
-//     is title-derived, so this is what keeps identity through a retitle (the importer
-//     matches source_path before title and renames the note in place).
+//   - relative .md links to another synced doc become [[wikilinks]] (within the same map by
+//     default; `links: "all"` also across maps);
+//   - the ORIGINAL repo path rides in as `source_path:` frontmatter, which keeps identity through
+//     a retitle (the importer matches source_path before title and renames the note in place).
 //
 // Re-running is safe: import is idempotent by source_path, then title.
-// This script belongs to the repo it lives in — adapt titles/sets/maps to local conventions.
-// Usage: node scripts/sync-docs-maps.mjs [--stage-only]
-import { readdirSync, readFileSync, mkdirSync, writeFileSync, mkdtempSync } from "node:fs";
+// Usage: node scripts/sync-docs-maps.mjs [--stage-only | --dry-run]
+//   --stage-only  write the staged files and stop (the dir is kept and printed)
+//   --dry-run     stage, then ask the importer for its plan without writing anything
 import { spawnSync } from "node:child_process";
-import { join, dirname, basename } from "node:path";
-import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
-const DOCS = join(ROOT, "docs");
-// A fresh dir per run: a fixed shared path let another repo's copy of this script, running at the
-// same time, restage its own docs under us, and our import pushed them into this project's maps.
-const OUT = mkdtempSync(join(tmpdir(), "alkahest-docs-staging-"));
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(HERE, "..");
+const CONFIG_FILE = join(HERE, "sync-docs-maps.config.mjs");
+const config = existsSync(CONFIG_FILE) ? ((await import(pathToFileURL(CONFIG_FILE).href)).default ?? {}) : {};
+
+const DOCS = join(ROOT, config.docsDir ?? "docs");
+const PROJECT = config.project ?? process.env.ALKAHEST_PROJECT;
+const STAGE_ONLY = process.argv.includes("--stage-only");
+const DRY_RUN = process.argv.includes("--dry-run");
+const LINKS = config.links ?? "set";
+const SETS = config.sets ?? [
+  { map: "adr", kind: "adr", dirs: ["decisions"], match: /^\d{3}-.*\.md$/, folders: false },
+  { map: "as-built", kind: "as-built", dirs: ["system", "components", "features", "modules"], folders: true },
+];
 
+// ---- helpers -----------------------------------------------------------------
 const sanitize = (t) =>
   t.replace(/\(\//g, "(").replace(/[/\\:]/g, "-").replace(/`/g, "").replace(/\s+/g, " ").trim();
+// A config title is kept as written — only what can't live in a filename is replaced.
+const fileSafe = (t) => t.replace(/[/\\]/g, "-").trim();
+const posix = (p) => p.split(sep).join("/");
 const firstH1 = (src) => (src.match(/^#\s+(.+)$/m) ?? [null, ""])[1].trim();
 // Frontmatter rides through to the staged file — the importer strips it from the stored body
 // and harvests its keys into note props (`tags:` is the reserved one). Split it off first so
@@ -43,88 +61,136 @@ const stripH1 = (src) => {
   const [fm, body] = splitFm(src);
   return fm + body.replace(/^#\s+.+\n+/, "");
 };
-// Rename-safe identity: inject the ORIGINAL repo path as source_path: frontmatter (merged
-// into an existing block, or a new block is minted).
 const withSource = (staged, rel) => {
   const [fm, body] = splitFm(staged);
   const line = `source_path: ${rel}\n`;
   return fm ? fm.replace(/---\r?\n*$/, (close) => line + close) + body : `---\n${line}---\n\n${staged}`;
 };
 
-// ---- ADRs ------------------------------------------------------------------
-const adrDir = join(DOCS, "decisions");
-const adrFiles = readdirSync(adrDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
-const adrTitle = {};
-for (const f of adrFiles) {
-  const h1 = firstH1(readFileSync(join(adrDir, f), "utf8"));
-  // Convention "ADR-NNN: title — tail"; the em-dash variant "ADR-NNN — title" also parses.
-  const m = h1.match(/^ADR-(\d{3})(?::|\s+—)\s*(.+)$/);
-  const num = m ? m[1] : f.slice(0, 3);
-  adrTitle[num] = sanitize(`ADR-${num} ${(m ? m[2] : h1).split(" — ")[0].trim()}`);
-}
-const linkAdrs = (body) =>
-  body.replace(/\[([^\]]*)\]\((?:\.\/)?(\d{3})-[^)#\s]*\.md(?:#[^)]*)?\)/g, (all, _label, num) =>
-    adrTitle[num] ? `[[${adrTitle[num]}]]` : all);
-mkdirSync(join(OUT, "adr"), { recursive: true });
-for (const f of adrFiles) {
-  const t = adrTitle[f.slice(0, 3)];
-  const staged = linkAdrs(stripH1(readFileSync(join(adrDir, f), "utf8")));
-  writeFileSync(join(OUT, "adr", `${t}.md`), withSource(staged, `docs/decisions/${f}`));
+/** The preset's own title rules, per set kind. */
+function defaultTitle(kind, file, h1) {
+  if (kind === "adr") {
+    // Convention "ADR-NNN: title — tail"; the em-dash variant "ADR-NNN — title" also parses.
+    const m = h1.match(/^ADR-(\d{3})(?::|\s+—)\s*(.+)$/);
+    const num = m ? m[1] : basename(file).slice(0, 3);
+    return sanitize(`ADR-${num} ${(m ? m[2] : h1).split(" — ")[0].trim()}`);
+  }
+  if (kind === "as-built") {
+    const t = h1.replace(/^(System|Component|Feature|Module)\s*—\s*/i, "").split(" — ")[0].trim();
+    return sanitize(t || h1);
+  }
+  return sanitize(h1 || basename(file, ".md"));
 }
 
-// ---- as-built --------------------------------------------------------------
-const cats = ["system", "components", "features", "modules"];
-const abTitle = {};
-const abSrc = {};
-for (const cat of cats) {
-  for (const f of readdirSync(join(DOCS, cat)).filter((x) => x.endsWith(".md"))) {
-    const src = readFileSync(join(DOCS, cat, f), "utf8");
-    let t = firstH1(src).replace(/^(System|Component|Feature|Module)\s*—\s*/i, "");
-    t = t.split(" — ")[0].trim() || firstH1(src);
-    abTitle[basename(f, ".md")] = sanitize(t);
-    abSrc[basename(f, ".md")] = { cat, src };
+// ---- collect -----------------------------------------------------------------
+const docs = []; // { rel (to DOCS), map, folder, src, title }
+for (const set of SETS) {
+  for (const d of set.dirs ?? []) {
+    const dir = join(DOCS, d);
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir).sort()) {
+      if (!f.endsWith(".md") || (set.match && !set.match.test(f))) continue;
+      docs.push({ rel: posix(join(d, f)), map: set.map, kind: set.kind, folder: set.folders ? d : null });
+    }
+  }
+  for (const f of config.extra?.[set.map] ?? []) {
+    if (existsSync(join(DOCS, f))) docs.push({ rel: posix(f), map: set.map, kind: set.kind, folder: null });
   }
 }
-const linkAb = (body) =>
-  body.replace(/\[([^\]]*)\]\((?:\.\.\/(?:system|components|features|modules)\/|\.\/)?([a-z0-9-]+)\.md(?:#[^)]*)?\)/g,
-    (all, _label, name) => (abTitle[name] ? `[[${abTitle[name]}]]` : all));
-for (const [name, { cat, src }] of Object.entries(abSrc)) {
-  mkdirSync(join(OUT, "as-built", cat), { recursive: true });
-  writeFileSync(join(OUT, "as-built", cat, `${abTitle[name]}.md`), withSource(linkAb(stripH1(src)), `docs/${cat}/${name}.md`));
+for (const doc of docs) {
+  doc.src = readFileSync(join(DOCS, doc.rel), "utf8");
+  const h1 = firstH1(doc.src);
+  const fallback = defaultTitle(doc.kind, doc.rel, h1);
+  const custom = config.title?.({ map: doc.map, kind: doc.kind, path: doc.rel, h1, defaultTitle: fallback });
+  doc.title = custom ? fileSafe(custom) : fallback;
 }
 
-console.log(`staged ${adrFiles.length} ADRs + ${Object.keys(abSrc).length} as-built docs → ${OUT}`);
-if (process.argv.includes("--stage-only")) process.exit(0);
+// ---- links → [[wikilinks]] -----------------------------------------------------
+const byRel = new Map(docs.map((d) => [d.rel, d]));
+const byName = new Map(); // `${map}/${basename}` → docs (the fallback for bare `name.md` links)
+for (const d of docs) {
+  const k = `${d.map}/${basename(d.rel)}`;
+  byName.set(k, [...(byName.get(k) ?? []), d]);
+}
+const LINK = /\[([^\]]*)\]\(([^)\s]+\.md)(#[^)\s]*)?\)/g;
+function linkify(doc, body) {
+  return body.replace(LINK, (whole, _label, href) => {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("/")) return whole;
+    const rel = posix(relative(DOCS, resolve(DOCS, dirname(doc.rel), href)));
+    let target = byRel.get(rel);
+    if (!target) {
+      const same = byName.get(`${doc.map}/${basename(href)}`);
+      if (same?.length === 1) target = same[0];
+    }
+    // ADRs are addressed by number: a link whose slug went stale after a retitle still names
+    // the right record (`./030-old-slug.md` → ADR-030).
+    const num = !target && /^(\d{3})-/.exec(basename(href))?.[1];
+    if (num) {
+      const adr = docs.filter((d) => d.kind === "adr" && basename(d.rel).startsWith(`${num}-`));
+      if (adr.length === 1) target = adr[0];
+    }
+    if (!target || (LINKS !== "all" && target.map !== doc.map)) return whole;
+    return `[[${target.title}]]`;
+  });
+}
+
+// ---- stage -----------------------------------------------------------------------
+// A fresh dir per run: a fixed shared path let another repo's copy of this script, running at the
+// same time, restage its own docs under us, and our import pushed them into this project's maps.
+const OUT = mkdtempSync(join(tmpdir(), "alkahest-docs-staging-"));
+const maps = [...new Set(SETS.map((s) => s.map))];
+for (const doc of docs) {
+  const dir = join(OUT, doc.map, ...(doc.folder ? doc.folder.split("/") : []));
+  mkdirSync(dir, { recursive: true });
+  const docsRel = posix(relative(ROOT, join(DOCS, doc.rel)));
+  writeFileSync(join(dir, `${doc.title}.md`), withSource(linkify(doc, stripH1(doc.src)), docsRel));
+}
+for (const m of maps) mkdirSync(join(OUT, m), { recursive: true });
+console.log(`staged ${maps.map((m) => `${docs.filter((d) => d.map === m).length} ${m}`).join(" + ")} docs → ${OUT}`);
+if (STAGE_ONLY) process.exit(0);
+
+// ---- import ------------------------------------------------------------------------
+const scope = ["--path", ROOT, ...(PROJECT ? ["--slug", PROJECT] : [])];
+if (PROJECT) console.log(`project: ${PROJECT}`);
+
+// A note map that doesn't exist yet is created (the preset install makes them, but a repo can
+// add a set or move projects). Skipped on --dry-run: a plan must not create anything.
+if (!DRY_RUN && config.createMaps !== false) {
+  const list = spawnSync("alkahest", ["maps", "list", ROOT, ...(PROJECT ? ["--slug", PROJECT] : [])], { encoding: "utf8" });
+  const have = list.status === 0 ? list.stdout : null;
+  for (const m of maps) {
+    if (have === null || new RegExp(`(^|[^\\w-])${m.replace(/[-]/g, "\\-")}([^\\w-]|$)`, "m").test(have)) continue;
+    console.log(`[sync] creating note map '${m}'`);
+    spawnSync("alkahest", ["maps", "create", m, "--type", "note", ...scope], { stdio: "inherit" });
+  }
+}
 
 // A full mirror is many sequential POSTs, so a transient failure is a question of when, not
 // if. The CLI handles it per file (keeps going, prints `✗ <file>: <message>`, exits 1) — act
 // on the exit code and retry the whole set: rows that already landed come back as updates.
-const ATTEMPTS = 3;
+const ATTEMPTS = DRY_RUN ? 1 : 3;
 const failed = [];
-
-for (const [dir, map] of [["adr", "adr"], ["as-built", "as-built"]]) {
+for (const m of maps) {
   let ok = false;
   for (let attempt = 1; attempt <= ATTEMPTS && !ok; attempt++) {
-    console.log(`\n== notes import ${dir} → map ${map}${attempt > 1 ? ` (retry ${attempt - 1})` : ""} ==`);
-    const run = spawnSync("alkahest", ["notes", "import", join(OUT, dir), "--map", map, "--path", ROOT], {
+    console.log(`\n== notes import ${m} → map ${m}${DRY_RUN ? " (dry run)" : ""}${attempt > 1 ? ` (retry ${attempt - 1})` : ""} ==`);
+    const run = spawnSync("alkahest", ["notes", "import", join(OUT, m), "--map", m, ...scope, ...(DRY_RUN ? ["--dry-run"] : [])], {
       stdio: "inherit",
     });
     if (run.error) console.error(`[sync] could not run alkahest: ${run.error.message}`);
     ok = !run.error && run.status === 0;
     if (!ok && attempt < ATTEMPTS) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5000);
   }
-  if (!ok) failed.push(`${dir} → ${map}`);
+  if (!ok) failed.push(m);
 }
 
 if (failed.length) {
-  console.error(`\n[sync] FAILED after ${ATTEMPTS} attempts: ${failed.join(", ")}`);
+  console.error(`\n[sync] FAILED after ${ATTEMPTS} attempt(s): ${failed.join(", ")}`);
   console.error("[sync] scroll up for the per-file '✗ <file>: <message>' lines from the importer.");
   console.error(`[sync] staged files kept for inspection: ${OUT}`);
   process.exit(1);
 }
-// The staging dir is this run's own (mkdtempSync), so removing it touches no other sync.
-// Kept on --stage-only (that's what it's for) and on failure (above). Imported here rather
-// than at the top so `alkahest preset update` can merge this into copies that reorganised
-// their import block.
-(await import("node:fs")).rmSync(OUT, { recursive: true, force: true });
-console.log("\n[sync] both maps up to date.");
+// The staging dir is this run's own, so removing it touches no other sync. Kept on
+// --stage-only (that's what it's for) and on failure (above).
+rmSync(OUT, { recursive: true, force: true });
+console.log(DRY_RUN ? "\n[sync] dry run done — nothing written." : `\n[sync] ${maps.join(" + ")} up to date.`);