fix(#1264): bootstrap fleet identity without a TTY

docs/USER-GUIDE/README.md

@@ -11,6 +11,7 @@ This book is the canonical home for end-user workflows, user-visible behavior, p
 - [Quickstart](getting-started/quickstart.md) — install Mosaic, complete setup, and launch a session.
 - [Web dashboard](product/web-dashboard.md) — current routes, navigation, chat persistence, projects/tasks views, settings, and admin behavior.
 - [Discord conversations](workflows/discord-conversations.md) — current authorized parent-channel, thread, attachment, and control workflow.
+- [Fleet unattended first start](workflows/fleet-unattended-first-start.md) — no-TTY identity bootstrap, exact roster identity, and separate runtime prerequisites.
 
 ## Chapter map
 
@@ -18,7 +19,7 @@ This book is the canonical home for end-user workflows, user-visible behavior, p
 | ------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
 | `getting-started/` | First-use setup, orientation, and quickstarts.                | Quickstart is current; additional pages are planned. |
 | `concepts/`        | User-facing terminology, product concepts, and mental models. | Scaffold only.                                       |
-| `workflows/`       | Task-oriented procedures for using Mosaic Stack.              | Discord conversation workflow is current.            |
+| `workflows/`       | Task-oriented procedures for using Mosaic Stack.              | Discord and fleet first-start workflows are current. |
 | `product/`         | Current product surfaces and visible behavior.                | Web dashboard reference is current.                  |
 | `troubleshooting/` | User-visible failures, diagnostics, and fixes.                | Scaffold only.                                       |
 
@@ -27,6 +28,7 @@ This book is the canonical home for end-user workflows, user-visible behavior, p
 - [Quickstart](getting-started/quickstart.md) — the verified installed-CLI first-use path.
 - [Web dashboard](product/web-dashboard.md) — verified current Next.js dashboard behavior and limitations.
 - [Discord conversations](workflows/discord-conversations.md) — verified current Discord user workflow.
+- [Fleet unattended first start](workflows/fleet-unattended-first-start.md) — verified no-TTY first-start behavior and prerequisite boundaries.
 
 Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
 

docs/USER-GUIDE/workflows/fleet-unattended-first-start.md

@@ -0,0 +1,59 @@
+# Fleet Unattended First Start
+
+> **Status:** Current for roster-owned local fleet launches after issue #1264 lands. Runtime
+> installation and provider authentication remain separate prerequisites.
+
+A fleet seat started by systemd has no operator at its pane. On its first launch, Mosaic must not
+stop at the interactive identity wizard.
+
+## What happens on first start
+
+When `MOSAIC_AGENT_NAME` names an exact member of the installed fleet roster and top-level identity
+contracts are absent, the launcher:
+
+1. validates the exact roster member and installed fleet communications helper;
+2. reads the shipped generic contracts from
+   `~/.config/mosaic/defaults/SOUL.md` and `defaults/USER.md`;
+3. creates only the missing top-level `SOUL.md` and `USER.md` as owner-private files;
+4. preserves any existing top-level identity file byte-for-byte; and
+5. launches the runtime with the roster member's exact agent/session name and role/class in composed
+   context.
+
+The generic defaults do **not** make every seat the same identity. They provide a shared behavioral
+base. The canonical roster row supplies each seat's exact name, class, peers, socket, and authority.
+
+## Operator behavior
+
+A normal standalone launch without a fleet identity still uses the interactive wizard when
+`SOUL.md` is absent:
+
+```bash
+mosaic pi
+```
+
+A roster-owned seat may be started without attaching to its pane:
+
+```bash
+mosaic fleet start <exact-roster-name>
+```
+
+Mosaic refuses before runtime execution if the requested member is absent, a required default is
+missing or unsafe, or an existing identity contract is not a safe regular file. Repair the named
+path and retry the same exact roster member; do not copy another seat's personalized identity.
+
+## Separate prerequisites
+
+This behavior clears the Mosaic identity-wizard wall only. A clean host still needs:
+
+- the declared runtime installed on the pane PATH;
+- the fleet transport and generated unit assets; and
+- runtime/provider authentication appropriate to that seat.
+
+Those checks are separate so a successful identity bootstrap is not reported as a fully authenticated
+agent session.
+
+## Related
+
+- [Administrator runbook](../../ADMIN-GUIDE/operations/fleet-unattended-first-start.md)
+- [Developer architecture](../../DEVELOPER-GUIDE/architecture/fleet-first-start-identity.md)
+- [Verification report](../../reports/qa/2026-08-16-1264-unattended-first-start.md)