> **Plain-language companion:** [v0.56.0.md](v0.56.0.md)

## v0.56.0 — Documentation Foundation

**Status: Released.**  Derived from
[plans/PLAN_DOCUMENTATION_GAPS_2.md](../plans/PLAN_DOCUMENTATION_GAPS_2.md)
(Round 2 documentation audit, 2026-05-11).

> **Release Theme**
> Fix every inaccuracy; complete every reference; add the two high-impact
> conceptual documents (MENTAL_MODEL.md, LIMITATIONS.md) and the performance
> cheat sheet.

---

### P0 — Blockers

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| DOC-P0-1 | Fix `scripts/gen_catalogs.py` — resolve PGS_* names to `pg_trickle.*`, convert Rust types to PG types, remove trailing garbage rows; regenerate `docs/GUC_CATALOG.md` | Medium | CRITICAL |
| DOC-P0-2 | Complete `docs/ERRORS.md` — add sections for Publication (2), SLA (1), CDC (2), Diagnostic (1), Snapshot (3), Outbox (3), Placeholder (1), and DVM hardening (3) error variants following existing template | Large | CRITICAL |
| DOC-P0-3 | Fix `pg_trickle.parallel_refresh_mode` default in `docs/CONFIGURATION.md` — verify against `src/config.rs`, update prose, default table, and sample `postgresql.conf` | Small | CRITICAL |

### P1 — High Impact (Reference Completeness)

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| DOC-P1-4 | Add working examples to `docs/SQL_REFERENCE.md` for 10 outbox/inbox consumer API functions: `poll_outbox`, `commit_offset`, `extend_lease`, `seek_offset`, `consumer_heartbeat`, `consumer_lag`, `drop_consumer_group`, `outbox_rows_consumed`, `replay_inbox_messages`, `inbox_ordering_gaps` | Medium | HIGH |
| DOC-P1-5 | Add column-schema tables to `docs/SQL_REFERENCE.md` for 7 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` | Medium | HIGH |
| DOC-P1-6 | Add 2–3 paragraph abstracts to three research stubs: `docs/research/CUSTOM_SQL_SYNTAX.md`, `docs/research/PG_IVM_COMPARISON.md`, `docs/research/TRIGGERS_VS_REPLICATION.md`; verify `plans/` source files exist | Medium | HIGH |
| DOC-P1-7 | Expand `docs/DVM_REWRITE_RULES.md` with before/after SQL examples for all 5 passes: view inlining, GROUPING SETS expansion, EXISTS-to-join, scalar subquery hoisting, delta key restriction | Medium | HIGH |
| DOC-P1-8 | Enrich `docs/introduction.md`: add 3 paragraphs of conceptual context; add INSTALL.md link to persona table; keep under 200 lines | Small | HIGH |

### P1 — New Documents

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| DOC-P1-9 | Create `docs/MENTAL_MODEL.md` — concept-first DVM explainer for developers who know SQL but not IVM; analogies before formulas; 8 sections from "the problem" through "DAG chaining" | Large | HIGH |
| DOC-P1-10 | Create `docs/LIMITATIONS.md` — unsupported SQL constructs, DIFFERENTIAL-mode constraints, source table restrictions, operational anti-patterns, "will this work?" decision tree | Large | HIGH |
| DOC-NEW-23 | Create `docs/PERFORMANCE_CHEATSHEET.md` — single-page quick reference: top-10 GUC quick-wins, 5 FULL-fallback patterns with rewrites, three golden rules | Medium | HIGH |

---

### Recommended Implementation Order

| Phase | Items | Description |
|-------|-------|-------------|
| Phase 1 | DOC-P0-1, DOC-P0-3 | Generator fix and default correction — unblocks |
| Phase 2 | DOC-P0-2 | Complete ERRORS.md — all 44 variants |
| Phase 3 | DOC-P1-4, DOC-P1-5 | SQL_REFERENCE.md completion |
| Phase 4 | DOC-P1-6, DOC-P1-7, DOC-P1-8 | Research stubs, DVM rules, introduction |
| Phase 5 | DOC-P1-9, DOC-P1-10, DOC-NEW-23 | New documents |

---

### Release Gate

- [x] `just lint` passes with zero warnings
- [x] `docs/GUC_CATALOG.md` generated cleanly; all GUC names start with `pg_trickle.`
- [x] `docs/ERRORS.md` has a section for every variant in `src/error.rs`
- [x] `docs/SQL_REFERENCE.md` has examples for all 59 documented functions
- [x] All three research stubs have standalone abstracts
- [x] `docs/MENTAL_MODEL.md` reviewed by at least one maintainer
- [x] `docs/LIMITATIONS.md` reviewed by at least one maintainer
- [x] All new SQL examples verified against a running pg_trickle instance

---

### Implementation Status

| ID | Title | Status |
|----|-------|--------|
| DOC-P0-1 | GUC_CATALOG regeneration | ✅ Done |
| DOC-P0-2 | ERRORS.md completion | ✅ Done |
| DOC-P0-3 | parallel_refresh_mode default fix | ✅ Done |
| DOC-P1-4 | SQL_REFERENCE outbox/inbox examples | ✅ Done |
| DOC-P1-5 | SQL_REFERENCE catalog table schemas | ✅ Done |
| DOC-P1-6 | Research stub abstracts | ✅ Done |
| DOC-P1-7 | DVM_REWRITE_RULES worked examples | ✅ Done |
| DOC-P1-8 | introduction.md enrichment | ✅ Done |
| DOC-P1-9 | docs/MENTAL_MODEL.md | ✅ Done |
| DOC-P1-10 | docs/LIMITATIONS.md | ✅ Done |
| DOC-NEW-23 | docs/PERFORMANCE_CHEATSHEET.md | ✅ Done |

---

### Files Changed

| File | Change |
|------|--------|
| `scripts/gen_catalogs.py` | Fix PGS_* → pg_trickle.* name resolution; Rust type → PG type mapping |
| `docs/GUC_CATALOG.md` | Regenerated — all 115 entries with correct names and types |
| `docs/ERRORS.md` | Add 14 new error variant entries across 6 missing categories |
| `docs/CONFIGURATION.md` | Fix `parallel_refresh_mode` default value |
| `docs/SQL_REFERENCE.md` | Add 10 function examples; add 7 catalog table column schemas |
| `docs/research/CUSTOM_SQL_SYNTAX.md` | Add abstract before include |
| `docs/research/PG_IVM_COMPARISON.md` | Add abstract before include |
| `docs/research/TRIGGERS_VS_REPLICATION.md` | Add abstract before include |
| `docs/DVM_REWRITE_RULES.md` | Add before/after SQL examples for 5 rewrite passes |
| `docs/introduction.md` | Add 3 paragraphs context + INSTALL.md link |
| `docs/MENTAL_MODEL.md` | New file (~500 lines) |
| `docs/LIMITATIONS.md` | New file (~400 lines) |
| `docs/PERFORMANCE_CHEATSHEET.md` | New file (~150 lines) |
| `docs/SUMMARY.md` | Add entries for MENTAL_MODEL.md, LIMITATIONS.md, PERFORMANCE_CHEATSHEET.md |