@allstak/wizard 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -4,7 +4,20 @@ All notable changes to `@allstak/wizard` will be documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/) and this project
 adheres to [Semantic Versioning](https://semver.org/).
 
-## [Unreleased] — 0.1.3
+## [Unreleased] — 0.1.4
+
+### Changed
+- README rewritten to reflect the v0.1.3 beta surface (real auth, full
+  command list, 123 tests, telemetry contract, error catalog, current v0.2
+  roadmap).
+- Package metadata polished for npm: tighter description, `sdk-install`
+  keyword consolidated to `sdk`, exports map gains `./config` and
+  `./errors` subpaths, `files` whitelist gains `docs/errors.md` and
+  `docs/beta/`.
+- Scrubbed two absolute local paths from shipped content
+  (`docs/architecture/v02-java-host-fix-spec.md`, `src/api/types.ts`).
+
+## [0.1.3] — 2026-05-07
 
 ### Added
 - Privacy-safe telemetry (`src/telemetry/*`) — disabled by default until an

package/README.md

@@ -1,79 +1,328 @@
 # @allstak/wizard
 
-> v0.1 — Unified installation and configuration wizard for AllStak SDKs.
+> **v0.1.3 beta** — Unified installation and configuration wizard for AllStak SDKs.
 
-A Sentry-Wizard-style CLI that installs and configures AllStak SDKs in your project with one command. Designed to be **honest by default**: only integrations validated end-to-end against real fixture projects ship with the `VALIDATED` tag; everything else is `SCAFFOLD` and refuses to apply patches without `--experimental`.
+A Sentry-Wizard-style CLI that installs and configures AllStak SDKs in
+your project with one command. Designed to be **honest by default**:
+integrations only graduate to `stable` after end-to-end fixture validation;
+`experimental` integrations refuse to run without an explicit opt-in;
+`unsupported` integrations refuse outright with a pointer to manual setup.
 
-## Status
+## Status: public beta
 
-| Integration   | Tag         | Notes |
-|---------------|-------------|-------|
-| `react`       | VALIDATED   | Vite + plain React, AST-tested |
-| `next`        | VALIDATED   | Next 13+ app & pages router |
-| `js`          | VALIDATED   | Vanilla Node entry-point patching |
-| `expo`        | SCAFFOLD    | Config-plugin path scaffolded; native build verification deferred to v0.2 |
-| `react-native` | UNSUPPORTED | Bare RN intentionally refused — Podfile/Gradle patching not validated |
-| `nestjs` / `fastify` / `otel` / `python` / `go` / `java` / `php` / `ruby` / `dotnet` / `flutter` | SCAFFOLD | Env-var writing only; framework wiring deferred to v0.2 |
+This release is **beta-ready, not stable**. Sit on it, dogfood it, file
+issues — but expect the surface to wobble in patch releases until 1.0.
 
-Run `allstak-wizard list` to see this matrix at runtime.
+| Integration | Stability | Notes |
+|-------------|-----------|-------|
+| `react` (Vite or CRA) | ✅ stable | Validated end-to-end; dogfooded |
+| `next` (13+, app + pages router) | 🟡 beta | Implementation complete; production-build matrix in progress |
+| `js` (vanilla Node) | ✅ stable | Validated end-to-end |
+| `expo`, `nestjs`, `fastify`, `otel`, `python`, `go`, `java`, `php`, `ruby`, `dotnet`, `flutter` | 🟠 experimental | Install + env-var writing only; framework wiring deferred. Refuses without `--experimental`. |
+| `react-native` (bare) | ❌ unsupported | Refused outright — Podfile/Gradle patching not validated. Use Expo or follow manual setup. |
 
-## Install
+`allstak-wizard list` prints this matrix at runtime. See
+[`docs/beta/known-limitations.md`](./docs/beta/known-limitations.md) for
+the full honest list.
 
-In v0.1 the package is not published. To run from source:
+## Install + run
 
 ```bash
-cd /path/to/sdks/allstak-wizard
-npm install
-npx tsx src/cli.ts --help
+# Show help (also fetches and runs the package via npx).
+npx @allstak/wizard@beta --help
+
+# Authenticate against AllStak (email OTP, optional 2FA).
+npx @allstak/wizard@beta login
+
+# Configure your project (auto-detects React / Next / Node).
+npx @allstak/wizard@beta -i react
+
+# Verify with a real test event roundtrip.
+npx @allstak/wizard@beta doctor --live-probe \
+  --api-key ask_live_... \
+  --project-id <project-uuid>
 ```
 
-## Usage
+Five-minute walkthrough: [`docs/beta/quickstart.md`](./docs/beta/quickstart.md).
+
+## Authentication
+
+Real AllStak auth flow — no fake endpoints. Backed by the verified
+`/api/v1/auth/*` endpoints on `api.allstak.sa`.
 
 ```bash
-# Auto-detect framework, interactive
-allstak-wizard
+allstak-wizard login              # email OTP → JWT pair stored in OS keychain
+allstak-wizard whoami [--verify]  # show current user; --verify round-trips /auth/me
+allstak-wizard logout             # revoke session + clear local credentials
+```
 
-# Explicit, non-interactive
-allstak-wizard -i react --api-key $ALLSTAK_API_KEY -y
+Supports:
 
-# Self-hosted
-allstak-wizard -i next --host https://api.acme.allstak.com --api-key $KEY -y
+- **Email OTP** primary flow (`/api/v1/auth/request-otp` → `/api/v1/auth/verify-otp`).
+- **TOTP** second factor when enabled on the account.
+- **JWT refresh** with proactive 60s pre-expiry refresh + token rotation.
+- **CI mode** via `--api-key` / `ALLSTAK_API_KEY` (skip login entirely).
+- **Cross-platform credential storage**: macOS Keychain, Linux Secret
+  Service (`secret-tool`), AES-256-GCM encrypted-file fallback.
 
-# Dry run (prints diff, writes nothing)
-allstak-wizard -i react --dry-run -y
+`--api-key` is for project-scoped data-plane operations (sending events).
+The user JWT is for control-plane operations (orgs, projects, doctor). The
+two are NOT interchangeable — that mirrors the backend's design.
+
+## Commands
 
-# Other commands
-allstak-wizard list
-allstak-wizard doctor [-i react]
-allstak-wizard repair -i react
-allstak-wizard uninstall -i react -y
 ```
+init [-i <integration>] [--api-key|--org|--project|--release|...] [--dry-run] [-y]
+doctor [-i <integration>] [--live-probe --api-key --project-id <uuid>]
+repair -i <integration> [--dry-run]
+uninstall -i <integration> [-y] [--dry-run]
+list
 
-## Authentication (v0.1)
+login [--email <e> --code <c>] [--totp <c>]
+logout [--local-only]
+whoami [--verify]
 
-Browser/device-flow login is **not** implemented in v0.1. Provide a key via `--api-key` or `ALLSTAK_API_KEY`. `allstak-wizard login` exits with a clear hint.
+orgs list
+projects list [--org <id>]
+projects create [--name --slug --platform --with-api-key]
 
-## Architecture
+restore list
+restore show <id|latest>
+restore apply <id|latest> [--files=a,b,c] [--dry-run] [-y]
+restore diff <id|latest>
 
-- **Registry** — every integration is an `Integration` object with `detect`, `plan`, `install`, `patch`, `validate`, `uninstall`, `repair`, `doctor` methods. New integrations register themselves; the CLI is integration-agnostic.
-- **Transaction** — every file mutation goes through a `Transaction` that snapshots before writing, validates syntax after writing, and rolls back the entire batch on any failure.
-- **Markers** — every injected region is wrapped with `>>> allstak-wizard:v1` markers. Re-runs replace the existing block (idempotent). `uninstall` removes the block cleanly.
-- **AST patching** — JS/TS files use `magicast` (recast under the hood) to add imports without disturbing user code; non-AST changes (provider wrap hints, Vite plugin hints) live in marker blocks.
-- **Dry-run** — every command supports `--dry-run`; the transaction layer captures the diff but skips disk writes.
+config validate
+config migrate [--dry-run]
+```
 
-## Self-hosted support
+Global flags:
 
-The wizard never assumes `api.allstak.sa`; pass `--host`, `--ingest-host`, and `--dashboard-host` to point at any AllStak deployment. Note: the Java SDK currently hardcodes its host — that's a known SDK-side bug, not a wizard bug. See the v0.1 implementation report for details.
+```
+--debug              verbose debug logging
+--json               machine-readable output to stdout (status text → stderr)
+--no-telemetry       disable anonymous usage telemetry for this run
+--telemetry-debug    print the telemetry payload to stderr without sending
+```
 
-## Testing
+## Telemetry & privacy
+
+**Default provider is `noopTelemetry`** — the wizard does not phone home in
+beta. An HTTP provider exists (`httpTelemetry({ endpoint })`) for operators
+to wire in once a backend telemetry endpoint is decided on.
+
+Three independent ways to opt out, any one suffices:
+
+```bash
+npx @allstak/wizard@beta --no-telemetry ...
+ALLSTAK_WIZARD_TELEMETRY=0 npx @allstak/wizard@beta ...
+# Or: leave the default noop provider in place (no operator config).
+```
+
+Inspect what _would_ be sent:
 
 ```bash
-npm run test              # 46 tests across markers, transaction, patchers, detect, integrations
-npm run type-check
+npx @allstak/wizard@beta --telemetry-debug -i react --dry-run
 ```
 
-Tests use temp-dir fixtures (no network, no SDK install required) and validate idempotency, rollback, dry-run, and uninstall round-trips for all VALIDATED integrations.
+The wizard's payload type is the entire on-the-wire contract. We do **NOT**
+collect:
+
+- API keys, DSNs, refresh tokens, OAuth secrets
+- Org names, project names, project ids, org ids
+- File paths (absolute or relative)
+- Env-var values
+- Source code, error message text, stack frames
+- Email addresses, IP addresses, hostnames
+
+We do collect: wizard version, command, integration id, stability level,
+OS family + major, Node major, package manager, outcome, stage, canonical
+error code (no message text), `rollbackTriggered` (boolean), `durationMs`.
+
+Full contract: [`docs/beta/privacy.md`](./docs/beta/privacy.md).
+
+## Config (`allstak.config.{ts,mjs,js,cjs,json}`)
+
+Optional project-level config so you don't repeat `--org`, `--project`,
+`--host`, etc. on every wizard invocation.
+
+```ts
+import { defineConfig } from '@allstak/wizard/config';
+
+export default defineConfig({
+  schemaVersion: 1,
+  organization: 'my-org',
+  project: 'my-project',
+  environment: 'production',
+  release: process.env.GIT_SHA,
+  sourceMaps: {
+    enabled: true,
+    ignore: ['node_modules'],
+  },
+  selfHosted: {
+    apiHost: 'https://api.allstak.example',
+    ingestHost: 'https://api.allstak.example',
+    dashboardHost: 'https://app.allstak.example',
+  },
+});
+```
+
+**Precedence:** `CLI flag > env var > config file > built-in default`.
+
+Validate:
+
+```bash
+allstak-wizard config validate
+```
+
+Migrate to a new schema version:
+
+```bash
+allstak-wizard config migrate --dry-run    # preview
+allstak-wizard config migrate              # rewrites .json in place
+```
+
+Full reference: [`docs/beta/config.md`](./docs/beta/config.md).
+
+## Doctor (deterministic diagnostics)
+
+```bash
+allstak-wizard doctor                              # offline check
+allstak-wizard doctor --live-probe \               # send + verify a real event
+  --api-key ask_live_... --project-id <uuid>
+```
+
+Runs seven named stages in fixed order — `auth → reachability → config →
+integration → event-ingest → release-linkage → source-maps`. Each stage
+reports `pass`/`warn`/`fail`/`skip` with an actionable fix. Live probe POSTs
+to `/ingest/v1/errors`, polls `/api/v1/errors`, and prints the dashboard URL
+of the captured event.
+
+Full reference: [`docs/beta/doctor.md`](./docs/beta/doctor.md).
+
+## Restore (persistent snapshots)
+
+Every wizard mutation is captured under
+`.allstak-wizard/backups/<id>/manifest.json` plus per-file pre-images.
+
+```bash
+allstak-wizard restore list
+allstak-wizard restore show latest
+allstak-wizard restore diff latest
+allstak-wizard restore apply latest [--files=src/main.tsx]
+```
+
+Full reference: [`docs/beta/restore.md`](./docs/beta/restore.md).
+
+## Error codes
+
+22 canonical error codes — stable across releases (added; never renamed).
+Both human and `--json` output expose `{code, stage, subcode?, message,
+hint}`. Catalog: [`docs/errors.md`](./docs/errors.md).
+
+```bash
+$ allstak-wizard --json -i react -y --skip-deps
+{
+  "outcome": "failure",
+  "errorCode": "E_AUTH_REQUIRED",
+  "data": { "error": {
+    "code": "E_AUTH_REQUIRED",
+    "stage": "auth",
+    "subcode": "E_MISSING_KEY",
+    "message": "...",
+    "hint": "Pass --api-key or run `allstak login`."
+  } }
+}
+```
+
+Exit codes: `0` success, `2` `WizardError`, `130` user cancellation.
+
+## Self-hosted
+
+Pass `--host`, `--ingest-host`, `--dashboard-host` directly, or set
+`selfHosted.*` in `allstak.config.*`. The wizard never assumes
+`api.allstak.sa`.
+
+**Caveat:** `allstak-java-sdk` currently hardcodes its host. Until that
+SDK ships a configurable `host` field, the wizard's `--host` flag is a
+no-op for `-i java`. Spec for the SDK fix:
+[`docs/architecture/v02-java-host-fix-spec.md`](./docs/architecture/v02-java-host-fix-spec.md).
+
+## Architecture
+
+- **Registry** — every integration is an `Integration` object with
+  `detect`, `plan`, `install`, `patch`, `validate`, `uninstall`, `repair`,
+  `doctor` methods. New integrations register themselves; the CLI is
+  integration-agnostic.
+- **Transaction** — every file mutation snapshots before write, syntax-
+  validates after write, and rolls back the entire batch on any failure.
+- **Persistent snapshots** — alongside in-memory rollback, every run
+  writes a backup under `.allstak-wizard/backups/<id>/` for cross-run
+  recovery via `restore`.
+- **Markers** — every injected region wrapped with `>>> allstak-wizard:v1`
+  markers. Re-runs replace in place (idempotent). `uninstall` removes the
+  block cleanly.
+- **AST patching** — `magicast` (recast under the hood) for JS/TS imports;
+  managed-block hints for non-AST patches (Vite plugins, Next config).
+- **Dry-run** — every command supports `--dry-run`; transaction layer
+  captures the diff and skips disk writes.
+- **Source-map providers** — pluggable abstraction (`vite`, `webpack`,
+  `next`, `metro`); integrations select a provider by id.
+- **Lifecycle hooks** — `beforeInstall`/`afterInstall`/`beforePatch`/
+  `afterPatch`/`beforeRollback`/`afterRollback`/`beforeUninstall`/
+  `afterUninstall` for telemetry + plugin extensions.
+
+Full design docs: [`docs/architecture/`](./docs/architecture/).
+
+## Development from source
+
+```bash
+cd /path/to/sdks/allstak-wizard
+npm install
+npm run type-check         # tsc --noEmit (clean)
+npm test                   # 123 tests, ~3s
+npm run build              # emits dist/ with .d.ts + source maps
+npx tsx src/cli.ts --help  # run from source
+
+# Smoke against a fixture (no network, no SDK install):
+cd fixtures/react-vite
+ALLSTAK_API_KEY=ask_test \
+  npx --prefix ../.. tsx ../../src/cli.ts -i react --dry-run -y --skip-deps
+```
+
+## Testing
+
+| Status | Count |
+|--------|-------|
+| Type-check | clean |
+| Unit + integration tests | **123 / 123** passing |
+| Build | clean (.js + .d.ts + source maps) |
+
+Tests run on temp-dir fixtures (no network, no real SDK install) and
+validate idempotency, rollback, dry-run, restore round-trip, error catalog
+coverage, telemetry payload contract, and config migration plumbing.
+
+## Roadmap (post-beta)
+
+Beta is shipping intentionally narrow. v0.2 priorities:
+
+1. **Bare React Native** — Podfile + Gradle patchers + iOS/Android
+   validation matrix. Spec:
+   [`docs/architecture/v02-bare-react-native-spec.md`](./docs/architecture/v02-bare-react-native-spec.md).
+2. **Source-maps end-to-end** — upload + symbolication round-trip against
+   `/api/v1/sourcemaps/upload`. Spec:
+   [`docs/architecture/v02-sourcemaps-e2e-spec.md`](./docs/architecture/v02-sourcemaps-e2e-spec.md).
+3. **Astro support** — currently falls through to `js` (env vars only).
+4. **Java SDK host fix** — coordinate with `allstak-java-sdk` to make
+   host configurable.
+5. **Backend SDK framework wiring** — NestJS `main.ts`, Spring Boot
+   `application.yml`, Django/FastAPI/Flask/Rails/.NET/Go/PHP entry-point
+   patching with per-framework fixture validation.
+6. **Telemetry HTTP endpoint** — backend contract pending.
+
+## License
+
+Apache-2.0 — see [`LICENSE`](./LICENSE).
 
-## v0.2 roadmap
+## Issues
 
-See `docs/reports/allstak-unified-sdk-wizard-v0.1-implementation.md` (in the platform monorepo) for the full plan.
+[github.com/allstak-io/sdks/issues](https://github.com/allstak-io/sdks/issues)

package/dist/api/types.d.ts

@@ -1,9 +1,9 @@
 /**
  * TypeScript shapes for the AllStak backend responses the wizard depends on.
  *
- * Source of truth: handler classes in `/Volumes/M.2/MyProjects/allstak/backend/`.
- * If a backend response shape changes incompatibly, bump `apiContractVersion`
- * and add a guard in src/api/http.ts.
+ * Source of truth: AllStak backend (`/api/v1/auth/*`, `/api/v1/projects/*`,
+ * `/ingest/v1/*`). If a backend response shape changes incompatibly, bump
+ * `apiContractVersion` and add a guard in src/api/http.ts.
  */
 export declare const apiContractVersion = "2026-05-07";
 export interface UserSummary {

package/dist/api/types.js

@@ -1,9 +1,9 @@
 /**
  * TypeScript shapes for the AllStak backend responses the wizard depends on.
  *
- * Source of truth: handler classes in `/Volumes/M.2/MyProjects/allstak/backend/`.
- * If a backend response shape changes incompatibly, bump `apiContractVersion`
- * and add a guard in src/api/http.ts.
+ * Source of truth: AllStak backend (`/api/v1/auth/*`, `/api/v1/projects/*`,
+ * `/ingest/v1/*`). If a backend response shape changes incompatibly, bump
+ * `apiContractVersion` and add a guard in src/api/http.ts.
  */
 export const apiContractVersion = '2026-05-07';
 //# sourceMappingURL=types.js.map

package/dist/util/wizard-version.d.ts

@@ -2,5 +2,5 @@
  * Single source of truth for the wizard's own version string. Bumping `package.json`
  * does NOT auto-update this constant — keep them in sync. Tests assert equality.
  */
-export declare const WIZARD_VERSION = "0.1.3";
+export declare const WIZARD_VERSION = "0.1.4";
 //# sourceMappingURL=wizard-version.d.ts.map

package/dist/util/wizard-version.js

@@ -2,5 +2,5 @@
  * Single source of truth for the wizard's own version string. Bumping `package.json`
  * does NOT auto-update this constant — keep them in sync. Tests assert equality.
  */
-export const WIZARD_VERSION = '0.1.3';
+export const WIZARD_VERSION = '0.1.4';
 //# sourceMappingURL=wizard-version.js.map

package/docs/architecture/v02-java-host-fix-spec.md

@@ -22,14 +22,10 @@ SDK-side blocker."
 
 ## Required SDK-side change
 
-Reference the AllStak SDK workspace at:
-
-```
-/Volumes/M.2/MyProjects/AllStak-Projects/sdks/allstak-java-sdk
-```
-
-The change is small but needs to land in the SDK before the wizard's `java`
-integration can graduate from `experimental`:
+Target package: `allstak-java-sdk` (the Java SDK in the AllStak SDK
+monorepo, sibling of `@allstak/wizard`). The change is small but must land
+in the SDK before the wizard's `java` integration can graduate from
+`experimental`:
 
 ### 1. Add a `host` field to `AllStakConfig`
 

package/docs/beta/README.md

@@ -0,0 +1,17 @@
+# `@allstak/wizard@beta` — public beta docs
+
+| Doc | What it covers |
+|-----|----------------|
+| [quickstart](./quickstart.md) | Install + run in five minutes |
+| [react](./react.md) | React (Vite or CRA) integration |
+| [next](./next.md) | Next.js 13+ integration |
+| [node](./node.md) | Vanilla Node.js / TypeScript |
+| [doctor](./doctor.md) | Deterministic diagnostics + `--live-probe` |
+| [restore](./restore.md) | Persistent snapshots + rollback |
+| [config](./config.md) | `allstak.config.*` schema + precedence + migrations |
+| [ci](./ci.md) | Running unattended in CI |
+| [privacy](./privacy.md) | Telemetry contract — what we send and how to disable |
+| [known-limitations](./known-limitations.md) | Honest list of what's NOT supported |
+| [troubleshooting](./troubleshooting.md) | Common errors mapped to fixes |
+| [errors](../errors.md) | Canonical error catalog |
+| [architecture](../architecture/) | Internal design docs (registry, transaction, rollback, etc.) |

package/docs/beta/ci.md

@@ -0,0 +1,122 @@
+# Running in CI
+
+The wizard is designed to run unattended once you've committed an
+`allstak.config.*` and stashed an API key.
+
+## One-shot setup in a CI step
+
+```yaml
+# .github/workflows/setup-allstak.yml (excerpt)
+- name: Configure AllStak
+  env:
+    ALLSTAK_API_KEY: ${{ secrets.ALLSTAK_API_KEY }}
+  run: |
+    npx @allstak/wizard@beta -i react -y \
+      --skip-deps \
+      --release "$GITHUB_SHA"
+```
+
+Why these flags:
+
+- `-y`: skip the confirmation prompt. The wizard refuses with `E_USER_CANCELLED`
+  in non-interactive mode otherwise.
+- `--skip-deps`: don't run a package install — your CI step before this
+  already installed dependencies.
+- `--release "$GITHUB_SHA"`: stamp the deploy commit on every event.
+
+The CLI exits 0 on success, 2 on `WizardError`, and 130 on user cancel
+(impossible in `-y` mode but documented for completeness).
+
+## Doctor in CI (smoke check)
+
+```yaml
+- name: Doctor
+  env:
+    ALLSTAK_API_KEY: ${{ secrets.ALLSTAK_API_KEY }}
+  run: |
+    npx @allstak/wizard@beta --json doctor \
+      --live-probe \
+      --project-id ${{ vars.ALLSTAK_PROJECT_ID }} \
+      > doctor.json
+    jq -e '.outcome == "success"' doctor.json
+```
+
+`--live-probe` sends a real test event and polls for ingestion. Use it as
+a deploy gate — if the ingestion path is broken, fail the deploy before
+users hit it.
+
+## JSON output everywhere
+
+`--json` writes a single JSON object to stdout (status text goes to stderr).
+Pipe it to `jq` or your own parser. Shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "init",
+  "outcome": "success",
+  "errorCode": null,
+  "durationMs": 4200,
+  "events": [...],
+  "diff": [...],
+  "doctor": [...],
+  "data": { ... }
+}
+```
+
+## Telemetry in CI
+
+Telemetry is on by default. To disable:
+
+```bash
+ALLSTAK_WIZARD_TELEMETRY=0 npx @allstak/wizard@beta ...
+# or
+npx @allstak/wizard@beta --no-telemetry ...
+```
+
+See [privacy.md](./privacy.md) for the exact payload shape. Telemetry
+failures NEVER abort the wizard.
+
+## Snapshot retention in CI
+
+Each wizard run writes a snapshot to `.allstak-wizard/backups/`. In CI the
+default retention of 10 is usually fine. To disable pruning entirely
+(useful when you keep a separate audit log):
+
+```bash
+npx @allstak/wizard@beta -i react -y --snapshot-keep 0
+```
+
+To skip persistent snapshots entirely (in-process rollback only) — not
+currently supported. Plans for v0.2.
+
+## Self-hosted in CI
+
+Either pass flags or commit a config:
+
+```bash
+npx @allstak/wizard@beta \
+  --host https://api.allstak.acme.com \
+  --dashboard-host https://app.allstak.acme.com \
+  -i react -y
+```
+
+## Validating the wizard itself
+
+The wizard ships a CI matrix workflow under `.github/workflows/ci.yml` that
+runs install/repair/uninstall/restore cycles against React+Vite, Next, and
+Node fixtures across Node 18/20/22. Fork the workflow if you want to
+gate your own CI on it.
+
+## Recommended pre-deploy chain
+
+```bash
+npm ci
+npm run test
+npx @allstak/wizard@beta config validate
+npx @allstak/wizard@beta -i react -y --release "$GIT_SHA"
+npx @allstak/wizard@beta --json doctor --live-probe \
+  --project-id "$ALLSTAK_PROJECT_ID" \
+  --api-key "$ALLSTAK_API_KEY"
+npm run build
+```