docs: run the AI-signs prose checker in CI and clean the pages it flags

.claude/skills/README.md

@@ -17,6 +17,7 @@ A skill is a folder with a `SKILL.md` (the instructions) and sometimes `referenc
 | [`content-create-hero-image`](content-create-hero-image/SKILL.md) | Generate a post's hero (SVG) and social/OG image (PNG) in the Eclipse house style | "Create a cover image for my Compute post" |
 | [`docs-writer`](docs-writer/README.md) | Write or rewrite developer docs (how-to, concept, reference) | "Write a how-to for deploying to Prisma Compute" |
 | [`docs-reader-review`](docs-reader-review/SKILL.md) | Check a written page reads for an ordinary user: banned-jargon, staccato, and AI-signs checks, then a fresh reviewer reads it cold and marks what it cannot follow | "Reader review this page" |
+| [`docs-reader-review/scripts/check-ai-signs.sh`](docs-reader-review/scripts/check-ai-signs.sh) | Runs in CI (`docs-prose.yml`) on every hand-written docs page a pull request adds or changes (the generated ORM and CLI error-reference pages are skipped; their text is fixed upstream); its word list is dated in `references/ai-writing-signs.md` and needs re-checking against Wikipedia's [Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) about every six months | "Update the AI-signs word list" |
 | [`docs-agent-ready`](docs-agent-ready/SKILL.md) | Hold the docs' agent-readiness invariants (llms.txt budgets, coverage, skill/MCP endpoints) when editing them | "Add a new docs section to llms.txt" |
 
 ---

.claude/skills/docs-reader-review/references/ai-writing-signs.md

@@ -32,7 +32,9 @@ Words that models use far more often than people do. Each row gives the plain re
 | authored, relocated, attempted, passed away, commenced, terminated | wrote, moved, tried, died, started, stopped |
 | in order to, as a result of, the fact that, a part of, all of the | to, because, that, part of, all the |
 
-Wikipedia notes that the over-used words change with each model generation, so this table is a snapshot. When a reviewer flags a word that reads as machine-made and it is not here, add it.
+Wikipedia notes that the over-used words change with each model generation, so this table is a snapshot. When a reviewer flags a word that reads as machine-made and it is not here, add it here and to the `vocab` pattern in `scripts/check-ai-signs.sh`.
+
+**Last reconciled with the Wikipedia page: 2026-09-16.** The page's "High density of AI vocabulary" section lists which words belong to which model generation and retires words that fall out of use. Re-read that section whenever a new model generation is in wide use (roughly every six months), update this table and the checker, and bump this date. The `docs-prose` workflow runs the checker on every hand-written docs page a pull request adds or changes (the generated ORM and CLI error-reference pages are skipped, because their text is fixed upstream), so a stale list means stale enforcement.
 
 ## Sentence shapes
 

.claude/skills/docs-reader-review/scripts/check-ai-signs.sh

@@ -16,7 +16,7 @@ set -u
 # Apostrophe in "it's", "isn't", "here's": straight or curly, as a literal alternation so it
 # matches under a C locale too, where "." is a single byte and would never match a three-byte ’.
 q="('|’)"
-vocab="\b(additionally|moreover|furthermore),|\b(crucial|pivotal|robust|seamless(ly)?|leverag(e|es|ed|ing)|utiliz(e|es|ed|ing)|enhanc(e|es|ed|ing)|bolster(s|ed|ing)?|foster(s|ed|ing)?|cultivat(e|es|ed|ing)|empower(s|ed|ing)?|showcas(e|es|ed|ing)|underscor(e|es|ed|ing)|delv(e|es|ed|ing)|deep dive|tapestry|testament to|vibrant|intricate|nuanced|streamlined|cutting-edge|groundbreaking|garner(s|ed)?|boasts?|interplay|synergy|paradigm|meticulous(ly)?|thoughtfully|invaluable|game-chang(er|ing))\b|\b(in today${q}s world|in the modern era|ever-evolving|the landscape of|the realm of)\b|\b(align|aligns|aligned|resonate|resonates) with\b"
+vocab="\b(additionally|moreover|furthermore),|\b(crucial|pivotal|robust|seamless(ly)?|leverag(e|es|ed|ing)|utiliz(e|es|ed|ing)|enhanc(e|es|ed|ing)|bolster(s|ed|ing)?|foster(s|ed|ing)?|cultivat(e|es|ed|ing)|empower(s|ed|ing)?|showcas(e|es|ed|ing)|underscor(e|es|ed|ing) (the|its|how|why|what|a|an)|delv(e|es|ed|ing)|deep dive|tapestry|testament to|vibrant|intricate|nuanced|streamlined|cutting-edge|groundbreaking|garner(s|ed)?|boasts?|interplay|synergy|paradigm|meticulous(ly)?|thoughtfully|invaluable|game-chang(er|ing))\b|\b(in today${q}s world|in the modern era|ever-evolving|the landscape of|the realm of)\b|\b(align|aligns|aligned|resonate|resonates) with\b"
 shapes="\b(serves?|acts?|functions?|stands?) as an?\b|\bnot (just|only|merely) [^.]{1,60}\bbut( also)?\b|\bisn${q}t [^.]{1,40}, it${q}s\b|\b(is|are|was|were|has been|have been) (closely |directly )?associated with\b|\bin connection with\b|\b(it${q}s|it is) (important|worth|crucial|essential|critical) (to note|noting|to remember|to consider|to keep in mind)\b|\bworth noting\b|\bkeep in mind that\b|\b(in summary|in conclusion|to recap|to sum up|overall),|\bdespite (these|its|their) (challenges|limitations|advantages)\b|\bfaces? (several|numerous|many|a number of) challenges\b|\b(many|most) (developers|teams|users|engineers) (find|agree|prefer|consider)\b|\b(it is|it${q}s) widely (considered|regarded|accepted)\b|\bexperts (recommend|agree|suggest)\b|\bbest practices? (suggests?|dictates?|recommends?)\b"
 leaked="\bi hope this helps\b|\blet me know if\b|\bwould you like me to\b|\bcertainly!|\bhere${q}s an? (breakdown|overview|summary) of\b|\bbelow is an? (breakdown|overview|summary)\b|\bin this (section|guide|article|post),? we (will|${q}ll)\b|\bthis (document|page|guide|article) aims to\b|\bas mentioned (above|earlier|previously)\b|\[(your name|link to [^]]*|insert [^]]*)\]|\bINSERT_[A-Z_]+\b|\b20[0-9]{2}-(xx|XX)-(xx|XX)\b|\bbased on (the )?available (information|sources)\b|\bnot (widely|extensively|well) (documented|available|known)\b|\bas of my last\b|\bas an ai\b"
 # Literal alternation, not a bracket expression: under a C locale grep matches bracket members

.github/workflows/docs-prose.yml

@@ -0,0 +1,37 @@
+name: Docs Prose
+
+# Runs the AI-signs prose checker from .claude/skills/docs-reader-review over
+# every docs page a pull request adds or changes. The generated error-reference
+# pages are skipped: their text comes from prisma/prisma and prisma/prisma-cli,
+# so the fix for a hit there is upstream.
+
+on:
+  pull_request:
+    paths:
+      - "apps/docs/content/docs/**/*.mdx"
+      - ".claude/skills/docs-reader-review/**"
+      - ".github/workflows/docs-prose.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  prose:
+    name: Check docs prose for signs of AI writing
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Run the checker on changed pages
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+        run: |
+          mapfile -t pages < <(git diff --name-only --diff-filter=AMR "$BASE"...HEAD -- 'apps/docs/content/docs/**/*.mdx' \
+            | grep -v -E '^apps/docs/content/docs/(orm/reference|cli)/error-reference\.mdx$' || true)
+          if [[ ${#pages[@]} -eq 0 ]]; then echo "No docs pages changed"; exit 0; fi
+          printf '%s\n' "${pages[@]}"
+          .claude/skills/docs-reader-review/scripts/check-ai-signs.sh "${pages[@]}"

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

@@ -115,7 +115,7 @@ Run:
 npx prisma@latest contract emit
 ```
 
