@allstak/wizard 0.1.7 → 0.1.8

package/docs/beta/restore.md

@@ -1,84 +0,0 @@
-# `allstak restore`
-
-Every wizard mutation is captured in a persistent snapshot under
-`.allstak-wizard/backups/<timestamp>--<integration>--<random>/`. The
-`restore` family lets you inspect and roll back those snapshots.
-
-## Subcommands
-
-```bash
-npx @allstak/wizard@beta restore list
-npx @allstak/wizard@beta restore show <id|latest>
-npx @allstak/wizard@beta restore diff <id|latest>
-npx @allstak/wizard@beta restore apply <id|latest> [--files=a,b,c] [--dry-run]
-```
-
-`<id>` is the trailing slug of a backup directory. `latest` always
-resolves to the most recent snapshot.
-
-## What's in a snapshot
-
-```
-.allstak-wizard/backups/2026-05-07T..--react--abc123/
-  manifest.json                    schemaVersion, integration, files[], dryRun, label
-  files/
-    src/main.tsx                   pre-image bytes (UTF-8)
-    .env.local                     pre-image bytes
-    .env.local.allstak-deleted     marker (file did not exist before)
-```
-
-Manifests and pre-images are plain text — they're safe to inspect with `cat`.
-
-## Common workflows
-
-### "I made a mess, give me my files back"
-
-```bash
-npx @allstak/wizard@beta restore apply latest
-```
-
-Confirms before writing. Pass `-y` to skip confirmation.
-
-### "What did the wizard change vs my current state?"
-
-```bash
-npx @allstak/wizard@beta restore diff latest
-```
-
-Each file shows one of: `identical`, `modified`, `created-since`, or
-`deleted-since`.
-
-### "Restore one file from a specific run"
-
-```bash
-npx @allstak/wizard@beta restore apply 2026-05-07T..--react--abc123 \
-  --files=src/main.tsx,.env.local
-```
-
-### "What WOULD restore do?"
-
-```bash
-npx @allstak/wizard@beta restore apply latest --dry-run
-```
-
-## Retention
-
-`init` prunes old snapshots after a successful run. The default keeps the
-10 most recent — override with `--snapshot-keep <n>` (0 disables pruning).
-`repair` and `uninstall` also write snapshots but do NOT prune.
-
-## Transactional
-
-Restoring is itself a transaction — partial failure rolls back to the
-pre-restore state. If a file in the snapshot is missing on disk, the
-restore reports `skipped` for that file and continues.
-
-## Limitations
-
-- Restoring across wizard major versions is supported but a `manifest.json`
-  with a `schemaVersion` higher than the running wizard's is refused.
-- Snapshots live in your repo by default. Add
-  `.allstak-wizard/` to `.gitignore` to keep them out of git (the wizard
-  does not auto-edit your `.gitignore`).
-- Snapshots are NOT encrypted. Don't store them in a public artifact bucket
-  — they contain the original contents of files the wizard touched.

package/docs/beta/troubleshooting.md

