docs(compute): add monorepo deployment guide

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

@@ -156,7 +156,7 @@ Make sure your project directory is a Git repository with a GitHub remote, then
 npx @prisma/cli@latest git connect
 ```
 
-`git connect` wires up the project this directory is linked to, which exists once you have deployed at least once. For monorepos and CI, see the [GitHub integration docs](/compute/github).
+`git connect` wires up the project this directory is linked to, which exists once you have deployed at least once. For a repository with several apps, see [Deploy a monorepo](/compute/monorepos). For integration details, see the [GitHub docs](/compute/github).
 
 ## Hand it to your agent
 
@@ -185,5 +185,6 @@ Notes for your agent:
 - [Branching](/compute/branching): how preview branches isolate work and map to your Git branches.
 - [Add environment variables](/compute/environment-variables) for configuration, secrets, and your database connection string.
 - [Deployments](/compute/deployments): promote, roll back, and inspect what you ship.
-- [GitHub integration](/compute/github): the full picture on deploy-on-push, monorepos, and cleanup.
+- [Deploy a monorepo](/compute/monorepos): configure, verify, and deploy several apps from one repository.
+- [GitHub integration](/compute/github): the full picture on deploy-on-push and cleanup.
 - [Read the full CLI getting-started guide](/compute/getting-started) for frameworks, project linking, and CI.

apps/docs/content/docs/compute/cli-reference.mdx

@@ -61,7 +61,7 @@ Manage apps and deployments for a project.
 | `app rollback`                | Roll back production to the previous deployment, without rebuilding       |
 | `app remove`                  | Remove the app from the current branch                                    |
 
-Promote and rollback switch the live endpoint between existing deployments; nothing is rebuilt, and env vars stay as resolved when each deployment was created. Most `app` commands also accept an optional `[app]` positional argument to pick a target from `prisma.compute.ts` when the config defines multiple apps.
+Promote and rollback switch the live endpoint between existing deployments; nothing is rebuilt, and env vars stay as resolved when each deployment was created. Most `app` commands also accept an optional `[app]` positional argument to pick a target from `prisma.compute.ts` when the config defines multiple apps. See [Deploy a monorepo](/compute/monorepos) for target setup and workflows.
 
 ### `app deploy` options
 

apps/docs/content/docs/compute/configuration.mdx

@@ -9,7 +9,7 @@ metaDescription: "Reference for the prisma.compute.ts file: declare your app's f
 `prisma.compute.ts` is an optional, committed file that declares what you deploy. [`app deploy`](/compute/cli-reference#app) already works with zero config (it detects your framework and builds), so reach for a config file when you want one of these:
 
 - **Reproducible deploys.** Pin the framework, port, and build settings so every deploy (yours, a teammate's, or [deploy-on-push](/compute/github)) does the same thing without re-passing flags.
-- **A monorepo.** Declare several apps in one repository and deploy them together, or one at a time.
+- **A monorepo.** [Declare several apps](/compute/monorepos) in one repository and deploy them together, or one at a time.
 - **Type safety.** Catch a typo'd field or an invalid framework in your editor, before you deploy.
 
 The file is read by `app deploy` and `app build`. It never selects your project, branch, or production; those stay explicit. It also does not configure a database; that stays on the [`--db` flag](/compute/cli-reference#app-deploy-options).
@@ -143,47 +143,7 @@ The config file's directory is treated as the project directory: the [`.prisma/l
 
 ## Monorepos
 
