feat(prisma-compute): teach agents the CLI feedback command

prisma-compute/SKILL.md

@@ -4,7 +4,7 @@ description: Prisma Compute deployment and hosting guide. Use whenever the user
 license: MIT
 metadata:
   author: prisma
-  version: "1.3.1"
+  version: "1.4.0"
 ---
 
 # Prisma Compute
@@ -42,7 +42,7 @@ Use this skill for:
 - Creating or updating a typed `prisma.compute.ts` deploy config
 - Deciding whether a framework is Compute-ready
 - Debugging `create-prisma --deploy`, `compute:deploy`, or `app deploy`
-- Managing Compute app logs, deployments, environment variables, branches, and domains
+- Managing Compute app logs, deployments, environment variables, and domains, and listing platform branches (`branch list`; there are no branch create/remove commands)
 - Inspecting GitHub/Console build logs and GitHub push-to-deploy status
 - Running non-interactive deploys with browser auth, multiple stored workspaces, or Prisma service tokens
 - Switching, selecting, listing, or logging out local Prisma Platform workspaces for `@prisma/cli`
@@ -120,6 +120,7 @@ Use this skill for:
 ### 5. Typed Compute Config
 
 - `config-optional-simple-app` - `prisma.compute.ts` is not required to deploy a normal single app; use flags when there is no durable config.
+- `config-init-formalizer` - Generate a fresh config with `bunx @prisma/cli@latest init`: it detects the framework, pins name/framework/httpPort (plus entry for Bun/Hono), and offers the Project link. `--format json` writes a dependency-free `prisma.compute.json` instead. `init` refuses when any config already exists, never scaffolds code, and never deploys.
 - `config-use-prisma-compute-ts` - Put reusable deploy defaults in `prisma.compute.ts` with `defineComputeConfig`, not in `prisma.config.ts`.
 - `config-app-vs-apps` - Use `app` for a single deploy target and `apps` for monorepos or multi-app repos; define exactly one.
 - `config-monorepo-roots` - For monorepos, use `prisma.compute.ts` to declare app targets, roots, framework defaults, entrypoints, ports, and env inputs.
@@ -141,13 +142,15 @@ Use this skill for:
 
 ### 7. Deploy Operations
 
-- `deploy-prod-intent` - Use `--prod --yes` only when the user intends a production deploy.
+- `deploy-prod-intent` - Use `--prod --yes` only when the user intends a production deploy. The first production deploy of an App auto-promotes without `--prod`; the flag gates subsequent production-branch deploys.
+- `deploy-no-promote` - Use `app deploy --no-promote` for build-then-verify: it builds a candidate reachable at its own URL without touching the live deployment, promoted later with `app promote <deployment-id>`.
 - `deploy-github-default-branch` - When a Compute app is connected to GitHub push-to-deploy, a merge to the default branch is the production deploy path; check deployment records or GitHub check runs instead of telling users to redeploy the merged PR branch or run a default-branch preview deploy.
 - `deploy-build-logs` - Use `@prisma/cli build logs <build-id>` for GitHub/Console build output. Use `app logs` for runtime deployment logs; the two ids are different.
 - `deploy-noninteractive-auth` - Non-interactive deploys need either the correct active stored OAuth workspace or a supported service token env var; never print the token.
 - `deploy-json-for-agents` - Use `--json --no-interactive` for scripts and agent-readable output.
 - `deploy-create-project` - Use `--create-project <name>` only when the user wants deploy to create and link a new project; it conflicts with `--project` and `PRISMA_PROJECT_ID`.
 - `deploy-ops-targets` - App show/open/logs/list-deploys/promote/rollback/remove and domain commands can also accept `[app]` targets from `prisma.compute.ts`.
+- `deploy-report-cli-bugs` - When a `@prisma/cli` command crashes (`UNEXPECTED_ERROR`) or fails in a way you cannot resolve, report it with `bunx @prisma/cli@latest feedback "<command>: <error summary>"`. Crash envelopes in `--json` include the exact pre-filled command in `nextActions`; run it as-is. Reports are anonymous and carry only the message plus CLI, node, and OS versions; never include secrets, URLs with credentials, or user data in the message.
 
 ### 8. SDK and API
 

