@ctxr/skill-llm-wiki 1.0.1 → 1.0.2

package/guide/consumers/recipes/post-write-heal.md

@@ -0,0 +1,125 @@
+---
+id: recipe-post-write-heal
+type: primary
+depth_role: leaf
+focus: "The canonical after-every-leaf-write heal invocation"
+parents:
+  - ../index.md
+tags:
+  - heal
+  - envelope
+  - post-write
+  - consumers
+activation:
+  keyword_matches:
+    - post write
+    - after write
+    - heal
+    - validate after write
+    - next command
+  tag_matches:
+    - heal
+    - post-write
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: post-write heal
+
+## Trigger
+
+Your consumer just wrote a leaf into a hosted wiki. Before moving on, call `heal` to classify the wiki's state and let it name the next command.
+
+## Commands
+
+```bash
+skill-llm-wiki heal .development/shared/reports --json
+```
+
+That is the entire step. Do not invoke `validate`, `fix`, or `rebuild` directly; `heal` is the router.
+
+## Envelope fields
+
+```json
+{
+  "schema": "skill-llm-wiki/v1",
+  "command": "heal",
+  "target": "/abs/.../reports",
+  "verdict": "ok" | "fixable" | "needs-rebuild" | "broken" | "ambiguous",
+  "exit": 0,
+  "diagnostics": [
+    { "code": "IDX-01", "severity": "warning", "path": "...", "message": "..." },
+    { "code": "NEXT-01", "severity": "info",    "path": "...", "message": "next: skill-llm-wiki fix ... --json" }
+  ],
+  "next": { "command": "skill-llm-wiki", "args": ["fix", "/abs/.../reports", "--json"] },
+  "timing_ms": 23
+}
+```
+
+> The `next` field is the canonical machine-readable form. The `NEXT-01`
+> info diagnostic carries the same hint as a human-readable string for
+> operators tailing stdout; consumers should prefer `env.next` and only
+> fall back to parsing the diagnostic when running against a pre-v1
+> skill that does not emit it.
+
+| Verdict | What the consumer does |
+|---|---|
+| `ok` | Nothing. Move on. |
+| `fixable` | Invoke `env.next.command` with `env.next.args` (typically `skill-llm-wiki fix <wiki> --json`). |
+| `needs-rebuild` | Invoke `env.next.command` with `env.next.args` (typically `skill-llm-wiki rebuild <wiki> --json`). |
+| `broken` | Surface every `severity: "error"` diagnostic to the user. Do not auto-mutate. |
+| `ambiguous` | `validate` itself failed; inspect `HEAL-00` diagnostic for the error. |
+
+## Minimum consumer code
+
+```js
+import { spawnSync } from "node:child_process";
+
+function healAfterWrite(wikiPath) {
+  const r = spawnSync(
+    "skill-llm-wiki",
+    ["heal", wikiPath, "--json"],
+    { encoding: "utf8" },
+  );
+  const env = JSON.parse(r.stdout);
+  switch (env.verdict) {
+    case "ok":
+      return;
+    case "fixable":
+    case "needs-rebuild": {
+      if (!env.next) throw new Error("heal returned fixable/needs-rebuild without a `next` field");
+      const result = spawnSync(env.next.command, env.next.args, { stdio: "inherit" });
+      if (result.status !== 0) {
+        throw new Error(`follow-up ${env.next.command} exited ${result.status}`);
+      }
+      return;
+    }
+    case "broken":
+      reportDiagnosticsToUser(env.diagnostics);
+      throw new Error(`heal: wiki is broken at ${wikiPath}`);
+    default:
+      throw new Error(`heal: unexpected verdict ${env.verdict}`);
+  }
+}
+```
+
+## Failure modes
+
+- `verdict: "ambiguous"` with a `HEAL-00` diagnostic: validate threw. The wiki substrate itself may be broken (e.g. missing `.llmwiki/git/`).
+- A `fixable` run whose follow-up `fix` invocation fails: re-run `heal`; it should now report `needs-rebuild` or `broken`.
+- `heal` on a path that does not exist or is not a wiki returns `verdict: "broken"` with `WIKI-01` in diagnostics.
+
+## Why not `fix` / `rebuild` / `validate` directly?
+
+Consumers that pick one of the three without checking the validate output end up:
+
+- Running `fix` on a structurally-broken wiki that only `rebuild` can resolve.
+- Running `rebuild` on a wiki with trivial index drift, triggering unnecessary Tier 2 sub-agent work.
+- Running `validate` and then duplicating the action table consumers always get wrong.
+
+`heal` centralises the classification so every consumer uses the same rules.
+
+## Do not
+
+- Call `heal` on hot paths (per-keystroke). It runs full validate; budget for one invocation per logical leaf-write batch.
+- Ignore `broken` verdicts silently. The wiki is corrupt and further writes will compound the problem.

