prisma
diff --git a/‎.claude/skills/docs-writer/SKILL.md‎
Lines changed: 23 additions & 0 deletions b/‎.claude/skills/docs-writer/SKILL.md‎
Lines changed: 23 additions & 0 deletions
diff --git a/‎apps/docs/content/docs/(index)/getting-started.mdx‎
Lines changed: 4 additions & 4 deletions b/‎apps/docs/content/docs/(index)/getting-started.mdx‎
Lines changed: 4 additions & 4 deletions
diff --git a/‎apps/docs/content/docs/(index)/index.mdx‎
Lines changed: 6 additions & 6 deletions b/‎apps/docs/content/docs/(index)/index.mdx‎
Lines changed: 6 additions & 6 deletions
@@ -64,6 +64,7 @@ A how-to gets the reader through a task. Two other types come up often. Same voi
 - List every parameter with type, whether it's required, and the default.
 - Give one runnable example per entry.
 - No narrative. The reader is scanning, not reading.
+- Order options the way readers need them: the common case first, then selection and targeting, then advanced or CI-specific behavior.
 
 ## Improving an existing page
 
@@ -154,6 +155,27 @@ Delete these on sight. They add length, not clarity.
 - **Em dashes**. Use a comma, colon, or period instead.
 - **Hype**: don't sell inside docs. The reader already chose the product; they want it to work.
 
+## Don't write like a model
+
+Model-drafted docs share habits a reviewer can spot in one pass. None of these is wrong in isolation; their density is what gives a page a synthetic voice. Check for each before finishing.
+
+- **Frontmatter echo**: the body's first sentence repeats the frontmatter `description` almost verbatim. The description summarizes the page for cards and search results; the opening orients the reader. Write them differently, and define the product once, not once per metadata field.
+- **Contrast slogans**: "X, not Y" constructions ("injected, not discovered", "built for agents, not just terminals", "refuses to guess"). One per page at most. A page of balanced contrasts reads like ad copy; state the behavior plainly instead.
+- **Absolute stacking**: "never", "every", "nothing", "always", "cannot drift" piling up across a page. Each absolute is a promise the product has to keep. Keep the ones you can verify and that the reader needs; describe what happens rather than asserting what can't.
+- **Exception-packed sentences**: one sentence carrying the normal case, an exception, its reason, the alternative, and a safety condition, held together by semicolons. One idea per sentence: state the default first ("By default, the command uses…"), then the exception as its own sentence ("In CI or other headless environments, set…"). A semicolon joining distinct ideas is usually two sentences.
+- **Manager-voice openers**: "`service` manages services…", "handles", "manages everything around". Lead with the user action or outcome ("Use `service` commands to manage…") and use concrete verbs: creates, stores, uses, selects, targets, deploys, builds.
+- **Coined shorthand**: compressed phrases invented mid-page ("local pin", "pick a target") instead of saying what actually happens. Spell out the relationship, and keep one consistent user-facing vocabulary: service, project, configuration, deployment, credentials.
+- **Implementation language**: internal detail that doesn't help the reader act ("the root node is `<entry>`'s default export"). Translate it into the behavior they observe ("the application exported as the default export from `<entry>`").
+- **Buried caveats**: a warning folded into a trailing clause. Turn it into a direct instruction: "The deploy command does not build your application. Run your build command before deploying."
+- **Confusable state left implicit**: when two things could be mixed up (local state vs committed configuration), contrast them directly: what is local, what is committed, and what each is used for.
+- **Mid-clause links**: a link dropped between unrelated clauses. Introduce it after the context it supports: "See [Deploying](…) for details."
+- **Definition cascade**: a landing page that defines every noun in identical rhythm ("An application is… A service is… A branch is…"). Define a term where the reader first needs it. If a glossary earns its place, keep it short and hand off to a page that goes deeper.
+- **Prose restating code**: after a code block, narrating what each line does. Explain only what the code can't show: why, or a non-obvious consequence.
+- **Triad reflex**: three-part lists everywhere ("reviewable, repeatable, and versioned"). Vary list length; cut members that don't earn their place.
+- **Exhaustive nav dumps**: a "What to read next" that lists every sibling page in the same grammatical form. Pick the two or three pages this reader most likely needs next; the sidebar already lists everything.
+
+The same applies to PR descriptions for docs changes: write a short reviewer-facing summary of what changed and why, and put validation details (commands run, environments used) in a collapsed section. Don't paste the working session's log.
+
 ## Voice
 
 - Calm and direct. The reader is mid-task, not browsing a landing page.
