diff --git a/docs/SITEMAP.md b/docs/SITEMAP.md index 250fdb1c..71a4699c 100644 --- a/docs/SITEMAP.md +++ b/docs/SITEMAP.md @@ -16,7 +16,7 @@ - [Product requirements](PRD.md) — normative requirements; currently marked draft and retaining authority-gated legacy references. - [Active task rollup](TASKS.md) — orchestrator-owned work state; workers do not modify it. -- [MVP mission manifest](MISSION-MANIFEST.md) — declares itself active; current workstream status and stale outbound links await orchestrator/maintainer validation. +- [MVP mission manifest](MISSION-MANIFEST.md) — control-plane mission rollup; activity and status remain under its authorized owner. - [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — complete baseline inventory, evidence labels, broken-link clusters, and migration recommendations. ## Protected current authority and executable books diff --git a/docs/USER-GUIDE/getting-started/quickstart.md b/docs/USER-GUIDE/getting-started/quickstart.md index ddedcb90..7d29fd28 100644 --- a/docs/USER-GUIDE/getting-started/quickstart.md +++ b/docs/USER-GUIDE/getting-started/quickstart.md @@ -8,7 +8,7 @@ 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. +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. @@ -25,31 +25,26 @@ Get the Mosaic CLI installed, complete first-run setup, connect to a gateway, an ## 1. Install Mosaic -The stable installer installs the Mosaic framework and the `mosaic` CLI, then launches the setup wizard by default: +> **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/mosaic@0.0.49`. Pin the exact package version and verify its published artifact integrity before installation: ```bash -curl -fsSL https://mosaicstack.dev/install.sh | bash +registry='https://git.mosaicstack.dev/api/packages/mosaicstack/npm/' +package='@mosaicstack/mosaic@0.0.49' +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" ``` -If your security policy requires reviewing the script before execution, download it first and inspect it. The installer also supports the direct repository URL: +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. -```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`. +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 -If the installer skipped the wizard, run it manually: +The versioned package install does not launch the wizard. Run it manually: ```bash mosaic wizard diff --git a/docs/_old_structure/federation/MISSION-MANIFEST.md b/docs/federation/MISSION-MANIFEST.md similarity index 100% rename from docs/_old_structure/federation/MISSION-MANIFEST.md rename to docs/federation/MISSION-MANIFEST.md diff --git a/docs/_old_structure/federation/TASKS.md b/docs/federation/TASKS.md similarity index 100% rename from docs/_old_structure/federation/TASKS.md rename to docs/federation/TASKS.md diff --git a/docs/scratchpads/DOCS-IA-002-catalog-audit.md b/docs/scratchpads/DOCS-IA-002-catalog-audit.md index ed2d884a..75b8dfac 100644 --- a/docs/scratchpads/DOCS-IA-002-catalog-audit.md +++ b/docs/scratchpads/DOCS-IA-002-catalog-audit.md @@ -117,7 +117,7 @@ No documentation-only relocation of these surfaces is authorized. A future move - `SITEMAP.md` links the protected Fleet and KBN authority surfaces at their canonical paths. Remaining authority-gated Federation, Kanban task-state, Tess/API, and deployment groups are summarized without presenting quarantine paths as current navigation. - `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. +- The empty `docs/QUICKSTART.md` placeholder was replaced by `docs/USER-GUIDE/getting-started/quickstart.md`, based on verified versioned-package, wizard, CLI, and runtime-safety behavior. The page holds mutable remote-script installation, pins and checks the published top-level package artifact, discloses that the transitive dependency closure is not independently immutable, and excludes held PostgreSQL/source-checkout routes. - The SSO guide now documents Authentik/WorkOS/Keycloak discovery, OIDC callbacks, Keycloak SAML fallback, partial-config failures, and the absence of frontend feature flags. The root guide and stale `.env.example` flags were removed. - The lease-broker acceptance suites directly consumed two quarantined `docs/architecture/` paths; promoting the protocol, security, mutator-gate, and compaction-revocation contracts to `DEVELOPER-GUIDE/architecture/` and updating those consumers restored the intended contract family without changing runtime behavior. - The #756 Discord code-review, security-review, and documentation-checklist reports had no source/test consumers and moved byte-identically to their canonical report categories. `docs/reports/README.md` labels their historical evidence boundary. @@ -139,11 +139,11 @@ No documentation-only relocation of these surfaces is authorized. A future move ## Risks and blockers -- `docs/PRD.md`, `docs/TASKS.md`, and `docs/MISSION-MANIFEST.md` retain authority-owned links that require maintainer/orchestrator disposition. Fleet source/test consumers are satisfied by retaining the executable book at `docs/fleet/`; Federation relocation remains coupled. +- Fleet source/test consumers are satisfied by retaining the executable book at `docs/fleet/`. Fred authorized the PR #1210 C2 disposition: five control-document destinations without a different canonical post-restructure home were restored byte-identically from quarantine to their canonical paths; no task or mission status semantics changed. - Historical documents may contain commands or security claims that are unsafe if resurfaced as current guidance. - Truth audit is static unless a claim can be verified without starting held services or violating database/runtime safety rules. -- `docs/TASKS.md` is single-writer orchestrator state and will not be edited by this task. -- After restoring active Fleet/KBN/#1187 surfaces and the Fleet-canary dependency, 65 quarantine files remain. Every remaining group is authority-, source/test-consumer-, safety-, or path-coupled; the Mos-gated compaction probes additionally hard-code their present repository-relative location and must not be moved or run independently. +- `docs/TASKS.md` remains single-writer orchestrator state. Fred authorized link-only C2 repair; restoration of the exact linked destinations resolved the defect without editing its payload. +- After restoring active Fleet/KBN/#1187 surfaces, the Fleet-canary dependency, and five authorized control-document destinations, 60 quarantine files remain. Every remaining group is authority-, source/test-consumer-, safety-, or path-coupled; the Mos-gated compaction probes additionally hard-code their present repository-relative location and must not be moved or run independently. - The pre-existing `9a1cc63` commit removed `docs/GETTING_STARTED.md` and added the `.obsidian` ignore rule before this audit commit; that state is not attributed to this task. ## Verification log @@ -163,7 +163,7 @@ No documentation-only relocation of these surfaces is authorized. A future move | 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 | +| Quickstart migration | PASS — exact `@mosaicstack/mosaic@0.0.49` artifact and published SHA-512 integrity are pinned; mutable remote scripts and immutable-closure overclaims are held | | SSO migration | PASS — auth/gateway/web SSO tests pass (15+2+2), source claims and navigation resolve, obsolete env flags are removed, and the root guide is retired | | Parallel Pi audits | PASS — four requested `openai-codex/gpt-5.6-luna:max` read-only lanes completed in clean isolated worktrees; no agent changes were imported | | Lease-broker architecture | PASS — four contract pages promoted, two source/test consumers and navigation updated, 20/20 Vitest acceptance tests passed, and the 3-test Python portability suite passed | @@ -179,7 +179,9 @@ No documentation-only relocation of these surfaces is authorized. A future move | Optional egress RFC | PASS — proposal remains draft/non-operative; model and runtime-provider boundaries are separated and candidates are not integrated | | Web dashboard guide | PASS — current routes, views, chat persistence, and absent project/task creation controls are documented from source/tests | | Sitemap refresh | PASS — 54/54 relative links resolve after PR #1210 protected-surface reconciliation | -| Canonical link audit | BLOCKED ONLY BY CONTROL DOCS — 443 links scanned, 10 unresolved; all are in orchestrator-owned `TASKS.md` or `MISSION-MANIFEST.md` | +| Canonical link audit | PASS AFTER AUTHORIZED C2 REPAIR — 443 relative links scanned, 0 unresolved; all ten control-doc links resolve through five byte-identical canonical destination restores | +| C1 anti-masking control | PASS — executable Vitest control scans the explicit current-installation page set and observed-red fixtures prove pipe-to-shell, process substitution, and mutable branches fail | +| C2 anti-masking control | PASS — all ten original `TASKS.md`/`MISSION-MANIFEST.md` uses resolve; restored destination blobs match their quarantine sources and the sitemap claim is owner-neutral | | Navigation review | PASS AFTER REMEDIATION — plan/scratchpad indexes added, current quarantine links removed, lifecycle/status copy aligned | | Safety review | PASS AFTER REMEDIATION — Discord pages no longer claim unproven ordinary persistence or restart continuity | | Stop-condition review | AUTONOMOUS COMPLETE — historical mission bundle migrated; remaining groups require authority or coupled source/test work | diff --git a/docs/_old_structure/scratchpads/mvp-20260312.md b/docs/scratchpads/mvp-20260312.md similarity index 100% rename from docs/_old_structure/scratchpads/mvp-20260312.md rename to docs/scratchpads/mvp-20260312.md diff --git a/docs/_old_structure/tess/MISSION-MANIFEST.md b/docs/tess/MISSION-MANIFEST.md similarity index 100% rename from docs/_old_structure/tess/MISSION-MANIFEST.md rename to docs/tess/MISSION-MANIFEST.md diff --git a/docs/_old_structure/tess/TASKS.md b/docs/tess/TASKS.md similarity index 100% rename from docs/_old_structure/tess/TASKS.md rename to docs/tess/TASKS.md diff --git a/packages/mosaic/src/installation-documentation.spec.ts b/packages/mosaic/src/installation-documentation.spec.ts new file mode 100644 index 00000000..a5a47e34 --- /dev/null +++ b/packages/mosaic/src/installation-documentation.spec.ts @@ -0,0 +1,56 @@ +import { readFile } from 'node:fs/promises'; +import { dirname, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { describe, expect, it } from 'vitest'; + +const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const repositoryRoot = resolve(packageRoot, '..', '..'); + +const CURRENT_INSTALLATION_PAGES = ['docs/USER-GUIDE/getting-started/quickstart.md'] as const; + +const UNSAFE_REMOTE_EXECUTION_PATTERNS = [ + { + name: 'pipe a remote response directly to a shell', + pattern: /\bcurl\b[^\n|]*\|\s*(?:ba|z|k)?sh\b/i, + }, + { + name: 'execute a remote response through shell process substitution', + pattern: /\b(?:ba|z|k)?sh\s*<\(\s*curl\b/i, + }, + { + name: 'fetch an installer from a mutable main or next branch', + pattern: + /(?:\/raw\/branch\/(?:main|next)\/|\/raw\/(?:refs\/heads\/)?(?:main|next)\/|\/-\/raw\/(?:main|next)\/)/i, + }, +] as const; + +function unsafeRemoteExecutionFindings(markdown: string): string[] { + return UNSAFE_REMOTE_EXECUTION_PATTERNS.filter(({ pattern }) => pattern.test(markdown)).map( + ({ name }) => name, + ); +} + +describe('current installation documentation safety', (): void => { + it.each(CURRENT_INSTALLATION_PAGES)( + 'keeps %s current without mutable remote-script execution', + async (relativePath): Promise => { + const markdown = await readFile(resolve(repositoryRoot, relativePath), 'utf8'); + + expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: current\n[\s\S]*?\n---\n/); + expect(unsafeRemoteExecutionFindings(markdown)).toEqual([]); + }, + ); + + it('proves the control reddens for each prohibited installation shape', (): void => { + const unsafeExamples = [ + 'curl -fsSL https://example.invalid/install.sh | bash', + 'bash <(curl -fsSL https://example.invalid/install.sh)', + 'curl -fsSL https://example.invalid/project/raw/branch/main/install.sh -o install.sh', + 'curl -fsSL https://example.invalid/project/-/raw/next/install.sh -o install.sh', + ]; + + for (const example of unsafeExamples) { + expect(unsafeRemoteExecutionFindings(example), example).not.toEqual([]); + } + }); +});