-This refreshes `src/prisma/contract.json` and `src/prisma/contract.d.ts` so the runtime and query APIs are aligned with the contract you just reviewed.
+This refreshes `src/prisma/contract.json` and `src/prisma/contract.d.ts` so the runtime and query APIs match the contract you just reviewed.
 
 ## 6. Run a simple high-level query
 

apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/postgresql.mdx

@@ -102,7 +102,7 @@ After you are happy with the contract, run:
 npx prisma@latest contract emit
 ```
 
-This refreshes `src/prisma/contract.json` and `src/prisma/contract.d.ts` so the runtime and query APIs are aligned with the contract you just reviewed.
+This refreshes `src/prisma/contract.json` and `src/prisma/contract.d.ts` so the runtime and query APIs match the contract you just reviewed.
 
 ## 6. Sign the database
 

apps/docs/content/docs/accelerate/evaluating.mdx

@@ -12,13 +12,13 @@ Evaluate Accelerate with high volume to see how it performs under load.
 
 ## How Accelerate's connection pool optimizes performance under load
 
-Prisma Accelerate employs a dynamic, serverless connection pooling infrastructure. When a request is made, a connection pool is quickly provisioned for the project in the region assigned while configuring Prisma Accelerate. This connection pool remains active, serving many additional requests while reusing established database connections. The connection pool will disconnect after a period of inactivity, so it’s important to evaluate Prisma Accelerate with a consistent stream of traffic.
+Prisma Accelerate employs a dynamic, serverless connection pooling infrastructure. When a request is made, a connection pool is quickly provisioned for the project in the region assigned while configuring Prisma Accelerate. This connection pool remains active, serving many additional requests while reusing established database connections. The connection pool will disconnect after a period of inactivity, so it's important to evaluate Prisma Accelerate with a consistent stream of traffic.
 
 **Key Benefits:**
 
 - **Optimized Query Performance:** The serverless connection pooler adapts to the query load, ensuring the database connections are managed efficiently during peak demand.
 
-  > Prisma Accelerate’s connection pooler cannot improve the performance of queries in the database. In scenarios where query performance is an issue, we recommend optimizing the Prisma query, applying indexes, or utilizing Accelerate’s edge caching.
+  > Prisma Accelerate's connection pooler cannot improve the performance of queries in the database. In scenarios where query performance is an issue, we recommend optimizing the Prisma query, applying indexes, or using Accelerate's edge caching.
 
 - **Maximize Connection Reuse:** Executing a consistent volume of queries helps maintain active instances of Accelerate connection poolers. This increases connection reuse, ensuring faster response times for subsequent queries.
 
@@ -124,9 +124,9 @@ main()
 
 ## Evaluating Prisma Accelerate caching performance
 
-Prisma Accelerate’s edge cache is also optimized for a high volume of queries. The cache automatically optimizes for repeated queries. As a result, the cache hit rate will increase as the query frequency does. Adding a query result to the cache is also non-blocking, so a short burst of queries might not utilize the cache or a sustained load.
+Prisma Accelerate's edge cache is also optimized for a high volume of queries. The cache automatically optimizes for repeated queries. As a result, the cache hit rate will increase as the query frequency does. Adding a query result to the cache is also non-blocking, so a short burst of queries might not hit the cache the way a sustained load does.
 
-To evaluate Accelerate’s edge caching, you can modify the above script with the below:
+To evaluate Accelerate's edge caching, modify the script above as follows:
 
 ```typescript
 import { PrismaClient } from "@prisma/client";

