baldart 4.21.0 → 4.21.1

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.21.1] - 2026-06-09
+
+**Nightly reconciliation of the canonical API registries (errors.md / schemas.md).** Makes the nightly `doc-review` run explicitly keep `${paths.api_errors}` and `${paths.api_schemas}` in sync with the day's code changes, instead of relying on the generic doc↔code drift step. **PATCH** (strengthens existing routine/agent behaviour; no new agent/skill/command/config key).
+
+### Changed
+
+- **`framework/routines/doc-review.routine.yml`** — new step 3b: when `features.has_api_docs: true`, reconcile the canonical `errors.md` (stable error codes added/renamed/removed → apply or flag `DOC_GAP`) and `schemas.md` (Zod/TS shape changes → update or flag `SCHEMA_DRIFT`) against the last-24h commits. Skips silently when the paths are unset.
+- **`framework/.claude/agents/doc-reviewer.md`** — new "Canonical API registries — reconciliation (nightly-owned)" section: the agent now explicitly OWNS the code→doc direction for the two registries (the `doc-writing-for-rag` skill owns the doc-authoring direction). Ties together the existing `SCHEMA_DRIFT` + error-code checks.
+
 ## [4.21.0] - 2026-06-09
 
 **Code knowledge graph layer (Graphify) + Karpathy wiki rebind + nightly doc-alignment command.** Introduce [Graphify](https://github.com/safishamsi/graphify) as the new retrieval engine replacing the removed RAG (v4.20.0): a single language-agnostic tool (tree-sitter, 28 langs, local/offline, native Leiden communities; pip `graphifyy`, CLI `graphify` + `graphify-mcp`). Opt-in, runtime-detected, silent fallback to LSP→Grep→Git. **MINOR** (additive; new agent + 2 skills + 1 routine + 1 protocol module; new config key `features.has_code_graph` + `graph.*` propagated end-to-end per the schema-change rule).

package/VERSION

@@ -1 +1 @@
-4.21.0
+4.21.1

package/framework/.claude/agents/doc-reviewer.md

@@ -409,6 +409,21 @@ Beyond route existence, also check schema diffs:
 - For new fields in a documented payload: NEEDS_UPDATE.
 - For removed fields still in doc: ORPHAN_FIELD.
 
+## Canonical API registries — reconciliation (nightly-owned)
+
+When `features.has_api_docs: true`, you OWN keeping the two canonical registries in
+sync with code on the nightly `doc-review` run (and on any API-doc rewrite):
+- **`${paths.api_errors}`** (errors.md) — the single registry of stable error codes.
+  A code added / renamed / removed in the code → apply it to the right domain
+  section (trivial fix) or flag `DOC_GAP`. Endpoint docs link to the **domain
+  anchor**; they must never duplicate the table.
+- **`${paths.api_schemas}`** (schemas.md) — the documented projection of the
+  Zod/TS shapes (Zod-in-code stays the SSOT). A shape change → update the table or
+  flag `SCHEMA_DRIFT`.
+Skip silently when either path is unset. This is the code→doc direction that keeps
+the registries authoritative; the `doc-writing-for-rag` skill handles the
+doc-authoring (APPEND, no duplication) direction.
+
 ## Endpoint Count Reconciliation
 
 Applies **when the project uses file-system route handlers** (e.g. Next.js App Router `route.ts`). Adapt the commands to the project's actual API layout — the paths below are the common Next.js convention, not a hardcoded assumption. The convention: SSOT count in `api/index.md` = sum of HTTP method exports (a handler exporting GET + POST counts as 2 endpoints).

package/framework/routines/doc-review.routine.yml

@@ -19,6 +19,14 @@ prompt: |
      references. Flag drift as `DOC_DRIFT`.
   3. For each source file change that landed without a corresponding doc
      update, flag `DOC_GAP`.
+  3b. If `features.has_api_docs: true`, reconcile the CANONICAL registries
+     against the day's code changes:
+       - `${paths.api_errors}` (errors.md): a stable error code added / renamed /
+         removed in the code → apply it to the registry (trivial) or flag
+         `DOC_GAP`. Endpoint docs must link to the domain anchor, never duplicate.
+       - `${paths.api_schemas}` (schemas.md): a route's Zod/TS request/response
+         shape changed → update the matching table or flag `SCHEMA_DRIFT`.
+     Skip silently when either path is unset.
   4. If the project ships a design-system SSOT, run the standard DS drift
      checks (INDEX coverage, per-component accuracy, animations
      reconciliation, tokens reconciliation).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.21.0",
+  "version": "4.21.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"