feat(blocks): 5 documentation blocks — claude-md/decisions/runbook/readme/diagrams

_blocks/docs-architecture-diagrams.md

@@ -0,0 +1,86 @@
+# DOCS — Architecture diagrams (Mermaid)
+
+Diagrams live beside the prose they describe. Mermaid renders natively on
+GitHub / Forgejo / Gitea / Obsidian — no extra tooling needed to view.
+
+## When to include
+
+- Any agent/skill that scaffolds documentation for a multi-component system
+- Any repo with ≥ 3 services / layers / subsystems
+
+## Four diagram patterns (use the right one)
+
+### 1. System context (C4 level 1) — `flowchart LR`
+
+```mermaid
+flowchart LR
+    U[User] -->|HTTP| API[API Gateway]
+    API -->|gRPC| SVC[Service]
+    SVC -->|SQL| DB[(PostgreSQL)]
+    SVC -->|publish| Q[[Queue]]
+```
+
+Use for: one-page overview, onboarding, README architecture section.
+
+### 2. Sequence — `sequenceDiagram`
+
+```mermaid
+sequenceDiagram
+    Client->>API: POST /orders
+    API->>DB: INSERT
+    DB-->>API: id
+    API-->>Client: 201 Created
+```
+
+Use for: request flow, auth handshake, error recovery sequence.
+
+### 3. State machine — `stateDiagram-v2`
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending
+    Pending --> Running: start
+    Running --> Done: success
+    Running --> Failed: error
+    Failed --> Pending: retry
+```
+
+Use for: job lifecycle, FSM-driven features, connection state.
+
+### 4. ER / data model — `erDiagram`
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+```
+
+Use for: DB schema summary. Keep ≤ 10 entities per diagram.
+
+## Rules
+
+- **Diagram-as-code, no binary exports.** `.mmd` or fenced block, never `.png`
+- **≤ 15 nodes / 20 edges per diagram.** Over that → split
+- **Labels are nouns.** Edges are verbs. No prose inside nodes
+- **One diagram = one concern.** Don't mix system context + sequence in one chart
+- **Preview locally** with `mmdc` before commit: `mmdc -i diagram.mmd -o /tmp/preview.svg`
+- **Link to source in caption** — "See `docs/diagrams/orders.mmd` for source"
+
+## Forbidden
+
+- ASCII art for multi-node graphs (use Mermaid — renders everywhere)
+- Diagrams that contradict the code (stale → delete or fix)
+- Secrets / real hostnames / IPs in diagrams (use placeholders)
+
+## Install `mmdc` (preview tool)
+
+```
+npm install -g @mermaid-js/mermaid-cli    # one-time
+mmdc -i docs/diagrams/context.mmd -o /tmp/preview.svg
+```
+
+## References
+
+- Mermaid syntax — https://mermaid.js.org/intro/ [VERIFIED: https://mermaid.js.org/intro/]
+- C4 model — https://c4model.com/ [VERIFIED: https://c4model.com/]
+- `~/.claude/rules/doc-conventions.md`

_blocks/docs-claude-md.md

@@ -0,0 +1,25 @@
+# DOCS — `CLAUDE.md` (project bootstrap template)
+
+A per-project `CLAUDE.md` answers one question: *what does a Claude agent need to know in the first 30 seconds on this repo?* It is read before any code work. Keep it under ~150 lines.
+
+**Canonical sections (in this order):**
+
+1. **Project one-liner** — name, domain, status (`active | maintenance | archived`), primary stack, public-surface flag.
+2. **Architecture** — 2-5 bullets + optional Mermaid block. Layer names match the code tree. If a layer diagram helps, `_blocks/docs-architecture-diagrams.md` has the patterns.
+3. **Stack / dependencies** — language(s), major frameworks, DB, queue, deploy target. One line per item.
+4. **Constraints** — API rate limits, licensing, cost tiers, platform quirks (e.g. "Flux 2 Pro zero-config", "SPM needs `-Xlinker`").
+5. **Known issues** — bugs that aren't fixable now, workarounds, tickets. Keep dated.
+6. **Test invariants** — how tests are run (`cargo test --release`, `pytest`, `flutter test`), coverage floor, which tests are load-bearing.
+7. **Commands cheatsheet** — 5-8 commands the agent will type most: build, test, lint, deploy, format.
+8. **Secrets / credentials** — env var NAMES only (RULE 0.8). Never literal tokens. Path: `secrets/*.env`.
+9. **Related files** — `DECISIONS.md`, `HOTPATHS.md`, `TODO.md`, runbooks.
+
+**Placeholders used by `kei-docs-scaffold.sh`:**
+`{{PROJECT_NAME}}`, `{{STACK}}`, `{{DEPLOY}}`, `{{PRIMARY_LANGUAGE}}`, `{{TEST_CMD}}`.
+
+**Forbidden:**
+- Copying the umbrella `~/.claude/CLAUDE.md` here — link to it, do not duplicate.
+- Storing API tokens / private URLs (use `secrets/*.env`).
+- Marketing prose. Every line must be actionable by the agent.
+
+**Source:** Anthropic Claude Code docs — `claude.ai/code` project-memory convention (E4). Karpathy viral CLAUDE.md (forrestchang/andrej-karpathy-skills, 15K+ stars) [E4].