prisma-compute/references/app-deploy-cli.md

@@ -179,8 +179,17 @@ bunx @prisma/cli@latest database remove db_123 --confirm db_123
 bunx @prisma/cli@latest database connection list db_123 --json
 bunx @prisma/cli@latest database connection create db_123 --name readonly
 bunx @prisma/cli@latest database connection remove conn_123 --confirm conn_123
+bunx @prisma/cli@latest database connection rotate conn_123 --confirm conn_123
+bunx @prisma/cli@latest database usage db_123 --json
+bunx @prisma/cli@latest database backup list db_123 --json
+bunx @prisma/cli@latest database restore db_123 --backup bkp_123 --confirm db_123
+bunx @prisma/cli@latest project rename new-name --project proj_123
+bunx @prisma/cli@latest project transfer proj_123 --to-workspace wksp_456 --confirm proj_123
+bunx @prisma/cli@latest project remove proj_123 --confirm proj_123
 ```
 
+Destructive and ownership-changing commands (`remove`, `restore`, `transfer`, `connection rotate`) require exact `--confirm <id>`; `--yes` is not enough.
+
 Git integration connects a Project to a GitHub repository. Console-side GitHub import can create a Compute app and trigger push-to-deploy for the connected repository, including default-branch production deploys. The CLI `git connect` command is setup, not a local deploy command; use `app deploy` for explicit CLI deploys.
 
 For GitHub-driven deploys, inspect the Console/build-runner state, deployment records, build logs, or the `Prisma Compute Deploy` GitHub check run instead of assuming local CLI output exists. The build runner can perform branch-aware database/env wiring: a preview branch with a Prisma schema and no `DATABASE_URL` can get a branch-scoped preview database, while production can wire a missing `DATABASE_URL` template from an existing ready database. GitHub check runs are the guided feedback path; do not promise Vercel-style PR comments.
@@ -229,17 +238,21 @@ Deploy with prompts:
 bunx @prisma/cli@latest app deploy
 ```
 
-Agent/script-friendly deploy:
+Agent/script-friendly deploy (do not assume production; add `--prod --yes` only when the user intends a production deploy, and note the first production deploy of an App auto-promotes without `--prod`):
 
 ```bash
 bunx @prisma/cli@latest app deploy \
   --json \
   --no-interactive \
-  --prod \
-  --yes \
   --env .env
 ```
 
+Build-then-verify path for CI: `--no-promote` builds a candidate deployment without changing the live one; it is reachable at its own candidate URL and promoted later with `app promote <deployment-id>`:
+
+```bash
+bunx @prisma/cli@latest app deploy --no-promote --json --no-interactive
+```
+
 For preview branches, omit `--prod` unless the user explicitly intends a production deploy:
 
 ```bash

prisma-compute/references/compute-config.md

@@ -6,6 +6,12 @@ Use this reference when creating or updating `prisma.compute.ts`, especially for
 
 For monorepos or multi-app repositories, use `prisma.compute.ts`: it is the practical way to tell Compute which app target lives at which `root` and which framework/entry/env defaults belong to each target.
 
+## Generating a Config with `init`
+
+Prefer `bunx @prisma/cli@latest init` over hand-writing a fresh single-app config. It detects the framework from the same registry deploy uses, pins `name`, `framework`, and `httpPort` (plus `entry` for Bun and Hono), previews every value with its source, offers the `@prisma/compute-sdk` devDependency for editor types, and offers the Project link. Useful flags: `--framework`, `--entry`, `--http-port`, `--name`, `--no-link`, `--json`.
+
+`--format json` writes a dependency-free static `prisma.compute.json` instead of the TypeScript config; a later explicit `init --format ts` converts it in place when the config needs to become programmatic. `init` fails with `INIT_CONFIG_EXISTS` when any compute config already exists, never scaffolds application code, and never deploys. Multi-app monorepo configs are still written by hand.
+
 ## File Names and Discovery
 
 The canonical file is `prisma.compute.ts`. The loader also accepts:
@@ -15,11 +21,14 @@ prisma.compute.mts
 prisma.compute.js
 prisma.compute.mjs
 prisma.compute.cjs
+prisma.compute.json
 ```
 