@@ -169,4 +191,5 @@ Before you finish, check:
 - [ ] Does each step say what it does before showing the command?
 - [ ] Is there a way to verify success at the end?
 - [ ] Did you cut every phrase from "Cut the slop"?
+- [ ] Did you check the page against every pattern in "Don't write like a model"?
 - [ ] Are product names and limitations accurate?
@@ -6,11 +6,11 @@ metaTitle: Prisma 7 getting started
 metaDescription: Choose the fastest Prisma 7 setup path. Quickstarts and existing-project guides for Prisma ORM 7, Prisma Postgres, and Prisma Compute, plus an agent prompt.
 ---
 
-Prisma 7 is the current generally available release of Prisma ORM, and `npx prisma@latest init` installs it. This page collects the Prisma 7 starting points: start a new project, add Prisma to an existing one, then deploy.
+Prisma 7 is the current generally available release of Prisma ORM. Install it with `npx prisma@latest init`. This page collects the Prisma 7 starting points: start a new project, add Prisma to an existing one, then deploy.
 
 :::note
 
-Starting a new project? [Prisma 8](/v8) is the recommended path for new apps. It is the next major version of Prisma ORM, now available as a Release Candidate. The [getting started page](/) covers it.
+Starting a new project? [Prisma 8](/v8) is the recommended path for new apps. It is the next major version of Prisma ORM, now available as a Release Candidate. To start with Prisma 8, see the [getting started page](/).
 
 :::
 
