@allstak/wizard 0.1.6 → 0.1.8

package/docs/architecture/patch-pipeline.md

@@ -1,58 +0,0 @@
-# Patch pipeline
-
-How a single `init` invocation flows from CLI to disk.
-
-```
-argv
-  │
-  ▼
-parseCli()
-  │  reporter = createReporter(json ? 'json' : 'human')
-  ▼
-runInit({ ... reporter })
-  │  bootstrapRegistry() / bootstrapSourceMaps() / bootstrapMigrations()
-  │
-  ├─► buildContext()       — projectRoot, framework detection, lifecycle emitter
-  │
-  ├─► registry.require(id) — pick the integration
-  │
-  ├─► integ.detect(ctx)    — compat engine; throws E_COMPAT on failure
-  │
-  ├─► stability gate       — experimental? require --experimental; beta? warn
-  │
-  ├─► integ.plan(ctx)      — print plan; prompt for confirmation unless -y
-  │
-  ├─► lifecycle.beforeInstall
-  ├─► integ.install(ctx)   — package-manager invocation (skipped on --skip-deps)
-  ├─► lifecycle.afterInstall
-  │
-  ├─► snapshotStore.begin(...)  — opens persistent backup directory
-  ├─► tx = new Transaction({ snapshotWriter, dryRun })
-  │
-  ├─► lifecycle.beforePatch
-  ├─► tx.run(() => integ.patch(ctx, tx))
-  │     │
-  │     ├─► writeStandardEnv() ───► patchEnvFile()
-  │     ├─► patchJsModule(entry, ...)
-  │     ├─► appendManagedBlock(entry, ...)
-  │     └─► sourceMapRegistry.get('vite').wire(ctx, tx)
-  │
-  ├─► lifecycle.afterPatch
-  │
-  ├─► snapshotStore.prune(keep)
-  ├─► integ.validate(ctx) — runs doctor, prints report
-  └─► reporter.finalize({ outcome, durationMs, data: { doctor }})
-```
-
-## Where to extend
-
-| Want to add | Touch |
-|-------------|-------|
-| New integration | `src/integrations/<id>/` + `bootstrapRegistry()` |
-| New version rule | `src/integrations/<id>/manifest.ts:compatibility` |
-| New file mutation kind | `src/patchers/` |
-| New bundler source-map provider | `src/sourcemaps/` + `bootstrapSourceMaps()` |
-| New env-var migration | `src/migrations/builtin/` + `bootstrapMigrations()` |
-| New CLI command | `src/commands/` + `src/cli.ts` |
-| New output mode | `src/output/` + `createReporter()` |
-| New telemetry sink | `src/telemetry/provider.ts:setTelemetryProvider()` + lifecycle subscriptions |

package/docs/architecture/registry.md

@@ -1,52 +0,0 @@
-# Registry
-
-## What it is
-
-A single in-memory map from `IntegrationId` → `Integration`. Integrations
-register themselves at boot via `bootstrapRegistry()`. The CLI is integration-
-agnostic — every command accepts `-i <id>`, looks the integration up in the
-registry, and drives the lifecycle.
-
-## Contract
-
-Every integration exposes:
-
-- `id: IntegrationId` — must match the value in its `manifest.id`.
-- `manifest: IntegrationManifest` — machine-readable metadata (versions,
-  capabilities, files, stability level). Surfaced via `allstak-wizard list`,
-  `allstak-wizard list --json`, and the programmatic API.
-- Seven lifecycle methods: `detect`, `plan`, `install`, `patch`, `validate`,
-  `uninstall`, `repair`, `doctor`. See `integration-lifecycle.md`.
-
-## Adding a new integration
-
-1. Pick an `IntegrationId` (add to the union in `src/detect/framework.ts`).
-2. Create `src/integrations/<id>/` with:
-   - `manifest.ts` — fill in stability, capabilities, compatibility, files.
-   - `files.ts` — file-locator helpers (no logic).
-   - `detect.ts` — calls `evaluateCompatibility(manifest, packageJson)` from
-     the compat engine. Don't inline `meetsMinimum(...)` — central rules only.
-   - `patch.ts` — install + env + entry + source-map wiring.
-   - `uninstall.ts` — reverse of `patch.ts`.
-   - `doctor.ts` — read-only health check.
-   - `index.ts` — composes the `Integration` object.
-3. Register in `src/registry/index.ts:bootstrapRegistry()`.
-4. Add a fixture under `fixtures/<id>-*/` if the patch path is non-trivial.
-5. Write tests under `test/integration-<id>.test.mts`.
-
-If the integration is not yet validated end-to-end, set
-`manifest.stability = 'experimental'` and use `simpleScaffold(...)` to keep
-the boilerplate small.
-
-## Stability gating
-
-The orchestrator gates on `manifest.stability`:
-
-- `stable` — runs without warning.
-- `beta` — runs but emits a warning line.
-- `experimental` — refuses to run patching unless `--experimental` is passed.
-- `unsupported` — `detect()` is expected to throw `UnsupportedFrameworkError`
-  and the integration acts as documentation only.
-
-This single-source gating means integrations don't need to repeat the warning
-or the refusal logic — just declare your stability level in the manifest.