+`prisma.compute.json` is the static, dependency-free variant of the same config; it is discovered and loaded like the others.
+
 Keep exactly one compute config file in a directory. If multiple names exist together, the CLI reports `COMPUTE_CONFIG_INVALID`.
 
-The CLI searches from the invocation directory up to the repository or workspace boundary. Boundaries include `.git`, `pnpm-workspace.yaml`, `bun.lock`, or `package.json#workspaces`. Config-relative paths such as `root` and `env.file` resolve from the config file directory. `--env` flag paths still resolve from the invocation directory.
+The CLI searches from the invocation directory up to the repository or workspace boundary. Boundaries include `.git`, `pnpm-workspace.yaml`, `bun.lock`, `bun.lockb`, or `package.json#workspaces`. Config-relative paths such as `root` and `env.file` resolve from the config file directory. `--env` flag paths still resolve from the invocation directory.
 
 When a config is discovered, its directory becomes the Compute project directory for local state: `.prisma/local.json` and `.prisma/cli/state.json` live beside that config, not necessarily inside the app root.
 
@@ -47,7 +56,7 @@ Define exactly one of:
 - `app` for a single deploy target
 - `apps` for a monorepo or multi-app repository
 
-Do not define both, and do not add unrelated top-level keys.
+Do not define both. Besides `app`/`apps`, the only other allowed top-level key is `region`: a project-level default region applied when deploy creates new apps, overridable per app and by `--region`.
 
 ## App Fields
 