@@ -41,10 +41,10 @@ Once your app runs locally, [Prisma Compute](/compute) (currently in Public Beta
 
 1. Sign in with `npx @prisma/cli@latest auth login`.
 2. Run `npx @prisma/cli@latest app deploy` from your app directory to get a live URL, adding `--env .env` so environment variables like `DATABASE_URL` reach the deployment.
-3. `--env .env` applies to that one deployment. Persist variables for future deploys with `npx @prisma/cli@latest project env add --file .env --role production`; see [environment variables](/compute/environment-variables).
+3. `--env .env` applies to that one deployment. Persist variables for future deployments with `npx @prisma/cli@latest project env add --file .env --role production`. See [environment variables](/compute/environment-variables).
 4. Keep deploying from the CLI, or [connect GitHub](/compute/github) to deploy on push.
 
-The [deploy guide](/prisma-compute/deploy) covers build settings, frameworks, and troubleshooting.
+`app deploy` is part of the earlier beta CLI (`@prisma/cli@latest`). The Prisma 8 RC CLI (`prisma@next`) that the [Compute docs](/compute) describe deploys through a git push, the Console, or [Prisma Composer](/composer) instead. Both CLIs talk to the same platform. For the git-push path, follow the [deploy quickstart](/prisma-compute/deploy).
 
 ## Use with your agent
 
 
@@ -51,7 +51,7 @@ If I have not told you which framework, stop and ask before scaffolding. Valid -
 
 1. Scaffold the app: `npx create-prisma@next create my-app --template [framework] --provider postgres --prisma-postgres --yes`. The `--prisma-postgres` flag provisions a Prisma Postgres database. If I give you a connection string, pass `--database-url "<url>"` instead of `--prisma-postgres`.
 2. From the project directory, apply the starter contract and seed: `npm run db:init`, then `npm run db:seed`. If seeding fails with `Cannot read properties of undefined (reading 'where')`, change `db.orm.User` to `db.orm.public.User` in `src/prisma/seed.ts`, `src/prisma/users.ts`, and any route files that query `db.orm`, then rerun.
-3. 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/cli@next migration plan`, then `npx @prisma/cli@next migrate --yes`. Migration planning diffs the emitted contract, so the emit step is required.
+3. 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 migrate --yes`. Migration planning diffs the emitted contract, so the emit step is required.
 4. Update the seed script and the app routes to query the new schema, start `npm run dev` in the background, 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.
 5. Deploy with Prisma Compute. First apply the framework's deploy requirement from the guide at https://www.prisma.io/docs/guides/v8/frameworks/[guide].md, where [guide] is the template name except: template `next` → guide `nextjs`, `nest` → `nestjs`, `svelte` → `sveltekit`. The requirements: Next.js needs `output: "standalone"` in `next.config.ts` (without it the deployed app returns 504s), TanStack Start needs the nitro build plugin, Astro needs the `@astrojs/node` adapter plus `--env HOST=0.0.0.0`, and Elysia needs `--framework bun --entry src/index.ts` on the deploy command. If the template is `svelte`, skip this step; Compute does not support SvelteKit yet. Check `npx @prisma/cli@latest auth whoami`. If I am not signed in, stop and ask me to run `npx @prisma/cli@latest auth login`, because that step opens a browser. Then run `npx @prisma/cli@latest app deploy --create-project my-app --env .env` so DATABASE_URL reaches the deployment, and verify the deployed URL with curl.
 
@@ -79,7 +79,7 @@ If you're using Express or another Node.js server, follow the [existing-project
 
 </SectionRow>
 
-<SectionRow title="Using Prisma 7?" description="Prisma 7 is the current generally available release of Prisma ORM, fully supported, and `npx prisma@latest init` installs it. It pairs with Prisma Postgres and Prisma Compute the same way. When you're ready, Prisma 8 is the upgrade path.">
+<SectionRow title="Using Prisma 7?" description="Prisma 7 is the current generally available release of Prisma ORM and remains fully supported. Install it with `npx prisma@latest init`. It pairs with Prisma Postgres and Prisma Compute the same way. When you're ready, Prisma 8 is the upgrade path.">
 
 <IconGrid>
   <IconLink href="/getting-started" title="Prisma 7 setup paths" description="All database quickstarts, plus the agent prompt" icon={<Milestone />} />
@@ -107,9 +107,9 @@ 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/cli@next orm init`. It writes `prisma-next.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`. It writes `prisma.config.ts`, a starter contract and `db.ts` under `src/prisma/`, and installs Prisma 8 skills for you.
 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/cli@next contract infer`, then `npx @prisma/cli@next contract emit`, then sign it with `npx @prisma/cli@next db sign`. If the database is empty, keep the starter contract and run `npx @prisma/cli@next db init`.
+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.
 
 Follow https://www.prisma.io/docs/v8/add-to-existing-project/postgresql.md and the installed Prisma 8 skills.
@@ -126,7 +126,7 @@ If I have not given you a connection string, stop and ask; do not invent one. Va
 
 1. Scaffold: `npx create-prisma@next create my-app --template [framework] --provider postgres --database-url "<my connection string>" --yes`.
 2. From the project directory: `npm run db:init`, then `npm run db:seed`, then start `npm run dev` in the background and verify the sample query returns data. If seeding fails with `Cannot read properties of undefined (reading 'where')`, change `db.orm.User` to `db.orm.public.User` in `src/prisma/seed.ts`, `src/prisma/users.ts`, and any route files that query `db.orm`, then rerun.
-3. Evolve the starter contract under `src/prisma/` into my schema, then run `npm run contract:emit`, `npx @prisma/cli@next migration plan`, and `npx @prisma/cli@next migrate --yes`.
+3. Evolve the starter contract under `src/prisma/` into my schema, then run `npm run contract:emit`, `npx prisma@next migration plan`, and `npx prisma@next migrate --yes`.
 
 Do not provision any hosted database. Use the installed Prisma 8 skills and https://www.prisma.io/docs/llms.txt for current docs.
 ```
@@ -179,7 +179,7 @@ Current docs: https://www.prisma.io/docs/prisma-compute/deploy.md.
 
 </AgentPrompt>
 
-If you're using MongoDB, follow the [MongoDB quickstart](/v8/quickstart/mongodb) or [add Prisma 8 to an existing MongoDB app](/v8/add-to-existing-project/mongodb). If you work with [Kysely](/prisma-postgres/quickstart/kysely), [Drizzle](/prisma-postgres/quickstart/drizzle-orm), or [TypeORM](/prisma-postgres/quickstart/typeorm), the Prisma Postgres quickstarts cover those tools.
+If you're using MongoDB, follow the [MongoDB quickstart](/v8/quickstart/mongodb) or [add Prisma 8 to an existing MongoDB app](/v8/add-to-existing-project/mongodb). If you work with [Kysely](/prisma-postgres/quickstart/kysely), [Drizzle](/prisma-postgres/quickstart/drizzle-orm), or [TypeORM](/prisma-postgres/quickstart/typeorm), follow the Prisma Postgres quickstart for that tool.
 
 </ModalRow>