docs: Composer 0.36.0 environments, local copies and dev secrets

apps/docs/content/docs/(index)/prisma-compute/deploy.mdx

@@ -13,7 +13,7 @@ Start from wherever you are:
 - **You're starting from scratch.** [Declare a new app](#start-from-scratch) and run it locally, then deploy it.
 - **You already have an app.** [Add a declaration around your server code](#bring-an-app-you-already-have), then deploy it.
 
-Both paths meet in the same [deploy step](#2-deploy), because Composer treats every app the same way. A deployed app becomes a **project**, deploying with no flags targets **production**, and `--stage <name>` deploys an isolated copy of the whole app as a [preview branch](/compute/branching) of the same project. Local runs never talk to the platform, so you need credentials only when you deploy. For the platform's resource model, see [Compute](/compute#the-model).
+Both paths meet in the same [deploy step](#2-deploy), because Composer treats every app the same way. A deployed app becomes a **project**, deploying with no flags targets the **production** environment, and `--environment <name>` deploys an isolated copy of the whole app as a [preview branch](/compute/branching) of the same project. Local runs never talk to the platform, so you need credentials only when you deploy. For the platform's resource model, see [Compute](/compute#the-model).
 
 ## Prerequisites
 
@@ -235,15 +235,15 @@ You can also inspect everything in the [Console](https://pris.ly/pdp): projects,
 
 ## 4. Ship changes and environments
 
-Re-deploying is idempotent: build again, deploy again, and the platform applies the difference instead of recreating everything. That includes removals: delete a provision from your module and the next deploy deletes the resource; see [Removing resources](/composer/deploying#removing-resources). Production and previews are separated by stages:
+Re-deploying is idempotent: build again, deploy again, and the platform applies the difference instead of recreating everything. That includes removals: delete a provision from your module and the next deploy deletes the resource; see [Removing resources](/composer/deploying#removing-resources). Production and previews are separate environments:
 
 ```npm
-npx prisma deploy                  # production
-npx prisma deploy --stage staging  # a persistent staging environment
-npx prisma deploy --stage pr-42    # one environment per PR
+npx prisma deploy                        # production
+npx prisma deploy --environment staging  # a persistent staging environment
+npx prisma deploy --environment pr-42    # one environment per PR
 ```
 
-A stage is a complete, isolated copy of the app: its own services, databases, and configuration, sharing only the code with production. In platform terms it is a [preview branch](/compute/branching) of the same project. Tearing a stage down needs the control API with service-token credentials, or a branch deletion in the Console; see [Destroying](/composer/deploying#destroying). [Deploying](/composer/deploying) covers CI, deploy state, and teardown in full.
+Each environment is a complete, isolated copy of the app: its own services, databases, and configuration, sharing only the code with the others. In platform terms, `production` is the project's default branch, and any other environment is a [preview branch](/compute/branching) of the same project with that name. Tearing an environment down needs the control API with service-token credentials, or a branch deletion in the Console; see [Destroying](/composer/deploying#destroying). [Deploying](/composer/deploying) covers CI, deploy state, and teardown in full.
 
 ## Hand it to your agent
 
@@ -273,5 +273,5 @@ Build a Bun API with a /todos endpoint backed by an in-memory list as a Prisma C
 
 - [Composer getting started](/composer/getting-started): the two-service version, with a typed contract between services.
 - [Databases](/composer/databases): give a service a Prisma Postgres database, plain or typed by a Prisma ORM contract.
-- [Deploying](/composer/deploying): stages, CI, deploy state, and teardown.
+- [Deploying](/composer/deploying): environments, CI, deploy state, and teardown.
 - [Local development](/local-development): run the app, database, and storage on your machine with the runtime you deploy.

apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx

@@ -47,7 +47,7 @@ npm install --save-dev prisma tsx typescript
 
 `temporal-polyfill` is a peer dependency of `@prisma/orm-postgres` too. It adds `Temporal`, the newer JavaScript date and time API, to runtimes such as Node.js 24 that do not have it built in. npm installs it for you, but with Yarn you add it yourself.
 
-The two Prisma packages have different version numbers, for example `prisma` 8.0.0-rc.28 and `@prisma/orm-postgres` 8.0.0-rc.21. That is normal, and any two `latest` versions work together.
+The two Prisma packages have different version numbers, for example `prisma` 8.0.0-rc.30 and `@prisma/orm-postgres` 8.0.0-rc.21. That is normal, and any two `latest` versions work together.
 
 ## 2. Create the config file and `.env`
 

apps/docs/content/docs/ai/tools/skills.mdx

@@ -131,7 +131,7 @@ npx prisma skills sync
 
 If you want the skill without installing the package, `npx skills add prisma/composer` still reads the [prisma/composer](https://github.com/prisma/composer) repository. That is a fallback: nothing keeps a copy installed that way up to date.
 
-It covers the whole Composer story: the mental model (Modules, `compute()`, `service.load()`), RPC contracts, databases, the first-party Modules for scheduled jobs, object storage, and event streams, config params and secrets, testing, and deploying with stages. Install it before your agent writes Composer code so it works from the current authoring API instead of inventing one.
+It covers the whole Composer story: the mental model (Modules, `compute()`, `service.load()`), RPC contracts, databases, the first-party Modules for scheduled jobs, object storage, and event streams, config params and secrets, testing, and deploying to environments. Install it before your agent writes Composer code so it works from the current authoring API instead of inventing one.
 
 ## Useful commands
 

apps/docs/content/docs/cli/deploy.mdx

@@ -1,9 +1,9 @@
 ---
 title: deploy
-description: Deploy a Composer application to Prisma Compute, to production or an isolated stage.
+description: Deploy a Composer application to Prisma Compute, to production or another environment.
 url: /cli/deploy
 metaTitle: deploy | Prisma CLI
-metaDescription: Complete reference for the prisma deploy command, including stages, credentials, CI reports, and the in-process control API.
+metaDescription: Complete reference for the prisma deploy command, including environments, credentials, CI reports, and the in-process control API.
 ---
 
 `deploy` deploys a [Prisma Composer](/composer) application to [Prisma Compute](/compute). It loads the module whose default export is the application root, named by `entry` in the `composer` section of `prisma.config.ts`, typically `./module.ts`. The command streams the deploy pipeline's own output to the terminal.
@@ -20,7 +20,8 @@ The `deploy` command does not build your application. Run your build command bef
 
 ```npm
 npx prisma deploy
-npx prisma deploy --stage feat-auth
+npx prisma deploy --environment feat-auth
+npx prisma deploy list --environment feat-auth
 ```
 
 ## Flags
@@ -29,10 +30,22 @@ npx prisma deploy --stage feat-auth
 | --- | --- |
 | `--entry <path>` | Deploy the app from this module instead of the `entry` in `prisma.config.ts` |
 | `--name <name>` | Override the application name for this deploy. It defaults to the name of the exported application, and that name selects the project in your workspace: a project this module deployed before is reused, and a same-name project whose hosted state cannot be verified stops the deploy with `HostedStateBootstrapError`, so pass `--name` when the default would land in a project you did not mean to deploy into |
-| `--stage <stage>` | Deploy scope to target; omit for production |
-| `--report <path>` | Write the deploy's outcome as JSON to this path: resources, preview URLs, and the failure cause. Also settable as `PRISMA_COMPOSER_REPORT_FILE` |
+| `--environment <name>` | The environment to deploy to. Defaults to `production`. Any other name is a complete, isolated copy of the app, such as `staging` or one per pull request. On Prisma Cloud, `production` is the project's default branch and any other name is a preview branch with that name |
+| `--report <path>` | Write the deploy's outcome as JSON to this path: resources, preview URLs, and the failure cause. The report's `environment` field names the environment it deployed. Also settable as `PRISMA_COMPOSER_REPORT_FILE` |
 | `--build-id <id>` | Join the deploy record your CI already created rather than letting the target create one |
 
+Upgrading from `--stage`: since `8.0.0-rc.30` the flag is `--environment`, and `--stage` fails with `CLI.COMMAND_MOVED`, naming the new flag. The `--report` file's `stage` field is now `environment`, and its `version` is `2`. Keep `@prisma/composer-prisma-cloud` on the same Composer version as the `prisma` CLI: an older one would read every environment as production, so the deploy refuses it with `DEPS.EXTENSION_INCOMPATIBLE` before it changes anything.
+
+## deploy list
+
+`deploy list` shows every node the app has deployed in an environment, the platform ID each one became and, for a service, its URL. It reads the environment on Prisma Cloud, so it works from any machine. Without `--environment` it lists `production`. It finds the app as `deploy` does, so run it where you run `deploy`, or pass the same `--name` and `--entry`.
+
+```npm
+npx prisma deploy list --environment pr-42
+```
+
+It fails with `DEPLOY.TARGET_NOT_FOUND` when the environment has nothing deployed.
+
 ## Global flags
 
 The Prisma CLI's global flags also apply: `--format`, `--json`, `--log-level`, `--verbose`, `--quiet`, `--yes`, `--confirm`, `--interactive`, `--color`, and `--config`.
@@ -48,16 +61,24 @@ The Prisma CLI's global flags also apply: `--format`, `--json`, `--log-level`, `
 
 ## Tearing down and log tailing
 
-The unified CLI has no `destroy` or `log` command. Both operations are available in-process through the control API below: `destroy` takes an explicit target (`{ kind: 'production' }` or `{ kind: 'stage', stage }`), and `log` tails a locally running application.
+The unified CLI has no `destroy` or `log` command. Both operations are available in-process through the control API below. `destroy` takes the name of the environment to remove, and has no default: production is `environment: 'production'`, and a call without `environment` fails with `DEPLOY.ENVIRONMENT_REQUIRED`. `log` tails a locally running application.
 
 ## The control API
 
 Everything the CLI does is also callable in-process, from `@prisma/composer/control`: typed `deploy`, `destroy`, `dev`, and `log` operations that return structured results instead of printing and exiting:
 
 ```ts
+import { fileURLToPath } from 'node:url';
 import { deploy } from '@prisma/composer/control';
-
-const result = await deploy({ entry: 'module.ts', stage: 'pr-42' });
+import prismaConfig from './prisma.config.ts';
+
+const result = await deploy({
+  environment: 'pr-42', // omit for production
+  config: {
+    value: prismaConfig.composer,
+    file: fileURLToPath(new URL('./prisma.config.ts', import.meta.url)),
+  },
+});
 if (!result.ok) console.error(result.failure.message);
 ```
 
@@ -69,4 +90,4 @@ The operations authenticate with `PRISMA_SERVICE_TOKEN` and `PRISMA_WORKSPACE_ID
 
 - [`dev`](/cli/dev): run the same application locally, with no credentials.
 - [Getting started](/composer/getting-started): the commands in a working flow.
-- [Deploying](/composer/deploying): stages, CI, and what a deploy prints.
+- [Deploying](/composer/deploying): environments, CI, and what a deploy prints.

apps/docs/content/docs/cli/dev.mdx

@@ -16,6 +16,7 @@ Like [`deploy`](/cli/deploy), `dev` runs your *built* output, so build first.
 npx prisma dev
 npx prisma dev --fresh
 npx prisma dev --detach
+npx prisma dev --environment test --fresh
 npx prisma dev url my-app.gateway
 npx prisma dev stop
 ```
@@ -26,7 +27,7 @@ npx prisma dev stop
 | --- | --- |
 | `dev` | Run the app on this machine and watch it for changes until you press `Ctrl-C` |
 | `dev url <address>` | Print where a service, database, or bucket of the app answers locally |
-| `dev stop` | Stop the app that `prisma dev` last ran from this directory |
+| `dev stop` | Stop the app's local copy in one environment |
 
 `dev url`, `dev stop`, and `--detach` are in `prisma` since `8.0.0-rc.24`. Check your version with `npx prisma --version`.
 
@@ -36,21 +37,23 @@ npx prisma dev stop
 | --- | --- |
 | `--entry <path>` | Load the app from this module instead of the `entry` in `prisma.config.ts` |
 | `--name <name>` | Run the app under this name instead of the name its root module declares. A different name gets its own local services, databases, and buckets |
-| `--fresh` | Before starting, delete this app's local services, databases, and buckets, with their data. Other apps run from the same directory keep theirs |
+| `--environment <name>` | The environment to run as. Defaults to `dev`. Each environment is a separate local copy of the app, with its own services, databases, buckets, and ports, so a second one, such as `test`, runs alongside `dev` and leaves its data alone |
+| `--fresh` | Before starting, delete this app's local services, databases, and buckets in the environment, with their data. Other apps and environments run from the same directory keep theirs |
 | `--detach` | Return once every service answers, and leave the app running without watching for changes. `prisma dev stop` stops it. Use it in scripts, agents, and CI |
 
-`dev` needs no credentials or environment variables; local runs never talk to the platform.
+`dev` needs no credentials; local runs never talk to the platform. It reads the secrets your services bind with `envSecret` from its environment variables: your shell, or a `.env` file that `prisma.config.ts` loads. A required secret that is unset or empty stops `dev` with an error naming it. See [Secrets](/composer/local-development#secrets).
 
-When `dev` ends, by `Ctrl-C` or a failure, it stops the app's service processes and local Postgres servers. The emulators themselves keep running. Their data and ports are kept, so the next `dev` in this directory starts with the same ports and data.
+When `dev` ends, by `Ctrl-C` or a failure, it stops the app's service processes and local Postgres servers. The emulators themselves keep running. Their data and ports are kept, so the next `dev` in this directory and environment starts with the same ports and data. Local state lives in `.prisma-composer/dev/<environment>/`.
 
-With `--detach`, `dev` prints the same `ready` line and service URLs as a foreground run, then exits with code `0` and leaves the app running. It does not pick up rebuilds: run `prisma dev --detach` again after a build, or run `prisma dev` in the foreground, which takes over the running app and watches it. If a detached start fails before every service answers, `dev` stops the whole app and exits non-zero. `--detach` combines with `--fresh` and `--name`.
+With `--detach`, `dev` prints the same `ready` line and service URLs as a foreground run, then exits with code `0` and leaves the app running. It does not pick up rebuilds: run `prisma dev --detach` again after a build, or run `prisma dev` in the foreground, which takes over the running app and watches it. If a detached start fails before every service answers, `dev` stops the whole app and exits non-zero. `--detach` combines with `--fresh`, `--name`, and `--environment`.
 
 ## dev url
 
-`dev url <address>` prints the local URL of one node of the app that `prisma dev` runs from the current directory. A node is a service, database, or bucket in the app, and its address is its path from the app's name, with dots between the names, such as `my-app.gateway` or, for a database inside a `catalog` module, `my-app.catalog.database`.
+`dev url <address>` prints the local URL of one node of an app that `prisma dev` runs from the current directory. A node is a service, database, or bucket in the app, and its address is its path from the app's name, with dots between the names, such as `my-app.gateway` or, for a database inside a `catalog` module, `my-app.catalog.database`.
 
 ```npm
 npx prisma dev url my-app.gateway
+npx prisma dev url my-app.gateway --environment test
 ```
 
 ```text no-copy
@@ -69,26 +72,28 @@ That line is for you to read. When standard output is a pipe or a file, or `$(..
 url=$(npx prisma dev url my-app.gateway) && curl "$url"
 ```
 
-Run it from the directory you ran `prisma dev` in, while the app runs. It starts nothing: it reads what the last `prisma dev` in this directory recorded. With `--json`, it prints `{ address, kind, url, state }` instead.
+Run it from the directory you ran `prisma dev` in, while the app runs. The first name of the address is the app, so `dev url` does not load your entry file. It reads the environment `dev` unless `--environment` names another, and it starts nothing: it reads what `prisma dev` recorded for that app and environment in this directory. With `--json`, it prints `{ address, kind, url, state }` instead.
 
 `dev url` prints a URL only for a node that is running, so something is listening at the URL it prints. Otherwise it fails with one of these codes:
 
 | Code | Meaning |
 | --- | --- |
-| `DEV.NOT_STARTED_HERE` | `prisma dev` never ran in this directory |
+| `DEV.NOT_STARTED_HERE` | `prisma dev` never ran that app in that environment in this directory |
+| `DEV.ENVIRONMENT_NAME_MISMATCH` | The environment's folder belongs to an environment whose name differs only in case, such as `dev` for `--environment Dev` on macOS. Use the recorded name |
 | `DEV.ADDRESS_UNKNOWN` | The app has no node at that address. The message lists the addresses it has |
 | `DEV.EMULATOR_UNREACHABLE` | The emulator that runs the node is not running. Run `prisma dev` again, which starts it |
-| `DEV.NOT_RUNNING` | The node exists but is not running. Usually it was stopped, by `prisma dev stop`, by `prisma dev` ending, or by running another app in this directory. A service that keeps crashing is reported this way too, with the path of its log |
+| `DEV.NOT_RUNNING` | The node exists but is not running. Usually it was stopped, by `prisma dev stop` or by `prisma dev` ending. A service that keeps crashing is reported this way too, with the path of its log |
 
 ## dev stop
 
-`dev stop` stops the app that `prisma dev` last ran from the current directory: its service processes and local database servers, as `Ctrl-C` does in a foreground `prisma dev`.
+`dev stop` stops the app's local copy in one environment: its service processes and local database servers, as `Ctrl-C` does in a foreground `prisma dev`. It finds the app as `prisma dev` does, from your entry file or `--name`, and stops the environment `dev` unless `--environment` names another. Other apps and environments keep running.
 
 ```npm
 npx prisma dev stop
+npx prisma dev stop --environment test
 ```
 
-Use it to stop an app started with `--detach`, or when `prisma dev` was killed without a chance to stop the app. It lists the services and databases it stopped. When nothing of the app was running, it prints `Nothing of <app> was running.` and still exits with code `0`. Data and ports are kept, so the next `prisma dev` starts with the same ports and data. The emulators themselves keep running, because apps in other directories may use them.
+Use it to stop an app started with `--detach`, or when `prisma dev` was killed without a chance to stop the app. If that app never ran in that environment here, it fails with `DEV.NOT_STARTED_HERE`. It lists the services and databases it stopped. When nothing of the app was running, it prints `Nothing of <app> was running.` and still exits with code `0`. Data and ports are kept, so the next `prisma dev` starts with the same ports and data. The emulators themselves keep running, because apps in other directories may use them.
 
 ## Global flags