anhedral 0.4.2 → 0.6.1

package/docs/NORTHSTAR.md

@@ -1,114 +0,0 @@
-# Anhedral DX north star
-
-## One command in. A working product foundation out.
-
-Anhedral should let a developer choose the surfaces and capabilities their idea
-needs, generate one understandable TypeScript workspace, and reach a working
-feature without first becoming an expert in every framework and provider.
-
-The generated application must feel like a project the developer wrote
-themselves:
-
-- ordinary framework source, package scripts, environment files, and tests;
-- one shared contract and API client across every selected surface;
-- working vertical slices instead of disconnected demonstrations;
-- safe, inspectable structural changes with no hidden runtime or control plane;
-- a clear path from first run to production without changing architecture; and
-- built-in scale through managed, autoscaling providers rather than custom
-  infrastructure.
-
-Anhedral succeeds when developers spend their time on the product idea, not on
-repeating setup, reconciling integrations, or reverse-engineering generated
-code.
-
-## Product principles
-
-### Fast to first value
-
-A developer should understand the choices before generation, see the resolved
-dependency closure, and know the next command when generation finishes.
-`pnpm first-run` prepares local configuration without overwriting it.
-`pnpm ready` answers whether required configuration is complete without
-revealing values. `pnpm verify` proves the source and selected integrations
-build.
-
-### Build once, ship everywhere
-
-Contracts, validation, API calls, authentication, persistence, and product
-behavior should be shared where the platforms permit it. Every selected client
-should receive an idiomatic UI for the same starter feature so the developer can
-prove the whole path on web, iOS, Android, desktop, and browser extension
-surfaces before replacing it with their idea.
-
-### Explicit composition
-
-The CLI must distinguish what the developer requested from what dependencies
-added. Interactive and automated use must produce the same canonical module
-closure. Complete-stack generation is explicit with `--all`; focused stacks
-remain first-class.
-
-### Safe evolution
-
-`add`, `ui add`, and `upgrade` must be transactional, previewable, deterministic,
-and ownership-aware. They may merge known configuration and replace unmodified
-managed substrate, but must never silently overwrite product code. `doctor`
-must explain drift and give a concrete recovery action.
-
-### Production-shaped from the start
-
-Development and production use the same package boundaries and provider
-integrations. Environment examples may contain placeholders, but generated
-applications must identify them before launch. Secrets stay server-side and
-uncommitted. Deployment guidance is specific to the selected stack and does not
-claim resources already exist.
-
-### Human and automation parity
-
-Human output should be concise and actionable. `--json` should provide one clean,
-stable document with the same resolved modules, plans, outcomes, and next steps
-for CI and coding agents. Noninteractive commands must never depend on a prompt.
-
-### Source ownership is the feature
-
-Generated product seams are user-owned and readable. Provider substrate is
-managed only where consistency and security require it. The manifest records
-the boundary, and every lifecycle command honors it.
-
-## Journey contract
-
-| Journey | The developer should experience | Acceptance signal |
-| --- | --- | --- |
-| Discover | Immediately understand cross-platform scope, modularity, cost posture, and ownership | README states the value plainly and links to exact commands |
-| Choose | See app surfaces, capabilities, dependencies, and runtime requirements before writes | Interactive confirmation and `--help` show the canonical resolved stack |
-| Create | Receive deterministic source, optional Git initialization, visible installation progress, and exact next steps | `new`, `init`, dry-run, JSON, skip-install, and Git variants are tested |
-| Configure | Safely create only missing local environment files and identify every unresolved placeholder without printing secrets | `pnpm first-run` is idempotent; `pnpm ready` returns a truthful exit status |
-| Prove | Exercise a real contract → database → API → client → UI feature on every selected surface | Focused and complete generated stacks typecheck, test, and build |
-| Develop | Know where product code belongs and use each framework normally | Generated README, development guide, stack map, and coding-agent skill agree |
-| Extend | Preview and add modules or source-owned UI without losing edits | Dry-run and apply plans are deterministic, transactional, and ownership-safe |
-| Diagnose | Understand generator drift, configuration readiness, and recovery actions | `pnpm ready` reports configuration blockers; `doctor` reports structural issues and actionable recommendations |
-| Upgrade | Move supported projects forward without replacing product seams | Upgrade is transactional, no-op when current, and tested from supported versions |
-| Ship | Follow selection-specific steps from previews to production and stores | Generated production guide and exact package scripts cover every selected target |
-| Automate | Consume stable output and releases without scraping terminal prose | JSON remains parseable; successful `main` CI prepares the next patch release |
-
-## Definition of done
-
-A change is complete only when:
-
-1. focused and complete module topologies generate deterministically;
-2. generated environment setup is idempotent and readiness checks are truthful;
-3. the shared starter feature reaches every selected compatible client;
-4. generated code typechecks, tests, builds, and passes runtime acceptance where
-   the platform is available;
-5. dry-run, JSON, no-op, failure, rollback, and recovery paths are covered;
-6. source ownership survives `add`, `ui add`, and `upgrade`;
-7. packed npm output behaves the same as repository source;
-8. security, dependency, secret, PII, source-hygiene, and release-policy checks
-   pass; and
-9. documentation describes the behavior that was actually verified.
-
-## Deliberate boundaries
-
-Anhedral does not hide provider accounts, fabricate credentials, submit paid or
-review-gated releases, run a proprietary application runtime, or own product
-code after generation. Those boundaries keep the output understandable,
-portable, and under the developer's control.

package/docs/conventions.md

@@ -1,94 +0,0 @@
-# Anhedral generated-project conventions
-
-Anhedral is a deterministic stack generator. These conventions describe the readable workspace it produces; they are not a new application framework or runtime API.
-
-## Core rule
-
-Use the underlying tool's normal programming model. Anhedral decides where integrations meet and generates safe defaults, but developers write ordinary Next.js, Expo Router, Fastify, Drizzle, Electron, and WXT code.
-
-## Source ownership
-
-```text
-apps/       deployable framework applications
-packages/   client-safe or server-shared TypeScript packages
-docs/       generated stack and development guidance
-```
-
-- `apps/web`: Next.js App Router pages, layouts, components, hooks, and web utilities.
-- `apps/mobile`: Expo Router screens, layouts, native components, and hooks.
-- `apps/api`: Fastify routes, services, plugins, provider clients, and server environment validation.
-- `apps/desktop`: Electron main/preload code and sandboxed React renderer code.
-- `apps/desktop-updater-worker`: optional read-only Cloudflare Worker serving signed Electron updates from a bound private R2 bucket.
-- `apps/extension`: WXT entrypoints, extension components, background logic, and content scripts.
-- `packages/contracts`: Zod schemas for data crossing HTTP boundaries.
-- `packages/api-client`: client-safe HTTP behavior shared across frontends.
-- `packages/db`: Drizzle schema, database access, and reviewed SQL migrations.
-- `packages/realtime`: client-safe Ably subscription behavior when selected.
-
-## End-to-end feature flow
-
-```text
-Zod contract
-    -> Drizzle schema/query or server service
-    -> Fastify route
-    -> shared API client
-    -> Next.js / Expo / Electron / WXT UI
-```
-
-Routes stay thin. They authenticate, validate, call a service, and return a declared contract. Business behavior and provider SDK calls live in server services. Frontends never import API services, database connections, or server environment modules.
-
-When `electron-updater` is selected, desktop releases follow a separate delivery path: the packaged Electron main process reads generated update metadata from an HTTPS custom domain, the Worker streams known keys from its private R2 binding, and release tooling uploads signed artifacts before mutable channel metadata. Neither Cloudflare credentials nor a public bucket URL enter the desktop application.
-
-## Database
-
-Database-enabled projects use managed Neon Postgres. Anhedral does not generate local Postgres, Docker Compose, or an embedded database substitute.
-
-1. Edit the user-owned `packages/db/src/app-schema.ts`; Anhedral keeps provider tables in `generated-schema.ts`.
-2. Run `pnpm db:generate`.
-3. Review and commit generated SQL and metadata.
-4. Run `pnpm verify:db`.
-5. Apply with `pnpm db:migrate` against the intended Neon branch or project.
-
-Schema generation must not happen during an application build. Migrations are reviewed release artifacts.
-
-## Authentication and secrets
-
-Clerk owns identity and sessions. The API derives identity from a verified server session and never trusts a client-supplied user ID. Only variables with a framework's explicit public prefix may enter client bundles. Database, Clerk secret, R2, RevenueCat, Ably, cron, and provider credentials remain server-only.
-
-## UI
-
-DOM clients use source-owned shadcn/ui components. Expo uses React Native Reusables with the selected NativeWind or Uniwind configuration.
-
-```sh
-pnpm anhedral:ui button dialog
-pnpm anhedral:ui data-table --target web
-```
-
-Generated UI files are application source and can be customized. Preserve accessibility, keyboard/focus behavior, and platform conventions.
-
-## Naming
-
-- Directories and source files use lowercase kebab-case.
-- React component filenames use kebab-case and export PascalCase components.
-- Hooks start with `use-`.
-- Framework-required entrypoint names stay unchanged.
-- Shared packages use the `@shared/<name>` namespace.
-
-## Structural changes
-
-Run `pnpm anhedral:doctor` before changing generated structure. Preview new modules or UI with `--dry-run`. Anhedral refuses managed-file drift, symlinks, and unowned collisions instead of overwriting source.
-
-Application product files are developer-owned. `README.md` and `PRODUCTION.md` become user-owned after initialization. Root configuration is mergeable. Integration substrate and generated guidance are recorded in `anhedral.json`.
-
-## Verification
-
-Run the smallest relevant package check while iterating, then the generated root verification before handoff:
-
-```sh
-pnpm first-run
-pnpm ready
-pnpm typecheck
-pnpm verify
-pnpm build
-pnpm anhedral:doctor
-```

package/docs/engineering-principles.md

@@ -1,88 +0,0 @@
-# The Zen of Anhedral
-
-Anhedral applies the spirit of Tim Peters' *Zen of Python* to a TypeScript stack
-generator. This is an engineering policy, not a preference for Python syntax.
-The goal is generated software whose behavior, ownership, and failure modes are
-easy to see.
-
-## Working rules
-
-1. **Make the result readable.** Generated source should look like ordinary,
-   idiomatic framework code. Prefer clear names and small seams over clever
-   abstractions or compressed templates.
-2. **Make choices explicit.** Keep requested modules distinct from dependencies
-   added by resolution. Record ownership, toolchain, template provenance, and
-   planned writes. Never infer permission to replace product code.
-3. **Keep one source of truth.** Module identity and kind belong to the
-   architecture registry. Project shape belongs to the project model. CLI,
-   templates, manifests, and docs consume those definitions instead of
-   restating them.
-4. **Choose the smallest complete design.** A simple vertical slice is better
-   than a generic subsystem. Real provider complexity may be necessary, but it
-   must stay behind a narrow, named boundary.
-5. **Prefer flat control flow.** Validate early, return early, and dispatch once.
-   Split orchestration, domain rules, rendering, filesystem transactions, and
-   process execution into distinct namespaces.
-6. **Generate sparsely.** A selected stack receives what it needs. Unselected
-   apps and providers must not leave dead packages, environment variables,
-   scripts, or documentation behind.
-7. **Treat rules uniformly.** Add module dependencies and conflicts to the
-   registry; do not scatter special-case resolution across commands. Introduce
-   an exception only when the practical behavior is clearer and it is covered
-   by a regression test.
-8. **Never hide failure.** Invalid input, drift, child-process failure, partial
-   configuration, and unsafe writes must produce a useful error and nonzero
-   status. An intentionally ignored failure must be named, local, and tested.
-9. **Do not guess through ambiguity.** Reject unknown commands, conflicting
-   edits, unowned collisions, unsafe paths, and unsupported project versions.
-   Interactive choices require confirmation; noninteractive behavior must be
-   deterministic.
-10. **Provide one obvious path.** Use `new` or `init` to create, `add` for
-    modules, `ui add` for source-owned UI, `upgrade` for schema evolution, and
-    `doctor` for drift. Generated projects use `first-run`, `ready`, `verify`,
-    and then `dev`.
-11. **Ship deliberate increments.** Finish a small explainable change now when
-    its behavior is proven. Defer a broad abstraction until it has a concrete
-    caller and an acceptance test.
-12. **Make explanation a design test.** If a change cannot be summarized as
-    input → decision → observable result, simplify it before merging.
-
-## Namespace boundaries
-
-```text
-CLI parsing and presentation
-    -> architecture and project model
-    -> scaffold orchestration and transactions
-    -> templates and configuration composers
-    -> generated framework source
-```
-
-- `src/architecture/` owns module resolution, plans, manifests, and composition
-  invariants.
-- `src/project.ts` owns the template-facing project shape.
-- `src/scaffold.ts` coordinates lifecycle operations; it must not become the
-  source of domain types or embed unrelated templates.
-- `src/templates/` renders selected framework and lifecycle files.
-- `src/transaction.ts` owns safe application and rollback.
-- `src/bin.ts`, `src/cli.ts`, and `src/prompts.ts` own user input and output.
-
-Dependencies point toward the model, not back toward the orchestrator. A
-template may depend on `ProjectOptions`; it should not depend on the scaffold
-command that called it.
-
-## Review questions
-
-Before merging, answer these plainly:
-
-- Where is the single authoritative definition for this behavior?
-- What input is explicit, what is derived, and is that distinction observable?
-- Does the happy path read top-to-bottom without hidden mutation?
-- What ambiguity or failure can occur, and how does the user see it?
-- Does the change add output for an unselected module?
-- Can an existing user-owned file be overwritten or silently reclassified?
-- Is there a focused test for the rule and a broader test for the journey?
-- Can the implementation be explained in a short paragraph?
-
-Practicality still wins: duplicated literal output inside generated framework
-code can be clearer than a generator-only abstraction. The burden is on an
-abstraction to remove real ambiguity or repetition without hiding behavior.

package/docs/master-stack-map.md

@@ -1,199 +0,0 @@
-# Anhedral master stack map
-
-This is the canonical whole-stack map for Anhedral. It shows the ordered flow
-from skill-led planning through deterministic generation, source layout,
-connected capabilities, cloud provisioning, command-driven operations, agent
-experience, and production verification.
-
-![Anhedral master stack diagram](../assets/anhedral-cli-init.svg)
-
-The diagram is generated from `scripts/render-master-stack-map.mjs`. Change the
-content or geometry there, then run `pnpm docs:stack-map`; do not hand-edit the
-SVG. The fixed-width map below remains the detailed text and accessibility
-reference.
-
-Read top to bottom. Arrows represent lifecycle order, not runtime network calls.
-Runtime and provider connections are stated explicitly inside each stage.
-
-```text
-+==========================================================================================================================+
-|                                                ANHEDRAL MASTER STACK MAP                                                 |
-+--------------------------------------------------------------------------------------------------------------------------+
-|OUTCOME One readable TypeScript codebase and one command surface connecting every application, cloud resource, release    |
-|path, runbook, and coding agent.                                                                                          |
-|PRINCIPLE Ordinary framework code, source ownership, and generated integration boundaries. Anhedral assembles the stack;  |
-|it is not the application runtime.                                                                                        |
-+==========================================================================================================================+
-                                                             |
-                                                             v
-+==========================================================================================================================+
-|                                                     1  SELECT + PLAN                                                     |
-+--------------------------------------------------------------------------------------------------------------------------+
-|SKILL FIRST Install and invoke $anhedral-init. Ask for project name and custom-domain status before generating or         |
-|provisioning.                                                                                                             |
-|CREATE anhedral new <directory> | anhedral init EXTEND anhedral add <modules> | anhedral ui add <components>              |
-|INSPECT anhedral doctor AUTOMATE --dry-run | --json | --verbose | --skip-install                                          |
-|SURFACES web | mobile | api | desktop | extension                                                                         |
-|FEATURES db | auth | billing | storage | native-subscriptions | electron-updater                                          |
-|UI shadcn/ui for DOM clients | React Native Reusables for Expo | NativeWind or Uniwind                                    |
-|CLOSURE auth -> api + db | billing -> auth | storage -> auth | native-subscriptions -> mobile + billing |                 |
-|electron-updater -> desktop                                                                                               |
-+==========================================================================================================================+
-                                                             |
-                                                             v
-+==========================================================================================================================+
-|                                                    2  GENERATE SAFELY                                                    |
-+--------------------------------------------------------------------------------------------------------------------------+
-|PIPELINE Resolve modules -> select immutable templates -> verify SHA-256 catalog -> stage files -> compose typed          |
-|contributions.                                                                                                            |
-|PIPELINE Run pinned UI providers only in staging -> record provenance and ownership -> atomic commit -> one root pnpm     |
-|install.                                                                                                                  |
-|REFUSES traversal | symlinks | nested repositories/workspaces | caches | oversized files | unowned collisions | managed   |
-|drift.                                                                                                                    |
-|OWNERSHIP Product source plus README/PRODUCTION are user-owned | root configuration is mergeable | integration substrate  |
-|is managed.                                                                                                               |
-|STATE anhedral.json records modules, versions, template/UI provenance, styling, file hashes, modes, and ownership.        |
-|WHY Deterministic, inspectable generation and safe incremental adds without replacing user work.                          |
-+==========================================================================================================================+
-                                                             |
-                                                             v
-+==========================================================================================================================+
-|                                       3  ONE PNPM + TURBOREPO TYPESCRIPT WORKSPACE                                       |
-+--------------------------------------------------------------------------------------------------------------------------+
-|apps/web Next.js App Router + React + shadcn/ui. WHY: SSR, routing, server-first web, and source-owned UI.                |
-|apps/mobile Expo Router + React Native Reusables. WHY: one native TypeScript product for iOS and Android.                 |
-|apps/api Fastify + validation/security plugins. WHY: thin routes, services, structured logs, and explicit boundaries.     |
-|apps/desktop Electron + Vite + sandboxed React renderer. WHY: cross-platform desktop with a narrow privileged bridge.     |
-|apps/extension WXT + React + MV3 entrypoints. WHY: browser permissions, side panel/background, builds, and packaging.     |
-|apps/assets-private-proxy Cloudflare Worker + private R2 binding. WHY: controlled GET/HEAD media delivery without bucket  |
-|listing.                                                                                                                  |
-|apps/desktop-updater-worker Cloudflare Worker + private R2 binding. WHY: custom-domain Electron metadata, ranges, and     |
-|downloads.                                                                                                                |
-|packages/contracts Zod schemas. WHY: one validated network contract shared across every boundary.                         |
-|packages/api-client Typed client-safe HTTP. WHY: one request path for web, mobile, desktop, and extension.                |
-|packages/db Drizzle schema + reviewed SQL migrations. WHY: readable TypeScript schema and explicit release artifacts.     |
-|packages/realtime Ably client. WHY: scoped invalidation events while clients refetch authoritative state.                 |
-+==========================================================================================================================+
-                                                             |
-                                                             v
-+==========================================================================================================================+
-|                                            4  CONNECTED PRODUCT CAPABILITIES                                             |
-+--------------------------------------------------------------------------------------------------------------------------+
-|REQUESTS Zod contract -> service/Drizzle query -> Fastify route -> typed API client -> every selected client.             |
-|IDENTITY Clerk sessions in clients -> verified server identity; never trust a client-supplied user ID.                    |
-|DATABASE Fastify -> Drizzle -> managed Neon Postgres with isolated dev/preview/production; no generated local Postgres.   |
-|STORAGE API presigns R2 PUT -> client uploads -> API confirms -> Worker streams confirmed assets or owner-authorized      |
-|reads.                                                                                                                    |
-|BILLING Expo purchase -> RevenueCat -> signed webhook -> Neon entitlement + transactional outbox.                         |
-|REALTIME Outbox -> scoped Ably event -> every client refetches the authoritative entitlement.                             |
-|DESKTOP UPDATE Signed native build -> artifacts then latest metadata -> private R2 -> updates.<domain> Worker ->          |
-|electron-updater.                                                                                                         |
-|SECURITY Server-only secrets | exact CORS | rate limits/headers | Electron isolation | least privilege | private buckets. |
-+==========================================================================================================================+
-                                                             |
-                                                             v
-+==========================================================================================================================+
-|                                            5  PROVISION + CONFIGURE THE CLOUD                                            |
-+--------------------------------------------------------------------------------------------------------------------------+
-|DOMAIN Buy/confirm domain -> add Cloudflare zone -> preserve mail records -> delegate nameservers -> activate DNSSEC.     |
-|GITHUB + CI Organization repository, protected environments, pinned Actions, PR checks, branches, and release artifacts.  |
-|NEON Projects/branches per environment, pooled DATABASE_URL, backups, reviewed migrations, and controlled deploy gates.   |
-|CLERK Development/production instances, publishable/secret keys, domains, OAuth, redirects, webhooks, native and CRX IDs. |
-|CLOUDFLARE Authoritative DNS, private R2 buckets, scoped tokens, CORS/lifecycle, Worker bindings, logs, and custom        |
-|domains.                                                                                                                  |
-|VERCEL Services deployment for web/API, rewrites, environment scopes, preview/production, cron endpoints, domains, and    |
-|TLS.                                                                                                                      |
-|REVENUECAT + ABLY Products, offerings, entitlements, store credentials, signed webhook, scoped realtime, and retry cron.  |
-|EAS + STORES Expo project, credentials, internal builds, TestFlight/Play testing, metadata, privacy, review, and rollout. |
-|BROWSER STORE Stable extension ID, least host permissions, OAuth sync, privacy disclosure, trusted testing, and review.   |
-|DESKTOP Native-OS signing/notarization, electron-builder installers, private update channel, upgrade tests, and rollback. |
-|DNS app.<domain> points from Cloudflare DNS to Vercel and stays DNS-only; assets/updates are Cloudflare Worker Custom     |
-|Domains.                                                                                                                  |
-|AGENT STOPS User handles sign-in/MFA, purchases, secret generation/reveal, destructive confirmations, and final           |
-|submissions.                                                                                                              |
-+==========================================================================================================================+
-                                                             |
-                                                             v
-+==========================================================================================================================+
-|                                        6  GENERATED package.json COMMAND SURFACE                                         |
-+--------------------------------------------------------------------------------------------------------------------------+
-|WORKSPACE dev | build | typecheck | verify WHY: run and validate exactly the selected monorepo.                           |
-|APP LOOPS dev:web | dev:mobile | dev:api | dev:desktop | dev:extension                                                    |
-|APP CHECKS verify:web | verify:mobile | verify:api | verify:desktop | verify:extension                                    |
-|VERCEL deploy:vercel:{link,preview,production,inspect,domain:inspect} WHY: connect, release, diagnose, and configure DNS. |
-|MOBILE mobile:eas:{login,init} | mobile:build:{internal,production}:{ios,android} | mobile:submit:{ios,android}           |
-|DATABASE neon:{login,project:create} | db:{generate,migrate,check,studio} | verify:db                                     |
-|STORAGE r2:{login,bucket:create,cors:list,cors:set} | assets:proxy:{check,dev,deploy} | verify:assets-proxy               |
-|UPDATES desktop:updates:{cloudflare:login,bucket:create,provision,publish}                                                |
-|UPDATES desktop:updates:worker:{check,dev,deploy,types} | desktop:updates:build:{mac,win,linux} | verify:desktop-updates  |
-|DESKTOP desktop:build | verify:desktop EXTENSION extension:zip | verify:extension                                         |
-|STRUCTURE anhedral doctor | add/ui --dry-run WHY: detect drift and preview safe structural changes.                       |
-+==========================================================================================================================+
-                                                             |
-                                                             v
-+==========================================================================================================================+
-|                                      7  DEVELOPER, AGENT + COMPUTER-USE EXPERIENCE                                       |
-+--------------------------------------------------------------------------------------------------------------------------+
-|DOCS README.md first run/source map | docs/DEVELOPMENT.md recipes | docs/STACK.md tool map | PRODUCTION.md cloud runbook. |
-|CONTROL SKILL.md agent workflow | ANHEDRAL.md ownership notes | anhedral.json source of truth | .env.example inventories. |
-|CODING AGENT Ask name/domain -> resolve modules -> generate -> read docs/manifest -> doctor -> provision -> verify ->     |
-|hand off.                                                                                                                 |
-|SUBAGENTS Lead owns mutations; delegate docs/env inventory, read-only DNS checks, and final verification without secrets. |
-|COMPUTER USE Drive provider consoles after user authentication; configure accounts, domains, OAuth, DNS, stores, and      |
-|rollout.                                                                                                                  |
-|SECRET HANDOFF Stop before Generate/Reveal/Create; name the variable/file; user pastes directly into uncommitted          |
-|env/provider UI.                                                                                                          |
-|UI DX Source-owned components, target routing, accessibility, ordinary framework APIs, and no hidden proprietary runtime. |
-|OPERATIONS DX Exact root commands, selection-aware docs/scripts, machine-readable plans, provider ledger, and explicit    |
-|stop gates.                                                                                                               |
-+==========================================================================================================================+
-                                                             |
-                                                             v
-+==========================================================================================================================+
-|                                               8  VERIFY, RELEASE + OPERATE                                               |
-+--------------------------------------------------------------------------------------------------------------------------+
-|LOCAL Smallest package check -> typecheck -> full verify -> build -> doctor; never weaken a failing gate.                 |
-|DATABASE Generate -> review/commit SQL -> drift gate -> controlled migrate -> health/readiness checks.                    |
-|RUNTIME API coverage, auth/CORS, billing replay/order, Ably reconnect, R2 upload/read/range/cache, Worker method/host     |
-|security.                                                                                                                 |
-|CLIENTS Next build | Expo compatibility/device checks | packaged Electron smoke/upgrade | live WXT MV3 worker in Chrome.  |
-|INFRA Confirm provider team/resource names, protected env presence, DNS answers, TLS, Vercel health, Worker bindings, and |
-|logs.                                                                                                                     |
-|CI Pinned toolchain, strict pnpm policy, allowed build scripts, OSV audit, secret scan, deterministic outputs, and        |
-|release checks.                                                                                                           |
-|RELEASES Vercel preview/prod | TestFlight/Play tracks | browser-store trusted/review | signed desktop staged update       |
-|channel.                                                                                                                  |
-|RECOVERY Transaction rollback, provider backups, database rollback plan, staged/phased rollout, telemetry, and documented |
-|owners.                                                                                                                   |
-+==========================================================================================================================+
-```
-
-## Runtime connection summary
-
-```text
-web / mobile / desktop / extension
-                |
-                v
-       packages/api-client
-                |
-                v
-       Fastify API + Zod contracts
-          |         |          |
-          v         v          v
-   Clerk identity  Neon     private R2
-                    |
-                    v
-          RevenueCat entitlement
-                    |
-                    v
-               Ably event
-                    |
-                    v
-           clients refetch state
-
-signed desktop release -> private update R2 -> updates.<domain> Worker -> electron-updater
-```
-
-The runtime summary is intentionally smaller than the lifecycle map. It shows
-only application data flow; DNS, provisioning, release gates, and agent actions
-remain in the master map above.