@cr8rcho/alkahest 0.1.90 → 0.1.92

package/presets/as-built/history/f431a6fcf54a4906

@@ -0,0 +1,123 @@
+#!/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, rmSync } 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");
+const OUT = join(tmpdir(), "alkahest-docs-staging");
+rmSync(OUT, { recursive: true, force: true });
+
+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.json

@@ -0,0 +1,60 @@
+{
+  "files": {
+    "skills/as-built-docs.md": [
+      {
+        "sha": "8a9e3845f322e51c",
+        "since": "0.1.72"
+      },
+      {
+        "sha": "5a9ef521edb13aa1",
+        "since": "0.1.74"
+      },
+      {
+        "sha": "0fe9dc4fc94d413f",
+        "since": "0.1.76"
+      }
+    ],
+    "skills/adr.md": [
+      {
+        "sha": "bd84de1dd9759c12",
+        "since": "0.1.72"
+      },
+      {
+        "sha": "6e0b36b4d353b6b6",
+        "since": "0.1.75"
+      },
+      {
+        "sha": "87497464ab8cfa7d",
+        "since": "0.1.76"
+      }
+    ],
+    "sync-docs-maps.mjs": [
+      {
+        "sha": "f431a6fcf54a4906",
+        "since": "0.1.72"
+      },
+      {
+        "sha": "32be1c85c4b2757d",
+        "since": "0.1.90"
+      },
+      {
+        "sha": "2eb353c13db7e5a7",
+        "since": "0.1.92"
+      }
+    ],
+    "CLAUDE-snippet.md": [
+      {
+        "sha": "8e8f6eebcb4b2a58",
+        "since": "0.1.72"
+      },
+      {
+        "sha": "ed625ebd1209c061",
+        "since": "0.1.76"
+      },
+      {
+        "sha": "96497831c905de56",
+        "since": "0.1.91"
+      }
+    ]
+  }
+}

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