package/docs/architecture/rollback.md

@@ -1,47 +0,0 @@
-# Rollback
-
-The wizard has **two** rollback layers with different scopes:
-
-## 1. In-memory transactional rollback (per-run)
-
-`Transaction` snapshots every touched file on first write. If `tx.run(work)`
-throws — or a syntax validator rejects a write — the transaction restores
-each file in reverse order and re-throws the error wrapped in
-`TransactionAbortedError`.
-
-Scope: lasts for one wizard invocation. Does not survive process exit.
-
-## 2. Persistent snapshots (cross-run)
-
-`SnapshotStore` writes a backup directory at
-`<projectRoot>/.allstak-wizard/backups/<timestamp>--<integration>--<random>/`
-containing:
-
-- `manifest.json` — schema-versioned record of what changed (path, kind,
-  size).
-- `files/<rel-path>` — the exact pre-image bytes for each modified file.
-- `files/<rel-path>.allstak-deleted` — empty marker for files that did not
-  exist before the run (so `wizard restore` knows to delete them).
-
-Scope: lives on disk until `SnapshotStore.prune(keep)` removes it (default
-retention is 10 most recent runs in `init.ts`).
-
-## What persistent snapshots are for
-
-- Support / debugging — "show me what the wizard changed yesterday."
-- Future `wizard restore` command (v0.2) — point-in-time restore of any
-  backed-up run.
-- Audit trail when a CI pipeline re-runs the wizard on shared infra.
-
-Snapshots are NOT used by the in-process rollback path — that has its own
-in-memory pre-image. Two layers, one purpose: make every wizard run safe
-both _during_ execution and _after_ commit.
-
-## Failure modes
-
-- If a snapshot directory cannot be written (permissions, full disk), the
-  wizard logs a warning and continues — the transactional rollback path is
-  unaffected because it doesn't depend on the persistent store.
-- If the wizard process is killed mid-write (SIGKILL), in-memory rollback is
-  lost. The persistent snapshot for that run is partial: `manifest.json` was
-  not yet written, so `SnapshotStore.list()` ignores the directory.

package/docs/architecture/sourcemaps.md

@@ -1,53 +0,0 @@
-# Source-map providers
-
-Source-map wiring used to live inside each integration's `patch()` method,
-which made it hard to reuse the Vite plugin wiring for a Vue/Solid integration
-later. v0.1.1 extracted it into a `SourceMapProvider` abstraction.
-
-## Provider contract
-
-```ts
-interface SourceMapProvider {
-  id: 'vite' | 'webpack' | 'next' | 'metro';
-  title: string;
-  pluginPackage: string;
-  detect(ctx): Promise<boolean>;
-  wire(ctx, tx): Promise<void>;
-  unwire(ctx, tx): Promise<void>;
-  status(ctx): Promise<SourceMapStatus>;
-}
-```
-
-Each provider is registered on `sourceMapRegistry` via
-`bootstrapSourceMaps()`. Integrations look providers up by id rather than
-constructing them inline:
-
-```ts
-const vite = sourceMapRegistry.get('vite');
-if (vite && (await vite.detect(ctx))) await vite.wire(ctx, tx);
-```
-
-## Status semantics
-
-`status(ctx)` returns one of:
-
-- `wired` — the plugin import is present and active.
-- `missing` — the bundler exists but the plugin is not wired.
-- `drifted` — the plugin is partially wired (e.g. import added but plugin
-  not invoked); doctor surfaces this as a warning with a `reason`.
-
-## Current providers
-
-| Provider | Status |
-|---|---|
-| `vite` | Validated. AST imports + managed-block hint in `vite.config.*`. |
-| `next` | Validated. Managed-block hint in `next.config.*` (no AST mutation — Next configs vary too much). |
-| `webpack` | Scaffolded. Managed-block hint only; AST mutation deferred (Webpack factory configs are too varied). |
-| `metro` | **Inert in v0.1.** `detect()` returns false; wire/unwire are no-ops. v0.2 will replace with real Gradle hook + iOS post-build. |
-
-## Adding a provider
-
-1. Create `src/sourcemaps/<bundler>.ts` exporting a `SourceMapProvider`.
-2. Register in `src/sourcemaps/index.ts:bootstrapSourceMaps()`.
-3. The integration's `patch.ts` needs no change beyond looking the provider
-   up by id.