_blocks/docs-decisions-adr.md

@@ -0,0 +1,59 @@
+# DOCS — `DECISIONS.md` / ADR template (MADR 4.0)
+
+Architecture Decision Records capture *why* a non-trivial choice was made, so future maintainers (including agents) don't re-litigate. Format: **MADR 4.0** (Markdown Any Decision Records, 2024). Nygard originated the practice in 2011.
+
+**One ADR per non-trivial decision.** File path convention:
+- Single-file log: append to `DECISIONS.md` (top-of-file = newest).
+- Per-decision files: `docs/adr/NNNN-kebab-case-title.md` (NNNN = zero-padded int).
+
+**MADR 4.0 template (copy as-is):**
+
+```markdown
+# ADR-NNNN: <short imperative title>
+
+- **Status:** Proposed | Accepted | Rejected | Superseded-by-ADR-NNNN | Deprecated
+- **Date:** YYYY-MM-DD
+- **Deciders:** @handle, @handle
+- **Evidence grade:** E1-E6 (see `_blocks/evidence-grading.md`)
+
+## Context and Problem Statement
+<1-3 sentences: what forces us to decide? What breaks if we don't?>
+
+## Decision Drivers
+- Driver 1 (e.g. cost < $X/mo)
+- Driver 2 (e.g. must run offline)
+- Driver 3 (e.g. team knows language Y)
+
+## Considered Options
+1. **Option A** — one-line summary
+2. **Option B** — one-line summary
+3. **Option C** — one-line summary
+
+## Decision Outcome
+Chosen: **Option <letter>**, because <1-2 sentences tying back to drivers>.
+
+### Consequences
+- Positive: <what improves>
+- Negative: <what we give up, tech debt incurred>
+- Neutral: <noteworthy but not directional>
+
+## Pros and Cons of the Options
+### Option A
+- Pro: ...
+- Con: ...
+### Option B
+- Pro: ...
+- Con: ...
+
+## Links
+- Supersedes: ADR-NNNN
+- Related: `HOTPATHS.md#section`, external URL
+- Evidence source: [VERIFIED: url] or [UNVERIFIED]
+```
+
+**Rules:**
+- Status `Accepted` = implemented or actively being implemented. `Proposed` = under review. `Rejected` stays as an ADR (the record of why we said no).
+- Never delete a past ADR. Supersede with a new ADR that references the old number.
+- Evidence grade mandatory (RULE 0.4). No grade → the ADR is unreviewable.
+
+**Source:** MADR 4.0 spec — [adr/madr](https://adr.github.io/madr/) [E4]. Nygard 2011 original post `cognitect.com/blog/2011/11/15/documenting-architecture-decisions` [E4].

_blocks/docs-readme-template.md

@@ -0,0 +1,75 @@
+# DOCS — Public `README.md` scaffold
+
+`README.md` is the first file a new reader (human OR agent) opens. One file, nine sections, in this order. Keep ≤ 300 lines; longer material lives in `docs/`.
+
+**Nine-section template:**
+
+```markdown
+# {{PROJECT_NAME}}
+
+> One-line pitch (what + why, ≤ 100 chars).
+
+[![CI](badge)](link) [![License](badge)](link) [![Version](badge)](link)
+
+## What
+2-3 sentences: what it does, who it's for. No marketing adjectives.
+
+## Why
+2-3 sentences: problem this solves, alternatives considered, why this one.
+Link to the relevant ADR: [DECISIONS.md](DECISIONS.md#adr-nnnn).
+
+## Install
+```bash
+# Primary path — the 90% case
+<one command>
+```
+
+**Prerequisites:** <language X >= vN, OS constraints, system deps>.
+
+<If needed: alternative install methods in `docs/install.md`.>
+
+## Usage
+Smallest working example. Copy-pasteable.
+```bash
+<command producing visible output>
+```
+
+Link to a richer quickstart in `docs/quickstart.md` if >20 lines.
+
+## Development
+```bash
+git clone <repo>
+cd <repo>
+<bootstrap command, e.g. cargo build>
+<test command>
+```
+
+Project layout:
+- `src/` — implementation
+- `tests/` — integration tests
+- `docs/` — long-form docs
+- `{{STACK}}-specific notes → link>
+
+## Deploy
+Target: **{{DEPLOY}}**. One-liner: `<deploy command>`.
+Full runbook: `docs/runbooks/deploy.md`.
+
+## Architecture
+One paragraph + one Mermaid diagram (see `_blocks/docs-architecture-diagrams.md`). Detail in `docs/architecture.md`.
+
+## Contributing
+- Issue tracker: <url>
+- Commit convention: Conventional Commits (see `_blocks/git-conventions` in kit)
+- PR checklist: `docs/CONTRIBUTING.md`
+
+## License
+<SPDX id> — see [LICENSE](LICENSE).
+```
+
+**Rules:**
+- No secrets (RULE 0.8). No literal tokens.
+- Install command must be ONE command for the happy path.
+- Every "see docs/X" link must resolve — scaffolder verifies or creates the target.
+- If the project is private / not publicly deployable (banned list per `rules/security.md`), mark the repo header with `<!-- PRIVATE — do not publish -->` and omit public badges.
+
+**Source:** standard-readme spec (RichardLitt/standard-readme) [E4]; GitHub "About READMEs" [E4].

_blocks/docs-runbook.md

@@ -0,0 +1,66 @@
+# DOCS — Operational runbook template
+
+A runbook tells on-call (or a future agent) exactly what to do when an alert fires. Every production system needs one per failure class. Format: *symptoms → checks → fixes → escalation*.
+
+**File path:** `docs/runbooks/<component>-<alert-name>.md`. Index in `docs/runbooks/README.md` (or link from `HOTPATHS.md`).
+
+**Template (copy as-is):**
+
+```markdown
+# Runbook — <component>: <alert or symptom name>
+
+## Metadata
+- **Severity:** SEV1 (page now) | SEV2 (work hours) | SEV3 (next day)
+- **On-call rotation:** <team / pagerduty schedule / single handle>
+- **Last rehearsed:** YYYY-MM-DD  (stale > 90d → re-rehearse)
+- **Linked ADRs:** ADR-NNNN
+
+## Symptoms
+- Observable signal: <metric name> > <threshold> for <duration>
+- User impact: <what breaks for end users>
+- Typical dashboards: <URLs>
+
+## Diagnostic checks (in order)
+1. Check dashboard X — if metric Y is flat, skip to step 4
+2. Tail logs: `<exact command>`
+3. Inspect dependency Z status page: <URL>
+4. Reproduce locally if unclear: `<command>`
+
+## Fixes (try in order; STOP at first that works)
+### Fix A — restart (lowest risk)
+```bash
+<exact command>
+```
+Verify: <metric returns to <threshold> within <time>>
+
+### Fix B — rollback
+```bash
+<exact command>
+```
+Verify: <...>
+
+### Fix C — scale up (if load-related)
+```bash
+<exact command>
+```
+
+## Escalation
+- 15 min without recovery → page <secondary on-call>
+- Data loss suspected → page <eng-lead> AND <security>
+- Customer-visible > 30 min → post to <status-page-url>
+
+## Post-incident
+- File incident report at `docs/incidents/YYYY-MM-DD-<slug>.md`
+- If root cause new → new ADR in `DECISIONS.md`
+- If runbook step failed → update this file (date the edit)
+
+## Known non-issues
+- Symptom X that looks scary but is benign (e.g. queue lag < 5s during deploy)
+```
+
+**Rules:**
+- One alert = one runbook. Do not bundle.
+- Every command is copy-pasteable. No placeholders `<...>` in the live fixes section.
+- Rehearse quarterly. Mark the date.
+
+**Source:** Google SRE Book Ch. 11 "Being On-Call" and Ch. 14 "Managing Incidents" [E4]; PagerDuty Incident Response Documentation [E4].