-Use `apps` instead of `app` to declare several apps in one repository, keyed by a target name:
-
-```ts title="prisma.compute.ts"
-import { defineComputeConfig } from "@prisma/compute-sdk/config";
-
-export default defineComputeConfig({
-  apps: {
-    api: {
-      root: "apps/api",
-      framework: "hono",
-      entry: "src/index.ts",
-    },
-    web: {
-      root: "apps/web",
-      framework: "nextjs",
-    },
-  },
-});
-```
-
-All the apps live in one project, deploying to the same branch. From here:
-
-- **Deploy everything** with a bare `app deploy`, which deploys every app in order. This is the default when no target is named or inferred:
-
-  ```npm
-  npx @prisma/cli@latest app deploy
-  ```
-
-- **Deploy one app** by naming its target, or by running from inside its `root` (the deepest matching root wins):
-
-  ```npm
-  npx @prisma/cli@latest app deploy api
-  ```
-
-  ```npm
-  cd apps/api && npx @prisma/cli@latest app deploy
-  ```
-
-When you deploy everything at once, per-app flags like `--framework` or `--entry` are rejected as ambiguous. Pass a target to apply them to one app. Project- and branch-level flags (`--branch`, `--db`, `--prod`, `--yes`) apply to the whole run.
-
-`app build` always targets a single app in a multi-app config. Unlike `deploy`, it has no all-apps form, so pass a target or run from inside the app's `root`.
+Use `apps` instead of `app` to declare several apps in one repository. Each map key is a CLI target, and every target accepts the same fields listed above. See [Deploy a monorepo](/compute/monorepos) for the complete config, directory layout, target selection, local builds, deploy-all behavior, and GitHub automation.
 
 ## How config and flags interact
 
@@ -199,7 +159,8 @@ A config that fails to load or validate stops the deploy before any remote work,
 
 ## What's next
 
+- [Deploy a monorepo](/compute/monorepos): configure, verify, and deploy several apps from one repository.
 - [CLI reference](/compute/cli-reference): every command, flag, and error code.
 - [Deploy your first app](/prisma-compute/deploy): the end-to-end quickstart.
 - [Environment variables](/compute/environment-variables): scoped configuration, secrets, and your database connection string.
-- [GitHub integration](/compute/github): deploy-on-push, including monorepos.
+- [GitHub integration](/compute/github): deploy-on-push and branch previews.

apps/docs/content/docs/compute/faq.mdx

@@ -57,7 +57,7 @@ No. Variables resolve at deploy time, so you need to redeploy for the app to pic
 
 ## How do I deploy from CI?
 
-Use a service token and explicit targets:
+Use a service token and name the remote project and app explicitly:
 
 ```bash
 PRISMA_SERVICE_TOKEN=... npx @prisma/cli@latest app deploy \
@@ -68,7 +68,7 @@ PRISMA_SERVICE_TOKEN=... npx @prisma/cli@latest app deploy \
   --no-interactive
 ```
 
-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.
+Passing every selector explicitly keeps the run self-contained; `--json` makes the result parseable, and `--no-interactive` turns any would-be prompt into a structured error. For multiple config targets in one repository, follow [Deploy a monorepo](/compute/monorepos).
 
 ## Why did my production deploy fail with `PROD_DEPLOY_REQUIRES_FLAG`?
 

apps/docs/content/docs/compute/github.mdx

@@ -56,20 +56,9 @@ Once a project is connected:
 
 Connecting doesn't deploy anything on its own; it wires up automation for *future* events. To deploy right now, run `app deploy` yourself.
 
-## CI and monorepos
+## Monorepos
 
-Auto-deploy handles monorepos that declare their apps in `prisma.compute.ts`: one pushed commit fans out into a targeted build per app. For custom pipelines, or anywhere you want full control, run the CLI directly with a service token and explicit targets:
-
-```bash
-PRISMA_SERVICE_TOKEN=... npx @prisma/cli@latest app deploy \
-  --project my-app \
-  --app web \
-  --branch "$GITHUB_HEAD_REF" \
-  --json \
-  --no-interactive
-```
-
-This keeps deploys deterministic and gives agents a structured result to read.
+A connected repository can deploy several Compute apps from each push. See [Deploy a monorepo](/compute/monorepos) for the root `prisma.compute.ts` config, build fan-out, target selection, and custom CI commands.
 
 ## What's not in beta
 