package/docs/architecture/stability-levels.md

@@ -1,35 +0,0 @@
-# Stability levels
-
-Replaces the binary `validated: boolean` flag. Every integration declares one
-of four stability levels in its `manifest.stability`:
-
-| Level | Behaviour | Doctor | When to use |
-|-------|-----------|--------|-------------|
-| `stable` | Runs without warning. | All checks must pass. | Fully validated end-to-end, fixture-tested, CLI-smoke-tested. |
-| `beta` | Runs but emits a warning line citing the manifest's `stabilityNote`. | Same checks as stable, but `degraded` summary acceptable. | Implementation complete, missing one of: live event ingestion, native build, multi-version matrix. |
-| `experimental` | Refuses to run patching unless `--experimental` is passed. | Always reports `broken` to surface the gap. | Scaffolded — install + env writing only. Framework wiring deferred. |
-| `unsupported` | `detect()` throws `UnsupportedFrameworkError` regardless of flags. | Always reports `broken`. | Intentionally refused (e.g. bare React Native in v0.1). |
-
-## Why four levels, not two
-
-A binary flag forced us to either lie ("validated") or refuse to register
-(can't surface to `list`). The four-level model lets us:
-
-- Be honest about what is and isn't tested (`beta` is real, validated, but
-  not yet at parity with `stable` on one axis).
-- Let users opt into experimental integrations without flipping a global
-  feature flag.
-- Keep `unsupported` integrations in the registry as documentation — they
-  show up in `list`, throw a clear pointer to manual setup, and prevent
-  accidental partial-support.
-
-## Where the gating lives
-
-`src/integrations/_scaffold.ts` handles the gating uniformly. Integrations
-declare their level in the manifest; `buildScaffold()` derives the right
-behaviour. `src/commands/init.ts` inspects `integration.manifest.stability`
-to decide whether to print the beta warning or refuse without
-`--experimental`.
-
-This means contributors adding a new integration only need to set one field
-to control the user-facing behaviour — never edit the orchestrator.

package/docs/architecture/transaction.md

@@ -1,51 +0,0 @@
-# Transaction
-
-`src/transaction/tx.ts`. Ensures every wizard run is atomic with respect to
-the user's source tree.
-
-## Contract
-
-A `Transaction`:
-
-1. **Snapshots** every file before its first write (in-memory pre-image).
-2. **Writes** the new content via `tx.write(path, content, validator?)`.
-3. Optionally runs a **syntax validator** on the new content; a thrown error
-   triggers immediate rollback of the file.
-4. On success, **commits** — pre-images are dropped from memory but the
-   `SnapshotWriter` flushes them to `.allstak-wizard/backups/` for audit.
-5. On any thrown error inside `tx.run(work)`, **rolls back** all writes in
-   reverse order, then re-throws as `TransactionAbortedError`.
-
-## Semantics
-
-- The same path written multiple times only snapshots once (the first call
-  captures the true pre-image).
-- Newly created files are restored to non-existence on rollback (we delete the
-  newly-created file).
-- `tx.delete(path)` is staged the same way: snapshot the deleted content,
-  remove from disk, restore on rollback.
-- `dryRun: true` records the planned diff but skips disk I/O entirely. Both
-  rollback and snapshot persistence become no-ops.
-
-## Usage pattern
-
-```ts
-const tx = new Transaction({ cwd, dryRun, snapshotWriter });
-await tx.run(async () => {
-  await tx.write(envPath, newEnvContent);
-  await patchJsModule(tx, entryPath, (mod) => ensureImport(mod, ...));
-  await appendManagedBlock(tx, entryPath, '...', { style: 'slash', validateJs: true });
-});
-// On exception inside the body, ALL three writes are rolled back.
-```
-
-## Why a custom transaction layer
-
-We considered `git worktree` / `git stash` for atomicity but rejected it:
-
-- Many AllStak users run the wizard in CI on a clean worktree where there's
-  nothing to stash and no `.git` to query.
-- Wizard ops touch a small set of well-known files, not arbitrary trees — a
-  custom transactional layer is ~150 LoC and has zero external deps.
-- We want syntax validation on writes (re-parse the file with magicast) which
-  would be awkward to express through git plumbing.

