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

---

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

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

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

Or if installed globally:

```bash
mosaic --help
```

### Signing In

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