docs(orm8): plain-language pass on the ORM client reference

[wmadden-electric]

Before, the MongoDB setup paragraph on the ORM client reference read:

Create a Mongo client with mongo(...). Models hang off db.orm and use the contract's root names too, but those are the lowercase plural collection names from the contract's roots map, not the PSL model names (db.orm.users, db.orm.posts, not db.orm.User).

After:

Create a MongoDB client with mongo(...). db.orm holds your models by collection name, with no schema in between: db.orm.users, db.orm.posts, not db.orm.User. The collection name is the one you set with @@map, or the model name with a lowercase first letter when you did not set one. dbName is the MongoDB database name.

Same fact, no "root names", no "roots map", no "facet".

The decision

This PR is the plain-language pass (C21) on orm/reference/orm-client.mdx, the same treatment the five fundamentals pages got in #8251. The page keeps its reference layout (Remarks, Options, Return type, Examples, PostgreSQL and MongoDB tabs) and every heading and anchor. What changed is the wording, the order of ideas, and the examples, plus the corrections the fact checks found.

Two decisions a reviewer should know about:

• The page no longer claims its examples are copied from a test suite. docs: add Prisma Next API reference section #8033 says they came from a local harness kept out of git, and no fixture in prisma/orm at rc.9 has this schema. Every example was instead checked call by call against the rc.9 source, and the result comments now read as illustrations of the shape.
• The heading "Array operations (MongoDB, unverified)" is now "Array operations (MongoDB)", with the old anchor pinned. The four operations have unit tests, and push/pull run against a live MongoDB in orm-ergonomics.test.ts.

What the fact checks corrected

The round-one fixes from the previous session were unverified, so this PR started with a full fact re-check against prisma/orm at 8.0.0-rc.9 (f889eeb89e), and ended with another after the wording rounds. Corrections that changed what the page says:

• TypeScript refuses all six update and delete methods without where() on PostgreSQL, not just update() and delete(). On MongoDB the check is at run time, code ORM.WHERE_MISSING, and covers upsert() too.
• The multi-table variant in the page's own schema is Bug on Task, so the ORM.OPERATION_UNSUPPORTED messages name those.
• The MongoDB update input is typed on the base model only; a variant field needs // @ts-expect-error. The MongoDB upsert() returns _id as a hex string, not an ObjectId.
• MongoFieldFilter.of passes any operator through, so $regex, $elemMatch, and $size are reachable; the page had said the library has no regex support anywhere.
• A misspelled field operation is a compile error, not undefined at run time.
• Aggregates called outside include() throw ORM.INCLUDE_INVALID. min() and max() are also null over an empty set. sum() and avg() accept a Time column, not an interval. avg() over an integer returns a floating-point number, not a rounded one.
• The shorthand object's null on MongoDB also matches a missing field. ORM.FILTER_UNSUPPORTED is PostgreSQL only, and the field type that triggers it is Json, not a vector.
• cursor() throws ORM.CURSOR_VALUE_MISSING when the cursor object leaves out a sort column.
• firstOrThrow() reads every matching row before returning the first.

The final re-check, after four wording rounds, found thirteen more drifts and fixed them. The ones a reader would have hit: a PostgreSQL DateTime filter takes a Temporal.Instant, not a Date (the example passed a Date); isRuntimeError is false for ORM.* errors, so the page no longer points catch blocks at it for those; create() and connect() take an object or an array on any relation; the grouped chain needs orderBy() before limit(), which the types enforce; setting an embedded object with set() needs every field.

After #8261 merged

Rebased onto main. #8261 had added a "Model and result types" section to the old page, so it is rewritten here against this page's schema and wording, with the same facts from the rc.10 release notes and shape.ts: the page's own ./contract.d import, the example User's fields, no SQLite, and the note that a contract emitted before rc.10 has no Models until you run contract emit again. One extra commit fixes a link on the SQL query builder page that #8262 pointed at #named-model-types; the heading's anchor is #model-and-result-types, and the docs link check fails on main because of it.

How it was checked

• Four reader rounds, each a fresh Opus reader per slice with the persona from .claude/skills/docs-reader-review/references/reader-persona.md, then a fixer per slice with the shared and page conventions and the rc.9 source. Round three and four ran with a "no longer than now" budget; the page went from 2,058 to 2,048 lines.
• Two fact re-checks, four Opus checkers each, claim by claim against the source.
• check-plain.sh, cspell, and the docs link check pass on the final page.

What a reviewer should know

• The reader reports, checker reports, and conventions files were removed from the branch in the last commit. They are in this branch's history at d104536 if you want to see what each round flagged.
• Two reader questions have no answer in the rc.9 source, so the page says nothing about them: an atomic increment or array operation on PostgreSQL through the ORM client, and the text of MongoDB's error when an array operation hits a non-array field.
• Readers on every round asked for more MongoDB depth (aggregation, more filter examples). That is the C24 content gap in changes.md, out of scope here.

Alternatives considered

• Rebase the example schema on the rc.9 test fixture so the "copied from a test suite" claim could stay. Rejected: the fixture has int4 ids, no enums, and no Task/Bug, so every example on the page and on the fundamentals pages would change.
• Drop the pinned anchors for the renamed headings. Rejected: links from other pages and from search results resolve through them.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated a cross-reference in the SQL query builder documentation to point to the “Model and result types” section.

[vercel]

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

Project	Deployment	Actions	Updated
blog	Ready	Preview	Sep 13, 2026 5:36am UTC
docs	Ready	Preview	Sep 13, 2026 5:36am UTC
eclipse	Ready	Preview	Sep 13, 2026 5:36am UTC
site	Ready	Preview	Sep 13, 2026 5:36am UTC

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 80345ccf-2004-4355-85c1-e155820c7261

📥 Commits

Reviewing files that changed from the base of the PR and between f6f037f and 1cfaeb7.

📒 Files selected for processing (1)

• apps/docs/content/docs/orm/reference/sql-query-builder.mdx

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

Walkthrough

The ResultType documentation now links to the ORM client’s “Model and result types” section. No API or runtime behavior changed.

Changes

ORM documentation link

Layer / File(s)	Summary
Update ResultType cross-reference apps/docs/content/docs/orm/reference/sql-query-builder.mdx	Updated the link text from “Named model types” to “Model and result types” and changed the anchor to #model-and-result-types.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~2 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 1cfae

The updated cross-reference points to the intended documentation section, so the change is ready to merge.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately identifies the main change: a plain-language update to the ORM client reference. It is concise and specific.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/orm8-plain-language-orm-client

---

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

[github-actions]

🍈 Lychee Link Check Report

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

✅ All links are working!

---

Full Statistics Table

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