Changelog / Audit
Unified change history across every entity type in a registry.
Handoff tracks change history per entity type, then unifies it into one time-ordered feed: "what changed," across tokens/components/pages/patterns together, plus, where recorded, why it changed.
Shape
Each entity type that participates keeps its own append-only change table, all following the
same rough pattern, a pushedAt timestamp, who pushed (pushedByUserId/pushedByName), a
trigger (push/mcp/manual), and a "why": an optional human-authored message plus a
lazily-generated aiSummary:
| Table | Tracks |
|---|---|
handoff_token_change | Per-push token diffs — added/removed/modified counts and keys, plus actual before/after values for changed keys (bounded to what changed). |
handoff_component_version | One row per component push — a full metadata snapshot, a change summary, source-file hashes, and artifact filenames present at that version. |
handoff_page_change | Per-push page create/update/delete — title and markdown-length before/after. |
handoff_pattern_change | Per-push pattern create/update/delete — title, block count. |
edit_history | A generic (entityType, entityId, diff) log for edits that don't have a dedicated table above. |
handoff_event_log | The broadest audit log — auth events, fetch/build pipeline runs, and AI usage/cost (provider, model, estimated tokens/cost) across the whole registry, not scoped to a single content entity. Backs /account/ai-cost and /admin/ai-cost. |
handoff_validation_run | A related but distinct concept: append-only health snapshots (score, grade, per-validator/per-component breakdown), one row per push that included validation results. Not a change log — a quality trend, surfaced at /system/health. See Components. |
Three surfaces
| Surface | Where |
|---|---|
| UI | /system/changelog — the unified changelog view; /system/health for the separate validation-trend view, see Registry → Stakeholder-facing UI routes. |
| REST | GET /api/handoff/changelog — a unified, time-ordered feed across components/tokens/pages/patterns, filterable by since (ISO 8601) and limit. Postgres only (no equivalent in workspace dev, since there's no push history to unify without a registry), see API → /api/handoff and Workspace → Local preview § What's push-dependent. |
| MCP | The Change Inquiry family, registry mode only: handoff_recent_changes (recent changes across components/tokens/pages/patterns, newest first, with the "why" when available), handoff_component_history (one component's version history — what, who, when, why), handoff_change_why (the reason behind one specific change — the human message, or a cached AI-generated summary of the diff). See MCP → Tool catalog § Change Inquiry. |
Replacing the legacy changelog pages
The legacy site's changelog/ section (four hand-maintained pages: overview, changelog,
releases, versioning/stability notes) is dropped in favor of this unified, database-backed
model going forward. Framework-level release notes, as opposed to a given registry's own
content changes above, live in handoff-app's own Changelog.md at the repository root,
maintained (Keep a Changelog format, semantic versioning) rather
than hand-duplicated here.