package/guide/consumers/recipes/skill-absent.md

@@ -0,0 +1,111 @@
+---
+id: recipe-skill-absent
+type: primary
+depth_role: leaf
+focus: "Detect the skill is missing and surface an upgrade path without silently degrading"
+parents:
+  - ../index.md
+tags:
+  - skill-absent
+  - preflight
+  - install-hint
+  - consumers
+activation:
+  keyword_matches:
+    - skill missing
+    - skill not installed
+    - install hint
+    - preflight skill
+    - hard dependency
+  tag_matches:
+    - skill-absent
+    - preflight
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: skill-absent detection
+
+## Trigger
+
+Your consumer treats `@ctxr/skill-llm-wiki` as a hard dependency and must refuse to run when the skill is missing, rather than silently degrading to raw-markdown writes.
+
+## Commands
+
+```bash
+skill-llm-wiki contract --json
+```
+
+This is the canonical probe. It is exempt from the runtime-dep preflight inside the skill itself, so even a partially-broken install still answers the probe as long as the binary is on PATH.
+
+## Decision tree
+
+`skill-llm-wiki contract --json` emits the **contract JSON** (schema `skill-llm-wiki/contract/v1`), not the operational envelope (`skill-llm-wiki/v1`). It has no `verdict` or `diagnostics` fields; gate on `format_version` directly.
+
+1. `skill-llm-wiki contract --json` exits `0` with a parseable contract JSON containing `format_version >= <your required>`: proceed.
+2. `skill-llm-wiki contract --json` exits `0` with `format_version` below your required value: the skill is present but too old. Surface an upgrade message.
+3. `skill-llm-wiki contract --json` exits non-zero: the skill is installed but broken (e.g. runtime deps corrupted). Surface a reinstall message.
+4. The binary is not on PATH (spawnSync returns ENOENT or no output): the skill is not installed. Surface an install message.
+
+## Minimum consumer code
+
+```js
+import { spawnSync } from "node:child_process";
+
+const REQUIRED_FORMAT_VERSION = 1;
+
+export function probeSkill() {
+  const r = spawnSync("skill-llm-wiki", ["contract", "--json"], {
+    encoding: "utf8",
+  });
+  if (r.error && r.error.code === "ENOENT") {
+    return { ok: false, state: "absent" };
+  }
+  if (r.status !== 0) {
+    return { ok: false, state: "broken", stderr: r.stderr };
+  }
+  try {
+    const env = JSON.parse(r.stdout);
+    if ((env.format_version ?? 0) < REQUIRED_FORMAT_VERSION) {
+      return { ok: false, state: "too-old", current: env.format_version };
+    }
+    return { ok: true, ...env };
+  } catch {
+    return { ok: false, state: "unparseable" };
+  }
+}
+
+export function enforceSkillPresent() {
+  const p = probeSkill();
+  if (p.ok) return p;
+  const hint =
+    p.state === "absent"
+      ? "@ctxr/skill-llm-wiki is not installed.\n" +
+        "Install with: npx @ctxr/kit install @ctxr/skill-llm-wiki"
+      : p.state === "too-old"
+        ? `@ctxr/skill-llm-wiki format_version ${p.current} is below the required ${REQUIRED_FORMAT_VERSION}.\n` +
+          "Upgrade with: npm i -g @ctxr/skill-llm-wiki@latest"
+        : `@ctxr/skill-llm-wiki is installed but not answering the contract probe.\n${p.stderr ?? ""}`;
+  throw new Error(hint);
+}
+```
+
+## Do not
+
+- Silently fall back to raw markdown writes when the skill is missing. Every downstream tool that expects the wiki format will break.
+- Inline the install command guess. Read the contract JSON's `package_version` and compare to your own requirement; publish your install hint alongside your agent.
+- Cache the probe result across sessions. A user can uninstall the skill at any time; the probe is cheap (~100ms) and should run once per invocation.
+
+## Recovery
+
+Once the consumer reports the skill is missing, recovery for the user is:
+
+```bash
+# Via @ctxr/kit (preferred, manages SKILL.md path + update flow):
+npx @ctxr/kit install @ctxr/skill-llm-wiki
+
+# Or plain npm for CI / scripted environments:
+npm i -g @ctxr/skill-llm-wiki
+```
+
+The consumer's preflight should re-run `probeSkill()` after the install.

