Kraite — update-docs

kraite-update-docs keeps Kraite documentation current with infrastructure, architecture, and feature changes. It maintains two surfaces — the raw functional specs in ~/Herd/docs/kraite/ and this curated four-lens reader site at ~/Code/syntax.kraite.test/.

The canonical updater runs from the ingestion repository because that project owns the cross-Kraite documentation set. A release started from admin, Kraite, or Syntax switches to that ingestion context for its documentation phase, so cross-project changes are still captured before shipping.

Documentation surfaces

Four-lens model (reader site)

The same change is documented from each angle that's affected — never duplicating canonical depth, always cross-linking back.

Canonical-chapter rule: the deep step-by-step flow (with step class names in order, decision points, rationale) lives in one chapter only — usually the lifecycle chapter for end-to-end flows, or the subsystem chapter for daemon-internal mechanics. Other lenses get short angle-specific views that link back to the canonical chapter. Never restate the full flow in multiple chapters.

Depth contract per chapter

Every authored chapter (not stub) must carry:

1. Lead paragraph with {% .lead %}
2. Flow narrative — ordered phases / states
3. Step class names listed in order, in inline code, no class internals
4. Decision points and branching — what triggers what, retry / idempotency rules
5. Rationale — why each decision exists, with incident dates and concrete context (e.g. "LAB #121 race window", "Position #64 on USELESS hit min_notional below 5"). Multi-paragraph rationale → {% callout %}; one-liner → inline prose
6. Cross-lens links section

Banned content: class internals, method signatures, full code snippets, framework-feature explanations. Those belong on the future api.kraite.com reference site.

"Major decision" threshold (wide net)

Surface in the chapter if the change is any of:

• Bruno-approved decision in conversation
• Anything that changes business behaviour (filter rules, branching, what gets traded / skipped)
• Incident-driven rule (past production incident → preventive rule)
• Architectural choice that constrains future work

Sub-thresholds (cosmetic refactors, pure renames, dependency bumps) → not worth a chapter mention.

Code-change → chapter mapping

When deciding which chapters need touching for a given commit:

When in doubt: update the canonical chapter for the flow + the most-specific lens. Never update more than necessary.

When NOT to touch the syntax site

• Pure infra / hardening / deploy-notes changes with no functional surface for Bruno
• Test-only changes
• Pure refactors with no behaviour change
• Documentation-only edits inside ~/Herd/docs/kraite/ (this site is curated FROM raw specs — re-curating without behaviour change is busywork)

Global guidelines routing — mandatory

Generic guidelines (PHP / Laravel / git / tests / debugging conventions) do NOT belong in Kraite docs. They live in ~/.claude/rules/*.md (laravel.md, ui.md, frontend.md, database.md, debugging.md, testing.md, git.md). Detect generic content BEFORE writing into Kraite docs; route to the matching rule file.

Hard rules

• README first — ~/Herd/docs/kraite/README.md must be read before any feature doc is touched.
• 80-char line wrap on raw spec edits.
• Functional specs only. Code details are BANNED from docs — no line-by-line code, no method signatures, no variable names. If it's in the code, don't duplicate it in docs.
• Update WhereAreWe.md in the current project root after any doc update.
• npm run build + smoke-check every refreshed chapter on the syntax site before declaring done.

Related

• Kraite — read-docs — the reader counterpart
• Kraite — tag — the parent that calls update-docs as Step 1c
• Kraite — release — Phase 0 entry point for every profile
• update-docs — generic version (docs/<project>/ for any project)