239 lines
6.2 KiB
Markdown
239 lines
6.2 KiB
Markdown
# 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/mosaic` package:
|
|
|
|
```bash
|
|
# From the monorepo root
|
|
pnpm --filter @mosaicstack/mosaic build
|
|
node packages/mosaic/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
|
|
```
|