package/guide/consumers/recipes/subject-wiki.md

@@ -0,0 +1,110 @@
+---
+id: recipe-subject-wiki
+type: primary
+depth_role: leaf
+focus: "Init a subject topic wiki (runbooks, adrs) with nested categories"
+parents:
+  - ../index.md
+tags:
+  - subject
+  - init
+  - hosted
+  - consumers
+activation:
+  keyword_matches:
+    - subject wiki
+    - runbooks wiki
+    - adr wiki
+    - nested categories
+  tag_matches:
+    - subject
+    - init
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: subject wiki
+
+## Trigger
+
+Your consumer wants to manage a topic whose entries group by subject (runbooks, architecture decisions, playbooks). The wiki grows by adding subcategories, not dates.
+
+## Commands
+
+```bash
+skill-llm-wiki init .development/shared/runbooks \
+  --kind subject --template runbooks --json
+
+# After init, build (one-time):
+skill-llm-wiki build .development/shared/runbooks \
+  --layout-mode hosted --target .development/shared/runbooks --json
+```
+
+Available subject templates:
+
+| Template | Best for |
+|---|---|
+| `runbooks` | operational runbooks, playbooks, incident response |
+| `adrs` | architecture decision records (zero-padded sequential prefix) |
+
+If you omit `--template`, `--kind subject` falls back to `runbooks`.
+
+## Category promotion rule
+
+Both shipped templates encode the same invariant in their `global_invariants`: create a subject subfolder on the first write, and grow the hierarchy whenever two or more leaves share a defensible grouping. Never pile leaves at the topic root after a threshold — do it on write.
+
+Your consumer should:
+
+1. Pick the subject subfolder before writing the leaf.
+2. Write the leaf at the deepest valid category path.
+3. Run `heal` (see [post-write-heal.md](post-write-heal.md)) so `validate` catches drift from the invariant.
+
+## Envelope fields
+
+Same `init` envelope as the dated recipe:
+
+```json
+{
+  "schema": "skill-llm-wiki/v1",
+  "command": "init",
+  "verdict": "initialised",
+  "target": "/abs/.../runbooks",
+  "artifacts": { "created": ["/abs/.../.llmwiki.layout.yaml"] },
+  "diagnostics": [{ "code": "NEXT-01", "severity": "info", "message": "..." }],
+  "next": {
+    "command": "skill-llm-wiki",
+    "args": ["build", "/abs/.../runbooks", "--layout-mode", "hosted", "--target", "/abs/.../runbooks", "--json"]
+  }
+}
+```
+
+Consumers read `env.next.command` + `env.next.args` to get the build invocation; the `NEXT-01` diagnostic carries the same hint as prose for humans tailing stdout.
+
+## Minimum consumer code
+
+```js
+import { spawnSync } from "node:child_process";
+
+function initSubject(topicPath, template = "runbooks") {
+  const r = spawnSync(
+    "skill-llm-wiki",
+    ["init", topicPath, "--kind", "subject", "--template", template, "--json"],
+    { encoding: "utf8" },
+  );
+  if (r.status !== 0) throw new Error(`init failed: ${r.stderr}`);
+  const env = JSON.parse(r.stdout);
+  // Prefer the structured `next` field over parsing NEXT-01.
+  return { contractPath: env.artifacts.created[0], next: env.next };
+}
+```
+
+## Failure modes
+
+- `verdict: "ambiguous"` with `INIT-05`: `--kind subject` does not match a dated template (`reports`, `sessions`, `regressions`, `plans`).
+- `verdict: "ambiguous"` with `INIT-07`: contract already exists; use `--force` or `rebuild`.
+- `verdict: "ambiguous"` with `INIT-08`: the topic path (or the contract path inside it) is a symbolic link. `init` refuses to follow symlinks for security. Resolve it explicitly or remove it before retrying.
+
+## Do not
+
+- Put runbooks in a flat list at the topic root. After three siblings, every new leaf should land under a named subcategory.
+- Use a date prefix or date subfolder. Subject wikis are explicitly not dated; that is why they use this template.

package/guide/consumers/recipes/testing.md

