From 70e9f2c6bc3dde9014e0320bc079a374c4e02de1 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Sun, 15 Mar 2026 19:40:44 +0000 Subject: [PATCH] docs: user guide, admin guide, dev guide (closes #57) (#151) Co-authored-by: Jason Woltje Co-committed-by: Jason Woltje --- docs/guides/admin-guide.md | 311 ++++++++++++++++++++++ docs/guides/dev-guide.md | 515 +++++++++++++++++++++++++++++++++++++ docs/guides/user-guide.md | 238 +++++++++++++++++ 3 files changed, 1064 insertions(+) create mode 100644 docs/guides/admin-guide.md create mode 100644 docs/guides/dev-guide.md create mode 100644 docs/guides/user-guide.md diff --git a/docs/guides/admin-guide.md b/docs/guides/admin-guide.md new file mode 100644 index 0000000..b4745db --- /dev/null +++ b/docs/guides/admin-guide.md @@ -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 | diff --git a/docs/guides/dev-guide.md b/docs/guides/dev-guide.md new file mode 100644 index 0000000..df1002b --- /dev/null +++ b/docs/guides/dev-guide.md @@ -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 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. diff --git a/docs/guides/user-guide.md b/docs/guides/user-guide.md new file mode 100644 index 0000000..41ef13e --- /dev/null +++ b/docs/guides/user-guide.md @@ -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/`. 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 ` | `http://localhost:4000` | 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 +```