apps/docs/content/docs/accelerate/getting-started.mdx

@@ -195,7 +195,7 @@ As of Prisma version `5.2.0` you can use Prisma Studio with the Accelerate conne
 
 If your application requires real-time or near-real-time data, cache invalidation ensures that users see the most current data, even when using a large `ttl` (Time-To-Live) or `swr` (Stale-While-Revalidate) [cache strategy](/accelerate/caching). By invalidating your cache, you can bypass extended caching periods to show live data whenever it's needed.
 
-For example, if a dashboard displays customer information and a customer’s contact details change, cache invalidation allows you to refresh only that data instantly, ensuring support staff always see the latest information without waiting for the cache to expire.
+For example, if a dashboard displays customer information and a customer's contact details change, cache invalidation allows you to refresh only that data instantly, ensuring support staff always see the latest information without waiting for the cache to expire.
 
 To invalidate a cached query result, you can add tags and then use the `$accelerate.invalidate` API.
 

apps/docs/content/docs/accelerate/local-development.mdx

@@ -8,7 +8,7 @@ metaDescription: Learn how to use Prisma Accelerate in a development environment
 
 Prisma Accelerate provides connection pooling and a global database cache for production traffic.
 
-In development environments, you may want to use a local database to minimize expenses. Furthermore, you may consider extending Prisma Client with the Accelerate client extension once so that you can use a local database in development and a hosted database with Accelerate’s connection pooling and caching enabled. This eliminates the need for conditional logic to switch clients between development and production.
+In development environments, you may want to use a local database to minimize expenses. You may also consider extending Prisma Client with the Accelerate client extension once so that you can use a local database in development and a hosted database with Accelerate's connection pooling and caching enabled. This eliminates the need for conditional logic to switch clients between development and production.
 
 This guide will explain how to use Prisma Accelerate client extension in a development environment with a local database.
 

