docs: Prisma ORM 8 docs audit, personas, journeys, and proposed IA (for discussion)

[wmadden-electric]

Most complaints about the Prisma ORM 8 docs come from two kinds of reader, and the site's entry points are built for a third:

The Newcomer   has an app already, wants typed queries; lands on pages that scaffold a new app for them
The Upgrader   has a Prisma ORM 7 app and a database with data; finds no page that says what moved or whether to move
The Builder    wants to ship on the platform with an agent's help; the root page, the agent prompts, and the tutorial are theirs

What this PR is

Draft, for discussion, not for merge as-is: the design documents behind the Prisma ORM 8 docs work, added under docs/orm-docs-audit/ so they can be read and commented in one place. They describe readers, the jobs those readers come to do, the mental model pages should be written from, the proposed information architecture, and the reasoning. They are design documents, not status: they describe the target and why, and do not track progress.

The decision they build up to

Serve the Newcomer and the Upgrader before the Builder at the ORM entry points, and organise the Getting Started > Prisma ORM subtree by the reader's starting state rather than by which tool runs:

1. New app from scratch
2. App already started, empty database
3. Existing database with data
4. Existing Prisma ORM 7 app

Each door is one page that carries the whole path. Two pages the Upgrader needs are added at the top level: "Coming from Prisma ORM 7" and "Release status". The /orm page shows the product (a contract, the query it enables, the typed result) instead of arguing for the design against Prisma ORM 7. Everything below the entry points (Data Modeling, Contract Authoring, Fundamentals, Migrations, Middleware, Extensions, Reference) stays where it is.

Reading order

1. README.md, then personas.md: the four readers.
2. journeys.md: ten jobs, each with what done looks like, what the docs must provide, and where the structure fails it.
3. mental-model.md: the first-principles explanation (contract versus schema, emit, signature, plans, migrations and refs) that pages get written from.
4. ia.md: the proposed sidebar trees and /orm page, then the current state and the reasons.
5. changes.md: every proposed change by kind, with the recommended order and the decisions that need an owner.
6. naming.md, the three briefs handed to ORM-side agents, and audit/, the page-by-page findings with a source citation for every claim.

What is already settled, and what is open

Settled: the readers and their order of priority; the naming rule (the product is Prisma ORM; a version number only when contrasting versions); the mental model as the source pages are written from; correcting the published pages before restructuring (done in #8236, #8237, #8238).

Open, and the reason this PR exists: the four-door structure of the ORM entry, the rewritten /orm page, and where the Prisma ORM 8 guides tree goes once the Prisma 7 guides have moved.

Alternatives considered

• Restructure first, correct pages after. Rejected: readers were copying broken samples every day; corrections were mechanical and did not depend on the structure.
• Organise the entry by database (PostgreSQL, MongoDB) at the top level. Rejected: the reader knows their starting state before they know which tool runs; the database split stays inside each door.
• Keep the design in a shared document outside the repo. Rejected: the documents cite file paths and source lines, and reviewers are engineers who will read them next to the pages.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
blog	Ready	Preview	Sep 23, 2026 7:08am UTC
docs	Ready	Preview	Sep 23, 2026 7:08am UTC
eclipse	Ready	Preview	Sep 23, 2026 7:08am UTC
site	Ready	Preview	Sep 23, 2026 7:08am UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[ankur-arch]

love this!

[prisma-robot]

Reviewed ff231f8 cold: all twenty-two files (the two new ones, plain-language.md and brief-intermediate-contracts.md, included), the ten commits since 5dce14b, and every dated claim re-checked against main today (6baf4da), npm, prisma/orm, and create-prisma. No gate in this repo touches top-level docs/, so there was nothing to run. Verified and holding: A1 (four doors on /prisma-orm), A2 (coming-from-prisma-orm-7 in the ORM Introduction group), A3 and A5 (the agent prompt still leads /prisma-orm, the root page still has the one-line "Here for the ORM?"), C4 (release-status says October 2026 and 18 months), C5 (editor-support.mdx), C18 (release-status states Node and TypeScript floors only), C25 in #8281, D1 in prisma/orm#30251, D3 in create-prisma#96, D14 in #30250/#30264/#30283, all merged.

Found and fixed in 02dbe81:

• The Models / Shape<> types are not "awaiting a tagged release". They shipped in rc.10 (2026-09-12, #30231) and docs(docs): update the Prisma ORM 8 pages for 8.0.0-rc.10 #8261 documents them as the "Model and result types" section of the client reference plus a row on Coming from Prisma 7. journeys.md J9, mental-model.md's mapping table, and changes.md C6 and D4 said otherwise; C6 moves from "not started" to "partly done" with what is left (the page with the Prisma 7 name beside each type).
• db sign does set the db ref now. mental-model.md (the file pages are written from) still said "db sign does not today", taught the baseline-plus-migration ref set workaround as the current fix, and listed db sign as writing only the signature; journeys.md J2 and changes.md C3 ("waits on D1") and ia.md's "adds baseline, ref" line said the same. Rewritten to the rc.10 behaviour, with --no-advance-ref and the D2 notice.
• changes.md contradicted itself on docs: correct the facts on the Prisma ORM 8 getting-started pages and guides #8238 and the naming pass. "Where things stand" says all three B PRs and the naming pass shipped; A4, the section B heading and intro still said "docs: correct the facts on the Prisma ORM 8 getting-started pages and guides #8238 open as of 2026-09-11", and the Naming section said "Not started". slice-corrections.md had the same "open" cell. docs: correct the facts on the Prisma ORM 8 getting-started pages and guides #8238 merged 2026-09-11 17:00.
• Twelve jobs, not ten. The new J11 and J12 left README.md saying "ten jobs", changes.md saying "J1 to J10", and ia.md's two job tables without rows for them. Fixed all three; J11/J12 now cite C22/C23 in their verdicts like the other jobs; journeys.md says its paths and verdicts describe the 2026-09-10 site, matching ia.md and the README's note on audit/.
• Stale numbers. D6 said prisma@latest is rc.13 (it is rc.15); D11 said create-prisma pins rc.8 at 0.11.7 (0.13.1, 2026-09-17, pins rc.11, current today; the item stays as the process point).
• README item 8 had its explanatory parenthetical after the brief-intermediate-contracts.md mention, so it read as describing C25; reordered, with the landed status.

Also merged main into the branch (clean; the branch was 57 commits behind, no overlap with docs/).

Left alone on purpose: the audit/ files, naming.md's 2026-09-10 counts, the three briefs, and ia.md's current-state section are dated snapshots and still say so.

This is the fourth reviewer fix round on this pull request overall (three on 2026-09-11 before the author's ten new commits) and the first on this head. Will re-read the new head cold in a few minutes; if that read finds more, I will hand it back rather than patch again.

— reviewer

[prisma-robot]

Reviewed 9f14bb8 cold (the head moved from a7812c3 to this while the run started): all twenty-two files, the two commits since 02dbe81, and every dated claim re-checked against main today (6baf4da, and the branch is 0 behind it), GitHub, npm, and the rc.11 tarballs. No gate in this repo touches top-level docs/ (oxfmt ignores **/*.md; cspell, lint:links, the prose check and lychee are scoped to apps/docs/content), so there was nothing to run.

Holding: all twenty-nine prisma/web PRs changes.md cites are in the state it says, including #8306 open with exactly three commits, one per C13/C14/C16, touching migration-api.mdx, both contract-authoring pages, contract-emit.mdx, the artifact page and the three Vite framework guides; prisma/orm #30251/#30250/#30264/#30283/#30231/#30236/#30158 and create-prisma#96 merged; prisma@latest rc.15, @prisma/client@latest 7.10.0, create-prisma@latest 0.13.1 (2026-09-17), @prisma/orm-postgres@latest rc.11, newest prisma/orm tag v8.0.0-rc.11; the four doors in (index)/prisma-orm/meta.json, the agent prompt still ahead of the framework and fundamentals sections on /prisma-orm, release-status stating only the Node and TypeScript floors, both error references generated, the root page's one-line ORM pointer. The flat db.orm.User claim is right: rc.11's orm() returns a proxy keyed only by namespace ids. No audit file cites an item number changes.md does not define.

Found in 3b90c1c, not yet fixed (see the end):

• changes.md "In review": "createInMemoryCacheStore is not public" is false. @prisma/orm-extension-middleware-cache@8.0.0-rc.11 exports it from its entry point, in both dist/index.mjs (export { cacheAnnotation, createCacheMiddleware, createInMemoryCacheStore }) and dist/index.d.mts line 218, and its README describes it. audit/builders.md:42 says "exported" and is right. What is true is that the site's cache page documents the store and maxEntries options and never names the factory.
• Same paragraph: "its runtime items were covered by docs(orm8): plain-language pass on the ORM client reference #8260 and docs(orm8): plain-language pass on the rest of the ORM reference section #8267" overstates it. query vs execute, verifyMarker, binding, db.raw, db.nativeEnums, db.contract, .first()/.firstOrThrow(), distinctOn, db.prepare, the per-query signal, MongoDB mode, MongoMiddleware and the SQLite client are on the reference pages on main; the configure(meta) callback and meta.annotate(...) are on the middleware pages (docs(orm): plain-language pass on the middleware section #8292), not the reference. db.context, db.stack and the static client (@prisma/orm-postgres/static ships postgresStatic in rc.11) are on no page. Both exist on the rc.11 facade type.
• audit/orm-client.md:41 is not marked. changes.md C15 says that file's flat-accessor claim "does not hold on rc.11", but the audit line carries no note, unlike audit/extras.md:35, which this PR marks "Overruled" in place for the streaming claim.

Proposed wording for the C15 sentence in "In review": "C15 needs no page changes: query vs execute, verifyMarker, binding, db.raw, db.nativeEnums, db.contract, .first() / .firstOrThrow(), distinctOn, db.prepare, the per-query signal, MongoDB mode, MongoMiddleware and the SQLite client are on the reference pages, and the configure(meta) callback and meta.annotate(...) are on the middleware pages; createInMemoryCacheStore is exported by @prisma/orm-extension-middleware-cache but the cache page documents the store and maxEntries options instead of the factory; the flat db.orm.User accessor is not in rc.11; db.context, db.stack and the static client (@prisma/orm-postgres/static) stay undocumented." Plus an "Overruled on rc.11" note on audit/orm-client.md:41 pointing at C15.

This would be the fifth reviewer fix round on this pull request, past the bound I work to, so I have asked the run's humans whether to push it or hand it back to the author. Not pushing until they answer.

— reviewer