Docs IA restructure: drill-in sidebar, REST API rename, CLI consolidation, Storage

.github/workflows/sync-management-api-docs.yml

@@ -1,4 +1,4 @@
-name: Sync Management API Docs
+name: Sync REST API Docs
 
 on:
   repository_dispatch:
@@ -11,50 +11,50 @@
 
 jobs:
   sync:
-    name: Sync Management API Documentation
+    name: Sync REST API Documentation
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           persist-credentials: false
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: "20"
           cache: "pnpm"
 
       - name: Install dependencies
         run: pnpm install
 
       - name: Generate docs and Postman collection
         working-directory: apps/docs
-        run: pnpm run generate:management-api-docs
+        run: pnpm run generate:rest-api-docs
 
       - name: Check for changes
         id: changes
         run: |
-          if [[ -z "$(git status --porcelain --untracked-files=all -- apps/docs/content/docs/management-api/ apps/docs/public/prisma-management-api.postman_collection.json apps/docs/vercel.json)" ]]; then
+          if [[ -z "$(git status --porcelain --untracked-files=all -- apps/docs/content/docs/rest-api/ apps/docs/public/prisma-rest-api.postman_collection.json apps/docs/vercel.json)" ]]; then
             echo "changed=false" >> $GITHUB_OUTPUT
             echo "No changes detected"
           else
             echo "changed=true" >> $GITHUB_OUTPUT
             echo "Changes detected:"
-            git status --short -- apps/docs/content/docs/management-api/ apps/docs/public/prisma-management-api.postman_collection.json apps/docs/vercel.json
+            git status --short -- apps/docs/content/docs/rest-api/ apps/docs/public/prisma-rest-api.postman_collection.json apps/docs/vercel.json
           fi
 
       - name: Commit and push
         if: steps.changes.outputs.changed == 'true'
         run: |
           git config user.email "prismabots@gmail.com"
           git config user.name "Prismo"
-          git add apps/docs/content/docs/management-api/ apps/docs/public/prisma-management-api.postman_collection.json apps/docs/vercel.json
-          git commit -m "chore(docs): sync management API documentation"
+          git add apps/docs/content/docs/rest-api/ apps/docs/public/prisma-rest-api.postman_collection.json apps/docs/vercel.json
+          git commit -m "chore(docs): sync REST API documentation"
           git push "https://x-access-token:${{ secrets.BOT_TOKEN_DOCS_COMMIT }}@github.com/${{ github.repository }}.git" HEAD:${{ github.ref_name }}
 
       - name: Trigger Vercel deploy
         run: curl --fail -X POST "${{ secrets.VERCEL_DEPLOY_HOOK_URL }}"

apps/docs/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md — Prisma docs app
+
+## Documentation taxonomy
+
+Classify every docs page as one of three kinds before writing or moving content:
+
+1. **Reference**: interface contracts. CLI commands, flags, REST API endpoints, parameters, config file fields, environment variables, API signatures.
+2. **Concepts**: platform fundamentals. Projects, workspaces, branching, environment variables as a topic, how things work.
+3. **Guides**: getting-started and structured step-by-step material.
+
+## Placement rules
+
+1. Reference material lives under `content/docs/cli/`, `content/docs/rest-api/`, or a section's `---Reference---` meta.json block. Never document flags, parameters, or endpoints in full inside a concept or guide page; link to the reference page instead.
+2. A product section may keep a thin `cli-reference.mdx` pointer page that links into `cli/v8/*`. `content/docs/compute/cli-reference.mdx` is the canonical example. Full command references live in `cli/v8/`.
+3. The section is named "REST API" (folder `rest-api`). Do not reintroduce "Management API" in titles, nav, prose, or new URLs. Code identifiers (`@prisma/management-api-sdk`, `createManagementApiClient`) keep their names.
+4. Sidebar grouping (Build/Deploy/Manage/Reference) is UI config in `src/lib/sidebar-sections.ts`, not content structure. Do not add grouping separators to the root `content/docs/meta.json`.
+
+## Moving or renaming pages
+
+1. Add a redirect in the live region of `next.config.mjs` `redirects()` (near the `/llms/next.txt` entry). Do not add entries to the commented "Prisma 8 URL cutover" staging blocks unless working on that cutover. Run `pnpm audit:redirects:strict` after.
+2. Re-run `npx tsx scripts/add-url-frontmatter.ts` after any file move; the required `url:` frontmatter goes stale silently and no linter catches it.
+3. New top-level sections need an entry in `llmsSections` in `src/lib/llms.ts` (see `.claude/skills/docs-agent-ready`).
+4. Do not rename the `orm/`, `cli/`, or `guides/` folders or their meta.json titles, and keep `cli/v8/meta.json` title exactly `"v8 (RC)"`: `src/lib/version.ts` path maps and `src/lib/versioned-sidebar-tree.ts` match on those strings and break the version switcher silently.
+
+## Generated content
+
+1. `content/docs/rest-api/endpoints/` and `public/prisma-rest-api.postman_collection.json` are generated. Never hand-edit; run `pnpm generate:rest-api-docs`.
+2. The generator prepends redirects to `vercel.json` for endpoints that disappear from the OpenAPI spec; review them after each run.
+
+## Validation
+
+Run from `apps/docs`:
+
+1. `pnpm lint:links` — internal links, anchors, `Card` hrefs. It does not check redirect destinations, `version.ts` path maps, `llms.ts` prefixes, or `url:` frontmatter.
+2. `pnpm audit:redirects:strict` after adding redirects.
+3. `pnpm lint:agent-ready` after touching sections, llms surfaces, or the OpenAPI explorer.
+4. `pnpm types:check` and `pnpm build` for code changes.

