docs: create user quickstart
This commit is contained in:
Jason Woltje
+1
-1
@@ -195,7 +195,7 @@ For every documentation change:
|
||||
The initial structure pass defined the target structure without moving or rewriting the existing documentation set. Subsequent migration slices may move or rewrite classified pages deliberately, with repository references and indexes updated together.
|
||||
|
||||
- Treat `_old_structure/` as read-only migration quarantine. Do not add new content there.
|
||||
- Treat the current root-level legacy pages (`QUICKSTART.md`, `SSO-PROVIDERS.md`, `openapi-tess.yaml`, and the task/mission documents) as migration backlog, not permission to create more root files. Historical evidence such as the P8-003 performance report belongs under `reports/qa/`.
|
||||
- Treat the current root-level legacy pages (`SSO-PROVIDERS.md`, `openapi-tess.yaml`, and the task/mission documents) as migration backlog, not permission to create more root files. The former empty `QUICKSTART.md` placeholder now lives as `USER-GUIDE/getting-started/quickstart.md`; historical evidence such as the P8-003 performance report belongs under `reports/qa/`.
|
||||
- Candidate destinations include `USER-GUIDE/getting-started/`, `ADMIN-GUIDE/security/`, `DEVELOPER-GUIDE/architecture/`, `API/`, `tasks/`, `plans/`, and `archive/`; classify each page before moving it.
|
||||
- Existing source code and tests still reference legacy paths such as `docs/fleet/` and `docs/federation/`. Update those references deliberately as part of the relevant migration slice; do not delete a referenced path blindly.
|
||||
- When a page is moved, update all repository links, source comments, tests, book indexes, and `SITEMAP.md` in the same logical change.
|
||||
|
||||
+2
-1
@@ -5,12 +5,13 @@
|
||||
## Current documentation structure
|
||||
|
||||
- [Documentation atlas](README.md) — placement, source-of-truth, linking, and migration rules.
|
||||
- [User guide index](USER-GUIDE/README.md) — scaffold for end-user documentation.
|
||||
- [User guide index](USER-GUIDE/README.md) — end-user documentation and current quickstart.
|
||||
- [Administrator guide index](ADMIN-GUIDE/README.md) — scaffold for operator documentation.
|
||||
- [Developer guide index](DEVELOPER-GUIDE/README.md) — scaffold for contributor and architecture documentation.
|
||||
- [Architecture index](DEVELOPER-GUIDE/architecture/README.md) — scaffold for system design, decisions, and RFCs.
|
||||
- [API documentation index](API/README.md) — scaffold for the consolidated gateway contract.
|
||||
- [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence and migration recommendations.
|
||||
- [User quickstart](USER-GUIDE/getting-started/quickstart.md) — installed-CLI first-use path.
|
||||
- [P8-003 performance report](reports/qa/p8-003-performance-optimization.md) — historical performance evidence; not a current SLO or runbook.
|
||||
- [Archive index](archive/README.md) — retained historical pages; not current guidance.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# User Guide
|
||||
|
||||
> **Status:** Scaffold only. No legacy page has been promoted into this book yet.
|
||||
> **Status:** Initial migration active. The quickstart is current; additional user pages remain to be migrated.
|
||||
|
||||
This book is the canonical home for end-user workflows, user-visible behavior, product concepts, and user troubleshooting. Keep installation, deployment, security controls, and recovery procedures in [`ADMIN-GUIDE/`](../ADMIN-GUIDE/); keep implementation detail in [`DEVELOPER-GUIDE/`](../DEVELOPER-GUIDE/).
|
||||
|
||||
@@ -8,16 +8,20 @@ This book is the canonical home for end-user workflows, user-visible behavior, p
|
||||
|
||||
- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
|
||||
- [Documentation sitemap](../SITEMAP.md) — existing navigation is transitional and still contains legacy paths.
|
||||
- [Quickstart candidate](../QUICKSTART.md) — currently empty; it is not yet a usable guide.
|
||||
- [Quickstart](getting-started/quickstart.md) — install Mosaic, complete setup, and launch a session.
|
||||
|
||||
## Chapter map
|
||||
|
||||
| Chapter | Scope | Status |
|
||||
| ------------------ | ------------------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| `getting-started/` | First-use setup, orientation, and quickstarts. | Scaffold only; `QUICKSTART.md` is the migration candidate. |
|
||||
| `concepts/` | User-facing terminology, product concepts, and mental models. | Scaffold only. |
|
||||
| `workflows/` | Task-oriented procedures for using Mosaic Stack. | Scaffold only. |
|
||||
| `troubleshooting/` | User-visible failures, diagnostics, and fixes. | Scaffold only. |
|
||||
| Chapter | Scope | Status |
|
||||
| ------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
|
||||
| `getting-started/` | First-use setup, orientation, and quickstarts. | Quickstart is current; additional pages are planned. |
|
||||
| `concepts/` | User-facing terminology, product concepts, and mental models. | Scaffold only. |
|
||||
| `workflows/` | Task-oriented procedures for using Mosaic Stack. | Scaffold only. |
|
||||
| `troubleshooting/` | User-visible failures, diagnostics, and fixes. | Scaffold only. |
|
||||
|
||||
### Current pages
|
||||
|
||||
- [Quickstart](getting-started/quickstart.md) — the verified installed-CLI first-use path.
|
||||
|
||||
Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
|
||||
|
||||
@@ -26,7 +30,7 @@ Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP
|
||||
These are source candidates, not current user guidance:
|
||||
|
||||
- [`_old_structure/guides/user-guide.md`](../_old_structure/guides/user-guide.md) — historical source; verify every claim before promotion.
|
||||
- [`QUICKSTART.md`](../QUICKSTART.md) — incomplete zero-byte placeholder.
|
||||
The former root `QUICKSTART.md` was an empty placeholder and has been replaced by the current page above.
|
||||
|
||||
Do not link to the quarantine as a current user path. Create a new page only after classifying its audience, status, and evidence in the migration report.
|
||||
|
||||
|
||||
@@ -0,0 +1,134 @@
|
||||
---
|
||||
title: Mosaic Stack Quickstart
|
||||
type: guide
|
||||
audience: user
|
||||
status: current
|
||||
source_of_truth: false
|
||||
---
|
||||
|
||||
# Mosaic Stack Quickstart
|
||||
|
||||
Get the Mosaic CLI installed, complete first-run setup, connect to a gateway, and launch an agent session. This page covers the supported 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
|
||||
|
||||
The stable installer installs the Mosaic framework and the `mosaic` CLI, then launches the setup wizard by default:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://mosaicstack.dev/install.sh | bash
|
||||
```
|
||||
|
||||
If your security policy requires reviewing the script before execution, download it first and inspect it. The installer also supports the direct repository URL:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh -o /tmp/mosaic-install.sh
|
||||
less /tmp/mosaic-install.sh
|
||||
bash /tmp/mosaic-install.sh
|
||||
```
|
||||
|
||||
To install without automatically launching the wizard:
|
||||
|
||||
```bash
|
||||
bash /tmp/mosaic-install.sh --no-auto-launch
|
||||
```
|
||||
|
||||
The installer places framework files under `~/.config/mosaic/` and installs the CLI under the configured npm global prefix, `~/.npm-global/` by default. Ensure that prefix is on your `PATH` if your shell cannot find `mosaic`.
|
||||
|
||||
## 2. Complete first-run setup
|
||||
|
||||
If the installer skipped 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)
|
||||
@@ -21,6 +21,7 @@
|
||||
- [x] Add current scaffold entry points to `SITEMAP.md` without rewriting its legacy sections.
|
||||
- [x] Select the P8-003 performance report as the first low-risk migration slice.
|
||||
- [x] Archive the contradicted TUI PRD/task pair with unchanged content and an explicit archive index.
|
||||
- [x] Create and promote the verified user quickstart from the empty root placeholder.
|
||||
|
||||
## Initial findings
|
||||
|
||||
@@ -37,6 +38,7 @@
|
||||
- `SITEMAP.md` now has a labeled current-structure section; its legacy sections remain unchanged and explicitly transitional.
|
||||
- `docs/PERFORMANCE.md` had no live source/test dependency or internal links; it moved unchanged to `docs/reports/qa/p8-003-performance-optimization.md`. The admin index and current sitemap now classify it as historical evidence, not an operator runbook.
|
||||
- `PRD-TUI_Improvements.md` and `TASKS-TUI_Improvements.md` had no live source/test dependencies beyond their internal relative link; both moved unchanged to `docs/archive/tui/`, and `docs/archive/README.md` labels them historical.
|
||||
- The empty `docs/QUICKSTART.md` placeholder was replaced by `docs/USER-GUIDE/getting-started/quickstart.md`, based on verified installer, wizard, CLI, and runtime-safety behavior. The page explicitly excludes held PostgreSQL/source-checkout routes.
|
||||
|
||||
## Method
|
||||
|
||||
@@ -71,3 +73,4 @@
|
||||
| First migration selection | PASS — P8-003 report selected as a no-rewrite evidence migration; live references identified before move |
|
||||
| P8-003 migration | PASS — destination is byte-identical, live references were updated, formatting and navigation checks pass, and only the scoped migration files are pending commit |
|
||||
| TUI archive migration | PASS — both pages are byte-identical, internal links and archive navigation resolve, formatting passes, and only the scoped archive files are pending commit |
|
||||
| Quickstart migration | PASS — current page content is source-checked, held routes are labeled, navigation resolves, root placeholder is removed, and formatting passes |
|
||||
|
||||
Reference in New Issue
Block a user