hit-em-with-the-docs

Hit 'Em With The Docs

A self-managing documentation system that keeps your docs organized, accurate, and easy to find.

[!IMPORTANT] You still need to remember to use this plugin when creating documentation! As projects grow, documentation needs to be created and maintained. You'll need to invoke this plugin or ask an LLM to create documentation for your features, workflows, or infrastructure. This plugin must be invoked to create, update, or maintain your docs.

[!NOTE] 2.5.0 — INDEX/REGISTRY regeneration fix. integrate could only append a row to an INDEX.md that already had a table, so the first document into any domain was never registered — and the failure was silently swallowed. integrate and maintain now rebuild domain + root INDEX.md/REGISTRY.md from the documents on disk via the real generators. New hewtd index (alias reindex) command regenerates all indexes on demand; maintain self-heals them every run; audit gains an index-drift rule that --strict gates CI on. Closes #7. See CHANGELOG.

2.4.0 — migrate-incident path bug fix + recovery command. migrate-incident now correctly writes to <vault-root>/incidents/<slug>/ (the location hewtd maintain's incidents-index generator scans). In 2.3.0 the target was derived from the source flat file's parent dir, which silently bypassed the canonical layout when the flat file lived at the vault root. New hewtd fix-legacy-layout command relocates 2.3.0-buggy folders and rewrites fact provenance: refs. Idempotent, dry-run supported. See CHANGELOG.

New in 2.3.0: the knowledge-base primitives layer. Three new tiers (fact, incident-narrative, incident-facts) for citable atomic claims and immutable postmortems, plus an optional symptoms: frontmatter field on any-tier playbooks for symptom→playbook routing with cites: to facts. Three new deterministic indexes (facts/INDEX.md, incidents/INDEX.md, symptoms/INDEX.md) auto-generate on hewtd maintain when a vault root exists. Five new CLI commands: find-citers, audit-facts [--run-verify], extract-facts, cite, migrate-incident. New audit --strict flag for CI gating. New /hit-em-with-the-docs:help slash command for LLM orientation. Four authoring templates at templates/knowledge-base/. Full reference: docs/knowledge-base-primitives.md. Agent guide: docs/LLM-GUIDE.md.

New in 2.2.0: the tier enum gains a "plan" value for persistent-planning lg-mode artifacts (phase / task / atom / notes documents), and the version and status fields are now conditionally relaxed for plan-tier docs (plans use lifecycle status, not semver). Existing tiers (guide / standard / example / reference / admin) are unchanged. See docs/plan-tier-frontmatter.md for the full reference.

Summary

When projects get bigger, documentation becomes a mess. Important information gets lost across many files, links break when you move things around, and nobody knows if the docs are still correct. Hit 'Em With The Docs fixes these problems by organizing everything into 15 clear categories, automatically checking your links, and making sure every document has the right information tags. The system watches your docs and fixes common problems without you having to do it manually. Everything stays organized and up-to-date so your team can find what they need fast.

Operational Summary

The plugin creates a special folder called .documentation in your project with 15 organized sections called "domains" - things like security, API docs, database guides, and testing information. When you add a document, the system reads it and figures out which category it belongs in based on keywords and content. Each document gets special information tags (metadata) added to the top - things like the title, what category it's in, when it was last updated, and how long it takes to read. This metadata helps both you and the system understand what each document is about.