@theglitchking/hit-em-with-the-docs 2.7.0 → 2.8.0

package/dist/utils/glob.d.ts

@@ -9,10 +9,21 @@ export interface GlobOptions {
  */
 export declare function glob(pattern: string, options?: GlobOptions): Promise<string[]>;
 /**
- * Reserved documentation subdirectory for DEPRECATED docs. Anything under
- * `<docs>/archive/` is intentionally excluded from every hewtd scan (audit,
- * link-check, metadata-sync, integrate dup-detection, link graph, search) —
- * it's a parking lot for retired docs, not part of the active corpus.
+ * Reserved documentation subdirectory for DEPRECATED docs.
+ *
+ * **Archived content is referenceable, never concrete.** A link *into* the
+ * archive still resolves — link-check validates targets by file existence, so
+ * history stays reachable. But nothing under an `archive/` folder is part of
+ * the active corpus: it is not indexed, not audited, not metadata-validated,
+ * not dup-checked, and never counted. It is what the docs *used* to say, and it
+ * is never evidence of what is true now.
+ *
+ * The exclusion applies at **any depth** — `<docs>/archive/` and
+ * `<docs>/features/archive/` alike. Before 2.8.0 the ignore glob was anchored
+ * at the docs root, so a nested `archive/` was still scanned and validated
+ * (while 2.7.1's indexer correctly skipped it) — archived docs could raise
+ * audit errors and stale-metadata warnings for content nobody was supposed to
+ * be reading.
  */
 export declare const ARCHIVE_DIR = "archive";
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/utils/glob.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,wBAAsB,IAAI,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,YAAY,CAAC;AAUrC;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAM,GAC1C,OAAO,CAAC,MAAM,EAAE,CAAC,CAQnB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOhE;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAStE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD"}
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/utils/glob.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,wBAAsB,IAAI,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,YAAY,CAAC;AAWrC;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAM,GAC1C,OAAO,CAAC,MAAM,EAAE,CAAC,CAQnB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOhE;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAStE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/utils/glob.js

@@ -17,10 +17,21 @@ export async function glob(pattern, options = {}) {
     return matches;
 }
 /**
- * Reserved documentation subdirectory for DEPRECATED docs. Anything under
- * `<docs>/archive/` is intentionally excluded from every hewtd scan (audit,
- * link-check, metadata-sync, integrate dup-detection, link graph, search) —
- * it's a parking lot for retired docs, not part of the active corpus.
+ * Reserved documentation subdirectory for DEPRECATED docs.
+ *
+ * **Archived content is referenceable, never concrete.** A link *into* the
+ * archive still resolves — link-check validates targets by file existence, so
+ * history stays reachable. But nothing under an `archive/` folder is part of
+ * the active corpus: it is not indexed, not audited, not metadata-validated,
+ * not dup-checked, and never counted. It is what the docs *used* to say, and it
+ * is never evidence of what is true now.
+ *
+ * The exclusion applies at **any depth** — `<docs>/archive/` and
+ * `<docs>/features/archive/` alike. Before 2.8.0 the ignore glob was anchored
+ * at the docs root, so a nested `archive/` was still scanned and validated
+ * (while 2.7.1's indexer correctly skipped it) — archived docs could raise
+ * audit errors and stale-metadata warnings for content nobody was supposed to
+ * be reading.
  */
 export const ARCHIVE_DIR = 'archive';
 /** Glob ignores always applied to documentation scans. */
@@ -29,6 +40,7 @@ const DOC_SCAN_IGNORE = [
     'dist/**',
     '.git/**',
     `${ARCHIVE_DIR}/**`,
+    `**/${ARCHIVE_DIR}/**`,
 ];
 /**
  * Find all markdown files in a directory.

package/dist/utils/glob.js.map

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

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "hit-em-with-the-docs SessionStart hook — nudges/auto-updates per policy.",
+  "description": "hit-em-with-the-docs hooks — SessionStart (update check + lifecycle brief) and PreToolUse (lifecycle enforcement).",
   "hooks": {
     "SessionStart": [
       {
@@ -7,6 +7,21 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-brief.js\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-use.js\""
           }
         ]
       }

package/hooks/pre-tool-use.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// hit-em-with-the-docs PreToolUse hook — lifecycle enforcement.
+//
+// Denies the two irreversible policy violations (hand-editing a generated
+// INDEX.md/REGISTRY.md, deleting a doc) and warns on the off-policy ones.
+//
+// This runs in EVERY session the plugin is installed in, including repos that
+// have nothing to do with hewtd. Two invariants follow, and they matter more
+// than any rule this file enforces:
+//
+//   1. No `.documentation/` tree (or whatever `docsDir` resolves to) → allow,
+//      immediately and silently.
+//   2. ANY error → allow. A guard that blocks a user's unrelated work because
+//      it threw is far worse than no guard at all. Every path fails open.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/** Allow the call and exit. Never throws, never blocks. */
+function allow() {
+  process.exit(0);
+}
+
+function respond(payload) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'PreToolUse', ...payload },
+    })
+  );
+  process.exit(0);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+/**
+ * Resolve the docs root and the enforcement policy for this project.
+ * `.claude/hit-em-with-the-docs.json` may carry an `enforcement` block; a
+ * missing or malformed config just means defaults.
+ */
+function loadProject(cwd) {
+  let policy = { blockIndexEdits: true, blockDocDeletion: true };
+  try {
+    const raw = readFileSync(join(cwd, '.claude', 'hit-em-with-the-docs.json'), 'utf-8');
+    const cfg = JSON.parse(raw);
+    const e = cfg?.enforcement;
+    if (e && typeof e === 'object') {
+      if (e.block_index_edits === false) policy.blockIndexEdits = false;
+      if (e.block_doc_deletion === false) policy.blockDocDeletion = false;
+    }
+  } catch {
+    // No config, or unreadable — defaults apply.
+  }
+  return { docsDir: '.documentation', policy };
+}
+
+async function main() {
+  const input = await readStdin();
+  if (!input.trim()) allow();
+
+  const payload = JSON.parse(input);
+  const cwd = payload.cwd || process.cwd();
+
+  // Invariant 1: not a hewtd project → this hook has no opinion.
+  if (!existsSync(resolve(cwd, '.documentation'))) allow();
+
+  const { docsDir, policy } = loadProject(cwd);
+
+  // The decision function ships compiled in dist/, so the hook stays a thin
+  // I/O shell and the rules themselves are unit-testable.
+  const { evaluate } = await import('../dist/core/enforce/guard.js');
+
+  const toolInput = payload.tool_input ?? {};
+  const decision = evaluate(
+    {
+      toolName: payload.tool_name,
+      filePath: toolInput.file_path,
+      command: toolInput.command,
+      text: toolInput.content ?? toolInput.new_string,
+      docsDir,
+    },
+    policy
+  );
+
+  if (decision.action === 'deny') {
+    respond({ permissionDecision: 'deny', permissionDecisionReason: decision.reason });
+  }
+  if (decision.action === 'warn') {
+    respond({ permissionDecision: 'allow', additionalContext: decision.context });
+  }
+  allow();
+}
+
+// Invariant 2: fail open, unconditionally.
+main().catch(() => allow());

