stack/docs/guides/user-guide.md

# Mosaic Stack — User Guide

## Table of Contents

1. [Getting Started](#getting-started)
2. [Chat Interface](#chat-interface)
3. [Projects](#projects)
4. [Tasks](#tasks)
5. [Settings](#settings)
6. [CLI Usage](#cli-usage)
7. [Sub-package Commands](#sub-package-commands)
8. [Telemetry](#telemetry)

---

## Getting Started

### Prerequisites

Mosaic Stack requires a running gateway. Your administrator provides the URL
(default: `http://localhost:14242`) and creates your account.

### Logging In (Web)

1. Navigate to the Mosaic web app (default: `http://localhost:3000`).
2. You are redirected to `/login` automatically.
3. Enter your email and password, then click **Sign in**.
4. On success you land on the **Chat** page.

### Registering an Account

If self-registration is enabled:

1. Go to `/register`.
2. Enter your name, email, and password.
3. Submit. You are signed in and redirected to Chat.

---

## Chat Interface

### Sending a Message

1. Type your message in the input bar at the bottom of the Chat page.
2. Press **Enter** to send.
3. The assistant response streams in real time. A spinner indicates the agent is
   processing.

### Streaming Responses

Responses appear token by token as the model generates them. You can read the
response while it is still being produced. The streaming indicator clears when
the response is complete.

### Conversation Management

- **New conversation**: Navigate to `/chat` or click **New Chat** in the sidebar.
  A new conversation ID is created automatically on your first message.
- **Resume a conversation**: Conversations are stored server-side. Refresh the
  page or navigate away and back to continue where you left off. The current
  conversation ID is shown in the URL.
- **Conversation list**: The sidebar shows recent conversations. Click any entry
  to switch.

### Model and Provider

The current model and provider are displayed in the chat header. To change them,
use the Settings page (see [Provider Settings](#providers)) or the CLI
`/model` and `/provider` commands.

---

## Projects

Projects group related missions and tasks. Navigate to **Projects** in the
sidebar.

### Creating a Project

1. Go to `/projects`.
2. Click **New Project**.
3. Enter a name and optional description.
4. Select a status: `active`, `paused`, `completed`, or `archived`.
5. Save. The project appears in the list.

### Viewing a Project

Click a project card to open its detail view at `/projects/<id>`. From here you
can see the project's missions, tasks, and metadata.

### Managing Tasks within a Project

Tasks are linked to projects and optionally to missions. See [Tasks](#tasks) for
full details. On the project detail page, the task list is filtered to the
selected project.

---

## Tasks

Navigate to **Tasks** in the sidebar to see all tasks across all projects.

### Task Statuses

| Status        | Meaning                  |
| ------------- | ------------------------ |
| `not-started` | Not yet started          |
| `in-progress` | Actively being worked on |
| `blocked`     | Waiting on something     |
| `done`        | Completed                |
| `cancelled`   | No longer needed         |

### Creating a Task

1. Go to `/tasks`.
2. Click **New Task**.
3. Enter a title, optional description, and link to a project or mission.
4. Set the status and priority.
5. Save.

### Updating a Task

Click a task to open its detail panel. Edit the fields inline and save.

---

## Settings

Navigate to **Settings** in the sidebar (or `/settings`) to manage your profile,
appearance, and providers.

### Profile Tab

- **Name**: Display name shown in the UI.
- **Email**: Read-only; contact your administrator to change email.
- Changes save automatically when you click **Save Profile**.

### Appearance Tab

- **Theme**: Choose `light`, `dark`, or `system`.
- The theme preference is saved to your account and applies on all devices.

### Notifications Tab

Configure notification preferences (future feature; placeholder in the current
release).

### Providers Tab

View all configured LLM providers and their models.

- **Test Connection**: Click **Test** next to a provider to check reachability.
  The result shows latency and discovered models.
- Provider configuration is managed by your administrator via environment
  variables. See the [Admin Guide](./admin-guide.md) for setup.

---

## CLI Usage

The `mosaic` CLI provides a terminal interface to the same gateway API.

### Installation

Install via the Mosaic installer:

```bash
curl -fsSL https://mosaicstack.dev/install.sh | bash
```

Or use the direct URL:

```bash
bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/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:

```bash
mosaic --help
```

### 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
```

You are prompted for a password if `--password` is not supplied. The session
cookie is saved locally and reused on subsequent commands.

### Launching the TUI

```bash
mosaic tui
```

Options:

| Flag                    | Default                  | Description                        |
| ----------------------- | ------------------------ | ---------------------------------- |
| `--gateway <url>`       | `http://localhost:14242` | Gateway URL                        |
| `--conversation <id>`   | —                        | Resume a specific conversation     |
| `--model <modelId>`     | server default           | Model to use (e.g. `llama3.2`)     |
| `--provider <provider>` | server default           | Provider (e.g. `ollama`, `openai`) |

If no valid session exists you are prompted to sign in before the TUI launches.

### TUI Slash Commands

Inside the TUI, type a `/` command and press Enter:

| Command                | Description                    |
| ---------------------- | ------------------------------ |
| `/model <modelId>`     | Switch to a different model    |
| `/provider <provider>` | Switch to a different provider |
| `/models`              | List available models          |
| `/exit` or `/quit`     | Exit the TUI                   |

### Session Management

```bash
# List saved sessions
mosaic sessions list

# Resume a session
mosaic sessions resume <sessionId>

# Destroy a session
mosaic sessions destroy <sessionId>
```

### Other Commands

```bash
# Run the Mosaic installation wizard
mosaic wizard

# PRD wizard (generate product requirement documents)
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
```