docs: establish canonical documentation architecture (#1210)

2026-08-13 17:56:13 +00:00
parent f82307c4dc
commit 7a6fb024b4
241 changed files with 4722 additions and 1579 deletions
@@ -0,0 +1,621 @@
+# 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)
+7. [Sub-package Commands](#sub-package-commands)
+8. [Telemetry](#telemetry)
+9. [Local Fleet Canary](./fleet-local-canary.md)
+
+---
+
+## 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
+
+Install via the Mosaic installer:
+
+```bash
+curl -fsSL https://mosaicstack.dev/install.sh | bash
+```
+
+Or use the direct URL:
+
+```bash
+bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh)
+```
+
+The installer places the `mosaic` binary at `~/.npm-global/bin/mosaic`.
+
+Install lanes:
+
+| Lane                     | Command                               | Source                                                                                       |
+| ------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Stable                   | `bash tools/install.sh`               | npm `@mosaicstack/mosaic@latest` + `main`                                                    |
+| Prerelease integration   | `bash tools/install.sh --next`        | Fast npm `@mosaicstack/mosaic@next` + `@mosaicstack/gateway@next`; source fallback at `next` |
+| Contributor/source build | `bash tools/install.sh --dev --ref X` | Build-from-source at the requested ref                                                       |
+
+`--next` is fast-by-default from the Gitea npm `next` dist-tag and falls back to a source build at the permanent `next` branch if the dist-tag is missing or unreachable. Explicit `--ref` or `MOSAIC_REF` still wins and uses the source path.
+Flags for non-interactive use:
+
+```bash
+--yes               # Accept all defaults
+--no-auto-launch    # Skip auto-launch of wizard after install
+```
+
+Unrecognized flags or positional arguments fail before installation starts and print the supported-option usage.
+
+Or if installed globally:
+
+```bash
+mosaic --help
+```
+
+### First-Run Wizard
+
+After install the wizard launches automatically. You can re-run it at any time:
+
+```bash
+mosaic wizard
+```
+
+The wizard guides you through:
+
+1. Gateway discovery or installation (`mosaic gateway install`)
+2. Authentication (`mosaic gateway login`)
+3. Post-install health check (`mosaic gateway verify`)
+
+### Gateway Login and Token Recovery
+
+```bash
+# Authenticate with a gateway and save a session token
+mosaic gateway login
+
+# Verify the gateway is reachable and responding
+mosaic gateway verify
+
+# Rotate your current API token
+mosaic gateway config rotate-token
+
+# Recover a token via BetterAuth cookie (for accounts with no token)
+mosaic gateway config recover-token
+```
+
+If you have an existing gateway account but lost your token (common after a
+reinstall), use `mosaic gateway config recover-token` to retrieve a new one
+without recreating your account.
+
+### Configuration
+
+```bash
+# Print full config as JSON
+mosaic config show
+
+# Read a specific key
+mosaic config get gateway.url
+
+# Write a key
+mosaic config set gateway.url http://localhost:14242
+
+# Open config in $EDITOR
+mosaic config edit
+
+# Print config file path
+mosaic config path
+```
+
+### Signing In (Legacy)
+
+```bash
+mosaic login --gateway http://localhost:14242 --email [email protected]
+```
+
+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
+```
+
+---
+
+### Claude Code Skill Registration
+
+Mosaic stores canonical skills under `~/.config/mosaic/skills/`. Claude Code scans
+`~/.claude/skills/`, so Mosaic maintains one symlink per skill between those
+directories.
+
+```bash
+mosaic skill list
+mosaic skill register <name>
+mosaic skill unregister <name>
+```
+
+- `register` is idempotent and repairs a dangling Mosaic-owned link. Names use
+  the safe grammar `[A-Za-z0-9][A-Za-z0-9._-]*`; files, directories, foreign
+  symlinks, path traversal, absolute paths, and names beginning with `-` are
+  refused.
+- `unregister` is idempotent when no entry exists. It removes only symlinks that
+  point inside `~/.config/mosaic/skills/`; foreign entries are never removed.
+- `list` reports `registered`, `unregistered`, `dangling`, `foreign`,
+  `foreign-dangling`, or `misdirected` for each canonical or Claude entry.
+
+Install, wizard finalization, and `mosaic update` framework re-seeding reconcile
+every canonical skill automatically. A skill directory added after initial
+setup therefore receives its Claude bridge without a per-skill code change or
+manual `ln -s`. If Claude Code is already running, use `/reload-skills` or start
+a new session after registration so its in-process skill registry rescans.
+
+This command group is Claude-only in M1. Pi can consume Mosaic's canonical skill
+root through its Mosaic launcher configuration and does not need this Claude
+bridge. Codex has a separate link path managed by the legacy full skill-sync
+script; equivalent lifecycle management remains follow-up scope and is not
+changed here.
+
+## Sub-package Commands
+
+Each Mosaic sub-package exposes its full API surface through the `mosaic` CLI.
+All sub-package commands accept `--help` for usage details.
+
+### `mosaic auth` — User & Authentication Management
+
+Manage gateway users, SSO providers, and active sessions.
+
+```bash
+# List all users
+mosaic auth users list
+
+# Create a new user
+mosaic auth users create --email [email protected] --name "Alice"
+
+# Delete a user
+mosaic auth users delete <userId>
+
+# List configured SSO providers
+mosaic auth sso
+
+# List active sessions
+mosaic auth sessions list
+
+# Revoke a session
+mosaic auth sessions revoke <sessionId>
+```
+
+### `mosaic brain` — Projects, Missions, Tasks, Conversations
+
+Browse and manage the brain data layer (PostgreSQL-backed project/mission/task
+store).
+
+```bash
+# List all projects
+mosaic brain projects
+
+# List missions for a project
+mosaic brain missions --project <projectId>
+
+# List tasks
+mosaic brain tasks --status in-progress
+
+# Browse conversations
+mosaic brain conversations
+mosaic brain conversations --project <projectId>
+```
+
+### `mosaic config` — CLI Configuration
+
+Read and write the `mosaic` CLI configuration file.
+
+```bash
+# Show full config
+mosaic config show
+
+# Get a value
+mosaic config get gateway.url
+
+# Set a value
+mosaic config set theme dark
+
+# Open in editor
+mosaic config edit
+
+# Print file path
+mosaic config path
+```
+
+### `mosaic forge` — AI Pipeline Management
+
+Interact with the Forge multi-stage AI delivery pipeline (intake → board review
+→ planning → coding → review → deploy).
+
+```bash
+# Start a new forge run for a brief
+mosaic forge run --brief "Add dark mode toggle to settings"
+
+# Check status of a running pipeline
+mosaic forge status
+mosaic forge status --run <runId>
+
+# Resume a paused or interrupted run
+mosaic forge resume --run <runId>
+
+# List available personas (board review evaluators)
+mosaic forge personas
+```
+
+### `mosaic gateway` — Gateway Lifecycle
+
+Install, authenticate with, and verify the Mosaic gateway service.
+
+```bash
+# Install gateway (guided)
+mosaic gateway install
+
+# Verify gateway health post-install
+mosaic gateway verify
+
+# Log in and save token
+mosaic gateway login
+
+# Rotate API token
+mosaic gateway config rotate-token
+
+# Recover token via BetterAuth cookie (lost-token recovery)
+mosaic gateway config recover-token
+```
+
+### `mosaic log` — Structured Log Access
+
+Query and stream structured logs from the gateway.
+
+```bash
+# Stream live logs
+mosaic log tail
+mosaic log tail --level warn
+
+# Search logs
+mosaic log search "database connection"
+mosaic log search --since 1h "error"
+
+# Export logs to file
+mosaic log export --output logs.json
+mosaic log export --since 24h --level error --output errors.json
+
+# Get/set log level
+mosaic log level
+mosaic log level debug
+```
+
+### `mosaic macp` — MACP Protocol
+
+Interact with the MACP credential resolution, gate runner, and event bus.
+
+```bash
+# List MACP tasks
+mosaic macp tasks
+mosaic macp tasks --status pending
+
+# Submit a new MACP task
+mosaic macp submit --type credential-resolve --payload '{"key":"OPENAI_API_KEY"}'
+
+# Run a gate check
+mosaic macp gate --gate quality-check
+
+# Stream MACP events
+mosaic macp events
+mosaic macp events --filter credential
+```
+
+### `mosaic memory` — Agent Memory
+
+Query and inspect the agent memory layer.
+
+```bash
+# Semantic search over memory
+mosaic memory search "previous decisions about auth"
+
+# Show memory statistics
+mosaic memory stats
+
+# Generate memory insights report
+mosaic memory insights
+
+# View stored preferences
+mosaic memory preferences
+mosaic memory preferences --set editor=neovim
+```
+
+### `mosaic queue` — Task Queue (Valkey)
+
+Manage the Valkey-backed task queue.
+
+```bash
+# List all queues
+mosaic queue list
+
+# Show queue statistics
+mosaic queue stats
+mosaic queue stats --queue agent-tasks
+
+# Pause a queue
+mosaic queue pause agent-tasks
+
+# Resume a paused queue
+mosaic queue resume agent-tasks
+
+# List jobs in a queue
+mosaic queue jobs agent-tasks
+mosaic queue jobs agent-tasks --status failed
+
+# Drain (empty) a queue
+mosaic queue drain agent-tasks
+```
+
+### `mosaic storage` — Object Storage
+
+Manage object storage tiers and data migrations.
+
+```bash
+# Show storage status and usage
+mosaic storage status
+
+# List available storage tiers
+mosaic storage tier
+
+# Export data from storage
+mosaic storage export --bucket agent-artifacts --output ./artifacts.tar.gz
+
+# Import data into storage
+mosaic storage import --bucket agent-artifacts --input ./artifacts.tar.gz
+
+# Schema migration is unavailable in this release. The current storage wrapper shells
+# directly to `pnpm --filter @mosaicstack/db db:migrate`; it is legacy N-1,
+# uncertified, and MUST NOT be invoked pending KBN-101-02/-03/-06/-08 activation.
+# Future schema migration is non-operative: external bootstrap → TLS/roles → runner
+# --run → runner --verify → readiness.
+
+# Tier copy uses only the separately held secure migrate-tier route. Never use a legacy
+# --from/--to storage-migrate command or pass a credential on argv.
+```
+
+---
+
+## Telemetry
+
+Mosaic includes an OpenTelemetry-based telemetry system. Local telemetry
+(traces, metrics sent to Jaeger) is always available. Remote telemetry upload
+requires explicit opt-in.
+
+### Local Telemetry
+
+```bash
+# Show local OTEL collector / Jaeger status
+mosaic telemetry local status
+
+# Tail live OTEL spans
+mosaic telemetry local tail
+
+# Open Jaeger UI URL
+mosaic telemetry local jaeger
+```
+
+### Remote Telemetry
+
+Remote upload is a no-op (dry-run) until you opt in. Your consent state is
+persisted in the config file.
+
+```bash
+# Show current consent state
+mosaic telemetry status
+
+# Opt in to remote telemetry
+mosaic telemetry opt-in
+
+# Opt out (data stays local)
+mosaic telemetry opt-out
+
+# Test telemetry pipeline without uploading
+mosaic telemetry test
+
+# Upload telemetry (requires opt-in; dry-run otherwise)
+mosaic telemetry upload
+```