apps/docs/content/docs/compute/limitations.mdx

@@ -38,7 +38,7 @@ Prisma Compute is in [Public Beta](/console/more/feature-maturity#public-beta).
 ## GitHub
 
 - GitHub is the only supported provider, and a project connects to one repository.
-- Auto-deploy supports multiple apps declared in `prisma.compute.ts`: one push build fans out into a targeted build per app. CI with a service token remains available when you need full control.
+- Auto-deploy supports [multiple apps declared in a monorepo config](/compute/monorepos).
 - The webhook path is branch- and push-driven. There are no PR comments or PR status automation.
 
 ## Domains

apps/docs/content/docs/compute/meta.json

@@ -9,6 +9,7 @@
     "---Features---",
     "branching",
     "deployments",
+    "monorepos",
     "keeping-instances-awake",
     "image-transformations",
     "environment-variables",

apps/docs/content/docs/compute/monorepos.mdx

@@ -0,0 +1,181 @@
+---
+title: Monorepos
+description: Deploy several apps from one repository with a root-level Prisma Compute config.
+url: /compute/monorepos
+metaTitle: Deploy a monorepo | Prisma Compute
+metaDescription: Configure, build, and deploy multiple apps from a monorepo with prisma.compute.ts and Prisma Compute.
+---
+
+Prisma Compute can deploy several apps from one repository. Put one `prisma.compute.ts` at the repository root, declare each deployable app under `apps`, and use the app's key as its CLI target.
+
+Each target becomes a separate Compute app with its own deployments and URL. The targets share one Prisma project and deploy to the same branch, so a preview branch can contain your whole application.
+
+Before you start, install the monorepo's dependencies and complete the sign-in and project-linking steps in [Get started](/compute/getting-started). Run commands from the repository root unless a step says otherwise.
+
+## Example repository
+
+This guide uses a Next.js frontend and a Hono API:
+
+```text title="Repository structure"
+acme-shop/
+├── apps/
+│   ├── api/
+│   │   ├── src/index.ts
+│   │   └── package.json
+│   └── web/
+│       ├── app/
+│       ├── next.config.ts
+│       └── package.json
+├── package.json
+├── pnpm-workspace.yaml
+└── prisma.compute.ts
+```
+
+Your apps can use different supported frameworks and can depend on shared workspace packages. Each app must still have a working build from its configured root.
+
+## 1. Add the Compute config
+
+Create `prisma.compute.ts` at the monorepo root:
+
+```ts title="prisma.compute.ts"
+import { defineComputeConfig } from "@prisma/compute-sdk/config";
+
+export default defineComputeConfig({
+  apps: {
+    web: {
+      root: "apps/web",
+      framework: "nextjs",
+    },
+    api: {
+      root: "apps/api",
+      framework: "hono",
+      entry: "src/index.ts",
+      httpPort: 3000,
+    },
+  },
+});
+```
+
+Here, `web` and `api` are **target keys**. They identify the apps in CLI commands and become the deployed app names unless you set `name` explicitly.
+
+Paths have two different bases:
+
+- `root` is relative to `prisma.compute.ts`.
+- `entry` and build output paths are relative to that app's `root`.
+
+`httpPort` must match the port the deployed server listens on. A server you start yourself must also listen on `0.0.0.0`, not only `localhost`.
+
+The Next.js app in this example also enables standalone output:
+
+```ts title="apps/web/next.config.ts"
+export default { output: "standalone" };
+```
+
+The CLI can load this config without a local SDK installation. Install `@prisma/compute-sdk` as a root development dependency if you want editor autocomplete and type checking. See the [configuration reference](/compute/configuration) for every field, environment inputs, custom build settings, and the JSON config format.
+
+## 2. Verify every app locally
+
+Build each target from the repository root before deploying:
+
+```npm title="Terminal"
+npx @prisma/cli@latest app build web
+npx @prisma/cli@latest app build api
+```
+
+`app build` always builds one target. If you omit the target at the monorepo root, the CLI returns `COMPUTE_CONFIG_TARGET_REQUIRED` and lists the available targets.
+
+From inside a configured `root`, the CLI infers the target, so this builds `api` too:
+
+```npm title="Terminal"
+cd apps/api
+npx @prisma/cli@latest app build
+```
+
+If roots overlap, the deepest matching root wins. Prefer non-overlapping roots unless that behavior is intentional.
+
+## 3. Deploy one app
+
+Pass the target key as the positional argument:
+
+```npm title="Terminal"
+npx @prisma/cli@latest app deploy web
+```
+
+To deploy the API instead:
+
+```npm title="Terminal"
+npx @prisma/cli@latest app deploy api
+```
+
+You can also run the command from inside an app's `root` and omit the target:
+
+```npm title="Terminal"
+cd apps/web
+npx @prisma/cli@latest app deploy
+```
+
+:::warning
+
+The positional `web` in `app deploy web` selects `apps.web` from the config. `--app web` has a different purpose: it overrides the deployed app name. It does not select a config target.
+
+:::
+
+## 4. Deploy the whole monorepo
+
+When your current directory is not inside a configured app root, a bare deploy covers the whole config. With the example structure, run this from the monorepo root:
+
+```npm title="Terminal"
+npx @prisma/cli@latest app deploy
+```
+
+The CLI deploys every target in config order. Project-, branch-, database-, and production-level options apply to the whole run. For example, this deploys every app to the same preview branch:
+
+```npm title="Terminal"
+npx @prisma/cli@latest app deploy --branch feature/search
+```
+
+A deploy-all run rejects per-app overrides such as `--app`, `--framework`, `--entry`, `--http-port`, `--region`, `--env`, and `PRISMA_APP_ID`. Put stable per-app values in `prisma.compute.ts`, or select one target before using an override:
+
+```npm title="Terminal"
+npx @prisma/cli@latest app deploy api --env apps/api/.env.preview
+```
+
+Targets deploy in order and the run stops at the first failure. The error tells you which targets are already live, which target failed, and which targets were not attempted. Fix the failure and rerun the command to converge the repository.
+
+## Command summary
+
+| Goal | Run from the monorepo root |
+| --- | --- |
+| Build one app | `npx @prisma/cli@latest app build web` |
+| Deploy one app | `npx @prisma/cli@latest app deploy web` |
+| Deploy every app | `npx @prisma/cli@latest app deploy` |
+| Deploy every app to a preview branch | `npx @prisma/cli@latest app deploy --branch feature/search` |
+
+## Deploy on push with GitHub
+
+The [GitHub integration](/compute/github) reads the same root config. On each push, Prisma discovers the targets and starts one build per app. Each build uses its target's `root`, framework, entrypoint, port, region, and build settings.
+
+Connect the linked project once:
+
+```npm title="Terminal"
+npx @prisma/cli@latest git connect
+```
+
+For a custom CI pipeline, set `PRISMA_SERVICE_TOKEN` and `PRISMA_PROJECT_ID`, then name the config target positionally:
+
+```bash title="CI"
+PRISMA_SERVICE_TOKEN=... PRISMA_PROJECT_ID=... \
+  npx @prisma/cli@latest app deploy web \
+  --branch "${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" \
+  --json \
+  --no-interactive
+```
+
+Run one command per target when your pipeline needs independent jobs. Use a bare `app deploy` when one job should deploy the entire monorepo.
+
+## What to read next
+
+- [Configuration](/compute/configuration): all config fields and precedence rules.
+- [GitHub integration](/compute/github): deploy-on-push and preview branches.
+- [Environment variables](/compute/environment-variables): production, preview, and branch-specific values.
+- [Deployments](/compute/deployments): inspect, promote, and roll back deployments.