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

## v0.57.0 — Documentation Excellence

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

> **Release Theme**
> Four new tutorials, P2/P3 quality polish across all existing docs, and
> a full consistency pass across all 83 documentation files.  After this
> release the documentation meets the world-class standard required for v1.0.

---

### P1 — New Tutorials

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| DOC-NEW-24 | Create `docs/tutorials/FIRST_DASHBOARD.md` — end-to-end tutorial: real-time analytics dashboard over e-commerce sample data; revenue-by-region + hourly-counts + top-products chain; Grafana pointers | Large | HIGH |
| DOC-NEW-25 | Create `docs/tutorials/EVENT_SOURCING.md` — end-to-end tutorial: stream tables as read-model projections over event-sourced writes; order state + customer LTV + inventory projections; CQRS pattern; event replay/backfill | Large | HIGH |
| DOC-NEW-26 | Create `docs/tutorials/BACKFILL_AND_MIGRATION.md` — zero-downtime migration from manually-maintained matview: assessment, `validate_query()`, parallel running, verification, consumer cutover, rollback | Medium | HIGH |
| DOC-NEW-27 | Create `docs/tutorials/SECURITY_HARDENING.md` — role separation, CDC trigger ownership, change buffer protection, audit logging; copy-paste SQL templates for all GRANT statements; verification checklist | Medium | HIGH |

### P2 — Quality Improvements

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| DOC-P2-11 | Add "Copy-Paste Templates" section to `docs/SECURITY_GUIDE.md` — `CREATE ROLE` and `GRANT` statements for `pgtrickle_admin`, `pgtrickle_user`, `pgtrickle_readonly` | Small | MEDIUM |
| DOC-P2-12 | Backfill `docs/WHATS_NEW.md` entries for v0.1–v0.7 — 3–5 sentence user-impact summaries derived from CHANGELOG.md | Medium | MEDIUM |
| DOC-P2-13 | Expand `docs/tutorials/HYBRID_SEARCH_PATTERNS.md` patterns 2 (RLS-scoped) and 3 (tiered storage) to match quality of pattern 1; document `pg_trickle.enable_vector_agg` GUC | Medium | MEDIUM |
| DOC-P2-14 | Document `partition_key => 'HASH:<col>:<buckets>'` syntax in `docs/tutorials/PER_TENANT_ANN_PATTERNS.md`; expand patterns 2–3 with full step-by-step examples | Medium | MEDIUM |
| DOC-P2-15 | Fix link inconsistencies in `docs/QUICKSTART_5MIN.md` and `docs/GETTING_STARTED.md`: `installation.md` → correct relative path to `INSTALL.md` | Small | MEDIUM |
| DOC-P2-16 | Add 3 worked examples to `docs/PERFORMANCE_COOKBOOK.md` §13: (a) `max_diff_ctes` hit and recovery steps; (b) detecting when FULL beats DIFFERENTIAL via `recommend_refresh_mode()`; (c) deep-join chain and `max_differential_joins` | Small | MEDIUM |
| DOC-P2-17 | Resolve TODO items in `docs/SECURITY_MODEL.md` supply-chain section: fill current status or mark "Planned for v1.0" with roadmap link | Small | MEDIUM |

### P3 — Polish

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| DOC-P3-18 | Convert plain-text GUC/function cross-references in `docs/FAQ.md` to markdown links pointing to CONFIGURATION.md and SQL_REFERENCE.md anchors | Small | LOW |
| DOC-P3-19 | Add operator quick-reference table at top of `docs/DVM_OPERATORS.md` (operator name, supported modes, section anchor) | Small | LOW |
| DOC-P3-20 | Add `pgtrickle.embedding_stream_table()` parameter breakdown or SQL_REFERENCE link to `docs/tutorials/VECTOR_RAG_STARTER.md` | Small | LOW |
| DOC-P3-21 | Add prose explanation of composite score thresholds (+0.15/−0.15) to `docs/tutorials/tuning-refresh-mode.md` | Small | LOW |
| DOC-P3-22 | Add implementation status banner to `docs/research/multi_db_refresh_broker.md` | Small | LOW |

### Consistency Pass

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| DOC-CONS-28 | Terminology sweep — enforce `stream table`, `differential refresh`, `change buffer`, `refresh frontier`, `CDC`, `DVM`, `DAG` usage across all 83 files | Medium | MEDIUM |
| DOC-CONS-29 | Capitalisation sweep — enforce `pg_trickle` (lowercase), `PostgreSQL` (not `Postgres`), `pgtrickle` (schema), `pgrx` (lowercase) | Small | MEDIUM |
| DOC-CONS-30 | Code style sweep — SQL keywords uppercase; `pgtrickle.` prefix on all function calls; language hints on all code blocks | Small | MEDIUM |
| DOC-CONS-31 | Cross-link audit — verify every `[text](path.md)` internal link resolves; fix relative-path errors | Medium | MEDIUM |

