# 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/`. 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 ` | `http://localhost:14242` | Gateway URL | | `--conversation ` | — | Resume a specific conversation | | `--model ` | server default | Model to use (e.g. `llama3.2`) | | `--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 ` | Switch to a different model | | `/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 # Destroy a session mosaic sessions destroy ``` ### Other Commands ```bash # Run the Mosaic installation wizard mosaic wizard # PRD wizard (generate product requirement documents) mosaic prdy # Quality rails scaffolder mosaic quality-rails ```