veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
131 lines
5.2 KiB
Markdown
131 lines
5.2 KiB
Markdown
---
|
|
kind: guide
|
|
status: active
|
|
title: Mosaic Stack Quickstart
|
|
type: guide
|
|
audience: user
|
|
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)
|