@@ -119,6 +119,12 @@ for (const [dir, map] of [["adr", "adr"], ["as-built", "as-built"]]) {
 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.");
+  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.");

package/presets/llm-wiki/CHANGES.md

@@ -0,0 +1,8 @@
+# llm-wiki preset — changes
+
+Why each shipped file changed, newest first. `alkahest preset update` prints the entries newer
+than the version an installed copy came from. One `## <version>` per release that touched the
+preset; each bullet names its file.
+
+## 0.1.88
+- First release of the preset.

package/presets/llm-wiki/history/44e1874c74476cd7

@@ -0,0 +1,57 @@
+# alkahest/wiki-capture — keep what you just learned
+
+The user says *"save this"*, *"keep that"*, *"put this in the wiki"*, *"이거 정리해서 넣어줘"*,
+*"기억해 둬"* — or a piece of work just finished and something durable came out of it. This
+skill turns knowledge that surfaced **during a session** into wiki pages. (A source the
+user hands you — an article, a URL, a transcript — is an *ingest*, see `alkahest/wiki`.)
+Read `alkahest/wiki` once first: it holds the layout, the tools and the rules this skill
+builds on.
+
+## Two modes — detect from the call
+
+- **Pointed capture** — the user gestured at one specific thing ("save the part about X",
+  an argument naming a topic). The worth-it decision is **already made by the user**; do
+  not re-litigate it. Scope to exactly what they pointed at and write **one focused
+  note** (or one update). Do not sweep the rest of the session.
+- **Sweep** — no specific pointer ("save anything useful from this", end of a task).
+  Scan the session for **durable, reusable** knowledge against the bar below. May yield
+  several notes. If nothing meets the bar, say so in a sentence and stop — no filler.
+
+When the pointer is ambiguous, ask one short question instead of guessing.
+
+## The worth-it bar (sweep; in pointed mode only to reject the clearly unfit)
+
+Keep: a decision and its rationale · a reusable concept, definition or pattern · a fact
+about a company, tool, product, person or process · a synthesis distilled from research ·
+a non-obvious how-to or operating rule · a good answer the user is likely to want again.
+
+Never keep: throwaway conversation, one-off debugging steps, anything already in the wiki,
+anything derivable from code or git history, secrets.
+
+## Steps
+
+1. **Dedupe first** — `search` / `notes q="<topic>"` (matches full bodies), `get_note` the
+   candidates. A page on the topic exists → **`update_note`** it. If the new knowledge
+   conflicts with it, don't overwrite silently: state the difference and prefer the newer
+   claim.
+2. **Route** — pick the folder by what the knowledge *is*: `wiki/concepts` (a definition or
+   pattern), `wiki/entities` (a company / tool / person), `wiki/topics` (an ongoing
+   subject), `wiki/syntheses` (something distilled from several pages), `outputs/…` for a
+   deliverable. Company-internal knowledge and general knowledge may live on different
+   note maps — check `maps` and the existing pages, and pass `map` accordingly.
+3. **Write** — one topic per note; a small markdown document with `##` sections
+   (Definition / Why it matters / How to apply, or Summary / Key points / Relevance —
+   whatever fits) and code where it carries the knowledge. Meaning-first title.
+   `props.tags` from the existing vocabulary (`note_props`), 1–3 tags.
+4. **Connect** — name 1–3 closest neighbours as `[[Title]]` references in the body (a
+   `## Related` list is the convention). The graph derives the edges; a note with no
+   references is an island — if you truly found no neighbour, say so in the report.
+5. **Report** — two lines: what was kept, and the viewer link of each created/updated
+   note (`https://alkahest.app/p/<project>/<map>/<note-slug>`), plus any conflict you
+   noted against an existing page.
+
+## Not this skill's job
+
+- **No deletions.** Capture updates or adds; retiring pages is `alkahest/wiki-lint`.
+- **No index or log notes.** The map and the history are those.
+- **No raw pages.** What the user hands you as a source goes through ingest.

package/presets/llm-wiki/history/59cf7b5051fce7e3

@@ -0,0 +1,93 @@
+# alkahest/wiki — an LLM-maintained knowledge wiki
+
+You maintain a **knowledge wiki** for the user: a hosted alkahest project whose notes are
+markdown documents the LLM writes and keeps current, and whose note map draws the graph.
+The user curates sources, asks questions and reads; **you do the bookkeeping** — summaries,
+cross-references, filing, consistency. Knowledge is compiled once and kept current, not
+re-derived from raw material on every question.
+
+The pattern is Andrej Karpathy's *LLM Wiki* idea file
+(<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>). This skill is that
+pattern instantiated on alkahest: the three layers and three loops are his; the note pool,
+the graph and the tools below are where they land.
+
+## The three layers, on alkahest
+
+| Layer | Karpathy | Here |
+|---|---|---|
+| Raw sources | `raw/` — immutable | notes under folder **`raw/…`** (`raw/articles`, `raw/notes`, `raw/transcripts`). You read them; you **never edit or delete them**. |
+| The wiki | `wiki/` — LLM-owned | notes under **`wiki/…`**: `sources` (one page per ingested source), `concepts`, `entities` (people, companies, products, tools), `topics`, `comparisons`, `syntheses`, `overviews`. |
+| The schema | `CLAUDE.md` / `AGENTS.md` | **this skill** plus its siblings `alkahest/wiki-capture` and `alkahest/wiki-lint`. Local preferences (language, extra folders) go in a note `wiki/overviews/Conventions` — read it when it exists. |
+
+Deliverables (briefs, decks, lint reports) go under **`outputs/…`** (`outputs/briefs`, `outputs/lint`).
+
+Two of Karpathy's files have no counterpart here, on purpose — **do not create them**:
+- `index.md` → the note map, the tree sidebar (folders) and server-side search (`search`, `notes q=`) are the catalog.
+- `log.md` → note history (revisions) and the activity journal already record what changed and when.
+
+## Tools
+
+`notes` (list — excerpts, `q` for full-body search, `map`) · `get_note` (one document + its links and backlinks)
+· `add_note` (`title`, `body`, `folder`, `props`, `map`) · `update_note` (`body`/`folder`/`props`; `delete`+`reason`
+and `restore` — lint only) · `note_props` (the notebook's property schema) · `search` (notes + issues + tasks in one).
+
+**Note-to-note connections are `[[Title]]` references in the body.** The graph derives them at
+read time; there is no separate edge to draw. A note nobody references and that references
+nothing is an island — always name at least one neighbour in the body.
+
+Properties: use `props.tags` (string array) for cross-cutting labels; keep a `source`
+property on `wiki/sources` pages pointing at the raw note (`[[Raw title]]`). Keep the tag
+vocabulary small — a tag on 3–12 notes is a useful hub, a tag on 1 is noise.
+
+## Loop 1 — Ingest (a new source arrives)
+
+1. **File the raw source** as a note under `raw/<kind>` with the original text (or the
+   text you fetched from the URL), the URL and date in a short frontmatter-style header.
+   Preserve the source's language. `props.tags: ["raw"]`.
+2. **Read it and discuss** the key takeaways with the user before writing — one source at
+   a time, the user stays involved. (A batch ingest is fine when they ask for it.)
+3. **Write the source page** under `wiki/sources`: what it claims, why it matters, key
+   quotes, and a `## Related` section of `[[…]]` references. Meaning-first title, not the
+   raw file name.
+4. **Update the wiki pages it touches** — `notes q=` first, then `update_note` existing
+   concept/entity/topic pages (add the new evidence, cite the source page) and `add_note`
+   only for concepts that have no page yet. A single source can rightly touch 5–15 pages.
+5. **Never erase a claim the new source contradicts.** State the difference in the page
+   ("Source A (2025) says X; Source B (2026) says Y") and prefer the newer claim when you
+   present current understanding.
+6. End with the map link and a one-paragraph summary of what changed.
+
+## Loop 2 — Query (the user asks a question)
+
+1. `search` / `notes q=` first, then `get_note` the pages that matter — read the wiki, not
+   the raw sources, unless the wiki is silent.
+2. Answer with citations as `[[Page title]]` references.
+3. **File the good answers back.** A comparison, an analysis, a connection the user
+   asked for is knowledge — save it under `wiki/comparisons` or `wiki/syntheses` with its
+   sources referenced, so explorations compound like ingested sources do. Ask when unsure
+   whether an answer is worth keeping; a throwaway answer stays in chat.
+
+## Loop 3 — Lint
+
+Periodically health-check the wiki: `alkahest/wiki-lint` has the checks, the self-trigger
+rule and the delete policy. Capturing knowledge that surfaced *during a session* (not from
+a source) is `alkahest/wiki-capture`.
+
+## Rules
+
+- **One topic per note.** Prefer updating an existing page to adding a near-duplicate —
+  always `notes q=` before `add_note`.
+- **Meaning-first titles.** The title is the node label and the `[[…]]` key other pages
+  cite; date-prefixed titles are for `raw/` only.
+- **Bodies are small markdown documents** — `##` sections, a `## Related` list, code where
+  it carries the knowledge. Consistent beats comprehensive.
+- **Language**: raw stays as it came; wiki pages follow the user's language (say it in
+  `wiki/overviews/Conventions` if it isn't obvious from the existing pages).
+- **Deletion is lint's job**, never ingest's or query's.
+
+## Getting this read
+
+Hosted skills are read when something asks for them. Tell your agent once, in whatever
+rules file it reads (`CLAUDE.md`, `AGENTS.md`, a user-level rules file):
+*"My knowledge wiki is the alkahest project `<slug>` — read the `alkahest/wiki` skill over MCP
+before touching it."* Or just say "read the alkahest/wiki skill" when you start a session.

package/presets/llm-wiki/history/b5f313af919c6236

@@ -0,0 +1,69 @@
+# alkahest/wiki-lint — keep the wiki healthy
+
+A periodic health check of the wiki: find what has drifted, fix what is mechanical, propose
+what needs the user, and leave a report the next lint can read. Read `alkahest/wiki` first
+for the layout and the tools.
+
+## When to run
+
+Run a lint when the user asks ("lint the wiki", "위키 정리해줘", "health check"), and
+**offer one yourself** when either is true:
+- roughly ten sources have been ingested since the last lint, or
+- the newest note under `outputs/lint` is older than two weeks (or there is none).
+
+(A real schedule — a weekly agent routine — is the user's choice; this skill only makes
+the agent raise its hand.)
+
+## Start with the Trash
+
+`notes` hides trashed pages, but the last lint may have sent pages there that the user
+has not reviewed. Before doing anything new, read the previous `outputs/lint` report's
+"Sent to the Trash" section: anything still inside its 30-day window is a pending
+decision — mention it, don't pile more on top without asking.
+
+## Checks
+
+Read the map with `notes` (excerpts; `full_bodies` only when the wiki is small), then:
+
+| Check | What to look for | Mechanical fix |
+|---|---|---|
+| **Orphans** | pages with no `[[…]]` backlinks and none outgoing (`get_note` shows both) | connect: add a `## Related` reference from the closest hub page, or into the orphan |
+| **Duplicates** | two pages on one topic (`notes q=` around suspicious titles) | merge into the better page, then trash the other |
+| **Empty / stub pages** | title only, or a body under a couple of lines with no references | fill from the source pages, or trash |
+| **Contradictions** | pages that disagree; a source page newer than the claim it contradicts | **write the difference into the page**, prefer the newer claim — never delete the older claim |
+| **Stale claims** | dated statements superseded by later sources | same as above; add "as of <date>" |
+| **Missing pages** | an entity or concept referenced as `[[…]]` from several pages but with no page of its own (unresolved references stay literal — they are the tell) | propose; create only when the sources on the map already support a page |
+| **Missing cross-references** | pages that obviously belong together but don't cite each other | add the references |
+| **Data gaps** | questions the wiki cannot answer that a web search or a new source could | list as follow-up research in the report |
+
+## Delete policy — three rules
+
+Deleting is `update_note` with `delete: true` and a **`reason`**. It is a soft delete: the
+page goes to the project Trash, restorable for 30 days from the web Trash view or with
+`update_note restore: true`, and only then is purged. The activity journal shows every
+deletion with its reason. That safety net is why lint may delete at all — and it is the
+whole safety net, so:
+
+1. **The reason says *why it should go*, in one line the user can judge without opening
+   the page** — `duplicate of [[X]], content merged`, `empty stub, topic covered by [[Y]]`,
+   `superseded by [[Z]] — lint 2026-09-19`. Never `cleanup`.
+2. **`raw/` is never deleted or edited.** It is the source of truth the wiki is compiled
+   from; a raw page's only lint outcome is "unlinked — no source page yet".
+3. **Contradictions and stale claims are written, not deleted.** "We used to think X" is
+   knowledge. Orphans are connected, not deleted.
+
+On a shared wiki, a page created by someone else is **proposed, not trashed** — list it in
+the report with the suggested action.
+
+## The report
+
+Write `outputs/lint/<YYYY-MM-DD> wiki lint` (`props.tags: ["lint"]`) with:
+
+- **Fixed** — what you connected, merged, filled, annotated (page links)
+- **Sent to the Trash** — each page with its reason, and one line on how to restore
+- **Proposed** — what needs the user: pages to create, contradictions to resolve, other
+  people's pages that look retirable
+- **Follow-up research** — the questions the wiki cannot answer yet
+- **Counts** — pages / orphans / trashed, so the next lint sees the trend
+
+Tell the user the report's link and the two or three items that most need their eye.

package/presets/llm-wiki/history.json

@@ -0,0 +1,22 @@
+{
+  "files": {
+    "skills/wiki.md": [
+      {
+        "sha": "59cf7b5051fce7e3",
+        "since": "0.1.88"
+      }
+    ],
+    "skills/wiki-capture.md": [
+      {
+        "sha": "44e1874c74476cd7",
+        "since": "0.1.88"
+      }
+    ],
+    "skills/wiki-lint.md": [
+      {
+        "sha": "b5f313af919c6236",
+        "since": "0.1.88"
+      }
+    ]
+  }
+}