@cr8rcho/alkahest 0.1.73 → 0.1.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cr8rcho/alkahest",
-  "version": "0.1.73",
+  "version": "0.1.75",
   "publishConfig": {
     "access": "public"
   },

package/presets/as-built/scaffold/docs/decisions/README.md

@@ -10,3 +10,15 @@ Quick rules:
 - Append-only: a changed decision gets a NEW ADR with `Supersedes:`; the old one keeps its
   body and gets `Status: Superseded by …`.
 - Start the practice with **ADR-001 — architecture snapshot** of the current code.
+
+## Tag vocabulary
+
+Every ADR opens with `tags:` frontmatter, and **this table is the vocabulary** — pick from
+it; extend it deliberately (add the row in the same commit as the ADR that needs it). On the
+hosted `adr` note map each tag becomes a hub node, so the vocabulary's shape IS the map's
+shape: one **surface** tag per ADR (the product/code area it touches) plus at most two
+**arc** tags (a storyline several ADRs share), and keep each tag attached to roughly 3–12
+ADRs. The first documentation pass seeds the surface rows from the codebase's actual areas.
+
+| Tag | Kind | Meaning |
+|---|---|---|

package/presets/as-built/skills/adr.md

@@ -38,6 +38,13 @@ one **surface** tag (the area of the product it touches) plus at most two **arc*
 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

package/presets/as-built/skills/as-built-docs.md

@@ -20,6 +20,13 @@ Placement rule of thumb: what the user *sees* → `components/`; what *happens o
 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
@@ -33,6 +40,10 @@ the user sees a map fast:
 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.
 
@@ -46,6 +57,10 @@ code changes touch.
   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)