apps/docs/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

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

@@ -1,10 +1,9 @@
 ---
 title: Get started with Prisma
-description: Scaffold an app with Prisma 8, create or connect Prisma Postgres, and deploy on Prisma Compute. One integrated TypeScript stack, from first query to live URL.
+description: Build an app with Prisma 8, create or connect Prisma Postgres, and deploy on Prisma Compute. One integrated TypeScript stack, from first query to live URL.
 url: /
 metaTitle: Get started with Prisma
-metaDescription: Scaffold an app with Prisma 8, create or connect Prisma Postgres, and deploy it on Prisma Compute. Quick setup, guided setup, and agent prompts.
-hideSidebar: true
+metaDescription: Build an app with Prisma 8, create or connect Prisma Postgres, and deploy it on Prisma Compute. Quick setup, guided setup, and agent prompts.
 full: true
 ---
 
@@ -189,7 +188,7 @@ If you're using MongoDB, follow the [MongoDB quickstart](/v8/quickstart/mongodb)
 
 <IconGrid columns={3}>
   <IconLink href="/orm" title="Prisma ORM" description="Prisma 7 and Prisma 8" icon={<Boxes />} />
-  <IconLink href="/postgres" title="Prisma Postgres" description="The managed database" icon={<TriangleDashed />} />
+  <IconLink href="/postgres" title="Prisma Postgres" description="The managed database" icon={<Database />} />
   <IconLink href="/compute" title="Prisma Compute" description="Hosting and branching" icon={<Cpu />} />
   <IconLink href="/cli" title="CLI reference" description="Every command and flag" icon={<Terminal />} />
   <IconLink href="/guides" title="Guides" description="Frameworks and workflows" icon={<NotebookTabs />} />

apps/docs/content/docs/(index)/meta.json

