- docs/federation/SETUP.md (NEW, 119 lines): what federated is, prerequisites, docker compose start, config snippet, mosaic gateway doctor health check, troubleshooting (port conflicts, pgvector errors, Valkey connection) - docs/guides/migrate-tier.md (NEW, 147 lines): when to migrate, dry-run first, what gets migrated/skipped (with rationale for accounts + provider_credentials), idempotency + advisory-lock semantics, manual verification queries, no in-place rollback - README.md: 1-line blurb in Configuration section linking to both All commands verified against actual CLI surface in packages/storage/src/cli.ts and packages/mosaic/src/commands/gateway-doctor.ts. Refs #460