package/hooks/session-brief.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// hit-em-with-the-docs SessionStart hook — the lifecycle brief.
+//
+// A separate hook from session-start.js on purpose: the plugin runtime owns
+// stdout for that one (it always emits exactly one SessionStart response for
+// the update check, and offers no way to append to it). Claude Code runs every
+// registered SessionStart hook and merges their context, so this stays
+// decoupled from the runtime instead of monkey-patching it.
+//
+// Emits nothing at all outside a hewtd-managed project.
+//
+// This exists because the policy used to live only in the README and in an
+// orphaned template that was never installed: an agent that had never heard of
+// hewtd would `rm` a stale doc, hand-edit a generated INDEX.md, or invent its
+// own `docs/` folder. The PreToolUse guard now denies the destructive half of
+// that; this is what stops the agent walking into the guard in the first place.
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+// Not a hewtd project → say nothing. This hook runs in every session the
+// plugin is installed in, most of which have no documentation tree.
+if (!existsSync(resolve(projectRoot, '.documentation'))) {
+  process.exit(0);
+}
+
+// Stated as facts, not instructions. Imperative text injected into context can
+// trip Claude's prompt-injection defenses; a description of how the repo works
+// does not.
+const BRIEF = `This project's documentation is managed by hit-em-with-the-docs (hewtd), under \`.documentation/\`, organized into domains (security, api, database, …).
+
+How the tree works:
+- \`INDEX.md\` and \`REGISTRY.md\` are **generated artifacts**, rebuilt from the documents on disk. Hand-edits to them are overwritten by the next \`hewtd index\`. To change what an index lists, change the documents.
+- New docs are registered with \`hewtd integrate <file>\`, which classifies them into a domain and adds the frontmatter. Markdown created outside \`.documentation/\` is not indexed, link-checked, or validated.
+- Docs are **never deleted**. \`hewtd archive <file>\` retires one: it moves the file under \`archive/\` (keeping git history), stamps \`archived_from\` so \`hewtd unarchive\` restores it exactly, and refuses if active docs still link to it. hewtd's own source contains no delete calls anywhere.
+- \`status: deprecated\` flags intent but leaves a doc live and indexed; \`hewtd archive\` is the step that actually retires it.
+- **Anything under an \`archive/\` folder is historical, at any depth.** It is excluded from every scan — not indexed, not audited, not link-checked, not validated. It can be *referenced* (links into it still resolve), but it is **never evidence of current behavior**: it is what the docs used to say. Do not cite it as how the system works today, and do not edit it. \`hewtd unarchive <file>\` restores it to active first.
+- \`hewtd maintain\` regenerates indexes, syncs metadata, and checks links. \`hewtd audit\` reports drift and policy violations.
+
+A PreToolUse hook enforces the two destructive cases: editing a generated index, and deleting a doc under \`.documentation/\`. Both are denied. Run \`/hit-em-with-the-docs:help\` for the full command surface.`;
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: BRIEF,
+    },
+  }) + '\n'
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/hit-em-with-the-docs",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Self-managing documentation system with hierarchical structure, intelligent automation, pattern discovery, and agent orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
@@ -24,6 +24,7 @@
     "dist",
     "templates",
     ".claude-plugin",
