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

README.md

@@ -7,7 +7,14 @@ Mosaic gives you a unified launcher for Claude Code, Codex, OpenCode, and Pi —
 ## Quick Install
 
 ```bash
-bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
+bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/mosaic-stack/raw/branch/main/tools/install.sh)
+```
+
+The installer auto-launches the setup wizard, which walks you through gateway install and verification. Flags for non-interactive use:
+
+```bash
+bash <(curl -fsSL …) --yes               # Accept all defaults
+bash <(curl -fsSL …) --yes --no-auto-launch  # Install only, skip wizard
 ```
 
 This installs both components:
@@ -17,10 +24,10 @@ This installs both components:
 | **Framework**           | Bash launcher, guides, runtime configs, tools, skills            | `~/.config/mosaic/`  |
 | **@mosaicstack/mosaic** | Unified `mosaic` CLI — TUI, gateway client, wizard, auto-updater | `~/.npm-global/bin/` |
 
-After install, set up your agent identity:
+After install, the wizard runs automatically or you can invoke it manually:
 
 ```bash
-mosaic init          # Interactive wizard
+mosaic wizard        # Full guided setup (gateway install → verify)
 ```
 
 ### Requirements
@@ -49,10 +56,32 @@ The launcher verifies your config, checks for `SOUL.md`, injects your `AGENTS.md
 
 ```bash
 mosaic tui                   # Interactive TUI connected to the gateway
-mosaic login                 # Authenticate with a gateway instance
+mosaic gateway login         # Authenticate with a gateway instance
 mosaic sessions list         # List active agent sessions
 ```
 
+### Gateway Management
+
+```bash
+mosaic gateway install       # Install and configure the gateway service
+mosaic gateway verify        # Post-install health check
+mosaic gateway login         # Authenticate and store a session token
+mosaic gateway config rotate-token    # Rotate your API token
+mosaic gateway config recover-token  # Recover a token via BetterAuth cookie
+```
+
+If you already have a gateway account but no token, use `mosaic gateway config recover-token` to retrieve one without recreating your account.
+
+### Configuration
+
+```bash
+mosaic config show           # Print full config as JSON
+mosaic config get <key>      # Read a specific key
+mosaic config set <key> <val># Write a key
+mosaic config edit           # Open config in $EDITOR
+mosaic config path           # Print config file path
+```
+
 ### Management
 
 ```bash
@@ -65,6 +94,80 @@ mosaic coord init            # Initialize a new orchestration mission
 mosaic prdy init             # Create a PRD via guided session
 ```
 
+### Sub-package Commands
+
+Each Mosaic sub-package exposes its API surface through the unified CLI:
+
+```bash
+# User management
+mosaic auth users list
+mosaic auth users create
+mosaic auth sso
+
+# Agent brain (projects, missions, tasks)
+mosaic brain projects
+mosaic brain missions
+mosaic brain tasks
+mosaic brain conversations
+
+# Agent forge pipeline
+mosaic forge run
+mosaic forge status
+mosaic forge resume
+mosaic forge personas
+
+# Structured logging
+mosaic log tail
+mosaic log search
+mosaic log export
+mosaic log level
+
+# MACP protocol
+mosaic macp tasks
+mosaic macp submit
+mosaic macp gate
+mosaic macp events
+
+# Agent memory
+mosaic memory search
+mosaic memory stats
+mosaic memory insights
+mosaic memory preferences
+
+# Task queue (Valkey)
+mosaic queue list
+mosaic queue stats
+mosaic queue pause
+mosaic queue resume
+mosaic queue jobs
+mosaic queue drain
+
+# Object storage
+mosaic storage status
+mosaic storage tier
+mosaic storage export
+mosaic storage import
+mosaic storage migrate
+```
+
+### Telemetry
+
+```bash
+# Local observability (OTEL / Jaeger)
+mosaic telemetry local status
+mosaic telemetry local tail
+mosaic telemetry local jaeger
+
+# Remote telemetry (dry-run by default)
+mosaic telemetry status
+mosaic telemetry opt-in
+mosaic telemetry opt-out
+mosaic telemetry test
+mosaic telemetry upload        # Dry-run unless opted in
+```
+
+Consent state is persisted in config. Remote upload is a no-op until you run `mosaic telemetry opt-in`.
+
 ## Development
 
 ### Prerequisites
@@ -76,7 +179,7 @@ mosaic prdy init             # Create a PRD via guided session
 ### Setup
 
 ```bash
-git clone git@git.mosaicstack.dev:mosaic/mosaic-stack.git
+git clone git@git.mosaicstack.dev:mosaicstack/mosaic-stack.git
 cd mosaic-stack
 
 # Start infrastructure (Postgres, Valkey, Jaeger)
@@ -131,8 +234,7 @@ mosaic-stack/
 │   ├── gateway/             NestJS API + WebSocket hub (Fastify, Socket.IO, OTEL)
 │   └── web/                 Next.js dashboard (React 19, Tailwind)
 ├── packages/
-│   ├── cli/                 Mosaic CLI — TUI, gateway client, wizard
+│   ├── mosaic/              Unified CLI — TUI, gateway client, wizard, sub-package commands
-│   ├── mosaic/              Framework — wizard, runtime detection, update checker
 │   ├── types/               Shared TypeScript contracts (Socket.IO typed events)
 │   ├── db/                  Drizzle ORM schema + migrations (pgvector)
 │   ├── auth/                BetterAuth configuration
@@ -153,7 +255,7 @@ mosaic-stack/
 │   ├── macp/                OpenClaw MACP runtime plugin
 │   └── mosaic-framework/    OpenClaw framework injection plugin
 ├── tools/
-│   └── install.sh           Unified installer (framework + npm CLI)
+│   └── install.sh           Unified installer (framework + npm CLI, --yes / --no-auto-launch)
 ├── scripts/agent/           Agent session lifecycle scripts
 ├── docker-compose.yml       Dev infrastructure
 └── .woodpecker/             CI pipeline configs
@@ -200,7 +302,7 @@ Each stage has a dispatch mode (`exec` for research/review, `yolo` for coding),
 Run the installer again — it handles upgrades automatically:
 
 ```bash
-bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
+bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/mosaic-stack/raw/branch/main/tools/install.sh)
 ```
 
 Or use the CLI:
@@ -215,10 +317,12 @@ The CLI also performs a background update check on every invocation (cached for
 ### Installer Flags
 
 ```bash
-bash tools/install.sh --check        # Version check only
+bash tools/install.sh --check           # Version check only
-bash tools/install.sh --framework    # Framework only (skip npm CLI)
+bash tools/install.sh --framework       # Framework only (skip npm CLI)
-bash tools/install.sh --cli          # npm CLI only (skip framework)
+bash tools/install.sh --cli             # npm CLI only (skip framework)
-bash tools/install.sh --ref v1.0     # Install from a specific git ref
+bash tools/install.sh --ref v1.0        # Install from a specific git ref
+bash tools/install.sh --yes             # Non-interactive, accept all defaults
+bash tools/install.sh --no-auto-launch  # Skip auto-launch of wizard
 ```
 
 ## Contributing

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
+bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/mosaic-stack/raw/branch/main/tools/install.sh)
-pnpm --filter @mosaicstack/mosaic build
+```
-node packages/mosaic/dist/cli.js --help
+
+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
+```

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicstack/mosaic",
-  "version": "0.0.21",
+  "version": "0.1.0",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/mosaic-stack.git",