Fix the V165/V166 manifest entries, revive S21, and close the squash-equivalence evidence gap

[mdon]

Closes the verification gap that every reviewer kept flagging before the 2.0 release — and it was not only a gap. Running the checks found two real defects.

The manifest was wrong on a healthy database

The V165/V166 objects are the only manifest entries written by hand rather than generated from a live DB, and all four were recorded in source-SQL form instead of the canonical form Postgres stores:

CHECK (kind IN ('user', 'resource')) -- manifest
CHECK ((kind = ANY (ARRAY['user'::text, 'resource'::text]))) -- what PG reports

The differ compares against pg_get_constraintdef / pg_get_indexdef, so these could never match. mix phoenix_kit.repair and mix phoenix_kit.doctor reported four error-severity divergences on every healthy V166 install — false alarms that train operators to ignore a report meant to mean something.

The index predicate shows the origin: it was copied from phoenix_kit_org_invitations_pending_unique_idx, whose status column is varchar (so PG emits ((status)::text = 'pending'::text)). access_requests.status is text, where that cast never appears. Same predicate, different column type, different deparsed output — verified against both columns in a live DB.

No migration files changed, so chain_hash is untouched.

S21 had silently stopped testing V164

s21 derived the migration under test as current_version() - 1 .. current_version(). That was correct only while V164 was the head. Once V165/V166 landed the delta became 165→166, so the scenario simulated the V56/V57 flush-order defect, skipped the migration that repairs it, and then reported ~70 unenforced foreign keys and ~44 nullable columns as a product defect.

Pinned to @s21_repair_version — the delta under test is a property of the migration, not of wherever the chain ends. V164's repair is now verified against a live database for the first time: restores every FK and NOT NULL, byte-identical on a second pass, orphan-blocked FK correctly left NOT VALID.

S1/S2 equivalence evidence now matches HEAD

The saved references were built at chain v163, so every run since skipped S1/S2 as reference-stale — #689's squash-equivalence evidence covered neither V164 nor V165/V166.

Regenerated from a git worktree at the bridge commit (113dddbf, the last pre-squash checkout) with V164–V166 grafted on and @current_version bumped to 166, so the old chain runs all 166 versions individually.

That graft also needed uuid_fk_columns.ex from HEAD — V164 drives its repair off fk_constraints/0, which the bridge copy does not expose. Worth a reviewer's eye: HEAD's copy also drops {:phoenix_kit_users_tokens, "user_uuid"} from the NOT NULL list, a deliberate 2026-08-08 fix (magic-link registration tokens are authorless by design; the V135 baseline does not enforce it either). Taking HEAD's copy keeps both sides of the comparison expressing the same intent — keeping the bridge's would have manufactured a "divergence" that is a documented fix rather than a squash defect.

This also unblocks S4: the below-floor handoff schema seeds from the same worktree, so the BelowFloorError guard protecting pre-2.0 upgrades is verified rather than skipped.

Docs

• The upgrade guide named ~> 1.7.235 as the bridge; the tagged bridge, and the version @bridge_version names in the refusal message, is 1.7.236. Two further stale spots predated V165/V166: the chain was described as ending at V164, and the healthy-install FK count was labelled as measured against a V135..V164 build. Re-measured against a fresh V135..V166 build: still 86, so only the label was wrong.
• The README was a bigger gap. It told every reader to install {:phoenix_kit, "~> 1.7"} — which does not resolve to 2.0 — and said nothing anywhere about upgrading. Since 2.0 refuses to migrate a database below V135, an existing user bumping the pin would have met a BelowFloorError with no warning in the document they were most likely to read. Added an "Upgrading to 2.0" section covering the floor, the bridge pin, the mix phoenix_kit.update step, and the comments-FK change from ON DELETE CASCADE to SET NULL.
• Fixed seven broken doc references (14 warnings → 0) that would have shipped as dead links in the 2.0 hexdocs — missing t:/c: prefixes, a bare Registry alias resolving to Elixir's stdlib, and one genuine error where Ecto.Adapters.SQL.checkout/2 does not exist and checkout/3 is @doc false (the code calls repo.checkout/2).

Verification

Full scenario harness against live PostgreSQL 17.6, from a clean slate (fresh DB, worktree removed):

22 PASS — s1, s2, s1_self, s2_self, s3, s4, s5, s6, s7, s8, s8_pre, s9, s10, s11, s11_pre, s13, s15, s17, s19, s20, s21, s22

4 SKIP — s4_seed (bridge-side half of a two-checkout handoff, by design), s12 (needs a pooled endpoint), s16 (P2 body unwritten), s18 (needs a manual trigger)

Also green: mix precommit · mix dialyzer · mix docs · release check (current_version == v166.ex, floor == V135, V135..V166 contiguous, chain_hash matches 32 on-disk files).

Pre-existing and unrelated: the full suite shows one flaky failure per run, a different test each time, all passing in isolation — shared global settings state across async tests.