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

---

Getting Started

Prerequisites

Mosaic Stack requires a running gateway. Your administrator provides the URL (default: http://localhost:4000) 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

The CLI ships as part of the @mosaic/cli package:

# From the monorepo root
pnpm --filter @mosaic/cli build
node packages/cli/dist/cli.js --help

Or if installed globally:

mosaic --help

Signing In

mosaic login --gateway http://localhost:4000 --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:4000	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