---

### Recommended Implementation Order

| Phase | Items | Description |
|-------|-------|-------------|
| Phase 1 | DOC-NEW-24, DOC-NEW-25 | High-traffic tutorials (dashboard, event sourcing) |
| Phase 2 | DOC-NEW-26, DOC-NEW-27 | Remaining tutorials (migration, security) |
| Phase 3 | DOC-P2-11 through DOC-P2-17 | Quality improvements to existing docs |
| Phase 4 | DOC-P3-18 through DOC-P3-22 | Polish |
| Phase 5 | DOC-CONS-28 through DOC-CONS-31 | Full consistency pass |

---

### Release Gate

- [x] All four new tutorials complete, SQL examples verified, linked from `docs/introduction.md` and `docs/SUMMARY.md`
- [x] `docs/SECURITY_GUIDE.md` has copy-paste GRANT templates verified against a running instance
- [x] `docs/WHATS_NEW.md` has entries for all versions
- [x] Consistency pass grep checks pass with zero violations
- [x] `just lint` passes with zero warnings
- [x] Docs site (`mdbook build`) builds with zero broken links

---

### Implementation Status

| ID | Title | Status |
|----|-------|--------|
| DOC-NEW-24 | docs/tutorials/FIRST_DASHBOARD.md | ✅ Done |
| DOC-NEW-25 | docs/tutorials/EVENT_SOURCING.md | ✅ Done |
| DOC-NEW-26 | docs/tutorials/BACKFILL_AND_MIGRATION.md | ✅ Done |
| DOC-NEW-27 | docs/tutorials/SECURITY_HARDENING.md | ✅ Done |
| DOC-P2-11 | SECURITY_GUIDE.md role templates | ✅ Done |
| DOC-P2-12 | WHATS_NEW.md backfill | ✅ Done |
| DOC-P2-13 | HYBRID_SEARCH_PATTERNS expansion | ✅ Done |
| DOC-P2-14 | PER_TENANT_ANN_PATTERNS expansion | ✅ Done |
| DOC-P2-15 | Link inconsistency fixes | ✅ Done |
| DOC-P2-16 | PERFORMANCE_COOKBOOK §13 examples | ✅ Done |
| DOC-P2-17 | SECURITY_MODEL supply-chain TODOs | ✅ Done |
| DOC-P3-18 | FAQ.md link conversion | ✅ Done |
| DOC-P3-19 | DVM_OPERATORS.md index | ✅ Done |
| DOC-P3-20 | VECTOR_RAG_STARTER parameter docs | ✅ Done |
| DOC-P3-21 | tuning-refresh-mode threshold prose | ✅ Done |
| DOC-P3-22 | multi_db_refresh_broker status banner | ✅ Done |
| DOC-CONS-28 | Terminology sweep | ✅ Done |
| DOC-CONS-29 | Capitalisation sweep | ✅ Done |
| DOC-CONS-30 | Code style sweep | ✅ Done |
| DOC-CONS-31 | Cross-link audit | ✅ Done |

---

### Files Changed

| File | Change |
|------|--------|
| `docs/tutorials/FIRST_DASHBOARD.md` | New file (~450 lines) |
| `docs/tutorials/EVENT_SOURCING.md` | New file (~450 lines) |
| `docs/tutorials/BACKFILL_AND_MIGRATION.md` | New file (~350 lines) |
| `docs/tutorials/SECURITY_HARDENING.md` | New file (~350 lines) |
| `docs/SECURITY_GUIDE.md` | Add role/grant templates section |
| `docs/WHATS_NEW.md` | Backfill v0.1–v0.7 entries |
| `docs/tutorials/HYBRID_SEARCH_PATTERNS.md` | Expand patterns 2–3 |
| `docs/tutorials/PER_TENANT_ANN_PATTERNS.md` | Document partition_key; expand patterns 2–3 |
| `docs/QUICKSTART_5MIN.md` | Fix installation.md → INSTALL.md link |
| `docs/GETTING_STARTED.md` | Fix installation.md → INSTALL.md link |
| `docs/PERFORMANCE_COOKBOOK.md` | Add §13 worked examples |
| `docs/SECURITY_MODEL.md` | Resolve supply-chain TODOs |
| `docs/FAQ.md` | Convert plain-text to markdown links |
| `docs/DVM_OPERATORS.md` | Add operator quick-reference index |
| `docs/tutorials/VECTOR_RAG_STARTER.md` | Document embedding_stream_table() params |
| `docs/tutorials/tuning-refresh-mode.md` | Add score threshold explanation |
| `docs/research/multi_db_refresh_broker.md` | Add status banner |
| All 83 docs files | Consistency pass (terminology, capitalisation, code style, links) |
| `docs/SUMMARY.md` | Add entries for four new tutorial files |