@theglitchking/hit-em-with-the-docs 2.1.1 → 2.3.0

package/dist/utils/config.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Plugin config loader for `.claude/hit-em-with-the-docs.json`.
+ *
+ * The runtime (`@theglitchking/claude-plugin-runtime`) owns the
+ * `updatePolicy` field. This module reads the same file and adds the
+ * 2.3.0 `vault` block for knowledge-base configuration. Missing or
+ * malformed files fall back to defaults — never throws.
+ */
+import { z } from 'zod';
+export declare const DEFAULT_VAULT_ROOT = ".documentation/knowledge-base/";
+export declare const DEFAULT_PLAYBOOK_GLOBS: string[];
+export declare const DEFAULT_AUDIT_WINDOW_DAYS = 90;
+/**
+ * Schema for `.claude/hit-em-with-the-docs.json`. Every field is optional
+ * with a sensible default. The runtime's `updatePolicy` is preserved via
+ * `.passthrough()`.
+ */
+declare const vaultConfigSchema: z.ZodDefault<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+    playbook_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    audit_window_days: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    root: string;
+    playbook_paths: string[];
+    audit_window_days: number;
+}, {
+    root?: string | undefined;
+    playbook_paths?: string[] | undefined;
+    audit_window_days?: number | undefined;
+}>>;
+declare const pluginConfigSchema: z.ZodObject<{
+    vault: z.ZodDefault<z.ZodObject<{
+        root: z.ZodDefault<z.ZodString>;
+        playbook_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        audit_window_days: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        root: string;
+        playbook_paths: string[];
+        audit_window_days: number;
+    }, {
+        root?: string | undefined;
+        playbook_paths?: string[] | undefined;
+        audit_window_days?: number | undefined;
+    }>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    vault: z.ZodDefault<z.ZodObject<{
+        root: z.ZodDefault<z.ZodString>;
+        playbook_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        audit_window_days: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        root: string;
+        playbook_paths: string[];
+        audit_window_days: number;
+    }, {
+        root?: string | undefined;
+        playbook_paths?: string[] | undefined;
+        audit_window_days?: number | undefined;
+    }>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    vault: z.ZodDefault<z.ZodObject<{
+        root: z.ZodDefault<z.ZodString>;
+        playbook_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        audit_window_days: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        root: string;
+        playbook_paths: string[];
+        audit_window_days: number;
+    }, {
+        root?: string | undefined;
+        playbook_paths?: string[] | undefined;
+        audit_window_days?: number | undefined;
+    }>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type VaultConfig = z.infer<typeof vaultConfigSchema>;
+export type PluginConfig = z.infer<typeof pluginConfigSchema>;
+/**
+ * Load the plugin config for a project, applying defaults. Never throws —
+ * missing file, malformed JSON, and invalid shapes all fall through to
+ * defaults. Pass `projectRoot` (defaults to `process.cwd()`) to control
+ * which directory to read from.
+ */
+export declare function loadPluginConfig(projectRoot?: string): Promise<PluginConfig>;
+/**
+ * Synchronous variant — used in test setup where async loading is awkward.
+ * Same fail-open behavior.
+ */
+export declare function loadPluginConfigSync(projectRoot?: string): PluginConfig;
+/**
+ * Resolve the vault root for a project, applying config + defaults.
+ * The returned path is absolute.
+ */
+export declare function resolveVaultRoot(projectRoot: string, config: PluginConfig): string;
+/**
+ * Resolve playbook scan globs relative to project root, as absolute glob
+ * patterns. Returned globs are suitable for `glob` library consumption.
+ */
+export declare function resolvePlaybookGlobs(projectRoot: string, config: PluginConfig): string[];
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/utils/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,kBAAkB,mCAAmC,CAAC;AACnE,eAAO,MAAM,sBAAsB,UAA6B,CAAC;AACjE,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;;GAIG;AACH,QAAA,MAAM,iBAAiB;;;;;;;;;;;;GAMT,CAAC;AAEf,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAIR,CAAC;AAEjB,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAkBlF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,CAoBvE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAElF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,YAAY,GACnB,MAAM,EAAE,CAEV"}

package/dist/utils/config.js

@@ -0,0 +1,95 @@
+/**
+ * Plugin config loader for `.claude/hit-em-with-the-docs.json`.
+ *
+ * The runtime (`@theglitchking/claude-plugin-runtime`) owns the
+ * `updatePolicy` field. This module reads the same file and adds the
+ * 2.3.0 `vault` block for knowledge-base configuration. Missing or
+ * malformed files fall back to defaults — never throws.
+ */
+import { readFile } from 'fs/promises';
+import { join, resolve } from 'path';
+import { z } from 'zod';
+export const DEFAULT_VAULT_ROOT = '.documentation/knowledge-base/';
+export const DEFAULT_PLAYBOOK_GLOBS = ['.documentation/**/*.md'];
+export const DEFAULT_AUDIT_WINDOW_DAYS = 90;
+/**
+ * Schema for `.claude/hit-em-with-the-docs.json`. Every field is optional
+ * with a sensible default. The runtime's `updatePolicy` is preserved via
+ * `.passthrough()`.
+ */
+const vaultConfigSchema = z
+    .object({
+    root: z.string().default(DEFAULT_VAULT_ROOT),
+    playbook_paths: z.array(z.string()).default(DEFAULT_PLAYBOOK_GLOBS),
+    audit_window_days: z.number().int().positive().default(DEFAULT_AUDIT_WINDOW_DAYS),
+})
+    .default({});
+const pluginConfigSchema = z
+    .object({
+    vault: vaultConfigSchema,
+})
+    .passthrough();
+const CONFIG_FILENAME = '.claude/hit-em-with-the-docs.json';
+/**
+ * Load the plugin config for a project, applying defaults. Never throws —
+ * missing file, malformed JSON, and invalid shapes all fall through to
+ * defaults. Pass `projectRoot` (defaults to `process.cwd()`) to control
+ * which directory to read from.
+ */
+export async function loadPluginConfig(projectRoot) {
+    const root = projectRoot ?? process.cwd();
+    const configPath = resolve(root, CONFIG_FILENAME);
+    let raw;
+    try {
+        const contents = await readFile(configPath, 'utf-8');
+        raw = JSON.parse(contents);
+    }
+    catch {
+        raw = {};
+    }
+    const parsed = pluginConfigSchema.safeParse(raw);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    // Malformed config — return defaults rather than crash.
+    return pluginConfigSchema.parse({});
+}
+/**
+ * Synchronous variant — used in test setup where async loading is awkward.
+ * Same fail-open behavior.
+ */
+export function loadPluginConfigSync(projectRoot) {
+    const root = projectRoot ?? process.cwd();
+    const configPath = resolve(root, CONFIG_FILENAME);
+    let raw;
+    try {
+        // Lazy require to avoid hoisting an fs dep when this code path isn't used.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { readFileSync } = require('fs');
+        const contents = readFileSync(configPath, 'utf-8');
+        raw = JSON.parse(contents);
+    }
+    catch {
+        raw = {};
+    }
+    const parsed = pluginConfigSchema.safeParse(raw);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    return pluginConfigSchema.parse({});
+}
+/**
+ * Resolve the vault root for a project, applying config + defaults.
+ * The returned path is absolute.
+ */
+export function resolveVaultRoot(projectRoot, config) {
+    return resolve(projectRoot, config.vault.root);
+}
+/**
+ * Resolve playbook scan globs relative to project root, as absolute glob
+ * patterns. Returned globs are suitable for `glob` library consumption.
+ */
+export function resolvePlaybookGlobs(projectRoot, config) {
+    return config.vault.playbook_paths.map((p) => join(projectRoot, p));
+}
+//# sourceMappingURL=config.js.map

package/dist/utils/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/hit-em-with-the-docs",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Self-managing documentation system with hierarchical structure, intelligent automation, pattern discovery, and agent orchestration",
   "type": "module",
   "main": "dist/cli/index.js",

package/templates/knowledge-base/README.md

@@ -0,0 +1,31 @@
+# Knowledge-base templates
+
+LLM-referenceable templates for authoring the four knowledge-base primitives
+shipped in 2.3.0. Each template shows the full required + commonly-optional
+frontmatter, the validation rules in comments, and a body skeleton with
+conventional sections.
+
+| Template | When to use |
+|---|---|
+| `fact.template.md` | A single citable claim with verify command. Lives at `<vault-root>/facts/<id>.md`. |
+| `incident-narrative.template.md` | An immutable postmortem. Lives at `<vault-root>/incidents/<YYYY-MM-DD-slug>/narrative.md`. |
+| `incident-facts.template.md` | The bridge linking an incident to the facts it produced. Lives at `<vault-root>/incidents/<YYYY-MM-DD-slug>/facts.md`. |
+| `playbook-symptoms.template.md` | A snippet showing how to enrich an EXISTING playbook with a `symptoms:` block. Not a tier on its own. |
+
+## For LLMs
+
+These templates are the canonical reference when creating new knowledge-base
+articles. The frontmatter shows every field the validator looks for. Comments
+inline (where the YAML allows) explain enums, constraints, and what counts
+as required vs. optional.
+
+When asked to create a new fact / incident / playbook entry:
+
+1. Read the corresponding template.
+2. Replace every `<placeholder>` with concrete content.
+3. Run `hewtd audit --strict` on the parent directory to confirm validity.
+
+## Validation reference
+
+See `docs/knowledge-base-primitives.md` (in the plugin repo) for the full
+schema reference, the list of error codes, and worked examples.

package/templates/knowledge-base/fact.template.md

@@ -0,0 +1,44 @@
+---
+title: <Short human-readable claim — e.g. "Alloy reads env only at entrypoint">
+tier: fact
+domains:
+  - <domain-1>
+  # - <domain-2>   # optional additional domains
+status: active     # one of: draft | active | deprecated | archived | weakened
+last_updated: YYYY-MM-DD
+id: <kebab-case-slug>           # MUST match the filename without `.md`
+confidence: high                # one of: high | medium | low | hypothesis
+last_verified: YYYY-MM-DD       # the date a human (or `hewtd audit-facts --run-verify`) confirmed the claim
+verify_command: |               # OPTIONAL but strongly recommended — a single shell command that proves the claim
+  <one-line command, e.g. `docker exec alloy printenv VAULT_TOKEN | head -c 10`>
+# For multi-line scripts, start with a shebang:
+# verify_command: |
+#   #!/usr/bin/env bash
+#   set -euo pipefail
+#   <command 1>
+#   <command 2>
+working_dir: <vault-root>/facts/   # OPTIONAL — CWD for verify_command; defaults to the facts dir if omitted
+provenance:                     # REQUIRED — at least one entry; where this fact came from
+  - <incidents/YYYY-MM-DD-incident-slug/>   # or a source path, or a postmortem reference
+sources:                        # OPTIONAL — code/config paths that embody this fact
+  - <repo-relative/path/to/file>
+tags:
+  - <tag-1>
+  - <tag-2>
+invalidated_by:                 # OPTIONAL — conditions under which this fact would no longer hold
+  - <free-text condition>
+---
+
+# <Same as title>
+
+## Claim
+<One paragraph stating the atomic claim. One claim per fact. If you find yourself writing "and also...", split it into two facts.>
+
+## How to verify
+<How a human can confirm this claim — the prose explanation. The shell command in `verify_command:` is the machine-runnable version.>
+
+## Consequences
+<What this means in practice. What workflows it affects. Why a reader should care.>
+
+## See also
+<Optional cross-links to related facts, incidents, or runbooks.>

package/templates/knowledge-base/incident-facts.template.md

@@ -0,0 +1,31 @@
+---
+title: Facts from YYYY-MM-DD <incident-slug>
+tier: incident-facts
+domains:
+  - incidents
+status: active                # active | archived
+last_updated: YYYY-MM-DD
+incident_id: YYYY-MM-DD-<kebab-slug>   # MUST match the parent folder name AND the sibling narrative.md's id
+produced:                              # REQUIRED — array, may be EMPTY if the incident produced no new facts
+  - <fact-id-1>
+  - <fact-id-2>
+strengthened:                          # OPTIONAL — facts whose confidence increased because of this incident
+  - <fact-id-a>
+weakened:                              # OPTIONAL — facts whose confidence decreased
+  - <fact-id-b>
+---
+
+# Facts from YYYY-MM-DD <incident-slug>
+
+## Produced
+<One line per produced fact, with a short justification tying it to the incident evidence.>
+- `<fact-id-1>` — <one-sentence justification: what during the incident proved this fact>
+- `<fact-id-2>` — <one-sentence justification>
+
+## Strengthened
+<For each strengthened fact, one line on what new evidence raised confidence.>
+- `<fact-id-a>` — <reason confidence increased>
+
+## Weakened
+<For each weakened fact, one line on what evidence contradicts it.>
+- `<fact-id-b>` — <reason confidence decreased>

package/templates/knowledge-base/incident-narrative.template.md

@@ -0,0 +1,50 @@
+---
+title: <Human-readable incident title — e.g. "Vault Down on Auth-Staging">
+tier: incident-narrative
+domains:
+  - incidents
+  - <additional-domain>   # e.g. observability, security
+status: active            # active | resolved | archived
+last_updated: YYYY-MM-DD
+id: YYYY-MM-DD-<kebab-slug>   # MUST match the parent folder name (e.g. 2026-05-14-vault-alloy-stuck)
+date: YYYY-MM-DD              # the date the incident occurred
+severity: high                # one of: low | medium | high | critical
+resolution_status: resolved   # one of: resolved | partial | open | planned
+components:                   # REQUIRED — at least one component affected
+  - <system-1>
+  - <system-2>
+tags:
+  - <tag-1>
+  - <tag-2>
+---
+
+# <Same as title>
+
+## Summary
+<One-paragraph TL;DR of what happened and how it was resolved.>
+
+## Timeline
+- HH:MM — <event 1>
+- HH:MM — <event 2>
+- HH:MM — <event 3>
+- HH:MM — <resolution event>
+
+## Root Cause
+<The actual cause. Be specific. If unknown, say "Unknown — see Open Questions".>
+
+## Impact
+<Who/what was affected. Duration. Severity rationale. Was customer-facing? Was data lost?>
+
+## Resolution
+<How it was fixed. The exact action taken.>
+
+## Lessons Learned
+- <Lesson 1 — short, actionable>
+- <Lesson 2>
+
+## Open Questions
+- <Anything unresolved that needs follow-up>
+
+## See also
+- `facts.md` — facts produced/strengthened/weakened by this incident
+- <Optional links to related incidents or runbooks>

package/templates/knowledge-base/playbook-symptoms.template.md

@@ -0,0 +1,74 @@
+# Playbook with symptoms — frontmatter snippet
+
+> This is NOT a standalone tier — it's a snippet showing how to enrich an
+> EXISTING playbook (any tier: guide, admin, reference, etc.) with a
+> `symptoms:` block. The plugin scans configured playbook paths, extracts
+> symptoms blocks, and generates `<vault-root>/symptoms/INDEX.md`.
+
+## Where this goes
+
+Drop the `symptoms:` block into the frontmatter of an existing markdown file.
+Keep the file's existing `tier:`, `domains:`, `status:`, etc. unchanged. Only
+the `symptoms:` field is being added.
+
+## Frontmatter snippet
+
+```yaml
+---
+title: <existing title, unchanged>
+tier: <existing tier — typically guide or admin for runbooks>
+domains:
+  - <existing domain>
+status: active
+last_updated: YYYY-MM-DD
+version: 1.0.0          # required for non-lifecycle tiers
+
+# ↓↓↓ The new bit ↓↓↓
+symptoms:
+  # 1. Exact alert name (e.g. from Grafana, Prometheus AlertManager).
+  #    Matched character-for-character.
+  - alert_name: "<exact alert name as it arrives from the alerting system>"
+    severity: critical              # one of: low | medium | high | critical
+    target: "#<anchor-in-this-file>"  # the heading the playbook step lives under
+    cites:                          # REQUIRED — array of fact ids the playbook depends on
+      - <fact-id-1>
+      - <fact-id-2>
+
+  # 2. User phrase (free-form support requests). Fuzzy substring match (lowercased).
+  - user_phrase:
+      - "<phrase 1>"
+      - "<phrase 2>"
+    severity: medium
+    target: "#<same-or-different-anchor>"
+    cites:
+      - <fact-id-1>
+
+  # 3. Error pattern (log lines, stack traces). Regex match.
+  - error_pattern: "<JavaScript-style regex, escaped as needed>"
+    severity: high
+    target: "#<anchor>"
+    cites:
+      - <fact-id-3>
+---
+```
+
+## What `cites:` does
+
+`cites:` binds playbook steps to facts. When a fact changes (e.g. its
+`confidence:` drops, or it's marked `invalidated_by:` something), the
+plugin can flag every playbook that cites it as potentially stale. This is
+the load-bearing field for drift detection.
+
+If you cite a fact id that doesn't exist, `hewtd audit --strict` will emit
+a `PLAYBOOK_SYMPTOM_DANGLING_CITE` error.
+
+## Tip: use `hewtd cite <fact-id>` to insert
+
+You don't have to write the citation by hand. Inside a playbook file:
+
+```bash
+hewtd cite <fact-id> --file <path-to-this-playbook>
+```
+
+This inserts a properly-formatted entry into the nearest `symptoms:` block,
+creating one if it doesn't exist. (`hewtd cite` ships in 2.3.0 PR3.)