@@ -1,133 +0,0 @@
-# Troubleshooting
-
-Common failure modes mapped to canonical error codes (see [errors.md](../errors.md)).
-
-## "I just ran `allstak login` and got `E_AUTH_FAILED`"
-
-- The OTP code expires after ~10 minutes. Run `login` again to request a new one.
-- Codes are 4–8 digits. If you typed an extra space, the wizard rejects with
-  the same code.
-- If you see `OTP_RATE_LIMITED` in the subcode, wait a minute and retry.
-
-## "`E_AUTH_REQUIRED` from `orgs list` but I am logged in"
-
-You were logged in to a different host. The wizard scopes credentials by
-host. Check `allstak whoami --verify` and rerun with the matching `--host`,
-or re-run `login --host <url>`.
-
-## "`E_AUTH_EXPIRED` after a long break"
-
-The refresh token was probably revoked (server-side logout, password reset,
-or it just expired). Run `allstak logout && allstak login`.
-
-## "`E_NETWORK_FAILED` everywhere"
-
-- Verify the configured host with `allstak whoami` (it prints the host).
-- Pass `--debug` and re-run; the underlying message includes the URL.
-- For self-hosted: confirm DNS + TLS are working from the wizard's host.
-
-## "`E_UNSUPPORTED_FRAMEWORK` even though I'm using React"
-
-- `package.json` may not declare `react` directly. The wizard reads
-  `dependencies` + `devDependencies`.
-- For monorepos, run the wizard from the **package directory**, not the
-  root.
-- Pass `-i react` explicitly if detection is ambiguous.
-
-## "`E_UNSUPPORTED_VERSION` but my React/Next is current"
-
-The compat engine reads the version range from `package.json`. If you have
-`"react": "*"` it cannot infer a minimum and reports too-old. Pin a real
-version range in `package.json`.
-
-## "`E_PACKAGE_MANAGER_CONFLICT`"
-
-Two lockfiles in the project root (e.g. both `pnpm-lock.yaml` and
-`package-lock.json`). The wizard refuses to guess. Delete the stale one.
-
-## "`E_PATCH_FAILED` mid-run"
-
-The transaction layer ALREADY rolled back your files. Re-run with
-`--debug` to see which patcher threw. Common causes:
-
-- A pre-existing syntax error in the file we tried to patch — fix the
-  syntax first, re-run the wizard.
-- File permissions denied on the entry file or `.env.local`.
-
-If rollback itself failed (`E_PATCH_ROLLBACK_FAILED`):
-
-```bash
-allstak restore list
-allstak restore apply <id>
-```
-
-## "`E_RESTORE_FAILED: No snapshot matches "<id>""
-
-`allstak restore list` shows what's available. Use the trailing slug
-(e.g. `2026-05-07T..--react--abc123`) or just `latest`.
-
-## "`E_INGEST_VERIFY_FAILED` on `--live-probe`"
-
-- The probe uses `--api-key` (project-scoped). If the key was issued for
-  a different project than `--project-id`, verification will never see the
-  event. Check both match.
-- The probe waits 60s by default. Increase via
-  `--live-probe-timeout 120000` if your backend is slow.
-- Open the dashboard URL printed in the probe output and look for the
-  fingerprint manually. The event id is in the JSON output even when
-  polling times out.
-
-## "`E_CONFIG_INVALID` after editing `allstak.config.ts`"
-
-```bash
-allstak config validate
-```
-
-prints the exact path-to-blame (e.g. `selfHosted.apiHost — expected
-absolute URL, got "api.acme"`). Fix and rerun.
-
-## "`E_CONFIG_MIGRATION_FAILED`"
-
-The migration runner refuses on:
-
-- A `schemaVersion` higher than the wizard supports (subcode
-  `E_CONFIG_FUTURE_VERSION`) — upgrade `@allstak/wizard`.
-- A migration that didn't bump the version correctly (subcode
-  `E_MIGRATION_NO_BUMP`) — file an issue, this is a wizard bug.
-
-## "`E_USER_CANCELLED` in CI"
-
-You forgot `-y`. The wizard refuses to apply changes without it in
-non-interactive mode.
-
-## "Wizard hung at the login OTP prompt in CI"
-
-CI has no TTY, so `@clack/prompts` rejects. Pass `--email` AND `--code` (or
-use a long-lived API key with `--api-key` instead of logging in).
-
-## "Telemetry warning showed up in my CI logs"
-
-Telemetry is on by default. To silence:
-
-```bash
-ALLSTAK_WIZARD_TELEMETRY=0
-# or
-allstak --no-telemetry ...
-```
-
-## "I see `// >>> allstak-wizard:v1` in my git diff"
-
-That's the wizard's idempotency marker. It's intentional — re-runs replace
-the block in place; `uninstall` removes it. Commit it; do not hand-edit
-inside the markers (your edits will be overwritten on the next run).
-
-## Last resort: nuke everything
-
-```bash
-allstak uninstall -i react -y    # remove SDK + patches
-allstak logout                   # clear credentials
-rm -rf .allstak-wizard/          # drop persistent snapshots
-```
-
-The local credential store on macOS may keep the keychain entry until you
-explicitly clear it: `security delete-generic-password -s allstak-wizard`.