diff --git a/README.md b/README.md
index 8c91587..446fa5b 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ Example workflow:
 ```bash
 pnpm prisma-cli auth login
 pnpm prisma-cli app deploy --env DATABASE_URL=postgresql://example
-pnpm prisma-cli app list-env
+pnpm prisma-cli project env list --role preview
 ```
 
 If you want local project scripts that look like the future command shape, add:
@@ -86,6 +86,7 @@ The CLI groups commands by developer workflow:
 
 - `auth`
 - `project`
+- `git`
 - `branch`
 - `app`
 
@@ -118,6 +119,9 @@ Start here when changing command behavior:
 See `CONTRIBUTING.md` for local development and contribution guidance.
 See `ARCHITECTURE.md` for the short architecture entrypoint.
 
+The npm package README lives at `packages/cli/README.md` and is copied into the
+staged publish artifact.
+
 ## Community
 
 Issues and feedback are welcome while the CLI is in public beta. Pull
diff --git a/packages/cli/README.md b/packages/cli/README.md
index b8efcbd..e16325d 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -1,27 +1,132 @@
-# Prisma CLI Beta
+<p align="center">
+  <img src="https://i.imgur.com/h6UIYTu.png" alt="Prisma" width="360" />
+</p>
 
-Beta npm package for the unified Prisma CLI.
+# Prisma CLI
 
