docs(federation): operator setup + migration guides (FED-M1-11) #480

jason.woltje · 2026-04-20T02:07:05Z

jason.woltje commented

2026-04-20 02:07:05 +00:00

FED-M1-11 — Operator-facing documentation for the federated tier.

What ships

docs/federation/SETUP.md (NEW, 119 lines) — what federated is, prerequisites, docker compose start command, mosaic.config.json snippet, mosaic gateway doctor health check (with --json example), troubleshooting (port conflicts, pgvector errors, Valkey connection refused).
docs/guides/migrate-tier.md (NEW, 147 lines) — when to migrate, dry-run first, what gets migrated and what gets skipped (with rationale for accounts and provider_credentials being intentionally migrated as durable user-bound credentials), idempotency + advisory-lock semantics, manual verification queries, no in-place rollback.
README.md — 1-line blurb in existing Configuration section linking to both docs.

Constraints honored

Operator-actionable only; no design rationale (those live in PRD.md).
All commands verified against actual CLI surface in packages/storage/src/cli.ts and packages/mosaic/src/commands/gateway-doctor.ts.
Runbook NOT touched (deferred to FED-M7 per task spec).
No changes to MISSION-MANIFEST.md, MILESTONES.md, PRD.md.

Test plan

CI green (format/lint gates only — no code changes)
Manual: walk through SETUP.md against a fresh machine, then walk through migrate-tier.md against a seeded local tier

Refs #460

FED-M1-11 — Operator-facing documentation for the federated tier. ## What ships - `docs/federation/SETUP.md` (NEW, 119 lines) — what federated is, prerequisites, docker compose start command, mosaic.config.json snippet, mosaic gateway doctor health check (with --json example), troubleshooting (port conflicts, pgvector errors, Valkey connection refused). - `docs/guides/migrate-tier.md` (NEW, 147 lines) — when to migrate, dry-run first, what gets migrated and what gets skipped (with rationale for accounts and provider_credentials being intentionally migrated as durable user-bound credentials), idempotency + advisory-lock semantics, manual verification queries, no in-place rollback. - README.md — 1-line blurb in existing Configuration section linking to both docs. ## Constraints honored - Operator-actionable only; no design rationale (those live in PRD.md). - All commands verified against actual CLI surface in packages/storage/src/cli.ts and packages/mosaic/src/commands/gateway-doctor.ts. - Runbook NOT touched (deferred to FED-M7 per task spec). - No changes to MISSION-MANIFEST.md, MILESTONES.md, PRD.md. ## Test plan - [ ] CI green (format/lint gates only — no code changes) - [ ] Manual: walk through SETUP.md against a fresh machine, then walk through migrate-tier.md against a seeded local tier Refs #460

jason.woltje added 1 commit 2026-04-20 02:07:06 +00:00

docs(federation): operator setup + migration guides for federated tier (FED-M1-11)

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

7493943945

- 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

jason.woltje merged commit 78841f228a into main

2026-04-20 02:07:17 +00:00

jason.woltje referenced this issue from a commit

2026-04-20 02:07:19 +00:00

docs(federation): operator setup + migration guides (FED-M1-11) (#480)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#480