Rework the push-to-deploy pages to follow the docs-writer style

Apply the docs-writer skill's conventions to the new and rewritten
pages: remove em dashes, contrast slogans, coined phrasings, and
stacked absolutes; move failure notes inline with the step where the
reader hits them instead of a separate troubleshooting section; trim
the next-steps lists.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: kristof-siket

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

@@ -6,15 +6,15 @@ metaTitle: git | Prisma 8 CLI
 metaDescription: Learn how to connect and disconnect a GitHub repository for Prisma Compute push-to-deploy with the unified Prisma CLI.
 ---
 
-Use `git` commands to manage the GitHub repository connection. Connecting enables the OIDC credential exchange for GitHub Actions deploys and the branch lifecycle automation; the deploys themselves run in your repository's own workflow. See [GitHub integration](/compute/github) and [Deploy on push](/compute/deploy-on-push).
+Use `git` commands to manage the GitHub repository connection. Connecting enables the OIDC credential exchange for GitHub Actions deploys and the branch lifecycle automation. See [GitHub integration](/compute/github) and [Deploy on push](/compute/deploy-on-push).
 
 ## Usage
 
 ```npm
 npx prisma@next git connect
 ```
 
-Run it from a [linked](/cli/v8/project) project directory. The command is interactive: it opens the browser to install the GitHub App when needed and waits for the install, so `--no-interactive` fails with `CLI.INTERACTION_REQUIRED`. Connecting from the CLI does not add a deploy workflow to the repository; [add it yourself](/compute/deploy-on-push#4-add-the-deploy-workflow), or connect through the [Console](https://pris.ly/pdp), which opens a pull request with the workflow.
+Run it from a [linked](/cli/v8/project) project directory. The command needs an interactive terminal: it opens the browser to install the GitHub App when needed and waits for the install. With `--no-interactive` it fails with `CLI.INTERACTION_REQUIRED`. Connecting from the CLI does not add a deploy workflow to the repository. [Add it yourself](/compute/deploy-on-push#4-add-the-deploy-workflow), or connect through the [Console](https://pris.ly/pdp), which opens a pull request with the workflow.
 
 ## Commands
 

apps/docs/content/docs/composer/deploying.mdx

@@ -108,7 +108,7 @@ Destroying a stage removes its resources, then deletes its branch along with the
 
 ## CI
 
-On GitHub, the ready-made path is [Deploy on push](/compute/deploy-on-push): connect the repository and add [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) to your workflow. The action derives the target from the branch, so the default branch deploys production and every other branch deploys its own stage, and connected repositories authenticate through GitHub's OIDC tokens with no secrets at all.
+On GitHub, connect the repository and add [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) to a workflow instead of scripting the deploy yourself. The action derives the target from the branch: the default branch deploys production, and every other branch deploys a stage named after it. Connected repositories authenticate through GitHub's OIDC tokens, without a stored secret. [Deploy on push](/compute/deploy-on-push) walks through the setup.
 
 Any other CI runs the same commands as your machine: set the two credential variables as CI secrets, build, and deploy. The per-PR environment pattern:
 

apps/docs/content/docs/compute/deploy-on-push.mdx

@@ -6,60 +6,55 @@ metaTitle: Deploy on push | Prisma Compute
 metaDescription: Connect a GitHub repository and deploy a Prisma Composer app from GitHub Actions with prisma/cloud-deploy-action - production on the default branch, isolated preview stages per branch, automatic teardown.
 ---
 
-You have a [Composer](/composer) app that deploys from your terminal with `deploy module.ts`, the way the [full-stack tutorial](/full-stack-tutorial) left you. This guide graduates it to a Git workflow:
+You have a [Composer](/composer) app that you deploy by running `deploy module.ts` in a terminal. In this guide you connect its GitHub repository and add a deploy workflow, so pushing replaces that manual step: a push to the default branch updates production, every other branch gets an isolated preview environment, and deleting a branch cleans its preview up.
 
-- A push to your default branch deploys **production**.
-- A push to any other branch deploys an isolated **preview stage**: its own services, its own databases, its own buckets, its own URL.
-- Deleting the branch tears the preview down.
-- No secrets land in the repository: workflow runs authenticate through GitHub's OIDC tokens.
+## How it works
 
-## How the pieces fit
+Push-to-deploy has two parts, and you set up both:
 
-Push-to-deploy is two complementary halves, and you set up both:
+1. **The repository connection.** [`git connect`](/cli/v8/git) installs the Prisma GitHub App and registers the repository with your project. This lets workflow runs authenticate: a job exchanges its GitHub OIDC token for a Prisma workspace token that expires after 30 minutes, so the workflow needs no repository secrets. The connection also subscribes the project to branch events, which is what tears a preview down when its Git branch is deleted.
+2. **The deploy workflow.** [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) runs in your repository's GitHub Actions. On each push it installs dependencies, runs your build, and runs the [`deploy` command](/cli/v8/deploy) against production or a stage named after the branch.
 
-1. **The repository connection** ([`git connect`](/cli/v8/git)) installs the Prisma GitHub App and registers the repository against your project. That enables the **credential exchange**, so your GitHub Actions runs can trade their OIDC token for a short-lived workspace token, and the **branch lifecycle automation**, so deleting a Git branch tears down the matching preview.
-2. **The deploy workflow** ([prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action)) runs in your own repository's GitHub Actions. On every push it installs dependencies, runs your build, and hands the result to the [`deploy` command](/cli/v8/deploy), targeting production or a stage named after the branch.
+Connecting a repository does not deploy it; deploys come from the workflow. Without the connection, the workflow has no credential: the action prints a notice, sets its `outcome` output to `skipped-no-credential`, and exits successfully, so the run stays green.
 
-Each half is inert without the other. A connection with no workflow deploys nothing: connecting wires up automation, it doesn't build your commits. A workflow with no connection stays green but skips: without a credential the action reports `skipped-no-credential` and exits successfully, which is also why the workflow is harmless on forks.
-
-There are two ways in. Connecting through the [Console](https://pris.ly/pdp) opens a pull request that adds the workflow for you, so both halves arrive together. Connecting from the CLI, as this guide does, sets up the connection only: you add the workflow file yourself in step 4.
+You can connect in the [Console](https://pris.ly/pdp) or from the CLI. The Console opens a pull request that adds the workflow file at the same time. The CLI registers the connection only, and you add the workflow file yourself. This guide uses the CLI.
 
 ## Prerequisites
 
-- A Composer app that builds and deploys from your machine. If you don't have one yet, the [full-stack tutorial](/full-stack-tutorial) gets you there in about 15 minutes.
-- Admin access to the GitHub repository, so you can install the Prisma GitHub App.
+- A Composer app that builds and deploys from your machine. The [full-stack tutorial](/full-stack-tutorial) ends with one.
+- Admin access to the GitHub repository, so you can install the Prisma GitHub App on it.
 
 ## 1. Push the project to GitHub
 
-If the app isn't on GitHub yet, create a repository from the project directory and push it. With the [GitHub CLI](https://cli.github.com/):
+If the app is not on GitHub yet, create a repository from the project directory and push it. With the [GitHub CLI](https://cli.github.com/):
 
 ```bash
 gh repo create my-app --private --source . --push
 ```
 
 ## 2. Link the directory to the project
 
-The `git` commands operate on the project this directory is linked to. If you already deployed from this directory, it is linked. Otherwise, link it to the project your deploys created:
+The `git` commands operate on the project this directory is linked to. If you have deployed from this directory before, it is already linked and you can skip this step. Otherwise, link it to the project your deploys created:
 
 ```npm
 npx prisma@next project link my-app
 ```
 
-Run this in the project root, next to `package.json` and `module.ts`. Linking pins the **current** directory (in a gitignored `.prisma/local.json`), and it will happily pin a parent directory without a warning; commands run from the project then fail with `PROJECT.SETUP_REQUIRED`. See the [`project` command reference](/cli/v8/project) for how the link is resolved.
+Run the command in the project root, next to `module.ts`. Linking records the current directory, and it accepts a parent directory without a warning. If later commands fail with `PROJECT.SETUP_REQUIRED`, re-run `project link` from the project root. See the [`project` command reference](/cli/v8/project) for how the link is stored and resolved.
 
 ## 3. Connect the repository
 
+Connect the project to the repository from step 1:
+
 ```npm
 npx prisma@next git connect https://github.com/you/my-app
 ```
 
-The command opens the browser to install the Prisma GitHub App on the repository if it isn't installed yet, then registers the connection. It needs you at the terminal: the install flow is interactive, and `--no-interactive` fails with `CLI.INTERACTION_REQUIRED` rather than printing an install URL to follow later. If you can't run it interactively, connect the repository through the [Console](https://pris.ly/pdp) instead.
-
-Connecting the CLI way does not add a workflow to the repository, and it does not deploy anything on its own. That's the next step.
+The command opens your browser to install the Prisma GitHub App if it is not installed yet, then registers the connection. It needs an interactive terminal. With `--no-interactive` it fails with `CLI.INTERACTION_REQUIRED`; if you cannot run it interactively, connect through the [Console](https://pris.ly/pdp) instead.
 
 ## 4. Add the deploy workflow
 
-Commit a workflow that runs [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) on every push:
+Commit a workflow that runs the deploy action on every push:
 
 ```yaml title=".github/workflows/prisma-deploy.yml"
 name: prisma-deploy
@@ -90,17 +85,17 @@ jobs:
           build-command: npm run build
 ```
 
-Three lines carry the weight:
+A few settings to be aware of:
 
-- **`id-token: write`** lets the job request an OIDC token from GitHub. The action exchanges it for a Prisma workspace token that expires after 30 minutes. That exchange only succeeds for the repository you connected in step 3, and it is the reason the workflow needs no secrets.
-- **`build-command`** is your build, run verbatim. The action never guesses how to build your app; a repository that runs its source directly sets `build-command: none`.
-- **`oven-sh/setup-bun@v2`** puts Bun on the runner PATH, which the action requires.
+- `id-token: write` lets the job request the OIDC token that the action exchanges for a workspace token. Without this permission the exchange cannot happen and the run skips.
+- `build-command` runs verbatim. The action does not detect your framework or build for you. If the app runs its source directly, set `build-command: none`.
+- The action requires Bun on the runner PATH, which `oven-sh/setup-bun@v2` provides.
 
-The action deploys with the repository's own installed `prisma` version when it finds one, so keep your `prisma` devDependency current. The action's [README](https://github.com/prisma/cloud-deploy-action) documents every input, including `module` for an entry file that isn't `module.ts` and `working-directory` for monorepos.
+When the repository has a `prisma` devDependency, the action deploys with that installed version, so keep it current. The action's [README](https://github.com/prisma/cloud-deploy-action) documents the remaining inputs, including `module` for an entry file that is not `module.ts` and `working-directory` for monorepos.
 
 ## 5. Push to deploy production
 
-Commit the workflow and push to your default branch. In the repository's **Actions** tab, the `prisma-deploy` run installs, builds, and deploys, and ends by printing the same deploy report you know from your terminal, public URL included:
+Commit the workflow and push to your default branch. In the repository's **Actions** tab, the `prisma-deploy` run installs, builds, and deploys, and ends with the same deploy report you know from your terminal:
 
 ```text no-copy
 my-app
@@ -109,47 +104,39 @@ my-app
          https://xyz.ewr.prisma.build
 ```
 
-From here on, the default branch is your production pipeline: every push to it deploys production, and re-deploys are idempotent updates, exactly as if you had run `deploy module.ts` yourself.
+Every later push to the default branch updates production the same way, as if you had run `deploy module.ts` yourself.
+
+If the deploy step fails with `CLI.UNKNOWN_COMMAND`, the action release predates the unified CLI: releases up to v1.5.0 call the removed `prisma composer` commands. Use a release that runs the top-level `deploy` command; the action's [releases page](https://github.com/prisma/cloud-deploy-action/releases) lists what changed in each. If the run is green but its log shows `skipped-no-credential`, the repository is not connected; repeat step 3. Runs triggered from forks skip the same way, because GitHub does not issue OIDC tokens to them, so contributors' pushes keep a green CI without reaching your workspace.
 
 ## 6. Preview a branch
 
-Push any other branch:
+Push a branch to try the preview flow:
 
 ```bash
 git switch -c feature/search
 git push -u origin feature/search
 ```
 
-The action deploys it as a [stage](/composer/deploying#production-and-stages) named after the branch, which is a [preview branch](/compute/branching) of the same project: its own compute services, its own databases (assigned to the preview branch, not production), its own buckets, and its own URL. The only thing it shares with production is the code. Inspect it like any branch:
+The action deploys the branch as a [stage](/composer/deploying#production-and-stages) named after it, which is a [preview branch](/compute/branching) of the same project. The preview has its own services, its own databases assigned to that branch, its own buckets, and its own URL. The only thing it shares with production is the code. Confirm it from your terminal:
 
 ```npm
 npx prisma@next service list --branch feature/search
 ```
 
-Iterate on the branch and every push updates the same preview. The preview's configuration comes from the branch's [environment variables](/compute/environment-variables), so a preview never reads production values.
+Further pushes to the branch update the same preview. Its configuration comes from the branch's [environment variables](/compute/environment-variables), so a preview reads preview-scoped values rather than production ones.
 
 ## 7. Delete the branch to clean up
 
+When the branch has served its purpose, delete it:
+
 ```bash
 git push origin --delete feature/search
 ```
 
-The platform's branch automation, wired up by `git connect` in step 3, tears down the matching preview: services, databases, and buckets are removed. Teardown comes from the repository connection, not from the workflow, so it works even when no Actions run fires for the deletion. Your production and default branches are never touched by automated cleanup.
-
-## Forks and unconnected repositories
-
-GitHub does not mint OIDC tokens for workflow runs triggered from forks, and the credential exchange refuses repositories that aren't connected. In both cases the action skips instead of failing: the run stays green, prints a notice, and sets its `outcome` output to `skipped-no-credential`. Contributors can fork your repository without their pushes failing CI or reaching your workspace.
-
-## Troubleshooting
-
-- **The deploy step fails with `CLI.UNKNOWN_COMMAND`.** The action release predates the unified CLI: releases up to v1.5.0 invoke the `prisma composer` subcommands, which were removed in `prisma` `8.0.0-rc.8`. Use a release that invokes the top-level `deploy` command (see the action's [releases](https://github.com/prisma/cloud-deploy-action/releases)).
-- **Commands fail with `PROJECT.SETUP_REQUIRED`.** The directory isn't linked, or you linked a parent directory. Re-run `project link` in the project root (step 2).
-- **`git connect` fails with `CLI.INTERACTION_REQUIRED`.** The command can't complete non-interactively. Run it at a terminal, or connect through the [Console](https://pris.ly/pdp).
-- **Runs are green but nothing deploys.** Check the run's log for `skipped-no-credential`: the repository isn't connected (step 3), or the run came from a fork.
+The platform tears down the matching preview: its services, databases, and buckets are removed. This automation comes from the connection you set up in step 3, so it runs whether or not a workflow fires for the deletion. Automated cleanup skips your production and default branches.
 
 ## Next steps
 
 - [GitHub integration](/compute/github): what the repository connection is and does.
 - [Branching](/compute/branching): how preview branches relate to Git branches.
-- [Deploying](/composer/deploying): stages, deploy state, and per-stage secrets, which all apply to CI deploys.
-- [Environment variables](/compute/environment-variables): per-branch configuration for previews.
+- [Deploying](/composer/deploying): stages, deploy state, and per-stage secrets, which apply to CI deploys too.