stack/docs/guides/user-guide.md

Mosaic Stack — User Guide

Table of Contents

1. Getting Started
2. Chat Interface
3. Projects
4. Tasks
5. Settings
6. CLI Usage
7. Sub-package Commands
8. 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) 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 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 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://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:

--yes               # Accept all defaults
--no-auto-launch    # Skip auto-launch of wizard after install

Or if installed globally:

mosaic --help

First-Run Wizard

After install the wizard launches automatically. You can re-run it at any time:

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

# 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

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

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

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

# List saved sessions
mosaic sessions list

# Resume a session
mosaic sessions resume <sessionId>

# Destroy a session
mosaic sessions destroy <sessionId>

Other Commands

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

# 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).

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

# 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).

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

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

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

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

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

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

# 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

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

# 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