anhedral 0.11.1 → 0.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,86 +4,64 @@
4
4
  [![npm](https://img.shields.io/npm/v/anhedral)](https://www.npmjs.com/package/anhedral)
5
5
  [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
6
6
 
7
- Anhedral scaffolds source code, guides authentication, then provisions, configures, and deploys the supported stack wherever provider APIs allow.
7
+ Anhedral creates TypeScript application workspaces and helps deliver them to your own cloud accounts. Start with a web app, add the interfaces and services your product needs, and keep the source code, infrastructure, data and billing under your control.
8
8
 
9
- You own the code, provider accounts, infrastructure, data, and billing. The CLI provides the foundation and delivery tools; application features remain development work. Anhedral offers feature development and ongoing maintenance for businesses that want that work delivered for them.
9
+ The default is **Vinext, React, Tailwind, shadcn/ui and Lucide on Cloudflare Workers**, with pnpm and Turborepo. The CLI generates the foundation and handles supported setup and delivery operations. You or your coding agent implement the product.
10
10
 
11
- ## Get started
11
+ ## Start locally
12
12
 
13
- Supported Cloudflare workspaces use Void 0.27.0 and require Node.js 24.21.0+ and pnpm 10.34.5. Explicit OpenNext, Queues and Basin selections use Wrangler. Other workspace profiles require Node.js 22.13+ on 22.x or Node.js 24+. Initialize on Linux, macOS, or WSL.
14
-
15
- Void owns Cloudflare provisioning, secret uploads and deployment. Anhedral retains stack composition, shared packages, customer ownership and independent release/product verification. Explicit OpenNext, Queues and Basin profiles use Anhedral’s Wrangler delivery path. Initialization creates source without deploying it.
13
+ Use **Node.js 24.21.0 or newer** and **pnpm 10.34.5**. Initialize on Linux, macOS or WSL.
16
14
 
17
15
  ```sh
18
16
  npm install --global anhedral
19
17
 
20
- # Preview the stack without creating project files or cloud resources
18
+ # Inspect the default selection; no writes or network requests.
21
19
  anhedral init my-app --dry-run --json
22
20
 
23
- # Generate a project and start development
21
+ # Generate source, install dependencies and start development.
24
22
  anhedral init my-app
25
23
  cd my-app
26
24
  pnpm dev
27
25
  ```
28
26
 
29
- You can also run the CLI with `pnpm dlx anhedral@latest`. Initialization downloads the upstream shadcn starter and installs dependencies; it does not create cloud resources or deploy your app.
27
+ Initialization downloads the pinned upstream starter and installs dependencies. It does not provision cloud services or deploy the app. Follow the generated README for local addresses and any setup required by your selection. You can also run the CLI with `pnpm dlx anhedral@latest`; pin a version for repeatable automation.
30
28
 
31
- ## Choose your stack
29
+ ## Choose what to generate
32
30
 
33
- The default is **Vinext, React, TypeScript, Tailwind, shadcn/ui, and Lucide on Cloudflare Workers**, organized as a pnpm/Turborepo monorepo.
31
+ An explicit selection chooses the requested applications; include the web option when you want web alongside another interface.
34
32
 
35
- | Application | Option |
36
- | --- | --- |
37
- | Web on Cloudflare Workers | Default |
38
- | Native Next.js on Vercel | `--next` |
39
- | Mobile with Expo | `--expo` |
40
- | Desktop with Electron | `--electron` |
41
- | Browser extension with WXT | `--wxt` |
42
- | Shared API with Hono | `--hono` |
33
+ | Project | Command |
34
+ | ---------------------------------- | -------------------------------------------------- |
35
+ | Default web app | `anhedral init my-app` |
36
+ | Web with D1 and Better Auth | `anhedral init my-app --vinext --d1 --better-auth` |
37
+ | Web and shared API with PostgreSQL | `anhedral init my-app --vinext --hono --neon` |
38
+ | Native Next.js on Vercel | `anhedral init my-app --next` |
39
+ | Expo mobile app | `anhedral init my-app --expo` |
40
+ | Electron desktop app | `anhedral init my-app --electron` |
41
+ | WXT browser extension | `anhedral init my-app --wxt` |
43
42
 
44
- Add capabilities when needed: D1 or Neon for data, Better Auth or Clerk for identity, R2 for files, and selected AI, billing, email, analytics, or background services.
43
+ Inspect available services and preview additions:
45
44
 
46
45
  ```sh
47
- anhedral init my-app --d1 --better-auth
48
- anhedral init mobile-app --expo
49
- anhedral init product --next --hono --d1 --r2
50
46
  anhedral registry list
51
47
  anhedral registry view resend --json
48
+ anhedral add resend --cwd my-app --dry-run --json
49
+ anhedral add resend --cwd my-app
52
50
  ```
53
51
 
54
- Optional `--neon-realtime` adds Neon live SQL foundations with separate server/client exports in `packages/neon-realtime`; it selects Neon and needs a server runtime. `--realtime` remains Cloudflare Durable Object WebSocket rooms. Neon Realtime is beta: enable the intended branch, allowed origins and secret manually, then implement authenticated, scoped query sealing and subscriptions. Initialization does not provision or verify Realtime. See the [stack standard](docs/stack-standard.md#neon-realtime).
55
-
56
- The project keeps Anhedral metadata in one committed root `anhedral.json`, with named sections for identity, stack selection, registry provenance, integrations and selected hosting. Credentials and delivery history remain in ignored runtime files and `.anhedral/`.
57
-
58
- The bundled registry contains recipes maintained and tested by Anhedral. Generated source belongs to your project and stays editable. External registries are unsupported. Preview additions before applying them:
59
-
60
- ```sh
61
- anhedral add resend stripe --cwd my-app --dry-run --json
62
- anhedral add resend stripe --cwd my-app
63
- ```
64
-
65
- See the [stack standard](docs/stack-standard.md) for supported combinations and architecture guidance.
52
+ Generated entry points live in `apps/*`, shared code in `packages/*`, and Anhedral configuration in one root `anhedral.json`. Read the [source-only full-stack example](https://github.com/anhedral/anhedral-cli/tree/main/examples/full-stack) to see a larger project without creating services.
66
53
 
67
- ## Authenticate and ship
54
+ ## Build and deliver
68
55
 
69
- Implement your app, configure its selected services, review migrations, and commit the source before delivery. The generated README explains the remaining setup. Run these commands from your project directory.
56
+ Implement the product, configure selected integrations and review database migrations. Then use the [software factory](docs/software-factory.md) to check provider access, connect the intended account and audience, commit source, ship and verify real user flows.
70
57
 
71
58
  ```sh
72
- anhedral auth
73
59
  anhedral auth --status --json
74
- anhedral connect --audience private --allow-email owner@example.com
60
+ anhedral doctor --providers --json
75
61
  anhedral ship --dry-run --json
76
- anhedral ship --json
77
- anhedral verify --json
78
62
  ```
79
63
 
80
- Replace the example email with the intended member. Private Workers hosting requires Cloudflare Zero Trust and the necessary Access permissions. Authentication does not establish every provisioning permission or complete service setup.
81
-
82
- For Wrangler profiles, changed resource IDs stop `ship` before deployment for review and a commit. Void can activate a target before recording new resource identities in `void.lock.json`; it then returns `configuration-required` with the activation receipts retained. Review and commit those locks, then ship the clean configuration. It never commits source automatically. Shipping runs project checks and records delivery results. `verify` exercises your application's live acceptance test; a successful scaffold or deployment alone does not prove its features work.
83
-
84
- Provider eligibility, subscriptions, usage limits, and charges remain your responsibility. Some setup requires owner action. Expo delivery returns EAS build links; it does not submit apps to stores.
85
-
86
- See [delivery and recovery](docs/delivery-workflow.md) and [provider configuration](docs/provider-configuration.md) for account selection, deployment, migration, rollback, and integration requirements.
64
+ These commands help inspect readiness; actual shipping can create resources, apply reviewed deployment migrations and publish code. Provider permissions, account eligibility and usage charges still apply. A generated starter or successful deployment does not establish a working product.
87
65
 
88
66
  ## Use with Codex
89
67
 
@@ -96,40 +74,26 @@ Select **Try now**, or start with:
96
74
 
97
75
  > Create a new project using [@Anhedral](plugin://anhedral@anhedral). Start by explaining the stack and asking me what it should be about.
98
76
 
99
- The plugin guides stack selection, feature development, setup, and verification. Its optional inspector displays local stack, setup, and recorded delivery evidence. It does not monitor live health or perform provisioning when opened. The CLI also works independently.
77
+ The plugin guides implementation using the same stack and workflow. Its optional inspector shows project structure, setup, recorded delivery evidence and explicit service controls. Opening it does not deploy the app. The CLI works independently.
100
78
 
101
- ## Commands and documentation
79
+ ## Read next
102
80
 
103
- Use `anhedral --help` or `anhedral help <command>` for options and examples. `--cwd` selects a project; `--json` provides structured output.
81
+ | Document | Use it to answer |
82
+ | -------------------------------------------- | ------------------------------------------------------------------------ |
83
+ | [Stack standard](docs/stack-standard.md) | What should the application contain, and how should it fit together? |
84
+ | [Software factory](docs/software-factory.md) | How do I turn a brief into a tested, delivered and maintainable product? |
104
85
 
105
- - [CLI usage](docs/cli-design.md)
106
- - [Stack standard](docs/stack-standard.md)
107
- - [Delivery and recovery](docs/delivery-workflow.md)
108
- - [Provider configuration](docs/provider-configuration.md)
109
- - [Plugin development](docs/plugin-ui.md)
86
+ Use `anhedral --help` and `anhedral help <command>` for command options. `--cwd` selects the project; `--json` produces structured output. Detailed references cover [provider configuration](docs/provider-configuration.md), [CLI behavior](docs/cli-design.md) and the [Codex inspector](docs/plugin-ui.md).
110
87
 
111
- ## Development and contributions
88
+ ## Work on the CLI
112
89
 
113
90
  ```sh
114
91
  pnpm install --frozen-lockfile
92
+ pnpm build
93
+ node dist/bin.js init ../my-test-app --dry-run --json
115
94
  pnpm test:all
116
- pnpm test:integration
117
95
  ```
118
96
 
119
- The root test command reuses a verified inspector runtime or installs its frozen dependencies and builds it when missing/stale. Preparing that runtime requires Node 22.13+ on 22.x or Node 24+; older CLI test lanes consume the verified CI runtime artifact. For inspector-specific checks, run `pnpm --dir plugins/codex/inspector install --frozen-lockfile` and `pnpm plugin:check`. Development builds require matching CLI and plugin versions; they do not update installed releases automatically.
120
-
121
- Focused fixes, tests, and documentation contributions are welcome. See [contributing](https://github.com/anhedral/anhedral-cli/blob/main/.github/CONTRIBUTING.md), [code of conduct](https://github.com/anhedral/anhedral-cli/blob/main/.github/CODE_OF_CONDUCT.md), and [security reporting](https://github.com/anhedral/anhedral-cli/blob/main/.github/SECURITY.md). Report reproducible problems in [issues](https://github.com/anhedral/anhedral-cli/issues) and vulnerabilities through [private reporting](https://github.com/anhedral/anhedral-cli/security/advisories/new).
122
-
123
- Anhedral is open source under the [Apache License 2.0](LICENSE). Generated applications are source code that developers can customize and license for their products, preserving applicable upstream notices.
124
-
125
- ## Repository layout
126
-
127
- | Path | Purpose |
128
- | --- | --- |
129
- | `src` | CLI and application scaffolding |
130
- | `plugins/codex/inspector` | Optional project inspector and MCP runtime sources |
131
- | `plugins/codex/distribution` | Plugin manifest, assets, skill and bundled runtime |
132
- | `scripts`, `tests` | Build, release and verification tooling |
133
- | `docs` | Canonical architecture, delivery and development documentation |
97
+ `pnpm test:integration` installs and checks generated projects. Inspector development uses `pnpm plugin:build`, `pnpm plugin:check` and `pnpm plugin:preview`; its dependencies and lockfile live in `plugins/codex/inspector`. Building the checkout does not update an installed CLI or plugin. See the [contribution guide](https://github.com/anhedral/anhedral-cli/blob/main/.github/CONTRIBUTING.md) for the development and review process.
134
98
 
135
- Run CLI commands from the repository root. `pnpm plugin:build`, `pnpm plugin:check` and `pnpm plugin:preview` delegate to the inspector application. The inspector owns its own dependencies and lockfile. Its build copies the bundled server and dashboard into `plugins/codex/distribution/runtime`; release packaging includes only the distribution directory. Shared project and provider logic stays in `src` so the CLI and plugin use the same implementation.
99
+ Anhedral is open source under the [Apache License 2.0](LICENSE). Generated applications are source code that developers can customize and license for their products, preserving upstream notices. Report bugs in [issues](https://github.com/anhedral/anhedral-cli/issues) and vulnerabilities through [private security reporting](https://github.com/anhedral/anhedral-cli/security/advisories/new).
package/dist/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const GENERATOR_VERSION = "0.11.1";
1
+ export declare const GENERATOR_VERSION = "0.11.2";
package/dist/version.js CHANGED
@@ -1 +1 @@
1
- export const GENERATOR_VERSION = '0.11.1';
1
+ export const GENERATOR_VERSION = '0.11.2';
@@ -0,0 +1,192 @@
1
+ # Software factory
2
+
3
+ Use this workflow to turn a product brief into an application that works, runs in the owner's accounts and can be maintained. The [stack standard](stack-standard.md) defines the architecture. This guide defines the work and the evidence needed to move it forward.
4
+
5
+ A developer or coding agent owns product implementation. The CLI supplies repeatable scaffolding, selected provider setup, delivery operations and recorded evidence. The owner supplies product decisions, account access and any required spending or release authorization. Source, repositories, infrastructure, data and billing stay owner-controlled.
6
+
7
+ ## 1. Define a small, testable product
8
+
9
+ Write the intended users, core flows, data, access boundaries and observable acceptance criteria in the application's `docs/architecture.md`. Include the selected components, actual connections, environment assumptions, cost limits and tradeoffs. Preserve suitable existing code and use the same project for later changes.
10
+
11
+ For a booking app, “a member can create a booking, see it after reload, and cannot read another member's booking” is an acceptance criterion. “Use auth and a database” is a stack choice. Plan both, then implement a vertical slice that exercises the real UI, server and persistence together.
12
+
13
+ Choose only the necessary catalog components. Decide whether the app is public or private, whether several clients share an API, and who owns production operations. Resolve decisions that materially affect architecture, access or cost before creating resources.
14
+
15
+ **Ready to generate:** the core flow, stack selection, owner and acceptance criteria are clear.
16
+
17
+ ## 2. Generate and inspect the foundation
18
+
19
+ Use Node.js `24.21.0+` and pnpm `10.34.5` for the default stack. Match the installed CLI version to the plugin's bundled registry `cliVersion` when using Codex. Pin that version for repeatable automation. For unpublished checkout work, run `pnpm build` and use `node dist/bin.js`; building does not update installed releases.
20
+
21
+ ```sh
22
+ anhedral init my-app --vinext --hono --d1 --better-auth --r2 --dry-run --json
23
+ anhedral init my-app --vinext --hono --d1 --better-auth --r2
24
+ cd my-app
25
+ pnpm dev
26
+ ```
27
+
28
+ Use an unused directory. `init --dry-run` performs no writes or network requests. Actual initialization downloads the upstream bootstrap, generates source and normally installs dependencies and initializes Git; it does not create cloud resources or deploy. `--skip-install` skips the final install, but the upstream bootstrap still needs network access.
29
+
30
+ Review the generated README, `AGENTS.md`, `docs/stack.md`, root `anhedral.json` and lockfile. The setup section records remaining requirements. Keep secrets in the selected runtime's private files, following its templates.
31
+
32
+ For later capabilities, preview before applying:
33
+
34
+ ```sh
35
+ anhedral add resend --dry-run --json
36
+ anhedral add resend --diff
37
+ anhedral add resend
38
+ anhedral doctor --json
39
+ ```
40
+
41
+ Additions use the bundled catalog and preserve edited source. Resolve conflicts deliberately. A selection plan marked `filesChecked: false` has not previewed files that require a new upstream web bootstrap. Add does not perform runtime relocation or switch the Cloudflare engine.
42
+
43
+ **Ready to implement:** the workspace starts, the selected packages have clear consumers, and remaining setup is understood.
44
+
45
+ ## 3. Implement the product and integrations
46
+
47
+ Build the acceptance flows with real persistence, validation and server-side authorization. Include loading, empty and failure states. Exercise denied access and cross-user/tenant isolation, not just the successful path. Keep shared contracts in packages and privileged code on servers.
48
+
49
+ Generate SQL with `pnpm db:generate`, review it, then apply it to the intended development database with `pnpm db:migrate`. Migration tasks are separate from build/startup. Production migrations need a reviewed apply plan and data compatibility assessment. The stack standard explains D1 ownership and separate Neon migration credentials.
50
+
51
+ Configure the selected integrations in the `providers` section of `anhedral.json`. Supply management keys through the process environment; runtime secrets stay private. Use existing scoped resources where appropriate. The [provider configuration reference](provider-configuration.md) lists supported automation, exact fields, credentials and owner prerequisites.
52
+
53
+ Domain verification, OAuth consent, billing enrollment, store signing and product-specific webhook/purchase behavior may require separate work. Neon Realtime additionally needs manual branch activation/origins and authenticated scoped sealing/subscription flows. Installed SDKs and obtained credentials do not establish that these features work.
54
+
55
+ **Ready to validate:** each core flow uses its intended implementation and remaining external dependencies are explicit.
56
+
57
+ ## 4. Check the actual application
58
+
59
+ From the generated project root:
60
+
61
+ ```sh
62
+ pnpm check
63
+ anhedral doctor --json
64
+ anhedral inspect --json
65
+ ```
66
+
67
+ `pnpm check` runs lint, types, Fallow analysis, dependency audit, tests and builds; the explicit OpenNext profile also builds its Worker output. Add meaningful product tests as you implement features. `doctor` checks local readiness and provenance. `inspect` reads local selection, setup and recorded delivery evidence offline; neither certifies live product behavior.
68
+
69
+ Exercise the actual runtime as well as compilation: Vinext/Vite workerd preview, OpenNext Worker preview, or native Next.js as selected. For mobile, desktop and extensions, check relevant device/packaged behavior and permissions. Verify retry, webhook duplication, private files, AI limits and recovery for the services you selected.
70
+
71
+ Record commands, results and gaps in the application's `docs/verification.md`. Distinguish local, preview and live results. A smoke check or HTTP 200 establishes availability of that route, not completion of the product.
72
+
73
+ **Ready to deliver:** checks pass and core flows have credible runtime evidence.
74
+
75
+ ## 5. Establish source, access and delivery authority
76
+
77
+ Verify the owner's Git identity and repository destination. Review source and secret ignores, then commit the application and configuration in its own repository. Generation does not create a source commit for you. Never commit private runtime files or `.anhedral/`.
78
+
79
+ ```sh
80
+ anhedral auth --status --json
81
+ anhedral auth
82
+ anhedral doctor --providers --json
83
+ anhedral repository --create --json
84
+ ```
85
+
86
+ `auth` can guide Cloudflare, Vercel and Expo login; API integrations use supplied environment credentials. `--status`, JSON and noninteractive modes never open login prompts. Authentication is separate from selecting a resource/account and proving every write permission.
87
+
88
+ `repository --create` creates a private GitHub repository under the selected account when necessary, pushes the intended source and verifies the exact remote identity/commit. Use explicit owner/name/visibility flags for a different authorized destination. Reuse matching origins; preserve existing remotes and visibility. Connecting Git to a host can trigger deployments, so check release authorization and policy first.
89
+
90
+ Connect the intended hosting account and audience, then review and commit the resulting configuration:
91
+
92
+ | Target | Example |
93
+ | ------------------------------ | ------------------------------------------------------------------------------------- |
94
+ | Private Cloudflare app | `anhedral connect --audience private --allow-email owner@example.com` |
95
+ | Intended public Cloudflare app | `anhedral connect --audience public` |
96
+ | Private Vercel app | `anhedral connect --scope customer-team --audience private --use commercial --create` |
97
+
98
+ Replace all example account/member values. Select `--account` for Cloudflare when needed, and `--provider cloudflare` or `--provider vercel` to disambiguate mixed projects. Private Cloudflare hosting requires Zero Trust and scoped Access permissions. Whole-Worker Access does not protect WebSockets; private realtime needs a separately reviewed identity/hostname design. Vercel private hosting requires verified all-deployment protection. Hosting access is separate from product identity and authorization.
99
+
100
+ Vercel Hobby is personal/non-commercial; use `--use personal` only for eligible personal use. Commercial apps need an eligible existing plan. Do not activate paid plans, broaden audience or weaken protection to clear a blocker.
101
+
102
+ **Ready to ship:** source is committed, account/audience are selected, and permissions and release authority cover the intended operations.
103
+
104
+ ## 6. Deliver one reviewed change
105
+
106
+ Choose one path for each change: CLI delivery, or connected Vercel Git delivery. Configure branch protection and required CI explicitly; a connected host does not automatically wait for GitHub Actions.
107
+
108
+ ### CLI delivery
109
+
110
+ ```sh
111
+ anhedral ship --dry-run --json
112
+ anhedral ship --json
113
+ anhedral status --refresh --json
114
+ ```
115
+
116
+ The dry run previews setup and delivery without provider operations. Actual `ship` coordinates supported integration setup, private runtime configuration, checks and hosting delivery. In mixed projects it handles Cloudflare services before the Vercel web app; provider flags select one target explicitly.
117
+
118
+ For supported Cloudflare selections, Void owns provisioning and deployment. `provision` reports the plan and defers writes to Void. Explicit OpenNext, Queues/DLQ and Basin use Wrangler; standalone `provision` reconciles Cloudflare resources only. The integration adapters and their limits are documented in the provider reference.
119
+
120
+ **Treat `configuration-required` as a checkpoint.** Wrangler can stop before deployment when resolved resource IDs change tracked bindings. Void can activate a target before recording new resource identities in `void.lock.json`; Anhedral retains activation receipts and then requires review and a commit. Inspect those results, commit the expected changes, and ship the clean configuration again. Do not assume a nonzero result means nothing happened. Anhedral never commits source automatically. Multiple Workers are not an atomic release.
121
+
122
+ Void apps use `env.example` and one private app-root `.env`. Production secrets travel through noninteractive stdin; public build variables must be present when building client bundles. Follow generated templates and the provider reference rather than adding unsupported environment files. Generate/review shared SQL first; exactly one server owns deployment migrations.
123
+
124
+ Anhedral independently checks active provider versions, traffic, account and audience against retained receipts. A process exit code or deployment log alone is insufficient. See [Void verification](void-verification.md) for the pinned receipt contract and outstanding live acceptance gates.
125
+
126
+ ### Connected Vercel Git delivery
127
+
128
+ After committing source and establishing the verified repository, add `--git` to the Vercel `connect` command. Then:
129
+
130
+ ```sh
131
+ pnpm check
132
+ anhedral repository --json
133
+ # Wait for the connected production deployment of this exact commit.
134
+ anhedral adopt --json
135
+ anhedral status --refresh --json
136
+ ```
137
+
138
+ `repository` pushes source; the host's Git integration deploys it. `adopt` verifies the active production source/repository and records the release without another push or deployment. Do not also run `ship` for that same change.
139
+
140
+ ### Native delivery
141
+
142
+ For Expo, set explicit owner/slug in static `apps/mobile/app.json`, configure the selected EAS profile and run:
143
+
144
+ ```sh
145
+ anhedral ship --platform android --profile preview --json
146
+ ```
147
+
148
+ Use `--platform ios` for iOS. Project creation/linking requires review and a commit before a build continues. A queued result returns the EAS build-page link; repeat the command to inspect that build rather than submitting another. A completed artifact must match the selected project/source. Store submission is separate. Simulator builds are not TestFlight artifacts; signed iOS builds require owner credentials. Electron/extension packaging and store distribution use their actual platform workflows.
149
+
150
+ **Ready for live acceptance:** the actual URL or artifact, exact source and provider identity are confirmed.
151
+
152
+ ## 7. Verify and hand over
153
+
154
+ Open the actual deployed URL or install the confirmed artifact. Exercise the original acceptance criteria with real intended users and integrations. For private hosting, check anonymous rejection at primary and deployment URLs, allowed-user sign-in and denied users. Verify product authorization and cross-tenant access separately. Provider-authenticated automation does not prove visitor login.
155
+
156
+ Implement a meaningful root `test:live` script and run:
157
+
158
+ ```sh
159
+ anhedral verify --json
160
+ ```
161
+
162
+ `verify` supplies the actual `ANHEDRAL_APP_URL` and checks source/provider provenance. Use the test to exercise the product's meaningful live assertions; a placeholder success script proves nothing. If access or an integration is blocked, retain the completed work and identify the exact unverified flow.
163
+
164
+ Keep the application's verification record current:
165
+
166
+ | Record | Include |
167
+ | ------------------ | -------------------------------------------------------------------------------- |
168
+ | Source | Repository, branch, exact commit, CLI/plugin versions |
169
+ | Hosting | Owner account/project, audience, active release, actual URL/artifact |
170
+ | Product evidence | Commands and observed results for each core flow; local/preview/live distinction |
171
+ | Integration status | Configured and exercised services, pending owner setup and acceptance gaps |
172
+ | Operations | Alert owner, usage limits, recovery procedure and next actions |
173
+
174
+ Do not include credentials. Successful delivery includes maintainable source, reproducible verification and a clear operating handoff. A later production change can make earlier acceptance evidence stale.
175
+
176
+ ## 8. Maintain and recover
177
+
178
+ | Need | Command and boundary |
179
+ | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
180
+ | Refresh deployments | `status --refresh --json` checks current provider evidence |
181
+ | Open a management overview | `manage --json`; `--local` explicitly uses historical local evidence |
182
+ | Inspect services on demand | `services list --json`, then supported status/metrics/data commands; reads can expose private data |
183
+ | Recover after cloning | `recover --json` reconstructs independently verified current hosting state, not missing history or credentials |
184
+ | Inspect interrupted integrations | `integrations status --json`; recover only the verified pending operation/resource |
185
+ | Release an interrupted local lock | `recover --lock` only removes a proven dead same-host delivery lock; inspect receipts first |
186
+ | Restore recorded code | `rollback --release <id> --data-compatible` after schema/resource compatibility review |
187
+
188
+ Rollback does not restore data, reverse SQL or cross incompatible Durable Object migration boundaries. Void rollback only restores covered code/triggers; review retained evidence. Restore matching clean source before verifying the result. Back up data and test restoration independently.
189
+
190
+ Keep alerts, dependency updates, quotas, retry/concurrency limits and shutdown controls owned and exercised. Ignored local receipts are not a durable historical backup. Live/foreign/uncertain locks are preserved; a leftover `.anhedral/ship.guard` needs manual ownership inspection. Lock recovery cannot be combined with provider/refresh flags and never replays provider writes.
191
+
192
+ Use `anhedral help <command>` for exact options. See [provider configuration](provider-configuration.md) for integration setup/retries and [CLI behavior](https://github.com/anhedral/anhedral-cli/blob/main/docs/cli-design.md) for machine output and previews. The optional [Codex inspector](plugin-ui.md) uses the same project logic; it does not replace runtime or product acceptance.
@@ -1,175 +1,142 @@
1
- # Supported application stack
1
+ # Stack standard
2
2
 
3
- 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.
3
+ This is the architecture standard for applications generated by Anhedral. Use it to select components and decide where code belongs. Follow the [software factory](software-factory.md) to implement and deliver the product.
4
4
 
5
- ## Bundled options
5
+ The default web foundation is Vinext, React, TypeScript, Tailwind, shadcn/ui and Lucide on Cloudflare Workers. Every project uses pnpm workspaces and Turborepo. Add components for a concrete product requirement; the default does not include a database, identity provider or every available service.
6
6
 
7
- | Layer | Supported options | Generated foundation |
8
- | --- | --- | --- |
9
- | Workspace | pnpm/Turborepo, TypeScript, ESLint, shared UI | Official pinned shadcn monorepo bootstrap, workspace configuration and checks |
10
- | 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 |
11
- | API | Hono | OpenAPI Worker application with selected service bindings |
12
- | Cloudflare delivery | Void; explicit Wrangler profiles | Void provisions and publishes; Anhedral composes, controls audience policy and independently verifies |
13
- | Mobile | Expo | React Native Reusables and NativeWind; native builds require platform toolchains |
14
- | Desktop | Electron | React application; packaging, signing and distribution require platform-specific setup |
15
- | Browser extension | WXT | React popup and Chrome side panel; installation and store distribution are separate steps |
16
- | Data | D1, Neon, local data | Drizzle schemas for D1/Neon; direct Neon serverless HTTP; device-local data foundations |
17
- | Live Postgres queries | Neon Realtime (`--neon-realtime`) | Optional server/client factories and Drizzle adapter; branch setup and authorized query flows remain application work |
18
- | Identity | Better Auth, Clerk | Server/client configuration and selected schema or provider middleware |
19
- | Worker services | R2, KV, realtime, Queues, cron, Workflows | Private storage bindings, cache/config bindings, Durable Object WebSocket rooms and job/schedule foundations |
20
- | AI | Workers AI, OpenAI, AI SDK | Server-side inference bindings or SDK factories |
21
- | Email | Resend | Server-side transactional email client |
22
- | Payments | Stripe, RevenueCat | Payment/entitlement integration foundations |
23
- | Monitoring and analytics | Sentry, PostHog, Basin | Runtime SDK factories or analytical ingestion configuration |
24
- | Shared styling | Styling | Tokens and presets for compatible native and extension clients |
7
+ ## Select the applications
25
8
 
26
- Every generated project uses pnpm workspaces (`apps/*` and `packages/*`), one root `pnpm-lock.yaml`, and a registry-pinned Turborepo version. Root commands run the shared task graph; adding a second interface does not introduce a separate installer or lockfile. Application/service entry points live in `apps`, reusable implementation in `packages`. Extract shared code around actual consumers rather than moving every helper into a package.
9
+ | Need | Selection | Architecture |
10
+ | ------------------------------ | ----------------------------- | ---------------------------------------------------------- |
11
+ | Web on Workers | Default, or `--vinext` | Vinext routing and rendering, React UI, Cloudflare runtime |
12
+ | Native Next.js on Vercel | `--next` | Next.js server code and Vercel hosting |
13
+ | Next.js on Workers | `--next --hosting=cloudflare` | OpenNext adapter and Wrangler delivery |
14
+ | API shared by multiple clients | `--hono` | Hono Worker with OpenAPI contracts |
15
+ | iOS and Android | `--expo` | Expo, React Native Reusables and NativeWind |
16
+ | Desktop | `--electron` | Electron and React; platform packaging and signing |
17
+ | Browser extension | `--wxt` | WXT and React popup/Chrome side panel |
27
18
 
28
- Database-backed selections create the server-only `@workspace/db` package:
19
+ For example, `--vinext --hono --expo --neon` selects web, an API, mobile and PostgreSQL. `--expo` alone selects mobile. Explicit product flags replace the default selection; required dependencies are resolved automatically. Vinext and Next.js are alternatives. Native Next.js defaults to Vercel; Vinext uses Workers.
29
20
 
30
- | Path | Responsibility |
31
- | --- | --- |
32
- | `packages/db/src/index.ts` | Database factory; the server supplies a connection string or D1 binding |
33
- | `packages/db/src/schema.ts` | Shared Drizzle schema, including selected auth tables |
34
- | `packages/db/src/migrate.ts` | Explicit migration entry point, separate from runtime exports |
35
- | `packages/db/drizzle/` | Generated SQL, snapshots and migration journal |
36
- | `packages/db/drizzle.config.ts` | Paths resolved relative to the configuration file, not the caller's working directory |
21
+ Use server routes inside the web app when it is the only consumer. Add Hono when mobile, desktop, extensions or independent clients need a shared API. Browser and device clients access server endpoints; they never import database factories or receive server credentials. Check actual Vinext behavior in its Worker runtime rather than assuming native Next.js parity.
37
22
 
38
- Only server consumers depend on `@workspace/db`; browser, mobile and extension interfaces use API contracts and endpoints. Reusable auth and other selected integrations remain independent packages. Each server is responsible for authentication, resource authorization and its environment. The database factory never loads environment files or migrates during application startup.
23
+ ## Select data, identity and services
39
24
 
40
- Run `pnpm db:generate` to generate SQL and review it before `pnpm db:migrate`. Both tasks disable Turbo caching and are excluded from build/check dependencies. D1 defaults to local migration; `pnpm db:migrate -- --remote` explicitly targets the configured database in the selected server Worker's `anhedral.cloudflare.json` (or `wrangler.jsonc` for Wrangler profiles). The Worker migration directory points to `packages/db/drizzle`. A single database migration owner coordinates all consumers.
25
+ | Need | Selection | Rule |
26
+ | ------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------ |
27
+ | SQL on Workers | `--d1` | Drizzle with D1 bindings; one deployment migration owner |
28
+ | PostgreSQL | `--neon` | Drizzle with Neon serverless HTTP; separate transactional migration connection |
29
+ | Application identity | `--better-auth` or `--clerk` | Choose one; implement product/resource authorization on the server |
30
+ | Private files | `--r2` | Authorize operations through server bindings |
31
+ | Cache and configuration | `--kv` | Eventually consistent; do not use as transactional authority |
32
+ | WebSocket rooms | `--realtime` | Cloudflare Durable Objects; define identity and reconnect behavior |
33
+ | Live SQL results | `--neon-realtime` | Neon sealed-query server/client factories; see below |
34
+ | Background work | `--queues`, `--cron`, `--workflows` | Define idempotency, retry limits, concurrency and failure recovery |
35
+ | Inference | `--workers-ai`, `--openai`, `--ai-sdk` | Server-side calls with explicit model, cost and usage limits |
36
+ | Transactional email | `--resend` | Verified sending domain, templates and delivery handling |
37
+ | Billing | `--stripe`, `--revenuecat` | Application-specific products, entitlements and verified webhooks/purchases |
38
+ | Errors and analytics | `--sentry`, `--posthog`, `--basin` | Initialize SDKs/events and define privacy and operating ownership |
39
+ | Device-local data and shared styling | `--local-data`, `--styling` | Select for supported client requirements |
41
40
 
42
- Neon runtime queries keep the HTTP adapter and server-supplied `DATABASE_URL`. Migrations use a transactional WebSocket connection and a direct `DATABASE_URL_UNPOOLED`, supplied through the environment or `packages/db/.env.local`/`.env`. Generation does not require credentials; migration does. Test against the intended development branch before applying production changes. Provisioning runtime credentials does not automatically supply migration credentials.
41
+ D1 is the standard choice when Worker-local SQL fits. Choose Neon when the application needs PostgreSQL semantics. Better Auth supplies application-controlled identity; Clerk supplies hosted identity. Hosting audience protection is a separate access layer from either choice.
43
42
 
44
- 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.
45
-
46
- Inspect exact current requirements before generation:
43
+ The bundled registry is authoritative for exact dependencies, destinations and compatibility:
47
44
 
48
45
  ```sh
49
46
  anhedral registry list --json
50
47
  anhedral registry view better-auth --json
51
- anhedral init my-app --hono --d1 --better-auth --r2 --dry-run --json
52
- ```
53
-
54
- The default selects only Vinext on Cloudflare Workers, delivered through Void, plus the shared workspace and UI foundation. 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.
55
-
56
- ## Neon Realtime
57
-
58
- Select `--neon-realtime` when the product needs live Postgres query results. It adds Neon when no database was selected and requires a server runtime; an explicit conflicting database is rejected. `--realtime` continues to mean Cloudflare Durable Object WebSocket rooms, which can be selected independently.
59
-
60
- The recipe creates `packages/neon-realtime` with separate `@workspace/neon-realtime/server` and `/client` exports. The server factory receives private `NEON_REALTIME_SECRET` and `DATABASE_URL` and uses the Drizzle adapter; the client factory receives the public `NEON_REALTIME_URL`. Keep database credentials and sealing code out of browser/native bundles. Follow the generated package README for usage and framework-specific public environment mapping.
61
-
62
- Manually enable Realtime on the intended Neon branch, allow the exact client origins and configure its secret and URL. The CLI does not automate Realtime provisioning. Authenticate each sealing request, derive user/tenant scope from verified identity and construct bounded, read-only queries on the server. No arbitrary SQL endpoint or complete subscription flow is generated. Clients subscribe with short-lived sealed queries; implement authorized renewal and test denied users and membership changes.
63
-
64
- [Neon Realtime](https://neon.com/docs/realtime/overview) is beta and currently has no RLS support. Application authorization must be expressed in the scoped queries you seal. See [query authorization](https://neon.com/docs/realtime/guides/queries#authorization) and [branch setup](https://neon.com/docs/realtime/quickstart). Local recipe checks do not establish live subscription, renewal or cross-tenant acceptance.
65
-
66
- ## Source layout and composition
67
-
68
- 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. The `setup` section of `anhedral.json` records setup requirements; its `registry` section records recipe versions, generated-file fingerprints and workspace references.
69
-
70
- The root `anhedral.json` is the single committed Anhedral configuration document. Its envelope has `schemaVersion: 1`; each named section retains its own domain schema version and validation. The CLI updates only the section it owns and preserves the other sections.
71
-
72
- | Section | Purpose |
73
- | --- | --- |
74
- | `identity` | Stable local application ID used by the project catalog |
75
- | `setup` | Selected products, hosting, environment requirements and owner setup |
76
- | `standard` | Scaffold conventions and version provenance |
77
- | `registry` | Recipe versions, generated-file fingerprints and workspace references |
78
- | `providers` | Nonsecret integration settings and selected provider resources |
79
- | `cloudflare` | Cloudflare delivery engine, account, audience and targets |
80
- | `vercel` | Vercel repository, project, team and audience |
81
-
82
- Only selected hosting sections are present. Keep credentials and delivery history in ignored runtime files and `.anhedral/`; they do not belong in `anhedral.json`. Per-app `anhedral.cloudflare.json`, `void.config.ts`, `void.lock.json` and native tool configuration remain with their owning applications.
83
-
84
- 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.
85
-
86
- 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. Additions require current registry receipts and preserve the selected runtime layout.
87
-
88
- ```sh
89
- anhedral --cwd my-app add resend stripe --dry-run --json
90
- anhedral --cwd my-app add resend stripe
91
- anhedral doctor my-app --json
48
+ anhedral init my-app --vinext --hono --d1 --better-auth --r2 --dry-run --json
92
49
  ```
93
50
 
94
- 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.
95
-
96
- ## Provider access and delivery
97
-
98
- ### Default Cloudflare delivery: Void
51
+ The resolver rejects conflicting databases/frameworks/identity providers and capabilities without a compatible server. There is no `--all` or external registry support. Recipes create integration foundations; provider resources, credentials and finished features have their own setup and acceptance requirements.
99
52
 
100
- Void is the default Cloudflare delivery engine for new supported projects. Adopting its deployment tooling is separate from adopting its application framework. Preserve Vinext routing/rendering, Hono where a shared API is needed, pnpm/Turborepo, reusable packages, Better Auth and the selected database adapter. Deploy directly to the customer's Cloudflare account.
53
+ ## Organize the source
101
54
 
102
- | Anhedral owns | Void owns |
103
- | --- | --- |
104
- | Stack selection, registry composition and multi-interface architecture | Supported Cloudflare builds and deployment mechanics |
105
- | Customer account selection, authored resource declarations and shared-package contracts | Resource provisioning and resolved resource identities |
106
- | Schema generation, SQL review and designation of one migration owner | Applying the designated reviewed deployment migrations |
107
- | Audience requirements, hosting-policy orchestration and application authorization | Supported readiness and operational deployment primitives |
108
- | Source provenance, independent provider checks and end-to-end product acceptance | Worker publication, deployment diagnostics and supported code rollback |
55
+ | Location | Owns |
56
+ | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
57
+ | `apps/web`, `apps/api`, other selected `apps/*` | Deployable applications and services, runtime entry points and configuration |
58
+ | `packages/ui` | Shared web UI components |
59
+ | `packages/db` | Server-only database factory, schemas and migrations |
60
+ | `packages/auth`, other selected `packages/*` | Reusable integration code with explicit inputs |
61
+ | `packages/typescript-config`, `packages/eslint-config` | Shared tooling conventions |
62
+ | `anhedral.json` | Committed Anhedral configuration and provenance |
63
+ | `docs/stack.md` | Generated selection, destinations and setup requirements |
64
+ | `.anhedral/` | Ignored local delivery journals and private state |
109
65
 
110
- **Versions and configuration.** Pin `void@0.27.0` in each deployable app and require Node.js `>=24.21.0`. The adapter checks both the dependency pin and installed executable before execution. Record the delivery engine in the `cloudflare` section of `anhedral.json`. Each app keeps canonical declarations in `anhedral.cloudflare.json`, with `void.config.ts`, `env.ts` and `env.example`. Void generates its Cloudflare configuration and records resource identities in `void.lock.json`; generated defaults must not redefine authored capabilities or migration ownership.
66
+ Use one root `pnpm-lock.yaml` and the root task graph. Keep framework-specific lint dependencies in the consuming app; shared lint configuration stays usable by non-web clients. Shared packages receive bindings, connections and configuration through factories. Extract code around actual consumers, and keep runtime/network relationships explicit.
111
67
 
112
- **One engine per Cloudflare workspace.** Explicit Next.js/OpenNext on Cloudflare, Queues with dead-letter recovery and Basin selections use Wrangler. Other supported Cloudflare selections use Void. Additive composition refuses choices that require switching the workspace engine. Native Next.js on Vercel uses its independent delivery path. Each Cloudflare target uses its own committed configuration; named Wrangler environments are unsupported by Void delivery.
68
+ See the [full-stack example](https://github.com/anhedral/anhedral-cli/tree/main/examples/full-stack) for a source-only composition. It demonstrates the structure; it is not a running production system.
113
69
 
114
- **Explicit resources and one writer.** Registry composition determines each server's capabilities. Shared packages receive bindings or connections through factories. Resource inference assists development; it does not establish transitive package discovery or capability isolation. Compare resolved/generated bindings against the selected capabilities, including auth- and migration-driven requirements. Anhedral `provision` reports the Void resource plan and defers creation to Void deployment. Deploy targets serially and serialize initial provisioning; never run a parallel Anhedral resource creator. Preserve existing D1/private R2 identities and independently inspect provider state after resolution.
70
+ ### One Anhedral configuration
115
71
 
116
- **One migration owner.** Keep authoritative schemas, SQL, snapshots and journals in `packages/db`. Determine ownership from canonical authored configuration, not a resolved lock: Void may add conventional migration directories to database consumers. Exactly one server applies shared D1 migrations; other servers consume the binding without acquiring ownership. The deployment adapter prepares an ignored, ownership-checked, byte-identical app-local validation copy for Void 0.27.0; it refuses edited or unowned copies. The configured apply directory remains `packages/db/drizzle`, and the copy never becomes another source of migrations. Keep custom Drizzle generation and SQL review because Void does not automatically detect drift in `packages/db/src/schema.ts`. Preserve Neon's HTTP runtime adapter and separate transactional migration connection; adopting Void does not select Hyperdrive or `void/db`.
72
+ The root `anhedral.json` has an envelope with `schemaVersion: 1` and validated named sections. Each section retains its own domain schema. Only selected hosting sections are present.
117
73
 
118
- **Credentials and environments.** Provider authentication is separate from account selection, write permissions, Zero Trust setup and visitor identity. The adapter uses an explicitly supplied `CLOUDFLARE_API_TOKEN`, or retrieves structured Wrangler credentials and passes them only through the Void child process's environment. Credential values never become command arguments, source or deployment evidence. Wrangler login alone does not establish Access permissions. Establish private hosting protection before product publication.
74
+ | Section | Purpose |
75
+ | ------------ | --------------------------------------------------------------------- |
76
+ | `identity` | Stable application identity and local catalog registration |
77
+ | `setup` | Products, hosting, environment requirements and owner setup |
78
+ | `standard` | Scaffold conventions and version provenance |
79
+ | `registry` | Recipe versions, generated-file fingerprints and workspace references |
80
+ | `providers` | Nonsecret integration settings and resource selections |
81
+ | `cloudflare` | Delivery engine, account, audience and targets |
82
+ | `vercel` | Repository, team, project and audience |
119
83
 
120
- Void reads one `.env` at each deployable app's project root and declares variables in `env.ts`. Use `env.example`; do not introduce unsupported `.env.*` companions or `.dev.vars` into that app. Production server secrets use noninteractive stdin; bulk sync is avoided because the pinned command prompts even in CI. Reject empty values, NUL bytes and terminal newlines rather than silently changing secret bytes. Exclude public `VITE_*`, `NEXT_PUBLIC_*` and `EXPO_PUBLIC_*` values from server-secret uploads. Vite clients expose `VITE_*` values at build time. The pinned Vinext plugin loads the app `.env` for local builds and maps `NEXT_PUBLIC_*` values into client bundles. Supply the selected public values in the production build environment; runtime server-secret uploads do not configure client bundles. Keep Neon migration credentials separate from runtime secrets.
84
+ Preserve unrelated sections when editing. Credentials and delivery history stay outside this document. Native tooling files remain with their applications: a single Anhedral document does not replace `package.json`, Vite configuration or per-app deployment configuration.
121
85
 
122
- **Activation, locks and verification.** Distinguish provisioned, uploaded, activated, ready and product-verified states. A failed command can leave resources or an active Worker. Initial activation may change only the allowed target `void.lock.json` files. Retain independently confirmed receipts and return `configuration-required`, with `activated: true` and `deployed: false`; review and commit the identities, then ship a clean committed release before product verification. Only recorded lock changes may carry across later targets; unrelated source edits still stop delivery. Commit locks before another checkout or CI deploys.
86
+ ## Data and migrations
123
87
 
124
- Require the pinned machine-readable JSONL deployment contract and independently correlate its Worker/version with 100% of active Cloudflare traffic and actual provider URLs. Console prose and a successful exit status are insufficient evidence. Correlate the checked invocation with exact source state before and after deployment; do not claim a provider-signed Git provenance guarantee. Check private-resource and audience policies around activation. Multiple Workers are not an atomic release. Readiness does not replace the application's meaningful live acceptance test.
88
+ All database-backed selections use the server-only `@workspace/db` package:
125
89
 
126
- Rollback delegates to Void and independently checks active versions. It restores code and only triggers covered by retained snapshots; it does not reverse SQL or cross incompatible Durable Object migration boundaries. Fresh-checkout recovery verifies current provider state, flags unsupported binding evidence and cannot reconstruct missing historical source-to-release mappings or product-verification results.
90
+ | Path | Responsibility |
91
+ | ------------------------------- | ----------------------------------------------------- |
92
+ | `packages/db/src/index.ts` | Factory receiving a D1 binding or connection string |
93
+ | `packages/db/src/schema.ts` | Shared Drizzle schema, including selected auth tables |
94
+ | `packages/db/src/migrate.ts` | Explicit migration entry point |
95
+ | `packages/db/drizzle/` | SQL, snapshots and migration journal |
96
+ | `packages/db/drizzle.config.ts` | Configuration with paths relative to itself |
127
97
 
128
- **Separate framework and platform decisions.** Native Void Pages, managed auth, typed WebSockets, Durable State, inbound-email handlers, the self-hosted Void Platform and connected-builder artifact publishing require separate recipes and acceptance. Deploying Vinext through Void does not make native-framework-only features available. Keep the self-hosted platform optional: its control plane, credentials, quotas and recovery are a separate operational commitment. Use the exact installed package's bundled Markdown documentation when assessing these paths.
98
+ The factory does not load environment files or migrate on startup. Review generated SQL from `pnpm db:generate` before running `pnpm db:migrate`. Both tasks are uncached and excluded from builds and checks. Exactly one server owns deployment migrations; other consumers share the database without becoming migration writers.
129
99
 
130
- **Acceptance status.** Actual generated Vinext/Hono builds, local workerd routing/assets/readiness, shared Better Auth/D1 flows and the read-only Wrangler-to-Void credential bridge have been exercised. Unit coverage checks ownership, secret transport, lock checkpoints and evidence rejection paths. These results do not establish complete remote compatibility. The current validation account still requires Zero Trust onboarding and usable Access authorization. Private first deployment, fresh-checkout resource reuse, full live user flows, failure recovery and remote rollback remain acceptance gates. Do not switch to public hosting to bypass private acceptance. Record results and reproducible checks in [Void verification](void-verification.md).
100
+ D1 manual migration defaults to local. `pnpm db:migrate -- --remote` explicitly targets the configured database in the migration owner's Worker configuration. Void deployment validates an ignored, byte-identical app-local copy against the authoritative shared SQL; the copy is not another migration source.
131
101
 
132
- Upstream contracts: [Cloudflare deployment](https://void.cloud/integrations/cloudflare), [configuration](https://void.cloud/reference/config), [deployment CLI](https://void.cloud/reference/cli/deploy), and [package requirements](https://www.npmjs.com/package/void).
102
+ Neon runtime queries use server-supplied `DATABASE_URL` through the HTTP adapter. Interactive transactions require a reviewed WebSocket or PostgreSQL adapter. Migrations use a transactional WebSocket connection and direct `DATABASE_URL_UNPOOLED` from the environment or `packages/db/.env.local`/`.env`. Test migrations on the intended development branch before production. Runtime provisioning does not supply migration credentials automatically.
133
103
 
134
- `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.
135
-
136
- `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.
104
+ ## Neon Realtime
137
105
 
138
- The CLI provides the foundation and delivery workflow. Product features, design, custom integrations and maintenance remain development work; Anhedral offers these services to businesses.
106
+ `--neon-realtime` selects live PostgreSQL query foundations and adds Neon if no database was chosen. It requires a server and rejects an explicit conflicting database. It can coexist with `--realtime`, which means Durable Object WebSocket rooms.
139
107
 
140
- ## Application requirements
108
+ The recipe creates `@workspace/neon-realtime/server` and `/client` exports in `packages/neon-realtime`. The server receives private `NEON_REALTIME_SECRET` and `DATABASE_URL`; the client receives public `NEON_REALTIME_URL`. Follow the generated package README for framework-specific public environment mapping.
141
109
 
142
- - Keep server credentials out of client bundles and version control. Configure separate environments and review database migrations.
143
- - Select one database and one identity provider. Implement resource and tenant authorization in the application; hosting access protection does not replace product identity.
144
- - Keep R2 private and authorize file operations. KV is eventually consistent and should not hold authoritative transactional state.
145
- - Implement webhooks and jobs idempotently. Bound retries, concurrency and paid usage; verify recovery and data compatibility before rollback.
146
- - 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.
147
- - Run generated checks and exercise product flows. Initialization, installed SDKs and successful builds do not prove provider configuration or production acceptance.
110
+ Enable Realtime on the intended Neon branch and configure exact allowed origins, secret and endpoint manually. Authenticate sealing requests, derive user/tenant scope from verified identity, and construct bounded read-only queries on the server. Clients subscribe with short-lived sealed queries; implement authorized renewal, reconnect behavior and isolation tests. No arbitrary SQL endpoint or complete subscription feature is generated.
148
111
 
149
- Follow the [delivery workflow](delivery-workflow.md) for the supported customer-account deployment, verification and recovery commands.
112
+ The pinned integration targets the [Neon Realtime beta](https://neon.com/docs/realtime/overview), whose reviewed authorization model has no RLS support. Scope the queries you seal and review the provider's current limits before production use. Recipe tests do not establish live subscription or cross-tenant acceptance.
150
113
 
151
- ## Maintenance and verification
114
+ ## Runtime and delivery configuration
152
115
 
153
- 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.
116
+ | Profile | Engine and configuration | Project runtime floor |
117
+ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
118
+ | Supported Cloudflare selections | Void `0.27.0`; app-local `anhedral.cloudflare.json`, `void.config.ts`, `env.ts`, `env.example`, committed `void.lock.json` | Node.js `24.21.0+` |
119
+ | Explicit OpenNext, Queues/DLQ or Basin | Wrangler; app-local `wrangler.jsonc` | Node.js `22.13+` on 22.x, or `24+` |
120
+ | Native Next.js/Vercel and other non-Void profiles | Native framework/platform tools | Node.js `22.13+` on 22.x, or `24+` |
154
121
 
155
- When installing a capability addition, Anhedral regenerates the root `node_modules` cache from the resolved frozen lockfile while retaining the separate package store. This prevents pnpm 10 from retaining skipped optional dependencies after they become required. Customer source and patch files remain outside that cache; a frozen installation that changes the planned lockfile fails. `--skip-install` leaves dependency installation to the owner.
122
+ Use pnpm `10.34.5`. The CLI's own supported Node range is broader than the generated toolchains' requirements. For a new development environment, Node.js `24.21.0+` satisfies these documented floors.
156
123
 
157
- Framework-specific lint dependencies belong to the consuming application. The shared `packages/eslint-config` retains generic TypeScript, React, Hooks and Turbo rules; web applications declare their own Next API lint plugin and configuration. API and native-only workspaces must not inherit Next-specific tooling solely because the bootstrap started from a Next template.
124
+ There is one Cloudflare engine per workspace. `add` refuses selections that would switch the engine or relocate existing runtime source. Anhedral owns composition, account/audience selection, shared packages and independent verification; Void owns its supported provisioning, deployment and code rollback mechanics. Native Void framework features are not implied by deploying Vinext through Void.
158
125
 
159
- Security overrides retain reviewed compatible `brace-expansion` 1.x, 2.x and 5.x releases. There is no blanket 3.x pin: [GHSA-3jxr-9vmj-r5cp](https://github.com/advisories/GHSA-3jxr-9vmj-r5cp) lists no repaired 3.x release, and the reviewed generated lockfiles do not consume that major. A future consumer on an affected line must be resolved through its compatible upstream dependency path; it receives no audit exception or additional local patch.
126
+ Void apps read one private app-root `.env`, copied from `env.example`. Avoid `.env.*` companions and `.dev.vars` in those apps. Wrangler and native Vercel use their generated runtime templates. Keep production secrets server-side; public `VITE_*`, `NEXT_PUBLIC_*` and `EXPO_PUBLIC_*` values are build inputs, not server secrets. Vinext maps `NEXT_PUBLIC_*` into client bundles. The [provider reference](provider-configuration.md) describes credential transport and each integration's prerequisites.
160
127
 
161
- Generated `pnpm audit:deps` runs the standard pnpm audit through a narrow patch policy and preserves its unmodified JSON in `.anhedral-audit-report.json`. High and critical findings fail except for the two reviewed, exact-version mitigations below. The gate permits `GHSA-vfj7-8cjw-p6xm` for configured reviewed `braces@3.0.3` and `GHSA-86w9-cpqp-85rv` for configured reviewed `node-forge@1.4.0`; it preserves both upstream findings and blocks unrelated advisories. Review the resolved lockfile for each generated profile: a clean CLI lockfile or direct-version catalog audit does not establish that a generated application’s transitive dependencies are clean. Removing an unused dependency path does not resolve other paths to the same vulnerable package.
128
+ ## Source ownership and dependency policy
162
129
 
163
- ### Temporary braces mitigation
130
+ Generated source belongs to the application and remains editable. Preview bundled additions with `add --dry-run`, `--diff` or `--view`; additions preserve edited/untracked source and record provenance. They require current registry receipts. When `filesChecked: false`, the selection plan is available but a new upstream web bootstrap cannot be previewed offline. Actual installation checks conflicts before committing files.
164
131
 
165
- When the resolved graph contains `braces@3.0.3`, new generation and actual additions copy the bundled `assets/patches/braces@3.0.3.patch` into `patches/`, merge an exact `patchedDependencies` mapping into `pnpm-workspace.yaml`, and resolve the lock again before frozen installation. Existing customer patch maps and files are preserved; conflicts require deliberate maintenance. Other versions do not receive this patch. Commit both the patch and updated workspace/lock files.
132
+ The catalog in `src/stack-registry.ts` defines composition, `src/dependencies.ts` pins dependencies, and `src/scaffold/` implements recipes. Generated plugin references come from these maintained sources and documents.
166
133
 
167
- This is a local mitigation for [CVE-2026-93687](https://github.com/advisories/GHSA-vfj7-8cjw-p6xm): nested brace/parenthesis parsing and direct AST traversal are limited to depth 100, and cyclic child/expansion-parent paths are rejected. It does not add expansion-width/range limits or replace the upstream glob API. The policy retains the affected upstream advisory and permits it only with the exact reviewed patch checksum and effective pnpm patch mapping. Frozen pnpm installation owns patch application and lockfile consistency. Depth/cycle runtime regressions run in this repository’s tests, rather than in generated applications. Outside the two reviewed exact-version mitigations, high and critical advisories remain blocking.
134
+ Commit the resolved lockfile and any generated `patches/*` plus `pnpm-workspace.yaml` patch mappings. Conditional reviewed patches apply only to `braces@3.0.3` and `node-forge@1.4.0`. `pnpm audit:deps` retains raw upstream findings in `.anhedral-audit-report.json` and blocks high/critical advisories except the exact reviewed advisory/version/patch combinations (`GHSA-vfj7-8cjw-p6xm` and `GHSA-86w9-cpqp-85rv`). Frozen pnpm installation applies patches; detailed runtime regressions belong to this repository's `pnpm test:patch`. These temporary mitigations must be reviewed each release and retired when a compatible verified fix replaces them. Compatible brace-expansion overrides do not create an exception for an affected 3.x consumer.
168
135
 
169
- Review the mitigation on every release. Remove it when a verified supported upstream fix or compatible consumer migration makes it unnecessary; test existing application patterns before changing the limit. `pnpm test:patch` exercises real frozen installations, runtime regressions, normal glob/watch behavior and changed-patch rejection. Focused unit tests cover exact-advisory handling. The upstream MIT notice is distributed alongside the patch.
136
+ Validate the resolved dependency graph for each application selection. A clean CLI dependency graph does not establish a clean generated application graph.
170
137
 
171
- ### Temporary node-forge mitigation
138
+ ## Product requirements
172
139
 
173
- The same conditional staging and conflict checks apply to `node-forge@1.4.0`. Its patch rejects extra nested DigestAlgorithm elements and nonempty DER NULL parameters in RSA PKCS#1 v1.5 verification, covering `lib/rsa.js` and both shipped minified browser bundles. It preserves the published APIs and includes the upstream BSD license notice.
140
+ A completed application has server-side resource authorization, private file access, reviewed migrations, meaningful error/loading/empty states and tests for its actual user flows. Jobs and webhooks must tolerate duplicates; paid operations need limits and ownership. Verify the selected runtime and any native packaging, permissions and signing.
174
141
 
175
- The policy permits the exact advisory only with the reviewed patch checksum and effective pnpm patch mapping. Repository installation tests exercise valid and malformed signatures through all three entrypoints with pure JavaScript RSA verification. Generated audits do not scan installed dependency trees or execute dependency runtime probes. The upstream advisory still has no official patched release; this is a tested local mitigation and must be retired when a compatible verified upstream fix becomes available. Commit the generated patch, attributes, workspace policy and resolved lockfile.
142
+ Use the [software factory](software-factory.md) for the implementation and acceptance process. Detailed delivery evidence and outstanding live acceptance gaps belong in the [Void verification reference](void-verification.md) and the application's own verification record, rather than in this architecture standard.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "anhedral",
3
- "version": "0.11.1",
3
+ "version": "0.11.2",
4
4
  "description": "Build and deliver applications with Cloudflare-first Vinext, selected services, optional Next.js on Vercel, and verified release evidence.",
5
5
  "type": "module",
6
6
  "exports": {
@@ -24,7 +24,7 @@
24
24
  "LICENSE",
25
25
  "README.md",
26
26
  "docs/stack-standard.md",
27
- "docs/delivery-workflow.md",
27
+ "docs/software-factory.md",
28
28
  "docs/void-verification.md",
29
29
  "docs/provider-configuration.md",
30
30
  "docs/cli-design.md",
@@ -1,98 +0,0 @@
1
- # Build and deliver an application
2
-
3
- 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.
4
-
5
- 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.
6
-
7
- ## Plan and implement
8
-
9
- 1. Choose only needed components from the [stack standard](https://github.com/anhedral/anhedral-cli/blob/main/docs/stack-standard.md). Record decisions, ownership, environment/cost assumptions and actual connections in the application's `docs/architecture.md`.
10
- 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`.
11
- 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 `anhedral --cwd <directory> add <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. Additions require current registry receipts and preserve the selected runtime layout. `doctor --providers --json` checks access without configuring infrastructure or certifying production.
12
- 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.
13
-
14
- ## Provider authentication
15
-
16
- 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.
17
-
18
- ## Source and release authority
19
-
20
- Complete the selected integrations' nonsecret account/resource choices in the `providers` section of `anhedral.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.
21
-
22
- Use customer-owned accounts and a reviewed clean commit. Default to a private repository in the selected account; organizations require selection.
23
-
24
- ```sh
25
- anhedral repository my-app --create --json
26
- ```
27
-
28
- This verifies the app's Git root, owner, visibility, write access and exact remote commit. Reuse matching origins without `--create`; do not replace remotes, change visibility or force-push. Connected repository identity is retained and rechecked.
29
-
30
- Choose one release path per change: checked `ship`, or checks followed by an authorized Git push, active production confirmation and `adopt`. Git integration can deploy independently of CLI checks; configure required CI/branch/deployment policy explicitly. Do not routinely deploy the same commit twice.
31
-
32
- ## Cloudflare delivery
33
-
34
- 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 delivery reads the `cloudflare` section of `anhedral.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. Supported Cloudflare selections use Void, while explicit OpenNext, queue/DLQ and Basin selections use Wrangler.
35
-
36
- ```sh
37
- anhedral connect my-app --audience private --allow-email owner@example.com
38
- anhedral provision my-app --dry-run --json
39
- anhedral ship my-app --dry-run --json
40
- anhedral ship my-app --json
41
- ```
42
-
43
- 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.
44
-
45
- For Void projects, `provision` reports the resource plan and defers writes to Void deployment. It never runs Anhedral's resource creator in parallel. The migration owner prepares an ignored, byte-identical validation copy from `packages/db/drizzle`; Void validates its apply set against the shared SQL. Other consumers receive no migration copy. Generate and review SQL with the shared Drizzle configuration first; Void does not inspect shared-package schema drift automatically. Void deploys targets serially, records actual IDs in each app's `void.lock.json`, and applies reviewed deployment migrations. The first activation may require reviewing and committing new locks before shipping a clean release; successful target activation is recorded separately from source completion and product verification. Subsequent deployments reuse the committed identities. Wrangler provisioning 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. Void apps use `anhedral.cloudflare.json`, `void.config.ts` and `env.ts`; copy `env.example` to the app's private `.env`. Do not add `.env.local`, `.env.production`, `.env.example` or `.dev.vars` alongside Void's local environment file. Secret commands use noninteractive stdin; public build variables stay in the build environment. Vite clients use `VITE_*`; the pinned Vinext plugin loads the app `.env` for local builds and maps `NEXT_PUBLIC_*` into client bundles. Supply the selected public values during production builds; server-secret uploads do not configure client bundles. 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. Void's pinned structured JSONL receipt is correlated with the active Cloudflare version independently; diagnostic prose is never a success receipt. Missing/ambiguous receipts or provider drift stop acceptance. Multiple Workers are not an atomic release; web deploys last by default. Code rollback delegates to Void for Void projects and does not undo database migrations or incompatible Durable Object class changes.
46
-
47
- See [Void verification and handoff](void-verification.md) for the pinned evidence contract, reproducible checks, live acceptance results and outstanding gates.
48
-
49
- ## Native Next.js/Vercel delivery
50
-
51
- Select `--next`, authenticate the intended customer account and choose an eligible plan. Hobby is personal/non-commercial; commercial use requires an eligible existing plan.
52
-
53
- ```sh
54
- anhedral connect my-app --scope customer-team --audience private --use personal --create --git
55
- pnpm --dir my-app run check
56
- anhedral repository my-app --json
57
- # Wait for the connected production Git deployment.
58
- anhedral adopt my-app --json
59
- anhedral verify my-app --json
60
- ```
61
-
62
- 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.
63
-
64
- ## Mobile build handoff
65
-
66
- 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.
67
-
68
- ## Acceptance and operating limits
69
-
70
- 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.
71
-
72
- Verify anonymous rejection at primary/deployment URLs, permitted-user login, denied-user and cross-tenant behavior. Verify selected private files, realtime reconnect/replay, duplicate jobs/webhooks, bounded AI, purchase/restore/refund, email/push and offline conflicts. Provider-authenticated requests do not prove visitor login or app authorization. Protected automation may use Vercel curl or authorized origin-scoped Trusted Sources; never weaken protection for testing.
73
-
74
- Record service quotas, maximum retries/concurrency/AI work, alert ownership and shutdown controls within the authorized budget. Test spikes, duplicate execution, partial deployment and backup restoration. Review migrations and compatibility before rollback; code rollback does not restore data.
75
-
76
- ## Operations and handoff
77
-
78
- | Command | Boundary |
79
- | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
80
- | `register` | Stable app identity; generated apps register automatically. |
81
- | `status --refresh` | Independently refresh provider state. |
82
- | `manage` / `manage --local` | Provider overview / explicitly historical local view. |
83
- | `adopt` | Verify active Vercel Git source/repository and record its checked release; no push/deploy. |
84
- | `recover` | Reconcile current provider state after cloning; no invented historical tests/releases. |
85
- | `verify` | Run meaningful root `test:live` with actual URL/release and source/provider checks. |
86
- | `rollback --release <id> --data-compatible` | Restore recorded code after compatibility review; no migration reversal/data restore. |
87
-
88
- 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.
89
-
90
- Committed manifests preserve identity. Ignored `.anhedral/` receipts are local history; back them up when needed. Before removing an interrupted shared lock, confirm no active process and inspect provider state. Maintain alerts, dependencies, costs and tested recovery. Recurring monitoring requires an authorized schedule. Release artifacts need exact contents, secret checks and integrity verification; never replace published version bytes.
91
-
92
- ## Evidence and maintenance
93
-
94
- 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.
95
-
96
- ### Interrupted local delivery locks
97
-
98
- 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, 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`.