feat(fleet): mosaic fleet regen — regenerate roster-derived projections (PR3 of #791) (#813)

docs/guides/fleet-local-canary.md

@@ -98,6 +98,39 @@ Expected results:
   that means the unit ran, not that an agent pane is live. Treat tmux
   `has-session`, `list-panes`, process tree, and logs as the liveness evidence.
 
+## Recovery — rebuild generated env projections
+
+Each agent's `~/.config/mosaic/fleet/agents/<name>.env.generated` is a
+deterministic projection of `roster.yaml` (the SSOT) that the launcher
+(`start-agent-session.sh`) sources at start. If an upgrade or a manual mistake
+wipes or diverges those projections, rebuild them from the roster with
+`mosaic fleet regen` — do NOT restart the affected unit first.
+
+```bash
+mosaic fleet regen            # dry-run (default): show create/rebuild plan per agent
+mosaic fleet regen --json     # same plan, machine-readable
+mosaic fleet regen --write    # rebuild fleet/agents/<name>.env.generated on disk
+```
+
+`regen` is projection-only and **never restarts an agent** — it has no path to
+systemd lifecycle. It is dry-run by default, deterministic/idempotent, uses the
+same roster→env mapping as `mosaic fleet reconcile`, and emits paths and counts
+only (never the projected `KEY=value` body). After `--write`, verify each unit
+resolves the intended values before restarting one unit at a time. The unit sets
+no `EnvironmentFile=` — `start-agent-session.sh` sources `.env.generated` itself —
+so verify the generated file directly and the launcher path, not a nonexistent
+`EnvironmentFile` property:
+
+```bash
+test -f ~/.config/mosaic/fleet/agents/<name>.env.generated
+systemctl --user cat mosaic-agent@<name> | grep ExecStart
+systemctl --user restart mosaic-agent@<name>
+```
+
+Full recovery runbook and the three-layer #791 protection model (manifest
+ownership → pre-update snapshot/restore → regen): see
+[Upgrade Safety & Recovery](./upgrade-safety-and-recovery.md).
+
 ## Release Preflight
 
 Run this checklist before cutting or dogfooding a fleet release: