# FCM-M5-001 — Fleet configuration operator documentation

- Task: `FCM-M5-001`
- Issue: `#758`
- Branch: `docs/758-fleet-config-operator-docs`
- Exact base: `9745bc3f29c26b021a478b7ad03cfb494f6c9de3` (tree `4da210da9a71b035130d4160a4a2e691bdfde2da`)

## Objective

Deliver the accepted fleet documentation information architecture, operator workflows, operations and migration references, comprehensive contract documentation, and deterministic link/example validation without live fleet action or product mutation.

## Scope and constraints

- Documentation, examples, documentation validation, and tracking only.
- `roster.yaml` remains the sole writable desired-state authority; generated state is derived/observed.
- No M4-002 implementation or execution; no canary, migration, rollback, deployment, systemd/tmux/session, generated projection, or product mutation.
- `mos-comms` is temporary and is not permanent architecture.
- Parent issue `#758` remains open through M5.
- No credentials, sensitive values, or privileged command content.

## Plan

1. Update tracking first with exact M4-001 evidence and mark M5-001 in progress.
2. Map the M0 checklist and current implementation behavior to documentation pages.
3. Author operator, operations, migration, schema/reference, recovery, troubleshooting, and security/authority docs.
4. Add or extend deterministic documentation/link/example validation if required, red-first.
5. Run repository documentation, link, example, and relevant package checks; review and remediate.
6. Commit, queue-guard, push one branch, and open one wrapper-created PR; stop for independent review.

## Budget

- Task estimate: `24K`.
- Working cap: stay within the card estimate by parallelizing read-only discovery and limiting edits to checklist-required artifacts.

## Progress checkpoints

- [x] Loaded repository/global delivery and documentation contracts.
- [x] Verified `origin/main` is exact required base and created isolated worktree.
- [x] Tracking updated first.
- [x] Checklist mapped and docs authored.
- [x] Validation green.
- [x] Review/remediation complete.
- [x] Commit, queue guard, push, PR #789.
- [x] Rejected exact-head RoR findings repaired on a new descendant commit candidate.
- [ ] New exact-head review and CI after repair push.

## Tests and verification

- Red-first documentation validator initially failed for the absent fleet entry point and canonical
  example, then passed after the IA and example were added.
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/roster-v2.spec.ts src/fleet/example-profile-dispositions.spec.ts src/fleet/fleet-documentation.spec.ts src/fleet/v1-v2-migration.spec.ts src/fleet/generated-env-boundary.spec.ts src/fleet/fleet-agent-crud.spec.ts src/fleet/fleet-reconciler.spec.ts` — 7 files, 195 tests passed after building workspace dependencies.
- `pnpm format:check` — passed.
- `pnpm lint` — 23 tasks passed.
- `pnpm typecheck` — 42 tasks passed.
- `pnpm test` — 43 tasks passed; `@mosaicstack/mosaic` contributed 61 files and 1,045 tests.
- `bash packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh` — passed.
- `bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh` — passed.
- `git diff --check` — passed before final review.
- Independent staged-snapshot review identified four documentation/validation blockers: reboot safety,
  heartbeat observation, migration failure envelope, and example-scan coverage. All were remediated;
  focused rereview approved the staged remediations with no blockers. Exact committed-head review remains
  a post-PR gate.
- Post-remediation `@mosaicstack/mosaic` lint/typecheck passed; package test passed 61 files / 1,045
  tests; sanitization and resident-budget gates passed again.

- Post-PR exact-head RoR on rejected head `0aee2c09819fd06e28f927384ea56fa2ef374edf`
  identified five blockers: update-lifecycle overclaim, missing explicit `fleet validate` gap,
  fragment-blind link validation, unsupported checklist-evidence claim, and insufficient example safety
  validation. Red-first regressions failed before implementation for missing-heading, privileged-command,
  and credential-format fixtures. Repairs now preserve/document implementation truth, validate heading
  fragments, narrow checklist claims, and scan fenced/canonical examples for common credential formats
  and privileged commands without printing fixture values.
- Repair-focused fleet contracts: 7 files, 192 tests passed after review remediation; documentation
  validator contributed 11 tests. Full gates passed: format; lint 23/23; typecheck 42/42; test 43/43
  tasks with `@mosaicstack/mosaic` 61 files / 1,052 tests; sanitization; resident budget; and
  `git diff --check`. New exact-head review/CI remain pending until the repair commit is pushed.

## Risks/blockers

- Checklist may include behavior intentionally deferred to M4-002/M5-002; such items must be recorded as approved-existing holds rather than claimed delivered.
- Commands/examples must remain non-live and avoid privileged/sensitive content.

## Final evidence

- Pending.