package/docs/architecture/v02-bare-react-native-spec.md

@@ -1,92 +0,0 @@
-# v0.2 spec — Bare React Native integration
-
-**Status:** UNSUPPORTED in v0.1.x — wizard refuses with `UnsupportedFrameworkError`.
-
-This spec is what v0.2 must implement before `react-native` flips from `unsupported` to `experimental` (and eventually `beta`).
-
----
-
-## Why bare RN is hard
-
-Bare RN integration is the only wizard target that touches **three** ecosystems at once:
-
-1. JavaScript / TypeScript source (entry file wrap).
-2. **iOS native** — Podfile + AppDelegate.swift modifications, CocoaPods install.
-3. **Android native** — settings.gradle + app/build.gradle, Gradle plugin classpath, AndroidManifest.
-
-Any one of these going wrong bricks `xcodebuild` or `./gradlew assembleDebug`. Wizard cannot validate that without running real device builds, which the v0.1.x test infrastructure does not have.
-
-Expo (config-plugin path) is a strict subset of this surface and is already partially scaffolded (`stability: experimental`).
-
----
-
-## Validation matrix v0.2 must pass
-
-Before flipping `stability` from `unsupported`:
-
-| Path | Validation |
-|------|------------|
-| Patch idempotency | `init` → `init` produces byte-identical project (already a wizard invariant; just needs a fixture to assert against). |
-| iOS sim build | `npx react-native run-ios` succeeds on iOS 16/17/18 simulators against a fresh fixture; AllStak crash hook captured a synthetic crash. |
-| Android emu build | `npx react-native run-android` succeeds against API 31/33/34 emulators. |
-| Hermes source-map round-trip | A symbolicated stack frame from a bundled-and-uploaded JS file resolves on the dashboard. |
-| Uninstall | After `init` then `uninstall`, both `xcodebuild` and `gradlew assembleDebug` still pass; no dangling Pod or Gradle entries. |
-| Repair | After hand-deleting our managed Podfile region, `repair` reinstates it without touching any other Podfile content. |
-| New Architecture (Fabric / TurboModules) | If the project enables `newArchEnabled=true`, the integration must not regress build. |
-
-The v0.1.x repo already supports Fixture-based testing in `fixtures/`. v0.2 needs a `fixtures/react-native-bare/` (and matching `react-native-expo/`) plus a CI runner that has Xcode + Android emulator access.
-
----
-
-## Files the integration patches
-
-### iOS
-
-- `ios/Podfile` — append (inside the project's main target):
-  ```ruby
-  pod 'AllStakRN', :path => '../node_modules/@allstak/react-native'
-  ```
-- `ios/<App>/AppDelegate.{m,mm,swift}` — call `[AllStak start]` from `application:didFinishLaunchingWithOptions:`.
-  - Wizard MUST detect Obj-C vs Swift AppDelegate and choose the right insertion.
-  - All insertions wrapped in markers (`// >>> allstak-wizard:v1 ...`).
-
-### Android
-
-- `android/settings.gradle` — append `include ':allstak-react-native'` and the matching `project(...)` line.
-- `android/app/build.gradle` — `dependencies { implementation project(':allstak-react-native') }`.
-- `android/app/src/main/java/.../MainApplication.{java,kt}` — register the package in `getPackages()`.
-- Wizard MUST read `org.gradle.jvmargs` to detect Hermes and conditionally wire the source-map post-build hook from `allstak-react-native/build-hooks/allstak-sourcemaps.gradle`.
-
-### JavaScript
-
-- `index.js` / `App.tsx` — wrap root component in `<AllStakProvider>` (same pattern as `react`).
-- `metro.config.js` — extend `transformer.hermesParser` only when needed; default leave alone.
-
----
-
-## Open questions for v0.2 design
-
-1. **Does `pod install` run inside the wizard's transaction?** Recommendation: NO. Pod install mutates `Podfile.lock` and the `Pods/` tree atomically; rolling that back is not feasible. The wizard should print "Pods updated; run `pod install` once more if you see linker errors" and let the user own that step.
-2. **Does the integration block on a connected emulator?** Recommendation: NO. The wizard is offline-first; users can run `react-native run-ios` themselves. Integration tests in CI gate on emulator presence.
-3. **Expo bare workflow** (post-`expo prebuild`) — is this `expo` integration (config-plugin path) or `react-native` (bare path)? Recommendation: detect `npx expo prebuild` evidence (presence of `ios/` AND a `app.json` with `expo` key) and offer the user a choice.
-4. **Old Architecture vs New Architecture** — wizard reads `android/gradle.properties:newArchEnabled`. If true, the integration must include the Fabric component registration (a more involved Gradle change). v0.2 might gate this behind `--experimental` even after the rest of bare RN is `beta`.
-
----
-
-## Wizard-side plumbing already in place
-
-These already exist and don't need re-work:
-
-- The `react-native` integration object refuses cleanly with a clear `UnsupportedFrameworkError` and pointer to manual docs.
-- The `IntegrationManifest` has `wire-native-ios` / `wire-native-android` capabilities to declare in v0.2.
-- `Transaction` + `SnapshotStore` already handle the JS-side patches transactionally.
-
----
-
-## Recommended ticket breakdown
-
-1. **RN-1** Add `fixtures/react-native-bare/` with a minimal RN 0.74 + 0.75 + 0.76 project. CI runner with Xcode + Android emu (use macOS GitHub-hosted runner for iOS, Ubuntu + Android emulator for Android).
-2. **RN-2** Implement `src/integrations/react-native-bare/` (renamed from current placeholder) with `manifest`/`detect`/`patch`/`uninstall`/`doctor`. Reuse `_shared.ts` and `_scaffold.ts`.
-3. **RN-3** Native patchers: `src/patchers/podfile.ts`, `src/patchers/gradle.ts`, `src/patchers/appdelegate.ts`. Each writes through `Transaction` with a parser-based syntax check.
-4. **RN-4** End-to-end `pod install` + `gradle assembleDebug` smoke in CI gated to RN-2.
-5. **RN-5** Hermes source-map upload roundtrip — depends on the source-maps E2E spec landing first.

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

@@ -1,121 +0,0 @@
-# v0.2 spec — Java SDK host configurability
-
-**Status:** PROPOSED. No code in `allstak-java-sdk` has been modified by this wizard release.
-
----
-
-## Problem
-
-The wizard's `--host` / `--ingest-host` / `--dashboard-host` flags allow users
-to point the wizard at a self-hosted AllStak deployment. For most SDKs this
-flows through to a runtime `host` field on `init()` config.
-
-For `sa.allstak:allstak-spring-boot-starter` and `sa.allstak:allstak-java-core`,
-the host is **hardcoded** to `https://api.allstak.sa` in the SDK source.
-Wizard's `--host` is silently a no-op for Java users — events go to the wrong
-backend without any error.
-
-Per the v0.1 implementation report (2026-05-07): "filed below as a v0.2
-SDK-side blocker."
-
----
-
-## Required SDK-side change
-
-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`
-
-```java
-public class AllStakConfig {
-  private String apiKey;
-  private String environment;
-  private String release;
-  private String serviceName;
-  private String host;          // NEW — defaults to "https://api.allstak.sa"
-  // …existing fields…
-
-  // Builder method:
-  public Builder host(String host) { this.host = host; return this; }
-}
-```
-
-### 2. Read `ALLSTAK_HOST` env var in the auto-config
-
-```java
-@ConfigurationProperties(prefix = "allstak")
-public class AllStakProperties {
-  // existing fields…
-  private String host = System.getenv().getOrDefault("ALLSTAK_HOST", "https://api.allstak.sa");
-}
-```
-
-### 3. Spring Boot `application.yml` exposure
-
-```yaml
-allstak:
-  api-key: ${ALLSTAK_API_KEY}
-  host: ${ALLSTAK_HOST:https://api.allstak.sa}    # NEW
-```
-
-### 4. Pass `host` through to the HTTP transport
-
-The transport class (likely `AllStakHttpClient` or similar) currently has a
-hardcoded base URL. Replace with `config.getHost()`.
-
----
-
-## Compatibility implications
-
-- **Backwards compatible:** existing users who pass nothing get the old
-  default. No breaking change to the public API.
-- **Bumps the minor version** — first SDK release with the field should be
-  `0.2.0` (not `0.1.x`) per semver.
-- **Wizard manifest update:** once shipped, edit
-  `src/integrations/java.ts` and the manifest's `compatibility` to require
-  the new minimum version: `{ name: 'sa.allstak:allstak-java-core',
-  minVersion: '0.2', maxMajorExclusive: null, required: true }`.
-- **Wizard's `java` integration warning** can be removed from
-  `manifest.stabilityNote` once v0.2.0 of the SDK is the minimum.
-
----
-
-## Wizard-side validation v0.2 must add
-
-After the SDK ships:
-
-1. Update `src/integrations/java.ts` to actually patch `pom.xml` /
-   `build.gradle` (currently the integration is `experimental` and only
-   writes env vars).
-2. Add `fixtures/spring-boot/` with a minimal Spring Boot 3.x project
-   (`./mvnw test` runs in CI).
-3. Doctor stage `event-ingest` should be runnable against a Java-emitted
-   event (the existing doctor probe is a generic event so this Just Works
-   once the SDK respects `--host`).
-
----
-
-## Why the wizard does NOT change this from this side
-
-- CLAUDE.md's monorepo policy: "Do not modify unrelated SDKs unless required."
-- Even with permission, modifying a Java SDK from a TypeScript wizard
-  session has no path to validate the change (no `mvn` in the wizard's CI
-  matrix).
-- The change is small enough (~20 LoC) that it belongs in a focused PR
-  against `allstak-java-sdk` rather than being smuggled in through wizard
-  work.
-
----
-
-## Action items for whoever picks this up
-
-1. Open a ticket against `allstak-java-sdk` referencing this spec.
-2. Implement the `host` field + env-var lookup in the SDK.
-3. Bump SDK to `0.2.0` and publish to Maven Central.
-4. Update `src/integrations/java.ts` manifest to require `0.2+`.
-5. Remove the warning blurb from the manifest's `stabilityNote`.
-6. Move the integration's `stability` from `experimental` toward `beta`
-   once Spring Boot fixture validation lands.

package/docs/architecture/v02-sourcemaps-e2e-spec.md

@@ -1,157 +0,0 @@
-# v0.2 spec — Source-maps end-to-end roundtrip
-
-**Status:** Wizard wires bundler plugins via `SourceMapProvider` (v0.1.1) but
-does NOT yet validate the upload → release-binding → symbolication chain
-against the live backend. This spec documents what v0.2 must add.
-
----
-
-## What works today (v0.1.x)
-
-- `vite` provider: imports `allstakSourcemaps` from `@allstak/react/vite`, adds it to the real Vite `plugins` array, and enables `build.sourcemap`.
-- `next` provider: managed-block hint pointing the user at `withAllStak`.
-- `webpack` provider: managed-block hint only.
-- `metro` provider: intentionally inert; `detect()` returns false.
-- `doctor` reports per-provider `wired` / `drifted` / `missing` state.
-
-What this gives us: the bundler is correctly configured to produce + upload
-source maps. What it does NOT verify: that uploaded maps actually resolve
-stack frames in the dashboard.
-
----
-
-## Backend contract (verified 2026-05-07)
-
-Endpoint:
-
-```
-POST /api/v1/sourcemaps/upload?projectId=:id&release=:version&fileName=:path&bundleUrl=:url
-  Content-Type: application/json
-  Authorization: Bearer <user JWT>
-
-  Body: raw .map JSON content (size limit 16 MB)
-
-  Response: 200 OK
-  {
-    "id": "uuid",
-    "release": "1.2.3",
-    "fileName": "assets/main-abc123.js.map",
-    "sizeBytes": 12345,
-    "uploadedAt": "2026-05-07T..."
-  }
-```
-
-Server-side resolution: the dashboard's error detail view symbolicates frames
-on read by looking up `(projectId, release, fileName)`. Maps are stored
-indefinitely (no TTL).
-
-Symbolication endpoint (used by error-detail UI; we can use it to verify):
-
-```
-POST /api/v1/sourcemaps/symbolicate
-  Body: { projectId, release, frames: [stackString] }
-  Response: { release, totalFrames, resolvedFrames, frames: [{ raw, resolved }] }
-```
-
----
-
-## Validation matrix v0.2 must pass
-
-| # | Check | Pass condition |
-|---|-------|----------------|
-| 1 | Upload happens during `npm run build` | Per-bundler post-build hook actually POSTs `.map` files. |
-| 2 | Release binding | Uploaded maps are queryable by `(projectId, release)`. |
-| 3 | Round-trip resolution | Send a synthetic event with a stack frame referencing the uploaded bundle → symbolicate endpoint resolves it to the original source line. |
-| 4 | Idempotent upload | Re-running build with same `(release, fileName)` is a no-op or a clean overwrite — never a duplicate. |
-| 5 | Auth scope | Upload requires JWT (not API key). Wizard's `requireUserCredentials` already handles this. |
-
----
-
-## What v0.2 needs to build
-
-### A. A real upload runner
-
-`src/sourcemaps/upload.ts`:
-
-```ts
-export async function uploadSourceMap(
-  apiHost: string,
-  accessToken: string,
-  params: {
-    projectId: string;
-    release: string;
-    fileName: string;     // e.g. "assets/main-abc123.js"
-    bundleUrl?: string;   // public URL of the bundle (helps dashboard match)
-    mapContent: string;   // raw JSON from .map
-  },
-): Promise<{ id: string }> {
-  // Use apiRequest from src/api/http.ts with body=mapContent and contentType='application/json'.
-}
-```
-
-This already has a slot in `src/api/http.ts` (the `contentType` override
-parameter exists for exactly this case).
-
-### B. A `wizard sourcemaps upload` CLI subcommand
-
-```bash
-allstak sourcemaps upload \
-  --project-id <uuid> \
-  --release "$GIT_SHA" \
-  --build-dir dist \
-  --pattern "**/*.js.map"
-```
-
-Walks `build-dir`, POSTs each `.map` file, prints the upload manifest. Reuses
-`getCredentialStore()` + `requireUserCredentials()`.
-
-### C. End-to-end doctor stage
-
-Extend `runDoctor` with a new stage `source-maps-e2e` that runs only with
-`--live-probe`:
-
-1. Build a tiny known fixture into a temp dir.
-2. Upload its `.map`.
-3. Send a probe event whose stack frame points at the uploaded bundle.
-4. Hit `/api/v1/sourcemaps/symbolicate` and assert `resolvedFrames > 0`.
-
-### D. CI matrix entry
-
-Add a `source-maps-e2e` job to the wizard's CI workflow gated on a
-repository secret (`ALLSTAK_E2E_API_KEY` + `ALLSTAK_E2E_PROJECT_ID`).
-Without those secrets the job skips.
-
----
-
-## Risks
-
-1. **`.map` files can be huge** (50MB+ for production bundles). Backend
-   currently caps at 16MB. v0.2 should either:
-   - Detect maps larger than the cap and skip with a warning, OR
-   - Negotiate a larger cap with the backend team.
-2. **`bundleUrl` parameter is optional but improves resolution accuracy.**
-   The wizard should compute it from the project's deploy target where
-   possible (Vercel? Netlify? Cloudflare Pages? — heuristics).
-3. **Hermes maps require a different upload format.** Bytecode → JS source
-   resolution is a separate symbolication pipeline; the v0.1 wizard does NOT
-   support this. Document explicitly when implementing.
-4. **Token rotation during long uploads.** The user JWT has a 15-minute TTL.
-   If uploading 100 `.map` files takes >15 minutes, the wizard must
-   `refreshTokens()` mid-upload. The credential store + auth client already
-   support this; just needs a wrapper.
-5. **Idempotency**: backend probably accepts the same `(release, fileName)`
-   twice and overwrites. Verify before relying on this.
-
----
-
-## Why this is deferred
-
-End-to-end validation requires:
-- A live AllStak instance (production or staging).
-- A real org + project the engineer can write to.
-- Credentials with both ingest scope AND user scope.
-- The ability to assert dashboard-side symbolication output.
-
-None of these are available in the v0.1.x wizard test environment. The
-provider abstraction landed in v0.1.1 specifically so this work can plug in
-without rewriting integrations.