prisma · ankur-arch · Jul 7, 2026
diff --git a/apps/docs/content/docs/compute/branching.mdx b/apps/docs/content/docs/compute/branching.mdx
@@ -16,8 +16,8 @@ A platform branch usually matches a Git branch name, but in Prisma it is a real
 
 Every branch has a role:
 
-- The **first branch** in a project is your production branch, usually `main`. It's protected and durable: after the first deploy, deploys to it need an explicit `--prod` flag, and automated cleanup never touches it.
-- **Every other branch** is a preview by default: disposable resources for testing changes before they merge. Preview deploys never ask for confirmation.
+- The **production branch** is your project's default branch, usually `main`. It exists from project creation, whether or not you've deployed to it yet. It's protected and durable: after the first deploy, deploys to it need an explicit `--prod` flag, and automated cleanup never touches it.
+- **Every other branch** is a preview: disposable resources for testing changes before they merge. Deploy order doesn't matter: if your first-ever deploy targets a non-default branch, it creates a preview, not production. Preview deploys never ask for confirmation.
 
 To learn more, see the [Deployments docs](/compute/deployments).
 
@@ -35,6 +35,12 @@ Inside a Git repo, deploying from `feature/search` targets the `feature/search`
 npx @prisma/cli@latest app deploy --branch feature/search
 ```
 
+:::warning
+
+Branch resolution decides production vs preview; flags don't. `app deploy --prod` from a Git feature branch resolves to that branch and creates a **preview** deployment — the `--prod` flag changes nothing there. To deploy production from any checkout, pass the branch explicitly: `app deploy --prod --branch main`. See [How Compute chooses production or preview](/compute/deployments#how-compute-chooses-production-or-preview).
+
+:::
+
 Inspect platform branches:
 
 ```npm

diff --git a/apps/docs/content/docs/compute/cli-reference.mdx b/apps/docs/content/docs/compute/cli-reference.mdx
@@ -42,7 +42,7 @@ Manage apps and deployments for a project.
 | `app logs`                    | Stream logs for the app's current deployment                              |
 | `app list-deploys`            | List deployments for the app                                              |
 | `app show-deploy <deployment>`| Show a deployment in detail                                               |
-| `app promote <deployment>`    | Promote a deployment to production, rebuilding with production env vars   |
+| `app promote <deployment>`    | Re-promote an earlier deployment of the current branch's app, rebuilding with that branch's env vars. Same-branch only: it can't move a preview deployment to production |
 | `app rollback`                | Roll back production to the previous deployment, without rebuilding       |
 | `app remove`                  | Remove the app from the current branch                                    |
 
@@ -54,20 +54,22 @@ Manage apps and deployments for a project.
 | `--project <id-or-name>`  | Target a specific project                                                    |
 | `--create-project <name>` | Create and link a new project before deploying                               |
 | `--branch <name>`         | Deploy to a specific branch; otherwise your active Git branch, then `main`   |
-| `--framework <name>`      | One of `nextjs`, `nuxt`, `astro`, `hono`, `tanstack-start`, `bun`            |
+| `--framework <name>`      | One of `nextjs`, `nuxt`, `astro`, `hono`, `nestjs`, `tanstack-start`, `custom`, `bun` |
 | `--entry <path>`          | Entry point, required for `bun` and useful when detection needs a hand       |
 | `--http-port <port>`      | HTTP port your app listens on                                                |
 | `--env <KEY=value>`       | Set a one-off variable for this deployment (repeatable)                      |
 | `--prod`                  | Confirm intent to deploy to the production branch                            |
 
 After the first production deploy, every later production deploy needs `--prod`; without it the deploy fails with `PROD_DEPLOY_REQUIRES_FLAG`. With `--prod`, the CLI asks for confirmation; pass `-y` / `--yes` to accept it up front. In non-interactive mode, a `--prod` deploy without `--yes` fails with `CONFIRMATION_REQUIRED`. The first production deploy is auto-promoted and needs neither flag.
 
+`--prod` confirms production; it doesn't select it. The resolved branch decides the environment, so from a non-default Git branch `app deploy --prod` creates a preview deployment. Pass `--branch main` to target production explicitly. See [How Compute chooses production or preview](/compute/deployments#how-compute-chooses-production-or-preview).
+
 ### `app build` and `app run` options
 
 | Flag                  | Description                                                                  |
 | --------------------- | ----------------------------------------------------------------------------- |
 | `--entry <path>`      | Entry point for Bun apps                                                       |
