docs: CLI unification release v0.1.0 (M8) (#419)

docs/guides/user-guide.md

@@ -8,6 +8,8 @@
 4. [Tasks](#tasks)
 5. [Settings](#settings)
 6. [CLI Usage](#cli-usage)
+7. [Sub-package Commands](#sub-package-commands)
+8. [Telemetry](#telemetry)
 
 ---
 
@@ -160,12 +162,18 @@ The `mosaic` CLI provides a terminal interface to the same gateway API.
 
 ### Installation
 
-The CLI ships as part of the `@mosaicstack/mosaic` package:
+Install via the Mosaic installer:
 
 ```bash
-# From the monorepo root
-pnpm --filter @mosaicstack/mosaic build
-node packages/mosaic/dist/cli.js --help
+bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/mosaic-stack/raw/branch/main/tools/install.sh)
+```
+
+The installer places the `mosaic` binary at `~/.npm-global/bin/mosaic`. Flags for
+non-interactive use:
+
+```bash
+--yes               # Accept all defaults
+--no-auto-launch    # Skip auto-launch of wizard after install
 ```
 
 Or if installed globally:
@@ -174,7 +182,60 @@ Or if installed globally:
 mosaic --help
 ```
 
-### Signing In
+### First-Run Wizard
+
+After install the wizard launches automatically. You can re-run it at any time:
+
+```bash
+mosaic wizard
+```
+
+The wizard guides you through:
+
+1. Gateway discovery or installation (`mosaic gateway install`)
+2. Authentication (`mosaic gateway login`)
+3. Post-install health check (`mosaic gateway verify`)
+
+### Gateway Login and Token Recovery
+
+```bash
+# Authenticate with a gateway and save a session token
+mosaic gateway login
+
+# Verify the gateway is reachable and responding
+mosaic gateway verify
+
+# Rotate your current API token
+mosaic gateway config rotate-token
+
+# Recover a token via BetterAuth cookie (for accounts with no token)
+mosaic gateway config recover-token
+```
+
+If you have an existing gateway account but lost your token (common after a
+reinstall), use `mosaic gateway config recover-token` to retrieve a new one
+without recreating your account.
+
+### Configuration
+
+```bash
+# Print full config as JSON
+mosaic config show
+
+# Read a specific key
+mosaic config get gateway.url
+
+# Write a key
+mosaic config set gateway.url http://localhost:14242
+
+# Open config in $EDITOR
+mosaic config edit
+
+# Print config file path
+mosaic config path
+```
+
+### Signing In (Legacy)
 
 ```bash
 mosaic login --gateway http://localhost:14242 --email you@example.com
@@ -236,3 +297,267 @@ mosaic prdy
 # Quality rails scaffolder
 mosaic quality-rails
 ```
+
+---
+
+## Sub-package Commands
+
+Each Mosaic sub-package exposes its full API surface through the `mosaic` CLI.
+All sub-package commands accept `--help` for usage details.
+
+### `mosaic auth` — User & Authentication Management
+
+Manage gateway users, SSO providers, and active sessions.
+
+```bash
+# List all users
+mosaic auth users list
+
+# Create a new user
+mosaic auth users create --email alice@example.com --name "Alice"
+
+# Delete a user
+mosaic auth users delete <userId>
+
+# List configured SSO providers
+mosaic auth sso
+
+# List active sessions
+mosaic auth sessions list
+
+# Revoke a session
+mosaic auth sessions revoke <sessionId>
+```
+
+### `mosaic brain` — Projects, Missions, Tasks, Conversations
+
+Browse and manage the brain data layer (PostgreSQL-backed project/mission/task
+store).
+
+```bash
+# List all projects
+mosaic brain projects
+
+# List missions for a project
+mosaic brain missions --project <projectId>
+
+# List tasks
+mosaic brain tasks --status in-progress
+
+# Browse conversations
+mosaic brain conversations
+mosaic brain conversations --project <projectId>
+```
+
+### `mosaic config` — CLI Configuration
+
+Read and write the `mosaic` CLI configuration file.
+
+```bash
+# Show full config
+mosaic config show
+
+# Get a value
+mosaic config get gateway.url
+
+# Set a value
+mosaic config set theme dark
+
+# Open in editor
+mosaic config edit
+
+# Print file path
+mosaic config path
+```
+
+### `mosaic forge` — AI Pipeline Management
+
+Interact with the Forge multi-stage AI delivery pipeline (intake → board review
+→ planning → coding → review → deploy).
+
+```bash
+# Start a new forge run for a brief
+mosaic forge run --brief "Add dark mode toggle to settings"
+
+# Check status of a running pipeline
+mosaic forge status
+mosaic forge status --run <runId>
+
+# Resume a paused or interrupted run
+mosaic forge resume --run <runId>
+
+# List available personas (board review evaluators)
+mosaic forge personas
+```
+
+### `mosaic gateway` — Gateway Lifecycle
+
+Install, authenticate with, and verify the Mosaic gateway service.
+
+```bash
+# Install gateway (guided)
+mosaic gateway install
+
+# Verify gateway health post-install
+mosaic gateway verify
+
+# Log in and save token
+mosaic gateway login
+
+# Rotate API token
+mosaic gateway config rotate-token
+
+# Recover token via BetterAuth cookie (lost-token recovery)
+mosaic gateway config recover-token
+```
+
+### `mosaic log` — Structured Log Access
+
+Query and stream structured logs from the gateway.
+
+```bash
+# Stream live logs
+mosaic log tail
+mosaic log tail --level warn
+
+# Search logs
+mosaic log search "database connection"
+mosaic log search --since 1h "error"
+
+# Export logs to file
+mosaic log export --output logs.json
+mosaic log export --since 24h --level error --output errors.json
+
+# Get/set log level
+mosaic log level
+mosaic log level debug
+```
+
+### `mosaic macp` — MACP Protocol
+
+Interact with the MACP credential resolution, gate runner, and event bus.
+
+```bash
+# List MACP tasks
+mosaic macp tasks
+mosaic macp tasks --status pending
+
+# Submit a new MACP task
+mosaic macp submit --type credential-resolve --payload '{"key":"OPENAI_API_KEY"}'
+
+# Run a gate check
+mosaic macp gate --gate quality-check
+
+# Stream MACP events
+mosaic macp events
+mosaic macp events --filter credential
+```
+
+### `mosaic memory` — Agent Memory
+
+Query and inspect the agent memory layer.
+
+```bash
+# Semantic search over memory
+mosaic memory search "previous decisions about auth"
+
+# Show memory statistics
+mosaic memory stats
+
+# Generate memory insights report
+mosaic memory insights
+
+# View stored preferences
+mosaic memory preferences
+mosaic memory preferences --set editor=neovim
+```
+
+### `mosaic queue` — Task Queue (Valkey)
+
+Manage the Valkey-backed task queue.
+
+```bash
+# List all queues
+mosaic queue list
+
+# Show queue statistics
+mosaic queue stats
+mosaic queue stats --queue agent-tasks
+
+# Pause a queue
+mosaic queue pause agent-tasks
+
+# Resume a paused queue
+mosaic queue resume agent-tasks
+
+# List jobs in a queue
+mosaic queue jobs agent-tasks
+mosaic queue jobs agent-tasks --status failed
+
+# Drain (empty) a queue
+mosaic queue drain agent-tasks
+```
+
+### `mosaic storage` — Object Storage
+
+Manage object storage tiers and data migrations.
+
+```bash
+# Show storage status and usage
+mosaic storage status
+
+# List available storage tiers
+mosaic storage tier
+
+# Export data from storage
+mosaic storage export --bucket agent-artifacts --output ./artifacts.tar.gz
+
+# Import data into storage
+mosaic storage import --bucket agent-artifacts --input ./artifacts.tar.gz
+
+# Migrate data between tiers
+mosaic storage migrate --from hot --to cold --older-than 30d
+```
+
+---
+
+## Telemetry
+
+Mosaic includes an OpenTelemetry-based telemetry system. Local telemetry
+(traces, metrics sent to Jaeger) is always available. Remote telemetry upload
+requires explicit opt-in.
+
+### Local Telemetry
+
+```bash
+# Show local OTEL collector / Jaeger status
+mosaic telemetry local status
+
+# Tail live OTEL spans
+mosaic telemetry local tail
+
+# Open Jaeger UI URL
+mosaic telemetry local jaeger
+```
+
+### Remote Telemetry
+
+Remote upload is a no-op (dry-run) until you opt in. Your consent state is
+persisted in the config file.
+
+```bash
+# Show current consent state
+mosaic telemetry status
+
+# Opt in to remote telemetry
+mosaic telemetry opt-in
+
+# Opt out (data stays local)
+mosaic telemetry opt-out
+
+# Test telemetry pipeline without uploading
+mosaic telemetry test
+
+# Upload telemetry (requires opt-in; dry-run otherwise)
+mosaic telemetry upload
+```