docs: user guide, admin guide, dev guide (closes #57) (#151)
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>
This commit was merged in pull request #151.
This commit is contained in:
238
docs/guides/user-guide.md
Normal file
238
docs/guides/user-guide.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# 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: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](#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 `@mosaic/cli` package:
|
||||
|
||||
```bash
|
||||
# From the monorepo root
|
||||
pnpm --filter @mosaic/cli build
|
||||
node packages/cli/dist/cli.js --help
|
||||
```
|
||||
|
||||
Or if installed globally:
|
||||
|
||||
```bash
|
||||
mosaic --help
|
||||
```
|
||||
|
||||
### Signing In
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```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
|
||||
```
|
||||
Reference in New Issue
Block a user