+    "skills",
     "commands",
     "hooks",
     "scripts/link-skills.js",

package/scripts/link-skills.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 // Postinstall — delegates to @theglitchking/claude-plugin-runtime.
-// hit-em-with-the-docs ships no bundled skills, so skillsDir is null;
-// the runtime still writes the default update-policy config and
-// registers the SessionStart hook in .claude/settings.json (with
+// Links the bundled skill (skills/documentation-lifecycle) into
+// .claude/skills/ for npm installs; plugin installs get it automatically via
+// the plugin's skills/ dir. The runtime also writes the default update-policy
+// config and registers the SessionStart hook in .claude/settings.json (with
 // plugin-vs-npm dedup).
 
 import { runPostinstall } from "@theglitchking/claude-plugin-runtime";
@@ -16,7 +17,7 @@ try {
     packageName: "@theglitchking/hit-em-with-the-docs",
     pluginName: "hit-em-with-the-docs",
     configFile: "hit-em-with-the-docs.json",
-    skillsDir: null,
+    skillsDir: "skills",
     packageRoot,
     hookCommand:
       "node ./node_modules/@theglitchking/hit-em-with-the-docs/hooks/session-start.js",

package/skills/documentation-lifecycle/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: documentation-lifecycle
+description: Create, update, retire, or reorganize documentation in a project managed by hit-em-with-the-docs (a `.documentation/` tree with domain folders). Use when writing a new doc, updating an existing one, deleting/deprecating/archiving a doc, fixing a broken docs link, wondering where a doc belongs, or when an INDEX.md/REGISTRY.md looks out of date. Also use when a tool call was denied by the hewtd lifecycle guard.
+---
+
+# Documentation lifecycle (hit-em-with-the-docs)
+
+This project's docs live in `.documentation/`, split into domain folders. hewtd
+owns that tree: it classifies documents, maintains their frontmatter, generates
+the indexes, checks the links, and retires docs without destroying them.
+
+**The one thing to internalize:** `INDEX.md` and `REGISTRY.md` are *generated*.
+They are rebuilt from the documents on disk on every `hewtd index` / `hewtd
+maintain`. Editing them by hand accomplishes nothing — your rows are overwritten
+on the next run. To change what an index says, change the documents, then
+regenerate.
+
+Run every command with `npx hit-em-with-the-docs …` (or `hewtd …`).
+
+## Creating a doc
+
+Write the markdown wherever is convenient, then:
+
+```bash
+hewtd integrate path/to/new-doc.md          # classifies + moves + registers it
+hewtd integrate path/to/new-doc.md --dry-run  # preview the chosen domain first
+```
+
+`integrate` picks the domain by keyword-matching the content, moves the file
+into `.documentation/<domain>/`, stamps frontmatter (`status: draft`, `tier:
+guide`, `version: 1.0.0`, `last_updated`, `word_count`), and regenerates the
+indexes. It never overwrites frontmatter you wrote yourself — it only fills what
+is missing.
+
+A markdown file left outside `.documentation/` is invisible to hewtd: not
+indexed, not link-checked, not validated. Don't hand-create `docs/` folders.
+
+## Updating a doc
+
+Edit the document normally, then:
+
+```bash
+hewtd maintain --quick     # regenerate indexes + sync metadata
+hewtd maintain --fix       # also auto-fix what it can
+```
+
+Never hand-edit `INDEX.md` or `REGISTRY.md` — a `PreToolUse` guard denies it.
+
+## Retiring a doc
+
+**Documents are never deleted.** hewtd's own source contains no `rm`/`unlink`
+calls anywhere, and the guard denies shell deletion of anything under
+`.documentation/`.
+
+Two distinct steps, often confused:
+
+| | What it does |
+|---|---|
+| `status: deprecated` | Flags *intent*. The doc stays in its domain folder, still indexed, still scanned. `audit` raises an INFO nudge toward archiving. |
+| `hewtd archive <file>` | Actually retires it. |
+
+```bash
+hewtd archive .documentation/api/old-guide.md --dry-run
+hewtd archive .documentation/api/old-guide.md -r "superseded by v2 guide"
+hewtd unarchive .documentation/archive/api/old-guide.md   # lossless restore
+```
+
+`archive` moves the doc to `archive/<same-subpath>/` (preferring `git mv` to keep
+history), stamps `status: archived`, `archived_on`, `archived_from`, and
+`archived_reason`, and reindexes so it drops out of its domain INDEX. The
+`archived_from` stamp is what makes `unarchive` exact — **a hand-rolled `mv`
+loses it**, and there is then nothing to restore from.
+
+**Link guard:** `archive` refuses if active docs still link to the target,
+listing each offender so you can fix them first. `--force` overrides, and the
+inbound links go dangling.
+
+`hewtd archive-candidates` lists docs that may warrant retiring — advisory and
+read-only, it never moves anything. Nothing is ever auto-archived.
+
+Point a replacement at the old doc with `superseded_by: <path>` in frontmatter.
+
+## Archived content: referenceable, never concrete
+
+**Anything under an `archive/` folder — at any depth — is history, not truth.**
+
+It is excluded from every hewtd scan: not indexed, not audited, not
+link-checked, not metadata-validated, never counted. Links *into* it still
+resolve, so history stays reachable and you may cite it as "what we used to do."
+
+What it is **not** is evidence of how the system works now. Never quote an
+archived doc as current behavior, never carry its claims into a new doc, and
+never treat a `status:`/`version:` inside it as live. If it turns out an archived
+doc is still correct and still needed, it should be restored, not read in place:
+
+```bash
+hewtd unarchive .documentation/archive/api/old-guide.md
+```
+
+Editing a file under `archive/` is not destructive, but it is almost always a
+mistake — the edit lands in a subtree nothing reads, so it changes nothing anyone
+will see. The guard warns when you try.
+
+## Checking the tree
+
+```bash
+hewtd audit                # policy + drift violations, health score
+hewtd link-check           # broken internal links
+hewtd index --dry-run      # what the indexes would become
+```
+
+`audit`'s `index-drift` rule reports any document on disk that its domain's
+`INDEX.md` fails to list — the fix is always `hewtd index`.
+
+## If the guard denied your tool call
+
+It denies exactly two things, both destructive:
+
+- **Editing a generated `INDEX.md`/`REGISTRY.md`** → change the documents and run
+  `hewtd index`.
+- **Deleting a doc under `.documentation/`** → use `hewtd archive` instead.
+
+Both rules are opt-out via `.claude/hit-em-with-the-docs.json`:
+
+```json
+{ "enforcement": { "block_index_edits": true, "block_doc_deletion": true } }
+```
+
+Turning one off is a deliberate choice by the human who owns the repo — not
+something to do to get past a denial.

package/templates/claude/CLAUDE.md

@@ -1,208 +0,0 @@
-# Documentation System Plugin (hit-em-with-the-docs)
-
-This project uses the hit-em-with-the-docs documentation system for hierarchical, self-managing documentation.
-
-## Quick Reference
-
-### Documentation Structure
-
-```
-.documentation/
-├── INDEX.md           # Navigation hub
-├── REGISTRY.md        # Quick reference
-├── security/          # Security, auth, Vault, Keycloak
-├── devops/            # Deployment, CI/CD, Docker
-├── database/          # Schema, migrations, RLS
-├── api/               # API endpoints, routes
-├── standards/         # Coding standards
-├── testing/           # Test strategies
-├── architecture/      # System design
-├── features/          # Feature guides
-├── quickstart/        # Setup guides
-├── procedures/        # Operational procedures
-├── workflows/         # Process documentation
-├── agents/            # AI agent docs
-├── backups/           # Backup guides
-├── troubleshooting/   # Debug guides
-└── plans/             # Planning documents
-```
-
-These 15 domains are built-in and always present. The set is **extensible** — register project-specific domains at runtime with `npx hit-em-with-the-docs domain add <id> -k <keywords>` (stored in `.claude/hit-em-with-the-docs.json` under `domains: []`, and scaffolded under `.documentation/<id>/`). Run `npx hit-em-with-the-docs domain list` to see the active set, and `domain remove <id>` to drop a custom one (never deletes docs).
-
-**Deprecated docs → `.documentation/archive/`.** To retire a doc without deleting it, use `npx hit-em-with-the-docs archive <file>` — it moves the doc under `archive/`, stamps lifecycle frontmatter (`archived_from` makes it reversible), and reindexes. A link guard refuses if active docs still link to it (`--force` overrides); `--dry-run` previews. `unarchive <file>` restores it where it came from, and `archive-candidates` lists docs that may warrant archiving (advisory, read-only — never moves anything). hewtd excludes the `archive/` folder from every scan (audit, link-check, metadata-sync, integrate, link graph, search), so archived docs are never validated or indexed. `archive` is reserved and cannot be a domain. A doc left at `status: deprecated` in an active folder is now surfaced by `audit` as an INFO nudge toward `archive`.
-
-## Commands
-
-### /docs
-
-Documentation commands for managing the hierarchical documentation system.
-
-#### /docs load <domain>
-
-Load documentation for a specific domain.
-
-Usage: `/docs load security`
-
-This loads:
-1. Domain INDEX.md (complete listing)
-2. Domain REGISTRY.md (quick reference)
-3. Key documents summary
-
-#### /docs list
-
-List all documentation domains (the 15 built-in plus any custom domains) with descriptions.
-
-#### /docs search <query>
-
-Search across all documentation for a query term.
-
-Usage: `/docs search "authentication"`
-
-#### /docs stats
-
-Show documentation health statistics including:
-- Total documents per domain
-- Link health
-- Metadata compliance
-- Recent updates
-
-#### /docs maintain
-
-Run documentation maintenance:
-```bash
-npx hit-em-with-the-docs maintain --quick
-```
-
-#### /docs integrate <file>
-
-Integrate a document into the system:
-```bash
-npx hit-em-with-the-docs integrate ./docs/new-guide.md
-```
-
-### /discover
-
-Pattern discovery commands for extracting patterns from the codebase.
-
-#### /discover patterns
-
-Discover coding patterns in the codebase:
-```bash
-npx hit-em-with-the-docs discover patterns
-```
-
-Detects: Service layer, Repository pattern, Factory pattern, Error handling, etc.
-
-#### /discover anti-patterns
-
-Detect anti-patterns and code smells:
-```bash
-npx hit-em-with-the-docs discover anti-patterns
-```
-
-Detects: Hardcoded credentials, SQL injection risks, console.log, any types, etc.
-
-#### /discover standards
-
-Extract implicit coding standards:
-```bash
-npx hit-em-with-the-docs discover standards
-```
-
-Extracts: Naming conventions, file organization, code style, documentation coverage.
-
-#### /discover dependencies
-
-Analyze project dependencies:
-```bash
-npx hit-em-with-the-docs discover dependencies
-```
-
-Analyzes: Package versions, circular dependencies, unused dependencies, security issues.
-
-## Metadata Schema
-
-Every documentation file should have this YAML frontmatter:
-
-```yaml
----
-# Required fields
-title: "Document Title"
-tier: guide|standard|example|reference|admin
-domains: [primary-domain]
-status: draft|active|deprecated|archived
-last_updated: 'YYYY-MM-DD'
-version: '1.0.0'
-
-# Optional fields
-audience: [all|developers|devops|admin]
-tags: [tag1, tag2]
-purpose: "One-sentence purpose"
-related_docs:
-  - path/to/related.md
-author: "Name"
----
-```
-
-## Tiers
-
-| Tier | Description | Size |
-|------|-------------|------|
-| guide | Step-by-step how-to guides | 15-30 KB |
-| standard | Coding standards and conventions | 5-15 KB |
-| example | Code examples and templates | 3-10 KB |
-| reference | Comprehensive references | 30+ KB |
-| admin | Administrative/operational docs | 10-20 KB |
-
-## Workflow Guidelines
-
-### Adding New Documentation
-
-1. Determine the appropriate domain
-2. Create file with kebab-case naming: `topic-name-type.md`
-3. Add required frontmatter
-4. Write content following tier template
-5. Run: `npx hit-em-with-the-docs integrate <file>`
-
-### Weekly Maintenance
-
-Run every Friday:
-```bash
-npx hit-em-with-the-docs maintain
-```
-
-This syncs metadata, checks links, and audits compliance.
-
-### Before Committing Documentation
-
-```bash
-# Quick check
-npx hit-em-with-the-docs audit
-
-# Fix issues
-npx hit-em-with-the-docs metadata-sync --fix
-```
-
-## File Naming Convention
-
-- Use kebab-case: `api-design-standards.md`
-- Include type suffix when appropriate: `-guide.md`, `-standard.md`, `-procedure.md`
-- Be specific: `keycloak-integration-guide.md` not `auth.md`
-
-## Related Commands
-
-```bash
-# Initialize documentation structure
-npx hit-em-with-the-docs init
-
-# Generate reports
-npx hit-em-with-the-docs report health
-npx hit-em-with-the-docs report audit
-npx hit-em-with-the-docs report links
-
-# Check links
-npx hit-em-with-the-docs link-check
-
-# Discover patterns
-npx hit-em-with-the-docs discover patterns --language typescript
-```