-Install:
+[![npm version](https://img.shields.io/npm/v/@prisma/cli?label=npm)](https://www.npmjs.com/package/@prisma/cli)
+[![license](https://img.shields.io/npm/l/@prisma/cli)](https://github.com/prisma/prisma-cli/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/node/v/@prisma/cli)](https://www.npmjs.com/package/@prisma/cli)
+
+[Quickstart](#quickstart) • [Commands](#commands) • [Beta notes](#beta-notes) • [Documentation](#documentation) • [Support](#support)
+
+---
+
+`@prisma/cli` is the public beta of the new CLI for the
+Prisma Developer Platform.
+
+It is the terminal surface managing your platform projects, branches, apps,
+deployments, and environment variables.
+
+The command model is under active development to include tooling for your
+schema, database, migration, and broader platform workflows.
+
+Looking for Prisma ORM commands such as `prisma generate`, `prisma migrate`, or
+`prisma studio`? Use the [`prisma`](https://www.npmjs.com/package/prisma)
+package.
+
+---
+
+## Quickstart
+
+Install the beta package locally:
 
 ```bash
-pnpm add -D @prisma/cli
+npm install --save-dev @prisma/cli
 ```
 
-Run:
+Run the binary exposed by this package:
 
 ```bash
-pnpm prisma-cli --help
+npx prisma-cli --help
+npx prisma-cli auth login
+npx prisma-cli app deploy
+```
+
+With `pnpm`:
+
+```bash
+pnpm add -D @prisma/cli
 pnpm prisma-cli auth login
-pnpm prisma-cli app deploy --env DATABASE_URL=postgresql://example
-pnpm prisma-cli app list-env
+pnpm prisma-cli app deploy
+```
+
+Useful next commands:
+
+```bash
+npx prisma-cli app logs
+npx prisma-cli app open
+npx prisma-cli project env add DATABASE_URL=postgresql://example --role preview
+npx prisma-cli project env list --role preview
 ```
 
-The package exposes `prisma-cli` so it can coexist with the existing `prisma`
-executable.
+The beta package exposes `prisma-cli` so it can coexist with the existing
+`prisma` executable.
 
-Notes:
+---
 
+## Commands
+
+| Group | What it does |
+| --- | --- |
+| `version` | Show the installed CLI build and host environment. |
+| `auth` | Log in, log out, and inspect the active Prisma account. |
+| `project` | List projects, show the resolved project, and manage project environment variables. |
+| `git` | Connect or disconnect a project from a GitHub repository. |
+| `branch` | Inspect the Prisma branch that maps to the current work context. |
+| `app` | Build, run, deploy, inspect, open, stream logs, promote, roll back, and remove apps. |
+
+Common examples:
+
+```bash
+npx prisma-cli version
+npx prisma-cli auth whoami
+npx prisma-cli project show
+npx prisma-cli branch show
+npx prisma-cli app deploy --branch feat-login --framework nextjs
+npx prisma-cli app promote <deployment-id>
+```
+
+### Built for humans, CI, and agents
+
+- Human-readable output by default.
+- `--json` for structured output.
+- `--no-interactive` and `--yes` for automation.
+- `PRISMA_SERVICE_TOKEN` for headless authenticated commands.
+- Stable command groups, flags, and error codes for scripts and agents.
+- Environment variable values are not printed back to the terminal.
+
+---
+
+## Beta notes
+
+- Requires Node.js 20 or newer.
 - This is a beta package and may change quickly.
-- `prisma.config.ts` stores linked project context for this CLI.
-- Environment variable values passed with `--env` are not printed back to the terminal.
+- Official beta releases publish as `@prisma/cli`.
+- The package binary is `prisma-cli`, not `prisma`, during beta.
+- Local project context is cached in `.prisma/local.json`, which is gitignored and not a declarative repo config file.
+
+---
+
+## Documentation
+
+- [CLI docs index](https://github.com/prisma/prisma-cli/blob/main/docs/README.md)
+- [Resource model](https://github.com/prisma/prisma-cli/blob/main/docs/product/resource-model.md)
+- [Command principles](https://github.com/prisma/prisma-cli/blob/main/docs/product/command-principles.md)
+- [Command spec](https://github.com/prisma/prisma-cli/blob/main/docs/product/command-spec.md)
+- [Output conventions](https://github.com/prisma/prisma-cli/blob/main/docs/product/output-conventions.md)
+- [Error conventions](https://github.com/prisma/prisma-cli/blob/main/docs/product/error-conventions.md)
+
+## Support
+
+Issues and feedback are welcome while the CLI is in public beta. Please use
+[GitHub issues](https://github.com/prisma/prisma-cli/issues) for bug reports and
+feature requests.
+
+Security reports should follow Prisma's
+[security policy](https://github.com/prisma/prisma-cli/blob/main/SECURITY.md)
+and should not be filed as public issues.
+
+## License
+
+Apache-2.0
diff --git a/packages/cli/package.json b/packages/cli/package.json
index acaf339..578ab22 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@prisma/cli",
   "version": "3.0.0-development",
-  "description": "Beta of the unified Prisma CLI.",
+  "description": "Command-line interface for the Prisma Developer Platform.",
   "type": "module",
   "bin": {
     "prisma-cli": "./dist/cli.js"
diff --git a/packages/cli/tests/publish-prep.test.ts b/packages/cli/tests/publish-prep.test.ts
index 435ae83..257a668 100644
--- a/packages/cli/tests/publish-prep.test.ts
+++ b/packages/cli/tests/publish-prep.test.ts
@@ -25,7 +25,7 @@ describe("prepare cli publish", () => {
           name: "@prisma/cli",
           private: true,
           version: "3.0.0-development",
-          description: "Beta of the unified Prisma CLI.",
+          description: "Command-line interface for the Prisma Developer Platform.",
           type: "module",
           engines: {
             node: ">=20",
@@ -60,7 +60,7 @@ describe("prepare cli publish", () => {
     expect(manifest).toEqual({
       name: "@prisma/cli",
       version: "3.0.0-development",
-      description: "Beta of the unified Prisma CLI.",
+      description: "Command-line interface for the Prisma Developer Platform.",
       type: "module",
       bin: {
         "prisma-cli": "./dist/cli.js",
@@ -103,7 +103,7 @@ describe("prepare cli publish", () => {
         {
           name: "@prisma/cli",
           version: "3.0.0-development",
-          description: "Beta of the unified Prisma CLI.",
+          description: "Command-line interface for the Prisma Developer Platform.",
           type: "module",
           dependencies: {},
         },
@@ -141,7 +141,7 @@ describe("prepare cli publish", () => {
         {
           name: "@prisma/cli",
           version: "3.0.0-development",
-          description: "Beta of the unified Prisma CLI.",
+          description: "Command-line interface for the Prisma Developer Platform.",
           type: "module",
           dependencies: {},
         },