-| `--build-type <type>` | `app build`: `auto`, `bun`, `nextjs`, `nuxt`, `astro`, `tanstack-start`. `app run`: `auto`, `bun`, `nextjs` |
+| `--build-type <type>` | `app build`: `auto`, `bun`, `nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, `custom`. `app run`: `auto`, `bun`, `nextjs` |
 | `--port <port>`       | Port for `app run`                                                             |
 
 ### Other `app` options

diff --git a/apps/docs/content/docs/compute/deployments.mdx b/apps/docs/content/docs/compute/deployments.mdx
@@ -40,16 +40,42 @@ npx @prisma/cli@latest app build
 npx @prisma/cli@latest app run --port 3000
 ```
 
-`app build` supports the build types `auto`, `bun`, `nextjs`, `nuxt`, `astro`, and `tanstack-start`. `app run` currently supports `auto`, `bun`, and `nextjs`.
+`app build` supports the build types `auto`, `bun`, `nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, and `custom`. `app run` currently supports `auto`, `bun`, and `nextjs`.
+
+## How Compute chooses production or preview
+
+The **resolved branch** decides the environment; no flag overrides it. A deploy resolves its branch in this order:
+
+1. `--branch <name>`, if you pass it.
+2. Your active Git branch.
+3. `main`.
+
+If the resolved branch is your project's default branch (usually `main`), the deploy is production. Any other branch is a preview. To confirm which one you got, check the deploy output: it prints the branch and its kind, and in `--json` mode it's the `branch` field:
+
+```json
+"branch": { "name": "main", "kind": "production" }
+```
+
+A `"promoted": true` in the output means the deployment went live *within its branch* — it does not mean it reached production.
 
 ## Deploy to production
 
-Your first deployment is promoted to production automatically. After that, every production deploy needs an explicit `--prod` flag, so you don't ship to production by accident:
+`--prod` confirms a production deploy; it doesn't cause one. Your first deployment to the production branch is promoted automatically. After that, every production deploy needs an explicit `--prod` flag, so you don't ship to production by accident:
 
 ```npm
 npx @prisma/cli@latest app deploy --prod
 ```
 
+:::warning
+
+**Branch context still matters.** Run `app deploy --prod` from a Git feature branch and the deploy resolves to that branch, so it creates a preview deployment — the `--prod` flag has no effect there and the CLI doesn't warn. To deploy production from any checkout, pass the branch explicitly:
+
+```npm
+npx @prisma/cli@latest app deploy --prod --branch main
+```
+
+:::
+
 Without `--prod`, a deploy that resolves to the production branch and already has a live production deployment fails with `PROD_DEPLOY_REQUIRES_FLAG`. With `--prod`, the CLI shows the current live deployment and asks you to confirm before replacing it.
 
 For scripts and CI, pass both flags so nothing waits on a prompt:
@@ -82,15 +108,40 @@ npx @prisma/cli@latest app logs --app web --deployment dep_123
 
 Your app's log lines go to stdout; the CLI's own status and errors go to stderr, so you can pipe them apart. If the platform can't serve logs for the resolved deployment, the command fails with `FEATURE_UNAVAILABLE`.
 
+## The deploy succeeded but the app only serves an error page
+
+A successful deploy means the build produced an artifact and a process started listening; it doesn't prove the app works. If the live URL returns an error page:
+
+- Stream `app logs` and look for startup errors.
+- Bind all interfaces: the server must listen on `0.0.0.0`, not `localhost` or `127.0.0.1`. A loopback-only listener looks ready to the platform but is unreachable from public ingress.
+- Listen on the deployed HTTP port: read `process.env.PORT` when your framework allows it, or pass the matching `--http-port` at deploy time.
+- Ship every file the app reads at runtime. Templates, static assets, and data files must be inside the build output; the runtime has no persistent filesystem and nothing outside the artifact exists at request time. Import assets through your bundler or place them where your framework's build includes them.
+- Reproduce with the exact artifact locally: `app build`, then `app run --port 3000`. If it fails the same way on your machine, the problem is in the build, not the platform.
+
 ## Promote and roll back
 
-Promote an earlier deployment to production:
+Promote an earlier **production** deployment back to live:
 
 ```npm
 npx @prisma/cli@latest app promote dep_123 --app web
 ```
 
-Promotion rebuilds the deployment with your production environment variables. The rebuild is necessary because values are baked in at deploy time: a preview build still carries preview config, so it can't serve production as-is.
+Promotion rebuilds the deployment with your current production environment variables. The rebuild is necessary because values are baked in at deploy time, so an old build can't pick up new config as-is. Because it rebuilds, verify the result serves correctly afterwards — `app logs` or a request to the live URL.
+
+`app promote` works within one branch. It has no `--branch` flag; the branch comes from your active Git branch (or `main` outside a repo), and the deployment id must belong to that branch's app. It cannot move a preview deployment to production:
+
+- From a preview Git branch, promote resolves the *preview* app. Promoting that branch's live deployment succeeds with the warning `The selected deployment is already live for this app` and changes nothing.
+- From the production branch, a preview deployment id fails with `DEPLOYMENT_NOT_FOUND`.
+
+To ship preview work to production, deploy it from source instead:
+
+```npm
+npx @prisma/cli@latest app deploy --prod --branch main
+```
+
+or merge to your default branch with [GitHub integration](/compute/github) connected.
+
+If `promote` appears to do nothing, check three things: the warnings array (`already live for this app` means you promoted within a preview, not to production), your current Git branch (it selects the app), and the deployment list (`app list-deploys` run from the production branch shows the ids promote can use). A transient `DEPLOY_FAILED` internal error can also occur; retrying the same command usually succeeds.
 
 Roll back to the previous deployment, or a specific one. Unlike `promote`, rollback reuses an existing build, so there is no rebuild step between you and a known-good state:
 

diff --git a/apps/docs/content/docs/compute/environment-variables.mdx b/apps/docs/content/docs/compute/environment-variables.mdx
@@ -20,6 +20,10 @@ There are three layers:
 
 A preview deploy gets the preview variables, with any branch overrides layered on top. Overrides help when one branch needs a different API key, database URL, or feature flag than the rest.
 
+### Which scope does a deploy use?
+
+The branch the deploy resolves to picks the scope: the production branch gets production variables, and every other branch gets preview variables plus its overrides. This holds regardless of flags — `app deploy --prod` run from a non-default Git branch is still a preview deploy and gets **preview** variables, not production ones. To confirm which scope applied, check the `branch` field in the deploy output: `"kind": "production"` or `"kind": "preview"`. See [How Compute chooses production or preview](/compute/deployments#how-compute-chooses-production-or-preview).
+
 Values are resolved at deploy time and baked into the deployment. Changing a variable doesn't touch deployments that already exist and doesn't trigger a redeploy; the new value applies the next time you deploy.
 
 ## Set a variable

diff --git a/apps/docs/content/docs/compute/faq.mdx b/apps/docs/content/docs/compute/faq.mdx
@@ -70,6 +70,20 @@ PRISMA_SERVICE_TOKEN=... npx @prisma/cli@latest app deploy \
 
 Passing every target explicitly keeps the run self-contained; `--json` makes the result parseable, and `--no-interactive` turns any would-be prompt into a structured error.
 
+## I ran `app deploy --prod`. Why did I get a preview deployment?
+
+`--prod` confirms a production deploy; it doesn't cause one. The environment comes from the branch the deploy resolves to: `--branch` if passed, then your active Git branch, then `main`. Only the project's default branch is production, so from a feature branch `app deploy --prod` deploys a preview of that branch — silently. Deploy production from any checkout with:
+
+```npm
+npx @prisma/cli@latest app deploy --prod --branch main
+```
+
+The deploy output's `branch` field shows which environment you got: `"kind": "production"` or `"kind": "preview"`. To learn more, see [How Compute chooses production or preview](/compute/deployments#how-compute-chooses-production-or-preview).
+
+## Why did `app promote` do nothing?
+
+`app promote` works within the branch your Git checkout resolves to, and only on deployment ids that belong to that branch's app. Run from a preview branch, it promotes within that preview: promoting the deployment that's already live there succeeds with the warning `The selected deployment is already live for this app` and changes nothing. It cannot move a preview deployment to production — from the production branch, a preview deployment id fails with `DEPLOYMENT_NOT_FOUND`. To ship preview work to production, run `app deploy --prod --branch main`, or merge to your default branch with [GitHub connected](/compute/github).
+
 ## Why did my production deploy fail with `PROD_DEPLOY_REQUIRES_FLAG`?
 
 Your first deploy is promoted to production automatically. After that, deploying to the production branch needs an explicit `--prod` flag. Re-run with `npx @prisma/cli@latest app deploy --prod`, or deploy from a preview branch instead.
@@ -88,7 +102,7 @@ This means your project holds more than one app, so the CLI can't tell which one
 
 ## How do I add a custom domain?
 
-Promote a production app, then:
+Deploy your app to production first, then:
 
 ```npm
 npx @prisma/cli@latest app domain add shop.acme.com --app web

