feat(installer): add next integration lane (#686)

Add --next installer flag (build-from-source at the next integration branch; MOSAIC_NEXT=1 env equiv; explicit --ref wins). Three-lane install docs (stable @latest / --next prerelease / --dev source) + @next dist-tag pipeline design doc. Green PR-event CI 1626 + review-of-record APPROVE (head 3a5c12a5).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/design/prerelease-next-dist-tag-pipeline.md

@@ -0,0 +1,40 @@
+# Planned Design — npm `@next` prerelease lane
+
+Status: **PLANNED / not yet built**
+
+## Current state
+
+`tools/install.sh --next` provides a prerelease integration lane by building the Mosaic CLI and gateway from source at the permanent `next` branch. This is correct for validating integration-branch source, but it is slower than the stable npm lane because it downloads the archive, installs workspace dependencies, builds packages, packs local tarballs, and installs those tarballs globally.
+
+## Medium-term target
+
+Publish every accepted `next` integration build to the npm registry under the `@next` dist-tag, for example:
+
+```text
+@mosaicstack/mosaic@0.0.49-next.1
+@mosaicstack/mosaic@0.0.49-next.2
+```
+
+Then move `tools/install.sh --next` from source-build behavior to a fast npm install:
+
+```bash
+npm install -g @mosaicstack/mosaic@next
+```
+
+The framework archive should still resolve from the matching `next` source/ref until framework packaging has a registry-backed equivalent.
+
+## Pipeline shape
+
+1. Trigger on successful CI for `next`.
+2. Compute the next prerelease version from the upcoming stable version plus a monotonic prerelease counter (`0.0.49-next.N`).
+3. Build and pack publishable packages in CI.
+4. Publish to the Mosaic Gitea npm registry with dist-tag `next`.
+5. Keep `latest` untouched; only main/release promotion can update `latest`.
+6. Teach the installer to prefer `@next` for the CLI/gateway prerelease lane once the registry tag is reliable.
+
+## Guardrails
+
+- `@next` is mutable prerelease convenience, not a deployment pin.
+- Stable installs continue to use `@latest`.
+- Contributor validation remains available through `--dev --ref <branch>`.
+- Pipeline must be reproducible and trace every prerelease package back to the source commit on `next`.

docs/guides/user-guide.md

@@ -175,8 +175,18 @@ Or use the direct URL:
 bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh)
 ```
 
-The installer places the `mosaic` binary at `~/.npm-global/bin/mosaic`. Flags for
-non-interactive use:
+The installer places the `mosaic` binary at `~/.npm-global/bin/mosaic`.
+
+Install lanes:
+
+| Lane                     | Command                               | Source                                       |
+| ------------------------ | ------------------------------------- | -------------------------------------------- |
+| Stable                   | `bash tools/install.sh`               | npm `@mosaicstack/mosaic@latest` + `main`    |
+| Prerelease integration   | `bash tools/install.sh --next`        | Build-from-source at permanent branch `next` |
+| Contributor/source build | `bash tools/install.sh --dev --ref X` | Build-from-source at the requested ref       |
+
+`--next` implies source-build mode at `next`; explicit `--ref` or `MOSAIC_REF` wins.
+Flags for non-interactive use:
 
 ```bash
 --yes               # Accept all defaults

docs/scratchpads/installer-next-lane-20260624.md

@@ -0,0 +1,35 @@
+# Scratchpad — installer `--next` lane
+
+## Objective
+
+Add a prerelease installer lane for the permanent `next` integration branch.
+
+## Scope
+
+- `tools/install.sh`
+- README/install documentation
+- Follow-up design note for future npm `@next` prerelease publishing
+
+## Plan
+
+1. Add `--next` and `MOSAIC_NEXT=1` as source-build shorthand for `next`.
+2. Preserve explicit ref precedence: `MOSAIC_REF` and `--ref` win over `--next`.
+3. Update installer source display/help text.
+4. Document three lanes:
+   - stable npm `@latest`
+   - prerelease `--next`
+   - contributor `--dev --ref X`
+5. Run shell and repo gates locally, then hold before push/PR until runner serialization greenlight.
+
+## Verification
+
+- `bash -n tools/install.sh` — pass.
+- `docker run --rm -v "$PWD:/mnt" -w /mnt koalaman/shellcheck:stable tools/install.sh` — pass.
+- `bash tools/install.sh --check --framework --next` — source display shows `ref: next, --next prerelease lane`.
+- `bash tools/install.sh --check --cli --next --ref feature-x` — source display shows explicit ref wins.
+- `MOSAIC_NEXT=1 MOSAIC_REF=feature-env bash tools/install.sh --check --cli` — source display shows explicit env ref wins.
+- `pnpm install --frozen-lockfile --prefer-offline --store-dir /home/jarvis/.local/share/pnpm/store` — pass (local override for repo `.npmrc` CI store path).
+- `pnpm typecheck` — pass (41 successful tasks).
+- `pnpm lint` — pass (23 successful tasks).
+- `pnpm format:check` — pass.
+- `bash tools/e2e-install-test.sh` — attempted; current baseline fails during gateway health after stable registry install because Valkey is unavailable in the clean container. The `tools/install.sh --yes --no-auto-launch` stage itself completed before the downstream gateway verification failure.