Merge branch 'refactor/composer-api-changes' of github.com:prisma/web into refactor/composer-api-changes

Author: tylerhogarth

apps/docs/content/docs/(index)/full-stack-tutorial.mdx

@@ -6,7 +6,7 @@ metaTitle: "Tutorial: the full Prisma stack"
 metaDescription: Compose an app with Prisma Composer, model data with Prisma 8, run it on a local Prisma Postgres, then deploy app and database to Prisma Compute with one command.
 ---
 
-This tutorial takes you through the whole recommended stack in one sitting. [Prisma Composer](/composer) declares your app: its services, its databases, and how they connect. [Prisma 8](/v8) types your data. [Prisma Postgres](/postgres) stores it, locally while you develop and on the platform when you deploy. One declaration drives everything: the same `module.ts` runs the app on your machine and deploys it to [Prisma Compute](/compute). About 15 minutes.
+This tutorial takes you through the whole recommended stack in one sitting. [Prisma Composer](/composer) declares your app: its services, its databases, and how they connect. [Prisma 8](/v8) types your data. [Prisma Postgres](/postgres) stores it, locally while you develop and on the platform when you deploy. One declaration drives everything: the same `module.ts` runs the app on your machine and deploys it to [Prisma Compute](/compute). Plan on about 15 minutes.
 
 It uses the `hono` template so you get a small API you can verify with curl at every step. The same journey works for the other templates; the [framework guides](/guides/v8) cover each one.
 
@@ -30,8 +30,6 @@ Create a new Hono API composed with Prisma Composer and Prisma 8, run it locally
 3. Build and run locally: `npm run build`, then `npx prisma@next dev module.ts`. This provisions a local Prisma Postgres database and applies the contract; no DATABASE_URL is needed. Sample users are seeded on the app's first query. Verify the local URL that `dev` prints: its /users endpoint returns the seeded users.
 4. Deploy: check `npx prisma@next auth whoami`; if I am not signed in, stop and ask me to run `npx prisma@next auth login` (it opens a browser). Capture the baseline migration first with `npx prisma@next migration plan --name init` and note the migration directory it writes. Then run `npx prisma@next deploy module.ts` and verify the live URL's /users endpoint with curl. The deploy creates the project and provisions the database from the module declaration; do not pass a DATABASE_URL.
 5. Evolve the schema: add `role String @default("member")` to the User model in `src/prisma/contract.prisma`, run `npx prisma@next contract emit`, add `"role"` to the typed select and the returned object in `src/prisma/users.ts`, and plan the migration with `npx prisma@next migration plan --name add-user-role --from <the init migration directory>`. Then run `npm run build` and `npx prisma@next deploy module.ts` again, and verify the live /users now returns `role: "member"` with the same createdAt values as before.
-
-Run the CLI directly as above; do not use the scaffold's `deploy` and `dev:composer` npm scripts, which still call the removed `composer` subcommand.
 ```
 
 </AgentPrompt>
@@ -50,7 +48,7 @@ Answer the prompts for contract authoring style and package manager, then enter
 cd my-app
 ```
 
-If you work with a coding agent, run [`npx prisma@next init`](/cli/v8/init) once. It installs the [Prisma agent skills](/ai/tools/skills) that ship inside the installed Prisma packages and adds a postinstall hook that keeps them matching the versions in use; see [`skills`](/cli/v8/skills).
+If you work with a coding agent, run [`npx prisma@next init`](/cli/v8/init) once. The scaffold has already synced the [Prisma agent skills](/ai/tools/skills) that ship inside its Prisma packages and added the `postinstall` hook that keeps them current, so on a fresh scaffold `init` confirms that setup and reports each step as already done. It is still worth running, because it is the command that repairs the setup after you upgrade a Prisma package. See [`skills`](/cli/v8/skills).
 
 ## 2. The Composer app
 
@@ -114,7 +112,7 @@ npx prisma@next dev module.ts
 
 `dev` provisions a local Prisma Postgres database, applies the contract to it, starts the service, and prints the app's local URL when everything is ready. No account, credentials, or connection string are involved; see [Local development](/local-development) for how the local platform works.
 
-Sample users are seeded automatically the first time the app queries the database. Confirm the API serves the seeded rows (use the port `dev` printed):
+Sample users are seeded automatically the first time the app queries the database. Confirm the API serves the seeded rows. `dev` picks a free port and prints the URL, so use the one it printed if it differs from the `3000` shown here:
 
 ```bash
 curl http://localhost:3000/users
@@ -128,7 +126,7 @@ curl http://localhost:3000/users
 ]
 ```
 