apps/docs/content/docs/accelerate/more/faq.mdx

@@ -116,17 +116,17 @@ No. We currently do not have any plans for supporting other ORMs/query builders
 
 The [Time-to-live](/accelerate/caching) (`ttl`) parameter can be set for up to a _year_. However, items within the cache may be evicted if they are not frequently accessed.
 
-Based on our experimentation, we’ve seen cache items persist for around 18 hours. While items may remain in the cache for an extended period if they are actively accessed, there is no guarantee.
+Based on our experimentation, we've seen cache items persist for around 18 hours. While items may remain in the cache for an extended period if they are actively accessed, there is no guarantee.
 
 > **Note**: Even frequently accessed items may occasionally be evicted from the cache. It's unlikely for an item to survive for up to or longer than a month, regardless of its activity level.
 
-## Why doesn’t Accelerate fall back to the direct connection string during a service disruption?
+## Why doesn't Accelerate fall back to the direct connection string during a service disruption?
 
 In the rare event of a service disruption, falling back to a direct connection would bypass the connection pool. This could potentially deplete the database's available connections and cause other issues on the database level.
 
 If there is a service disruption, it's recommended to verify on the [status page](https://pris.ly/data-platform-status). You can reach out to one of Prisma's [support channels](/console/more/support) for assistance.
 
-> **Note:** Additionally, it's worth noting that some edge function runtime environments may not support direct connections with Prisma ORM. For further details, refer to our [Edge functions documentation](/orm/v7/prisma-client/deployment/edge/overview).
+> **Note:** Some edge function runtime environments may not support direct connections with Prisma ORM. For further details, refer to our [Edge functions documentation](/orm/v7/prisma-client/deployment/edge/overview).
 
 ## Are each of the queries within an interactive transaction counted separately for billing?
 
@@ -184,11 +184,11 @@ Here is a [demo app](https://pris.ly/test-cache-invalidation) to test the time i
 
 ## When should I use the cache invalidate API?
 
-The [cache invalidate API](/accelerate/caching) is essential when data consistency cannot wait for the cache’s standard expiration or revalidation. Key use cases include:
+The [cache invalidate API](/accelerate/caching) is essential when data consistency cannot wait for the cache's standard expiration or revalidation. Key use cases include:
 
 - **Content updates**: When critical changes occur, such as edits to a published article, product updates, or profile modifications, that need to be visible immediately.
 - **Inventory management**: In real-time applications, like inventory or booking systems, where stock levels, availability, or reservation statuses must reflect the latest information.
-- **High-priority data**: For time-sensitive data, like breaking news or urgent notifications, where it’s essential for users to see the most current information right away.
+- **High-priority data**: For time-sensitive data, like breaking news or urgent notifications, where it's essential for users to see the most current information right away.
 
 ## How does Accelerate count queries for billing?
 
@@ -200,7 +200,7 @@ Queries are counted regardless of whether they are served from the cache or the
 
 If you previously signed up using GitHub and want to switch to email and password login, follow these steps:
 
-### 1. Verify Your GitHub Email Address
+### 1. Verify your GitHub email address
 
 - Check the primary email address associated with your GitHub account (e.g., from your GitHub profile or notification settings).
 
@@ -210,7 +210,7 @@ If you previously signed up using GitHub and want to switch to email and passwor
 - Use the **same email address** linked to your GitHub account to create the new account.
 - Our system will automatically connect your new email/password account to your existing data.
 
-### 3. Test Your Login
+### 3. Test your login
 
 - Log out and try logging in with your email and the password you just created.
 

apps/docs/content/docs/accelerate/more/known-limitations.mdx

@@ -39,4 +39,4 @@ Accelerate does not support direct IPv4 addresses in MongoDB connection strings.
 - **IPv4 connection string** (not supported): `mongodb://user:password@192.168.1.100:27017/db_name`
 - **DNS record connection string** (supported): `mongodb://user:password@my-database.example.com:27017/db_name`
 
-For additional details on Accelerate’s IPv6-first design, refer to our [blog post](https://www.prisma.io/blog/accelerate-ipv6-first).
+For additional details on Accelerate's IPv6-first design, refer to our [blog post](https://www.prisma.io/blog/accelerate-ipv6-first).