@@ -115,7 +124,7 @@ export default defineComputeConfig({
 
 `build.entrypoint` is relative to `build.outputDirectory` when an output directory is set. For Bun/Hono configs without an output directory, an entrypoint-backed build can supply the source entrypoint. Do not set both `entry` and `build.entrypoint` unless they describe the same file.
 
-`build` applies to frameworks whose build settings are configurable by Compute, such as `nextjs`, `hono`, `tanstack-start`, `custom`, and `bun`. Nuxt, Astro, and NestJS use their framework strategy output and reject a config `build` block.
+A config `build` block is accepted for every supported framework: the config-backed build types are `nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, `custom`, and `bun` (`hono` builds through the `bun` strategy). Only `custom` requires one (`build.outputDirectory` and `build.entrypoint`); for the others it overrides inferred build settings.
 
 ## Monorepos and Multi-App Repos
 

prisma-compute/references/frameworks.md

@@ -25,7 +25,7 @@ Auto-detection:
 - Nuxt: `nuxt.config.*` or `nuxt` dependency
 - Astro: `astro.config.*` or `astro` dependency
 - Hono: `hono` dependency
-- NestJS: `@nestjs/core` dependency
+- NestJS: `nest-cli.json` or `@nestjs/core` dependency
 - TanStack Start: `@tanstack/react-start` or `@tanstack/solid-start`
 - Custom artifact: explicit `framework: "custom"` plus `build.outputDirectory` and `build.entrypoint` in `prisma.compute.ts`
 - Bun: explicit `--entry <path>` or `--framework bun`
@@ -37,10 +37,10 @@ If detection is ambiguous, set `framework` in `prisma.compute.ts` or pass a supp
 | App shape | Deploy command shape | Auto-detected | Required output/entry | Notes |
 |-----------|----------------------|---------------|-----------------------|-------|
 | Next.js | `--framework nextjs` | Yes | standalone `server.js` output | Requires `output: "standalone"` |
-| Nuxt | `--framework nuxt` | Yes | `.output/server/index.mjs` | CLI owns framework build output; do not add a config `build` block |
-| Astro | `--framework astro` | Yes | standalone Node server artifact | CLI owns framework build output; do not add a config `build` block |
+| Nuxt | `--framework nuxt` | Yes | `.output/server/index.mjs` | Framework strategy supplies build defaults; a config `build` block is optional |
+| Astro | `--framework astro` | Yes | standalone Node server artifact | Framework strategy supplies build defaults; a config `build` block is optional |
 | Hono | `--framework hono` | Yes | Bun entry from `main`, `module`, `--entry`, or `src/index.ts` | Usually fixed port `8080` in generated config/scripts |
-| NestJS | `--framework nestjs` | Yes | NestJS server artifact | Omit host or bind to `0.0.0.0`; do not add a config `build` block |
+| NestJS | `--framework nestjs` | Yes | NestJS server artifact | Omit host or bind to `0.0.0.0`; a config `build` block is optional |
 | TanStack Start | `--framework tanstack-start` | Yes | `.output/server/index.mjs` | Requires Nitro node output |
 | Custom artifact | config-backed `framework: "custom"` | No | configured `build.outputDirectory` and `build.entrypoint` | Use for prebuilt/custom-built Node artifacts |
 | Bun / plain server | `--framework bun --entry <path>` | With explicit entry | server entrypoint | Use for Elysia and custom HTTP servers |
@@ -52,7 +52,7 @@ If detection is ambiguous, set `framework` in `prisma.compute.ts` or pass a supp
 
 `app run --build-type` is local-dev oriented and supports `auto`, `bun`, and `nextjs`. It streams the local dev server and is not proof that the deployed app is reachable through public ingress.
 
-`prisma.compute.ts` can set framework, entrypoint, HTTP port, env inputs, app root, region, and build settings. Config `build` blocks apply only where Compute consumes committed settings: `nextjs`, `hono`, `tanstack-start`, `custom`, and `bun`. The CLI rejects `build` blocks for `nuxt`, `astro`, and `nestjs` because their framework build paths are owned by the framework strategy.
+`prisma.compute.ts` can set framework, entrypoint, HTTP port, env inputs, app root, region, and build settings. A config `build` block is accepted for every supported framework; all build types are config-backed (`nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, `custom`, `bun`; `hono` builds through the `bun` strategy). For Nuxt, Astro, and NestJS the framework strategy supplies the default build command and output, so a `build` block is optional and normally unnecessary, but it overrides those defaults when present. Only `custom` requires one.
 
 Config snippets below assume:
 
@@ -64,7 +64,7 @@ import { defineComputeConfig } from "@prisma/compute-sdk/config";
 
 Compute needs a server process:
 
-- It must listen on the deployed HTTP port. `@prisma/cli app deploy` defaults to HTTP `3000` unless `--http-port` is passed.
+- It must listen on the deployed HTTP port. `@prisma/cli app deploy` defaults to the framework's default HTTP port (3000 for most frameworks, 4321 for Astro) unless `--http-port` is passed.
 - It must bind on all interfaces. Do not hard-code `localhost` or `127.0.0.1` for a deployed server; use `0.0.0.0`, `server.host: true`, or the framework equivalent.
 - It must have a deployable entrypoint or recognized framework output.
 - It must not rely on a preview-only command such as `vite preview`.
@@ -157,11 +157,11 @@ export default defineComputeConfig({
 
 Project expectations:
 
-- dependency detection uses `@nestjs/core`; pass `--framework nestjs` when the dependency graph is unusual
+- detection uses `nest-cli.json` or the `@nestjs/core` dependency; pass `--framework nestjs` when neither signal is present
 - `src/main.ts` or the compiled runtime must start an HTTP server
 - read `process.env.PORT` and default to the same port used by `--http-port`
 - omit the host argument in `app.listen(port)` or pass `"0.0.0.0"`; do not pass `"localhost"` or `"127.0.0.1"`
-- do not add a `build` block for NestJS in `prisma.compute.ts`; the Compute framework strategy owns the build/output path
+- a `build` block is optional for NestJS; the framework strategy supplies the build/output defaults, and a committed `build` block overrides them
 - use `app build --build-type nestjs` for a Compute artifact check; `app run --build-type nestjs` is not supported, so use the Nest dev server locally
 
 Example runtime shape:
@@ -234,7 +234,7 @@ export default defineComputeConfig({
 });
 ```
 
-Nuxt uses Nitro output at `.output/server/index.mjs`. Keep the Nitro preset compatible with a Node server runtime. Do not add a `build` block for Nuxt in `prisma.compute.ts`; the Compute framework strategy owns the build command and output.
+Nuxt uses Nitro output at `.output/server/index.mjs`. Keep the Nitro preset compatible with a Node server runtime. A `build` block is optional for Nuxt: the framework strategy supplies the build command and output, and a committed `build` block overrides them.
 
 ## Astro
 
@@ -269,7 +269,7 @@ export default defineConfig({
 })
 ```
 
-Do not add a `build` block for Astro in `prisma.compute.ts`; the Compute framework strategy owns the build command and output.
+A `build` block is optional for Astro: the framework strategy supplies the build command and output, and a committed `build` block overrides them.
 
 ## Bun, Elysia, and Plain Source Servers
 

prisma-compute/references/sdk-api.md

@@ -66,7 +66,7 @@ if (result.isOk()) {
 }
 ```
 
-SDK methods return `Result<T, E>`. Check `isOk()` or `isErr()` instead of assuming errors throw. Deploy results expose app/deployment vocabulary: `appId`, `appName`, `deploymentId`, `deploymentEndpointDomain`, `appEndpointDomain`, `promoted`, and `resolvedConfig`.
+SDK methods return `Result<T, E>`. Check `isOk()` or `isErr()` instead of assuming errors throw. Deploy results expose app/deployment vocabulary including `appId`, `appName`, `projectId`, `region`, `deploymentId`, `deploymentEndpointDomain`, `appEndpointDomain`, `promoted`, `previousDeploymentId`, `previousDeploymentAction`, and `resolvedConfig`.
 
 ## SDK Build Strategies
 
@@ -118,7 +118,7 @@ Low-level public routes use App/Deployment names:
 
 Internal compatibility aliases may still appear in code. Prefer App/Deployment names in new docs, skills, and automation.
 
-Environment variables are not embedded directly in the low-level deployment create payload. They resolve from the app's attached Branch. Use project/environment-variable APIs or CLI env commands to write env vars first, and keep the branch name consistent across app creation, database creation, and env writes.
+Environment variables are not embedded directly in the low-level deployment create payload. The attached branch's role selects their scope: a preview branch resolves branch-scoped vars, while a production branch (or no branch) resolves project-scoped production vars. Use project/environment-variable APIs or CLI env commands to write env vars first, and keep the branch name consistent across app creation, database creation, and env writes.
 
 When using the CLI alongside SDK automation:
 

prisma-compute/references/troubleshooting.md

@@ -423,3 +423,13 @@ bunx @prisma/cli@latest build logs <build-id> --json
 Use `build logs` for build output keyed by a Build id from a GitHub check run, Console build page, or Management API build record. Use `app logs` for runtime logs keyed by the current app deployment or a deployment id.
 
 Summarize relevant errors. Do not paste secrets.
+
+## Report Unresolved CLI Issues
+
+When a CLI failure survives the checks above, or a command crashes with `UNEXPECTED_ERROR`, report it to the Prisma team:
+
+```bash
+bunx @prisma/cli@latest feedback "app deploy crashed: <first error line>"
+```
+
+Crash output points here on its own: human mode prints a `Tell us what happened:` hint, and `--json` crash envelopes carry the exact pre-filled command as a `recover` entry in `nextActions`; prefer running that command verbatim. Feedback is anonymous and attaches only the CLI version, node version, and OS platform/arch. Do not put secrets, connection URLs, or tokens in the message.