# Mission Manifest — CLI Unification & E2E First-Run

> Persistent document tracking full mission scope, status, and session history.
> Updated by the orchestrator at each phase transition and milestone completion.

## Mission

**ID:** cli-unification-20260404
**Statement:** Transform the Mosaic CLI from a partially-duplicated, manually-assembled experience into a single cohesive entry point that installs, configures, and controls the entire Mosaic system. Every Mosaic package gets first-class CLI surface. The first-run experience works end-to-end with no manual stitching. Gateway token recovery is possible without the web UI. Opt-in telemetry uses the published telemetry clients.
**Phase:** Execution
**Current Milestone:** cu-m03 / cu-m04 / cu-m05 (parallel-eligible)
**Progress:** 2 / 8 milestones
**Status:** active
**Last Updated:** 2026-04-04

## Success Criteria

- [ ] AC-1: Fresh machine `bash <(curl …install.sh)` → single command lands on a working authenticated gateway with a usable admin token; no secondary manual wizards required
- [ ] AC-2: `mosaic --help` lists every sub-package as a top-level command and is alphabetized for readability
- [ ] AC-3: `mosaic auth`, `mosaic brain`, `mosaic forge`, `mosaic log`, `mosaic macp`, `mosaic memory`, `mosaic queue`, `mosaic storage`, `mosaic telemetry` each expose at least one working subcommand that exercises the underlying package
- [ ] AC-4: Gateway admin token can be rotated or recovered from the CLI alone — operator is never stranded because the web UI is inaccessible
- [ ] AC-5: `mosaic telemetry` uses the published `@mosaicstack/telemetry-client-js` (from the Gitea npm registry); local OTEL stays for wide-event logging / post-mortems; remote upload is opt-in and disabled by default
- [ ] AC-6: Install → wizard → gateway install → TUI verification flow is a single cohesive path with clear state transitions and no dead ends
- [ ] AC-7: `@mosaicstack/mosaic` is the sole `mosaic` binary owner; `@mosaicstack/cli` is gone from the repo and all docs
- [ ] AC-8: All milestones ship as merged PRs with green CI, closed issues, and updated release notes

## Milestones

| #   | ID     | Name                                                                     | Status      | Branch                             | Issue | Started    | Completed  |
| --- | ------ | ------------------------------------------------------------------------ | ----------- | ---------------------------------- | ----- | ---------- | ---------- |
| 1   | cu-m01 | Kill legacy @mosaicstack/cli package                                     | done        | chore/remove-cli-package-duplicate | #398  | 2026-04-04 | 2026-04-04 |
| 2   | cu-m02 | Archive stale mission state + scaffold new mission                       | done        | docs/mission-cli-unification       | #399  | 2026-04-04 | 2026-04-04 |
| 3   | cu-m03 | Fix gateway bootstrap token recovery (server + CLI paths)                | not-started | —                                  | —     | —          | —          |
| 4   | cu-m04 | Alphabetize + group `mosaic --help` output                               | not-started | —                                  | —     | —          | —          |
| 5   | cu-m05 | Sub-package CLI surface (auth/brain/forge/log/macp/memory/queue/storage) | not-started | —                                  | —     | —          | —          |
| 6   | cu-m06 | `mosaic telemetry` — local OTEL + opt-in remote upload                   | not-started | —                                  | —     | —          | —          |
| 7   | cu-m07 | Unified first-run UX (install.sh → wizard → gateway → TUI)               | not-started | —                                  | —     | —          | —          |
| 8   | cu-m08 | Docs refresh + release tag                                               | not-started | —                                  | —     | —          | —          |

## Deployment

| Target               | URL       | Method                                          |
| -------------------- | --------- | ----------------------------------------------- |
| Local tier (default) | localhost | `mosaic gateway install` — pglite + local queue |
| Team tier            | any host  | `mosaic gateway install` — PG + Valkey          |
| Docker Compose (dev) | localhost | `docker compose up` for PG/Valkey/OTEL/Jaeger   |

## Coordination

- **Primary Agent:** claude-opus-4-6[1m]
- **Sibling Agents:** sonnet (standard implementation), haiku (status/explore/verify), codex (coding-heavy tasks)
- **Shared Contracts:** `docs/PRD.md` (existing v0.1.0 PRD — still the long-term target), this manifest, `docs/TASKS.md`, `docs/scratchpads/cli-unification-20260404.md`

## Token Budget

| Metric | Value  |
| ------ | ------ |
| Budget | TBD    |
| Used   | ~80K   |
| Mode   | normal |

## Session History

| Session | Runtime         | Started    | Duration  | Ended Reason | Last Task                                                    |
| ------- | --------------- | ---------- | --------- | ------------ | ------------------------------------------------------------ |
| 1       | claude-opus-4-6 | 2026-04-04 | in-flight | —            | cu-m01 + cu-m02 merged (#398, #399); open questions resolved |

## Scratchpad

Path: `docs/scratchpads/cli-unification-20260404.md`