anhedral 0.4.1 → 0.6.0

package/docs/references/manual-scaffolding.md

@@ -1,403 +0,0 @@
-# Manual Anhedral scaffolding
-
-Use this procedure to build an Anhedral-style workspace without invoking the Anhedral CLI or importing its generator. Complete the phases in order. Do not stop after framework initialization: shared contracts, integration wiring, tests, root scripts, environment examples, CI, and deployment files are part of the scaffold.
-
-## Contents
-
-1. Record inputs and resolve modules
-2. Establish the workspace contract
-3. Create root configuration
-4. Create shared packages
-5. Create the API
-6. Create client surfaces
-7. Wire optional features
-8. Configure environments and providers
-9. Install, migrate, and verify
-10. Audit completeness
-11. Work from the Anhedral source repository
-
-## 1. Record inputs and resolve modules
-
-Record these values before editing:
-
-- `projectName`: a valid npm package name; use it for the root package and child package prefixes.
-- `displayName`: human-readable product name; escape it for every JSON, JavaScript, HTML, and Markdown context.
-- requested app surfaces: `web`, `mobile`, `api`, `desktop`, `extension`.
-- requested features: `db`, `auth`, `billing`, `storage`, `native-subscriptions`, `electron-updater`.
-- toolchain policy: exact tested versions for reproducibility, or current compatible versions when the user explicitly wants upgrades.
-
-Resolve the transitive closure before writing files:
-
-```text
-auth                 -> api + db
-billing              -> auth -> api + db
-storage              -> auth -> api + db
-native-subscriptions -> mobile + billing -> auth + api + db
-electron-updater     -> desktop
-```
-
-If no modules were specified, select all five surfaces and all six features. Never create a feature without its prerequisites. Keep normalized order `web, mobile, api, desktop, extension, db, auth, billing, storage, native-subscriptions, electron-updater` when displaying or recording a plan.
-
-Choose Node `^20.19.0 || >=22.12.0` unless mobile is selected. Expo mobile requires `^22.13.0 || ^24.3.0 || >=25`. Use one root pnpm workspace and one root lockfile; never leave nested lockfiles, workspaces, `.git` directories, or `node_modules` inside apps.
-
-Use this stable baseline when current source is unavailable. It was verified on 2026-07-15; keep each version exact and update the baseline as one tested set rather than upgrading packages independently:
-
-```text
-pnpm 10.34.5; turbo 2.9.14; TypeScript 5.9.3; @types/node 20.19.43
-contracts: zod 4.2.1
-db: @neondatabase/serverless 1.0.2, drizzle-orm 0.45.2,
-    drizzle-kit 0.31.7, dotenv 17.2.3, tsx 4.20.6
-api: fastify 5.8.5, @fastify/cors 11.1.0, @fastify/compress 8.3.0,
-     @fastify/helmet 13.0.2, @fastify/rate-limit 10.3.0,
-     @clerk/fastify 3.1.51, @aws-sdk/client-s3 3.1047.0,
-     @aws-sdk/s3-request-presigner 3.1047.0, ably 2.24.0, vitest 4.1.0
-web: next 16.2.11, react/react-dom 19.2.3, @clerk/nextjs 7.5.18,
-     @clerk/ui 1.25.3, tailwindcss and @tailwindcss/postcss 4.1.18
-mobile: expo 56.0.16, expo-router 56.2.15, react-native 0.85.3,
-        @clerk/expo 3.7.5, expo-secure-store 56.0.4,
-        react-native-purchases/react-native-purchases-ui 10.4.2
-desktop: electron 43.1.1, electron-builder 26.15.3, vite 7.3.6,
-         @vitejs/plugin-react 5.2.0, @clerk/clerk-js 6.25.3,
-         electron-updater 6.8.9 when electron-updater is selected
-extension: wxt 0.20.27, @wxt-dev/module-react 1.2.2,
-           @clerk/chrome-extension 3.1.52, tailwindcss 3.4.19
-shared UI: clsx 2.1.1, tailwind-merge 3.4.0
-```
-
-Expo's package uses TypeScript 6.0.3 and its SDK-compatible React Native support packages from `src/dependencies.ts`; do not force the root TypeScript version into mobile.
-
-## 2. Establish the workspace contract
-
-Create only selected branches of this tree. A bracketed condition makes the file required exactly when true.
-
-```text
-<root>/
-  .env.example
-  .github/workflows/anhedral-ci.yml
-  .gitignore
-  .vercelignore
-  README.md
-  PRODUCTION.md
-  package.json
-  pnpm-workspace.yaml
-  turbo.json
-  vercel.json
-  scripts/verify-db-migrations.mjs                         [db]
-  packages/contracts/{package.json,tsconfig.json,src/index.ts} [api]
-  packages/api-client/{package.json,tsconfig.json,src/index.ts} [api + any client]
-  packages/realtime/{package.json,tsconfig.json,src/index.ts}   [billing + any client]
-  packages/db/{package.json,tsconfig.json,drizzle.config.ts,.env.example} [db]
-  packages/db/src/{index.ts,migrate.ts,schema.ts}           [db]
-  packages/db/migrations/.gitkeep                           [db]
-  apps/api/{package.json,tsconfig.json,vitest.config.ts,.env.example,.gitignore} [api]
-  apps/api/src/{application.ts,env.ts,index.ts,routes.ts}    [api]
-  apps/api/src/auth.ts                                      [auth]
-  apps/api/src/billing.ts                                   [billing]
-  apps/api/src/realtime.ts                                  [billing]
-  apps/api/src/storage.ts                                   [storage]
-  apps/api/tests/{health.test.ts,env.test.ts}                [api]
-  apps/api/tests/revenuecat-webhook.test.ts                  [billing]
-  apps/api/tests/storage.test.ts                             [storage]
-  apps/assets-private-proxy/{package.json,wrangler.jsonc}    [storage]
-  apps/assets-private-proxy/src/index.js                     [storage]
-  cloudflare/{README.md,r2-cors.template.json}               [storage]
-  apps/web/{package.json,tsconfig.json,next-env.d.ts,next.config.ts,postcss.config.mjs,components.json,.env.example} [web]
-  apps/web/app/{layout.tsx,page.tsx,globals.css}             [web]
-  apps/web/components/ui/{button.tsx,card.tsx}               [web]
-  apps/web/lib/utils.ts                                     [web]
-  apps/web/{lib/api.ts,hooks/use-api-client.ts}              [web + api]
-  apps/web/components/account-actions.tsx                   [web + auth]
-  apps/web/{hooks/use-entitlement.ts,components/subscription-status.tsx} [web + billing]
-  apps/mobile/{package.json,app.json,tsconfig.json,expo-env.d.ts,eas.json,.env.example,.gitignore} [mobile]
-  apps/mobile/app/{_layout.tsx,index.tsx}                    [mobile]
-  apps/mobile/{lib/api.ts,hooks/use-api-client.ts}           [mobile + api]
-  apps/mobile/components/account-controls.tsx               [mobile + auth]
-  apps/mobile/hooks/use-entitlement.ts                      [mobile + billing]
-  apps/mobile/lib/subscriptions.ts                           [native-subscriptions]
-  apps/desktop/{package.json,tsconfig.json,tsconfig.main.json,vite.config.ts,postcss.config.mjs,components.json,index.html,.env.example} [desktop]
-  apps/desktop/scripts/dev.mjs                              [desktop]
-  apps/desktop/src/main/{main.ts,preload.cts}                [desktop]
-  apps/desktop/src/renderer/{main.tsx,styles.css,lib/utils.ts} [desktop]
-  apps/desktop/src/renderer/components/ui/button.tsx        [desktop]
-  apps/desktop/src/renderer/lib/api.ts                       [desktop + api]
-  apps/desktop/src/renderer/lib/auth.ts                      [desktop + auth]
-  apps/desktop/src/renderer/hooks/use-entitlement.ts        [desktop + billing]
-  apps/desktop/electron-builder.env.example                 [electron-updater]
-  apps/desktop/scripts/publish-updates.mjs                  [electron-updater]
-  apps/desktop-updater-worker/{package.json,wrangler.jsonc} [electron-updater]
-  apps/desktop-updater-worker/src/index.js                  [electron-updater]
-  cloudflare/desktop-updates.md                             [electron-updater]
-  apps/extension/{package.json,tsconfig.json,wxt.config.ts,postcss.config.cjs,tailwind.config.cjs,components.json,.env.example,README.md} [extension]
-  apps/extension/src/{styles/main.css,lib/utils.ts}          [extension]
-  apps/extension/src/components/ui/button.tsx               [extension]
-  apps/extension/src/entrypoints/{background.ts,sidepanel/index.html,sidepanel/main.tsx,sidepanel/app.tsx} [extension]
-  apps/extension/src/contexts/auth-context.tsx              [extension + auth]
-  apps/extension/src/lib/api.ts                              [extension + api]
-  apps/extension/src/hooks/use-entitlement.ts               [extension + billing]
-```
-
-Do not create `anhedral.json` manually. Its schema-v5 hashes, modes, ownership classes, template and UI-provider provenance, module resolution, generator version, and toolchain channel form a trust boundary for `add` and `doctor`. Invented records are worse than no manifest. Also omit `ANHEDRAL.md`, whose CLI-management claims would be false for a manual workspace.
-
-## 3. Create root configuration
-
-### Root package
-
-Create a private `package.json` with version `0.1.0`, the selected Node engine, the pnpm version being used, `turbo` as an exact dev dependency, and `workspaces` containing `apps/*` when any app exists and `packages/*` when API or database exists.
-
-Always add `build: turbo build` and `typecheck: turbo typecheck`. Set `dev` to
-the primary product loop: run the first selected client in canonical module
-order plus API when present, or API alone for a backend-only project. When the
-project has additional app surfaces, add `dev:all` to run every selected app in
-parallel. Each command uses `turbo dev --parallel` with explicit
-`--filter=./apps/<surface>` arguments. Add only selected scripts:
-
-```text
-web:       dev:web, verify:web = typecheck + build
-mobile:    dev:mobile, verify:mobile = typecheck + build:web
-api:       dev:api, verify:api = test:coverage + build
-desktop:   dev:desktop, desktop:build, verify:desktop = typecheck + build
-electron-updater: desktop:updates:cloudflare:login,
-                  desktop:updates:bucket:create, desktop:updates:first-provision,
-                  desktop:updates:worker:{check,dev,deploy,types},
-                  desktop:updates:build:{mac,win,linux},
-                  desktop:updates:publish, verify:desktop-updates
-extension: dev:extension, extension:zip, verify:extension = typecheck + zip
-db:        db:generate, db:migrate, db:check, db:studio, verify:db
-storage:   r2:login, r2:bucket:create, r2:cors:list, r2:cors:set,
-           assets:proxy:check, assets:proxy:dev, assets:proxy:deploy,
-           verify:assets-proxy
-```
-
-Set root `verify` to every selected `verify:<module>` joined with `&&`; include `verify:db`. If no app exists, begin it with `pnpm typecheck`.
-
-### pnpm workspace
-
-Create `pnpm-workspace.yaml` with the same workspace globs as the root package. Set `autoInstallPeers: false`, then add:
-
-```yaml
-onlyBuiltDependencies:
-  - electron
-  - esbuild
-  - sharp
-ignoredBuiltDependencies:
-  - browser-tabs-lock
-  - bufferutil
-  - core-js
-  - electron-winstaller
-  - spawn-sync
-  - utf-8-validate
-peerDependencyRules:
-  ignoreMissing:
-    - '@solana/web3.js'
-    - bs58
-    - react-native
-  allowedVersions:
-    esbuild: '>=0.25.0'
-    utf-8-validate: '>=5.0.2'
-```
-
-Pin current security overrides for `@vitejs/plugin-react`, `postcss`, vulnerable `esbuild` ranges, `shell-quote`, `tmp`, and `uuid`. Inside the Anhedral repository, copy exact override keys and values from `SECURITY_OVERRIDES` in `src/dependencies.ts`.
-
-### Turbo, ignore files, Vercel, and CI
-
-Create `turbo.json` using `https://turborepo.dev/schema.json` with:
-
-- `build.dependsOn = ["^build"]` and outputs `.next/**`, `!.next/cache/**`, `.output/**`, `dist/**`.
-- `typecheck.dependsOn = ["^build"]`.
-- `dev.cache = false` and `dev.persistent = true`.
-
-Ignore `node_modules`, framework/build caches, coverage, release output, every `.env` variant except `.env.example`, and `*.tsbuildinfo`. Put extension output, mobile web export, desktop release output, `apps/assets-private-proxy`, and `apps/desktop-updater-worker` in `.vercelignore`.
-
-Create the single root `vercel.json` using `https://openapi.vercel.sh/vercel.json`. Add service `api` rooted at `apps/api` and service `web` rooted at `apps/web` as selected. Put the `/api/(.*)` rewrite before the web `/(.*)` catch-all. If billing is selected, add `*/5 * * * *` for `/api/internal/realtime/flush`; if storage is selected, add `0 3 * * *` for `/api/internal/storage/cleanup`. Protect both internal routes with the same high-entropy `CRON_SECRET` bearer token.
-
-Create `.github/workflows/anhedral-ci.yml` with read-only contents permission, concurrency cancellation, pinned action commit SHAs, pnpm setup, Node `22.13.0` for mobile or `20.19.0` otherwise, and frozen installation. Run `pnpm typecheck`, API coverage tests when API exists, and `pnpm build`. For database workspaces also run `pnpm verify:db`, run `pnpm db:generate`, fail on any migration diff, and fail on untracked migration artifacts.
-
-Create `README.md` containing selected modules and first-run commands. Create `PRODUCTION.md` containing provider and deployment requirements from sections 8 and 9. These two files become user-owned; do not rewrite them during later manual module additions.
-
-## 4. Create shared packages
-
-Use strict TypeScript with `moduleResolution: Bundler`, `noEmit`, `skipLibCheck`, and `noUncheckedIndexedAccess`. Export source TypeScript directly inside the workspace.
-
-### Contracts
-
-Create `@shared/contracts` whenever API is selected. Depend on Zod. Define and export schemas plus inferred types for health and readiness; authenticated user when auth is selected; revisioned entitlement, realtime token request, and `subscription.changed` invalidation when billing is selected; and strict create-upload, confirm-upload, upload-record, and route-param data when storage is selected.
-
-Keep the upload content-type allowlist and maximum upload size in contracts so API and clients share one source of truth. Validate API response bodies in the client package before returning them.
-
-### API client
-
-Create `@shared/api-client` when API and at least one client surface are selected. Depend on contracts and Zod. Implement:
-
-- strict absolute `http:`/`https:` base-URL normalization with no credentials, query, or fragment;
-- an `ApiError` carrying HTTP status, stable code, details, and cause;
-- optional async token retrieval;
-- timeout and caller-abort composition with listener/timer cleanup;
-- JSON parsing and Zod response validation;
-- typed methods for health/readiness and only selected auth, billing, and storage routes.
-
-Do not make server-only provider SDKs dependencies of clients.
-
-### Realtime client
-
-Create `@shared/realtime` only when billing and at least one client are selected. Depend on Ably and contracts. Accept an async API-token callback, connect with `authCallback`, subscribe only to `private:users/<userId>/subscriptions`, validate every `subscription.changed` payload, expose connection errors, and return an idempotent cleanup function that unsubscribes and closes the client. Never put `ABLY_API_KEY` or a broad Ably capability in a client package.
-
-### Database
-
-Create `@shared/db` when `db` is selected. Use Neon serverless, Drizzle ORM, dotenv, Drizzle Kit, and tsx. Provide `db:generate`, `db:migrate`, `db:check`, and `db:studio`. Configure PostgreSQL with `src/schema.ts` and `migrations/`.
-
-Always define an `items` table. For billing, add `subscriptions` with a monotonic integer `revision`, idempotent `webhookEvents`, and `realtimeOutbox` with user, topic, revision, attempt/error, delivery, and creation fields. Add `uploads` for storage, including user ownership, staging/final keys, declared and actual metadata, status/rejection fields, expiry, cleanup, confirmation, and creation timestamps. Export the Drizzle client and schema, and fail immediately when `DATABASE_URL` is absent.
-
-Create `scripts/verify-db-migrations.mjs`. It must recursively find committed SQL files, fail when none exist, fail when SQL is untracked inside a Git worktree, and require a Git worktree in CI.
-
-## 5. Create the API
-
-Create a Fastify TypeScript package with `dev`, `build`, `typecheck`, `test`, and `test:coverage`. Use Fastify, CORS, compression, Helmet, rate limiting, Zod, and only provider/database dependencies selected by the module plan.
-
-Implement these layers:
-
-- `env.ts`: validate selected values, exact CORS origins, port, proxy hops, demo mode, production key prefixes, URL forms, secret strength, and provider identifier formats. Never silently fall back to demo behavior in production.
-- `application.ts`: construct the app, set proxy trust, register security plugins, expose shutdown state, centralize safe error serialization, and register routes under `/api`.
-- `routes.ts`: register health/readiness unconditionally and provider routes conditionally.
-- `index.ts`: listen on `0.0.0.0`, handle `SIGINT`/`SIGTERM` once, begin draining, close gracefully, and enforce a shutdown deadline.
-
-Always provide `GET /api/health` and `GET /api/ready`. Readiness returns 503 for dependency failure or shutdown. Do not leak internal errors, stack traces, credentials, or arbitrary details in 5xx responses. Allow safe details only for intentional 4xx errors.
-
-When auth is selected, verify Clerk requests server-side and expose protected `/api/me`. When billing is selected, implement a RevenueCat webhook with constant-time secret comparison, shape validation, durable idempotency, claim/retry handling, monotonic event timestamps, and server-side subscriber reconciliation. In the same database transaction as every accepted subscription mutation, increment its revision and insert an outbox record. Expose authenticated `GET /api/subscriptions/me`, `POST /api/subscriptions/refresh`, and `POST /api/realtime/token`; issue a short-lived Ably token request limited to the authenticated Clerk user's subscribe-only channel. Publish only `{ type, revision }`, mark delivery after publish, retain failures for retry, and expose `GET /api/internal/realtime/flush` behind `CRON_SECRET`. When storage is selected, issue short-lived R2 presigned PUTs bound to content type and length, persist pending uploads, verify object metadata before confirmation, isolate every key below `R2_PREFIX`, expose an owner-authorized read-URL endpoint with a bounded presigned-GET TTL, and provide an authenticated cleanup endpoint for the scheduled cron.
-
-Test health, readiness, shutdown state, safe errors, and exact CORS behavior. Test environment validation. Add replay/out-of-order/retry tests for billing and size/type/ownership/cleanup tests for storage.
-
-## 6. Create client surfaces
-
-Every client with API access must use `@shared/api-client`; do not duplicate fetch/error logic. Every authenticated client supplies its Clerk session token to that client. Require HTTPS for configured production API URLs. Billing clients load the authoritative entitlement first, subscribe through `@shared/realtime`, ignore invalidation revisions they already hold, and refetch rather than trusting event payloads. They must also refetch after visibility/foreground recovery so missed or delayed events cannot leave stale access.
-
-### Web
-
-Create a Next.js App Router app with Tailwind and shadcn-style `Button` and `Card` primitives. Use strict TypeScript, the `@/*` alias, a development rewrite from `/api/:path*` to `http://localhost:8787/api/:path*`, and same-origin `/api` in production. Wrap the layout in Clerk only for auth. Add account controls for auth and typed API status UI for API. For billing, render a subscription-status component backed by a realtime entitlement hook and refetch on document visibility.
-
-### Mobile
-
-Create an Expo Router app with static web export, a normalized URL scheme, strict TypeScript, and EAS production profiles. Add Clerk plus secure token caching only for auth. Add the typed API hook only for API. For billing, subscribe to realtime invalidations and refetch when `AppState` returns active. For native subscriptions, configure RevenueCat independently for iOS and Android public SDK keys, synchronize the RevenueCat app-user ID after Clerk loads, log RevenueCat out when Clerk signs out, expose retryable synchronization errors, register one global customer-info update listener, and present the configured entitlement paywall. After purchase/restore success or a RevenueCat customer-info callback, call the authenticated refresh endpoint so every other surface updates without waiting for webhook delivery.
-
-### Desktop
-
-Create Electron main/preload and a Vite React renderer. Keep `contextIsolation: true`, `nodeIntegration: false`, sandboxing enabled, and navigation/window-open restricted to trusted targets. Use a preload bridge rather than exposing Node. Add Tailwind/shadcn-style UI. Add typed API and Clerk browser auth only when selected. For billing, expose the current Clerk user ID to a realtime entitlement hook and refetch when the renderer becomes visible. Provide development orchestration plus current-host and platform-specific electron-builder scripts.
-
-### Extension
-
-Create a WXT React side-panel extension with Tailwind/shadcn-style UI. Generate permissions from selected features and host permissions only from validated API/Clerk origins. Require HTTPS in production. Add Clerk's extension provider/context only for auth and typed API only for API. For billing, consume the authenticated user ID/API client from that context, subscribe to invalidations, and refetch when the side panel becomes visible. Include `storage` and `cookies` permissions only when Clerk needs them. Provide `dev`, `build`, `zip`, `postinstall`, and `typecheck`.
-
-## 7. Wire optional features
-
-After selected surfaces exist, perform a cross-surface pass:
-
-- `auth`: Clerk server verification; protected API route; provider/account UI in every selected client; token-aware API hooks; client publishable keys and server secret separated.
-- `billing`: revisioned database state and transactional outbox; RevenueCat webhook/direct refresh; entitlement, scoped-token, and retry routes; Ably publisher and shared subscriber; contracts/API-client methods; live hooks in every client. Never expose RevenueCat or Ably secret keys.
-- `storage`: upload tables; R2 presign/confirm/cleanup; owner-authorized presigned GET URLs; contracts and client methods; Vercel cron; generated R2 CORS/lifecycle guidance; and `apps/assets-private-proxy` with Worker name `assets-private-proxy`, private bucket binding `ASSETS`, `workers.dev` disabled, a user-owned custom-domain config, confirmed-prefix-only streaming GET/HEAD delivery, ranges, conditionals, cache, method/host validation, and no bucket listing.
-- `native-subscriptions`: mobile RevenueCat SDKs, platform keys, Clerk identity synchronization, entitlement/paywall behavior, and error recovery.
-
-Search the finished workspace for imports of unselected providers. Remove both source branches and dependencies when a feature is absent.
-
-## 8. Configure environments and providers
-
-The root `.env.example` is an inventory, not a runtime file. Create package-local examples and copy them to ignored runtime files:
-
-```text
-apps/api/.env.example       -> apps/api/.env
-packages/db/.env.example    -> packages/db/.env
-apps/web/.env.example       -> apps/web/.env.local
-apps/mobile/.env.example    -> apps/mobile/.env
-apps/desktop/.env.example   -> apps/desktop/.env
-apps/extension/.env.example -> apps/extension/.env
-```
-
-Include only selected values:
-
-```text
-API:       NODE_ENV, PORT, TRUST_PROXY_HOPS, CORS_ORIGINS, ANHEDRAL_DEMO
-db:        DATABASE_URL
-auth:      CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY
-web:       NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, NEXT_PUBLIC_API_URL
-mobile:    EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY, EXPO_PUBLIC_API_URL
-desktop:   VITE_CLERK_PUBLISHABLE_KEY, VITE_API_URL
-extension: VITE_CLERK_PUBLISHABLE_KEY, VITE_CLERK_FRONTEND_API_URL,
-           VITE_CLERK_SYNC_HOST, VITE_API_URL, optional VITE_CRX_PUBLIC_KEY
-billing:   RC_WEBHOOK_SECRET, RC_SECRET_API_KEY, RC_ENTITLEMENT_ID,
-           ABLY_API_KEY, CRON_SECRET
-native:    EXPO_PUBLIC_RC_API_KEY_IOS, EXPO_PUBLIC_RC_API_KEY_ANDROID,
-           EXPO_PUBLIC_RC_ENTITLEMENT_ID
-storage:   BASE_URL, R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY,
-           R2_BUCKET_NAME, R2_PREFIX=storage,
-           R2_PROXY_READ_URL_TTL_SECONDS=600, CLOUDFLARE_API_TOKEN (ops/CI only),
-           CRON_SECRET
-```
-
-Use explicit local CORS origins for selected browser clients. Include `null` only for Electron's file origin. Production uses exact HTTPS origins. Keep `ANHEDRAL_DEMO=false`, server secrets server-only, and real environment files out of Git.
-
-For R2, generate a user-owned `cloudflare/r2-cors.template.json`, list the live policy before replacing it, and retain every exact upload origin. Add a lifecycle rule for `storage/staging/` whose age exceeds the application cleanup grace period. Keep `r2.dev` and R2 bucket custom domains disabled. Use the generated Worker Custom Domain at `assets.<domain>` for public-by-key `storage/confirmed/` objects only. Use the authenticated upload-owner read-URL route for private delivery; it returns a short-lived presigned GET governed by `R2_PROXY_READ_URL_TTL_SECONDS`.
-
-## 9. Install, migrate, and verify
-
-Run from the root:
-
-```sh
-pnpm install
-pnpm typecheck
-```
-
-For a database workspace, copy its environment, generate and review the initial migration, and add it to Git before the gate:
-
-```sh
-pnpm db:generate
-git add packages/db/migrations
-pnpm verify:db
-pnpm db:migrate
-```
-
-Then run every selected package verification, root verification, and build:
-
-```sh
-pnpm verify
-pnpm build
-```
-
-Run API coverage when API exists, Expo compatibility checks when mobile exists, a packaged Electron smoke test when desktop exists, and load unpacked WXT output when extension exists. Exercise one authenticated API call per selected client. For billing, replay a webhook, send an older event, verify an outbox record is committed atomically, verify the scoped token cannot publish or subscribe to another user, and observe one native purchase/refresh update web, Android, extension, and desktop sessions. Disconnect one client, mutate the entitlement, reconnect/foreground it, and confirm authoritative recovery. For storage, perform browser preflight, presigned upload, confirmation, cross-user private-read rejection, read-URL TTL verification, cleanup, Worker syntax/Wrangler dry-run validation, GET/HEAD/range/conditional/cache behavior, forbidden methods, unexpected hosts, missing keys, staging/private-prefix rejection, and direct-bucket inaccessibility.
-
-Do not weaken types, tests, provider validation, security headers, or migration checks to make verification green. Report the failing package and command, fix the owning layer, and rerun the narrow check before root verification.
-
-## 10. Audit completeness
-
-Answer yes to every applicable item:
-
-- Were prerequisites resolved before creation?
-- Is there exactly one pnpm workspace and lockfile?
-- Do root scripts reference only selected modules?
-- Does every selected conditional file exist and every unselected one stay absent?
-- Are contracts shared by API and clients?
-- Are provider dependencies and environment keys gated by selection?
-- Are secrets absent from clients and committed files?
-- Are optional flows wired end to end rather than represented by placeholders?
-- For billing, are revisions monotonic, outbox writes atomic, Ably capabilities user-scoped, and all clients recovery-safe?
-- Is a reviewed, committed migration present for `db`?
-- Do CI, Vercel services/rewrites, cron, CORS, and local ports agree?
-- For storage, is the bucket private, is the hostname attached to the Worker rather than R2, and does the documented public-key or authenticated download policy match the code?
-- Did `pnpm verify` and `pnpm build` pass?
-- Is `anhedral.json` absent unless produced by the matching CLI?
-
-## 11. Work from the Anhedral source repository
-
-Inside the Anhedral repository, treat current source as higher authority than copied versions or prose. Read before exact reconstruction:
-
-```text
-src/architecture/modules.ts   dependency closure and canonical module IDs
-src/dependencies.ts           exact versions, engines, and overrides
-src/scaffold.ts               root config, CI, docs, env inventory, manifest boundary
-src/templates/shared.ts       contracts, API client, and database
-src/templates/api.ts          Fastify source, providers, and tests
-src/templates/web.ts          Next.js source and conditional wiring
-src/templates/mobile.ts       Expo source and RevenueCat integration
-src/templates/desktop.ts      Electron/Vite source and security settings
-src/templates/extension.ts    WXT source, permissions, auth, and side panel
-docs/output-tree-contract.md   expected paths for representative plans
-```
-
-Render selected branches manually and replace project/display-name literals safely. Do not execute `dist/bin.js`, `bin/anhedral.js`, `scaffoldProject`, or template scaffold functions. Compare against the relevant output-tree contract, but never copy `demo/`: demos can contain installed artifacts or lag current templates. If source and this guide disagree, follow source and update this guide in the same change.

