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,129 @@
+---
+title: Mosaic Stack Quickstart
+type: guide
+audience: user
+status: current
+source_of_truth: false
+---
+
+# Mosaic Stack Quickstart
+
+Verify and install the versioned Mosaic CLI package, complete first-run setup, connect to a gateway, and launch an agent session. This page covers the installed-CLI path with the default local storage tier.
+
+> **Scope:** This is an end-user installation route. It does not authorize PostgreSQL setup, production deployment, or starting Gateway/Web directly from a source checkout. Use the [administrator guide](../../ADMIN-GUIDE/README.md) for deployment and the [developer guide](../../DEVELOPER-GUIDE/README.md) for contributor setup.
+
+## Requirements
+
+- Node.js 20 or newer.
+- npm, for the global Mosaic CLI installation.
+- At least one supported agent runtime:
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+  - [Codex](https://github.com/openai/codex)
+  - [OpenCode](https://opencode.ai)
+  - [Pi](https://pi.dev)
+- Credentials for the runtime or model provider you plan to use.
+
+## 1. Install Mosaic
+
+> **Installation hold:** Do not execute the website installer or a script fetched from a mutable repository branch. The current release tooling does not publish an independently verified immutable dependency closure or a signed installer. If your policy requires either property, stop until a release provides it.
+
+The currently published CLI/framework package is `@mosaicstack/[email protected]`. Pin the exact package version and verify its published artifact integrity before installation:
+
+```bash
+registry='https://git.mosaicstack.dev/api/packages/mosaicstack/npm/'
+package='@mosaicstack/[email protected]'
+expected_integrity='sha512-/Zsjdf8Ln2QchQTG9lirpqSxhDbNyBjOvGkWrDWRugxCuqUWP5V0rUNVDivmPvro+Vyq3hxDyA9i4hDfkEFmMg=='
+actual_integrity="$(npm view --registry="$registry" "$package" dist.integrity)"
+test "$actual_integrity" = "$expected_integrity"
+npm install --global --registry="$registry" "$package"
+```
+
+The explicit comparison pins the reviewed top-level package artifact; npm also checks the downloaded tarball against registry integrity metadata. It does **not** make the package's transitive dependency graph independently immutable. Review the [package release](https://git.mosaicstack.dev/mosaicstack/-/packages/npm/%40mosaicstack%2Fmosaic/0.0.49) before proceeding, and stop if the integrity comparison fails.
+
+The versioned package includes the Mosaic framework and CLI. npm installs it under your configured global prefix. Ensure that prefix's `bin` directory is on `PATH` if your shell cannot find `mosaic`.
+
+## 2. Complete first-run setup
+
+The versioned package install does not launch the wizard. Run it manually:
+
+```bash
+mosaic wizard
+```
+
+The wizard guides framework setup and gateway installation. It can collect your agent identity, preferences, provider configuration, and gateway administrator details interactively.
+
+For a separately installed or existing gateway, skip local gateway installation and use its URL in the login step below.
+
+## 3. Verify and sign in
+
+For a gateway installed on this machine, check its health and setup state:
+
+```bash
+mosaic gateway status
+mosaic gateway verify
+```
+
+Sign in without putting your password in shell history or process listings:
+
+```bash
+mosaic gateway login
+```
+
+The command prompts for the gateway URL, email, and password as needed. Do not pass passwords with `--password`.
+
+For a remote gateway, provide its URL explicitly:
+
+```bash
+mosaic gateway login --gateway https://gateway.example.com
+```
+
+## 4. Launch Mosaic
+
+Open the interactive terminal interface:
+
+```bash
+mosaic tui
+```
+
+The TUI defaults to `http://localhost:14242` and can prompt for login if no valid session is saved. To connect it to another gateway:
+
+```bash
+mosaic tui --gateway https://gateway.example.com
+```
+
+You can also launch a supported runtime through Mosaic:
+
+```bash
+mosaic pi
+mosaic claude
+mosaic codex
+mosaic opencode
+```
+
+Use the launcher matching the runtime you installed and authenticated.
+
+## 5. Inspect configuration and health
+
+These commands are safe diagnostics and do not change the product requirements or active task ledger:
+
+```bash
+mosaic config show
+mosaic doctor
+mosaic gateway logs
+```
+
+If the gateway is unhealthy, run `mosaic gateway status` and `mosaic gateway logs` before attempting a reinstall. If your session expires, run `mosaic gateway login` again.
+
+## Storage and deployment boundary
+
+The default local gateway tier uses embedded PGlite and does not require an external PostgreSQL or Valkey service. This quickstart intentionally does not configure `DATABASE_URL`, PostgreSQL, pgvector, or a federated deployment.
+
+For standalone or federated storage, deployment topology, secrets, SSO, backups, or recovery, stop here and use the [administrator guide](../../ADMIN-GUIDE/README.md). For work from a repository checkout, keep `DATABASE_URL` unset and follow the [developer guide](../../DEVELOPER-GUIDE/README.md); do not use root `pnpm dev` as a local PGlite route while the current dotenv safety hold remains active.
+
+## Related
+
+- [User Guide](../README.md)
+- [Documentation atlas](../../README.md)
+- [Administrator Guide](../../ADMIN-GUIDE/README.md)
+- [Developer Guide](../../DEVELOPER-GUIDE/README.md)
+- [Repository README](../../../README.md)