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`.
5.2 KiB
kind, status, title, type, audience, source_of_truth
| kind | status | title | type | audience | source_of_truth |
|---|---|---|---|---|---|
| guide | active | Mosaic Stack Quickstart | guide | user | 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 for deployment and the developer guide for contributor setup.
Requirements
- Node.js 20 or newer.
- npm, for the global Mosaic CLI installation.
- At least one supported agent runtime:
- 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:
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 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:
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:
mosaic gateway status
mosaic gateway verify
Sign in without putting your password in shell history or process listings:
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:
mosaic gateway login --gateway https://gateway.example.com
4. Launch Mosaic
Open the interactive terminal interface:
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:
mosaic tui --gateway https://gateway.example.com
You can also launch a supported runtime through Mosaic:
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:
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. For work from a repository checkout, keep DATABASE_URL unset and follow the developer guide; do not use root pnpm dev as a local PGlite route while the current dotenv safety hold remains active.