@cr8rcho/alkahest 0.1.90 → 0.1.92

package/presets/as-built/history/32be1c85c4b2757d

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// Reference implementation (alkahest as-built preset) — mirror this repo's 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):
+//   - 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;
+//   - 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).
+//
+// 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";
+import { spawnSync } from "node:child_process";
+import { join, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+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 sanitize = (t) =>
+  t.replace(/\(\//g, "(").replace(/[/\\:]/g, "-").replace(/`/g, "").replace(/\s+/g, " ").trim();
+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+/, "");
+};
+// 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}`));
+}
+
+// ---- 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 };
+  }
+}
+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`));
+}
+
+console.log(`staged ${adrFiles.length} ADRs + ${Object.keys(abSrc).length} as-built docs → ${OUT}`);
+if (process.argv.includes("--stage-only")) process.exit(0);
+
+// 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 failed = [];
+
+for (const [dir, map] of [["adr", "adr"], ["as-built", "as-built"]]) {
+  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], {
+      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 (failed.length) {
+  console.error(`\n[sync] FAILED after ${ATTEMPTS} attempts: ${failed.join(", ")}`);
+  console.error("[sync] scroll up for the per-file '✗ <file>: <message>' lines from the importer.");
+  process.exit(1);
+}
+console.log("\n[sync] both maps up to date.");

package/presets/as-built/history/5a9ef521edb13aa1

@@ -0,0 +1,71 @@
+# as-built-docs — writing instructions
+
+You are maintaining this repository's **as-built documentation**: documents that record how
+the system **is actually built**. Never plans, PRDs, or aspirations — present tense, code as
+the source of truth.
+
+## The four layers
+
+Documents live under `docs/` in four folders, split by scope and viewpoint:
+
+| Layer | Scope | Viewpoint | Answers |
+|---|---|---|---|
+| `system/` | whole app | architecture / data flow | "How is this app put together overall?" |
+| `components/` | one UI area | what the user sees | "What is on this screen area, and what does each control do?" |
+| `features/` | one behavior | time / user action | "When and under what conditions does this behavior run?" |
+| `modules/` | one code layer | developer view | "What does this layer provide, and how is it separated from the rest?" |
+
+Placement rule of thumb: what the user *sees* → `components/`; what *happens over time* →
+`features/`; *code structure* → `modules/`; the picture that crosses all three → `system/`.
+When a topic straddles two layers, pick one as the **main** document and leave a short
+summary + link in the other.
+
+## Document shape
+
+Title each document with a **classed H1**: `# System — <name>`, `# Component — <name>`,
+`# Feature — <name>`, `# Module — <name>`. The note-map mirror strips the class prefix,
+so the hosted note is titled just `<name>` while the file stays unambiguous in the repo.
+(ADRs have their own H1 shape — see the `adr` skill.)
+
+## Bootstrap — when the repo has no docs yet
+
+Do NOT try to document everything in one session. The first pass is deliberately small so
+the user sees a map fast:
+
+1. `docs/system/<app>.md` — one system map: layers, data flow, key dependencies, honest
+   Known Limitations.
+2. Two or three `docs/modules/*.md` for the load-bearing modules only.
+3. One decision record (see the `adr` skill): **ADR-001, an architecture snapshot** — the
+   decisions already embedded in the current code.
+4. Add each document to the index in `docs/README.md`, then **mirror to the note maps and
+   hand the user the map link** (the mirroring rule lives in this repo's CLAUDE.md).
+
+In the first pass, **prefer `modules/`** (plus the one `system/` map) when a topic could
+fit several layers — grow `features/` and `components/` in later sessions, and leave their
+index tables empty until they have documents.
+
+Grow the rest incrementally: each later work session adds or updates only the documents its
+code changes touch.
+
+## Tone and rules
+
+- **As-built, present tense** — "this is how it is built." Cite real file paths, function
+  names, and constants so readers can jump straight to code.
+- **Decision history is a separate axis** — why / alternatives / trade-offs belong in ADRs
+  (`docs/decisions/`, see the `adr` skill), not in these documents.
+- **Known Limitations, honestly** — the most valuable section of a post-hoc document.
+  Remove limitations you fixed; add the ones you introduced.
+- **Overwrite freely** — these documents always describe the present. (ADRs are the
+  append-only record; never blend the two.)
+- **Trust the code over connected tools** — an MCP server configured in your session
+  (a database MCP, for instance) may be bound to a *different* project than the repo you
+  are documenting. Verify the binding before citing anything from it, or read the schema
+  from the code instead.
+
+## After every code change (checklist)
+
+- [ ] Does the affected document still describe current behavior?
+- [ ] Are its code citations (paths, names, constants) still valid?
+- [ ] Known Limitations updated — fixed ones removed, new ones added?
+- [ ] Cross-references from documents in other layers updated?
+- [ ] `docs/README.md` index still accurate (add a row when adding a document)?

package/presets/as-built/history/6e0b36b4d353b6b6

@@ -0,0 +1,72 @@
+# adr — decision records
+
+ADRs (`docs/decisions/NNN-kebab-title.md`) record the **why** of decisions: context,
+alternatives, trade-offs. They are a separate axis from as-built docs — as-built documents
+are overwritten to stay current; ADRs are **append-only**, frozen at decision time.
+
+## When to write one
+
+One-line test: **if the code diff alone cannot reconstruct the "why", it deserves an ADR.**
+
+Typical cases: data-model or structural changes; policy decisions and their reversals;
+adopting an external dependency or license; fixing an ownership boundary ("this module is
+the single owner of that transform"); behavior changes that trade something away; and
+decisions deliberately **not** taken (record the reason and the revisit trigger).
+
+Skip when: plain bug fixes, refactors, dependency bumps — anything self-evident from the
+code and the as-built docs.
+
+## Bootstrap — ADR-001
+
+On a repo's first documentation pass, write **ADR-001 as an architecture snapshot**: the
+decisions already embedded in the current code (framework, storage, module boundaries),
+each with the alternatives it implicitly rejected. This seeds the habit of communicating
+through decision records.
+
+## Numbering & lifecycle
+
+- `NNN` is zero-padded, sequential, never reused or renumbered.
+- Never rewrite an accepted ADR. When a decision changes, write a **new** ADR that names
+  the old one in `Supersedes:`, and flip the old one's Status to `Superseded by …`
+  (keep the body — "why we did it that way once, then backed out" is the value).
+
+## Tags (frontmatter)
+
+Every ADR opens with a `tags:` frontmatter block. Keep the vocabulary small and stable:
+one **surface** tag (the area of the product it touches) plus at most two **arc** tags
+(a storyline several ADRs share). On the hosted `adr` note map each tag renders as a hub
+node — keep every tag attached to roughly 3–12 ADRs so the map stays legible, and prefer
+reusing an existing tag over inventing a new one.
+
+**The vocabulary lives in `docs/decisions/README.md`'s tag table, and the repo owns it.**
+On the bootstrap pass, seed it: derive 3–7 surface tags from the codebase's *actual* areas
+(the folders/verticals you just documented), record them in the table, and tag ADR-001 from
+that set. Afterwards, every ADR picks from the table; a genuinely new tag means adding its
+row in the same commit. Arc tags are not invented up front — they emerge when several ADRs
+turn out to share a storyline.
+
+## Template
+
+```markdown
+---
+tags: [<one surface tag>, <0-2 arc tags>]
+---
+
+# ADR-NNN: <one-line title>
+
+* **Status**: Accepted (YYYY-MM-DD)
+* **Date**: YYYY-MM-DD
+* **Supersedes**: none | ADR-NNN (partial/full)
+* **Related**: ADRs, as-built docs
+
+***
+
+## 1. Context
+## 2. Decision
+## 3. Trade-offs
+## 4. Considered alternatives
+## 5. Known limitations
+```
+
+Keep *Trade-offs*, *Considered alternatives*, and *Known limitations* non-empty — they are
+the point of the record. Cite code richly (files, functions, constants).

package/presets/as-built/history/87497464ab8cfa7d

@@ -0,0 +1,72 @@
+# alkahest/adr — decision records
+
+ADRs (`docs/decisions/NNN-kebab-title.md`) record the **why** of decisions: context,
+alternatives, trade-offs. They are a separate axis from as-built docs — as-built documents
+are overwritten to stay current; ADRs are **append-only**, frozen at decision time.
+
+## When to write one
+
+One-line test: **if the code diff alone cannot reconstruct the "why", it deserves an ADR.**
+
+Typical cases: data-model or structural changes; policy decisions and their reversals;
+adopting an external dependency or license; fixing an ownership boundary ("this module is
+the single owner of that transform"); behavior changes that trade something away; and
+decisions deliberately **not** taken (record the reason and the revisit trigger).
+
+Skip when: plain bug fixes, refactors, dependency bumps — anything self-evident from the
+code and the as-built docs.
+
+## Bootstrap — ADR-001
+
+On a repo's first documentation pass, write **ADR-001 as an architecture snapshot**: the
+decisions already embedded in the current code (framework, storage, module boundaries),
+each with the alternatives it implicitly rejected. This seeds the habit of communicating
+through decision records.
+
+## Numbering & lifecycle
+
+- `NNN` is zero-padded, sequential, never reused or renumbered.
+- Never rewrite an accepted ADR. When a decision changes, write a **new** ADR that names
+  the old one in `Supersedes:`, and flip the old one's Status to `Superseded by …`
+  (keep the body — "why we did it that way once, then backed out" is the value).
+
+## Tags (frontmatter)
+
+Every ADR opens with a `tags:` frontmatter block. Keep the vocabulary small and stable:
+one **surface** tag (the area of the product it touches) plus at most two **arc** tags
+(a storyline several ADRs share). On the hosted `adr` note map each tag renders as a hub
+node — keep every tag attached to roughly 3–12 ADRs so the map stays legible, and prefer
+reusing an existing tag over inventing a new one.
+
+**The vocabulary lives in `docs/decisions/README.md`'s tag table, and the repo owns it.**
+On the bootstrap pass, seed it: derive 3–7 surface tags from the codebase's *actual* areas
+(the folders/verticals you just documented), record them in the table, and tag ADR-001 from
+that set. Afterwards, every ADR picks from the table; a genuinely new tag means adding its
+row in the same commit. Arc tags are not invented up front — they emerge when several ADRs
+turn out to share a storyline.
+
+## Template
+
+```markdown
+---
+tags: [<one surface tag>, <0-2 arc tags>]
+---
+
+# ADR-NNN: <one-line title>
+
+* **Status**: Accepted (YYYY-MM-DD)
+* **Date**: YYYY-MM-DD
+* **Supersedes**: none | ADR-NNN (partial/full)
+* **Related**: ADRs, as-built docs
+
+***
+
+## 1. Context
+## 2. Decision
+## 3. Trade-offs
+## 4. Considered alternatives
+## 5. Known limitations
+```
+
+Keep *Trade-offs*, *Considered alternatives*, and *Known limitations* non-empty — they are
+the point of the record. Cite code richly (files, functions, constants).

package/presets/as-built/history/8a9e3845f322e51c

@@ -0,0 +1,56 @@
+# as-built-docs — writing instructions
+
+You are maintaining this repository's **as-built documentation**: documents that record how
+the system **is actually built**. Never plans, PRDs, or aspirations — present tense, code as
+the source of truth.
+
+## The four layers
+
+Documents live under `docs/` in four folders, split by scope and viewpoint:
+
+| Layer | Scope | Viewpoint | Answers |
+|---|---|---|---|
+| `system/` | whole app | architecture / data flow | "How is this app put together overall?" |
+| `components/` | one UI area | what the user sees | "What is on this screen area, and what does each control do?" |
+| `features/` | one behavior | time / user action | "When and under what conditions does this behavior run?" |
+| `modules/` | one code layer | developer view | "What does this layer provide, and how is it separated from the rest?" |
+
+Placement rule of thumb: what the user *sees* → `components/`; what *happens over time* →
+`features/`; *code structure* → `modules/`; the picture that crosses all three → `system/`.
+When a topic straddles two layers, pick one as the **main** document and leave a short
+summary + link in the other.
+
+## Bootstrap — when the repo has no docs yet
+
+Do NOT try to document everything in one session. The first pass is deliberately small so
+the user sees a map fast:
+
+1. `docs/system/<app>.md` — one system map: layers, data flow, key dependencies, honest
+   Known Limitations.
+2. Two or three `docs/modules/*.md` for the load-bearing modules only.
+3. One decision record (see the `adr` skill): **ADR-001, an architecture snapshot** — the
+   decisions already embedded in the current code.
+4. Add each document to the index in `docs/README.md`, then **mirror to the note maps and
+   hand the user the map link** (the mirroring rule lives in this repo's CLAUDE.md).
+
+Grow the rest incrementally: each later work session adds or updates only the documents its
+code changes touch.
+
+## Tone and rules
+
+- **As-built, present tense** — "this is how it is built." Cite real file paths, function
+  names, and constants so readers can jump straight to code.
+- **Decision history is a separate axis** — why / alternatives / trade-offs belong in ADRs
+  (`docs/decisions/`, see the `adr` skill), not in these documents.
+- **Known Limitations, honestly** — the most valuable section of a post-hoc document.
+  Remove limitations you fixed; add the ones you introduced.
+- **Overwrite freely** — these documents always describe the present. (ADRs are the
+  append-only record; never blend the two.)
+
+## After every code change (checklist)
+
+- [ ] Does the affected document still describe current behavior?
+- [ ] Are its code citations (paths, names, constants) still valid?
+- [ ] Known Limitations updated — fixed ones removed, new ones added?
+- [ ] Cross-references from documents in other layers updated?
+- [ ] `docs/README.md` index still accurate (add a row when adding a document)?

package/presets/as-built/history/8e8f6eebcb4b2a58

@@ -0,0 +1,24 @@
+<!-- alkahest as-built preset — installed by `alkahest docs init`. Owned by this repo: edit freely. -->
+## 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 `as-built-docs` and `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 `as-built-docs` skill. Write an
+   ADR only for decisions whose "why" a code diff cannot reconstruct (criteria and the
+   template are in the `adr` skill).
+2. **First documentation pass (repo has no docs yet)?** Follow the bootstrap protocol in
+   the `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 a reference implementation and belongs to this repo: adapt it to
+   local conventions freely.

package/presets/as-built/history/96497831c905de56

@@ -0,0 +1,25 @@
+<!-- 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 a reference implementation and belongs to this repo: adapt it to
+   local conventions freely.
+<!-- /alkahest as-built preset -->

package/presets/as-built/history/bd84de1dd9759c12

@@ -0,0 +1,65 @@
+# adr — decision records
+
+ADRs (`docs/decisions/NNN-kebab-title.md`) record the **why** of decisions: context,
+alternatives, trade-offs. They are a separate axis from as-built docs — as-built documents
+are overwritten to stay current; ADRs are **append-only**, frozen at decision time.
+
+## When to write one
+
+One-line test: **if the code diff alone cannot reconstruct the "why", it deserves an ADR.**
+
+Typical cases: data-model or structural changes; policy decisions and their reversals;
+adopting an external dependency or license; fixing an ownership boundary ("this module is
+the single owner of that transform"); behavior changes that trade something away; and
+decisions deliberately **not** taken (record the reason and the revisit trigger).
+
+Skip when: plain bug fixes, refactors, dependency bumps — anything self-evident from the
+code and the as-built docs.
+
+## Bootstrap — ADR-001
+
+On a repo's first documentation pass, write **ADR-001 as an architecture snapshot**: the
+decisions already embedded in the current code (framework, storage, module boundaries),
+each with the alternatives it implicitly rejected. This seeds the habit of communicating
+through decision records.
+
+## Numbering & lifecycle
+
+- `NNN` is zero-padded, sequential, never reused or renumbered.
+- Never rewrite an accepted ADR. When a decision changes, write a **new** ADR that names
+  the old one in `Supersedes:`, and flip the old one's Status to `Superseded by …`
+  (keep the body — "why we did it that way once, then backed out" is the value).
+
+## Tags (frontmatter)
+
+Every ADR opens with a `tags:` frontmatter block. Keep the vocabulary small and stable:
+one **surface** tag (the area of the product it touches) plus at most two **arc** tags
+(a storyline several ADRs share). On the hosted `adr` note map each tag renders as a hub
+node — keep every tag attached to roughly 3–12 ADRs so the map stays legible, and prefer
+reusing an existing tag over inventing a new one.
+
+## Template
+
+```markdown
+---
+tags: [<one surface tag>, <0-2 arc tags>]
+---
+
+# ADR-NNN: <one-line title>
+
+* **Status**: Accepted (YYYY-MM-DD)
+* **Date**: YYYY-MM-DD
+* **Supersedes**: none | ADR-NNN (partial/full)
+* **Related**: ADRs, as-built docs
+
+***
+
+## 1. Context
+## 2. Decision
+## 3. Trade-offs
+## 4. Considered alternatives
+## 5. Known limitations
+```
+
+Keep *Trade-offs*, *Considered alternatives*, and *Known limitations* non-empty — they are
+the point of the record. Cite code richly (files, functions, constants).

package/presets/as-built/history/ed625ebd1209c061

@@ -0,0 +1,24 @@
+<!-- alkahest as-built preset — installed by `alkahest docs init`. Owned by this repo: edit freely. -->
+## 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 a reference implementation and belongs to this repo: adapt it to
+   local conventions freely.