From 7cfd7b7ac9975fddbbce7e14174ead318f173ccb Mon Sep 17 00:00:00 2001
From: Jimmy Angelakos <jimmy@pgedge.com>
Date: Wed, 30 Sep 2026 20:15:57 +0100
Subject: [PATCH 1/3] docs: title-case headings and apply the pgEdge docs style
 pass

---
 DUCKDB_1.5_PATCHED.md          |  14 +-
 README.md                      |  21 +--
 docs/architecture.md           | 318 ++++++++++++++++-----------------
 docs/architecture_decoupled.md |  85 +++++----
 docs/architecture_tiered.md    | 204 ++++++++++-----------
 docs/architecture_vectors.md   |  34 ++--
 docs/compaction.md             |  24 +--
 docs/formal/README.md          | 106 +++++------
 docs/index.md                  |  12 +-
 docs/installation.md           |  32 ++--
 docs/object_store.md           |  61 +++----
 docs/usage.md                  | 135 +++++++-------
 docs/usage_vectors.md          |  62 ++++---
 docs/walkthrough.md            |   8 +-
 docs/walkthrough_demos.md      | 145 +++++++++------
 15 files changed, 645 insertions(+), 616 deletions(-)

diff --git a/DUCKDB_1.5_PATCHED.md b/DUCKDB_1.5_PATCHED.md
index 520bbee..bb61c3c 100644
--- a/DUCKDB_1.5_PATCHED.md
+++ b/DUCKDB_1.5_PATCHED.md
@@ -121,12 +121,14 @@ inside `DoTableUpdates` (PG `PRE_COMMIT`, while the ticket is held):
    3 then land the write on the live head. An expired start snapshot keeps the
    error.
 
-**Formally verified** before the code (the project rule):
-`docs/formal/Bakery.tla` models the async ordering; `Bakery_async.cfg`
-(patched) holds `NoLakekeeperConflict`, `Bakery_race.cfg` (async **without**
-the patch) violates it — the standing proof the patch is mandatory for async.
-**Validated** over Azure ADLS: journey 6b (4 concurrent mixed-tier writers →
-8/8, 0 loss) and 9b (8 concurrent cold writers → 8/8).
+### Formally verified
+
+Before the code (the project rule): `docs/formal/Bakery.tla` models the async
+ordering; `Bakery_async.cfg` (patched) holds `NoLakekeeperConflict`,
+`Bakery_race.cfg` (async **without** the patch) violates it — the standing
+proof the patch is mandatory for async. **Validated** over Azure ADLS: journey
+6b (4 concurrent mixed-tier writers → 8/8, 0 loss) and 9b (8 concurrent cold
+writers → 8/8).
 
 ## 3. Strict-reader interop (two patches + one upstream fix)
 
diff --git a/README.md b/README.md
index 0f640ad..3c8d8e1 100644
--- a/README.md
+++ b/README.md
@@ -70,13 +70,14 @@ modes in action with copy-pasteable commands.
 
 ColdFront is open source under the PostgreSQL License and runs on stock
 PostgreSQL 16, 17, and 18. The full build workflow lives in the
-**[Installation guide](docs/installation.md)**: build the thin coldfront layer
+**[Installation guide](docs/installation.md)**: build the thin ColdFront layer
 on top of the published DuckDB 1.5.x base image (or build the base yourself),
 or install bare-metal. Then continue with the Quickstart below.
 
-**Setting up on cloud S3?** Once the image is built, the
-**[S3 setup guide](docs/object_store.md)** takes you from an empty bucket to a
-working cold tier end-to-end.
+### Setting Up on Cloud S3?
+
+Once the image is built, the **[S3 setup guide](docs/object_store.md)** takes
+you from an empty bucket to a working cold tier end-to-end.
 
 ## Quickstart
 
@@ -106,18 +107,18 @@ SELECT count(*) FROM events;
 A table that already exists in the Iceberg catalog is adopted rather than
 created: `coldfront.adopt_iceberg_table()` reads its schema from the catalog
 and gives it the same wrapper view and registry row, read-only unless writes
-are asked for. `coldfront.release_iceberg_table()` hands it back with the
-Iceberg table untouched. See
-[Adopting a table that already exists in the catalog](docs/usage.md#adopting-a-table-that-already-exists-in-the-catalog).
+are asked for. `coldfront.release_iceberg_table()` hands the table back with
+the Iceberg table untouched. See
+[Adopting a Table That Already Exists in the Catalog](docs/usage.md#adopting-a-table-that-already-exists-in-the-catalog).
 
 To remove a table again, `coldfront.drop_iceberg_table()` unregisters it and
 drops the Iceberg table, deleting the stored objects only when asked to. See
-[Dropping an Iceberg table](docs/usage.md#dropping-an-iceberg-table-both-modes).
+[Dropping an Iceberg Table](docs/usage.md#dropping-an-iceberg-table-both-modes).
 
 For compliance environments that cannot store an object-store credential,
 `coldfront.set_storage_secret_vended()` runs with no credential in the
 database: Lakekeeper issues short-lived per-table credentials at access time.
-See [Vended credentials](docs/usage.md#vended-credentials).
+See [Vended Credentials](docs/usage.md#vended-credentials).
 
 ## Documentation
 
@@ -135,7 +136,7 @@ The following table lists the ColdFront guides and what each one covers:
 | **[Architecture: decoupled](docs/architecture_decoupled.md)** | Decoupled (iceberg-only) deep dive |
 | **[Architecture: vectors](docs/architecture_vectors.md)** | Vector storage internals - type mapping, routing state, cluster assignment, layout |
 
-## Least-privilege application roles
+## Least-Privilege Application Roles
 
 Application roles need no superuser and no server-file access, yet they read
 and write the cold tier through the same transparent view. Onboarding an
diff --git a/docs/architecture.md b/docs/architecture.md
index 0a7f065..d94e6c6 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -7,32 +7,16 @@ rewrites reads and writes to hit the right tier, and **all Iceberg I/O goes
 through `pg_duckdb` running in-process inside PostgreSQL** - no external query
 engine, no Go Iceberg libraries.
 
-## Contents
-
-This document is organized into the following sections:
-
-- [Operating modes and topologies](#operating-modes-and-topologies) - the three
-  axes + read target (primary / standby)
-- [System Overview](#system-overview) - the moving parts
-- [Core Mechanics: pg_duckdb](#core-mechanics-pg_duckdb) - how Iceberg I/O
-  happens
-- [Application Interface](#application-interface) - the shared rewrite hook
-- [Concurrency and pgEdge Spock Deployments](#concurrency-and-pgedge-spock-deployments) -
-  bakery, cold-write strategy, DDL, OID-vs-name
-- [Known Limitations](#known-limitations) - cross-cutting
-- [Infrastructure (Docker)](#infrastructure-docker)
-- [Upstream Requests](#upstream-requests) - open asks to pg_duckdb /
-  duckdb-iceberg
-
 For mode-specific design, see [architecture_tiered.md](architecture_tiered.md)
 (hot PG + cold Iceberg) ·
 [architecture_decoupled.md](architecture_decoupled.md) (all-Iceberg) ·
 [architecture_vectors.md](architecture_vectors.md) (vector storage).
 
-## Operating modes and topologies
+## Operating Modes and Topologies
 
-Three independent axes describe any ColdFront deployment, selected as shown
-below. They compose freely - e.g. tiered + mesh + permissive writes:
+Three independent axes describe any ColdFront deployment; they compose freely -
+e.g. tiered + mesh + permissive writes. The following table shows how each axis
+is selected:
 
 | Axis | Values | Selected by |
 |---|---|---|
@@ -44,14 +28,14 @@ Both storage modes coexist in one database and share **one** code path: the
 transparent view and read rewriter, the INSERT/UPDATE/DELETE hook (`emit_cold`
 / `emit_hot` / `emit_dual` in
 [`extension/coldfront/src/coldfront.c`](https://github.com/pgEdge/ColdFront/blob/main/extension/coldfront/src/coldfront.c)),
-and the `_exec_iceberg_with_claim` write chokepoint. Decoupled mode simply
-always classifies as `TIER_COLD` and never reaches `emit_hot`; vanilla and mesh
-differ only in how that chokepoint serializes cold writes. This document covers
-the shared mechanics and the tiered path; see
+and the `_exec_iceberg_with_claim` write chokepoint. Decoupled mode always
+classifies as `TIER_COLD` and never reaches `emit_hot`; vanilla and mesh differ
+only in how that chokepoint serializes cold writes. This document covers the
+shared mechanics and the tiered path; see
 [architecture_decoupled.md](architecture_decoupled.md) for the decoupled mode's
 ACID model and distributed scaling story.
 
-### Read target: primary or physical standby
+### Read Target: Primary or Physical Standby
 
 Orthogonal to the three axes above, any ColdFront node - vanilla or a mesh
 member - can have one or more **physical (streaming) standbys that serve
@@ -95,7 +79,7 @@ below:
 └──────────────┬───────────────────────────────────────────┘
                │
 ┌──────────────▼───────────────────────────────────────────┐
-│  Lakekeeper — Iceberg REST catalog (own dedicated Postgres)│
+│  Lakekeeper - Iceberg REST catalog (own dedicated Postgres)│
 │  Manages Iceberg metadata, snapshots, commit concurrency   │
 └──────────────┬───────────────────────────────────────────┘
                │
@@ -110,7 +94,7 @@ The following table describes each component, its role, and its license:
 | Component | Role | License |
 |-----------|------|---------|
 | PostgreSQL 16+ | Heap storage; range partitioning for the tiered hot tier. Works uniformly on PG 16, 17, and 18 - the cold-tier secret is a DuckDB persistent secret loaded at instance init, with no version-gated mechanism. | PostgreSQL |
-| pg_duckdb | DuckDB in-process. Iceberg read + write. Analytics. pg_duckdb 1.5.4 (PR #1025). The `duckdb-iceberg` carries the bakery-aware commit-refresh patch (async parquet overlap, no 409); see [Cold-write strategy](#cold-write-strategy-stock-vs-patched-duckdb-iceberg). | MIT |
+| pg_duckdb | DuckDB in-process. Iceberg read + write. Analytics. pg_duckdb 1.5.4 (PR #1025). The `duckdb-iceberg` carries the bakery-aware commit-refresh patch (async parquet overlap, no 409); see [Cold-Write Strategy](#cold-write-strategy-stock-vs-patched-duckdb-iceberg). | MIT |
 | coldfront | PGXS C extension. `post_parse_analyze_hook` rewrites INSERT/UPDATE/DELETE on registered views to the correct tier and, on a SELECT DuckDB will run, the spellings DuckDB lacks (`date_bin`, `::jsonb`, the JSON builders); `planner_hook` folds bound parameters into such a read; `ProcessUtility_hook` handles DDL; the hook lazily ATTACHes the Iceberg catalog on the first query touching a tiered view. | PostgreSQL |
 | Lakekeeper | Iceberg REST catalog. Single Rust binary. | Apache 2.0 |
 | S3-compatible store | Any: SeaweedFS, MinIO, GCS, Azure Blob, etc. | Varies |
@@ -118,7 +102,7 @@ The following table describes each component, its role, and its license:
 
 How rows move through this depends on the storage mode: the tiered hot heap +
 archiver + `UNION ALL` data-flow is in
-[architecture_tiered.md → Data flow](architecture_tiered.md#data-flow); the
+[architecture_tiered.md → Data Flow](architecture_tiered.md#data-flow); the
 all-Iceberg flow is in [architecture_decoupled.md](architecture_decoupled.md).
 
 ## Core Mechanics: pg_duckdb
@@ -127,7 +111,7 @@ All Iceberg I/O goes through SQL executed against PostgreSQL. There are no Go
 DuckDB/Iceberg/Arrow libraries. DuckDB Iceberg writes require a REST catalog -
 Lakekeeper fills this role.
 
-### Session setup
+### Session Setup
 
 The cold-tier S3 secret is set once per cluster. A single call records the
 credentials and materializes a DuckDB persistent secret:
@@ -173,14 +157,14 @@ The Iceberg catalog ATTACH is **lazy**: the coldfront C extension hook issues
 `coldfront.warehouse` and `coldfront.lakekeeper_endpoint` GUCs - on the **first
 query that touches a tiered view** (read or write), per DuckDB cached
 connection. There is no arming step and no per-session boilerplate: both reads
-(`iceberg_scan`) and writes (`duckdb.raw_query`) just work on a fresh psql
-session. Until a tiered view is touched no ATTACH is attempted, so a
-pre-bootstrap connection is never blocked by a missing warehouse.
+(`iceberg_scan`) and writes (`duckdb.raw_query`) work on a fresh psql session.
+Until a tiered view is touched no ATTACH is attempted, so a pre-bootstrap
+connection is never blocked by a missing warehouse.
 
-### Non-superuser app roles (least privilege)
+### Non-Superuser App Roles (Least Privilege)
 
 pg_duckdb force-disables DuckDB's `LocalFileSystem` for non-superusers (see
-[Upstream Requests](#pg_duckdb-non-superuser-localfilesystem-blocks-side-loaded-extensions)),
+[Upstream requests](#pg_duckdb-non-superuser-localfilesystem-blocks-side-loaded-extensions)),
 which would block the side-loaded iceberg/postgres DuckDB extensions from
 loading on `ATTACH`. So `coldfront.ensure_attached()` / `ensure_pg_attached()`
 are `SECURITY DEFINER` with a pinned `search_path`: the extension load +
@@ -217,7 +201,7 @@ still violates `NoLakekeeperConflict`).
 See README "Security"; asserted by the journey's `story_app_privilege`,
 `ci/ops.sh` check 3, and the `privilege_model` pg_regress test.
 
-### Temp table bridge: PG → Iceberg
+### Temp Table Bridge: PG → Iceberg
 
 `duckdb.raw_query()` cannot see PG tables directly. The bridge is a DuckDB temp
 table:
@@ -230,7 +214,7 @@ SELECT duckdb.raw_query($$INSERT INTO ice.public.events
 DROP TABLE duck_stage;
 ```
 
-### Cold-side column references
+### Cold-Side Column References
 
 `iceberg_scan()` requires `r['col']::type` syntax:
 
@@ -256,7 +240,7 @@ the statement the view is named (a CTE, a sub-select, a set-operation branch):
 `date_bin`, the `::jsonb` cast, `jsonb_array_length` and the JSON builders
 (`jsonb_build_object`, `jsonb_agg` and their `json_` twins) are rewritten into
 spellings both engines accept (see
-[usage.md → Supported column types](usage.md#supported-column-types)). A
+[usage.md → Supported Column Types](usage.md#supported-column-types)). A
 `planner_hook` folds bound parameters into such a read before pg_duckdb plans
 it when a parameter sits where DuckDB cannot type a placeholder (a direct
 argument of a pg_duckdb function, any argument of a table function); the plan
@@ -265,7 +249,7 @@ priced above any custom plan, so under the plan cache's cost-based selection
 the read is planned from its values on every execution.
 `plan_cache_mode = force_generic_plan` bypasses that selection and picks the
 value-less generic plan, which fails with `only works with DuckDB execution`
-(see [usage.md → Supported column types](usage.md#supported-column-types)).
+(see [usage.md → Supported Column Types](usage.md#supported-column-types)).
 
 The following table maps each operation to its interface and routing path:
 
@@ -289,23 +273,22 @@ How the hook splits a write is mode-specific:
 - **Decoupled** always classifies `TIER_COLD`: every write is a single-tier
   Iceberg write. See [architecture_decoupled.md](architecture_decoupled.md).
 
-### Cold-tier DML from inside plpgsql (functions, DO blocks, triggers)
+### Cold-Tier DML from Inside PL/pgSQL (Functions, DO Blocks, Triggers)
 
 Cold-tier `INSERT`/`UPDATE`/`DELETE` work as top-level statements *and* from
 inside a plpgsql function / `DO` block / trigger, via two mechanisms:
 
-1. **Parameters are emitted as a runtime `format(<template>, $1, $2, …)` call**
-   (`cold_sql_arg`), with the param types declared on the re-parse
-   (`parse_analyze_fixedparams`). PG binds the values at execution, so DuckDB
-   only ever sees finished literals. This applies everywhere - a driver's
-   parameterized cold `UPDATE` at the top level is the same case.
+- **Parameters are emitted as a runtime `format(<template>, $1, $2, …)` call**
+  (`cold_sql_arg`), with the param types declared on the re-parse
+  (`parse_analyze_fixedparams`). PG binds the values at execution, so DuckDB
+  only ever sees finished literals. This applies everywhere - a driver's
+  parameterized cold `UPDATE` at the top level is the same case.
 
-2. **A cold call parsed inside plpgsql is wrapped as a DML over a permanent
-   single-row carrier, `coldfront._dummy_dml_target`.** plpgsql rejects a bare
-   result-returning `SELECT` with no `INTO`/`PERFORM` ("query has no
-   destination for result data") and the cold target is a DuckDB-attached
-   object PG cannot tag a real DML against, so the call is reshaped as a no-row
-   DML:
+- **A cold call parsed inside plpgsql is wrapped as a DML over a permanent
+  single-row carrier, `coldfront._dummy_dml_target`.** plpgsql rejects a bare
+  result-returning `SELECT` with no `INTO`/`PERFORM` ("query has no destination
+  for result data") and the cold target is a DuckDB-attached object PG cannot
+  tag a real DML against, so the call is reshaped as a no-row DML:
 
     ```sql
     UPDATE coldfront._dummy_dml_target SET anchor = anchor
@@ -338,13 +321,13 @@ ColdFront coordinates concurrent writes across the cluster as follows:
   PG-side by the **bakery protocol** in the coldfront extension - every
   iceberg-only INSERT/UPDATE/DELETE wraps in
   `coldfront._exec_iceberg_with_claim`, which holds a globally-ordered
-  snowflake ticket via the Spock-replicated `coldfront.claims` table and waits
+  Snowflake ticket via the Spock-replicated `coldfront.claims` table and waits
   for its turn before issuing the iceberg commit. No 409s, no app-level retry.
   See
   [architecture_decoupled.md → Concurrency](architecture_decoupled.md#concurrency-horizontal-scaling-the-bakery-protocol)
   for the full design and benchmarks.
 
-### Cold-write strategy: stock vs patched duckdb-iceberg
+### Cold-Write Strategy: Stock vs Patched duckdb-iceberg
 
 Every cold write runs through the same `_exec_iceberg_with_claim` chokepoint.
 What differs is *when* the bakery ticket is held. The async ordering is active
@@ -404,7 +387,7 @@ replicated `ALTER TABLE`; the hook rebuilds **that peer's own** local view, but
 `coldfront._mirror_iceberg_alter` skips the Iceberg `ALTER` there (it runs
 under `session_replication_role = replica`) because the originator already
 evolved the shared Lakekeeper catalog. Because the registry is name-keyed (see
-[Registry keying](#registry-keying-by-name-not-oid)), the row is identical on
+[Registry Keying](#registry-keying-by-name-not-oid)), the row is identical on
 every node: the rebuild needs no re-pointing. DROP and TRUNCATE are blocked on
 every node. What a tiered table additionally needs to be usable on a peer is
 covered next.
@@ -412,9 +395,9 @@ covered next.
 The tiered-specific cross-node behavior - what replicates so a tiered table is
 usable on every peer, and why both the registry and the watermark join the
 replication set - is in
-[architecture_tiered.md → Tiered tables in a Spock mesh](architecture_tiered.md#tiered-tables-in-a-spock-mesh).
+[architecture_tiered.md → Tiered Tables in a Spock Mesh](architecture_tiered.md#tiered-tables-in-a-spock-mesh).
 
-### Registry keying: by name, not OID
+### Registry Keying: By Name, Not OID
 
 `coldfront.tiered_views` is keyed by `(schema_name, relname)` - the transparent
 view's qualified name. The C hook resolves it with
@@ -436,32 +419,32 @@ node-independent, so the registry row is identical on every node and the
 replication set copies it by value (an OID is node-local and could not be).
 That is what makes cross-node tiered tables work with no per-node
 re-resolution - see
-[architecture_tiered.md → Tiered tables in a Spock mesh](architecture_tiered.md#tiered-tables-in-a-spock-mesh).
+[architecture_tiered.md → Tiered Tables in a Spock Mesh](architecture_tiered.md#tiered-tables-in-a-spock-mesh).
 
 Lower-level operations that genuinely need an OID - catalog lookups, the DDL
 hook matching the hot heap - resolve name→OID via `to_regclass` /
 `get_rel_name` at the point of use: names everywhere, OIDs only where required.
 
-### Per-table config: `coldfront.partition_config`
+### Per-Table Config: `coldfront.partition_config`
 
 Which tables are managed and their lifecycle (`hot_period`, `retention_period`,
 `partition_period`, premake, mode, `expiration_strategy`) live in
 `coldfront.partition_config` - like `tiered_views` and `archive_watermark`, a
-name-keyed table (see [Registry keying](#registry-keying-by-name-not-oid)). It
-is auto-added to the default replication set on a spock node (a no-op on
-vanilla, where there is one node), so every node reads identical config with no
-per-node file syncing. `hot_period` and `retention_period` are native
-PostgreSQL `interval` columns - the column type validates each value on write,
-and expiry cutoffs are computed in-DB with calendar-accurate interval
-arithmetic (`now() - period`: real months, leap years), never an approximate
-fixed-day duration in Go. `CHECK` constraints encode the structural lifecycle
-rules (a destroy boundary is required; `id` mode forbids a hot tier - the cold
-tier is time-only; 2-level needs an explicit RANGE column;
-`expiration_strategy` is `drop`|`detach`, and `detach` - expire by detaching
-only, not dropping - is allowed partition-only), so an invalid row is rejected
-at write time. The one rule that is *operator-config policy* rather than a
-storage invariant - `retention_period` must exceed `hot_period` - is validated
-at the `register`/`set` CLI boundary and at binary startup
+name-keyed table (see [Registry Keying](#registry-keying-by-name-not-oid)).
+`coldfront.partition_config` is auto-added to the default replication set on a
+Spock node (a no-op on vanilla, where there is one node), so every node reads
+identical config with no per-node file syncing. `hot_period` and
+`retention_period` are native PostgreSQL `interval` columns - the column type
+validates each value on write, and expiry cutoffs are computed in-DB with
+calendar-accurate interval arithmetic (`now() - period`: real months, leap
+years), never an approximate fixed-day duration in Go. `CHECK` constraints
+encode the structural lifecycle rules (a destroy boundary is required; `id`
+mode forbids a hot tier - the cold tier is time-only; 2-level needs an explicit
+RANGE column; `expiration_strategy` is `drop`|`detach`, and `detach` - expire
+by detaching only, not dropping - is allowed partition-only), so an invalid row
+is rejected at write time. The one rule that is *operator-config policy* rather
+than a storage invariant - `retention_period` must exceed `hot_period` - is
+validated at the `register`/`set` CLI boundary and at binary startup
 (`partition.ValidatePeriods`, a calendar-aware interval comparison),
 deliberately **not** a CHECK. The standalone partitioner self-materializes the
 table on stock PostgreSQL via `EnsureTable`, needing no extension. Connection
@@ -498,50 +481,50 @@ Both expose a management CLI - `register` / `list` / `set` / `remove` /
 These apply to both storage modes. Tiered-only limitations (cold RETURNING,
 dual-tier command tag, crash-safety of permissive writes, partition-scheme
 constraints, autovacuum-vs-cutover) are in
-[architecture_tiered.md → Tiered-specific limitations](architecture_tiered.md#tiered-specific-limitations).
+[architecture_tiered.md → Tiered-Specific Limitations](architecture_tiered.md#tiered-specific-limitations).
 
 The cross-cutting limitations are:
 
-1. **One-time secret setup after warehouse bootstrap** - after Lakekeeper is
-   provisioned, an operator calls `SELECT coldfront.set_storage_secret(...)`
-   once per cluster; the catalog ATTACH itself is lazy, so there is no
-   per-session arming (see [Session setup](#session-setup)).
-
-2. **`jsonb` surfaces as `json` through the view** - DuckDB has no native
-   `jsonb`, and pg_duckdb takes over any query that references `iceberg_scan`
-   (all-or-nothing plan takeover), so the cold branch can't produce a PG
-   `jsonb` directly. The view generator casts `jsonb` columns to DuckDB-safe
-   `json` on both sides: hot emits `"col"::json`, cold emits `r['col']::json`,
-   the UNION unifies on `json`. Standard JSON access (`->>`, `->`, `#>`) works
-   without any caller-side cast; jsonb-only operators (`?`, `@>`, containment,
-   de-dup) need an explicit `data::jsonb` in the caller's query. Storage in
-   Iceberg remains VARCHAR (Iceberg has no JSON type either). The INSTEAD OF
-   trigger's cold path still casts the incoming value to `text` before sending
-   it to `duckdb.raw_query`.
-
-3. **S3 compatibility** - Lakekeeper remote signing may not work with all
-   S3-compatible stores. Workaround: `ACCESS_DELEGATION_MODE NONE` with direct
-   DuckDB S3 secret.
-
-4. **Planner-level interception, no per-query decision engine** - `pg_duckdb`
-   decides whether to take over a query by inspecting the parse tree for
-   signals (references to `iceberg_scan`, the `duckdb.force_execution` GUC,
-   DuckDB-only functions). Once it takes over, the whole statement runs in
-   DuckDB; there is no cost-based hot-vs-cold split per predicate. Hot-only
-   queries can target `_events` directly (native PG, no `pg_duckdb` roundtrip);
-   queries that need cross-tier semantics go through the view.
-
-5. **Single-node query execution** - a query runs on the PG backend it landed
-   on. `pg_duckdb` does not distribute the DuckDB plan across nodes.
-   Replication (single- or multi-master via pgEdge Spock) is supported on the
-   hot tier and transparent to the application; scaling read throughput
-   requires more replicas rather than parallelizing one query. Those replicas,
-   including read-only physical standbys, serve cross-tier reads (see
-   [Read target](#read-target-primary-or-physical-standby)).
-
-6. **Iceberg only** - no Delta Lake support. Adding Delta would require either
-   a second writer path in `pg_duckdb`'s Iceberg extension or a different
-   analytical engine.
+- **One-time secret setup after warehouse bootstrap** - after Lakekeeper is
+  provisioned, an operator calls `SELECT coldfront.set_storage_secret(...)`
+  once per cluster; the catalog ATTACH itself is lazy, so there is no
+  per-session arming (see [Session Setup](#session-setup)).
+
+- **`jsonb` surfaces as `json` through the view** - DuckDB has no native
+  `jsonb`, and pg_duckdb takes over any query that references `iceberg_scan`
+  (all-or-nothing plan takeover), so the cold branch can't produce a PG `jsonb`
+  directly. The view generator casts `jsonb` columns to DuckDB-safe `json` on
+  both sides: hot emits `"col"::json`, cold emits `r['col']::json`, the UNION
+  unifies on `json`. Standard JSON access (`->>`, `->`, `#>`) works without any
+  caller-side cast; jsonb-only operators (`?`, `@>`, containment, de-dup) need
+  an explicit `data::jsonb` in the caller's query. Storage in Iceberg remains
+  VARCHAR (Iceberg has no JSON type either). The INSTEAD OF trigger's cold path
+  still casts the incoming value to `text` before sending it to
+  `duckdb.raw_query`.
+
+- **S3 compatibility** - Lakekeeper remote signing may not work with all
+  S3-compatible stores. Workaround: `ACCESS_DELEGATION_MODE NONE` with direct
+  DuckDB S3 secret.
+
+- **Planner-level interception, no per-query decision engine** - `pg_duckdb`
+  decides whether to take over a query by inspecting the parse tree for signals
+  (references to `iceberg_scan`, the `duckdb.force_execution` GUC, DuckDB-only
+  functions). Once it takes over, the whole statement runs in DuckDB; there is
+  no cost-based hot-vs-cold split per predicate. Hot-only queries can target
+  `_events` directly (native PG, no `pg_duckdb` roundtrip); queries that need
+  cross-tier semantics go through the view.
+
+- **Single-node query execution** - a query runs on the PG backend it landed
+  on. `pg_duckdb` does not distribute the DuckDB plan across nodes. Replication
+  (single- or multi-master via pgEdge Spock) is supported on the hot tier and
+  transparent to the application; scaling read throughput requires more
+  replicas rather than parallelizing one query. Those replicas, including
+  read-only physical standbys, serve cross-tier reads (see
+  [Read Target](#read-target-primary-or-physical-standby)).
+
+- **Iceberg only** - no Delta Lake support. Adding Delta would require either a
+  second writer path in `pg_duckdb`'s Iceberg extension or a different
+  analytical engine.
 
 ## Infrastructure (Docker)
 
@@ -557,6 +540,9 @@ and a thin **app** layer (`docker/Dockerfile.duckdb15`,
 plays both topology roles - vanilla leaves spock/snowflake out of
 `shared_preload_libraries`; mesh loads them (`MESH=on`, set by the entrypoint).
 
+The following compose file shows the three services - the database, Lakekeeper,
+and the S3-compatible store:
+
 ```yaml
 services:
   db:
@@ -578,11 +564,11 @@ then warehouse creation (`POST /management/v1/warehouse`) with S3 credentials
 and `sts-enabled: false`, `remote-signing-enabled: false`.
 
 Lakekeeper keeps its own catalog tables in a PostgreSQL database (and its
-schema migration needs the `uuid-ossp` contrib extension). It runs on its **own
-dedicated Postgres** - a separate `lakekeeper-db` container in the test stack,
-and a separate managed instance in production - **never co-located on a
-ColdFront data node.** Co-locating would couple the catalog's availability and
-load to a data node and would drag contrib into the ColdFront image for no
+schema migration needs the `uuid-ossp` contrib extension). Lakekeeper runs on
+its **own dedicated Postgres** - a separate `lakekeeper-db` container in the
+test stack, and a separate managed instance in production - **never co-located
+on a ColdFront data node.** Co-locating would couple the catalog's availability
+and load to a data node and would drag contrib into the ColdFront image for no
 reason; the dedicated store keeps the ColdFront image lean (core `uuid` type
 only, no uuid-ossp).
 
@@ -592,7 +578,7 @@ Behaviors in upstream projects that ColdFront works around, kept as
 architectural notes: the gap, the workaround in use today, and the shape of the
 upstream capability that would let us drop the workaround.
 
-### pg_duckdb: non-superuser LocalFileSystem blocks side-loaded extensions
+### pg_duckdb: Non-Superuser LocalFileSystem Blocks Side-Loaded Extensions
 
 pg_duckdb force-disables DuckDB's `LocalFileSystem` for non-superusers, which
 also blocks **loading a locally-installed DuckDB extension** - and ColdFront
@@ -600,31 +586,31 @@ side-loads a patched `iceberg` (and `postgres`) extension from disk, which
 DuckDB lazily loads on `ATTACH`, so a non-superuser's first cold query fails at
 the elevated load step.
 
-**Workaround today:** the `SECURITY DEFINER` attach helpers described under
-[Non-superuser app roles](#non-superuser-app-roles-least-privilege).
+Workaround today: the `SECURITY DEFINER` attach helpers described under
+[Non-Superuser App Roles](#non-superuser-app-roles-least-privilege).
 
-**Upstream shape that would drop it:** either a way to mark specific
+Upstream shape that would drop it: either a way to mark specific
 locally-installed extensions as loadable without `LocalFileSystem` access, or
 distinguishing extension-load file access from user-initiated raw file access
 in the non-superuser sandbox - so a non-superuser member of
 `duckdb.postgres_role` could `ATTACH (TYPE ICEBERG, …)` directly, without
 ColdFront's `SECURITY DEFINER` shim.
 
-### pg_duckdb: native PG-reader → Iceberg streaming (no libpq round-trip)
+### pg_duckdb: Native PG-Reader → Iceberg Streaming (No libpq Round-Trip)
 
 pg_duckdb has a fully-native, in-process Postgres-table reader for analytics on
 PG heap data, but that machinery is **not reachable** from the write path into
 an attached Iceberg catalog.
 
-**Workaround today:** ColdFront's hook rewrites the INSERT into one
+Workaround today: ColdFront's hook rewrites the INSERT into one
 `duckdb.raw_query` that reads through the DuckDB `postgres` extension's
 `pglocal.<schema>.<table>` ATTACH, pipelining rows over libpq (loopback) →
 DuckDB executor → Iceberg writer → S3 in a single pass, no local
 materialization. The cost is the libpq round-trip per row batch - real, but
 dwarfed by the Iceberg commit work for any realistic batch.
 
-**Desired end-state.** A way to drive the native in-process reader straight
-into the Iceberg writer - e.g. a `COPY` form:
+Desired end-state. A way to drive the native in-process reader straight into
+the Iceberg writer - e.g. a `COPY` form:
 
 ```sql
 COPY (SELECT * FROM public.events_partition) TO ICEBERG 'ice.public.events';
@@ -634,7 +620,7 @@ That would make pg_duckdb the only place in the data path that touches the
 rows: PG executor (heap reader) → pg_duckdb vector format → Iceberg writer,
 **one pass, in-process**, with no libpq loopback and no temp-disk.
 
-### pg_duckdb: a statement DuckDB cannot run is refused, not delegated
+### pg_duckdb: A Statement DuckDB Cannot Run Is Refused, Not Delegated
 
 pg_duckdb's planner hook takes over any statement whose parse tree references a
 DuckDB item, and then requires that statement to be one DuckDB can execute:
@@ -653,7 +639,7 @@ A plain `INSERT ... VALUES` through an `INSTEAD OF INSERT` trigger is
 unaffected, because that plan never expands the view and so carries no DuckDB
 item into the hook.
 
-**Workaround today:** ColdFront's `post_parse_analyze_hook` rewrites
+Workaround today: ColdFront's `post_parse_analyze_hook` rewrites
 INSERT/UPDATE/DELETE on a registered view into its hot, cold or dual emit path
 before planning, so on the paths ColdFront owns pg_duckdb only ever sees a
 shape it accepts; the wrapper view's `INSTEAD OF INSERT` trigger covers plain
@@ -661,13 +647,13 @@ inserts when the extension is not loaded. What has no workaround is a view an
 application defines over cold data with its own `INSTEAD OF UPDATE`/`DELETE`
 triggers, or an `INSERT ... SELECT` drawing from such a view.
 
-**Upstream shape that would drop it:** where `NeedsDuckdbExecution` is true and
+Upstream shape that would drop it: where `NeedsDuckdbExecution` is true and
 `IsAllowedStatement` is false, chain to the previous planner hook instead of
 throwing, so PostgreSQL plans the statement and its `INSTEAD OF` triggers fire.
 Every statement DuckDB can run stays on the DuckDB path, and the check that
 decides this already exists in a non-throwing form.
 
-### DuckDB: spill files are not namespaced per instance
+### DuckDB: Spill Files Are Not Namespaced per Instance
 
 DuckDB names a spill file from a counter that starts at zero in every instance
 (`duckdb_temp_storage_<class>-<index>.tmp`, `duckdb_temp_block-<id>.block`),
@@ -680,7 +666,7 @@ aggregate under a 150 MB memory limit, three died with
 `IO Error: Could not read enough bytes`. Tracked as duckdb#15173 (open,
 reproduced); pg_duckdb#887 is an unmerged fix one layer up.
 
-**Workaround today:** each backend takes a subdirectory of the configured path
+Workaround today: each backend takes a subdirectory of the configured path
 named after its own PID, assigned by `cf_own_duckdb_temp_dir` from the
 parse-analyze hook on the session's first statement, which is ahead of
 pg_duckdb building its instance and reading the setting. The same hook reclaims
@@ -689,46 +675,44 @@ and the directory and reporting what that freed. That sweep runs once per
 session and costs single-digit milliseconds per spill file, so even a directory
 abandoned with 600 GB in it (about 600 files at DuckDB's file size) is a couple
 of seconds on the one statement that finds it. See
-[usage.md → Tuning knobs](usage.md#tuning-knobs).
+[usage.md → Tuning Knobs](usage.md#tuning-knobs).
 
 The PID is what makes that reclaim possible, and is why ColdFront does not
-simply carry pg_duckdb#887, which names the directory with a random uuid and
-removes it from an `on_proc_exit` hook. That hook does not run when a backend
-is killed by `SIGKILL`, an immediate shutdown or the OOM killer, which is
-precisely when spill files are left behind, and a random name cannot be
-attributed to an owner afterwards: nothing can decide whether the directory
-belongs to a live session or a dead one, so the disk is never reclaimed. A PID
-can be checked against the live backends (`BackendPidGetProc`), so any later
-session reclaims the orphans, whole gigabytes at a time. A reused PID resolves
-to a live backend and is left alone, as is any directory holding something
-other than spill files.
-
-**Upstream shape that would drop it:** a spill filename that carries the
-instance's own identity, so instances sharing a temp directory cannot collide
-and teardown deletes only what it wrote. That belongs in DuckDB, where the
-naming is, rather than in each embedder.
-
-### duckdb-iceberg: secret visibility under fresh transactions
+carry pg_duckdb#887, which names the directory with a random uuid and removes
+it from an `on_proc_exit` hook. That hook does not run when a backend is killed
+by `SIGKILL`, an immediate shutdown or the OOM killer, which is precisely when
+spill files are left behind, and a random name cannot be attributed to an owner
+afterwards: nothing can decide whether the directory belongs to a live session
+or a dead one, so the disk is never reclaimed. A PID can be checked against the
+live backends (`BackendPidGetProc`), so any later session reclaims the orphans,
+whole gigabytes at a time. A reused PID resolves to a live backend and is left
+alone, as is any directory holding something other than spill files.
+
+Upstream shape that would drop it: a spill filename that carries the instance's
+own identity, so instances sharing a temp directory cannot collide and teardown
+deletes only what it wrote. That belongs in DuckDB, where the naming is, rather
+than in each embedder.
+
+### duckdb-iceberg: Secret Visibility Under Fresh Transactions
 
 A secret created with `CREATE SECRET` from a caller's still-active transaction
 is not visible to the fresh transaction `duckdb-iceberg` opens for its
 commit-time I/O, so a fresh PG backend's first cold-tier write would fail with
 HTTP 403 against any non-AWS S3-compatible endpoint.
 
-**Workaround today:** the DuckDB **persistent secret** materialized by
-`coldfront.set_storage_secret(...)` (see [Session setup](#session-setup)) -
+Workaround today: the DuckDB **persistent secret** materialized by
+`coldfront.set_storage_secret(...)` (see [Session Setup](#session-setup)) -
 loaded at instance init, it already sits at a committed timestamp before any
 backend's first cold-tier write looks it up.
 
-**Desired end-state.** Either `IcebergTransaction::Commit` runs its commit-time
-I/O under the caller's `ClientContext` (rather than a freshly-opened
-Connection), or any extension that synthesises `CREATE SECRET` from external
-state commits that transaction explicitly, so the secret sits at a committed
-timestamp before a consumer's fresh transaction looks it up. Either would let a
-per-session synthesized secret work without relying on the persistent-secret
-mechanism.
+Desired end-state. Either `IcebergTransaction::Commit` runs its commit-time I/O
+under the caller's `ClientContext` (rather than a freshly-opened Connection),
+or any extension that synthesises `CREATE SECRET` from external state commits
+that transaction explicitly, so the secret sits at a committed timestamp before
+a consumer's fresh transaction looks it up. Either would let a per-session
+synthesized secret work without relying on the persistent-secret mechanism.
 
-### duckdb-iceberg: append to the manifest list instead of rebuilding it
+### duckdb-iceberg: Append to the Manifest List Instead of Rebuilding It
 
 At commit, duckdb-iceberg (v1.5) rebuilds the new snapshot's manifest list from
 every entry of the existing one (`CreateFromEntries` plus
@@ -738,19 +722,19 @@ writer holds the bakery ticket, and its cost grows with the manifest-list
 length, so it inflates the serialized critical section (compaction only partly
 offsets it).
 
-**Workaround today:** the `iceberg-bakery-aware-commit-refresh` patch re-reads
-the manifest list from the freshly-loaded catalog head inside the ticket
+Workaround today: the `iceberg-bakery-aware-commit-refresh` patch re-reads the
+manifest list from the freshly-loaded catalog head inside the ticket
 (`RefreshExistingManifestList`). This is correct - it folds in any peer
 manifests committed since this writer staged its parquet - but it pays the full
 re-scan of the manifest list under the lock.
 
-**Upstream shape that would drop it:** a manifest-list commit that appends the
-new manifest to the existing manifest-list file, referenced by path from the
+Upstream shape that would drop it: a manifest-list commit that appends the new
+manifest to the existing manifest-list file, referenced by path from the
 current catalog head, instead of rebuilding from all scanned entries. That
 keeps peer inclusion (the fresh head already points at peers' manifests) while
 removing the full re-scan from the commit, so the serialized section no longer
-grows with manifest-list length. It is correctness-sensitive (manifest-list
-integrity, commit conflicts, silent data loss) and its throughput value is
-unmeasured and workload dependent, so it belongs upstream with fleet
-benchmarking rather than as a ColdFront-carried patch.
+grows with manifest-list length. That change is correctness-sensitive
+(manifest-list integrity, commit conflicts, silent data loss) and its
+throughput value is unmeasured and workload dependent, so it belongs upstream
+with fleet benchmarking rather than as a ColdFront-carried patch.
 
diff --git a/docs/architecture_decoupled.md b/docs/architecture_decoupled.md
index 3cb75b4..6717e31 100644
--- a/docs/architecture_decoupled.md
+++ b/docs/architecture_decoupled.md
@@ -1,17 +1,16 @@
-# Decoupled (iceberg-only) operating mode
+# Decoupled (Iceberg-Only) Operating Mode
 
-This document describes an alternate operating mode of the coldfront project
+This document describes an alternate operating mode of the ColdFront project
 where a table lives entirely in Iceberg - no PG-native heap, no hot tier, no
 archiver. PostgreSQL becomes a stateless compute front-end; storage is owned by
-Lakekeeper + the underlying S3-compatible object store.
+Lakekeeper + the underlying S3-compatible object store. Decoupled mode shares
+the same codebase, docker stack and extension as tiered mode. The shared
+mechanics - pg_duckdb Iceberg I/O, the rewrite hook, the bakery protocol, the
+registry - are in [architecture.md](architecture.md); tiered mode is in
+[architecture_tiered.md](architecture_tiered.md). This document covers what is
+specific to decoupled mode.
 
-It shares the same codebase, docker stack and extension as tiered mode. The
-shared mechanics - pg_duckdb Iceberg I/O, the rewrite hook, the bakery
-protocol, the registry - are in [architecture.md](architecture.md); tiered mode
-is in [architecture_tiered.md](architecture_tiered.md). This document covers
-what is specific to decoupled mode.
-
-## What "decoupled" means
+## What "Decoupled" Means
 
 The table below contrasts each concern between tiered mode and decoupled mode
 described in this document:
@@ -43,7 +42,7 @@ Iceberg snapshot per statement. Tables that don't appear in
 `coldfront.tiered_views` are invisible to the hook (`lookup_tiered_view`
 returns null → fast path-out).
 
-## Bootstrap sequence
+## Bootstrap Sequence
 
 Configure the warehouse GUCs, then create the extensions and storage secret
 once per database:
@@ -63,7 +62,7 @@ SELECT coldfront.set_storage_secret('<key>', '<secret>', '<endpoint>');  -- cold
 table - an extension-member table (so its data is excluded from `pg_dump` by
 default) that is added to the Spock repset (so it replicates by value to every
 mesh node) - and materializes a DuckDB PERSISTENT SECRET, which DuckDB loads at
-instance init. It is set once; no per-session arming is needed.
+instance init. The secret is set once; no per-session arming is needed.
 
 After that, the first query touching a tiered view in any session lazily
 attaches the catalog and `ice.public.*` becomes available.
@@ -73,7 +72,7 @@ attaches the catalog and `ice.public.*` becomes available.
 With the coldfront extension loaded and the storage secret set, the wrapper
 view supports the operations below.
 
-### What works
+### What Works
 
 The following operations are supported, with their dispatch path and notes:
 
@@ -89,7 +88,7 @@ The following operations are supported, with their dispatch path and notes:
 | ROLLBACK of writes | `BEGIN; raw_query(...); ROLLBACK;` | pg_duckdb's `XactCallback` ties DuckDB↔PG tx, so ROLLBACK undoes pending Iceberg writes |
 | DROP TABLE | `SELECT coldfront.drop_iceberg_table('<schema>', '<name>', <purge>)` | Removes the wrapper view and every registration row, vector configuration included. A raw `DROP TABLE` through `duckdb.raw_query` drops only the catalog table and leaves them behind |
 
-### What does not work
+### What Does Not Work
 
 The following attempts fail, with the reason for each:
 
@@ -105,7 +104,7 @@ through `duckdb.raw_query('… DuckDB SQL …')`. Neither is as ergonomic as a
 normal PG table. This is the fundamental ergonomics gap of decoupled mode
 without a PG-side wrapper view.
 
-## Supported column types
+## Supported Column Types
 
 The supported column types are exactly the set that round-trips cleanly between
 PG and Iceberg (shared with tiered mode; see `pgFormatTypeToDuckDB` in
@@ -147,11 +146,11 @@ The narrowing is deliberate: a type that cannot round-trip exactly is rejected
 rather than silently downgraded, because data that appears stored but changes
 shape on read is worse than no support.
 
-## Wrapper helper: `coldfront.create_iceberg_table()`
+## Wrapper Helper: `coldfront.create_iceberg_table()`
 
 Raw_query / iceberg_scan are functional but ergonomically poor - every read
 needs `r['col']` accessor, every write needs a
-`duckdb.raw_query('… DuckDB SQL …')` envelope. To close that gap, coldfront
+`duckdb.raw_query('… DuckDB SQL …')` envelope. To close that gap, ColdFront
 ships a single helper that provisions an Iceberg-only table together with a
 PG-side wrapper view and a registry row that arms the C hook to handle every
 DML on the view. After that, applications use **plain PG syntax** against the
@@ -193,7 +192,7 @@ What the helper does:
    column types are validated by `coldfront._iceberg_storage_type()`, which
    mirrors the canonical map in `cmd/archiver/main.go pgFormatTypeToDuckDB`.
    Anything outside the supported set (see
-   [Supported column types](#supported-column-types) above) raises before any
+   [Supported Column Types](#supported-column-types) above) raises before any
    DDL is issued.
 3. `CREATE OR REPLACE VIEW <schema>.<name> AS SELECT r['col']::pg_type AS col, … FROM duckdb.query('SELECT * FROM ice.public.<name>') AS t(r)` -
    projection wraps the struct accessor so applications see flat columns.
@@ -232,7 +231,7 @@ Limits the helper inherits from the platform:
 The helper doesn't add capability over raw_query - it composes the existing
 primitives into a single call so applications get a normal-looking PG table.
 
-## Wrapper helper: `coldfront.adopt_iceberg_table()`
+## Wrapper Helper: `coldfront.adopt_iceberg_table()`
 
 Adoption registers a table that already exists in the Iceberg catalog. The
 wrapper view and the registry row are built from the schema the catalog holds,
@@ -264,7 +263,7 @@ registry row records writability. The C hook emits `tiered_views.iceberg_table`
 verbatim, so a reference outside `ice.<pg_schema>.<pg_relname>` needs no
 further handling.
 
-### Types an adopted column reads as
+### Types an Adopted Column Reads As
 
 Iceberg records no PostgreSQL type, so the PostgreSQL types that share one
 storage type all come back as the type that storage type reads as natively. The
@@ -327,7 +326,7 @@ refuse a read-only relation too, since each rewrites or destroys the Iceberg
 table. The archiver and `create_iceberg_table()` set the flag; adoption
 defaults it to false.
 
-### One relation per Iceberg table
+### One Relation per Iceberg Table
 
 `coldfront.tiered_views` has a unique constraint on `iceberg_table`, and
 adoption refuses a reference that is already registered. The cluster-column
@@ -340,7 +339,7 @@ with every part quoted, such as `"ice"."lake"."orders"`, and the compactor
 claims under that same spelling. The constraint and the bakery compare
 references as strings, so each Iceberg table has exactly one.
 
-### Adoption binds the name once
+### Adoption Binds the Name Once
 
 A second `adopt_iceberg_table()` under a registered name is refused whatever
 its arguments, as is a tiered relation's name. To arm writes, change an
@@ -354,7 +353,7 @@ a peer's own adopt is refused as already registered. A release unregisters
 everywhere, because the registry `DELETE` precedes the `DROP VIEW` in the same
 transaction and disarms the peer's DDL hook before the drop is applied there.
 
-### Handing a table back
+### Handing a Table Back
 
 `coldfront.release_iceberg_table()` removes the wrapper view, the registry row
 and the relation's vector configuration, and performs no Iceberg I/O, so the
@@ -385,7 +384,7 @@ Adoption inherits three limits:
   the watermark and the partition configuration would have to be reconciled
   with data ColdFront did not write.
 
-## Wrapper helper: `coldfront.drop_iceberg_table()`
+## Wrapper Helper: `coldfront.drop_iceberg_table()`
 
 Drops the Iceberg table backing a registered relation, in either mode:
 
@@ -411,7 +410,7 @@ differ, and the function says which path it took in a NOTICE:
 `p_purge` has no default, because the two outcomes are irreversible in opposite
 directions. `true` deletes the data and metadata objects, which for the cold
 tier are the only copy of that data. `false` leaves those objects in the object
-store with no catalog entry, where no coldfront component reclaims them, since
+store with no catalog entry, where no ColdFront component reclaims them, since
 the compactor's expiry and orphan passes walk the snapshots of a table that
 still exists. The caller states which one they mean.
 
@@ -453,7 +452,7 @@ Three properties worth knowing:
   dropped at all, and this function cannot override that: the drop carries
   `PURGE_REQUESTED` but never `force`.
 
-## ACID model
+## ACID Model
 
 (Summarizes material from [architecture.md](architecture.md) §Concurrency and
 §Known Limitations applied to the decoupled scenario.)
@@ -469,10 +468,10 @@ The table below gives the status of each ACID property in decoupled mode:
 | Isolation | **Read-your-own-write within a tx works** when the wrapper view uses `duckdb.query('SELECT * FROM ice.…')` as its read path (the helper does this by default). The plain `iceberg_scan('ice.…')` form is *not* tx-aware (it re-resolves the table from Lakekeeper each call), but pg_duckdb's planner folds `duckdb.query('SELECT * FROM ice.…')` into the same `ICEBERG_SCAN` plan with identical predicate pushdown, so the wrapper view gets tx visibility for free. Cross-call snapshot consistency is weaker than PG-native (see [Limitations](#limitations)). |
 | Durability | **Yes** - Iceberg commits are durable on the object store once Lakekeeper acknowledges. Stronger than PG WAL on local disk for many production setups. |
 
-## Concurrency / horizontal scaling - the bakery protocol
+## Concurrency / Horizontal Scaling - The Bakery Protocol
 
 Decoupled mode makes the data layer fully shared between any number of PG nodes
-pointing at the same Lakekeeper endpoint and S3 bucket.
+pointing at the same Lakekeeper endpoint and S3 bucket:
 
 - **Reads scale out trivially.** Each PG node hits Lakekeeper + S3
   independently. New nodes spin up in seconds; no data sync.
@@ -485,7 +484,7 @@ pointing at the same Lakekeeper endpoint and S3 bucket.
   and every live peer has acked (a peer defers its ack while it holds a smaller
   ticket). This stays safe under Spock's *asymmetric* apply - each node applies
   peers' rows on its own independent queue, so it never assumes a peer has
-  applied its concurrent claim; the snowflake-ticket total order and the ack
+  applied its concurrent claim; the Snowflake-ticket total order and the ack
   barrier serialize commits, not any global apply ordering. Modeled in
   [docs/formal/Bakery.tla](https://github.com/pgEdge/ColdFront/blob/main/docs/formal/Bakery.tla);
   the safety properties are verified via TLA+ (`Bakery.cfg`).
@@ -496,7 +495,7 @@ pointing at the same Lakekeeper endpoint and S3 bucket.
       deleted on release.
     - `coldfront.claim_acks` - peers insert
       `(ticket, ack_from_name, iceberg_table)` to acknowledge an originator's
-      claim, keyed by the acker's spock node name. Replicates back to the
+      claim, keyed by the acker's Spock node name. Replicates back to the
       originator, and is deleted with the claim: only the originator's own wait
       loop ever reads its acks, so a row has no reader once the claim is gone.
 
@@ -552,7 +551,7 @@ pointing at the same Lakekeeper endpoint and S3 bucket.
     node-local advisory transaction lock per Iceberg table, held across the
     whole claim + commit, so at most one same-node writer is inside the bakery
     at a time; the wait loop also requires that no same-node claim with a
-    smaller ticket exists on the table (snowflake tickets are per-node
+    smaller ticket exists on the table (Snowflake tickets are per-node
     monotonic + timestamped, so a smaller ticket means `nextval` was called
     earlier on this node).
 
@@ -627,21 +626,21 @@ pointing at the same Lakekeeper endpoint and S3 bucket.
 - **DDL replication.** Spock's `ddl_sql` repset replicates `CREATE/ALTER/DROP`
   of the wrapper view, and the `default` repset replicates the
   `coldfront.tiered_views` registry row (see
-  [Distributed setup](usage.md#distributed-setup-3-node-mesh-decoupled-mode)),
+  [Distributed Setup](usage.md#distributed-setup-3-node-mesh-decoupled-mode)),
   so one node provisions the table and replication arms every peer's hook.
 
-### Throughput characterization
+### Throughput Characterization
 
 The commit-rate ceiling sits at Lakekeeper, not at the PG side, so scale
 throughput with larger per-INSERT batches or by partitioning the Iceberg table.
 
-### Required configuration on every PG node
+### Required Configuration on Every PG Node
 
 Apply the following settings on every PG node - the server-wide settings first,
 then the per-node settings:
 
 ```ini
-# postgresql.conf — server-wide
+# postgresql.conf - server-wide
 wal_level = logical
 shared_preload_libraries = 'snowflake,spock,pg_duckdb,coldfront'
 
@@ -649,11 +648,11 @@ shared_preload_libraries = 'snowflake,spock,pg_duckdb,coldfront'
 # liveness check (PG default 10s would false-positive idle peers as dead).
 wal_receiver_status_interval = 1s
 
-# Sync-rep is NOT required by the bakery — R-A's ack barrier replaces it.
+# Sync-rep is NOT required by the bakery - R-A's ack barrier replaces it.
 ```
 
 ```ini
-# postgresql.conf — per-node. snowflake.node is any integer 1..1023, unique per
+# postgresql.conf - per-node. snowflake.node is any integer 1..1023, unique per
 # node; the value is otherwise arbitrary. The bakery matches acks by spock node
 # name (dead-peer detection joins claim_acks.ack_from_name to spock.node), so it
 # imposes no relationship between snowflake.node and the node name.
@@ -664,7 +663,7 @@ snowflake.node = 1     # node1
 # DSN of the loopback that runs the bakery's autonomous claim/ack/release statements (unix socket).
 coldfront.dblink_self = 'host=/tmp dbname=coldfront user=coldfront application_name=coldfront_dblink'
 
-# Optional — peer-liveness window for R-A's dead-peer escape; a peer
+# Optional - peer-liveness window for R-A's dead-peer escape; a peer
 # whose reply_time is older than this is treated as already-acked.
 coldfront.peer_alive_window_ms = 5000
 ```
@@ -674,9 +673,9 @@ The bakery has no peer-ack timeout knob. Dead peers are caught by the
 walsender is treated as already-acked); alive peers that haven't acked are
 either deferring legitimately or about to ack.
 
-**Per-node bootstrap** - after spock mesh setup, register the bakery tables in
-each node's default repset. Required because `spock.repset_add_table` needs the
-local spock node to exist (can't run at `CREATE EXTENSION` time):
+Per-node bootstrap - after Spock mesh setup, register the bakery tables in each
+node's default repset. Required because `spock.repset_add_table` needs the
+local Spock node to exist (can't run at `CREATE EXTENSION` time):
 
 ```sql
 -- run on every node, after spock.node_create + spock.sub_create:
@@ -693,7 +692,7 @@ receive the wrapper-view DDL via Spock's `ddl_sql` repset but do *not* re-run
 the helper - so the explicit per-node call above is mandatory in any multi-node
 setup.
 
-## When to use decoupled vs tiered
+## When to Use Decoupled vs Tiered
 
 The two modes suit different workloads; the guidance below summarizes when each
 one fits.
@@ -705,7 +704,7 @@ Decoupled (iceberg-only) is the right choice when:
   workloads).
 - Operational simplicity outweighs ergonomics: no archiver cron, no watermark,
   no autovacuum-vs-cutover lock conflict (see
-  [architecture_tiered.md → Tiered-specific limitations](architecture_tiered.md#tiered-specific-limitations)),
+  [architecture_tiered.md → Tiered-Specific Limitations](architecture_tiered.md#tiered-specific-limitations)),
   no PK rebuild after bulk load, no partition-management script.
 - You can tolerate the isolation gap (cross-query snapshot consistency). Tables
   created via `create_iceberg_table()` are queried with plain SQL through the
diff --git a/docs/architecture_tiered.md b/docs/architecture_tiered.md
index 0083f94..457bb1a 100644
--- a/docs/architecture_tiered.md
+++ b/docs/architecture_tiered.md
@@ -1,4 +1,4 @@
-# ColdFront - Tiered operating mode
+# ColdFront - Tiered Operating Mode
 
 Tiered mode keeps recent rows in the PostgreSQL heap and archives older rows to
 Apache Iceberg, presenting both as one table through a `UNION ALL` view. An
@@ -10,21 +10,7 @@ handling, infrastructure - live in [architecture.md](architecture.md); the
 all-Iceberg alternative is
 [architecture_decoupled.md](architecture_decoupled.md).
 
-## Contents
-
-This document is organized into the following sections:
-
-- [Data flow](#data-flow)
-- [Archiver Workflow](#archiver-workflow)
-- [Two-level (LIST → RANGE) tiering](#two-level-list-range-tiering)
-- [Transparent INSERT](#transparent-insert)
-- [Transparent UPDATE/DELETE](#transparent-updatedelete)
-- [Write modes: strict vs permissive](#write-modes-strict-vs-permissive-allow_mixed_writes)
-- [Tiered tables in a Spock mesh](#tiered-tables-in-a-spock-mesh)
-- [Partition Scheme Compatibility](#partition-scheme-compatibility)
-- [Tiered-specific limitations](#tiered-specific-limitations)
-
-## Data flow
+## Data Flow
 
 The following diagram shows how data moves between PostgreSQL, the Iceberg
 catalog, the object store, and the archiver:
@@ -38,7 +24,7 @@ catalog, the object store, and the archiver:
 │  ├── p_2026_04  (hot, native heap)                        │
 │  └── ...                                                  │
 │                                                           │
-│  events VIEW (replaces original table — hot + cold)       │
+│  events VIEW (replaces original table - hot + cold)       │
 │  + INSTEAD OF INSERT trigger (fallback when hook isn't    │
 │                                loaded; bypassed otherwise)│
 │  + archive_watermark table (cutoff boundary)              │
@@ -87,12 +73,12 @@ Iceberg I/O goes through `pg_duckdb` (see
 
 The archiver requires the following before its first run:
 
-1. PostgreSQL 16+ with pg_duckdb, Lakekeeper bootstrapped with a warehouse
-2. Persistent S3 secret configured (see
-   [architecture.md → Session setup](architecture.md#session-setup))
-3. An existing range-partitioned table
+- PostgreSQL 16+ with pg_duckdb, Lakekeeper bootstrapped with a warehouse
+- Persistent S3 secret configured (see
+  [architecture.md → Session Setup](architecture.md#session-setup))
+- An existing range-partitioned table
 
-### First run: conversion
+### First Run: Conversion
 
 The archiver auto-detects the partition column from `pg_get_partkeydef()` and
 column types from `information_schema.columns`.
@@ -122,7 +108,7 @@ and a cold `duckdb.raw_query` INSERT of the older rows. The view also carries
 an INSTEAD OF INSERT trigger that does the same routing; it is the fallback
 that fires only when the extension is not loaded.
 
-### The archive pipeline
+### The Archive Pipeline
 
 Candidates are tiered oldest first, ordered by partition **bound**. The order
 is a correctness contract: each cutover advances the watermark to its
@@ -142,42 +128,42 @@ only copy, so the archiver refuses the drop and fails the table.
 Each remaining partition past the hot window then moves to Iceberg through a
 six-phase pipeline:
 
-**0. Idempotent Iceberg-range wipe** - deletes any Iceberg rows already in the
-partition's range (a previous cycle may have exported without cutting over), so
-the re-export cannot duplicate rows.
+0. Idempotent Iceberg-range wipe - deletes any Iceberg rows already in the
+   partition's range (a previous cycle may have exported without cutting over),
+   so the re-export cannot duplicate rows.
 
-**1. Install capture** - installs a capture trigger and an UNLOGGED delta table
-on the partition, so writes that land during the export are recorded for
-replay.
+1. Install capture - installs a capture trigger and an UNLOGGED delta table on
+   the partition, so writes that land during the export are recorded for
+   replay.
 
-**2. Bulk export** - exports the partition PG → Iceberg under a captured
-snapshot, using the temp table bridge (see
-[architecture.md → Temp table bridge](architecture.md#temp-table-bridge-pg-iceberg))
-and a single bakery-claimed Iceberg INSERT. On the very first export, creates
-the Iceberg namespace and table.
+2. Bulk export - exports the partition PG → Iceberg under a captured snapshot,
+   using the temp table bridge (see
+   [architecture.md → Temp Table Bridge](architecture.md#temp-table-bridge-pg-iceberg))
+   and a single bakery-claimed Iceberg INSERT. On the very first export,
+   creates the Iceberg namespace and table.
 
-**3. Delta replay** - applies the delta rows the export snapshot did not see to
-Iceberg in batched commits, with no lock on the partition - concurrent writers
-keep going and keep adding to the delta.
+3. Delta replay - applies the delta rows the export snapshot did not see to
+   Iceberg in batched commits, with no lock on the partition - concurrent
+   writers keep going and keep adding to the delta.
 
-**4. Atomic cutover** (`cutover_archive`) - a single transaction updates
-`coldfront.archive_watermark` to the partition's upper bound (derived from
-`pg_catalog`, not `MAX(ts)`), takes the bakery claim on the Iceberg table,
-takes `ACCESS EXCLUSIVE` on the parent and the partition under a 100 ms
-`lock_timeout` circuit breaker, re-issues the view DDL with the new cutoff, and
-detaches the partition with a plain transactional `DETACH PARTITION` - all of
-it commits atomically or rolls back whole. On a lock timeout, phases 3-4 are
-retried (10 attempts, exponential backoff from 100 ms to 51.2 s); any other
-error fails the cycle immediately.
+4. Atomic cutover (`cutover_archive`) - a single transaction updates
+   `coldfront.archive_watermark` to the partition's upper bound (derived from
+   `pg_catalog`, not `MAX(ts)`), takes the bakery claim on the Iceberg table,
+   takes `ACCESS EXCLUSIVE` on the parent and the partition under a 100 ms
+   `lock_timeout` circuit breaker, re-issues the view DDL with the new cutoff,
+   and detaches the partition with a plain transactional `DETACH PARTITION` -
+   all of it commits atomically or rolls back whole. On a lock timeout, phases
+   3-4 are retried (10 attempts, exponential backoff from 100 ms to 51.2 s);
+   any other error fails the cycle immediately.
 
-**5. Cleanup** (`cutover_cleanup`) - drains stragglers that landed between
-phase 3's last commit and phase 4's lock, then drops the detached partition,
-the capture trigger, and the delta table.
+5. Cleanup (`cutover_cleanup`) - drains stragglers that landed between phase
+   3's last commit and phase 4's lock, then drops the detached partition, the
+   capture trigger, and the delta table.
 
-### Subsequent runs
+### Subsequent Runs
 
-Every run executes the same cycle - the conversion above is just the first
-cycle's bootstrap actually renaming the table. In order:
+Every run executes the same cycle - the conversion above is the first cycle's
+bootstrap actually renaming the table. In order:
 
 1. Create future partitions (default: 3) and self-heal the partition covering
    now
@@ -196,7 +182,7 @@ requirement on tables you bring yourself. A partition covering only part of a
 period is reported as such, naming both ranges, since PostgreSQL cannot create
 the partition that completes it.
 
-### Crash recovery
+### Crash Recovery
 
 The watermark is the single source of truth, and phase 4 is the only step that
 changes it - the watermark, view, and DETACH commit together or not at all, so
@@ -209,7 +195,7 @@ archiver recovers from a crash at each point in the pipeline:
 | During phase 4 (cutover) | The transaction rolls back whole: watermark unchanged, view unchanged, partition still attached; lock timeouts are retried in-run, anything else leaves the trigger + delta for the next cycle to retry |
 | Between phase 4 and phase 5 | The cutover is already committed (watermark, view, and DETACH all in place); the detached partition and its now-inert capture trigger + delta table are left behind for the operator to drop |
 
-## Two-level (LIST → RANGE) tiering
+## Two-Level (LIST → RANGE) Tiering
 
 A `LIST (key) → RANGE (ts)` table is tiered as **one** relation. The LIST key
 is an ordinary column in the cold tier, so every LIST value's rows land in a
@@ -222,7 +208,7 @@ re-run each cycle: every value it returns gets a LIST child and a RANGE
 sub-tree beneath it, so a newly appearing value is provisioned automatically on
 the next pass.
 
-### Period-major ordering
+### Period-Major Ordering
 
 Because the watermark is shared, the cycle is **period-major across LIST
 values**, not value-major. Past-hot leaves are grouped by their `ts` period,
@@ -243,7 +229,7 @@ cutoff crosses that period. Exporting the entire group first is what
 establishes that, and running the groups oldest first keeps the cutoff moving
 in one direction.
 
-### Scoped range wipe
+### Scoped Range Wipe
 
 Phase 0 deletes existing Iceberg rows in the range about to be exported. The
 cold tier is shared, so that delete is scoped by the LIST column and value: it
@@ -253,7 +239,7 @@ already-cold rows in the same `ts` range untouched.
 Scoping also makes re-export idempotent, so this path exports every past-hot
 leaf it finds without consulting the watermark. A leaf interrupted between the
 two passes is exported again on the next cycle. The stale-partition branch
-described under [The archive pipeline](#the-archive-pipeline) is specific to
+described under [The Archive Pipeline](#the-archive-pipeline) is specific to
 the flat path.
 
 `id` mode is not available here: the cold tier is keyed by time.
@@ -297,8 +283,8 @@ and its cost:
 The hot half is always plain set-based `INSERT INTO _events` - IDENTITY
 auto-allocates server-side, full PG speed regardless of row count.
 
-A watermark-split INSERT cannot use `RETURNING` - see
-[Tiered-specific limitations](#tiered-specific-limitations) #1.
+A watermark-split INSERT cannot use `RETURNING` - see Cold RETURNING under
+[Tiered-Specific Limitations](#tiered-specific-limitations).
 
 ## Transparent UPDATE/DELETE
 
@@ -343,12 +329,14 @@ hook handles a partition-column SET separately by the
 Before anything is archived (no cutoff) every row is hot, so a partition-column
 UPDATE is a plain hot UPDATE in either mode.
 
-## Write modes: strict vs permissive (`allow_mixed_writes`)
+## Write Modes: Strict vs Permissive (`allow_mixed_writes`)
 
 When the predicate is AMBIGUOUS the hook picks one of two behaviors from the
 `coldfront.allow_mixed_writes` GUC (USERSET, default `on`).
 
-**Permissive (`on`, default).** The hook emits a dual-tier CTE:
+### Permissive (`on`, Default)
+
+The hook emits a dual-tier CTE:
 
 ```sql
 WITH hot AS (UPDATE _events SET ... WHERE ... RETURNING *)
@@ -366,20 +354,22 @@ upload and the PG commit can leave orphaned object-storage files referenced by
 an uncommitted snapshot. Iceberg housekeeping (orphan-file expiry) reclaims
 them. Strict mode avoids this path entirely.
 
-**Strict (`off`).** The hook raises an error with a hint pointing at the
-partition column and the accepted predicate shapes; nothing is written. Use
-strict mode to guarantee every write is unambiguously attributable to one tier,
-at the cost of requiring applications to supply a tier-deterministic WHERE
-clause.
+### Strict (`off`)
+
+The hook raises an error with a hint pointing at the partition column and the
+accepted predicate shapes; nothing is written. Use strict mode to guarantee
+every write is unambiguously attributable to one tier, at the cost of requiring
+applications to supply a tier-deterministic WHERE clause.
 
-## Tiered tables in a Spock mesh
+## Tiered Tables in a Spock Mesh
 
 The bakery protocol that serializes cold writes cluster-wide is described in
 [architecture.md → Concurrency](architecture.md#concurrency-and-pgedge-spock-deployments).
 This section covers what is specific to a *tiered* table across a mesh.
 
 A tiered table provisioned on one node becomes usable on every peer, but the
-pieces arrive by different routes:
+pieces arrive by different routes. The following table shows how each
+capability reaches a peer:
 
 | Capability on a peer | How it gets there |
 |---|---|
@@ -398,7 +388,7 @@ but UPDATE/DELETE/DDL-blocking stop recognizing the view.
 Both tables are **name-keyed** - `tiered_views` by `(schema_name, relname)`,
 `archive_watermark` by `table_name` - so each row replicates verbatim and
 correct on every node, with no OID divergence to reason about. See
-[architecture.md → Registry keying](architecture.md#registry-keying-by-name-not-oid).
+[architecture.md → Registry Keying](architecture.md#registry-keying-by-name-not-oid).
 
 ## Partition Scheme Compatibility
 
@@ -406,7 +396,7 @@ The archiver tiers two partition shapes: a flat table partitioned by RANGE on a
 single time-like column, and a two-level `LIST → RANGE` tree registered with a
 sub-partition block. Anything else is rejected at archiver startup.
 
-### Supported: single-column RANGE
+### Supported: Single-Column RANGE
 
 The archiver accepts a single-column RANGE-partitioned table such as the
 following:
@@ -423,14 +413,14 @@ The partition column, primary-key columns, and any
 `GENERATED ALWAYS AS IDENTITY` columns are auto-detected from `pg_catalog` - no
 assumptions about naming or arity.
 
-### Not supported: composite partition keys
+### Not Supported: Composite Partition Keys
 
 The archiver rejects composite partition keys such as
 `PARTITION BY RANGE (tenant_id, ts)` and similar. The archiver uses a single
 scalar watermark per table; a composite key would need one watermark per
 non-time dimension value.
 
-### Supported: two-level LIST → RANGE, with a sub-partition block
+### Supported: Two-Level LIST → RANGE, with a Sub-Partition Block
 
 A table whose top level is `LIST` and whose children are themselves
 `RANGE`-partitioned by time is tiered as one relation:
@@ -461,7 +451,7 @@ sub-partition block is to register each `events_branch_N` as its own flat
 table, tiered independently. Each then becomes its own view, and applications
 query those rather than the top-level `events`.
 
-### Performance note: partition pruning after the swap
+### Performance Note: Partition Pruning After the Swap
 
 A query through the `events` view routes via pg_duckdb's takeover path
 (`iceberg_scan` is present, so pg_duckdb converts the whole query to DuckDB
@@ -480,7 +470,7 @@ SELECT * FROM _events WHERE ts = '2026-04-15';
 
 This is a read-path detail; writes are unaffected.
 
-## Cold-tier partitioning
+## Cold-Tier Partitioning
 
 The archiver creates the Iceberg table partitioned the way the hot table is:
 `month(ts)` or `day(ts)` on the time column, following `partition_period`, and
@@ -505,7 +495,7 @@ each file's `min(ts)/max(ts)` statistics prune as well. Retention DELETEs and
 the wipe are position deletes, so partitioning makes reads skip months; it does
 not make deletes cheaper.
 
-## Tiered-specific limitations
+## Tiered-Specific Limitations
 
 These are specific to the dual-tier model. Cross-cutting limitations (the
 planner-level takeover, jsonb-as-json, single-node execution, S3 compatibility,
@@ -514,38 +504,38 @@ one-time secret setup) are in
 
 The dual-tier model carries the following limitations:
 
-1. **Cold RETURNING** - any write that touches the cold tier (a cold-only
-   UPDATE/DELETE, a permissive dual-tier UPDATE/DELETE, or a watermark-split
-   INSERT) **rejects `RETURNING` with a clear error** rather than returning a
-   partial result. The cold tier genuinely cannot return affected rows:
-   duckdb-iceberg's binder refuses `RETURNING` on Iceberg writes and
-   pg_duckdb's row-returning entry point is SELECT-only. Hot-only DML keeps
-   `RETURNING` (it is plain PG DML).
-
-2. **Command tag** - an ambiguous dual-tier UPDATE returns `SELECT n` rather
-   than `UPDATE n`, because the rewrite produces a SELECT wrapper around a DML
-   CTE. The row count reflects hot rows only.
-
-3. **Self-join / multiple references** - an UPDATE/DELETE that references the
-   same tiered view more than once - a self-join
-   (`UPDATE events ... FROM events e2`), `DELETE ... USING events`, or a
-   sub-select (`... WHERE id IN (SELECT ... FROM events)`) - is rejected with a
-   clear error. The rewrite swaps only the leading result-relation reference,
-   so a second one cannot be retargeted; reference the view once.
-
-4. **Crash-safety of permissive writes** - a backend crash mid-commit can leave
-   orphaned S3 objects; see
-   [Write modes](#write-modes-strict-vs-permissive-allow_mixed_writes).
-
-5. **Partitioned tables only** - the source table must already be
-   range-partitioned.
-
-6. **Cutover blocked by autovacuum on freshly-loaded partitions** - Phase 4 of
-   `archivePartition` takes `ACCESS EXCLUSIVE` on the partition under a 100 ms
-   `lock_timeout` circuit breaker. Autovacuum's `SHARE UPDATE EXCLUSIVE` on the
-   partition conflicts with that request, so when a vacuum is running the
-   cutover fails cleanly with `ERROR: canceling statement due to lock timeout`
-   and leaves the trigger + delta in place for the next cycle to retry.
+- **Cold RETURNING** - any write that touches the cold tier (a cold-only
+  UPDATE/DELETE, a permissive dual-tier UPDATE/DELETE, or a watermark-split
+  INSERT) **rejects `RETURNING` with a clear error** rather than returning a
+  partial result. The cold tier genuinely cannot return affected rows:
+  duckdb-iceberg's binder refuses `RETURNING` on Iceberg writes and pg_duckdb's
+  row-returning entry point is SELECT-only. Hot-only DML keeps `RETURNING` (it
+  is plain PG DML).
+
+- **Command tag** - an ambiguous dual-tier UPDATE returns `SELECT n` rather
+  than `UPDATE n`, because the rewrite produces a SELECT wrapper around a DML
+  CTE. The row count reflects hot rows only.
+
+- **Self-join / multiple references** - an UPDATE/DELETE that references the
+  same tiered view more than once - a self-join
+  (`UPDATE events ... FROM events e2`), `DELETE ... USING events`, or a
+  sub-select (`... WHERE id IN (SELECT ... FROM events)`) - is rejected with a
+  clear error. The rewrite swaps only the leading result-relation reference, so
+  a second one cannot be retargeted; reference the view once.
+
+- **Crash-safety of permissive writes** - a backend crash mid-commit can leave
+  orphaned S3 objects; see
+  [Write Modes](#write-modes-strict-vs-permissive-allow_mixed_writes).
+
+- **Partitioned tables only** - the source table must already be
+  range-partitioned.
+
+- **Cutover blocked by autovacuum on freshly-loaded partitions** - Phase 4 of
+  `archivePartition` takes `ACCESS EXCLUSIVE` on the partition under a 100 ms
+  `lock_timeout` circuit breaker. Autovacuum's `SHARE UPDATE EXCLUSIVE` on the
+  partition conflicts with that request, so when a vacuum is running the
+  cutover fails cleanly with `ERROR: canceling statement due to lock timeout`
+  and leaves the trigger + delta in place for the next cycle to retry.
 
     Mitigation: disable autovacuum on the soon-to-be-archived partition
     (`ALTER TABLE <part> SET (autovacuum_enabled = false);` - the setting goes
diff --git a/docs/architecture_vectors.md b/docs/architecture_vectors.md
index c3b7f6f..9a62eb1 100644
--- a/docs/architecture_vectors.md
+++ b/docs/architecture_vectors.md
@@ -1,10 +1,10 @@
-# Vector storage architecture
+# Vector Storage Architecture
 
 Reference for maintainers. Embeddings live in the cold (Iceberg) tier as
 `list<float>`; PostgreSQL holds the hot rows, the routing centroids, and
 nothing proportional to the corpus.
 
-## Type mapping and the two column forms
+## Type Mapping and the Two Column Forms
 
 A `vector(n)` or `halfvec(n)` column maps to Iceberg `FLOAT[]`, and the tiered
 view exposes it as `real[]`, because DuckDB has no `vector` type and both arms
@@ -34,7 +34,7 @@ column per user column. Teardown drops it.
 function's expression. A hot row therefore stores its embedding twice. Cold
 rows, which are all of the data by design, do not.
 
-## The search operators
+## The Search Operators
 
 `coldfront.install_vector_ops()` creates three functions and three operators on
 `(real[], real[])` in pgvector's own schema, resolved from the catalog rather
@@ -61,7 +61,7 @@ operator resolution, and pgvector's cast function is immutable so a constant
 folds. The same cast makes an `INSERT` of a `vector` value coerce to the
 column.
 
-## Routing state
+## Routing State
 
 Two tables, both name-keyed so a Spock mesh replicates them by value and every
 node resolves a vector to the same cluster id without sharing OIDs:
@@ -72,7 +72,7 @@ node resolves a vector to the same cluster id without sharing OIDs:
 | `coldfront.vector_centroids` | the centroids themselves, keyed additionally by `(generation, centroid_id)`, with `parent_id` for an adaptive addition |
 
 Both are registered in Spock's `default` replication set by
-`coldfront._ensure_vector_state_replicated()`, gated on the spock extension so
+`coldfront._ensure_vector_state_replicated()`, gated on the Spock extension so
 vanilla is a no-op, and both are `pg_extension_config_dump`-marked: losing them
 makes every stored cluster id uninterpretable and forces a retrain.
 
@@ -90,7 +90,7 @@ order. It cannot be derived afterwards in either mode: the view exposes
 `real[]` rather than the pgvector type, and a decoupled table names its types
 without holding them.
 
-## The cluster columns, and which one owns the sort order
+## The Cluster Columns, and Which One Owns the Sort Order
 
 A table may carry several vector columns. The Iceberg schema gets one cluster
 column per vector column, `_cf_vec_list_<column>`, leading the schema in column
@@ -117,9 +117,8 @@ and the rewrite declines.
 
 `_cf_vec_list_<column> integer` exists in the Iceberg schema and nowhere else.
 It is not a column of the hot table and neither branch of the view projects it,
-so no query written against the view can name it.
-
-It **leads** the Iceberg schema. Iceberg schema evolution appends, and a cold
+so no query written against the view can name it. `_cf_vec_list_<column>`
+**leads** the Iceberg schema. Iceberg schema evolution appends, and a cold
 INSERT is positional, so a column added later has to land after everything both
 sides already agree on. Trailing the cluster column would put a user's
 `ADD COLUMN` on the far side of an internal column and silently misalign every
@@ -173,7 +172,10 @@ A retrain cannot interleave with a cold write, because an operation that
 rewrites the table holds the table's claim and every cold write serializes on
 that same claim.
 
-### The seven paths
+### The Seven Paths
+
+Every path that can put a row into a clustered table's Iceberg storage must
+derive that row's cluster assignment; these are the seven that do it, and how:
 
 | Path | Where | Shape |
 |---|---|---|
@@ -218,6 +220,9 @@ carries the literals that name its configuration row.
 
 ## Training
 
+Training computes a fresh set of centroids for one column and reassigns every
+cold row's cluster against them, through this signature:
+
 `CALL coldfront.vector_train(schema, table, column, nlist, sample, iterations)`.
 
 A `PROCEDURE`, not a function, and this is a hard requirement. pg_duckdb
@@ -354,7 +359,7 @@ row group.
 Each group is bin-packed to the file-size target, so a merge holds one group in
 memory rather than one table.
 
-## Reading: the probe
+## Reading: The Probe
 
 `cf_maybe_inject_probe` runs on the read path, alongside the hot-tier reroute
 and the jsonb normalization, and it is what makes the layout worth maintaining.
@@ -472,7 +477,7 @@ call, and the SQL layer makes no HTTP calls. The compactor reports files and
 bytes on every pass, and file count is the wrong health signal regardless: a
 merge bounds it without changing what a probe reads.
 
-## Current gaps
+## Current Gaps
 
 These are properties of the code as it stands, not plans.
 
@@ -480,7 +485,10 @@ These are properties of the code as it stands, not plans.
   in cursor order and would need buffering to sort. It is the fallback path for
   a tiered INSERT that omits an IDENTITY column.
 
-## Constraints that are correctness
+## Constraints That Are Correctness
+
+These are not implementation quirks to work around; violating any of them
+produces silently wrong results or a hard failure:
 
 - **The query vector is a literal, never a bound parameter.** A parameter typed
   `vector` fails to convert, and so does one typed `real[]`, on a custom plan
diff --git a/docs/compaction.md b/docs/compaction.md
index 06f7e23..4f36636 100644
--- a/docs/compaction.md
+++ b/docs/compaction.md
@@ -1,17 +1,16 @@
-# COMPACTOR - cold-tier table maintenance
+# COMPACTOR - Cold-Tier Table Maintenance
 
 `cmd/compactor` keeps a cold-tier Iceberg table healthy: it compacts each
 partition's small Parquet files into fewer large ones, expires old snapshots,
 and removes orphan files. ColdFront's cold tier writes one Parquet file per
 append and nothing else reclaims the resulting bloat, so without maintenance a
 busy table accumulates tens of thousands of tiny files and an unbounded
-snapshot history.
-
-It is a standalone static binary built on [apache/iceberg-go], separate from
-the archiver. Every operation that mutates a table is serialized through the
-ColdFront bakery - the same claim cold writes take - so it never conflicts
-(409s) with concurrent writers, on a single node or across a Spock mesh. It
-runs against a primary; against a read-only standby it exits with an error.
+snapshot history. The compactor is a standalone static binary built on
+[apache/iceberg-go], separate from the archiver. Every operation that mutates a
+table is serialized through the ColdFront bakery - the same claim cold writes
+take - so it never conflicts (409s) with concurrent writers, on a single node
+or across a Spock mesh. The compactor runs against a primary; against a
+read-only standby it exits with an error.
 
 [apache/iceberg-go]: https://github.com/apache/iceberg-go
 
@@ -23,8 +22,8 @@ Run the compactor against a deployment config, naming the table to maintain:
 compactor --config <yaml> --table <name> [flags]
 ```
 
-The flags below control which maintenance steps run and how aggressively each
-reclaims:
+The following table describes the flags that control which maintenance steps
+run and how aggressively each reclaims:
 
 | Flag | Default | Effect |
 |---|---|---|
@@ -52,7 +51,8 @@ cold-store stanza.
 
 ## Backends
 
-One binary serves every ColdFront cold store; configure exactly one:
+The following table lists the backends a single binary serves; configure
+exactly one:
 
 | Backend | Config |
 |---|---|
@@ -61,7 +61,7 @@ One binary serves every ColdFront cold store; configure exactly one:
 | Google Cloud Storage | `s3:` pointed at `storage.googleapis.com` with HMAC keys (S3-interop) |
 | Azure ADLS Gen2 | `azure: {connection_string}` |
 
-## How it works
+## How It Works
 
 The compactor loads the table from the Lakekeeper catalog and runs the
 requested steps, each under a bakery claim on that table:
diff --git a/docs/formal/README.md b/docs/formal/README.md
index 7e86d88..40bdaf5 100644
--- a/docs/formal/README.md
+++ b/docs/formal/README.md
@@ -1,4 +1,4 @@
-# Formal model - coldfront decoupled-mode bakery (TLA+/PlusCal)
+# Formal Model - ColdFront Decoupled-Mode Bakery (TLA+/PlusCal)
 
 This directory contains a formal model of the multi-writer Iceberg commit
 serialization protocol that lives in
@@ -20,11 +20,11 @@ an explicit applier. The following table describes its files and their roles:
 
 | File | Role |
 |---|---|
-| `Bakery.tla` | PlusCal source.  Models the real spock world: each node has its OWN local `claims[nd]` view, INSERTs propagate via an explicit `Applier`.  No `synchronous_commit = remote_apply`.  Coordination is Lamport's 1978 distributed mutual exclusion algorithm with Ricart-Agrawala's (1981) deferred-reply optimization: peers ack each claim immediately unless they have a pending claim with smaller ticket, in which case they defer the ack until they release their own claim.  Also models the `coldfront.iceberg_async_parquet` flag (constants `AsyncParquet`/`RestampPatch`): the `Stage` label stages parquet OUTSIDE the claim (async ordering); `Prepare` captures the `parent_snapshot_id` UNDER the claim (stock at stage time, patched async re-stamped at the commit POST); the `Decide` CAS asserts against it.  **Defer/drain atomicity** is modeled too (constant `SafeAcks`): the apply-time defer DECISION and its WRITE (`ApplyDecide`/`ApplyEmit`), and the release drain's FORWARD and DELETE (`DrainForward`/`DrainDelete`), are SEPARATE steps — faithful to the non-atomic SQL.  `SafeAcks=FALSE` lets them race (a deferral written behind a just-released claim is deleted unforwarded / orphaned — a dropped ack); `SafeAcks=TRUE` is the safe implementation: an atomic re-check of R-A's own defer rule against the claim, i.e. `SELECT … FOR UPDATE` on the claim row in `coldfront._on_claim_apply`.  **The orphan reaper** (constant `Reaper`): a same-node claim whose writer has crashed holds no advisory lock, so `BeginClaim` deletes it in the step that inserts its own claim; the `Applier` does the same on its defer branch under `HoldsTableLock(nd)` (a live writer holds `coldfront_iceberg:<table>` from `WaitAcks` through `DrainDelete`, because the release runs in the COMMIT callback before PostgreSQL drops the xact lock); and a `Poker` process models the waiter's periodic no-op UPDATE of its own claim row, which re-runs the peer's defer branch and is what unwedges a waiter whose peer's holder died after deferring to it. Constant `NodeRetries` restricts the `Crasher` to writers whose node still has an unstarted writer (the node is touched again); FALSE allows the crash after which only the poke reaches the node. The `Crasher` cannot split `Release`/`DrainForward`/`DrainDelete`, which are one loopback transaction in the real code. |
+| `Bakery.tla` | PlusCal source.  Models the real Spock world: each node has its OWN local `claims[nd]` view, INSERTs propagate via an explicit `Applier`.  No `synchronous_commit = remote_apply`.  Coordination is Lamport's 1978 distributed mutual exclusion algorithm with Ricart-Agrawala's (1981) deferred-reply optimization: peers ack each claim immediately unless they have a pending claim with smaller ticket, in which case they defer the ack until they release their own claim.  Also models the `coldfront.iceberg_async_parquet` flag (constants `AsyncParquet`/`RestampPatch`): the `Stage` label stages parquet OUTSIDE the claim (async ordering); `Prepare` captures the `parent_snapshot_id` UNDER the claim (stock at stage time, patched async re-stamped at the commit POST); the `Decide` CAS asserts against it.  **Defer/drain atomicity** is modeled too (constant `SafeAcks`): the apply-time defer DECISION and its WRITE (`ApplyDecide`/`ApplyEmit`), and the release drain's FORWARD and DELETE (`DrainForward`/`DrainDelete`), are SEPARATE steps - faithful to the non-atomic SQL.  `SafeAcks=FALSE` lets them race (a deferral written behind a just-released claim is deleted unforwarded / orphaned - a dropped ack); `SafeAcks=TRUE` is the safe implementation: an atomic re-check of R-A's own defer rule against the claim, i.e. `SELECT … FOR UPDATE` on the claim row in `coldfront._on_claim_apply`.  **The orphan reaper** (constant `Reaper`): a same-node claim whose writer has crashed holds no advisory lock, so `BeginClaim` deletes it in the step that inserts its own claim; the `Applier` does the same on its defer branch under `HoldsTableLock(nd)` (a live writer holds `coldfront_iceberg:<table>` from `WaitAcks` through `DrainDelete`, because the release runs in the COMMIT callback before PostgreSQL drops the xact lock); and a `Poker` process models the waiter's periodic no-op UPDATE of its own claim row, which re-runs the peer's defer branch and is what unwedges a waiter whose peer's holder died after deferring to it. Constant `NodeRetries` restricts the `Crasher` to writers whose node still has an unstarted writer (the node is touched again); FALSE allows the crash after which only the poke reaches the node. The `Crasher` cannot split `Release`/`DrainForward`/`DrainDelete`, which are one loopback transaction in the real code. |
 | `Bakery.cfg` | TLC config: 3 writers, no crashes, all four safety invariants. **Stock ordering** (`AsyncParquet=FALSE` - the default; parquet staged inside the claim).  Passes - R-A makes `NoLakekeeperConflict` and `TicketOrderPreserved` hold even with realistic asymmetric apply. |
 | `Bakery_async.cfg` | **Patched async ordering** (`AsyncParquet=TRUE, RestampPatch=TRUE`) - what the DuckDB 1.5.x (duckdb15) image runs: parquet staged outside the claim, `parent_snapshot_id` re-stamped at the commit POST under the claim by the bakery-aware patch.  All four safety invariants HOLD; the test is non-vacuous (shares the stock config's under-claim `Prepare→Decide` window, which R-A keeps empty). |
 | `Bakery_race.cfg` | **Pre-patch async race** (`AsyncParquet=TRUE, RestampPatch=FALSE`) - async ordering WITHOUT the bakery-aware patch: the stale tentative parent from the pre-claim stage is used at the POST. **`NoLakekeeperConflict` is EXPECTED to be violated** - the formal proof that the patch is mandatory for the async ordering. |
-| `Bakery_crash.cfg` | 3 writers, 1 crash budget (stock ordering - crash-safety is ordering-independent).  Safety invariants still hold (a crashed peer's missing ack just leaves surviving writers blocked at `WaitAcks` - no incorrect commits). |
+| `Bakery_crash.cfg` | 3 writers, 1 crash budget (stock ordering - crash-safety is ordering-independent).  Safety invariants still hold (a crashed peer's missing ack leaves surviving writers blocked at `WaitAcks` - no incorrect commits). |
 | `Bakery_live.cfg` | **The defer/drain race** (`SafeAcks=FALSE`) - the non-atomic implementation. **`EventualProgress` is EXPECTED to be VIOLATED**: a deferred ack written behind a just-released claim is dropped, stranding the min-ticket holder at `WaitAcks` forever - the N-writer wedge this race produces. The four safety invariants still HOLD (a dropped ack is a liveness failure, not a wrong commit). No `SYMMETRY` (unsound with liveness checking). |
 | `Bakery_fixed.cfg` | **The fix** (`SafeAcks=TRUE`) - the atomic defer/drain (`FOR UPDATE` on the claim row). `EventualProgress` HOLDS *and* all four safety invariants hold: the formal proof the fix restores liveness without weakening safety. |
 | `Bakery_samenode_race.cfg` | **Multiple cold writers per node, no same-node lock** (`NodeParts={{a1,a2},{b1}}`, `SameNodeLock=FALSE`). Two same-node claims `a1<a2` below a peer's `b1`: the node defers `b1` behind its smallest same-node claim `a1` and, on `a1`'s release, forwards the ack for `b1` without re-deferring behind `a2` (still held, still `< b1`), so `a2` and `b1` both clear the bakery. **`NoLakekeeperConflict` is EXPECTED to be violated** - the multi-writer-per-node race, reproduced in the model. |
@@ -79,8 +79,10 @@ TLC checks these properties as `PROPERTIES`:
 
 ## Running TLC
 
-Prereqs: Java 11+, TLA+ tools 1.8.0 jar at `/tmp/tla2tools.jar` (download
+The prerequisites are Java 11+ and the TLA+ tools 1.8.0 jar at
+`/tmp/tla2tools.jar` (download
 from <https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tla2tools.jar>).
+Translate the PlusCal source and run each config as follows:
 
 ```sh
 TLA=/tmp/tla2tools.jar
@@ -95,28 +97,28 @@ java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery.cfg Bakery.tla
 # b. Patched async ordering (the duckdb15 image's path).  All hold.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_async.cfg Bakery.tla
 
-# c. Pre-patch async race.  EXPECTED FAILURE: NoLakekeeperConflict violated —
+# c. Pre-patch async race.  EXPECTED FAILURE: NoLakekeeperConflict violated -
 #       the formal proof the bakery-aware patch is mandatory for the async path.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_race.cfg Bakery.tla
 
 # d. 1 crash budget.  Safety still holds (crashed peer's missing ack
-#       leaves survivors blocked at WaitAcks — no incorrect commits).
+#       leaves survivors blocked at WaitAcks - no incorrect commits).
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_crash.cfg Bakery.tla
 
 # e. Defer/drain race (SafeAcks=FALSE).  EXPECTED FAILURE: EventualProgress
-#       violated — the dropped-ack wedge reproduced in the model.
+#       violated - the dropped-ack wedge reproduced in the model.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_live.cfg Bakery.tla
 
-# f. The fix (SafeAcks=TRUE — FOR UPDATE on the claim row).  All hold:
+# f. The fix (SafeAcks=TRUE - FOR UPDATE on the claim row).  All hold:
 #       EventualProgress AND the four safety invariants.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_fixed.cfg Bakery.tla
 
 # g. Multiple cold writers per node, NO same-node lock (SameNodeLock=FALSE).
-#      EXPECTED to violate NoLakekeeperConflict — the multi-writer-per-node race.
+#      EXPECTED to violate NoLakekeeperConflict - the multi-writer-per-node race.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_samenode_race.cfg Bakery.tla
 
 # h. Same topology WITH the node-local advisory lock (SameNodeLock=TRUE).
-#      All four safety invariants HOLD — the lock restores safety.
+#      All four safety invariants HOLD - the lock restores safety.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_samenode.cfg Bakery.tla
 
 # i. Orphan-claim wedge, reaper OFF (Reaper=FALSE, 1 crash).  EXPECTED FAILURE:
@@ -148,12 +150,12 @@ with a crash a live writer can be stuck in `WaitAcks` forever waiting for the
 orphan ticket. We want TLC to report this as a `EventualProgress` violation,
 not as `Deadlock reached`.
 
-## Expected outputs
+## Expected Outputs
 
 This section records the expected TLC result for each config, so a reviewer can
 confirm a run matches the known-good output.
 
-### `Bakery.cfg` (stock ordering)
+### `Bakery.cfg` (Stock Ordering)
 
 The stock-ordering config reports a clean check with the following output:
 
@@ -166,7 +168,7 @@ All four safety invariants hold for the stock ordering (parquet staged inside
 the claim; parent stamped under the claim). R-A makes `NoLakekeeperConflict`
 and `TicketOrderPreserved` hold despite asymmetric Spock apply.
 
-### `Bakery_async.cfg` (patched async ordering)
+### `Bakery_async.cfg` (Patched Async Ordering)
 
 The patched-async config reports a clean check with the following output:
 
@@ -182,7 +184,7 @@ hold. The check is non-vacuous: it shares the stock config's under-claim
 defers its ack until it releases, so two writers never both clear `WaitAcks`).
 This is the ordering the DuckDB 1.5.x (duckdb15) image runs.
 
-### `Bakery_race.cfg` (pre-patch async - EXPECTED FAILURE)
+### `Bakery_race.cfg` (Pre-Patch Async - EXPECTED FAILURE)
 
 The pre-patch async config is expected to fail the check, reporting the
 following output:
@@ -193,18 +195,18 @@ Error: Invariant NoLakekeeperConflict is violated.
 2898 states generated, 891 distinct states found, 44 states left on queue.
 ```
 
-**Failure expected.** With the async ordering but WITHOUT the bakery-aware
-patch (`RestampPatch=FALSE`), a writer asserts the CAS against the stale
-tentative parent it captured at the pre-claim stage; a peer that committed
-while it awaited/held the claim has advanced the iceberg head, so the CAS
-mismatches → Lakekeeper 409. This is the formal proof that the patch is
-mandatory for the async ordering - the stock ordering (`Bakery.cfg`) stamps the
-parent under the claim and needs no patch. (The asymmetric-apply race that
-motivates R-A itself - two writers passing a naive local min-check on stale
-views - is structurally prevented by the R-A ack barrier in this model, so it
-has no standalone config.)
+Failure expected. With the async ordering but WITHOUT the bakery-aware patch
+(`RestampPatch=FALSE`), a writer asserts the CAS against the stale tentative
+parent it captured at the pre-claim stage; a peer that committed while it
+awaited/held the claim has advanced the iceberg head, so the CAS mismatches →
+Lakekeeper 409. This is the formal proof that the patch is mandatory for the
+async ordering - the stock ordering (`Bakery.cfg`) stamps the parent under the
+claim and needs no patch. (The asymmetric-apply race that motivates R-A
+itself - two writers passing a naive local min-check on stale views - is
+structurally prevented by the R-A ack barrier in this model, so it has no
+standalone config.)
 
-### `Bakery_samenode_race.cfg` (multi-writer-per-node - EXPECTED FAILURE)
+### `Bakery_samenode_race.cfg` (Multi-Writer-Per-Node - EXPECTED FAILURE)
 
 The no-same-node-lock config is expected to fail the check, reporting the
 following output:
@@ -215,7 +217,7 @@ Error: Invariant NoLakekeeperConflict is violated.
 62256 states generated, 20448 distinct states found, 2595 states left on queue.
 ```
 
-**Failure expected.** With two cold writers `a1 < a2` on one node and `b1` on a
+Failure expected. With two cold writers `a1 < a2` on one node and `b1` on a
 peer (`NodeParts={{a1,a2},{b1}}`, `SameNodeLock=FALSE`), the node defers `b1`
 behind its smallest same-node claim `a1`; when `a1` releases, it forwards the
 ack for `b1` without re-deferring behind `a2` (still held, still `< b1`). So
@@ -224,7 +226,7 @@ clear the bakery and race the CAS → Lakekeeper 409. This reproduces the
 multi-writer-per-node race in the model, isolated from the async race
 (`AsyncParquet=FALSE`) and the ack-atomicity race (`SafeAcks=TRUE`).
 
-### `Bakery_samenode.cfg` (node-local lock)
+### `Bakery_samenode.cfg` (Node-Local Lock)
 
 The same-node-lock config reports a clean check with the following output:
 
@@ -240,7 +242,7 @@ still holds; the topology collapses to one active claim per node and all four
 safety invariants hold. This is the formal proof that the node-local lock is
 mandatory for multi-writer-per-node cold writes.
 
-## Model fidelity
+## Model Fidelity
 
 The model is a *protocol-level* abstraction. The following are represented
 faithfully because they affect protocol correctness:
@@ -262,7 +264,7 @@ faithfully because they affect protocol correctness:
 - pg_duckdb's iceberg ROLLBACK on PG ABORT (no append on the rollback branch) -
   required for the `RollbackNoIceberg` property to hold.
 
-### Compactor commits (`cmd/compactor`)
+### Compactor Commits (`cmd/compactor`)
 
 The Go compactor (`cmd/compactor`, apache/iceberg-go) is a bakery claimant
 **indistinguishable from a cold writer at the protocol level**: it acquires a
@@ -270,19 +272,19 @@ claim via `_claim_iceberg_lock` on the node it connects to, captures the parent
 snapshot under the held claim, issues one Lakekeeper CAS POST - a *replace*
 (`RewriteDataFiles`: drop small data files, add the rewritten one), which has
 the same parent-CAS conflict shape as the append modeled at `Decide` - then
-releases. It adds no new protocol primitive, so it is covered by the existing
-proof as the **stock-ordering writer** (`AsyncParquet = FALSE`, `Bakery.cfg`).
-
-Its two maintenance operations are the **same claimant**, so they need no new
-model: **`ExpireSnapshots`** issues another CAS commit (drop old snapshots -
-identical conflict shape) under the held claim, covered exactly like
-`RewriteDataFiles`; **`DeleteOrphanFiles`** holds the claim but makes **no
-Lakekeeper commit** (it only deletes unreferenced files), so it cannot cause a
-catalog conflict at all - strictly weaker than a committing claimant, hence
-trivially within `NoLakekeeperConflict`. All three reuse the existing
-`coldfront._claim_iceberg_external` and are covered by the existing model and
-configs; no dedicated config is needed. (Lakekeeper itself does no Iceberg
-snapshot/orphan maintenance - it is a catalog - so this is the go-native path.)
+releases. The compactor adds no new protocol primitive, so it is covered by the
+existing proof as the **stock-ordering writer** (`AsyncParquet = FALSE`,
+`Bakery.cfg`). The compactor's two maintenance operations are the **same
+claimant**, so they need no new model: **`ExpireSnapshots`** issues another CAS
+commit (drop old snapshots - identical conflict shape) under the held claim,
+covered exactly like `RewriteDataFiles`; **`DeleteOrphanFiles`** holds the
+claim but makes **no Lakekeeper commit** (it only deletes unreferenced files),
+so it cannot cause a catalog conflict at all - strictly weaker than a
+committing claimant, hence trivially within `NoLakekeeperConflict`. All three
+reuse the existing `coldfront._claim_iceberg_external` and are covered by the
+existing model and configs; no dedicated config is needed. (Lakekeeper itself
+does no Iceberg snapshot/orphan maintenance - it is a catalog - so this is the
+go-native path.)
 
 Binding constraint: iceberg-go carries **no bakery-aware re-stamp patch** (that
 patch lives only in the duckdb-iceberg commit path), so the compactor MUST hold
@@ -293,13 +295,13 @@ Commit-then-release matches the cold-write shape the model already abstracts as
 the atomic `Decide` step (commit iceberg, then DELETE the claim), so the
 existing configs cover it; no dedicated config is needed.
 
-### DDL mirroring (`ALTER TABLE`)
+### DDL Mirroring (`ALTER TABLE`)
 
 Tiered-table column DDL (ADD/DROP/ALTER-TYPE/RENAME COLUMN) is mirrored onto
 the shared Iceberg tier by `coldfront._mirror_iceberg_alter`, which routes the
-Iceberg ALTER through the **unchanged** `_exec_iceberg_with_claim`. It is
-therefore the **same stock-ordering claimant** the cold writer is: one
-metadata-only CAS commit (the schema change - identical parent-CAS conflict
+Iceberg ALTER through the **unchanged** `_exec_iceberg_with_claim`. The mirror
+function is therefore the **same stock-ordering claimant** the cold writer is:
+one metadata-only CAS commit (the schema change - identical parent-CAS conflict
 shape to the append modeled at `Decide`) under the held claim, then release. It
 forces the claim-first ordering
 (`SET LOCAL coldfront.iceberg_async_parquet = off`): an ALTER stages no
@@ -315,7 +317,7 @@ evolved by the originator. The single-commit shape thus holds - the catalog is
 altered exactly once, by one claimant - and peers only rebuild their per-node
 view.
 
-### Cross-tier move (partition-column UPDATE)
+### Cross-Tier Move (Partition-Column UPDATE)
 
 A partition-column `UPDATE` that crosses the cutoff is rewritten to
 `coldfront._cross_tier_move`, which relocates rows between tiers. Its hot-tier
@@ -335,7 +337,7 @@ min-ticket gate), so the move never holds two tickets. It adds no new protocol
 primitive, so it is covered by the existing model and configs; no dedicated
 config is needed.
 
-### Partition detach fan-out
+### Partition Detach Fan-Out
 
 The retention path detaches expired partitions with
 `DETACH PARTITION … CONCURRENTLY`, which Spock cannot replicate (it is
@@ -350,7 +352,7 @@ cutover *does* commit to Iceberg under a claim, but its detach is a plain
 transactional `DETACH` that Spock replicates on its own - it is the
 already-modeled stock-ordering writer, not a new primitive.)
 
-### Known abstractions (model deviates from reality)
+### Known Abstractions (Model Deviates from Reality)
 
 These are the points where the model deliberately deviates from runtime
 reality:
@@ -394,9 +396,9 @@ interchangeable under `NodeParts`); the other configs declare it.
 The model is small enough that larger bounds are interesting only if a
 regression is suspected.
 
-## When to re-run
+## When to Re-Run
 
-Re-run the model whenever the protocol it abstracts is touched. Any change to:
+Re-run the model after any change to the following:
 
 - The bakery functions in `extension/coldfront/coldfront--1.0.sql`
   (`_claim_iceberg_lock`, `_insert_claim`, `_take_iceberg_claim`,
@@ -417,7 +419,7 @@ coordination primitive), update the PlusCal source first, re-translate,
 re-check. CI integration is a future task; for now, running the configs by hand
 is the workflow.
 
-## Future work
+## Future Work
 
 The following extensions to the model and its tooling are planned:
 
diff --git a/docs/index.md b/docs/index.md
index e40927c..c7a2254 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -90,20 +90,20 @@ SELECT count(*) FROM events;
 A table that already exists in the Iceberg catalog is adopted rather than
 created: `coldfront.adopt_iceberg_table()` reads its schema from the catalog
 and gives it the same wrapper view and registry row, read-only unless writes
-are asked for. `coldfront.release_iceberg_table()` hands it back with the
-Iceberg table untouched. See
-[Adopting a table that already exists in the catalog](usage.md#adopting-a-table-that-already-exists-in-the-catalog).
+are asked for. `coldfront.release_iceberg_table()` hands the table back with
+the Iceberg table untouched. See
+[Adopting a Table That Already Exists in the Catalog](usage.md#adopting-a-table-that-already-exists-in-the-catalog).
 
 To remove a table again, `coldfront.drop_iceberg_table()` unregisters it and
 drops the Iceberg table, deleting the stored objects only when asked to. See
-[Dropping an Iceberg table](usage.md#dropping-an-iceberg-table-both-modes).
+[Dropping an Iceberg Table](usage.md#dropping-an-iceberg-table-both-modes).
 
 For compliance environments that cannot store an object-store credential,
 `coldfront.set_storage_secret_vended()` runs with no credential in the
 database: Lakekeeper issues short-lived per-table credentials at access time.
-See [Vended credentials](usage.md#vended-credentials).
+See [Vended Credentials](usage.md#vended-credentials).
 
-## Least-privilege application roles
+## Least-Privilege Application Roles
 
 Application roles need no superuser and no server-file access, yet they read
 and write the cold tier through the same transparent view. Onboarding an
diff --git a/docs/installation.md b/docs/installation.md
index 487fc71..ba9b78c 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,4 +1,4 @@
-# Building ColdFront from source
+# Building ColdFront from Source
 
 > **Most users should install from packages** - see
 > [Installation](https://github.com/pgEdge/ColdFront/blob/main/README.md#installation)
@@ -15,7 +15,7 @@ column in UTC. No released pg_duckdb tag carries DuckDB 1.5.x yet, so the stack
 is built from a pinned upstream PR plus our patches - all from sources you can
 fetch.
 
-## What gets built
+## What Gets Built
 
 `docker/Dockerfile.duckdb15-base` is the recipe; it fetches the requirements,
 applies our patches, and compiles the following components:
@@ -53,7 +53,7 @@ source pin and compile step - is
 [`docker/Dockerfile.duckdb15-base`](https://github.com/pgEdge/ColdFront/blob/main/docker/Dockerfile.duckdb15-base)
 itself.
 
-## Build the image (Docker)
+## Build the Image (Docker)
 
 Build the stack in two stages, the prebuilt base and the thin app layer:
 
@@ -66,10 +66,10 @@ git clone <coldfront-repo> && cd coldfront
 docker build -f docker/Dockerfile.duckdb15-base --build-arg PG_MAJOR=18 \
   -t ghcr.io/pgedge/coldfront-duckdb-base:pg18 .
 
-# 2. Build the thin coldfront app layer + bring up the stack (seconds — it only
+# 2. Build the thin coldfront app layer + bring up the stack (seconds - it only
 #    compiles the coldfront extension on top of the base).
 docker compose up -d --build      # end-user single-node stack (ports published)
-# (CI uses docker-compose.matrix.yml / docker-compose.mesh.yml — NOT for end-user setup)
+# (CI uses docker-compose.matrix.yml / docker-compose.mesh.yml - NOT for end-user setup)
 ```
 
 The split keeps app builds fast and always testing current source: the
@@ -77,8 +77,8 @@ expensive, stable compiles (pg_duckdb 1.5.4 + the patched duckdb-iceberg) live
 in the prebuilt **base**, published to
 `ghcr.io/pgedge/coldfront-duckdb-base:pg{16,17,18}`; the **app** build
 ([`docker/Dockerfile.duckdb15`](https://github.com/pgEdge/ColdFront/blob/main/docker/Dockerfile.duckdb15))
-just `FROM`s it and compiles the coldfront extension in seconds. If you build
-the base yourself (step 1) the app layer `FROM`s your local image; otherwise it
+`FROM`s it and compiles the coldfront extension in seconds. If you build the
+base yourself (step 1) the app layer `FROM`s your local image; otherwise it
 `FROM`s the published `ghcr.io/pgedge/coldfront-duckdb-base:pg<major>`. Rebuild
 the published base via the
 [base-image workflow](https://github.com/pgEdge/ColdFront/blob/main/.github/workflows/base-image.yml)
@@ -88,11 +88,11 @@ covers the base Dockerfile and the files it copies in, and stops before the app
 build if that tag is not published, naming the command that publishes it. The
 floating `pg<major>` tag moves to the same image once the change is on `main`.
 
-Then follow [usage.md → One-time setup](usage.md#one-time-setup) (bootstrap
+Then follow [usage.md → One-Time Setup](usage.md#one-time-setup) (bootstrap
 Lakekeeper → create a table → tier → verify).
 
 > **pg_duckdb pin.** The base pins pg_duckdb to the merged PR #1025 commit
-> `c04e6a2` (DuckDB 1.5.4 — its duckdb submodule is the v1.5.4 tag), a fixed
+> `c04e6a2` (DuckDB 1.5.4 - its duckdb submodule is the v1.5.4 tag), a fixed
 > commit for reproducible builds rather than a moving PR head.
 >
 > **Base foundation.** The base is
@@ -100,7 +100,7 @@ Lakekeeper → create a table → tier → verify).
 > access to that image (or substitute an equivalent PostgreSQL base with the
 > same layout).
 
-## Verify the build
+## Verify the Build
 
 A self-contained smoke test confirms the freshly built stack works end to end:
 pg_duckdb, the patched duckdb-iceberg, Lakekeeper, and the object store. The
@@ -154,10 +154,10 @@ SQL
 
 A row count of 1 read back through Iceberg confirms the full path. For a real
 cloud store, drop the `local-store` profile, point the warehouse at your own
-bucket, and follow [usage.md → One-time setup](usage.md#one-time-setup) for the
+bucket, and follow [usage.md → One-Time Setup](usage.md#one-time-setup) for the
 full tier-and-verify journey.
 
-## Build prerequisites
+## Build Prerequisites
 
 The following table lists the prerequisites for each build path:
 
@@ -167,7 +167,7 @@ The following table lists the prerequisites for each build path:
 | The archiver (all paths) | Go 1.26.5+ (pinned in [go.mod](https://github.com/pgEdge/ColdFront/blob/main/go.mod)), `make` (`make build` → `./bin/archiver`) |
 | Bare metal (below) | `pg_config`, PostgreSQL server dev headers, libpq client headers/library (libpq-dev / libpq-devel), `make`, `gcc` |
 
-## Bare metal (no Docker)
+## Bare Metal (No Docker)
 
 The coldfront extension is a standard PGXS C extension:
 
@@ -203,7 +203,7 @@ built on the prebuilt
 [base](https://github.com/pgEdge/ColdFront/blob/main/docker/Dockerfile.duckdb15-base);
 `--build-arg PG_MAJOR=16|17|18`).
 
-### Pre-commit gate
+### Pre-Commit Gate
 
 `./run-ci-local.sh` runs `ci/matrix.sh --quick`: gofmt, golangci-lint, unit
 tests, build, the pg_regress unit layer, and the full journey on one
@@ -213,7 +213,7 @@ GitHub Actions
 runs the identical `ci/matrix.sh` harness - `--quick` on every push/PR,
 `--full` nightly and on demand - so local and CI never diverge.
 
-### Full matrix
+### Full Matrix
 
 `ci/matrix.sh --full`, the beta gate: PG {16, 17, 18} × {vanilla, mesh (3-node
 Spock)} × {tiered, decoupled} × {primary, standby} × {s3, aws, azure, gcs}. The
@@ -222,7 +222,7 @@ visibility via the shared Lakekeeper catalog, the R-A bakery serializing
 concurrent cold writers (same-node and cross-node) with no 409, and an N×(N-1)
 probe that the bakery's `coldfront.claims` table replicates in every direction.
 
-### Storage-backend gating
+### Storage-Backend Gating
 
 The same policy applies locally and in GitHub CI: the hermetic
 **SeaweedFS-as-S3** backend (`s3`) always runs - that is the default coverage
diff --git a/docs/object_store.md b/docs/object_store.md
index ab3f6d7..e912000 100644
--- a/docs/object_store.md
+++ b/docs/object_store.md
@@ -1,4 +1,4 @@
-# Get ColdFront running on S3
+# Get ColdFront Running on S3
 
 This walkthrough takes you from an empty S3 bucket to a working ColdFront cold
 tier in one sitting. You stand up the ColdFront stack (PostgreSQL + the
@@ -8,7 +8,7 @@ Postgres.
 
 It targets a real cloud S3 service that uses virtual-hosted addressing. For a
 path-style S3-compatible store (MinIO, SeaweedFS) or GCS, see
-[usage.md → Storage backends](usage.md#storage-backends) instead.
+[usage.md → Storage Backends](usage.md#storage-backends) instead.
 
 No prior ColdFront knowledge assumed. Copy-paste top to bottom. Placeholders
 used throughout: bucket `my-iceberg-bucket`, region `eu-west-1`, key
@@ -60,7 +60,7 @@ Before you begin, gather the following:
 
 ---
 
-## 2. Bring up the stack (Postgres + Lakekeeper)
+## 2. Bring Up the Stack (Postgres + Lakekeeper)
 
 Start the stack from the repo root with a single Compose command:
 
@@ -72,7 +72,8 @@ This starts **Postgres** (with `pg_duckdb` and `coldfront` preloaded),
 **Lakekeeper** (the Iceberg REST catalog), Lakekeeper's **own catalog
 Postgres**, and a one-shot **migrate** job. It does **not** start the bundled
 SeaweedFS - that is gated behind the `local-store` profile for credential-free
-local eval. For cloud S3 you talk to the bucket directly, so you don't need it.
+local eval. For cloud S3 you talk to the bucket directly, so you don't need the
+bundled SeaweedFS.
 
 If a local Postgres already owns port 5432, pick another host port:
 
@@ -89,7 +90,7 @@ docker inspect -f '{{.State.Health.Status}}' "$(docker compose ps -q db)"   # =>
 
 ---
 
-## 3. One-time Lakekeeper setup
+## 3. One-Time Lakekeeper Setup
 
 Run the following three calls once each.
 
@@ -103,7 +104,7 @@ curl -X POST http://localhost:8181/management/v1/bootstrap \
   -d '{"accept-terms-of-use":true}'
 ```
 
-### 3b. Create the S3 warehouse
+### 3b. Create the S3 Warehouse
 
 A warehouse tells Lakekeeper where on S3 your Iceberg tables live and which
 credential to use. This is the **virtual-hosted cloud-S3** profile - these
@@ -144,20 +145,20 @@ curl -X POST http://localhost:8181/management/v1/warehouse \
 # => HTTP 201
 ```
 
-The `key-prefix` is an arbitrary path inside the bucket. `coldfront` is just an
+The `key-prefix` is an arbitrary path inside the bucket. `coldfront` is only an
 example.
 
-**Vended-credentials variant.** To run ColdFront with no stored credential
+Vended-credentials variant. To run ColdFront with no stored credential
 ([usage.md](usage.md#vended-credentials)), the warehouse issues per-table STS
 credentials instead of handing the client a static key. Two things change from
 the warehouse above.
 
-First, create an IAM role scoped to the bucket. Lakekeeper assumes it per table
-and vends the resulting short-lived key, secret, and session token to
+First, create an IAM role scoped to the bucket. Lakekeeper assumes the role per
+table and vends the resulting short-lived key, secret, and session token to
 ColdFront. Its permission policy grants `GetObject` / `PutObject` /
 `DeleteObject` / `ListBucket` (plus the multipart actions) on the bucket and
 `arn:aws:s3:::my-iceberg-bucket/*`. Its trust policy lets the warehouse
-credential's own IAM identity assume it, gated by an `ExternalId` that
+credential's own IAM identity assume the role, gated by an `ExternalId` that
 Lakekeeper must present (confused-deputy protection):
 
 ```json
@@ -194,14 +195,14 @@ in the warehouse and in the role's trust condition must match. On the database
 side, replace the `set_storage_secret(...)` call in Section 4 with
 `SELECT coldfront.set_storage_secret_vended();`.
 
-### 3c. Pre-create the `public` namespace
+### 3c. Pre-Create the `public` Namespace
 
 Resolve the warehouse id, then create the `public` namespace under it:
 
 ```bash
 WID=$(curl -s http://localhost:8181/management/v1/warehouse \
   | grep -oE '"warehouse-id":"[^"]+"' | head -1 | cut -d'"' -f4)
-[ -n "$WID" ] || { echo "no warehouse id — did step 3b return 201?"; exit 1; }
+[ -n "$WID" ] || { echo "no warehouse id - did step 3b return 201?"; exit 1; }
 
 curl -X POST "http://localhost:8181/catalog/v1/$WID/namespaces" \
   -H "Content-Type: application/json" \
@@ -218,7 +219,7 @@ curl -X POST "http://localhost:8181/catalog/v1/$WID/namespaces" \
 
 ---
 
-## 4. Database setup
+## 4. Database Setup
 
 Open psql inside the Postgres container:
 
@@ -232,7 +233,7 @@ Create both extensions in your database:
 CREATE EXTENSION IF NOT EXISTS pg_duckdb;
 CREATE EXTENSION IF NOT EXISTS coldfront;
 -- duckdb.install_extension('iceberg') is harmless but NOT needed on the ColdFront
--- image — the patched iceberg extension ships preplaced and autoloads on ATTACH.
+-- image - the patched iceberg extension ships preplaced and autoloads on ATTACH.
 ```
 
 > **`CREATE EXTENSION coldfront` is required and easy to miss.** The image
@@ -257,7 +258,7 @@ SELECT coldfront.set_storage_secret('AKIAEXAMPLE...', '<your-secret-key>', NULL,
 
 ---
 
-## 5. Fastest demo - decoupled mode (the table lives entirely in S3)
+## 5. Fastest Demo - Decoupled Mode (The Table Lives Entirely in S3)
 
 A decoupled (iceberg-only) table has no Postgres hot tier; every row lives in
 Iceberg on S3, and you read and write it through a normal-looking Postgres
@@ -283,7 +284,7 @@ SELECT count(*) AS n, max(note) AS last FROM public.s3_demo;
 That `count(*) = 2` is read back through `iceberg_scan` from your real S3
 bucket - the round trip is complete.
 
-### Tiered mode - the headline feature
+### Tiered Mode - The Headline Feature
 
 Decoupled mode is the warm-up. ColdFront's real purpose is **tiered** tables: a
 partitioned Postgres table whose hot partitions automatically age out to
@@ -291,15 +292,15 @@ Iceberg on S3 once they pass a retention window, after which reads
 transparently union live Postgres data with cold S3 data and writes route to
 the correct tier.
 
-You drive it with the `archiver` binary against a small YAML config (Postgres
-DSN, the `wh` warehouse, your S3 region/keys); each table's lifecycle is
-registered with `archiver register`. The credential and warehouse you set up
+You drive tiered tables with the `archiver` binary against a small YAML config
+(Postgres DSN, the `wh` warehouse, your S3 region/keys); each table's lifecycle
+is registered with `archiver register`. The credential and warehouse you set up
 above are exactly what it needs. See [usage.md](usage.md) for the archiver
 config and the partition CLI.
 
 ---
 
-## 6. Verify in S3 and troubleshoot
+## 6. Verify in S3 and Troubleshoot
 
 Confirm objects physically landed (an S3 client such as the `aws` CLI, region
 exported):
@@ -316,12 +317,12 @@ did `s3_demo` go?" → look under the UUID path beneath your `key-prefix`.
 
 Work through this checklist if something failed:
 
-1. **`CREATE EXTENSION coldfront`** - ran it once in your database? Preloading
-   is not the same as creating the extension. Symptom:
-   `schema "coldfront" does not exist`.
-2. **`set_storage_secret(..., NULL, 'eu-west-1')`** - 3rd arg `NULL` (native
-   vhost+HTTPS), 4th arg your real region? A non-NULL endpoint forces
-   path-style and breaks modern Regions (HTTP 400).
-3. **Namespace `public` pre-created** in Lakekeeper before
-   `create_iceberg_table`? Without it the decoupled create 404s.
-4. **Long-term key** - not an SSO / temporary session-token credential.
+- **`CREATE EXTENSION coldfront`** - ran it once in your database? Preloading
+  is not the same as creating the extension. Symptom:
+  `schema "coldfront" does not exist`.
+- **`set_storage_secret(..., NULL, 'eu-west-1')`** - 3rd arg `NULL` (native
+  vhost+HTTPS), 4th arg your real region? A non-NULL endpoint forces path-style
+  and breaks modern Regions (HTTP 400).
+- **Namespace `public` pre-created** in Lakekeeper before
+  `create_iceberg_table`? Without it the decoupled create 404s.
+- **Long-term key** - not an SSO / temporary session-token credential.
diff --git a/docs/usage.md b/docs/usage.md
index cc249fd..03a0495 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -1,4 +1,4 @@
-# Using coldfront
+# Using ColdFront
 
 ColdFront offers two operating modes. Pick one per table; both can coexist in
 the same database. The two modes compare as follows:
@@ -13,14 +13,13 @@ the same database. The two modes compare as follows:
 Once the table exists, **the SQL surface is identical**: `SELECT`, `INSERT`,
 `UPDATE`, `DELETE` all work normally against the relation name (e.g. `events`).
 
-## Prerequisites (both modes)
+## Prerequisites (Both Modes)
 
-The stack must already be running as three services: PostgreSQL with the
-pg_duckdb and coldfront extensions, Lakekeeper, and any S3-compatible object
-store (SeaweedFS, MinIO, GCS, etc.). The one-time setup below brings it up and
-bootstraps it.
+The setup needs three services: PostgreSQL with the pg_duckdb and coldfront
+extensions, Lakekeeper, and any S3-compatible object store (SeaweedFS, MinIO,
+GCS, etc.). The one-time setup below brings them up and bootstraps them.
 
-## One-time setup
+## One-Time Setup
 
 Bring up the end-user stack (the example uses SeaweedFS, gated behind the
 `local-store` compose profile; host ports are published so the `localhost`
@@ -58,8 +57,8 @@ curl -X POST http://localhost:8181/management/v1/warehouse \
 # 3. Create the Iceberg namespace in the new warehouse.
 #    REQUIRED for decoupled (iceberg-only) mode: the Iceberg CREATE SCHEMA is
 #    deferred to transaction COMMIT but CREATE TABLE is POSTed eagerly, so
-#    coldfront.create_iceberg_table — which runs both in one
-#    transaction — would 404 against a cold warehouse. Pre-creating the
+#    coldfront.create_iceberg_table - which runs both in one
+#    transaction - would 404 against a cold warehouse. Pre-creating the
 #    namespace here (its own committed REST call) makes the function's in-txn
 #    CREATE SCHEMA IF NOT EXISTS a no-op so the table create succeeds. The
 #    archiver (tiered mode) creates the namespace itself and does not need this.
@@ -88,7 +87,7 @@ query that touches a tiered/decoupled view (read or write).
 
 For a real cloud-S3 setup, see [object_store.md](object_store.md).
 
-## Mode 1 - Tiered (hot + cold)
+## Mode 1 - Tiered (Hot + Cold)
 
 Create a partitioned table normally:
 
@@ -131,7 +130,7 @@ and registers it. From then on every cycle (1) tiers partitions older than
 lifecycle is **hot → `hot_period` → cold → `retention_period` → gone**; omit
 `retention_period` to keep cold data forever.
 
-### Inbound foreign keys
+### Inbound Foreign Keys
 
 A tiered table cannot be the target of an enforced foreign key from another
 table over its archivable range. Archiving physically removes the rows from
@@ -155,7 +154,7 @@ ALTER TABLE event_logs DROP CONSTRAINT event_logs_events_fkey;
 Better still, do not point an enforced foreign key at a tiered table over its
 archivable range in the first place.
 
-### 2-level (LIST → RANGE) tiered tables
+### 2-Level (LIST → RANGE) Tiered Tables
 
 A table partitioned `LIST (region) → RANGE (ts)` can be tiered too - the same
 `sub_partition` block as the standalone partition manager (Mode 3), so a
@@ -164,7 +163,7 @@ archiver at it:
 
 ```yaml
     - source_table: regional
-      partition_column: ts          # the RANGE (time) column — required for 2-level
+      partition_column: ts          # the RANGE (time) column - required for 2-level
       partition_period: monthly
       hot_period: 1 month
       # retention_period: 5 years   # optional cold expiry (region-agnostic, by ts)
@@ -172,14 +171,14 @@ archiver at it:
         values_source: "SELECT region FROM regions"
 ```
 
-One Iceberg table holds every region (region is just a column); the archiver
-tiers leaves a whole `ts` period at a time across **all** regions before
-advancing the shared hot/cold watermark, so a period only becomes cold once it
-is cold for every region. `id` mode is not supported in tiered mode (the cold
-tier is time-keyed). For why the ordering works that way, see
+One Iceberg table holds every region (region is an ordinary column); the
+archiver tiers leaves a whole `ts` period at a time across **all** regions
+before advancing the shared hot/cold watermark, so a period only becomes cold
+once it is cold for every region. `id` mode is not supported in tiered mode
+(the cold tier is time-keyed). For why the ordering works that way, see
 [architecture_tiered.md → Two-level tiering](architecture_tiered.md#two-level-list-range-tiering).
 
-## Mode 2 - Decoupled (iceberg-only)
+## Mode 2 - Decoupled (Iceberg-Only)
 
 Single call:
 
@@ -213,17 +212,19 @@ That single statement provisions:
 
 - `ice.public.events` on the attached Iceberg catalog.
 - a PG-side wrapper view `public.events` with proper PG-typed columns.
+
 - a `coldfront.tiered_views` registry row - every INSERT, UPDATE, and DELETE on
   the view is intercepted by the coldfront C hook and rewritten to a single
   `duckdb.raw_query(...)` against `ice.public.events`.
 
+
 In a mesh one node provisions: Spock's `ddl_sql` repset replicates the
 `CREATE VIEW`, and the `default` repset replicates the name-keyed registry row,
 which arms the write hook on every peer. Each node also needs the bakery armed
 via `coldfront._ensure_claims_replicated()` - see the one-time mesh setup
 below.
 
-### Adopting a table that already exists in the catalog
+### Adopting a Table That Already Exists in the Catalog
 
 A table another engine wrote needs no provisioning, only a wrapper view and a
 registry row. `coldfront.adopt_iceberg_table()` reads the schema from the
@@ -281,7 +282,7 @@ collide at Lakekeeper.
 One relation can be registered per Iceberg table. A namespace that needs
 quoting, such as `Lake-EU`, works.
 
-## Mode 3 - Standalone partition manager (no cold tier)
+## Mode 3 - Standalone Partition Manager (No Cold Tier)
 
 **You don't need Iceberg at all.** If automated PostgreSQL partition
 maintenance is all you want - declarative time- or id-based RANGE partitioning
@@ -320,7 +321,7 @@ Register each managed table in `coldfront.partition_config`:
                       #     standalone table - data preserved)
 ```
 
-### Operating it
+### Operating It
 
 Schedule one pass per period or more often - a cron line, or a systemd
 `oneshot` service plus timer (a failed pass then surfaces as a failed unit, so
@@ -353,7 +354,7 @@ Keep the following operational behavior in mind when scheduling it:
   correct). `detach` is partition-only - the tiered archiver always drops after
   exporting to cold.
 
-### Primary keys on time-partitioned tables (id mode)
+### Primary Keys on Time-Partitioned Tables (id Mode)
 
 PostgreSQL requires a unique index to include the partition key, so a plain
 `PRIMARY KEY (id)` is impossible on a table partitioned by a separate `ts`
@@ -370,11 +371,11 @@ key *is* the key - a single-column `PRIMARY KEY (id)`:
 ```
 
 `uuidv7` reads the RFC 9562 leading-millisecond timestamp; `snowflake` decodes
-the pgEdge snowflake extension's layout. Either way the manager computes the
+the pgEdge Snowflake extension's layout. Either way the manager computes the
 month/day partition bounds as id values, so id-order equals time-order and the
 forward/retention schedule is unchanged.
 
-### Two-level (LIST → RANGE) sub-partitioning
+### Two-Level (LIST → RANGE) Sub-Partitioning
 
 For a table partitioned by `LIST (region)` whose children are themselves
 `RANGE`-partitioned by time, add a `sub_partition` block. `values_source` is a
@@ -391,7 +392,7 @@ values automatically:
         values_source: "SELECT code FROM regions"
 ```
 
-## Dropping an Iceberg table (both modes)
+## Dropping an Iceberg Table (Both Modes)
 
 `coldfront.drop_iceberg_table()` removes the Iceberg table backing a registered
 relation. It is the only sanctioned way to do so: a plain `DROP TABLE` or
@@ -436,7 +437,7 @@ Deletion is not instantaneous. The catalog entry disappears with the call, and
 Lakekeeper's own background queue removes the objects shortly afterwards, so a
 listing taken immediately after the call can still show them.
 
-### Handing an adopted table back
+### Handing an Adopted Table Back
 
 An adopted table is released rather than dropped, because ColdFront does not
 own it. `coldfront.release_iceberg_table()` removes the wrapper view, the
@@ -452,11 +453,11 @@ cold rows unreachable while the hot table returned under the relation's name.
 `drop_iceberg_table()` refuses a relation adopted read-only, for the mirrored
 reason: read access carries no authority to destroy.
 
-## Managing partitioned tables (CLI)
+## Managing Partitioned Tables (CLI)
 
 ColdFront splits configuration into two kinds. **Connection** config - the
-Postgres DSN, and (tiered archiver only) the Iceberg/S3 connection - stays in a
-small per-node YAML and is never replicated. **Per-table lifecycle** lives in
+PostgreSQL DSN, and (tiered archiver only) the Iceberg/S3 connection - stays in
+a small per-node YAML and is never replicated. **Per-table lifecycle** lives in
 `coldfront.partition_config`, a name-keyed table that replicates by value
 across a Spock mesh (like `tiered_views`/`archive_watermark`), so every node
 reads identical config - no per-node file syncing. Manage it with the CLI below
@@ -475,7 +476,7 @@ The data lifecycle is **hot PG → `hot_period` → cold Iceberg →
 dropped** (partition-only). Setting `hot_period` makes a table tiered; omitting
 it makes it partition-only.
 
-### What registration refuses
+### What Registration Refuses
 
 `register`, `import` and `set` share one validation gate, so a table that one
 command rejects cannot be added by another. Registration fails when:
@@ -498,7 +499,7 @@ command rejects cannot be added by another. Registration fails when:
 - the name leaves no room for the generated partition suffix: 53 characters for
   monthly and 50 for daily, within PostgreSQL's 63-byte identifier limit.
 - a tiered table carries a column whose type has no Iceberg equivalent (see
-  [Supported column types](#supported-column-types)). Every column goes through
+  [Supported Column Types](#supported-column-types)). Every column goes through
   the same type map the cold tier itself uses, so the answer comes back at the
   prompt rather than hours later from cron. Partition-only tables are exempt:
   nothing about them reaches Iceberg, so their column types are PostgreSQL's
@@ -542,7 +543,7 @@ partitioner register --config cf.yaml --table events --period monthly \
 archiver register --config cf.yaml --table events --period monthly \
     --hot-period "1 month" --retention "5 years"
 
-# id mode — a real single-column PRIMARY KEY (id) on a snowflake-keyed table.
+# id mode - a real single-column PRIMARY KEY (id) on a snowflake-keyed table.
 partitioner register --config cf.yaml --table events --period monthly \
     --column id --part-mode id --id-scheme snowflake --retention "1 year"
 
@@ -569,14 +570,14 @@ removing it; a disabled table is skipped by reconcile and omitted from
 `pg_catalog` for flat tables (required for 2-level). `register` writes a row
 whose `CHECK` constraints enforce the lifecycle rules at write time.
 
-**Managing tables:** the archiver and partitioner read the managed set only
-from `coldfront.partition_config`. `register` adds one table; `import` adds
-every table in a YAML `archiver.tables` list. Both write through the same
-validation (the PK must cover the partition key; `retention` must exceed
-`hot_period`), so an imported table is checked exactly as a registered one.
-`export` dumps the active rows back to YAML or SQL for git.
+Managing tables: the archiver and partitioner read the managed set only from
+`coldfront.partition_config`. `register` adds one table; `import` adds every
+table in a YAML `archiver.tables` list. Both write through the same validation
+(the PK must cover the partition key; `retention` must exceed `hot_period`), so
+an imported table is checked exactly as a registered one. `export` dumps the
+active rows back to YAML or SQL for git.
 
-## Storage backends
+## Storage Backends
 
 Configure **exactly one** cold-store backend:
 
@@ -585,12 +586,12 @@ Configure **exactly one** cold-store backend:
   `vhost`.
 - **Virtual-hosted cloud S3** (AWS S3 is the canonical one) - **omit
   `endpoint`** (and the `endpoint` arg to `set_storage_secret`) so DuckDB uses
-  the native per-Region virtual-hosted + HTTPS addressing; just set `region` to
-  your bucket's Region. This is **required** for Regions launched after
-  2019-03-20 (e.g. `ap-south-2`), whose DNS does not route path-style requests
-  and returns HTTP 400. The Lakekeeper warehouse profile must be a
-  virtual-hosted `s3` profile (`flavor: aws`, `path-style-access: false`, no
-  custom endpoint); the full walkthrough is [object_store.md](object_store.md).
+  the native per-Region virtual-hosted + HTTPS addressing; set `region` to your
+  bucket's Region. This is **required** for Regions launched after 2019-03-20
+  (e.g. `ap-south-2`), whose DNS does not route path-style requests and returns
+  HTTP 400. The Lakekeeper warehouse profile must be a virtual-hosted `s3`
+  profile (`flavor: aws`, `path-style-access: false`, no custom endpoint); the
+  full walkthrough is [object_store.md](object_store.md).
 - **Google Cloud Storage** - *not a separate backend*: use `s3:` pointed at
   GCS's S3-interoperability endpoint with an
   [HMAC key pair](https://cloud.google.com/storage/docs/authentication/hmackeys)
@@ -618,7 +619,7 @@ It writes the same `coldfront.storage_secret` row (replicated,
 Azure cold tier is subject to the soft-delete / change-feed restriction in
 [Caveats](index.md#caveats).
 
-## Vended credentials
+## Vended Credentials
 
 Vended credentials let a deployment run with no object-store credential stored
 in the database, in a DuckDB secret file, or in an archiver config; this suits
@@ -669,13 +670,13 @@ the attach mode, which is fixed per PostgreSQL backend at attach time; open a
 new session (or restart the archiver and compactor, which are short-lived
 processes) so the new mode takes effect.
 
-## Reading + writing (identical for both modes)
+## Reading + Writing (Identical for Both Modes)
 
 The same SQL works against the relation name in either mode, as the following
 examples show:
 
 ```sql
--- Reads — pg_duckdb handles the iceberg side; PG handles the heap side
+-- Reads - pg_duckdb handles the iceberg side; PG handles the heap side
 SELECT count(*) FROM events;
 SELECT id, status, data->>'k' FROM events WHERE ts >= '2026-04-01';
 
@@ -687,7 +688,7 @@ INSERT INTO events (ts, status, data) VALUES (now(), 'ok', '{"k":1}');
 UPDATE events SET status = 'fixed' WHERE id = 123;
 DELETE FROM events WHERE ts < '2025-01-01';
 
--- Bulk INSERT shapes are all set-based — no per-row work:
+-- Bulk INSERT shapes are all set-based - no per-row work:
 INSERT INTO events (ts, status, data) VALUES (...), (...), (...);
 INSERT INTO events (ts, status, data) SELECT ts, status, data FROM staging;
 INSERT INTO events (ts, status, data) SELECT now() + i*'1s'::interval, 'ok', '{}'
@@ -701,7 +702,7 @@ ROLLBACK;
 SELECT status FROM events WHERE id = 1;     -- back to whatever it was
 ```
 
-## Supported column types
+## Supported Column Types
 
 The following PostgreSQL column types are supported:
 
@@ -768,7 +769,7 @@ cross-tier read is planned by pg_duckdb - so no cast makes them readable. Store
 IP data as `text` and `oid` values as `bigint` (you can still index/compare
 them; cast on the hot side only if needed).
 
-## Gotchas
+## Caveats
 
 Keep the following caveats in mind when running either mode:
 
@@ -777,7 +778,7 @@ Keep the following caveats in mind when running either mode:
   `jsonb_build_object` / `jsonb_agg` and `date_bin`; other jsonb operators and
   functions are unsupported on cold or cross-tier reads. A hot-only read of the
   view runs in PostgreSQL with full jsonb (see
-  [Supported column types](#supported-column-types)).
+  [Supported Column Types](#supported-column-types)).
 - **Cross-tier isolation**: a long-running `SELECT` that touches the Iceberg
   side multiple times within one transaction may see writes from other sessions
   interleaved between scans. PG's repeatable-read does not extend across the
@@ -789,7 +790,7 @@ Keep the following caveats in mind when running either mode:
 - **Concurrent writes from multiple PG nodes (decoupled mode)**: serialized
   PG-side by the bakery protocol - every iceberg-only INSERT goes through
   `coldfront._exec_iceberg_with_claim`, which holds a globally-ordered
-  snowflake ticket and waits for its turn before committing to Lakekeeper. No
+  Snowflake ticket and waits for its turn before committing to Lakekeeper. No
   409 conflicts, no app-level retry. The protocol is Lamport-1978 mutex with
   the Ricart-Agrawala (1981) deferred-reply optimization; claims and acks
   replicate as Spock rows and it stays safe under Spock's asymmetric apply
@@ -797,7 +798,7 @@ Keep the following caveats in mind when running either mode:
   [docs/formal/Bakery.tla](https://github.com/pgEdge/ColdFront/blob/main/docs/formal/Bakery.tla)).
   The bakery requires the `snowflake` extension, the `coldfront.dblink_self`
   GUC (the connection string of the node's loopback), and a one-time
-  `SELECT coldfront._ensure_claims_replicated()` call on every node after spock
+  `SELECT coldfront._ensure_claims_replicated()` call on every node after Spock
   mesh setup; see
   [architecture_decoupled.md](architecture_decoupled.md#concurrency-horizontal-scaling-the-bakery-protocol).
   Sync-rep is **not** required. The throughput ceiling is Lakekeeper's commit
@@ -816,13 +817,13 @@ Keep the following caveats in mind when running either mode:
   very large historical seeds (mostly-cold), prefer iceberg-only mode where ids
   come from your source data.
 
-## Distributed setup (3-node mesh, decoupled mode)
+## Distributed Setup (3-Node Mesh, Decoupled Mode)
 
-For multi-writer iceberg workloads, run coldfront on N PG nodes in a Spock mesh
+For multi-writer iceberg workloads, run ColdFront on N PG nodes in a Spock mesh
 against the same Lakekeeper + S3. The bakery serializes commits PG-side so
 writers never collide at the catalog.
 
-### Per-node `postgresql.conf`
+### Per-Node `postgresql.conf`
 
 The configuration below applies to each node in the mesh:
 
@@ -852,8 +853,8 @@ output_plugin_libraries = 'pgoutput, test_decoding, spock_output'
 # quiet period.  1 s leaves comfortable margin.
 wal_receiver_status_interval = 1s
 
-# Per-node — any distinct integer 1..1023 (must be unique per node; the value
-# is otherwise arbitrary — the bakery matches acks by spock node name, not by id).
+# Per-node - any distinct integer 1..1023 (must be unique per node; the value
+# is otherwise arbitrary - the bakery matches acks by spock node name, not by id).
 snowflake.node = 1
 
 # DSN of the node's loopback, which runs the bakery's autonomous claim
@@ -890,9 +891,9 @@ R-A ack barrier is what serializes iceberg commits. You can still enable it
 cluster-wide if you want stronger durability for non-bakery writes, but it
 plays no part in iceberg-commit serialization.
 
-**One-time mesh setup** - must be done in this order on every node, because
+One-time mesh setup - must be done in this order on every node, because
 `coldfront._ensure_claims_replicated()` calls `spock.repset_add_table` and so
-requires the local spock node to already exist:
+requires the local Spock node to already exist:
 
 ```sql
 -- 1. Extensions, in dependency order. snowflake is a bakery prereq
@@ -936,11 +937,11 @@ SELECT spock.repset_add_table('default', 'coldfront.archive_watermark'::regclass
 `synchronize_structure := false, synchronize_data := false` - tables already
 exist on every node from the coldfront extension; no initial copy needed.
 
-**Verify before benching** - insert a sentinel claim on each node and read it
-back from every other node. All N×(N-1) directions must show the row before
-traffic starts. `ci/journey.sh` `story_mesh_substrate` is a copyable reference.
+Verify before benching - insert a sentinel claim on each node and read it back
+from every other node. All N×(N-1) directions must show the row before traffic
+starts. `ci/journey.sh` `story_mesh_substrate` is a copyable reference.
 
-## Tuning knobs
+## Tuning Knobs
 
 The following GUCs adjust write behavior and execution; tune them as needed:
 
@@ -967,7 +968,7 @@ The following GUCs adjust write behavior and execution; tune them as needed:
   divide it by the concurrent sessions or give the temp path its own filesystem
   or quota.
 
-## Going deeper
+## Going Deeper
 
 For deeper detail on each mode's internals, see the architecture references:
 
diff --git a/docs/usage_vectors.md b/docs/usage_vectors.md
index 7a8a3e3..3634c1f 100644
--- a/docs/usage_vectors.md
+++ b/docs/usage_vectors.md
@@ -1,11 +1,11 @@
-# Working with embeddings
+# Working with Embeddings
 
 ColdFront stores embeddings in the cold tier as Iceberg `list<float>` and keeps
 the pgvector interface you already write. A vector column works in both modes:
 a tiered table whose recent rows stay in PostgreSQL, and a decoupled table that
 lives entirely in Iceberg.
 
-## Creating a table
+## Creating a Table
 
 Tiered, through the archiver's normal configuration:
 
@@ -45,7 +45,7 @@ The value coerces to the column whether the row lands hot or cold, and an
 changes when a table is clustered (below): assignments are maintained for you
 in the same statement as the write.
 
-## Reading and searching
+## Reading and Searching
 
 The view exposes the column as `real[]`, which is the same type Iceberg stores.
 Read it like any column:
@@ -68,7 +68,7 @@ All three pgvector operators are available: `<=>` cosine, `<->` Euclidean,
 `<#>` negative inner product. Use `<=>` unless you have a reason not to;
 clustering is built on cosine.
 
-### Three rules for the query vector
+### Three Rules for the Query Vector
 
 These are requirements, not style. Each fails clearly if broken.
 
@@ -108,23 +108,28 @@ CALL coldfront.vector_train('public', 'chunks', 'embedding');
 
 `CALL`, not `SELECT`: this is a procedure. It samples the cold tier, trains
 `nlist` centroids, stores them as a new generation, and assigns every cold row
-to its nearest centroid, rewriting the rows whose cluster changed. Every cold
-write after it assigns the row in the same statement, on every write path.
+to its nearest centroid, rewriting the rows whose cluster changed. After
+`vector_train` runs, every cold write assigns the row to a cluster in the same
+statement, on every write path.
 
 Compact afterwards. The assignment leaves a delete marker per rewritten row and
 those rows in rewrite order; compaction is what puts them in cluster order and
 clears the markers. Without it the rows are assigned but a search still reads
 more of the table than it needs to.
 
-**Retraining.** Call `vector_train` again when the data has grown or you want a
-different `nlist`. Without `p_nlist`, the new centroids start from the current
-ones and keep their identities, so only the rows whose nearest centroid changed
-are rewritten; with a new `nlist`, every row is. Either way the centroids and
-the assignments change together, so a search is never wrong in between; it is
-only slower until the next compaction.
+### Retraining
 
-**Time partitioning.** A tiered vector table is partitioned by time, because
-its hot table is; a decoupled one only if it was created with time partitioning
+Call `vector_train` again when the data has grown or you want a different
+`nlist`. Without `p_nlist`, the new centroids start from the current ones and
+keep their identities, so only the rows whose nearest centroid changed are
+rewritten; with a new `nlist`, every row is. Either way the centroids and the
+assignments change together, so a search is never wrong in between; it is only
+slower until the next compaction.
+
+### Time Partitioning
+
+A tiered vector table is partitioned by time, because its hot table is; a
+decoupled one only if it was created with time partitioning
 (`p_partition_cols`). On such a table a search with a time filter skips the
 months outside it, and a search over all of history reads one row group of each
 probed cluster per month rather than one, roughly the number of months more
@@ -139,8 +144,9 @@ stop reducing the data read. Above it there is a wide plateau.
 ### Choosing `nprobe`
 
 `nprobe` is how many clusters a search reads, and it is the dial between recall
-and speed. Measured on a 10 million row corpus of 1024-dimension embeddings,
-`nlist` 1000, against the exact answer for 100 queries:
+and speed. The following table shows recall and query time at each `nprobe`,
+measured on a 10 million row corpus of 1024-dimension embeddings, `nlist` 1000,
+against the exact answer for 100 queries:
 
 | `nprobe` | clusters read | recall | median query |
 |---|---|---|---|
@@ -176,7 +182,7 @@ faster at the same recall.
 Your corpus is not this one. Take these as the shape of the curve, and measure
 your own against a sample of queries you have exact answers for.
 
-### What a clustered search does
+### What a Clustered Search Does
 
 Once a column has a trained generation, a search that ends in
 `ORDER BY <column> <=> <vector> LIMIT n` reads only the `nprobe` clusters
@@ -195,7 +201,8 @@ Anything that is not that shape stays an exact scan of both tiers, which is
 correct. Two cases worth knowing: a search with no `LIMIT` is answered exactly,
 because asking for every row in order is not a request to approximate; and so
 is one wrapped in a subquery or CTE, because the clustering is applied to the
-statement you write rather than to a nested part of it.
+statement you write rather than to a nested part of it. The following two
+statements show the difference:
 
 ```sql
 -- narrowed to the nearest clusters
@@ -207,7 +214,7 @@ SELECT string_agg(body, ',') FROM (
 
 Rows written before the column was trained have no cluster, and they are
 returned by every search regardless of which clusters it reads. So is every
-hot-tier row. Nothing goes missing because it predates the clustering.
+hot-tier row. A row written before training never goes missing on that account.
 
 Two settings, per session:
 
@@ -221,7 +228,9 @@ SET coldfront.vector_probe = off;
 Leave `coldfront.vector_nprobe` at its default of `0` to use the `nprobe` you
 recorded for the column.
 
-### Checking whether the clustering is earning its keep
+### Checking Whether the Clustering Is Earning Its Keep
+
+Call `vector_status` and query its results table:
 
 ```sql
 CALL coldfront.vector_status();
@@ -232,7 +241,8 @@ SELECT table_name, rows_total, rows_unassigned, clusters_occupied,
 
 `probe_fraction` is the number to watch: the share of the cold rows a search
 reads on average. Lower is faster. `advice` is filled in only when something
-specific is holding that number up, and says which:
+specific is holding that number up; the following table shows what each message
+means and what to do:
 
 | What it says | What to do |
 |---|---|
@@ -245,7 +255,7 @@ Pass a schema and table to report on one column:
 `CALL coldfront.vector_status('public', 'chunks')`. The results land in a
 temporary table that lasts for your session, and each call replaces the last.
 
-## More than one vector column
+## More than One Vector Column
 
 A table may carry as many vector columns as you like. Each gets its own
 configuration, its own centroids and its own generation, and each is assigned
@@ -267,7 +277,7 @@ clusters are scattered through it, so its row-group statistics cover most of
 the file and nothing gets skipped.
 
 What a later column still gets is the filter. Its predicate cuts the rows that
-have to be *scored*, just not the rows that have to be *read*, and reading is
+have to be *scored*, but not the rows that have to be *read*, and reading is
 about 95% of the cost. Expect single-digit percent rather than the 54x the
 first column gets.
 
@@ -284,7 +294,7 @@ If a second vector column needs to be fast, the honest answer is a second table
 holding that column and a key, ordered by its own clustering. That is what a
 secondary index is, and Iceberg gives us no way to have two orders in one file.
 
-## What a clustered table needs from the deployment
+## What a Clustered Table Needs from the Deployment
 
 The assignment lookup reads the centroid tables through a local connection, so
 `coldfront.local_pg_dsn` must be set. The shipped container image sets it. On
@@ -311,7 +321,9 @@ so the number of places a search looks is set by data volume rather than by
 write count. Nothing to configure: the table records its own sort column at
 creation and the compactor reads it.
 
-## Limits worth knowing
+## Limits Worth Knowing
+
+The following limits apply to vector columns:
 
 - A hot pgvector index is optional and capped by pgvector itself: HNSW refuses
   a `vector` column beyond 2,000 dimensions and a `halfvec` beyond 4,000, while
diff --git a/docs/walkthrough.md b/docs/walkthrough.md
index bc2d2a6..692a622 100644
--- a/docs/walkthrough.md
+++ b/docs/walkthrough.md
@@ -1,7 +1,7 @@
 ---
 cwd: ../
 ---
-# ColdFront guided walkthrough
+# ColdFront Guided Walkthrough
 
 New here? Run the guided walkthrough.
 
@@ -28,7 +28,7 @@ minutes); everything after it is quick.
 Prefer a terminal? `bash examples/walkthrough/guide.sh` runs the same demos as
 an interactive guide.
 
-## 💻 On your own machine
+## 💻 On Your Own Machine
 
 You need Docker 24+ with Compose V2 (the `docker compose` plugin, not the
 legacy `docker-compose` binary), roughly 3 GB of free disk inside Docker's
@@ -56,7 +56,7 @@ stack, and walks through each demo interactively. This page and the
 [demos](walkthrough_demos.md) cover the same steps - run them from the doc or
 paste them into your shell.
 
-## What setup does
+## What Setup Does
 
 Setup runs before the demos begin. Setup starts the containers, waits for
 PostgreSQL and Lakekeeper to accept connections, and creates the Lakekeeper
@@ -134,7 +134,7 @@ curl -sf -X POST \
   -d '{"namespace":["public"]}'
 ```
 
-### Using a cloud object store
+### Using a Cloud Object Store
 
 The walkthrough hero path uses SeaweedFS. To use a cloud store instead, replace
 the warehouse JSON above and the `set_storage_secret` call in Step 5 of
diff --git a/docs/walkthrough_demos.md b/docs/walkthrough_demos.md
index 1b09284..9aebc73 100644
--- a/docs/walkthrough_demos.md
+++ b/docs/walkthrough_demos.md
@@ -1,13 +1,13 @@
 ---
 cwd: ../
 ---
-# ColdFront walkthrough demos
+# ColdFront Walkthrough Demos
 
 This page contains the four demos of the [guided walkthrough](walkthrough.md).
-Run the steps in [What setup does](walkthrough.md#what-setup-does) before you
+Run the steps in [What Setup Does](walkthrough.md#what-setup-does) before you
 start Demo 1.
 
-## Demo 1: tiered storage
+## Demo 1: Tiered Storage
 
 Tiered storage is a brownfield retrofit: you begin with a plain PostgreSQL
 database full of data, add ColdFront to it, and let the archiver relocate the
@@ -18,24 +18,24 @@ The following table shows the eleven steps this demo covers:
 
 | Step | What you will do |
 |------|-----------------|
-| 1. Start the stack | Bring up Postgres, Lakekeeper, and the object store |
-| 2. Create a table and load history | An ordinary partitioned table with months of data |
-| 3. See the problem | All rows in hot Postgres storage, and it only grows |
-| 4. Enable the extensions | Two extensions retrofit tiering onto the existing database |
-| 5. Point at object storage | Tell ColdFront where cold data lives |
-| 6. Show the archiver policy | `hot_period: 30 days` - the hot/cold boundary |
-| 7. Run the archiver | Move everything older than 30 days to object storage |
-| 8. Where it lives now | The hot/cold split: rows and space in each tier |
-| 9. Query across tiers | One table, one query, hot + cold together |
-| 10. Write to cold data | UPDATE an archived row in place - no rehydration |
-| 11. Prove it stuck | Reconnect and confirm the edit persisted in cold storage |
-
-### Step 1 - Start the stack (setup)
+| [1. Start the stack](#step-1-start-the-stack-setup) | Bring up Postgres, Lakekeeper, and the object store |
+| [2. Create a table and load history](#step-2-create-a-table-and-load-months-of-history) | An ordinary partitioned table with months of data |
+| [3. See the problem](#step-3-see-the-problem) | All rows in hot Postgres storage, and it only grows |
+| [4. Enable the extensions](#step-4-enable-the-extensions) | Two extensions retrofit tiering onto the existing database |
+| [5. Point at object storage](#step-5-point-coldfront-at-the-object-store) | Tell ColdFront where cold data lives |
+| [6. Show the archiver policy](#step-6-show-the-archiver-policy) | `hot_period: 30 days` - the hot/cold boundary |
+| [7. Run the archiver](#step-7-register-the-table-then-run-the-archiver) | Move everything older than 30 days to object storage |
+| [8. Where it lives now](#step-8-where-the-data-lives-now) | The hot/cold split: rows and space in each tier |
+| [9. Query across tiers](#step-9-query-across-tiers) | One table, one query, hot + cold together |
+| [10. Write to cold data](#step-10-write-to-cold-data) | UPDATE an archived row in place - no rehydration |
+| [11. Prove it stuck](#step-11-prove-it-stuck) | Reconnect and confirm the edit persisted in cold storage |
+
+### Step 1: Start the Stack (Setup)
 
 Setup starts the infrastructure: PostgreSQL (your database), plus Lakekeeper
 and SeaweedFS. The cold-storage side sits idle until you point ColdFront at it
 in Step 5. Run the `docker compose up` command shown in
-[What setup does](walkthrough.md#what-setup-does). Then confirm that the `db`,
+[What Setup Does](walkthrough.md#what-setup-does). Then confirm that the `db`,
 `lakekeeper-db`, and `lakekeeper` services report `healthy`:
 
 ```bash
@@ -46,7 +46,7 @@ PostgreSQL is your existing database. The catalog and object store are also
 running - that is the cold-storage side, unused until Step 5. Locally the store
 is SeaweedFS; in production it is your AWS S3, Azure Blob, or GCS bucket.
 
-### Step 2 - Create a table and load months of history
+### Step 2: Create a Table and Load Months of History
 
 This step stands in for the database you already run: an ordinary
 range-partitioned PostgreSQL table, filled with months of accumulated data.
@@ -118,6 +118,8 @@ Confirm all rows landed:
 SELECT count(*) FROM events;
 ```
 
+The count confirms it:
+
 ```text {"ignore":"true"}
   count
 ---------
@@ -127,7 +129,7 @@ SELECT count(*) FROM events;
 Months of data now live in an ordinary PostgreSQL table - no ColdFront involved
 yet.
 
-### Step 3 - See the problem
+### Step 3: See the Problem
 
 This step measures how much hot Postgres storage that data occupies and
 confirms that none of it is anywhere cheaper yet. This is the baseline you will
@@ -148,6 +150,8 @@ SELECT pg_size_pretty(
 ) AS hot_size;
 ```
 
+The result:
+
 ```text {"ignore":"true"}
  hot_size
 ----------
@@ -158,7 +162,7 @@ Every row - all one million - occupies hot, expensive primary storage, and the
 table only grows. Remember this figure; Step 8 shows where it goes after
 tiering.
 
-### Step 4 - Enable the extensions
+### Step 4: Enable the Extensions
 
 This step retrofits tiering onto the database you already have, using two
 extensions. `pg_duckdb` gives PostgreSQL an in-process engine that can read
@@ -179,6 +183,8 @@ Confirm both are installed:
 \dx
 ```
 
+The output lists both:
+
 ```text {"ignore":"true"}
    Name    | Version |   Schema   |                                          Description
 -----------+---------+------------+------------------------------------------------------------------------------------------------
@@ -190,7 +196,7 @@ Confirm both are installed:
 Two extensions - that is the entire ColdFront install. No sidecar, no proxy, no
 data movement yet.
 
-### Step 5 - Point ColdFront at the object store
+### Step 5: Point ColdFront at the Object Store
 
 This step tells ColdFront where cold data goes and how to authenticate to it.
 The credentials below are throwaway values for the local SeaweedFS emulator. In
@@ -213,15 +219,17 @@ curl -s localhost:8181/management/v1/warehouse \
   | grep -o '"name":"wh"'
 ```
 
+The response confirms it:
+
 ```text {"ignore":"true"}
 "name":"wh"
 ```
 
-### Step 6 - Show the archiver policy
+### Step 6: Show the Archiver Policy
 
 The archiver policy is one rule in a YAML file: data older than 30 days belongs
 in cheap object storage; the most recent data stays hot in PostgreSQL. Nothing
-moves yet - this step just shows the boundary.
+moves yet - this step shows the boundary.
 
 Inspect the archiver configuration:
 
@@ -229,6 +237,8 @@ Inspect the archiver configuration:
 cat examples/walkthrough/config/archiver.yaml
 ```
 
+The file reads:
+
 ```yaml {"ignore":"true"}
 # ColdFront walkthrough archiver config: Demo 1 (tiered).
 #
@@ -259,7 +269,7 @@ The `hot_period: 30 days` value is the hot/cold line. Any partition whose data
 is entirely older than 30 days will move to object storage when the archiver
 runs.
 
-### Step 7 - Register the table, then run the archiver
+### Step 7: Register the Table, Then Run the Archiver
 
 The archiver reads its managed-table set from `coldfront.partition_config`, not
 from the YAML at run time. Seed that table once from the YAML's
@@ -287,9 +297,10 @@ The archiver connects inside the Compose network (service name `db`, not
 exports them to Iceberg via pg_duckdb, and replaces the `events` table with a
 unified view that queries both tiers.
 
-**Proof (a) - the cold rows are really in S3 as Parquet.** The
-`iceberg_metadata()` table function resolves its argument as a filesystem path,
-so a REST-catalog table cannot be addressed by name directly. Resolve the
+#### Proof (a): The Cold Rows Are Really in S3 as Parquet
+
+The `iceberg_metadata()` table function resolves its argument as a filesystem
+path, so a REST-catalog table cannot be addressed by name directly. Resolve the
 table's `metadata.json` S3 location from the Lakekeeper catalog first, then
 point `iceberg_metadata()` at that path:
 
@@ -317,6 +328,8 @@ LIMIT 3;
 SQL
 ```
 
+The query returns:
+
 ```text {"ignore":"true"}
 s3://iceberg/<warehouse-uuid>/<table-uuid>/metadata/00023-<uuid>.gz.metadata.json
 
@@ -332,7 +345,9 @@ PostgreSQL - they are objects in object storage. Each month's files sit under
 their own `month_ts_<n>=` directory: the cold table is partitioned by month,
 the way the hot table is.
 
-**Proof (b) - the table changed shape.** Inspect the relation type:
+#### Proof (b): The Table Changed Shape
+
+Inspect the relation type:
 
 ```sql {"interpreter":"psql postgresql://coldfront@localhost:5432/coldfront?options=-cclient_min_messages%3Dwarning -v ON_ERROR_STOP=1 -P pager=off -f"}
 \d events
@@ -345,7 +360,7 @@ the following query to see the recorded hot/cold cutoff:
 SELECT * FROM coldfront.archive_watermark;
 ```
 
-### Step 8 - Where the data lives now
+### Step 8: Where the Data Lives Now
 
 This step accounts for every row after tiering: how many are still hot in
 PostgreSQL, how many are now cold in object storage, and how much space each
@@ -391,7 +406,7 @@ Before tiering (Step 3): one million rows, all hot, approximately 152 MB of
 Postgres heap. After tiering: only the last month or two remains in PostgreSQL;
 over 90% of the hot storage is gone while the total row count is unchanged.
 
-### Step 9 - Query across tiers
+### Step 9: Query Across Tiers
 
 This step runs one ordinary query against `events` that spans both tiers, then
 queries the hot-only table for contrast. The application issuing this query
@@ -419,6 +434,8 @@ ORDER BY ts
 LIMIT 3;
 ```
 
+The query returns:
+
 ```text {"ignore":"true"}
  id |              ts               | status
 ----+-------------------------------+--------
@@ -430,7 +447,7 @@ LIMIT 3;
 The timestamps track your load: row 1 sits exactly 730 days before it. One
 table, one query, no application change required.
 
-### Step 10 - Write to cold data
+### Step 10: Write to Cold Data
 
 This step takes a specific row from a cold (archived) month and updates it
 through the same `events` view. Watch for what does not happen: no rehydration
@@ -449,6 +466,8 @@ ORDER BY ts
 LIMIT 1;
 ```
 
+The query returns:
+
 ```text {"ignore":"true"}
  id |              ts               | status
 ----+-------------------------------+--------
@@ -467,6 +486,8 @@ Read the row back immediately:
 SELECT id, ts, status FROM events WHERE id = 1;
 ```
 
+The updated row reads:
+
 ```text {"ignore":"true"}
  id |              ts               |  status
 ----+-------------------------------+-----------
@@ -476,7 +497,7 @@ SELECT id, ts, status FROM events WHERE id = 1;
 The row's status flipped `warn` to `corrected`. That row is still sitting in
 object storage - ColdFront wrote through to it directly.
 
-### Step 11 - Prove it stuck
+### Step 11: Prove It Stuck
 
 This step opens a fresh `psql` connection (nothing cached from the session that
 did the write) and re-checks the row, the total row count, and the hot heap
@@ -484,8 +505,8 @@ size. This confirms that the cold edit is durable persistent state and that the
 data did not quietly return to PostgreSQL to make the edit possible.
 
 Each runnable cell on this page already opens a fresh connection, so
-cell-runners can simply run the checks below. In a local shell, open a new
-terminal and connect with a fresh session first:
+cell-runners can run the checks below. In a local shell, open a new terminal
+and connect with a fresh session first:
 
 ```bash {"ignore":"true"}
 PGOPTIONS='-c client_min_messages=warning' \
@@ -498,6 +519,8 @@ Confirm the archived row is still `corrected`:
 SELECT id, status FROM events WHERE id = 1;
 ```
 
+The row reads:
+
 ```text {"ignore":"true"}
   id |  status
 -----+-----------
@@ -510,6 +533,8 @@ Confirm the total row count is unchanged:
 SELECT count(*) AS total_rows FROM events;
 ```
 
+The count confirms it:
+
 ```text {"ignore":"true"}
  total_rows
 ------------
@@ -529,6 +554,8 @@ SELECT pg_size_pretty(
 ) AS hot_size;
 ```
 
+The result:
+
 ```text {"ignore":"true"}
  hot_size
 ----------
@@ -541,7 +568,7 @@ PostgreSQL. Over 90% of the original storage now lives in object storage as
 Parquet, and that data is still a normal, writeable part of the table -
 corrected in place, no rehydration, no separate system.
 
-## Demo 2: decoupled (Iceberg-only)
+## Demo 2: Decoupled (Iceberg-Only)
 
 Decoupled mode stores a table entirely in Iceberg from the first row.
 PostgreSQL holds a thin wrapper view and a registry entry. This is a fresh
@@ -550,7 +577,7 @@ independent. Demo 2 still needs the extensions and storage secret from Steps 4
 and 5 of [Demo 1](#demo-1-tiered-storage). If you start here, run those two
 steps first.
 
-### Create an Iceberg-only table
+### Create an Iceberg-Only Table
 
 One SQL call provisions the Iceberg table and the PostgreSQL view. The `public`
 namespace was seeded during setup, and the call wraps both steps in a single
@@ -572,7 +599,7 @@ SELECT coldfront.create_iceberg_table(
 After the call returns, `events_lake` is a view; every row lives in Iceberg on
 S3.
 
-### Read and write the lake table
+### Read and Write the Lake Table
 
 `events_lake` behaves like any PostgreSQL table:
 
@@ -596,13 +623,13 @@ All four DML operations reach the Iceberg table transparently. The coldfront
 extension intercepts each statement on the view and rewrites it to the Iceberg
 path via pg_duckdb.
 
-## Demo 2b: adopt a table already in the lake
+## Demo 2b: Adopt a Table Already in the Lake
 
 Not every Iceberg table starts in ColdFront. A table another engine wrote needs
 no provisioning, only a wrapper view and a registry row. Adoption builds both
 from the schema the catalog already holds.
 
-### Stand in for the external writer
+### Stand In for the External Writer
 
 These three statements are the only ones in this walkthrough written in DuckDB
 SQL, because they represent what some other engine already did to your lake.
@@ -629,7 +656,7 @@ SELECT duckdb.raw_query($$
     (2, now(), 'globex', 249.50, '{"tier":"silver"}')$$);
 ```
 
-### Adopt it read-only
+### Adopt It Read-Only
 
 One call, and no column list; the schema comes from the catalog. The view goes
 in the PostgreSQL schema `public`; `lake` is the Iceberg namespace, and no
@@ -653,12 +680,14 @@ Writes are refused, and the message says what to do:
 UPDATE orders SET amount = 0 WHERE order_id = 1;
 ```
 
+The refusal reads:
+
 ```text
 ERROR:  coldfront: "public.orders" is adopted read-only
 HINT:  Release it with coldfront.release_iceberg_table() and adopt again with p_writable => true to arm INSERT/UPDATE/DELETE.
 ```
 
-### Enable writes
+### Enable Writes
 
 Adoption binds the name once, so enabling writes is a release followed by a
 second adopt with `p_writable => true`, which gives the view the same DML
@@ -677,11 +706,11 @@ DELETE FROM orders WHERE order_id = 1;
 SELECT order_id, customer, amount FROM orders ORDER BY order_id;
 ```
 
-### Restore a type Iceberg cannot record
+### Restore a Type Iceberg Cannot Record
 
 The `meta` column reads as text, because Iceberg stores JSON as `VARCHAR` and
-records no PostgreSQL type. `p_types` restores it, and the override is accepted
-because it maps to what the catalog stores:
+records no PostgreSQL type. `p_types` restores the column's type, and the
+override is accepted because it maps to what the catalog stores:
 
 ```sql {"interpreter":"psql postgresql://coldfront@localhost:5432/coldfront?options=-cclient_min_messages%3Dwarning -v ON_ERROR_STOP=1 -P pager=off -f"}
 SELECT coldfront.release_iceberg_table('public', 'orders');
@@ -692,7 +721,7 @@ SELECT coldfront.adopt_iceberg_table('public', 'orders', 'lake',
 SELECT order_id, meta->>'tier' AS tier FROM orders ORDER BY order_id;
 ```
 
-### Hand it back
+### Hand It Back
 
 Release removes the view and the registry row and performs no Iceberg I/O, so
 the table keeps every row and stays in the catalog:
@@ -703,17 +732,17 @@ SELECT coldfront.release_iceberg_table('public', 'orders');
 
 Two things to take from this demo. A `VARCHAR` column comes back as text rather
 than as `jsonb` unless `p_types` says otherwise, because Iceberg records no
-PostgreSQL type. And the bakery serializes ColdFront's own writers, not an
-external engine writing the same table.
+PostgreSQL type. The bakery serializes ColdFront's own writers, not an external
+engine writing the same table.
 
-## Demo 3: standalone partitioner
+## Demo 3: Standalone Partitioner
 
 The partitioner binary manages PostgreSQL range partitions without any cold
 tier. If all you need is automated partition maintenance on stock PostgreSQL,
 the partitioner is the whole product - no Iceberg, no DuckDB, no archiver cold
 path.
 
-### Create the demo table
+### Create the Demo Table
 
 Create a partitioned table with no existing partitions:
 
@@ -728,7 +757,7 @@ CREATE TABLE part_demo (
 ) PARTITION BY RANGE (ts);
 ```
 
-### Register and reconcile
+### Register and Reconcile
 
 Register the table with the partitioner (monthly period, 12-month retention)
 and run a reconcile pass. Both commands run inside the Compose network against
@@ -773,7 +802,7 @@ archiver:
           retention_period: 12 months
 ```
 
-### Verify the partitions
+### Verify the Partitions
 
 Each reconcile pass premakes the next three monthly partitions ahead of now and
 ensures a partition covering today always exists. It also drops any partition
@@ -785,7 +814,7 @@ FROM pg_inherits
 WHERE inhparent = 'part_demo'::regclass;
 ```
 
-## Demo 4: distributed
+## Demo 4: Distributed
 
 Distributed mode points two or more PostgreSQL nodes at the *same* lake. The
 nodes form an active-active [Spock](https://github.com/pgEdge/spock) mesh; the
@@ -811,7 +840,7 @@ bash examples/walkthrough/guide.sh   # then choose: 4) Distributed
 The sections below show what that option does, so you can follow along or
 reproduce it by hand.
 
-### Bring up the two-node mesh
+### Bring Up the Two-Node Mesh
 
 Start the mesh stack, then form the Spock mesh - create a node on each member,
 subscribe each to the other, and set up the cold-write coordination on both.
@@ -826,7 +855,7 @@ If port 5442, 5443, 8191, or 8343 is already in use on your host, set
 or `COLDFRONT_MESH_S3_PORT` before `up`.
 
 Next, run the `curl` block from
-[What setup does](walkthrough.md#what-setup-does) with port 8191 in place
+[What Setup Does](walkthrough.md#what-setup-does) with port 8191 in place
 of 8181. That creates the `wh` warehouse and `public` namespace on the mesh's
 own Lakekeeper.
 
@@ -870,7 +899,7 @@ nodes - never the table data, which stays in the lake. The `set_storage_secret`
 call is what lets each node's DuckDB write Parquet to the shared object store;
 without it, cold writes fail to authenticate.
 
-### See the mesh
+### See the Mesh
 
 Both nodes are present, each subscribed to the other:
 
@@ -879,7 +908,7 @@ SELECT node_name FROM spock.node ORDER BY node_name;   -- db1, db2
 SELECT sub_name  FROM spock.subscription;              -- one per node
 ```
 
-### Write on one node, read on the other
+### Write on One Node, Read on the Other
 
 Create a lake-native table on `db1` and register it on `db2` as well (the call
 is idempotent and the registry is keyed by name, so each node ends up with an
@@ -913,7 +942,7 @@ FROM pg_class WHERE relname = 'events_lake';   -- v, 0 bytes
 reads straight from the shared lake. That is the point of distributed mode: add
 a node for compute over one copy of the data, with no storage to replicate.
 
-### Concurrent writes serialize (the bakery)
+### Concurrent Writes Serialize (The Bakery)
 
 Two nodes committing the same Iceberg table at once would normally collide -
 the catalog rejects the second commit with a `409 Conflict` and the application
@@ -932,7 +961,7 @@ INSERT INTO events_lake VALUES (301, now(), 'held', '{"n":"db1"}');
 ```
 
 In a second session, the claim is on `db1`, keyed by a ticket that also names
-the issuing node (a snowflake id), and it is already on `db2`: the claim is
+the issuing node (a Snowflake id), and it is already on `db2`: the claim is
 written over its own connection and committed at once, so it replicates while
 the transaction that took it is still open:
 

From be0dd190fecb80f2aafe2e5df4b04792979924ea Mon Sep 17 00:00:00 2001
From: Jimmy Angelakos <jimmy@pgedge.com>
Date: Thu, 1 Oct 2026 17:10:37 +0100
Subject: [PATCH 2/3] docs: finish the pgEdge docs style pass and wrap every
 tracked doc at 79 columns

---
 .claude/agents/golang-expert.md    |   3 +-
 .claude/agents/postgres-expert.md  |   7 +-
 .claude/agents/security-auditor.md |   9 +-
 .github/PULL_REQUEST_TEMPLATE.md   |   6 +-
 LICENSE.md                         |  20 +-
 README.md                          | 151 ++++++--
 THIRD_PARTY_NOTICES.md             |  50 +--
 docs/LICENSE.md                    |  16 +-
 docs/architecture.md               | 400 +++++++++++----------
 docs/architecture_decoupled.md     | 535 ++++++++++++++++------------
 docs/architecture_tiered.md        | 298 +++++++++-------
 docs/architecture_vectors.md       | 347 ++++++++++--------
 docs/changelog.md                  | 225 ++++++------
 docs/compaction.md                 |  95 +++--
 docs/formal/README.md              | 365 ++++++++++---------
 docs/index.md                      |  38 +-
 docs/installation.md               | 139 +++++---
 docs/object_store.md               | 145 ++++----
 docs/usage.md                      | 550 ++++++++++++++++++-----------
 docs/usage_vectors.md              | 237 +++++++++----
 docs/walkthrough.md                |  37 +-
 docs/walkthrough_demos.md          | 166 +++++----
 22 files changed, 2282 insertions(+), 1557 deletions(-)

diff --git a/.claude/agents/golang-expert.md b/.claude/agents/golang-expert.md
index 33cacae..71f029d 100644
--- a/.claude/agents/golang-expert.md
+++ b/.claude/agents/golang-expert.md
@@ -26,7 +26,8 @@ You are a Go development specialist for ColdFront.
 ## Testing Approach
 
 - Table-driven tests preferred
-- Integration tests with a real database (the `ci/journey.sh` harness), not mocks
+- Integration tests with a real database (the `ci/journey.sh` harness), not
+  mocks
 - Hand-written mocks defined locally in test files when a unit needs one
 - Test files next to the code they test
 - Use `t.Helper()` in test utilities
diff --git a/.claude/agents/postgres-expert.md b/.claude/agents/postgres-expert.md
index e2c338b..2368dc8 100644
--- a/.claude/agents/postgres-expert.md
+++ b/.claude/agents/postgres-expert.md
@@ -23,11 +23,12 @@ You are a PostgreSQL specialist for ColdFront.
 - Index naming: `idx_{table}_{column}`
 - Constraint naming: `chk_`, `fk_`, `{table}_{cols}_unique`
 - `COMMENT ON` for schema objects
-- Parameterized queries only; interpolate only sanitized identifiers, never values
+- Parameterized queries only; interpolate only sanitized identifiers, never
+  values
 - pgerrcode for error classification
 - Idempotent migrations (`IF NOT EXISTS`)
-- NEVER write plpgsql `EXCEPTION`/`SAVEPOINT` in the cold path — pg_duckdb rejects
-  subtransactions; use precondition checks instead
+- NEVER write plpgsql `EXCEPTION`/`SAVEPOINT` in the cold path — pg_duckdb
+  rejects subtransactions; use precondition checks instead
 
 ## Replication Safety
 
diff --git a/.claude/agents/security-auditor.md b/.claude/agents/security-auditor.md
index bddede5..48e01b2 100644
--- a/.claude/agents/security-auditor.md
+++ b/.claude/agents/security-auditor.md
@@ -17,11 +17,14 @@ You are a security specialist for ColdFront.
 
 ## Standards
 
-- No hardcoded secrets (use config / environment variables / DuckDB persistent secrets)
-- No real hostnames, buckets, accounts, keys, or paths in committed code, tests, docs, or commit messages
+- No hardcoded secrets (use config / environment variables / DuckDB persistent
+  secrets)
+- No real hostnames, buckets, accounts, keys, or paths in committed code,
+  tests, docs, or commit messages
 - Parameterized queries; never concatenate values into SQL
 - Input validation at all boundaries
 - gitleaks must pass (no committed secrets)
 - gosec findings must be addressed
 - Principle of least privilege for database connections and app roles
-  (`grant_app_access`, the SECURITY DEFINER attach helpers, PGC_SUSET config GUCs)
+  (`grant_app_access`, the SECURITY DEFINER attach helpers, PGC_SUSET config
+  GUCs)
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 56479da..3562339 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,10 +4,12 @@
 
 ## Checklist
 
-- [ ] `./run-ci-local.sh` passes (gofmt, golangci-lint, build, pg_regress, journey)
+- [ ] `./run-ci-local.sh` passes (gofmt, golangci-lint, build, pg_regress,
+  journey)
 - [ ] Tests added/updated (test-first)
 - [ ] Docs updated where applicable (README / USAGE / INSTALL / ARCHITECTURE)
-- [ ] Bakery / mesh / distributed changes: TLA+ model updated and TLC re-checked (`docs/formal/`)
+- [ ] Bakery / mesh / distributed changes: TLA+ model updated and TLC
+  re-checked (`docs/formal/`)
 - [ ] Commit messages are short and imperative
 
 ## Related issues
diff --git a/LICENSE.md b/LICENSE.md
index bd01495..dc796f4 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -2,12 +2,24 @@ The PostgreSQL License
 
 Portions copyright (c) 2026, pgEdge, Inc.
 
-Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies.
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose, without fee, and without a written agreement is
+hereby granted, provided that the above copyright notice and this paragraph and
+the following two paragraphs appear in all copies.
 
-IN NO EVENT SHALL pgEdge, Inc. BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF pgEdge, Inc. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+IN NO EVENT SHALL pgEdge, Inc. BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
+SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING
+OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF pgEdge, Inc. HAS
+BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-pgEdge, Inc. SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND pgEdge, Inc. HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
+pgEdge, Inc. SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND pgEdge,
+Inc. HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS,
+OR MODIFICATIONS.
 
 ---
 
-This software redistributes third-party components under their own licenses (DuckDB, pg_duckdb, duckdb-iceberg, and others). Those copyright and license notices are reproduced in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+This software redistributes third-party components under their own licenses
+(DuckDB, pg_duckdb, duckdb-iceberg, and others). Those copyright and license
+notices are reproduced in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
diff --git a/README.md b/README.md
index 3c8d8e1..4aca500 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,40 @@
 # pgEdge ColdFront
 
-> [!WARNING]
-> ColdFront is beta software under active development. Do not use it in
-> production. Interfaces, on-disk formats, and behavior may change without
-> notice, and data loss is possible.
-
 [![CI](https://github.com/pgEdge/ColdFront/actions/workflows/ci.yml/badge.svg)](https://github.com/pgEdge/ColdFront/actions/workflows/ci.yml)
 
+## Table of Contents
+
+The ColdFront documentation consists of the following guides:
+
+- [Introduction](docs/index.md)
+- Getting Started
+    - [Running the Walkthrough](docs/walkthrough.md)
+    - [Exploring the Walkthrough Demos](docs/walkthrough_demos.md)
+    - [Building ColdFront from Source](docs/installation.md)
+    - [Setting Up an Object Store](docs/object_store.md)
+- Architecture
+    - [Architecture Overview](docs/architecture.md)
+    - [Tiered Mode](docs/architecture_tiered.md)
+    - [Decoupled Mode](docs/architecture_decoupled.md)
+    - [Vector Storage](docs/architecture_vectors.md)
+- [Using ColdFront](docs/usage.md)
+- [Storing and Searching Embeddings](docs/usage_vectors.md)
+- [Compacting the Cold Tier](docs/compaction.md)
+- Developer Resources
+    - [Verifying the Bakery Protocol](docs/formal/README.md)
+- [Release Notes](docs/changelog.md)
+
 ColdFront keeps tables in PostgreSQL and cold data in Apache Iceberg (Parquet
 on S3-compatible, Azure, or GCS storage), and the cold tier is both readable
 and writable through the same SQL with no application changes. The application
 queries every table as an ordinary PostgreSQL relation, and both operating
 modes present the same standard SQL surface.
 
+> [!WARNING]
+> ColdFront is beta software under active development. Do not use it in
+> production. Interfaces, on-disk formats, and behavior may change without
+> notice, and data loss is possible.
+
 ColdFront provides two operating modes:
 
 - Tiered mode keeps recent data in native PostgreSQL partitions and archives
@@ -65,11 +87,13 @@ tier, so the application sees one relation:
 
 ## Installation
 
-New here? Run the [guided walkthrough](docs/walkthrough.md) to see all three
-modes in action with copy-pasteable commands.
+If you are new to ColdFront, run the [guided walkthrough](docs/walkthrough.md)
+to see all three modes in action with copy-pasteable commands.
 
-ColdFront is open source under the PostgreSQL License and runs on stock
-PostgreSQL 16, 17, and 18. The full build workflow lives in the
+ColdFront is open source under the PostgreSQL License and runs on PostgreSQL
+16, 17, and 18: stock PostgreSQL for a single node, and pgEdge's PostgreSQL
+build with Spock, which the Docker image is based on, for distributed mode. The
+full build workflow lives in the
 **[Installation guide](docs/installation.md)**: build the thin ColdFront layer
 on top of the published DuckDB 1.5.x base image (or build the base yourself),
 or install bare-metal. Then continue with the Quickstart below.
@@ -79,13 +103,27 @@ or install bare-metal. Then continue with the Quickstart below.
 Once the image is built, the **[S3 setup guide](docs/object_store.md)** takes
 you from an empty bucket to a working cold tier end-to-end.
 
+## Configuration
+
+ColdFront reads its settings from two places. The server settings live in
+`postgresql.conf`: `shared_preload_libraries = 'pg_duckdb,coldfront'`,
+`coldfront.warehouse` and `coldfront.lakekeeper_endpoint`, plus
+`snowflake.node` and `coldfront.dblink_self` on every node of a mesh. The
+Docker image writes them on first start. The archiver, partitioner, and
+compactor read a deployment YAML, modeled on
+[config.example.yaml](config.example.yaml), for the database DSN, the Iceberg
+catalog, and the cold-store credentials, and each table's lifecycle lives in
+`coldfront.partition_config`. For every setting, see
+[Using ColdFront → One-Time Setup](docs/usage.md#one-time-setup) and
+[Tuning Knobs](docs/usage.md#tuning-knobs).
+
 ## Quickstart
 
 Build the image (see the [Installation](docs/installation.md) guide) and bring
 up the stack:
 
 ```bash
-docker compose up -d --build
+docker compose --profile local-store up -d --build
 ```
 
 Bootstrap Lakekeeper and create a warehouse (see the one-time setup in the
@@ -120,21 +158,31 @@ For compliance environments that cannot store an object-store credential,
 database: Lakekeeper issues short-lived per-table credentials at access time.
 See [Vended Credentials](docs/usage.md#vended-credentials).
 
+## Using ColdFront
+
+The Quickstart covers a decoupled table from start to finish. The
+[Using ColdFront](docs/usage.md) guide covers both modes in depth, the
+standalone partition manager and its CLI, the storage backends, and the
+distributed setup; the [walkthrough demos](docs/walkthrough_demos.md) run each
+mode on a sample table.
+
 ## Documentation
 
 The following table lists the ColdFront guides and what each one covers:
 
 | Doc | Contents |
 |---|---|
-| **[Embeddings](docs/usage_vectors.md)** | Storing and searching embeddings with the pgvector interface |
-| **[Usage](docs/usage.md)** | Day-to-day use - both modes plus the standalone partition manager, one-time setup, reading/writing, supported types, the partition CLI, storage backends, distributed (mesh) setup, tuning |
-| **[Installation](docs/installation.md)** | Build from source (Docker or bare-metal); Testing & CI |
-| **[Object store setup](docs/object_store.md)** | Get ColdFront running on cloud S3 (virtual-hosted), end-to-end |
-| **[Compaction](docs/compaction.md)** | Cold-tier table maintenance - compaction, snapshot expiry, orphan-file removal |
-| **[Architecture](docs/architecture.md)** | Shared architecture and core mechanics |
-| **[Architecture: tiered](docs/architecture_tiered.md)** | Tiered (hot PG + cold Iceberg) deep dive |
-| **[Architecture: decoupled](docs/architecture_decoupled.md)** | Decoupled (iceberg-only) deep dive |
-| **[Architecture: vectors](docs/architecture_vectors.md)** | Vector storage internals - type mapping, routing state, cluster assignment, layout |
+| [Walkthrough](docs/walkthrough.md) | Sets up the demo stack and runs ColdFront hands-on. |
+| [Walkthrough demos](docs/walkthrough_demos.md) | Walks through the tiered, decoupled, partitioner, and distributed demos. |
+| [Embeddings](docs/usage_vectors.md) | Covers storing and searching embeddings with the pgvector interface. |
+| [Usage](docs/usage.md) | Covers day-to-day use: both modes plus the standalone partition manager, one-time setup, reading and writing, supported types, the partition CLI, storage backends, distributed (mesh) setup, and tuning. |
+| [Installation](docs/installation.md) | Covers building from source (Docker or bare-metal), and testing and CI. |
+| [Object store setup](docs/object_store.md) | Gets ColdFront running on cloud S3 (virtual-hosted), end to end. |
+| [Compaction](docs/compaction.md) | Covers cold-tier table maintenance: compaction, snapshot expiry, and orphan-file removal. |
+| [Architecture](docs/architecture.md) | Describes the shared architecture and core mechanics. |
+| [Architecture: tiered](docs/architecture_tiered.md) | Describes tiered mode (hot PG plus cold Iceberg) in depth. |
+| [Architecture: decoupled](docs/architecture_decoupled.md) | Describes decoupled (iceberg-only) mode in depth. |
+| [Architecture: vectors](docs/architecture_vectors.md) | Describes vector storage internals: type mapping, routing state, cluster assignment, and layout. |
 
 ## Least-Privilege Application Roles
 
@@ -147,8 +195,10 @@ SELECT coldfront.grant_app_access('alice');
 ```
 
 grant_app_access grants only the minimum the cold path needs: membership in
-duckdb.postgres_role, schema USAGE, SELECT on the registry, and DML on every
-registered view and the hot table and sequences behind it. Those objects are
+duckdb.postgres_role, SET on the duckdb.unsafe_allow_execution_inside_functions
+parameter, schema USAGE, SELECT on the registry and the watermark table, DML on
+the dual-write anchor table, DML on every registered view and the hot table
+behind it, and USAGE and SELECT on the hot table's sequences. Those objects are
 derived from the registry, not hardcoded, and the call also grants EXECUTE on a
 fixed allow-list of runtime cold-path functions. The call is idempotent and is
 not executable by PUBLIC, so an application role can never self-grant. The role
@@ -156,10 +206,16 @@ is never granted pg_read_server_files or pg_write_server_files, so it has no
 host-file access. CREATE ROLE and GRANT both replicate over Spock, so you
 onboard a role once on any node and it propagates across the mesh.
 
-For how the non-superuser path works under the hood - the `SECURITY DEFINER`
-attach helpers, the `PGC_SUSET` / `GUC_SUPERUSER_ONLY` config hardening, the
-turnkey `duckdb.postgres_role` default, and how least privilege holds across a
-Spock mesh - see
+The Docker image sets `duckdb.postgres_role` to `coldfront_duckdb` and creates
+that role when it initializes a new data directory. To name a different role,
+set the container's `COLDFRONT_DUCKDB_ROLE` environment variable before that
+first start. An empty value keeps pg_duckdb's default, under which only
+superusers run DuckDB, so grant_app_access then fails with an error.
+
+For how the non-superuser path works - the `SECURITY DEFINER` attach helpers,
+the `PGC_SUSET` / `GUC_SUPERUSER_ONLY` config hardening, the
+`duckdb.postgres_role` default that the image sets up, and how least privilege
+holds across a Spock mesh - see
 [Architecture: non-superuser app roles](docs/architecture.md#non-superuser-app-roles-least-privilege).
 
 ## Caveats
@@ -198,17 +254,19 @@ pgedge-coldfront/
 │   ├── topo/                   ← vanilla.sh (1 node) · mesh.sh (3-node Spock)
 │   └── runbooks/               ← failover-patroni.md (failover delegated to Patroni)
 ├── docker/
-│   ├── Dockerfile.duckdb15-base ← DuckDB 1.5.x base (pg_duckdb 1.5.4 + patched iceberg)
+│   ├── Dockerfile.duckdb15-base ← DuckDB 1.5.x base (pg_duckdb on DuckDB 1.5.4 + patched iceberg)
 │   ├── Dockerfile.duckdb15      ← thin coldfront app layer (ARG PG_MAJOR=16|17|18)
 │   ├── iceberg-*.patch          ← duckdb-iceberg patches (bakery commit-refresh + strict-reader interop)
 │   ├── iceberg-azure-extension-config-v15.cmake ← Azure ADLS extension build config
 │   ├── entrypoint.sh
 │   └── seaweedfs-s3.json        ← SeaweedFS S3 auth config (example)
 ├── docs/                       ← MkDocs site (user docs; mkdocs.yml at repo root)
-│   ├── index.md · installation.md · object_store.md · usage.md · compaction.md
+│   ├── index.md · walkthrough.md · walkthrough_demos.md · installation.md
+│   ├── object_store.md · usage.md · compaction.md
 │   ├── architecture.md · architecture_tiered.md · architecture_decoupled.md
 │   ├── architecture_vectors.md · usage_vectors.md · changelog.md
 │   └── formal/                 ← TLA+ model of the bakery protocol (Bakery.tla)
+├── examples/walkthrough/       ← interactive walkthrough (guide.sh, its compose stack and configs)
 ├── docker-compose.yml          ← END-USER single-node stack (ports published)
 ├── docker-compose.matrix.yml   ← CI only: single-node vanilla matrix
 ├── docker-compose.matrix-azure.yml ← CI only: vanilla matrix on Azure ADLS
@@ -226,11 +284,12 @@ The following table lists the services and components ColdFront runs against:
 
 | Component | Version | Purpose |
 |-----------|---------|---------|
-| PostgreSQL | 16, 17, or 18 | Database with native partitioning (stock upstream; no fork) |
-| pg_duckdb | 1.5.4 (PR #1025) | Iceberg reads + writes via DuckDB in-process |
-| duckdb-iceberg | `v1.5-variegata` @ `5edc45f0`, patched | Iceberg catalog/IO for DuckDB; carries ColdFront's four patches (see [docker/Dockerfile.duckdb15-base](docker/Dockerfile.duckdb15-base)) |
-| Lakekeeper | latest | Iceberg REST catalog (Rust binary) |
-| S3-compatible store | any | SeaweedFS, MinIO, GCS, Azure Blob, etc. |
+| PostgreSQL | 16, 17, or 18 | Provides the database with native partitioning; stock PostgreSQL serves a single node, and the Docker image and distributed mode use pgEdge's PostgreSQL build with Spock. |
+| pg_duckdb | commit c04e6a2 (PR #1025), on DuckDB 1.5.4 | Runs Iceberg reads and writes through in-process DuckDB. |
+| duckdb-iceberg | `v1.5-variegata` @ `5edc45f0`, patched | Provides Iceberg catalog and I/O for DuckDB, with ColdFront's four patches applied (see [docker/Dockerfile.duckdb15-base](docker/Dockerfile.duckdb15-base)). |
+| Lakekeeper | latest | Provides the Iceberg REST catalog (a Rust binary). |
+| S3-compatible store | any | Stores the cold data; SeaweedFS, MinIO, AWS S3, and GCS all work. |
+| Azure ADLS Gen2 | any | Stores the cold data instead of an S3 store, through `set_storage_secret_azure` and an `adls` warehouse. |
 
 Building from source needs the Go toolchain (the version is pinned in
 [go.mod](go.mod)). The Go module dependencies are the source of truth in
@@ -240,7 +299,7 @@ static, CGO-free binaries on `pgx/v5`, and the compactor is a separate module
 
 ## Versioning
 
-ColdFront carries two independent version numbers, each following its own
+ColdFront has two independent version numbers, each following its own
 convention:
 
 - Release tags use three-part [Semantic Versioning](https://semver.org)
@@ -249,21 +308,35 @@ convention:
   required because ColdFront is a Go module, and the toolchain recognizes only
   full `vX.Y.Z` tags as releases. The patch field keeps a bugfix-only release
   (`v1.0.1`) distinct from a feature release (`v1.1.0`), which matters for a
-  data-writing extension where "same behavior, one safety fix" is worth stating
-  plainly.
+  data-writing extension, where a release that keeps the same behavior and adds
+  one safety fix must be easy to recognize.
 - The PostgreSQL extension uses the conventional two-part version in its
   control file (`default_version = '1.0'`) and upgrade-script filenames
   (`coldfront--1.0--1.1.sql`), as is standard for PostgreSQL extensions.
 
 The two map cleanly: extension `1.0` ships inside release `v1.0.0`, and a patch
-release may carry the same extension version or bump it with an upgrade script
+release may keep the same extension version or bump it with an upgrade script
 when the SQL changes.
 
+## Support & Resources
+
+For more information about pgEdge products, visit
+[docs.pgedge.com](https://docs.pgedge.com).
+
+To report an issue with the software, visit
+[GitHub Issues](https://github.com/pgEdge/ColdFront/issues).
+
+## Contributing
+
+We welcome your project contributions; for more information, see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Author
 
-Created by Jimmy Angelakos.
+Jimmy Angelakos created ColdFront.
 
 ## License
 
-PostgreSQL License. See [LICENSE.md](LICENSE.md). Redistributed third-party
-components and their notices: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+This project is licensed under the [PostgreSQL License](LICENSE.md). The
+redistributed third-party components and their notices are listed in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 14226d5..9cf8a0e 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -11,22 +11,23 @@ Copyright © Stichting DuckDB Foundation — **DuckDB** (2018-2025), **pg_duckdb
 **postgres_scanner** extensions. duckdb-iceberg is modified by ColdFront
 (`docker/iceberg-bakery-aware-commit-refresh-v15.patch`).
 
-> Permission is hereby granted, free of charge, to any person obtaining a copy of
-> this software and associated documentation files (the "Software"), to deal in the
-> Software without restriction, including without limitation the rights to use,
-> copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
-> Software, and to permit persons to whom the Software is furnished to do so,
-> subject to the following conditions:
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
 >
-> The above copyright notice and this permission notice shall be included in all
-> copies or substantial portions of the Software.
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
 >
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-> FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-> COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
-> AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-> WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
 
 ## PostgreSQL License
 
@@ -43,17 +44,18 @@ client is httplib). It is distributed under the curl License:
 > Copyright (C) Daniel Stenberg, daniel@haxx.se, and many contributors.
 >
 > Permission to use, copy, modify, and distribute this software for any purpose
-> with or without fee is hereby granted, provided that the above copyright notice
-> and this permission notice appear in all copies.
+> with or without fee is hereby granted, provided that the above copyright
+> notice and this permission notice appear in all copies.
 >
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-> FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT
-> SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
-> OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-> SOFTWARE.
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS.
+> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+> DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+> OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+> OR OTHER DEALINGS IN THE SOFTWARE.
 >
-> Except as contained in this notice, the name of a copyright holder shall not be
-> used in advertising or otherwise to promote the sale, use or other dealings in
-> this Software without prior written authorization of the copyright holder.
+> Except as contained in this notice, the name of a copyright holder shall not
+> be used in advertising or otherwise to promote the sale, use or other
+> dealings in this Software without prior written authorization of the
+> copyright holder.
diff --git a/docs/LICENSE.md b/docs/LICENSE.md
index 94cd706..944fbc3 100644
--- a/docs/LICENSE.md
+++ b/docs/LICENSE.md
@@ -2,8 +2,18 @@ The PostgreSQL License
 
 Portions copyright (c) 2026, pgEdge, Inc.
 
-Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies.
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose, without fee, and without a written agreement is
+hereby granted, provided that the above copyright notice and this paragraph and
+the following two paragraphs appear in all copies.
 
-IN NO EVENT SHALL pgEdge, Inc. BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF pgEdge, Inc. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+IN NO EVENT SHALL pgEdge, Inc. BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
+SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING
+OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF pgEdge, Inc. HAS
+BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-pgEdge, Inc. SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND pgEdge, Inc. HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
+pgEdge, Inc. SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND pgEdge,
+Inc. HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS,
+OR MODIFICATIONS.
diff --git a/docs/architecture.md b/docs/architecture.md
index d94e6c6..08be941 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -20,18 +20,19 @@ is selected:
 
 | Axis | Values | Selected by |
 |---|---|---|
-| **Storage mode** | **Tiered** - hot PG heap + cold Iceberg, unified by a `UNION ALL` view; an archiver moves rows hot→cold on a cron. · **Decoupled** - the table lives entirely in Iceberg; PG holds only a wrapper view + a registry row (no archiver, no PG storage, no watermark). | Per relation at creation, via the `is_iceberg_only` flag on `coldfront.tiered_views` (short-circuited in the hook's `classify_tier()`). |
-| **Topology** | **Vanilla** - single node; `spock`/`snowflake` not loaded; cold writes serialize on a local advisory lock. · **Mesh** - 3-node pgEdge Spock active-active; cold writes serialize cluster-wide via the bakery protocol. | Whether `spock`/`snowflake` are in `shared_preload_libraries`. One image and one SQL surface serve both; the `_exec_iceberg_with_claim` chokepoint self-selects via its `v_armed` gate. |
-| **Write mode** | **Permissive** (default) - an ambiguous cross-tier `UPDATE`/`DELETE` writes both tiers. · **Strict** - it is rejected with a hint. | `coldfront.allow_mixed_writes` (USERSET). |
+| Storage mode | In tiered mode, a `UNION ALL` view unifies the hot PG heap and cold Iceberg, and an archiver moves rows from hot to cold on a cron. In decoupled mode, the table lives entirely in Iceberg, and PG holds only a wrapper view and a registry row (no archiver, no PG storage, no watermark). | The `is_iceberg_only` flag on `coldfront.tiered_views` selects the mode per relation at creation, and the hook's `classify_tier()` short-circuits on that flag. |
+| Topology | In a vanilla topology (a single node, with `spock`/`snowflake` not loaded), cold writes serialize on a local advisory lock. In a mesh (3-node pgEdge Spock active-active), cold writes serialize cluster-wide via the bakery protocol. | The topology follows whether `spock`/`snowflake` are in `shared_preload_libraries`. One image and one SQL surface serve both. The serializer follows `coldfront._bakery_armed()`: the bakery when both `snowflake.node` and `coldfront.dblink_self` are set, and a local advisory lock otherwise; the image sets both only when `MESH=on`. |
+| Write mode | In permissive mode (the default), an ambiguous cross-tier `UPDATE`/`DELETE` writes both tiers. In strict mode, such a statement is rejected with a hint. | `coldfront.allow_mixed_writes` (USERSET) selects the write mode. |
 
 Both storage modes coexist in one database and share **one** code path: the
 transparent view and read rewriter, the INSERT/UPDATE/DELETE hook (`emit_cold`
 / `emit_hot` / `emit_dual` in
 [`extension/coldfront/src/coldfront.c`](https://github.com/pgEdge/ColdFront/blob/main/extension/coldfront/src/coldfront.c)),
-and the `_exec_iceberg_with_claim` write chokepoint. Decoupled mode always
-classifies as `TIER_COLD` and never reaches `emit_hot`; vanilla and mesh differ
-only in how that chokepoint serializes cold writes. This document covers the
-shared mechanics and the tiered path; see
+and the per-table claim (`coldfront._take_iceberg_claim`) that every cold write
+path in the hook takes, mostly through `_exec_iceberg_with_claim`. Decoupled
+mode always classifies as `TIER_COLD` and never reaches `emit_hot`; vanilla and
+mesh differ only in how that claim serializes cold writes. This document covers
+the shared mechanics and the tiered path; see
 [architecture_decoupled.md](architecture_decoupled.md) for the decoupled mode's
 ACID model and distributed scaling story.
 
@@ -41,15 +42,16 @@ Orthogonal to the three axes above, any ColdFront node - vanilla or a mesh
 member - can have one or more **physical (streaming) standbys that serve
 read-only cross-tier reads**. The hot tier arrives by physical replication; the
 cold tier is read by `iceberg_scan` executing on the read-only backend. A base
-backup carries everything a replica needs - the coldfront catalog
-(`tiered_views`, `archive_watermark`, `storage_secret`), the DuckDB persistent
-S3 secret (loaded at instance init), and the GUCs (in `postgresql.conf`, not
-`ALTER SYSTEM`) - so a replica is byte-identical to its primary (same OIDs)
-with zero extra setup. Cold **writes** are refused on a standby: every cold
-write funnels through `_exec_iceberg_with_claim`, which raises when
-`pg_is_in_recovery()`, so a read replica can never become an uncoordinated
-writer to the shared Iceberg table (hot writes hit a PG heap and PG rejects
-them natively).
+backup contains the coldfront catalog (`tiered_views`, `archive_watermark`,
+`storage_secret`) and the GUCs (in `postgresql.conf`, not `ALTER SYSTEM`), so a
+replica is byte-identical to its primary (same OIDs). The DuckDB persistent
+secret file sits under the OS user's home directory, outside PGDATA, so with
+static credentials run `SELECT coldfront.materialize_storage_secret()` once on
+the replica. Cold **writes** are refused on a standby: every cold write path in
+the hook calls `coldfront._reject_on_standby`, which raises when
+`pg_is_in_recovery()`, before it takes the claim, so a read replica can never
+become an uncoordinated writer to the shared Iceberg table (hot writes hit a PG
+heap and PG rejects them natively).
 
 Standby reads are gated by
 [`ci/probe-standby.sh`](https://github.com/pgEdge/ColdFront/blob/main/ci/probe-standby.sh)
@@ -93,12 +95,12 @@ The following table describes each component, its role, and its license:
 
 | Component | Role | License |
 |-----------|------|---------|
-| PostgreSQL 16+ | Heap storage; range partitioning for the tiered hot tier. Works uniformly on PG 16, 17, and 18 - the cold-tier secret is a DuckDB persistent secret loaded at instance init, with no version-gated mechanism. | PostgreSQL |
-| pg_duckdb | DuckDB in-process. Iceberg read + write. Analytics. pg_duckdb 1.5.4 (PR #1025). The `duckdb-iceberg` carries the bakery-aware commit-refresh patch (async parquet overlap, no 409); see [Cold-Write Strategy](#cold-write-strategy-stock-vs-patched-duckdb-iceberg). | MIT |
-| coldfront | PGXS C extension. `post_parse_analyze_hook` rewrites INSERT/UPDATE/DELETE on registered views to the correct tier and, on a SELECT DuckDB will run, the spellings DuckDB lacks (`date_bin`, `::jsonb`, the JSON builders); `planner_hook` folds bound parameters into such a read; `ProcessUtility_hook` handles DDL; the hook lazily ATTACHes the Iceberg catalog on the first query touching a tiered view. | PostgreSQL |
-| Lakekeeper | Iceberg REST catalog. Single Rust binary. | Apache 2.0 |
-| S3-compatible store | Any: SeaweedFS, MinIO, GCS, Azure Blob, etc. | Varies |
-| Archiver (tiered mode) | Go binary, invoked by cron. Thin SQL orchestrator that moves rows hot→cold. | PostgreSQL |
+| PostgreSQL 16+ | Provides heap storage and range partitioning for the tiered hot tier. ColdFront works uniformly on PG 16, 17, and 18, because the cold-tier secret is a DuckDB persistent secret loaded at instance init, with no version-gated mechanism. | PostgreSQL |
+| pg_duckdb | Runs DuckDB in-process for Iceberg reads, writes, and analytics; the build is pg_duckdb at commit c04e6a2 (PR #1025) on DuckDB 1.5.4. The bundled `duckdb-iceberg` includes the bakery-aware commit-refresh patch (async parquet overlap, no 409); see [Cold-Write Strategy](#cold-write-strategy-stock-vs-patched-duckdb-iceberg). | MIT |
+| coldfront | This PGXS C extension's `post_parse_analyze_hook` rewrites INSERT/UPDATE/DELETE on registered views to the correct tier and, on a SELECT DuckDB will run, the spellings DuckDB lacks (`date_bin`, `::jsonb`, the JSON builders); `planner_hook` folds bound parameters into such a read; `ProcessUtility_hook` handles DDL; the hook lazily ATTACHes the Iceberg catalog on the first query touching a tiered view. | PostgreSQL |
+| Lakekeeper | Provides the Iceberg REST catalog as a single Rust binary. | Apache 2.0 |
+| S3-compatible store or Azure ADLS Gen2 | Stores the cold data; any S3-compatible store works, including SeaweedFS, MinIO, AWS S3, and GCS, and Azure ADLS Gen2 works through `set_storage_secret_azure`. | Varies |
+| Archiver (tiered mode) | Moves rows from hot to cold; this Go binary is a thin SQL orchestrator that cron invokes. | PostgreSQL |
 
 How rows move through this depends on the storage mode: the tiered hot heap +
 archiver + `UNION ALL` data-flow is in
@@ -118,15 +120,20 @@ credentials and materializes a DuckDB persistent secret:
 
 ```sql
 SELECT coldfront.set_storage_secret('<key>', '<secret>', '<endpoint>');
+-- Azure ADLS Gen2 instead of an S3-compatible store:
+SELECT coldfront.set_storage_secret_azure('<connection string>');
 ```
 
-This does two things. (1) It stores the secret in the
+`set_storage_secret` does two things. (1) The function stores the secret in the
 `coldfront.storage_secret` table - an extension-member table, so its data is
 excluded from `pg_dump` by default, and it is added to the Spock replication
 set, so the secret replicates **by value** to every mesh node with no per-node
-file syncing. (2) It materializes a DuckDB **persistent secret**, which DuckDB
-loads automatically at instance init - so every backend, including the first
-fresh one, sees the secret at a committed timestamp before any query runs.
+file syncing. (2) The function materializes a DuckDB **persistent secret**,
+which DuckDB loads automatically at instance init - so every backend, including
+the first fresh one, sees the secret at a committed timestamp before any query
+runs. `set_storage_secret_azure` takes one connection string holding the
+account name, account key and endpoint suffix, writes the same row, and
+materializes a `TYPE azure` persistent secret.
 
 For deployments that must not store a credential at all,
 `coldfront.set_storage_secret_vended()` records a vended
@@ -143,27 +150,28 @@ per-table secret inside the commit transaction.
 For backup and restore (`pg_dump`), the durable tiering metadata -
 `coldfront.tiered_views` (registry), `archive_watermark` (cutoffs) and
 `partition_config` - is marked with `pg_extension_config_dump`, so a logical
-`pg_dump` carries it and a restore re-attaches to the **same** Iceberg cold
+`pg_dump` includes it and a restore re-attaches to the **same** Iceberg cold
 tier with no re-provisioning. Two things are deliberately **not** dumped: the
 credential (`coldfront.storage_secret` above - re-run `set_storage_secret` (or
-`set_storage_secret_vended`) once after restoring into a fresh instance) and
-the bakery's transient claim tables (`claims` / `claim_acks` / `deferred_acks`,
-per-node mesh state). Until the credential is re-established a restored node
-serves hot reads but fails cold I/O cleanly. `ci/ops.sh` Check 4 exercises
-exactly this.
+`set_storage_secret_azure` or `set_storage_secret_vended`) once after restoring
+into a fresh instance) and the bakery's transient claim tables (`claims` /
+`claim_acks` / `deferred_acks`, per-node mesh state). Until the credential is
+re-established a restored node serves hot reads but fails cold I/O cleanly.
+`ci/ops.sh` Check 4 exercises exactly this.
 
 The Iceberg catalog ATTACH is **lazy**: the coldfront C extension hook issues
 `ATTACH IF NOT EXISTS` against Lakekeeper - using the cluster's
 `coldfront.warehouse` and `coldfront.lakekeeper_endpoint` GUCs - on the **first
 query that touches a tiered view** (read or write), per DuckDB cached
-connection. There is no arming step and no per-session boilerplate: both reads
+connection. There is no setup step and no per-session boilerplate: both reads
 (`iceberg_scan`) and writes (`duckdb.raw_query`) work on a fresh psql session.
 Until a tiered view is touched no ATTACH is attempted, so a pre-bootstrap
 connection is never blocked by a missing warehouse.
 
 ### Non-Superuser App Roles (Least Privilege)
 
-pg_duckdb force-disables DuckDB's `LocalFileSystem` for non-superusers (see
+pg_duckdb force-disables DuckDB's `LocalFileSystem` for any role that lacks
+both `pg_read_server_files` and `pg_write_server_files` (see
 [Upstream requests](#pg_duckdb-non-superuser-localfilesystem-blocks-side-loaded-extensions)),
 which would block the side-loaded iceberg/postgres DuckDB extensions from
 loading on `ATTACH`. So `coldfront.ensure_attached()` / `ensure_pg_attached()`
@@ -172,34 +180,41 @@ are `SECURITY DEFINER` with a pinned `search_path`: the extension load +
 because the DuckDB instance is per-backend the attach persists for the
 session - every subsequent `iceberg_scan` / `_exec_iceberg_with_claim` then
 runs as the **app role** over S3/httpfs, never touching `LocalFileSystem`. The
-app role needs only `duckdb.postgres_role` membership + object grants; **no
-superuser, no `pg_{read,write}_server_files`**.
+app role needs only `duckdb.postgres_role` membership, object grants, and SET
+on the superuser-only `duckdb.unsafe_allow_execution_inside_functions`
+parameter, which the cross-tier move needs; **no superuser, no
+`pg_{read,write}_server_files`**.
 
 Because the attach helpers run elevated, the deployment-config GUCs they
 consume (`coldfront.warehouse`, `coldfront.lakekeeper_endpoint`,
 `coldfront.local_pg_dsn`) are registered `PGC_SUSET` (the last also
 `GUC_SUPERUSER_ONLY`) in `_PG_init`, so a non-superuser cannot redirect the
-elevated `ATTACH` at an attacker endpoint. Onboarding is one operator call,
+elevated `ATTACH` at an attacker endpoint. `coldfront.dblink_self`, the DSN of
+the bakery's loopback, is `PGC_SUSET` as well, because the loopback runs claim
+statements as the user that DSN names. It stays readable by every role, since
+the invoker-rights `coldfront._bakery_armed()` reads it on every cold write.
+All four GUCs default to an empty string. Onboarding is one operator call,
 `coldfront.grant_app_access(role)` - idempotent, registry-derived (schemas,
 views, the hot heap + its identity sequence, the cold-path function EXECUTE
 allow-list), not `PUBLIC`-executable. The image defaults
 `duckdb.postgres_role = coldfront_duckdb` (env `COLDFRONT_DUCKDB_ROLE`) and
-creates the role, so the path is turnkey.
+creates the role, so the path needs no further setup.
 
 In a **Spock mesh** the role and its grants replicate via Spock DDL - onboard
-once on any node. Mesh cold *writes* route through the R-A bakery; its
+once on any node. Mesh cold *writes* route through the bakery protocol; its
 coordination function `_claim_iceberg_lock` is itself `SECURITY DEFINER`
 (search_path-pinned, fully schema-qualified) so a non-superuser drives the
 cross-node serialization (`pg_stat_replication` liveness + the loopback claim)
 with the privilege it requires. `_exec_iceberg_with_claim` deliberately stays
 `SECURITY INVOKER` - it runs the caller's cold DML, which must execute as the
-caller. The bakery SD is **protocol-neutral**: it changes the PG execution
-privilege, not the claim/ack/lock/ticket protocol, re-verified against
-[the TLA+ model](formal/Bakery.tla) (all safe configs pass; the race config
-still violates `NoLakekeeperConflict`).
+caller. This `SECURITY DEFINER` setting is **protocol-neutral**: it changes the
+PG execution privilege, not the claim/ack/lock/ticket protocol, re-verified
+against [the TLA+ model](formal/Bakery.tla) (all safe configs pass; the race
+config still violates `NoLakekeeperConflict`).
 
-See README "Security"; asserted by the journey's `story_app_privilege`,
-`ci/ops.sh` check 3, and the `privilege_model` pg_regress test.
+See README "Security"; the setting is asserted by the journey's
+`story_app_privilege`, `ci/ops.sh` check 3, and the `privilege_model`
+pg_regress test.
 
 ### Temp Table Bridge: PG → Iceberg
 
@@ -230,8 +245,8 @@ Applications use the transparent view exactly like a table. A
 `post_parse_analyze_hook` in the coldfront extension intercepts
 INSERT/UPDATE/DELETE whose target is a registered relation - resolved in
 `coldfront.tiered_views` by name (`schema_name`, `relname`) - and rewrites the
-parsed `Query` so it lands in the correct tier; cold-side writes funnel through
-the `_exec_iceberg_with_claim` chokepoint (see
+parsed `Query` so it lands in the correct tier; cold-side writes go through
+`_exec_iceberg_with_claim` (see
 [Concurrency](#concurrency-and-pgedge-spock-deployments)). A
 `ProcessUtility_hook` handles DDL on the same relations.
 
@@ -244,9 +259,9 @@ spellings both engines accept (see
 `planner_hook` folds bound parameters into such a read before pg_duckdb plans
 it when a parameter sits where DuckDB cannot type a placeholder (a direct
 argument of a pg_duckdb function, any argument of a table function); the plan
-cache's generic-plan build, which carries no values, gets a PostgreSQL plan
-priced above any custom plan, so under the plan cache's cost-based selection
-the read is planned from its values on every execution.
+cache's generic-plan build, which has no values, gets a PostgreSQL plan priced
+above any custom plan, so under the plan cache's cost-based selection the read
+is planned from its values on every execution.
 `plan_cache_mode = force_generic_plan` bypasses that selection and picks the
 value-less generic plan, which fails with `only works with DuckDB execution`
 (see [usage.md → Supported Column Types](usage.md#supported-column-types)).
@@ -255,37 +270,38 @@ The following table maps each operation to its interface and routing path:
 
 | Operation | Interface | Routed via |
 |---|---|---|
-| SELECT | `SELECT FROM events` | pg_duckdb (UNION ALL in tiered, wrapper view in decoupled) |
+| SELECT | `SELECT FROM events` | pg_duckdb (UNION ALL in tiered, wrapper view in decoupled); a single-table tiered read whose WHERE proves it hot is rerouted to the hot heap in plain PostgreSQL |
 | INSERT | `INSERT INTO events ...` | coldfront `post_parse_analyze_hook` |
 | UPDATE / DELETE | `... events WHERE ...` | coldfront `post_parse_analyze_hook` |
 | DDL (ALTER / RENAME) | `ALTER TABLE _events ...` | coldfront `ProcessUtility_hook` (see [Transparent DDL](#transparent-ddl-via-coldfront)) |
-| DROP / TRUNCATE | `DROP TABLE _events` | blocked by the hook (see [Transparent DDL](#transparent-ddl-via-coldfront)) |
+| DROP / TRUNCATE | `DROP TABLE _events` | The hook blocks the statement (see [Transparent DDL](#transparent-ddl-via-coldfront)). |
 
 With `duckdb.force_execution = true`, hot-side queries are also accelerated by
 DuckDB's vectorized columnar engine.
 
 How the hook splits a write is mode-specific:
 
-- **Tiered** routes by the partition-column watermark - hot heap vs cold
-  Iceberg, with dual-tier writes for ambiguous predicates. See
+- In tiered mode, the hook routes by the partition-column watermark - hot heap
+  vs cold Iceberg, with dual-tier writes for ambiguous predicates. See
   [architecture_tiered.md → Transparent INSERT](architecture_tiered.md#transparent-insert)
   and [→ UPDATE/DELETE](architecture_tiered.md#transparent-updatedelete).
-- **Decoupled** always classifies `TIER_COLD`: every write is a single-tier
-  Iceberg write. See [architecture_decoupled.md](architecture_decoupled.md).
+- In decoupled mode, the hook always classifies `TIER_COLD`, so every write is
+  a single-tier Iceberg write. See
+  [architecture_decoupled.md](architecture_decoupled.md).
 
 ### Cold-Tier DML from Inside PL/pgSQL (Functions, DO Blocks, Triggers)
 
 Cold-tier `INSERT`/`UPDATE`/`DELETE` work as top-level statements *and* from
 inside a plpgsql function / `DO` block / trigger, via two mechanisms:
 
-- **Parameters are emitted as a runtime `format(<template>, $1, $2, …)` call**
+- Parameters are emitted as a runtime `format(<template>, $1, $2, …)` call
   (`cold_sql_arg`), with the param types declared on the re-parse
   (`parse_analyze_fixedparams`). PG binds the values at execution, so DuckDB
   only ever sees finished literals. This applies everywhere - a driver's
   parameterized cold `UPDATE` at the top level is the same case.
 
-- **A cold call parsed inside plpgsql is wrapped as a DML over a permanent
-  single-row carrier, `coldfront._dummy_dml_target`.** plpgsql rejects a bare
+- A cold call parsed inside plpgsql is wrapped as a DML over a permanent
+  single-row carrier, `coldfront._dummy_dml_target`. plpgsql rejects a bare
   result-returning `SELECT` with no `INTO`/`PERFORM` ("query has no destination
   for result data") and the cold target is a DuckDB-attached object PG cannot
   tag a real DML against, so the call is reshaped as a no-row DML:
@@ -299,8 +315,8 @@ inside a plpgsql function / `DO` block / trigger, via two mechanisms:
     `_exec_iceberg_with_claim` returns `void` and `void IS NULL` is always
     false, **zero rows match - the carrier is never written: no dead rows, no
     WAL, no bloat.** For dual-tier and tiered-INSERT the hot DML is the outer
-    statement and this same UPDATE rides in a data-modifying `WITH`-CTE. At the
-    top level the rewrite keeps the plain
+    statement and this same UPDATE runs inside a data-modifying `WITH`-CTE. At
+    the top level the rewrite keeps the plain
     `SELECT coldfront._exec_iceberg_with_claim(...)` shape.
 
 "Inside plpgsql" is detected via `pstate->p_post_columnref_hook != NULL`
@@ -322,29 +338,31 @@ ColdFront coordinates concurrent writes across the cluster as follows:
   iceberg-only INSERT/UPDATE/DELETE wraps in
   `coldfront._exec_iceberg_with_claim`, which holds a globally-ordered
   Snowflake ticket via the Spock-replicated `coldfront.claims` table and waits
-  for its turn before issuing the iceberg commit. No 409s, no app-level retry.
-  See
+  for its turn before issuing the iceberg commit. There are no 409s and no
+  app-level retry. See
   [architecture_decoupled.md → Concurrency](architecture_decoupled.md#concurrency-horizontal-scaling-the-bakery-protocol)
   for the full design and benchmarks.
 
 ### Cold-Write Strategy: Stock vs Patched duckdb-iceberg
 
-Every cold write runs through the same `_exec_iceberg_with_claim` chokepoint.
-What differs is *when* the bakery ticket is held. The async ordering is active
-only when **both** `coldfront.iceberg_async_parquet` (default `off`) and the
-build marker `coldfront.iceberg_bakery_patch` (asserting the loaded
-duckdb-iceberg carries the patch) are on (`coldfront._iceberg_async_active()`),
-as the following table shows:
+Most cold writes run through `_exec_iceberg_with_claim`; the tiered INSERT
+fallback and the cross-tier move take the claim through `_take_iceberg_claim`
+themselves. What differs is *when* the bakery ticket is held. The async
+ordering is used only on a mesh node with the bakery enabled, and only when
+**both** `coldfront.iceberg_async_parquet` (default `off`) and the build marker
+`coldfront.iceberg_bakery_patch` (asserting the loaded duckdb-iceberg includes
+the patch) are on (`coldfront._iceberg_async_active()`); a vanilla node always
+takes its lock before uploading. The following table shows the two orderings:
 
 | Ordering | duckdb-iceberg | Behavior |
 |---|---|---|
-| stock (default) | **stock** upstream | Claim-first: take the bakery ticket, *then* upload parquet **and** commit inside the ticket. Correct on an unpatched binary, but the whole parquet upload happens under the lock, so concurrent writers serialize on upload + commit. |
-| async (both GUCs `on`) | **patched** (`iceberg-bakery-aware-commit-refresh-v15.patch`) | Overlap: upload parquet in the background *first*, then take the ticket only for the Lakekeeper commit. Concurrent writers' uploads overlap; only the short commit POST is serialized. |
+| stock (default) | stock upstream | The writer takes the bakery ticket first, *then* uploads parquet and commits inside the ticket. This ordering is correct on an unpatched binary, but the whole parquet upload happens under the lock, so concurrent writers serialize on upload and commit. |
+| async (both GUCs `on`) | patched (`iceberg-bakery-aware-commit-refresh-v15.patch`) | The writer uploads parquet in the background *first*, then takes the ticket only for the Lakekeeper commit. Concurrent writers' uploads overlap; only the short commit POST is serialized. |
 
 The code path and the application-visible behavior are identical, so the GUCs
 are purely a performance knob. The patch relocates parent-snapshot stamping
 from upload time into PG's pre-commit phase (inside the bakery ticket, against
-a freshly-fetched table), so overlapping uploads can't commit a stale parent.
+a freshly-fetched table), so overlapping uploads cannot commit a stale parent.
 Async requested without the build marker downgrades safely to the stock
 ordering, noted once per session with a server LOG line - never a silent 409.
 The Docker image ships the patched binary and sets both GUCs on
@@ -363,11 +381,11 @@ table summarizes:
 
 | DDL | Behavior |
 |---|---|
-| `ALTER TABLE _t ADD/DROP COLUMN`, `ALTER COLUMN ... TYPE`, `RENAME COLUMN` | **Mirrored to Iceberg** - the hook drops the view, runs the hot-side change, then `coldfront._mirror_iceberg_alter` issues the matching Iceberg `ALTER` (one bakery-serialized, claim-first catalog change) and rebuilds the view, so both tiers evolve in one statement. Column types map through `coldfront._iceberg_storage_type`, so an unsupported type (e.g. `inet`) is rejected up front; `ALTER COLUMN TYPE` is limited to the safe promotions duckdb-iceberg accepts (int→bigint, float→double, date→timestamp, decimal-widen). |
-| `ALTER TABLE _t RENAME TO ...` | Supported (touches no Iceberg schema): update `tiered_views.hot_table`, rebuild the view. |
-| `ALTER VIEW v RENAME TO ...` | Supported: migrate the name-keyed registry + `archive_watermark` rows to the new view name, then rebuild (otherwise the lookups miss and the cold UNION branch silently disappears). |
-| `DROP TABLE _t` / `DROP VIEW v` | **Blocked by design** - would orphan the Iceberg cold tier. Dismantling tiering is a deliberate operator action, never a side effect of a habitual statement: call `coldfront.drop_iceberg_table(schema, table, purge)`, which unregisters the table, drops the view, renames the hot table back, and drops the cold tier, deleting its objects only if `purge` says so. |
-| `TRUNCATE _t` | **Blocked by design** - cold-tier rows would remain visible through the view. The operator truncates each tier explicitly. |
+| `ALTER TABLE _t ADD/DROP COLUMN`, `ALTER COLUMN ... TYPE`, `RENAME COLUMN` | The DDL is mirrored to Iceberg: the hook drops the view (except for RENAME COLUMN), runs the hot-side change, then `coldfront._mirror_iceberg_alter` issues the matching Iceberg `ALTER` (one bakery-serialized, claim-first catalog change) and rebuilds the view, so both tiers evolve in one statement. Renaming a column of the view itself is rejected. Column types map through `coldfront._iceberg_storage_type`, so an unsupported type (e.g. `inet`) is rejected up front; `ALTER COLUMN TYPE` is limited to the safe promotions duckdb-iceberg accepts (int to bigint, float to double, date to timestamp, and decimal widening). |
+| `ALTER TABLE _t RENAME TO ...` | The rename is supported because it touches no Iceberg schema: the hook updates `tiered_views.hot_table` and rebuilds the view. |
+| `ALTER VIEW v RENAME TO ...` | The rename is supported: the hook migrates the name-keyed registry and `archive_watermark` rows to the new view name, then rebuilds the view (otherwise the lookups miss and the cold UNION branch silently disappears). |
+| `DROP TABLE _t` / `DROP VIEW v` | The statement is blocked by design, because it would orphan the Iceberg cold tier. Dismantling tiering is a deliberate operator action, never a side effect of a habitual statement: call `coldfront.drop_iceberg_table(schema, table, purge)`, which unregisters the table, drops the view, renames the hot table back, and drops the cold tier, deleting its objects only if `purge` says so. |
+| `TRUNCATE _t` | The statement is blocked by design, because cold-tier rows would remain visible through the view. To empty the table, truncate the hot partitions individually and delete cold rows through the view. |
 
 The hook's view rebuild does `DROP VIEW` + `CREATE VIEW` (not
 `CREATE OR REPLACE VIEW`, which PG only allows for appending columns at the
@@ -380,10 +398,12 @@ there is nothing to re-point. A column change is mirrored to Iceberg through
 rebuilds the view regardless. Concurrent schema changes are serialized by the
 same bakery as cold DML.
 
-In active-active deployments, Spock replicates the top-level `ALTER TABLE` (the
-hook's SPI-issued mirror/rebuild DDL runs at non-top-level context, which
-Spock's `autoddl_can_proceed()` filters out). A peer's apply worker re-runs the
-replicated `ALTER TABLE`; the hook rebuilds **that peer's own** local view, but
+In active-active deployments, Spock replicates the top-level `ALTER TABLE`.
+Because the image sets `spock.allow_ddl_from_functions = on`, Spock also
+replicates the hook's SPI-issued `DROP VIEW` and `CREATE VIEW`:
+`autoddl_can_proceed()` accepts statements in `PROCESS_UTILITY_QUERY` context
+when that setting is on. A peer's apply worker re-runs the replicated
+`ALTER TABLE`; the hook rebuilds **that peer's own** local view, but
 `coldfront._mirror_iceberg_alter` skips the Iceberg `ALTER` there (it runs
 under `session_replication_role = replica`) because the originator already
 evolved the shared Lakekeeper catalog. Because the registry is name-keyed (see
@@ -400,10 +420,10 @@ replication set - is in
 ### Registry Keying: By Name, Not OID
 
 `coldfront.tiered_views` is keyed by `(schema_name, relname)` - the transparent
-view's qualified name. The C hook resolves it with
-`WHERE schema_name = … AND relname = …` on every parsed statement that targets
-a candidate relation; the hook already holds the target `relid`, from which the
-schema and name are a cheap syscache lookup.
+view's qualified name. The C hook reads the whole registry, joined to the
+watermark, once per command, and matches each candidate relation's schema and
+name in memory; the hook already holds the target `relid`, from which the
+schema and name are an inexpensive syscache lookup.
 
 The name is the right key because it is **stable across the churn the system
 actually produces**. The DDL-rebuild path does `DROP`+`CREATE` on the view,
@@ -449,7 +469,7 @@ validated at the `register`/`set` CLI boundary and at binary startup
 deliberately **not** a CHECK. The standalone partitioner self-materializes the
 table on stock PostgreSQL via `EnsureTable`, needing no extension. Connection
 config (DSN, Iceberg/S3 credentials) is deliberately **not** stored here - it
-is per-node and must never ride the replication stream.
+is per-node and must never be replicated.
 
 The *config* replicates by value; the partition **lifecycle DDL** must also
 reach every node. `CREATE … PARTITION OF …` and `DROP TABLE` are ordinary
@@ -470,11 +490,12 @@ partitioner run by `story_mesh_partition_ddl` in `ci/journey.sh` (an N×(N-1)
 probe: create from every node, detach, drop, asserting each lands on all
 nodes).
 
-Both binaries read this table and exit with an error when it is empty; tables
-enter it via `register`, or from a YAML `archiver.tables` list fed to `import`.
-Both expose a management CLI - `register` / `list` / `set` / `remove` /
-`import` / `export` - documented in
-[usage.md](usage.md#managing-partitioned-tables-cli).
+Both binaries read this table, each loading only the enabled rows of its own
+mode (the archiver those with a `hot_period`, the partitioner those without),
+and exit with an error when they find none; tables enter it via `register`, or
+from a YAML `archiver.tables` list fed to `import`. Both expose a management
+CLI - `register` / `list` / `set` / `remove` / `import` / `export` - documented
+in [usage.md](usage.md#managing-partitioned-tables-cli).
 
 ## Known Limitations
 
@@ -485,57 +506,61 @@ constraints, autovacuum-vs-cutover) are in
 
 The cross-cutting limitations are:
 
-- **One-time secret setup after warehouse bootstrap** - after Lakekeeper is
-  provisioned, an operator calls `SELECT coldfront.set_storage_secret(...)`
-  once per cluster; the catalog ATTACH itself is lazy, so there is no
-  per-session arming (see [Session Setup](#session-setup)).
-
-- **`jsonb` surfaces as `json` through the view** - DuckDB has no native
-  `jsonb`, and pg_duckdb takes over any query that references `iceberg_scan`
-  (all-or-nothing plan takeover), so the cold branch can't produce a PG `jsonb`
-  directly. The view generator casts `jsonb` columns to DuckDB-safe `json` on
-  both sides: hot emits `"col"::json`, cold emits `r['col']::json`, the UNION
-  unifies on `json`. Standard JSON access (`->>`, `->`, `#>`) works without any
-  caller-side cast; jsonb-only operators (`?`, `@>`, containment, de-dup) need
-  an explicit `data::jsonb` in the caller's query. Storage in Iceberg remains
-  VARCHAR (Iceberg has no JSON type either). The INSTEAD OF trigger's cold path
-  still casts the incoming value to `text` before sending it to
-  `duckdb.raw_query`.
-
-- **S3 compatibility** - Lakekeeper remote signing may not work with all
-  S3-compatible stores. Workaround: `ACCESS_DELEGATION_MODE NONE` with direct
-  DuckDB S3 secret.
-
-- **Planner-level interception, no per-query decision engine** - `pg_duckdb`
-  decides whether to take over a query by inspecting the parse tree for signals
-  (references to `iceberg_scan`, the `duckdb.force_execution` GUC, DuckDB-only
-  functions). Once it takes over, the whole statement runs in DuckDB; there is
-  no cost-based hot-vs-cold split per predicate. Hot-only queries can target
-  `_events` directly (native PG, no `pg_duckdb` roundtrip); queries that need
-  cross-tier semantics go through the view.
-
-- **Single-node query execution** - a query runs on the PG backend it landed
-  on. `pg_duckdb` does not distribute the DuckDB plan across nodes. Replication
+- The storage secret needs a one-time setup after warehouse bootstrap: after
+  Lakekeeper is provisioned, an operator calls
+  `SELECT coldfront.set_storage_secret(...)` once per cluster; the catalog
+  ATTACH itself is lazy, so there is no per-session setup (see
+  [Session Setup](#session-setup)).
+
+- `jsonb` reads as `json` through the view, unless the read is rerouted to the
+  hot heap: DuckDB has no native `jsonb`, and pg_duckdb takes over any query
+  that references `iceberg_scan` (all-or-nothing plan takeover), so the cold
+  branch cannot produce a PG `jsonb` directly. The view generator casts `jsonb`
+  columns to DuckDB-safe `json` on both sides: hot emits `"col"::json`, cold
+  emits `r['col']::json`, the UNION unifies on `json`. Standard JSON access
+  (`->>`, `->`, `#>`) works without any caller-side cast; jsonb-only operators
+  (`?`, `@>`, containment, de-dup) need an explicit `data::jsonb` in the
+  caller's query. Storage in Iceberg remains VARCHAR (Iceberg has no JSON type
+  either). The INSTEAD OF trigger's cold path still casts the incoming value to
+  `text` before sending it to `duckdb.raw_query`.
+
+- Lakekeeper remote signing may not work with all S3-compatible stores; the
+  workaround is `ACCESS_DELEGATION_MODE NONE` with a direct DuckDB S3 secret.
+
+- Interception happens at the planner level, with no per-query decision engine:
+  `pg_duckdb` decides whether to take over a query by inspecting the parse tree
+  for signals (references to `iceberg_scan`, the `duckdb.force_execution` GUC,
+  DuckDB-only functions). Once pg_duckdb takes over, the whole statement runs
+  in DuckDB; there is no cost-based hot-vs-cold split per predicate. The one
+  exception is a single-table read whose WHERE proves `ts >= cutoff`: the hook
+  rewrites it to read the hot heap in plain PostgreSQL, which returns native
+  `jsonb`. Other hot-only queries can target `_events` directly (native PG, no
+  `pg_duckdb` roundtrip); queries that need cross-tier semantics go through the
+  view.
+
+- Query execution is single-node: a query runs on the PG backend it landed on.
+  `pg_duckdb` does not distribute the DuckDB plan across nodes. Replication
   (single- or multi-master via pgEdge Spock) is supported on the hot tier and
   transparent to the application; scaling read throughput requires more
   replicas rather than parallelizing one query. Those replicas, including
   read-only physical standbys, serve cross-tier reads (see
   [Read Target](#read-target-primary-or-physical-standby)).
 
-- **Iceberg only** - no Delta Lake support. Adding Delta would require either a
-  second writer path in `pg_duckdb`'s Iceberg extension or a different
+- ColdFront supports Iceberg only, not Delta Lake. Adding Delta would require
+  either a second writer path in `pg_duckdb`'s Iceberg extension or a different
   analytical engine.
 
 ## Infrastructure (Docker)
 
 Three services run: PG+pg_duckdb+coldfront, Lakekeeper, and any S3-compatible
 store. Both extensions must be in `shared_preload_libraries` - `coldfront`
-installs its hook in `_PG_init`, which fires at backend start.
+installs its hook in `_PG_init`, which runs when the postmaster loads the
+library.
 
 A two-layer image serves every deployment: a prebuilt **base**
-(`docker/Dockerfile.duckdb15-base`) carrying pg_duckdb 1.5.4 (PR #1025) + the
-patched duckdb-iceberg on a pgEdge `*-spock5-minimal` base (Spock + Snowflake),
-and a thin **app** layer (`docker/Dockerfile.duckdb15`,
+(`docker/Dockerfile.duckdb15-base`) including pg_duckdb (PR #1025) on DuckDB
+1.5.4 + the patched duckdb-iceberg on a pgEdge `*-spock5-minimal` base (Spock +
+Snowflake), and a thin **app** layer (`docker/Dockerfile.duckdb15`,
 `--build-arg PG_MAJOR=16|17|18`) that compiles coldfront on top. The same image
 plays both topology roles - vanilla leaves spock/snowflake out of
 `shared_preload_libraries`; mesh loads them (`MESH=on`, set by the entrypoint).
@@ -574,22 +599,23 @@ only, no uuid-ossp).
 
 ## Upstream Requests
 
-Behaviors in upstream projects that ColdFront works around, kept as
-architectural notes: the gap, the workaround in use today, and the shape of the
-upstream capability that would let us drop the workaround.
+The behaviors in upstream projects that ColdFront works around are kept here as
+architectural notes: what is missing, the workaround in use today, and the
+shape of the upstream capability that would let ColdFront drop the workaround.
 
 ### pg_duckdb: Non-Superuser LocalFileSystem Blocks Side-Loaded Extensions
 
-pg_duckdb force-disables DuckDB's `LocalFileSystem` for non-superusers, which
-also blocks **loading a locally-installed DuckDB extension** - and ColdFront
-side-loads a patched `iceberg` (and `postgres`) extension from disk, which
-DuckDB lazily loads on `ATTACH`, so a non-superuser's first cold query fails at
-the elevated load step.
+pg_duckdb force-disables DuckDB's `LocalFileSystem` for any role that lacks
+both `pg_read_server_files` and `pg_write_server_files`, which also blocks
+**loading a locally-installed DuckDB extension** - and ColdFront side-loads a
+patched `iceberg` (and `postgres`) extension from disk, which DuckDB lazily
+loads on `ATTACH`, so a non-superuser's first cold query fails at the elevated
+load step.
 
-Workaround today: the `SECURITY DEFINER` attach helpers described under
-[Non-Superuser App Roles](#non-superuser-app-roles-least-privilege).
+The workaround in use today is the `SECURITY DEFINER` attach helpers described
+under [Non-Superuser App Roles](#non-superuser-app-roles-least-privilege).
 
-Upstream shape that would drop it: either a way to mark specific
+The upstream shape that would drop it is either a way to mark specific
 locally-installed extensions as loadable without `LocalFileSystem` access, or
 distinguishing extension-load file access from user-initiated raw file access
 in the non-superuser sandbox - so a non-superuser member of
@@ -602,15 +628,15 @@ pg_duckdb has a fully-native, in-process Postgres-table reader for analytics on
 PG heap data, but that machinery is **not reachable** from the write path into
 an attached Iceberg catalog.
 
-Workaround today: ColdFront's hook rewrites the INSERT into one
+As the workaround in use today, ColdFront's hook rewrites the INSERT into one
 `duckdb.raw_query` that reads through the DuckDB `postgres` extension's
 `pglocal.<schema>.<table>` ATTACH, pipelining rows over libpq (loopback) →
 DuckDB executor → Iceberg writer → S3 in a single pass, no local
 materialization. The cost is the libpq round-trip per row batch - real, but
 dwarfed by the Iceberg commit work for any realistic batch.
 
-Desired end-state. A way to drive the native in-process reader straight into
-the Iceberg writer - e.g. a `COPY` form:
+The desired end-state is a way to drive the native in-process reader straight
+into the Iceberg writer - e.g. a `COPY` form:
 
 ```sql
 COPY (SELECT * FROM public.events_partition) TO ICEBERG 'ice.public.events';
@@ -627,19 +653,20 @@ DuckDB item, and then requires that statement to be one DuckDB can execute:
 `IsAllowedStatement` runs with `throw_error` set, so a statement that needs
 DuckDB but modifies a PostgreSQL relation raises *"DuckDB does not support
 modifying Postgres tables"* rather than being handed back to the PostgreSQL
-planner. Two shapes reach it through a view whose body reads a cold table:
+planner. Two statement shapes reach that error through a view whose body reads
+a cold table:
 
-- `UPDATE`/`DELETE` on a view carrying `INSTEAD OF` triggers. PostgreSQL
-  expands the view to scan its rows and fire the trigger, the expanded body
-  carries the DuckDB item, and the statement errors before any trigger runs.
+- `UPDATE`/`DELETE` on a view with `INSTEAD OF` triggers. PostgreSQL expands
+  the view to scan its rows and fire the trigger, the expanded body contains
+  the DuckDB item, and the statement errors before any trigger runs.
 - `INSERT ... SELECT` whose source needs DuckDB, even where the target's own
   `INSTEAD OF INSERT` trigger would have taken the row.
 
 A plain `INSERT ... VALUES` through an `INSTEAD OF INSERT` trigger is
-unaffected, because that plan never expands the view and so carries no DuckDB
-item into the hook.
+unaffected, because that plan never expands the view, so no DuckDB item reaches
+the hook.
 
-Workaround today: ColdFront's `post_parse_analyze_hook` rewrites
+As the workaround in use today, ColdFront's `post_parse_analyze_hook` rewrites
 INSERT/UPDATE/DELETE on a registered view into its hot, cold or dual emit path
 before planning, so on the paths ColdFront owns pg_duckdb only ever sees a
 shape it accepts; the wrapper view's `INSTEAD OF INSERT` trigger covers plain
@@ -647,11 +674,11 @@ inserts when the extension is not loaded. What has no workaround is a view an
 application defines over cold data with its own `INSTEAD OF UPDATE`/`DELETE`
 triggers, or an `INSERT ... SELECT` drawing from such a view.
 
-Upstream shape that would drop it: where `NeedsDuckdbExecution` is true and
-`IsAllowedStatement` is false, chain to the previous planner hook instead of
-throwing, so PostgreSQL plans the statement and its `INSTEAD OF` triggers fire.
-Every statement DuckDB can run stays on the DuckDB path, and the check that
-decides this already exists in a non-throwing form.
+In the upstream shape that would drop it, where `NeedsDuckdbExecution` is true
+and `IsAllowedStatement` is false, pg_duckdb chains to the previous planner
+hook instead of throwing, so PostgreSQL plans the statement and its
+`INSTEAD OF` triggers fire. Every statement DuckDB can run stays on the DuckDB
+path, and the check that decides this already exists in a non-throwing form.
 
 ### DuckDB: Spill Files Are Not Namespaced per Instance
 
@@ -663,12 +690,12 @@ directory. pg_duckdb gives each backend its own DuckDB instance but one shared
 backends that spill open the same paths, read each other's bytes, and delete
 each other's files. On the 1.5.4 stack, of four sessions spilling a 3M-group
 aggregate under a 150 MB memory limit, three died with
-`IO Error: Could not read enough bytes`. Tracked as duckdb#15173 (open,
-reproduced); pg_duckdb#887 is an unmerged fix one layer up.
+`IO Error: Could not read enough bytes`. The defect is tracked as duckdb#15173
+(open, reproduced); pg_duckdb#887 is an unmerged fix one layer up.
 
-Workaround today: each backend takes a subdirectory of the configured path
-named after its own PID, assigned by `cf_own_duckdb_temp_dir` from the
-parse-analyze hook on the session's first statement, which is ahead of
+As the workaround in use today, each backend takes a subdirectory of the
+configured path named after its own PID, assigned by `cf_own_duckdb_temp_dir`
+from the parse-analyze hook on the session's first statement, which is ahead of
 pg_duckdb building its instance and reading the setting. The same hook reclaims
 the subdirectories whose PID no live backend holds, removing their spill files
 and the directory and reporting what that freed. That sweep runs once per
@@ -678,7 +705,7 @@ of seconds on the one statement that finds it. See
 [usage.md → Tuning Knobs](usage.md#tuning-knobs).
 
 The PID is what makes that reclaim possible, and is why ColdFront does not
-carry pg_duckdb#887, which names the directory with a random uuid and removes
+apply pg_duckdb#887, which names the directory with a random uuid and removes
 it from an `on_proc_exit` hook. That hook does not run when a backend is killed
 by `SIGKILL`, an immediate shutdown or the OOM killer, which is precisely when
 spill files are left behind, and a random name cannot be attributed to an owner
@@ -688,10 +715,10 @@ live backends (`BackendPidGetProc`), so any later session reclaims the orphans,
 whole gigabytes at a time. A reused PID resolves to a live backend and is left
 alone, as is any directory holding something other than spill files.
 
-Upstream shape that would drop it: a spill filename that carries the instance's
-own identity, so instances sharing a temp directory cannot collide and teardown
-deletes only what it wrote. That belongs in DuckDB, where the naming is, rather
-than in each embedder.
+The upstream shape that would drop it is a spill filename that includes the
+instance's own identity, so instances sharing a temp directory cannot collide
+and teardown deletes only what it wrote. That belongs in DuckDB, where the
+naming is, rather than in each embedder.
 
 ### duckdb-iceberg: Secret Visibility Under Fresh Transactions
 
@@ -700,17 +727,18 @@ is not visible to the fresh transaction `duckdb-iceberg` opens for its
 commit-time I/O, so a fresh PG backend's first cold-tier write would fail with
 HTTP 403 against any non-AWS S3-compatible endpoint.
 
-Workaround today: the DuckDB **persistent secret** materialized by
+The workaround in use today is the DuckDB **persistent secret** materialized by
 `coldfront.set_storage_secret(...)` (see [Session Setup](#session-setup)) -
 loaded at instance init, it already sits at a committed timestamp before any
 backend's first cold-tier write looks it up.
 
-Desired end-state. Either `IcebergTransaction::Commit` runs its commit-time I/O
-under the caller's `ClientContext` (rather than a freshly-opened Connection),
-or any extension that synthesises `CREATE SECRET` from external state commits
-that transaction explicitly, so the secret sits at a committed timestamp before
-a consumer's fresh transaction looks it up. Either would let a per-session
-synthesized secret work without relying on the persistent-secret mechanism.
+In the desired end-state, either `IcebergTransaction::Commit` runs its
+commit-time I/O under the caller's `ClientContext` (rather than a
+freshly-opened Connection), or any extension that synthesises `CREATE SECRET`
+from external state commits that transaction explicitly, so the secret sits at
+a committed timestamp before a consumer's fresh transaction looks it up. Either
+would let a per-session synthesized secret work without relying on the
+persistent-secret mechanism.
 
 ### duckdb-iceberg: Append to the Manifest List Instead of Rebuilding It
 
@@ -722,19 +750,31 @@ writer holds the bakery ticket, and its cost grows with the manifest-list
 length, so it inflates the serialized critical section (compaction only partly
 offsets it).
 
-Workaround today: the `iceberg-bakery-aware-commit-refresh` patch re-reads the
-manifest list from the freshly-loaded catalog head inside the ticket
-(`RefreshExistingManifestList`). This is correct - it folds in any peer
-manifests committed since this writer staged its parquet - but it pays the full
-re-scan of the manifest list under the lock.
+As the workaround in use today, the `iceberg-bakery-aware-commit-refresh` patch
+re-reads the manifest list from the freshly-loaded catalog head inside the
+ticket (`RefreshExistingManifestList`). The re-read is correct - it folds in
+any peer manifests committed since this writer staged its parquet - but it pays
+the full re-scan of the manifest list under the lock.
 
-Upstream shape that would drop it: a manifest-list commit that appends the new
-manifest to the existing manifest-list file, referenced by path from the
-current catalog head, instead of rebuilding from all scanned entries. That
+The upstream shape that would drop it is a manifest-list commit that appends
+the new manifest to the existing manifest-list file, referenced by path from
+the current catalog head, instead of rebuilding from all scanned entries. That
 keeps peer inclusion (the fresh head already points at peers' manifests) while
 removing the full re-scan from the commit, so the serialized section no longer
 grows with manifest-list length. That change is correctness-sensitive
 (manifest-list integrity, commit conflicts, silent data loss) and its
 throughput value is unmeasured and workload dependent, so it belongs upstream
-with fleet benchmarking rather than as a ColdFront-carried patch.
+with fleet benchmarking rather than as a patch ColdFront maintains.
+
+## Next Steps
+
+To go further with ColdFront, consult the following documents:
+
+- The [Tiered Mode](architecture_tiered.md) deep dive describes the archive
+  pipeline, transparent DML, and tiered tables in a Spock mesh.
+- The [Decoupled Mode](architecture_decoupled.md) deep dive describes
+  iceberg-only tables, their ACID model, and the bakery protocol.
+- The [Vector Storage](architecture_vectors.md) deep dive describes how
+  embeddings are stored, assigned to clusters, and searched.
+- The [Using ColdFront](usage.md) guide covers day-to-day use of both modes.
 
diff --git a/docs/architecture_decoupled.md b/docs/architecture_decoupled.md
index 6717e31..653a7aa 100644
--- a/docs/architecture_decoupled.md
+++ b/docs/architecture_decoupled.md
@@ -12,19 +12,19 @@ specific to decoupled mode.
 
 ## What "Decoupled" Means
 
-The table below contrasts each concern between tiered mode and decoupled mode
-described in this document:
+The following table compares tiered mode with the decoupled mode described in
+this document, concern by concern:
 
 | Concern | Tiered mode | Decoupled mode (this doc) |
 |---|---|---|
-| Hot rows | PG heap (`_events` partitioned) | - (no hot rows) |
-| Cold rows | Iceberg via Lakekeeper | All rows in Iceberg |
-| Unified view | `events` UNION-ALLs hot + cold | - (user queries Iceberg directly) |
-| INSTEAD-OF trigger | Bypassed when coldfront is preloaded; remains as fallback when it isn't | - (none) |
-| `post_parse_analyze_hook` | Rewrites INSERT/UPDATE/DELETE per tier | Rewrites every INSERT/UPDATE/DELETE on the wrapper view to a single `duckdb.raw_query(...)` against the Iceberg ref |
-| Archiver | Moves rows hot → cold on cron | - (nothing to archive) |
-| `coldfront.tiered_views` row | Required per managed table | Required (with `is_iceberg_only = true`); registered by `create_iceberg_table()` |
-| Required at runtime | `pg_duckdb`, `coldfront`, Lakekeeper, S3 | `pg_duckdb`, `coldfront` (lazy catalog ATTACH + DML rewrite + write serialization), Lakekeeper, S3 |
+| Hot rows | PG heap (`_events`, partitioned) | None |
+| Cold rows | Iceberg via Lakekeeper | All rows, in Iceberg |
+| Unified view | The `events` view UNION-ALLs hot and cold. | None; users query Iceberg directly. |
+| INSTEAD-OF trigger | The trigger is bypassed when coldfront is preloaded and remains as a fallback when it is not. | None |
+| `post_parse_analyze_hook` | The hook rewrites INSERT/UPDATE/DELETE per tier. | The hook rewrites every INSERT/UPDATE/DELETE on the wrapper view to a single `SELECT coldfront._exec_iceberg_with_claim(<ref>, <DuckDB SQL>)`, which takes the table's claim and runs the statement through `duckdb.raw_query`. |
+| Archiver | The archiver moves rows from hot to cold on a cron. | None, because there is nothing to archive. |
+| `coldfront.tiered_views` row | The row is required for each managed table. | The row is required (with `is_iceberg_only = true`), and `create_iceberg_table()` registers it. |
+| Required at runtime | `pg_duckdb`, `coldfront`, Lakekeeper, S3 | `pg_duckdb`, `coldfront` (lazy catalog ATTACH, DML rewrite, and write serialization), Lakekeeper, S3 |
 
 The coldfront extension provides the lazy catalog-attach glue: the C extension
 hook intercepts the first query that touches a tiered view (read or write) and,
@@ -37,10 +37,11 @@ the first time a session actually queries Iceberg.
 For tables registered as iceberg-only via `coldfront.create_iceberg_table()`,
 the parse-analyze rewriter is the **primary** dispatch path: it intercepts
 every INSERT/UPDATE/DELETE on the wrapper view and emits one
-`SELECT duckdb.raw_query('…')` that targets the Iceberg ref directly - a single
-Iceberg snapshot per statement. Tables that don't appear in
-`coldfront.tiered_views` are invisible to the hook (`lookup_tiered_view`
-returns null → fast path-out).
+`SELECT coldfront._exec_iceberg_with_claim(<ref>, '…')`, which takes the
+table's claim and runs the DuckDB statement against the Iceberg table through
+`duckdb.raw_query` - a single Iceberg snapshot per statement. Tables that do
+not appear in `coldfront.tiered_views` are invisible to the hook
+(`lookup_tiered_view` returns null → fast path-out).
 
 ## Bootstrap Sequence
 
@@ -51,6 +52,8 @@ once per database:
 -- (postgresql.conf or per-database config)
 coldfront.warehouse = 'wh'
 coldfront.lakekeeper_endpoint = 'http://lakekeeper:8181/catalog'
+-- only for INSERT ... SELECT from a PostgreSQL table:
+coldfront.local_pg_dsn = 'host=/var/run/postgresql dbname=coldfront user=coldfront'
 
 -- one-time, per database:
 CREATE EXTENSION pg_duckdb;
@@ -62,7 +65,15 @@ SELECT coldfront.set_storage_secret('<key>', '<secret>', '<endpoint>');  -- cold
 table - an extension-member table (so its data is excluded from `pg_dump` by
 default) that is added to the Spock repset (so it replicates by value to every
 mesh node) - and materializes a DuckDB PERSISTENT SECRET, which DuckDB loads at
-instance init. The secret is set once; no per-session arming is needed.
+instance init. The secret is set once; no per-session setup is needed.
+
+`coldfront.local_pg_dsn` is the libpq DSN that DuckDB's `postgres` extension
+attaches as `pglocal`. Only an `INSERT ... SELECT` that reads a PostgreSQL
+table uses it. The GUC is `PGC_SUSET` and superuser-only, because the DSN can
+hold credentials. `set_storage_secret` installs the `postgres` extension when
+the GUC is set, and `coldfront.ensure_pg_attached()` attaches `pglocal` when
+such an INSERT runs. With the GUC unset, that INSERT fails, because DuckDB has
+no `pglocal` catalog to resolve.
 
 After that, the first query touching a tiered view in any session lazily
 attaches the catalog and `ice.public.*` becomes available.
@@ -74,35 +85,36 @@ view supports the operations below.
 
 ### What Works
 
-The following operations are supported, with their dispatch path and notes:
+The following table shows the supported operations, their dispatch path, and
+notes:
 
 | Operation | Path | Notes |
 |---|---|---|
-| Lazy catalog ATTACH | C hook → `ensure_attached()` on first query touching a tiered view | One round-trip on first Iceberg query per session |
-| CREATE TABLE | `SELECT duckdb.raw_query('CREATE TABLE ice.<ns>.<name> (...)')` | DuckDB SQL, attached-catalog syntax |
-| INSERT | `INSERT INTO <view> [VALUES (…) | SELECT … FROM <pg_table> | SELECT … FROM generate_series(…)]` - the C hook rewrites this to one `SELECT duckdb.raw_query('INSERT INTO ice.<ns>.<name> …')`. Source-table refs get prefixed with `pglocal.<schema>.<table>` so DuckDB's postgres extension streams the source via libpq into the Iceberg writer | Single Iceberg snapshot per INSERT, regardless of row count |
-| UPDATE | `UPDATE <view> SET … WHERE …` - hook → `SELECT duckdb.raw_query('UPDATE ice.<ns>.<name> SET ... WHERE ...')` | Iceberg merge-on-read |
-| DELETE | `DELETE FROM <view> WHERE …` - hook → `SELECT duckdb.raw_query('DELETE FROM ice.<ns>.<name> WHERE ...')` | Iceberg position-delete files |
-| SELECT (function-call form) | `SELECT … FROM iceberg_scan('ice.<ns>.<name>') r WHERE r['col'] = …` | Columns must use `r['col']` accessor |
-| SELECT (raw-query form) | `SELECT duckdb.raw_query('SELECT ... FROM ice.<ns>.<name> WHERE ...')` | Returns scalar/text result via pg_duckdb's NOTICE channel |
-| ROLLBACK of writes | `BEGIN; raw_query(...); ROLLBACK;` | pg_duckdb's `XactCallback` ties DuckDB↔PG tx, so ROLLBACK undoes pending Iceberg writes |
-| DROP TABLE | `SELECT coldfront.drop_iceberg_table('<schema>', '<name>', <purge>)` | Removes the wrapper view and every registration row, vector configuration included. A raw `DROP TABLE` through `duckdb.raw_query` drops only the catalog table and leaves them behind |
+| Lazy catalog ATTACH | The C hook calls `ensure_attached()` on the first query that touches a tiered view. | The ATTACH costs one round-trip on the first Iceberg query per session. |
+| CREATE TABLE | `SELECT duckdb.raw_query('CREATE TABLE ice.<ns>.<name> (...)')` | The statement is DuckDB SQL in attached-catalog syntax. |
+| INSERT | The C hook rewrites `INSERT INTO <view> [VALUES (…) | SELECT … FROM <pg_table> | SELECT … FROM generate_series(…)]` to one `SELECT coldfront._exec_iceberg_with_claim(<ref>, 'INSERT INTO ice.<ns>.<name> …')`. Source-table references get the prefix `pglocal.<schema>.<table>`, so DuckDB's postgres extension streams the source via libpq into the Iceberg writer. That attachment needs `coldfront.local_pg_dsn` (see [Bootstrap Sequence](#bootstrap-sequence)). | Each INSERT produces a single Iceberg snapshot, regardless of row count. |
+| UPDATE | The hook rewrites `UPDATE <view> SET … WHERE …` to `SELECT coldfront._exec_iceberg_with_claim(<ref>, 'UPDATE ice.<ns>.<name> SET ... WHERE ...')`. | Iceberg applies the update as merge-on-read. |
+| DELETE | The hook rewrites `DELETE FROM <view> WHERE …` to `SELECT coldfront._exec_iceberg_with_claim(<ref>, 'DELETE FROM ice.<ns>.<name> WHERE ...')`. | Iceberg records the delete in position-delete files. |
+| SELECT (function-call form) | `SELECT … FROM iceberg_scan('ice.<ns>.<name>') r WHERE r['col'] = …` | Columns must use the `r['col']` accessor. In a fresh session, run `SELECT coldfront.ensure_attached();` first, or DuckDB treats the argument as a file path. |
+| SELECT (raw-query form) | `SELECT duckdb.raw_query('SELECT ... FROM ice.<ns>.<name> WHERE ...')` | The query returns a scalar or text result via pg_duckdb's NOTICE channel. |
+| ROLLBACK of writes | `BEGIN; raw_query(...); ROLLBACK;` | pg_duckdb's `XactCallback` ties the DuckDB and PG transactions together, so ROLLBACK undoes pending Iceberg writes. |
+| DROP TABLE | `SELECT coldfront.drop_iceberg_table('<schema>', '<name>', <purge>)` | The function removes the wrapper view and every registration row, vector configuration included. A raw `DROP TABLE` through `duckdb.raw_query` drops only the catalog table and leaves those rows behind. |
 
 ### What Does Not Work
 
-The following attempts fail, with the reason for each:
+The following table shows attempts that fail and the reason for each:
 
 | Attempt | Failure |
 |---|---|
-| `SELECT * FROM ice.public.events` | PG parser rejects: `cross-database references are not implemented`. PG sees the 3-part name as `database.schema.table` and refuses. There is no "ice is an attached duckdb catalog" handling at the PG parser level. |
-| `INSERT INTO ice.public.events VALUES (...)` (PG-native DML on the 3-part name) | Same parser rejection. |
+| `SELECT * FROM ice.public.events` | The PG parser rejects the statement with `cross-database references are not implemented`. PG sees the 3-part name as `database.schema.table` and refuses. There is no "ice is an attached duckdb catalog" handling at the PG parser level. |
+| `INSERT INTO ice.public.events VALUES (...)` (PG-native DML on the 3-part name) | The PG parser rejects the statement the same way. |
 | Bare-column predicates on `iceberg_scan(...)` | `iceberg_scan` returns a single-column row of struct; columns must be accessed via `r['col']`. Bare `WHERE col = …` fails with "column does not exist". |
 
-The net effect: every read or write of an Iceberg-only table either goes
+The net effect is that every read or write of an Iceberg-only table either goes
 through the `iceberg_scan(...)` table-function (with `r['col']` accessor) or
-through `duckdb.raw_query('… DuckDB SQL …')`. Neither is as ergonomic as a
-normal PG table. This is the fundamental ergonomics gap of decoupled mode
-without a PG-side wrapper view.
+through `duckdb.raw_query('… DuckDB SQL …')`. Neither is as easy to use as a
+normal PG table, which is the main drawback of decoupled mode without a PG-side
+wrapper view.
 
 ## Supported Column Types
 
@@ -111,36 +123,41 @@ PG and Iceberg (shared with tiered mode; see `pgFormatTypeToDuckDB` in
 [cmd/archiver/main.go](https://github.com/pgEdge/ColdFront/blob/main/cmd/archiver/main.go)).
 Anything outside this list is rejected at table-creation time.
 
-The supported types, their Iceberg/Parquet storage, and round-trip surface are:
+The following table shows the supported types, their Iceberg/Parquet storage,
+and how each reads back:
 
-| PG type | Iceberg/Parquet storage | Round-trip surface |
+| PG type | Iceberg/Parquet storage | Round trip |
 |---|---|---|
-| `bigint` / `integer` / `smallint` | `BIGINT` / `INTEGER` / `SMALLINT` | identical |
-| `real` / `double precision` | `REAL` / `DOUBLE` | identical |
-| `boolean` | `BOOLEAN` | identical |
-| `timestamp with time zone` | `TIMESTAMPTZ` | identical |
-| `timestamp without time zone` | `TIMESTAMP` | identical |
-| `date` / `time without time zone` | `DATE` / `TIME` | identical |
-| `uuid` | `UUID` | identical |
-| `bytea` | `BLOB` | identical |
-| `text` / `varchar(N)` / `char(N)` | `VARCHAR` | unbounded; declared length not enforced; `char(N)` returns unpadded (`pg_typeof varchar`) |
-| `numeric(P,S)` (P ≤ 38) | `DECIMAL(P,S)` | identical |
-| `jsonb` / `json` | `VARCHAR` | view-cast back to `json` (not `jsonb` - Iceberg has no JSON primitive) |
-| `interval` | `VARCHAR` | view-cast back to `interval` |
-
-Rejected (rather than silently downgraded to `VARCHAR` and losing
-precision/identity):
-
-- `inet` / `cidr` / `oid` - pg_duckdb cannot process them (`inet` Oid 869,
-  `oid` Oid 26) in any query it plans, and every Iceberg-backed read is planned
-  by pg_duckdb. No cast makes them readable; store IP data as `text` and `oid`
-  values as `bigint`.
-- `numeric` without explicit `(P,S)` - Iceberg requires bounded decimals.
-- Custom enums, `xml`, `tsvector`/`tsquery`, range types, multirange types.
-- Composite types and arrays. (Arrays would map to Parquet `LIST<…>` only if
-  the element type is itself supported; not yet implemented for decoupled
-  mode.)
-- Any type not enumerated above.
+| `bigint` / `integer` | `BIGINT` / `INTEGER` | Identical |
+| `smallint` | `INTEGER` (Iceberg has no 16-bit integer) | The column reads back as `integer`. |
+| `real` / `double precision` | `REAL` / `DOUBLE` | Identical |
+| `boolean` | `BOOLEAN` | Identical |
+| `timestamp with time zone` | `TIMESTAMPTZ` | Identical |
+| `timestamp without time zone` | `TIMESTAMP` | Identical |
+| `date` / `time without time zone` | `DATE` / `TIME` | Identical |
+| `uuid` | `UUID` | Identical |
+| `bytea` | `BLOB` | Identical |
+| `text` / `varchar(N)` / `char(N)` | `VARCHAR` | The value is unbounded, the declared length is not enforced, and `char(N)` returns unpadded (`pg_typeof varchar`). |
+| `numeric(P,S)` (P ≤ 38) | `DECIMAL(P,S)` | Identical |
+| `jsonb` / `json` | `VARCHAR` | The view casts the value back to `json` (not `jsonb`, because Iceberg has no JSON primitive). |
+| `interval` | `VARCHAR` | The view casts the value back to `interval`. |
+| `vector(N)` / `halfvec(N)` | `FLOAT[]` (list of float) | The column reads back as `real[]`. |
+
+The following types are rejected rather than silently downgraded to `VARCHAR`,
+which would lose precision or identity:
+
+- `inet`, `cidr` and `oid`, because pg_duckdb cannot process them (`inet` Oid
+  869, `oid` Oid 26) in any query it plans, and every Iceberg-backed read is
+  planned by pg_duckdb. No cast makes them readable; store IP data as `text`
+  and `oid` values as `bigint`.
+- `numeric` without explicit `(P,S)`, because Iceberg requires bounded
+  decimals.
+- custom enums, `xml`, `tsvector`/`tsquery`, range types, and multirange types.
+- composite types and arrays. (Arrays would map to Parquet `LIST<…>` only if
+  the element type is itself supported; that mapping is not yet implemented for
+  decoupled mode.)
+- pgvector's `sparsevec`.
+- any type not enumerated above.
 
 The narrowing is deliberate: a type that cannot round-trip exactly is rejected
 rather than silently downgraded, because data that appears stored but changes
@@ -150,11 +167,11 @@ shape on read is worse than no support.
 
 Raw_query / iceberg_scan are functional but ergonomically poor - every read
 needs `r['col']` accessor, every write needs a
-`duckdb.raw_query('… DuckDB SQL …')` envelope. To close that gap, ColdFront
-ships a single helper that provisions an Iceberg-only table together with a
-PG-side wrapper view and a registry row that arms the C hook to handle every
-DML on the view. After that, applications use **plain PG syntax** against the
-named relation:
+`duckdb.raw_query('… DuckDB SQL …')` envelope. To make an Iceberg-only table as
+easy to use as a PG table, ColdFront ships a single helper that provisions an
+Iceberg-only table together with a PG-side wrapper view and a registry row that
+makes the C hook to handle every DML on the view. After that, applications use
+**plain PG syntax** against the named relation:
 
 ```sql
 SELECT coldfront.create_iceberg_table(
@@ -184,51 +201,57 @@ transform on a column that is not a timestamp or date (for `hour`, not a
 timestamp), `coldfront._partition_clause()` makes at the same point, while no
 table exists yet.
 
-What the helper does:
+The helper performs the following steps:
 
-1. `duckdb.raw_query('CREATE SCHEMA IF NOT EXISTS ice."public"')` - idempotent
-   namespace creation against Lakekeeper.
-2. `duckdb.raw_query('CREATE TABLE ice.public.<name> (col1 STORAGE_TYPE, …) PARTITIONED BY (…)')` -
-   column types are validated by `coldfront._iceberg_storage_type()`, which
+1. Creates the Iceberg namespace against Lakekeeper, idempotently, with
+   `duckdb.raw_query('CREATE SCHEMA IF NOT EXISTS ice."public"')`.
+2. Creates the Iceberg table with
+   `duckdb.raw_query('CREATE TABLE ice.public.<name> (col1 STORAGE_TYPE, …) PARTITIONED BY (…)')`.
+   Column types are validated by `coldfront._iceberg_storage_type()`, which
    mirrors the canonical map in `cmd/archiver/main.go pgFormatTypeToDuckDB`.
    Anything outside the supported set (see
    [Supported Column Types](#supported-column-types) above) raises before any
    DDL is issued.
-3. `CREATE OR REPLACE VIEW <schema>.<name> AS SELECT r['col']::pg_type AS col, … FROM duckdb.query('SELECT * FROM ice.public.<name>') AS t(r)` -
-   projection wraps the struct accessor so applications see flat columns.
-   View-cast types (`jsonb` → `json`, `interval`) are surfaced via the
-   appropriate cast. The view reads via `duckdb.query()` so read-your-own-write
-   inside an explicit transaction works; pg_duckdb's planner folds it into the
-   same `ICEBERG_SCAN` plan with identical Parquet predicate pushdown, so
-   there's no perf cost.
+3. Creates the wrapper view with
+   `CREATE OR REPLACE VIEW <schema>.<name> AS SELECT r['col']::<view type> AS col, … FROM duckdb.query('SELECT * FROM ice.public.<name>') AS t(r)`.
+   The projection wraps the struct accessor so applications see flat columns.
+   Each column is cast to its view type where one exists (`json` for `jsonb`,
+   `interval`, `double precision`, `bytea`, `real[]` for vectors), and to its
+   storage type otherwise, so a `text` column reads as `character varying`. The
+   view reads via `duckdb.query()` so read-your-own-write inside an explicit
+   transaction works; pg_duckdb's planner folds it into the same `ICEBERG_SCAN`
+   plan with identical Parquet predicate pushdown, so there is no performance
+   cost.
 4. Registers the row in `coldfront.tiered_views` with `is_iceberg_only = true`.
    The C-side `post_parse_analyze_hook` reads this flag and short-circuits
    `classify_tier()` to `TIER_COLD` for any INSERT/UPDATE/DELETE on the wrapper
    view, regardless of WHERE clause or watermark - so every write rewrites
    cleanly into a single
-   `SELECT duckdb.raw_query('INSERT/UPDATE/DELETE ice.public.<name> …')`. No
-   INSTEAD OF INSERT trigger is created - the hook is the dispatch path.
-
-Write semantics through the wrapper view:
-
-- INSERT → row appears in Iceberg, fresh-session SELECT sees it.
-- UPDATE → row updates in Iceberg, fresh-session SELECT sees the new value.
-- DELETE → row removed from Iceberg.
-- ROLLBACK of an INSERT/UPDATE inside `BEGIN` undoes the Iceberg snapshot;
-  post-tx count matches pre-tx count.
-- jsonb column round-trips through Parquet `VARCHAR` storage and surfaces as PG
+   `SELECT coldfront._exec_iceberg_with_claim(<ref>, 'INSERT/UPDATE/DELETE ice.public.<name> …')`.
+   No INSTEAD OF INSERT trigger is created - the hook is the dispatch path.
+
+Writes through the wrapper view behave as follows:
+
+- An INSERT adds the row to Iceberg, and a fresh session's SELECT sees it.
+- An UPDATE changes the row in Iceberg, and a fresh session's SELECT sees the
+  new value.
+- A DELETE removes the row from Iceberg.
+- A ROLLBACK of an INSERT/UPDATE inside `BEGIN` undoes the Iceberg snapshot, so
+  the row count after the transaction matches the count before it.
+- A jsonb column round-trips through Parquet `VARCHAR` storage and reads as PG
   `json` via the wrapper view's cast (`data->>'k'` works).
 
-Limits the helper inherits from the platform:
+The helper inherits the following limit from the platform:
 
-- **Mixed-write guard relaxed.** The helper sets
+- The mixed-write guard is relaxed: the helper sets
   `duckdb.unsafe_allow_mixed_transactions = on` LOCAL during provisioning
   (Iceberg DDL + coldfront registry row both happen). The hook does the same
-  for each rewritten DML so PG-side parse-analyze + DuckDB-side raw_query
-  coexist in one tx. ROLLBACK still works via XactCallback; the flag only
-  bypasses the pre-commit guard.
+  for tiered INSERT splits and dual-tier UPDATE/DELETE, where PG-side and
+  DuckDB-side writes share one transaction; iceberg-only DML does not need it.
+  ROLLBACK still works via XactCallback; the flag only bypasses the pre-commit
+  guard.
 
-The helper doesn't add capability over raw_query - it composes the existing
+The helper does not add capability over raw_query - it composes the existing
 primitives into a single call so applications get a normal-looking PG table.
 
 ## Wrapper Helper: `coldfront.adopt_iceberg_table()`
@@ -245,11 +268,11 @@ The following table describes the parameters:
 
 | Parameter | Meaning |
 |---|---|
-| `p_schema` | PostgreSQL schema that holds the wrapper view; it must exist. |
-| `p_table` | The view's name, and the Iceberg table's name. |
-| `p_namespace` | Iceberg namespace the table lives in; NULL means `p_schema`. It need not exist as a PostgreSQL schema. |
-| `p_writable` | False registers the read path alone; true arms the DML rewrite. |
-| `p_types` | `{"column": "pg_type"}` overrides for the types the columns read as. |
+| `p_schema` | Names the PostgreSQL schema that holds the wrapper view; the schema must exist. |
+| `p_table` | Names both the view and the Iceberg table. |
+| `p_namespace` | Names the Iceberg namespace the table lives in; NULL means `p_schema`. The namespace need not exist as a PostgreSQL schema. |
+| `p_writable` | False registers the read path alone; true also enables the DML rewrite. |
+| `p_types` | Overrides the types the columns read as, given as `{"column": "pg_type"}`. |
 
 The schema is read with `DESCRIBE` through `duckdb.query()`, with
 `duckdb.unsafe_allow_execution_inside_functions = on` set LOCAL for the call.
@@ -289,7 +312,9 @@ each row:
 
 Nanosecond timestamps are refused, because PostgreSQL stores microseconds; so
 are variant, geometry, struct, map, and lists of anything but float. The
-refusal names the column and the Iceberg type.
+refusal names the column and the Iceberg type, except for `timestamptz_ns` and
+`geography`, which duckdb-iceberg refuses itself, with its own error, when the
+table loads.
 
 `p_types` sets the type a column reads as, so a `jsonb` column that ColdFront
 created adopts as `jsonb` rather than `text`:
@@ -307,13 +332,13 @@ holds. Both sides run through the same reverse map, so `timestamptz` matches
 `bigint` over a `DECIMAL(12,2)` column is refused. An override cannot
 reinterpret the stored bytes.
 
-A `FLOAT[]` column whose Iceberg schema carries a `_cf_vec_list_<column>`
-sibling is recorded in `vec_columns`, and the cluster columns stay out of the
-view's projection. Without the sibling the column is a plain `real[]`.
+A `FLOAT[]` column whose Iceberg schema has a `_cf_vec_list_<column>` sibling
+is recorded in `vec_columns`, and the cluster columns stay out of the view's
+projection. Without the sibling the column is a plain `real[]`.
 
 ### Writability
 
-The registry row carries `is_writable`, and the parse-analyze hook refuses
+The registry row has an `is_writable` flag, and the parse-analyze hook refuses
 INSERT, UPDATE and DELETE on a relation whose flag is false:
 
 ```text
@@ -342,16 +367,17 @@ references as strings, so each Iceberg table has exactly one.
 ### Adoption Binds the Name Once
 
 A second `adopt_iceberg_table()` under a registered name is refused whatever
-its arguments, as is a tiered relation's name. To arm writes, change an
+its arguments, as is a tiered relation's name. To enable writes, change an
 override, or pick up an evolved schema, release the table and adopt it again;
 the new view is built from the schema the catalog holds then.
 
 In a Spock mesh one node adopts. The `CREATE VIEW` replicates through the
 `ddl_sql` repset (`spock.allow_ddl_from_functions` is on) and the registry row
-through the `default` repset, which arms the parse-analyze hook on every peer;
-a peer's own adopt is refused as already registered. A release unregisters
-everywhere, because the registry `DELETE` precedes the `DROP VIEW` in the same
-transaction and disarms the peer's DDL hook before the drop is applied there.
+through the `default` repset, which enables the parse-analyze hook on every
+peer; a peer's own adopt is refused as already registered. A release
+unregisters everywhere, because the registry `DELETE` precedes the `DROP VIEW`
+in the same transaction and disarms the peer's DDL hook before the drop is
+applied there.
 
 ### Handing a Table Back
 
@@ -400,12 +426,12 @@ One verb covers both modes because in both the thing being dropped is the
 Iceberg table. What that means for PostgreSQL differs, because the modes
 differ, and the function says which path it took in a NOTICE:
 
-- Iceberg-only: the Iceberg table is the whole relation, so nothing remains.
-  This is the inverse of `create_iceberg_table()`.
-- Tiered: the Iceberg table is the cold tier, so the cold tier goes and the hot
-  table returns under the relation's own name. This is the inverse of tiering,
-  so the table ends up an ordinary partitioned Postgres table again, holding
-  the data that had not yet aged out.
+- For an iceberg-only table, the Iceberg table is the whole relation, so
+  nothing remains. This is the inverse of `create_iceberg_table()`.
+- For a tiered table, the Iceberg table is the cold tier, so the cold tier goes
+  and the hot table returns under the relation's own name. This is the inverse
+  of tiering, so the table ends up an ordinary partitioned Postgres table
+  again, holding the data that had not yet aged out.
 
 `p_purge` has no default, because the two outcomes are irreversible in opposite
 directions. `true` deletes the data and metadata objects, which for the cold
@@ -414,20 +440,28 @@ store with no catalog entry, where no ColdFront component reclaims them, since
 the compactor's expiry and orphan passes walk the snapshots of a table that
 still exists. The caller states which one they mean.
 
-What the function does:
+The function performs the following steps:
 
 1. Refuses a relation that is not registered in `coldfront.tiered_views`, so a
-   drop never runs against the catalog blindly.
-2. Deletes the registration. For a tiered table that includes the
+   drop never targets a relation ColdFront does not manage. A call on a
+   physical standby is refused as well, through `coldfront._reject_on_standby`.
+2. Takes the same per-table claim every other cold write takes, before it
+   changes anything, so the drop keeps the global lock order. When
+   `lock_timeout` is 0, the PostgreSQL default, the function sets it to 100 ms
+   for the transaction, the same limit the archiver's cutover uses. A contended
+   `ACCESS EXCLUSIVE` request then fails fast instead of queueing while the
+   claim stalls cold writes on every node. A nonzero `lock_timeout` the
+   operator set is kept.
+3. Deletes the registration. For a tiered table that includes the
    `partition_config` and `archive_watermark` rows, because the archiver
    resolves its work from `partition_config` and a surviving row would re-tier
    the table into a catalog entry that no longer exists. Deleting the
    `tiered_views` row also disarms the C DDL hook for the relation, which is
-   what permits step 3.
-3. Drops the wrapper view, and for a tiered table renames the hot table back,
+   what permits step 4.
+4. Drops the wrapper view, and for a tiered table renames the hot table back,
    reversing the rename the archiver's first run performed.
-4. Takes the same per-table claim every other cold write takes, then drops the
-   Iceberg table through a second attachment carrying `PURGE_REQUESTED`.
+5. Drops the Iceberg table: through a separate attachment created with
+   `PURGE_REQUESTED true` when `p_purge` is true, and through `ice` otherwise.
    Lakekeeper performs the object deletion itself, with the warehouse
    credential, so purge works unchanged under vended credentials.
 
@@ -435,11 +469,12 @@ Plain `DROP TABLE` and `DROP VIEW` on a registered relation stay blocked by the
 DDL hook; this function is the sanctioned path. Destroying a cold tier is
 deliberate, and a habitual statement is the wrong trigger for it.
 
-Three properties worth knowing:
+Three properties are worth knowing:
 
 - The purge decision is an ATTACH option in duckdb-iceberg rather than a
-  statement clause, so the drop runs through a scoped attachment whose alias
-  encodes the flag. The long-lived `ice` attachment is never purge-armed.
+  statement clause, so a purging drop runs through a separate attachment,
+  `ice_drop_purge`, which stays attached for the session. A non-purging drop
+  runs through the long-lived `ice` attachment, which never has the option set.
 - Purge is asynchronous. The catalog entry disappears with the drop, but the
   objects are removed by Lakekeeper's own background purge queue shortly
   afterwards, so a check made immediately after the call can still see them.
@@ -449,82 +484,93 @@ Three properties worth knowing:
   deleted; under the hard profile, which is Lakekeeper's default, there is no
   recovery window and the purge is queued as soon as the table is dropped. A
   table on which a Lakekeeper hold (`set_table_protection`) is set cannot be
-  dropped at all, and this function cannot override that: the drop carries
-  `PURGE_REQUESTED` but never `force`.
+  dropped at all, and this function cannot override that: the drop request
+  sends `PURGE_REQUESTED` but never `force`.
 
 ## ACID Model
 
-(Summarizes material from [architecture.md](architecture.md) §Concurrency and
-§Known Limitations applied to the decoupled scenario.)
+(This section summarizes material from [architecture.md](architecture.md)
+§Concurrency and §Known Limitations applied to the decoupled scenario.)
 
-The table below gives the status of each ACID property in decoupled mode:
+The following table shows the status of each ACID property in decoupled mode:
 
 | Property | Status |
 |---|---|
-| Atomicity (single statement) | **Yes.** One `duckdb.raw_query('INSERT/UPDATE/DELETE …')` is one DuckDB transaction → one Iceberg snapshot commit. |
-| Atomicity (multi-statement tx, graceful) | **Yes.** pg_duckdb's `XactCallback` ties the DuckDB transaction to PG's, so PG `ROLLBACK` undoes pending Iceberg writes. |
-| Atomicity (multi-statement tx, backend crash) | **Partial.** A backend crash between Iceberg snapshot commit and PG commit can leave S3 objects orphaned. Iceberg housekeeping (orphan-file expiry) reclaims them; not corrupting, but a real failure mode for very-strict ACID requirements. |
-| Consistency | **Yes** within a snapshot - Iceberg's serializable model + Lakekeeper optimistic concurrency. |
-| Isolation | **Read-your-own-write within a tx works** when the wrapper view uses `duckdb.query('SELECT * FROM ice.…')` as its read path (the helper does this by default). The plain `iceberg_scan('ice.…')` form is *not* tx-aware (it re-resolves the table from Lakekeeper each call), but pg_duckdb's planner folds `duckdb.query('SELECT * FROM ice.…')` into the same `ICEBERG_SCAN` plan with identical predicate pushdown, so the wrapper view gets tx visibility for free. Cross-call snapshot consistency is weaker than PG-native (see [Limitations](#limitations)). |
-| Durability | **Yes** - Iceberg commits are durable on the object store once Lakekeeper acknowledges. Stronger than PG WAL on local disk for many production setups. |
+| Atomicity (single statement) | Yes. One `duckdb.raw_query('INSERT/UPDATE/DELETE …')` is one DuckDB transaction and produces one Iceberg snapshot commit. |
+| Atomicity (multi-statement tx, graceful) | Yes. pg_duckdb's `XactCallback` ties the DuckDB transaction to PG's, so PG `ROLLBACK` undoes pending Iceberg writes. |
+| Atomicity (multi-statement tx, backend crash) | Partial. pg_duckdb commits the Iceberg snapshot at PRE_COMMIT, so a backend crash after that but before the PG commit record leaves the Iceberg write committed and the PG side lost. A crash after the Parquet upload but before the commit POST leaves unreferenced objects, which the compactor's orphan pass reclaims. |
+| Consistency | Yes, within a snapshot: Iceberg's serializable model and Lakekeeper's optimistic concurrency provide it. |
+| Isolation | Read-your-own-write within a tx works. Both the wrapper view, which reads through `duckdb.query('SELECT * FROM ice.…')`, and the plain `iceberg_scan('ice.…')` form read one Iceberg snapshot for the whole transaction: pg_duckdb runs one DuckDB transaction per PostgreSQL transaction, and duckdb-iceberg resolves the table as of that transaction's start. A commit by another session after the transaction's first read therefore stays invisible until the transaction ends, at READ COMMITTED as well as REPEATABLE READ (see [Limitations](#limitations)). pg_duckdb's planner folds the view's `duckdb.query(...)` into the same `ICEBERG_SCAN` plan as `iceberg_scan`, with identical predicate pushdown. |
+| Durability | Yes. Iceberg commits are durable on the object store once Lakekeeper acknowledges them, which is stronger than PG WAL on local disk for many production setups. |
 
 ## Concurrency / Horizontal Scaling - The Bakery Protocol
 
 Decoupled mode makes the data layer fully shared between any number of PG nodes
 pointing at the same Lakekeeper endpoint and S3 bucket:
 
-- **Reads scale out trivially.** Each PG node hits Lakekeeper + S3
-  independently. New nodes spin up in seconds; no data sync.
-
-- **Writes are serialized PG-side by the bakery protocol** so they never
-  collide at Lakekeeper. The implementation is Lamport's 1978 distributed
-  mutual exclusion with the Ricart-Agrawala (1981) deferred-reply optimization.
-  Claims and acks travel as Spock-replicated rows (the two repset tables
-  below); a writer commits only when it holds the minimum outstanding ticket
-  and every live peer has acked (a peer defers its ack while it holds a smaller
-  ticket). This stays safe under Spock's *asymmetric* apply - each node applies
-  peers' rows on its own independent queue, so it never assumes a peer has
-  applied its concurrent claim; the Snowflake-ticket total order and the ack
-  barrier serialize commits, not any global apply ordering. Modeled in
+- Reads scale out because each PG node queries Lakekeeper and S3 independently.
+  New nodes start in seconds, with no data sync.
+
+- Writes are serialized PG-side by the bakery protocol so they never collide at
+  Lakekeeper. The implementation is Lamport's 1978 distributed mutual exclusion
+  with the Ricart-Agrawala (1981) deferred-reply optimization. Claims and acks
+  travel as Spock-replicated rows (the two repset tables below); a writer
+  commits only when it holds the minimum outstanding ticket and every live peer
+  has acked (a peer defers its ack while it holds a smaller ticket). This stays
+  safe under Spock's *asymmetric* apply - each node applies peers' rows on its
+  own independent queue, so it never assumes a peer has applied its concurrent
+  claim; the Snowflake-ticket total order and the ack barrier serialize
+  commits, not any global apply ordering. The protocol is modeled in
   [docs/formal/Bakery.tla](https://github.com/pgEdge/ColdFront/blob/main/docs/formal/Bakery.tla);
   the safety properties are verified via TLA+ (`Bakery.cfg`).
 
-    Two tables, both in Spock's `default` repset:
+    The protocol uses two tables, both in Spock's `default` repset:
 
-    - `coldfront.claims` - each writer inserts `(iceberg_table, ticket)` here;
-      deleted on release.
-    - `coldfront.claim_acks` - peers insert
-      `(ticket, ack_from_name, iceberg_table)` to acknowledge an originator's
-      claim, keyed by the acker's Spock node name. Replicates back to the
-      originator, and is deleted with the claim: only the originator's own wait
-      loop ever reads its acks, so a row has no reader once the claim is gone.
+    - Each writer inserts `(iceberg_table, ticket)` into `coldfront.claims`,
+      and the row is deleted on release.
+    - Peers insert `(ticket, ack_from_name, iceberg_table)` into
+      `coldfront.claim_acks` to acknowledge an originator's claim, keyed by the
+      acker's Spock node name. The ack replicates back to the originator and is
+      deleted with the claim: only the originator's own wait loop ever reads
+      its acks, so a row has no reader once the claim is gone.
 
     Locally on every node, `coldfront.deferred_acks` queues acks the node has
     *deferred* because it has its own pending claim with a smaller ticket on
-    the same table. Not replicated.
+    the same table. This table is not replicated.
 
-    Per-writer flow:
+    Each writer follows these steps:
 
-    1. `snowflake.nextval()` - fresh globally-unique ticket.
+    1. Take a fresh globally-unique ticket from `snowflake.nextval()`.
     2. Insert `(iceberg_table, ticket)` into `coldfront.claims` over the node's
        loopback, a libpq connection the extension's C code keeps (autonomous
-       tx; replicates async via Spock). SQL reaches it only through
+       tx; replicates async via Spock). SQL reaches the loopback only through
        `coldfront._loopback()`, which PUBLIC cannot execute. Only a superuser
        can set its connection string, `coldfront.dblink_self`, and the loopback
        resolves names in `pg_catalog` only. The ticket is taken inside that
        transaction, under the table's claim key, and every lock it takes ends
        with it.
-    3. **Wait until both** (a) no same-node writer has a smaller ticket on this
+    3. Wait until both (a) no same-node writer has a smaller ticket on this
        table, and (b) every alive peer has acked the ticket (its row appears in
        `coldfront.claim_acks`).
-    4. Issue the iceberg `duckdb.raw_query(...)` write - exactly one
+    4. Issue the iceberg `duckdb.raw_query(...)` write, which is exactly one
        uncontested commit at Lakekeeper.
-    5. Release at PG outer-transaction end (COMMIT or ABORT): the ticket is
-       enqueued at claim time (`_enqueue_release`) and the C `XactCallback`
-       deletes the claim over a loopback connection, running after pg_duckdb's
-       callback so the Iceberg snapshot has already committed (or rolled back).
-       The release trigger drains `coldfront.deferred_acks` for that ticket,
-       emitting any acks the node had been holding back.
+    5. Release the claim at PG outer-transaction end (COMMIT or ABORT): the
+       ticket is enqueued at claim time (`_enqueue_release`) and the C
+       `XactCallback` deletes the claim over a loopback connection at the
+       COMMIT event. pg_duckdb commits the Iceberg transaction earlier, at
+       PRE_COMMIT, so the snapshot is committed before the claim is released;
+       on ABORT the claim is deleted before pg_duckdb discards the uncommitted
+       Iceberg work. The release trigger drains `coldfront.deferred_acks` for
+       that ticket, emitting any acks the node had been holding back.
+
+    This is the stock ordering. With `coldfront.iceberg_async_parquet` and
+    `coldfront.iceberg_bakery_patch` both on, as the shipped image sets them, a
+    mesh writer stages the Parquet upload through `duckdb.raw_query` first and
+    takes the claim afterwards; only the commit POST runs under the claim, with
+    the parent snapshot re-stamped by the bakery-aware patch. With
+    `coldfront.iceberg_async_parquet` on and `coldfront.iceberg_bakery_patch`
+    off, `coldfront._iceberg_async_active()` returns false, and the writer
+    keeps the stock ordering and logs the downgrade once per session.
 
     A transaction takes one claim per table and holds it until it ends, so a
     second cold write to the same table in that transaction rides the first
@@ -535,12 +581,12 @@ pointing at the same Lakekeeper endpoint and S3 bucket:
 
     - If the peer has its own pending claim with a *smaller* ticket on the same
       table, it first asks whether that claim can have a live owner (see
-      *Orphan reaping* below); if it can → defer (queue in
-      `coldfront.deferred_acks` to emit later when the smaller claim is
-      released).
-    - Otherwise → ack immediately (INSERT into `coldfront.claim_acks` over the
-      loopback, so the row is tagged with the local node as origin and Spock
-      replicates it back to the originator).
+      *Orphan reaping* below); if it can, the trigger defers the ack, queueing
+      it in `coldfront.deferred_acks` to emit later when the smaller claim is
+      released.
+    - Otherwise, the trigger acks immediately by inserting into
+      `coldfront.claim_acks` over the loopback, so the row is tagged with the
+      local node as origin and Spock replicates it back to the originator.
 
     The same trigger fires on UPDATE, for the waiter's poke described under
     *Orphan reaping*.
@@ -567,35 +613,36 @@ pointing at the same Lakekeeper endpoint and S3 bucket:
     riding a statement the bakery already executes, with no timeout, scheduler
     or background worker:
 
-    - **Claim path.** `_claim_iceberg_lock` already holds the lock for its own
-      table. Its claim transaction on the loopback (`_insert_claim`) tries the
-      lock of every other table this node has a claim on; a lock the claimant's
-      own transaction holds makes the try fail, so a transaction never reaps
-      its own claims. It then deletes every same-node claim on those tables
-      (and, after a restart, any claim from before
-      `pg_postmaster_start_time()`) together with their acks before inserting
-      the new claim, so any cold write on the node clears every orphan the node
-      left. The DELETE fires the release trigger, which forwards whatever peers
-      had deferred behind the orphan.
-    - **Apply path.** When a peer's claim arrives and a smaller same-node claim
-      exists, `_on_claim_apply` tries the lock (`pg_try_advisory_xact_lock`).
-      Success means no live local writer, so it deletes the same-node claims
-      and their acks through the loopback and acks the arrival instead of
-      deferring it. A live writer's lock makes the try fail at once, and the
-      trigger defers as before.
-    - **Waiter's poke.** A peer that deferred while the lock was held, whose
-      holder then vanished, sees no further event. So a writer in the wait loop
-      re-touches its own claim row about once a second (a no-op UPDATE); it
-      replicates, the peer's trigger runs the apply path again for that ticket,
-      and the orphan is reaped. A poke that reaps nothing is silent, so no ack
-      is ever issued after its claim is gone.
+    - On the claim path, `_claim_iceberg_lock` already holds the lock for its
+      own table. Its claim transaction on the loopback (`_insert_claim`) tries
+      the lock of every other table this node has a claim on; a lock the
+      claimant's own transaction holds makes the try fail, so a transaction
+      never reaps its own claims. The claim transaction then deletes every
+      same-node claim on those tables (and, after a restart, any claim from
+      before `pg_postmaster_start_time()`) together with their acks before
+      inserting the new claim, so any cold write on the node clears every
+      orphan the node left. The DELETE fires the release trigger, which
+      forwards whatever peers had deferred behind the orphan.
+    - On the apply path, when a peer's claim arrives and a smaller same-node
+      claim exists, `_on_claim_apply` tries the lock
+      (`pg_try_advisory_xact_lock`). Success means no live local writer, so it
+      deletes the same-node claims and their acks through the loopback and acks
+      the arrival instead of deferring it. A live writer's lock makes the try
+      fail at once, and the trigger defers as before.
+    - The waiter's poke covers a peer that deferred while the lock was held and
+      whose holder then vanished, because that peer sees no further event. A
+      writer in the wait loop therefore re-touches its own claim row about once
+      a second (a no-op UPDATE); the UPDATE replicates, the peer's trigger runs
+      the apply path again for that ticket, and the orphan is reaped. A poke
+      that reaps nothing is silent, so no ack is ever issued after its claim is
+      gone.
 
     A node only ever deletes its own claims: a peer's claim that looks
     abandoned may belong to a partitioned node mid-write, and it enters neither
-    wait condition anyway. Modeled as the `Reaper` constant, the `Applier`'s
-    reap branch and the `Poker` process in `Bakery.tla`: `Bakery_wedge.cfg`
-    shows the stranding without it, and `Bakery_reaper.cfg` and
-    `Bakery_reaper_quiet.cfg` show liveness and all four safety invariants
+    wait condition anyway. Orphan reaping is modeled as the `Reaper` constant,
+    the `Applier`'s reap branch and the `Poker` process in `Bakery.tla`:
+    `Bakery_wedge.cfg` shows the stranding without it, and `Bakery_reaper.cfg`
+    and `Bakery_reaper_quiet.cfg` show liveness and all four safety invariants
     holding with it, the second in the case where nothing but the poke ever
     reaches the crashed node.
 
@@ -604,7 +651,7 @@ pointing at the same Lakekeeper endpoint and S3 bucket:
     `pg_stat_replication.reply_time`: a peer whose walsender has been silent
     longer than `coldfront.peer_alive_window_ms` (default 5000 ms; tune up on
     slow/lossy WAN links) is implicitly treated as already-acked. An *alive*
-    peer that hasn't acked is either deferring (R-A's defer rule, legitimate)
+    peer that has not acked is either deferring (R-A's defer rule, legitimate)
     or about to ack - either way, waiting is correct. A same-node claim is
     released by the C XactCallback in
     [extension/coldfront/src/coldfront.c](https://github.com/pgEdge/ColdFront/blob/main/extension/coldfront/src/coldfront.c)
@@ -623,11 +670,11 @@ pointing at the same Lakekeeper endpoint and S3 bucket:
     `duckdb-iceberg` does not implement one; the bakery sidesteps the
     requirement.)
 
-- **DDL replication.** Spock's `ddl_sql` repset replicates `CREATE/ALTER/DROP`
-  of the wrapper view, and the `default` repset replicates the
+- For DDL, Spock's `ddl_sql` repset replicates `CREATE/ALTER/DROP` of the
+  wrapper view, and the `default` repset replicates the
   `coldfront.tiered_views` registry row (see
   [Distributed Setup](usage.md#distributed-setup-3-node-mesh-decoupled-mode)),
-  so one node provisions the table and replication arms every peer's hook.
+  so one node provisions the table and replication enables every peer's hook.
 
 ### Throughput Characterization
 
@@ -636,21 +683,24 @@ throughput with larger per-INSERT batches or by partitioning the Iceberg table.
 
 ### Required Configuration on Every PG Node
 
-Apply the following settings on every PG node - the server-wide settings first,
-then the per-node settings:
+Apply the following settings on every PG node, starting with the server-wide
+settings:
 
 ```ini
 # postgresql.conf - server-wide
 wal_level = logical
 shared_preload_libraries = 'snowflake,spock,pg_duckdb,coldfront'
 
-# Keeps pg_stat_replication.reply_time fresh for the bakery's dead-peer
-# liveness check (PG default 10s would false-positive idle peers as dead).
+# Spock's apply worker does not read this setting: on an idle link,
+# pg_stat_replication.reply_time refreshes only on the walsender's
+# reply-requested keepalive, every wal_sender_timeout/2 (30 s by default).
 wal_receiver_status_interval = 1s
 
 # Sync-rep is NOT required by the bakery - R-A's ack barrier replaces it.
 ```
 
+Then apply the per-node settings:
+
 ```ini
 # postgresql.conf - per-node. snowflake.node is any integer 1..1023, unique per
 # node; the value is otherwise arbitrary. The bakery matches acks by spock node
@@ -668,29 +718,37 @@ coldfront.dblink_self = 'host=/tmp dbname=coldfront user=coldfront application_n
 coldfront.peer_alive_window_ms = 5000
 ```
 
+The bakery runs only on a node where both `snowflake.node` and
+`coldfront.dblink_self` are set, which `coldfront._bakery_armed()` checks on
+every cold write. A node missing either setting serializes its cold writes on a
+transaction-scoped local advisory lock instead. That lock orders the writers on
+one node only, so every mesh node needs both settings.
+
 The bakery has no peer-ack timeout knob. Dead peers are caught by the
 `pg_stat_replication.reply_time` liveness check inside the wait-loop (a stale
-walsender is treated as already-acked); alive peers that haven't acked are
+walsender is treated as already-acked); alive peers that have not acked are
 either deferring legitimately or about to ack.
 
-Per-node bootstrap - after Spock mesh setup, register the bakery tables in each
-node's default repset. Required because `spock.repset_add_table` needs the
-local Spock node to exist (can't run at `CREATE EXTENSION` time):
+For the per-node bootstrap, after Spock mesh setup, register the bakery tables
+in each node's default repset. This step is required because
+`spock.repset_add_table` needs the local Spock node to exist (it cannot run at
+`CREATE EXTENSION` time):
 
 ```sql
 -- run on every node, after spock.node_create + spock.sub_create:
 SELECT coldfront._ensure_claims_replicated();
 ```
 
-The helper is idempotent. Without it on a peer, that peer's ack INSERTs are
-local-only and never replicate back to the originating writer: every claim on
-the originator waits forever at the ack barrier.
+The helper is idempotent. If the helper has not run on a peer, that peer's ack
+INSERTs are local-only and never replicate back to the originating writer:
+every claim on the originator waits forever at the ack barrier.
 
-`coldfront.create_iceberg_table()` calls `_ensure_claims_replicated()` on the
-node it runs on, but that only registers the repset on *that* node. Peers
-receive the wrapper-view DDL via Spock's `ddl_sql` repset but do *not* re-run
-the helper - so the explicit per-node call above is mandatory in any multi-node
-setup.
+`coldfront.create_iceberg_table()` and
+`coldfront.adopt_iceberg_table(p_writable => true)` call
+`_ensure_claims_replicated()` on the node they run on, but that only registers
+the repset on *that* node. Peers receive the wrapper-view DDL via Spock's
+`ddl_sql` repset but do *not* re-run the helper - so the explicit per-node call
+above is mandatory in any multi-node setup.
 
 ## When to Use Decoupled vs Tiered
 
@@ -706,12 +764,13 @@ Decoupled (iceberg-only) is the right choice when:
   no autovacuum-vs-cutover lock conflict (see
   [architecture_tiered.md → Tiered-Specific Limitations](architecture_tiered.md#tiered-specific-limitations)),
   no PK rebuild after bulk load, no partition-management script.
-- You can tolerate the isolation gap (cross-query snapshot consistency). Tables
-  created via `create_iceberg_table()` are queried with plain SQL through the
-  wrapper view; the verbose `iceberg_scan` / `raw_query` syntax applies only to
-  tables used without the helper.
-- You want true storage/compute decoupling - adding compute = `docker run` a
-  new PG node, no data sync.
+- You can accept that cold reads in one transaction share one Iceberg snapshot,
+  even at READ COMMITTED (see [Limitations](#limitations)). Tables created via
+  `create_iceberg_table()` are queried with plain SQL through the wrapper view;
+  the verbose `iceberg_scan` / `raw_query` syntax applies only to tables used
+  without the helper.
+- You want true storage/compute decoupling: adding compute means starting a new
+  PG node with `docker run`, with no data sync.
 
 Tiered (the default) is the right choice when:
 
@@ -725,10 +784,20 @@ Tiered (the default) is the right choice when:
 
 ## Limitations
 
-Decoupled mode carries the following limitation:
+Decoupled mode has the following limitation:
+
+- The cold tier keeps one Iceberg snapshot for the whole transaction, even at
+  READ COMMITTED: a commit by another session after the transaction's first
+  cold read stays invisible until the transaction ends, where PostgreSQL would
+  show it to the next statement.
+
+## Next Steps
+
+To go further with ColdFront, consult the following documents:
 
-- **Cross-call snapshot pinning.** PG-native isolation across multiple
-  `iceberg_scan` calls within one transaction would require either upstream
-  support in pg_duckdb (a "freeze the iceberg snapshot at tx-start" knob) or a
-  session-level lock; neither is in place, so a long-running transaction can
-  observe a newer snapshot on a later scan.
+- The [Architecture](architecture.md) overview describes the mechanics both
+  modes share.
+- The [Formal Verification](formal/README.md) document describes the TLA+ model
+  of the bakery protocol and how to check it.
+- The [Using ColdFront](usage.md) guide covers creating decoupled tables and
+  setting up a distributed mesh.
diff --git a/docs/architecture_tiered.md b/docs/architecture_tiered.md
index 457bb1a..fed253f 100644
--- a/docs/architecture_tiered.md
+++ b/docs/architecture_tiered.md
@@ -63,8 +63,8 @@ catalog, the object store, and the archiver:
 
 ## Archiver Workflow
 
-A single Go binary runs via cron. It converts an existing partitioned table
-into a tiered table on first run, then manages the ongoing lifecycle. The
+A single Go binary runs via cron. The binary converts an existing partitioned
+table into a tiered table on first run, then manages the ongoing lifecycle. The
 archiver is a thin SQL orchestrator - no DuckDB/Iceberg/Arrow Go libraries; all
 Iceberg I/O goes through `pg_duckdb` (see
 [architecture.md → Core Mechanics](architecture.md#core-mechanics-pg_duckdb)).
@@ -73,29 +73,35 @@ Iceberg I/O goes through `pg_duckdb` (see
 
 The archiver requires the following before its first run:
 
-- PostgreSQL 16+ with pg_duckdb, Lakekeeper bootstrapped with a warehouse
-- Persistent S3 secret configured (see
-  [architecture.md → Session Setup](architecture.md#session-setup))
-- An existing range-partitioned table
+- PostgreSQL 16+ with pg_duckdb.
+- Lakekeeper, bootstrapped with a warehouse.
+- a configured storage secret (see
+  [architecture.md → Session Setup](architecture.md#session-setup)).
+- static `s3:` or `azure:` credentials in the archiver config, unless the cold
+  store uses vended credentials.
+- an existing range-partitioned table.
 
 ### First Run: Conversion
 
 The archiver auto-detects the partition column from `pg_get_partkeydef()` and
-column types from `information_schema.columns`.
+column types from `pg_attribute` via `format_type()`.
 
 A run that finds partitions past the hot window (older than `hot_period`)
 starts with an idempotent bootstrap, executed once before the per-partition
-loop: rename the source table, recreate the unified view with the current
-watermark as its cutoff, and register the view in `coldfront.tiered_views`:
+loop: rename the source table, recreate the unified view, and register the view
+in `coldfront.tiered_views`. Until the first cutover sets a watermark, the view
+reads the hot table alone; after it, the view is a UNION with the watermark as
+its cutoff, and both branches cast every column to its view type (`jsonb` to
+`json`):
 
 ```sql
 ALTER TABLE events RENAME TO _events;
 
 CREATE OR REPLACE VIEW events AS
-  SELECT "id", "ts", "status", "data"::text FROM _events
+  SELECT "id"::bigint, "ts"::timestamptz, "status"::text, "data"::json FROM _events
   WHERE "ts" >= '2026-03-01'::timestamptz
   UNION ALL
-  SELECT r['id']::bigint, r['ts']::timestamptz, r['status']::text, r['data']::text
+  SELECT r['id']::bigint, r['ts']::timestamptz, r['status']::text, r['data']::json
   FROM iceberg_scan('ice.public.events') r
   WHERE r['ts'] < '2026-03-01'::timestamptz;
 ```
@@ -104,9 +110,9 @@ The rename is conditional, so it converts the table on the first run and no-ops
 afterwards; the `CREATE OR REPLACE VIEW` keeps the view's OID across runs. With
 the extension loaded, the C hook rewrites an INSERT on the view by the
 watermark cutoff, into a hot INSERT of the at/after-cutoff rows into `_events`
-and a cold `duckdb.raw_query` INSERT of the older rows. The view also carries
-an INSTEAD OF INSERT trigger that does the same routing; it is the fallback
-that fires only when the extension is not loaded.
+and a cold `duckdb.raw_query` INSERT of the older rows. The view also has an
+INSTEAD OF INSERT trigger that does the same routing; it is the fallback that
+fires only when the extension is not loaded.
 
 ### The Archive Pipeline
 
@@ -123,64 +129,66 @@ requires the partition to be **empty**. Phase 4 detaches atomically with the
 watermark advance, so a partition the pipeline archived is never a candidate
 again, and rows found in one here are in neither tier: an out-of-band write to
 the heap, or a mesh peer writing hot against a stale cutoff. Those rows are the
-only copy, so the archiver refuses the drop and fails the table.
+only copy, so the archiver refuses the drop and exits non-zero, skipping the
+remaining tables.
 
 Each remaining partition past the hot window then moves to Iceberg through a
 six-phase pipeline:
 
-0. Idempotent Iceberg-range wipe - deletes any Iceberg rows already in the
+0. The idempotent Iceberg-range wipe deletes any Iceberg rows already in the
    partition's range (a previous cycle may have exported without cutting over),
    so the re-export cannot duplicate rows.
 
-1. Install capture - installs a capture trigger and an UNLOGGED delta table on
-   the partition, so writes that land during the export are recorded for
-   replay.
+1. Capture installation (`install_archive_capture`) adds a capture trigger and
+   an UNLOGGED delta table to the partition, so writes that land during the
+   export are recorded for replay.
 
-2. Bulk export - exports the partition PG → Iceberg under a captured snapshot,
+2. The bulk export copies the partition PG → Iceberg under a captured snapshot,
    using the temp table bridge (see
    [architecture.md → Temp Table Bridge](architecture.md#temp-table-bridge-pg-iceberg))
-   and a single bakery-claimed Iceberg INSERT. On the very first export,
-   creates the Iceberg namespace and table.
+   and a single bakery-claimed Iceberg INSERT. Each cycle has already created
+   the Iceberg namespace and table, if missing, before the per-partition loop.
 
-3. Delta replay - applies the delta rows the export snapshot did not see to
-   Iceberg in batched commits, with no lock on the partition - concurrent
-   writers keep going and keep adding to the delta.
+3. Delta replay (`replay_archive_delta`) applies the delta rows the export
+   snapshot did not see to Iceberg in batched commits, with no lock on the
+   partition - concurrent writers keep going and keep adding to the delta.
 
-4. Atomic cutover (`cutover_archive`) - a single transaction updates
+4. The atomic cutover (`cutover_archive`) is a single transaction that updates
    `coldfront.archive_watermark` to the partition's upper bound (derived from
    `pg_catalog`, not `MAX(ts)`), takes the bakery claim on the Iceberg table,
    takes `ACCESS EXCLUSIVE` on the parent and the partition under a 100 ms
-   `lock_timeout` circuit breaker, re-issues the view DDL with the new cutoff,
-   and detaches the partition with a plain transactional `DETACH PARTITION` -
-   all of it commits atomically or rolls back whole. On a lock timeout, phases
-   3-4 are retried (10 attempts, exponential backoff from 100 ms to 51.2 s);
-   any other error fails the cycle immediately.
-
-5. Cleanup (`cutover_cleanup`) - drains stragglers that landed between phase
-   3's last commit and phase 4's lock, then drops the detached partition, the
+   `lock_timeout`, re-issues the view DDL with the new cutoff, and detaches the
+   partition with a plain transactional `DETACH PARTITION` - all of it commits
+   atomically or rolls back whole. On a lock timeout, phases 3-4 are retried
+   (10 attempts, exponential backoff from 100 ms to 51.2 s); any other error
+   fails the cycle immediately.
+
+5. Cleanup (`cutover_cleanup`) drains stragglers that landed between phase 3's
+   last commit and phase 4's lock, then drops the detached partition, the
    capture trigger, and the delta table.
 
 ### Subsequent Runs
 
 Every run executes the same cycle - the conversion above is the first cycle's
-bootstrap actually renaming the table. In order:
+bootstrap actually renaming the table. Each run performs the following steps in
+order:
 
 1. Create future partitions (default: 3) and self-heal the partition covering
-   now
+   now.
 2. Run the bootstrap, then the six-phase pipeline for each partition past the
-   hot window
-3. Delete cold rows older than `retention_period` (when configured)
+   hot window.
+3. Delete cold rows older than `retention_period` (when configured).
 
-A run with nothing past the hot window and no `retention_period` set is a
-no-op.
+A run with nothing past the hot window and no `retention_period` set only
+creates future partitions and self-heals the current one.
 
-Premake provisions a **range**, not a name. Each period it provisions is first
-checked against the parent's existing partition bounds, so a period another
-partition already covers is left alone whatever that partition is called - the
-generated `events_p_YYYY_MM` names are ColdFront's own convention, not a
-requirement on tables you bring yourself. A partition covering only part of a
-period is reported as such, naming both ranges, since PostgreSQL cannot create
-the partition that completes it.
+Premake provisions a **range**, not a name. Each period premake provisions is
+first checked against the parent's existing partition bounds, so a period
+another partition already covers is left alone whatever that partition is
+called - the generated `events_p_YYYY_MM` names are ColdFront's own convention,
+not a requirement on tables you bring yourself. A partition covering only part
+of a period is reported as such, naming both ranges, since PostgreSQL cannot
+create the partition that completes it.
 
 ### Crash Recovery
 
@@ -191,9 +199,9 @@ archiver recovers from a crash at each point in the pipeline:
 
 | Crash point | Recovery |
 |---|---|
-| During phases 0-3 (wipe, capture, export, replay) | Watermark unchanged, partition still attached; the next cycle re-runs the pipeline - the phase-0 range wipe and the delta replay are idempotent, so no duplicates |
-| During phase 4 (cutover) | The transaction rolls back whole: watermark unchanged, view unchanged, partition still attached; lock timeouts are retried in-run, anything else leaves the trigger + delta for the next cycle to retry |
-| Between phase 4 and phase 5 | The cutover is already committed (watermark, view, and DETACH all in place); the detached partition and its now-inert capture trigger + delta table are left behind for the operator to drop |
+| During phases 0-3 (wipe, capture, export, replay) | The watermark is unchanged and the partition is still attached. The next cycle re-runs the pipeline, and because the phase-0 range wipe and the delta replay are idempotent, no duplicates result. |
+| During phase 4 (cutover) | The transaction rolls back whole: the watermark and view are unchanged, and the partition is still attached. Lock timeouts are retried in the same run; any other error leaves the trigger and delta table for the next cycle to retry. |
+| Between phase 4 and phase 5 | The cutover is already committed (the watermark, view, and DETACH are all in place). The detached partition, its capture trigger, and the delta table are left behind, and the delta can still hold rows that landed after phase 3's last commit. Run `CALL coldfront.cutover_cleanup(schema, partition, NULL, iceberg_ref)` to replay the delta into Iceberg and drop the leftovers; dropping them by hand loses those rows. |
 
 ## Two-Level (LIST → RANGE) Tiering
 
@@ -215,8 +223,8 @@ values**, not value-major. Past-hot leaves are grouped by their `ts` period,
 the groups run oldest first, and within a group two passes run strictly in
 sequence:
 
-1. Export every LIST value's leaf for that period. No detach, watermark
-   unchanged.
+1. Export every LIST value's leaf for that period. This pass detaches nothing
+   and leaves the watermark unchanged.
 2. Cut them all over. The first cutover advances the watermark to the period's
    upper bound; the rest re-set it to the same value and detach their
    now-excluded leaf.
@@ -262,7 +270,7 @@ WITH hot_ins AS MATERIALIZED (
   RETURNING 1
 ),
 cold_call AS MATERIALIZED (
-  SELECT duckdb.raw_query(
+  SELECT coldfront._exec_iceberg_with_claim('ice.public.events',
     'INSERT INTO ice.public.events
      SELECT id, ts, status, data FROM (<source-pglocal-prefixed>) ...
      WHERE ts < ''<cutoff>'''
@@ -277,8 +285,8 @@ and its cost:
 
 | Cold side | When | Cost |
 |---|---|---|
-| **Bulk pglocal stream** (single `raw_query`, source streamed via libpq through DuckDB's postgres extension into the Iceberg writer in one pipeline) | Default. Used whenever the user's INSERT either (a) has no IDENTITY column on `_events`, or (b) supplies an explicit value for the IDENTITY column. DEFAULT clauses on omitted columns are inlined into the cold SELECT so DuckDB evaluates them per row. | Same as iceberg-only INSERT - one Iceberg snapshot for the whole cold subset, no per-row PG/DuckDB round-trip. |
-| **plpgsql cold-loop** (`coldfront._tiered_insert_cold` - a PG cursor over the cold subset, calls `nextval()` on the IDENTITY sequence per row, accumulates VALUES, flushes one `raw_query` per `coldfront.cold_write_batch_size` rows, default 10000) | Fallback. Only triggered when the table has an IDENTITY column AND the user's INSERT omits it - the only case that requires PG-side `nextval()` per row to keep cold ids coherent with hot. | Bounded by plpgsql per-row iteration speed (~10-50k rows/s). For very large mostly-cold seeds, prefer iceberg-only mode where ids come from the source data. |
+| The bulk pglocal stream is a single `raw_query` that streams the source via libpq through DuckDB's postgres extension into the Iceberg writer in one pipeline. | This is the default path, used whenever the user's INSERT either (a) has no IDENTITY column on `_events`, or (b) supplies an explicit value for the IDENTITY column. DEFAULT clauses on omitted columns are inlined into the cold SELECT so DuckDB evaluates them per row. | The cost matches an iceberg-only INSERT: one Iceberg snapshot for the whole cold subset, with no per-row PG/DuckDB round-trip. |
+| The plpgsql cold loop (`coldfront._tiered_insert_cold`) runs a PG cursor over the cold subset, calls `nextval()` on the IDENTITY sequence per row, accumulates VALUES, and flushes one `raw_query` per `coldfront.cold_write_batch_size` rows (default 10000). | This is the fallback path, triggered only when the table has an IDENTITY column AND the user's INSERT omits it, the only case that requires PG-side `nextval()` per row to keep cold ids coherent with hot. | Throughput is bounded by plpgsql per-row iteration speed (~10-50k rows/s). For very large mostly-cold seeds, prefer iceberg-only mode where ids come from the source data. |
 
 The hot half is always plain set-based `INSERT INTO _events` - IDENTITY
 auto-allocates server-side, full PG speed regardless of row count.
@@ -289,42 +297,49 @@ A watermark-split INSERT cannot use `RETURNING` - see Cold RETURNING under
 ## Transparent UPDATE/DELETE
 
 The hook inspects every UPDATE/DELETE whose target is a registered tiered view.
-It looks at the WHERE clause and the archive watermark, classifies the
+The hook looks at the WHERE clause and the archive watermark, classifies the
 predicate into one of three tiers, and rewrites the Query accordingly. The
 following table maps each predicate shape to its tier and rewrite:
 
 | Predicate shape | Tier | Rewrite |
 |---|---|---|
-| WHERE proves all matching rows have `ts >= cutoff` (equality, `>=`, `>`, BETWEEN, IN, OR all in hot range) | HOT | `UPDATE _events SET ... WHERE ...` - plain PG DML, preserves RETURNING |
-| WHERE proves all matching rows have `ts <  cutoff` | COLD | `SELECT duckdb.raw_query('UPDATE ice.public.events SET ... WHERE ...')` - DuckDB DML wrapped as a standard SQL literal (via `quote_literal_cstr`); the SELECT envelope keeps it off PG's command-ID counter so there's no mixed-write tripwire |
-| WHERE cannot be proven to target one tier | AMBIGUOUS | depends on `coldfront.allow_mixed_writes` - see next section |
+| The WHERE clause proves that all matching rows have `ts >= cutoff` (equality, `>=`, `>`, BETWEEN, IN, or OR, all in the hot range). | HOT | The statement becomes `UPDATE _events SET ... WHERE ...`, plain PG DML that preserves RETURNING. |
+| The WHERE clause proves that all matching rows have `ts <  cutoff`. | COLD | The statement becomes `SELECT coldfront._exec_iceberg_with_claim('ice.public.events', 'UPDATE ice.public.events SET ... WHERE ...')`, with the DuckDB DML as a standard SQL literal (via `quote_literal_cstr`), or as a `format()` call when bound parameters are present. The SELECT envelope keeps the DML off PG's command-ID counter, so pg_duckdb's mixed-write guard does not fire. |
+| The WHERE clause cannot be proven to target one tier. | AMBIGUOUS | The rewrite depends on `coldfront.allow_mixed_writes` (see the next section). |
 
-The classifier understands `Var <op> Const` (both operand orders), AND of
+The classifier understands `Var <op> bound` (both operand orders), AND of
 those, OR of those when all arms prove the same tier, BETWEEN (via its
-desugaring to AND), and `ts IN (...)` (ScalarArrayOpExpr). Subqueries, UDF
-calls, and expressions on the partition column are AMBIGUOUS.
-
-The tier classification above applies to the WHERE clause. The SET clause
-carries a separate rule for the partition column itself, because changing it
-can move a row across the cutoff. An in-place per-tier rewrite would leave such
-a row in its old tier where the view's tier predicate then hides it, so the
-hook handles a partition-column SET separately by the
-`coldfront.allow_mixed_writes` GUC:
-
-- Permissive (on, default): the hook rewrites the UPDATE to
+desugaring to AND), and `ts IN (...)` (ScalarArrayOpExpr). The bound must be
+`timestamptz`-typed: a literal, or a non-volatile expression such as
+`now() - interval '1 hour'` (a STABLE function call counts); IN-list elements
+must be `timestamptz` literals. A `date` or `timestamp` literal, a volatile
+call, a subquery, or an expression on the partition column classifies as
+AMBIGUOUS.
+
+The tier classification above applies to the WHERE clause. The SET clause has a
+separate rule for the partition column itself, because changing it can move a
+row across the cutoff. An in-place per-tier rewrite would leave such a row in
+its old tier where the view's tier predicate then hides it, so the hook handles
+a partition-column SET separately by the `coldfront.allow_mixed_writes` GUC:
+
+- When the GUC is on (permissive, the default), the hook rewrites the UPDATE to
   `SELECT coldfront._cross_tier_move(...)`, which RELOCATES each matched row
-  between tiers. The function reads the affected rows once, then applies four
-  disjoint cases by current tier and new value: stay-hot (in-place heap
-  UPDATE), stay-cold (re-add to Iceberg with the new value), hot to cold (heap
-  DELETE plus Iceberg INSERT), and cold to hot (heap INSERT plus Iceberg
-  DELETE). The hot side is plain PG; the cold side is one `duckdb.raw_query`
-  (DELETE plus INSERT, one Iceberg snapshot) under one bakery claim. A target
-  value with no covering hot partition is rejected naming the view; the move is
-  not supported inside a function or DO block, with bound parameters, with a
-  VOLATILE new value, with a bare NULL new value, with a new value referencing
-  other columns, or alongside a SET of other columns.
-- Strict (off): the hook rejects the partition-column SET. To change the
-  partition column, delete the row and re-insert it with the new value.
+  between tiers. The function first checks that every hot landing target has a
+  covering partition, then captures the affected rows and applies four disjoint
+  cases by current tier and new value: stay-hot (in-place heap UPDATE),
+  stay-cold (re-add to Iceberg with the new value), hot to cold (heap DELETE
+  plus Iceberg INSERT), and cold to hot (heap INSERT plus Iceberg DELETE). The
+  hot side is plain PG; the cold side is one `duckdb.raw_query` (DELETE plus
+  INSERT, one Iceberg snapshot) under one bakery claim. A target value with no
+  covering hot partition is rejected naming the view; the move is not supported
+  inside a function or DO block, with bound parameters, with a VOLATILE new
+  value, with a bare NULL new value, with a new value referencing other
+  columns, alongside a SET of other columns, with `RETURNING`, with a WHERE
+  that references other tables or sub-queries (`UPDATE … FROM`, a sub-select),
+  or on a hot table without a primary key.
+- When the GUC is off (strict), the hook rejects the partition-column SET. To
+  change the partition column, delete the row and re-insert it with the new
+  value.
 
 Before anything is archived (no cutoff) every row is hot, so a partition-column
 UPDATE is a plain hot UPDATE in either mode.
@@ -340,11 +355,12 @@ The hook emits a dual-tier CTE:
 
 ```sql
 WITH hot AS (UPDATE _events SET ... WHERE ... RETURNING *)
-   , cold AS (SELECT duckdb.raw_query('UPDATE ice.public.events SET ... WHERE ...'))
+   , cold AS (SELECT coldfront._exec_iceberg_with_claim('ice.public.events',
+                       'UPDATE ice.public.events SET ... WHERE ...'))
 SELECT h.* FROM hot h CROSS JOIN cold c;
 ```
 
-The CROSS JOIN forces PG to execute the cold CTE (a pure-SELECT CTE that isn't
+The CROSS JOIN forces PG to execute the cold CTE (a pure-SELECT CTE that is not
 otherwise referenced would be pruned even with MATERIALIZED). The hook also
 sets `duckdb.unsafe_allow_mixed_transactions = on` LOCAL for the current
 transaction to clear pg_duckdb's pre-commit mixed-write check. pg_duckdb's
@@ -373,17 +389,18 @@ capability reaches a peer:
 
 | Capability on a peer | How it gets there |
 |---|---|
-| **Read** (hot + cold, via the `UNION ALL` view) | The view is created by replicated DDL; hot rows arrive via normal Spock DML replication; cold rows are read from the **shared Lakekeeper catalog** that every node attaches. |
-| **INSERT** through the view | The `INSTEAD OF INSERT` trigger is part of the replicated view definition, so it fires on the peer with no registry lookup. |
-| **UPDATE / DELETE** and **DDL-blocking** | Need the `coldfront.tiered_views` row present on the peer - the hook resolves the target view through it. |
-| **Hot/cold write routing** | Needs the `coldfront.archive_watermark` row (name-keyed) so the peer's write hook knows the cutoff. |
+| Read (hot and cold, via the `UNION ALL` view) | The view is created by replicated DDL; hot rows arrive via normal Spock DML replication; cold rows are read from the shared Lakekeeper catalog, which a node attaches only for a view that has a `coldfront.tiered_views` row, so reads need that row too. |
+| INSERT through the view | The `INSTEAD OF INSERT` trigger fires on the peer with no registry lookup, but it is a separate trigger rather than part of the view definition, and its cold INSERT takes no bakery claim. |
+| UPDATE / DELETE and DDL blocking | These need the `coldfront.tiered_views` row present on the peer, because the hook resolves the target view through that row. |
+| Hot/cold write routing | Routing needs the `coldfront.archive_watermark` row (name-keyed) so the peer's write hook knows the cutoff. |
 
 So alongside the bakery substrate (`coldfront.claims` /
 `coldfront.claim_acks`), **both `coldfront.tiered_views` and
 `coldfront.archive_watermark` are added to the Spock replication set** when a
 mesh runs in tiered mode. The archiver runs on one node, so a peer only gets
-these rows by replication; without `tiered_views` a peer can read and INSERT
-but UPDATE/DELETE/DDL-blocking stop recognizing the view.
+these rows by replication; without `tiered_views` a peer cannot read the cold
+tier, can INSERT only through the trigger fallback, and UPDATE/DELETE/
+DDL-blocking stop recognizing the view.
 
 Both tables are **name-keyed** - `tiered_views` by `(schema_name, relname)`,
 `archive_watermark` by `table_name` - so each row replicates verbatim and
@@ -431,9 +448,10 @@ CREATE TABLE events_branch_1 PARTITION OF events
   FOR VALUES IN (1) PARTITION BY RANGE (ts);
 ```
 
-It requires a sub-partition block naming the query that yields the current LIST
-values, and an explicit `partition_column` for the RANGE (time) key, since on a
-first run there is no LIST child to detect it from:
+Registering such a table requires a sub-partition block naming the query that
+yields the current LIST values, and an explicit `partition_column` for the
+RANGE (time) key, since on a first run there is no LIST child to detect it
+from:
 
 ```sh
 archiver register --config cf.yaml --table events --period monthly \
@@ -456,15 +474,18 @@ query those rather than the top-level `events`.
 A query through the `events` view routes via pg_duckdb's takeover path
 (`iceberg_scan` is present, so pg_duckdb converts the whole query to DuckDB
 SQL, which issues a `postgres_scan` on `_events` where PG applies partition
-pruning natively). Pruning works, but hot-only queries pay pg_duckdb's
-roundtrip overhead; users who know their query hits only hot data can query
-`_events` directly for fully native PG with no pg_duckdb involvement:
+pruning natively). A single-table read whose WHERE proves it hot
+(`ts >= cutoff`) is rerouted to `_events` automatically and runs in plain
+PostgreSQL. Other queries through the view, such as joins or reads that span
+the cutoff, pay pg_duckdb's roundtrip overhead; users who know such a query
+hits only hot data can query `_events` directly for fully native PG with no
+pg_duckdb involvement:
 
 ```sql
--- Transparent (hot + cold via pg_duckdb):
+-- Through the view: a provably hot single-table read is rerouted to _events.
 SELECT * FROM events WHERE ts = '2026-04-15';
 
--- Zero-overhead hot-only (native PG partition pruning only):
+-- Directly on the hot table (native PG partition pruning only):
 SELECT * FROM _events WHERE ts = '2026-04-15';
 ```
 
@@ -479,7 +500,7 @@ for a two-level LIST→RANGE table the LIST column first, so `regional` becomes
 `CREATE TABLE IF NOT EXISTS` and stays with the table. Each export then writes
 exactly one partition, the Phase-0 wipe of a leaf covers exactly one, and a
 predicate on `ts` or on the LIST column skips whole manifests before any data
-file is opened: the manifest list carries each manifest's partition-value
+file is opened: the manifest list records each manifest's partition-value
 bounds, and duckdb-iceberg applies the transform to the predicate's constant to
 compare them. The comparison is by month, so an upper bound that falls exactly
 on a month's start keeps that month's manifests (`ts < '2026-07-01'` reads as
@@ -493,7 +514,7 @@ rather than the bare column); the path is opaque to readers, and iceberg-go's
 rewrites use the same field name with its own value format. Within a partition,
 each file's `min(ts)/max(ts)` statistics prune as well. Retention DELETEs and
 the wipe are position deletes, so partitioning makes reads skip months; it does
-not make deletes cheaper.
+not make deletes less expensive.
 
 ## Tiered-Specific Limitations
 
@@ -502,42 +523,55 @@ planner-level takeover, jsonb-as-json, single-node execution, S3 compatibility,
 one-time secret setup) are in
 [architecture.md → Known Limitations](architecture.md#known-limitations).
 
-The dual-tier model carries the following limitations:
-
-- **Cold RETURNING** - any write that touches the cold tier (a cold-only
-  UPDATE/DELETE, a permissive dual-tier UPDATE/DELETE, or a watermark-split
-  INSERT) **rejects `RETURNING` with a clear error** rather than returning a
-  partial result. The cold tier genuinely cannot return affected rows:
-  duckdb-iceberg's binder refuses `RETURNING` on Iceberg writes and pg_duckdb's
-  row-returning entry point is SELECT-only. Hot-only DML keeps `RETURNING` (it
-  is plain PG DML).
-
-- **Command tag** - an ambiguous dual-tier UPDATE returns `SELECT n` rather
-  than `UPDATE n`, because the rewrite produces a SELECT wrapper around a DML
-  CTE. The row count reflects hot rows only.
-
-- **Self-join / multiple references** - an UPDATE/DELETE that references the
-  same tiered view more than once - a self-join
-  (`UPDATE events ... FROM events e2`), `DELETE ... USING events`, or a
-  sub-select (`... WHERE id IN (SELECT ... FROM events)`) - is rejected with a
-  clear error. The rewrite swaps only the leading result-relation reference, so
-  a second one cannot be retargeted; reference the view once.
-
-- **Crash-safety of permissive writes** - a backend crash mid-commit can leave
+The dual-tier model has the following limitations:
+
+- Any write that touches the cold tier (a cold-only UPDATE/DELETE, a permissive
+  dual-tier UPDATE/DELETE, or a watermark-split INSERT) **rejects `RETURNING`
+  with a clear error** rather than returning a partial result. The cold tier
+  genuinely cannot return affected rows: duckdb-iceberg's binder refuses
+  `RETURNING` on Iceberg writes and pg_duckdb's row-returning entry point is
+  SELECT-only. Hot-only DML keeps `RETURNING` (it is plain PG DML).
+
+- An ambiguous dual-tier UPDATE returns the command tag `SELECT n` rather than
+  `UPDATE n`, because the rewrite produces a SELECT wrapper around a DML CTE.
+  The row count reflects hot rows only. Other rewritten writes report
+  `SELECT 1`: a top-level cold-only UPDATE/DELETE, a watermark-split INSERT
+  (which returns one `(hot_rows, cold_rows)` row), and a cross-tier move.
+  Inside PL/pgSQL, a cold-only write reports `UPDATE 0`, so `FOUND` is false.
+
+- An UPDATE/DELETE that references the same tiered view more than once - a
+  self-join (`UPDATE events ... FROM events e2`), `DELETE ... USING events`, or
+  a sub-select (`... WHERE id IN (SELECT ... FROM events)`) - is rejected with
+  a clear error. The rewrite swaps only the leading result-relation reference,
+  so a second one cannot be retargeted; reference the view once.
+
+- A backend crash in the middle of a permissive write's commit can leave
   orphaned S3 objects; see
   [Write Modes](#write-modes-strict-vs-permissive-allow_mixed_writes).
 
-- **Partitioned tables only** - the source table must already be
-  range-partitioned.
+- The source table must already be range-partitioned.
 
-- **Cutover blocked by autovacuum on freshly-loaded partitions** - Phase 4 of
+- Autovacuum on a freshly-loaded partition can block the cutover: Phase 4 of
   `archivePartition` takes `ACCESS EXCLUSIVE` on the partition under a 100 ms
-  `lock_timeout` circuit breaker. Autovacuum's `SHARE UPDATE EXCLUSIVE` on the
-  partition conflicts with that request, so when a vacuum is running the
-  cutover fails cleanly with `ERROR: canceling statement due to lock timeout`
-  and leaves the trigger + delta in place for the next cycle to retry.
-
-    Mitigation: disable autovacuum on the soon-to-be-archived partition
+  `lock_timeout`. Autovacuum's `SHARE UPDATE EXCLUSIVE` on the partition
+  conflicts with that request, so while a vacuum runs, each attempt times out
+  with `ERROR: canceling statement due to lock timeout`. The archiver retries
+  up to 10 times in the same run, with backoff from 100 ms to 51.2 s; only then
+  does the cutover fail, leaving the trigger and delta in place for the next
+  cycle.
+
+    To mitigate this, disable autovacuum on the soon-to-be-archived partition
     (`ALTER TABLE <part> SET (autovacuum_enabled = false);` - the setting goes
     with the partition when it is detached and dropped), or schedule the
     archive cycle so partitions have already settled.
+
+## Next Steps
+
+To go further with ColdFront, consult the following documents:
+
+- The [Architecture](architecture.md) overview describes the mechanics both
+  modes share.
+- The [Decoupled Mode](architecture_decoupled.md) deep dive describes the
+  bakery protocol that serializes cold writes.
+- The [Using ColdFront](usage.md) guide covers tiering a table and managing it
+  with the partition CLI.
diff --git a/docs/architecture_vectors.md b/docs/architecture_vectors.md
index 9a62eb1..6b970c1 100644
--- a/docs/architecture_vectors.md
+++ b/docs/architecture_vectors.md
@@ -1,8 +1,8 @@
 # Vector Storage Architecture
 
-Reference for maintainers. Embeddings live in the cold (Iceberg) tier as
-`list<float>`; PostgreSQL holds the hot rows, the routing centroids, and
-nothing proportional to the corpus.
+This page is a reference for maintainers. Embeddings live in the cold (Iceberg)
+tier as `list<float>`; PostgreSQL holds the hot rows, the routing centroids,
+and nothing proportional to the corpus.
 
 ## Type Mapping and the Two Column Forms
 
@@ -13,22 +13,22 @@ same type under two spellings.
 
 pg_duckdb maps PostgreSQL types by OID and has no entry for an extension type.
 The refusal lands on the column reference while the plan is built, so no cast
-in a projection can rescue it. Any plan carrying a pgvector column fails
+in a projection can rescue it. Any plan that includes a pgvector column fails
 regardless of how few rows can match.
 
-The hot table therefore carries a companion:
+The hot table therefore has a companion:
 
 ```sql
 _cf_vec_<col> real[] GENERATED ALWAYS AS (<col>::real[]) STORED
 ```
 
-Every hot-side read goes through it: the view's hot branch, the bulk export's
-projection, and the SQL-side view rebuild. `view.Column.HotRef` decides this on
-the Go side and `coldfront._vec_companion` derives the same name on the SQL
-side; the two must agree. `coldfront._is_vec_companion` keeps the companion out
-of every column list that describes the user's table, so the Iceberg schema,
-the view, the INSERT lists and the cross-tier move each carry exactly one
-column per user column. Teardown drops it.
+Every hot-side read goes through the companion: the view's hot branch, the bulk
+export's projection, and the SQL-side view rebuild. `view.Column.HotRef`
+decides this on the Go side and `coldfront._vec_companion` derives the same
+name on the SQL side; the two must agree. `coldfront._is_vec_companion` keeps
+the companion out of every column list that describes the user's table, so the
+Iceberg schema, the view, the INSERT lists and the cross-tier move each have
+exactly one column per user column. Teardown drops the companion.
 
 `STORED` is required: PostgreSQL rejects `VIRTUAL` for a user-defined
 function's expression. A hot row therefore stores its embedding twice. Cold
@@ -38,7 +38,8 @@ rows, which are all of the data by design, do not.
 
 `coldfront.install_vector_ops()` creates three functions and three operators on
 `(real[], real[])` in pgvector's own schema, resolved from the catalog rather
-than hardcoded:
+than hardcoded. The following table shows each operator, its function, and its
+metric:
 
 | Operator | Function | Metric |
 |---|---|---|
@@ -46,11 +47,15 @@ than hardcoded:
 | `<->` | `list_distance` | Euclidean |
 | `<#>` | `list_negative_inner_product` | negative inner product |
 
-pg_duckdb resolves an operator by its implementing function's *name* in
-DuckDB's catalog, so the names above are the mechanism, not a convention. The
-PostgreSQL bodies are real implementations that delegate to pgvector, because a
-hot-only (pre-cutover) view has no Iceberg scan to pull the query into DuckDB
-and PostgreSQL executes them itself.
+pg_duckdb passes the operator symbol to DuckDB, which resolves `<=>` and `<->`
+as its own aliases of `list_cosine_distance` and `list_distance`. DuckDB has no
+`<#>`, so that operator fails with a parser error on any query DuckDB runs, and
+`list_negative_inner_product(…)` is the spelling that works there. The
+PostgreSQL function names match DuckDB's, so the function-call form resolves
+too and the probe can recognize the sort expression. The PostgreSQL bodies are
+real implementations that delegate to pgvector, because a hot-only
+(pre-cutover) view has no Iceberg scan to pull the query into DuckDB and
+PostgreSQL executes them itself.
 
 The function runs at onboarding rather than at `CREATE EXTENSION`, and installs
 pgvector if it is absent. `CREATE EXTENSION coldfront` never requires pgvector.
@@ -63,19 +68,27 @@ column.
 
 ## Routing State
 
-Two tables, both name-keyed so a Spock mesh replicates them by value and every
-node resolves a vector to the same cluster id without sharing OIDs:
+Two tables hold the routing state. Both are name-keyed, so a Spock mesh
+replicates them by value and every node resolves a vector to the same cluster
+id without sharing OIDs. The following table describes what each one holds:
 
 | Table | Holds |
 |---|---|
-| `coldfront.vector_config` | `nlist`, `nprobe`, the live `generation`, `addition_cap`, per (schema, table, column) |
-| `coldfront.vector_centroids` | the centroids themselves, keyed additionally by `(generation, centroid_id)`, with `parent_id` for an adaptive addition |
+| `coldfront.vector_config` | The table holds `nlist`, `nprobe`, the live `generation`, and `addition_cap` (reserved, default 0) for each (schema, table, column). |
+| `coldfront.vector_centroids` | The table holds the centroids themselves, keyed additionally by `(generation, centroid_id)`, with a `parent_id` column that no code path sets. |
 
 Both are registered in Spock's `default` replication set by
 `coldfront._ensure_vector_state_replicated()`, gated on the Spock extension so
 vanilla is a no-op, and both are `pg_extension_config_dump`-marked: losing them
 makes every stored cluster id uninterpretable and forces a retrain.
 
+`coldfront._unregister_iceberg`, which both `release_iceberg_table` and
+`drop_iceberg_table` call, deletes the table's rows from both tables. The
+centroids and the configuration describe the table that registration named, so
+a relation registered later under the same name must not inherit them. Such a
+relation starts with no `vector_config` row, and its first training seeds with
+k-means++.
+
 `vector_centroids.centroid` is `real[]`, not a pgvector value. These tables are
 created with the extension, which must install on a database that has no
 vectors and may never have any. Scoring against them goes through the same
@@ -86,13 +99,13 @@ an assignment already stored keeps meaning what it meant, and the primary key
 rejects a repeated `centroid_id` within one generation.
 
 `coldfront.tiered_views.vec_columns` records which columns are clustered, in
-order. It cannot be derived afterwards in either mode: the view exposes
+order. The list cannot be derived afterwards in either mode: the view exposes
 `real[]` rather than the pgvector type, and a decoupled table names its types
 without holding them.
 
 ## The Cluster Columns, and Which One Owns the Sort Order
 
-A table may carry several vector columns. The Iceberg schema gets one cluster
+A table may have several vector columns. The Iceberg schema gets one cluster
 column per vector column, `_cf_vec_list_<column>`, leading the schema in column
 order, and every write path assigns all of them. The registry records the
 ordered list in `tiered_views.vec_columns`, and that order is a contract: a
@@ -116,8 +129,8 @@ cluster column from it. A column with no configuration resolves to no probe set
 and the rewrite declines.
 
 `_cf_vec_list_<column> integer` exists in the Iceberg schema and nowhere else.
-It is not a column of the hot table and neither branch of the view projects it,
-so no query written against the view can name it. `_cf_vec_list_<column>`
+The column is not part of the hot table and neither branch of the view projects
+it, so no query written against the view can name it. `_cf_vec_list_<column>`
 **leads** the Iceberg schema. Iceberg schema evolution appends, and a cold
 INSERT is positional, so a column added later has to land after everything both
 sides already agree on. Trailing the cluster column would put a user's
@@ -127,6 +140,15 @@ positional write.
 `coldfront._vec_list_col(column)` and `view.VecListColumn(column)` are the two
 spellings of the name.
 
+Adoption rebuilds `vec_columns` from the Iceberg schema, the only place the
+cluster columns' order can come from. `adopt_iceberg_table` reads the schema
+with `DESCRIBE`, whose rows arrive in schema order. It records each
+`_cf_vec_list_<column>` as a clustered `<column>` instead of projecting it, and
+runs `coldfront.install_vector_ops()` when it finds one. The routing state does
+not come back with the columns: an adopted column has no `vector_config` row
+and no centroids, so its probe declines until a configuration row is inserted
+and `vector_train` runs.
+
 ## Assignment
 
 `coldfront._vec_list_expr(schema, table, column, vec_expr)` is the only place a
@@ -154,7 +176,7 @@ planner binds the relation and hands the scan down as part of the converted
 plan. A cold write is a `raw_query` string that DuckDB binds itself, so an
 attachment is the only route in. `coldfront.ensure_pg_attached()` loads
 DuckDB's `postgres` extension and attaches the local instance as `pglocal`,
-with the DSN from the `coldfront.local_pg_dsn` GUC. Consequences: the
+with the DSN from the `coldfront.local_pg_dsn` GUC. As a consequence, the
 PostgreSQL table stays the only copy of the centroids, no path inlines a
 centroid set, and no path keeps a session copy it has no way to check.
 
@@ -163,24 +185,26 @@ statement generated once, such as a trigger body, keeps assigning against the
 live generation after a retrain instead of filtering on one that no longer
 exists.
 
-Before any training the config carries no generation, the inner query matches
+Before any training the config has no generation, the inner query matches
 nothing, and the expression yields `NULL`. Unassigned is a legitimate value:
-rows a foreign engine appended straight to Iceberg carry none either, and the
+rows a foreign engine appended straight to Iceberg have none either, and the
 read path handles them explicitly.
 
 A retrain cannot interleave with a cold write, because an operation that
 rewrites the table holds the table's claim and every cold write serializes on
 that same claim.
 
-### The Seven Paths
+### The Eight Paths
 
 Every path that can put a row into a clustered table's Iceberg storage must
-derive that row's cluster assignment; these are the seven that do it, and how:
+derive that row's cluster assignment. The following table shows the eight paths
+that do so, where each one lives, and its shape:
 
 | Path | Where | Shape |
 |---|---|---|
 | bulk archive | the Iceberg INSERT in `cmd/archiver`, not the staging SELECT | set-based |
-| tiered trigger INSERT | `internal/view` (Go) and `coldfront._rebuild_tiered_view` (SQL twin) | per statement |
+| tiered INSERT, cold half | the C rewrite (`build_cold_bulk_call`) | per statement |
+| tiered trigger INSERT | `coldfront._rebuild_write_trigger` (called by the archiver and by `_rebuild_tiered_view`) | per row |
 | slow per-row INSERT | `coldfront._tiered_insert_cold` | per row, cursor loop |
 | cross-tier move | `coldfront._move_row_literal` | per row |
 | replay drain | `coldfront.replay_archive_delta` | set-based |
@@ -198,10 +222,11 @@ INSERT INTO <ice> (_cf_vec_list_<col>, <cols>)
 SELECT <lookup>, <cols> FROM (<source>) AS coldfront_src(<cols>)
 ```
 
-The cold UPDATE adds one SET item before the statement's own WHERE, or at the
-end when it has none. `find_toplevel_where` locates it by tracking quotes
-before parens, because a literal can contain the word, a sublink carries its
-own one level down, and a literal can hold an unbalanced paren. This lives in
+The cold UPDATE adds one SET item per clustered vector column it sets, before
+the statement's own WHERE, or at the end when it has none.
+`find_toplevel_where` locates that WHERE by tracking quotes before parens,
+because a literal can contain the word, a sublink has its own WHERE one level
+down, and a literal can hold an unbalanced paren. This lives in
 `build_cold_dml` rather than in a caller: the cold path and the dual path both
 build their cold half through it, and an ambiguous predicate takes the dual
 path.
@@ -216,7 +241,7 @@ only for a clustered table, and the per-row paths guard on
 
 The generated trigger's placeholder list is apostrophe-escaped, because the
 INSERT template is itself a single-quoted string and the assignment expression
-carries the literals that name its configuration row.
+contains the literals that name its configuration row.
 
 ## Training
 
@@ -225,16 +250,17 @@ cold row's cluster against them, through this signature:
 
 `CALL coldfront.vector_train(schema, table, column, nlist, sample, iterations)`.
 
-A `PROCEDURE`, not a function, and this is a hard requirement. pg_duckdb
-refuses to execute a DuckDB query inside a function
-(`DuckDB execution is not supported inside functions`); a procedure and a `DO`
-block are exempt. `raw_query` does run inside a function but is a bare DuckDB
-channel with no PostgreSQL catalog, so a function can move data in neither
-direction.
-
-Lloyd iterations run as DuckDB statements over a reservoir sample, with fixed
-`REPEATABLE` seeds so a retrain on unchanged data reproduces the same
-centroids. The mean recompute unnests the vector against a matching `range` so
+It is a `PROCEDURE`, not a function. pg_duckdb refuses to execute a DuckDB
+query inside a function (`DuckDB execution is not supported inside functions`)
+unless `duckdb.unsafe_allow_execution_inside_functions` is on; a procedure and
+a `DO` block need no unsafe setting. `raw_query` does run inside a function,
+but it is a bare DuckDB channel with no PostgreSQL catalog.
+
+Lloyd iterations run as DuckDB statements over a reservoir sample. The sample
+and the first k-means++ seed use fixed `REPEATABLE` seeds, but later k-means++
+draws use DuckDB's unseeded `random()`, so a fresh training is not
+reproducible; a retrain at the same `nlist` continues from the live centroids
+instead. The mean recompute unnests the vector against a matching `range` so
 the two lists advance together, because DuckDB has no `WITH ORDINALITY`. The
 sample and the working tables are DuckDB temporary tables, session-scoped, so
 the whole loop must run in one call; temporary rather than `memory.main`
@@ -248,28 +274,35 @@ makes the whole statement DuckDB's, so the read and the write are separate
 statements.
 
 Empty clusters do not come back from the mean, so the stored count can be below
-`nlist`; the actual count is recorded rather than padded. A `vector_config` row
+`nlist`. Rather than padding, `vector_train` stores the trained count in
+`vector_config.nlist` and lowers `nprobe` to it if needed. Both change in one
+`UPDATE`, because a row with `nprobe` above `nlist` fails the `vc_nprobe_fit`
+check and would abort the whole training transaction. A `vector_config` row
 must exist first, since it holds the generation pointer the procedure writes.
 
 A retrain at the same `nlist` (a call without `p_nlist`, or with the trained
 count) starts the iterations from the live centroids instead of fresh seeds, so
-each centroid keeps its id and moves with its data. A first training, or a
-changed `nlist`, has no set to start from and seeds with k-means++.
+each centroid keeps its id and moves with its data. It reads the live centroids
+over `pglocal`, so it needs `coldfront.local_pg_dsn` like a cold write. A first
+training, or a changed `nlist`, has no set to start from and seeds with
+k-means++. Neither reads anything over `pglocal`, because the assignment at the
+end scores against the session's copy of the new centroids.
 
 Training ends with the loop's final step applied to the table rather than the
 sample: every cold row is assigned to its nearest centroid of the generation
 just written, in one claimed `UPDATE` whose `WHERE` is
 `cluster IS DISTINCT FROM nearest`, so only a row whose cluster changed is
-rewritten and a row with no cluster counts as changed. It scores against the
-session's copy of the new centroids (`temp.main.cf_gen`), because the rows
-inserted into `vector_centroids` in this transaction are invisible over
-`pglocal` until commit; the formula is `_vec_nearest_expr`, the same one every
-write path uses. The pointer and the assignments commit together, so no search
-ever reads a row against centroids it was not assigned under. The claim is held
-from the sample to the commit, as the compactor holds it across its read and
-rewrite, so a cold write cannot land between the two with an assignment against
-the replaced set. What the pass leaves behind is a merge-on-read delete per
-rewritten row, and those rows in update order; compaction resolves both.
+rewritten and a row with no cluster counts as changed. The UPDATE scores rows
+against the session's copy of the new centroids (`temp.main.cf_gen`), because
+the rows inserted into `vector_centroids` in this transaction are invisible
+over `pglocal` until commit; the formula is `_vec_nearest_expr`, the same one
+every write path uses. The pointer and the assignments commit together, so no
+search ever reads a row against centroids it was not assigned under. The claim
+is held from the sample to the commit, as the compactor holds it across its
+read and rewrite, so a cold write cannot land between the two with an
+assignment against the replaced set. What the pass leaves behind is a
+merge-on-read delete per rewritten row, and those rows in update order;
+compaction resolves both.
 
 Seeds come from k-means++: one sample row at random, then each next drawn with
 probability proportional to its squared distance from the nearest seed already
@@ -290,38 +323,41 @@ difference either way.
 
 ## Layout
 
-Three properties, set at `CREATE TABLE`:
+Three table properties are set at `CREATE TABLE`. The following table shows
+each property, its value, and what reads it:
 
 | Property | Value | Read by |
 |---|---|---|
 | `write.parquet.row-group-limit` | `2048` | iceberg-go |
-| `write.target-file-size-bytes` | `536870912`, unpartitioned only | both |
-| `coldfront.sort-key` | the cluster column, then the key | the compactor |
+| `write.target-file-size-bytes` | `536870912`, unpartitioned only | DuckDB writes |
+| `coldfront.sort-key` | the cluster column, then the primary key on a tiered table (the cluster column alone on a decoupled one) | the compactor |
 
 Row groups are the pruning granularity: the Parquet reader skips a row group
 whose statistics cannot match the filter. The two writers each read one
 row-group property and ignore the other. iceberg-go honors the 2048-row limit,
-so a compacted file's groups hold a median of one cluster. DuckDB reads only
-`write.parquet.row-group-size-bytes`, and a table carrying that property
-refuses every DuckDB write to it
-(`ROW_GROUP_SIZE_BYTES does not work while preserving insertion order`), so it
-is not set: a DuckDB write emits its own row groups of up to 122,880 rows, each
-a contiguous slice of the ordered stream, and compaction is what cuts them
+so a compacted file's groups hold a median of one cluster. DuckDB ignores
+`write.parquet.row-group-limit`. It honors `write.parquet.row-group-size`, a
+row count ColdFront does not set, and it refuses every write to a table that
+sets `write.parquet.row-group-size-bytes`
+(`ROW_GROUP_SIZE_BYTES does not work while preserving insertion order` when
+unpartitioned, and a not-supported error when partitioned), so that property is
+not set either: a DuckDB write emits its own row groups of up to 122,880 rows,
+each a contiguous slice of the ordered stream, and compaction is what cuts them
 down.
 
 The file target is large because on object storage every file a query touches
 is a billed round trip. A partitioned table (every tiered table, and a
 decoupled one created with `p_partition_cols`) is created without it: DuckDB
 refuses the property on a partitioned table and does not split a partitioned
-write by size anyway, and the compactor takes its target from
-`--target-size-mb`.
+write by size anyway. The compactor ignores the property on every table and
+takes its target from `--target-size-mb` (default 128 MiB).
 
-The sort key's leading column is what a compaction orders its inputs by. The
-key after it is a tiebreak for determinism, not a pruning aid: sorting by
-cluster scatters a cluster's rows through key space.
+The compactor sorts on the sort key's leading column only. The key after it is
+a tiebreak for determinism in the archiver's own `ORDER BY`, not a pruning aid:
+sorting by cluster scatters a cluster's rows through key space.
 
-Properties cannot be altered after creation on this build, so a table that
-predates its vector column keeps the defaults.
+ColdFront sets these properties only at `CREATE TABLE` and never alters them,
+so a table that predates its vector column keeps the defaults.
 
 **Batch cold writes order by cluster.** The archiver's Iceberg INSERT appends
 `ORDER BY 1` (the cluster leads the projection) plus the key, and the C bulk
@@ -330,16 +366,16 @@ internally sorted and its own row groups prune. No existing file is touched:
 sorted regions accumulate, and a probe reads the matching row groups in each of
 them.
 
-**Compaction merges those regions rather than appending them.** A table
-carrying `coldfront.sort-key` is rewritten group by group through
-`rewriteSorted` (`cmd/compactor/compact.go`), which reads the group with
-`Scan.ReadTasks`, sorts it on the sort column, and writes it back with
-`WriteRecords`. Appending the files in key order, which is what the compactor
-did while the only clustered files came from a single sorted pass, preserves
-order only while their ranges are disjoint, and an incremental write's file
-spans the whole of cluster space by construction. What that would cost is a run
-count: a probe reads at least one row group per sorted run, so bounding file
-count without merging the runs bounds the wrong thing.
+**Compaction merges those regions rather than appending them.** A table with
+`coldfront.sort-key` is rewritten group by group through `rewriteSorted`
+(`cmd/compactor/compact.go`), which reads the group with `Scan.ReadTasks`,
+sorts it on the sort column, and writes it back with `WriteRecords`. Appending
+the files in key order, which is what the compactor did while the only
+clustered files came from a single sorted pass, preserves order only while
+their ranges are disjoint, and an incremental write's file spans the whole of
+cluster space by construction. What that would cost is a run count: a probe
+reads at least one row group per sorted run, so bounding file count without
+merging the runs bounds the wrong thing.
 
 **A partition is a run boundary.** Compaction merges within a partition, never
 across, so a table partitioned by month holds at least one sorted run per
@@ -363,13 +399,15 @@ memory rather than one table.
 
 `cf_maybe_inject_probe` runs on the read path, alongside the hot-tier reroute
 and the jsonb normalization, and it is what makes the layout worth maintaining.
-It recognizes one shape and rewrites it:
+`cf_maybe_inject_probe` rewrites a query only when all of the following hold:
 
-- a single-relation `SELECT` on a registered view with a clustered vector
-  column.
-- ordered by exactly one cosine distance between that column and a constant.
-- with a `LIMIT`.
-- and at the top level of the statement.
+- the query is a single-relation `SELECT` on a registered view with a clustered
+  vector column.
+- the query is ordered by exactly one cosine distance between that column and a
+  constant, written as `<=>` or as a call to `list_cosine_distance`, with the
+  column as either argument.
+- the query has a `LIMIT`.
+- the query is at the top level of the statement.
 
 The hook sees one `Query`, so a top-k nested in a subquery or a CTE is not the
 query it is looking at. Wrapping a search to aggregate over it therefore makes
@@ -379,17 +417,17 @@ Grouping, aggregation, window functions and `DISTINCT` above that `ORDER BY`
 are accepted, and they compute over the narrowed scan: the probe restricts
 rows, and the statement's own semantics apply to what was read. The structural
 declines are joins, CTEs, set operations, sublinks and row-marks. On PostgreSQL
-18 a grouped query carries an `RTE_GROUP` entry and its sort expression
-references grouping expressions as Vars of that RTE; the hook counts that entry
-as no second relation and resolves such Vars through `groupexprs` before
-matching the shape.
+18 a grouped query has an `RTE_GROUP` entry and its sort expression references
+grouping expressions as Vars of that RTE; the hook counts that entry as no
+second relation and resolves such Vars through `groupexprs` before matching the
+shape.
 
 Everything else is left byte-identical. That is an exact scan over both tiers,
 which is correct, and it is what the product did before there was a layout.
 
-Three of those conditions are load-bearing. **The `LIMIT`** is part of the
-shape because a probe trades recall for reads: that is the bargain a top-k asks
-for, and not one to impose on a query that asked for every row in order.
+The rewrite depends on three of those conditions. **The `LIMIT`** is part of
+the shape because a probe trades recall for reads: that is the bargain a top-k
+asks for, and not one to impose on a query that asked for every row in order.
 **Cosine only**, because the centroids were trained under cosine, and ordering
 by `<->` or `<#>` would route to clusters chosen under a different metric and
 quietly return the wrong rows. **A constant query vector**, because pg_duckdb
@@ -399,9 +437,9 @@ could only be resolved from a parameter could not have run at all.
 The rewrite resolves the nearest `nprobe` centroid ids
 (`coldfront._vec_probe_ids`), turns them into a predicate
 (`coldfront._vec_probe_qual`), and substitutes the view reference for the
-view's own definition with its cold arm twice: once carrying that predicate,
-and once carrying `IS NULL` on the cluster column for the rows with no
-assignment (`coldfront._vec_probed_viewdef`):
+view's own definition with its cold arm twice: once with that predicate, and
+once with `IS NULL` on the cluster column for the rows with no assignment
+(`coldfront._vec_probed_viewdef`):
 
 ```sql
 … WHERE r['ts'] < <cutoff>
@@ -414,34 +452,37 @@ UNION ALL
 The substitution exists because the predicate has nowhere else to go: the
 cluster column is in no branch of the view, so no query written against the
 view can name it. Adding the test inside the definition puts it where the
-column exists and leaves the user's column list alone. It is a range-table
-entry swapped for a subquery, not text surgery on the caller's SQL, and
-PostgreSQL deparses the result.
+column exists and leaves the user's column list alone. The substitution is a
+range-table entry swapped for a subquery, not text surgery on the caller's SQL,
+and PostgreSQL deparses the result.
 
-The hot arm is untouched: hot rows carry no assignment and every one of them is
+The hot arm is untouched: hot rows have no assignment and every one of them is
 returned.
 
 **The unassigned arm is not optional, and it is a second arm rather than an
-OR.** Rows another engine appended straight to Iceberg carry no assignment, and
-a bare `IN` drops them silently. As its own arm it is also not expensive: the
-reader prunes it on each file's null count, so unassigned rows are read in
-proportion to their own size, and a table with none reads nothing for it. It is
-not an `OR` on the first arm because DuckDB pushes an `IN` into the scan and to
-the manifest bounds, but not an `OR` that carries `IS NULL`.
+OR.** Rows another engine appended straight to Iceberg have no assignment, and
+a bare `IN` drops them silently. The separate unassigned arm is also not
+expensive: the reader prunes it on each file's null count, so unassigned rows
+are read in proportion to their own size, and a table with none reads nothing
+for it. The unassigned arm is not an `OR` on the first arm because DuckDB
+pushes an `IN` into the scan and to the manifest bounds, but not an `OR` that
+contains `IS NULL`.
 
 **Declining is total and silent.** No centroid generation, an empty probe set,
 a view with no cold arm: each keeps today's query. This is the one place in the
 vector path that fails open, and deliberately so. A read that loses its
-predicate is slower, never wrong. A *write* that cannot resolve a generation
-fails loudly instead, because a wrong cluster id makes a row invisible to its
-own probe.
+predicate is slower, never wrong. A write with no trained generation stores no
+cluster, and every probe still reads it. A write that cannot reach the
+centroids (pglocal not attached) fails instead, because a wrong cluster id
+would make a row invisible to its own probe.
 
-Two session knobs, both `PGC_USERSET`:
+Two session settings, both `PGC_USERSET`, control the probe. The following
+table shows their defaults and effects:
 
 | GUC | Default | Effect |
 |---|---|---|
-| `coldfront.vector_probe` | `on` | `off` gives the exact scan a recall measurement compares against |
-| `coldfront.vector_nprobe` | `0` | `0` uses the column's configured `nprobe`; a value at or above `nlist` is exhaustive |
+| `coldfront.vector_probe` | `on` | `off` gives the exact scan that a recall measurement compares against. |
+| `coldfront.vector_nprobe` | `0` | `0` uses the column's configured `nprobe`; a value at or above `nlist` is exhaustive. |
 
 ## Reporting
 
@@ -449,9 +490,10 @@ Two session knobs, both `PGC_USERSET`:
 temporary table `cf_vector_status`, one row per registered clustered column. A
 procedure writing a table rather than a function returning rows, for the reason
 `vector_train` is one: pg_duckdb refuses to execute a DuckDB query inside a
-function, and a single `INSERT … SELECT` over a DuckDB scan is planned as
-DuckDB's, which cannot write a PostgreSQL table. Session lifetime rather than
-`ON COMMIT DROP` because a bare `CALL` is its own transaction.
+function unless an unsafe setting is on, and a single `INSERT … SELECT` over a
+DuckDB scan is planned as DuckDB's, which cannot write a PostgreSQL table.
+Session lifetime rather than `ON COMMIT DROP` because a bare `CALL` is its own
+transaction.
 
 Nothing is staged on the way. DuckDB groups the table by cluster and aggregates
 that grouping in one query, so a row of scalars crosses back per table, read
@@ -459,17 +501,17 @@ through `EXECUTE format(...)`: `duckdb.query` needs a constant at plan time,
 not a literal in the source, and a dynamic table name built into the executed
 text is one again. The work list is a pair of key arrays walked by index,
 because a `FOR` over a query would hold a portal open for its body and
-pg_duckdb refuses a DuckDB read while one is. `vector_train`'s `memory.main`
+pg_duckdb refuses a DuckDB read while one is. `vector_train`'s DuckDB temporary
 tables are its algorithm's own state, not a way to move a result across, and
 nothing else here needs one.
 
 The headline is `probe_fraction`: the share of the corpus a probe reads on
-average, which is the cost the layout exists to lower. Everything beside it
-explains that number when it disappoints. `rows_unassigned` is the part no
-probe can skip, since a row with no cluster is read by every one of them.
-`clusters_below_row_group` counts occupied clusters holding fewer rows than a
-row group, which is the measured floor on `nlist`. `advice` names the first
-condition that holds, or is NULL.
+average, which is the cost the layout exists to lower. Everything beside
+`probe_fraction` explains that number when it disappoints. `rows_unassigned` is
+the part no probe can skip, since a row with no cluster is read by every one of
+them. `clusters_below_row_group` counts occupied clusters holding fewer rows
+than a row group, which is the measured floor on `nlist`. `advice` names the
+first condition that holds, or is NULL.
 
 File count, bytes and row-group structure are deliberately absent. Reaching
 them means resolving a table's metadata location, which is a Lakekeeper HTTP
@@ -477,36 +519,49 @@ call, and the SQL layer makes no HTTP calls. The compactor reports files and
 bytes on every pass, and file count is the wrong health signal regardless: a
 merge bounds it without changing what a probe reads.
 
-## Current Gaps
+## Current Limitations
 
-These are properties of the code as it stands, not plans.
+The following are properties of the code as it stands, not plans:
 
-- **`coldfront._tiered_insert_cold` writes unsorted.** Its cursor loop appends
-  in cursor order and would need buffering to sort. It is the fallback path for
-  a tiered INSERT that omits an IDENTITY column.
+- `coldfront._tiered_insert_cold` writes unsorted: its cursor loop appends in
+  cursor order and would need buffering to sort. The function is the fallback
+  path for a tiered INSERT that omits an IDENTITY column.
+- The replay drain (`coldfront.replay_archive_delta`) and the cross-tier move
+  also write without ordering by cluster.
 
 ## Constraints That Are Correctness
 
 These are not implementation quirks to work around; violating any of them
 produces silently wrong results or a hard failure:
 
-- **The query vector is a literal, never a bound parameter.** A parameter typed
+- The query vector is a literal, never a bound parameter. A parameter typed
   `vector` fails to convert, and so does one typed `real[]`, on a custom plan
   as much as a generic one. A scalar parameter elsewhere in the same query is
   fine.
-- **`'{…}'::real[]` does not work as the query vector.** It reaches DuckDB as a
-  VARCHAR and fails to cast. The spelling is `ARRAY[…]::real[]`.
-- **`embedding::vector <=> …` fails** with
-  `Type with name vector does not exist!`, and materializing the read does not
-  help. The unadorned form resolves, so nothing needs the cast.
-- **There is no PostgreSQL-side fallback.** When a view embeds `iceberg_scan`,
+- `'{…}'::real[]` does not work as the query vector. That form reaches DuckDB
+  as a VARCHAR and fails to cast. The spelling is `ARRAY[…]::real[]`.
+- `embedding::vector <=> …` fails with `Type with name vector does not exist!`,
+  and materializing the read does not help. The unadorned form resolves, so
+  nothing needs the cast.
+- There is no PostgreSQL-side fallback. When a view embeds `iceberg_scan`,
   DuckDB owns the whole query and a function it lacks is a hard error rather
   than a slow path. Every expression the product wants users to write has to
   resolve in DuckDB.
-- **Cosine everywhere.** Assignment and search both use cosine. `list_distance`
-  is Euclidean and would be silently wrong against cosine centroids.
-- **No `EXCEPTION` block in any of this plpgsql.** pg_duckdb rejects
+- Assignment and search both use cosine distance everywhere. `list_distance` is
+  Euclidean and would be silently wrong against cosine centroids.
+- None of this plpgsql uses an `EXCEPTION` block, because pg_duckdb rejects
   subtransactions outright.
-- **`coldfront.local_pg_dsn` must be set** for a clustered table, or the
-  assignment lookup fails with `Catalog 'pglocal' does not exist`. The shipped
-  container configuration sets it.
+- `coldfront.local_pg_dsn` must be set for a clustered table, or the assignment
+  lookup fails with `Catalog "pglocal" does not exist!`. The shipped container
+  configuration sets it.
+
+## Next Steps
+
+To go further with ColdFront, consult the following documents:
+
+- The [Embeddings](usage_vectors.md) guide covers declaring, training, and
+  searching vector columns.
+- The [Compaction](compaction.md) guide covers the maintenance that restores
+  cluster order.
+- The [Architecture](architecture.md) overview describes the mechanics both
+  modes share.
diff --git a/docs/changelog.md b/docs/changelog.md
index be1c8a4..ab7ba7e 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -1,122 +1,124 @@
 # Changelog
 
-All notable changes to pgEdge ColdFront will be documented in this
-file.
+All notable changes to pgEdge ColdFront will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/),
-and this project adheres to
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and
+this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.0.0-rc1] - 2026-09-28
 
 ### Added
 
-- pgvector columns tier like any other column. The archiver carries them to
-  Iceberg as `list<float>`, the tiered view keeps the pgvector query
-  interface, and writes through the view work unchanged on both tiers. A
-  table may carry several vector columns, with the Iceberg file layout
-  sorted for one of them.
+- pgvector columns tier like any other column. The archiver writes them to
+  Iceberg as `list<float>`, the tiered view keeps the pgvector query interface,
+  and writes through the view work unchanged on both tiers. A table may have
+  several vector columns, with the Iceberg file layout sorted for one of them.
 - `coldfront.vector_train` clusters a vector column with k-means and assigns
   the cold rows to the clusters; a retrain without a new `nlist` keeps each
   centroid's identity and rewrites only the rows whose nearest centroid
   changed. Every cold write assigns each row to its nearest cluster, the
-  compactor keeps that
-  layout, and a nearest-neighbour search through the view reads the nearest
-  clusters, `nlist` and `nprobe` being per-column settings, plus the rows
-  that carry no assignment. Grouped, aggregated, windowed and `DISTINCT`
-  shapes are recognised; an unrecognised shape scans exactly.
+  compactor keeps that layout, and a nearest-neighbour search through the view
+  reads the nearest clusters, `nlist` and `nprobe` being per-column settings,
+  plus the rows that have no assignment. Grouped, aggregated, windowed and
+  `DISTINCT` shapes are recognised; an unrecognised shape scans exactly.
   `coldfront.vector_status` reports cluster health.
+- `coldfront.adopt_iceberg_table()` gives a table that already exists in the
+  Iceberg catalog a PostgreSQL wrapper view and a registry row, so it reads
+  like one ColdFront created. The schema comes from the catalog, and `p_types`
+  restores a type Iceberg cannot record. Adoption is read-only unless
+  `p_writable => true` arms the write path.
+- `coldfront.release_iceberg_table()` hands an adopted table back: the wrapper
+  view and the registry row go, and the Iceberg table keeps every row.
+- Cold tables are partitioned. The archiver creates a tiered table's Iceberg
+  table partitioned the way the hot table is, `month(ts)` or `day(ts)` on the
+  time column, led by the LIST column of a two-level table, so each export is
+  one partition and a query with a time filter skips the months outside it
+  before reading anything.
+- `coldfront.create_iceberg_table()` takes `p_partition_cols`, the partitioning
+  as DuckDB's own `PARTITIONED BY` terms: `'{month(ts)}'`,
+  `'{month(ts), region}'`, `'{"bucket(16, id)"}'`.
 - Reads that DuckDB executes accept `date_bin` (rewritten to `time_bucket`),
   `jsonb_build_object` and `jsonb_agg` with their `json_` twins (`ORDER BY`,
-  `FILTER` and `DISTINCT` kept), and bound parameters where DuckDB cannot
-  type a placeholder. Such reads are planned from their values each
-  execution, so `plan_cache_mode = force_generic_plan` cannot run them. A
-  view named in a CTE, sub-select or set-operation branch is detected
-  wherever it sits in the statement.
+  `FILTER` and `DISTINCT` kept), and bound parameters where DuckDB cannot type
+  a placeholder. Such reads are planned from their values each execution, so
+  `plan_cache_mode = force_generic_plan` cannot run them. A view named in a
+  CTE, sub-select or set-operation branch is detected wherever it sits in the
+  statement.
+- The base image includes a fourth duckdb-iceberg patch, a port of upstream
+  d3c3348271, so the month of a `timestamptz` partition column is its UTC month
+  whatever the session's time zone.
 - `--version` on the archiver, the partitioner and the compactor.
-- Cold tables are partitioned. The archiver creates a tiered table's
-  Iceberg table partitioned the way the hot table is, `month(ts)` or
-  `day(ts)` on the time column, led by the LIST column of a two-level
-  table, so each export is one partition and a query with a time filter
-  skips the months outside it before reading anything.
-- `coldfront.create_iceberg_table()` takes `p_partition_cols`, the
-  partitioning as DuckDB's own `PARTITIONED BY` terms: `'{month(ts)}'`,
-  `'{month(ts), region}'`, `'{"bucket(16, id)"}'`.
-- The base image carries a fourth duckdb-iceberg patch, a port of upstream
-  d3c3348271, so the month of a `timestamptz` partition column is its UTC
-  month whatever the session's time zone.
-- `coldfront.adopt_iceberg_table()` gives a table that already exists in
-  the Iceberg catalog a PostgreSQL wrapper view and a registry row, so it
-  reads like one ColdFront created. The schema comes from the catalog, and
-  `p_types` restores a type Iceberg cannot record. Adoption is read-only
-  unless `p_writable => true` arms the write path.
-- `coldfront.release_iceberg_table()` hands an adopted table back: the
-  wrapper view and the registry row go, and the Iceberg table keeps every
-  row.
 
 ### Changed
 
-- `coldfront.tiered_views` carries an `is_writable` column and a unique
-  constraint on `iceberg_table`. Every existing registration is writable,
-  and one relation is registered per Iceberg table.
-- `coldfront.drop_iceberg_table()` refuses a relation adopted read-only,
-  and builds its catalog DDL from the stored Iceberg reference rather than
-  from the PostgreSQL schema and table names.
 - The mesh bakery no longer needs the `dblink` extension. Claims, acks,
   releases and orphan reaping run over a libpq loopback connection that the
   extension opens from `coldfront.dblink_self`.
+- `coldfront.tiered_views` has an `is_writable` column and a unique constraint
+  on `iceberg_table`. Every existing registration is writable, and one relation
+  is registered per Iceberg table.
+- `coldfront.drop_iceberg_table()` refuses a relation adopted read-only, and
+  builds its catalog DDL from the stored Iceberg reference rather than from the
+  PostgreSQL schema and table names.
 - Registering a tiered table rejects a column whose type has no Iceberg
   mapping, instead of failing at the first archive cycle.
+- The walkthrough's distributed demo shows the bakery at work on one held
+  write: the ticket on the writing node, the same claim on its peer, the peer's
+  ack, and the ledger cleared once the write commits. After the concurrent
+  writes it lists the table's snapshot history.
 
 ### Fixed
 
+- After one cold write on a mesh, an app role could run any SQL as the loopback
+  connection's user through the `coldfront_self` dblink connection the claim
+  left open in its session, and by setting `coldfront.dblink_self` it could
+  make the loopback run functions of its own as that user. An app role can no
+  longer reach the loopback or set its connection string, and the loopback
+  resolves names in `pg_catalog` only.
+- The compactor read a table before taking its bakery claim. A run that had to
+  wait for a cold write then had its commit refused and exited with an error,
+  and an orphan-file pass with `--orphan-age 0s` could delete the files that
+  write had just committed. Each step now reads the table under its claim.
+- The compactor claimed a table made by `coldfront.create_iceberg_table()`
+  under a different spelling of its Iceberg reference than the one cold writes
+  to it claimed, so compaction and snapshot expiry did not wait for those
+  writes. Every registration now stores the reference with each part quoted,
+  which is how the archiver and the compactor spell it.
+- On a server that has `output_plugin_libraries` (PostgreSQL 16.15, 17.11 and
+  18.6), no Spock subscription could create its replication slot, because the
+  setting's default leaves out `spock_output`. The Docker image adds
+  `spock_output` to it on mesh nodes, and the per-node configuration in the
+  usage guide lists it.
+- Backends that shared one `duckdb.temporary_directory` overwrote each other's
+  spill files, since DuckDB numbers them from zero per instance, and a backend
+  whose DuckDB instance ended deleted its peers' spills. Each backend now
+  spills into its own subdirectory of the configured path, and the files of a
+  departed backend are removed.
+- A transaction that made two cold writes to the same table on a mesh hung on
+  its own first claim. A transaction now holds one claim per table.
+- A writer terminated in the middle of its claim could leave a claim that the
+  node's next writer on that table waited behind indefinitely.
+- A cold write on a mesh that failed or was cancelled during its claim left an
+  advisory lock held for the rest of the session, and the node's other writers
+  on that table waited on it. Every lock the claim takes now ends with a
+  transaction.
+- A mesh session whose loopback connection had died failed every later cold
+  write. The loopback now reconnects.
 - `CREATE EXTENSION coldfront` failed on a database the standalone partitioner
   had already set up ("table partition_config is not a member of extension"):
   the extension now adopts that table, registrations included.
-- After one cold write on a mesh, an app role could run any SQL as the
-  loopback connection's user through the `coldfront_self` dblink connection
-  the claim left open in its session, and by setting
-  `coldfront.dblink_self` it could make the loopback run functions of its
-  own as that user. An app role can no longer reach the loopback or set its
-  connection string, and the loopback resolves names in `pg_catalog` only.
-- A cold write on a mesh that failed or was cancelled during its claim left
-  an advisory lock held for the rest of the session, and the node's other
-  writers on that table waited on it. Every lock the claim takes now ends
-  with a transaction.
-- A mesh session whose loopback connection had died failed every later cold
-  write. The loopback now reconnects.
-- A transaction that made two cold writes to the same table on a mesh hung
-  on its own first claim. A transaction now holds one claim per table.
-- A writer terminated in the middle of its claim could leave a claim that
-  the node's next writer on that table waited behind indefinitely.
-- On a server that has `output_plugin_libraries` (PostgreSQL 16.15, 17.11
-  and 18.6), no Spock subscription could create its
-  replication slot, because the setting's default leaves out
-  `spock_output`. The Docker image adds `spock_output` to it on mesh nodes,
-  and the per-node configuration in the usage guide lists it.
-- The compactor claimed a table made by `coldfront.create_iceberg_table()`
-  under a different spelling of its Iceberg reference than the one cold
-  writes to it claimed, so compaction and snapshot expiry did not wait for
-  those writes. Every registration now stores the reference with each part
-  quoted, which is how the archiver and the compactor spell it.
-- The compactor read a table before taking its bakery claim. A run that had
-  to wait for a cold write then had its commit refused and exited with an
-  error, and an orphan-file pass with `--orphan-age 0s` could delete the
-  files that write had just committed. Each step now reads the table under
-  its claim.
-- The pg_duckdb packages for different PostgreSQL majors could not be
-  installed side by side: each claimed the same build-id link for the
-  bundled `libduckdb.so`. The RPMs carry no build-id links and the DEBs no
-  longer produce dbgsym packages.
-- `partitioner import` refused a file without a `postgres` section, which
-  is what `export` writes, even with `--dsn` given. A tables-only file now
+- The pg_duckdb packages for different PostgreSQL majors could not be installed
+  side by side: each claimed the same build-id link for the bundled
+  `libduckdb.so`. The RPMs contain no build-id links and the DEBs no longer
+  produce dbgsym packages.
+- `partitioner import` refused a file without a `postgres` section, which is
+  what `export` writes, even with `--dsn` given. A tables-only file now
   imports, each table validated as tiered when it has a `hot_period` and as
   partition-only otherwise.
-- Backends that shared one `duckdb.temporary_directory` overwrote each
-  other's spill files, since DuckDB numbers them from zero per instance, and
-  a backend whose DuckDB instance ended deleted its peers' spills. Each
-  backend now spills into its own subdirectory of the configured path, and
-  the files of a departed backend are removed.
+- The walkthrough's guide ran whatever archiver image an earlier run had built,
+  because the `archiver` service sits behind a Compose profile that
+  `up --build` skips. The guide now builds that image at bring-up.
 
 ## [1.0.0-beta2] - 2026-08-08
 
@@ -124,10 +126,10 @@ and this project adheres to
 
 - `coldfront.drop_iceberg_table()` drops a decoupled or tiered table, with
   purge or keep-files for the stored objects.
-- Vended object-store credentials, so cold access can use
-  short-lived credentials issued by Lakekeeper instead of static keys.
-- Cross-tier row relocation: an UPDATE that moves a row's partition key
-  across the cutoff now moves the row between tiers.
+- Vended object-store credentials, so cold access can use short-lived
+  credentials issued by Lakekeeper instead of static keys.
+- Cross-tier row relocation: an UPDATE that moves a row's partition key across
+  the cutoff now moves the row between tiers.
 - Multi-arch base images: linux/amd64 and linux/arm64.
 - An interactive walkthrough with four demos, runnable in Codespaces.
 
@@ -140,8 +142,8 @@ and this project adheres to
 ### Fixed
 
 - Cold-tier writes are refused on a standby in every path that reaches them.
-- Exotic partition bounds parse correctly, DEFAULT partitions are refused,
-  and timestamp-without-time-zone bounds are handled.
+- Exotic partition bounds parse correctly, DEFAULT partitions are refused, and
+  timestamp-without-time-zone bounds are handled.
 - `oid` columns are rejected as unsupported rather than failing later.
 - Same-node cold writers serialise through a node-local advisory lock, and
   bakery acknowledgements match on the spock node name.
@@ -149,26 +151,25 @@ and this project adheres to
 
 ## [1.0.0-beta1] - 2026-06-18
 
-First public beta of pgEdge ColdFront. Pre-release software; not for
-production use.
+First public beta of pgEdge ColdFront. Pre-release software; not for production
+use.
 
 ### Added
 
-- Tiered mode keeps recent data in native PostgreSQL partitions and
-  archives older data to Apache Iceberg on a watermark, presented to the
-  application as a single unified view.
-- Decoupled mode stores a table entirely in Iceberg from the first row,
-  with PostgreSQL holding a thin wrapper view and the coldfront
-  extension handling every data-modifying statement on that view.
-- Horizontal scale-out for decoupled mode across multiple PostgreSQL
-  nodes sharing one Lakekeeper catalog and one object store, serialised
-  by the bakery protocol; the protocol implements Lamport mutual
-  exclusion with the Ricart-Agrawala optimisation and its safety is
-  verified in TLA+.
+- Tiered mode keeps recent data in native PostgreSQL partitions and archives
+  older data to Apache Iceberg on a watermark, presented to the application as
+  a single unified view.
+- Decoupled mode stores a table entirely in Iceberg from the first row, with
+  PostgreSQL holding a thin wrapper view and the coldfront extension handling
+  every data-modifying statement on that view.
+- Horizontal scale-out for decoupled mode across multiple PostgreSQL nodes
+  sharing one Lakekeeper catalog and one object store, serialised by the bakery
+  protocol; the protocol implements Lamport mutual exclusion with the
+  Ricart-Agrawala optimisation and its safety is verified in TLA+.
 - The coldfront PostgreSQL extension at version 1.0.
-- Archiver and partitioner binaries for the tiered workflow, plus a
-  separate compactor for Iceberg table maintenance.
-- Support for PostgreSQL 16, 17, and 18 on stock upstream builds, with
-  Iceberg reads and writes through pg_duckdb.
-- Support for any S3-compatible object store, Azure Blob Storage, and
-  Google Cloud Storage.
+- Archiver and partitioner binaries for the tiered workflow, plus a separate
+  compactor for Iceberg table maintenance.
+- Support for PostgreSQL 16, 17, and 18 on stock upstream builds, with Iceberg
+  reads and writes through pg_duckdb.
+- Support for any S3-compatible object store, Azure Blob Storage, and Google
+  Cloud Storage.
diff --git a/docs/compaction.md b/docs/compaction.md
index 4f36636..449df08 100644
--- a/docs/compaction.md
+++ b/docs/compaction.md
@@ -8,9 +8,10 @@ busy table accumulates tens of thousands of tiny files and an unbounded
 snapshot history. The compactor is a standalone static binary built on
 [apache/iceberg-go], separate from the archiver. Every operation that mutates a
 table is serialized through the ColdFront bakery - the same claim cold writes
-take - so it never conflicts (409s) with concurrent writers, on a single node
-or across a Spock mesh. The compactor runs against a primary; against a
-read-only standby it exits with an error.
+take - so it never conflicts (HTTP 409) with concurrent writers, on a single
+node or across a Spock mesh. The compactor runs against a primary; against a
+read-only standby, any run other than `--dry-run` fails at its first bakery
+claim.
 
 [apache/iceberg-go]: https://github.com/apache/iceberg-go
 
@@ -19,25 +20,28 @@ read-only standby it exits with an error.
 Run the compactor against a deployment config, naming the table to maintain:
 
 ```text
-compactor --config <yaml> --table <name> [flags]
+compactor --config <yaml> --table <[schema.]name> [flags]
 ```
 
+A bare table name means the `public` schema; the schema is also the table's
+Iceberg namespace.
+
 The following table describes the flags that control which maintenance steps
 run and how aggressively each reclaims:
 
 | Flag | Default | Effect |
 |---|---|---|
-| `--target-size-mb N` | 128 | compaction target file size; only files well below it are rewritten |
-| `--expire-snapshots` | off | expire old snapshots and (by default) delete the files they alone pinned |
-| `--expire-older-than D` | 168h | with `--expire-snapshots`: expire snapshots older than D - lower it to reclaim sooner |
-| `--expire-retain-last N` | 1 | with `--expire-snapshots`: always keep at least the N most-recent snapshots |
-| `--expire-keep-files` | off | expire metadata only; leave the freed files for an `--orphans` pass |
-| `--orphans` | off | delete files under the table location that no retained snapshot references |
-| `--orphan-age D` | 72h | with `--orphans`: only delete files older than D - protects in-flight writes; never set 0 in production |
-| `--version` |  | print the version and exit |
-| `--dry-run` | off | report what each step would do; change nothing |
-
-Compaction always runs (a no-op when nothing is below target);
+| `--target-size-mb N` | 128 | Sets the compaction target file size; files below 75% of it are rewritten. |
+| `--expire-snapshots` | off | Expires old snapshots and, by default, deletes the files they alone pinned. |
+| `--expire-older-than D` | 168h | With `--expire-snapshots`, expires snapshots older than D; lower the value to reclaim sooner. |
+| `--expire-retain-last N` | 1 | With `--expire-snapshots`, always keeps at least the N most recent snapshots. |
+| `--expire-keep-files` | off | With `--expire-snapshots`, expires metadata only and leaves the freed files for an `--orphans` pass. |
+| `--orphans` | off | Deletes files under the table location that no retained snapshot references. |
+| `--orphan-age D` | 72h | With `--orphans`, deletes only files older than D, which protects in-flight writes; never set the value to 0 in production. |
+| `--version` |  | Prints the version and exits. |
+| `--dry-run` | off | Reports what each step would do and changes nothing; for snapshot expiry it reports only the snapshot count and the `--expire-retain-last` floor. |
+
+Compaction always runs (a no-op when no partition has enough small files);
 `--expire-snapshots` and `--orphans` are opt-in. A typical maintenance pass
 looks like this:
 
@@ -46,45 +50,50 @@ compactor --config deploy.yaml --table events --expire-snapshots --orphans
 ```
 
 The config is the same deployment YAML the archiver reads - `postgres.dsn` (for
-the bakery claim), `iceberg.{warehouse, lakekeeper_endpoint}`, and exactly one
-cold-store stanza.
+the bakery claim), `iceberg.{warehouse, lakekeeper_endpoint}`, and at most one
+cold-store stanza: `s3:` or `azure:` for static credentials, or none when the
+deployment uses vended credentials (`set_storage_secret_vended`).
 
 ## Backends
 
-The following table lists the backends a single binary serves; configure
-exactly one:
+The following table lists the backends a single binary serves; configure at
+most one, and none for vended credentials:
 
 | Backend | Config |
 |---|---|
 | S3-compatible (SeaweedFS, MinIO) | `s3: {endpoint, region, access_key, secret_key, use_ssl, url_style}` |
-| AWS S3 | `s3:` with no `endpoint` (uses the AWS SDK credential chain) |
-| Google Cloud Storage | `s3:` pointed at `storage.googleapis.com` with HMAC keys (S3-interop) |
-| Azure ADLS Gen2 | `azure: {connection_string}` |
+| AWS S3 | `s3: {region, access_key, secret_key}` with no `endpoint`; without keys, the AWS SDK default credential chain applies |
+| Google Cloud Storage | `s3: {endpoint: storage.googleapis.com, use_ssl: true, access_key, secret_key}` with HMAC keys (S3 interoperability) |
+| Azure ADLS Gen2 | `azure: {connection_string}`, which must contain `AccountName` and `AccountKey` (shared key) |
 
 ## How It Works
 
 The compactor loads the table from the Lakekeeper catalog and runs the
 requested steps, each under a bakery claim on that table:
 
-- **Compaction** bin-packs below-target data files, partition by partition, and
-  rewrites each group into one larger file under its partition, preserving
-  every row (existing deletes are applied). If nothing is below target it does
-  nothing. Before planning, each data file's position-delete files are scoped
-  to its own partition, the only ones that can reference its rows: iceberg-go
-  attaches them by the delete file's `file_path` bounds, which duckdb-iceberg
-  writes under DuckDB's own field id, so it would otherwise attach every delete
-  file to every data file and remove a skipped partition's delete files along
-  with a rewritten one.
-- **Snapshot expiry** is age-driven: it drops snapshots older than
+- Compaction rewrites data files below 75% of the target size, plus any file
+  with five or more delete files, bin-packing them partition by partition into
+  larger files under their partition and preserving every row (existing deletes
+  are applied). A partition, and each bin within it, needs at least five such
+  files, so a partition with fewer is left alone. When the table property
+  `coldfront.sort-key` names a column, each group is sorted on that column as
+  it is rewritten; if the column does not exist, compaction is skipped with a
+  `NOT compacted` warning and the other steps still run. Before planning, each
+  data file's position-delete files are scoped to its own partition, the only
+  ones that can reference its rows: iceberg-go attaches them by the delete
+  file's `file_path` bounds, which duckdb-iceberg writes under DuckDB's own
+  field id, so it would otherwise attach every delete file to every data file
+  and remove a skipped partition's delete files along with a rewritten one.
+- Snapshot expiry is age-driven: it drops snapshots older than
   `--expire-older-than` (always keeping the current snapshot and at least
   `--expire-retain-last`) and, by default, deletes the data and manifest files
   only those snapshots referenced. This is what reclaims the small files a
   compaction supersedes - they stay pinned by the pre-compaction snapshot until
   it is expired.
-- **Orphan removal** deletes files under the table location that no retained
-  snapshot references - the safety net for files left by an interrupted write
-  or by `--expire-keep-files`. The `--orphan-age` window keeps a concurrent
-  writer's freshly-staged files from being removed.
+- Orphan removal deletes files under the table location that no retained
+  snapshot references, which covers files left by an interrupted write or by
+  `--expire-keep-files`. The `--orphan-age` window keeps a concurrent writer's
+  freshly-staged files from being removed.
 
 Each mutating step holds the bakery claim across its catalog commit and
 releases it when its PostgreSQL transaction commits, so it cannot interleave
@@ -94,4 +103,16 @@ not the catalog's: Lakekeeper does no Iceberg snapshot or orphan maintenance.
 ## Requirements
 
 The compactor (`cmd/compactor`, apache/iceberg-go) reads the cold-tier Iceberg
-tables directly. Build the binary with `make compactor`.
+tables directly. Build the binary with `make compactor`, which vets, lints
+(golangci-lint required), tests, and builds `./bin/compactor`.
+
+## Next Steps
+
+To go further with ColdFront, consult the following documents:
+
+- The [Using ColdFront](usage.md) guide covers the deployment YAML the
+  compactor shares with the archiver.
+- The [Vector Storage](architecture_vectors.md) deep dive describes the sort
+  key the compactor applies to clustered tables.
+- The [Architecture](architecture.md) overview describes the bakery claim each
+  compaction step takes.
diff --git a/docs/formal/README.md b/docs/formal/README.md
index 40bdaf5..1b578c6 100644
--- a/docs/formal/README.md
+++ b/docs/formal/README.md
@@ -9,7 +9,7 @@ The CI journey (`ci/journey.sh` - `story_mesh` / `story_decoupled_concurrency`
 / `story_mesh_substrate`, driven by `ci/matrix.sh`) tests the protocol against
 a fixed mesh shape - three docker containers, single iceberg table, well-paced
 workload. The model exhaustively explores **every interleaving** of N writers
-within bounded depth, including failure injections that the CI can't easily
+within bounded depth, including failure injections that the CI cannot easily
 reproduce.
 
 ## Files
@@ -20,20 +20,20 @@ an explicit applier. The following table describes its files and their roles:
 
 | File | Role |
 |---|---|
-| `Bakery.tla` | PlusCal source.  Models the real Spock world: each node has its OWN local `claims[nd]` view, INSERTs propagate via an explicit `Applier`.  No `synchronous_commit = remote_apply`.  Coordination is Lamport's 1978 distributed mutual exclusion algorithm with Ricart-Agrawala's (1981) deferred-reply optimization: peers ack each claim immediately unless they have a pending claim with smaller ticket, in which case they defer the ack until they release their own claim.  Also models the `coldfront.iceberg_async_parquet` flag (constants `AsyncParquet`/`RestampPatch`): the `Stage` label stages parquet OUTSIDE the claim (async ordering); `Prepare` captures the `parent_snapshot_id` UNDER the claim (stock at stage time, patched async re-stamped at the commit POST); the `Decide` CAS asserts against it.  **Defer/drain atomicity** is modeled too (constant `SafeAcks`): the apply-time defer DECISION and its WRITE (`ApplyDecide`/`ApplyEmit`), and the release drain's FORWARD and DELETE (`DrainForward`/`DrainDelete`), are SEPARATE steps - faithful to the non-atomic SQL.  `SafeAcks=FALSE` lets them race (a deferral written behind a just-released claim is deleted unforwarded / orphaned - a dropped ack); `SafeAcks=TRUE` is the safe implementation: an atomic re-check of R-A's own defer rule against the claim, i.e. `SELECT … FOR UPDATE` on the claim row in `coldfront._on_claim_apply`.  **The orphan reaper** (constant `Reaper`): a same-node claim whose writer has crashed holds no advisory lock, so `BeginClaim` deletes it in the step that inserts its own claim; the `Applier` does the same on its defer branch under `HoldsTableLock(nd)` (a live writer holds `coldfront_iceberg:<table>` from `WaitAcks` through `DrainDelete`, because the release runs in the COMMIT callback before PostgreSQL drops the xact lock); and a `Poker` process models the waiter's periodic no-op UPDATE of its own claim row, which re-runs the peer's defer branch and is what unwedges a waiter whose peer's holder died after deferring to it. Constant `NodeRetries` restricts the `Crasher` to writers whose node still has an unstarted writer (the node is touched again); FALSE allows the crash after which only the poke reaches the node. The `Crasher` cannot split `Release`/`DrainForward`/`DrainDelete`, which are one loopback transaction in the real code. |
-| `Bakery.cfg` | TLC config: 3 writers, no crashes, all four safety invariants. **Stock ordering** (`AsyncParquet=FALSE` - the default; parquet staged inside the claim).  Passes - R-A makes `NoLakekeeperConflict` and `TicketOrderPreserved` hold even with realistic asymmetric apply. |
-| `Bakery_async.cfg` | **Patched async ordering** (`AsyncParquet=TRUE, RestampPatch=TRUE`) - what the DuckDB 1.5.x (duckdb15) image runs: parquet staged outside the claim, `parent_snapshot_id` re-stamped at the commit POST under the claim by the bakery-aware patch.  All four safety invariants HOLD; the test is non-vacuous (shares the stock config's under-claim `Prepare→Decide` window, which R-A keeps empty). |
-| `Bakery_race.cfg` | **Pre-patch async race** (`AsyncParquet=TRUE, RestampPatch=FALSE`) - async ordering WITHOUT the bakery-aware patch: the stale tentative parent from the pre-claim stage is used at the POST. **`NoLakekeeperConflict` is EXPECTED to be violated** - the formal proof that the patch is mandatory for the async ordering. |
-| `Bakery_crash.cfg` | 3 writers, 1 crash budget (stock ordering - crash-safety is ordering-independent).  Safety invariants still hold (a crashed peer's missing ack leaves surviving writers blocked at `WaitAcks` - no incorrect commits). |
-| `Bakery_live.cfg` | **The defer/drain race** (`SafeAcks=FALSE`) - the non-atomic implementation. **`EventualProgress` is EXPECTED to be VIOLATED**: a deferred ack written behind a just-released claim is dropped, stranding the min-ticket holder at `WaitAcks` forever - the N-writer wedge this race produces. The four safety invariants still HOLD (a dropped ack is a liveness failure, not a wrong commit). No `SYMMETRY` (unsound with liveness checking). |
-| `Bakery_fixed.cfg` | **The fix** (`SafeAcks=TRUE`) - the atomic defer/drain (`FOR UPDATE` on the claim row). `EventualProgress` HOLDS *and* all four safety invariants hold: the formal proof the fix restores liveness without weakening safety. |
-| `Bakery_samenode_race.cfg` | **Multiple cold writers per node, no same-node lock** (`NodeParts={{a1,a2},{b1}}`, `SameNodeLock=FALSE`). Two same-node claims `a1<a2` below a peer's `b1`: the node defers `b1` behind its smallest same-node claim `a1` and, on `a1`'s release, forwards the ack for `b1` without re-deferring behind `a2` (still held, still `< b1`), so `a2` and `b1` both clear the bakery. **`NoLakekeeperConflict` is EXPECTED to be violated** - the multi-writer-per-node race, reproduced in the model. |
-| `Bakery_samenode.cfg` | **The fix** (`SameNodeLock=TRUE`) - `coldfront._claim_iceberg_lock`'s node-local advisory xact lock, so at most one same-node writer is in the bakery at a time. `a1` and `a2` never coexist; the topology collapses to one active claim per node and all four safety invariants HOLD: the formal proof the node-local lock is mandatory for multi-writer-per-node cold writes. |
-| `Bakery_wedge.cfg` | **The orphan-claim wedge, reaper OFF** (`Reaper=FALSE`, `NodeParts={{a1,a2},{b1}}`, 1 crash). A same-node writer crashes holding its claim; its row stays in `coldfront.claims` with no owner. **`SurvivorProgress` is EXPECTED to be violated**: the surviving writer never decides. Safety still holds. The first config to check liveness under crash at all; `Bakery_crash.cfg` checks only safety. |
-| `Bakery_reaper.cfg` | **The reaper ON** (`Reaper=TRUE`, `NodeRetries=TRUE`), same topology. Three paths reap ownerless same-node claims: the claim path under the table lock, the apply path on its defer branch when the lock is free, and the waiter's poke. `SurvivorProgress` HOLDS *and* all four safety invariants hold: the reap never breaks mutual exclusion. |
-| `Bakery_reaper_quiet.cfg` | **The poke's case** (`Reaper=TRUE`, `NodeRetries=FALSE`): the crash strands a claim on a node no local writer or new peer claim ever reaches again, while a peer that already deferred behind it waits. Only the waiter's poke reaches that node. `SurvivorProgress` HOLDS and safety holds. |
-| `Bakery_adopt_race.cfg` | **Table registration OUTSIDE the bakery** (`AdoptClaims=FALSE`, one writer per node on two nodes). `_adopt_preflight` reads only the calling node's `coldfront.tiered_views`, so while the peer's row is in flight both preflights pass and both nodes INSERT. **`NoDoubleRegistration` is EXPECTED to be violated.** On a mesh the rows then replicate into each other and the second violates `UNIQUE (iceberg_table)` inside the apply worker, where no status field reports it. |
-| `Bakery_adopt.cfg` | **Registration UNDER the claim** (`AdoptClaims=TRUE`), same topology. The second node cannot reach its preflight until the first releases, and the release runs in the COMMIT callback, after the registry row is committed and ahead of the drained ack that frees the waiter. `NoDoubleRegistration` HOLDS *and* the four safety invariants hold: adding a claimant costs nothing the bakery already guarantees. |
+| `Bakery.tla` | This file is the PlusCal source. It models the real Spock world: each node has its OWN local `claims[nd]` view, and INSERTs propagate via an explicit `Applier`. The model does not assume `synchronous_commit = remote_apply`. Coordination is Lamport's 1978 distributed mutual exclusion algorithm with Ricart-Agrawala's (1981; henceforth abbreviated R-A) deferred-reply optimization: peers ack each claim immediately unless they have a pending claim with smaller ticket, in which case they defer the ack until they release their own claim. The file also models the `coldfront.iceberg_async_parquet` flag (constants `AsyncParquet`/`RestampPatch`): the `Stage` label stages parquet OUTSIDE the claim (async ordering); `Prepare` captures the `parent_snapshot_id` UNDER the claim (stock at stage time, patched async re-stamped at the commit POST); the conditional commit at `Decide` asserts against it. Defer/drain atomicity is modeled too (constant `SafeAcks`): the apply-time defer DECISION and its WRITE (`ApplyDecide`/`ApplyEmit`), and the release drain's FORWARD and DELETE (`DrainForward`/`DrainDelete`), are SEPARATE steps, faithful to the non-atomic SQL. `SafeAcks=FALSE` lets them race (a deferral written behind a just-released claim is deleted unforwarded / orphaned - a dropped ack); `SafeAcks=TRUE` is the safe implementation: an atomic re-check of R-A's own defer rule against the claim, i.e. `SELECT … FOR UPDATE` on the claim row in `coldfront._on_claim_apply`. The orphan reaper is modeled as well (constant `Reaper`): a same-node claim whose writer has crashed holds no advisory lock, so `BeginClaim` deletes it in the step that inserts its own claim; the `Applier` does the same on its defer branch under `HoldsTableLock(nd)` (a live writer holds `coldfront_iceberg:<table>` from `WaitAcks` through `DrainDelete`, because the release runs in the COMMIT callback before PostgreSQL drops the xact lock); and a `Poker` process models the waiter's periodic no-op UPDATE of its own claim row, which re-runs the peer's defer branch and is what unwedges a waiter whose peer's holder died after deferring to it. Constant `NodeRetries` restricts the `Crasher` to writers whose node still has an unstarted writer (the node is touched again); FALSE allows the crash after which only the poke reaches the node. The `Crasher` cannot split `Release`/`DrainForward`/`DrainDelete`, which are one loopback transaction in the real code. |
+| `Bakery.cfg` | This TLC config checks 3 writers with no crashes against all four safety invariants, in stock ordering (`AsyncParquet=FALSE`, the default, with parquet staged inside the claim). The config passes: the bakery makes `NoLakekeeperConflict` and `TicketOrderPreserved` hold even with realistic asymmetric apply. |
+| `Bakery_async.cfg` | This config checks the patched async ordering (`AsyncParquet=TRUE, RestampPatch=TRUE`) that the DuckDB 1.5.x (duckdb15) image runs: parquet is staged outside the claim, and the bakery-aware patch re-stamps `parent_snapshot_id` at the commit POST under the claim. All four safety invariants HOLD; the test is non-vacuous, because it shares the stock config's under-claim window from `Prepare` to `Decide`, which R-A keeps empty. |
+| `Bakery_race.cfg` | This config checks the pre-patch async race (`AsyncParquet=TRUE, RestampPatch=FALSE`): async ordering WITHOUT the bakery-aware patch, where the stale tentative parent from the pre-claim stage is used at the POST. `NoLakekeeperConflict` is EXPECTED to be violated, which is the formal proof that the patch is mandatory for the async ordering. |
+| `Bakery_crash.cfg` | This config checks 3 writers with a budget of 1 crash, in stock ordering (crash safety is ordering-independent). The safety invariants still hold, and survivors proceed, because the dead-peer escape treats a crashed node as already acked. This config checks safety only; stranding under a crash appears only with same-node writers (`Bakery_wedge.cfg`). |
+| `Bakery_live.cfg` | This config checks the defer/drain race (`SafeAcks=FALSE`), the non-atomic implementation. `EventualProgress` is EXPECTED to be VIOLATED: a deferred ack written behind a just-released claim is dropped, stranding the min-ticket holder at `WaitAcks` forever, which is the N-writer wedge this race produces. The four safety invariants still HOLD (a dropped ack is a liveness failure, not a wrong commit). The config declares no `SYMMETRY`, because symmetry reduction is unsound with liveness checking. |
+| `Bakery_fixed.cfg` | This config checks the fix (`SafeAcks=TRUE`), the atomic defer/drain (`FOR UPDATE` on the claim row). `EventualProgress` HOLDS *and* all four safety invariants hold, which is the formal proof that the fix restores liveness without weakening safety. |
+| `Bakery_samenode_race.cfg` | This config checks multiple cold writers per node with no same-node lock (`NodeParts={{a1,a2},{b1}}`, `SameNodeLock=FALSE`). Two same-node claims `a1<a2` below a peer's `b1`: the node defers `b1` behind its smallest same-node claim `a1` and, on `a1`'s release, forwards the ack for `b1` without re-deferring behind `a2` (still held, still `< b1`), so `a2` and `b1` both clear the bakery. `NoLakekeeperConflict` is EXPECTED to be violated, which reproduces the multi-writer-per-node race in the model. |
+| `Bakery_samenode.cfg` | This config checks the fix (`SameNodeLock=TRUE`): `coldfront._claim_iceberg_lock`'s node-local advisory xact lock, so at most one same-node writer is in the bakery at a time. `a1` and `a2` never coexist; the topology collapses to one active claim per node and all four safety invariants HOLD, which is the formal proof that the node-local lock is mandatory for multi-writer-per-node cold writes. |
+| `Bakery_wedge.cfg` | This config checks the orphan-claim wedge with the reaper OFF (`Reaper=FALSE`, `NodeParts={{a1,a2},{b1}}`, 1 crash). A same-node writer crashes holding its claim; its row stays in `coldfront.claims` with no owner. `SurvivorProgress` is EXPECTED to be violated: the surviving writer never decides. Safety still holds. This is the first config to check liveness under crash at all; `Bakery_crash.cfg` checks only safety. |
+| `Bakery_reaper.cfg` | This config checks the reaper ON (`Reaper=TRUE`, `NodeRetries=TRUE`) in the same topology. Three paths reap ownerless same-node claims: the claim path under the table lock, the apply path on its defer branch when the lock is free, and the waiter's poke. `SurvivorProgress` HOLDS *and* all four safety invariants hold: the reap never breaks mutual exclusion. |
+| `Bakery_reaper_quiet.cfg` | This config checks the poke's case (`Reaper=TRUE`, `NodeRetries=FALSE`): the crash strands a claim on a node no local writer or new peer claim ever reaches again, while a peer that already deferred behind it waits. Only the waiter's poke reaches that node. `SurvivorProgress` HOLDS and safety holds. |
+| `Bakery_adopt_race.cfg` | This config checks table registration OUTSIDE the bakery (`AdoptClaims=FALSE`, one writer per node on two nodes). `_adopt_preflight` reads only the calling node's `coldfront.tiered_views`, so while the peer's row is in flight both preflights pass and both nodes INSERT. `NoDoubleRegistration` is EXPECTED to be violated. On a mesh the rows then replicate into each other and the second violates `UNIQUE (iceberg_table)` inside the apply worker, where no status field reports it. |
+| `Bakery_adopt.cfg` | This config checks registration UNDER the claim (`AdoptClaims=TRUE`) in the same topology. The second node cannot reach its preflight until the first releases, and the release runs in the COMMIT callback, after the registry row is committed and ahead of the drained ack that frees the waiter. `NoDoubleRegistration` HOLDS *and* the four safety invariants hold: adding a claimant costs nothing the bakery already guarantees. |
 
 ## Properties
 
@@ -44,44 +44,48 @@ by category.
 
 These properties must hold; TLC checks them as `INVARIANTS`:
 
-- `NoLakekeeperConflict` - no writer's `decision` ends in `lk_409`.
-  Equivalently: while a writer holds the bakery's minimum ticket, no other
-  writer can issue a Lakekeeper CAS POST against the same iceberg table. This
-  is the headline correctness claim - pre-bakery this could fail and produce
-  silent commit loss.
-- `RollbackNoIceberg` - if a writer's `decision = "rolled_back"`, there is no
-  iceberg snapshot owned by that writer in the committed history. Models PG
-  ROLLBACK undoing pg_duckdb's pending iceberg MetaTransaction.
-- `UniqueTickets` - snowflake.nextval() doesn't return duplicates. Sanity check
-  on the model abstraction.
-- `TicketOrderPreserved` - committed snapshots are appended in the order their
-  owners' tickets were granted. Ensured structurally by the bakery's min-ticket
-  gate; encoded as an invariant for documentation.
+- `NoLakekeeperConflict` states that no writer's `decision` ends in `lk_409`.
+  Equivalently, while a writer holds the bakery's minimum ticket, no other
+  writer can issue a conditional commit POST to Lakekeeper against the same
+  iceberg table. This is the headline correctness claim - pre-bakery this could
+  fail and produce silent commit loss.
+- `RollbackNoIceberg` states that if a writer's `decision = "rolled_back"`,
+  there is no iceberg snapshot owned by that writer in the committed history.
+  The property models PG ROLLBACK undoing pg_duckdb's pending iceberg
+  MetaTransaction.
+- `UniqueTickets` states that snowflake.nextval() does not return duplicates.
+  The property is a sanity check on the model abstraction.
+- `TicketOrderPreserved` states that committed snapshots are appended in the
+  order their owners' tickets were granted. The bakery's min-ticket gate
+  ensures this structurally; the model encodes it as an invariant for
+  documentation.
+- `NoDoubleRegistration` states that at most one node registers a given Iceberg
+  table. `Bakery_adopt.cfg` and `Bakery_adopt_race.cfg` check it.
 
 ### Liveness
 
 TLC checks these properties as `PROPERTIES`:
 
-- `EventualProgress` - every writer that begins a claim eventually reaches a
-  terminal `decision` (`committed`, `rolled_back`, or `lk_409`). Holds when no
-  crashes; vacuously fails for writers that themselves crash mid-bakery (they
-  can never decide). It is also the defer/drain race check: `Bakery_fixed.cfg`
-  (`SafeAcks=TRUE`) HOLDS it; `Bakery_live.cfg` (`SafeAcks=FALSE`) VIOLATES
-  it - the dropped-ack wedge that strands the min-ticket holder at `WaitAcks`
-  forever.
-- `SurvivorProgress` - every writer eventually decides *or crashes*.
+- `EventualProgress` states that every writer that begins a claim eventually
+  reaches a terminal `decision` (`committed`, `rolled_back`, or `lk_409`). The
+  property holds when no crashes occur, and vacuously fails for writers that
+  themselves crash mid-bakery (they can never decide). `EventualProgress` is
+  also the defer/drain race check: `Bakery_fixed.cfg` (`SafeAcks=TRUE`) HOLDS
+  it; `Bakery_live.cfg` (`SafeAcks=FALSE`) VIOLATES it - the dropped-ack wedge
+  that strands the min-ticket holder at `WaitAcks` forever.
+- `SurvivorProgress` states that every writer eventually decides *or crashes*.
   `EventualProgress` is unusable with `MaxCrashes > 0`, since a crashed writer
   never decides; this is the form a crash config can check. `Bakery_wedge.cfg`
-  (`Reaper=FALSE`) VIOLATES it, the surviving same-node writer waiting forever
-  on a claim nobody owns; `Bakery_reaper.cfg` (`Reaper=TRUE`,
+  (`Reaper=FALSE`) VIOLATES `SurvivorProgress`, the surviving same-node writer
+  waiting forever on a claim nobody owns; `Bakery_reaper.cfg` (`Reaper=TRUE`,
   `NodeRetries=TRUE`) and `Bakery_reaper_quiet.cfg` (`NodeRetries=FALSE`, only
   the poke reaches the crashed node) both HOLD it.
 
 ## Running TLC
 
 The prerequisites are Java 11+ and the TLA+ tools 1.8.0 jar at
-`/tmp/tla2tools.jar` (download
-from <https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tla2tools.jar>).
+`/tmp/tla2tools.jar` (download from
+<https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tla2tools.jar>).
 Translate the PlusCal source and run each config as follows:
 
 ```sh
@@ -91,38 +95,45 @@ cd docs/formal
 # Translate the PlusCal source (idempotent).
 java -cp $TLA pcal.trans Bakery.tla
 
-# a. Stock ordering (AsyncParquet=FALSE): 3 writers, no crashes.  All hold.
+# a. This run checks stock ordering (AsyncParquet=FALSE) with 3 writers and no
+#       crashes.  All hold.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery.cfg Bakery.tla
 
-# b. Patched async ordering (the duckdb15 image's path).  All hold.
+# b. This run checks the patched async ordering (the duckdb15 image's path).
+#       All hold.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_async.cfg Bakery.tla
 
-# c. Pre-patch async race.  EXPECTED FAILURE: NoLakekeeperConflict violated -
-#       the formal proof the bakery-aware patch is mandatory for the async path.
+# c. This run checks the pre-patch async race.  EXPECTED FAILURE:
+#       NoLakekeeperConflict is violated, which is the formal proof that the
+#       bakery-aware patch is mandatory for the async path.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_race.cfg Bakery.tla
 
-# d. 1 crash budget.  Safety still holds (crashed peer's missing ack
-#       leaves survivors blocked at WaitAcks - no incorrect commits).
+# d. This run has a budget of 1 crash.  Safety still holds; survivors proceed,
+#       because a crashed node counts as already acked.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_crash.cfg Bakery.tla
 
-# e. Defer/drain race (SafeAcks=FALSE).  EXPECTED FAILURE: EventualProgress
-#       violated - the dropped-ack wedge reproduced in the model.
+# e. This run checks the defer/drain race (SafeAcks=FALSE).  EXPECTED FAILURE:
+#       EventualProgress is violated, which reproduces the dropped-ack wedge in
+#       the model.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_live.cfg Bakery.tla
 
-# f. The fix (SafeAcks=TRUE - FOR UPDATE on the claim row).  All hold:
-#       EventualProgress AND the four safety invariants.
+# f. This run checks the fix (SafeAcks=TRUE, FOR UPDATE on the claim row).
+#       All hold: EventualProgress AND the four safety invariants.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_fixed.cfg Bakery.tla
 
-# g. Multiple cold writers per node, NO same-node lock (SameNodeLock=FALSE).
-#      EXPECTED to violate NoLakekeeperConflict - the multi-writer-per-node race.
+# g. This run checks multiple cold writers per node with NO same-node lock
+#      (SameNodeLock=FALSE).  It is EXPECTED to violate NoLakekeeperConflict,
+#      which reproduces the multi-writer-per-node race.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_samenode_race.cfg Bakery.tla
 
-# h. Same topology WITH the node-local advisory lock (SameNodeLock=TRUE).
-#      All four safety invariants HOLD - the lock restores safety.
+# h. This run checks the same topology WITH the node-local advisory lock
+#      (SameNodeLock=TRUE).  All four safety invariants HOLD - the lock
+#      restores safety.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_samenode.cfg Bakery.tla
 
-# i. Orphan-claim wedge, reaper OFF (Reaper=FALSE, 1 crash).  EXPECTED FAILURE:
-#      SurvivorProgress violated: a crashed same-node claim holder strands the survivor.
+# i. This run checks the orphan-claim wedge with the reaper OFF (Reaper=FALSE,
+#      1 crash).  EXPECTED FAILURE: SurvivorProgress is violated, because a
+#      crashed same-node claim holder strands the survivor.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_wedge.cfg Bakery.tla
 
 # j. The reaper ON (Reaper=TRUE, NodeRetries=TRUE): the crashed node is touched
@@ -130,30 +141,36 @@ java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_wedge.cfg Bakery.t
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_reaper.cfg Bakery.tla
 
 # k. The poke's case (Reaper=TRUE, NodeRetries=FALSE): no local writer or new
-#      peer claim ever reaches the crashed node; only the waiter's poke does.  All
-#      hold: SurvivorProgress AND the four safety invariants.
+#      peer claim ever reaches the crashed node; only the waiter's poke does.
+#      All hold: SurvivorProgress AND the four safety invariants.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_reaper_quiet.cfg Bakery.tla
 
 # l. Table registration OUTSIDE the bakery (AdoptClaims=FALSE): two nodes adopt
-#      one Iceberg table and both preflights pass inside the replication window.
-#      EXPECTED: NoDoubleRegistration VIOLATED.
+#      one Iceberg table, and both preflights pass inside the replication
+#      window.
+#      EXPECTED: NoDoubleRegistration is VIOLATED.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_adopt_race.cfg Bakery.tla
 
-# m. Registration UNDER the claim (AdoptClaims=TRUE), same topology.  All hold:
-#      NoDoubleRegistration AND the four safety invariants.
+# m. This run checks registration UNDER the claim (AdoptClaims=TRUE) in the
+#      same topology.  All hold: NoDoubleRegistration AND the four safety
+#      invariants.
 java -cp $TLA tlc2.TLC -workers auto -deadlock -config Bakery_adopt.cfg Bakery.tla
 ```
 
 The `-deadlock` flag tells TLC not to flag final stuttering states as errors.
-Without crashes the model terminates cleanly when every writer reaches `Done`;
-with a crash a live writer can be stuck in `WaitAcks` forever waiting for the
-orphan ticket. We want TLC to report this as a `EventualProgress` violation,
-not as `Deadlock reached`.
+Without crashes the model terminates cleanly when every writer reaches `Done`.
+With a crash in a same-node config and the reaper off (`Bakery_wedge.cfg`), a
+surviving writer can wait forever on the orphan claim. TLC must report this as
+a `SurvivorProgress` violation, not as `Deadlock reached`.
 
 ## Expected Outputs
 
 This section records the expected TLC result for each config, so a reviewer can
-confirm a run matches the known-good output.
+confirm a run matches the known-good output. The counts come from TLC 1.8.0. A
+config that passes explores every state, so its counts are the same with any
+`-workers` value. A config that fails stops at the first violation, so its
+counts depend on worker scheduling; the counts shown for those were taken with
+`-workers 1`, which reproduces them exactly.
 
 ### `Bakery.cfg` (Stock Ordering)
 
@@ -161,12 +178,13 @@ The stock-ordering config reports a clean check with the following output:
 
 ```text
 Model checking completed. No error has been found.
-2442 states generated, 702 distinct states found, 0 states left on queue.
+116332 states generated, 38570 distinct states found, 0 states left on queue.
 ```
 
 All four safety invariants hold for the stock ordering (parquet staged inside
-the claim; parent stamped under the claim). R-A makes `NoLakekeeperConflict`
-and `TicketOrderPreserved` hold despite asymmetric Spock apply.
+the claim; parent stamped under the claim). The bakery makes
+`NoLakekeeperConflict` and `TicketOrderPreserved` hold despite asymmetric Spock
+apply.
 
 ### `Bakery_async.cfg` (Patched Async Ordering)
 
@@ -174,7 +192,7 @@ The patched-async config reports a clean check with the following output:
 
 ```text
 Model checking completed. No error has been found.
-3361 states generated, 1084 distinct states found, 0 states left on queue.
+339258 states generated, 113262 distinct states found, 0 states left on queue.
 ```
 
 The patched async ordering - parquet staged OUTSIDE the claim, parent
@@ -192,19 +210,19 @@ following output:
 ```text
 Error: Invariant NoLakekeeperConflict is violated.
 …
-2898 states generated, 891 distinct states found, 44 states left on queue.
+26659 states generated, 9430 distinct states found, 2073 states left on queue.
 ```
 
-Failure expected. With the async ordering but WITHOUT the bakery-aware patch
-(`RestampPatch=FALSE`), a writer asserts the CAS against the stale tentative
-parent it captured at the pre-claim stage; a peer that committed while it
-awaited/held the claim has advanced the iceberg head, so the CAS mismatches →
-Lakekeeper 409. This is the formal proof that the patch is mandatory for the
-async ordering - the stock ordering (`Bakery.cfg`) stamps the parent under the
-claim and needs no patch. (The asymmetric-apply race that motivates R-A
-itself - two writers passing a naive local min-check on stale views - is
-structurally prevented by the R-A ack barrier in this model, so it has no
-standalone config.)
+The failure is expected. With the async ordering but WITHOUT the bakery-aware
+patch (`RestampPatch=FALSE`), a writer asserts the conditional commit against
+the stale tentative parent it captured at the pre-claim stage; a peer that
+committed while it awaited/held the claim has advanced the iceberg head, so the
+conditional commit fails because its parent is stale → Lakekeeper 409. This is
+the formal proof that the patch is mandatory for the async ordering - the stock
+ordering (`Bakery.cfg`) stamps the parent under the claim and needs no patch.
+(The asymmetric-apply race that motivates R-A itself - two writers passing a
+naive local min-check on stale views - is structurally prevented by the R-A ack
+barrier in this model, so it has no standalone config.)
 
 ### `Bakery_samenode_race.cfg` (Multi-Writer-Per-Node - EXPECTED FAILURE)
 
@@ -214,17 +232,17 @@ following output:
 ```text
 Error: Invariant NoLakekeeperConflict is violated.
 …
-62256 states generated, 20448 distinct states found, 2595 states left on queue.
+134609 states generated, 43418 distinct states found, 4695 states left on queue.
 ```
 
-Failure expected. With two cold writers `a1 < a2` on one node and `b1` on a
-peer (`NodeParts={{a1,a2},{b1}}`, `SameNodeLock=FALSE`), the node defers `b1`
-behind its smallest same-node claim `a1`; when `a1` releases, it forwards the
-ack for `b1` without re-deferring behind `a2` (still held, still `< b1`). So
-`a2` (already acked by the peer, since `a2 < b1`) and `b1` (now acked) both
-clear the bakery and race the CAS → Lakekeeper 409. This reproduces the
-multi-writer-per-node race in the model, isolated from the async race
-(`AsyncParquet=FALSE`) and the ack-atomicity race (`SafeAcks=TRUE`).
+The failure is expected. With two cold writers `a1 < a2` on one node and `b1`
+on a peer (`NodeParts={{a1,a2},{b1}}`, `SameNodeLock=FALSE`), the node defers
+`b1` behind its smallest same-node claim `a1`; when `a1` releases, it forwards
+the ack for `b1` without re-deferring behind `a2` (still held, still `< b1`).
+So `a2` (already acked by the peer, since `a2 < b1`) and `b1` (now acked) both
+clear the bakery and race their conditional commits → Lakekeeper 409. This
+reproduces the multi-writer-per-node race in the model, isolated from the async
+race (`AsyncParquet=FALSE`) and the ack-atomicity race (`SafeAcks=TRUE`).
 
 ### `Bakery_samenode.cfg` (Node-Local Lock)
 
@@ -232,7 +250,7 @@ The same-node-lock config reports a clean check with the following output:
 
 ```text
 Model checking completed. No error has been found.
-71617 states generated, 24076 distinct states found, 0 states left on queue.
+174206 states generated, 59106 distinct states found, 0 states left on queue.
 ```
 
 `SameNodeLock=TRUE` models `coldfront._claim_iceberg_lock`'s node-local
@@ -251,49 +269,56 @@ faithfully because they affect protocol correctness:
   [_exec_iceberg_with_claim](https://github.com/pgEdge/ColdFront/blob/main/extension/coldfront/coldfront--1.0.sql):
   stock (claim → stage+commit under the claim) and patched async (stage parquet
   outside the claim → claim → re-stamp `parent_snapshot_id` at the commit POST
-  under the claim). The safety-critical invariant - the CAS parent is taken
-  UNDER the held claim - is captured at `Prepare` for both; the
-  `AsyncParquet`/`RestampPatch` constants select the ordering and whether the
-  bakery-aware patch is present.
+  under the claim). The safety-critical invariant - the parent snapshot the
+  conditional commit checks is taken UNDER the held claim - is captured at
+  `Prepare` for both; the `AsyncParquet`/`RestampPatch` constants select the
+  ordering and whether the bakery-aware patch is present. In the code,
+  `coldfront._iceberg_async_active()` selects the async ordering only when the
+  build marker `coldfront.iceberg_bakery_patch` is also on. With the flag
+  alone, the writer keeps the stock ordering and logs the downgrade once per
+  session, so the `Bakery_race.cfg` combination runs only where the marker is
+  set on a stock binary.
 - The bakery's min-ticket spin in
   [_claim_iceberg_lock](https://github.com/pgEdge/ColdFront/blob/main/extension/coldfront/coldfront--1.0.sql).
-- The deferred release: pg_duckdb's XactCallback commits iceberg first, then
-  coldfront's XactCallback (registered after, runs after per PG's documented
-  registration-order chain) DELETEs the claim. Modeled as the iceberg append at
-  `Decide` followed by the claim DELETE at `Release`.
-- pg_duckdb's iceberg ROLLBACK on PG ABORT (no append on the rollback branch) -
-  required for the `RollbackNoIceberg` property to hold.
+- The deferred release, in which pg_duckdb commits the Iceberg transaction at
+  `XACT_EVENT_PRE_COMMIT` and coldfront's XactCallback DELETEs the claim at
+  `XACT_EVENT_COMMIT`, so the commit always precedes the release whatever order
+  the two callbacks were registered in. The model represents this as the
+  iceberg append at `Decide` followed by the claim DELETE at `Release`.
+- pg_duckdb's iceberg ROLLBACK on PG ABORT (no append on the rollback branch),
+  which the `RollbackNoIceberg` property requires.
 
 ### Compactor Commits (`cmd/compactor`)
 
 The Go compactor (`cmd/compactor`, apache/iceberg-go) is a bakery claimant
 **indistinguishable from a cold writer at the protocol level**: it acquires a
 claim via `_claim_iceberg_lock` on the node it connects to, captures the parent
-snapshot under the held claim, issues one Lakekeeper CAS POST - a *replace*
-(`RewriteDataFiles`: drop small data files, add the rewritten one), which has
-the same parent-CAS conflict shape as the append modeled at `Decide` - then
-releases. The compactor adds no new protocol primitive, so it is covered by the
-existing proof as the **stock-ordering writer** (`AsyncParquet = FALSE`,
-`Bakery.cfg`). The compactor's two maintenance operations are the **same
-claimant**, so they need no new model: **`ExpireSnapshots`** issues another CAS
-commit (drop old snapshots - identical conflict shape) under the held claim,
-covered exactly like `RewriteDataFiles`; **`DeleteOrphanFiles`** holds the
-claim but makes **no Lakekeeper commit** (it only deletes unreferenced files),
-so it cannot cause a catalog conflict at all - strictly weaker than a
-committing claimant, hence trivially within `NoLakekeeperConflict`. All three
-reuse the existing `coldfront._claim_iceberg_external` and are covered by the
-existing model and configs; no dedicated config is needed. (Lakekeeper itself
-does no Iceberg snapshot/orphan maintenance - it is a catalog - so this is the
-go-native path.)
-
-Binding constraint: iceberg-go carries **no bakery-aware re-stamp patch** (that
+snapshot under the held claim, issues one conditional commit POST to
+Lakekeeper - a *replace* (`RewriteDataFiles`: drop small data files, add the
+rewritten one), which has the same parent-snapshot conflict shape as the append
+modeled at `Decide` - then releases. The compactor adds no new protocol
+primitive, so it is covered by the existing proof as the **stock-ordering
+writer** (`AsyncParquet = FALSE`, `Bakery.cfg`). The compactor's two
+maintenance operations are the **same claimant**, so they need no new model:
+**`ExpireSnapshots`** issues another conditional commit (drop old snapshots -
+identical conflict shape) under the held claim, covered exactly like
+`RewriteDataFiles`; **`DeleteOrphanFiles`** holds the claim but makes **no
+Lakekeeper commit** (it only deletes unreferenced files), so it cannot cause a
+catalog conflict at all - strictly weaker than a committing claimant, hence
+trivially within `NoLakekeeperConflict`. All three reuse the existing
+`coldfront._claim_iceberg_external` and are covered by the existing model and
+configs; no dedicated config is needed. (Lakekeeper itself does no Iceberg
+snapshot/orphan maintenance - it is a catalog - so this is the go-native path.)
+
+Binding constraint: iceberg-go has **no bakery-aware re-stamp patch** (that
 patch lives only in the duckdb-iceberg commit path), so the compactor MUST hold
-the claim across the whole read → rewrite → commit and stamp the CAS parent
-under the claim. `Bakery_race.cfg` is the proof that the patchless-async
-shortcut 409s - the compactor is therefore forbidden the async-parquet path.
-Commit-then-release matches the cold-write shape the model already abstracts as
-the atomic `Decide` step (commit iceberg, then DELETE the claim), so the
-existing configs cover it; no dedicated config is needed.
+the claim across the whole read → rewrite → commit and stamp, under the claim,
+the parent snapshot that the conditional commit checks. `Bakery_race.cfg` is
+the proof that the patchless-async shortcut fails with HTTP 409 - the compactor
+is therefore forbidden the async-parquet path. Commit-then-release matches the
+cold-write shape the model already abstracts as the atomic `Decide` step
+(commit iceberg, then DELETE the claim), so the existing configs cover it; no
+dedicated config is needed.
 
 ### DDL Mirroring (`ALTER TABLE`)
 
@@ -301,13 +326,13 @@ Tiered-table column DDL (ADD/DROP/ALTER-TYPE/RENAME COLUMN) is mirrored onto
 the shared Iceberg tier by `coldfront._mirror_iceberg_alter`, which routes the
 Iceberg ALTER through the **unchanged** `_exec_iceberg_with_claim`. The mirror
 function is therefore the **same stock-ordering claimant** the cold writer is:
-one metadata-only CAS commit (the schema change - identical parent-CAS conflict
-shape to the append modeled at `Decide`) under the held claim, then release. It
-forces the claim-first ordering
+one metadata-only conditional commit (the schema change - identical
+parent-snapshot conflict shape to the append modeled at `Decide`) under the
+held claim, then release. The mirror function forces the claim-first ordering
 (`SET LOCAL coldfront.iceberg_async_parquet = off`): an ALTER stages no
 parquet, so there is nothing to overlap, and `AsyncParquet = FALSE`
-(`Bakery.cfg`) is the config the model already proves safe. It adds no new
-protocol primitive, so it is covered by the existing model and configs; no
+(`Bakery.cfg`) is the config the model already proves safe. The mirror adds no
+new protocol primitive, so it is covered by the existing model and configs; no
 dedicated config is needed.
 
 In a mesh the user's ALTER replicates as a top-level statement and re-runs in
@@ -324,16 +349,17 @@ A partition-column `UPDATE` that crosses the cutoff is rewritten to
 work is plain PostgreSQL (heap INSERT/UPDATE/DELETE - no Iceberg, no claim).
 Its cold-tier work is **one** `duckdb.raw_query` issued through the
 **unchanged** path: a single DELETE-set plus INSERT-set in one DuckDB
-MetaTransaction - one Iceberg snapshot, one Lakekeeper CAS POST - under **one**
-`_claim_iceberg_lock` held to transaction end (released by the C
-`XactCallback`). It is therefore the **same stock-ordering single claimant**
-the cold writer is: one CAS commit (identical parent-CAS conflict shape to the
-append modeled at `Decide`) under the held claim. It forces
-`iceberg_async_parquet = off` (`AsyncParquet = FALSE`, `Bakery.cfg`) - the
-DELETE+INSERT bundle is not pg_duckdb's single deferred POST that the async
-re-stamp patch wraps. Exactly **one** claim per move (a second
-`_claim_iceberg_lock` on the same table in one txn would self-deadlock at the
-min-ticket gate), so the move never holds two tickets. It adds no new protocol
+MetaTransaction - one Iceberg snapshot, one conditional commit POST to
+Lakekeeper - under **one** `_claim_iceberg_lock` held to transaction end
+(released by the C `XactCallback`). The move is therefore the **same
+stock-ordering single claimant** the cold writer is: one conditional commit
+(identical parent-snapshot conflict shape to the append modeled at `Decide`)
+under the held claim. The move forces `iceberg_async_parquet = off`
+(`AsyncParquet = FALSE`, `Bakery.cfg`) - the DELETE+INSERT bundle is not
+pg_duckdb's single deferred POST that the async re-stamp patch wraps. Each move
+takes exactly **one** claim (a second claim on the same table would reap the
+first, which `_take_iceberg_claim` prevents by reusing the transaction's
+claim), so the move never holds two tickets. The move adds no new protocol
 primitive, so it is covered by the existing model and configs; no dedicated
 config is needed.
 
@@ -346,10 +372,10 @@ on each peer itself, over its own connection to each Spock node (gated on Spock
 being present; a no-op on a vanilla single node). This is **outside the modeled
 protocol entirely**: it touches no Iceberg catalog, takes no claim, and POSTs
 nothing to Lakekeeper - it is pure PostgreSQL partition maintenance on the hot
-tier. It adds no claimant, no CAS commit, and no new ordering, so it falls
-outside `Bakery`'s scope; no dedicated config is needed. (The archiver's cold
-cutover *does* commit to Iceberg under a claim, but its detach is a plain
-transactional `DETACH` that Spock replicates on its own - it is the
+tier. The fan-out adds no claimant, no conditional commit, and no new ordering,
+so it falls outside `Bakery`'s scope; no dedicated config is needed. (The
+archiver's cold cutover *does* commit to Iceberg under a claim, but its detach
+is a plain transactional `DETACH` that Spock replicates on its own - it is the
 already-modeled stock-ordering writer, not a new primitive.)
 
 ### Known Abstractions (Model Deviates from Reality)
@@ -357,26 +383,28 @@ already-modeled stock-ordering writer, not a new primitive.)
 These are the points where the model deliberately deviates from runtime
 reality:
 
-- **No `lk_409` residual.** `NoLakekeeperConflict` holds because the R-A ack
-  barrier keeps the under-claim window empty. No application-level 409-retry
-  exists or is needed: concurrent cold writers never receive a Lakekeeper 409.
+- The model has no `lk_409` residual: `NoLakekeeperConflict` holds because the
+  R-A ack barrier keeps the under-claim window empty. No application-level
+  409-retry exists or is needed: concurrent cold writers never receive a
+  Lakekeeper 409.
 
-The following are *abstracted away* because they don't affect protocol
+The following are *abstracted away* because they do not affect protocol
 correctness:
 
-- Lakekeeper REST API and Iceberg snapshot serialization. Modeled as an atomic
-  CAS on a sequence head.
-- pg_duckdb internals (its XactCallback registration ordering is a *premise* -
-  coldfront loads after pg_duckdb in `shared_preload_libraries`).
+- The Lakekeeper REST API and Iceberg snapshot serialization, which the model
+  represents as an atomic conditional update of a sequence head.
+- pg_duckdb internals (the transaction-event order is a *premise*: pg_duckdb
+  commits at PRE_COMMIT, before coldfront's release at COMMIT).
 - Spock walsender / heartbeat cadence (wal_sender_timeout/2 ≈ 30 s default
-  keepalive cadence; reply_time freshness in the reap uses a 5 s threshold
-  which works in active clusters but degrades to the keepalive cadence floor
-  for idle-then-crashed peers).
+  keepalive cadence; reply_time freshness in the wait loop's dead-peer check
+  uses `coldfront.peer_alive_window_ms`, default 5 s, a threshold which works
+  in active clusters but degrades to the keepalive cadence floor for
+  idle-then-crashed peers).
 - DuckDB's pglocal connection-keepalive behavior. The bakery does not use
   pglocal; the archiver's Phase 3 does, but Phase 3 is a separate code path
   with its own CI test (the race-window regression in `ci/journey.sh` story 9).
-- Async-replicated user-data tables (Spock's data path for non-bakery commits).
-  Doesn't interact with the bakery state.
+- Async-replicated user-data tables (Spock's data path for non-bakery commits),
+  which do not interact with the bakery state.
 
 If any of these abstractions is questioned in code review, the model must be
 re-examined to ensure it still represents the runtime faithfully - formal
@@ -386,12 +414,14 @@ models are only as useful as their fidelity.
 
 `MaxTickets = 6, MaxIcebergLen = 5, |Writers| = 3` is the default bound
 (`MaxCrashes` is 1 in the crash configs and 0 elsewhere; the same-node configs
-use `MaxTickets = 3` with writers `{a1, a2, b1}`). Every config checks in
-seconds on a modern laptop. `SYMMETRY` on `Writers` (up to a ~6× reduction at 3
-writers) is per-config: the liveness configs (`Bakery_live.cfg`,
+use `MaxTickets = 3` with writers `{a1, a2, b1}`, and the adopt configs use
+`MaxTickets = 2` and `MaxIcebergLen = 4` with writers `{a1, b1}`). Every config
+checks in seconds on a modern laptop. `SYMMETRY` on `Writers` (up to a ~6×
+reduction at 3 writers) is per-config: the liveness configs (`Bakery_live.cfg`,
 `Bakery_fixed.cfg`) run without it (symmetry reduction is unsound with liveness
 checking), and the same-node configs run without it (`a1`/`a2`/`b1` are not
-interchangeable under `NodeParts`); the other configs declare it.
+interchangeable under `NodeParts`), and so do the two adopt configs; the other
+configs declare it.
 
 The model is small enough that larger bounds are interesting only if a
 regression is suspected.
@@ -406,13 +436,14 @@ Re-run the model after any change to the following:
   `_on_claim_release`, `_ensure_claims_replicated`).
 - The `_exec_iceberg_with_claim` ordering or the
   `coldfront.iceberg_async_parquet` flag's meaning (which parquet-stage point /
-  where `parent_snapshot_id` is stamped relative to the claim) - re-check
-  `Bakery.cfg` (stock) AND `Bakery_async.cfg` (patched).
+  where `parent_snapshot_id` is stamped relative to the claim), which means
+  re-checking `Bakery.cfg` (stock) AND `Bakery_async.cfg` (patched).
 - The C-level XactCallback in `extension/coldfront/src/coldfront.c`
   (`coldfront_xact_callback`, `RegisterXactCallback` ordering).
-- The `cmd/compactor` bakery wrapper - the claim/release that brackets its
-  iceberg-go `RewriteDataFiles` commit (it must stay stock-ordering: claim held
-  across read → rewrite → commit; no async-parquet shortcut).
+- The `cmd/compactor` bakery wrapper, meaning the claim/release that brackets
+  its iceberg-go `RewriteDataFiles` commit (the wrapper must stay
+  stock-ordering: claim held across read → rewrite → commit; no async-parquet
+  shortcut).
 
 If the protocol-level shape changes (e.g. swapping the bakery for a different
 coordination primitive), update the PlusCal source first, re-translate,
diff --git a/docs/index.md b/docs/index.md
index c7a2254..819019b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,17 +1,17 @@
 # pgEdge ColdFront
 
-!!! warning "Pre-release beta software"
-
-    ColdFront is pre-release beta software under active development. Do not use
-    it in production. Interfaces, on-disk formats, and behavior may change
-    without notice, and data loss is possible.
-
 ColdFront keeps tables in PostgreSQL and cold data in Apache Iceberg (Parquet
 on S3-compatible, Azure, or GCS storage), and the cold tier is both readable
 and writable through the same SQL with no application changes. The application
 queries every table as an ordinary PostgreSQL relation, and both operating
 modes present the same standard SQL surface.
 
+!!! warning "Beta software"
+
+    ColdFront is beta software under active development. Do not use it in
+    production. Interfaces, on-disk formats, and behavior may change without
+    notice, and data loss is possible.
+
 ColdFront provides two operating modes:
 
 - Tiered mode keeps recent data in native PostgreSQL partitions and archives
@@ -68,7 +68,7 @@ Build the image (see the [Installation](installation.md) guide) and bring up
 the stack:
 
 ```bash
-docker compose up -d --build
+docker compose --profile local-store up -d --build
 ```
 
 Bootstrap Lakekeeper and create a warehouse (see the one-time setup in the
@@ -114,8 +114,10 @@ SELECT coldfront.grant_app_access('alice');
 ```
 
 grant_app_access grants only the minimum the cold path needs: membership in
-duckdb.postgres_role, schema USAGE, SELECT on the registry, and DML on every
-registered view and the hot table and sequences behind it. Those objects are
+duckdb.postgres_role, SET on the duckdb.unsafe_allow_execution_inside_functions
+parameter, schema USAGE, SELECT on the registry and the watermark table, DML on
+the dual-write anchor table, DML on every registered view and the hot table
+behind it, and USAGE and SELECT on the hot table's sequences. Those objects are
 derived from the registry, not hardcoded, and the call also grants EXECUTE on a
 fixed allow-list of runtime cold-path functions. The call is idempotent and is
 not executable by PUBLIC, so an application role can never self-grant. The role
@@ -123,10 +125,16 @@ is never granted pg_read_server_files or pg_write_server_files, so it has no
 host-file access. CREATE ROLE and GRANT both replicate over Spock, so you
 onboard a role once on any node and it propagates across the mesh.
 
-For how the non-superuser path works under the hood - the `SECURITY DEFINER`
-attach helpers, the `PGC_SUSET` / `GUC_SUPERUSER_ONLY` config hardening, the
-turnkey `duckdb.postgres_role` default, and how least privilege holds across a
-Spock mesh - see
+The Docker image sets `duckdb.postgres_role` to `coldfront_duckdb` and creates
+that role when it initializes a new data directory. To name a different role,
+set the container's `COLDFRONT_DUCKDB_ROLE` environment variable before that
+first start. An empty value keeps pg_duckdb's default, under which only
+superusers run DuckDB, so grant_app_access then fails with an error.
+
+For how the non-superuser path works - the `SECURITY DEFINER` attach helpers,
+the `PGC_SUSET` / `GUC_SUPERUSER_ONLY` config hardening, the
+`duckdb.postgres_role` default that the image sets up, and how least privilege
+holds across a Spock mesh - see
 [Architecture: non-superuser app roles](architecture.md#non-superuser-app-roles-least-privilege).
 
 ## Caveats
@@ -139,8 +147,8 @@ storage account before using it as a cold tier.
 
 ## Next Steps
 
-New here? Run the [guided walkthrough](walkthrough.md) to see all three modes
-in action with copy-pasteable commands.
+If you are new to ColdFront, run the [guided walkthrough](walkthrough.md) to
+see all three modes in action with copy-pasteable commands.
 
 To go further with ColdFront, consult the following guides:
 
diff --git a/docs/installation.md b/docs/installation.md
index ba9b78c..6828435 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,45 +1,53 @@
 # Building ColdFront from Source
 
+This guide builds ColdFront from source, either in Docker on top of the
+published base image or on bare metal.
+
 > **Most users should install from packages** - see
 > [Installation](https://github.com/pgEdge/ColdFront/blob/main/README.md#installation)
 > in the README. This document is the **build-from-source** workflow: build the
 > patched DuckDB-1.5.x stack yourself, in Docker or bare-metal.
 
 ColdFront runs on a **DuckDB 1.5.x** stack: PostgreSQL + pg_duckdb (DuckDB
-1.5.4) and a **patched** duckdb-iceberg that carries ColdFront's four patches -
-the bakery-aware commit-refresh patch (the no-409 guarantee for concurrent
-cold-tier writers), two strict-reader interop patches (so apache/iceberg-go,
-the cold-tier compactor, can read the manifests duckdb-iceberg writes) and a
-port of an upstream fix that computes the time partitions of a `timestamptz`
-column in UTC. No released pg_duckdb tag carries DuckDB 1.5.x yet, so the stack
-is built from a pinned upstream PR plus our patches - all from sources you can
-fetch.
+1.5.4) and a **patched** duckdb-iceberg that includes ColdFront's four
+patches - the bakery-aware commit-refresh patch (the no-409 guarantee for
+concurrent cold-tier writers), two strict-reader interop patches (so
+apache/iceberg-go, the cold-tier compactor, can read the manifests
+duckdb-iceberg writes) and a port of an upstream fix that computes the time
+partitions of a `timestamptz` column in UTC. No released pg_duckdb tag includes
+DuckDB 1.5.x yet, so the stack is built from a pinned upstream PR plus
+ColdFront's patches - all from sources you can fetch.
 
 ## What Gets Built
 
 `docker/Dockerfile.duckdb15-base` is the recipe; it fetches the requirements,
-applies our patches, and compiles the following components:
+applies ColdFront's patches, and compiles a set of components. The following
+table shows each component and its source:
 
 | Component | Source |
 |---|---|
-| libcurl 8.12.0 | `curl.se`, built from source (compile-time dep of DuckDB 1.5.4 httpfs; needs curl >= 7.77, the pgEdge base ships 7.76.1) |
+| libcurl 8.12.0 | The recipe builds libcurl from source from `curl.se`, because DuckDB 1.5.4 httpfs needs curl 7.77 or later at compile time and the pgEdge base ships 7.76.1. |
 | pg_duckdb (DuckDB 1.5.4) | `github.com/duckdb/pg_duckdb`, PR #1025 |
 | duckdb-iceberg | `github.com/duckdb/duckdb-iceberg`, `v1.5-variegata` @ `5edc45f0` |
+| DuckDB 1.5.4 | `github.com/duckdb/duckdb`, tag `v1.5.4`, which replaces duckdb-iceberg's own DuckDB submodule |
+| duckdb-avro, duckdb-azure, duckdb-postgres | `github.com/duckdb/duckdb-avro` @ `7f423d69`, `github.com/duckdb/duckdb-azure` @ `563589b2`, and `github.com/duckdb/duckdb-postgres` @ `6b2b12ca`, pinned in `docker/iceberg-azure-extension-config-v15.cmake` |
 | vcpkg | `github.com/microsoft/vcpkg` |
+| Base images | `ghcr.io/pgedge/pgedge-postgres:<pg>-spock5-minimal` and `quay.io/pypa/manylinux_2_28_<arch>` |
 
 The base build runs as three Docker stages: the first builds libcurl and
 pg_duckdb; the second clones duckdb-iceberg at the pinned ref, applies
 ColdFront's four patches, and compiles the iceberg, avro, azure, and
 postgres_scanner extensions under vcpkg; the third assembles the runtime. The
 build `git apply --check`s each patch before applying it, so it fails loudly on
-patch rot rather than silently shipping stock iceberg (which 409s under
-concurrency and writes manifests strict Apache readers reject).
+patch rot rather than silently shipping stock iceberg (which fails with HTTP
+409 under concurrency and writes manifests strict Apache readers reject).
 
-ColdFront applies the following four patches to duckdb-iceberg:
+ColdFront applies four patches to duckdb-iceberg. The following table describes
+what each one does:
 
 | Patch | What it does |
 |---|---|
-| `iceberg-bakery-aware-commit-refresh-v15` | Refreshes the table head at the commit POST (and re-creates the table's storage secret in the commit context, needed under catalog credential vending) so concurrent cold writers never get a Lakekeeper 409 (the no-409 guarantee). |
+| `iceberg-bakery-aware-commit-refresh-v15` | Refreshes the table head at the commit POST (and re-creates the table's storage secret in the commit context, needed under catalog credential vending) so concurrent cold writers never get a Lakekeeper 409 (the no-409 guarantee). It also lets writers queued behind the first commit into a never-written table proceed instead of failing as "already outdated". |
 | `iceberg-manifest-list-format-version-v15` | Adds the spec-optional `format-version` key to the manifest-list metadata so strict Apache readers parse the entries as v2. |
 | `iceberg-data-file-format-v15` | Upper-cases the data-file format in the manifest to match the spec enum strict readers check case-sensitively. |
 | `iceberg-timestamptz-utc-transforms-v15` | Computes the year/month/day/hour partition of a `timestamptz` column on the UTC instant rather than in the session's time zone (a port of upstream duckdb-iceberg d3c3348271). |
@@ -61,7 +69,7 @@ Build the stack in two stages, the prebuilt base and the thin app layer:
 git clone <coldfront-repo> && cd coldfront
 
 # 1. Build the base (fetches the deps above, applies our patches, compiles
-#    pg_duckdb 1.5.4 + the patched duckdb-iceberg). ~30–60 min,
+#    pg_duckdb on DuckDB 1.5.4 + the patched duckdb-iceberg). ~30–60 min,
 #    needs network + a few GB of disk/RAM. Repeat with =16 / =17 for those majors.
 docker build -f docker/Dockerfile.duckdb15-base --build-arg PG_MAJOR=18 \
   -t ghcr.io/pgedge/coldfront-duckdb-base:pg18 .
@@ -73,8 +81,8 @@ docker compose up -d --build      # end-user single-node stack (ports published)
 ```
 
 The split keeps app builds fast and always testing current source: the
-expensive, stable compiles (pg_duckdb 1.5.4 + the patched duckdb-iceberg) live
-in the prebuilt **base**, published to
+expensive, stable compiles (pg_duckdb on DuckDB 1.5.4 + the patched
+duckdb-iceberg) live in the prebuilt **base**, published to
 `ghcr.io/pgedge/coldfront-duckdb-base:pg{16,17,18}`; the **app** build
 ([`docker/Dockerfile.duckdb15`](https://github.com/pgEdge/ColdFront/blob/main/docker/Dockerfile.duckdb15))
 `FROM`s it and compiles the coldfront extension in seconds. If you build the
@@ -82,11 +90,14 @@ base yourself (step 1) the app layer `FROM`s your local image; otherwise it
 `FROM`s the published `ghcr.io/pgedge/coldfront-duckdb-base:pg<major>`. Rebuild
 the published base via the
 [base-image workflow](https://github.com/pgEdge/ColdFront/blob/main/.github/workflows/base-image.yml)
-(`gh workflow run base-image.yml`) when its inputs change. CI builds the app on
-the tag `ci/base-ref.sh <major>` prints, `pg<major>-r<hash>`, where the hash
-covers the base Dockerfile and the files it copies in, and stops before the app
-build if that tag is not published, naming the command that publishes it. The
-floating `pg<major>` tag moves to the same image once the change is on `main`.
+(`gh workflow run base-image.yml --ref <branch> -f push=true`) when its inputs
+change; without `push=true` the workflow builds but publishes nothing. CI
+builds the app on the tag `ci/base-ref.sh <major>` prints, `pg<major>-r<hash>`,
+where the hash covers the base Dockerfile and the files it copies in, and stops
+before the app build if that tag is not published, naming the command that
+publishes it. The floating `pg<major>` tag moves to the same image only when
+the base-image workflow is dispatched from `main` with `push=true` and both
+architectures.
 
 Then follow [usage.md → One-Time Setup](usage.md#one-time-setup) (bootstrap
 Lakekeeper → create a table → tier → verify).
@@ -163,9 +174,10 @@ The following table lists the prerequisites for each build path:
 
 | For | You need |
 |---|---|
-| Docker build (above) | Docker; network access (GitHub / quay.io); ~a few GB disk + RAM and 30-60 min for the base compile |
-| The archiver (all paths) | Go 1.26.5+ (pinned in [go.mod](https://github.com/pgEdge/ColdFront/blob/main/go.mod)), `make` (`make build` → `./bin/archiver`) |
-| Bare metal (below) | `pg_config`, PostgreSQL server dev headers, libpq client headers/library (libpq-dev / libpq-devel), `make`, `gcc` |
+| Docker build (above) | Docker, network access (GitHub, ghcr.io, quay.io, curl.se, and the distribution's RPM repositories), a few GB of disk and RAM, and 30-60 minutes for the base compile. |
+| The archiver and partitioner (all paths) | Go 1.26.5+ (pinned in [go.mod](https://github.com/pgEdge/ColdFront/blob/main/go.mod)) and `make` (`make build` produces `./bin/archiver` and `./bin/partitioner`). |
+| The compactor and the CI gate | golangci-lint for `make compactor`; `./run-ci-local.sh` also needs Docker and mkdocs with mkdocs-material. |
+| Bare metal (below) | `pg_config`, PostgreSQL server dev headers, libpq client headers and library (libpq-dev / libpq-devel), `make`, and `gcc`. |
 
 ## Bare Metal (No Docker)
 
@@ -177,19 +189,27 @@ make && make install        # needs pg_config + PG server dev headers on PATH
 ```
 
 You separately need pg_duckdb (DuckDB 1.5.4) and the **patched** iceberg DuckDB
-extension installed in your PostgreSQL - follow the compile steps in
-[`docker/Dockerfile.duckdb15-base`](https://github.com/pgEdge/ColdFront/blob/main/docker/Dockerfile.duckdb15-base) -
-plus, in `postgresql.conf`:
+extension installed in your PostgreSQL. Follow the compile steps in
+[`docker/Dockerfile.duckdb15-base`](https://github.com/pgEdge/ColdFront/blob/main/docker/Dockerfile.duckdb15-base),
+and copy the built iceberg, avro, azure, and postgres_scanner extensions into
+`$PGDATA/pg_duckdb/extensions/v1.5.4/linux_<arch>/`, as
+[`docker/entrypoint.sh`](https://github.com/pgEdge/ColdFront/blob/main/docker/entrypoint.sh)
+does. Then set the following in `postgresql.conf`:
 
 ```ini
 shared_preload_libraries = 'pg_duckdb,coldfront'
+# The locally built iceberg extension is unsigned.
+duckdb.allow_unsigned_extensions = true
 coldfront.warehouse           = '<warehouse-name>'
 coldfront.lakekeeper_endpoint = 'http://<lakekeeper-host>:8181/catalog'
 coldfront.local_pg_dsn        = 'host=/var/run/postgresql dbname=<db> user=<role>'
+# Optional, and only with the patched duckdb-iceberg: async cold-write ordering.
+coldfront.iceberg_async_parquet = on
+coldfront.iceberg_bakery_patch  = on
 ```
 
-(See the README for the full GUC set and the optional turnkey non-superuser
-role.)
+See [usage.md → Tuning Knobs](usage.md#tuning-knobs) for the remaining GUCs,
+and the README for the optional non-superuser role that the image sets up.
 
 ## Testing & CI
 
@@ -205,22 +225,27 @@ built on the prebuilt
 
 ### Pre-Commit Gate
 
-`./run-ci-local.sh` runs `ci/matrix.sh --quick`: gofmt, golangci-lint, unit
-tests, build, the pg_regress unit layer, and the full journey on one
-representative cell (PG18 · vanilla · tiered · s3). Fast; runs on every commit.
-GitHub Actions
+`./run-ci-local.sh` runs `ci/matrix.sh --quick`: gofmt, go vet, golangci-lint,
+unit tests, build, the compactor module gate (vet, lint, test, build),
+`mkdocs build --strict`, the base recipe hash check, the pg_regress unit layer,
+and the full journey on one representative cell (PG18 · vanilla · tiered · s3).
+The gate is fast and runs on every commit. GitHub Actions
 ([.github/workflows/ci.yml](https://github.com/pgEdge/ColdFront/blob/main/.github/workflows/ci.yml))
-runs the identical `ci/matrix.sh` harness - `--quick` on every push/PR,
-`--full` nightly and on demand - so local and CI never diverge.
+runs the identical `ci/matrix.sh` harness: `--quick` on every pull request and
+every push to `main`, and `--full` nightly and on demand. GitHub also runs a
+gitleaks secret scan, a go-licenses check, and the path-filtered walkthrough
+workflow, which the local gate does not.
 
 ### Full Matrix
 
-`ci/matrix.sh --full`, the beta gate: PG {16, 17, 18} × {vanilla, mesh (3-node
-Spock)} × {tiered, decoupled} × {primary, standby} × {s3, aws, azure, gcs}. The
-mesh cells add the cross-node stories - hot visibility via Spock, cold
-visibility via the shared Lakekeeper catalog, the R-A bakery serializing
-concurrent cold writers (same-node and cross-node) with no 409, and an N×(N-1)
-probe that the bakery's `coldfront.claims` table replicates in every direction.
+`ci/matrix.sh --full` is the release gate, covering PG {16, 17, 18} × {vanilla,
+mesh (3-node Spock)} × {tiered, decoupled} × {primary, standby} × {s3, aws,
+azure, gcs, vended, azure-vended}, where the two vended backends run on vanilla
+only. The ops-hardening and probe-snowflake cells run once, on PG18. The mesh
+cells add the cross-node stories - hot visibility via Spock, cold visibility
+via the shared Lakekeeper catalog, the R-A bakery serializing concurrent cold
+writers (same-node and cross-node) with no 409, and an N×(N-1) probe that the
+bakery's `coldfront.claims` table replicates in every direction.
 
 ### Storage-Backend Gating
 
@@ -229,15 +254,29 @@ The same policy applies locally and in GitHub CI: the hermetic
 with no credentials. The real cloud stores run **only when their credentials
 are present in the environment**, else they are reported `PENDING` and never
 invoked (no real cloud calls without explicit creds). The following table shows
-each backend and its gating environment variables:
-
-| Backend | Store | Gating env vars |
-|---|---|---|
-| `s3`    | SeaweedFS (in-compose, hermetic) | - always runs |
-| `aws`   | real AWS S3 (native vhost+HTTPS) | `COLDFRONT_AWS_ACCESS_KEY`, `_SECRET_KEY`, `_BUCKET`, `_REGION` |
-| `azure` | real Azure ADLS Gen2             | `COLDFRONT_AZURE_ACCOUNT`, `_FILESYSTEM`, `_KEY`, `_CONNECTION_STRING` |
-| `gcs`   | real GCS via S3-interop (HMAC)   | `COLDFRONT_GCS_ACCESS_KEY`, `_SECRET_KEY`, `_BUCKET` |
+each backend, the variable whose presence turns it on, and the other variables
+it then requires; a lane turned on without the rest fails instead of staying
+`PENDING`:
+
+| Backend | Store | Gate variable | Also required |
+|---|---|---|---|
+| `s3`    | SeaweedFS (in-compose, hermetic) | None; this backend always runs. | None |
+| `vended` | SeaweedFS STS credential vending (hermetic, vanilla only) | None; this backend always runs. | None |
+| `aws`   | Real AWS S3 (native virtual-hosted addressing over HTTPS) | `COLDFRONT_AWS_ACCESS_KEY` | `COLDFRONT_AWS_SECRET_KEY`, `_BUCKET`, `_REGION` |
+| `azure` | Real Azure ADLS Gen2 | `COLDFRONT_AZURE_CONNECTION_STRING` | `COLDFRONT_AZURE_ACCOUNT`, `_FILESYSTEM`, `_KEY` |
+| `azure-vended` | Real Azure ADLS Gen2 with SAS vending (vanilla only) | `COLDFRONT_AZURE_KEY` | `COLDFRONT_AZURE_ACCOUNT`, `_FILESYSTEM` |
+| `gcs`   | Real GCS via S3 interoperability (HMAC) | `COLDFRONT_GCS_ACCESS_KEY` | `COLDFRONT_GCS_SECRET_KEY`, `_BUCKET` |
 
 In GitHub Actions these come from repo secrets; an unset secret arrives empty,
 so that backend stays `PENDING`. Fork PRs (no secret access) run
 SeaweedFS-only.
+
+## Next Steps
+
+To go further with ColdFront, consult the following guides:
+
+- The [Walkthrough](walkthrough.md) guide runs the demo stack hands-on.
+- The [Using ColdFront](usage.md) guide covers the one-time setup and both
+  modes.
+- The [Object Store Setup](object_store.md) guide connects the cold tier to AWS
+  S3.
diff --git a/docs/object_store.md b/docs/object_store.md
index e912000..661dbc0 100644
--- a/docs/object_store.md
+++ b/docs/object_store.md
@@ -6,13 +6,14 @@ Lakekeeper Iceberg catalog) with Docker, point it at your bucket, and write
 rows that land as Apache Iceberg tables in S3 - readable straight back through
 Postgres.
 
-It targets a real cloud S3 service that uses virtual-hosted addressing. For a
-path-style S3-compatible store (MinIO, SeaweedFS) or GCS, see
+This walkthrough targets a real cloud S3 service that uses virtual-hosted
+addressing. For a path-style S3-compatible store (MinIO, SeaweedFS) or GCS, see
 [usage.md → Storage Backends](usage.md#storage-backends) instead.
 
-No prior ColdFront knowledge assumed. Copy-paste top to bottom. Placeholders
-used throughout: bucket `my-iceberg-bucket`, region `eu-west-1`, key
-`AKIAEXAMPLE...`, secret `<your-secret-key>` - substitute your own.
+No prior ColdFront knowledge is assumed. Copy and paste the commands from top
+to bottom. The examples use the following placeholders throughout: bucket
+`my-iceberg-bucket`, region `eu-west-1`, key `AKIAEXAMPLE...`, secret
+`<your-secret-key>` - substitute your own.
 
 ---
 
@@ -20,23 +21,24 @@ used throughout: bucket `my-iceberg-bucket`, region `eu-west-1`, key
 
 Before you begin, gather the following:
 
-- **An S3 bucket** - `my-iceberg-bucket` below.
-- **Its region** - `eu-west-1` below. Use your bucket's real region.
-- **A long-term access key** - an access key id (`AKIAEXAMPLE...`) and secret
-  (`<your-secret-key>`).
+- an S3 bucket (`my-iceberg-bucket` in the examples below).
+- the bucket's real region (`eu-west-1` in the examples below).
+- a long-term access key, meaning an access key id (`AKIAEXAMPLE...`) and its
+  secret (`<your-secret-key>`).
 
-    > **Long-term keys only.** Lakekeeper's warehouse credential has no field
-    > for a session token, so single sign-on (SSO) or temporary session-token
-    > credentials do **not** work here. Use a permanent access-key pair with no
-    > expiry.
+    > **Only long-term keys work.** Lakekeeper's warehouse credential has no
+    > field for a session token, so single sign-on (SSO) or temporary
+    > session-token credentials do **not** work here. Use a permanent
+    > access-key pair with no expiry.
     >
     > This applies to the warehouse's own credential. A deployment that must
     > not store any object-store credential in the database can use vended
     > credentials instead, where the warehouse issues short-lived per-table
     > credentials at access time; see [usage.md](usage.md#vended-credentials).
 
-- **Permissions** - the key needs read/write/list on the bucket (`GetObject` /
-  `PutObject` / `DeleteObject` / `ListBucket`). Example policy:
+- permission for the key to read, write and list the bucket (`GetObject` /
+  `PutObject` / `DeleteObject` / `ListBucket`), as in the following example
+  policy:
 
     ```json
     {
@@ -54,9 +56,9 @@ Before you begin, gather the following:
     }
     ```
 
-- **The ColdFront image, built once.** Build it by following
-  [installation.md](installation.md) (it notes the registry access the base
-  image needs). Run the commands below from the repo root.
+- the ColdFront image, built once by following
+  [installation.md](installation.md), which notes the registry access the base
+  image needs. Run the commands below from the repo root.
 
 ---
 
@@ -70,10 +72,10 @@ docker compose up -d --build
 
 This starts **Postgres** (with `pg_duckdb` and `coldfront` preloaded),
 **Lakekeeper** (the Iceberg REST catalog), Lakekeeper's **own catalog
-Postgres**, and a one-shot **migrate** job. It does **not** start the bundled
-SeaweedFS - that is gated behind the `local-store` profile for credential-free
-local eval. For cloud S3 you talk to the bucket directly, so you don't need the
-bundled SeaweedFS.
+Postgres**, and a one-shot **migrate** job. The command does **not** start the
+bundled SeaweedFS - that is gated behind the `local-store` profile for
+credential-free local evaluation. For cloud S3 you connect to the bucket
+directly, so you do not need the bundled SeaweedFS.
 
 If a local Postgres already owns port 5432, pick another host port:
 
@@ -81,6 +83,10 @@ If a local Postgres already owns port 5432, pick another host port:
 COLDFRONT_PG_PORT=55432 docker compose up -d --build
 ```
 
+If port 8181 is taken, set `COLDFRONT_LK_PORT` the same way to move
+Lakekeeper's host port. Then use that port in place of `8181` in every `curl`
+command in Section 3.
+
 Wait for Postgres to report healthy (the container name is derived from your
 directory, so resolve it at runtime):
 
@@ -107,16 +113,17 @@ curl -X POST http://localhost:8181/management/v1/bootstrap \
 ### 3b. Create the S3 Warehouse
 
 A warehouse tells Lakekeeper where on S3 your Iceberg tables live and which
-credential to use. This is the **virtual-hosted cloud-S3** profile - these
-flags matter:
-
-- `endpoint` **omitted** ⇒ native per-Region virtual-hosted + HTTPS addressing.
-- `path-style-access: false` - required for virtual-hosted S3; path-style fails
-  on any Region launched after 2019.
-- `flavor: "aws"` - the Lakekeeper profile for virtual-hosted S3, not
+credential to use. This is the **virtual-hosted cloud-S3** profile, and the
+following flags matter:
+
+- omitting `endpoint` selects native per-Region virtual-hosted addressing over
+  HTTPS.
+- `path-style-access: false` is required for virtual-hosted S3, because
+  path-style fails on any Region launched after 2019.
+- `flavor: "aws"` selects the Lakekeeper profile for virtual-hosted S3, not
   `s3-compat`.
-- `sts-enabled: false` and `remote-signing-enabled: false` - long-term access
-  key.
+- `sts-enabled: false` and `remote-signing-enabled: false` make the warehouse
+  use the long-term access key.
 
 Create the warehouse with those flags set:
 
@@ -148,10 +155,10 @@ curl -X POST http://localhost:8181/management/v1/warehouse \
 The `key-prefix` is an arbitrary path inside the bucket. `coldfront` is only an
 example.
 
-Vended-credentials variant. To run ColdFront with no stored credential
-([usage.md](usage.md#vended-credentials)), the warehouse issues per-table STS
-credentials instead of handing the client a static key. Two things change from
-the warehouse above.
+A vended-credentials variant is also available. To run ColdFront with no stored
+credential ([usage.md](usage.md#vended-credentials)), the warehouse issues
+per-table temporary credentials from AWS Security Token Service (STS) instead
+of handing the client a static key. Two things change from the warehouse above.
 
 First, create an IAM role scoped to the bucket. Lakekeeper assumes the role per
 table and vends the resulting short-lived key, secret, and session token to
@@ -190,10 +197,11 @@ the `storage-profile`, and add the matching `external-id` to the
 }
 ```
 
-An `external-id` is **required** with `assume-role-arn`; the `<shared-secret>`
-in the warehouse and in the role's trust condition must match. On the database
-side, replace the `set_storage_secret(...)` call in Section 4 with
-`SELECT coldfront.set_storage_secret_vended();`.
+The role's trust policy above requires `sts:ExternalId`, so the `external-id`
+in the warehouse credential must match the `<shared-secret>` in that condition;
+Lakekeeper itself makes `external-id` mandatory only for `aws-system-identity`
+credentials. On the database side, replace the `set_storage_secret(...)` call
+in Section 4 with `SELECT coldfront.set_storage_secret_vended();`.
 
 ### 3c. Pre-Create the `public` Namespace
 
@@ -212,10 +220,11 @@ curl -X POST "http://localhost:8181/catalog/v1/$WID/namespaces" \
 > **Why this step is required (decoupled mode).**
 > `coldfront.create_iceberg_table()` (Section 5) runs `CREATE SCHEMA` and
 > `CREATE TABLE` in one transaction. The schema create is deferred to COMMIT
-> but the table create is POSTed eagerly, so against a namespace-less warehouse
-> it 404s. Pre-creating `public` makes the in-transaction
-> `CREATE SCHEMA IF NOT EXISTS` a no-op. (Tiered mode's archiver creates the
-> namespace itself, so this is only needed for the decoupled demo below.)
+> but the table-create POST is sent immediately, so against a namespace-less
+> warehouse it fails with HTTP 404. Pre-creating `public` makes the
+> in-transaction `CREATE SCHEMA IF NOT EXISTS` a no-op. (Tiered mode's archiver
+> creates the namespace itself, so this is only needed for the decoupled demo
+> below.)
 
 ---
 
@@ -239,7 +248,7 @@ CREATE EXTENSION IF NOT EXISTS coldfront;
 > **`CREATE EXTENSION coldfront` is required and easy to miss.** The image
 > preloads the `coldfront` shared library, but preloading does not register the
 > extension's schema and functions in your database - you must
-> `CREATE EXTENSION` it once. Skip it and the next call fails with
+> `CREATE EXTENSION` it once. Skip that step and the next call fails with
 > `schema "coldfront" does not exist`.
 
 Set the cold-tier S3 credential once. The signature is
@@ -310,19 +319,35 @@ export AWS_DEFAULT_REGION=eu-west-1
 aws s3 ls s3://my-iceberg-bucket/coldfront/ --recursive
 ```
 
-Iceberg stores objects under `coldfront/<namespace-uuid>/<table-uuid>/` with a
-`data/` directory (parquet) and a `metadata/` directory (metadata JSON,
-`*.avro` manifests, snapshot files) - UUID paths, not your table name. "Where
-did `s3_demo` go?" → look under the UUID path beneath your `key-prefix`.
-
-Work through this checklist if something failed:
-
-- **`CREATE EXTENSION coldfront`** - ran it once in your database? Preloading
-  is not the same as creating the extension. Symptom:
-  `schema "coldfront" does not exist`.
-- **`set_storage_secret(..., NULL, 'eu-west-1')`** - 3rd arg `NULL` (native
-  vhost+HTTPS), 4th arg your real region? A non-NULL endpoint forces path-style
-  and breaks modern Regions (HTTP 400).
-- **Namespace `public` pre-created** in Lakekeeper before
-  `create_iceberg_table`? Without it the decoupled create 404s.
-- **Long-term key** - not an SSO / temporary session-token credential.
+Iceberg stores each table directly under your `key-prefix`, as
+`coldfront/<table-uuid>/`, with a `data/` directory (parquet) and a `metadata/`
+directory (metadata JSON, `*.avro` manifests, snapshot files) - UUID paths, not
+your table name. (A namespace created on a Lakekeeper release before 0.13 keeps
+its `coldfront/<namespace-uuid>/<table-uuid>/` layout.) "Where did `s3_demo`
+go?" → look under the UUID path beneath your `key-prefix`.
+
+Work through the following checklist if something failed:
+
+- Check that you ran `CREATE EXTENSION coldfront` once in your database.
+  Preloading is not the same as creating the extension, and a missing extension
+  produces `schema "coldfront" does not exist`.
+- Check that `set_storage_secret(..., NULL, 'eu-west-1')` has `NULL` as its
+  third argument (native virtual-hosted addressing over HTTPS) and your real
+  region as its fourth. A non-NULL endpoint forces path-style addressing and
+  breaks modern Regions with HTTP 400.
+- Check that the namespace `public` exists in Lakekeeper before
+  `create_iceberg_table` runs. Without the namespace, the decoupled create
+  fails with HTTP 404.
+- Check that the key is a long-term key, not an SSO or temporary session-token
+  credential.
+
+## Next Steps
+
+To go further with ColdFront, consult the following guides:
+
+- The [Using ColdFront](usage.md) guide covers the archiver config, the
+  partition CLI, and the other storage backends.
+- The [Compaction](compaction.md) guide covers cold-tier maintenance on the
+  bucket.
+- The [Architecture](architecture.md) overview describes how the cold tier is
+  read and written.
diff --git a/docs/usage.md b/docs/usage.md
index 03a0495..8b78d24 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -1,17 +1,18 @@
 # Using ColdFront
 
 ColdFront offers two operating modes. Pick one per table; both can coexist in
-the same database. The two modes compare as follows:
+the same database. The following table compares the two modes:
 
 | | Tiered (hot + cold) | Decoupled (iceberg-only) |
 |---|---|---|
-| **Where rows live** | Hot in PG heap (recent), cold in Iceberg (archived) | Everything in Iceberg |
-| **Setup** | Create a partitioned table; let the archiver convert it on first run | One SQL call: `coldfront.create_iceberg_table(...)` |
-| **Archiver** | Required (cron, moves old partitions to cold) | Not used |
-| **Best when** | Workload has a recent-row OLTP part that benefits from PG indexes + transactional ergonomics | Pure analytic / append-mostly; you want zero PG storage and stateless compute |
+| Where rows live | Recent rows are hot in the PG heap, and archived rows are cold in Iceberg. | Every row is in Iceberg. |
+| Setup | Create a partitioned table and let the archiver convert it on the first run that finds a partition older than `hot_period`. | One SQL call, `coldfront.create_iceberg_table(...)`, sets up the table. |
+| Archiver | The archiver is required; it runs from cron and moves old partitions to cold. | The archiver is not used. |
+| Best when | The workload has a recent-row OLTP part that benefits from PG indexes and transactional ergonomics. | The workload is purely analytic or append-mostly, and you want zero PG storage and stateless compute. |
 
 Once the table exists, **the SQL surface is identical**: `SELECT`, `INSERT`,
-`UPDATE`, `DELETE` all work normally against the relation name (e.g. `events`).
+`UPDATE`, `DELETE` all work normally against the relation name (e.g. `events`),
+except that a write touching the cold tier rejects `RETURNING`.
 
 ## Prerequisites (Both Modes)
 
@@ -56,12 +57,13 @@ curl -X POST http://localhost:8181/management/v1/warehouse \
 
 # 3. Create the Iceberg namespace in the new warehouse.
 #    REQUIRED for decoupled (iceberg-only) mode: the Iceberg CREATE SCHEMA is
-#    deferred to transaction COMMIT but CREATE TABLE is POSTed eagerly, so
-#    coldfront.create_iceberg_table - which runs both in one
-#    transaction - would 404 against a cold warehouse. Pre-creating the
-#    namespace here (its own committed REST call) makes the function's in-txn
-#    CREATE SCHEMA IF NOT EXISTS a no-op so the table create succeeds. The
-#    archiver (tiered mode) creates the namespace itself and does not need this.
+#    deferred to transaction COMMIT but the CREATE TABLE POST is sent
+#    immediately, so coldfront.create_iceberg_table - which runs both in one
+#    transaction - would fail with HTTP 404 against a cold warehouse.
+#    Pre-creating the namespace here (its own committed REST call) makes the
+#    function's in-txn CREATE SCHEMA IF NOT EXISTS a no-op so the table create
+#    succeeds. The archiver (tiered mode) creates the namespace itself and does
+#    not need this.
 WID=$(curl -s http://localhost:8181/management/v1/warehouse \
   | grep -oE '"warehouse-id":"[^"]+"' | head -1 | cut -d'"' -f4)
 curl -X POST "http://localhost:8181/catalog/v1/$WID/namespaces" \
@@ -85,6 +87,42 @@ SECRET that loads at instance init. There is **no per-session setup**: the
 Iceberg catalog `ice` attaches **lazily** by the coldfront C hook on the first
 query that touches a tiered/decoupled view (read or write).
 
+Every `set_storage_secret()` argument after the secret is optional.
+`p_endpoint` defaults to `NULL`, `p_region` to `'us-east-1'`, `p_url_style` to
+`'path'` (the other value is `'vhost'`), and `p_use_ssl` to `false`.
+`p_url_style` and `p_use_ssl` apply only when an endpoint is given. A TLS
+endpoint such as GCS's needs `p_use_ssl => true`, and AWS S3 omits the endpoint
+and sets `p_region` to the bucket's Region.
+
+The image writes the server settings ColdFront needs into `postgresql.conf`
+when it initializes a new data directory. A server built another way sets them
+itself, as [installation.md](installation.md#bare-metal-no-docker) shows:
+
+- `shared_preload_libraries = 'pg_duckdb,coldfront'` loads both extensions at
+  server start.
+- `coldfront.warehouse` and `coldfront.lakekeeper_endpoint` name the Lakekeeper
+  warehouse and its catalog endpoint, which the Iceberg catalog `ice` attaches
+  to. Only a superuser can set them, and while either is empty the catalog does
+  not attach.
+- `coldfront.local_pg_dsn` is the connection string DuckDB uses to read
+  PostgreSQL tables from this server, which a cold `INSERT … SELECT` from a
+  PostgreSQL table needs. Only a superuser can set or read it. Set it before
+  calling `set_storage_secret()`, which installs the DuckDB `postgres`
+  extension this path loads only when the setting is present.
+
+An application that connects as a non-superuser needs its role granted access
+with `coldfront.grant_app_access()`, which takes an existing role:
+
+```sql
+SELECT coldfront.grant_app_access('alice');
+```
+
+The grants are derived from the registry at call time, so run the call again
+after a table is created, adopted or first tiered. The call fails while
+`duckdb.postgres_role` is unset, because only superusers can then run DuckDB.
+[Least-Privilege Application Roles](index.md#least-privilege-application-roles)
+lists what it grants.
+
 For a real cloud-S3 setup, see [object_store.md](object_store.md).
 
 ## Mode 1 - Tiered (Hot + Cold)
@@ -104,8 +142,31 @@ CREATE TABLE p_2026_04 PARTITION OF events
     FOR VALUES FROM ('2026-04-01') TO ('2026-05-01');
 ```
 
-Register it in `coldfront.partition_config` (the in-DB per-table config; the
-YAML holds only the connection + cold-store settings):
+The archiver reads its connection and cold-store settings from a YAML file:
+
+```yaml
+postgres:
+  dsn: "host=localhost dbname=mydb"
+iceberg:
+  warehouse: "wh"
+  lakekeeper_endpoint: "http://lakekeeper:8181/catalog"
+s3:
+  endpoint: "seaweedfs:8333"
+  access_key: "admin"
+  secret_key: "adminsecret"
+```
+
+The archiver cannot run without `iceberg.warehouse` and
+`iceberg.lakekeeper_endpoint`. A config that sets an S3 endpoint or key, or an
+Azure connection string, without them fails to load. A config that sets none of
+these keys is partition-only, and a partition-only config rejects every tiered
+table. `s3.region` defaults to `us-east-1`.
+[Storage Backends](#storage-backends) describes the other `s3:` and `azure:`
+keys, and a deployment on [vended credentials](#vended-credentials) omits both
+sections.
+
+Register the table in `coldfront.partition_config` (the in-DB per-table config;
+the YAML holds only the connection + cold-store settings):
 
 ```bash
 ./bin/archiver register --config config.yaml --table events \
@@ -120,12 +181,23 @@ Run the archiver (typically via cron):
 ./bin/archiver --config config.yaml
 ```
 
-`--version` prints the build's version (the release tag, or the commit it was
-built from) and exits; the partitioner and compactor accept the same flag.
-
-The first run renames `events` → `_events`, creates the unified view `events`,
-and registers it. From then on every cycle (1) tiers partitions older than
-`hot_period` from hot PG to cold Iceberg and advances the watermark, and (2) if
+`--version` prints the version that `make build` stamps from `git describe`
+(the release tag, or the commit it was built from) and exits; a plain
+`go build` prints `unknown`. The partitioner and compactor accept the same
+flag.
+
+Without `--config`, the archiver reads `config.yaml` from the working
+directory. The partitioner has no default and exits with
+`--config is required`. The archiver also accepts `--debug-export-delay`, a
+test-only Go duration (such as `5s`) that holds each partition's capture window
+open between the bulk export and the replay, so that a test can race concurrent
+writes into it. Leave it unset in production.
+
+The first run that finds a partition older than `hot_period` renames `events` →
+`_events`, creates the unified view `events`, and registers it; until then the
+archiver only premakes partitions, and the table stays a plain partitioned
+table. From then on every cycle (1) tiers partitions older than `hot_period`
+from hot PG to cold Iceberg and advances the watermark, and (2) if
 `retention_period` is set, drops cold Iceberg rows older than it. The data
 lifecycle is **hot → `hot_period` → cold → `retention_period` → gone**; omit
 `retention_period` to keep cold data forever.
@@ -180,7 +252,7 @@ once it is cold for every region. `id` mode is not supported in tiered mode
 
 ## Mode 2 - Decoupled (Iceberg-Only)
 
-Single call:
+A single call creates a decoupled table:
 
 ```sql
 SELECT coldfront.create_iceberg_table(
@@ -199,30 +271,30 @@ SELECT coldfront.create_iceberg_table(
 `p_partition_cols` partitions the Iceberg table, here by the month of `ts`:
 each month's rows land in their own data files, and a query with a time filter
 skips the months outside it before reading anything. Each element is one term
-as DuckDB's `PARTITIONED BY` takes it: a column name, `year(col)`,
-`month(col)`, `day(col)` or `hour(col)` on a timestamp or date column,
+as DuckDB's `PARTITIONED BY` takes it: a column name, `year(col)`, `month(col)`
+or `day(col)` on a timestamp or date column, `hour(col)` on a timestamp column,
 `bucket(N, col)` or `truncate(W, col)`; `'{month(ts), region}'` partitions by
 both. The argument is a PostgreSQL array literal, so a term that contains a
 comma is double-quoted inside it, the comma being the array's delimiter:
-`'{"bucket(16, id)"}'`. A column name that itself needs double quotes carries
-them backslashed inside such an element: `'{"month(\"Event Time\")"}'`. Leave
-the argument out for an unpartitioned table.
+`'{"bucket(16, id)"}'`. A column name that itself needs double quotes has them
+backslashed inside such an element: `'{"month(\"Event Time\")"}'`. Leave the
+argument out for an unpartitioned table.
 
 That single statement provisions:
 
 - `ice.public.events` on the attached Iceberg catalog.
 - a PG-side wrapper view `public.events` with proper PG-typed columns.
 
-- a `coldfront.tiered_views` registry row - every INSERT, UPDATE, and DELETE on
-  the view is intercepted by the coldfront C hook and rewritten to a single
-  `duckdb.raw_query(...)` against `ice.public.events`.
+- a `coldfront.tiered_views` registry row, so that the coldfront C hook
+  intercepts every INSERT, UPDATE, and DELETE on the view and rewrites each one
+  to a single `duckdb.raw_query(...)` against `ice.public.events`.
 
 
 In a mesh one node provisions: Spock's `ddl_sql` repset replicates the
 `CREATE VIEW`, and the `default` repset replicates the name-keyed registry row,
-which arms the write hook on every peer. Each node also needs the bakery armed
-via `coldfront._ensure_claims_replicated()` - see the one-time mesh setup
-below.
+which enables the write hook on every peer. Each node also needs the bakery
+enabled via `coldfront._ensure_claims_replicated()` - see the one-time mesh
+setup below.
 
 ### Adopting a Table That Already Exists in the Catalog
 
@@ -244,8 +316,8 @@ not exist as a PostgreSQL schema; it defaults to `p_schema` when omitted. The
 view takes the table's name.
 
 Adoption is read-only unless asked otherwise, so reading someone else's lake
-table cannot become writing it by accident. Passing `p_writable => true` arms
-the same INSERT, UPDATE and DELETE rewrite a created table gets:
+table cannot become writing it by accident. Passing `p_writable => true`
+enables the same INSERT, UPDATE and DELETE rewrite a created table gets:
 
 ```sql
 SELECT coldfront.adopt_iceberg_table('public', 'orders', 'lake',
@@ -264,10 +336,10 @@ SELECT coldfront.adopt_iceberg_table('public', 'orders', 'lake',
 ```
 
 Adoption binds the name once. A second call under a registered name is refused
-whatever its arguments; to arm writes or change an override, release the table
-with `coldfront.release_iceberg_table()` and adopt it again. A non-superuser
-deployment runs `coldfront.grant_app_access()` after adopting, because the
-grant reads the registry at call time.
+whatever its arguments; to enable writes or change an override, release the
+table with `coldfront.release_iceberg_table()` and adopt it again. A
+non-superuser deployment runs `coldfront.grant_app_access()` after adopting,
+because the grant reads the registry at call time.
 
 In a mesh one node adopts. The wrapper view replicates through Spock's
 `ddl_sql` repset and the registry row through the `default` repset (see the
@@ -284,7 +356,7 @@ quoting, such as `Lake-EU`, works.
 
 ## Mode 3 - Standalone Partition Manager (No Cold Tier)
 
-**You don't need Iceberg at all.** If automated PostgreSQL partition
+**You do not need Iceberg at all.** If automated PostgreSQL partition
 maintenance is all you want - declarative time- or id-based RANGE partitioning
 with a premade forward window and automatic age-out of old partitions -
 ColdFront's `partitioner` binary is the whole product: stock PostgreSQL (or a
@@ -292,7 +364,7 @@ Spock mesh), no cold tier, no DuckDB, no Iceberg, nothing to preload. Each
 invocation makes one reconcile pass per managed table: premake the forward
 window, ensure the partition covering *now* exists, and detach-then-drop
 partitions past retention (`DETACH ... CONCURRENTLY`, never a bare `DROP` of
-attached data). Build it with `make build` and run it from cron:
+attached data). Build the partitioner with `make build` and run it from cron:
 
 ```bash
 go build -o bin/partitioner ./cmd/partitioner   # or: make build
@@ -303,8 +375,9 @@ A database set up this way can gain the cold tier later:
 `CREATE EXTENSION coldfront` adopts the `coldfront.partition_config` the
 partitioner created, registrations included.
 
-A partition-only config omits the `iceberg:` and `s3:` sections entirely
-(supply either all of them or none - a half-filled cold config is rejected):
+A partition-only config has no `iceberg:`, `s3:` or `azure:` section. Any one
+of them makes it a cold-tier config, which requires `iceberg.warehouse` and
+`iceberg.lakekeeper_endpoint` and which the partitioner rejects:
 
 ```yaml
 postgres:
@@ -324,8 +397,8 @@ Register each managed table in `coldfront.partition_config`:
 ### Operating It
 
 Schedule one pass per period or more often - a cron line, or a systemd
-`oneshot` service plus timer (a failed pass then surfaces as a failed unit, so
-alerting is free):
+`oneshot` service plus timer (systemd then reports a failed pass as a failed
+unit, so alerting is free):
 
 ```text
 17 * * * * postgres /usr/local/bin/partitioner --config /etc/coldfront/partitioner.yaml >> /var/log/coldfront-partitioner.log 2>&1
@@ -333,19 +406,20 @@ alerting is free):
 
 Keep the following operational behavior in mind when scheduling it:
 
-- **Exit codes.** `0` = every table reconciled (a self-healed *behind*
-  condition still exits `0`); non-zero = at least one table failed
-  (`N table(s) failed`), each logged with its `[schema.table]` prefix. Alert on
-  non-zero.
-- **Behind-detection.** If the table already has a *past* partition but none
-  covers *now* at the start of a pass (a lagging cron - live inserts had no
-  home), the pass heals it (creates the current partition), logs a
-  `WARNING (self-healed)` line, and still exits `0`. Monitor for that warning
-  in the log rather than via the exit code, and widen `future_partitions` or
-  run more often. A fresh table (only just-premade future partitions) is
-  **not** behind: its first reconcile succeeds cleanly.
-- **Retention strategy.** With the default `expiration_strategy: drop`, expiry
-  is `DETACH CONCURRENTLY` + `DROP TABLE` - the data is **gone**, so back up
+- The exit code is `0` when every table reconciled (a self-healed *behind*
+  condition still exits `0`) and non-zero when at least one table failed
+  (`N table(s) failed`), each failure logged with a `[table]` prefix (the bare
+  table name) followed by the schema-qualified error. Alert on a non-zero exit
+  code.
+- If a table already has a *past* partition but none covers *now* at the start
+  of a pass (a lagging cron - live inserts had no home), the pass heals the
+  table (creates the current partition), logs a `WARNING (self-healed)` line,
+  and still exits `0`. Monitor for that warning in the log rather than via the
+  exit code, and widen `future_partitions` or run more often. A fresh table
+  (only just-premade future partitions) is **not** behind: its first reconcile
+  succeeds cleanly.
+- With the default `expiration_strategy: drop`, expiry is
+  `DETACH CONCURRENTLY` + `DROP TABLE` - the data is **gone**, so back up
   before shrinking `retention_period`. Set `expiration_strategy: detach` to
   instead leave the expired partition as a standalone table (detached from the
   parent, data preserved) and reclaim it yourself. A partition is expired only
@@ -392,12 +466,19 @@ values automatically:
         values_source: "SELECT code FROM regions"
 ```
 
+Each level-1 child is named `<table>_<value>`, with the value lowercased and
+every character outside `a-z`, `0-9` and `_` replaced by `_`. That name must
+fit in 50 bytes, which leaves room for the daily leaf suffix within
+PostgreSQL's 63-byte identifier limit. A pass that meets a longer name fails,
+for tiered two-level tables as well. The partitioner also fails a pass in which
+two values map to the same name.
+
 ## Dropping an Iceberg Table (Both Modes)
 
 `coldfront.drop_iceberg_table()` removes the Iceberg table backing a registered
-relation. It is the only sanctioned way to do so: a plain `DROP TABLE` or
-`DROP VIEW` on a registered relation stays blocked, because it would leave the
-cold tier behind with nothing pointing at it.
+relation. The function is the only sanctioned way to do so: a plain
+`DROP TABLE` or `DROP VIEW` on a registered relation stays blocked, because it
+would leave the cold tier behind with nothing pointing at it.
 
 The call takes the schema, the table, and an explicit purge decision:
 
@@ -451,7 +532,7 @@ SELECT coldfront.release_iceberg_table('public', 'orders');
 Release refuses a tiered registration, because removing one would leave its
 cold rows unreachable while the hot table returned under the relation's name.
 `drop_iceberg_table()` refuses a relation adopted read-only, for the mirrored
-reason: read access carries no authority to destroy.
+reason: read access gives no authority to destroy.
 
 ## Managing Partitioned Tables (CLI)
 
@@ -460,16 +541,17 @@ PostgreSQL DSN, and (tiered archiver only) the Iceberg/S3 connection - stays in
 a small per-node YAML and is never replicated. **Per-table lifecycle** lives in
 `coldfront.partition_config`, a name-keyed table that replicates by value
 across a Spock mesh (like `tiered_views`/`archive_watermark`), so every node
-reads identical config - no per-node file syncing. Manage it with the CLI below
-(both `partitioner` and `archiver` expose these subcommands; with no subcommand
-they do their normal reconcile/archive run).
+reads identical config - no per-node file syncing. Manage that table with the
+CLI below (both `partitioner` and `archiver` expose these subcommands; with no
+subcommand they do their normal reconcile/archive run).
 
 `register` is the primary way to manage tables: one command adds or adopts one
 table, validated on the spot. `import` and `export` are bulk helpers for
 (re)configuring a machine - seed a fresh node from a YAML, or dump the live
-config to git and replay it on another node - not the day-to-day path. Every
-write (`register`, `import`, `set`) goes through the same validation, so no
-command can leave `partition_config` in a state another command would reject.
+config to git and replay it on another node - not the day-to-day path.
+`register` and `import` run the full validation; `set` re-runs it only when it
+changes the partition column, `hot_period`, `retention_period` or the
+sub-partition source, and otherwise relies on the table's CHECK constraints.
 
 The data lifecycle is **hot PG → `hot_period` → cold Iceberg →
 `retention_period` → dropped** (tiered) or **hot PG → `retention_period` →
@@ -478,27 +560,28 @@ it makes it partition-only.
 
 ### What Registration Refuses
 
-`register`, `import` and `set` share one validation gate, so a table that one
-command rejects cannot be added by another. Registration fails when:
+`register` and `import` run the same validation, so a table that one rejects
+cannot be added by the other; `set` re-runs it when it changes a validated
+field. Registration fails when:
 
 - any relation in the partition tree is `UNLOGGED`, because that data is
   truncated after a crash and replicates nowhere, so archiving it would
   preserve rows PostgreSQL never promised to keep.
-- the table has a `DEFAULT` partition. Rows it catches carry no time bounds, so
-  they can never be tiered or expired, and PostgreSQL refuses
-  `DETACH PARTITION ... CONCURRENTLY` for every partition of a table that has
-  one, which is how partitions are expired. Its mere existence is enough; it
-  does not have to hold any rows. Move any rows it holds into real partitions
-  and detach it.
+- the table has a `DEFAULT` partition. Rows the `DEFAULT` partition catches
+  have no time bounds, so they can never be tiered or expired, and PostgreSQL
+  refuses `DETACH PARTITION ... CONCURRENTLY` for every partition of a table
+  that has one, which is how partitions are expired. The partition's mere
+  existence is enough; it does not have to hold any rows. Move any rows the
+  `DEFAULT` partition holds into real partitions and detach it.
 - the name differs only by case from an already-registered table. PostgreSQL
   keeps `public."Events"` and `public.events` apart, but DuckDB matches
   identifiers case-insensitively even when they are quoted, so both names would
   resolve to one Iceberg table and overwrite each other.
 - the name starts with an underscore, which is reserved for the tiered hot
   table.
-- the name leaves no room for the generated partition suffix: 53 characters for
+- the name leaves no room for the generated partition suffix: 53 bytes for
   monthly and 50 for daily, within PostgreSQL's 63-byte identifier limit.
-- a tiered table carries a column whose type has no Iceberg equivalent (see
+- a tiered table has a column whose type has no Iceberg equivalent (see
   [Supported Column Types](#supported-column-types)). Every column goes through
   the same type map the cold tier itself uses, so the answer comes back at the
   prompt rather than hours later from cron. Partition-only tables are exempt:
@@ -520,16 +603,18 @@ boundaries are computed with calendar-accurate interval arithmetic
 (`now() - period`: real months, leap years), and `retention_period` must exceed
 `hot_period` (validated at `register`/`set` time).
 
-The CLI exposes the following subcommands:
+The following table describes the CLI subcommands:
 
 | Command | Purpose |
 |---|---|
-| `register` | add/adopt a table - validates the PRIMARY KEY covers the partition key |
-| `list` | show managed tables and their lifecycle |
-| `set` | change fields, or `--disable`/`--enable` a table |
-| `remove` | stop managing a table (the table itself is left intact) |
-| `import` | bulk-load a machine's tables from a YAML's `archiver.tables` (provision/restore; each table validated as `register` does) |
-| `export` | dump the **active (enabled)** config to YAML or SQL - a git-reviewable backup to replay on another node |
+| `register` | Adds or adopts a table, and validates that the PRIMARY KEY covers the partition key. |
+| `list` | Shows the managed tables and their lifecycle. |
+| `set` | Changes fields, or disables or enables a table with `--disable`/`--enable`. |
+| `remove` | Stops managing a table; the table itself is left intact. |
+| `import` | Bulk-loads a machine's tables from a YAML's `archiver.tables` (for provisioning or restore), validating each table as `register` does. |
+| `export` | Dumps the active (enabled) config to YAML or SQL, as a git-reviewable backup to replay on another node. |
+
+The following examples register, inspect, and change managed tables:
 
 ```bash
 # Partition-only: keep 3 future partitions, drop those older than 12 months.
@@ -570,54 +655,93 @@ removing it; a disabled table is skipped by reconcile and omitted from
 `pg_catalog` for flat tables (required for 2-level). `register` writes a row
 whose `CHECK` constraints enforce the lifecycle rules at write time.
 
-Managing tables: the archiver and partitioner read the managed set only from
-`coldfront.partition_config`. `register` adds one table; `import` adds every
-table in a YAML `archiver.tables` list. Both write through the same validation
-(the PK must cover the partition key; `retention` must exceed `hot_period`), so
-an imported table is checked exactly as a registered one. `export` dumps the
-active rows back to YAML or SQL for git.
+The subcommands also take the following connection and table flags:
+
+- `--dsn` takes a PostgreSQL connection string on every subcommand and takes
+  precedence over `--config`, whose `postgres.dsn` is read only when `--dsn` is
+  unset.
+- `--config` names the deployment YAML, and on `import` it is required because
+  it names the file whose `archiver.tables` are imported.
+- `--schema` (default `public`) names the table's schema on `register`, `set`
+  and `remove`.
+- `--premake` (default `3`) sets on `register` how many future partitions are
+  kept ahead of now, stored as `future_partitions`.
+
+`set` changes only the fields whose flags are passed: `--period`, `--column`,
+`--premake`, `--hot-period`, `--retention`, `--sub-values-source` and
+`--strategy`, each taking the same value as on `register`. An empty value
+clears the field, so `--hot-period ""` makes a tiered table partition-only and
+hands it to the partitioner. A change that leaves neither a `hot_period` nor a
+`retention_period` is refused.
+
+For managing tables, the archiver and partitioner read the managed set only
+from `coldfront.partition_config`. `register` adds one table; `import` adds
+every table in a YAML `archiver.tables` list. Both write through the same
+validation (the PK must cover the partition key; `retention` must exceed
+`hot_period`), so an imported table is checked exactly as a registered one.
+`export` dumps the active rows back to YAML or SQL for git.
+
+The archiver manages only the rows that have a `hot_period`, and the
+partitioner only the rows without one, so each table belongs to one binary. A
+run that finds none of its own rows exits non-zero with
+`no tables in coldfront.partition_config`, naming the `register` and `import`
+commands that add one.
+
+In an `archiver.tables` entry, `source_schema` names the table's schema and
+defaults to `public`. `source_table` also accepts the `schema.table` form, and
+an explicit `source_schema` takes precedence over that prefix.
+`future_partitions` defaults to `3`, as `--premake` does on `register`.
 
 ## Storage Backends
 
-Configure **exactly one** cold-store backend:
-
-- **S3** - any S3-compatible store (SeaweedFS, MinIO). Set `endpoint`,
-  `use_ssl: true` for a TLS endpoint, and `url_style: path` (default) or
-  `vhost`.
-- **Virtual-hosted cloud S3** (AWS S3 is the canonical one) - **omit
-  `endpoint`** (and the `endpoint` arg to `set_storage_secret`) so DuckDB uses
-  the native per-Region virtual-hosted + HTTPS addressing; set `region` to your
-  bucket's Region. This is **required** for Regions launched after 2019-03-20
-  (e.g. `ap-south-2`), whose DNS does not route path-style requests and returns
-  HTTP 400. The Lakekeeper warehouse profile must be a virtual-hosted `s3`
-  profile (`flavor: aws`, `path-style-access: false`, no custom endpoint); the
-  full walkthrough is [object_store.md](object_store.md).
-- **Google Cloud Storage** - *not a separate backend*: use `s3:` pointed at
-  GCS's S3-interoperability endpoint with an
-  [HMAC key pair](https://cloud.google.com/storage/docs/authentication/hmackeys)
-  (`endpoint: storage.googleapis.com`, `use_ssl: true`,
-  `access_key`/`secret_key` = the HMAC id/secret). Lakekeeper's warehouse uses
-  an `s3` profile (`flavor: s3-compat`, `path-style`) at the same endpoint.
-  Verified end-to-end (iceberg read+write over interop). Lakekeeper's native
-  `gcs` profile is service-account only and is **not** used.
-- **Azure ADLS Gen2** - a supported cold-store backend; the access key rides
-  inside `connection_string`.
-
-For an **Azure ADLS Gen2** cold tier, set the credential with
-`set_storage_secret_azure()` instead of `set_storage_secret()` - it takes a
-CONFIG-provider connection string. The storage-account access key rides inside
-`AccountKey=…`; the DuckDB azure secret has no separate account-key parameter,
-so shared-key auth lives entirely in the connection string:
+Configure **exactly one** of the following cold-store backends.
+
+### S3
+
+The S3 backend works with any S3-compatible store (SeaweedFS, MinIO). Set
+`endpoint`, `use_ssl: true` for a TLS endpoint, and `url_style: path` (default)
+or `vhost`. `region` defaults to `us-east-1`.
+
+### Virtual-Hosted Cloud S3
+
+For virtual-hosted cloud S3 (AWS S3 is the canonical one), **omit `endpoint`**
+(and the `endpoint` arg to `set_storage_secret`) so DuckDB uses the native
+per-Region virtual-hosted + HTTPS addressing; set `region` to your bucket's
+Region. This is **required** for Regions launched after 2019-03-20 (e.g.
+`ap-south-2`), whose DNS does not route path-style requests and returns
+HTTP 400. The Lakekeeper warehouse profile must be a virtual-hosted `s3`
+profile (`flavor: aws`, `path-style-access: false`, no custom endpoint); the
+full walkthrough is [object_store.md](object_store.md).
+
+### Google Cloud Storage
+
+Google Cloud Storage is *not a separate backend*: use `s3:` pointed at GCS's
+S3-interoperability endpoint with an
+[HMAC key pair](https://cloud.google.com/storage/docs/authentication/hmackeys)
+(`endpoint: storage.googleapis.com`, `use_ssl: true`,
+`access_key`/`secret_key` = the HMAC id/secret). Lakekeeper's warehouse uses an
+`s3` profile (`flavor: s3-compat`, `path-style`) at the same endpoint. This
+setup is verified end-to-end (iceberg read+write over interop). Lakekeeper's
+native `gcs` profile is service-account only and is **not** used.
+
+### Azure ADLS Gen2
+
+Azure ADLS Gen2 is a supported cold-store backend; the access key rides inside
+`connection_string`. Set the credential with `set_storage_secret_azure()`
+instead of `set_storage_secret()` - it takes a CONFIG-provider connection
+string. The storage-account access key rides inside `AccountKey=…`; the DuckDB
+azure secret has no separate account-key parameter, so shared-key auth lives
+entirely in the connection string:
 
 ```sql
 SELECT coldfront.set_storage_secret_azure(
     'DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<key>;EndpointSuffix=core.windows.net');
 ```
 
-It writes the same `coldfront.storage_secret` row (replicated,
-`pg_dump`-excluded) and materializes a `TYPE azure` PERSISTENT SECRET. The
-Azure cold tier is subject to the soft-delete / change-feed restriction in
-[Caveats](index.md#caveats).
+`set_storage_secret_azure()` writes the same `coldfront.storage_secret` row
+(replicated, `pg_dump`-excluded) and materializes a `TYPE azure` PERSISTENT
+SECRET. The Azure cold tier is subject to the soft-delete / change-feed
+restriction in [Caveats](index.md#caveats).
 
 ## Vended Credentials
 
@@ -628,7 +752,7 @@ issues a short-lived, per-table credential (an S3 STS access key, secret, and
 session token) at read and write time, and ColdFront uses it directly. The
 long-term credential lives only in the Lakekeeper warehouse.
 
-Enable it with a single call that stores no credential:
+Enable vended credentials with a single call that stores no credential:
 
 ```sql
 SELECT coldfront.set_storage_secret_vended();
@@ -651,13 +775,15 @@ SELECT coldfront.set_storage_secret_vended('azure');
 
 Vending requires a Lakekeeper warehouse configured to vend credentials:
 
-- AWS S3: `flavor: aws` with `sts-enabled: true`, an `assume-role-arn` for a
-  bucket-scoped IAM role, and an `external-id` on the warehouse credential that
-  the role's trust policy also requires. The full warehouse and IAM-role setup
-  is in [object_store.md](object_store.md#3b-create-the-s3-warehouse).
-- Azure ADLS Gen2: an `adls` warehouse with `sas-enabled` (on by default).
-  Lakekeeper vends a per-container SAS token; the warehouse credential can be a
-  `shared-access-key`, `client-credentials`, or `azure-system-identity`.
+- On AWS S3, the warehouse uses `flavor: aws` with `sts-enabled: true`, an
+  `assume-role-arn` for a bucket-scoped IAM role, and an `external-id` on the
+  warehouse credential that the role's trust policy also requires. The full
+  warehouse and IAM-role setup is in
+  [object_store.md](object_store.md#3b-create-the-s3-warehouse).
+- On Azure ADLS Gen2, the warehouse is an `adls` warehouse with `sas-enabled`
+  (on by default). Lakekeeper vends a per-container SAS token; the warehouse
+  credential can be a `shared-access-key`, `client-credentials`, or
+  `azure-system-identity`.
 
 Google Cloud Storage over the S3-interoperability endpoint has no STS to issue
 short-lived credentials, so GCS stays on static HMAC credentials.
@@ -709,12 +835,14 @@ The following PostgreSQL column types are supported:
 `bigint` · `integer` · `smallint` · `real` · `double precision` · `boolean` ·
 `timestamp with time zone` · `timestamp without time zone` · `date` ·
 `time without time zone` · `uuid` · `text` · `varchar(N)` · `char(N)` · `bytea`
-· `numeric(P,S)` (P ≤ 38) · `jsonb` / `json` · `interval`
+· `numeric(P,S)` (P ≤ 38) · `jsonb` / `json` · `interval` · `vector(N)` /
+`halfvec(N)` (pgvector; see [usage_vectors.md](usage_vectors.md))
 
 Anything else (unbounded `numeric`, `xml`, `tsvector`, range/multirange types,
-custom enums, arrays, composite types) is rejected when a tiered table is
-registered, and when a decoupled table is created. We refuse silent fallback to
-`varchar` - losing precision/identity is worse than no support.
+custom enums, arrays, composite types, pgvector's `sparsevec`) is rejected when
+a tiered table is registered, and when a decoupled table is created. ColdFront
+refuses silent fallback to `varchar` - losing precision/identity is worse than
+no support.
 
 `char(N)` is stored and read as `varchar`. The data round-trips losslessly:
 values, comparisons, and `length()` match a hot PG table, where `length()`
@@ -725,7 +853,7 @@ blank-padded display matters.
 
 `json`, `jsonb` and `interval` are stored as `varchar` in Iceberg (no native
 primitive). On read, `interval` is view-cast back to the rich PG type; `json`
-and `jsonb` surface as DuckDB's `json` (the equivalent of PG's `jsonb`), not
+and `jsonb` come back as DuckDB's `json` (the equivalent of PG's `jsonb`), not
 the rich PG `jsonb` type, because Iceberg-backed reads run entirely in DuckDB.
 Queries like `data->>'key'` and `data->'key'` work, and ColdFront translates
 the `::jsonb` cast, `jsonb_array_length`, `jsonb_build_object` / `jsonb_agg`
@@ -759,7 +887,7 @@ A hot-only read is the exception. When a `SELECT` reads a tiered view directly
 (no join, CTE, or sub-query) and its `WHERE` provably restricts to the hot
 tier, ColdFront rewrites it to read the hot partition table in plain
 PostgreSQL: the full jsonb operator and function set works, and the query skips
-DuckDB entirely. Such a read surfaces `data` as native `jsonb` rather than the
+DuckDB entirely. Such a read returns `data` as native `jsonb` rather than the
 view's `json`. Reads that span tiers, are cold-only, or reach the view through
 a join or sub-query stay in DuckDB, where the limits above apply.
 
@@ -773,28 +901,31 @@ them; cast on the hot side only if needed).
 
 Keep the following caveats in mind when running either mode:
 
-- **`jsonb` reads**: surface as `json`. The `->`/`->>` operators work, and
+- `jsonb` reads come back as `json`. The `->`/`->>` operators work, and
   ColdFront translates the `::jsonb` cast, `jsonb_array_length`,
   `jsonb_build_object` / `jsonb_agg` and `date_bin`; other jsonb operators and
   functions are unsupported on cold or cross-tier reads. A hot-only read of the
   view runs in PostgreSQL with full jsonb (see
   [Supported Column Types](#supported-column-types)).
-- **Cross-tier isolation**: a long-running `SELECT` that touches the Iceberg
-  side multiple times within one transaction may see writes from other sessions
-  interleaved between scans. PG's repeatable-read does not extend across the
-  pg_duckdb boundary. Read-your-own-write *within* one tx works (verified) -
-  it's only cross-statement consistency vs. concurrent writers that's weaker.
-- **Crash-mid-commit (decoupled mode)**: if a backend crashes between Iceberg
-  snapshot commit and PG commit, S3 objects can be orphaned. Iceberg
-  housekeeping reclaims them - not corrupting, but a real failure mode.
-- **Concurrent writes from multiple PG nodes (decoupled mode)**: serialized
-  PG-side by the bakery protocol - every iceberg-only INSERT goes through
+- Cross-tier isolation differs from PG-native isolation. The cold tier keeps
+  one Iceberg snapshot for the whole transaction, even at READ COMMITTED, so a
+  commit by another session after the transaction's first cold read stays
+  invisible until the transaction ends. The hot tier follows PostgreSQL's own
+  isolation level, so at READ COMMITTED a later statement can see new hot rows
+  but not new cold ones. Read-your-own-write *within* one transaction works.
+- In decoupled mode, pg_duckdb commits the Iceberg snapshot at PRE_COMMIT, so a
+  backend crash after that but before the PG commit record leaves the Iceberg
+  write committed and the PG side lost. A crash after the Parquet upload but
+  before the commit POST leaves unreferenced objects, which the compactor's
+  orphan pass reclaims.
+- In decoupled mode, concurrent writes from multiple PG nodes are serialized
+  PG-side by the bakery protocol: every iceberg-only INSERT goes through
   `coldfront._exec_iceberg_with_claim`, which holds a globally-ordered
-  Snowflake ticket and waits for its turn before committing to Lakekeeper. No
-  409 conflicts, no app-level retry. The protocol is Lamport-1978 mutex with
-  the Ricart-Agrawala (1981) deferred-reply optimization; claims and acks
-  replicate as Spock rows and it stays safe under Spock's asymmetric apply
-  (modeled in
+  Snowflake ticket and waits for its turn before committing to Lakekeeper.
+  There are no 409 conflicts and no app-level retries. The protocol is
+  Lamport-1978 mutex with the Ricart-Agrawala (1981) deferred-reply
+  optimization; claims and acks replicate as Spock rows and it stays safe under
+  Spock's asymmetric apply (modeled in
   [docs/formal/Bakery.tla](https://github.com/pgEdge/ColdFront/blob/main/docs/formal/Bakery.tla)).
   The bakery requires the `snowflake` extension, the `coldfront.dblink_self`
   GUC (the connection string of the node's loopback), and a one-time
@@ -803,19 +934,22 @@ Keep the following caveats in mind when running either mode:
   [architecture_decoupled.md](architecture_decoupled.md#concurrency-horizontal-scaling-the-bakery-protocol).
   Sync-rep is **not** required. The throughput ceiling is Lakekeeper's commit
   rate, not the writer count.
-- **Direct table access**: `_events` is the hot heap (tiered mode only).
+- For direct table access, `_events` is the hot heap (tiered mode only).
   `ice.public.<name>` is the Iceberg table - only addressable via
   `iceberg_scan(...)` or `duckdb.raw_query('… ice.… …')`, never via PG-native
   3-part names.
-- **Tiered INSERT with omitted IDENTITY column** (e.g.
+- When a tiered INSERT omits an IDENTITY column (e.g.
   `INSERT INTO events (ts, status, data) VALUES …` where `id` is
-  `GENERATED ALWAYS AS IDENTITY`): the cold side falls back to a plpgsql cursor
+  `GENERATED ALWAYS AS IDENTITY`), the cold side falls back to a plpgsql cursor
   loop that calls `nextval()` per row so cold ids share the hot side's
   sequence. Correctness is full; throughput is lower than the set-based fast
   path. Either supply `id` explicitly in the INSERT, or use a partition-column
   predicate that proves the rows are all hot, to stay on the fast path. For
   very large historical seeds (mostly-cold), prefer iceberg-only mode where ids
   come from your source data.
+- `TRUNCATE` on a registered relation, or on the hot table behind a tiered one,
+  fails with an error, because the cold rows in Iceberg would stay visible
+  through the view.
 
 ## Distributed Setup (3-Node Mesh, Decoupled Mode)
 
@@ -847,10 +981,9 @@ spock.include_ddl_repset = on
 # without the setting refuses to start with this line in place.
 output_plugin_libraries = 'pgoutput, test_decoding, spock_output'
 
-# Keep pg_stat_replication.reply_time fresh on every walsender.  PG
-# default is 10 s; with the bakery's 5 s liveness window that would
-# false-positive every idle peer as "dead" on the first claim after a
-# quiet period.  1 s leaves comfortable margin.
+# Spock's apply worker does not read this setting: on an idle link,
+# pg_stat_replication.reply_time refreshes only on the walsender's
+# reply-requested keepalive, every wal_sender_timeout/2 (30 s by default).
 wal_receiver_status_interval = 1s
 
 # Per-node - any distinct integer 1..1023 (must be unique per node; the value
@@ -867,6 +1000,12 @@ coldfront.dblink_self = 'host=/tmp dbname=coldfront user=coldfront application_n
 
 coldfront.warehouse = 'wh'
 coldfront.lakekeeper_endpoint = 'http://lakekeeper:8181/catalog'
+
+# Upload the Parquet outside the bakery claim and serialize only the catalog
+# commit. Set both, and only where duckdb-iceberg includes ColdFront's patch (the
+# ColdFront image does). With either off, the upload is serialized too.
+coldfront.iceberg_async_parquet = on
+coldfront.iceberg_bakery_patch = on
 ```
 
 The bakery has no peer-ack timeout. R-A's only failure mode is a dead peer
@@ -874,7 +1013,7 @@ The bakery has no peer-ack timeout. R-A's only failure mode is a dead peer
 whose `pg_stat_replication.reply_time` is older than
 `coldfront.peer_alive_window_ms` (default `5000`) is implicitly treated as
 already-acked. Raise this on slow/lossy WAN links if false-positive dead-peer
-rulings become a problem. An alive peer that hasn't acked is either deferring
+rulings become a problem. An alive peer that has not acked is either deferring
 legitimately (R-A's defer rule) or about to ack - either way, waiting is
 correct, not a failure.
 
@@ -887,11 +1026,11 @@ nothing waits. See [architecture_decoupled.md](architecture_decoupled.md),
 *Orphan reaping*.
 
 Sync-rep (`synchronous_standby_names`) is **not required** by the bakery - the
-R-A ack barrier is what serializes iceberg commits. You can still enable it
-cluster-wide if you want stronger durability for non-bakery writes, but it
-plays no part in iceberg-commit serialization.
+R-A ack barrier is what serializes iceberg commits. You can still enable
+sync-rep cluster-wide if you want stronger durability for non-bakery writes,
+but it plays no part in iceberg-commit serialization.
 
-One-time mesh setup - must be done in this order on every node, because
+The one-time mesh setup must be done in this order on every node, because
 `coldfront._ensure_claims_replicated()` calls `spock.repset_add_table` and so
 requires the local Spock node to already exist:
 
@@ -903,7 +1042,11 @@ CREATE EXTENSION IF NOT EXISTS spock;
 CREATE EXTENSION IF NOT EXISTS pg_duckdb;
 CREATE EXTENSION IF NOT EXISTS coldfront;
 
--- 2. Spock node + full-mesh subscriptions (each node has N-1 subs).
+-- 2. Spock node + full-mesh subscriptions (each node has N-1 subs). Name each
+-- subscription sub_<subscriber>_from_<provider> (on n1: sub_n1_from_n2): the
+-- bakery's peer-liveness check looks the walsender up by that name, and a peer
+-- whose subscription is named any other way counts as dead and is treated as
+-- already acked.
 SELECT spock.node_create('n<i>', 'host=<this_node_priv_ip> user=coldfront dbname=coldfront port=5432');
 
 -- on n1 (n2 and n3 symmetric):
@@ -934,8 +1077,10 @@ SELECT spock.repset_add_table('default', 'coldfront.tiered_views'::regclass, fal
 SELECT spock.repset_add_table('default', 'coldfront.archive_watermark'::regclass, false);
 ```
 
-`synchronize_structure := false, synchronize_data := false` - tables already
-exist on every node from the coldfront extension; no initial copy needed.
+The subscriptions set
+`synchronize_structure := false, synchronize_data := false` because the tables
+already exist on every node from the coldfront extension, so no initial copy is
+needed.
 
 Verify before benching - insert a sentinel claim on each node and read it back
 from every other node. All N×(N-1) directions must show the row before traffic
@@ -945,34 +1090,45 @@ starts. `ci/journey.sh` `story_mesh_substrate` is a copyable reference.
 
 The following GUCs adjust write behavior and execution; tune them as needed:
 
-- `coldfront.allow_mixed_writes` (bool, default `on`) - controls what happens
-  for tiered-mode UPDATE/DELETE whose WHERE can't be proven to target one tier.
-  `on` emits a dual-tier CTE; `off` rejects with an error and a hint. Not
-  relevant in decoupled mode (every write is single-tier by definition).
-- `coldfront.vector_probe` (bool, default `on`) - whether a recognized
+- `coldfront.allow_mixed_writes` (bool, default `on`) controls what happens for
+  tiered-mode UPDATE/DELETE whose WHERE cannot be proven to target one tier.
+  `on` emits a dual-tier CTE; `off` rejects with an error and a hint. The
+  setting is not relevant in decoupled mode (every write is single-tier by
+  definition).
+- `coldfront.cold_write_batch_size` (int, default `10000`, minimum `1`) sets
+  how many rows the IDENTITY cursor loop (see [Caveats](#caveats)) gathers
+  before it writes them to Iceberg as one append. A larger value writes fewer,
+  larger Parquet files, and the remainder always flushes, so a small write
+  stays one file.
+- `coldfront.vector_probe` (bool, default `on`) sets whether a recognized
   similarity search reads only the clusters nearest its query vector. `off`
-  gives an exact scan of the whole corpus. Only affects a table with a trained
-  vector column ([usage_vectors.md](usage_vectors.md)).
-- `coldfront.vector_nprobe` (int, default `0`) - clusters such a search reads,
-  overriding the column's own `nprobe`. `0` uses the configured value; at or
-  above the column's `nlist` the search is exhaustive.
-- `duckdb.force_execution` - bench it before flipping: on a mixed workload it
-  helps `count(distinct)` and similar but regresses index lookups, top-K with
-  PK ordering, and JSON access. **Default off.**
-- `duckdb.temporary_directory` - where DuckDB spills. Each backend gets its own
-  subdirectory of it, named after its process id, so concurrent spills cannot
-  collide; one left by a departed backend is reclaimed. See
+  gives an exact scan of the whole corpus. The setting affects only a table
+  with a trained vector column ([usage_vectors.md](usage_vectors.md)).
+- `coldfront.vector_nprobe` (int, default `0`) sets how many clusters such a
+  search reads, overriding the column's own `nprobe`. `0` uses the configured
+  value; at or above the column's `nlist` the search is exhaustive.
+- `duckdb.force_execution` (default off) should be benchmarked before you turn
+  it on: on a mixed workload it helps `count(distinct)` and similar but
+  regresses index lookups, top-K with PK ordering, and JSON access.
+- `duckdb.temporary_directory` sets where DuckDB spills. Each backend gets its
+  own subdirectory there, named after its process id, so concurrent spills
+  cannot collide; one left by a departed backend is reclaimed. See
   [architecture.md](architecture.md#duckdb-spill-files-are-not-namespaced-per-instance).
-- `duckdb.max_temp_directory_size` - a cap **per connection**, not a cluster
-  total, and unset it is 90% of free space per session. For a total budget,
-  divide it by the concurrent sessions or give the temp path its own filesystem
-  or quota.
-
-## Going Deeper
-
-For deeper detail on each mode's internals, see the architecture references:
-
-- Tiered architecture, watermark, archiver, transparent UPDATE/DELETE,
-  concurrency: [architecture.md](architecture.md).
-- Decoupled mode internals, ACID model, distributed scaling:
-  [architecture_decoupled.md](architecture_decoupled.md).
+- `duckdb.max_temp_directory_size` is a cap **per connection**, not a cluster
+  total, and when unset the cap is 90% of free space per session. For a total
+  budget, divide it by the concurrent sessions or give the temp path its own
+  filesystem or quota.
+
+## Next Steps
+
+To go further with ColdFront, consult the following guides:
+
+- The [Architecture](architecture.md) overview describes the tiered
+  architecture, the watermark, the archiver, transparent UPDATE/DELETE, and
+  concurrency.
+- The [Decoupled Mode](architecture_decoupled.md) deep dive describes
+  decoupled-mode internals, the ACID model, and distributed scaling.
+- The [Embeddings](usage_vectors.md) guide covers storing and searching
+  embeddings through the pgvector interface.
+- The [Compaction](compaction.md) guide covers cold-tier maintenance:
+  compaction, snapshot expiry, and orphan-file removal.
diff --git a/docs/usage_vectors.md b/docs/usage_vectors.md
index 3634c1f..d36b308 100644
--- a/docs/usage_vectors.md
+++ b/docs/usage_vectors.md
@@ -7,18 +7,19 @@ lives entirely in Iceberg.
 
 ## Creating a Table
 
-Tiered, through the archiver's normal configuration:
+Create a tiered table through the archiver's normal configuration:
 
 ```sql
 CREATE TABLE chunks (
     id        bigserial,
     ts        timestamptz NOT NULL,
     body      text,
-    embedding vector(1536)
+    embedding vector(1536),
+    PRIMARY KEY (id, ts)
 ) PARTITION BY RANGE (ts);
 ```
 
-Decoupled, declared in one call:
+Declare a decoupled table in one call:
 
 ```sql
 SELECT coldfront.create_iceberg_table('public', 'chunks', '[
@@ -29,11 +30,25 @@ SELECT coldfront.create_iceberg_table('public', 'chunks', '[
 ```
 
 pgvector is installed for you the first time a table declares a vector column.
-You do not need it in a database that has none.
+You do not need pgvector in a database that has none.
+
+A table that already exists in the catalog can be adopted instead, through
+`coldfront.adopt_iceberg_table()` (see
+[Adopting a Table That Already Exists in the Catalog](usage.md#adopting-a-table-that-already-exists-in-the-catalog)).
+Adoption registers a clustered vector column for each Iceberg column named
+`_cf_vec_list_<column>`, which is where ColdFront keeps each row's cluster. No
+`coldfront.vector_config` row and no centroids come back with an adopted
+column, so its searches stay exact until you record its settings and train it
+(see [Clustering](#clustering)).
+
+Releasing or dropping a table deletes its `vector_config` and
+`vector_centroids` rows. A table registered again under the same name, such as
+one released and adopted again, needs a new configuration row and a first
+training from fresh centroids.
 
 ## Writing
 
-Ordinary pgvector syntax, on either tier:
+Writes use ordinary pgvector syntax, on either tier:
 
 ```sql
 INSERT INTO chunks (ts, body, embedding)
@@ -48,7 +63,7 @@ in the same statement as the write.
 ## Reading and Searching
 
 The view exposes the column as `real[]`, which is the same type Iceberg stores.
-Read it like any column:
+Read the column like any other:
 
 ```sql
 SELECT id, body, embedding FROM chunks WHERE id = 42;
@@ -64,9 +79,12 @@ SELECT id, body
  LIMIT 10;
 ```
 
-All three pgvector operators are available: `<=>` cosine, `<->` Euclidean,
-`<#>` negative inner product. Use `<=>` unless you have a reason not to;
-clustering is built on cosine.
+`<=>` (cosine) and `<->` (Euclidean) work on both tiers. `<#>` (negative inner
+product) works only while a query runs entirely in PostgreSQL: DuckDB has no
+`<#>` operator, so any query that reads the cold tier fails with a parser
+error. Write `list_negative_inner_product(embedding, ARRAY[…]::real[])`
+instead. Use `<=>` unless you have a reason not to; clustering is built on
+cosine.
 
 ### Three Rules for the Query Vector
 
@@ -83,8 +101,8 @@ are fine, so only the vector itself has to be inlined:
 … ORDER BY embedding <=> $1 LIMIT 10;
 ```
 
-**Spell it `ARRAY[…]::real[]`.** The `'{0.1,0.2}'::real[]` form reaches the
-cold tier as text and fails to cast.
+**Spell the query vector `ARRAY[…]::real[]`.** The `'{0.1,0.2}'::real[]` form
+reaches the cold tier as text and fails to cast.
 
 **Do not cast the column.** `embedding <=> ARRAY[…]::real[]` resolves;
 `embedding::vector <=> …` fails with `Type with name vector does not exist!`.
@@ -92,8 +110,8 @@ Your own `'[…]'::vector` literal on the right-hand side is fine.
 
 ## Clustering
 
-Clustering is optional. Without it, a search is an exact scan of both tiers,
-which is correct and needs no configuration.
+Clustering is optional. Without clustering, a search is an exact scan of both
+tiers, which is correct and needs no configuration.
 
 To prepare a column for clustering, record its settings and train a centroid
 set:
@@ -106,25 +124,57 @@ VALUES ('public', 'chunks', 'embedding', 500, 20);
 CALL coldfront.vector_train('public', 'chunks', 'embedding');
 ```
 
-`CALL`, not `SELECT`: this is a procedure. It samples the cold tier, trains
-`nlist` centroids, stores them as a new generation, and assigns every cold row
-to its nearest centroid, rewriting the rows whose cluster changed. After
-`vector_train` runs, every cold write assigns the row to a cluster in the same
-statement, on every write path.
+The `vector_config` row has no default for `nlist` or `nprobe`, so the INSERT
+names both. Check constraints require `nlist` to be at least 1 and `nprobe` to
+lie between 1 and `nlist`. `schema_name` defaults to `'public'`, and
+`generation` and `addition_cap` default to `0`. `vector_train` maintains
+`generation`, and `addition_cap` is reserved. When training produces fewer
+centroids than `nprobe`, it lowers `nprobe` to the trained count.
+
+Run `vector_train` with `CALL`, not `SELECT`: this is a procedure. The
+procedure samples the cold tier, trains up to `nlist` centroids (recording the
+count actually trained as the column's `nlist`), stores them as a new
+generation, and assigns every cold row to its nearest centroid, rewriting the
+rows whose cluster changed. After `vector_train` runs, every cold write assigns
+the row to a cluster in the same statement, on every write path.
 
 Compact afterwards. The assignment leaves a delete marker per rewritten row and
 those rows in rewrite order; compaction is what puts them in cluster order and
-clears the markers. Without it the rows are assigned but a search still reads
-more of the table than it needs to.
+clears the markers. Without compaction the rows are assigned but a search still
+reads more of the table than it needs to.
+
+The following table describes the parameters of `vector_train`:
+
+| Parameter | Default | Description |
+|---|---|---|
+| `p_schema` | required | The parameter names the schema that holds the registered table. |
+| `p_table` | required | The parameter names the registered table. |
+| `p_column` | required | The parameter names the vector column to train. |
+| `p_nlist` | the configured `nlist` | The parameter sets the number of centroids to train. |
+| `p_sample` | `20000` | The parameter sets how many cold rows with a non-null vector training samples. |
+| `p_iterations` | `8` | The parameter sets how many k-means iterations run over the sample. |
+
+`vector_train` stops with an error in each of the following cases:
+
+- The server is a read-only standby, so training must run on the primary.
+- The table is not registered with ColdFront, and the error reports that it
+  `is not a registered tiered table`.
+- The table was adopted read-only. Training rewrites the cold rows, so release
+  the table and adopt it again with `p_writable => true`.
+- The column has no `coldfront.vector_config` row. Passing `p_nlist` does not
+  replace that row, because it holds the generation pointer training writes.
+- The cold tier holds no row with a non-null vector, and the error reports that
+  the column `has no cold rows to train on`. Training samples only the cold
+  tier, so the hot rows of a tiered table do not count.
 
 ### Retraining
 
 Call `vector_train` again when the data has grown or you want a different
 `nlist`. Without `p_nlist`, the new centroids start from the current ones and
 keep their identities, so only the rows whose nearest centroid changed are
-rewritten; with a new `nlist`, every row is. Either way the centroids and the
-assignments change together, so a search is never wrong in between; it is only
-slower until the next compaction.
+rewritten; with a new `nlist`, nearly every row is. Either way the centroids
+and the assignments change together, so a search is never wrong in between; it
+is only slower until the next compaction.
 
 ### Time Partitioning
 
@@ -132,14 +182,15 @@ A tiered vector table is partitioned by time, because its hot table is; a
 decoupled one only if it was created with time partitioning
 (`p_partition_cols`). On such a table a search with a time filter skips the
 months outside it, and a search over all of history reads one row group of each
-probed cluster per month rather than one, roughly the number of months more
-data. A decoupled vector table created without time partitioning is unaffected.
+probed cluster per partition (per month or per day, and per list value on a
+two-level table) rather than one, roughly the number of partitions more data. A
+decoupled vector table created without time partitioning is unaffected.
 
 ### Choosing `nlist`
 
 Choosing `nlist` is a floor rather than a formula: aim for at least one row
 group's worth of rows per cluster, roughly 2048. Below that, extra clusters
-stop reducing the data read. Above it there is a wide plateau.
+stop reducing the data read. Above that floor there is a wide plateau.
 
 ### Choosing `nprobe`
 
@@ -150,10 +201,10 @@ against the exact answer for 100 queries:
 
 | `nprobe` | clusters read | recall | median query |
 |---|---|---|---|
-| 1 | 0.1% | 57% | 49 ms |
-| 10 | 1% | 87% | 307 ms |
-| 20 | 2% | 93% | 592 ms |
-| 50 | 5% | 97% | 1.9 s |
+| 1 | 0.1% | 56.9% | 49 ms |
+| 10 | 1% | 86.8% | 307 ms |
+| 20 | 2% | 93.2% | 592 ms |
+| 50 | 5% | 96.7% | 1.9 s |
 | 100 | 10% | 98.5% | 5.1 s |
 
 The same queries scanned exactly take 32 s each, so `nprobe` 20 is roughly 54
@@ -162,8 +213,8 @@ times faster for 93% of the exact answer.
 **Start at 2% of `nlist`.** Recall gets rapidly more expensive as you buy more
 of it: on that corpus the first 23 points of recall cost 111 ms, and the last
 1.8 points cost 3.2 s. The rate worsens from 5 ms per recall point to 1776, and
-the knee is at 2% of the clusters. Above it you are paying several hundred
-milliseconds per point.
+the knee is at 2% of the clusters. Above the knee you are paying several
+hundred milliseconds per point.
 
 That also fixes `nlist`, given the row-group floor above. **Aim for `nlist` ≈
 rows / 10,000**, which leaves a few row groups per cluster: 1000 clusters for
@@ -171,7 +222,7 @@ rows / 10,000**, which leaves a few row groups per cluster: 1000 clusters for
 latency without buying anything, because a cluster read pulls a whole row group
 either way.
 
-Two things the averages hide. **Recall is an average over queries, and the tail
+The averages hide two things. **Recall is an average over queries, and the tail
 is worse**: at `nprobe` 20 the worst of those 100 queries returned 4 of its
 true 10. If every query matters, measure the worst case rather than the mean.
 **A more finely divided index is not automatically better**: `nlist` 4999
@@ -186,7 +237,9 @@ your own against a sample of queries you have exact answers for.
 
 Once a column has a trained generation, a search that ends in
 `ORDER BY <column> <=> <vector> LIMIT n` reads only the `nprobe` clusters
-nearest your query vector. The query you write does not change. The result
+nearest your query vector. The function-call form,
+`ORDER BY list_cosine_distance(<column>, <vector>) LIMIT n`, is the same search
+and is narrowed the same way. The query you write does not change. The result
 becomes approximate, in the same way it does with any vector index: raise
 `nprobe` for recall, lower it for speed.
 
@@ -198,11 +251,11 @@ form of one statement: wrapping the search in a subquery makes the whole thing
 exact.
 
 Anything that is not that shape stays an exact scan of both tiers, which is
-correct. Two cases worth knowing: a search with no `LIMIT` is answered exactly,
-because asking for every row in order is not a request to approximate; and so
-is one wrapped in a subquery or CTE, because the clustering is applied to the
-statement you write rather than to a nested part of it. The following two
-statements show the difference:
+correct. Two cases are worth knowing: a search with no `LIMIT` is answered
+exactly, because asking for every row in order is not a request to approximate;
+and so is one wrapped in a subquery or CTE, because the clustering is applied
+to the statement you write rather than to a nested part of it. The following
+two statements show the difference:
 
 ```sql
 -- narrowed to the nearest clusters
@@ -212,11 +265,12 @@ SELECT string_agg(body, ',') FROM (
   SELECT body FROM chunks ORDER BY embedding <=> ARRAY[…]::real[] LIMIT 10) t;
 ```
 
-Rows written before the column was trained have no cluster, and they are
-returned by every search regardless of which clusters it reads. So is every
-hot-tier row. A row written before training never goes missing on that account.
+Rows with no cluster, such as rows another engine appended straight to Iceberg,
+are returned by every search regardless of which clusters it reads. So is every
+hot-tier row. Training assigns every cold row written before it, and an
+unassigned row never goes missing on that account.
 
-Two settings, per session:
+Two settings change this behavior per session:
 
 ```sql
 -- read every cluster: exact, and the reference to compare recall against
@@ -228,7 +282,7 @@ SET coldfront.vector_probe = off;
 Leave `coldfront.vector_nprobe` at its default of `0` to use the `nprobe` you
 recorded for the column.
 
-### Checking Whether the Clustering Is Earning Its Keep
+### Checking Whether the Clustering Is Worth Having
 
 Call `vector_status` and query its results table:
 
@@ -246,18 +300,48 @@ means and what to do:
 
 | What it says | What to do |
 |---|---|
-| no trained generation | `CALL coldfront.vector_train(...)` |
-| over half the rows have no assignment | rows another engine appended straight to Iceberg carry none; `CALL coldfront.vector_train(...)` assigns them, then compact |
-| over half the clusters hold less than one row group | retrain with a smaller `nlist` |
-| the largest clusters hold over 4x the median | expect some queries to be slower than `probe_fraction` suggests; uneven clusters are mostly a property of the embeddings and a retrain rarely changes it |
-
-Pass a schema and table to report on one column:
-`CALL coldfront.vector_status('public', 'chunks')`. The results land in a
-temporary table that lasts for your session, and each call replaces the last.
+| no trained generation | Run `CALL coldfront.vector_train(...)`. |
+| over half the rows have no assignment | Rows another engine appended straight to Iceberg have no assignment. Run `CALL coldfront.vector_train(...)` to assign them, then compact. |
+| over half the occupied clusters hold less than one row group | Retrain with a smaller `nlist`. |
+| the largest clusters hold over 4x the median | Expect some queries to be slower than `probe_fraction` suggests. Uneven clusters are mostly a property of the embeddings, and a retrain rarely changes that. |
+
+Pass a schema and table to report on one table:
+`CALL coldfront.vector_status('public', 'chunks')`. Pass the schema alone,
+`CALL coldfront.vector_status('public')`, to report on every clustered table in
+that schema. The results land in a temporary table that lasts for your session,
+and each call replaces the last. When no table with a clustered vector column
+matches the arguments, `cf_vector_status` is empty and the call raises the
+notice `coldfront: no registered table has a clustered vector column`.
+
+The following table describes the columns of `cf_vector_status`, one row per
+clustered vector column:
+
+| Column | Description |
+|---|---|
+| `schema_name` | The column holds the schema of the registered table. |
+| `table_name` | The column holds the name of the registered table. |
+| `column_name` | The column holds the name of the clustered vector column. |
+| `prunes` | The value is true for the vector column that owns the physical sort order (see [More than One Vector Column](#more-than-one-vector-column)). |
+| `generation` | The column holds the live centroid generation, or NULL when nothing has been trained. |
+| `nlist` | The column holds the configured `nlist`, or NULL when the column has no `vector_config` row. |
+| `nprobe` | The column holds the configured `nprobe`, or NULL when the column has no `vector_config` row. |
+| `clusters_trained` | The column counts the centroids in the live generation. |
+| `clusters_occupied` | The column counts the clusters that hold at least one cold row. |
+| `additions` | The column counts the centroids in the live generation that have a `parent_id`; ColdFront sets none, so the value is 0. |
+| `addition_cap` | The column holds the configured `addition_cap`, which is reserved. |
+| `rows_total` | The column counts the rows in the cold tier. |
+| `rows_unassigned` | The column counts the cold rows with no cluster, which every search reads. |
+| `rows_per_cluster_min` | The column holds the fewest cold rows in any occupied cluster. |
+| `rows_per_cluster_max` | The column holds the most cold rows in any occupied cluster. |
+| `rows_per_cluster_p50` | The column holds the median number of cold rows per occupied cluster. |
+| `rows_per_cluster_p99` | The column holds the 99th percentile of cold rows per occupied cluster. |
+| `clusters_below_row_group` | The column counts the occupied clusters that hold fewer than 2,048 rows, which is one row group. |
+| `probe_fraction` | The column holds the average share of the cold rows a search reads, including every unassigned row. |
+| `advice` | The column names the first condition holding `probe_fraction` up, or is NULL when none does. |
 
 ## More than One Vector Column
 
-A table may carry as many vector columns as you like. Each gets its own
+A table may have as many vector columns as you like. Each gets its own
 configuration, its own centroids and its own generation, and each is assigned
 on every write path:
 
@@ -269,12 +353,12 @@ CALL coldfront.vector_train('public', 'docs', 'body_embedding');
 CALL coldfront.vector_train('public', 'docs', 'title_embedding');
 ```
 
-**Only the first vector column's searches get the full speedup.** Not a policy
-choice: a Parquet file has one physical row order, and the clustering works by
-putting a cluster's rows next to each other so the reader can skip whole row
-groups. The first column in table order gets that order. A second column's
-clusters are scattered through it, so its row-group statistics cover most of
-the file and nothing gets skipped.
+**Only the first vector column's searches get the full speedup.** This is not a
+policy choice: a Parquet file has one physical row order, and the clustering
+works by putting a cluster's rows next to each other so the reader can skip
+whole row groups. The first column in table order gets that order. A second
+column's clusters are scattered through it, so its row-group statistics cover
+most of the file and nothing gets skipped.
 
 What a later column still gets is the filter. Its predicate cuts the rows that
 have to be *scored*, but not the rows that have to be *read*, and reading is
@@ -292,21 +376,23 @@ SELECT table_name, column_name, prunes, probe_fraction FROM cf_vector_status;
 
 If a second vector column needs to be fast, the honest answer is a second table
 holding that column and a key, ordered by its own clustering. That is what a
-secondary index is, and Iceberg gives us no way to have two orders in one file.
+secondary index is, and Iceberg offers no way to have two orders in one file.
 
 ## What a Clustered Table Needs from the Deployment
 
 The assignment lookup reads the centroid tables through a local connection, so
-`coldfront.local_pg_dsn` must be set. The shipped container image sets it. On
-bare metal, add it to `postgresql.conf`:
+`coldfront.local_pg_dsn` must be set. The shipped container image sets that
+parameter. On bare metal, add the setting to `postgresql.conf`:
 
 ```ini
 
 coldfront.local_pg_dsn = 'host=/var/run/postgresql dbname=<db> user=<role>'
 ```
 
-Without it, a cold write to a clustered table fails with
-`Catalog 'pglocal' does not exist` rather than writing an unassigned row.
+Without that setting, a cold write to a clustered table fails with
+`Catalog "pglocal" does not exist!` rather than writing an unassigned row. A
+retrain at the same `nlist` reads the live centroids through the same
+connection, so it fails with the same error.
 
 ## Compaction
 
@@ -314,12 +400,12 @@ Compaction stays mandatory on these tables, as it is on any ColdFront table:
 every small write makes a file and query cost grows with file count. Run the
 compactor as you already do.
 
-On a clustered table it does more than consolidate. Each write leaves a file
-sorted within itself, and a search has to look in every one of them; compaction
-merges them on the sort column, one ordered run per size-bounded merge group,
-so the number of places a search looks is set by data volume rather than by
-write count. Nothing to configure: the table records its own sort column at
-creation and the compactor reads it.
+On a clustered table, compaction does more than consolidate. Each batch write
+leaves a file sorted within itself, and a search has to look in every one of
+them; compaction merges them on the sort column, one ordered run per
+size-bounded merge group, so the number of places a search looks is set by data
+volume rather than by write count. There is nothing to configure: the table
+records its own sort column at creation and the compactor reads it.
 
 ## Limits Worth Knowing
 
@@ -337,3 +423,14 @@ The following limits apply to vector columns:
 - A hot row stores its embedding twice, once as `vector` and once in a
   generated `real[]` column that the cold reader can scan. Cold rows, which are
   the bulk of the data, store it once.
+
+## Next Steps
+
+To go further with ColdFront, consult the following documents:
+
+- The [Vector Storage](architecture_vectors.md) deep dive describes the routing
+  state, cluster assignment, and probe rewrite behind this guide.
+- The [Compaction](compaction.md) guide covers the maintenance that keeps
+  clustered tables in cluster order.
+- The [Using ColdFront](usage.md) guide covers the table setup both modes
+  share.
diff --git a/docs/walkthrough.md b/docs/walkthrough.md
index 692a622..ce92c54 100644
--- a/docs/walkthrough.md
+++ b/docs/walkthrough.md
@@ -3,7 +3,7 @@ cwd: ../
 ---
 # ColdFront Guided Walkthrough
 
-New here? Run the guided walkthrough.
+If you are new to ColdFront, run the guided walkthrough.
 
 The walkthrough is a self-contained, step-by-step tour of ColdFront's three
 operating modes - tiered storage (hot PostgreSQL + cold Iceberg), decoupled
@@ -12,9 +12,9 @@ distributed demo that runs two nodes over one shared lake. Every command on
 this page is real: click it to run in Codespaces, or copy it into a local
 shell.
 
-> **Pre-release beta software** - ColdFront is pre-release beta software under
-> active development. Do not use it in production. Interfaces, on-disk formats,
-> and behavior may change without notice, and data loss is possible.
+> **Beta software** - ColdFront is beta software under active development. Do
+> not use it in production. Interfaces, on-disk formats, and behavior may
+> change without notice, and data loss is possible.
 
 ## ▶ In GitHub Codespaces
 
@@ -25,8 +25,8 @@ that turns each code block below into a runnable cell. Click **Run** on each
 cell as you read. The first cell builds the Docker images (two to five
 minutes); everything after it is quick.
 
-Prefer a terminal? `bash examples/walkthrough/guide.sh` runs the same demos as
-an interactive guide.
+If you prefer a terminal, `bash examples/walkthrough/guide.sh` runs the same
+demos as an interactive guide.
 
 ## 💻 On Your Own Machine
 
@@ -45,6 +45,13 @@ curl -fsSL \
   | bash
 ```
 
+The installer writes the files to a `coldfront-walkthrough` directory under the
+current directory, and downloads them from the `main` branch. Set
+`WALKTHROUGH_DIR` to choose another directory, or `WALKTHROUGH_BRANCH` to
+download the files and build sources from another branch. Both variables must
+reach `bash`, so set them after the pipe, as in
+`| WALKTHROUGH_DIR=cf-demo bash`.
+
 If you already have the repository cloned, run the guide directly:
 
 ```bash {"ignore":"true"}
@@ -56,6 +63,11 @@ stack, and walks through each demo interactively. This page and the
 [demos](walkthrough_demos.md) cover the same steps - run them from the doc or
 paste them into your shell.
 
+The guide prints each demo command and query before it runs it. To have the
+guide type each one a character at a time, as in a recording, set
+`WALKTHROUGH_TYPE_DELAY` to the delay in seconds between characters (for
+example, `0.03`). The default of `0` prints each command at once.
+
 ## What Setup Does
 
 Setup runs before the demos begin. Setup starts the containers, waits for
@@ -137,8 +149,10 @@ curl -sf -X POST \
 ### Using a Cloud Object Store
 
 The walkthrough hero path uses SeaweedFS. To use a cloud store instead, replace
-the warehouse JSON above and the `set_storage_secret` call in Step 5 of
-[Demo 1](walkthrough_demos.md#demo-1-tiered-storage).
+the warehouse JSON above, the `set_storage_secret` call in Step 5 of
+[Demo 1](walkthrough_demos.md#demo-1-tiered-storage), and the `s3:` block in
+`examples/walkthrough/config/archiver.yaml`, which the archiver uses for its
+own connection to the store.
 
 The following table shows the `set_storage_secret` signature for each supported
 store:
@@ -148,10 +162,11 @@ store:
 | SeaweedFS (local) | `SELECT coldfront.set_storage_secret('admin', 'adminsecret', 'seaweedfs:8333');` |
 | AWS S3 | `SELECT coldfront.set_storage_secret('key-id', 'secret-key', null, 'ap-south-2');` |
 | GCS (HMAC) | `SELECT coldfront.set_storage_secret(p_key_id => '<hmac-key>', p_secret => '<hmac-secret>', p_endpoint => 'storage.googleapis.com', p_region => 'us-east-1', p_url_style => 'path', p_use_ssl => true);` |
-| Azure Blob | `SELECT coldfront.set_storage_secret_azure('AccountName=<account>;AccountKey=<key>;EndpointSuffix=core.windows.net');` |
+| Azure ADLS Gen2 | `SELECT coldfront.set_storage_secret_azure('AccountName=<account>;AccountKey=<key>;EndpointSuffix=core.windows.net');` |
 
-For the matching warehouse JSON for each store, see the
-[Object Store Setup](object_store.md) guide.
+The [Object Store Setup](object_store.md) guide shows the matching warehouse
+JSON for AWS S3; for GCS and Azure, see
+[usage.md → Storage Backends](usage.md#storage-backends).
 
 ## Next Steps
 
diff --git a/docs/walkthrough_demos.md b/docs/walkthrough_demos.md
index 9aebc73..c8bf055 100644
--- a/docs/walkthrough_demos.md
+++ b/docs/walkthrough_demos.md
@@ -18,17 +18,17 @@ The following table shows the eleven steps this demo covers:
 
 | Step | What you will do |
 |------|-----------------|
-| [1. Start the stack](#step-1-start-the-stack-setup) | Bring up Postgres, Lakekeeper, and the object store |
-| [2. Create a table and load history](#step-2-create-a-table-and-load-months-of-history) | An ordinary partitioned table with months of data |
-| [3. See the problem](#step-3-see-the-problem) | All rows in hot Postgres storage, and it only grows |
-| [4. Enable the extensions](#step-4-enable-the-extensions) | Two extensions retrofit tiering onto the existing database |
-| [5. Point at object storage](#step-5-point-coldfront-at-the-object-store) | Tell ColdFront where cold data lives |
-| [6. Show the archiver policy](#step-6-show-the-archiver-policy) | `hot_period: 30 days` - the hot/cold boundary |
-| [7. Run the archiver](#step-7-register-the-table-then-run-the-archiver) | Move everything older than 30 days to object storage |
-| [8. Where it lives now](#step-8-where-the-data-lives-now) | The hot/cold split: rows and space in each tier |
-| [9. Query across tiers](#step-9-query-across-tiers) | One table, one query, hot + cold together |
-| [10. Write to cold data](#step-10-write-to-cold-data) | UPDATE an archived row in place - no rehydration |
-| [11. Prove it stuck](#step-11-prove-it-stuck) | Reconnect and confirm the edit persisted in cold storage |
+| [1. Start the stack](#step-1-start-the-stack-setup) | Bring up Postgres, Lakekeeper, and the object store. |
+| [2. Create a table and load history](#step-2-create-a-table-and-load-months-of-history) | Create an ordinary partitioned table with months of data. |
+| [3. See the problem](#step-3-see-the-problem) | See that all rows sit in hot Postgres storage, which only grows. |
+| [4. Enable the extensions](#step-4-enable-the-extensions) | Enable the two extensions that retrofit tiering onto the existing database. |
+| [5. Point at object storage](#step-5-point-coldfront-at-the-object-store) | Tell ColdFront where cold data lives. |
+| [6. Show the archiver policy](#step-6-show-the-archiver-policy) | Review the policy, where `hot_period: 30 days` sets the hot/cold boundary. |
+| [7. Run the archiver](#step-7-register-the-table-then-run-the-archiver) | Move everything older than 30 days to object storage. |
+| [8. Where it lives now](#step-8-where-the-data-lives-now) | Inspect the hot/cold split: the rows and space in each tier. |
+| [9. Query across tiers](#step-9-query-across-tiers) | Run one query on one table that reads hot and cold data together. |
+| [10. Write to cold data](#step-10-write-to-cold-data) | UPDATE an archived row in place, with no rehydration. |
+| [11. Prove it stuck](#step-11-prove-it-stuck) | Reconnect and confirm the edit persisted in cold storage. |
 
 ### Step 1: Start the Stack (Setup)
 
@@ -44,7 +44,7 @@ docker compose -f examples/walkthrough/docker-compose.yml ps
 
 PostgreSQL is your existing database. The catalog and object store are also
 running - that is the cold-storage side, unused until Step 5. Locally the store
-is SeaweedFS; in production it is your AWS S3, Azure Blob, or GCS bucket.
+is SeaweedFS; in production it is AWS S3, GCS, or Azure ADLS Gen2.
 
 ### Step 2: Create a Table and Load Months of History
 
@@ -52,10 +52,10 @@ This step stands in for the database you already run: an ordinary
 range-partitioned PostgreSQL table, filled with months of accumulated data.
 Nothing here is ColdFront-specific.
 
-Running the cells from this page? Skip ahead - every SQL cell below opens its
-own connection. Following along in a local shell instead, connect once with the
-walkthrough credentials (notices suppressed so the output stays clean) and
-paste each SQL block into the session:
+If you are running the cells from this page, skip ahead - every SQL cell below
+opens its own connection. Following along in a local shell instead, connect
+once with the walkthrough credentials (notices suppressed so the output stays
+clean) and paste each SQL block into the session:
 
 ```bash {"ignore":"true"}
 PGOPTIONS='-c client_min_messages=warning' \
@@ -112,13 +112,18 @@ SELECT i,
 FROM generate_series(1, 1000000) i;
 ```
 
+The interactive guide asks for the row count instead of loading one million
+rows. It offers a suggested size that fits Docker's free disk with headroom
+(the default), 1M, 10M, or 50M rows, or a custom count. When a size would not
+fit, the guide warns and asks again.
+
 Confirm all rows landed:
 
 ```sql {"interpreter":"psql postgresql://coldfront@localhost:5432/coldfront?options=-cclient_min_messages%3Dwarning -v ON_ERROR_STOP=1 -P pager=off -f"}
 SELECT count(*) FROM events;
 ```
 
-The count confirms it:
+The count confirms that all rows landed:
 
 ```text {"ignore":"true"}
   count
@@ -132,8 +137,8 @@ yet.
 ### Step 3: See the Problem
 
 This step measures how much hot Postgres storage that data occupies and
-confirms that none of it is anywhere cheaper yet. This is the baseline you will
-compare against after tiering in Step 8.
+confirms that none of it is in lower-cost storage yet. This is the baseline you
+will compare against after tiering in Step 8.
 
 `pg_total_relation_size()` on a partitioned parent counts only the empty parent
 itself and reports zero. Sum across `pg_partition_tree` to get the true heap
@@ -150,7 +155,7 @@ SELECT pg_size_pretty(
 ) AS hot_size;
 ```
 
-The result:
+The query returns:
 
 ```text {"ignore":"true"}
  hot_size
@@ -167,8 +172,8 @@ tiering.
 This step retrofits tiering onto the database you already have, using two
 extensions. `pg_duckdb` gives PostgreSQL an in-process engine that can read
 Parquet in object storage. `coldfront` adds the layer that routes each query to
-the right tier and rewrites DML. No migration, no new database - these install
-onto the running one.
+the right tier and rewrites DML. There is no migration and no new database -
+these install onto the running one.
 
 Run the following SQL to create both extensions:
 
@@ -186,15 +191,17 @@ Confirm both are installed:
 The output lists both:
 
 ```text {"ignore":"true"}
-   Name    | Version |   Schema   |                                          Description
------------+---------+------------+------------------------------------------------------------------------------------------------
- coldfront | 1.0     | coldfront  | Transparent tiered storage: route DML on tiered views across hot (PG) and cold (Iceberg) tiers
- pg_duckdb | 1.1.0   | public     | DuckDB Embedded in Postgres
- plpgsql   | 1.0     | pg_catalog | PL/pgSQL procedural language
+                                                            List of installed extensions
+   Name    | Version | Default version |   Schema   |                                          Description
+-----------+---------+-----------------+------------+------------------------------------------------------------------------------------------------
+ coldfront | 1.0     | 1.0             | coldfront  | Transparent tiered storage: route DML on tiered views across hot (PG) and cold (Iceberg) tiers
+ pg_duckdb | 1.1.0   | 1.1.0           | public     | DuckDB Embedded in Postgres
+ plpgsql   | 1.0     | 1.0             | pg_catalog | PL/pgSQL procedural language
+(3 rows)
 ```
 
-Two extensions - that is the entire ColdFront install. No sidecar, no proxy, no
-data movement yet.
+Two extensions - that is the entire ColdFront install. There is no sidecar, no
+proxy, and no data movement yet.
 
 ### Step 5: Point ColdFront at the Object Store
 
@@ -219,7 +226,7 @@ curl -s localhost:8181/management/v1/warehouse \
   | grep -o '"name":"wh"'
 ```
 
-The response confirms it:
+The response confirms that the warehouse exists:
 
 ```text {"ignore":"true"}
 "name":"wh"
@@ -228,8 +235,8 @@ The response confirms it:
 ### Step 6: Show the Archiver Policy
 
 The archiver policy is one rule in a YAML file: data older than 30 days belongs
-in cheap object storage; the most recent data stays hot in PostgreSQL. Nothing
-moves yet - this step shows the boundary.
+in low-cost object storage; the most recent data stays hot in PostgreSQL.
+Nothing moves yet - this step shows the boundary.
 
 Inspect the archiver configuration:
 
@@ -278,6 +285,8 @@ hand), then run the archiver: it moves every partition older than 30 days out
 of the PostgreSQL heap into Parquet files in object storage and rebuilds
 `events` as a unified view over the hot remainder and the cold data.
 
+The following commands import the table and run the archiver:
+
 ```bash
 docker compose \
   -f examples/walkthrough/docker-compose.yml \
@@ -290,7 +299,8 @@ docker compose \
 
 The `--no-deps` flag reuses the already-running, data-loaded `db` container;
 without it, `docker compose run` re-evaluates `depends_on` and can recreate
-`db` from its config hash, wiping the rows you just loaded.
+`db` from its config hash, restarting the database in the middle of the demo
+(the `pgdata` volume keeps the rows).
 
 The archiver connects inside the Compose network (service name `db`, not
 `localhost`), detaches the partitions older than 30 days from PostgreSQL,
@@ -331,7 +341,7 @@ SQL
 The query returns:
 
 ```text {"ignore":"true"}
-s3://iceberg/<warehouse-uuid>/<table-uuid>/metadata/00023-<uuid>.gz.metadata.json
+s3://iceberg/<table-uuid>/metadata/00023-<uuid>.gz.metadata.json
 
  file_path
 -----------------------------------------------------------------
@@ -396,14 +406,17 @@ Together, the three queries give the following hot/cold split:
 ```text {"ignore":"true"}
   Tier                    Rows         Postgres heap
   ----------------------  -----------  ----------------
-  Hot  (Postgres)             ~68,000  ~10 MB
-  Cold (Parquet in S3)       ~932,000  0 bytes in PG
+  Hot  (Postgres)             ~42,000  ~6.6 MB
+  Cold (Parquet in S3)       ~958,000  0 bytes in PG
   ----------------------  -----------  ----------------
   Total                     1,000,000
 ```
 
-Before tiering (Step 3): one million rows, all hot, approximately 152 MB of
-Postgres heap. After tiering: only the last month or two remains in PostgreSQL;
+The hot share depends on the day of the month you run the demo, because the
+cutoff is the start of the previous month: a run on the 1st keeps about 41,000
+rows hot, and a run at the end of a month about 83,000. Before tiering (Step
+3), the table held one million rows, all hot, in approximately 152 MB of
+Postgres heap. After tiering, only the last month or two remains in PostgreSQL;
 over 90% of the hot storage is gone while the total row count is unchanged.
 
 ### Step 9: Query Across Tiers
@@ -439,13 +452,15 @@ The query returns:
 ```text {"ignore":"true"}
  id |              ts               | status
 ----+-------------------------------+--------
-  1 | 2024-09-29 08:17:49.334041+00 | warn
-  2 | 2024-09-29 08:23:04.694041+00 | error
-  3 | 2024-09-29 08:28:20.054041+00 | ok
+  1 | 2024-10-01 14:44:24.687844+00 | warn
+  2 | 2024-10-01 14:45:27.759844+00 | error
+  3 | 2024-10-01 14:46:30.831844+00 | ok
+(3 rows)
 ```
 
-The timestamps track your load: row 1 sits exactly 730 days before it. One
-table, one query, no application change required.
+The timestamps track your load: the rows are 63.072 seconds apart (730 days
+divided by one million), and row 1 sits one such step short of 730 days before
+the load. It is one table and one query, and no application change is required.
 
 ### Step 10: Write to Cold Data
 
@@ -491,7 +506,7 @@ The updated row reads:
 ```text {"ignore":"true"}
  id |              ts               |  status
 ----+-------------------------------+-----------
-  1 | 2024-09-29 08:17:49.334041+00 | corrected
+  1 | 2024-10-01 14:44:24.687844+00 | corrected
 ```
 
 The row's status flipped `warn` to `corrected`. That row is still sitting in
@@ -522,9 +537,10 @@ SELECT id, status FROM events WHERE id = 1;
 The row reads:
 
 ```text {"ignore":"true"}
-  id |  status
------+-----------
-   1 | corrected
+ id |  status
+----+-----------
+  1 | corrected
+(1 row)
 ```
 
 Confirm the total row count is unchanged:
@@ -533,7 +549,7 @@ Confirm the total row count is unchanged:
 SELECT count(*) AS total_rows FROM events;
 ```
 
-The count confirms it:
+The count confirms the total is unchanged:
 
 ```text {"ignore":"true"}
  total_rows
@@ -554,16 +570,17 @@ SELECT pg_size_pretty(
 ) AS hot_size;
 ```
 
-The result:
+The query returns:
 
 ```text {"ignore":"true"}
  hot_size
 ----------
- ~10 MB
+ 6616 kB
+(1 row)
 ```
 
-Fresh connection: the archived row is still `corrected`, all one million rows
-are present, and the hot heap is still small. The data never came back to
+In the fresh connection, the archived row is still `corrected`, all one million
+rows are present, and the hot heap is still small. The data never came back to
 PostgreSQL. Over 90% of the original storage now lives in object storage as
 Parquet, and that data is still a normal, writeable part of the table -
 corrected in place, no rehydration, no separate system.
@@ -658,9 +675,9 @@ SELECT duckdb.raw_query($$
 
 ### Adopt It Read-Only
 
-One call, and no column list; the schema comes from the catalog. The view goes
-in the PostgreSQL schema `public`; `lake` is the Iceberg namespace, and no
-PostgreSQL schema of that name is needed:
+Adoption takes one call and no column list; the schema comes from the catalog.
+The view goes in the PostgreSQL schema `public`; `lake` is the Iceberg
+namespace, and no PostgreSQL schema of that name is needed:
 
 ```sql {"interpreter":"psql postgresql://coldfront@localhost:5432/coldfront?options=-cclient_min_messages%3Dwarning -v ON_ERROR_STOP=1 -P pager=off -f"}
 SELECT coldfront.adopt_iceberg_table('public', 'orders', 'lake');
@@ -730,10 +747,10 @@ the table keeps every row and stays in the catalog:
 SELECT coldfront.release_iceberg_table('public', 'orders');
 ```
 
-Two things to take from this demo. A `VARCHAR` column comes back as text rather
-than as `jsonb` unless `p_types` says otherwise, because Iceberg records no
-PostgreSQL type. The bakery serializes ColdFront's own writers, not an external
-engine writing the same table.
+There are two things to take from this demo. A `VARCHAR` column comes back as
+text rather than as `jsonb` unless `p_types` says otherwise, because Iceberg
+records no PostgreSQL type. The bakery serializes ColdFront's own writers, not
+an external engine writing the same table.
 
 ## Demo 3: Standalone Partitioner
 
@@ -804,9 +821,10 @@ archiver:
 
 ### Verify the Partitions
 
-Each reconcile pass premakes the next three monthly partitions ahead of now and
-ensures a partition covering today always exists. It also drops any partition
-older than the retention period:
+Each reconcile pass premakes the next three monthly partitions ahead of now
+(three is the `register --premake` default) and ensures a partition covering
+today always exists. Each pass also drops any partition older than the
+retention period:
 
 ```sql {"interpreter":"psql postgresql://coldfront@localhost:5432/coldfront?options=-cclient_min_messages%3Dwarning -v ON_ERROR_STOP=1 -P pager=off -f"}
 SELECT count(*) AS partitions
@@ -814,6 +832,11 @@ FROM pg_inherits
 WHERE inhparent = 'part_demo'::regclass;
 ```
 
+A table registered with `--strategy detach` keeps its expired partitions as
+standalone tables instead of dropping them. The
+[Managing Partitioned Tables (CLI)](usage.md#managing-partitioned-tables-cli)
+section describes the partition CLI and shows more `register` examples.
+
 ## Demo 4: Distributed
 
 Distributed mode points two or more PostgreSQL nodes at the *same* lake. The
@@ -825,8 +848,9 @@ are serialized cluster-wide so they never collide.
 
 This demo uses a different stack from the single-node walkthrough - two
 `MESH=on` nodes (`db1`, `db2`) plus a shared Lakekeeper and object store. The
-interactive guide automates the whole switch (it stops the single-node stack
-first, since a laptop rarely has room for both):
+interactive guide automates the whole switch. It first removes the single-node
+stack and its volumes with `docker compose down -v`, since a laptop rarely has
+room for both, so the data from Demos 1-3 does not survive the switch:
 
 > **This demo is not click-runnable.** It needs a different two-node stack and
 > separate psql sessions against each node (`db1` on port 5442, `db2` on 5443),
@@ -1028,7 +1052,8 @@ ORDER BY sequence_number;
 SQL
 ```
 
-Twelve writes from two nodes, twelve snapshots, no gap and no fork.
+Twelve writes from two nodes produce twelve snapshots, with no missing sequence
+number and no fork.
 
 ## Teardown
 
@@ -1040,8 +1065,8 @@ docker compose \
   down -v
 ```
 
-The `-v` flag removes the named volumes (`pgdata` and `s3data`). Omit it to
-keep the data for a later session.
+The `-v` flag removes the named volumes (`pgdata` and `s3data`). Omit the flag
+to keep the data for a later session.
 
 If you ran the distributed demo, tear down its separate mesh stack too:
 
@@ -1051,6 +1076,11 @@ docker compose \
   down -v
 ```
 
+In the interactive guide, the menu's R) Reset option drops the tables every
+demo created, in PostgreSQL and in the Iceberg catalog, and keeps the stack
+running. If the two-node cluster from Demo 4 is up, Reset first switches back
+to the single-node stack.
+
 ## Next Steps
 
 To go further with ColdFront, consult the following guides:
@@ -1059,7 +1089,7 @@ To go further with ColdFront, consult the following guides:
   the full one-time setup, supported column types, the partition manager CLI,
   and tuning options.
 - The [Object Store Setup](object_store.md) guide takes you from an empty
-  bucket to a working cold tier on cloud S3, GCS, or Azure.
+  bucket to a working cold tier on AWS S3.
 - The [Architecture](architecture.md) overview explains the shared mechanics
   and links to the per-mode deep dives.
 - The [Compaction](compaction.md) guide covers cold-tier maintenance:

From 6f642f4f45236ba27b8aff2b7e27c9a294e88410 Mon Sep 17 00:00:00 2001
From: Jimmy Angelakos <jimmy@pgedge.com>
Date: Thu, 1 Oct 2026 17:41:07 +0100
Subject: [PATCH 3/3] docs: fix review findings in the storage, decoupled and
 walkthrough pages

---
 docs/architecture_decoupled.md |  4 ++--
 docs/object_store.md           | 32 +++++++++++++++++++-------------
 docs/usage.md                  | 10 +++++-----
 docs/walkthrough_demos.md      | 16 +++++++++-------
 4 files changed, 35 insertions(+), 27 deletions(-)

diff --git a/docs/architecture_decoupled.md b/docs/architecture_decoupled.md
index 653a7aa..86d5e95 100644
--- a/docs/architecture_decoupled.md
+++ b/docs/architecture_decoupled.md
@@ -24,7 +24,7 @@ this document, concern by concern:
 | `post_parse_analyze_hook` | The hook rewrites INSERT/UPDATE/DELETE per tier. | The hook rewrites every INSERT/UPDATE/DELETE on the wrapper view to a single `SELECT coldfront._exec_iceberg_with_claim(<ref>, <DuckDB SQL>)`, which takes the table's claim and runs the statement through `duckdb.raw_query`. |
 | Archiver | The archiver moves rows from hot to cold on a cron. | None, because there is nothing to archive. |
 | `coldfront.tiered_views` row | The row is required for each managed table. | The row is required (with `is_iceberg_only = true`), and `create_iceberg_table()` registers it. |
-| Required at runtime | `pg_duckdb`, `coldfront`, Lakekeeper, S3 | `pg_duckdb`, `coldfront` (lazy catalog ATTACH, DML rewrite, and write serialization), Lakekeeper, S3 |
+| Required at runtime | `pg_duckdb`, `coldfront`, Lakekeeper, an S3-compatible store or Azure ADLS Gen2 | `pg_duckdb`, `coldfront` (lazy catalog ATTACH, DML rewrite, and write serialization), Lakekeeper, an S3-compatible store or Azure ADLS Gen2 |
 
 The coldfront extension provides the lazy catalog-attach glue: the C extension
 hook intercepts the first query that touches a tiered view (read or write) and,
@@ -92,7 +92,7 @@ notes:
 |---|---|---|
 | Lazy catalog ATTACH | The C hook calls `ensure_attached()` on the first query that touches a tiered view. | The ATTACH costs one round-trip on the first Iceberg query per session. |
 | CREATE TABLE | `SELECT duckdb.raw_query('CREATE TABLE ice.<ns>.<name> (...)')` | The statement is DuckDB SQL in attached-catalog syntax. |
-| INSERT | The C hook rewrites `INSERT INTO <view> [VALUES (…) | SELECT … FROM <pg_table> | SELECT … FROM generate_series(…)]` to one `SELECT coldfront._exec_iceberg_with_claim(<ref>, 'INSERT INTO ice.<ns>.<name> …')`. Source-table references get the prefix `pglocal.<schema>.<table>`, so DuckDB's postgres extension streams the source via libpq into the Iceberg writer. That attachment needs `coldfront.local_pg_dsn` (see [Bootstrap Sequence](#bootstrap-sequence)). | Each INSERT produces a single Iceberg snapshot, regardless of row count. |
+| INSERT | The C hook rewrites an `INSERT INTO <view>` whose source is `VALUES (…)`, `SELECT … FROM <pg_table>` or `SELECT … FROM generate_series(…)` to one `SELECT coldfront._exec_iceberg_with_claim(<ref>, 'INSERT INTO ice.<ns>.<name> …')`. Source-table references get the prefix `pglocal.<schema>.<table>`, so DuckDB's postgres extension streams the source via libpq into the Iceberg writer. That attachment needs `coldfront.local_pg_dsn` (see [Bootstrap Sequence](#bootstrap-sequence)). | Each INSERT produces a single Iceberg snapshot, regardless of row count. |
 | UPDATE | The hook rewrites `UPDATE <view> SET … WHERE …` to `SELECT coldfront._exec_iceberg_with_claim(<ref>, 'UPDATE ice.<ns>.<name> SET ... WHERE ...')`. | Iceberg applies the update as merge-on-read. |
 | DELETE | The hook rewrites `DELETE FROM <view> WHERE …` to `SELECT coldfront._exec_iceberg_with_claim(<ref>, 'DELETE FROM ice.<ns>.<name> WHERE ...')`. | Iceberg records the delete in position-delete files. |
 | SELECT (function-call form) | `SELECT … FROM iceberg_scan('ice.<ns>.<name>') r WHERE r['col'] = …` | Columns must use the `r['col']` accessor. In a fresh session, run `SELECT coldfront.ensure_attached();` first, or DuckDB treats the argument as a file path. |
diff --git a/docs/object_store.md b/docs/object_store.md
index 661dbc0..3b3a724 100644
--- a/docs/object_store.md
+++ b/docs/object_store.md
@@ -37,8 +37,8 @@ Before you begin, gather the following:
     > credentials at access time; see [usage.md](usage.md#vended-credentials).
 
 - permission for the key to read, write and list the bucket (`GetObject` /
-  `PutObject` / `DeleteObject` / `ListBucket`), as in the following example
-  policy:
+  `PutObject` / `DeleteObject` / `ListBucket`) and to abort a failed multipart
+  upload (`AbortMultipartUpload`), as in the following example policy:
 
     ```json
     {
@@ -46,7 +46,7 @@ Before you begin, gather the following:
       "Statement": [
         {
           "Effect": "Allow",
-          "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"],
+          "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket", "s3:AbortMultipartUpload"],
           "Resource": [
             "arn:aws:s3:::my-iceberg-bucket",
             "arn:aws:s3:::my-iceberg-bucket/*"
@@ -56,6 +56,10 @@ Before you begin, gather the following:
     }
     ```
 
+    DuckDB never aborts a failed multipart upload, so add an
+    `AbortIncompleteMultipartUpload` lifecycle rule to the bucket to delete
+    leftover parts.
+
 - the ColdFront image, built once by following
   [installation.md](installation.md), which notes the registry access the base
   image needs. Run the commands below from the repo root.
@@ -118,10 +122,10 @@ following flags matter:
 
 - omitting `endpoint` selects native per-Region virtual-hosted addressing over
   HTTPS.
-- `path-style-access: false` is required for virtual-hosted S3, because
-  path-style fails on any Region launched after 2019.
-- `flavor: "aws"` selects the Lakekeeper profile for virtual-hosted S3, not
-  `s3-compat`.
+- `path-style-access: false` selects virtual-hosted addressing, because AWS
+  plans to discontinue path-style URLs.
+- `flavor: "aws"` marks the store as AWS S3, which decides how Lakekeeper uses
+  STS, while `s3-compat` is for other S3-compatible stores.
 - `sts-enabled: false` and `remote-signing-enabled: false` make the warehouse
   use the long-term access key.
 
@@ -260,10 +264,10 @@ SELECT coldfront.set_storage_secret('AKIAEXAMPLE...', '<your-secret-key>', NULL,
 ```
 
 > **The 3rd argument (endpoint) must be `NULL` for a cloud S3 endpoint** - that
-> selects DuckDB's native per-Region virtual-hosted + HTTPS addressing
-> (required for Regions launched after 2019). The 4th argument is your bucket's
-> region. The SeaweedFS form you may have seen elsewhere passes a non-NULL
-> endpoint and no region - do **not** use that shape for cloud S3.
+> selects DuckDB's native per-Region virtual-hosted + HTTPS addressing. The 4th
+> argument is your bucket's region, from which DuckDB derives the endpoint. The
+> SeaweedFS form you may have seen elsewhere passes a non-NULL endpoint and no
+> region - do **not** use that shape for cloud S3.
 
 ---
 
@@ -333,8 +337,10 @@ Work through the following checklist if something failed:
   produces `schema "coldfront" does not exist`.
 - Check that `set_storage_secret(..., NULL, 'eu-west-1')` has `NULL` as its
   third argument (native virtual-hosted addressing over HTTPS) and your real
-  region as its fourth. A non-NULL endpoint forces path-style addressing and
-  breaks modern Regions with HTTP 400.
+  region as its fourth. A non-NULL endpoint applies `url_style` and `use_ssl`,
+  which default to path-style over plain HTTP. A wrong region sends requests to
+  another Region's endpoint, which S3 rejects (with HTTP 400 for a bucket in a
+  Region launched after 2019-03-20).
 - Check that the namespace `public` exists in Lakekeeper before
   `create_iceberg_table` runs. Without the namespace, the decoupled create
   fails with HTTP 404.
diff --git a/docs/usage.md b/docs/usage.md
index 8b78d24..7a13c18 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -707,11 +707,11 @@ or `vhost`. `region` defaults to `us-east-1`.
 For virtual-hosted cloud S3 (AWS S3 is the canonical one), **omit `endpoint`**
 (and the `endpoint` arg to `set_storage_secret`) so DuckDB uses the native
 per-Region virtual-hosted + HTTPS addressing; set `region` to your bucket's
-Region. This is **required** for Regions launched after 2019-03-20 (e.g.
-`ap-south-2`), whose DNS does not route path-style requests and returns
-HTTP 400. The Lakekeeper warehouse profile must be a virtual-hosted `s3`
-profile (`flavor: aws`, `path-style-access: false`, no custom endpoint); the
-full walkthrough is [object_store.md](object_store.md).
+Region. DuckDB derives the endpoint from `region`, and a bucket in a Region
+launched after 2019-03-20 (e.g. `ap-south-2`) rejects requests sent to another
+Region's endpoint with HTTP 400. The Lakekeeper warehouse profile must be a
+virtual-hosted `s3` profile (`flavor: aws`, `path-style-access: false`, no
+custom endpoint); the full walkthrough is [object_store.md](object_store.md).
 
 ### Google Cloud Storage
 
diff --git a/docs/walkthrough_demos.md b/docs/walkthrough_demos.md
index c8bf055..269ceff 100644
--- a/docs/walkthrough_demos.md
+++ b/docs/walkthrough_demos.md
@@ -412,12 +412,14 @@ Together, the three queries give the following hot/cold split:
   Total                     1,000,000
 ```
 
-The hot share depends on the day of the month you run the demo, because the
-cutoff is the start of the previous month: a run on the 1st keeps about 41,000
-rows hot, and a run at the end of a month about 83,000. Before tiering (Step
-3), the table held one million rows, all hot, in approximately 152 MB of
-Postgres heap. After tiering, only the last month or two remains in PostgreSQL;
-over 90% of the hot storage is gone while the total row count is unchanged.
+The hot share depends on the day you run the demo. The archiver moves a monthly
+partition to cold storage once its end is at least 30 days in the past, so the
+previous month stays hot until the 31st. A run on the 1st or the 31st keeps
+about 42,000 rows hot, and a run late in any other month about 83,000. Before
+tiering (Step 3), the table held one million rows, all hot, in approximately
+152 MB of Postgres heap. After tiering, only the last month or two remains in
+PostgreSQL; over 90% of the hot storage is gone while the total row count is
+unchanged.
 
 ### Step 9: Query Across Tiers
 
@@ -486,7 +488,7 @@ The query returns:
 ```text {"ignore":"true"}
  id |              ts               | status
 ----+-------------------------------+--------
-  1 | 2024-09-29 08:17:49.334041+00 | warn
+  1 | 2024-10-01 14:44:24.687844+00 | warn
 ```
 
 Update the archived row through the same table using the captured id: