anhedral 0.10.0 → 0.11.0

package/docs/application-stack-standard.md

@@ -1,104 +1,75 @@
-# Anhedral Application Stack & Delivery Standard
+# Supported application stack
 
-Anhedral builds client-owned applications using established frameworks and provider tools. Default web apps use Vinext, React, TypeScript, Tailwind, shadcn/ui and Lucide on Cloudflare Workers. Native Next.js on Vercel is the established alternative. React is the UI layer within these full-stack frameworks, not a standalone web-app recipe. Add components only when the product needs them, prefer free-first plans where suitable, and keep source, accounts, data, billing and recovery customer-owned.
+Anhedral scaffolds ordinary TypeScript applications in a pnpm/Turborepo monorepo. Its bundled registry defines the supported recipes, dependencies, generated files, environment requirements and composition constraints. Application source, repositories, provider accounts and billing remain under the application owner's control.
 
-Respect existing account, budget, audience and release authorization. Request only missing approval for paid activation, material spending, architecture changes or release.
+## Bundled options
 
-## Stack selection
-
-Cloudflare first. **Default** = preferred when needed; **Option** = choose for the stated requirement. Alternatives are grouped beside their defaults. Preserve justified existing stacks.
-
-### Foundation and clients
-
-| Capability | Default — when | Options — when |
+| Layer | Supported options | Generated foundation |
 | --- | --- | --- |
-| Shared source | **Default:** [TypeScript](https://www.typescriptlang.org/docs/), [pnpm](https://pnpm.io/), [Turborepo](https://turborepo.dev/docs), [Zod](https://zod.dev/) — shared code, builds and validation. | — |
-| Web | **Default:** [Vinext + React](https://developers.cloudflare.com/workers/framework-guides/web-apps/nextjs/) — full-stack web on Workers. | **Option:** [Next.js + OpenNext](https://opennext.js.org/cloudflare) — existing Next app on Workers; [Next.js + Vercel](https://vercel.com/docs/frameworks/nextjs) — native Next hosting. |
-| UI | **Default:** [Tailwind](https://tailwindcss.com/docs/), [shadcn/ui](https://ui.shadcn.com/docs) — web styling/components. | **Option:** [CSS Modules](https://nextjs.org/docs/app/getting-started/css) — bespoke styling or existing CSS. |
-| Mobile | **Default:** [Expo](https://docs.expo.dev/) — React Native iOS/Android. | **Option:** [SwiftUI](https://developer.apple.com/documentation/swiftui) / [Compose](https://developer.android.com/compose) — platform-specific UI; [Flutter](https://docs.flutter.dev/) — Dart shared UI; [Capacitor](https://capacitorjs.com/docs) — package web UI with native access. |
-| Desktop | **Default:** [Electron](https://www.electronjs.org/docs/latest/) — reuse web UI with Chromium/Node. | **Option:** [Tauri](https://v2.tauri.app/) — smaller system-webview packages; [GPUI](https://github.com/zed-industries/zed/blob/main/crates/gpui/README.md) — GPU-rendered Rust UI, separate UI code and pre-1.0 APIs; [SwiftUI/AppKit](https://developer.apple.com/documentation/appkit) — Apple-specific desktop experience. |
-| Extensions | **Default:** [WXT](https://wxt.dev/guide/introduction.html) — browser extensions. | **Option:** [Chrome extension APIs](https://developer.chrome.com/docs/extensions) — direct implementation or existing extension. |
+| Workspace | pnpm/Turborepo, TypeScript, ESLint, shared UI | Official pinned shadcn monorepo bootstrap, workspace configuration and checks |
+| Web | Vinext; Next.js | React, Tailwind, shadcn/ui and Lucide; Vinext on Workers by default, native Next.js on Vercel or explicit OpenNext on Workers |
+| API | Hono | OpenAPI Worker application with selected service bindings |
+| Mobile | Expo | React Native Reusables and NativeWind; native builds require platform toolchains |
+| Desktop | Electron | React application; packaging, signing and distribution require platform-specific setup |
+| Browser extension | WXT | React popup and Chrome side panel; installation and store distribution are separate steps |
+| Data | D1, Neon, local data | Drizzle schemas for D1/Neon; direct Neon serverless HTTP; device-local data foundations |
+| Identity | Better Auth, Clerk | Server/client configuration and selected schema or provider middleware |
+| Worker services | R2, KV, realtime, Queues, cron, Workflows | Private storage bindings, cache/config bindings, Durable Object WebSocket rooms and job/schedule foundations |
+| AI | Workers AI, OpenAI, AI SDK | Server-side inference bindings or SDK factories |
+| Email | Resend | Server-side transactional email client |
+| Payments | Stripe, RevenueCat | Payment/entitlement integration foundations |
+| Monitoring and analytics | Sentry, PostHog, Basin | Runtime SDK factories or analytical ingestion configuration |
+| Shared styling | Styling | Tokens and presets for compatible native and extension clients |
 
-### Backend and data
+These are scaffolding recipes, not completed application features. Database migrations, authorization, provider resources, webhooks, email domains, product behavior and monitoring initialization require application-specific implementation and verification. Environment examples contain names and placeholders, never provider credentials.
 
-| Capability | Default — when | Options — when |
-| --- | --- | --- |
-| API/runtime | **Default:** [Workers](https://developers.cloudflare.com/workers/) + [Hono](https://hono.dev/docs/getting-started/cloudflare-workers) — APIs, webhooks and services. | **Option:** framework server routes — integrated web backend; [Containers](https://developers.cloudflare.com/containers/) — Linux/native dependencies. |
-| Database | **Default:** [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver) + [Drizzle](https://orm.drizzle.team/docs/connect-neon) — direct HTTP for CRUD and independent queries; no Hyperdrive required. | **Option:** [Hyperdrive + Neon](https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/) — pg/postgres.js, connection reuse or optional caching, justified by workload/latency measurements; Neon WebSocket driver — session/interactive transactions; [D1 + Drizzle](https://orm.drizzle.team/docs/sqlite/connect-cloudflare-d1) — Worker-native SQLite; [SQLite](https://www.sqlite.org/docs.html) / [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) — local/offline data. |
-| Authentication | **Default:** [Better Auth](https://better-auth.com/docs/adapters/drizzle) — own identities, sessions and organizations. | **Option:** [Clerk](https://clerk.com/docs) — managed authentication and identity features. |
-| Files | **Default:** [R2](https://developers.cloudflare.com/r2/) — uploads, attachments and archives. | **Option:** local files — device-only apps; existing S3-compatible storage — migration has no benefit. |
-| Realtime/state | **Default:** [Durable Objects + hibernating WebSockets](https://developers.cloudflare.com/durable-objects/best-practices/websockets/) — rooms, presence and coordinated events. | **Option:** [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) — one-way updates; polling — infrequent changes; [KV](https://developers.cloudflare.com/kv/) — read-heavy, eventually consistent cache/config. |
-| Background work | **Default:** [Queues](https://developers.cloudflare.com/queues/) — jobs/retries; [Workflows](https://developers.cloudflare.com/workflows/) — durable multi-step work; [Cron](https://developers.cloudflare.com/workers/configuration/cron-triggers/) — schedules. | **Option:** [DO alarms](https://developers.cloudflare.com/durable-objects/api/alarms/) — entity timers; [K2](https://developers.cloudflare.com/k2/) — retained replayable streams, beta acceptable. |
-| Placement | **Default:** standard Workers placement — request-proximate execution. | **Option:** [Placement](https://developers.cloudflare.com/workers/configuration/placement/) — database/backend round trips dominate. |
+Inspect exact current requirements before generation:
 
-Start with direct Neon HTTP; use non-interactive transaction batches where suitable, or WebSocket/standard-driver transactions when interactive sessions are needed. Benchmark before adding Hyperdrive. Its pooling operates on Cloudflare infrastructure; Neon PgBouncer operates near Postgres. With Hyperdrive use pg/postgres.js against Neon’s non-pooled endpoint, not the Neon serverless driver or stacked poolers. Disable result caching for authoritative auth, permissions, entitlements and balances. Neither Neon nor D1 is universally faster/cheaper; offline sync remains application work.
+```sh
+anhedral registry list --json
+anhedral registry view better-auth --json
+anhedral new my-app --hono --d1 --better-auth --r2 --dry-run --json
+```
 
-### AI, media and communication
+The default selects only Vinext on Cloudflare Workers. Add capabilities because the application needs them. The resolver adds required dependencies and rejects incompatible choices, including conflicting web frameworks, databases and identity providers. `--all` is unsupported. Native Next.js selects Vercel unless Cloudflare hosting is explicit. Some services require a Worker application; inspect the plan rather than assuming every selection can run on every client.
 
-| Capability | Default — when | Options — when |
-| --- | --- | --- |
-| Inference | **Default:** [Workers AI](https://developers.cloudflare.com/workers-ai/) — supported models fit; [AI Gateway](https://developers.cloudflare.com/ai-gateway/) — routing/controls/telemetry. | **Option:** [OpenAI/other providers through Gateway](https://developers.cloudflare.com/ai-gateway/usage/providers/) — required models; [AI SDK](https://ai-sdk.dev/docs/introduction) — shared model interfaces and streaming UI. |
-| Retrieval/agents | **Default:** [AI Search](https://developers.cloudflare.com/ai-search/) — managed RAG. | **Option:** [Vectorize](https://developers.cloudflare.com/vectorize/) — custom vector pipeline; [Agents SDK](https://developers.cloudflare.com/agents/) — stateful agents. |
-| Isolated execution | — | **Option:** [Sandboxes](https://developers.cloudflare.com/sandbox/) — user/agent code; [Browser Run](https://developers.cloudflare.com/browser-run/) — automation, screenshots/PDFs; [Containers](https://developers.cloudflare.com/containers/) — custom runtime. |
-| Calls | **Default:** [RealtimeKit](https://developers.cloudflare.com/realtime/realtimekit/) — audio/video/screensharing. | **Option:** [Realtime SFU + TURN](https://developers.cloudflare.com/realtime/) — custom WebRTC; [LiveKit](https://docs.livekit.io/) — existing ecosystem or voice-agent requirements. |
-| Images/video | **Default:** [Images](https://developers.cloudflare.com/images/) — transforms/delivery; [Stream](https://developers.cloudflare.com/stream/) — encoding/playback/live video. | **Option:** [R2](https://developers.cloudflare.com/r2/) — originals/downloads without managed processing; [Media over QUIC](https://developers.cloudflare.com/moq/) — specialized low-latency transport. |
-| Email | **Default:** [Email Service](https://developers.cloudflare.com/email-service/) — email workflows, sending beta acceptable. | **Option:** [Resend](https://resend.com/docs) — established transactional email provider. |
-| Notifications | **Default:** [Expo Push](https://docs.expo.dev/push-notifications/overview/) — Expo mobile notifications. | **Option:** [APNs](https://developer.apple.com/documentation/usernotifications) / [FCM](https://firebase.google.com/docs/cloud-messaging) — direct native delivery; [Web Push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) — browser notifications. |
+## Source layout and composition
 
-Durable Objects coordinate calls/events; SFU/TURN handle media. WebSockets do not replace background push.
+Use `apps/*` for applications and services, and `packages/*` for shared code. Generated `docs/stack.md` lists the resolved options, destinations, environment names and setup requirements. `anhedral.setup.json` records setup requirements; `anhedral.registry.json` records recipe versions, generated-file fingerprints and workspace references.
 
-### Commerce and access
+The catalog in `src/stack-registry.ts` owns recipe identity and composition rules. Dependencies and the official shadcn bootstrap are pinned in `src/dependencies.ts`. Recipes under `src/scaffold/` compose the resolved selection inside a staging transaction. Workspace names must be unique, references must resolve, and dependency cycles fail before commit.
 
-| Capability | Default — when | Options — when |
-| --- | --- | --- |
-| Web billing | **Default:** [Stripe Checkout](https://docs.stripe.com/payments/checkout) + [Billing](https://docs.stripe.com/billing) — payments, subscriptions and usage billing. | **Option:** [Connect](https://docs.stripe.com/connect) — marketplaces/payouts; [Tax](https://docs.stripe.com/tax) — tax calculation. |
-| Cross-store purchases | **Default:** [RevenueCat](https://www.revenuecat.com/docs/web/integrations/stripe) — supported store/web subscriptions and entitlements. | **Option:** [StoreKit](https://developer.apple.com/documentation/storekit) / [Play Billing](https://developer.android.com/google/play/billing) — own purchase lifecycle integrations. |
-| Access enforcement | **Default:** Workers + chosen database — entitlement projections, seats, grants and credit/usage ledger. | **Option:** [Monetization Gateway](https://developers.cloudflare.com/monetization-gateway/) — eligible x402 requests, closed beta acceptable. |
+Incremental `add` uses only the bundled catalog maintained with the CLI. External registries and custom registry payloads are unsupported. Additions preserve edited and untracked source, refresh generated stack documentation and record provenance. Runtime relocation and older projects without compatible receipts require deliberate migration.
 
-Stripe/stores remain purchase authorities; RevenueCat does not cover every Stripe pricing model. Verify webhooks, process idempotently and reconcile refunds/restores. Cloudflare hosts enforcement; it does not replace payment processing.
+```sh
+anhedral add my-app resend stripe --dry-run --json
+anhedral add my-app resend stripe
+anhedral doctor my-app --json
+```
 
-### Security, analytics and operations
+This catalog uses an Anhedral recipe schema; it is not a shadcn registry payload. The plugin's catalog and documentation are generated from the same maintained sources.
 
-| Capability | Default — when | Options — when |
-| --- | --- | --- |
-| Public protection | **Default:** [DNS/TLS](https://developers.cloudflare.com/directory/), [WAF](https://developers.cloudflare.com/waf/), [Turnstile](https://developers.cloudflare.com/turnstile/) — domains, HTTPS and abuse controls. | **Option:** [API Shield](https://developers.cloudflare.com/api-shield/) — additional API protection; [Access + Tunnel](https://developers.cloudflare.com/cloudflare-one/) — staff tools/private origins. |
-| Specialized security/networking | — | **Option:** [Load Balancing](https://developers.cloudflare.com/load-balancing/) — multiple origins; [Spectrum](https://developers.cloudflare.com/spectrum/) — TCP/UDP proxying; [Data Localization](https://developers.cloudflare.com/data-localization/) — regional processing requirements. |
-| Credentials | **Default:** [Worker secrets](https://developers.cloudflare.com/workers/configuration/secrets/) — server credentials. | **Option:** [Secrets Store](https://developers.cloudflare.com/secrets-store/) — shared account secrets, beta acceptable. |
-| Website analytics | **Default:** [free Web Analytics](https://www.cloudflare.com/web-analytics/) — traffic/performance. | **Option:** [PostHog](https://posthog.com/docs) — product funnels, cohorts and replay. |
-| Operational telemetry | **Default:** [Workers Observability](https://developers.cloudflare.com/workers/observability/) — logs/traces/errors. | **Option:** [Sentry](https://docs.sentry.io/platforms/javascript/) — cross-client error monitoring; [Analytics Engine](https://developers.cloudflare.com/analytics/analytics-engine/) — custom telemetry; [Basin](https://developers.cloudflare.com/basin/) — event ingestion and analytical SQL on R2/Iceberg. |
-| Feature delivery | — | **Option:** [Flagship](https://developers.cloudflare.com/flagship/) — targeted exposure; [PostHog](https://posthog.com/docs/feature-flags) — existing flags/experiments. |
-| Content/source tooling | — | **Option:** [Artifacts](https://developers.cloudflare.com/artifacts/) — durable versioned source/artifacts, beta acceptable; [GitHub](https://docs.github.com/) — customer-owned Git source. |
-| Customer platforms | — | **Option:** [Cloudflare for SaaS](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/) — customer domains; [Workers for Platforms](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/) — customer code. |
-
-### Development, releases and accounts
-
-| Capability | Default — when | Options — when |
-| --- | --- | --- |
-| Agent tooling | **Default:** [Cloudflare Codex plugin](https://developers.cloudflare.com/agent-setup/codex/) — Cloudflare Skills/MCP and agent operations. | **Option:** [cf CLI](https://developers.cloudflare.com/cf/) — broad API/project operations, beta acceptable. |
-| Cloud releases | **Default:** [Wrangler](https://developers.cloudflare.com/workers/wrangler/) + [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) — Worker development/releases. | **Option:** [GitHub Actions](https://docs.github.com/en/actions) — custom CI; [Vercel](https://vercel.com/docs/deployments) — selected native Next stack. |
-| Native builds | **Default:** [EAS](https://docs.expo.dev/build/introduction/) — hosted Expo builds. | **Option:** [local Expo builds](https://docs.expo.dev/build-reference/local-builds/) — local CI; platform toolchains — GPUI/Tauri/native clients. |
-| Distribution/accounts | **Default:** customer-owned [Apple](https://developer.apple.com/programs/), [Play](https://play.google.com/console/about/), [Chrome](https://developer.chrome.com/docs/webstore/register) accounts — selected stores. | **Option:** direct desktop distribution — signed/notarized packages; [free Cloudflare account creation](https://developers.cloudflare.com/changelog/post/2026-08-04-free-dashboard-button/) — eligible separate customer accounts. |
+## Provider access and delivery
 
-Use customer-owned resources. Implement backup/recovery, authorization, replay, offline sync and ledger correctness explicitly. Select specialized capabilities as needed; alternatives are choices, not dependencies to install together.
+`anhedral auth <app>` derives required providers from the selected stack. `--status` checks access without opening login; noninteractive and JSON calls report blockers. A provider session or accessible API endpoint is not proof of all resource permissions or completed integration setup. Provider administration credentials remain separate from application runtime secrets.
 
-The CLI generates Vinext, Next.js, Expo, Electron, WXT and Hono applications plus selected provider starters. Neon starters use the direct serverless HTTP driver with Drizzle. Alternatives in the table require deliberate project implementation. A starter does not establish configured infrastructure or working product behavior. The bundled capability registry and `new --dry-run --json` describe generated requirements.
+`ship` coordinates selected integration provisioning, private runtime configuration and supported hosting delivery. [Provider configuration](provider-configuration.md) documents the eight API adapters, required management credentials and owner prerequisites. Authentication checks alone do not establish every write permission. If resolved bindings change tracked configuration, review and commit them before repeating the command. Expo delivery verifies the selected account/project/source and returns a build-page link while queued or a download link when complete; store submission remains separate.
 
-The bundled stack registry in `src/stack-registry.ts` owns each item’s identity, version, source recipe, setup requirements, environment variables, bindings, destinations and composition constraints. Product IDs and capability views derive from that catalog. Foundations include pnpm/Turborepo, TypeScript, ESLint and shared UI; the official shadcn bootstrap is pinned in `src/dependencies.ts`. The resolver validates selections and orders dependencies; focused modules under `src/scaffold/` install the resolved recipes inside the staging transaction. `registry list|view` exposes the catalog, dry-run plans expose concrete destinations, and `anhedral.registry.json` records installed recipes and local workspace references. Package names must be unique, workspace references must resolve, and dependency cycles fail before commit. `doctor` verifies the installed receipt and workspace graph against the setup plan. To add a supported part, declare one catalog entry with its recipe and composition policy, then exercise composition and rollback in the registry tests. Build and release tooling regenerate matching plugin catalogs. Incremental `add` stages bundled or declarative local/HTTPS registry items, resolves dependencies, rejects unsafe paths and installation hooks, and refuses to replace edited source. Receipts record source integrity and generated-file hashes. Runtime relocation and older projects without fingerprints require explicit migration. This is an Anhedral recipe schema; shadcn JSON interoperability is not supported. Stack alternatives without generator recipes remain deliberate implementation choices.
+The CLI provides the foundation and delivery workflow. Product features, design, custom integrations and maintenance remain development work; Anhedral offers these services to businesses.
 
-## Implementation rules
+## Application requirements
 
-- Start new projects with the official shadcn pnpm/Turborepo monorepo; use `apps/*` and genuinely shared `packages/*`. Web/Electron use React, TypeScript, Tailwind, shadcn/ui and Lucide; Expo uses React Native Reusables; WXT uses Chrome Side Panel. Preserve suitable existing architecture.
-- Vinext is the default Worker framework; verify its actual compatibility. Native Next.js uses Vercel; explicit Next.js on Workers uses OpenNext. Shared/mobile APIs use Hono/OpenAPI; web-only endpoints can use framework routes.
-- Select one database and one identity provider. Generator alternatives remain deliberate flags, not automatic migrations. Better Auth requires a database; authentication is optional. Configure origins/sessions and enforce tenant/resource authorization server-side. Hosting privacy is separate from product identity.
-- Keep R2 private and authorize file operations in Workers. Keep secrets server-side, environments separate and migrations reviewed. KV is not authoritative transactional state. Bound retries, concurrency, AI usage and paid consumption; implement idempotency, quotas and recovery.
-- Use customer-owned source, accounts, billing and recovery. Domain registration/brokerage uses GoDaddy and Cloudflare DNS; preserve existing mail/DNSSEC. Configure actual sender domains and inbound destinations; routing does not migrate mailboxes.
-- Codex and browser/native tools implement and verify product flows; Fallow audits TS/JS. A starter, installed package or successful deployment does not prove a configured integration or working application.
-- Record decisions and connections in the application's `docs/architecture.md`; keep tested behavior, environment, release/source identity and unresolved gaps in `docs/verification.md`. Update these existing files after relevant changes.
+- Keep server credentials out of client bundles and version control. Configure separate environments and review database migrations.
+- Select one database and one identity provider. Implement resource and tenant authorization in the application; hosting access protection does not replace product identity.
+- Keep R2 private and authorize file operations. KV is eventually consistent and should not hold authoritative transactional state.
+- Implement webhooks and jobs idempotently. Bound retries, concurrency and paid usage; verify recovery and data compatibility before rollback.
+- Verify the actual runtime: Vinext/Vite on Workers, Next.js/OpenNext on Workers, or native Next.js on Vercel. Generated native clients need device, packaging and signing checks appropriate to their target.
+- Run generated checks and exercise product flows. Initialization, installed SDKs and successful builds do not prove provider configuration or production acceptance.
 
-Follow the [delivery workflow](delivery-workflow.md) for release, acceptance and recovery. The [managed-hosting contract](https://github.com/anhedral/anhedral-init/blob/main/docs/managed-hosting-architecture.md) describes an undeployed client/backend boundary, not an available service. Installed versions, publication and live acceptance require separate evidence.
+Follow the [delivery workflow](delivery-workflow.md) for the supported customer-account deployment, verification and recovery commands.
 
-## Maintenance
+## Maintenance and verification
 
-This file owns stack choices; the delivery guide owns lifecycle/acceptance; the managed contract owns its API; sponsorship owns support information. Update the owning file in the same change when behavior or provider requirements change. Remove stale claims and unused options. Verify current official guidance when selecting a provider; beta availability is not guaranteed. Do not add catalogs, duplicated analyses or progress reports to `docs`. The plugin's bundled stack/delivery files are generated copies, never separate sources of truth.
+Update the catalog, recipe and relevant documentation together when supported behavior changes. Regenerate plugin references with `pnpm build`; do not edit generated copies independently. Verify supported selection combinations and packaged output before release.
 
-Generated `pnpm audit:deps` checks all dependencies and verifies reviewed security backports against patch hashes, installed package hashes and regression checks. Unknown advisories and altered backports fail closed.
+Generated `pnpm audit:deps` checks dependencies and verifies reviewed security backports against patch hashes, installed package hashes and regression checks. Unknown advisories and altered backports remain blocking.

package/docs/cli-design.md

@@ -0,0 +1,67 @@
+# CLI behavior and design
+
+Anhedral uses three primary commands: `init` scaffolds source, `auth` checks or guides provider authentication, and `ship` provisions/configures the supported stack and coordinates delivery. `add`, `registry`, and `doctor` support development. Hosting selection and advanced release operations remain available through focused command help.
+
+The comparison below uses current upstream documentation and source inspected on October 12, 2026. These projects solve different problems; the useful comparison is how they make commands discoverable, changes reviewable, and failures understandable.
+
+| Reference | Useful practice | Anhedral behavior |
+| --- | --- | --- |
+| [shadcn CLI](https://ui.shadcn.com/docs/cli) and its [command source](https://github.com/shadcn-ui/ui/tree/main/packages/shadcn/src/commands) | Source ownership, command-specific help, working-directory selection, and previews before changing files | Bundled recipes scaffold owned source; focused help, `--cwd`, and `add --dry-run`, `--diff`, and `--view` support review |
+| [shadcn monorepos](https://ui.shadcn.com/docs/monorepo) | Resolve application and shared-package destinations coherently | The registry resolves dependencies and workspace references into `apps/*` and `packages/*`; additions preserve edited source and record provenance |
+| [GitHub CLI help](https://cli.github.com/manual/gh_help) | Discover commands through focused help topics | `anhedral help <command>` and `<command> --help` show the same options, examples, and relevant prerequisites |
+| [uv command reference](https://docs.astral.sh/uv/reference/cli/) | Consistent output controls and discoverable options | `--quiet` suppresses human output; `--json` retains one machine-readable result; errors remain on stderr |
+| [CLI Guidelines](https://clig.dev/) | Explain outcomes, suggest corrections, and show the next action | Human summaries describe selected parts, pending setup, release evidence, and next steps; command/flag typos receive bounded suggestions |
+
+Shadcn's entry point uses Commander and registers separate commands; its initialization separates preflight checks, configuration, templates, registry work, and source updates. Anhedral separates its command metadata, argument handling, human output, registry resolution, staged transactions, and provider operations. The existing provider verification and mutation boundaries remain in the operation modules. See [shadcn's entry point](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/index.ts) and [initialization implementation](https://github.com/shadcn-ui/ui/blob/main/packages/shadcn/src/commands/init.ts).
+
+## Command definitions
+
+`src/command-schema.ts` declares command descriptions, option flags and aliases, required or optional values, and repeatable options. Command help and argument validation consume this same metadata; help text is never parsed to infer flag behavior. Singleton command options reject duplicates, required values reject missing input, and boolean options reject inline values without echoing those values. `--allow-email` remains repeatable; `add --diff` and `--view` accept an optional path. Command dispatch and domain-specific value validation remain in the operation handlers.
+
+## Daily use
+
+```sh
+anhedral init client-app --hono --neon --dry-run
+anhedral init client-app --hono --neon
+anhedral auth --cwd client-app
+anhedral ship --cwd client-app --dry-run
+
+anhedral add resend --cwd client-app --dry-run
+anhedral add resend --cwd client-app --diff
+anhedral add resend --cwd client-app --view packages/email/src/index.ts
+anhedral add resend --cwd client-app
+
+anhedral help ship
+anhedral registry view neon
+anhedral doctor --cwd client-app --json
+```
+
+Complete the selected provider settings and connect the intended hosting account before delivery, as described in [provider configuration](provider-configuration.md). The commands above are examples, not authorization to deploy an application.
+
+`--cwd` / `-c` selects the working directory and resolves relative directory arguments from it. `add <items...>` uses the current project; the earlier `add <directory> <items...>` form remains supported. Use `--cwd` or an explicit `./directory` when a directory name is also a stack item. `new` remains a compatibility alias for scaffolding an explicit destination; documentation and help lead with `init`.
+
+## Output contract
+
+- Human output summarizes the operation and relevant next steps. Interactive scaffolding reports its current stage on stderr. Redirected output has no animated terminal effects or progress messages.
+- `--json` emits a complete result on stdout. Failures emit a JSON error, code, and next action on stderr with a nonzero exit status. Login prompts and scaffolding tool output are suppressed in machine mode.
+- `--quiet` / `-q` suppresses human results and progress, retaining errors. Combining it with `--json` retains the JSON result.
+- `--verbose` exposes local scaffolding tool output in human mode. Machine and quiet modes keep tool output suppressed.
+- Help and version checks do not require an existing project or a usable working directory. Unknown commands and flags fail before setup or provider operations; suggestions do not execute corrections.
+
+## Source previews
+
+`add --diff [path]` shows an applicable unified patch. `add --view [path]` shows generated source. Both imply a dry run and use the existing staged transaction; neither installs the preview. Without a path, they show the changed generated files. Conflict reporting still applies; previewing a conflict does not permit overwriting edited source.
+
+Previews exclude private environment files and `.anhedral/` state. Public `.env.example` / `.dev.vars.example` templates can be inspected. Binary, nonregular, or files over 256 KiB are marked unavailable. The combined preview has a 1 MiB limit; select a file for larger additions. Diffs use a linear single-contextual-hunk implementation, including explicit handling of final newlines and new empty files.
+
+A selection that needs a new upstream web bootstrap cannot produce source previews offline. The CLI explains this and directs the user to the selection-only `--dry-run` plan, which marks `filesChecked: false`. It does not fabricate files or run a networked generator during that preview.
+
+## Deliberate boundaries
+
+The public CLI accepts only bundled registry options. It does not accept external URLs, local third-party registries, or arbitrary remote content. It does not force overwrites, infer paid activation, or claim that scaffolding and authentication establish complete product behavior. Provider enrollment, permissions, DNS, billing eligibility, signing, and feature development remain explicit where required.
+
+Contract and local-flow tests establish command behavior, source preservation, machine output, and provider request/response handling. Live account provisioning and deployment require separate authorized verification. Release remains a separate review decision.
+
+## Read-only project inspection
+
+`anhedral inspect [directory] --json` returns the shared versioned project-inspector contract used by the optional plugin UI. It reads bounded allowlisted local source and receipt files only, with independent errors for unavailable evidence. It does not contact providers, inspect credential values, migrate state or change files. It preserves per-target latest attempt and last successful release as separate facts. Authentication, permission and live provider health remain explicitly unknown. Read time does not make an old receipt fresh.

package/docs/delivery-workflow.md

@@ -1,16 +1,24 @@
 # Build and deliver an application
 
-Codex implements the product; the CLI supplies scaffolding, selected resource reconciliation and source/provider evidence. Customer-account delivery exists. Managed hosting has a local client foundation, not an operated service. Start with users, flows, audience, budget and observable acceptance criteria; preserve suitable existing apps.
+The CLI supplies the source foundation, provider access checks and supported delivery operations. Feature design, product implementation, custom integrations and ongoing maintenance are development work. Anhedral offers these services; scaffolding and successful deployment do not establish a finished product.
+
+Codex implements the product; the CLI supplies scaffolding, selected resource reconciliation and source/provider evidence. Delivery uses your own Cloudflare or Vercel account. Start with users, flows, audience, budget and observable acceptance criteria; preserve suitable existing apps.
 
 ## Plan and implement
 
 1. Choose only needed components from the [stack standard](application-stack-standard.md). Record decisions, ownership, environment/cost assumptions and actual connections in the application's `docs/architecture.md`.
 2. Match installed plugin, registry `cliVersion` and executable versions. Check Node/pnpm, Git identity, toolchains and customer provider access. For unpublished development use `pnpm build` and `node dist/bin.js`; never silently substitute `@latest`.
-3. Inspect `new <unused-directory> <flags> --dry-run --json`, then generate with those choices. Review README, AGENTS, setup manifests and resolved lockfile. For initialized apps, preview `add <directory> <items...> --dry-run --json`; additions protect edited source and record registry provenance. Select only items from the bundled Anhedral catalog. If a web addition reports `filesChecked: false`, the preview covers selection and targets only; the actual transaction checks generated-file conflicts before committing. Older projects and runtime relocation require explicit migration. `doctor --providers --json` checks access without configuring infrastructure or certifying production.
+3. Inspect `init <unused-directory> <flags> --dry-run --json`, then generate with those choices. Review README, AGENTS, setup manifests and resolved lockfile. For initialized apps, preview `add <directory> <items...> --dry-run --json`; additions protect edited source and record registry provenance. Select only items from the bundled Anhedral catalog. If a web addition reports `filesChecked: false`, the preview covers selection and targets only; the actual transaction checks generated-file conflicts before committing. Older projects and runtime relocation require explicit migration. `doctor --providers --json` checks access without configuring infrastructure or certifying production.
 4. Implement screens, APIs, persistence, authorization and integration behavior. Replace placeholders with working flows. Configure real secrets, origins and reviewed migrations using provider tools; starters do not establish setup completion. Keep credentials out of source, logs and handoffs.
 
+## Provider authentication
+
+Run `anhedral auth <directory>` for the selected stack. `--status` checks existing access without opening login; `--provider <name>` limits the check to a required provider. JSON and `--non-interactive` never start login prompts. Missing credentials, insufficient permissions and unverified access return a nonzero exit status. Environment-supplied API credentials stay out of output and committed configuration. Authentication does not activate subscriptions, select hosting audience or configure integration resources.
+
 ## Source and release authority
 
+Complete the selected integrations' nonsecret account/resource choices in `anhedral.providers.json`. See [provider configuration](provider-configuration.md) for supported adapters, management credentials, private runtime files, retry behavior, provider prerequisites and verification limits. `ship --dry-run` previews their missing settings without provider operations.
+
 Use customer-owned accounts and a reviewed clean commit. Default to a private repository in the selected account; organizations require selection.
 
 ```sh
@@ -23,7 +31,7 @@ Choose one release path per change: checked `ship`, or checks followed by an aut
 
 ## Cloudflare delivery
 
-Vinext/Workers is the default web recipe. Explicit Next.js on Workers uses `--next --hosting=cloudflare`. Select persistence, identity and AI from the standard. Cloudflare manifests use `anhedral.project.json`; mixed apps append `--provider cloudflare` to lifecycle operations.
+Vinext/Workers is the default web recipe. Explicit Next.js on Workers uses `--next --hosting=cloudflare`. Select persistence, identity and AI from the standard. Cloudflare manifests use `anhedral.project.json`. Default `ship` coordinates Cloudflare services before the Vercel web app in mixed projects. Use `--provider cloudflare` or `--provider vercel` to operate on one hosting target explicitly; standalone `provision` is Cloudflare-only.
 
 ```sh
 anhedral connect my-app --audience private --allow-email owner@example.com
@@ -35,7 +43,7 @@ anhedral ship my-app --json
 
 Connect verifies the sole accessible or explicitly selected `--account` and preserves audience/account choices. Public access requires authorization. Private hosting needs Zero Trust and scoped Access/Workers permissions; verify routes, domains and previews before and after deployment. Whole-Worker Access does not cover WebSockets: design and verify private realtime separately.
 
-Provision reconciles D1, private R2, KV and Queues/dead-letter queues; it does not implement schemas or integrations. Configure reviewed migrations, direct Neon (or selected Hyperdrive), Basin and external providers separately. The Neon starter uses direct serverless HTTP with a server-side DATABASE_URL. Reconcile partial operations before retrying. Shipping requires clean source, checks account/bindings, runs application checks and confirms active versions/traffic. Multiple Workers are not an atomic release; web deploys last by default.
+Provision reconciles D1, private R2, KV and Queues/dead-letter queues; it does not implement schemas or integrations. Full `ship` also configures the selected integration adapters and private Basin streams. Review database migrations and application-specific integrations separately; developer-added Hyperdrive, Basin sinks and transforms need an explicit provider workflow. The Neon starter uses direct serverless HTTP with a server-side DATABASE_URL. Reconcile partial operations before retrying. Shipping requires clean source, checks account/bindings, runs application checks and confirms active versions/traffic. Multiple Workers are not an atomic release; web deploys last by default.
 
 ## Native Next.js/Vercel delivery
 
@@ -52,6 +60,10 @@ anhedral verify my-app --json
 
 Connect checks project/framework/root, repository link and audience. New private projects establish independently verified all-deployment Vercel Authentication before code or Git deployment. Hosting membership is separate from product identity; do not add members, seats or paid upgrades automatically. Existing protection changes need authorization. Mixed apps provision/ship Cloudflare services first, then verify the web-to-service flow.
 
+## Mobile build handoff
+
+Use `ship --platform ios|android --profile <eas-profile>`. Set an explicit Expo owner and slug in static `app.json`; project creation/linking stops for review and a commit. Subsequent builds check the linked identity, configure only public mobile keys, and use the pinned EAS CLI. A queued build returns a build-page link; repeat the same command to inspect that build without submitting another. Completed artifacts must match the selected project and source commit before returning a download URL. It does not submit to a store. Simulator builds cannot be submitted to TestFlight. Signed iOS builds require Apple credentials; Android APK builds can be installed directly.
+
 ## Acceptance and operating limits
 
 Run relevant lint/types/Fallow, dependency audits, meaningful tests and actual runtime builds. Exercise browser flows, installed extension permissions, packaged desktop behavior and signed/native device flows where selected. Deployment or HTTP 200 alone does not establish product completion.
@@ -62,15 +74,15 @@ Record service quotas, maximum retries/concurrency/AI work, alert ownership and
 
 ## Operations and handoff
 
-| Command | Boundary |
-| --- | --- |
-| `register` | Stable app identity; generated apps register automatically. |
-| `status --refresh` | Independently refresh provider state. |
-| `manage` / `manage --local` | Provider overview / explicitly historical local view. |
-| `adopt` | Verify active Vercel Git source/repository and record its checked release; no push/deploy. |
-| `recover` | Reconcile current provider state after cloning; no invented historical tests/releases. |
-| `verify` | Run meaningful root `test:live` with actual URL/release and source/provider checks. |
-| `rollback --release <id> --data-compatible` | Restore recorded code after compatibility review; no migration reversal/data restore. |
+| Command                                     | Boundary                                                                                   |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `register`                                  | Stable app identity; generated apps register automatically.                                |
+| `status --refresh`                          | Independently refresh provider state.                                                      |
+| `manage` / `manage --local`                 | Provider overview / explicitly historical local view.                                      |
+| `adopt`                                     | Verify active Vercel Git source/repository and record its checked release; no push/deploy. |
+| `recover`                                   | Reconcile current provider state after cloning; no invented historical tests/releases.     |
+| `verify`                                    | Run meaningful root `test:live` with actual URL/release and source/provider checks.        |
+| `rollback --release <id> --data-compatible` | Restore recorded code after compatibility review; no migration reversal/data restore.      |
 
 Open the actual app URL or installable artifact and exercise acceptance. Maintain the application's existing `docs/verification.md`: exact versions, source/release, repository, provider identity, audience, configured versus tested integrations, reproducible results and remaining actions. Refresh after changes; acceptance becomes stale when production changes. After rollback, restore matching clean source before verifying.
 
@@ -78,6 +90,8 @@ Committed manifests preserve identity. Ignored `.anhedral/` receipts are local h
 
 ## Evidence and maintenance
 
-Local/mocked coverage is distinct from live GitHub/Vercel private setup, fresh-clone recovery, installed fresh-chat workflow and connected integrations. Retained HTTP/CRUD/redeploy/rollback runs prove only their tested profile. Sites' inventory, visitor connectors and managed sharing require separate platform implementation. No operated managed backend or issued app URL is established here; see the [managed contract](https://github.com/anhedral/anhedral-init/blob/main/docs/managed-hosting-architecture.md).
-
 Before release, check the exact candidate's runtime, current dependency advisories, remote CI, installed-plugin and selected provider/native acceptance. Unresolved high-severity production audit failures block shipping. Keep dated results with release/test artifacts. Update this guide when commands, lifecycle or acceptance requirements change, and regenerate its bundled plugin copy.
+
+### Interrupted local delivery locks
+
+Use `anhedral recover --lock [directory]` only after an interrupted command. This releases a lock only when its recorded process is proven dead on the same host. It never replays provider operations or deletes delivery receipts. Inspect status and receipts before retrying. Live, foreign, legacy, malformed, and uncertain locks are preserved. A leftover `.anhedral/ship.guard` requires manual inspection; the CLI cannot safely infer its ownership. Do not combine local lock recovery with `--provider` or `--refresh`.

package/docs/plugin-ui.md

@@ -0,0 +1,61 @@
+# Anhedral project inspector
+
+Anhedral is headless-first: describe the application to Codex, review the selected stack, develop its features, authenticate to your providers and ship through the CLI. The optional project inspector displays the same local evidence available from `anhedral inspect --json`. Opening or refreshing it performs no provider calls, credential checks, provisioning, deployment or migrations.
+
+Building or packaging the plugin does not install or publish it. Actual Codex host rendering and composer behavior require separate verification; protocol tests do not establish those behaviors.
+
+## Screens and evidence
+
+| Screen | Information | Evidence boundary |
+| --- | --- | --- |
+| Overview | Project identity, stack selection, per-target latest attempt and last success | Recorded results; not live health or feature acceptance |
+| Stack | Workspace package dependencies, declared bindings, environment names and cron expressions | Package dependencies do not prove network calls; declarations do not prove resource existence |
+| Setup | Local prerequisites, selected providers, capability limits and setup guidance | Authentication, selected-account permission and billing remain not checked |
+| Delivery | Separate Cloudflare, Vercel and mobile records; integration pending outcomes and latest operation | One provider's success does not establish another's; old running records do not prove a process is active |
+
+The inspector has no live analytics reader, database-row reader, or schedule-execution reader. These unsupported tabs have been removed. Credentials do not activate an unimplemented reader. Environment names come from example files and reveal no values or proof of secret validity. Mobile download URLs may contain access tokens and are excluded; validated Expo build-page links may be displayed. Missing record timestamps and project identity are unavailable rather than invented.
+
+Every section is bounded and validated independently. A corrupt provider journal must not hide another target's valid evidence. Read time is explicitly distinct from receipt time. Configured, recorded and unknown states must remain distinguishable. General secret files, provider credential vaults, runtime state, raw diagnostics and absolute source paths are excluded from the UI projection.
+
+## Interactions
+
+New project opens a new composer with this prompt, without sending: “Create a new project using [@Anhedral](plugin://anhedral@anhedral). Start by explaining the stack and asking me what it should be about.” Setup and delivery actions prepare unsent drafts for the current conversation. The user reviews and sends the request before Codex acts. Unsupported hosts offer copyable text. Project selection updates authorized model context; it does not execute commands.
+
+Refresh reloads local files only. Rename and forget affect only local catalog metadata, never project source or provider resources. There is no project-creation or registration dialog. Register an explicitly authorized directory through the local operator command. MCP tool inputs accept project IDs rather than arbitrary filesystem paths.
+
+## Installation
+
+Install with `codex plugin marketplace add anhedral/anhedral-cli`, then `codex plugin add anhedral@anhedral`. The marketplace references `plugin-v<version>` in the same repository. The release workflow creates this immutable tag from the verified ZIP, including its generated runtime; the development source directory alone is not an installable release. Plugin source tags retain the reviewed release commit as their parent. Existing tags cannot be replaced by the release workflow.
+
+## Local development
+
+The UI toolchain requires Node 22.13+ within Node 22, or Node 24+. The CLI retains its separately documented engines.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm --dir plugin-app install --frozen-lockfile
+pnpm build
+pnpm plugin:check
+ANHEDRAL_PLUGIN_DATA="$PWD/.artifacts/plugin-preview" node plugin-app/dist/server.mjs register "$PWD" "Anhedral"
+ANHEDRAL_PLUGIN_DATA="$PWD/.artifacts/plugin-preview" pnpm plugin:preview
+```
+
+Open `http://127.0.0.1:4317/`. The preview binds only to loopback, validates Host/Origin, bounds requests and uses a restrictive content security policy. `anhedral inspect [directory] --json` provides the shared read-only projection directly. `anhedral registry capabilities --json` explains the supported automation and owner steps.
+
+`src/project-inspector.ts` owns projection; `plugin-app/server/snapshot.ts` adds catalog identity. The browser only renders its validated schema. The MCP server exposes `open_projects`, `list_projects`, `get_project`, local metadata tools and model-only source/catalog context tools. They remain useful without UI rendering. Standard MCP Apps resources and bridge messages provide the optional panel, host themes and inline/fullscreen modes. Native host-specific draft support is a separate acceptance gate.
+
+The private catalog retains its existing on-disk location for registered users. List views read bounded summaries; only a selected project loads detailed inspection. The server does not automatically discover other projects. A remote server cannot inspect these local directories without a separately reviewed architecture; never publish the local catalog through a tunnel.
+
+## Recovery and release review
+
+Interrupted catalog writers can be inspected and recovered with the same private catalog directory:
+
+```sh
+ANHEDRAL_PLUGIN_DATA="$PWD/.artifacts/plugin-preview" node plugin-app/dist/server.mjs recover-catalog-lock
+```
+
+Only a proven dead same-host owner permits recovery. Live, foreign, malformed and uncertain owners remain blocked. Recovery changes catalog access only, not provider work or delivery state.
+
+Build/package checks bind the runtime and self-contained browser HTML to source and CLI version. Exact ZIP protocol tests exercise resources, schemas and headless tools. Before publication, verify native host entrypoints, unsent drafts, theme/reload behavior, all four sections, keyboard navigation and narrow screens against the exact rebuilt ZIP. Publication remains a separate reviewed action.
+
+The design follows the official [optional UI guidance](https://developers.openai.com/plugins/concepts/plugins#optional-ui) and [MCP Apps foundation](https://developers.openai.com/plugins/build/chatgpt-ui#start-with-mcp-apps).

package/docs/provider-configuration.md

@@ -0,0 +1,117 @@
+# Provider configuration
+
+Anhedral scaffolds source, guides authentication, and provisions and configures the selected stack before deployment. The application and accounts belong to the developer or client. Feature development, design, custom integrations, and ongoing maintenance are Anhedral's services.
+
+## Setup
+
+1. Run `anhedral init <directory> <stack-flags>`. Review the generated source and install dependencies.
+2. Fill in `anhedral.providers.json`. It contains only selected integrations, nonsecret resource names, account identifiers, regions, and desired webhook settings. Empty account/domain fields require an explicit choice. Commit this file with the application source. To use an existing resource, set its ID instead of requesting a new project by name.
+3. Supply management credentials through the process environment and run `anhedral auth <directory>`. `--status` performs checks without opening login. Cloudflare, Vercel, and Expo support interactive CLI login; API integrations show their required credentials. A successful read does not prove every write permission.
+4. Connect the intended hosting account, project, plan, and audience using `anhedral connect`. Review and commit the connection manifest. Expo uses the explicit `owner` and `slug` in `apps/mobile/app.json`.
+5. Inspect `anhedral registry capabilities --json` for implemented scope and evidence limits, then inspect `anhedral ship <directory> --dry-run`. It reports missing provider settings without login, network requests, writes, provisioning, or deployment. Run `ship` after reviewing the plan and authorizing the provider operations.
+
+The manifest uses a typed, provider-specific configuration contract. It rejects unsupported providers, foreign fields, unknown enum choices, and duplicate webhook events before network operations. Empty fields are accepted for scaffolding but must be completed when required for provisioning. The exported `PROVIDER_CONFIGURATION_SCHEMA` matches these fields and enums; no generated `$schema` URL is currently installed in projects.
+
+Authentication results label verified access as `session`, `management`, or `runtime`; unsuccessful checks use `none`. Clerk and OpenAI management credentials take precedence over runtime credentials. A runtime probe is never reported as management access. Vercel and Expo session probes require bounded, single-identity output from the pinned CLI; diagnostic paragraphs do not count as a session. These probes do not verify the selected project, all write permissions, account enrollment, or remaining owner prerequisites.
+
+Management keys do not belong in this manifest or application source. Runtime credentials returned by providers are configured in ignored application environment files and private `.anhedral/` state. API errors and CLI results omit credential values. Never attach this private state to an issue or commit it.
+
+## Adapters
+
+| Provider | Management credential | Automated configuration | Owner prerequisites and remaining application work |
+| --- | --- | --- | --- |
+| Neon | `NEON_API_KEY` | Create or select an explicitly scoped organization/project; check outstanding operations; obtain the selected database/role's pooled connection URI; configure runtime and migration environment files | An eligible account/region; reviewed schema and migrations; application data access |
+| Clerk | `CLERK_PLATFORM_API_KEY` | Verify the selected workspace; create or select an application and environment; retrieve its matching publishable and secret keys | Platform API access; production domain/DNS/OAuth setup; application authorization. `CLERK_SECRET_KEY` alone verifies runtime access and cannot create an application |
+| Resend | `RESEND_API_KEY` with management access | Create or select the explicit sending domain; request verification; report required DNS records; issue a domain-scoped sending key only after verification | Domain ownership and DNS publication/propagation; sending eligibility; templates and delivery behavior |
+| Stripe | `STRIPE_SECRET_KEY` | Verify the explicit account and test/live key mode; configure a webhook with explicitly listed events when requested; securely retain its signing secret | Account activation for live payments; product/price decisions and webhook handlers. Provisioning does not invent a billing model or create financial commitments |
+| RevenueCat | `RC_API_KEY` with v2 configuration access | Create or select a project; create/select iOS, Android, or connected Stripe apps; retrieve platform public SDK keys | Store credentials or Stripe account connection; products, offerings, entitlements, SDK installation, and purchase verification |
+| Sentry | `SENTRY_AUTH_TOKEN` | Select organization/team/project; create a project if absent; verify the team/platform; select a single active client key or create one if absent; configure DSN | Appropriate organization/team permissions; platform SDK initialization, source maps, privacy filtering, and alerts |
+| PostHog | `POSTHOG_PERSONAL_API_KEY` | Select US/EU region and organization; create/select a project; retrieve its ingestion key and matching ingestion host | Project permissions; product events, privacy/consent rules, and SDK initialization. Personal management keys never become ingestion keys |
+| OpenAI | `OPENAI_ADMIN_KEY` | Create or select an active project; create a named service account; retain its one-time runtime key privately | Organization administration access, provider billing eligibility, limits, and application AI behavior. `OPENAI_API_KEY` alone cannot create projects |
+
+The adapters implement a bounded scaffolding setup, not every administration endpoint a provider exposes. Account enrollment, required billing acceptance, DNS ownership, OAuth consent, store enrollment, and product-specific design remain explicit owner steps. Provisioning success does not certify those steps or finished product functionality.
+
+### Example manifest
+
+For a selected Hono + Neon + PostHog stack:
+
+```json
+{
+  "schemaVersion": 1,
+  "providers": {
+    "neon": {
+      "name": "customer-app",
+      "organizationId": "org-example",
+      "region": "aws-us-east-1",
+      "database": "app",
+      "role": "app_owner"
+    },
+    "posthog": {
+      "name": "customer-app",
+      "organizationId": "00000000-0000-0000-0000-000000000000",
+      "region": "eu"
+    }
+  }
+}
+```
+
+Replace example organization IDs with the intended account's actual identifiers. Existing resources use `projectId`; Clerk uses `applicationId` and `workspaceId`; Resend uses `domainId`; RevenueCat can select `iosAppId`, `androidAppId`, or `webAppId`. New RevenueCat native apps use `bundleId` / `packageName`; a new Stripe app requires a previously connected `stripeAccountId`. Sentry selects `organization`, `team`, `project`, and `platform`. Stripe requires `accountId` and `mode`; optional `webhookUrl` must use HTTPS and `webhookEvents` must explicitly name the handled events. A webhook endpoint and handler must already be designed before registering it.
+
+## Delivery and retries
+
+Cloudflare reconciles D1, private R2 buckets, KV, Queues, and private JSON Basin streams. Basin HTTP ingestion stays disabled; the Worker binding is enabled. Sinks and transformations require application-specific design. Durable Objects, schedules, Workflows, and Workers AI bindings are configured through Worker deployment. Hyperdrive configurations added by a developer still require an explicit provider workflow.
+
+If resource provisioning changes tracked binding IDs, `ship` returns `configuration-required` and stops before deployment. Review and commit those changes, then repeat the command. It never commits code automatically. Pending Neon operations or unverified Resend DNS return `provider-configuration-required` and stop deployment. The configured integrations' remaining product setup appears in their results.
+
+Review the generated database schema and apply the selected database migrations before testing application features or authentication. Generated tables and SDK factories are starting points; provisioning resources does not migrate the application database or implement its authorization rules.
+
+For selected Better Auth applications, shipping first reads `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` from the primary server's ignored, untracked runtime file. Configure a generated nonplaceholder secret of at least 32 characters and the intended HTTPS public origin. On POSIX systems this file must have mode `0600`; keep equivalent private file access on other systems. Tracked or symlinked files, broad file permissions, missing values, placeholder secrets, and unsafe origins stop shipping before provider mutations. For older generated Workers, remove `BETTER_AUTH_URL` or `BETTER_AUTH_SECRET` from tracked `wrangler.jsonc` `vars`, review and commit that change, then configure both values in the private runtime file. Wrangler cannot deploy a same-named plain variable and secret. The preflight does not generate a secret, choose a domain, modify files, configure OAuth, or verify application-user authorization.
+
+Cloudflare uploads runtime credentials with the code using Wrangler's `--secrets-file`; it does not make a separate secret update that deploys an old Worker. Temporary credential files are private and removed after the operation. Vercel configures only the selected web runtime's production environment, checks every returned result for success, and then performs the checked deployment. In mixed Vercel/Cloudflare projects, default `ship` coordinates Cloudflare services first, then the Vercel web application under one operation lock. `ship --provider cloudflare` or `ship --provider vercel` explicitly selects only that hosting target. A setup gate stops before the dependent web deployment. If Cloudflare completes and Vercel fails, the result is partial; no atomic provider or data rollback is attempted. Repeating `ship` rechecks both targets and reuses provider receipts where available; it does not skip completed phases merely because the diagnostic operation journal says they completed.
+
+Shipping records nonsecret phases and outcome in ignored `.anhedral/operation.json`. This is a diagnostic journal, not a resumable transaction or proof of live product behavior. `status --json` and the dashboard can show the recorded operation; resource replay protection remains in the provider journals and deployment/build receipts. A new run records a new operation and revalidates current prerequisites.
+
+Creation receipts are saved immediately in ignored `.anhedral/providers.json`. Schema 2 keeps minimal creation identities and status there; supported one-time credentials are stored separately in ignored `.anhedral/provider-credentials.json` with private file permissions. Legacy schema 1 journals migrate credentials before replacing their full-response receipts, preserving recovery evidence if receipt writing is interrupted. Subsequent runs verify existing resources and reuse saved credentials. Ignored `.anhedral/runtime.json` contains deployment runtime values and must also remain private. A confirmed 4xx rejection can be retried after access is corrected. A timeout, malformed success response, rate limit, or server error can leave an unknown creation outcome: the CLI stops rather than replaying the mutation. Inspect the provider and preserve a secure backup of the receipt before reconciling the pending operation. Desired configuration changes also stop and require reconciliation. Never remove state blindly to bypass this check.
+
+Read-only API requests retry bounded transient failures (429, 502, 503, 504, transport interruptions and timeouts) within a 30-second overall deadline, with at most three attempts. Short provider retry delays are respected; longer delays return an actionable failure instead of retrying early. Invalid or oversized JSON is not retried. Mutating POST/PATCH requests are never replayed automatically, including requests carrying an idempotency key.
+
+Keep secure backups of `.anhedral/` and runtime environment files when moving machines. A fresh clone does not carry one-time credentials or provisioning receipts. Configure explicitly selected existing resource IDs and recover runtime credentials through authorized provider tooling rather than treating it as the original provisioning session. The CLI does not automatically delete, rotate, or replace resources. `integrations status` reads the journal without migration or writes. `integrations recover --provider <provider> --operation <exact hash> --resource <id>` verifies a supported existing resource against the unchanged recorded configuration, then writes only its local completion receipt. It never recreates or deletes a provider resource. Recovery is unavailable for legacy pending entries without operation metadata, changed desired configuration, and one-time credential creation when the original credential is missing; inspect the provider and retain secure backups. RevenueCat application recovery requires the parent project ID recorded explicitly in the original configuration.
+
+```sh
+anhedral integrations status my-app --json
+anhedral integrations recover my-app --provider neon --operation <exact-64-character-hash> --resource <verified-project-id> --json
+```
+
+Copy the operation hash from status and supply the intended resource ID yourself. Supported recovery checks cover known Neon projects, Clerk applications/workspace/environment, Resend domains, PostHog projects/organizations, active OpenAI projects, Sentry projects/teams/platform, and RevenueCat projects or explicitly scoped apps. They perform provider GET requests and then update only the local completion receipt. Status does not migrate old journals or create directories. It shows missing descriptors and one-time-credential operations as blocked. Resend sending keys, Stripe webhook signing secrets, and OpenAI service-account keys cannot be recovered from a resource ID alone; securely retained credentials and explicit provider inspection are required. Never paste credentials into the command or conversation.
+
+
+## Mobile delivery
+
+Use `anhedral ship <directory> --platform ios|android --profile <profile>`. Set the intended Expo `owner` and `slug` in static `apps/mobile/app.json`. The pinned EAS CLI creates/links the project when needed, then stops for review and a source commit. Subsequent builds independently check the linked project identity. Inherited profiles require explicit resolution before automatic delivery.
+
+Only public mobile keys are uploaded to the selected EAS environment; server credentials are excluded. Queued builds return a build-page link and `building` state. Repeat the same command to inspect the saved build ID without creating another build. Completed builds must match the selected project and source commit before returning the download link. Failed/cancelled builds require provider inspection before removing the pending record and requesting another build.
+
+Android preview builds produce APKs; production builds produce AABs. iOS simulator artifacts need no device signing; signed iOS builds need the developer's Apple credentials and enrollment. Anhedral never runs `eas submit`. Store uploads and approvals belong to the owner.
+
+## Verification scope
+
+Local contract tests cover selected-stack planning, API request/response shapes, resource reuse, one-time credentials, account mismatch, pending operations, DNS gates, unknown outcomes, private file safety, runtime partitioning, and deployment handoff. These tests do not establish live account eligibility, quota, permissions, billing, DNS, signing, or production product behavior. Verify those in explicitly authorized accounts before release.
+
+Provider contracts: [Neon API](https://api-docs.neon.tech/reference/createproject), [Clerk Platform schema](https://github.com/clerk/openapi-specs/blob/main/platform/beta.yml), [Resend API](https://resend.com/docs/api-reference/introduction), [Stripe API](https://docs.stripe.com/api), [RevenueCat API v2](https://www.revenuecat.com/docs/api-v2), [Sentry API](https://docs.sentry.io/api/), [PostHog API](https://posthog.com/docs/api), [OpenAI administration](https://developers.openai.com/api/reference/resources/admin/), [Cloudflare secrets](https://developers.cloudflare.com/workers/configuration/secrets/), [Vercel OpenAPI](https://openapi.vercel.sh), and [pinned EAS source](https://github.com/expo/eas-cli/tree/v21.0.1/packages/eas-cli/src/commands).
+
+## Authorized staging acceptance
+
+Use a dedicated, explicitly selected account/project for live verification. Before the first mutation, record its owner, region, resource names, permitted operations, spending limit, cleanup responsibility, and retention period in the application's verification notes. Never use production credentials for routine tests or treat access to an account as permission to incur unspecified costs.
+
+For each selected provider, verify the following against the exact candidate CLI:
+
+1. Missing, expired, and insufficient credentials produce an actionable state without leaking keys or starting creation.
+2. The selected account, organization, environment and region match the manifest before provisioning.
+3. First creation and repeated configuration use the intended resources, with no duplicate creation.
+4. Pending DNS, provider operations or enrollment produce an explicit blocked state before deployment.
+5. An interrupted or unknown creation outcome preserves evidence and stops automatic replay; recovery requires inspected provider state.
+6. Runtime credentials reach only their intended server or public client target. Check runtime access through a bounded application flow, without publishing the credential value.
+7. The actual deployed service or build matches the selected project and checked source commit. Test its promised user flow independently of build success.
+8. Record provider/resource IDs, source revision, nonsecret verification results, unresolved owner steps, and cleanup results. Keep credential files and complete provider responses out of public logs and issues.
+
+A completed local contract test, an accessible API endpoint, a created resource, a successful deployment, and a verified product flow are separate evidence levels. Release notes must name the level actually established; do not promote one to another.