@@ -0,0 +1,149 @@
+---
+id: recipe-testing
+type: primary
+depth_role: leaf
+focus: "Use the shipped testkit in consumer test suites"
+parents:
+  - ../index.md
+tags:
+  - testing
+  - testkit
+  - fixtures
+  - consumers
+activation:
+  keyword_matches:
+    - test harness
+    - consumer tests
+    - testkit
+    - stub skill
+    - wiki fixture
+  tag_matches:
+    - testing
+    - testkit
+
+generator: "skill-llm-wiki/v1"
+---
+
+# Recipe: testing with the shipped testkit
+
+## Trigger
+
+Your consumer has tests that interact with `skill-llm-wiki` (e.g. your installer refuses without the skill present, your wiki-write workflow post-heal classifies verdicts). Use the shipped testkit instead of hand-rolling fixtures.
+
+## Commands to locate the testkit
+
+```bash
+skill-llm-wiki where --json | jq -r '.testkit_dir'
+```
+
+The returned absolute path contains:
+
+- `stub-skill.mjs` — seed a presence-only skill under `.claude/skills/` or `.agents/skills/`.
+- `make-wiki-fixture.mjs` — build a minimal hosted-mode wiki at a temp path using the shipped templates.
+- `assert-frontmatter.mjs` — parse a leaf's frontmatter and assert expected fields.
+- `cli-run.mjs` — spawn the CLI, capture stdout/stderr/status, auto-parse the envelope.
+
+> **About `<testkit_dir>` in the code below:** the literal string
+> `<testkit_dir>` is a placeholder. Resolve it at test-load time via
+> the `where` probe, and convert the filesystem path to a `file://`
+> URL before passing it to dynamic `import()` — Node ESM requires
+> this on Windows (where `TESTKIT` looks like `C:\...`) and it is
+> harmless on POSIX. Example:
+>
+> ```js
+> import { spawnSync } from "node:child_process";
+> import { pathToFileURL } from "node:url";
+> const WHERE = JSON.parse(
+>   spawnSync("skill-llm-wiki", ["where", "--json"], { encoding: "utf8" }).stdout,
+> );
+> const TESTKIT = WHERE.testkit_dir;
+> const { stubSkill } = await import(
+>   pathToFileURL(`${TESTKIT}/stub-skill.mjs`).href,
+> );
+> ```
+>
+> Do not copy the `<testkit_dir>/stub-skill.mjs` string verbatim
+> into your imports — it will not resolve.
+
+## Consumer test code
+
+### Presence stub (replaces hand-rolled `wikiSkillStub`)
+
+```js
+import { test } from "node:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stubSkill } from "<testkit_dir>/stub-skill.mjs";
+
+test("installer refuses when skill is absent", async () => {
+  const home = mkdtempSync(join(tmpdir(), "test-"));
+  // Do NOT call stubSkill — simulate the absent case.
+  const r = await runInstaller({ env: { HOME: home } });
+  assert.equal(r.status, 1);
+  assert.match(r.stderr, /skill-llm-wiki is not installed/);
+});
+
+test("installer proceeds when stub is present", async () => {
+  const home = mkdtempSync(join(tmpdir(), "test-"));
+  await stubSkill({ home });
+  const r = await runInstaller({ env: { HOME: home } });
+  assert.equal(r.status, 0);
+});
+```
+
+### Fixture wiki (for exercising write workflows)
+
+```js
+import { makeWikiFixture } from "<testkit_dir>/make-wiki-fixture.mjs";
+
+test("my consumer writes a report leaf in the right shape", async () => {
+  const wiki = await makeWikiFixture({
+    path: join(tmpdir(), `reports-${Date.now()}`),
+    kind: "dated",
+    template: "reports",
+    seedLeaves: ["2026/04/18/example.md"],
+  });
+  // Now drive your consumer write code against `wiki.path`.
+  await writeMyLeaf(wiki.path, "2026/04/18/new-report.md", "content");
+  assert.ok(existsSync(join(wiki.path, "2026/04/18/new-report.md")));
+});
+```
+
+### CLI run (for end-to-end verdict-handling tests)
+
+```js
+import { runCli } from "<testkit_dir>/cli-run.mjs";
+
+test("heal on a fresh wiki returns verdict=ok", async () => {
+  const wiki = await makeWikiFixture({ path: tmpWiki(), kind: "dated" });
+  const r = runCli(["heal", wiki.path, "--json"]);
+  assert.equal(r.envelope.verdict, "ok");
+});
+```
+
+### Frontmatter assertions
+
+```js
+import { assertFrontmatterShape } from "<testkit_dir>/assert-frontmatter.mjs";
+
+test("my consumer writes the expected frontmatter", async () => {
+  await writeMyLeaf(wiki.path, "2026/04/18/leaf.md", "content");
+  assertFrontmatterShape(join(wiki.path, "2026/04/18/leaf.md"), {
+    type: "primary",
+    depth_role: "leaf",
+    focus: "leaf",
+  });
+});
+```
+
+## Failure modes
+
+- `testkit_dir` is `null`: you are running against an old skill version without the testkit. Gate on `format_version >= 1` in CI.
+- `stubSkill` fails with "unknown layout": pass one of `"claude-skills"` or `"agents-skills"`.
+- `makeWikiFixture` fails on the template lookup: pass a name matching one of the shipped templates (see [dated-wiki.md](dated-wiki.md) / [subject-wiki.md](subject-wiki.md)).
+
+## Do not
+
+- Import from `scripts/lib/` in your tests. Those are internal; only `scripts/testkit/` is part of the consumer contract.
+- Hand-roll parallel stub helpers once this testkit exists. Drift between your stub and the skill's canonical shape is a real bug source.

