# v0.56.0 — Documentation Foundation

> **Full details:** [v0.56.0.md-full.md](v0.56.0.md-full.md)

## What's New

v0.56.0 resolves every accuracy and completeness gap identified in the
Round 2 documentation audit
([plans/PLAN_DOCUMENTATION_GAPS_2.md](../plans/PLAN_DOCUMENTATION_GAPS_2.md)).
Three blockers are fixed — a corrupted GUC_CATALOG.md, an incomplete
ERRORS.md covering only 54% of error variants, and a wrong default value
in CONFIGURATION.md — and three major new documents are added that have
been absent since the project's early releases.

### DOC-P0-1: GUC_CATALOG.md Regenerated with Correct Names

The code generator (`scripts/gen_catalogs.py`) was producing
`(registration pending — PGS_*)` placeholder names for every GUC entry
instead of the resolved `pg_trickle.*` names, raw Rust types instead
of PostgreSQL types, and four malformed trailing rows.  The generator
is fixed and the catalog regenerated: all 115 parameters now show their
correct `pg_trickle.` names, SQL types (`bool`, `integer`, `float`,
`text`), and accurate default values.

### DOC-P0-2: ERRORS.md Covers All 44 Error Variants

Six error categories in `src/error.rs` were undocumented — affecting
users of v0.27+ snapshots, v0.28+ outbox/inbox deployments, and any
deployment using WAL-based CDC.  New sections with message format,
causes, and resolution steps are added for: `PublicationAlreadyExists`,
`PublicationNotFound`, `SlaTooSmall`, `ChangedColsBitmaskFailed`,
`PublicationRebuildFailed`, `DiagnosticError`, all three snapshot errors,
all three outbox errors, `UnresolvedPlaceholder`,
`DiffDepthExceeded`, `DiffCteCountExceeded`, and
`StSourceFrontierMissing`.

### DOC-P0-3: parallel_refresh_mode Default Corrected

`pg_trickle.parallel_refresh_mode` was documented with default `'off'`;
source code default is `'on'`.  CONFIGURATION.md prose, the default
table, and the sample `postgresql.conf` block are corrected.

### DOC-P1-4 / DOC-P1-5: SQL_REFERENCE.md — Outbox/Inbox Complete

Ten v0.28.0 consumer API functions now have working examples, and seven
previously undocumented catalog tables (`pgt_outbox_config`,
`pgt_consumer_groups`, `pgt_consumer_offsets`, `pgt_consumer_leases`,
`pgt_inbox_config`, `pgt_inbox_ordering_config`, `pgt_inbox_priority_config`)
now have full column-schema documentation.

### DOC-P1-6: Research Stubs Now Self-Contained

The three 15-line stubs in `docs/research/` — `CUSTOM_SQL_SYNTAX.md`,
`PG_IVM_COMPARISON.md`, and `TRIGGERS_VS_REPLICATION.md` — each gain a
2–3 paragraph abstract summarising key findings before the `{{#include}}`
directive, so GitHub readers get the essential conclusion without
following the link.

### DOC-P1-7: DVM_REWRITE_RULES.md — Worked SQL Examples Added

All five rewrite passes (view inlining, GROUPING SETS expansion,
EXISTS-to-join, scalar subquery hoisting, delta key restriction) now
include a before/after SQL example and a one-sentence explanation of
why the transformation is required for differential maintenance.

### DOC-P1-8: introduction.md Enriched

`docs/introduction.md` gains three paragraphs of conceptual context
(the problem, how it works at one level of abstraction, when not to
use it) and an "Install" link in the persona routing table.  The file
remains under 200 lines.

### DOC-P1-9: New — docs/MENTAL_MODEL.md

A concept-first explainer of differential view maintenance for
developers who know SQL but have not encountered IVM.  Uses analogies
and intuition before any formulas, walks through the delta-thinking
insight, CDC capture, the differential merge, FULL fallback, and
DAG chaining.  No DBSP/DRed jargon until the final "Further reading"
section.

### DOC-P1-10: New — docs/LIMITATIONS.md

An honest, well-organised reference for what pg_trickle cannot do —
unsupported SQL constructs, DIFFERENTIAL-mode constraints, source table
restrictions, operational anti-patterns, and a "will this work?"
decision tree.  Every limitation links to a workaround or mitigation
where one exists.

### DOC-NEW-23: New — docs/PERFORMANCE_CHEATSHEET.md

A single-page quick reference: 10 GUC quick-wins, 5 query patterns that
trigger FULL fallback (with their rewrites), and three golden rules.
Print/bookmark-friendly complement to the full PERFORMANCE_COOKBOOK.md.