@samebase/alchemy-convex 0.3.0 → 0.4.0

package/NOTICE

@@ -0,0 +1,24 @@
+@samebase/alchemy-convex
+Copyright 2026 Samebase
+
+This product follows patterns from Confect (https://github.com/rjdellecese/confect),
+packages/alchemy, under the ISC license:
+
+- the adoption check order in src/Adoption.ts (internal/Lifecycle.ts),
+- the Convex CLI runner in src/Push.ts (internal/CommandRunner.ts),
+- the deployment lookup rules in src/Deployment.ts and the project listing in src/Project.ts.
+
+ISC License
+
+Copyright 2024 RJ Dellecese
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without
+fee is hereby granted, provided that the above copyright notice and this permission notice appear
+in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/README.md

@@ -1,20 +1,20 @@
 # @samebase/alchemy-convex
 
-Convex resources for [Alchemy v2](https://alchemy.run): projects, deployments, deploy keys,
-environment variables, project default environment variables, and the code push. One Alchemy stack
-can own a Convex app end to end: it creates the deployment, pushes the functions, and gives the
-deployment URLs to a Cloudflare Worker or a Vite site as ordinary outputs. The Convex CLI that
-your app installs keeps doing typecheck, codegen, bundling, and the push.
+The Convex plane for [Alchemy v2](https://alchemy.run): projects, deployments, their environment
+variables, and the push of the functions. One Alchemy stack owns a Convex app end to end. The
+deployment resource pushes your `convex/` folder when its content changes and gives the deployment
+URLs to a Cloudflare Worker or a Vite site as ordinary outputs. No deploy key goes from one resource
+to another. The Convex CLI that your app installs keeps doing typecheck, codegen, bundling, and the
+push.
 
 Alchemy has no built-in Convex provider ([alchemy-run/alchemy-async#1306](https://github.com/alchemy-run/alchemy-async/issues/1306)).
-This is a community provider, maintained by [Samebase](https://samebase.com).
+This is a community provider, maintained by [Samebase](https://samebase.com). The resource model
+follows the "Convex Plain" mode of [rjdellecese/confect#408](https://github.com/rjdellecese/confect/issues/408).
+[docs/design/convex-plane.md](docs/design/convex-plane.md) records the decisions.
 
-Status: 0.3, pinned to `alchemy@2.0.0-beta.80` and Effect 4. Alchemy ships breaking changes
-between betas; upgrade this package and Alchemy together. The 0.2 deploy step was verified end to
-end on a Vite app with a Cloudflare Worker: production on `main`, a Convex preview deployment plus
-a Worker Preview per pull request, destroy on close. `Convex.Deployment` and `Convex.Code` are
-verified by a live test with the real Convex CLI: a push to a production deployment and to a
-preview deployment, then a delete of the preview.
+Status: pinned to `alchemy@2.0.0-beta.80` and Effect 4. Alchemy ships breaking changes between
+betas; upgrade this package and Alchemy together. A live test runs the full sequence with the real
+Convex CLI: create, push, no-op, change, preview, deploy keys alone, and destroy.
 
 ## Install
 
@@ -22,32 +22,9 @@ preview deployment, then a delete of the preview.
 pnpm add -D @samebase/alchemy-convex alchemy@2.0.0-beta.80 effect@^4.0.0 @effect/platform-node@^4.0.0 convex
 ```
 
-## Credentials
-
-The provider calls the [Convex Management API](https://docs.convex.dev/management-api) with a
-bearer token. By default it reads `CONVEX_ACCESS_TOKEN` through the stack's config provider
-(process env, `.env`, stack secrets) and then falls back to the token the Convex CLI saved after
-`npx convex login` (`~/.convex/config.json`). A developer who is logged in needs no setup. CI sets
-the variable to a team access token.
-
-To pass a token explicitly:
-
-```ts
-Convex.providers(Convex.fromToken(Redacted.make(token)));
-```
-
-A team access token is team wide. The deploy keys this provider creates are scoped to one
-deployment or one project, and those are what CI deploys with.
-
 ## Example
 
 ```ts
-import * as Alchemy from "alchemy";
-import * as Cloudflare from "alchemy/Cloudflare";
-import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
-import * as Convex from "@samebase/alchemy-convex";
-
 export default Alchemy.Stack(
   "MyApp",
   {
@@ -55,251 +32,132 @@ export default Alchemy.Stack(
     state: Cloudflare.state(),
   },
   Effect.gen(function* () {
-    const project = yield* Convex.Project("Project", { team: 38516, name: "score-four" });
-    const prod = yield* Convex.Deployment("Prod", { projectId: project.projectId, type: "prod" });
-    const key = yield* Convex.DeployKey("DeployKey", {
-      deployment: prod.name,
-      name: "alchemy",
-      allowedActions: ["deployment:deploy", "deployment:env:view", "deployment:env:write"],
-    });
-    const backend = yield* Convex.Code("Backend", {
-      deployment: prod,
-      deployKey: key.deployKey,
-      cwd: ".",
-    });
-
-    // backend.url and backend.siteUrl feed a Cloudflare Worker or a Vite site.
+    const { stage } = yield* Alchemy.Stack;
+    const backend =
+      stage === "prod"
+        ? yield* Convex.Deployment("Backend", {
+            // An existing project. A new one: { team: "my-team", name: "my-app" }.
+            project: yield* Convex.Project("Project", { team: "my-team", slug: "my-app" }),
+            type: "prod",
+            source: "./convex",
+            env: { AUTH_SECRET: Config.Redacted("AUTH_SECRET") },
+          })
+        : yield* Convex.Deployment("Backend", {
+            // The project that the stage "prod" owns, read from its state.
+            project: yield* Convex.Project.ref("Project", { stage: "prod" }),
+            type: "preview",
+            name: stage, // such as "pr-42"
+            source: "./convex",
+          }).pipe(RemovalPolicy.destroy());
     const site = yield* Cloudflare.Website.Vite("Site", {
       env: { VITE_CONVEX_URL: backend.url, VITE_CONVEX_SITE_URL: backend.siteUrl },
     });
-
     return { url: site.url, convexUrl: backend.url };
   }),
 );
 ```
 
-Order follows the outputs: the project exists before its deployment, the deployment before its key,
-the key before the push, and the push before the site build. On a Vite Worker, a `VITE_` key in
-`env` goes into the client bundle as `import.meta.env.VITE_*` and is also a Worker variable.
-`Cloudflare.Worker` takes the same `env`.
+The imports are `alchemy`, `alchemy/Cloudflare`, `alchemy/RemovalPolicy`, `effect/Config`,
+`effect/Effect`, `effect/Layer`, and `@samebase/alchemy-convex` as `Convex`. Order follows the
+outputs: the project exists before its deployment, and the push finishes before the site build. The
+first `alchemy deploy --stage prod` takes over the existing project, and its production
+deployment if it has code, only with `--adopt`.
+`alchemy destroy --stage pr-42` deletes the preview deployment. Without `RemovalPolicy.destroy()`,
+it stays until Convex deletes it at expiry (14 days by default).
+[`examples/app/alchemy.run.ts`](examples/app/alchemy.run.ts) is the same stack.
 
-### Preview stages
+## Credentials
 
-On a pull request stage, push to a preview deployment of the same project. Name the preview after
-the stage, and use a preview deploy key of the project:
+Credentials are a layer, never props, so they do not go into Alchemy state. `Convex.providers()`
+reads them through the stack's config provider (process env, `.env`, stack secrets):
+
+- `CONVEX_ACCESS_TOKEN`, a team access token, for the Management API. Without it, the provider uses
+  the token that `npx convex login` saved (`~/.convex/config.json`). `Convex.Project` needs it, and
+  so does a deployment that the deploy key does not reach.
+- `CONVEX_DEPLOY_KEY`, optional, the same variable that the Convex CLI reads:
+  - A deploy key of one deployment (`prod:<name>|...`) sets variables and pushes to that deployment.
+    That stage then needs no access token if it passes `project: { projectId }` or a
+    `Convex.Project.ref`. The key must have `deployment:data:view` (dashboard keys have all
+    actions), because the provider reads the project and type of its deployment first.
+  - A preview deploy key of a project (`preview:<team>:<project>|...`) creates, pushes to, and
+    deletes preview deployments of that project. It cannot change variables: with `env`, the
+    provider uses the access token, and without one it stops with `EnvironmentNeedsDeployKey`
+    before it creates anything. Use project default variables in the Convex dashboard for previews.
+
+A key that does not fit the deployment is not used: the provider uses the access token. To pass
+values explicitly: `Convex.providers(Convex.fromValues({ accessToken, deployKey }))`.
 
-```ts
-const stack = yield * Alchemy.Stack; // stack.stage, such as "pr-42"
-// The project that the stage "prod" owns. A preview stage reads it and does not own it.
-const project = yield * Convex.Project.ref("Project", { stage: "prod" });
-const preview =
-  yield *
-  Convex.Deployment("Preview", {
-    projectId: project.projectId,
-    type: "preview",
-    name: stack.stage,
-  }).pipe(Alchemy.RemovalPolicy.destroy());
-const previewKey =
-  yield *
-  Convex.PreviewDeployKey("PreviewDeployKey", {
-    projectId: project.projectId,
-    name: "alchemy",
-  });
-const backend =
-  yield *
-  Convex.Code("Backend", {
-    deployment: preview,
-    deployKey: previewKey.previewDeployKey,
-    cwd: ".",
-  });
-```
+## Resources
 
-`alchemy destroy --stage pr-42` then deletes the preview deployment. Without
-`RemovalPolicy.destroy()`, the preview deployment stays until Convex deletes it at expiry (14 days
-by default). [`examples/app/alchemy.run.ts`](examples/app/alchemy.run.ts) has both stages in one
-stack. Variables that every preview deployment needs, such as auth keys, go on the project as
-`DefaultEnvironmentVariable` for `preview`.
+- `Convex.Project`: `{ team, name, deploymentRegion?, deploymentType? }` creates a project with its
+  default deployment, or takes over one with that exact name with `--adopt`. A changed `name`
+  renames the project in place. `{ team, slug }` is an existing project, found by its slug and
+  taken over with `--adopt`; it never creates or renames a project. Outputs `projectId`, `slug`,
+  `name`, `teamId`, `prodDeploymentName`, `prodDeploymentUrl`.
+- `Convex.Deployment`: `{ project, type: "prod" }` or `{ project, type: "dev" | "preview", name }`,
+  each with optional `source` and `env`. Outputs `name` (such as `happy-animal-123`), `url`,
+  `siteUrl`, `type`, `projectId`, `reference`, `previewName`, `hash`, and `envNames`.
+  - `prod` is the project's default production deployment (with a deploy key: the key's
+    production deployment). The resource never creates or deletes one. A production deployment
+    with code that is not in state is taken over only with `--adopt`.
+  - `dev` creates a dev deployment with `name` as its reference; `preview` creates a preview
+    deployment with `name` as its preview name. An expired preview is created again on the next
+    deploy.
+  - `source` is the Convex functions directory: `convex/`, or the `functions` field of
+    convex.json (`SourceMismatch`). The CLI runs in the nearest directory above it with a
+    package.json, with the Node.js that runs Alchemy, and is never downloaded (`ConvexCliNotFound`).
+  - The content identity is a hash of every file of that app directory that git does not ignore,
+    the nearest lockfile, the deployment name, and `env`. The same hash is a no-op. Otherwise the
+    update sets `env`, then pushes. A failed push sets the changed variables back, and deletes a
+    dev or preview deployment that the same run created.
+  - `env` values are strings or secrets such as `Config.Redacted("AUTH_SECRET")`. A name that
+    leaves `env` is removed from the deployment.
+  - `source: { path, command?, include? }` replaces `convex deploy` with `command`, run in the app
+    directory with the push key in `CONVEX_DEPLOY_KEY`, such as
+    `["node_modules/.bin/convex-hosting", "deploy", "--build", "node_modules/.bin/vp build", "--dist", "dist/client"]`.
+    The command must push with `convex deploy` (convex-hosting does, through `--cmd`). `include`
+    narrows the hash to `path`, package.json, convex.json, the lockfile, and the listed globs, such
+    as the build inputs `["src/**", "public/**", "vite.config.ts"]`. A minted key for a command
+    has every action, because the command can do more than a push.
 
 ## Data safety
 
-Deleting a Convex project deletes all of its deployments and data. This package does not delete,
-replace, or overwrite your data by accident:
-
-- `Convex.Project` has the removal policy `retain`. When you remove the resource or run
-  `alchemy destroy`, Alchemy forgets the project and Convex keeps it. To delete the project with
-  the resource, add `RemovalPolicy.destroy()`:
-
-  ```ts
-  yield * Convex.Project("Project", { team, name }).pipe(Alchemy.RemovalPolicy.destroy());
-  ```
-
-- A project is never replaced. A change to `name` renames the project in place
-  (`PATCH /projects/{project_id}`). The id, the slug, the deployments, and the data stay.
-- A change to `team`, `deploymentType`, or `deploymentRegion` stops the deploy with
-  `ProjectTeamChange` or `ProjectDeploymentChange`. Convex cannot move a project or change its
-  first deployment. Set the old value again, or create a new resource with a new logical id and
-  move the data yourself.
-- With state, the provider finds the project only by the id in state. Without state, it finds a
-  project by its exact name, on all pages of the team's project list, and takes it over only with
-  `--adopt`. When two projects have that name, the deploy stops with `AmbiguousProject`.
-- Each `DeployKey` and `PreviewDeployKey` requests a name that is unique to the resource: the
-  `name` prop, a dash, and a hash of the resource identity. The provider deletes a key only by its
-  secret, so it cannot revoke the key of another resource. When the key list does not show
-  exactly one key with the requested name, the deploy stops with `DeployKeyRecoveryRequired`,
-  which lists the key ids. The provider never revokes a key on a failed create.
-- With an OAuth token as the credential, Convex creates no new key: it returns the OAuth token
-  with a new prefix. The key resources then stop with `DeployKeyIsCredential` and do not keep that
-  value, because a delete would revoke the OAuth token. Use a team access token or the Convex CLI
-  login.
-- `Convex.Deployment` has the removal policy `retain` for every type. It never deletes a
-  production deployment, also not with `RemovalPolicy.destroy()` and also not a dev deployment that
-  became a production deployment: delete the project for that. A
-  dev or preview deployment is deleted only with `RemovalPolicy.destroy()`.
-- `Convex.Deployment` takes over the project's production deployment without `--adopt`: Convex
-  creates it with the project, and the resource never changes or deletes it. A dev or preview
-  deployment that exists but is not in state belongs to someone else, such as a preview that CI
-  made with `npx convex deploy --preview-name`. The resource takes it over only with `--adopt`.
-  It never creates over it: a Convex create for an existing preview name deletes that preview.
-- A deployment keeps its `projectId`, `type`, and `name`. A change stops the deploy with
-  `DeploymentIdentityChange`. The resource is never replaced.
-- `Convex.Code` checks before the push that the deploy key fits the deployment, and after the push
-  that the CLI pushed to that deployment. A production deploy key on a preview stage stops the deploy
-  before the push.
-- An `EnvironmentVariable` or a `DefaultEnvironmentVariable` that exists but is not in state
-  belongs to someone else. The provider overwrites it only with `--adopt`. The same is true for a
-  `Convex.Code` `env` variable that exists with another value.
-- A variable keeps its name and deployment (a default keeps its project, name, and deployment
-  type). A change stops the deploy with `VariableIdentityChange`. To rename or move a variable,
-  create a new resource with a new logical id and remove the old one. A rename in place would
-  need a cleanup step that can fail and leave a variable or a revoked deploy key behind.
+- `Convex.Project` and `Convex.Deployment` have the removal policy `retain`. `alchemy destroy`
+  forgets them and Convex keeps them. Add `RemovalPolicy.destroy()` to delete with the resource.
+- A project is never replaced. A change of `team`, `slug`, `deploymentType`, or `deploymentRegion`
+  stops the deploy with a typed error that names the fix.
+- A deployment keeps its `project`, `type`, and `name`; a change stops the deploy with
+  `DeploymentIdentityChange`. A production deployment is never deleted, also not with
+  `RemovalPolicy.destroy()`, and also not a dev deployment that became one.
+- A dev or preview deployment that exists but is not in state belongs to someone else, such as a
+  preview that CI made. The resource takes it over only with `--adopt`, and never creates over it:
+  a Convex create for an existing preview name deletes that preview.
+- With the access token, each push uses a new deploy key with only `deployment:deploy`,
+  `deployment:env:view`, and `deployment:env:write`, which expires after two hours and is deleted
+  after the push, also after a failure. With an OAuth token, Convex returns the token itself as the
+  key, so the delete is skipped. No other key is created or revoked.
+- The key reaches the CLI only in an env file with mode 0600, in a temporary home directory that is
+  removed after the run. Variables named `CONVEX_*` are not passed on. The CLI output stays out of
+  the logs; a failure (`CodePushFailed`) shows the last 20 lines with the key removed. A push to
+  another deployment stops the deploy with `PushTargetMismatch`.
+- A variable in `env` that exists with another value and that the resource did not set stops the
+  deploy with `VariablesOwnedBySomeoneElse`. `--adopt` overwrites it. Destroy leaves variables in
+  place: they go with the deployment.
 - A variable write runs again after a Convex write conflict or a 5xx answer, at most four more
-  times. The write sets a value, so a second write has the same result.
-
-Upgrade from 0.2: `Convex.Deploy` keeps working. To move to `Convex.Code`, add a
-`Convex.Deployment` and a `Convex.Code` with a new logical id and remove the `Convex.Deploy`.
-Removing `Convex.Deploy` changes nothing in Convex. For a preview stage, use `previewName`, not
-`previewCreate`, while you still use `Convex.Deploy`.
-
-Upgrade from 0.1: state from 0.1 records the policy `destroy` for each project. Run
-`alchemy deploy` one time with 0.2 while the stack still declares the project. That deploy records
-`retain`. Do this before you remove a project from the stack or run `alchemy destroy`.
-Deploy keys from 0.1 state keep working, but 0.2 does not delete them: their state cannot show that
-the secret is a new key and not an OAuth token. When you remove or replace such a key, delete it in
-the Convex dashboard.
-
-## Resources
-
-- `Convex.Project`: `{ team: slug | id, name, deploymentRegion?, deploymentType? }`. Creates a
-  project with its default deployment. Outputs `projectId`, `slug`, `teamId`,
-  `prodDeploymentName`, `prodDeploymentUrl`. A changed `name` renames the project in place. A
-  changed `team`, `deploymentRegion`, or `deploymentType` stops the deploy. An existing project
-  with the same name is adopted only with `--adopt`. The removal policy is `retain`: only a
-  resource with `RemovalPolicy.destroy()` deletes the project with its deployments and data.
-- `Convex.Deployment`: `{ projectId, type: "prod" }` or
-  `{ projectId, type: "dev" | "preview", name }`. Outputs `name` (such as `happy-animal-123`),
-  `url` (`https://<name>.convex.cloud`, with the region outside US East), `siteUrl` (the same
-  host on `.convex.site`), `type`, `projectId`, `reference`, and `previewName`.
-  - `prod` takes over the project's default production deployment, and follows it when another
-    production deployment becomes the default. It never creates one: a project without one stops
-    the deploy with `ProductionDeploymentNotFound`.
-  - `dev` creates a dev deployment with `name` as its reference, through
-    `POST /projects/{project_id}/create_deployment`. Convex records the member of the access token
-    as its creator. It is not that member's default dev deployment, so `npx convex dev` does not
-    select it.
-  - `preview` creates a preview deployment with `name` as its preview name, through the same
-    call. `npx convex deploy --preview-name <name>` with a preview deploy key finds it.
-  - When the deployment in state is gone, such as an expired preview, the next deploy creates it
-    again. Two deployments with the name stop the deploy with `AmbiguousDeployment`.
-- `Convex.Code`: `{ deployment, deployKey, cwd, command?, env?, typecheck?, codegen? }`. Pushes
-  the functions of the Convex app in `cwd` with `convex deploy`. Outputs `deploymentName`,
-  `url`, `siteUrl`, `deployedAt` (milliseconds since the Unix epoch), and `envNames`.
-  - `deployment` is a `Convex.Deployment` resource or a deployment name. `deployKey` is a
-    deploy key of that deployment, or, for a preview deployment, a preview deploy key of the
-    project: Code then runs `convex deploy --preview-name <name>`. Any other key stops the deploy
-    with `DeployKeyMismatch` before the push.
-  - Code pushes on every deploy. It does not hash the sources: a preview can expire, a push from
-    outside Alchemy can change the deployment, and a hash misses workspace packages. The CLI
-    uploads only the modules that changed.
-  - Code runs the `convex` package that `cwd` resolves, with the Node.js that runs Alchemy, and
-    never downloads one (`ConvexCliNotFound`). `command`, such as `["pnpm", "exec", "convex"]`,
-    replaces it.
-  - The key goes to the CLI only in an env file with mode 0600 (`--env-file`), in a temporary
-    directory that is removed after the run, also after a failure or an interruption. That
-    directory is the home directory of the CLI, so the CLI cannot use the Convex login of the
-    machine. Variables named `CONVEX_*` are not passed on.
-  - The CLI output stays out of the logs. A failure (`CodePushFailed`) shows the last 20 lines
-    with the key removed. A push to another deployment stops the deploy with
-    `PushTargetMismatch`.
-  - `env` sets variables on the deployment before the push, with the deploy key. A name that
-    leaves `env` is removed from the deployment. A preview deploy key cannot set variables
-    (`EnvironmentNeedsDeployKey`).
-  - `typecheck` (`enable`, `try`, `disable`) and `codegen` (`enable`, `disable`) go to
-    `convex deploy` as flags.
-  - Deleting the resource does nothing. The functions and the `env` variables stay: the deployment
-    runs them.
-- `Convex.DeployKey`: `{ deployment, name, allowedActions? }`. Outputs `uniqueName`, `keyId`, and
-  the `deployKey` secret. Any change replaces the key. Delete revokes the key by its secret; a key
-  from 0.1 state stays. Keys are never adopted: a key without its secret is useless. The live test
-  pushes with `Convex.Code` and sets `env` with a key that has only `deployment:deploy`,
-  `deployment:env:view`, and `deployment:env:write`.
-- `Convex.PreviewDeployKey`: `{ projectId, name }`. Project-level key for preview deployments.
-  Outputs `uniqueName`, `keyId`, and `previewDeployKey`.
-- `Convex.EnvironmentVariable`: `{ deployment, deployKey, name, value }`. One variable on one
-  deployment, set through the deployment API with that deployment's key. An existing variable with
-  the same name is adopted and overwritten only with `--adopt`. A new `value` or `deployKey` is an
-  update in place. A new `name` or `deployment` stops the deploy with `VariableIdentityChange`:
-  use a new logical id. Outputs `deployment`, `name`, and `deployKey`. Read and delete use the
-  deploy key in the outputs, not the props.
-- `Convex.DefaultEnvironmentVariable`: `{ projectId, name, value, deploymentType }`. A project
-  default that new deployments of that type inherit. Use it for preview and dev deployments. An
-  existing default with the same name and type is adopted and overwritten only with `--adopt`. A
-  new `value` is an update in place. A new `projectId`, `name`, or `deploymentType` stops the
-  deploy with `VariableIdentityChange`: use a new logical id.
-- `Convex.Deploy` (deprecated since 0.3, use `Convex.Code`): `{ cwd?, env?, deployKey,
-previewName?, previewCreate?, previewRun?, extraArgs?, memo?, timeout? }`. Runs
-  `npx convex deploy` with `CONVEX_DEPLOY_KEY` set and parses the deployment URL from the CLI
-  output. Outputs `url`, `deploymentName`, `hash`. It stays so that stacks and state from 0.1
-  and 0.2 keep working. Deleting the resource does nothing.
-
-### Which Convex call each operation uses
-
-| Operation                                | Path                                                                                |
-| ---------------------------------------- | ----------------------------------------------------------------------------------- |
-| Find the production deployment           | `GET /projects/{project_id}/list_deployments?deploymentType=prod&isDefault=true`    |
-| Find a dev or preview deployment by name | `GET /projects/{project_id}/list_deployments?deploymentType=<type>`                 |
-| Create a dev or preview deployment       | `POST /projects/{project_id}/create_deployment` with `type` and `reference`         |
-| Check that a deployment exists           | `GET /deployments/{deployment_name}`                                                |
-| Delete a dev or preview deployment       | `POST /deployments/{deployment_name}/delete`                                        |
-| Push to a deployment                     | `convex deploy --env-file <file>` with a deploy key of the deployment               |
-| Push to a preview deployment             | `convex deploy --preview-name <name> --env-file <file>` with a preview deploy key   |
-| Set `env` variables                      | `POST https://<deployment>/api/v1/update_environment_variables` with the deploy key |
-
-Code uses `--preview-name`, not `--preview-create`: `--preview-create` deletes and creates the
-preview deployment again on every push, so every deploy would lose the preview data and change its
-URL.
+  times.
 
 ## Limits
 
-- Team slugs resolve through an unofficial dashboard endpoint. Pass the numeric team id to avoid
-  it.
-- Deploy keys and other secret outputs are part of Alchemy state. Alchemy's Cloudflare state store
-  encrypts state at rest; the local file store does not.
-- A deleted deploy key keeps working on the deployment API for roughly 30 seconds.
-- A run that stops between a key create and the state write leaves a key that state does not
-  know. The next run stops with `DeployKeyRecoveryRequired`. Delete the listed key in the Convex
-  dashboard, then run the deploy again.
-- A run that stops between a deployment create and the state write leaves a dev or preview
-  deployment that state does not know. The next run stops with `OwnedBySomeoneElse`. Run it with
-  `--adopt` to take that deployment over.
-- Between the lookup and the create of a preview deployment, another writer can create a preview
-  with the same name. The Convex create then replaces it. The Management API has no create that
-  fails for an existing preview name.
-- `siteUrl` is the `.convex.site` URL. A custom domain is not used.
-- When another production deployment becomes the default, a `DeployKey` with `deployment: prod.name`
-  gets a new key on the new deployment. Alchemy plans this as an update, not a replacement, so the
-  key on the old deployment stays. Delete it in the Convex dashboard.
-- Variables that `Convex.Code` set on a deployment stay there when `deployment` changes to
-  another deployment, and when the resource is removed.
+- `env` values are props, so Alchemy state holds them. Keep `.alchemy/` git-ignored, and use an
+  encrypted state store, such as `Cloudflare.state()`, in CI.
+- The hash does not see a change in a workspace package outside the app directory, or a push from
+  outside Alchemy. Change a file of the app to push again.
+- With a deploy key, the provider reaches the deployment at `https://<name>.convex.cloud`, so the
+  deployment must answer there.
+- A run that stops between a deployment create and the state write leaves a deployment that state
+  does not know. The next run stops with `OwnedBySomeoneElse`; run it with `--adopt`.
+- Team slugs for `{ team, name }` resolve through an unofficial dashboard endpoint. Pass the numeric
+  team id to avoid it. `{ team, slug }` uses the official endpoint.
 - Not covered: deployment regions and classes, custom domains, log streams, teams and members,
   components, snapshots.
 
@@ -312,26 +170,16 @@ pnpm run build            # lib/ with declarations, then publint and attw
 pnpm run test:live        # real API calls, see below
 ```
 
-Use Node 24 (`.node-version`) and pnpm 11. `pnpm install` also installs a pre-commit hook that
-runs `vp staged`.
-
-Unit tests run against recorded Management API payloads in `test/fixtures/management/`. Live tests
-run only with `ALCHEMY_CONVEX_LIVE=1`, which `pnpm run test:live` sets. They need a Convex login or
-`CONVEX_ACCESS_TOKEN`, and a throwaway project.
-Point them at yours with `ALCHEMY_CONVEX_LIVE_TEAM`, `ALCHEMY_CONVEX_LIVE_PROJECT_ID`,
-`ALCHEMY_CONVEX_LIVE_DEPLOYMENT`, and `ALCHEMY_CONVEX_LIVE_PROJECT_DIR` (a Convex app directory for
-the deploy test). They create resources named `tmp-alchemy-convex-*` and remove them again.
-A file argument runs one live file only, for example
-`pnpm run test:live test/live/safety.live.test.ts`. That test runs the data safety contract
-through the Alchemy engine. It creates a project `tmp-alchemy-convex-<8 hex>` in
-`ALCHEMY_CONVEX_LIVE_TEAM` and deletes it at the end, also after a failure. It refuses to delete a
-project whose name does not start with `tmp-alchemy-convex-`.
-`test/live/deployment-code.live.test.ts` does the same for `Convex.Deployment` and
-`Convex.Code`: it pushes the app in `test/fixtures/convex-app` with the real Convex CLI to the
-production deployment and to a preview deployment, and it also refuses to delete a deployment of
-another project.
+Use Node 24 (`.node-version`) and pnpm 11. Unit tests run against recorded Management API payloads
+in `test/fixtures/management/` and a fake Convex CLI. Live tests run only with
+`ALCHEMY_CONVEX_LIVE=1`, which `pnpm run test:live` sets. They need a Convex login or
+`CONVEX_ACCESS_TOKEN` that can create projects in `ALCHEMY_CONVEX_LIVE_TEAM`. Each test creates a
+project whose name starts with `ALCHEMY_CONVEX_LIVE_PREFIX` (default `tmp-alchemy-convex-`),
+deletes it at the end, also after a failure, and refuses to delete a project, or a deployment of a
+project, without that prefix. A file argument runs one live file only, for example
+`pnpm run test:live test/live/plane.live.test.ts`.
 
 Releases: change `version` in `package.json` in a pull request. After the merge,
 `.github/workflows/release.yml` publishes that version from `main` with npm trusted publishing.
 
-License: Apache 2.0.
+License: Apache 2.0. Parts follow Confect; see [NOTICE](NOTICE).