diff --git a/apps/docs/content/docs/compute/getting-started.mdx b/apps/docs/content/docs/compute/getting-started.mdx
@@ -89,20 +89,22 @@ npx @prisma/cli@latest project list
 
 ## Pick a framework
 
-The CLI detects your framework automatically. Today there is first-class support for **Next.js**, **Nuxt**, **Astro**, **Hono**, and **TanStack Start**:
+The CLI detects your framework automatically. Dedicated build support exists for exactly these frameworks: **Next.js**, **Nuxt**, **Astro**, **Hono**, **NestJS**, and **TanStack Start**:
 
 ```npm
 npx @prisma/cli@latest app deploy --framework nextjs
 npx @prisma/cli@latest app deploy --framework hono --entry src/index.ts
 npx @prisma/cli@latest app deploy --framework tanstack-start
 ```
 
-Deploy a plain Bun server by pointing `--entry` at your server file:
+Every other framework deploys as a plain Bun server — point `--entry` at the file that starts your HTTP server:
 
 ```npm
 npx @prisma/cli@latest app deploy --framework bun --entry src/server.ts
 ```
 
+This is how you deploy Elysia, Express, Fastify, or any hand-rolled server. There is no framework-specific handling on this path: the server must bind `0.0.0.0` (not `localhost`), listen on the deployed HTTP port (`process.env.PORT`, or pass `--http-port`), and any files it reads at runtime — templates, static assets — must be part of the built output. If a deploy succeeds but the URL serves an error page, see [the troubleshooting steps](/compute/deployments#the-deploy-succeeded-but-the-app-only-serves-an-error-page).
+
 :::note
 
 Next.js apps must set `output: "standalone"` in their Next.js config before deploying. The CLI builds the standalone output and fails the build if it's missing.
@@ -124,12 +126,18 @@ npx @prisma/cli@latest app run --port 3000
 
 ## Deploy to production
 
-Your first deployment is promoted to production automatically. After that, every production deploy needs an explicit `--prod` flag, so you don't ship to production by accident:
+Production or preview is decided by the branch your deploy resolves to (`--branch`, then your active Git branch, then `main`): the project's default branch is production, everything else is a preview. Your first deployment to the production branch is promoted automatically. After that, every production deploy needs an explicit `--prod` flag, so you don't ship to production by accident:
 
 ```npm
 npx @prisma/cli@latest app deploy --prod
 ```
 
+:::warning
+
+`--prod` confirms a production deploy; it doesn't select one. From a Git feature branch, `app deploy --prod` still creates a **preview** deployment of that branch. To deploy production from any checkout, pass the branch explicitly: `app deploy --prod --branch main`. The deploy output's `branch` field (`"kind": "production"` or `"kind": "preview"`) tells you which environment you got.
+
+:::
+
 Without `--prod`, a deploy that resolves to the production branch and already has a live production deployment fails with the error code `PROD_DEPLOY_REQUIRES_FLAG`. With `--prod`, the CLI shows the current live deployment and asks you to confirm before replacing it.
 
 For scripts and CI, pass both `--prod` and `-y` / `--yes` to accept the confirmation up front:

diff --git a/apps/docs/content/docs/compute/limitations.mdx b/apps/docs/content/docs/compute/limitations.mdx
@@ -17,14 +17,17 @@ Prisma Compute is in [Public Beta](/console/more/feature-maturity#public-beta).
 ## Projects and branches
 
 - Project setup is explicit: `--yes` won't create or choose a project for you.
-- The first branch in a project is production; the rest are preview by default.
+- The production branch is the project's default branch, usually `main`. Every other branch is a preview, regardless of deploy order: a first deploy that targets a non-default branch creates a preview, not production.
+- `app deploy --prod` confirms a production deploy; it doesn't redirect one. From a non-default Git branch it still creates a preview deployment. Pass `--branch main` to target production explicitly.
+- `app promote` works within a single branch and can't move a preview deployment to production. It has no `--branch` flag (neither does `app remove`); their branch context comes from your active Git branch.
 - `branch list` inspects branches; it doesn't create remote state.
 - Deleting a branch on GitHub can tear down the matching platform branch, but production and default branches are always left alone.
 
 ## Frameworks and runtimes
 
-- `app deploy --framework` accepts `nextjs`, `nuxt`, `astro`, `hono`, `tanstack-start`, and `bun`.
-- `app build --build-type` accepts `auto`, `bun`, `nextjs`, `nuxt`, `astro`, and `tanstack-start`.
+- `app deploy --framework` accepts `nextjs`, `nuxt`, `astro`, `hono`, `nestjs`, `tanstack-start`, `custom`, and `bun`. This list is exhaustive: no other framework has dedicated support.
+- Frameworks not on the list (Elysia, Express, Fastify, and anything else that runs as a plain HTTP server) deploy with `--framework bun --entry <server-file>`. They get no framework-specific handling: the server must bind `0.0.0.0`, listen on the deployed port, and bundle any files it reads at runtime.
+- `app build --build-type` accepts `auto`, `bun`, `nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, and `custom`.
 - `app run --build-type` accepts `auto`, `bun`, and `nextjs`.
 - Use `--entry` for Bun, or whenever detection needs a hand.