package/docs/references/provisioning.md

@@ -1,220 +0,0 @@
-# Agent-run Anhedral provisioning
-
-Use this checklist after the user asks a coding agent to create or provision an
-Anhedral project. Keep one lead agent responsible for the plan, names, secrets,
-and final verification.
-
-## 1. Start with user inputs
-
-Before running `anhedral new` or opening a provider dashboard, ask the user:
-
-1. What is the project name? Derive one stable lowercase kebab-case resource
-   stem from it and show the proposed value.
-2. Do they already own a custom domain for this product? If yes, record the
-   exact domain, registrar, current DNS provider, and whether production email
-   already uses it. If no, ask for the desired domain and obtain explicit
-   approval before any paid purchase.
-3. Which surfaces and features do they want? If they want the complete product,
-   use every module. Otherwise record explicit modules.
-4. Which provider organizations/teams should own Cloudflare, Vercel, GitHub,
-   Neon, Clerk, RevenueCat, Ably, Expo, Apple, Google Play, and Chrome Web Store
-   resources that apply to the selected modules?
-5. Is this development, preview, or production? Never point a preview at live
-   users, billing, or production data without explicit direction.
-
-Do not improvise names independently in provider dashboards. Maintain a small
-resource ledger containing the project stem, display name, domain, selected
-modules, provider team, resource name, hostname, environment, status, and next
-user action. Never put credential values in the ledger.
-
-## 2. Discover agent capabilities
-
-Inspect the environment before planning execution:
-
-- If Computer Use or an authenticated browser-control tool is available, use it
-  for provider dashboards after the user requests provisioning.
-- If subagents are available, keep the lead agent in control and delegate only
-  bounded, independent work. Good tasks are reading generated documentation,
-  checking current DNS records without changing them, and producing a
-  selection-specific environment-variable inventory.
-- Do not give subagents passwords, session cookies, secret values, or concurrent
-  control of the same browser/profile. Do not let two agents mutate DNS or the
-  same provider resource.
-- If neither capability exists, use generated CLI commands and give the user
-  exact dashboard instructions for the remaining steps.
-
-Recommended subagent sequence:
-
-1. Lead: collect inputs, resolve modules, choose canonical names, and run init.
-2. Documentation subagent: read the generated `README.md`, `PRODUCTION.md`, and
-   package-local `.env.example` files; return the provider/resource checklist.
-3. DNS subagent: perform read-only registrar, nameserver, DNS, and hostname
-   collision checks; return existing records that must be preserved.
-4. Verification subagent: after provisioning, run read-only domain, health,
-   Worker, and configuration checks. The lead performs or approves mutations.
-
-If subagents are unavailable, perform the same phases serially. Their absence is
-not a blocker.
-
-## 3. Generate the project
-
-Prefer the skill-guided CLI path:
-
-```sh
-pnpm dlx anhedral@latest new <project-name> <explicit-modules...> --toolchain stable
-cd <project-name>
-```
-
-Omit module arguments only when the user chose the complete stack. Examples:
-
-```sh
-pnpm dlx anhedral@latest new acme --web --api --db --auth --toolchain stable
-pnpm dlx anhedral@latest new acme desktop electron-updater --toolchain stable
-```
-
-Then:
-
-1. Read the generated `README.md` and `PRODUCTION.md` completely.
-2. Read `anhedral.json` and confirm the resolved module closure with the user.
-3. Copy only package-local environment examples that exist.
-4. Run `pnpm dlx anhedral@latest doctor`, `pnpm verify`, and `pnpm build` before
-   provisioning. Fix code-generation or build failures before creating cloud
-   resources.
-
-## 4. Authentication and secret boundaries
-
-Computer Use may navigate dashboards, fill non-secret settings, create approved
-resources, deploy, configure DNS, and verify results. Apply these hard stops:
-
-- Stop at every sign-in, password, passkey, MFA, CAPTCHA, device-approval, or
-  provider-consent boundary. Tell the user which provider is requesting access
-  and wait for them to complete it. Resume only after they say it is complete.
-- Stop immediately before a paid purchase, registrar transfer, destructive
-  replacement, production release, store submission, or other consequential
-  final confirmation. Show the exact action, target, and cost/impact and obtain
-  approval.
-- Stop at the final **Create**, **Generate**, **Reveal**, or **Rotate secret**
-  action. Tell the user the exact button to click, exact variable name, and exact
-  local uncommitted environment file to receive the value. The user must paste
-  it directly into that file or the provider's secret field, never into chat.
-- Never read a populated `.env` file back into tool output, screenshots, logs,
-  the resource ledger, or a subagent message. Validate names and presence with a
-  redacting parser or the generated application checks.
-- Public identifiers such as publishable keys, project IDs, account IDs, bucket
-  names, and hostnames may be recorded where their generated examples expect
-  them. Treat any provider value marked secret as secret even if it appears in a
-  browser page.
-
-When the user finishes a secret step, ask only for confirmation such as
-"`CLERK_SECRET_KEY` is saved in `apps/api/.env`". Do not ask them to repeat the
-value. Mirror production secrets into Vercel or another deployment provider by
-having the user paste into that provider's protected environment-variable UI,
-or by using an approved secret-input flow that never prints the value.
-
-## 5. Domain foundation
-
-Use Cloudflare as authoritative DNS and Vercel as the web/API runtime. A domain
-can remain registered at GoDaddy; changing nameservers is not a registrar
-transfer.
-
-1. If the user has no domain, use Computer Use to search the approved registrar
-   (usually GoDaddy), select the exact domain, and fill registration settings.
-   Stop before the paid purchase confirmation. Ask the user to review price,
-   renewal terms, registrant, and organization ownership and submit it.
-2. Inventory existing DNS before changing nameservers. Preserve MX, TXT, SPF,
-   DKIM, DMARC, verification, CAA, and application records. A domain with active
-   email requires an explicit preservation review.
-3. Add the domain as a Cloudflare zone. Stop for Cloudflare authentication. Copy
-   the two assigned authoritative nameservers.
-4. At the registrar, replace the authoritative nameservers with Cloudflare's
-   exact values. Disable conflicting registrar DNSSEC/DS records first when
-   required; wait until Cloudflare reports the zone **Active**, then enable
-   DNSSEC in Cloudflare and publish the requested DS record at the registrar.
-5. Do not transfer registration unless the user separately requests it. A
-   transfer changes billing/registrar ownership and may be subject to locks.
-
-Use distinct hostnames:
-
-```text
-app.example.com      Vercel web/API custom domain
-assets.example.com   assets-private-proxy Worker Custom Domain
-updates.example.com  desktop-updater Worker Custom Domain
-```
-
-`app.example.com` is a Vercel project domain whose A/CNAME/TXT records are
-managed in Cloudflare DNS. Add the domain to Vercel first, inspect the exact
-records Vercel requests, then add those records in Cloudflare. Keep the Vercel
-origin record DNS-only unless current Vercel guidance and the user's architecture
-explicitly require another topology.
-
-Worker hostnames are Cloudflare **Worker Custom Domains**, not CNAMEs to Vercel
-or R2. Configure `custom_domain: true` in the generated Wrangler file and deploy;
-Cloudflare creates the DNS record and certificate. Remove any conflicting A,
-AAAA, or CNAME record before attaching the Worker hostname.
-
-## 6. Provision selected providers
-
-Follow the generated `PRODUCTION.md`; it is the selection-specific authority.
-Use this dependency order so downstream configuration receives real URLs and
-public identifiers:
-
-1. **GitHub**: create or select the organization repository, review the initial
-   diff, and push. Stop before changing repository visibility or overwriting an
-   existing remote.
-2. **Neon (`db`)**: create separate development/preview/production projects or
-   branches. At connection-string generation, stop and have the user save the
-   pooled URL as `DATABASE_URL` in `packages/db/.env`, `apps/api/.env` when
-   required, and the protected Vercel API environment.
-3. **Clerk (`auth`)**: create development and production instances and configure
-   allowed origins, redirect URLs, and native/extension identifiers. Stop at key
-   generation/reveal. Put the secret key only in server environments and the
-   publishable key in each selected client's documented public variable.
-4. **RevenueCat and Ably (`billing`)**: create projects/apps, entitlement,
-   products, webhook URL/secret, and Ably API key. Stop at every secret creation.
-   Keep RevenueCat secret and Ably API keys server-only; clients receive only
-   documented public SDK keys or scoped Ably tokens.
-5. **Cloudflare R2 (`storage`)**: run the generated login, bucket, CORS, Worker
-   check, and Worker deploy commands. Keep R2 private and `r2.dev` disabled.
-   Stop when Cloudflare requests authentication or before creating S3/API token
-   secrets; have the user save them under the exact `R2_*` names. Attach
-   `assets.<domain>` as the generated Worker Custom Domain.
-6. **Vercel (`web`/`api`)**: link/import the root repository, select the generated
-   Services configuration, populate Development/Preview/Production variables,
-   deploy, then add `app.<domain>`. Inspect Vercel's exact DNS requirements and
-   create them in Cloudflare DNS. Verify domain status and TLS after propagation.
-7. **Electron updater (`electron-updater`)**: edit both generated
-   `updates.example.com` values, set the matching HTTPS origin in
-   `apps/desktop/electron-builder.env`, run
-   `pnpm desktop:updates:first-provision` exactly once, and verify the private R2 binding plus
-   Worker Custom Domain. Build/sign on each native OS and upload artifacts
-   before channel metadata with the generated publish command.
-8. **Expo/EAS and stores (`mobile`)**: create/link the EAS project, configure
-   public build variables and signing credentials, and build internal releases.
-   Stop at Apple/Google sign-in, credential, paid membership, agreement, and
-   store-submission boundaries.
-9. **Chrome Web Store (`extension`)**: configure a stable extension ID, test the
-   generated ZIP as trusted/unlisted, and complete listing/privacy fields. Stop
-   before developer registration payment and final store submission.
-
-Create strong `CRON_SECRET` and webhook secrets through a password manager or a
-local non-logging generator. The user places them directly into server and
-deployment environments.
-
-## 7. Verify and hand off
-
-After configuration:
-
-1. Run `pnpm verify`, `pnpm build`, and `anhedral doctor`.
-2. Verify Vercel deployment health, custom-domain status, DNS answers, and TLS.
-3. Verify every selected Worker accepts its intended GET/HEAD behavior, rejects
-   forbidden methods/hosts, and cannot expose or list the private bucket.
-4. Verify database migration status, auth redirect/sign-out, billing webhook and
-   entitlement refresh, storage upload/read policy, and scheduled jobs as
-   selected.
-5. Record resource names, URLs, provider teams, and remaining manual approvals.
-   Record no secrets.
-6. Stop before production/store release and give the user a concise checklist of
-   the exact final buttons or approvals still required.
-
-Do not claim completion while a dashboard is merely open, DNS is still pending,
-TLS is unissued, an environment value is absent, or verification has not run.