docs(orm): Core concepts explains each piece in the order a reader meets it

[wmadden-electric]

The Core concepts page (/orm/core-concepts) is the one page that explains how Prisma ORM 8 fits together. Today its section headings run in vocabulary order:

The contract and the schema
Emitting: from source to artifacts
Hashes and the database signature
Queries compile to plans
The query APIs
The stack behind one package
Capabilities
Codecs
Extensions
Middleware
Migrations: a graph of contracts
How the CLI commands combine

After this change they run in the order a developer meets each piece, and each section says what the piece does for you:

The contract and the schema
Emit: build the contract into two files
The signature: which contract the database matches
Queries: every query is built before it runs
Migrations: steps from one contract to another
  The everyday change
  Planning a migration
  The db ref
  Adopting an existing database
  Iterating with db update
  If you know Git
The command vocabulary
The pieces underneath
What moved from Prisma ORM 7
The eight words

The decision

The page explains each piece when the reader needs it, says what it buys them, and names the Prisma ORM 7 thing it replaces. Every command claim on it matches the command's reference page under /cli. The reader it is written for is a developer who used Prisma ORM 7 for two years and has never seen version 8.

Why

Reader feedback on the Prisma ORM 8 docs says they read as if a model wrote them: source-code vocabulary, mechanism instead of action, several ideas per sentence. On this page the symptom was order: a reader met "hash", "plan", and "codec" before learning what a contract is for, and the everyday workflow (edit the contract, emit, plan, migrate) appeared only in the last section. The old page also carried a few claims that the reference pages contradict.

What changed, step by step

1. Order. The page opens with one idea: your app and your database each have an opinion about the data, and Prisma ORM 8 records in the database which contract it matches and checks that record. Then the contract and the schema, emit, the signature, queries, migrations, the command table, and a short glossary. The stack, database features, value conversion, extensions, and middleware become one paragraph each under "The pieces underneath", with a first sentence that says you do not need them for everyday work.
2. The everyday workflow comes first in the migrations section, with its three commands, and the section says it applies to every project, new or adopted. Planning, the db ref (with a table of which commands move it), adopting an existing database, and db update follow in that order.
3. Facts corrected against the reference pages, where the old page was wrong:
   • The app's runtime check only logs a warning on a signature mismatch and cannot be made to fail. db verify in the deploy pipeline is the check that stops a deploy.
   • Four commands write the signature, not three: db init, db sign, db migrate, and db update.
   • db init is not only for an empty database; it adds what is missing and stops on a destructive change.
   • A failed db migrate is safe to rerun on PostgreSQL because the run is one transaction; MongoDB has no such transaction.
   • Database features are checked at contract emit and when a query is built, not at startup.
   • A DateTime field comes back as a Temporal.Instant, not a JavaScript Date.
4. New material: the origin rules for migration plan (including MIGRATION.PLAN_ORIGIN_UNKNOWN), the adoption sequence with the automatic baseline, how to get from db update back to a committed migration, and a command table with what each of eleven commands reads and writes and when you run it.

How it was checked

• Four rounds of a cold read. Each round, a reviewer with no memory of writing the page read it once as the Prisma ORM 7 developer above and reported every sentence it could not restate, every word it had to guess, and every place it asked "so what do I type?". Each round was followed by a fix pass, and every fix was checked against a reference page; claims no page supports were left out.
• The fourth round still asks how a committed db ref describes several developers' databases, how merged branches become a path for db migrate, and for the contents of db.ts and prisma.config.ts. The linked pages (the migration graph, generating a migration, orm init) answer those, and the page stays a concepts page rather than a tutorial.
• The docs app's plain-language, sentence-rhythm, and machine-writing checks pass; lint:links reports 0 errors; the docs app tests pass (70).
• Rendered in the docs app at desktop and 375 pixels: the section order is as above, and the wide command table scrolls inside its wrapper at phone width.

Alternatives considered

• Keep the glossary order and patch the gaps. The problem was order and motivation, not missing terms.
• Cut the stack, capabilities, and codec sections. Their names appear in error messages, so they stay, shortened, under a heading that says they are not needed for everyday work.

Context

Slice 05 of the Prisma ORM 8 docs restructure. The page is written from the audit's source document, docs/orm-docs-audit/mental-model.md, and the spec is docs/orm-docs-audit/slices/05-core-concepts-from-mental-model/spec.md, both on the docs/orm8-docs-audit-design branch (#8243). Where the source document disagreed with a reference page, the reference page won, and the corrections are recorded at the end of the source document.

Agent: gulliver-20

🤖 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 30, 2026 4:10pm UTC
docs	Ready	Preview	Sep 30, 2026 4:10pm UTC
eclipse	Ready	Preview	Sep 30, 2026 4:10pm UTC
handbook	Error		Sep 30, 2026 4:10pm UTC
site	Ready	Preview	Sep 30, 2026 4:10pm UTC

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: b0aa3be8-4b55-4455-b47d-13a70c495e50

📥 Commits

Reviewing files that changed from the base of the PR and between 12eec49 and dfd2508.

📒 Files selected for processing (1)

• apps/docs/content/docs/orm/core-concepts.mdx

 _________________________________________________________________________
< Yo dawg, I heard you like code reviews, so I reviewed your code review. >
 -------------------------------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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

[github-actions]

🍈 Lychee Link Check Report

63 links: ✅ 0 OK | 🚫 0 errors | 🔀 0 redirects | 👻 63 excluded

✅ All links are working!

---

Full Statistics Table

Status	Count
✅ Successful	0
🔀 Redirected	0
👻 Excluded	63
🚫 Errors	0
⛔ Unsupported	0
⏳ Timeouts	0
❓ Unknown	0