@@ -2,7 +2,6 @@
   "title": "Getting Started",
   "root": true,
   "pages": [
-    "---Getting Started---",
     "index",
     "---Prisma 8 (recommended)---",
     "v8/index",

apps/docs/content/docs/(index)/v8/add-to-existing-project/mongodb.mdx

@@ -12,7 +12,7 @@ Use this path when you already have an application and database. Make sure the a
 
 :::note[The Prisma 8 Release Candidate is available]
 
-Prisma 8 is the next major version of Prisma ORM, now available as a Release Candidate. It’s the cutting-edge version of Prisma ORM and will become the future of Prisma, so we’d love for you to try it, explore what’s new, and [share your feedback in Discord](https://pris.ly/discord).
+Prisma 8 Release Candidate is now live and the recommended version of the Prisma ORM. Cutting-edge and the future of the Prisma ORM. We’d love for you to try it, explore what’s new, and [share your feedback in Discord](https://pris.ly/discord).
 
 If you want to stay on the current generally available version of Prisma ORM, you can continue with [Prisma 7](/getting-started).
 

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

@@ -5,7 +5,6 @@ url: /v8
 metaTitle: Introduction to Prisma 8
 metaDescription: Start here for Prisma 8, the TypeScript-native rebuild of Prisma ORM, now a Release Candidate. Quickstarts, framework guides, and agent prompts.
 badge: release-candidate
-hideSidebar: true
 ---
 
 Prisma 8 is a ground-up rebuild of Prisma ORM, from the runtime and query APIs to the migration flow and project setup.

apps/docs/content/docs/ai/prompts/nuxt.mdx

@@ -1,7 +1,7 @@
 ---
 title: Nuxt + Prisma
 description: Step-by-step guide for integrating Prisma ORM and Prisma Postgres in a Nuxt project
-url: /docs/ai/prompts/nuxt
+url: /ai/prompts/nuxt
 metaTitle: How to Initialize a Nuxt App with Prisma ORM and Prisma Postgres
 metaDescription: Step-by-step guide for integrating Prisma ORM and Prisma Postgres in a Nuxt project.
 ---

apps/docs/content/docs/ai/tools/skills.mdx

@@ -75,15 +75,15 @@ Covers PostgreSQL, Prisma Postgres, MySQL/MariaDB, SQLite, MongoDB, SQL Server,
 
 ### `prisma-postgres`
 
-Prisma Postgres workflows across Console, CLI, Management API, and SDK.
+Prisma Postgres workflows across Console, CLI, REST API, and SDK.
 
-Covers `npx create-db`, Console operations, programmatic provisioning via the Management API, and the `@prisma/management-api-sdk`. Use this when creating or managing Prisma Postgres databases.
+Covers `npx create-db`, Console operations, programmatic provisioning via the REST API, and the `@prisma/management-api-sdk`. Use this when creating or managing Prisma Postgres databases.
 
 ### `prisma-postgres-setup`
 
 Gets a new Prisma Postgres database up and connected to your project.
 
-Covers authenticating with a service token, listing regions, creating a project and database via the Management API, obtaining a connection string, and configuring `prisma.config.ts`, the schema, and the driver adapter. Use this when setting up a database or connecting an app to Prisma Postgres.
+Covers authenticating with a service token, listing regions, creating a project and database via the REST API, obtaining a connection string, and configuring `prisma.config.ts`, the schema, and the driver adapter. Use this when setting up a database or connecting an app to Prisma Postgres.
 
 ### `prisma-compute`
 

apps/docs/content/docs/cli/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: CLI Overview
+title: Overview
 description: 'The Prisma CLI is the command-line interface for Prisma ORM. Use it to initialize projects, generate Prisma Client, manage databases, run migrations, and more'
 metaTitle: Prisma CLI Reference | Commands for ORM, Migrate & Database
 metaDescription: 'Complete Prisma CLI reference. Initialize projects, generate Prisma Client, run migrations, manage databases, and use Prisma Studio. Install with npm.'
@@ -24,7 +24,7 @@ npm install prisma --save-dev
 
 :::info
 
-This page documents the Prisma 7 CLI that ships in the `prisma` package. Prisma 8 introduces a new, unified Prisma CLI that also includes commands for [Prisma Composer](/composer) and [Prisma Compute](/compute). The Prisma 8 RC publishes it as `prisma@next`. See the [Prisma 8 CLI reference](/cli/v8), the [Composer CLI reference](/composer/cli-reference), and the [Prisma Compute CLI reference](/compute/cli-reference).
+This page documents the Prisma 7 CLI that ships in the `prisma` package. Prisma 8 introduces a new, unified Prisma CLI that also includes commands for [Prisma Composer](/composer) and [Prisma Compute](/compute). The Prisma 8 RC publishes it as `prisma@next`. See the [Prisma 8 CLI reference](/cli/v8), the [Composer commands](/cli/v8/composer), and the [platform commands](/cli/v8#platform-commands).
 
 :::
 

apps/docs/content/docs/composer/cli-reference.mdx → apps/docs/content/docs/cli/v8/composer.mdx

@@ -1,18 +1,23 @@
 ---
-title: CLI reference
-description: Every Composer command and flag in the Prisma CLI, plus the in-process control API.
-url: /composer/cli-reference
-metaTitle: CLI reference | Prisma Composer
+title: composer
+description: Deploy, tear down, and locally run Composer applications.
+url: /cli/v8/composer
+metaTitle: composer | Prisma 8 CLI
 metaDescription: Complete reference for the prisma composer command group, including deploy, destroy, dev, and log, their flags, credentials, and the in-process control API.
 ---
 
-Composer ships as the `composer` command group of the unified Prisma CLI, published as `prisma@next` during the Prisma 8 RC:
+Use `composer` commands to deploy and run [Prisma Composer](/composer) applications. Composer ships as the `composer` command group of the unified Prisma CLI, published as `prisma@next` during the Prisma 8 RC.
+
+Every command takes an `<entry>` argument: the module whose default export is the application root, typically `module.ts`. All four commands stream the underlying pipeline's own output to the terminal.
+
+## Usage
 
 ```npm
-npx prisma@next composer <command>
+npx prisma@next composer deploy module.ts
+npx prisma@next composer dev module.ts
 ```
 
-Every command takes an `<entry>` argument: the module whose default export is the application root, typically `module.ts`. All four commands stream the underlying pipeline's own output to the terminal.
+## Commands
 
 | Command | Description |
 | --- | --- |
@@ -101,7 +106,16 @@ The Prisma CLI's global flags also apply: `--format`, `--json`, `--log-level`, `
 
 ## The control API
 
-Everything the CLI does is also callable in-process from `@prisma/composer/control`: typed `deploy`, `destroy`, `dev`, and `log` operations that return `{ ok: true, value }` or `{ ok: false, failure }` instead of printing and exiting. The CLI commands are renderers over these operations. See [Driving deploys from code](/composer/deploying#driving-deploys-from-code).
+Everything the CLI does is also callable in-process, from `@prisma/composer/control`: typed `deploy`, `destroy`, `dev`, and `log` operations that return structured results instead of printing and exiting. The CLI commands are thin renderers over these same operations, so both surfaces behave the same:
+
+```ts
+import { deploy } from '@prisma/composer/control';
+
+const result = await deploy({ entry: 'module.ts', stage: 'pr-42' });
+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. `destroy` takes an explicit target, `{ kind: 'production' }` or `{ kind: 'stage', stage }`. There is no default. The deploy engine's live output still streams to your process's stdio; the operations do not capture it.
 
 ## Next steps
 

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

@@ -1,5 +1,5 @@
 ---
-title: CLI configuration
+title: Configuration
 description: Configure Prisma 8 CLI commands with prisma.config.ts and global flags.
 url: /cli/v8/configuration
 metaTitle: Prisma 8 CLI configuration

apps/docs/content/docs/cli/v8/global-flags.mdx

@@ -0,0 +1,28 @@
+---
+title: Global flags
+description: Flags accepted by every command in the unified Prisma CLI.
+url: /cli/v8/global-flags
+metaTitle: Global flags | Prisma 8 CLI
+metaDescription: Reference for the global flags every Prisma 8 CLI command accepts, including output format, log level, prompts, and config path.
+---
+
+All commands in the unified Prisma CLI accept these flags.
+
+| Flag | What it does |
+| --- | --- |
+| `--json` | Print machine-readable output (shorthand for `--format json`). Use this in CI and scripts. |
+| `--format <mode>` | Output format, `human` or `json`. |
+| `--log-level <level>` | Commentary verbosity: `error`, `warn`, `info`, or `verbose`. |
+| `-q`, `--quiet` | Suppress nonessential output (shorthand for `--log-level error`). |
+| `-v`, `--verbose` | Print more detail (shorthand for `--log-level verbose`). |
+| `--color` / `--no-color` | Force colored output on or off. |
+| `--interactive` / `--no-interactive` | Force prompts on or off. |
+| `-y`, `--yes` | Accept prompt defaults without asking. |
+| `--confirm <token>` | Grant a consent prompt non-interactively by typing its token (repeatable). |
+| `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
+| `-h`, `--help` | Print help for a command. |
+| `--version` | Print the CLI version and exit. |
+
+Use `npx prisma@next <command> --help` when you need the exact command help from the installed version.
+
+The output modes and the JSON envelope these flags select are documented on [Configuration](/cli/v8/configuration#output-modes).