package/guide/index.md

@@ -74,6 +74,13 @@ entries:
     file: "ux/index.md"
     type: index
     focus: User-facing intent resolution and preflight failure messaging.
+  - id: consumers
+    file: "consumers/index.md"
+    type: index
+    focus: "Integrating another skill or agent as a consumer of skill-llm-wiki."
+    tags:
+      - consumers
+      - integration
 children:
   - "basics/index.md"
   - "correctness/index.md"
@@ -83,6 +90,7 @@ children:
   - "operations/index.md"
   - "substrate/index.md"
   - "ux/index.md"
+  - "consumers/index.md"
 ---
 <!-- BEGIN AUTO-GENERATED NAVIGATION -->
 
@@ -110,6 +118,7 @@ children:
 | [operations/index.md](operations/index.md) | 📁 index | per-operation phase pipelines for Build, Extend, Validate, Rebuild, Fix, and Join |
 | [substrate/index.md](substrate/index.md) | 📁 index | Decision machinery — rewrite operators and the tiered AI ladder driving them. |
 | [ux/index.md](ux/index.md) | 📁 index | User-facing intent resolution and preflight failure messaging. |
+| [consumers/index.md](consumers/index.md) | 📁 index | Integrating another skill or agent as a consumer of skill-llm-wiki. |
 
 <!-- END AUTO-GENERATED NAVIGATION -->
 

package/guide/ux/user-intent.md

@@ -9,7 +9,7 @@ covers:
   - the CLI refuses every ambiguous invocation with a structured INT-NN code
   - Claude MUST ask the user before running the skill when intent is unclear
   - ambiguity scenarios each have a fixed resolving flag the user can pick
-  - "--json-errors makes the ambiguity body machine-parseable for Claude to read"
+  - "--json (canonical) or --json-errors (legacy alias) makes the ambiguity body machine-parseable for Claude to read"
   - "--no-prompt / LLM_WIKI_NO_PROMPT=1 disables interactive fallback; failures become hard errors"
   - never silently default — the cost of a wrong guess is always higher than a clarifying question
 tags:
@@ -82,11 +82,12 @@ in the wrong place) is always higher than a one-sentence clarifying question.
 | INT-12 | Prompt required in non-interactive mode | supply the flag the prompt was asking for, or re-run in a TTY |
 | INT-13 | Unknown `--quality-mode` value | use `tiered-fast` / `claude-first` / `tier0-only` |
 
-## `--json-errors` for programmatic consumption
+## `--json` for programmatic consumption
 
 When the skill is called from a script or from another Claude session, pass
-`--json-errors` on every invocation. The ambiguity body becomes a single JSON
-object on stderr:
+`--json` (canonical) on every invocation; `--json-errors` is the legacy alias
+and continues to work. The ambiguity body becomes a single JSON object on
+stderr:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctxr/skill-llm-wiki",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Claude Code skill — build, extend, validate, rebuild, fix, and join LLM wikis from any knowledge corpus. Token-efficient retrieval via hierarchical indices, DAG parents, and deterministic rewrite operators.",
   "type": "module",
   "license": "MIT",
@@ -31,12 +31,16 @@
     "LICENSE",
     "CHANGELOG.md",
     "scripts/",
-    "guide/"
+    "guide/",
+    "templates/"
   ],
   "ctxr": {
     "type": "skill",
     "target": "folder"
   },
+  "bin": {
+    "skill-llm-wiki": "scripts/cli.mjs"
+  },
   "scripts": {
     "test": "node --test",
     "validate": "node scripts/cli.mjs --version",