-Prefer the framework's own dev server? `npm run dev` runs it directly. Direct mode is not managed by Composer, so it needs a database of your own in `DATABASE_URL`. Create one inside your project with the CLI:
+If you prefer the framework's own dev server, `npm run dev` runs it directly. Composer does not manage that mode, so the app needs a database of your own in `DATABASE_URL`. Create one inside your project with the CLI:
 
 ```npm
 npx prisma@next auth login
@@ -161,7 +159,7 @@ npm run build
 npx prisma@next deploy module.ts
 ```
 
-Composer creates a project named after your module, provisions the Prisma Postgres database declared in `module.ts`, wires it to the service, and starts the app. There is nothing to configure and no environment file to pass: the deployed database comes from the declaration, exactly like the local one did. The deploy finishes by printing your app's topology and its public URL:
+Composer creates a project named after your module, provisions the Prisma Postgres database declared in `module.ts`, wires it to the service, and starts the app. There is nothing to configure and no environment file to pass, because the deployed database comes from the declaration exactly as the local one did. When everything is up, the deploy prints what it made, each part of your app next to the platform resource it became, along with the public URL:
 
 ```text no-copy
 my-app
@@ -170,9 +168,13 @@ my-app
               https://xyz.ewr.prisma.build
 ```
 
-:::note
+:::warning[The module name must be unique in your workspace]
 
-The scaffold's `npm run deploy` and `npm run dev:composer` scripts still call the CLI's former `composer` subcommand, which the current release candidate removed. Run `npx prisma@next deploy module.ts` and `npx prisma@next dev module.ts` directly until the template catches up.
+`deploy` looks the module name up in your workspace and reuses an existing project with that name rather than creating another. If you have deployed a `my-app` before, the deploy stops with `HostedStateBootstrapError` and names a project id you did not choose. Deploy under a different name with `--name`, or rename the module in `module.ts`:
+
+```npm
+npx prisma@next deploy module.ts --name my-app-tutorial
+```
 
 :::
 
@@ -182,7 +184,7 @@ The scaffold's `npm run deploy` and `npm run dev:composer` scripts still call th
 curl https://xyz.ewr.prisma.build/users
 ```
 
-The same three users come back, now served from production next to your database, seeded on the deployed app's first query. Re-deploying is idempotent: build again, deploy again, and the platform applies the difference. That includes removals: your module is the source of truth, so deleting a provision from `module.ts` and deploying again removes the resource from the platform. See [Removing resources](/composer/deploying#removing-resources).
+The same three users come back, now served from production next to your database, seeded on the deployed app's first query. Re-deploying is idempotent: build again, deploy again, and the platform applies only the difference. That includes removals, because your module is the source of truth: delete a provision from `module.ts`, deploy again, and the resource disappears from the platform. See [Removing resources](/composer/deploying#removing-resources).
 
 ## 7. Evolve the data model
 
@@ -208,7 +210,7 @@ npx prisma@next contract emit
 npx prisma@next migration plan --name add-user-role --from <timestamp>_init
 ```
 
-`--from` names the migration you are building on. Teams point a [ref](/cli/v8/migration-ref) named `db` at the applied migration instead, so plans chain automatically without naming directories.
+`--from` names the migration you are building on, and here it is required. Without it, `migration plan` starts from the [ref](/cli/v8/migration-ref) named `db`. `db init` sets that ref when you initialize a database directly, but a Composer deploy never does, so a plan without `--from` in this project would start from an empty database and describe every table again. Teams that want plans to chain on their own point the ref at the applied migration once (`migration ref set db <timestamp>_init`) and advance it after each deploy.
 
 The plan is your change and nothing else. Review it like any other diff, with [`migration show`](/cli/v8/migration-show) or by reading the generated package:
 
