Docs: clarify 3.1 schema reconciliation behavior

CHANGELOG.md

@@ -708,13 +708,21 @@ and the changes most likely to affect consumers.
   safer than a false modification that churns.
 - Adds a schema **diff subsystem** (`BerlinDB\Database\Diff\`, decoupled from `Kern`):
   a pure, stateless `Comparator` compares two schemas and returns a `Patch` describing
-  the changes that transform one into the other - added/dropped columns and indexes
-  (matched by identity; the primary key by type). `Schema::diff( Schema $other )` is the
-  pure entry point; `Table::diff()` introspects the live table and compares it to the
-  declared schema, and `Table::diverged()` is the boolean drift check. The `Patch` carries
+  the changes that transform one into the other - added, dropped, and modified columns
+  and indexes (matched by identity; the primary key by type).
+  `Schema::diff( Schema $other )` is the pure entry point; `Table::diff()` introspects
+  the live table and compares it to the declared schema, and `Table::diverged()` is
+  the boolean drift check. The `Patch` carries
   the real `Column`/`Index` objects and exposes `is_empty()`, `revert()` (the inverse
-  patch), and stubbed `apply()`/`to_sql()` (phase 3). v1 detects adds/drops only; modified
-  detection lands next (#224 phase 2).
+  patch), `to_sql()` for an ordered SQL preview, and `apply()` to reconcile a bound
+  table. Applying additions and modifications is the default; drops are opt-in (#224).
+- A `Table` version bump with no bespoke upgrade callback now reconciles added
+  columns and indexes against its declared Schema by default. This automatic
+  upgrade uses a complete live-schema snapshot and defers when introspection is
+  incomplete. Set `reconcile => false` to retain a version-only bump, `true` to
+  include modifications, or an explicit operations list to control additions,
+  modifications, and drops. Bespoke upgrade callbacks still run as before;
+  automatic reconciliation applies only when none are pending (#224).
 - `Schema::from_table()` now introspects **indexes** as well as columns: it runs
   `SHOW INDEX FROM`, groups the rows by `Key_name`, and builds an `Index` per group via
   `Index::from_mysql()`, so a live table round-trips losslessly into a `Schema` (#224

docs/upgrading-to-3.1.md

@@ -54,6 +54,12 @@ The older datetime, decimal, and UUID Column validators remain public.
   name on a preset is respected rather than replaced by the preset default.
   Declare an explicit `UNIQUE` index if a UUID must be unique in the database;
   the derived UUID lookup index is not unique.
+- A `Table` version bump with no pending custom upgrade callback now adds
+  missing declared columns and indexes automatically. Check the declared Schema
+  before bumping its version. Set `reconcile => false` on a Table to keep the
+  old version-only behavior; use `true` to opt into modifications, or an
+  explicit operations list to opt into drops. An incomplete schema snapshot
+  defers the version bump so the upgrade can retry.
 - Temporal columns declared with `CURRENT_TIMESTAMP` now emit the unquoted SQL
   function, and empty values can defer to MySQL's default or `ON UPDATE`
   behavior. Nullable datetimes with a `null` default now store SQL `NULL` for