mosaicstack/stack
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases 11 Wiki Activity

docs: user guide, admin guide, dev guide (closes #57) (#151)
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details

Browse Source 
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:
Jason Woltje
2026-03-15 19:40:44 +00:00
committed by jason.woltje
parent a760401407
commit 70e9f2c6bc
3 changed files with 1064 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

311
docs/guides/admin-guide.md Normal file
View File

@@ -0,0 +1,311 @@
# Mosaic Stack — Admin Guide
## Table of Contents
1. [User Management](#user-management)
2. [System Health Monitoring](#system-health-monitoring)
3. [Provider Configuration](#provider-configuration)
4. [MCP Server Configuration](#mcp-server-configuration)
5. [Environment Variables Reference](#environment-variables-reference)
---
## User Management
Admins access user management at `/admin` in the web dashboard. All admin
endpoints require a session with `role = admin`.
### Creating a User
**Via the web admin panel:**
1. Navigate to `/admin`.
2. Click **Create User**.
3. Enter name, email, password, and role (`admin` or `member`).
4. Submit.
**Via the API:**
```http
POST /api/admin/users
Content-Type: application/json
{
"name": "Jane Doe",
"email": "jane@example.com",
"password": "securepassword",
"role": "member"
}
```
Passwords are hashed by BetterAuth before storage. Passwords are never stored in
plaintext.
### Roles
| Role | Permissions |
| -------- | --------------------------------------------------------------------- |
| `admin` | Full access: user management, health, all agent tools |
| `member` | Standard user access; agent tool set restricted by `AGENT_USER_TOOLS` |
### Updating a User's Role
```http
PATCH /api/admin/users/:id/role
Content-Type: application/json
{ "role": "admin" }
```
### Banning and Unbanning
Banned users cannot sign in. Provide an optional reason:
```http
POST /api/admin/users/:id/ban
Content-Type: application/json
{ "reason": "Violated terms of service" }
```
To lift a ban:
```http
POST /api/admin/users/:id/unban
```
### Deleting a User
```http
DELETE /api/admin/users/:id
```
This permanently deletes the user. Related data (sessions, accounts) is
cascade-deleted. Conversations and tasks reference the user via `owner_id`
which is set to `NULL` on delete (`set null`).
---
## System Health Monitoring
The health endpoint is available to admin users only.
```http
GET /api/admin/health
```
Sample response:
```json
{
"status": "ok",
"database": { "status": "ok", "latencyMs": 2 },
"cache": { "status": "ok", "latencyMs": 1 },
"agentPool": { "activeSessions": 3 },
"providers": [{ "id": "ollama", "name": "ollama", "available": true, "modelCount": 3 }],
"checkedAt": "2026-03-15T12:00:00.000Z"
}
```
`status` is `ok` when both database and cache pass. It is `degraded` when either
service fails.
The web admin panel at `/admin` polls this endpoint and renders the results in a
status dashboard.
---
## Provider Configuration
Providers are configured via environment variables and loaded at gateway startup.
No restart-free hot reload is supported; the gateway must be restarted after
changing provider env vars.
### Ollama
Set `OLLAMA_BASE_URL` (or the legacy `OLLAMA_HOST`) to the base URL of your
Ollama instance:
```env
OLLAMA_BASE_URL=http://localhost:11434
```
Specify which models to expose (comma-separated):
```env
OLLAMA_MODELS=llama3.2,codellama,mistral
```
Default when unset: `llama3.2,codellama,mistral`.
The gateway registers Ollama models using the OpenAI-compatible completions API
(`/v1/chat/completions`).
### Custom Providers (OpenAI-compatible APIs)
Any OpenAI-compatible API (LM Studio, llama.cpp HTTP server, etc.) can be
registered via `MOSAIC_CUSTOM_PROVIDERS`. The value is a JSON array:
```env
MOSAIC_CUSTOM_PROVIDERS='[
{
"id": "lmstudio",
"name": "LM Studio",
"baseUrl": "http://localhost:1234",
"models": ["mistral-7b-instruct"]
}
]'
```
Each entry must include:
| Field | Required | Description |
| --------- | -------- | ----------------------------------- |
| `id` | Yes | Unique provider identifier |
| `name` | Yes | Display name |
| `baseUrl` | Yes | API base URL (no trailing slash) |
| `models` | Yes | Array of model ID strings to expose |
| `apiKey` | No | API key if required by the endpoint |
### Testing Provider Connectivity
From the web admin panel or settings page, click **Test** next to a provider.
This calls:
```http
POST /api/agent/providers/:id/test
```
The response includes `reachable`, `latencyMs`, and optionally
`discoveredModels`.
---
## MCP Server Configuration
The gateway can connect to external MCP (Model Context Protocol) servers and
expose their tools to agent sessions.
Set `MCP_SERVERS` to a JSON array of server configurations:
```env
MCP_SERVERS='[
{
"name": "my-tools",
"url": "http://localhost:3001/mcp",
"headers": {
"Authorization": "Bearer my-token"
}
}
]'
```
Each entry:
| Field | Required | Description |
| --------- | -------- | ----------------------------------- |
| `name` | Yes | Unique server name |
| `url` | Yes | MCP server URL (`/mcp` endpoint) |
| `headers` | No | Additional HTTP headers (e.g. auth) |
On gateway startup, each configured server is connected and its tools are
discovered. Tools are bridged into the Pi SDK tool format and become available
in agent sessions.
The gateway itself also exposes an MCP server endpoint at `POST /mcp` for
external clients. Authentication requires a valid BetterAuth session (cookie or
`Authorization` header).
---
## Environment Variables Reference
### Required
| Variable | Description |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | Secret key for BetterAuth session signing. Must be set or gateway will not start. |
| `DATABASE_URL` | PostgreSQL connection string. Default: `postgresql://mosaic:mosaic@localhost:5433/mosaic` |
### Gateway
| Variable | Default | Description |
| --------------------- | ----------------------- | ---------------------------------------------- |
| `GATEWAY_PORT` | `4000` | Port the gateway listens on |
| `GATEWAY_CORS_ORIGIN` | `http://localhost:3000` | Allowed CORS origin for browser clients |
| `BETTER_AUTH_URL` | `http://localhost:4000` | Public URL of the gateway (used by BetterAuth) |
### SSO (Optional)
| Variable | Description |
| ------------------------- | ------------------------------ |
| `AUTHENTIK_CLIENT_ID` | Authentik OAuth2 client ID |
| `AUTHENTIK_CLIENT_SECRET` | Authentik OAuth2 client secret |
| `AUTHENTIK_ISSUER` | Authentik OIDC issuer URL |
All three Authentik variables must be set together. If only `AUTHENTIK_CLIENT_ID`
is set, a warning is logged and SSO is disabled.
### Agent
| Variable | Default | Description |
| ------------------------ | --------------- | ------------------------------------------------------- |
| `AGENT_FILE_SANDBOX_DIR` | `process.cwd()` | Root directory for file/git/shell tool access |
| `AGENT_SYSTEM_PROMPT` | — | Platform-level system prompt injected into all sessions |
| `AGENT_USER_TOOLS` | all tools | Comma-separated allowlist of tools for non-admin users |
### Providers
| Variable | Default | Description |
| ------------------------- | ---------------------------- | ------------------------------------------------ |
| `OLLAMA_BASE_URL` | — | Ollama API base URL |
| `OLLAMA_HOST` | — | Alias for `OLLAMA_BASE_URL` (legacy) |
| `OLLAMA_MODELS` | `llama3.2,codellama,mistral` | Comma-separated Ollama model IDs |
| `MOSAIC_CUSTOM_PROVIDERS` | — | JSON array of custom OpenAI-compatible providers |
### Memory and Embeddings
| Variable | Default | Description |
| ----------------------- | --------------------------- | ---------------------------------------------------- |
| `OPENAI_API_KEY` | — | API key for OpenAI embedding and summarization calls |
| `EMBEDDING_API_URL` | `https://api.openai.com/v1` | Base URL for embedding API |
| `EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model ID |
| `SUMMARIZATION_API_URL` | `https://api.openai.com/v1` | Base URL for log summarization API |
| `SUMMARIZATION_MODEL` | `gpt-4o-mini` | Model used for log summarization |
| `SUMMARIZATION_CRON` | `0 */6 * * *` | Cron schedule for log summarization (every 6 hours) |
| `TIER_MANAGEMENT_CRON` | `0 3 * * *` | Cron schedule for log tier management (daily at 3am) |
### MCP
| Variable | Description |
| ------------- | ------------------------------------------------ |
| `MCP_SERVERS` | JSON array of external MCP server configurations |
### Plugins
| Variable | Description |
| ---------------------- | ------------------------------------------------------------------------- |
| `DISCORD_BOT_TOKEN` | Discord bot token (enables Discord plugin) |
| `DISCORD_GUILD_ID` | Discord guild/server ID |
| `DISCORD_GATEWAY_URL` | Gateway URL for Discord plugin to call (default: `http://localhost:4000`) |
| `TELEGRAM_BOT_TOKEN` | Telegram bot token (enables Telegram plugin) |
| `TELEGRAM_GATEWAY_URL` | Gateway URL for Telegram plugin to call |
### Observability
| Variable | Default | Description |
| ----------------------------- | ----------------------- | -------------------------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | OpenTelemetry collector endpoint |
| `OTEL_SERVICE_NAME` | `mosaic-gateway` | Service name in traces |
### Web App
| Variable | Default | Description |
| ------------------------- | ----------------------- | -------------------------------------- |
| `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:4000` | Gateway URL used by the Next.js client |
### Coordination
| Variable | Default | Description |
| ----------------------- | ----------------------------- | ------------------------------------------ |
| `MOSAIC_WORKSPACE_ROOT` | monorepo root (auto-detected) | Root path for mission workspace operations |

515
docs/guides/dev-guide.md Normal file
View File

@@ -0,0 +1,515 @@
# Mosaic Stack — Developer Guide
## Table of Contents
1. [Architecture Overview](#architecture-overview)
2. [Local Development Setup](#local-development-setup)
3. [Building and Testing](#building-and-testing)
4. [Adding New Agent Tools](#adding-new-agent-tools)
5. [Adding New MCP Tools](#adding-new-mcp-tools)
6. [Database Schema and Migrations](#database-schema-and-migrations)
7. [API Endpoint Reference](#api-endpoint-reference)
---
## Architecture Overview
Mosaic Stack is a TypeScript monorepo managed with **pnpm workspaces** and
**Turborepo**.
```
mosaic-mono-v1/
├── apps/
│ ├── gateway/ # NestJS + Fastify API server
│ └── web/ # Next.js 16 + React 19 web dashboard
├── packages/
│ ├── agent/ # Agent session types (shared)
│ ├── auth/ # BetterAuth configuration
│ ├── brain/ # Structured data layer (projects, tasks, missions)
│ ├── cli/ # mosaic CLI and TUI (Ink)
│ ├── coord/ # Mission coordination engine
│ ├── db/ # Drizzle ORM schema, migrations, client
│ ├── design-tokens/ # Shared design system tokens
│ ├── log/ # Agent log ingestion and tiering
│ ├── memory/ # Preference and insight storage
│ ├── mosaic/ # Install wizard and bootstrap utilities
│ ├── prdy/ # PRD wizard CLI
│ ├── quality-rails/ # Code quality scaffolder CLI
│ ├── queue/ # Valkey-backed task queue
│ └── types/ # Shared TypeScript types
├── docker/ # Dockerfile(s) for containerized deployment
├── infra/ # Infra config (OTEL collector, pg-init scripts)
├── docker-compose.yml # Local services (Postgres, Valkey, OTEL, Jaeger)
└── CLAUDE.md # Project conventions for AI coding agents
```
### Key Technology Choices
| Concern | Technology |
| ----------------- | ---------------------------------------- |
| API framework | NestJS with Fastify adapter |
| Web framework | Next.js 16 (App Router), React 19 |
| ORM | Drizzle ORM |
| Database | PostgreSQL 17 + pgvector extension |
| Auth | BetterAuth |
| Agent harness | Pi SDK (`@mariozechner/pi-coding-agent`) |
| Queue | Valkey 8 (Redis-compatible) |
| Build | pnpm workspaces + Turborepo |
| CI | Woodpecker CI |
| Observability | OpenTelemetry → Jaeger |
| Module resolution | NodeNext (ESM everywhere) |
### Module System
All packages use `"type": "module"` and NodeNext resolution. Import paths must
include the `.js` extension even when the source file is `.ts`.
NestJS `@Inject()` decorators must be used explicitly because `tsx`/`esbuild`
does not support `emitDecoratorMetadata`.
---
## Local Development Setup
### Prerequisites
- Node.js 20+
- pnpm 9+
- Docker and Docker Compose
### 1. Clone and Install Dependencies
```bash
git clone <repo-url> mosaic-mono-v1
cd mosaic-mono-v1
pnpm install
```
### 2. Start Infrastructure Services
```bash
docker compose up -d
```
This starts:
| Service | Port | Description |
| ------------------------ | -------------- | -------------------- |
| PostgreSQL 17 + pgvector | `5433` (host) | Primary database |
| Valkey 8 | `6380` (host) | Queue and cache |
| OpenTelemetry Collector | `4317`, `4318` | OTEL gRPC and HTTP |
| Jaeger | `16686` | Distributed trace UI |
### 3. Configure Environment
Create a `.env` file in the monorepo root:
```env
# Database (matches docker-compose defaults)
DATABASE_URL=postgresql://mosaic:mosaic@localhost:5433/mosaic
# Auth (required — generate a random 32+ char string)
BETTER_AUTH_SECRET=change-me-to-a-random-secret
# Gateway
GATEWAY_PORT=4000
GATEWAY_CORS_ORIGIN=http://localhost:3000
# Web
NEXT_PUBLIC_GATEWAY_URL=http://localhost:4000
# Optional: Ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODELS=llama3.2
```
The gateway loads `.env` from the monorepo root via `dotenv` at startup
(`apps/gateway/src/main.ts`).
### 4. Push the Database Schema
```bash
pnpm --filter @mosaic/db db:push
```
This applies the Drizzle schema directly to the database (development only; use
migrations in production).
### 5. Start the Gateway
```bash
pnpm --filter @mosaic/gateway exec tsx src/main.ts
```
The gateway starts on port `4000` by default.
### 6. Start the Web App
```bash
pnpm --filter @mosaic/web dev
```
The web app starts on port `3000` by default.
---
## Building and Testing
### TypeScript Typecheck
```bash
pnpm typecheck
```
Runs `tsc --noEmit` across all packages in dependency order via Turborepo.
### Lint
```bash
pnpm lint
```
Runs ESLint across all packages. Config is in `eslint.config.mjs` at the root.
### Format Check
```bash
pnpm format:check
```
Runs Prettier in check mode. To auto-fix:
```bash
pnpm format
```
### Tests
```bash
pnpm test
```
Runs Vitest across all packages. The workspace config is at
`vitest.workspace.ts`.
### Build
```bash
pnpm build
```
Builds all packages and apps in dependency order.
### Pre-Push Gates (MANDATORY)
All three must pass before any push:
```bash
pnpm format:check && pnpm typecheck && pnpm lint
```
A pre-push hook enforces this mechanically.
---
## Adding New Agent Tools
Agent tools are Pi SDK `ToolDefinition` objects registered in
`apps/gateway/src/agent/agent.service.ts`.
### 1. Create a Tool Factory File
Add a new file in `apps/gateway/src/agent/tools/`:
```typescript
// apps/gateway/src/agent/tools/my-tools.ts
import { Type } from '@sinclair/typebox';
import type { ToolDefinition } from '@mariozechner/pi-coding-agent';
export function createMyTools(): ToolDefinition[] {
const myTool: ToolDefinition = {
name: 'my_tool_name',
label: 'Human Readable Label',
description: 'What this tool does.',
parameters: Type.Object({
input: Type.String({ description: 'The input parameter' }),
}),
async execute(_toolCallId, params) {
const { input } = params as { input: string };
const result = `Processed: ${input}`;
return {
content: [{ type: 'text' as const, text: result }],
details: undefined,
};
},
};
return [myTool];
}
```
### 2. Register the Tools in AgentService
In `apps/gateway/src/agent/agent.service.ts`, import and call your factory
alongside the existing tool registrations:
```typescript
import { createMyTools } from './tools/my-tools.js';
// Inside the session creation logic where tools are assembled:
const tools: ToolDefinition[] = [
...createBrainTools(this.brain),
...createCoordTools(this.coordService),
...createMemoryTools(this.memory, this.embeddingService),
...createFileTools(sandboxDir),
...createGitTools(sandboxDir),
...createShellTools(sandboxDir),
...createWebTools(),
...createMyTools(), // Add this line
...mcpTools,
...skillTools,
];
```
### 3. Export from the Tools Index
Add an export to `apps/gateway/src/agent/tools/index.ts`:
```typescript
export { createMyTools } from './my-tools.js';
```
### 4. Typecheck and Test
```bash
pnpm typecheck
pnpm test
```
---
## Adding New MCP Tools
Mosaic connects to external MCP servers via `McpClientService`. To expose tools
from a new MCP server:
### 1. Run an MCP Server
Implement a standard MCP server that exposes tools via the streamable HTTP
transport or SSE transport. The server must accept connections at a `/mcp`
endpoint.
### 2. Configure `MCP_SERVERS`
In your `.env`:
```env
MCP_SERVERS='[{"name":"my-server","url":"http://localhost:3001/mcp"}]'
```
With authentication:
```env
MCP_SERVERS='[{"name":"secure-server","url":"http://my-server/mcp","headers":{"Authorization":"Bearer token"}}]'
```
### 3. Restart the Gateway
On startup, `McpClientService` (`apps/gateway/src/mcp-client/mcp-client.service.ts`)
connects to each configured server, calls `tools/list`, and bridges the results
to Pi SDK `ToolDefinition` format. These tools become available in all new agent
sessions.
### Tool Naming
Bridged MCP tool names are taken directly from the MCP server's tool manifest.
Ensure names do not conflict with built-in tools (check
`apps/gateway/src/agent/tools/`).
---
## Database Schema and Migrations
The schema lives in a single file:
`packages/db/src/schema.ts`
### Schema Overview
| Table | Purpose |
| -------------------- | ------------------------------------------------- |
| `users` | User accounts (BetterAuth-compatible) |
| `sessions` | Auth sessions |
| `accounts` | OAuth accounts |
| `verifications` | Email verification tokens |
| `projects` | Project records |
| `missions` | Mission records (linked to projects) |
| `tasks` | Task records (linked to projects and/or missions) |
| `conversations` | Chat conversation metadata |
| `messages` | Individual chat messages |
| `preferences` | Per-user key-value preference store |
| `insights` | Vector-embedded memory insights |
| `agent_logs` | Agent interaction logs (hot/warm/cold tiers) |
| `skills` | Installed agent skills |
| `summarization_jobs` | Log summarization job tracking |
The `insights` table uses a `vector(1536)` column (pgvector) for semantic search.
### Development: Push Schema
Apply schema changes directly to the dev database (no migration files created):
```bash
pnpm --filter @mosaic/db db:push
```
### Generating Migrations
For production-safe, versioned changes:
```bash
pnpm --filter @mosaic/db db:generate
```
This creates a new SQL migration file in `packages/db/drizzle/`.
### Running Migrations
```bash
pnpm --filter @mosaic/db db:migrate
```
### Drizzle Config
Config is at `packages/db/drizzle.config.ts`. The schema file path and output
directory are defined there.
### Adding a New Table
1. Add the table definition to `packages/db/src/schema.ts`.
2. Export it from `packages/db/src/index.ts`.
3. Run `pnpm --filter @mosaic/db db:push` (dev) or
`pnpm --filter @mosaic/db db:generate && pnpm --filter @mosaic/db db:migrate`
(production).
---
## API Endpoint Reference
All endpoints are served by the gateway at `http://localhost:4000` by default.
### Authentication
Authentication uses BetterAuth session cookies. The auth handler is mounted at
`/api/auth/*` via a Fastify low-level hook in
`apps/gateway/src/auth/auth.controller.ts`.
| Endpoint | Method | Description |
| ------------------------- | ------ | -------------------------------- |
| `/api/auth/sign-in/email` | POST | Sign in with email/password |
| `/api/auth/sign-up/email` | POST | Register a new account |
| `/api/auth/sign-out` | POST | Sign out (clears session cookie) |
| `/api/auth/get-session` | GET | Returns the current session |
### Chat
WebSocket namespace `/chat` (Socket.IO). Authentication via session cookie.
Events sent by the client:
| Event | Payload | Description |
| --------- | --------------------------------------------------- | -------------- |
| `message` | `{ content, conversationId?, provider?, modelId? }` | Send a message |
Events emitted by the server:
| Event | Payload | Description |
| ------- | --------------------------- | ---------------------- |
| `token` | `{ token, conversationId }` | Streaming token |
| `end` | `{ conversationId }` | Stream complete |
| `error` | `{ message }` | Error during streaming |
HTTP endpoints (`apps/gateway/src/chat/chat.controller.ts`):
| Endpoint | Method | Auth | Description |
| -------------------------------------- | ------ | ---- | ------------------------------- |
| `/api/chat/conversations` | GET | User | List conversations |
| `/api/chat/conversations/:id/messages` | GET | User | Get messages for a conversation |
### Admin
All admin endpoints require `role = admin`.
| Endpoint | Method | Description |
| --------------------------------- | ------ | -------------------- |
| `GET /api/admin/users` | GET | List all users |
| `GET /api/admin/users/:id` | GET | Get a single user |
| `POST /api/admin/users` | POST | Create a user |
| `PATCH /api/admin/users/:id/role` | PATCH | Update user role |
| `POST /api/admin/users/:id/ban` | POST | Ban a user |
| `POST /api/admin/users/:id/unban` | POST | Unban a user |
| `DELETE /api/admin/users/:id` | DELETE | Delete a user |
| `GET /api/admin/health` | GET | System health status |
### Agent / Providers
| Endpoint | Method | Auth | Description |
| ------------------------------------ | ------ | ---- | ----------------------------------- |
| `GET /api/agent/providers` | GET | User | List all providers and their models |
| `GET /api/agent/providers/models` | GET | User | List available models |
| `POST /api/agent/providers/:id/test` | POST | User | Test provider connectivity |
### Projects / Brain
| Endpoint | Method | Auth | Description |
| -------------------------------- | ------ | ---- | ---------------- |
| `GET /api/brain/projects` | GET | User | List projects |
| `POST /api/brain/projects` | POST | User | Create a project |
| `GET /api/brain/projects/:id` | GET | User | Get a project |
| `PATCH /api/brain/projects/:id` | PATCH | User | Update a project |
| `DELETE /api/brain/projects/:id` | DELETE | User | Delete a project |
| `GET /api/brain/tasks` | GET | User | List tasks |
| `POST /api/brain/tasks` | POST | User | Create a task |
| `GET /api/brain/tasks/:id` | GET | User | Get a task |
| `PATCH /api/brain/tasks/:id` | PATCH | User | Update a task |
| `DELETE /api/brain/tasks/:id` | DELETE | User | Delete a task |
### Memory / Preferences
| Endpoint | Method | Auth | Description |
| ----------------------------- | ------ | ---- | -------------------- |
| `GET /api/memory/preferences` | GET | User | Get user preferences |
| `PUT /api/memory/preferences` | PUT | User | Upsert a preference |
### MCP Server (Gateway-side)
| Endpoint | Method | Auth | Description |
| ----------- | ------ | --------------------------------------------- | ----------------------------- |
| `POST /mcp` | POST | User (session cookie or Authorization header) | MCP streamable HTTP transport |
| `GET /mcp` | GET | User | MCP SSE stream reconnect |
### Skills
| Endpoint | Method | Auth | Description |
| ------------------------ | ------ | ----- | --------------------- |
| `GET /api/skills` | GET | User | List installed skills |
| `POST /api/skills` | POST | Admin | Install a skill |
| `PATCH /api/skills/:id` | PATCH | Admin | Update a skill |
| `DELETE /api/skills/:id` | DELETE | Admin | Remove a skill |
### Coord (Mission Coordination)
| Endpoint | Method | Auth | Description |
| ------------------------------- | ------ | ---- | ---------------- |
| `GET /api/coord/missions` | GET | User | List missions |
| `POST /api/coord/missions` | POST | User | Create a mission |
| `GET /api/coord/missions/:id` | GET | User | Get a mission |
| `PATCH /api/coord/missions/:id` | PATCH | User | Update a mission |
### Observability
OpenTelemetry traces are exported to the OTEL collector (`OTEL_EXPORTER_OTLP_ENDPOINT`).
View traces in Jaeger at `http://localhost:16686`.
Tracing is initialized before NestJS bootstrap in
`apps/gateway/src/tracing.ts`. The import order in `apps/gateway/src/main.ts`
is intentional: `import './tracing.js'` must come before any NestJS imports.

238
docs/guides/user-guide.md Normal file
View 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
```