@@ -224,7 +226,7 @@ const users = await db.orm.public.User.select("id", "email", "username", "name",
 
 This is the Prisma 8 loop: the contract is the source of truth, the emit step regenerates the types, and the compiler points at every query the change touches.
 
-Verify locally first if you like (`npm run build`, then `npx prisma@next dev module.ts`; the local database picks up the contract change on start). Then build and deploy again:
+If you want to see the change on your machine first, run `npm run build` and `npx prisma@next dev module.ts` again; the local database applies the new migration on start and `/users` returns the role there too. Then build and deploy again:
 
 ```npm
 npm run build
@@ -243,6 +245,14 @@ curl https://xyz.ewr.prisma.build/users
 ]
 ```
 
+## 8. Clean up (optional)
+
+The project keeps running until you remove it. Deleting it removes the service and the database, so the command asks you to repeat the project id (find it with `npx prisma@next project list`):
+
+```npm
+npx prisma@next project delete <project-id> --confirm <project-id>
+```
+
 ## Next steps
 
 - [Learn Composer](/composer/getting-started): typed contracts between services, databases, storage, and scheduled jobs.

apps/docs/content/docs/(index)/index.mdx

@@ -91,7 +91,7 @@ Add Prisma 8 to this existing project.
 
 This flow is for PostgreSQL. If the project uses MongoDB, follow https://www.prisma.io/docs/v8/add-to-existing-project/mongodb.md instead; for other databases, stop and tell me.
 
-1. Run `npx prisma@next orm init`. It writes `prisma.config.ts`, a starter contract and `db.ts` under `src/prisma/`, and installs Prisma 8 skills for you.
+1. Run `npx prisma@next orm init --yes --target postgres --authoring psl` (the flags are required when the CLI cannot prompt). It writes `prisma.config.ts`, a starter contract and `db.ts` under `src/prisma/`, and installs dependencies. Then run `npx prisma@next skills sync` to install the Prisma 8 skills; `orm init` may end with `CLI.INIT_SKILL_INSTALL_FAILED`, which the sync repairs.
 2. Set `DATABASE_URL` in `.env` to my database. If I did not give you one, create a Prisma Postgres database with `npx create-db@latest`, put its connection string in `.env`, and show me the claim URL it prints so I can keep the database.
 3. If the database already has tables, infer the contract from it: `npx prisma@next contract infer`, then `npx prisma@next contract emit`, then sign it with `npx prisma@next db sign`. If the database is empty, keep the starter contract and run `npx prisma@next db init`.
 4. Write one query with the generated `db` client in an existing code path, run it, and show me the returned rows.

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

@@ -201,11 +201,11 @@ npm run build
 npx prisma@next deploy module.ts
 ```
 
-The CLI creates a project named after your root module, provisions the services on Compute and any databases on Prisma Postgres, wires the dependencies, and starts everything.
+The CLI creates a project named after your root module, provisions the services on Compute and any databases on Prisma Postgres, wires the dependencies, and starts everything. The project name has to be unique in your workspace: an existing project with the same name is reused rather than duplicated, and if it holds resources from an earlier deploy the command stops with `HostedStateBootstrapError`. Deploy under another name with `--name <unique-name>` when that happens.
 
 ## 3. Verify the deployment
 
-A deploy finishes by printing your app's topology: each service, the platform resource it became, and its public URL:
+A deploy finishes by printing what it made: each service, the platform resource it became, and its public URL:
 
 ```text no-copy
 my-app
@@ -231,7 +231,7 @@ npx prisma@next deploy module.ts --stage staging  # a persistent staging environ
 npx prisma@next deploy module.ts --stage 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. See [Deploying](/composer/deploying) for CI, deploy state, and teardown in full.
+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.
 
 ## Hand it to your agent
 

apps/docs/content/docs/(index)/v8/getting-started.mdx

@@ -67,7 +67,7 @@ Add Prisma 8 to this existing project.
 
 This flow is for PostgreSQL. If the project uses MongoDB, follow https://www.prisma.io/docs/v8/add-to-existing-project/mongodb.md instead; for other databases, stop and tell me.
 
-1. Run `npx prisma@next orm init`. It writes `prisma.config.ts`, a starter contract and `db.ts` under `src/prisma/`, and installs Prisma 8 skills for you.
+1. Run `npx prisma@next orm init --yes --target postgres --authoring psl` (the flags are required when the CLI cannot prompt). It writes `prisma.config.ts`, a starter contract and `db.ts` under `src/prisma/`, and installs dependencies. Then run `npx prisma@next skills sync` to install the Prisma 8 skills; `orm init` may end with `CLI.INIT_SKILL_INSTALL_FAILED`, which the sync repairs.
 2. Set `DATABASE_URL` in `.env` to my database. If I did not give you one, create a Prisma Postgres database with `npx create-db@latest`, put its connection string in `.env`, and show me the claim URL it prints so I can keep the database.
 3. If the database already has tables, infer the contract from it: `npx prisma@next contract infer`, then `npx prisma@next contract emit`, then sign it with `npx prisma@next db sign`. If the database is empty, keep the starter contract and run `npx prisma@next db init`.
 4. Write one query with the generated `db` client in an existing code path, run it, and show me the returned rows.

apps/docs/content/docs/(index)/v8/index.mdx

@@ -50,7 +50,7 @@ If I have not told you which framework, stop and ask before scaffolding. Valid -
 3. From the project directory, apply the starter contract: `npm run db:init`. Sample users are seeded automatically on the app's first query; there is no separate seed script.
 4. Edit the starter contract under `src/prisma/` into a small schema for my use case, then run `npm run contract:emit` and plan and apply the migration: `npx prisma@next migration plan`, then `npx prisma@next db migrate --yes`. Migration planning diffs the emitted contract, so the emit step is required.
 5. Update the seed script under `src/prisma/` and the app routes to query the new schema, start `npm run dev` in the background (with `DATABASE_URL` exported), and verify with a request against the running app. For the `nest` template, if routes return 500s with `reading 'findAll'` in the logs, add explicit `@Inject()` tokens as shown in https://www.prisma.io/docs/guides/v8/frameworks/nestjs.md.
-6. Deploy with Prisma Compute. If the template is `svelte`, skip this step; Compute does not support SvelteKit yet. The scaffold declares the app for Prisma Composer in `module.ts` and `service.ts`, with the framework's build requirements (Next.js standalone output, Astro's node adapter, TanStack Start's Nitro build) already configured; the framework guide at https://www.prisma.io/docs/guides/v8/frameworks/[guide].md has the details, where [guide] is the template name except: template `next` → guide `nextjs`, `nest` → `nestjs`. Check `npx prisma@next auth whoami`. If I am not signed in, stop and ask me to run `npx prisma@next auth login`, because that step opens a browser. Then run `npm run build` followed by `npx prisma@next deploy module.ts`, and verify the deployed URL with curl. The deployed app provisions and seeds its own Prisma Postgres database; do not pass the local DATABASE_URL. Do not use the scaffold's `deploy` npm script, which still calls the removed `composer` subcommand.
+6. Deploy with Prisma Compute. If the template is `svelte`, skip this step; Compute does not support SvelteKit yet. The scaffold declares the app for Prisma Composer in `module.ts` and `service.ts`, with the framework's build requirements (Next.js standalone output, Astro's node adapter, TanStack Start's Nitro build) already configured; the framework guide at https://www.prisma.io/docs/guides/v8/frameworks/[guide].md has the details, where [guide] is the template name except: template `next` → guide `nextjs`, `nest` → `nestjs`. Check `npx prisma@next auth whoami`. If I am not signed in, stop and ask me to run `npx prisma@next auth login`, because that step opens a browser. Then run `npm run build` followed by `npx prisma@next deploy module.ts`, and verify the deployed URL with curl. The deployed app provisions and seeds its own Prisma Postgres database; do not pass the local DATABASE_URL. If the deploy fails with `HostedStateBootstrapError`, a project with the module's name already exists in my workspace; re-run the deploy with `--name <a unique name>`.
 
 Use the installed Prisma 8 skills and the current Prisma docs: https://www.prisma.io/docs/llms.txt (append `.md` to any docs URL for a markdown version).
 ```

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

@@ -25,7 +25,7 @@ npx prisma@next deploy module.ts --stage feat-auth
 
 | Flag | Description |
 | --- | --- |
-| `--name <name>` | Override the application name for this deploy. It defaults to the name of the exported application |
+| `--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: an existing project with the same name is reused, 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` |
 | `--build-id <id>` | Join the deploy record your CI already created rather than letting the target create one |
@@ -59,6 +59,8 @@ if (!result.ok) console.error(result.failure.message);
 
 Operations return `{ ok: true, value }` or `{ ok: false, failure }`. Failures come back as structured errors with a dotted `failure.code` and the same fix-naming `message` the CLI renders. The deploy engine's live output still streams to your process's stdio; the operations do not capture it.
 
+The operations authenticate with `PRISMA_SERVICE_TOKEN` and `PRISMA_WORKSPACE_ID` only. They do not read the session stored by `auth login`, so a script that runs fine next to the CLI's `deploy` fails under the control API with `environment variable PRISMA_WORKSPACE_ID is required` until both variables are exported.
+
 ## Next steps
 
 - [`dev`](/cli/v8/dev): run the same application locally, with no credentials.