From 12af6b91f333090adb8e8de7c83bc25a64de8eb1 Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sat, 16 May 2026 12:06:09 +0100
Subject: [PATCH 1/8] docs: add documentation style guide and bring all docs up
 to standard

Adds a Documentation Style Guide (contributing/docs-style-guide) distilling
Astro-grade conventions: readability, neutral voice (no we/us/let's), code-sample
intros, Expressive Code diffs, the upgrade-guide breaking-changes format, headings,
and EmDash specifics (sandboxed vs native, Atmosphere accounts, experimental
surfaces, no messages.po in PRs).

Audits and updates every other docs page against it. Excludes the pages in
PR #1059 (plugin CLI/manifest/authoring docs). Also fixes real defects found
during the audit: broken Astro frontmatter in three coming-from/wordpress code
samples, two dead internal links (plugin-porting -> porting-plugins), an
inconsistent field-type count, and competitor name-drops.
---
 docs/astro.config.mjs                         |   4 +
 .../docs/coming-from/astro-for-wp-devs.mdx    |  12 +-
 docs/src/content/docs/coming-from/astro.mdx   |  12 +-
 .../content/docs/coming-from/wordpress.mdx    |  15 +-
 .../src/content/docs/concepts/admin-panel.mdx | 121 ++++++++-------
 .../content/docs/concepts/architecture.mdx    | 113 +++++++-------
 .../src/content/docs/concepts/collections.mdx |  54 +++----
 .../content/docs/concepts/content-model.mdx   | 102 ++++++-------
 .../docs/contributing/docs-style-guide.mdx    | 140 ++++++++++++++++++
 docs/src/content/docs/contributing/index.mdx  |   2 +-
 .../content/docs/contributing/translating.mdx |   6 +-
 .../content/docs/deployment/cloudflare.mdx    |   4 +-
 docs/src/content/docs/deployment/database.mdx |   2 +-
 docs/src/content/docs/deployment/nodejs.mdx   |   8 +-
 docs/src/content/docs/deployment/storage.mdx  |   6 +
 docs/src/content/docs/docs-mcp.mdx            |  28 ++--
 docs/src/content/docs/getting-started.mdx     |  28 ++--
 .../content/docs/guides/atmosphere-auth.mdx   |  10 +-
 .../content/docs/guides/authentication.mdx    |  14 +-
 .../src/content/docs/guides/create-a-blog.mdx |  20 +--
 .../docs/guides/internationalization.mdx      |   6 +-
 .../src/content/docs/guides/media-library.mdx |  14 +-
 docs/src/content/docs/guides/preview.mdx      |  10 +-
 docs/src/content/docs/guides/sections.mdx     |  24 ++-
 .../src/content/docs/guides/site-settings.mdx |  10 +-
 docs/src/content/docs/guides/taxonomies.mdx   |  18 ++-
 docs/src/content/docs/guides/widgets.mdx      |   4 +
 .../docs/guides/working-with-content.mdx      |   8 +-
 .../src/content/docs/guides/x402-payments.mdx |   4 +
 docs/src/content/docs/index.mdx               |   9 +-
 docs/src/content/docs/introduction.mdx        |   4 +-
 .../content/docs/migration/content-import.mdx |  32 ++--
 .../content/docs/migration/from-wordpress.mdx |   2 +-
 .../docs/migration/porting-plugins.mdx        |   6 +-
 .../creating-native-plugins/distributing.mdx  |  10 +-
 .../page-fragments.mdx                        |  10 +-
 .../portable-text-components.mdx              |   2 +-
 .../creating-native-plugins/react-admin.mdx   |  16 +-
 .../your-first-native-plugin.mdx              |  14 +-
 docs/src/content/docs/plugins/field-kit.mdx   |  22 +--
 docs/src/content/docs/plugins/installing.mdx  |   6 +-
 docs/src/content/docs/plugins/overview.mdx    |   2 +-
 docs/src/content/docs/reference/api.mdx       |  68 ++++++---
 docs/src/content/docs/reference/cli.mdx       |  24 +--
 .../content/docs/reference/configuration.mdx  |  93 +++++++-----
 .../content/docs/reference/field-types.mdx    |  22 +--
 docs/src/content/docs/reference/hooks.mdx     |   4 +-
 .../src/content/docs/reference/mcp-server.mdx |   8 +
 docs/src/content/docs/reference/rest-api.mdx  |  12 +-
 .../content/docs/themes/creating-themes.mdx   |  22 ++-
 docs/src/content/docs/themes/overview.mdx     |  49 ++----
 .../content/docs/themes/porting-wp-themes.mdx |   9 +-
 docs/src/content/docs/themes/seed-files.mdx   |  22 +--
 docs/src/content/docs/why-emdash.mdx          |   2 +-
 54 files changed, 783 insertions(+), 486 deletions(-)
 create mode 100644 docs/src/content/docs/contributing/docs-style-guide.mdx

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index a7f0157d7..ce2cc21cc 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -147,6 +147,10 @@ export default defineConfig({
 					collapsed: true,
 					items: [
 						{ label: "Contributor Guide", slug: "contributing" },
+						{
+							label: "Documentation Style Guide",
+							slug: "contributing/docs-style-guide",
+						},
 						{ label: "Translating EmDash", slug: "contributing/translating" },
 					],
 				},
diff --git a/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx b/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx
index a2ff96094..3e611785d 100644
--- a/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx
+++ b/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx
@@ -41,7 +41,7 @@ WordPress themes have a flat structure with magic filenames. Astro uses explicit
 | `style.css`                 | `src/styles/`      | Global CSS         |
 | `functions.php`             | `astro.config.mjs` | Site configuration |
 
-A typical Astro project:
+The following tree shows a typical Astro project layout:
 
 ```
 src/
@@ -64,6 +64,8 @@ src/
 1. **Frontmatter** (between `---` fences) — Server-side code, like PHP at the top of a template
 2. **Template** — HTML with expressions, like the rest of a PHP template
 
+The following component declares typed props in the frontmatter and renders them in the template:
+
 ```astro title="src/components/PostCard.astro"
 ---
 // Frontmatter: runs on server, never sent to browser
@@ -183,7 +185,7 @@ const { title, featured = false } = Astro.props;
 </article>
 ```
 
-Usage:
+The following markup uses that component, passing the default slot and a named `footer` slot:
 
 ```astro
 <Card title="Hello" featured>
@@ -249,7 +251,7 @@ The difference: slots receive child elements at the call site, while WordPress h
 
 ## Layouts
 
-Layouts wrap pages with common HTML structure—the `<head>`, header, footer, and anything shared across pages. This replaces `header.php` + `footer.php`.
+Layouts wrap pages with common HTML structure—the `<head>`, header, footer, and anything shared across pages. This replaces `header.php` + `footer.php`. The following layout defines that shared shell and exposes a slot for page content:
 
 ```astro title="src/layouts/Base.astro"
 ---
@@ -402,9 +404,9 @@ For simple interactions, add a `<script>` tag:
 
 Scripts are bundled and deduplicated automatically. If this component appears twice on a page, the script runs once.
 
-### Advanced: Interactive Components
+### Advanced interactive components
 
-For more complex interactivity, Astro can load JavaScript components (React, Vue, Svelte) on demand. This is optional—most sites work fine with just `<script>` tags.
+For more complex interactivity, Astro can load JavaScript components (React, Vue, Svelte) on demand. This is optional—most sites work fine with just `<script>` tags. The following page loads a component only when it scrolls into view:
 
 ```astro title="src/pages/index.astro"
 ---
diff --git a/docs/src/content/docs/coming-from/astro.mdx b/docs/src/content/docs/coming-from/astro.mdx
index d2895b88d..f1c847018 100644
--- a/docs/src/content/docs/coming-from/astro.mdx
+++ b/docs/src/content/docs/coming-from/astro.mdx
@@ -69,6 +69,8 @@ EmDash requires two configuration files.
 
 ### Astro Integration
 
+The following configuration registers EmDash as an Astro integration in server output mode:
+
 ```ts title="astro.config.mjs"
 import { defineConfig } from "astro/config";
 import emdash, { local } from "emdash/astro";
@@ -90,6 +92,8 @@ export default defineConfig({
 
 ### Live Collections Loader
 
+The following file registers EmDash as a live content source:
+
 ```ts title="src/live.config.ts"
 import { defineLiveCollection } from "astro:content";
 import { emdashLoader } from "emdash/runtime";
@@ -101,7 +105,7 @@ export const collections = {
 };
 ```
 
-This registers EmDash as a live content source. The `_emdash` collection internally routes to your content types (posts, pages, products).
+The `_emdash` collection internally routes to your content types (posts, pages, products).
 
 ## Querying Content
 
@@ -204,6 +208,8 @@ EmDash provides APIs for WordPress-style features that don't exist in Astro's co
 
 ### Navigation Menus
 
+The following layout fetches a menu by location and renders it with nested items:
+
 ```astro title="src/layouts/Base.astro"
 ---
 import { getMenu } from "emdash";
@@ -233,6 +239,8 @@ const primaryMenu = await getMenu("primary");
 
 ### Widget Areas
 
+The following layout fetches a widget area and renders each widget:
+
 ```astro title="src/layouts/BlogPost.astro"
 ---
 import { getWidgetArea } from "emdash";
@@ -257,6 +265,8 @@ const sidebar = await getWidgetArea("sidebar");
 
 ### Site Settings
 
+The following component reads global site settings and renders a logo or title:
+
 ```astro title="src/components/Header.astro"
 ---
 import { getSiteSettings, getSiteSetting } from "emdash";
diff --git a/docs/src/content/docs/coming-from/wordpress.mdx b/docs/src/content/docs/coming-from/wordpress.mdx
index 75e41935c..e0d8c0b27 100644
--- a/docs/src/content/docs/coming-from/wordpress.mdx
+++ b/docs/src/content/docs/coming-from/wordpress.mdx
@@ -113,6 +113,8 @@ where: { category: "news" },
 
 ### Getting a Single Entry
 
+The following examples fetch one entry by identifier and render it, in WordPress and in EmDash:
+
 <Tabs>
 	<TabItem label="WordPress">
 ```php title="single.php"
@@ -134,7 +136,8 @@ import { PortableText } from "emdash/ui";
 const { slug } = Astro.params;
 const { entry: post } = await getEmDashEntry("posts", slug);
 
-## if (!post) return Astro.redirect("/404");
+if (!post) return Astro.redirect("/404");
+---
 
 <article>
   <h1>{post.data.title}</h1>
@@ -198,6 +201,8 @@ const { post } = Astro.props;
 </article>
 ```
 
+The following page imports that component and renders it for each post:
+
 ```astro title="src/pages/index.astro"
 ---
 import PostCard from "../components/PostCard.astro";
@@ -233,7 +238,8 @@ wp_nav_menu([
 ---
 import { getMenu } from "emdash";
 
-## const menu = await getMenu("primary");
+const menu = await getMenu("primary");
+---
 
 <nav>
   <ul>
@@ -270,7 +276,8 @@ Widget areas work like sidebars in WordPress:
 import { getWidgetArea } from "emdash";
 import { PortableText } from "emdash/ui";
 
-## const sidebar = await getWidgetArea("sidebar");
+const sidebar = await getWidgetArea("sidebar");
+---
 
 {sidebar && (
 
@@ -299,6 +306,8 @@ Site options and customizer settings map to `getSiteSetting()`:
 | `get_option('date_format')` | `getSiteSetting("dateFormat")` |
 | `home_url()`                | `Astro.site`                   |
 
+The following example reads individual settings with `getSiteSetting()`:
+
 ```ts
 import { getSiteSetting } from "emdash";
 
diff --git a/docs/src/content/docs/concepts/admin-panel.mdx b/docs/src/content/docs/concepts/admin-panel.mdx
index e91a915bb..c45a8eb21 100644
--- a/docs/src/content/docs/concepts/admin-panel.mdx
+++ b/docs/src/content/docs/concepts/admin-panel.mdx
@@ -7,7 +7,9 @@ import { Aside, Card, CardGrid, Steps } from "@astrojs/starlight/components";
 
 The EmDash admin panel is a React single-page application embedded in your Astro site. It provides a complete content management interface for editors and administrators.
 
-## Architecture Overview
+## Architecture overview
+
+The following diagram shows how the admin panel sits inside the Astro shell:
 
 ```
 ┌────────────────────────────────────────────────────────────────┐
@@ -30,9 +32,9 @@ The EmDash admin panel is a React single-page application embedded in your Astro
 └────────────────────────────────────────────────────────────────┘
 ```
 
-The admin is a "big island" React app. Astro handles the shell and authentication; all navigation and rendering inside the admin is client-side.
+The admin is a single React island. Astro handles the shell and authentication; all navigation and rendering inside the admin is client-side.
 
-## Technology Stack
+## Technology stack
 
 | Layer       | Technology            | Purpose                                  |
 | ----------- | --------------------- | ---------------------------------------- |
@@ -45,13 +47,13 @@ The admin is a "big island" React app. Astro handles the shell and authenticatio
 | **Editor**  | TipTap                | Rich text editing (Portable Text)        |
 
 <Aside type="note">
-	Kumo is Cloudflare's design system, built on Base UI primitives with Tailwind styling. It's
+	Kumo is Cloudflare's design system, built on Base UI primitives with Tailwind styling. It is
 	installed as a dependency of the admin package.
 </Aside>
 
-## Route Structure
+## Route structure
 
-The admin mounts at `/_emdash/admin/` and uses client-side routing:
+The admin mounts at `/_emdash/admin/` and uses client-side routing. The following table lists the available routes:
 
 | Path                       | Screen                      |
 | -------------------------- | --------------------------- |
@@ -72,15 +74,15 @@ The admin mounts at `/_emdash/admin/` and uses client-side routing:
 	have permission to manage.
 </Aside>
 
-## Manifest-Driven UI
+## Manifest-driven UI
 
-The admin doesn't hardcode knowledge of collections or plugins. Instead, it fetches a manifest from the server:
+The admin does not hardcode knowledge of collections or plugins. Instead, it fetches a manifest from the server with the following request:
 
 ```
 GET /_emdash/api/manifest
 ```
 
-Response:
+The server responds with the collections, plugins, and taxonomies the current user can access:
 
 ```json
 {
@@ -110,29 +112,35 @@ Response:
 }
 ```
 
-The admin builds its navigation, forms, and editors entirely from this manifest. Benefits:
+The admin builds its navigation, forms, and editors entirely from this manifest. This means:
+
+- Schema changes appear immediately, with no admin rebuild needed.
+- Plugin pages and widgets integrate automatically from the manifest.
+- Zod schemas stay on the server, keeping type safety at the boundary.
 
-- **Schema changes appear immediately** — No admin rebuild needed
-- **Plugin UI integrates automatically** — Pages and widgets from the manifest
-- **Type safety at the boundary** — Zod schemas stay on the server
+## Data flow
 
-## Data Flow
+A request through the admin follows these steps:
 
 <Steps>
-	1. **Admin SPA loads** — TanStack Router initializes 2. **Fetch manifest** — TanStack Query caches
-	collection/plugin metadata 3. **Build navigation** — Sidebar generated from manifest 4. **User
-	navigates** — Client-side routing, no page reload 5. **Fetch data** — TanStack Query requests
-	content from REST APIs 6. **Render forms** — Field editors generated from manifest field
-	descriptors 7. **Submit changes** — Mutations via TanStack Query, optimistic updates 8. **Server
-	validates** — Zod schemas on the server, errors returned as JSON
+1. The admin SPA loads and TanStack Router initializes.
+2. TanStack Query fetches and caches the manifest's collection and plugin metadata.
+3. The sidebar navigation is generated from the manifest.
+4. The user navigates with client-side routing, with no page reload.
+5. TanStack Query fetches content from the REST APIs.
+6. Field editors are generated from the manifest's field descriptors.
+7. Changes are submitted as TanStack Query mutations with optimistic updates.
+8. The server validates against Zod schemas and returns any errors as JSON.
 </Steps>
 
-## REST API Endpoints
+## REST API endpoints
 
-The admin communicates exclusively through REST APIs:
+The admin communicates exclusively through REST APIs.
 
 ### Content APIs
 
+The content APIs handle entry CRUD, revisions, and preview URLs:
+
 | Method   | Endpoint                                   | Purpose              |
 | -------- | ------------------------------------------ | -------------------- |
 | `GET`    | `/api/content/:collection`                 | List entries         |
@@ -145,6 +153,8 @@ The admin communicates exclusively through REST APIs:
 
 ### Schema APIs
 
+The schema APIs manage collections and fields:
+
 | Method   | Endpoint                                      | Purpose            |
 | -------- | --------------------------------------------- | ------------------ |
 | `GET`    | `/api/schema`                                 | Export full schema |
@@ -158,6 +168,8 @@ The admin communicates exclusively through REST APIs:
 
 ### Media APIs
 
+The media APIs handle uploads and the media library:
+
 | Method   | Endpoint                 | Purpose                 |
 | -------- | ------------------------ | ----------------------- |
 | `GET`    | `/api/media`             | List media items        |
@@ -168,6 +180,8 @@ The admin communicates exclusively through REST APIs:
 
 ### Other APIs
 
+Settings, menus, widgets, taxonomies, and plugin state use these endpoints:
+
 | Endpoint               | Purpose                  |
 | ---------------------- | ------------------------ |
 | `/api/settings`        | Site settings (GET/POST) |
@@ -178,7 +192,7 @@ The admin communicates exclusively through REST APIs:
 
 ## Pagination
 
-All list endpoints use cursor-based pagination:
+All list endpoints use cursor-based pagination. A list response includes the items and an optional cursor for the next page:
 
 ```json
 {
@@ -187,7 +201,7 @@ All list endpoints use cursor-based pagination:
 }
 ```
 
-Fetch the next page:
+To fetch the next page, pass the cursor back as a query parameter:
 
 ```
 GET /api/content/posts?cursor=eyJpZCI6IjAxSjEyMzQ1NiJ9
@@ -198,12 +212,11 @@ GET /api/content/posts?cursor=eyJpZCI6IjAxSjEyMzQ1NiJ9
 	requests.
 </Aside>
 
-## Plugin Admin UI
+## Plugin admin UI
 
-Plugins can extend the admin with pages and dashboard widgets. The integration generates a virtual module with static imports:
+Plugins can extend the admin with pages and dashboard widgets. The integration generates a virtual module with static imports for each plugin's admin entry point:
 
-```ts
-// virtual:emdash/plugin-admins (generated)
+```ts title="virtual:emdash/plugin-admins (generated)"
 import * as pluginAdmin0 from "@emdash-cms/plugin-seo/admin";
 import * as pluginAdmin1 from "@emdash-cms/plugin-analytics/admin";
 
@@ -213,12 +226,11 @@ export const pluginAdmins = {
 };
 ```
 
-### Plugin Pages
+### Plugin pages
 
-Plugin pages mount under `/_emdash/admin/plugins/:pluginId/*`:
+Plugin pages mount under `/_emdash/admin/plugins/:pluginId/*`. A plugin exports its pages from its admin entry point:
 
-```tsx
-// @emdash-cms/plugin-seo/src/admin.tsx
+```tsx title="@emdash-cms/plugin-seo/src/admin.tsx"
 export const pages = [
 	{
 		path: "settings",
@@ -228,11 +240,11 @@ export const pages = [
 ];
 ```
 
-Renders at: `/_emdash/admin/plugins/seo/settings`
+The example above renders at `/_emdash/admin/plugins/seo/settings`.
 
-### Dashboard Widgets
+### Dashboard widgets
 
-Plugins can add widgets to the dashboard:
+Plugins can add widgets to the dashboard by exporting a `widgets` array:
 
 ```tsx
 export const widgets = [
@@ -252,10 +264,9 @@ export const widgets = [
 
 ## Authentication
 
-The admin shell route enforces authentication via Astro middleware:
+The admin shell route enforces authentication via Astro middleware. The following simplified middleware redirects unauthenticated requests to the login page:
 
 ```ts
-// Simplified middleware logic
 export async function onRequest({ request, locals }, next) {
 	const session = await getSession(request);
 
@@ -270,9 +281,9 @@ export async function onRequest({ request, locals }, next) {
 }
 ```
 
-The admin SPA itself doesn't handle login—that's an Astro page that sets a session cookie.
+The admin SPA itself does not handle login. Login is an Astro page that sets a session cookie.
 
-## Role-Based Access
+## Role-based access
 
 Different roles see different parts of the admin:
 
@@ -284,12 +295,11 @@ Different roles see different parts of the admin:
 
 The manifest endpoint filters collections and features based on the requesting user's role.
 
-## Content Editor
+## Content editor
 
-The content editor generates forms dynamically based on field definitions:
+The content editor generates forms dynamically based on field definitions. The following simplified component renders one widget per field:
 
 ```tsx
-// Simplified editor rendering
 function ContentEditor({ collection, fields }) {
 	return (
 		<form>
@@ -307,7 +317,7 @@ function ContentEditor({ collection, fields }) {
 }
 ```
 
-Each field type has a corresponding widget:
+Each field type has a corresponding widget, as listed below:
 
 | Field Type     | Widget           |
 | -------------- | ---------------- |
@@ -322,18 +332,18 @@ Each field type has a corresponding widget:
 | `image`        | Media picker     |
 | `reference`    | Entry picker     |
 
-## Rich Text Editor
+## Rich text editor
 
-Portable Text fields use TipTap (ProseMirror) for editing:
+Portable Text fields use TipTap (ProseMirror) for editing. Content is converted between formats at the load and save boundaries:
 
 ```
 User types → TipTap (ProseMirror JSON) → Save → Portable Text (DB)
 Load → Portable Text (DB) → TipTap (ProseMirror JSON) → Display
 ```
 
-Conversion happens at load/save boundaries via `portableTextToProsemirror()` and `prosemirrorToPortableText()`.
+Conversion happens via `portableTextToProsemirror()` and `prosemirrorToPortableText()`.
 
-Supported blocks:
+The editor supports these blocks:
 
 - Paragraphs, headings (H1-H6)
 - Bullet and numbered lists
@@ -343,27 +353,28 @@ Supported blocks:
 
 Unknown blocks from plugins or imports are preserved as read-only placeholders.
 
-## Media Library
+## Media library
 
 The media library provides:
 
 - Grid and list views
-- Search and filter by type, date
+- Search and filter by type and date
 - Drag-and-drop upload
 - Image preview with metadata
 - Bulk selection and delete
 
-Uploads use signed URLs for direct client-to-storage upload:
+Uploads use signed URLs for direct client-to-storage upload, following these steps:
 
 <Steps>
-	1. **Request upload URL** — `POST /api/media/upload-url` 2. **Upload directly** — Client PUTs file
-	to signed URL (R2/S3) 3. **Confirm upload** — `POST /api/media/:id/confirm` 4. **Server extracts
-	metadata** — Dimensions, MIME type, etc.
+1. The client requests an upload URL with `POST /api/media/upload-url`.
+2. The client uploads the file directly to the signed URL (R2 or S3).
+3. The client confirms the upload with `POST /api/media/:id/confirm`.
+4. The server extracts metadata such as dimensions and MIME type.
 </Steps>
 
-This approach bypasses Workers body size limits and provides real upload progress.
+This approach bypasses Workers body size limits and provides accurate upload progress.
 
-## Next Steps
+## Next steps
 
 <CardGrid>
 	<Card title="Getting Started" icon="rocket">
diff --git a/docs/src/content/docs/concepts/architecture.mdx b/docs/src/content/docs/concepts/architecture.mdx
index df66c772e..612d1c35c 100644
--- a/docs/src/content/docs/concepts/architecture.mdx
+++ b/docs/src/content/docs/concepts/architecture.mdx
@@ -7,7 +7,9 @@ import { Aside, Card, CardGrid, Steps } from "@astrojs/starlight/components";
 
 EmDash integrates deeply with Astro to provide a complete CMS experience. This page explains the key architectural decisions and how the pieces fit together.
 
-## High-Level Overview
+## High-level overview
+
+The following diagram shows how EmDash sits inside an Astro site:
 
 ```
 ┌──────────────────────────────────────────────────────────────────┐
@@ -36,35 +38,34 @@ EmDash integrates deeply with Astro to provide a complete CMS experience. This p
 
 EmDash runs as an Astro integration. It injects routes for the admin panel and REST APIs, provides a content loader for Live Collections, and manages database migrations and storage connections.
 
-## Database-First Schema
+## Database-first schema
 
-Unlike traditional CMSs that define schema in code, EmDash stores schema definitions in the database itself. Two system tables track your content structure:
+EmDash stores schema definitions in the database itself rather than in code. Two system tables track the content structure:
 
 - `_emdash_collections` — Collection metadata (slug, label, features)
 - `_emdash_fields` — Field definitions for each collection
 
-When you create a "products" collection with title and price fields via the admin UI, EmDash:
+When you create a products collection with title and price fields through the admin UI, EmDash performs two steps:
 
-1. Inserts records into `_emdash_collections` and `_emdash_fields`
-2. Runs `ALTER TABLE` to create `ec_products` with the appropriate columns
+1. Inserts records into `_emdash_collections` and `_emdash_fields`.
+2. Runs `ALTER TABLE` to create `ec_products` with the appropriate columns.
 
 This design enables:
 
-- **Runtime schema modification** — Create and edit content types without code changes or rebuilds
-- **Non-developer-friendly setup** — Content editors can design their data model through the UI
-- **Real SQL columns** — Proper indexing, foreign keys, and query optimization
+- Runtime schema modification: create and edit content types without code changes or rebuilds.
+- Setup without a developer: content editors can design their data model through the UI.
+- Real SQL columns, with proper indexing, foreign keys, and query optimization.
 
 <Aside type="tip">
 	Run `npx emdash types` to generate TypeScript types from the live schema. This gives you type
 	safety for dynamically-defined collections.
 </Aside>
 
-## Per-Collection Tables
+## Per-collection tables
 
-Each collection gets its own SQLite table with an `ec_` prefix:
+Each collection gets its own SQLite table with an `ec_` prefix. The following table is created when a posts collection is added:
 
 ```sql
--- Created when "posts" collection is added
 CREATE TABLE ec_posts (
   -- System columns (always present)
   id TEXT PRIMARY KEY,
@@ -84,22 +85,21 @@ CREATE TABLE ec_posts (
 );
 ```
 
-**Why per-collection tables instead of a single content table with JSON?**
+Per-collection tables, rather than a single content table with a JSON column, give EmDash:
 
-- Real SQL columns enable proper indexing and queries
-- Foreign keys work correctly
-- Schema is self-documenting in the database
+- Real SQL columns for proper indexing and queries
+- Working foreign keys
+- A self-documenting schema in the database
 - No JSON parsing overhead for field access
-- Database tools can inspect schema directly
+- Schema that database tools can inspect directly
 
-## Live Collections Integration
+## Live Collections integration
 
-EmDash uses Astro 6's Live Collections to serve content at runtime. Content changes are immediately available without static rebuilds.
+EmDash uses Astro's [Live Collections](https://docs.astro.build/en/reference/experimental-flags/live-content-collections/) to serve content at runtime. Content changes are available immediately, without static rebuilds.
 
-The `emdashLoader()` implements Astro's `LiveLoader` interface:
+The `emdashLoader()` function implements Astro's `LiveLoader` interface:
 
-```ts
-// src/live.config.ts
+```ts title="src/live.config.ts"
 import { defineLiveCollection } from "astro:content";
 import { emdashLoader } from "emdash/runtime";
 
@@ -109,11 +109,11 @@ export const collections = {
 ```
 
 <Aside type="note">
-	A single `_emdash` Astro collection wraps all your content types. The loader filters by type
+	A single `_emdash` Astro collection wraps all content types. The loader filters by type
 	internally when you call `getEmDashCollection("posts")`.
 </Aside>
 
-Query content using the provided wrapper functions:
+Query content using the provided wrapper functions. The following example fetches published posts, drafts, and a single entry:
 
 ```ts
 import { getEmDashCollection, getEmDashEntry } from "emdash";
@@ -130,7 +130,7 @@ const { entries: drafts } = await getEmDashCollection("posts", {
 const { entry: post } = await getEmDashEntry("posts", "my-post-slug");
 ```
 
-## Route Injection
+## Route injection
 
 The EmDash integration uses Astro's `injectRoute` API to add admin and API routes:
 
@@ -145,9 +145,9 @@ The EmDash integration uses Astro's `injectRoute` API to add admin and API route
 | `/_emdash/api/menus/*`              | Navigation menus                      |
 | `/_emdash/api/taxonomies/*`         | Categories, tags, custom taxonomies   |
 
-Routes are injected from the `emdash` package—nothing is copied into your project.
+Routes are injected from the `emdash` package. Nothing is copied into your project.
 
-## Data Layer
+## Data layer
 
 EmDash uses [Kysely](https://kysely.dev) for type-safe SQL queries across all supported databases:
 
@@ -165,7 +165,7 @@ EmDash uses [Kysely](https://kysely.dev) for type-safe SQL queries across all su
 
 Database configuration is passed to the integration in `astro.config.mjs`:
 
-```ts
+```ts title="astro.config.mjs"
 import { defineConfig } from "astro/config";
 import emdash from "emdash/astro";
 import { sqlite } from "emdash/db";
@@ -184,32 +184,33 @@ export default defineConfig({
 });
 ```
 
-## Storage Abstraction
+## Storage abstraction
 
 Media files are stored separately from the database. EmDash supports:
 
-- **Local filesystem** — Development and simple deployments
-- **Cloudflare R2** — S3-compatible object storage on the edge
-- **S3-compatible** — Any S3-compatible object storage
+- Local filesystem, for development and simple deployments
+- Cloudflare R2, S3-compatible object storage on the edge
+- Any other S3-compatible object storage
 
 Uploads use signed URLs for direct client-to-storage uploads, bypassing Workers body size limits.
 
-## Plugin Architecture
+## Plugin architecture
 
-Plugins extend EmDash through a WordPress-inspired hook system:
+Plugins extend EmDash through a hook system:
 
-- **Content hooks** — `content:beforeSave`, `content:afterSave`, `content:beforeDelete`, `content:afterDelete`
-- **Media hooks** — `media:beforeUpload`, `media:afterUpload`
-- **Isolated storage** — Each plugin gets namespaced KV access
-- **Admin UI extensions** — Dashboard widgets, settings pages, custom field editors
+- Content hooks: `content:beforeSave`, `content:afterSave`, `content:beforeDelete`, `content:afterDelete`
+- Media hooks: `media:beforeUpload`, `media:afterUpload`
+- Isolated storage: each plugin gets namespaced KV access
+- Admin UI extensions: dashboard widgets, settings pages, custom field editors
 
 Plugins can run in two modes:
 
-1. **Native** — Full access to the host environment (for first-party plugins)
-2. **Sandboxed** — Run in V8 isolates with capability-based permissions (for third-party plugins on Cloudflare)
+1. Native plugins have full access to the host environment, and are intended for first-party plugins.
+2. Sandboxed plugins run in V8 isolates with capability-based permissions, for third-party plugins on Cloudflare.
 
-```ts
-// astro.config.mjs
+The following example registers a plugin in `astro.config.mjs`:
+
+```ts title="astro.config.mjs"
 import { seoPlugin } from "@emdash-cms/plugin-seo";
 
 emdash({
@@ -217,27 +218,29 @@ emdash({
 });
 ```
 
-## Request Flow
+## Request flow
 
-A typical content request follows this path:
+A content request from a page follows these steps:
 
 <Steps>
-	1. **Astro receives request** — Your page component runs 2. **Query content** —
-	`getEmDashCollection()` calls Astro's `getLiveCollection()` 3. **Loader executes** —
-	`emdashLoader` queries the appropriate `ec_*` table via Kysely 4. **Data returned** — Entries
-	are mapped to Astro's entry format with `id`, `slug`, and `data` 5. **Page renders** — Your
-	component receives the content and renders HTML
+1. Astro receives the request and your page component runs.
+2. `getEmDashCollection()` calls Astro's `getLiveCollection()`.
+3. `emdashLoader` queries the appropriate `ec_*` table via Kysely.
+4. Entries are mapped to Astro's entry format with `id`, `slug`, and `data`.
+5. Your component receives the content and renders HTML.
 </Steps>
 
-For admin requests:
+An admin request follows these steps:
 
 <Steps>
-	1. **Middleware authenticates** — Validates session token 2. **API route handles request** — CRUD
-	operations via repositories 3. **Hooks fire** — `beforeCreate`, `afterUpdate`, etc. 4. **Database
-	updates** — Kysely executes SQL 5. **Response returned** — JSON response to admin SPA
+1. Middleware validates the session token.
+2. The API route handles the request, performing CRUD operations via repositories.
+3. Hooks fire, such as `beforeCreate` and `afterUpdate`.
+4. Kysely executes the SQL to update the database.
+5. The route returns a JSON response to the admin SPA.
 </Steps>
 
-## Virtual Modules
+## Virtual modules
 
 EmDash generates virtual modules at build time to configure the runtime:
 
@@ -249,7 +252,7 @@ EmDash generates virtual modules at build time to configure the runtime:
 
 This approach ensures bundlers can properly resolve and tree-shake plugin code.
 
-## Next Steps
+## Next steps
 
 <CardGrid>
 	<Card title="Collections" icon="document">
diff --git a/docs/src/content/docs/concepts/collections.mdx b/docs/src/content/docs/concepts/collections.mdx
index f25d3381b..dfa248c7e 100644
--- a/docs/src/content/docs/concepts/collections.mdx
+++ b/docs/src/content/docs/concepts/collections.mdx
@@ -8,9 +8,9 @@ import contentTypesImg from "../../../assets/screenshots/admin-content-types.png
 
 Collections are the foundation of EmDash's content model. Each collection represents a content type (posts, pages, products) and contains field definitions that determine the shape of your data.
 
-## Creating Collections
+## Creating collections
 
-Create collections through the admin panel under **Content Types**. Each collection has:
+Create collections through the admin panel under **Content Types**. Each collection has the following properties:
 
 <img src={contentTypesImg.src} alt="EmDash content types showing Pages, Posts, and custom collections with their features" />
 
@@ -28,7 +28,7 @@ Create collections through the admin panel under **Content Types**. Each collect
 	`options`, `audit_logs`.
 </Aside>
 
-## Collection Features
+## Collection features
 
 When creating a collection, enable the features you need:
 
@@ -39,8 +39,9 @@ When creating a collection, enable the features you need:
 | `preview`    | Generate signed preview URLs for draft content |
 | `scheduling` | Schedule content to publish at a future date   |
 
+The following collection enables all four features:
+
 ```ts
-// Example collection with all features enabled
 {
   slug: "posts",
   label: "Blog Posts",
@@ -49,11 +50,11 @@ When creating a collection, enable the features you need:
 }
 ```
 
-## Field Types
+## Field types
 
-EmDash supports 15 field types that map to SQLite column types:
+EmDash supports 14 field types that map to SQLite column types.
 
-### Text Fields
+### Text fields
 
 <Tabs>
   <TabItem label="string">
@@ -79,7 +80,7 @@ EmDash supports 15 field types that map to SQLite column types:
   </TabItem>
 </Tabs>
 
-### Rich Content
+### Rich content
 
 <Tabs>
   <TabItem label="portableText">
@@ -119,7 +120,7 @@ EmDash supports 15 field types that map to SQLite column types:
   </TabItem>
 </Tabs>
 
-### Booleans & Dates
+### Booleans and dates
 
 <Tabs>
   <TabItem label="boolean">
@@ -171,7 +172,7 @@ EmDash supports 15 field types that map to SQLite column types:
   </TabItem>
 </Tabs>
 
-### Media & References
+### Media and references
 
 <Tabs>
   <TabItem label="image">
@@ -204,7 +205,7 @@ EmDash supports 15 field types that map to SQLite column types:
   </TabItem>
 </Tabs>
 
-## Field Properties
+## Field properties
 
 Every field supports these properties:
 
@@ -212,7 +213,7 @@ Every field supports these properties:
 | -------------- | ----------- | -------------------------------------------- |
 | `slug`         | `string`    | Column name in the database                  |
 | `label`        | `string`    | Display label in admin UI                    |
-| `type`         | `FieldType` | One of the 15 field types                    |
+| `type`         | `FieldType` | One of the 14 field types                    |
 | `required`     | `boolean`   | Whether the field must have a value          |
 | `unique`       | `boolean`   | Whether values must be unique across entries |
 | `defaultValue` | `unknown`   | Default value for new entries                |
@@ -227,9 +228,9 @@ Every field supports these properties:
 	`version`, `live_revision_id`, `draft_revision_id`.
 </Aside>
 
-## Validation Rules
+## Validation rules
 
-The `validation` object varies by field type:
+The `validation` object varies by field type. Its full shape is:
 
 ```ts
 interface FieldValidation {
@@ -243,7 +244,7 @@ interface FieldValidation {
 }
 ```
 
-Example with validation:
+The following field requires a unique, pattern-matched email address:
 
 ```ts
 {
@@ -258,9 +259,9 @@ Example with validation:
 }
 ```
 
-## Widget Options
+## Widget options
 
-The `options` object configures field-specific UI behavior:
+The `options` object configures field-specific UI behavior. Its full shape is:
 
 ```ts
 interface FieldWidgetOptions {
@@ -272,7 +273,7 @@ interface FieldWidgetOptions {
 }
 ```
 
-Example reference field:
+The following reference field links to multiple products:
 
 ```ts
 {
@@ -286,9 +287,9 @@ Example reference field:
 }
 ```
 
-## Querying Collections
+## Querying collections
 
-Use the provided query functions to fetch content. These follow Astro's live collections pattern, returning structured results:
+Use the provided query functions to fetch content. These follow Astro's live collections pattern, returning structured results. The following example shows the common query options:
 
 ```ts
 import { getEmDashCollection, getEmDashEntry } from "emdash";
@@ -321,12 +322,11 @@ if (error) {
 }
 ```
 
-## Type Generation
+## Type generation
 
-Run `npx emdash types` to generate TypeScript types from your schema:
+Run `npx emdash types` to generate TypeScript types from your schema. The generated file contains one interface per collection:
 
-```ts
-// .emdash/types.ts (generated)
+```ts title=".emdash/types.ts (generated)"
 export interface Post {
 	title: string;
 	content: PortableTextBlock[];
@@ -346,9 +346,9 @@ export interface Product {
 	Re-run `emdash types` after modifying collections in the admin panel to keep types in sync.
 </Aside>
 
-## Database Mapping
+## Database mapping
 
-Field types map to SQLite column types:
+Field types map to SQLite column types as follows:
 
 | Field Type     | SQLite Type | Notes                 |
 | -------------- | ----------- | --------------------- |
@@ -367,7 +367,7 @@ Field types map to SQLite column types:
 | `reference`    | `TEXT`      | Entry ID              |
 | `json`         | `JSON`      | Arbitrary JSON        |
 
-## Next Steps
+## Next steps
 
 <CardGrid>
 	<Card title="Content Model" icon="open-book">
diff --git a/docs/src/content/docs/concepts/content-model.mdx b/docs/src/content/docs/concepts/content-model.mdx
index b5f1a5044..156faf4fe 100644
--- a/docs/src/content/docs/concepts/content-model.mdx
+++ b/docs/src/content/docs/concepts/content-model.mdx
@@ -7,12 +7,11 @@ import { Aside, Card, CardGrid, Steps } from "@astrojs/starlight/components";
 
 EmDash uses a **database-first content model** where schema definitions live in the database, not in code. This is a fundamental design choice that enables runtime schema modification and non-developer-friendly setup.
 
-## Schema as Data
+## Schema as data
 
-Traditional CMSs like Strapi or Keystatic require you to define schema in code:
+Many CMSs define schema in code, where a collection's fields are declared as a code object:
 
 ```ts
-// Traditional approach - schema in code
 const posts = collection({
 	fields: {
 		title: text({ required: true }),
@@ -21,14 +20,12 @@ const posts = collection({
 });
 ```
 
-EmDash stores this same information in database tables:
+EmDash stores this same information in database tables. The following statements define an equivalent posts collection:
 
 ```sql
--- _emdash_collections table
 INSERT INTO _emdash_collections (slug, label)
 VALUES ('posts', 'Blog Posts');
 
--- _emdash_fields table
 INSERT INTO _emdash_fields (collection_id, slug, type, required)
 VALUES
   ('coll_abc', 'title', 'string', true),
@@ -37,7 +34,7 @@ VALUES
 
 Both approaches define the same content structure. The difference is where that structure lives and how it can be modified.
 
-## Why Database-First?
+## Why database-first
 
 <CardGrid>
 	<Card title="Runtime Modification" icon="pencil">
@@ -45,8 +42,7 @@ Both approaches define the same content structure. The difference is where that
 		data model through the admin UI.
 	</Card>
 	<Card title="Real SQL Columns" icon="seti:db">
-		Unlike WordPress's EAV (Entity-Attribute-Value) model, each field gets a real column. Proper
-		indexing, foreign keys, and query optimization.
+		Each field gets a real column, with proper indexing, foreign keys, and query optimization.
 	</Card>
 	<Card title="Self-Documenting" icon="document">
 		Database tools can inspect schema directly. No need to parse code to understand the data model.
@@ -56,11 +52,13 @@ Both approaches define the same content structure. The difference is where that
 	</Card>
 </CardGrid>
 
-## Schema Tables
+## Schema tables
 
-Two system tables define your content structure:
+Two system tables define your content structure.
 
-### Collections Table
+### Collections table
+
+The `_emdash_collections` table holds one row per collection:
 
 ```sql
 CREATE TABLE _emdash_collections (
@@ -77,7 +75,7 @@ CREATE TABLE _emdash_collections (
 );
 ```
 
-The `source` field tracks how the collection was created:
+The `source` field tracks how the collection was created, with one of these values:
 
 | Source             | Description                        |
 | ------------------ | ---------------------------------- |
@@ -86,7 +84,9 @@ The `source` field tracks how the collection was created:
 | `import:wordpress` | Imported from WordPress            |
 | `discovered`       | Auto-discovered from existing data |
 
-### Fields Table
+### Fields table
+
+The `_emdash_fields` table holds one row per field, linked to its collection:
 
 ```sql
 CREATE TABLE _emdash_fields (
@@ -108,9 +108,9 @@ CREATE TABLE _emdash_fields (
 );
 ```
 
-## Content Tables
+## Content tables
 
-Each collection gets its own table with the `ec_` prefix. When you create a "products" collection with title and price fields:
+Each collection gets its own table with the `ec_` prefix. The following table is created for a products collection with title and price fields:
 
 ```sql
 CREATE TABLE ec_products (
@@ -132,17 +132,18 @@ CREATE TABLE ec_products (
 ```
 
 <Aside type="tip">
-	System columns are automatically added to every content table. You don't define them as
-	fields—they're always present.
+	System columns are automatically added to every content table. You do not define them as
+	fields; they are always present.
 </Aside>
 
-## Runtime Schema Changes
+## Runtime schema changes
 
-When you add a field via the admin UI, EmDash:
+When you add a field through the admin UI, EmDash performs these steps:
 
 <Steps>
-	1. Inserts a record into `_emdash_fields` 2. Runs `ALTER TABLE ec_collection ADD COLUMN
-	column_name TYPE` 3. Regenerates the Zod schema for validation
+1. Inserts a record into `_emdash_fields`.
+2. Runs `ALTER TABLE ec_collection ADD COLUMN column_name TYPE`.
+3. Regenerates the Zod schema for validation.
 </Steps>
 
 SQLite supports these `ALTER TABLE` operations at runtime:
@@ -154,11 +155,11 @@ SQLite supports these `ALTER TABLE` operations at runtime:
 | Drop column        | Yes (SQLite 3.35+)          |
 | Change column type | No (requires table rebuild) |
 
-For type changes, EmDash handles the table rebuild transparently: create new table → copy data → drop old table → rename new table.
+For type changes, EmDash handles the table rebuild transparently: create a new table, copy data, drop the old table, then rename the new table.
 
-## Schema vs. Content Separation
+## Schema and content separation
 
-EmDash maintains a clear separation:
+EmDash maintains a clear separation between schema, content, media, and settings:
 
 | Concern      | Location                 | Tables                                      |
 | ------------ | ------------------------ | ------------------------------------------- |
@@ -173,12 +174,11 @@ This separation means:
 - Content can be migrated between schemas
 - System tables are never cluttered with user data
 
-## Validation at Runtime
+## Validation at runtime
 
-EmDash builds Zod schemas from database field definitions at startup:
+EmDash builds Zod schemas from database field definitions at startup. The following simplified function shows the approach:
 
 ```ts
-// Simplified example
 function buildSchema(fields: Field[]): ZodSchema {
 	const shape: Record<string, ZodType> = {};
 
@@ -202,19 +202,17 @@ function buildSchema(fields: Field[]): ZodSchema {
 
 Content is validated against these runtime schemas on every create and update operation.
 
-## TypeScript Integration
+## TypeScript integration
 
-Generate TypeScript types from your database schema:
+Generate TypeScript types from your database schema with the following command:
 
 ```bash
-# Fetch schema from database, generate types
 npx emdash types
 ```
 
-This generates `.emdash/types.ts`:
+This generates a `.emdash/types.ts` file with an interface per collection and typed query overloads:
 
-```ts
-// .emdash/types.ts (generated)
+```ts title=".emdash/types.ts (generated)"
 export interface Post {
 	title: string;
 	content: PortableTextBlock[];
@@ -246,9 +244,9 @@ declare module "emdash" {
 	dynamically-defined collections.
 </Aside>
 
-## Developer vs. Non-Developer Workflow
+## Developer and non-developer workflows
 
-**Developers** can use the CLI:
+Developers can use the CLI to generate types and export the schema:
 
 ```bash
 # Fetch schema, generate types
@@ -258,18 +256,20 @@ npx emdash types
 npx emdash export-seed > seed.json
 ```
 
-**Non-developers** use the admin UI exclusively:
+Non-developers use the admin UI instead, following these steps:
 
-1. Open **Content Types** in the admin panel
-2. Click **Add Collection**
-3. Define fields through the visual builder
-4. Start creating content immediately
+<Steps>
+1. Open **Content Types** in the admin panel.
+2. Click **Add Collection**.
+3. Define fields through the visual builder.
+4. Start creating content.
+</Steps>
 
 Both approaches modify the same underlying database tables.
 
-## Seed Files
+## Seed files
 
-Templates and exports use JSON seed files for portable schema definitions:
+Templates and exports use JSON seed files for portable schema definitions. A seed file describes collections, taxonomies, and menus:
 
 ```json
 {
@@ -292,7 +292,7 @@ Templates and exports use JSON seed files for portable schema definitions:
 }
 ```
 
-Apply seed files programmatically:
+Apply seed files programmatically with `validateSeed` and `applySeed`:
 
 ```ts
 import { applySeed, validateSeed } from "emdash/seed";
@@ -308,19 +308,11 @@ await applySeed(db, seedData, {
 });
 ```
 
-## Comparison with Other Approaches
-
-| Approach      | Schema Location | Runtime Modification    | Type Safety        |
-| ------------- | --------------- | ----------------------- | ------------------ |
-| **EmDash**  | Database        | Yes (full)              | Generated from DB  |
-| **WordPress** | PHP code + EAV  | Limited (meta fields)   | None               |
-| **Strapi**    | Code files      | No (rebuild required)   | Generated at build |
-| **Sanity**    | Code files      | No (schema must deploy) | Built-in           |
-| **Directus**  | Database        | Yes (full)              | Generated from DB  |
+## Summary
 
-EmDash follows the Directus model: database-first with optional type generation. This provides maximum flexibility while still supporting type-safe development when desired.
+EmDash is database-first with optional type generation. Schema lives in the database, can be modified at runtime through the admin UI or CLI, and types are generated from the live schema when you want type-safe development.
 
-## Next Steps
+## Next steps
 
 <CardGrid>
 	<Card title="Collections" icon="document">
diff --git a/docs/src/content/docs/contributing/docs-style-guide.mdx b/docs/src/content/docs/contributing/docs-style-guide.mdx
new file mode 100644
index 000000000..2f5b3b663
--- /dev/null
+++ b/docs/src/content/docs/contributing/docs-style-guide.mdx
@@ -0,0 +1,140 @@
+---
+title: Documentation Style Guide
+description: The writing, structure, and code-sample conventions for EmDash documentation.
+---
+
+This guide defines how EmDash documentation is written. Contributions are edited to match it. You do not need to memorise it — reviewers and editors will help — but following it makes a contribution merge faster.
+
+Documentation exists to help someone do something, then get back to their project. Write for a reader who is tired, in a hurry, reading in a second language, or new to the stack. Serve that reader above all else.
+
+## Readability
+
+Prefer:
+
+- Short sentences and short paragraphs.
+- Plain vocabulary over jargon.
+- Abbreviations and acronyms written out the first time.
+- Headings and lists to break up long passages.
+- Active voice.
+
+Document **how to build with EmDash**, not **how EmDash is built**. Implementation detail belongs in docs only when it changes a decision the reader has to make (when to pick a non-default value, a caveat that affects their project). It never replaces a usage example.
+
+For non-EmDash topics — TypeScript, the AT Protocol, web fonts, SQL — link to a reputable source instead of explaining them. Document what someone needs to know to use the feature **in EmDash**.
+
+## Voice and tone
+
+Write neutral, factual sentences. State facts directly.
+
+✅ Plugins run in an isolated runtime and can only reach the APIs they declare.
+
+❌ Plugins live in a cosy little sandbox where nothing bad can ever happen!
+
+- **Do not use _we_, _us_, _our_, or _let's_.** You are not sitting with the reader. Rephrase to address the reader directly or describe the system.
+- **Never use _I_.** Documentation is not about the author.
+- **Address the reader as _you_** when needed, especially to flag a step where something can go wrong.
+- **Do not narrate or tell a story.** No "now that we've set up X, let's move on to Y". Start a section with the goal, then the steps.
+- **Avoid whimsy, mascots, and cultural references.** They add reading effort and do not translate.
+- **Exclamation points are rare.** Use one only for something genuinely encouraging or surprising. When unsure, use a period.
+
+Do not describe the previous behaviour of EmDash in a regular guide ("this used to be called…", "no longer", "instead of the old…"). A guide documents how the software works now. Changes between versions belong in an [upgrade guide](#upgrade-and-migration-guides).
+
+## Headings
+
+- Page title is the `<h1>` (from frontmatter `title`). Sections start at `<h2>`.
+- Keep headings short. `<h2>` and `<h3>` appear in the "On this page" sidebar; preview it and shorten anything that wraps.
+- No trailing punctuation, including a colon.
+- Format code as `<code>` in headings the same as in body text.
+
+## Lists
+
+- Use a bulleted list when order does not matter, such as a set of options or properties.
+- Use a numbered list for steps that must be followed in sequence. Use the Starlight `<Steps>` component for procedures.
+- When list items grow into multiple paragraphs or carry several code terms, switch to `<h3>` sections instead.
+
+## Examples
+
+- "for example" in full introduces a single example or hypothetical.
+- "e.g." inside parentheses introduces a non-exhaustive list (`e.g. GitHub, GitLab`).
+- A list that covers **every** option is not a list of examples — use parentheses without "e.g." (`the required properties (src, alt)`).
+
+## Code samples
+
+Code samples are as important as the prose around them.
+
+**Introduce every code block with a full, standalone sentence** on its own line, telling the reader what the block does. Do not lead in with a sentence fragment ending in a colon, a bare heading, or "like so:".
+
+✅ The following example registers a plugin in the `sandboxed` array:
+
+❌ Add the plugin like so:
+
+The introduction primes the reader for what the code does, so they only need to work out _how_. It also creates a fill-in-the-blank pattern for a reader doing something slightly different.
+
+Within a `<Steps>` procedure, a direct imperative instruction is the introduction ("Add a `tsconfig.json`:" followed by the file is fine in a numbered step).
+
+Other rules:
+
+- **Use real, working code.** No `foo`/`bar`. Show one realistic configuration, not every possible value — the reader will only have one.
+- **Add a `title=` filename** to any block that represents a file, so the reader knows where the code goes.
+
+  ````md
+  ```ts title="src/plugin.ts"
+  ````
+
+- **Use Expressive Code annotations**, not raw ` ```diff ` fences, for before/after changes. Mark changed lines with `del={n}` / `ins={n}` or changed text with `del="…"` / `ins="…"`. Keep diffs minimal and local to the lines that change.
+
+  The following example shows a single line changing:
+
+  ````md
+  ```ts del={1} ins={2}
+  import { definePlugin } from "emdash";
+  import type { SandboxedPlugin } from "emdash/plugin";
+  ```
+  ````
+
+- Preview rendered code locally before submitting. A typo can break the display.
+
+## Upgrade and migration guides
+
+A guide that helps a reader move an existing project to a new version follows a fixed structure. The "What should I do?" sections are the part readers value most — do not skimp on them.
+
+Open with: how to upgrade, a note that things may "just work" but to read on if not, and a link to the changelog.
+
+Then list each breaking change as its own entry:
+
+```md
+### [Renamed/Changed/Removed/Deprecated]: <feature>
+
+In earlier versions, <one sentence, past tense, what it did>.
+
+<One sentence, present tense, how it works now>.
+
+#### What should I do?
+
+<Imperative actions: Update… / Replace… / Remove…, with a minimal diff.>
+```
+
+Choose the verb by how the reader feels the impact. If a new default replaces their value, that is a "Changed: default value", not an "Added: option".
+
+A breaking change is one that requires a change to the reader's project or it stops working. Give the action, not just the fact. Not "the minimum Node.js version is now X" but "check your Node.js version with the following command, and upgrade if it is below X".
+
+## EmDash specifics
+
+### Plugins: sandboxed vs native
+
+Sandboxed and native plugins are different formats with different authoring shapes. A change to one rarely affects the other. State which format a page or example is about. When editing a sandboxed-plugin page, do not change native-plugin examples, and the reverse.
+
+### Atmosphere accounts
+
+The portable, user-owned identity behind Bluesky and the wider AT Protocol network is an **Atmosphere account**. Use that term. Link the first mention to [the Atmosphere login guide](/guides/atmosphere-auth/) or [atmosphereaccount.com](https://atmosphereaccount.com). `did:plc:…` and handles are the concrete identifiers of an Atmosphere account; use them where a literal value is needed.
+
+### Experimental features
+
+A feature behind an experimental flag, or an unstable wire format under an RFC, can change without notice. Keep its documentation lean, flag it with a caution `<Aside>`, and point to the RFC or discussion as the source of truth. Do not document an unstable surface in exhaustive detail.
+
+### Localization
+
+Do not include `messages.po` changes in a docs PR. A workflow extracts catalogs on merge to `main`. Including them creates churn and merge conflicts.
+
+## Docs are code
+
+The documentation site is an EmDash-adjacent Astro project. Documentation changes go through the same pull request and review flow as code. Every text change waits for a review; a wording change can shift the meaning of a sentence or need matching edits elsewhere on the site. Small, reviewed, consistent changes keep the whole site coherent.
diff --git a/docs/src/content/docs/contributing/index.mdx b/docs/src/content/docs/contributing/index.mdx
index 953914e75..e473eab66 100644
--- a/docs/src/content/docs/contributing/index.mdx
+++ b/docs/src/content/docs/contributing/index.mdx
@@ -100,7 +100,7 @@ pnpm test:e2e    # starts its own server
 
 Tests use real in-memory SQLite — no mocking. Each test gets a fresh database.
 
-## What We Accept
+## What Gets Accepted
 
 | Type             | Process                                                                                       |
 | ---------------- | --------------------------------------------------------------------------------------------- |
diff --git a/docs/src/content/docs/contributing/translating.mdx b/docs/src/content/docs/contributing/translating.mdx
index d4353bc7a..b78971e4a 100644
--- a/docs/src/content/docs/contributing/translating.mdx
+++ b/docs/src/content/docs/contributing/translating.mdx
@@ -13,9 +13,9 @@ See the [translation dashboard](https://i18n.emdashcms.com) for current progress
 
 ## Who can translate
 
-Translations must come from **native or fluent speakers**. We don't accept machine-generated translations. If you use AI tools to assist, you must review every string by hand and test the result in context (see [Testing your translations](#testing-your-translations) below).
+Translations must come from **native or fluent speakers**. Machine-generated translations are not accepted. If you use AI tools to assist, you must review every string by hand and test the result in context (see [Testing your translations](#testing-your-translations) below).
 
-We'd rather have no translation for a string than a bad one. A wrong translation is worse than showing the English fallback — it actively misleads users.
+No translation is better than a bad one. A wrong translation is worse than showing the English fallback — it actively misleads users.
 
 ## File structure
 
@@ -149,7 +149,7 @@ If your language doesn't have a PO file yet:
    ];
    ```
 
-   This is the single source of truth — `lingui.config.ts`, `lunaria.config.ts` and the admin runtime all derive their locale lists from this file. Set `enabled: false` unless your translations have 100% coverage — we'll enable it once the translation reaches sufficient coverage.
+   This is the single source of truth — `lingui.config.ts`, `lunaria.config.ts` and the admin runtime all derive their locale lists from this file. Set `enabled: false` unless your translations have 100% coverage — a maintainer enables it once the translation reaches sufficient coverage.
 
 2. **Run extraction** to generate the empty PO file:
 
diff --git a/docs/src/content/docs/deployment/cloudflare.mdx b/docs/src/content/docs/deployment/cloudflare.mdx
index a5f6da7b6..4a62cfaea 100644
--- a/docs/src/content/docs/deployment/cloudflare.mdx
+++ b/docs/src/content/docs/deployment/cloudflare.mdx
@@ -126,7 +126,7 @@ storage: r2({
 
 ## Cloudflare Access Authentication
 
-If your organization uses Cloudflare Access, you can use it as your authentication provider instead of passkeys. This provides SSO with your existing identity provider.
+If your organization uses Cloudflare Access, you can use it as the authentication provider instead of passkeys, giving single sign-on through your existing identity provider. The following configuration enables it:
 
 ```js title="astro.config.mjs"
 emdash({
@@ -159,6 +159,8 @@ The key is provided by you and never stored in the database; only
 encrypted ciphertext is. Losing it means losing every secret encrypted
 with it.
 
+Generate a key and store it as a Worker secret with the following commands:
+
 ```bash
 npx emdash secrets generate
 wrangler secret put EMDASH_ENCRYPTION_KEY
diff --git a/docs/src/content/docs/deployment/database.mdx b/docs/src/content/docs/deployment/database.mdx
index d15ae02e9..8f3cadef2 100644
--- a/docs/src/content/docs/deployment/database.mdx
+++ b/docs/src/content/docs/deployment/database.mdx
@@ -282,7 +282,7 @@ export default defineConfig({
 });
 ```
 
-Or switch based on environment variables:
+The choice can also key off an environment variable instead of the build mode:
 
 ```js
 const database = process.env.DATABASE_URL
diff --git a/docs/src/content/docs/deployment/nodejs.mdx b/docs/src/content/docs/deployment/nodejs.mdx
index 5299222a2..b79103902 100644
--- a/docs/src/content/docs/deployment/nodejs.mdx
+++ b/docs/src/content/docs/deployment/nodejs.mdx
@@ -117,14 +117,14 @@ CMD ["node", "./dist/server/entry.mjs"]
 
 The seed file is read at build time and inlined into the bundle, so it does not need to be copied into the runtime image. Migrations run on the first request after a deploy; the seed applies only when the database has no collections and setup hasn't been completed — existing data is never overwritten.
 
-Build and run:
+Build the image and run the container:
 
 ```bash
 docker build -t my-emdash-site .
 docker run -p 4321:4321 -v emdash-data:/app/data my-emdash-site
 ```
 
-Or use Docker Compose:
+A Docker Compose file manages the same container with a named volume:
 
 ```yaml title="compose.yaml"
 services:
@@ -140,6 +140,8 @@ volumes:
   emdash-data:
 ```
 
+Start the stack in the background:
+
 ```bash
 docker compose up -d
 ```
@@ -153,6 +155,8 @@ current release validates the key but does not yet use it — plugin
 secret encryption is rolling out and will start using this value
 automatically when available. Set it now so your deployment is ready.
 
+Generate a key and add the result to your environment:
+
 ```bash
 npx emdash secrets generate  # add the result to your environment
 ```
diff --git a/docs/src/content/docs/deployment/storage.mdx b/docs/src/content/docs/deployment/storage.mdx
index 9e6fe8854..b2f095a71 100644
--- a/docs/src/content/docs/deployment/storage.mdx
+++ b/docs/src/content/docs/deployment/storage.mdx
@@ -108,6 +108,8 @@ The S3 adapter works with Cloudflare R2 (via S3 API), MinIO, and other S3-compat
 
 </Aside>
 
+The following configuration points EmDash at an S3-compatible bucket:
+
 ```js title="astro.config.mjs"
 import emdash, { s3 } from "emdash/astro";
 
@@ -159,6 +161,8 @@ environment variables.
 Environment variables are read from `process.env` when the process starts. This is a
 Node-only feature.
 
+Calling `s3()` with no arguments reads every field from the `S3_*` environment variables:
+
 ```js title="astro.config.mjs — runtime environment variable example"
 import emdash, { s3 } from "emdash/astro";
 
@@ -208,6 +212,8 @@ Generate R2 API credentials in the Cloudflare dashboard under R2 > Manage R2 API
 
 ### MinIO
 
+Point the S3 adapter at a MinIO endpoint with its access credentials:
+
 ```js
 storage: s3({
 	endpoint: "https://minio.example.com",
diff --git a/docs/src/content/docs/docs-mcp.mdx b/docs/src/content/docs/docs-mcp.mdx
index 0e5accb54..d9f07558b 100644
--- a/docs/src/content/docs/docs-mcp.mdx
+++ b/docs/src/content/docs/docs-mcp.mdx
@@ -21,14 +21,12 @@ Behind the scenes it uses [Cloudflare AI Search](https://developers.cloudflare.c
 
 ## Connect it
 
-The endpoint is:
+The server is reachable at the following endpoint, with no authentication or API key. It is public and read-only.
 
 ```
 https://docs.emdashcms.com/mcp
 ```
 
-No authentication, no API key. It's public and read-only.
-
 ### Auto-discovery in EmDash templates
 
 If you started your project from an EmDash template (`npm create emdash`), three config files are already in place and will be picked up automatically:
@@ -39,7 +37,7 @@ If you started your project from an EmDash template (`npm create emdash`), three
 | `.cursor/mcp.json`  | Cursor       |
 | `.vscode/mcp.json`  | VS Code      |
 
-Just open the project and accept the workspace-trust prompt your tool shows on first run. Nothing else to do.
+Open the project and accept the workspace-trust prompt the tool shows on first run. No further setup is required.
 
 ### Manual setup
 
@@ -48,15 +46,15 @@ If you're not using a template, or you use a different tool, add it once with th
 <Tabs>
 <TabItem label="Claude Code">
 
-Add the server with the Claude Code CLI:
+The following command adds the server with the Claude Code CLI:
 
 ```bash
 claude mcp add --transport http emdash-docs https://docs.emdashcms.com/mcp
 ```
 
-Or commit a `.mcp.json` at your project root:
+Alternatively, commit a `.mcp.json` file at the project root with the following contents:
 
-```json
+```json title=".mcp.json"
 {
   "mcpServers": {
     "emdash-docs": {
@@ -70,9 +68,9 @@ Or commit a `.mcp.json` at your project root:
 </TabItem>
 <TabItem label="OpenCode">
 
-Add to your `opencode.jsonc`:
+Add the following entry to `opencode.jsonc`:
 
-```jsonc
+```jsonc title="opencode.jsonc"
 {
   "mcp": {
     "emdash-docs": {
@@ -86,9 +84,9 @@ Add to your `opencode.jsonc`:
 </TabItem>
 <TabItem label="Cursor">
 
-Commit `.cursor/mcp.json` at your project root, or add it via **Cursor Settings -> MCP -> Add new MCP server**:
+Commit a `.cursor/mcp.json` file at the project root with the following contents, or add the server via **Cursor Settings -> MCP -> Add new MCP server**:
 
-```json
+```json title=".cursor/mcp.json"
 {
   "mcpServers": {
     "emdash-docs": {
@@ -102,9 +100,9 @@ Commit `.cursor/mcp.json` at your project root, or add it via **Cursor Settings
 </TabItem>
 <TabItem label="VS Code">
 
-Add to `.vscode/mcp.json` in your project (or your user settings):
+Add the following entry to `.vscode/mcp.json` in the project, or to user settings:
 
-```json
+```json title=".vscode/mcp.json"
 {
   "servers": {
     "emdash-docs": {
@@ -118,9 +116,9 @@ Add to `.vscode/mcp.json` in your project (or your user settings):
 </TabItem>
 <TabItem label="Claude Desktop">
 
-Claude Desktop only supports stdio MCP servers natively, so use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a bridge. Add to `claude_desktop_config.json`:
+Claude Desktop only supports stdio MCP servers natively, so use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a bridge. Add the following entry to `claude_desktop_config.json`:
 
-```json
+```json title="claude_desktop_config.json"
 {
   "mcpServers": {
     "emdash-docs": {
diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx
index 939d59fee..120c62759 100644
--- a/docs/src/content/docs/getting-started.mdx
+++ b/docs/src/content/docs/getting-started.mdx
@@ -106,7 +106,7 @@ Once your passkey is registered, you're logged in and redirected to the admin da
 
 4. Set the status to **Published** and click **Save**.
 
-5. Visit your site's homepage to see your post live—no rebuild needed!
+5. Visit your site's homepage to see your post live. No rebuild is needed.
 
 </Steps>
 
@@ -140,7 +140,7 @@ my-emdash-site/
 
 ### astro.config.mjs
 
-This configures EmDash as an Astro integration:
+The following configuration registers EmDash as an Astro integration with a local SQLite database and local file storage:
 
 ```js title="astro.config.mjs"
 import { defineConfig } from "astro/config";
@@ -162,7 +162,7 @@ export default defineConfig({
 
 ### src/live.config.ts
 
-This connects EmDash to Astro's content system:
+The following file connects EmDash to Astro's content system through a single live collection:
 
 ```ts title="src/live.config.ts"
 import { defineLiveCollection } from "astro:content";
@@ -180,33 +180,23 @@ export const collections = {
 
 ### Environment Variables
 
-For production, set an encryption key for plugin secrets:
+For production, generate an encryption key for plugin secrets with the following command:
 
 ```bash
 npx emdash secrets generate
 ```
 
-Add the result to your environment as `EMDASH_ENCRYPTION_KEY`. This
-key is used to encrypt plugin secrets at rest. The current release
-validates the key but does not yet use it to encrypt anything; plugin
-secret encryption is rolling out and will start using this value
-automatically when available. Set it now so your deployment is ready.
+Add the generated value to your environment as `EMDASH_ENCRYPTION_KEY`, as shown below. This key encrypts plugin secrets at rest. Set it now so your deployment is ready when plugin secret encryption uses it.
 
 ```bash
 EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...
 ```
 
-The key is never stored in the database — only encrypted ciphertext is.
-Back it up somewhere durable; losing it means losing every secret
-encrypted with it.
+The key is never stored in the database — only encrypted ciphertext is. Back it up somewhere durable, because losing it means losing every secret encrypted with it.
 
-The preview HMAC secret and commenter-IP hash salt are auto-generated
-and stored in the database on first use; you don't need to set them.
-You can override either if a separate process needs to share the value
-with your main site:
+The preview HMAC secret and commenter-IP hash salt are generated and stored in the database on first use, so you do not need to set them. Override the preview secret only if a separate process needs to verify the same tokens as your main site, as shown below.
 
 ```bash
-# Optional override — only needed if another process verifies these tokens
 EMDASH_PREVIEW_SECRET=your-preview-secret
 ```
 
@@ -234,7 +224,7 @@ const { entries: posts } = await getEmDashCollection("posts");
 </Base>
 ```
 
-For single entries:
+The following page fetches a single entry by slug:
 
 ```astro title="src/pages/posts/[slug].astro"
 ---
@@ -263,7 +253,7 @@ This creates `.emdash/types.ts` with interfaces for all your collections. Your e
 
 ## Next Steps
 
-You now have a working EmDash site! Here's where to go next:
+With the site running, the following pages cover what to do next:
 
 - **[Core Concepts](/concepts/architecture/)** — Understand how EmDash works under the hood
 - **[Working with Content](/guides/working-with-content/)** — Learn to query and render content
diff --git a/docs/src/content/docs/guides/atmosphere-auth.mdx b/docs/src/content/docs/guides/atmosphere-auth.mdx
index 1b15ee2f6..e86e44187 100644
--- a/docs/src/content/docs/guides/atmosphere-auth.mdx
+++ b/docs/src/content/docs/guides/atmosphere-auth.mdx
@@ -15,10 +15,14 @@ This is a good fit when:
 
 ## Install
 
+Install the provider package:
+
 ```bash
 pnpm add @emdash-cms/auth-atproto
 ```
 
+Add the provider to the EmDash integration:
+
 ```js title="astro.config.mjs"
 import { defineConfig } from "astro/config";
 import emdash from "emdash/astro";
@@ -42,6 +46,8 @@ No environment variables, client secret, or OAuth-app registration is required.
 
 ## Configuration
 
+The `atproto()` provider accepts an allowlist and a default role:
+
 ```js
 atproto({
 	allowedDIDs: ["did:plc:abc123..."],
@@ -94,7 +100,7 @@ When you start a fresh site with the Atmosphere provider configured, the setup w
 
 </Steps>
 
-The same flow runs for every subsequent login — handle in, redirect to your provider, redirect back, you're signed in.
+The same flow runs for every subsequent login: enter your handle, authenticate at your provider, and return to EmDash signed in.
 
 ## Local development
 
@@ -127,7 +133,7 @@ There's nothing extra to configure for production. The provider serves its own c
 https://your-site.example.com/.well-known/atproto-client-metadata.json
 ```
 
-Authorization servers fetch this URL during the login dance to verify the client's redirect URI. Make sure your deployment's site URL is reachable on the public internet over HTTPS — internal-only deployments behind a VPN won't be able to complete a login because the user's authorization server can't fetch the metadata document.
+Authorization servers fetch this URL during login to verify the client's redirect URI. Make sure your deployment's site URL is reachable on the public internet over HTTPS — internal-only deployments behind a VPN won't be able to complete a login because the user's authorization server can't fetch the metadata document.
 
 If you run EmDash behind a TLS-terminating reverse proxy, set [`siteUrl`](/reference/configuration#siteurl) so EmDash builds the right redirect URI. Without it, requests look like `http://internal-host:4321` and the metadata won't match what the auth server sees.
 
diff --git a/docs/src/content/docs/guides/authentication.mdx b/docs/src/content/docs/guides/authentication.mdx
index 6cab1b692..364ca5f20 100644
--- a/docs/src/content/docs/guides/authentication.mdx
+++ b/docs/src/content/docs/guides/authentication.mdx
@@ -97,7 +97,7 @@ Providers are additive — passkeys keep working when providers are enabled, and
 
 ### Configuring providers
 
-Pass providers to the `authProviders` array on the EmDash integration:
+Pass providers to the `authProviders` array on the EmDash integration. The following example enables GitHub, Google, and Atmosphere:
 
 ```js title="astro.config.mjs"
 import { defineConfig } from "astro/config";
@@ -119,6 +119,8 @@ Order matters for the login page: providers render in the order you list them, w
 
 ### GitHub
 
+The following example enables the GitHub provider:
+
 ```js
 import { github } from "emdash/auth/providers/github";
 
@@ -136,12 +138,16 @@ Configure your GitHub OAuth app's callback URL as `https://your-site.example.com
 
 ### Google
 
+The following example enables the Google provider:
+
 ```js
 import { google } from "emdash/auth/providers/google";
 
 emdash({ authProviders: [google()] });
 ```
 
+Set credentials via environment variables. EmDash checks the prefixed names first and falls back to the unprefixed ones:
+
 | Variable                                                      | Purpose                |
 | ------------------------------------------------------------- | ---------------------- |
 | `EMDASH_OAUTH_GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_ID`          | OAuth app client ID    |
@@ -151,12 +157,14 @@ Configure your Google OAuth client's redirect URI as `https://your-site.example.
 
 ### Atmosphere (AT Protocol)
 
-For sites where contributors already have an account on the AT Protocol network — the same identity that powers Bluesky and a growing collection of other apps — install the Atmosphere provider:
+For sites where contributors already have an [Atmosphere account](/guides/atmosphere-auth/) — the user-owned identity behind Bluesky and the wider AT Protocol network — install the Atmosphere provider:
 
 ```bash
 pnpm add @emdash-cms/auth-atproto
 ```
 
+The following example enables the Atmosphere provider with a handle allowlist:
+
 ```js
 import { atproto } from "@emdash-cms/auth-atproto";
 
@@ -332,7 +340,7 @@ When deploying to Cloudflare, you can use [Cloudflare Access](https://developers
 	Passkeys, OAuth, magic links, and self-signup are all disabled.
 </Aside>
 
-### Why Use Cloudflare Access?
+### Why Use Cloudflare Access
 
 - **Single Sign-On** — Users authenticate with your company's IdP
 - **Centralized access control** — Manage who can access the admin in the Cloudflare dashboard
diff --git a/docs/src/content/docs/guides/create-a-blog.mdx b/docs/src/content/docs/guides/create-a-blog.mdx
index 90769201c..a34c982ed 100644
--- a/docs/src/content/docs/guides/create-a-blog.mdx
+++ b/docs/src/content/docs/guides/create-a-blog.mdx
@@ -7,7 +7,7 @@ import { Aside, Steps, Tabs, TabItem, Code } from "@astrojs/starlight/components
 import postsListImg from "../../../assets/screenshots/admin-posts-list.png";
 import postEditorImg from "../../../assets/screenshots/admin-post-editor.png";
 
-This guide walks you through creating a blog with EmDash, from defining your content type to displaying posts with categories and tags.
+This guide covers creating a blog with EmDash, from defining the content type to displaying posts with categories and tags.
 
 ## Prerequisites
 
@@ -16,7 +16,7 @@ This guide walks you through creating a blog with EmDash, from defining your con
 
 ## Define the Posts Collection
 
-EmDash creates a default "posts" collection during setup. If you need to customize it, use the admin dashboard or API.
+EmDash creates a default "posts" collection during setup. Customize it from the admin dashboard or the API.
 
 The default posts collection includes:
 
@@ -48,13 +48,13 @@ The default posts collection includes:
 
 7. Click **Save**
 
-Your post is now live. No rebuild required.
+The post is now live. No rebuild is required.
 
 ## Display Posts on Your Site
 
 ### List All Posts
 
-Create a page that displays all published posts:
+The following page displays all published posts:
 
 ```astro title="src/pages/blog/index.astro"
 ---
@@ -91,7 +91,7 @@ const sortedPosts = posts.sort(
 
 ### Display a Single Post
 
-Create a dynamic route for individual posts:
+The following dynamic route renders an individual post:
 
 ```astro title="src/pages/blog/[slug].astro"
 ---
@@ -142,6 +142,8 @@ EmDash includes built-in category and tag taxonomies. See [Taxonomies](/guides/t
 
 ### Filter Posts by Category
 
+The following route lists posts in a single category:
+
 ```astro title="src/pages/category/[slug].astro"
 ---
 import { getEmDashCollection, getTerm, getTaxonomyTerms } from "emdash";
@@ -183,7 +185,7 @@ const { entries: posts } = await getEmDashCollection("posts", {
 
 ### Display Post Categories
 
-Show categories on individual posts:
+The following component shows the categories and tags assigned to a post:
 
 ```astro title="src/components/PostMeta.astro"
 ---
@@ -221,7 +223,7 @@ const tags = await getEntryTerms("posts", postId, "tag");
 
 ## Add Pagination
 
-For blogs with many posts, add pagination:
+For blogs with many posts, the following route paginates the post list:
 
 ```astro title="src/pages/blog/page/[page].astro"
 ---
@@ -282,7 +284,7 @@ const posts = sortedPosts.slice(start, start + POSTS_PER_PAGE);
 
 ## Add an RSS Feed
 
-Create an RSS feed for your blog:
+The following endpoint generates an RSS feed for the blog:
 
 ```ts title="src/pages/rss.xml.ts"
 import rss from "@astrojs/rss";
@@ -307,7 +309,7 @@ export async function GET(context) {
 }
 ```
 
-Install the RSS package if you haven't already:
+The feed depends on the `@astrojs/rss` package. The following command installs it:
 
 ```bash
 npm install @astrojs/rss
diff --git a/docs/src/content/docs/guides/internationalization.mdx b/docs/src/content/docs/guides/internationalization.mdx
index 03c16e4b8..7e0e638ad 100644
--- a/docs/src/content/docs/guides/internationalization.mdx
+++ b/docs/src/content/docs/guides/internationalization.mdx
@@ -40,7 +40,7 @@ When `i18n` is not present in the Astro config, all i18n features are disabled a
 
 ## How Translations Work
 
-EmDash uses a **row-per-locale** model. Each translation is its own row in the database with its own ID, slug, and status, linked to other translations via a shared `translation_group` identifier.
+EmDash uses a **row-per-locale** model. Each translation is its own row in the database with its own ID, slug, and status, linked to other translations via a shared `translation_group` identifier. A posts table with three translations looks like this:
 
 ```
 ec_posts:
@@ -102,6 +102,8 @@ locales, all linked via a shared `translation_group`. Menu items resolve their
 content references against the active locale's version of the referenced
 content.
 
+The following component fetches the primary menu for the active locale:
+
 ```astro title="src/components/PrimaryNav.astro"
 ---
 import { getMenu } from "emdash";
@@ -130,6 +132,8 @@ so `label` / `labelSingular` can be translated too. The pivot
 `content_taxonomies.taxonomy_id` stores the term's `translation_group`, so a
 single assignment spans every locale of the content.
 
+The following example fetches categories and a post's terms for the active locale:
+
 ```astro
 ---
 import { getTaxonomyTerms, getEntryTerms } from "emdash";
diff --git a/docs/src/content/docs/guides/media-library.mdx b/docs/src/content/docs/guides/media-library.mdx
index 7e88db9ae..9a6636cb2 100644
--- a/docs/src/content/docs/guides/media-library.mdx
+++ b/docs/src/content/docs/guides/media-library.mdx
@@ -231,10 +231,6 @@ const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
 
 For responsive images, use Astro's Image component with external URLs:
 
-### Responsive Images
-
-For responsive images, use Astro's Image component with external URLs:
-
 ```astro
 ---
 import { Image } from "astro:assets";
@@ -256,7 +252,7 @@ const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
 <Aside type="tip">
 Configure allowed image domains in `astro.config.mjs` to use the Image component with external URLs:
 
-```js
+```js title="astro.config.mjs"
 export default defineConfig({
 	image: {
 		domains: ["media.example.com"],
@@ -295,7 +291,7 @@ Authorization: Bearer YOUR_API_TOKEN
 file=<binary file data>
 ```
 
-Response:
+A successful upload returns the stored media item:
 
 ```json
 {
@@ -315,6 +311,8 @@ Response:
 
 ### List Media
 
+The following request lists media under a prefix:
+
 ```bash
 GET /_emdash/api/media?prefix=images/&limit=20
 Authorization: Bearer YOUR_API_TOKEN
@@ -322,6 +320,8 @@ Authorization: Bearer YOUR_API_TOKEN
 
 ### Delete Media
 
+The following request deletes a stored file:
+
 ```bash
 DELETE /_emdash/api/media/images/hero.jpg
 Authorization: Bearer YOUR_API_TOKEN
@@ -467,7 +467,7 @@ Media fields store a `MediaValue` object containing provider information:
 interface MediaValue {
   provider?: string;    // Provider ID, defaults to "local"
   id: string;           // Provider-specific ID
-  src?: string;         // Direct URL (for local media or legacy data)
+  src?: string;         // Direct URL (for local media or plain-string values)
   previewUrl?: string;  // Preview URL for admin display (external providers)
   filename?: string;    // Original filename
   mimeType?: string;    // MIME type
diff --git a/docs/src/content/docs/guides/preview.mdx b/docs/src/content/docs/guides/preview.mdx
index a96b9345c..92be40389 100644
--- a/docs/src/content/docs/guides/preview.mdx
+++ b/docs/src/content/docs/guides/preview.mdx
@@ -36,7 +36,7 @@ EMDASH_PREVIEW_SECRET="your-random-secret-key-here"
 
 If set, the env value wins over the DB-stored value.
 
-That's it. Your existing templates work with preview automatically:
+Existing templates work with preview automatically, as in the following page:
 
 ```astro title="src/pages/posts/[...slug].astro"
 ---
@@ -94,7 +94,7 @@ explicitly — pin your env var if you call it from page templates. Most
 sites use the admin UI's "Generate preview link" button instead, which
 goes through the API and uses the resolved secret automatically.
 
-With a base URL for absolute links:
+Pass `baseUrl` to generate an absolute URL:
 
 ```ts
 const fullUrl = await getPreviewUrl({
@@ -106,7 +106,7 @@ const fullUrl = await getPreviewUrl({
 // Returns: https://example.com/posts/my-draft-post?_preview=eyJjaWQ...
 ```
 
-With a custom path pattern:
+Pass `pathPattern` to generate a URL with a custom path:
 
 ```ts
 const blogUrl = await getPreviewUrl({
@@ -124,6 +124,8 @@ const blogUrl = await getPreviewUrl({
 when the entry is in the default locale and `prefixDefaultLocale` is `false`;
 adjacent slashes left by the empty value are collapsed automatically.
 
+The following example builds a locale-prefixed preview URL:
+
 ```ts
 await getPreviewUrl({
 	collection: "posts",
@@ -284,7 +286,7 @@ Tokens are signed with HMAC-SHA256 using your preview secret.
 
 ## Complete Example
 
-A full blog post page with preview and visual editing support:
+The following page combines preview and visual editing support in a full blog post template:
 
 ```astro title="src/pages/posts/[...slug].astro"
 ---
diff --git a/docs/src/content/docs/guides/sections.mdx b/docs/src/content/docs/guides/sections.mdx
index 0e9ee8d8c..2964831aa 100644
--- a/docs/src/content/docs/guides/sections.mdx
+++ b/docs/src/content/docs/guides/sections.mdx
@@ -11,7 +11,7 @@ Sections are reusable content blocks that editors can insert into any content vi
 
 ### getSection
 
-Fetch a single section by slug:
+The following example fetches a single section by slug:
 
 ```typescript
 import { getSection } from "emdash";
@@ -26,7 +26,7 @@ if (cta) {
 
 ### getSections
 
-Fetch multiple sections with optional filters:
+The following example fetches multiple sections with optional filters:
 
 ```typescript
 import { getSections } from "emdash";
@@ -45,6 +45,8 @@ const { items: results } = await getSections({ search: "newsletter" });
 
 ## Section Structure
 
+A section has the following shape:
+
 ```typescript
 interface Section {
   id: string;
@@ -71,7 +73,7 @@ interface Section {
 
 ## Using Sections in Content
 
-Editors insert sections using the `/section` slash command in the rich text editor:
+Editors insert sections using the `/section` slash command in the rich text editor.
 
 <Steps>
 
@@ -112,9 +114,9 @@ The section's Portable Text content is copied into the document. This means:
 
 ### Via Seed Files
 
-Include sections in your theme's seed file:
+The following seed file defines two sections for a theme:
 
-```json
+```json title=".emdash/seed.json"
 {
   "sections": [
     {
@@ -159,7 +161,7 @@ WordPress reusable blocks (`wp_block` post type) are automatically imported as s
 
 ## Rendering Sections Programmatically
 
-For server-rendered section content outside the editor:
+The following example renders a section's content server-side, outside the editor:
 
 ```astro
 ---
@@ -212,6 +214,8 @@ List sections with optional filters.
 
 ### List Sections
 
+List sections, optionally filtered by source or search term:
+
 ```http
 GET /_emdash/api/sections
 GET /_emdash/api/sections?source=theme
@@ -220,12 +224,16 @@ GET /_emdash/api/sections?search=newsletter
 
 ### Get Section
 
+Fetch a single section by slug:
+
 ```http
 GET /_emdash/api/sections/newsletter-cta
 ```
 
 ### Create Section
 
+Create a section with a POST request:
+
 ```http
 POST /_emdash/api/sections
 Content-Type: application/json
@@ -241,6 +249,8 @@ Content-Type: application/json
 
 ### Update Section
 
+Update a section with a PUT request:
+
 ```http
 PUT /_emdash/api/sections/my-section
 Content-Type: application/json
@@ -253,6 +263,8 @@ Content-Type: application/json
 
 ### Delete Section
 
+Delete a section by slug:
+
 ```http
 DELETE /_emdash/api/sections/my-section
 ```
diff --git a/docs/src/content/docs/guides/site-settings.mdx b/docs/src/content/docs/guides/site-settings.mdx
index a4a59805b..586e80477 100644
--- a/docs/src/content/docs/guides/site-settings.mdx
+++ b/docs/src/content/docs/guides/site-settings.mdx
@@ -97,6 +97,8 @@ This is useful when you only need one or two values and want to avoid fetching e
 
 ### Site Header
 
+The following component renders a header with the site logo and primary menu:
+
 ```astro title="src/components/Header.astro"
 ---
 import { getSiteSettings, getMenu } from "emdash";
@@ -131,6 +133,8 @@ const menu = await getMenu("primary");
 
 ### Social Links
 
+The following component renders links for each configured social platform:
+
 ```astro title="src/components/SocialLinks.astro"
 ---
 import { getSiteSetting } from "emdash";
@@ -167,6 +171,8 @@ const platforms = [
 
 ### SEO Meta Tags
 
+The following component builds document and Open Graph meta tags from site settings:
+
 ```astro title="src/components/SEO.astro"
 ---
 import { getSiteSettings } from "emdash";
@@ -239,13 +245,13 @@ const formatted = new Intl.DateTimeFormat("en-US", {
 
 ## Admin API
 
-Fetch settings programmatically:
+Fetch settings programmatically with a GET request:
 
 ```http
 GET /_emdash/api/settings
 ```
 
-Response:
+The response is a JSON object of the settings:
 
 ```json
 {
diff --git a/docs/src/content/docs/guides/taxonomies.mdx b/docs/src/content/docs/guides/taxonomies.mdx
index d2d9bcd54..42fdc5368 100644
--- a/docs/src/content/docs/guides/taxonomies.mdx
+++ b/docs/src/content/docs/guides/taxonomies.mdx
@@ -39,19 +39,21 @@ Both are available for the posts collection by default.
   </TabItem>
   <TabItem label="Content Editor">
 
-5. Open a content entry in the editor
+1. Open a content entry in the editor
 
-6. Find the taxonomy panel in the sidebar
+2. Find the taxonomy panel in the sidebar
 
-7. For categories: check the boxes for applicable terms, or click **+ Add New**
+3. For categories, check the boxes for applicable terms, or click **+ Add New**
 
-8. For tags: type tag names separated by commas
+4. For tags, type tag names separated by commas
 
-9. Save the content
+5. Save the content
 
   </TabItem>
   <TabItem label="API">
 
+The following request creates a term in the `category` taxonomy:
+
 ```bash
 POST /_emdash/api/taxonomies/category/terms
 Content-Type: application/json
@@ -126,6 +128,8 @@ interface TaxonomyTerm {
 
 ### Get a Single Term
 
+The following example fetches one term by taxonomy and slug:
+
 ```ts
 import { getTerm } from "emdash";
 
@@ -135,6 +139,8 @@ const category = await getTerm("category", "news");
 
 ### Get Terms for an Entry
 
+The following example retrieves the categories and tags assigned to a single entry:
+
 ```ts
 import { getEntryTerms } from "emdash";
 
@@ -441,6 +447,8 @@ Taxonomies specify which collections they apply to:
 
 ### Assign Terms to Content
 
+The following request assigns category terms to a post:
+
 ```bash
 POST /_emdash/api/content/posts/post-123/terms/category
 Content-Type: application/json
diff --git a/docs/src/content/docs/guides/widgets.mdx b/docs/src/content/docs/guides/widgets.mdx
index ec8b836fa..9728bb078 100644
--- a/docs/src/content/docs/guides/widgets.mdx
+++ b/docs/src/content/docs/guides/widgets.mdx
@@ -181,6 +181,8 @@ const menu = widget.type === "menu" && widget.menuName
 
 ### Recent Posts Widget
 
+The following component renders the most recent posts, with optional thumbnails and dates:
+
 ```astro title="src/components/widgets/RecentPosts.astro"
 ---
 import { getEmDashCollection } from "emdash";
@@ -218,6 +220,8 @@ const { entries: posts } = await getEmDashCollection("posts", {
 
 ### Search Widget
 
+The following component renders a search form that submits to a search page:
+
 ```astro title="src/components/widgets/SearchForm.astro"
 ---
 interface Props {
diff --git a/docs/src/content/docs/guides/working-with-content.mdx b/docs/src/content/docs/guides/working-with-content.mdx
index 678f79d7e..b78339f57 100644
--- a/docs/src/content/docs/guides/working-with-content.mdx
+++ b/docs/src/content/docs/guides/working-with-content.mdx
@@ -206,10 +206,12 @@ Delete content from the edit screen or content list:
 
 ## Content API
 
-For programmatic access, use the EmDash admin API:
+For programmatic access, use the EmDash admin API.
 
 ### Create Content
 
+The following request creates a draft post:
+
 ```bash
 POST /_emdash/api/content/posts
 Content-Type: application/json
@@ -225,6 +227,8 @@ Authorization: Bearer YOUR_API_TOKEN
 
 ### Update Content
 
+The following request updates an existing post and publishes it:
+
 ```bash
 PUT /_emdash/api/content/posts/my-new-post
 Content-Type: application/json
@@ -238,6 +242,8 @@ Authorization: Bearer YOUR_API_TOKEN
 
 ### Delete Content
 
+The following request permanently deletes a post:
+
 ```bash
 DELETE /_emdash/api/content/posts/my-new-post
 Authorization: Bearer YOUR_API_TOKEN
diff --git a/docs/src/content/docs/guides/x402-payments.mdx b/docs/src/content/docs/guides/x402-payments.mdx
index e499e51e2..84f4e1e7c 100644
--- a/docs/src/content/docs/guides/x402-payments.mdx
+++ b/docs/src/content/docs/guides/x402-payments.mdx
@@ -17,6 +17,8 @@ You can also enforce payment for all visitors, or check for payment headers with
 
 ## Installation
 
+Install the package with your package manager:
+
 <Tabs>
 <TabItem label="pnpm">
 ```bash
@@ -232,6 +234,8 @@ Solana is opt-in. Install `@x402/svm` and enable it in config:
 pnpm add @x402/svm
 ```
 
+Set the network to a Solana identifier and disable EVM if you only use Solana:
+
 ```js title="astro.config.mjs"
 x402({
 	payTo: "YourSolanaAddress",
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
index bec06affd..c56a7e0cf 100644
--- a/docs/src/content/docs/index.mdx
+++ b/docs/src/content/docs/index.mdx
@@ -16,7 +16,7 @@ hero:
 
 import { Card, CardGrid } from "@astrojs/starlight/components";
 
-## Why EmDash?
+## Why EmDash
 
 <CardGrid stagger>
 	<Card title="Astro-Native" icon="astro">
@@ -35,14 +35,11 @@ import { Card, CardGrid } from "@astrojs/starlight/components";
 
 ## Quick Start
 
+The following commands create a new EmDash site and start the development server. The admin UI is then available at `http://localhost:4321/_emdash/admin`.
+
 ```bash
-# Create a new EmDash site
 npm create astro@latest -- --template @emdash-cms/template-blog
-
-# Start the dev server
 npm run dev
-
-# Visit the admin at http://localhost:4321/_emdash/admin
 ```
 
 ## Features
diff --git a/docs/src/content/docs/introduction.mdx b/docs/src/content/docs/introduction.mdx
index 260204e15..40d91f3de 100644
--- a/docs/src/content/docs/introduction.mdx
+++ b/docs/src/content/docs/introduction.mdx
@@ -44,6 +44,8 @@ EmDash is a CMS built specifically for [Astro](https://astro.build). It uses Ast
 
 ## Architecture at a Glance
 
+The following diagram shows how EmDash sits inside an Astro site, connecting the content engine, admin panel, and plugins to the data layer.
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                      Your Astro Site                        │
@@ -76,7 +78,7 @@ EmDash is a CMS built specifically for [Astro](https://astro.build). It uses Ast
 
 ## Core Concepts
 
-Before diving in, familiarize yourself with these key concepts:
+These are the key concepts used throughout the documentation:
 
 - **Collections** — Content types defined in the database (posts, pages, products, etc.)
 - **Fields** — The properties of a collection (title, content, price, etc.)
diff --git a/docs/src/content/docs/migration/content-import.mdx b/docs/src/content/docs/migration/content-import.mdx
index 668d6331b..f2adcdb3e 100644
--- a/docs/src/content/docs/migration/content-import.mdx
+++ b/docs/src/content/docs/migration/content-import.mdx
@@ -5,7 +5,7 @@ description: Import content from WordPress and other sources into EmDash.
 
 import { Aside, Card, CardGrid, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
 
-EmDash's import system uses a pluggable source architecture. Each source knows how to probe, analyze, and fetch content from a specific platform.
+The EmDash import system is built on pluggable sources. Each source probes, analyzes, and fetches content from a specific platform.
 
 ## Import Sources
 
@@ -131,7 +131,7 @@ Each post type shows its status:
 
 Click **Create Schema & Import** to:
 
-1. Create new collections via SchemaRegistry
+1. Create new collections
 2. Add missing fields with correct column types
 3. Set up content tables with indexes
 
@@ -249,6 +249,8 @@ The import system exposes these endpoints:
 
 ### Probe URL
 
+Detect the platform behind a URL with a probe request:
+
 ```http
 POST /_emdash/api/import/probe
 Content-Type: application/json
@@ -256,10 +258,12 @@ Content-Type: application/json
 { "url": "https://example.com" }
 ```
 
-Returns detected platform and suggested action.
+The response contains the detected platform and suggested action.
 
 ### Analyze WXR
 
+Upload a WXR file to analyze its post types and schema compatibility:
+
 ```http
 POST /_emdash/api/import/wordpress/analyze
 Content-Type: multipart/form-data
@@ -267,10 +271,12 @@ Content-Type: multipart/form-data
 file: [WordPress export .xml]
 ```
 
-Returns post type analysis with schema compatibility.
+The response contains the post type analysis with schema compatibility.
 
 ### Prepare Schema
 
+Create the collections and fields for the selected post types:
+
 ```http
 POST /_emdash/api/import/wordpress/prepare
 Content-Type: application/json
@@ -282,10 +288,10 @@ Content-Type: application/json
 }
 ```
 
-Creates collections and fields.
-
 ### Execute Import
 
+Import the content into the mapped collections:
+
 ```http
 POST /_emdash/api/import/wordpress/execute
 Content-Type: multipart/form-data
@@ -294,10 +300,10 @@ file: [WordPress export .xml]
 config: { "postTypeMappings": { "post": { "collection": "posts" } } }
 ```
 
-Imports content to specified collections.
-
 ### Import Media
 
+Download and store the media attachments referenced by the import:
+
 ```http
 POST /_emdash/api/import/wordpress/media
 Content-Type: application/json
@@ -308,10 +314,12 @@ Content-Type: application/json
 }
 ```
 
-Streams NDJSON progress updates during download/upload.
+The response streams NDJSON progress updates during download and upload.
 
 ### Rewrite URLs
 
+Replace old media URLs in imported content with their stored equivalents:
+
 ```http
 POST /_emdash/api/import/wordpress/rewrite-urls
 Content-Type: application/json
@@ -321,8 +329,6 @@ Content-Type: application/json
 }
 ```
 
-Updates Portable Text content with new media URLs.
-
 ## Error Handling
 
 ### Recoverable Errors
@@ -339,7 +345,7 @@ Updates Portable Text content with new media URLs.
 
 ### Error Report
 
-After import:
+After an import completes, EmDash shows a summary of what succeeded, what was adjusted, and what failed:
 
 ```
 Import Complete
@@ -424,4 +430,4 @@ export default defineConfig({
 ## Next Steps
 
 - **[WordPress Migration](/migration/from-wordpress/)** — Complete WordPress migration guide
-- **[Plugin Porting](/migration/plugin-porting/)** — Port WordPress plugins to EmDash
+- **[Plugin Porting](/migration/porting-plugins/)** — Port WordPress plugins to EmDash
diff --git a/docs/src/content/docs/migration/from-wordpress.mdx b/docs/src/content/docs/migration/from-wordpress.mdx
index a9ec23914..f23019a0b 100644
--- a/docs/src/content/docs/migration/from-wordpress.mdx
+++ b/docs/src/content/docs/migration/from-wordpress.mdx
@@ -252,5 +252,5 @@ For exports over 100MB, consider:
 ## Next Steps
 
 - **[Content Import](/migration/content-import/)** — Other import sources and methods
-- **[Plugin Porting](/migration/plugin-porting/)** — Migrate WordPress plugin functionality
+- **[Plugin Porting](/migration/porting-plugins/)** — Migrate WordPress plugin functionality
 - **[Working with Content](/guides/working-with-content/)** — Query and render your imported content
diff --git a/docs/src/content/docs/migration/porting-plugins.mdx b/docs/src/content/docs/migration/porting-plugins.mdx
index ca03e446e..1906ef6dc 100644
--- a/docs/src/content/docs/migration/porting-plugins.mdx
+++ b/docs/src/content/docs/migration/porting-plugins.mdx
@@ -389,9 +389,9 @@ export function createPlugin() {
 </Tabs>
 
 <Aside type="tip" title="AI-Assisted Porting">
-	Plugin porting is more nuanced than theme porting, but AI agents still help significantly. Provide
-	the WordPress plugin code along with EmDash's Plugin API documentation, and the agent can
-	generate a reasonable first draft. Complex plugins may need multiple iterations.
+	Plugin porting is more nuanced than theme porting. Provide the WordPress plugin code along with
+	the EmDash Plugin API documentation to generate a first draft. Complex plugins may need several
+	iterations.
 </Aside>
 
 ## Capabilities
diff --git a/docs/src/content/docs/plugins/creating-native-plugins/distributing.mdx b/docs/src/content/docs/plugins/creating-native-plugins/distributing.mdx
index 5348c49ee..4b4944c93 100644
--- a/docs/src/content/docs/plugins/creating-native-plugins/distributing.mdx
+++ b/docs/src/content/docs/plugins/creating-native-plugins/distributing.mdx
@@ -9,7 +9,7 @@ Native plugins distribute via npm, not the marketplace. There's no bundler, no m
 
 ## Package layout
 
-A typical native plugin package:
+A typical native plugin package has the following layout:
 
 ```
 @my-org/plugin-analytics/
@@ -26,6 +26,8 @@ A typical native plugin package:
 
 ## package.json
 
+The following `package.json` declares the build scripts, exports, and peer dependencies a distributable plugin needs:
+
 ```json title="package.json"
 {
 	"name": "@my-org/plugin-analytics",
@@ -107,6 +109,8 @@ A good plugin README covers:
 
 ## Publishing to npm
 
+Bump the version and publish the package:
+
 ```bash
 npm version patch     # or minor/major
 npm publish --access public
@@ -130,8 +134,8 @@ pnpm add @my-org/plugin-analytics --workspace
 
 Then register the plugin in the test site's `astro.config.mjs` and run the dev server. Hook handlers run on the next request after `pnpm build` finishes.
 
-## Marketplace? No.
+## Marketplace availability
 
 Native plugins can't be published to the EmDash marketplace. The marketplace is sandboxed-only: every published plugin runs through `emdash plugin bundle` (which validates that the backend code is self-contained, doesn't import Node.js built-ins, and stays under size limits), gets a security audit, and runs in the sandbox runtime when installed.
 
-If you want the marketplace's distribution surface but your plugin currently uses native-only features, ask whether you actually need them — a lot of plugins can drop `page:fragments` or convert from `settingsSchema` to a Block Kit settings page and become sandboxable. See [Choosing a plugin format](/plugins/creating-plugins/choosing-a-format/) for the trade-offs.
+A plugin that uses native-only features can sometimes drop them and become sandboxable — for example, by removing `page:fragments` or converting `settingsSchema` to a Block Kit settings page. See [Choosing a plugin format](/plugins/creating-plugins/choosing-a-format/) for the trade-offs.
diff --git a/docs/src/content/docs/plugins/creating-native-plugins/page-fragments.mdx b/docs/src/content/docs/plugins/creating-native-plugins/page-fragments.mdx
index d535dc204..be4f1ec4a 100644
--- a/docs/src/content/docs/plugins/creating-native-plugins/page-fragments.mdx
+++ b/docs/src/content/docs/plugins/creating-native-plugins/page-fragments.mdx
@@ -36,7 +36,7 @@ Templates that omit one of these components silently ignore fragments targeting
 
 ## Contribution kinds
 
-Three kinds of contributions:
+A hook can return one of three contribution kinds:
 
 ```typescript
 type PageFragmentContribution =
@@ -70,7 +70,7 @@ type PageFragmentContribution =
 
 ### External script
 
-Inject a third-party tag manager:
+The following hook injects a third-party tag manager into `<head>`:
 
 ```typescript
 "page:fragments": async (event, ctx) => {
@@ -88,7 +88,7 @@ Inject a third-party tag manager:
 
 ### Inline script
 
-Run a small piece of JavaScript at the top of `<body>`:
+The following hook runs a small piece of JavaScript at the top of `<body>` on content pages:
 
 ```typescript
 "page:fragments": async (event, ctx) => {
@@ -107,7 +107,7 @@ Run a small piece of JavaScript at the top of `<body>`:
 
 ### HTML fragment
 
-Append a noscript fallback at the end of `<body>`:
+The following hook appends a noscript fallback at the end of `<body>`:
 
 ```typescript
 "page:fragments": async (event, ctx) => {
@@ -124,7 +124,7 @@ Append a noscript fallback at the end of `<body>`:
 
 ### Multiple fragments
 
-Return an array to contribute multiple fragments from a single hook:
+A hook can return an array to contribute multiple fragments at once. The following hook adds both a script and a noscript fallback:
 
 ```typescript
 "page:fragments": async (event, ctx) => {
diff --git a/docs/src/content/docs/plugins/creating-native-plugins/portable-text-components.mdx b/docs/src/content/docs/plugins/creating-native-plugins/portable-text-components.mdx
index cdac0876f..10d5f5e12 100644
--- a/docs/src/content/docs/plugins/creating-native-plugins/portable-text-components.mdx
+++ b/docs/src/content/docs/plugins/creating-native-plugins/portable-text-components.mdx
@@ -97,4 +97,4 @@ If you want a plugin to be sandboxed but still ship a default rendering experien
 2. Ship a separate companion native package on npm that provides the Astro rendering components.
 3. Document both: end users install the sandboxed plugin from the marketplace and `npm install` the companion package for rendering.
 
-This trades one-step install for keeping the editor side sandboxed. Most plugin authors prefer to just go native when block rendering is involved — but the option exists.
+This trades a one-step install for keeping the editor side sandboxed. Going fully native is simpler when block rendering is involved, but this split remains an option.
diff --git a/docs/src/content/docs/plugins/creating-native-plugins/react-admin.mdx b/docs/src/content/docs/plugins/creating-native-plugins/react-admin.mdx
index 2c4ff5975..ed81338ba 100644
--- a/docs/src/content/docs/plugins/creating-native-plugins/react-admin.mdx
+++ b/docs/src/content/docs/plugins/creating-native-plugins/react-admin.mdx
@@ -64,6 +64,8 @@ Admin pages are React components that mount under `/_emdash/admin/plugins/<plugi
 
 ### Page definition
 
+Declare each page under `admin.pages` with a path, label, and icon:
+
 ```typescript
 admin: {
 	pages: [
@@ -83,6 +85,8 @@ admin: {
 
 ### Page component
 
+The following component reads and saves settings through the plugin API hook:
+
 ```typescript title="src/components/SettingsPage.tsx"
 import { useState, useEffect } from "react";
 import { usePluginAPI } from "@emdash-cms/admin";
@@ -145,6 +149,8 @@ Widgets appear on the admin dashboard and provide at-a-glance information.
 
 ### Widget definition
 
+Declare each widget under `admin.widgets` with an id, title, and size:
+
 ```typescript
 admin: {
 	widgets: [
@@ -159,6 +165,8 @@ admin: {
 
 ### Widget component
 
+The following component fetches its data on mount and renders a compact summary:
+
 ```typescript title="src/components/SEOWidget.tsx"
 import { useState, useEffect } from "react";
 import { usePluginAPI } from "@emdash-cms/admin";
@@ -264,7 +272,7 @@ EmDash generates a settings page automatically. Reach for custom React pages onl
 
 ## Navigation
 
-Plugin pages appear in the admin sidebar under the plugin's name. The order matches the `admin.pages` array.
+Plugin pages appear in the admin sidebar under the plugin's name. The order matches the `admin.pages` array, as shown below:
 
 ```typescript
 admin: {
@@ -278,7 +286,7 @@ admin: {
 
 ## Build configuration
 
-Admin components need a separate build entry point. Configure your bundler:
+Admin components need a separate build entry point. The following bundler configuration builds both the server and admin entrypoints:
 
 <Tabs>
 <TabItem label="tsdown">
@@ -325,6 +333,8 @@ const enabled = await ctx.kv.get<boolean>("_emdash:enabled");
 
 ## Complete example
 
+The following plugin defines a dashboard page, a settings page, and a widget, with the runtime and admin entrypoints in separate files. The `src/index.ts` file holds the descriptor and runtime:
+
 ```typescript title="src/index.ts"
 import { definePlugin } from "emdash";
 import type { PluginDescriptor } from "emdash";
@@ -386,6 +396,8 @@ export function createPlugin() {
 export default createPlugin;
 ```
 
+The `src/admin.tsx` file maps page paths and widget ids to their React components:
+
 ```typescript title="src/admin.tsx"
 import { EventsWidget } from "./components/EventsWidget";
 import { DashboardPage } from "./components/DashboardPage";
diff --git a/docs/src/content/docs/plugins/creating-native-plugins/your-first-native-plugin.mdx b/docs/src/content/docs/plugins/creating-native-plugins/your-first-native-plugin.mdx
index ac714b36b..14365043b 100644
--- a/docs/src/content/docs/plugins/creating-native-plugins/your-first-native-plugin.mdx
+++ b/docs/src/content/docs/plugins/creating-native-plugins/your-first-native-plugin.mdx
@@ -31,6 +31,8 @@ my-native-plugin/
 
 ## Set up the package
 
+The following `package.json` declares the entrypoints and peer dependencies a native plugin needs:
+
 ```json title="package.json"
 {
 	"name": "@my-org/plugin-analytics",
@@ -59,6 +61,8 @@ Keep `emdash` and `react` as peer dependencies so the host site provides the act
 
 ## Write the descriptor and runtime
 
+The following `src/index.ts` defines the descriptor factory and the `createPlugin` runtime in one file:
+
 ```typescript title="src/index.ts"
 import { definePlugin } from "emdash";
 import type { PluginDescriptor } from "emdash";
@@ -139,7 +143,7 @@ export function createPlugin(options: AnalyticsOptions = {}) {
 export default createPlugin;
 ```
 
-A few details worth knowing:
+Key details of this configuration:
 
 - **`format: "native"` is required.** The default would otherwise be `"native"` too — but being explicit on every descriptor makes it easy to spot which format you're working with.
 - **`entrypoint` is the package's main export.** EmDash imports it at runtime and calls the default export to construct the resolved plugin.
@@ -149,7 +153,7 @@ A few details worth knowing:
 
 ## Plugin id rules
 
-The `id` field must match `/^[a-z][a-z0-9_-]*$/` — start with a lowercase letter, then letters, digits, hyphens, or underscores. The id is used as a single path segment in plugin route URLs and as part of generated SQL identifiers for plugin storage indexes, so anything outside that pattern fails at runtime.
+The `id` field must match `/^[a-z][a-z0-9_-]*$/` — start with a lowercase letter, then letters, digits, hyphens, or underscores. The id is used as a single path segment in plugin route URLs and as part of generated SQL identifiers for plugin storage indexes, so anything outside that pattern fails at runtime. The following values show which ids are accepted:
 
 ```typescript
 // Valid
@@ -169,7 +173,7 @@ Pair an unscoped `id` with a scoped npm package name in `entrypoint` — the pac
 
 ## Version format
 
-Use semantic versioning:
+Use semantic versioning. The following values show which version strings are accepted:
 
 ```typescript
 version: "1.0.0";       // valid
@@ -215,7 +219,9 @@ Field types: `string`, `number`, `boolean`, `select`, `secret`, `url`, `email`.
 
 For richer settings UI than `settingsSchema` provides, ship custom React pages — see [React admin pages and widgets](/plugins/creating-native-plugins/react-admin/).
 
-## Complete example: audit log plugin
+## Complete example — audit log plugin
+
+The following plugin records every content create, update, and delete to indexed storage and exposes a recent-activity route:
 
 ```typescript title="src/index.ts"
 import { definePlugin } from "emdash";
diff --git a/docs/src/content/docs/plugins/field-kit.mdx b/docs/src/content/docs/plugins/field-kit.mdx
index 84b4c7e09..8bb68cb43 100644
--- a/docs/src/content/docs/plugins/field-kit.mdx
+++ b/docs/src/content/docs/plugins/field-kit.mdx
@@ -13,13 +13,15 @@ Field Kit widgets store **clean JSON**: removing the plugin leaves valid data in
 
 ## Installation
 
+Install the package from npm:
+
 ```bash
 npm i @emdash-cms/plugin-field-kit
 ```
 
-Register the plugin in `astro.config.mjs`:
+The following configuration registers the plugin:
 
-```typescript
+```typescript title="astro.config.mjs"
 import { defineConfig } from "astro/config";
 import emdash from "emdash";
 import { fieldKitPlugin } from "@emdash-cms/plugin-field-kit";
@@ -33,7 +35,7 @@ export default defineConfig({
 });
 ```
 
-Then attach a widget to any `json` field by setting `widget` to `field-kit:<name>`:
+Attach a widget to any `json` field by setting `widget` to `field-kit:<name>`. The following field definition uses the `list` widget:
 
 ```json
 {
@@ -57,7 +59,7 @@ If a widget is missing its required `options` (e.g. `fields` for `object-form`/`
 
 ### object-form
 
-Renders a group of typed sub-fields that store as a single JSON object. Good for fixed-shape structured data like nutrition facts or contact info.
+Renders a group of typed sub-fields that store as a single JSON object. Good for fixed-shape structured data like nutrition facts or contact info. The following field definition configures a nutrition object:
 
 ```json
 {
@@ -86,7 +88,7 @@ Stored value: `{ "calories": 250, "protein": 12.5, "fat": 8, "carbs": 30 }`.
 
 ### list
 
-An ordered array editor with add, remove, and reorder controls. Each row is a JSON object whose shape is defined by `fields`. The row header shows a summary rendered from a Mustache-style template.
+An ordered array editor with add, remove, and reorder controls. Each row is a JSON object whose shape is defined by `fields`. The row header shows a summary rendered from a Mustache-style template. The following field definition configures an ingredients list:
 
 ```json
 {
@@ -108,7 +110,7 @@ An ordered array editor with add, remove, and reorder controls. Each row is a JS
 }
 ```
 
-Stored value:
+The stored value is an array of row objects:
 
 ```json
 [
@@ -129,7 +131,7 @@ Stored value:
 
 ### grid
 
-A two-dimensional matrix of rows × columns. Each cell can be a toggle, text input, number input, or select. Useful for matrices like seasonal availability, price tables, or feature comparisons.
+A two-dimensional matrix of rows × columns. Each cell can be a toggle, text input, number input, or select. Useful for matrices like seasonal availability, price tables, or feature comparisons. The following field definition configures a seasonal availability grid:
 
 ```json
 {
@@ -153,7 +155,7 @@ A two-dimensional matrix of rows × columns. Each cell can be a toggle, text inp
 }
 ```
 
-Stored value:
+The stored value is an object keyed by row, then by column:
 
 ```json
 {
@@ -173,7 +175,7 @@ Stored value:
 
 ### tags
 
-A chip-style input for arrays of strings. Supports a fixed `suggestions` list, free-form custom values (toggleable), case transforms, and an optional `max`.
+A chip-style input for arrays of strings. Supports a fixed `suggestions` list, free-form custom values (toggleable), case transforms, and an optional `max`. The following field definition configures a keywords tag input:
 
 ```json
 {
@@ -222,7 +224,7 @@ Common props on every sub-field: `required`, `helpText`, `defaultValue`.
 
 ## Summary templates
 
-The `list` widget renders each collapsed row using a Mustache-style template in `options.summary`. `{{key}}` is replaced with the row's value for that key (coerced to a string). Falsy values fall back to `"{itemLabel} {n}"`.
+The `list` widget renders each collapsed row using a Mustache-style template in `options.summary`. `{{key}}` is replaced with the row's value for that key (coerced to a string). Falsy values fall back to `"{itemLabel} {n}"`. The following template combines two keys:
 
 ```
 "summary": "{{name}} — {{amount}}"
diff --git a/docs/src/content/docs/plugins/installing.mdx b/docs/src/content/docs/plugins/installing.mdx
index 631591531..1069631a0 100644
--- a/docs/src/content/docs/plugins/installing.mdx
+++ b/docs/src/content/docs/plugins/installing.mdx
@@ -15,7 +15,7 @@ The admin dashboard includes a marketplace browser where you can search, install
 
 To install marketplace plugins, your site needs:
 
-1. **Sandbox runner configured** — Marketplace plugins run in an isolated runtime, which requires the sandbox runner:
+1. **Sandbox runner configured** — Marketplace plugins run in an isolated runtime, which requires the sandbox runner. The following configuration enables it:
 
    ```typescript title="astro.config.mjs"
    import { emdash } from "emdash/astro";
@@ -97,7 +97,7 @@ The plugin's sandbox code is removed from your R2 bucket and it stops running im
 
 ## From Configuration
 
-For native plugins (your own code, or packages you install via npm), add them directly to your Astro config:
+Native plugins — your own code, or packages installed via npm — are added directly to the Astro config. The following example registers the SEO plugin:
 
 ```typescript title="astro.config.mjs"
 import { defineConfig } from "astro/config";
@@ -126,7 +126,7 @@ Native plugins:
   Use native plugins only when you need features that require build-time integration: React admin pages, Portable Text rendering components, or page fragment injection. For everything else, prefer sandboxed plugins -- they can be installed, updated, and removed without code changes or redeployments.
 </Aside>
 
-## Marketplace vs. Config: When to Use Which
+## Marketplace vs. config — when to use which
 
 | | Marketplace (sandboxed) | Config (native or in-process sandboxed) |
 | --- | --- | --- |
diff --git a/docs/src/content/docs/plugins/overview.mdx b/docs/src/content/docs/plugins/overview.mdx
index cb5afa1ea..af8841160 100644
--- a/docs/src/content/docs/plugins/overview.mdx
+++ b/docs/src/content/docs/plugins/overview.mdx
@@ -32,7 +32,7 @@ Plugins extend EmDash without modifying core code. They can react to content lif
 
 ## Two kinds of plugins
 
-EmDash plugins come in two flavours:
+EmDash plugins come in two formats:
 
 - **Sandboxed plugins** run in an isolated runtime managed by a configurable sandbox runner. They can be installed from the marketplace with one click, are subject to capability and resource enforcement, and can't reach anything they didn't explicitly declare. This is the recommended choice for most plugins.
 - **Native plugins** run in the same process as your Astro site. They have full access to the runtime, can ship React admin pages and Portable Text rendering components, and inject HTML into public pages — but can't be published to the marketplace and require a code change plus a deploy to install.
diff --git a/docs/src/content/docs/reference/api.mdx b/docs/src/content/docs/reference/api.mdx
index ae691361c..9fec57a8e 100644
--- a/docs/src/content/docs/reference/api.mdx
+++ b/docs/src/content/docs/reference/api.mdx
@@ -7,13 +7,13 @@ import { Aside } from "@astrojs/starlight/components";
 
 EmDash exports functions for querying content, managing media, and working with the database.
 
-## Content Queries
+## Content queries
 
 EmDash's query functions follow Astro's [live content collections](https://docs.astro.build/en/reference/experimental-flags/live-content-collections/) pattern, returning `{ entries, error }` or `{ entry, error }` for graceful error handling.
 
 ### `getEmDashCollection()`
 
-Fetch all entries from a collection.
+Fetch all entries from a collection. The following example loads all posts and checks for an error:
 
 ```ts
 import { getEmDashCollection } from "emdash";
@@ -34,6 +34,8 @@ if (error) {
 
 #### Options
 
+The `options` parameter accepts the following filter:
+
 ```ts
 interface CollectionFilter {
 	status?: "draft" | "published" | "archived";
@@ -44,6 +46,8 @@ interface CollectionFilter {
 
 #### Returns
 
+The function resolves to a `CollectionResult`:
+
 ```ts
 interface CollectionResult<T> {
 	entries: ContentEntry<T>[]; // Empty array if error or none found
@@ -53,6 +57,8 @@ interface CollectionResult<T> {
 
 #### Examples
 
+The following examples filter by status and taxonomy, limit results, and handle errors:
+
 ```ts
 // Get all published posts
 const { entries: posts } = await getEmDashCollection("posts", {
@@ -80,7 +86,7 @@ if (error) {
 
 ### `getEmDashEntry()`
 
-Fetch a single entry by slug or ID.
+Fetch a single entry by slug or ID. The following example loads a post and redirects when it is missing:
 
 ```ts
 import { getEmDashEntry } from "emdash";
@@ -103,6 +109,8 @@ Preview mode is handled automatically — the middleware detects `_preview` toke
 
 #### Returns
 
+The function resolves to an `EntryResult`:
+
 ```ts
 interface EntryResult<T> {
 	entry: ContentEntry<T> | null; // null if not found
@@ -113,6 +121,8 @@ interface EntryResult<T> {
 
 #### Examples
 
+The following examples fetch by slug and ID, read preview state, and distinguish errors from not-found:
+
 ```ts
 // Get by slug
 const { entry: post } = await getEmDashEntry("posts", "hello-world");
@@ -132,11 +142,11 @@ if (!entry) {
 }
 ```
 
-## Content Types
+## Content types
 
 ### `ContentEntry`
 
-The entry returned by query functions:
+Query functions return entries in the following shape:
 
 ```ts
 interface ContentEntry<T = Record<string, unknown>> {
@@ -158,11 +168,11 @@ The `data` object contains all content fields plus system fields:
 - `publishedAt` - ISO timestamp or null
 - Plus all custom fields defined in your collection schema
 
-## Database Functions
+## Database functions
 
 ### `createDatabase()`
 
-Create a database connection.
+Create a database connection. The following example connects to a local SQLite file:
 
 ```ts
 import { createDatabase } from "emdash";
@@ -176,7 +186,7 @@ const db = createDatabase({ url: "file:./data.db" });
 
 ### `runMigrations()`
 
-Run pending database migrations.
+Run pending database migrations. The following example applies migrations and logs the count:
 
 ```ts
 import { createDatabase, runMigrations } from "emdash";
@@ -188,7 +198,7 @@ console.log(`Applied ${applied.length} migrations`);
 
 ### `getMigrationStatus()`
 
-Check migration status.
+Check which migrations have been applied and which are pending:
 
 ```ts
 import { createDatabase, getMigrationStatus } from "emdash";
@@ -204,6 +214,8 @@ Low-level data access through repositories.
 
 ### `ContentRepository`
 
+The following example shows the full set of `ContentRepository` operations:
+
 ```ts
 import { ContentRepository, createDatabase } from "emdash";
 
@@ -238,6 +250,8 @@ await repo.delete("posts", "01HXK5MZSN...");
 
 ### `MediaRepository`
 
+The following example lists, fetches, and records media:
+
 ```ts
 import { MediaRepository, createDatabase } from "emdash";
 
@@ -259,9 +273,9 @@ const newMedia = await repo.create({
 });
 ```
 
-## Schema Registry
+## Schema registry
 
-Programmatic schema management.
+Programmatic schema management. The following example lists collections, then creates a collection and a field:
 
 ```ts
 import { SchemaRegistry, createDatabase } from "emdash";
@@ -292,11 +306,11 @@ await registry.createField("products", {
 });
 ```
 
-## Preview System
+## Preview system
 
 ### `generatePreviewToken()`
 
-Generate a preview token for draft content.
+Generate a preview token for draft content. The following example creates a token that expires in one hour:
 
 ```ts
 import { generatePreviewToken } from "emdash";
@@ -310,7 +324,7 @@ const token = await generatePreviewToken({
 
 ### `verifyPreviewToken()`
 
-Verify a preview token.
+Verify a preview token and read its payload:
 
 ```ts
 import { verifyPreviewToken } from "emdash";
@@ -328,7 +342,7 @@ if (result.valid) {
 
 ### `isPreviewRequest()`
 
-Check if a request includes a preview token.
+Check whether a request includes a preview token, then read it:
 
 ```ts
 import { isPreviewRequest, getPreviewToken } from "emdash";
@@ -339,9 +353,9 @@ if (isPreviewRequest(Astro.request)) {
 }
 ```
 
-## Content Converters
+## Content converters
 
-Convert between Portable Text and ProseMirror formats.
+Convert between Portable Text and ProseMirror formats:
 
 ```ts
 import { prosemirrorToPortableText, portableTextToProsemirror } from "emdash";
@@ -353,7 +367,9 @@ const portableText = prosemirrorToPortableText(prosemirrorDoc);
 const prosemirrorDoc = portableTextToProsemirror(portableText);
 ```
 
-## Site Settings
+## Site settings
+
+Read site-wide settings with `getSiteSettings` and `getSiteSetting`:
 
 ```ts
 import { getSiteSettings, getSiteSetting } from "emdash";
@@ -369,6 +385,8 @@ Settings are read-only from the runtime API. Use the admin API to update them.
 
 ## Menus
 
+Fetch navigation menus and iterate their items, including nested children:
+
 ```ts
 import { getMenu, getMenus } from "emdash";
 
@@ -389,6 +407,8 @@ if (primaryMenu) {
 
 ## Taxonomies
 
+Fetch taxonomy terms, a single term, an entry's terms, or entries by term:
+
 ```ts
 import { getTaxonomyTerms, getTerm, getEntryTerms, getEntriesByTerm } from "emdash";
 
@@ -405,7 +425,9 @@ const postCategories = await getEntryTerms("posts", "post-123", "category");
 const newsPosts = await getEntriesByTerm("posts", "category", "news");
 ```
 
-## Widget Areas
+## Widget areas
+
+Fetch widget areas and the widgets they contain:
 
 ```ts
 import { getWidgetArea, getWidgetAreas } from "emdash";
@@ -425,6 +447,8 @@ if (sidebar) {
 
 ## Sections
 
+Fetch sections, filter them, and read their categories:
+
 ```ts
 import { getSection, getSections, getSectionCategories } from "emdash";
 
@@ -445,6 +469,8 @@ const categories = await getSectionCategories();
 
 ## Search
 
+Run a global search or a collection-specific search. Results include highlighted snippets:
+
 ```ts
 import { search, searchCollection } from "emdash";
 
@@ -468,9 +494,9 @@ const posts = await searchCollection("posts", "typescript", {
 });
 ```
 
-## Error Handling
+## Error handling
 
-EmDash exports error classes for handling specific failures:
+EmDash exports error classes for handling specific failures. The following example catches validation and schema errors:
 
 ```ts
 import {
diff --git a/docs/src/content/docs/reference/cli.mdx b/docs/src/content/docs/reference/cli.mdx
index 48fd10235..0e33536a5 100644
--- a/docs/src/content/docs/reference/cli.mdx
+++ b/docs/src/content/docs/reference/cli.mdx
@@ -9,7 +9,7 @@ The EmDash CLI provides commands for managing an EmDash CMS instance — databas
 
 ## Installation
 
-The CLI is included with the `emdash` package:
+The CLI is included with the `emdash` package. Install it with the following command:
 
 ```bash
 npm install emdash
@@ -200,7 +200,7 @@ npx emdash content get posts 01ABC123 --raw
 | ------- | ------------------------------------------------ |
 | `--raw` | Return raw Portable Text (skip markdown conversion) |
 
-The response includes a `_rev` token — pass it to `content update` to prove you've seen what you're overwriting.
+The response includes a `_rev` token. Pass it to `content update` to confirm you have seen the current state before overwriting it.
 
 #### `content create <collection>`
 
@@ -222,7 +222,7 @@ Provide data via exactly one of `--data`, `--file`, or `--stdin`.
 
 #### `content update <collection> <id>`
 
-Like a file editor that requires you to read before you write — you must provide the `_rev` token from a prior `get` to prove you've seen the current state. This prevents accidentally overwriting changes you haven't seen.
+You must provide the `_rev` token from a prior `get` to prove you have seen the current state. This prevents overwriting changes you have not seen. The following steps read an item, then update it with that token:
 
 ```bash
 # 1. Read the item, note the _rev
@@ -491,7 +491,7 @@ npx emdash secrets generate
 ```
 
 Prints the new key to stdout. Pipe it into your secret store, or write it
-straight to a dev file with `--write`:
+straight to a dev file with `--write`. The following commands write the key to `.dev.vars` or `.env`:
 
 ```bash
 npx emdash secrets generate --write .dev.vars
@@ -505,7 +505,7 @@ those secrets unreadable, so the protection is intentional.
 ### `emdash secrets fingerprint <key>`
 
 Print the 8-character fingerprint (kid) of a key without exposing its
-value. Useful in CI for verifying the right key was deployed:
+value. This is useful in CI for verifying the right key was deployed. The following command prints a key's fingerprint:
 
 ```bash
 npx emdash secrets fingerprint emdash_enc_v1_...
@@ -515,9 +515,9 @@ npx emdash secrets fingerprint emdash_enc_v1_...
 
 ### `.emdash/types.ts`
 
-TypeScript interfaces generated by `emdash types`:
+The `emdash types` command generates TypeScript interfaces for each collection:
 
-```ts
+```ts title=".emdash/types.ts"
 // Generated by EmDash CLI
 // Do not edit manually - run `emdash types` to regenerate
 
@@ -533,9 +533,9 @@ export interface Post {
 
 ### `.emdash/schema.json`
 
-Raw schema export for tooling:
+The command also writes a raw schema export for tooling:
 
-```json
+```json title=".emdash/schema.json"
 {
   "version": "a1b2c3d4",
   "collections": [
@@ -560,9 +560,11 @@ Raw schema export for tooling:
 | `EMDASH_IP_SALT`          | Optional override for the commenter-IP hash salt. When unset, EmDash generates and persists one in the options table. |
 | `EMDASH_AUTH_SECRET`      | Legacy. Used as the IP-salt source if set, so existing installs keep stable commenter-IP hashes across upgrade. New installs should not set this. |
 
-## Package Scripts
+## Package scripts
 
-```json
+Add the CLI commands as `package.json` scripts for convenience:
+
+```json title="package.json"
 {
 	"scripts": {
 		"dev": "emdash dev",
diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx
index 67d6143ba..a3e67980f 100644
--- a/docs/src/content/docs/reference/configuration.mdx
+++ b/docs/src/content/docs/reference/configuration.mdx
@@ -7,9 +7,9 @@ import { Aside } from "@astrojs/starlight/components";
 
 EmDash is configured through two files: `astro.config.mjs` for the integration and `src/live.config.ts` for content collections.
 
-## Astro Integration
+## Astro integration
 
-Configure EmDash as an Astro integration:
+Configure EmDash as an Astro integration in `astro.config.mjs`:
 
 ```js title="astro.config.mjs"
 import { defineConfig } from "astro/config";
@@ -30,11 +30,11 @@ export default defineConfig({
 });
 ```
 
-## Integration Options
+## Integration options
 
 ### `database`
 
-**Required.** Database adapter configuration.
+**Required.** Database adapter configuration. Choose one adapter:
 
 ```js
 // SQLite (Node.js)
@@ -57,7 +57,7 @@ See [Database Options](/deployment/database/) for details.
 
 ### `storage`
 
-**Required.** Media storage adapter configuration.
+**Required.** Media storage adapter configuration. Choose one adapter:
 
 ```js
 // Local filesystem (development)
@@ -90,7 +90,7 @@ See [Storage Options](/deployment/storage/) for details.
 
 ### `plugins`
 
-**Optional.** Array of EmDash plugins.
+**Optional.** Array of EmDash plugins. The following example registers one plugin:
 
 ```js
 import seoPlugin from "@emdash-cms/plugin-seo";
@@ -104,7 +104,7 @@ plugins: [seoPlugin()];
 
 By default, EmDash loads [Noto Sans](https://fonts.google.com/noto/specimen/Noto+Sans) via the [Astro Font API](https://docs.astro.build/en/guides/fonts/). Fonts are downloaded from Google at build time and self-hosted, so there are no runtime CDN requests. The base font covers Latin, Cyrillic, Greek, Devanagari, and Vietnamese scripts.
 
-To add support for additional writing systems, pass script names:
+To add support for additional writing systems, pass script names. The following example adds Arabic and Japanese:
 
 ```js
 emdash({
@@ -114,7 +114,7 @@ emdash({
 })
 ```
 
-Available scripts: `arabic`, `armenian`, `bengali`, `chinese-simplified`, `chinese-traditional`, `chinese-hongkong`, `devanagari`, `ethiopic`, `georgian`, `gujarati`, `gurmukhi`, `hebrew`, `japanese`, `kannada`, `khmer`, `korean`, `lao`, `malayalam`, `myanmar`, `oriya`, `sinhala`, `tamil`, `telugu`, `thai`, `tibetan`.
+The available scripts are `arabic`, `armenian`, `bengali`, `chinese-simplified`, `chinese-traditional`, `chinese-hongkong`, `devanagari`, `ethiopic`, `georgian`, `gujarati`, `gurmukhi`, `hebrew`, `japanese`, `kannada`, `khmer`, `korean`, `lao`, `malayalam`, `myanmar`, `oriya`, `sinhala`, `tamil`, `telugu`, `thai`, and `tibetan`.
 
 Each script maps to the corresponding Noto Sans variant on Google Fonts (e.g. `"arabic"` loads Noto Sans Arabic). All font faces share a single `font-family` name and use `unicode-range` so the browser only downloads the files it needs for the characters on the page.
 
@@ -122,7 +122,7 @@ Set to `false` to disable font injection entirely and use system fonts:
 
 ```js
 emdash({
-  fonts: false,
+	fonts: false,
 })
 ```
 
@@ -130,7 +130,7 @@ The admin CSS uses the `--font-emdash` CSS variable. This is set automatically b
 
 ### `auth`
 
-**Optional.** Authentication configuration.
+**Optional.** Authentication configuration. The following example shows self-signup, sessions, and Cloudflare Access together:
 
 ```js
 import { github } from "emdash/auth/providers/github";
@@ -178,6 +178,8 @@ Allow users to self-register if their email domain is allowed.
 | `domains`     | `string[]` | `[]`    | Allowed email domains     |
 | `defaultRole` | `number`   | `20`    | Role for self-signups     |
 
+The following example allows two domains and assigns the Contributor role:
+
 ```js
 selfSignup: {
   domains: ["example.com", "acme.org"],
@@ -187,7 +189,7 @@ selfSignup: {
 
 ### `authProviders`
 
-**Optional.** An array of pluggable login providers (top-level, alongside `auth`). Each entry is the result of calling a provider factory:
+**Optional.** An array of pluggable login providers (top-level, alongside `auth`). Each entry is the result of calling a provider factory, as shown below:
 
 ```js
 import { github } from "emdash/auth/providers/github";
@@ -203,7 +205,7 @@ Built-in providers:
 
 - `github()` — reads `EMDASH_OAUTH_GITHUB_CLIENT_ID` / `EMDASH_OAUTH_GITHUB_CLIENT_SECRET` (or unprefixed fallbacks).
 - `google()` — reads `EMDASH_OAUTH_GOOGLE_CLIENT_ID` / `EMDASH_OAUTH_GOOGLE_CLIENT_SECRET`.
-- `atproto()` — Atmosphere/AT Protocol login. No env vars needed. Accepts `{ allowedDIDs, allowedHandles, defaultRole }`. See the [Atmosphere login guide](/guides/atmosphere-auth/).
+- `atproto()` — Atmosphere account login (Bluesky and the wider AT Protocol network). No env vars needed. Accepts `{ allowedDIDs, allowedHandles, defaultRole }`. See the [Atmosphere login guide](/guides/atmosphere-auth/).
 
 Third-party packages can register their own providers using the same `AuthProviderDescriptor` shape — see [Login Providers](/guides/authentication/#login-providers).
 
@@ -242,6 +244,8 @@ Behind a **TLS-terminating reverse proxy**, `Astro.url` returns the internal add
 
 The integration **validates** this value at load time: it must be a valid URL with **`http:`** or **`https:`** protocol and is normalized to **origin** (path is stripped).
 
+The following example sets the public origin:
+
 ```js
 emdash({
 	database: sqlite({ url: "file:./data.db" }),
@@ -256,7 +260,8 @@ emdash({
 When `siteUrl` is not set in config, EmDash checks environment variables in order: `EMDASH_SITE_URL`, then `SITE_URL`. This is useful for container deployments where the public URL is set at runtime.
 
 <Aside type="tip">
-	`siteUrl` replaces `passkeyPublicOrigin` (removed). If you were using `passkeyPublicOrigin`, rename it to `siteUrl` -- it now covers passkeys and all other origin-dependent features.
+	`siteUrl` is the single option for the public origin. It covers passkeys and all other
+	origin-dependent features.
 </Aside>
 
 #### Multi-origin passkey verification
@@ -265,6 +270,8 @@ When `siteUrl` is not set in config, EmDash checks environment variables in orde
 
 Declare additional accepted origins via either `allowedOrigins` in `astro.config.mjs` or the `EMDASH_ALLOWED_ORIGINS` env var. The canonical `siteUrl` remains the source of `rpId`; entries listed here are accepted at verification time. The two sources are merged at runtime, so config can declare the stable origins (versioned, code-reviewed) while env adds environment-specific extras (e.g. ephemeral PR previews).
 
+The following example declares one extra origin in config:
+
 ```js title="astro.config.mjs"
 emdash({
 	siteUrl: "https://example.com",
@@ -272,6 +279,8 @@ emdash({
 })
 ```
 
+The equivalent values can also come from environment variables:
+
 ```bash title=".env / wrangler.jsonc / Docker env"
 EMDASH_SITE_URL=https://example.com
 EMDASH_ALLOWED_ORIGINS=https://preview.example.com,https://staging.example.com
@@ -306,6 +315,8 @@ If your proxy writes a client-IP header, set [**`trustedProxyHeaders`**](#truste
 	Your reverse proxy should forward a **port-aware** `Host` / `X-Forwarded-Host` when you use non-default ports. If the proxy strips the port, **`rpId`** and Astro’s rebuilt URL can be wrong.
 </Aside>
 
+The following configuration sets `allowedDomains`, `vite.server.allowedHosts`, and `siteUrl` together for a reverse-proxy deployment:
+
 ```js title="astro.config.mjs (excerpt)"
 import { defineConfig } from "astro/config";
 import emdash, { local } from "emdash/astro";
@@ -342,19 +353,19 @@ export default defineConfig({
 
 On Cloudflare the `cf` object attached to the request is used automatically — you normally do **not** need to set this. On self-hosted deployments behind nginx, Caddy, Traefik, Fly, Railway, or similar, set this to the header your proxy writes so rate limits can bucket by real client IP instead of treating every request as "unknown".
 
+The following example trusts the `x-real-ip` header set by nginx, Caddy, or Traefik:
+
 ```js
 emdash({
 	database: sqlite({ url: "file:./data.db" }),
-	// nginx / Caddy / Traefik
 	trustedProxyHeaders: ["x-real-ip"],
 });
 ```
 
-Headers are tried in order. Values matching `*-forwarded-for` are parsed as comma-separated lists and the first entry is used.
+Headers are tried in order. Values matching `*-forwarded-for` are parsed as comma-separated lists and the first entry is used. The following example prefers Fly.io's header and falls back to `x-forwarded-for`:
 
 ```js
 emdash({
-	// Fly.io, falling back to generic X-Forwarded-For
 	trustedProxyHeaders: ["fly-client-ip", "x-forwarded-for"],
 });
 ```
@@ -371,7 +382,7 @@ When not set in config, EmDash reads the `EMDASH_TRUSTED_PROXY_HEADERS` env var
 
 ### `maxUploadSize`
 
-**Optional.** Maximum allowed media file upload size in bytes. Applies to both direct multipart uploads and signed-URL uploads. Defaults to `52_428_800` (50 MB).
+**Optional.** Maximum allowed media file upload size in bytes. Applies to both direct multipart uploads and signed-URL uploads. Defaults to `52_428_800` (50 MB). The following example raises the limit to 100 MB:
 
 ```js
 emdash({
@@ -391,9 +402,9 @@ emdash({
 
 Uploads that exceed the configured limit are rejected with a `413 Payload Too Large` response on the direct upload path, or a `400 Validation Error` on the signed-URL path.
 
-## Database Adapters
+## Database adapters
 
-Import from `emdash/db`:
+Import the adapters from `emdash/db`:
 
 ```js
 import { sqlite, libsql, postgres, d1 } from "emdash/db";
@@ -401,7 +412,7 @@ import { sqlite, libsql, postgres, d1 } from "emdash/db";
 
 ### `sqlite(config)`
 
-SQLite database using better-sqlite3.
+SQLite database using better-sqlite3. The following example connects to a local file:
 
 | Option | Type     | Description                   |
 | ------ | -------- | ----------------------------- |
@@ -413,7 +424,7 @@ sqlite({ url: "file:./data.db" });
 
 ### `libsql(config)`
 
-libSQL database.
+libSQL database. The following example connects to a remote libSQL database:
 
 | Option      | Type     | Description                           |
 | ----------- | -------- | ------------------------------------- |
@@ -443,6 +454,8 @@ PostgreSQL database with connection pooling.
 | `pool.min`         | `number`  | Minimum pool size (default: 0)       |
 | `pool.max`         | `number`  | Maximum pool size (default: 10)      |
 
+The following example connects with a connection string:
+
 ```js
 postgres({ connectionString: process.env.DATABASE_URL });
 ```
@@ -457,6 +470,8 @@ Cloudflare D1 database. Import from `@emdash-cms/cloudflare`.
 | `session`        | `string` | `"disabled"`         | Read replication mode: `"disabled"`, `"auto"`, or `"primary-first"` |
 | `bookmarkCookie` | `string` | `"__em_d1_bookmark"` | Cookie name for session bookmarks                   |
 
+The following example shows a basic binding and one with read replicas enabled:
+
 ```js
 // Basic
 d1({ binding: "DB" });
@@ -471,9 +486,9 @@ When `session` is `"auto"` or `"primary-first"`, EmDash uses the D1 Sessions API
 	D1 requires migrations via Wrangler CLI. DDL statements are not allowed at runtime.
 </Aside>
 
-## Storage Adapters
+## Storage adapters
 
-Import from `emdash/astro`:
+Import the adapters from `emdash/astro`:
 
 ```js
 import emdash, { local, r2, s3 } from "emdash/astro";
@@ -481,7 +496,7 @@ import emdash, { local, r2, s3 } from "emdash/astro";
 
 ### `local(config)`
 
-Local filesystem storage.
+Local filesystem storage. The following example serves uploads from a local directory:
 
 | Option      | Type     | Description                |
 | ----------- | -------- | -------------------------- |
@@ -497,7 +512,7 @@ local({
 
 ### `r2(config)`
 
-Cloudflare R2 binding.
+Cloudflare R2 binding. The following example uses an R2 binding with a public URL:
 
 | Option      | Type     | Description         |
 | ----------- | -------- | ------------------- |
@@ -531,6 +546,8 @@ for details.
 | `region`          | `string` | Region, default `"auto"` (`S3_REGION`) |
 | `publicUrl`       | `string` | Optional CDN URL (`S3_PUBLIC_URL`)  |
 
+The following examples resolve all fields from the environment, mix config and environment, or pass every field explicitly:
+
 ```js
 // All fields from S3_* environment variables (Node container deployments)
 s3()
@@ -538,7 +555,7 @@ s3()
 // Mix: CDN from config, rest from environment
 s3({ publicUrl: "https://cdn.example.com" })
 
-// All explicit (unchanged from before)
+// All explicit
 s3({
 	endpoint: "https://xxx.r2.cloudflarestorage.com",
 	bucket: "media",
@@ -555,7 +572,7 @@ not picked up. Workers deployments should either use the [`r2(config)`](#r2confi
 adapter or pass explicit values to `s3({...})`. See
 [Storage Options](/deployment/storage/#s3-compatible-storage) for details.
 
-## Live Collections
+## Live collections
 
 Configure the EmDash loader in `src/live.config.ts`:
 
@@ -570,17 +587,15 @@ export const collections = {
 };
 ```
 
-### Loader Options
+### Loader options
 
-The `emdashLoader()` function accepts optional configuration:
+The `emdashLoader()` function accepts an optional configuration object, reserved for future use:
 
 ```ts
-emdashLoader({
-	// Currently no options - reserved for future use
-});
+emdashLoader({});
 ```
 
-## Environment Variables
+## Environment variables
 
 EmDash respects these environment variables:
 
@@ -595,15 +610,15 @@ EmDash respects these environment variables:
 | `EMDASH_AUTH_SECRET`      | Legacy. Used as the IP-salt source if set; existing installs should keep this to preserve stable commenter-IP hashes across upgrade. |
 | `EMDASH_URL`              | Remote EmDash URL for schema sync         |
 
-Generate an encryption key with:
+Generate an encryption key with the following command:
 
 ```bash
 npx emdash secrets generate
 ```
 
-## package.json Configuration
+## package.json configuration
 
-Optional configuration in `package.json`:
+Templates and sites can declare optional metadata under an `emdash` key in `package.json`:
 
 ```json title="package.json"
 {
@@ -625,9 +640,9 @@ Optional configuration in `package.json`:
 | `url`         | Remote URL for schema sync         |
 | `preview`     | Demo site URL for template preview |
 
-## TypeScript Configuration
+## TypeScript configuration
 
-EmDash generates types in `.emdash/types.ts`. Add to your `tsconfig.json`:
+EmDash generates types in `.emdash/types.ts`. Add a path alias to your `tsconfig.json`:
 
 ```json title="tsconfig.json"
 {
@@ -639,7 +654,7 @@ EmDash generates types in `.emdash/types.ts`. Add to your `tsconfig.json`:
 }
 ```
 
-Generate types with:
+Generate types with the following command:
 
 ```bash
 npx emdash types
diff --git a/docs/src/content/docs/reference/field-types.mdx b/docs/src/content/docs/reference/field-types.mdx
index 789cf6665..10d43fbf4 100644
--- a/docs/src/content/docs/reference/field-types.mdx
+++ b/docs/src/content/docs/reference/field-types.mdx
@@ -9,6 +9,8 @@ EmDash supports 14 field types for defining content schemas. Each type maps to a
 
 ## Overview
 
+The following table lists every field type and its SQLite column:
+
 | Type           | SQLite Column | Description                |
 | -------------- | ------------- | -------------------------- |
 | `string`       | TEXT          | Short text input           |
@@ -242,7 +244,7 @@ Rich text content using Portable Text format. Supports headings, lists, links, i
 }
 ```
 
-Stored as JSON array of Portable Text blocks:
+The value is stored as a JSON array of Portable Text blocks, for example:
 
 ```json
 [
@@ -282,7 +284,7 @@ Reference to an uploaded image. Includes metadata like dimensions and alt text.
 
 - `showPreview` — Show image preview in admin (default: true)
 
-**Stored value:**
+The value is stored as an object with the media reference and its metadata:
 
 ```json
 {
@@ -296,7 +298,7 @@ Reference to an uploaded image. Includes metadata like dimensions and alt text.
 
 ### `file`
 
-Reference to an uploaded file (documents, PDFs, etc.).
+Reference to an uploaded file such as a document or PDF.
 
 ```ts
 {
@@ -306,7 +308,7 @@ Reference to an uploaded file (documents, PDFs, etc.).
 }
 ```
 
-**Stored value:**
+The value is stored as an object with the file reference and its metadata:
 
 ```json
 {
@@ -341,13 +343,13 @@ Reference to another content entry.
 - `collection` — Target collection slug (required)
 - `allowMultiple` — Allow multiple references (default: false)
 
-**Single reference stored value:**
+A single reference is stored as the target entry ID:
 
 ```json
 "01HXK5MZSN..."
 ```
 
-**Multiple references stored value:**
+Multiple references are stored as an array of entry IDs:
 
 ```json
 ["01HXK5MZSN...", "01HXK6NATS..."]
@@ -371,7 +373,7 @@ Stored as-is in SQLite JSON column.
 
 <Aside type="caution">JSON fields have no validation. Use sparingly for truly dynamic data.</Aside>
 
-## Field Properties
+## Field properties
 
 All fields support these common properties:
 
@@ -388,7 +390,7 @@ All fields support these common properties:
 | `options`      | `object`    | Widget configuration                |
 | `sortOrder`    | `number`    | Display order in admin              |
 
-## Reserved Field Slugs
+## Reserved field slugs
 
 These slugs are reserved and cannot be used:
 
@@ -402,9 +404,9 @@ These slugs are reserved and cannot be used:
 - `deleted_at`
 - `version`
 
-## TypeScript Types
+## TypeScript types
 
-Import field types for programmatic use:
+Import the field type definitions for programmatic use:
 
 ```ts
 import type { FieldType, Field, CreateFieldInput } from "emdash";
diff --git a/docs/src/content/docs/reference/hooks.mdx b/docs/src/content/docs/reference/hooks.mdx
index 8c7e007d9..7f445e563 100644
--- a/docs/src/content/docs/reference/hooks.mdx
+++ b/docs/src/content/docs/reference/hooks.mdx
@@ -7,7 +7,9 @@ import { Aside } from "@astrojs/starlight/components";
 
 Hooks allow plugins to intercept and modify EmDash behavior at specific points in the content, media, email, comment, and page lifecycle.
 
-## Hook Overview
+## Hook overview
+
+The following table lists every hook, what triggers it, what it can modify, and whether it is exclusive:
 
 | Hook                    | Trigger                               | Can Modify        | Exclusive |
 | ----------------------- | ------------------------------------- | ----------------- | --------- |
diff --git a/docs/src/content/docs/reference/mcp-server.mdx b/docs/src/content/docs/reference/mcp-server.mdx
index ca0630b92..39ce4e3f4 100644
--- a/docs/src/content/docs/reference/mcp-server.mdx
+++ b/docs/src/content/docs/reference/mcp-server.mdx
@@ -683,10 +683,14 @@ MCP clients that support OAuth 2.1 can automatically discover how to authenticat
 
 ### Protected Resource Metadata
 
+Request the protected resource metadata at the following endpoint:
+
 ```http
 GET /.well-known/oauth-protected-resource
 ```
 
+The server responds with the resource identifier, its authorization server, and supported scopes:
+
 ```json
 {
   "resource": "https://example.com/_emdash/api/mcp",
@@ -705,10 +709,14 @@ GET /.well-known/oauth-protected-resource
 
 ### Authorization Server Metadata
 
+Request the authorization server metadata at the following endpoint:
+
 ```http
 GET /.well-known/oauth-authorization-server/_emdash
 ```
 
+The server responds with the endpoints, scopes, and grant types it supports:
+
 ```json
 {
   "issuer": "https://example.com/_emdash",
diff --git a/docs/src/content/docs/reference/rest-api.mdx b/docs/src/content/docs/reference/rest-api.mdx
index 86d05f5e9..db7455192 100644
--- a/docs/src/content/docs/reference/rest-api.mdx
+++ b/docs/src/content/docs/reference/rest-api.mdx
@@ -9,7 +9,7 @@ EmDash exposes a REST API at `/_emdash/api/` for content management, media uploa
 
 ## Authentication
 
-API requests require authentication via Bearer token:
+API requests require authentication via a Bearer token in the `Authorization` header:
 
 ```http
 Authorization: Bearer <token>
@@ -17,18 +17,20 @@ Authorization: Bearer <token>
 
 Generate tokens through the admin interface or programmatically.
 
-## Response Format
+## Response format
 
-All responses follow a consistent format:
+All responses follow a consistent format. A successful response wraps the result in `data`:
 
 ```json
-// Success
 {
   "success": true,
   "data": { ... }
 }
+```
+
+An error response includes a code, message, and optional details:
 
-// Error
+```json
 {
   "success": false,
   "error": {
diff --git a/docs/src/content/docs/themes/creating-themes.mdx b/docs/src/content/docs/themes/creating-themes.mdx
index c39b85383..b2a2ecd5f 100644
--- a/docs/src/content/docs/themes/creating-themes.mdx
+++ b/docs/src/content/docs/themes/creating-themes.mdx
@@ -9,14 +9,14 @@ An EmDash theme is a complete Astro site -- pages, layouts, components, styles -
 
 ## Key Concepts
 
-- **A theme is a working Astro project.** There's no theme API or abstraction layer. You build a site and ship it as a template. The seed file just tells EmDash what collections, fields, menus, redirects, and taxonomies to create on first run.
-- **EmDash gives you more control over the content model than WordPress.** Themes take advantage of this -- the seed file declares exactly what fields each collection needs. Build on the standard **posts** and **pages** collections and add fields and taxonomies as your design requires, rather than inventing entirely new content types.
+- **A theme is a working Astro project.** There is no theme API or abstraction layer. A theme is a site shipped as a template. The seed file tells EmDash what collections, fields, menus, redirects, and taxonomies to create on first run.
+- **The seed file declares the content model.** It lists exactly what fields each collection needs. Build on the standard **posts** and **pages** collections and add fields and taxonomies as the design requires, rather than inventing entirely new content types.
 - **Theme content pages must be server-rendered.** In a theme, content changes at runtime through the admin UI, so pages that display EmDash content must not be prerendered. Do not use `getStaticPaths()` in theme content routes. (Static site builds using EmDash as a build-time data source _can_ use `getStaticPaths`, but themes are always SSR.)
 - **No hard-coded content.** Site title, tagline, navigation, and other dynamic content come from the CMS via API calls -- not from template strings.
 
 ## Project Structure
 
-Create a theme with this structure:
+A theme uses the following structure:
 
 ```
 my-emdash-theme/
@@ -346,9 +346,9 @@ const primaryMenu = await getMenu("primary");
 
 Themes often need multiple page layouts -- a default layout, a full-width layout, a landing page layout. In EmDash, add a `template` select field to the pages collection and map it to layout components in your catch-all route.
 
-Add the field to your pages collection in the seed file:
+Add the field to the pages collection in the seed file:
 
-```json
+```json title=".emdash/seed.json"
 {
 	"slug": "template",
 	"label": "Page Template",
@@ -486,9 +486,7 @@ Include sample content in the seed file to demonstrate your theme's design:
 
 ## Including Media
 
-Reference images in sample content using the `$media` syntax.
-
-For remote images:
+Reference images in sample content using the `$media` syntax. A remote image is referenced by URL:
 
 ```json
 {
@@ -504,7 +502,7 @@ For remote images:
 }
 ```
 
-For local images, place files in `.emdash/uploads/` and reference them:
+For local images, place files in `.emdash/uploads/` and reference them by filename:
 
 ```json
 {
@@ -580,7 +578,7 @@ Users can then install your theme:
 npm create astro@latest -- --template @your-org/emdash-theme-blog
 ```
 
-For GitHub-hosted themes:
+A GitHub-hosted theme is installed with the `github:` template prefix:
 
 ```bash
 npm create astro@latest -- --template github:your-org/emdash-theme-blog
@@ -684,7 +682,7 @@ const marketingTypes = {
 <PortableText value={value} components={{ types: marketingTypes }} />
 ```
 
-Then use it in your pages:
+Render the wrapper component in a page:
 
 ```astro title="src/pages/index.astro"
 ---
@@ -715,7 +713,7 @@ Add `_key` to blocks that should be linkable:
 }
 ```
 
-Then use it as an anchor in your component:
+Use the `_key` value as an anchor in the block component:
 
 ```astro
 <section id={value._key}>
diff --git a/docs/src/content/docs/themes/overview.mdx b/docs/src/content/docs/themes/overview.mdx
index e30af76a0..1174f75e9 100644
--- a/docs/src/content/docs/themes/overview.mdx
+++ b/docs/src/content/docs/themes/overview.mdx
@@ -18,14 +18,15 @@ A theme is a working Astro project with:
 - **A seed file** — JSON that tells the CMS what content types and fields to create
 
 <Aside>
-	EmDash gives you far more control over the content model than WordPress does. Themes take
-	advantage of this by declaring exactly which collections and fields they need via the seed file.
-	Most themes should build on the standard **posts** and **pages** collections, adding fields and
-	taxonomies as needed rather than inventing entirely new content types.
+	A theme declares exactly which collections and fields it needs via the seed file. Most themes
+	build on the standard **posts** and **pages** collections, adding fields and taxonomies as needed
+	rather than inventing entirely new content types.
 </Aside>
 
 ## Theme Structure
 
+A theme has the following layout:
+
 ```
 my-theme/
 ├── package.json           # Theme metadata + EmDash config
@@ -42,10 +43,10 @@ my-theme/
 
 ## How Themes Bootstrap Sites
 
-When you create a site from a theme, this happens:
+Creating a site from a theme follows these steps:
 
 1. `create-astro` scaffolds the project from the template
-2. You run `npm install` and `npm run dev`
+2. Run `npm install` and `npm run dev`
 3. On first admin visit, the **Setup Wizard** runs automatically
 4. The wizard applies the seed file, creating collections, menus, redirects, and content
 5. The site is ready to use
@@ -61,19 +62,19 @@ When you create a site from a theme, this happens:
 
 ## Installing a Theme
 
-Use `create-astro` with a template:
+The following command scaffolds a site from an official theme template:
 
 ```bash
 npm create astro@latest -- --template @emdash-cms/template-blog
 ```
 
-Community themes work via GitHub:
+Community themes hosted on GitHub use the `github:` template prefix:
 
 ```bash
 npm create astro@latest -- --template github:user/emdash-portfolio
 ```
 
-After installation:
+After scaffolding, install dependencies and start the dev server:
 
 ```bash
 cd my-site
@@ -85,35 +86,13 @@ Visit `http://localhost:4321/_emdash/admin` to complete the Setup Wizard.
 
 ## The Setup Wizard
 
-The Setup Wizard runs automatically on first admin visit. It:
+The Setup Wizard runs automatically on first admin visit. It performs these steps:
 
 1. Prompts for site title, tagline, and admin credentials
 2. Offers an option to include sample content
 3. Applies the seed file to the database
 4. Redirects to the admin dashboard
 
-```
-┌────────────────────────────────────────────────────────┐
-│                                                        │
-│                    ◆ EmDash                          │
-│                                                        │
-│              Welcome to your new site                  │
-│                                                        │
-│  Site Title:     [My Awesome Blog                    ] │
-│  Tagline:        [Thoughts and ideas                 ] │
-│                                                        │
-│  Admin Email:    [admin@example.com                  ] │
-│  Admin Password: [••••••••••••                       ] │
-│                                                        │
-│  ☑ Include sample content                              │
-│                                                        │
-│                   [Create Site →]                      │
-│                                                        │
-│  Template: Blog Starter                                │
-│  Creates: 2 collections, 3 pages, 1 post              │
-└────────────────────────────────────────────────────────┘
-```
-
 <Aside type="tip">
 	Check "Include sample content" when exploring a theme for the first time. The sample content
 	demonstrates how the theme expects content to be structured.
@@ -131,7 +110,7 @@ EmDash provides official starter themes, each available in local (SQLite + files
 
 ### Cloudflare Variants
 
-For deployment on Cloudflare Pages with D1 and R2, append `-cloudflare` to the template name:
+For deployment on Cloudflare Pages with D1 and R2, append `-cloudflare` to the template name, as in the following commands:
 
 ```bash
 npm create astro@latest -- --template @emdash-cms/template-blog-cloudflare
@@ -143,7 +122,7 @@ These variants include `wrangler.jsonc` for deployment configuration.
 
 ## Customizing After Install
 
-After the Setup Wizard completes, your site is a standard Astro project. Customize it like any Astro site:
+After the Setup Wizard completes, the site is a standard Astro project. Customize it like any Astro site:
 
 - Edit pages in `src/pages/`
 - Modify layouts in `src/layouts/`
@@ -151,7 +130,7 @@ After the Setup Wizard completes, your site is a standard Astro project. Customi
 - Install Astro integrations
 - Deploy anywhere Astro runs
 
-The seed file is only used during initial setup. Once applied, your schema lives in the database.
+The seed file is only used during initial setup. Once applied, the schema lives in the database.
 
 ## Next Steps
 
diff --git a/docs/src/content/docs/themes/porting-wp-themes.mdx b/docs/src/content/docs/themes/porting-wp-themes.mdx
index bb46d41e4..e67378ac0 100644
--- a/docs/src/content/docs/themes/porting-wp-themes.mdx
+++ b/docs/src/content/docs/themes/porting-wp-themes.mdx
@@ -8,10 +8,9 @@ import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
 WordPress themes can be systematically converted to EmDash. The visual design, content structure, and dynamic features all transfer using a three-phase approach.
 
 <Aside type="tip" title="AI-Assisted Porting">
-	AI coding agents excel at mechanical conversions like template porting. Feed the agent your
-	WordPress theme files along with the concept mapping tables in this guide, and it can generate a
-	solid first draft of Astro components. Review and refine the output—the agent handles the tedious
-	parts while you focus on quality.
+	Template porting is a mechanical conversion that AI coding agents handle well. Provide the agent
+	with the WordPress theme files and the concept mapping tables in this guide to generate a first
+	draft of the Astro components. Review and refine the output before shipping.
 </Aside>
 
 ## Three-Phase Approach
@@ -373,7 +372,7 @@ const { images } = Astro.props;
 </div>
 ```
 
-Register with PortableText:
+Register the component with `PortableText`:
 
 ```astro
 <PortableText value={content} components={{ gallery: Gallery }} />
diff --git a/docs/src/content/docs/themes/seed-files.mdx b/docs/src/content/docs/themes/seed-files.mdx
index 1fa65e233..2ceaa23ef 100644
--- a/docs/src/content/docs/themes/seed-files.mdx
+++ b/docs/src/content/docs/themes/seed-files.mdx
@@ -9,6 +9,8 @@ Seed files are JSON documents that bootstrap EmDash sites. They define collectio
 
 ## Root Structure
 
+A seed file has the following top-level shape:
+
 ```json
 {
 	"$schema": "https://emdashcms.com/seed.schema.json",
@@ -43,7 +45,7 @@ Seed files are JSON documents that bootstrap EmDash sites. They define collectio
 
 ## Meta
 
-Optional metadata about the seed:
+The `meta` object holds optional descriptive metadata about the seed:
 
 ```json
 {
@@ -57,7 +59,7 @@ Optional metadata about the seed:
 
 ## Settings
 
-Site-wide configuration values:
+The `settings` object holds site-wide configuration values:
 
 ```json
 {
@@ -74,7 +76,7 @@ Settings are applied to the `options` table with the `site:` prefix. The Setup W
 
 ## Collections
 
-Collection definitions create content types in the database:
+Each collection definition creates a content type in the database:
 
 ```json
 {
@@ -157,7 +159,7 @@ Collection definitions create content types in the database:
 
 ## Taxonomies
 
-Classification systems for content:
+Taxonomies are classification systems for content:
 
 ```json
 {
@@ -211,7 +213,7 @@ Classification systems for content:
 
 ## Menus
 
-Navigation menus editable from the admin:
+The `menus` array defines navigation menus that are editable from the admin:
 
 ```json
 {
@@ -292,7 +294,7 @@ Byline profiles are separate from ownership (`author_id`). Define reusable bylin
 
 ## Redirects
 
-Redirect rules to preserve legacy URLs after migration:
+The `redirects` array defines redirect rules that preserve legacy URLs after migration:
 
 ```json
 {
@@ -325,7 +327,7 @@ Redirect rules to preserve legacy URLs after migration:
 
 ## Widget Areas
 
-Configurable content regions:
+The `widgetAreas` array defines configurable content regions:
 
 ```json
 {
@@ -383,7 +385,7 @@ Configurable content regions:
 
 ## Sections
 
-Reusable content blocks that editors can insert into Portable Text fields via the `/section` slash command:
+Sections are reusable content blocks that editors insert into Portable Text fields via the `/section` slash command:
 
 ```json
 {
@@ -426,7 +428,7 @@ Sections from seed files are marked `source: "theme"` and cannot be deleted from
 
 ## Content
 
-Sample content organized by collection:
+The `content` object holds sample content entries organized by collection:
 
 ```json
 {
@@ -643,7 +645,7 @@ if (!valid) {
 warnings.forEach((w) => console.warn(w));
 ```
 
-Validation checks:
+Validation checks that:
 
 - Required fields are present
 - Slugs follow naming conventions (lowercase, underscores)
diff --git a/docs/src/content/docs/why-emdash.mdx b/docs/src/content/docs/why-emdash.mdx
index 1c45b4bb7..4438873fb 100644
--- a/docs/src/content/docs/why-emdash.mdx
+++ b/docs/src/content/docs/why-emdash.mdx
@@ -1,5 +1,5 @@
 ---
-title: Why EmDash?
+title: Why EmDash
 description: Understand what problems EmDash solves and how it compares to other approaches.
 ---
 

From 0ea13d7ac03bbeb88a4bbd64e04b0b19cf67bec3 Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sat, 16 May 2026 12:44:28 +0100
Subject: [PATCH 2/8] docs: separate 'how to use' from 'how it's built'

Adds contributing/architecture (internals) and rewrites concepts/architecture,
concepts/content-model, and concepts/admin-panel around what a reader decides
and does. Relocates table layouts, the request path, code generation, admin
internals, and the ImportSource extensibility API into the contributor doc
rather than deleting them. Trims protocol/format internals from
reference/mcp-server, migration/content-import, and guides/preview.

Also corrects contributing/translating: AI-generated translations are accepted
when a fluent speaker reviews every string and previews them in the running
admin panel; only unsupervised machine output is rejected.
---
 docs/astro.config.mjs                         |   4 +
 .../src/content/docs/concepts/admin-panel.mdx | 395 +++---------------
 .../content/docs/concepts/architecture.mdx    | 266 +++---------
 .../content/docs/concepts/content-model.mdx   | 270 +++---------
 .../docs/contributing/architecture.mdx        | 271 ++++++++++++
 .../content/docs/contributing/translating.mdx |  10 +-
 docs/src/content/docs/guides/preview.mdx      |  16 +-
 .../content/docs/migration/content-import.mdx | 116 +----
 .../src/content/docs/reference/mcp-server.mdx |   2 +-
 9 files changed, 451 insertions(+), 899 deletions(-)
 create mode 100644 docs/src/content/docs/contributing/architecture.mdx

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index ce2cc21cc..18ebe8ce1 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -147,6 +147,10 @@ export default defineConfig({
 					collapsed: true,
 					items: [
 						{ label: "Contributor Guide", slug: "contributing" },
+						{
+							label: "Architecture (internals)",
+							slug: "contributing/architecture",
+						},
 						{
 							label: "Documentation Style Guide",
 							slug: "contributing/docs-style-guide",
diff --git a/docs/src/content/docs/concepts/admin-panel.mdx b/docs/src/content/docs/concepts/admin-panel.mdx
index c45a8eb21..e8b3de08a 100644
--- a/docs/src/content/docs/concepts/admin-panel.mdx
+++ b/docs/src/content/docs/concepts/admin-panel.mdx
@@ -1,361 +1,71 @@
 ---
 title: Admin Panel
-description: The EmDash admin panel—a React SPA with TanStack Router, TanStack Query, and Kumo components.
+description: What the EmDash admin panel offers editors, administrators, and developers.
 ---
 
-import { Aside, Card, CardGrid, Steps } from "@astrojs/starlight/components";
+import { Aside, Card, CardGrid } from "@astrojs/starlight/components";
 
-The EmDash admin panel is a React single-page application embedded in your Astro site. It provides a complete content management interface for editors and administrators.
+The admin panel is the content management interface for your site. It is served at `/_emdash/admin/` inside your Astro site, and it adapts automatically to your collections, plugins, and the signed-in user's role. For how it is built, see [Architecture (internals)](/contributing/architecture/#admin-panel-internals).
 
-## Architecture overview
+## Screens
 
-The following diagram shows how the admin panel sits inside the Astro shell:
+| Path                       | Screen                          |
+| -------------------------- | ------------------------------- |
+| `/`                        | Dashboard                       |
+| `/content/:collection`     | Content list                    |
+| `/content/:collection/:id` | Content editor                  |
+| `/content/:collection/new` | New entry                       |
+| `/media`                   | Media library                   |
+| `/content-types`           | Schema builder (administrators) |
+| `/menus`                   | Navigation menus                |
+| `/widgets`                 | Widget areas                    |
+| `/taxonomies`              | Categories and tags             |
+| `/settings`                | Site settings                   |
+| `/plugins/:pluginId/*`     | Plugin pages                    |
 
-```
-┌────────────────────────────────────────────────────────────────┐
-│                    Astro Shell                                 │
-│  /_emdash/admin/[...path].astro                              │
-│                                                                │
-│  ┌──────────────────────────────────────────────────────────┐  │
-│  │                    React SPA                             │  │
-│  │                                                          │  │
-│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │  │
-│  │  │  TanStack   │  │  TanStack   │  │     Kumo        │   │  │
-│  │  │   Router    │  │   Query     │  │   Components    │   │  │
-│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │  │
-│  │                                                          │  │
-│  │  ┌────────────────────────────────────────────────────┐  │  │
-│  │  │              REST API Client                       │  │  │
-│  │  │           /_emdash/api/*                         │  │  │
-│  │  └────────────────────────────────────────────────────┘  │  │
-│  └──────────────────────────────────────────────────────────┘  │
-└────────────────────────────────────────────────────────────────┘
-```
+Navigation is generated from your collections and installed plugins, so a schema or plugin change appears in the admin without a rebuild.
 
-The admin is a single React island. Astro handles the shell and authentication; all navigation and rendering inside the admin is client-side.
+## Roles
 
-## Technology stack
+What a user sees depends on their role:
 
-| Layer       | Technology            | Purpose                                  |
-| ----------- | --------------------- | ---------------------------------------- |
-| **Routing** | TanStack Router       | Type-safe client-side routing            |
-| **Data**    | TanStack Query        | Server state, caching, mutations         |
-| **UI**      | Kumo                  | Accessible components (Base UI + Tailwind) |
-| **Tables**  | TanStack Table        | Sorting, filtering, pagination             |
-| **Forms**   | React Hook Form + Zod | Validation matching server schema          |
-| **Icons**   | Phosphor              | Consistent iconography                     |
-| **Editor**  | TipTap                | Rich text editing (Portable Text)        |
+| Role      | Can access                                              |
+| --------- | ------------------------------------------------------- |
+| Editor    | Dashboard, assigned collections, media                  |
+| Admin     | The above, plus all collections, content types, settings |
+| Developer | The above, plus CLI access and generated types          |
 
-<Aside type="note">
-	Kumo is Cloudflare's design system, built on Base UI primitives with Tailwind styling. It is
-	installed as a dependency of the admin package.
-</Aside>
-
-## Route structure
-
-The admin mounts at `/_emdash/admin/` and uses client-side routing. The following table lists the available routes:
-
-| Path                       | Screen                      |
-| -------------------------- | --------------------------- |
-| `/`                        | Dashboard                   |
-| `/content/:collection`     | Content list                |
-| `/content/:collection/:id` | Content editor              |
-| `/content/:collection/new` | New entry                   |
-| `/media`                   | Media library               |
-| `/content-types`           | Schema builder (admin only) |
-| `/menus`                   | Navigation menus            |
-| `/widgets`                 | Widget areas                |
-| `/taxonomies`              | Category/tag management     |
-| `/settings`                | Site settings               |
-| `/plugins/:pluginId/*`     | Plugin pages                |
-
-<Aside type="tip">
-	The `/content-types` route is only visible to administrators. Editors see only the content they
-	have permission to manage.
-</Aside>
-
-## Manifest-driven UI
-
-The admin does not hardcode knowledge of collections or plugins. Instead, it fetches a manifest from the server with the following request:
-
-```
-GET /_emdash/api/manifest
-```
-
-The server responds with the collections, plugins, and taxonomies the current user can access:
-
-```json
-{
-	"collections": [
-		{
-			"slug": "posts",
-			"label": "Blog Posts",
-			"labelSingular": "Post",
-			"icon": "file-text",
-			"supports": ["drafts", "revisions", "preview"],
-			"fields": [
-				{ "slug": "title", "type": "string", "required": true },
-				{ "slug": "content", "type": "portableText" }
-			]
-		}
-	],
-	"plugins": [
-		{
-			"id": "audit-log",
-			"label": "Audit Log",
-			"adminPages": [{ "path": "history", "label": "Audit History" }],
-			"widgets": [{ "id": "recent-activity", "title": "Recent Activity" }]
-		}
-	],
-	"taxonomies": [{ "name": "category", "label": "Categories", "hierarchical": true }],
-	"version": "abc123"
-}
-```
-
-The admin builds its navigation, forms, and editors entirely from this manifest. This means:
-
-- Schema changes appear immediately, with no admin rebuild needed.
-- Plugin pages and widgets integrate automatically from the manifest.
-- Zod schemas stay on the server, keeping type safety at the boundary.
-
-## Data flow
-
-A request through the admin follows these steps:
-
-<Steps>
-1. The admin SPA loads and TanStack Router initializes.
-2. TanStack Query fetches and caches the manifest's collection and plugin metadata.
-3. The sidebar navigation is generated from the manifest.
-4. The user navigates with client-side routing, with no page reload.
-5. TanStack Query fetches content from the REST APIs.
-6. Field editors are generated from the manifest's field descriptors.
-7. Changes are submitted as TanStack Query mutations with optimistic updates.
-8. The server validates against Zod schemas and returns any errors as JSON.
-</Steps>
-
-## REST API endpoints
-
-The admin communicates exclusively through REST APIs.
-
-### Content APIs
-
-The content APIs handle entry CRUD, revisions, and preview URLs:
-
-| Method   | Endpoint                                   | Purpose              |
-| -------- | ------------------------------------------ | -------------------- |
-| `GET`    | `/api/content/:collection`                 | List entries         |
-| `POST`   | `/api/content/:collection`                 | Create entry         |
-| `GET`    | `/api/content/:collection/:id`             | Get entry            |
-| `PUT`    | `/api/content/:collection/:id`             | Update entry         |
-| `DELETE` | `/api/content/:collection/:id`             | Soft delete entry    |
-| `GET`    | `/api/content/:collection/:id/revisions`   | List revisions       |
-| `POST`   | `/api/content/:collection/:id/preview-url` | Generate preview URL |
-
-### Schema APIs
-
-The schema APIs manage collections and fields:
-
-| Method   | Endpoint                                      | Purpose            |
-| -------- | --------------------------------------------- | ------------------ |
-| `GET`    | `/api/schema`                                 | Export full schema |
-| `GET`    | `/api/schema/collections`                     | List collections   |
-| `POST`   | `/api/schema/collections`                     | Create collection  |
-| `PUT`    | `/api/schema/collections/:slug`               | Update collection  |
-| `DELETE` | `/api/schema/collections/:slug`               | Delete collection  |
-| `POST`   | `/api/schema/collections/:slug/fields`        | Add field          |
-| `PUT`    | `/api/schema/collections/:slug/fields/:field` | Update field       |
-| `DELETE` | `/api/schema/collections/:slug/fields/:field` | Delete field       |
-
-### Media APIs
-
-The media APIs handle uploads and the media library:
-
-| Method   | Endpoint                 | Purpose                 |
-| -------- | ------------------------ | ----------------------- |
-| `GET`    | `/api/media`             | List media items        |
-| `POST`   | `/api/media/upload-url`  | Get signed upload URL   |
-| `POST`   | `/api/media/:id/confirm` | Confirm upload complete |
-| `DELETE` | `/api/media/:id`         | Delete media item       |
-| `GET`    | `/api/media/file/:key`   | Serve media file        |
-
-### Other APIs
-
-Settings, menus, widgets, taxonomies, and plugin state use these endpoints:
-
-| Endpoint               | Purpose                  |
-| ---------------------- | ------------------------ |
-| `/api/settings`        | Site settings (GET/POST) |
-| `/api/menus/*`         | Navigation menus         |
-| `/api/widget-areas/*`  | Widget management        |
-| `/api/taxonomies/*`    | Taxonomy terms           |
-| `/api/admin/plugins/*` | Plugin state             |
-
-## Pagination
-
-All list endpoints use cursor-based pagination. A list response includes the items and an optional cursor for the next page:
-
-```json
-{
-  "items": [...],
-  "nextCursor": "eyJpZCI6IjAxSjEyMzQ1NiJ9"
-}
-```
-
-To fetch the next page, pass the cursor back as a query parameter:
-
-```
-GET /api/content/posts?cursor=eyJpZCI6IjAxSjEyMzQ1NiJ9
-```
+Editors only see the content they have permission to manage. The schema builder at `/content-types` is administrator-only.
 
 <Aside type="note">
-	Cursor pagination provides consistent results even when content is added or removed between
-	requests.
+	The admin requires a signed-in user. Login is a separate page that
+	establishes a session; see [Authentication](/guides/authentication/).
 </Aside>
 
-## Plugin admin UI
-
-Plugins can extend the admin with pages and dashboard widgets. The integration generates a virtual module with static imports for each plugin's admin entry point:
-
-```ts title="virtual:emdash/plugin-admins (generated)"
-import * as pluginAdmin0 from "@emdash-cms/plugin-seo/admin";
-import * as pluginAdmin1 from "@emdash-cms/plugin-analytics/admin";
-
-export const pluginAdmins = {
-	seo: pluginAdmin0,
-	analytics: pluginAdmin1,
-};
-```
-
-### Plugin pages
-
-Plugin pages mount under `/_emdash/admin/plugins/:pluginId/*`. A plugin exports its pages from its admin entry point:
-
-```tsx title="@emdash-cms/plugin-seo/src/admin.tsx"
-export const pages = [
-	{
-		path: "settings",
-		component: SEOSettingsPage,
-		label: "SEO Settings",
-	},
-];
-```
-
-The example above renders at `/_emdash/admin/plugins/seo/settings`.
-
-### Dashboard widgets
-
-Plugins can add widgets to the dashboard by exporting a `widgets` array:
-
-```tsx
-export const widgets = [
-	{
-		id: "seo-overview",
-		component: SEOWidget,
-		title: "SEO Overview",
-		size: "half", // "full" | "half" | "third"
-	},
-];
-```
-
-<Aside type="caution">
-	Plugins can only mount pages under their own namespace (`/plugins/:pluginId/*`). They cannot
-	override core admin routes.
-</Aside>
-
-## Authentication
-
-The admin shell route enforces authentication via Astro middleware. The following simplified middleware redirects unauthenticated requests to the login page:
-
-```ts
-export async function onRequest({ request, locals }, next) {
-	const session = await getSession(request);
-
-	if (request.url.includes("/_emdash/admin")) {
-		if (!session?.user) {
-			return redirect("/_emdash/admin/login");
-		}
-		locals.user = session.user;
-	}
-
-	return next();
-}
-```
-
-The admin SPA itself does not handle login. Login is an Astro page that sets a session cookie.
-
-## Role-based access
-
-Different roles see different parts of the admin:
-
-| Role          | Visible Sections                           |
-| ------------- | ------------------------------------------ |
-| **Editor**    | Dashboard, assigned collections, media     |
-| **Admin**     | + Content Types, all collections, settings |
-| **Developer** | + CLI access, generated types              |
-
-The manifest endpoint filters collections and features based on the requesting user's role.
-
 ## Content editor
 
-The content editor generates forms dynamically based on field definitions. The following simplified component renders one widget per field:
-
-```tsx
-function ContentEditor({ collection, fields }) {
-	return (
-		<form>
-			{fields.map((field) => (
-				<FieldWidget
-					key={field.slug}
-					type={field.type}
-					label={field.label}
-					required={field.required}
-					options={field.options}
-				/>
-			))}
-		</form>
-	);
-}
-```
-
-Each field type has a corresponding widget, as listed below:
-
-| Field Type     | Widget           |
-| -------------- | ---------------- |
-| `string`       | Text input       |
-| `text`         | Textarea         |
-| `number`       | Number input     |
-| `boolean`      | Toggle switch    |
-| `datetime`     | Date/time picker |
-| `select`       | Dropdown         |
-| `multiSelect`  | Multi-select     |
-| `portableText` | TipTap editor    |
-| `image`        | Media picker     |
-| `reference`    | Entry picker     |
-
-## Rich text editor
-
-Portable Text fields use TipTap (ProseMirror) for editing. Content is converted between formats at the load and save boundaries:
-
-```
-User types → TipTap (ProseMirror JSON) → Save → Portable Text (DB)
-Load → Portable Text (DB) → TipTap (ProseMirror JSON) → Display
-```
-
-Conversion happens via `portableTextToProsemirror()` and `prosemirrorToPortableText()`.
+The content editor builds a form from a collection's fields. Each field type uses a matching input:
 
-The editor supports these blocks:
+| Field type     | Editor            |
+| -------------- | ----------------- |
+| `string`       | Text input        |
+| `text`         | Textarea          |
+| `number`       | Number input      |
+| `boolean`      | Toggle            |
+| `datetime`     | Date/time picker  |
+| `select`       | Dropdown          |
+| `multiSelect`  | Multi-select      |
+| `portableText` | Rich text editor  |
+| `image`        | Media picker      |
+| `reference`    | Entry picker      |
 
-- Paragraphs, headings (H1-H6)
-- Bullet and numbered lists
-- Blockquotes, code blocks
-- Images (from media library)
-- Links
+Rich text fields edit as formatted content — headings, lists, quotes, code, links, and images from the media library. Content from plugins or imports that the editor does not recognise is preserved untouched.
 
-Unknown blocks from plugins or imports are preserved as read-only placeholders.
+Lists are paginated and stay consistent even when content changes between pages.
 
 ## Media library
 
-The media library provides:
+The media library supports:
 
 - Grid and list views
 - Search and filter by type and date
@@ -363,16 +73,11 @@ The media library provides:
 - Image preview with metadata
 - Bulk selection and delete
 
-Uploads use signed URLs for direct client-to-storage upload, following these steps:
+Uploads go directly from the browser to your storage backend, so large files are not limited by request size.
 
-<Steps>
-1. The client requests an upload URL with `POST /api/media/upload-url`.
-2. The client uploads the file directly to the signed URL (R2 or S3).
-3. The client confirms the upload with `POST /api/media/:id/confirm`.
-4. The server extracts metadata such as dimensions and MIME type.
-</Steps>
+## Plugin pages and widgets
 
-This approach bypasses Workers body size limits and provides accurate upload progress.
+A plugin can add pages and dashboard widgets to the admin. Plugin pages appear under `/_emdash/admin/plugins/:pluginId/`, and a plugin can only mount under its own namespace — it cannot override core admin screens. See [installing plugins](/plugins/installing/).
 
 ## Next steps
 
@@ -380,10 +85,10 @@ This approach bypasses Workers body size limits and provides accurate upload pro
 	<Card title="Getting Started" icon="rocket">
 		[Set up your first EmDash site](/getting-started/).
 	</Card>
-	<Card title="Plugin Development" icon="puzzle">
-		[Build admin UI extensions](/plugins/creating-native-plugins/react-admin/).
+	<Card title="REST API" icon="puzzle">
+		The admin uses the [REST API](/reference/rest-api/); you can call it too.
 	</Card>
 	<Card title="Architecture" icon="open-book">
-		Review the full [system architecture](/concepts/architecture/).
+		Review the [content model](/concepts/content-model/).
 	</Card>
 </CardGrid>
diff --git a/docs/src/content/docs/concepts/architecture.mdx b/docs/src/content/docs/concepts/architecture.mdx
index 612d1c35c..1af742f17 100644
--- a/docs/src/content/docs/concepts/architecture.mdx
+++ b/docs/src/content/docs/concepts/architecture.mdx
@@ -1,169 +1,76 @@
 ---
 title: Architecture
-description: How EmDash works under the hood—database-first schema, Live Collections, plugin system, and admin panel.
+description: The mental model for building with EmDash — an Astro integration with database-first content and live queries.
 ---
 
-import { Aside, Card, CardGrid, Steps } from "@astrojs/starlight/components";
+import { Aside, Card, CardGrid } from "@astrojs/starlight/components";
 
-EmDash integrates deeply with Astro to provide a complete CMS experience. This page explains the key architectural decisions and how the pieces fit together.
+EmDash is an Astro integration. You add it to `astro.config.mjs`, choose a database and storage, and define content collections. This page covers the model you need to build a site. For internals (table layouts, the request path, code generation), see [Architecture (internals)](/contributing/architecture/).
 
-## High-level overview
+## What EmDash adds to your site
 
-The following diagram shows how EmDash sits inside an Astro site:
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│                         Your Astro Site                          │
-│                                                                  │
-│  ┌────────────────────────────────────────────────────────────┐  │
-│  │                   EmDash Integration                     │  │
-│  │                                                            │  │
-│  │  ┌──────────────┐   ┌──────────────┐   ┌───────────────┐   │  │
-│  │  │   Content    │   │    Admin     │   │    Plugins    │   │  │
-│  │  │    APIs      │   │    Panel     │   │               │   │  │
-│  │  └──────────────┘   └──────────────┘   └───────────────┘   │  │
-│  │                                                            │  │
-│  │  ┌──────────────────────────────────────────────────────┐  │  │
-│  │  │                    Data Layer                        │  │  │
-│  │  │      Database (D1/SQLite)     +  Storage (R2/S3)     │  │  │
-│  │  └──────────────────────────────────────────────────────┘  │  │
-│  └────────────────────────────────────────────────────────────┘  │
-│                                                                  │
-│  ┌────────────────────────────────────────────────────────────┐  │
-│  │                    Astro Framework                         │  │
-│  │         Live Collections · Middleware · Sessions           │  │
-│  └────────────────────────────────────────────────────────────┘  │
-└──────────────────────────────────────────────────────────────────┘
 ```
-
-EmDash runs as an Astro integration. It injects routes for the admin panel and REST APIs, provides a content loader for Live Collections, and manages database migrations and storage connections.
-
-## Database-first schema
-
-EmDash stores schema definitions in the database itself rather than in code. Two system tables track the content structure:
-
-- `_emdash_collections` — Collection metadata (slug, label, features)
-- `_emdash_fields` — Field definitions for each collection
-
-When you create a products collection with title and price fields through the admin UI, EmDash performs two steps:
-
-1. Inserts records into `_emdash_collections` and `_emdash_fields`.
-2. Runs `ALTER TABLE` to create `ec_products` with the appropriate columns.
-
-This design enables:
-
-- Runtime schema modification: create and edit content types without code changes or rebuilds.
-- Setup without a developer: content editors can design their data model through the UI.
-- Real SQL columns, with proper indexing, foreign keys, and query optimization.
-
-<Aside type="tip">
-	Run `npx emdash types` to generate TypeScript types from the live schema. This gives you type
-	safety for dynamically-defined collections.
-</Aside>
-
-## Per-collection tables
-
-Each collection gets its own SQLite table with an `ec_` prefix. The following table is created when a posts collection is added:
-
-```sql
-CREATE TABLE ec_posts (
-  -- System columns (always present)
-  id TEXT PRIMARY KEY,
-  slug TEXT UNIQUE,
-  status TEXT DEFAULT 'draft',  -- draft, published, scheduled
-  author_id TEXT,
-  created_at TEXT DEFAULT (datetime('now')),
-  updated_at TEXT DEFAULT (datetime('now')),
-  published_at TEXT,
-  deleted_at TEXT,              -- Soft delete
-  version INTEGER DEFAULT 1,    -- Optimistic locking
-
-  -- Content columns (from your field definitions)
-  title TEXT NOT NULL,
-  content JSON,                 -- Portable Text
-  excerpt TEXT
-);
+┌──────────────────────────────────────────────┐
+│                Your Astro site                │
+│                                               │
+│   Pages and components you write              │
+│        │                                      │
+│        │  getEmDashCollection() / getEmDashEntry()
+│        ▼                                      │
+│   ┌───────────────┐      ┌────────────────┐   │
+│   │   Content     │      │  Admin panel   │   │
+│   │  (your data)  │◄────►│ /_emdash/admin │   │
+│   └───────────────┘      └────────────────┘   │
+│        │                                      │
+│   Database (SQLite / D1 / libSQL)             │
+│   Media storage (local / R2 / S3)             │
+└──────────────────────────────────────────────┘
 ```
 
-Per-collection tables, rather than a single content table with a JSON column, give EmDash:
+You write pages and components as normal. EmDash provides the content, an admin panel for editing it, and the database and storage behind it. Editors work in the admin panel; your pages read the same content through query functions.
 
-- Real SQL columns for proper indexing and queries
-- Working foreign keys
-- A self-documenting schema in the database
-- No JSON parsing overhead for field access
-- Schema that database tools can inspect directly
+## Database-first content
 
-## Live Collections integration
+Your content model lives in the database, not in code. When someone adds a `products` collection with `title` and `price` in the admin panel, EmDash creates a real `products` table with real `title` and `price` columns.
 
-EmDash uses Astro's [Live Collections](https://docs.astro.build/en/reference/experimental-flags/live-content-collections/) to serve content at runtime. Content changes are available immediately, without static rebuilds.
+This is the decision that shapes everything else:
 
-The `emdashLoader()` function implements Astro's `LiveLoader` interface:
-
-```ts title="src/live.config.ts"
-import { defineLiveCollection } from "astro:content";
-import { emdashLoader } from "emdash/runtime";
+<CardGrid>
+	<Card title="Change the model at runtime" icon="pencil">
+		Add or edit collections and fields in the admin panel. No code change, no
+		rebuild, no migration to write.
+	</Card>
+	<Card title="Set up without a developer" icon="seti:plan">
+		A non-developer can design the content model through the admin UI.
+	</Card>
+	<Card title="Real SQL underneath" icon="seti:db">
+		Each field is a real column with proper indexing and queries — useful if
+		you ever query the database directly.
+	</Card>
+	<Card title="Portable" icon="right-arrow">
+		Export the schema as a JSON seed file for version control, and apply it in
+		another environment.
+	</Card>
+</CardGrid>
 
-export const collections = {
-	_emdash: defineLiveCollection({ loader: emdashLoader() }),
-};
-```
+The trade-off you accept is that the source of truth for your schema is the database. Use [type generation](/concepts/content-model/#typescript-types) and [seed files](/themes/seed-files/) to keep that manageable in a code workflow.
 
-<Aside type="note">
-	A single `_emdash` Astro collection wraps all content types. The loader filters by type
-	internally when you call `getEmDashCollection("posts")`.
-</Aside>
+## Content is live
 
-Query content using the provided wrapper functions. The following example fetches published posts, drafts, and a single entry:
+EmDash serves content through Astro's Live Collections, so changes an editor makes are visible immediately without a static rebuild. You read content with two functions:
 
-```ts
+```ts title="src/pages/blog.astro"
 import { getEmDashCollection, getEmDashEntry } from "emdash";
 
-// Get all published posts
 const { entries: posts } = await getEmDashCollection("posts");
-
-// Get drafts
-const { entries: drafts } = await getEmDashCollection("posts", {
-	status: "draft",
-});
-
-// Get a single entry by slug
 const { entry: post } = await getEmDashEntry("posts", "my-post-slug");
 ```
 
-## Route injection
+See [Querying content](/guides/querying-content/) for filtering, pagination, and drafts.
 
-The EmDash integration uses Astro's `injectRoute` API to add admin and API routes:
+## What you configure
 
-| Path Pattern                          | Purpose                               |
-| ------------------------------------- | ------------------------------------- |
-| `/_emdash/admin/[...path]`          | Admin panel SPA                       |
-| `/_emdash/api/manifest`             | Admin manifest (collections, plugins) |
-| `/_emdash/api/content/[collection]` | CRUD for content entries              |
-| `/_emdash/api/media/*`              | Media library operations              |
-| `/_emdash/api/schema/*`             | Schema management                     |
-| `/_emdash/api/settings`             | Site settings                         |
-| `/_emdash/api/menus/*`              | Navigation menus                      |
-| `/_emdash/api/taxonomies/*`         | Categories, tags, custom taxonomies   |
-
-Routes are injected from the `emdash` package. Nothing is copied into your project.
-
-## Data layer
-
-EmDash uses [Kysely](https://kysely.dev) for type-safe SQL queries across all supported databases:
-
-<CardGrid>
-  <Card title="SQLite" icon="laptop">
-    Local development with `sqlite({ url: "file:./data.db" })`
-  </Card>
-  <Card title="D1" icon="cloudflare">
-    Cloudflare's serverless SQL with `d1({ binding: "DB" })`
-  </Card>
-  <Card title="libSQL" icon="external">
-    Remote SQLite with `libsql({ url: "...", authToken: "..." })`
-  </Card>
-</CardGrid>
-
-Database configuration is passed to the integration in `astro.config.mjs`:
+You pass a database and a storage backend to the integration. Everything else has a default.
 
 ```ts title="astro.config.mjs"
 import { defineConfig } from "astro/config";
@@ -175,93 +82,34 @@ export default defineConfig({
 	integrations: [
 		emdash({
 			database: sqlite({ url: "file:./data.db" }),
-			storage: local({
-				directory: "./uploads",
-				baseUrl: "/_emdash/api/media/file",
-			}),
+			storage: local({ directory: "./uploads" }),
 		}),
 	],
 });
 ```
 
-## Storage abstraction
-
-Media files are stored separately from the database. EmDash supports:
-
-- Local filesystem, for development and simple deployments
-- Cloudflare R2, S3-compatible object storage on the edge
-- Any other S3-compatible object storage
-
-Uploads use signed URLs for direct client-to-storage uploads, bypassing Workers body size limits.
-
-## Plugin architecture
-
-Plugins extend EmDash through a hook system:
-
-- Content hooks: `content:beforeSave`, `content:afterSave`, `content:beforeDelete`, `content:afterDelete`
-- Media hooks: `media:beforeUpload`, `media:afterUpload`
-- Isolated storage: each plugin gets namespaced KV access
-- Admin UI extensions: dashboard widgets, settings pages, custom field editors
-
-Plugins can run in two modes:
-
-1. Native plugins have full access to the host environment, and are intended for first-party plugins.
-2. Sandboxed plugins run in V8 isolates with capability-based permissions, for third-party plugins on Cloudflare.
-
-The following example registers a plugin in `astro.config.mjs`:
-
-```ts title="astro.config.mjs"
-import { seoPlugin } from "@emdash-cms/plugin-seo";
-
-emdash({
-	plugins: [seoPlugin({ maxTitleLength: 60 })],
-});
-```
-
-## Request flow
-
-A content request from a page follows these steps:
-
-<Steps>
-1. Astro receives the request and your page component runs.
-2. `getEmDashCollection()` calls Astro's `getLiveCollection()`.
-3. `emdashLoader` queries the appropriate `ec_*` table via Kysely.
-4. Entries are mapped to Astro's entry format with `id`, `slug`, and `data`.
-5. Your component receives the content and renders HTML.
-</Steps>
-
-An admin request follows these steps:
-
-<Steps>
-1. Middleware validates the session token.
-2. The API route handles the request, performing CRUD operations via repositories.
-3. Hooks fire, such as `beforeCreate` and `afterUpdate`.
-4. Kysely executes the SQL to update the database.
-5. The route returns a JSON response to the admin SPA.
-</Steps>
+- **Database**: SQLite for local development, Cloudflare D1, or libSQL. See [Database options](/deployment/database/).
+- **Storage**: the local filesystem, Cloudflare R2, or any S3-compatible storage for media. See [Storage options](/deployment/storage/).
 
-## Virtual modules
+## Extending with plugins
 
-EmDash generates virtual modules at build time to configure the runtime:
+Plugins react to content and media lifecycle events and can add admin pages, dashboard widgets, and settings. There are two formats:
 
-| Module                           | Purpose                             |
-| -------------------------------- | ----------------------------------- |
-| `virtual:emdash/config`        | Database and storage configuration  |
-| `virtual:emdash/dialect`       | Database dialect factory            |
-| `virtual:emdash/plugin-admins` | Static imports for plugin admin UIs |
+- **Native plugins** run in the host environment with full access. Best for first-party and trusted plugins.
+- **Sandboxed plugins** run in an isolated runtime with capability-based permissions. Best for third-party plugins.
 
-This approach ensures bundlers can properly resolve and tree-shake plugin code.
+See the [plugin overview](/plugins/overview/) to choose and install plugins, or [create a plugin](/plugins/creating-plugins/choosing-a-format/).
 
 ## Next steps
 
 <CardGrid>
 	<Card title="Collections" icon="document">
-		Learn about [content collections and field types](/concepts/collections/).
+		Define [content collections and field types](/concepts/collections/).
 	</Card>
 	<Card title="Content Model" icon="open-book">
 		Understand the [database-first content model](/concepts/content-model/).
 	</Card>
 	<Card title="Admin Panel" icon="setting">
-		Explore the [admin panel architecture](/concepts/admin-panel/).
+		See what the [admin panel](/concepts/admin-panel/) offers editors and admins.
 	</Card>
 </CardGrid>
diff --git a/docs/src/content/docs/concepts/content-model.mdx b/docs/src/content/docs/concepts/content-model.mdx
index 156faf4fe..6d9478c83 100644
--- a/docs/src/content/docs/concepts/content-model.mdx
+++ b/docs/src/content/docs/concepts/content-model.mdx
@@ -1,15 +1,15 @@
 ---
 title: Content Model
-description: EmDash's database-first content model—how schema is stored, modified at runtime, and queried.
+description: How EmDash's database-first content model works for you — runtime schema changes, type generation, and seed files.
 ---
 
 import { Aside, Card, CardGrid, Steps } from "@astrojs/starlight/components";
 
-EmDash uses a **database-first content model** where schema definitions live in the database, not in code. This is a fundamental design choice that enables runtime schema modification and non-developer-friendly setup.
+EmDash is **database-first**: your content model lives in the database, not in a code file. This page covers what that means for how you set up and evolve a site. For the table layouts and validation internals, see [Architecture (internals)](/contributing/architecture/#database-first-schema).
 
 ## Schema as data
 
-Many CMSs define schema in code, where a collection's fields are declared as a code object:
+In many CMSs you declare a collection's fields in code:
 
 ```ts
 const posts = collection({
@@ -20,258 +20,105 @@ const posts = collection({
 });
 ```
 
-EmDash stores this same information in database tables. The following statements define an equivalent posts collection:
+EmDash stores that same structure in the database instead. You define collections and fields in the admin panel or with the CLI, and EmDash turns them into real tables and columns. The structure is the same; what changes is where it lives and how you modify it.
 
-```sql
-INSERT INTO _emdash_collections (slug, label)
-VALUES ('posts', 'Blog Posts');
-
-INSERT INTO _emdash_fields (collection_id, slug, type, required)
-VALUES
-  ('coll_abc', 'title', 'string', true),
-  ('coll_abc', 'content', 'portableText', false);
-```
-
-Both approaches define the same content structure. The difference is where that structure lives and how it can be modified.
-
-## Why database-first
+## Why this matters
 
 <CardGrid>
-	<Card title="Runtime Modification" icon="pencil">
-		Create and edit content types without code changes or rebuilds. Non-developers can design their
-		data model through the admin UI.
+	<Card title="Change the model at runtime" icon="pencil">
+		Add, rename, or remove collections and fields whenever you need to. No
+		code change, no rebuild, no migration to write.
 	</Card>
-	<Card title="Real SQL Columns" icon="seti:db">
-		Each field gets a real column, with proper indexing, foreign keys, and query optimization.
+	<Card title="Set up without a developer" icon="seti:plan">
+		A content editor can design the whole data model through the admin UI.
 	</Card>
-	<Card title="Self-Documenting" icon="document">
-		Database tools can inspect schema directly. No need to parse code to understand the data model.
+	<Card title="Real SQL columns" icon="seti:db">
+		Each field is a real column with proper indexing and queries.
 	</Card>
-	<Card title="Migration Path" icon="right-arrow">
-		Export schema as JSON for version control. Import schema in new environments.
+	<Card title="Portable" icon="right-arrow">
+		Export the schema as a JSON seed file for version control, and apply it in
+		another environment.
 	</Card>
 </CardGrid>
 
-## Schema tables
+## System fields
 
-Two system tables define your content structure.
+Every entry has a set of fields EmDash manages for you, in addition to the fields you define. You do not declare these; they are always present:
 
-### Collections table
+| Field          | Purpose                                  |
+| -------------- | ---------------------------------------- |
+| `id`           | Stable unique identifier                 |
+| `slug`         | URL-safe identifier, unique per locale   |
+| `status`       | `draft`, `published`, or `scheduled`     |
+| `author_id`    | The user who created the entry           |
+| `created_at` / `updated_at` / `published_at` | Timestamps             |
+| `deleted_at`   | Set on soft delete; the row is kept      |
+| `version`      | Increments on each save                  |
 
-The `_emdash_collections` table holds one row per collection:
+A deleted entry is soft-deleted: the row stays, with `deleted_at` set, so it can be restored.
 
-```sql
-CREATE TABLE _emdash_collections (
-  id TEXT PRIMARY KEY,
-  slug TEXT UNIQUE NOT NULL,        -- "posts", "products"
-  label TEXT NOT NULL,              -- "Blog Posts"
-  label_singular TEXT,              -- "Post"
-  description TEXT,
-  icon TEXT,                        -- Lucide icon name
-  supports JSON,                    -- ["drafts", "revisions", "preview"]
-  source TEXT,                      -- How it was created
-  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
-  updated_at TEXT
-);
-```
-
-The `source` field tracks how the collection was created, with one of these values:
-
-| Source             | Description                        |
-| ------------------ | ---------------------------------- |
-| `manual`           | Created via admin UI               |
-| `template:blog`    | Created by a template's seed file  |
-| `import:wordpress` | Imported from WordPress            |
-| `discovered`       | Auto-discovered from existing data |
-
-### Fields table
-
-The `_emdash_fields` table holds one row per field, linked to its collection:
-
-```sql
-CREATE TABLE _emdash_fields (
-  id TEXT PRIMARY KEY,
-  collection_id TEXT REFERENCES _emdash_collections(id),
-  slug TEXT NOT NULL,               -- Column name: "title", "price"
-  label TEXT NOT NULL,              -- Display label
-  type TEXT NOT NULL,               -- Field type
-  column_type TEXT NOT NULL,        -- SQLite type: TEXT, REAL, INTEGER, JSON
-  required INTEGER DEFAULT 0,
-  unique_field INTEGER DEFAULT 0,
-  default_value TEXT,               -- JSON-encoded default
-  validation JSON,                  -- Validation rules
-  widget TEXT,                      -- Custom widget identifier
-  options JSON,                     -- Widget options
-  sort_order INTEGER,
-  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
-  UNIQUE(collection_id, slug)
-);
-```
+## Changing the model at runtime
 
-## Content tables
-
-Each collection gets its own table with the `ec_` prefix. The following table is created for a products collection with title and price fields:
-
-```sql
-CREATE TABLE ec_products (
-  -- System columns (always present)
-  id TEXT PRIMARY KEY,
-  slug TEXT UNIQUE,
-  status TEXT DEFAULT 'draft',
-  author_id TEXT,
-  created_at TEXT DEFAULT (datetime('now')),
-  updated_at TEXT DEFAULT (datetime('now')),
-  published_at TEXT,
-  deleted_at TEXT,                  -- Soft delete
-  version INTEGER DEFAULT 1,        -- Optimistic locking
-
-  -- Content columns (from field definitions)
-  title TEXT NOT NULL,
-  price REAL
-);
-```
+You can add, rename, or remove a field on a live collection at any time, through the admin panel or the CLI. Existing content is preserved. Changing a field's type is also supported; EmDash handles the underlying data move for you.
 
 <Aside type="tip">
-	System columns are automatically added to every content table. You do not define them as
-	fields; they are always present.
+	Adding a field is always safe. Removing one drops its data. Rename rather
+	than remove-and-recreate when you want to keep existing values.
 </Aside>
 
-## Runtime schema changes
-
-When you add a field through the admin UI, EmDash performs these steps:
-
-<Steps>
-1. Inserts a record into `_emdash_fields`.
-2. Runs `ALTER TABLE ec_collection ADD COLUMN column_name TYPE`.
-3. Regenerates the Zod schema for validation.
-</Steps>
-
-SQLite supports these `ALTER TABLE` operations at runtime:
-
-| Operation          | Supported                   |
-| ------------------ | --------------------------- |
-| Add column         | Yes                         |
-| Rename column      | Yes                         |
-| Drop column        | Yes (SQLite 3.35+)          |
-| Change column type | No (requires table rebuild) |
+## TypeScript types
 
-For type changes, EmDash handles the table rebuild transparently: create a new table, copy data, drop the old table, then rename the new table.
-
-## Schema and content separation
-
-EmDash maintains a clear separation between schema, content, media, and settings:
-
-| Concern      | Location                 | Tables                                      |
-| ------------ | ------------------------ | ------------------------------------------- |
-| **Schema**   | System tables            | `_emdash_collections`, `_emdash_fields` |
-| **Content**  | Per-collection tables    | `ec_posts`, `ec_products`, etc.             |
-| **Media**    | Separate table + storage | `media` table + R2/S3                       |
-| **Settings** | Options table            | `options` with `site:` prefix               |
-
-This separation means:
-
-- Schema can be exported without content
-- Content can be migrated between schemas
-- System tables are never cluttered with user data
-
-## Validation at runtime
-
-EmDash builds Zod schemas from database field definitions at startup. The following simplified function shows the approach:
-
-```ts
-function buildSchema(fields: Field[]): ZodSchema {
-	const shape: Record<string, ZodType> = {};
-
-	for (const field of fields) {
-		let zodType = fieldTypeToZod(field.type);
-
-		if (field.required) {
-			zodType = zodType.required();
-		}
-
-		if (field.validation?.min !== undefined) {
-			zodType = zodType.min(field.validation.min);
-		}
-
-		shape[field.slug] = zodType;
-	}
-
-	return z.object(shape);
-}
-```
-
-Content is validated against these runtime schemas on every create and update operation.
-
-## TypeScript integration
-
-Generate TypeScript types from your database schema with the following command:
+Type generation is optional but recommended. Generate types from the live schema:
 
 ```bash
 npx emdash types
 ```
 
-This generates a `.emdash/types.ts` file with an interface per collection and typed query overloads:
+This writes `.emdash/types.ts` with an interface per collection and typed query overloads, so `getEmDashCollection("posts")` returns fully typed entries:
 
 ```ts title=".emdash/types.ts (generated)"
 export interface Post {
 	title: string;
 	content: PortableTextBlock[];
 	excerpt?: string;
-	featuredImage?: string;
-}
-
-export interface Product {
-	title: string;
-	price: number;
-	quantity: number;
 }
 
-// Typed overloads for query functions
 declare module "emdash" {
 	export function getEmDashCollection(
 		type: "posts",
 	): Promise<{ entries: ContentEntry<Post>[]; error?: Error }>;
-
-	export function getEmDashEntry(
-		type: "products",
-		id: string,
-	): Promise<{ entry: ContentEntry<Product> | null; error?: Error; isPreview: boolean }>;
 }
 ```
 
-<Aside type="note">
-	Type generation is optional but recommended. It gives you autocomplete and type checking for your
-	dynamically-defined collections.
-</Aside>
+Re-run the command after changing the schema to keep types in sync.
 
 ## Developer and non-developer workflows
 
-Developers can use the CLI to generate types and export the schema:
+Both workflows modify the same content model.
 
-```bash
-# Fetch schema, generate types
-npx emdash types
-
-# Export schema as JSON
-npx emdash export-seed > seed.json
-```
-
-Non-developers use the admin UI instead, following these steps:
+A non-developer uses the admin panel:
 
 <Steps>
+
 1. Open **Content Types** in the admin panel.
 2. Click **Add Collection**.
-3. Define fields through the visual builder.
+3. Define fields with the visual builder.
 4. Start creating content.
+
 </Steps>
 
-Both approaches modify the same underlying database tables.
+A developer can use the CLI to generate types and move the schema between environments:
+
+```bash
+npx emdash types               # generate TypeScript types
+npx emdash export-seed > seed.json   # export the schema as a seed file
+```
 
 ## Seed files
 
-Templates and exports use JSON seed files for portable schema definitions. A seed file describes collections, taxonomies, and menus:
+A seed file is a JSON description of collections, taxonomies, and menus. Templates ship one, and you can export your own for version control or to set up another environment.
 
-```json
+```json title=".emdash/seed.json"
 {
 	"version": "1",
 	"collections": [
@@ -282,8 +129,7 @@ Templates and exports use JSON seed files for portable schema definitions. A see
 			"supports": ["drafts", "revisions", "preview"],
 			"fields": [
 				{ "slug": "title", "type": "string", "required": true },
-				{ "slug": "content", "type": "portableText" },
-				{ "slug": "featuredImage", "type": "image" }
+				{ "slug": "content", "type": "portableText" }
 			]
 		}
 	],
@@ -292,34 +138,26 @@ Templates and exports use JSON seed files for portable schema definitions. A see
 }
 ```
 
-Apply seed files programmatically with `validateSeed` and `applySeed`:
+Applying a seed is idempotent, so it is safe to re-run:
 
 ```ts
 import { applySeed, validateSeed } from "emdash/seed";
 import seedData from "./.emdash/seed.json";
 
-// Validate first
 const { valid, errors } = validateSeed(seedData);
-
-// Apply (idempotent - safe to re-run)
-await applySeed(db, seedData, {
-	includeContent: true,
-	onConflict: "skip", // 'skip' | 'update' | 'error'
-});
+await applySeed(db, seedData, { includeContent: true, onConflict: "skip" });
 ```
 
-## Summary
-
-EmDash is database-first with optional type generation. Schema lives in the database, can be modified at runtime through the admin UI or CLI, and types are generated from the live schema when you want type-safe development.
+See [Seed file format](/themes/seed-files/) for the full schema.
 
 ## Next steps
 
 <CardGrid>
 	<Card title="Collections" icon="document">
-		Learn about [field types and validation](/concepts/collections/).
+		Define [field types and validation](/concepts/collections/).
 	</Card>
 	<Card title="Admin Panel" icon="setting">
-		Explore the [admin architecture](/concepts/admin-panel/).
+		See the [admin panel](/concepts/admin-panel/).
 	</Card>
 	<Card title="Seeding" icon="open-book">
 		Set up sites with [seed files](/themes/seed-files/).
diff --git a/docs/src/content/docs/contributing/architecture.mdx b/docs/src/content/docs/contributing/architecture.mdx
new file mode 100644
index 000000000..93b37f45c
--- /dev/null
+++ b/docs/src/content/docs/contributing/architecture.mdx
@@ -0,0 +1,271 @@
+---
+title: Architecture (internals)
+description: How EmDash works under the hood, for people contributing to EmDash itself.
+---
+
+import { Aside, Steps } from "@astrojs/starlight/components";
+
+This page is for people working **on** EmDash, not building a site with it. It documents internal mechanics — table layouts, the Astro integration, the request path, code generation. None of it is needed to use EmDash. If you are building a site, read [Architecture](/concepts/architecture/) and the [Content Model](/concepts/content-model/) instead.
+
+## The Astro integration
+
+EmDash runs as an Astro integration from the `emdash` package. At build time it:
+
+- Injects the admin SPA and REST API routes with Astro's `injectRoute` API. Nothing is copied into the user's project. The injected paths are:
+
+  | Path pattern                        | Purpose                               |
+  | ----------------------------------- | ------------------------------------- |
+  | `/_emdash/admin/[...path]`          | Admin panel SPA                       |
+  | `/_emdash/api/manifest`             | Admin manifest (collections, plugins) |
+  | `/_emdash/api/content/[collection]` | Content entry CRUD                    |
+  | `/_emdash/api/media/*`              | Media library operations              |
+  | `/_emdash/api/schema/*`             | Schema management                     |
+  | `/_emdash/api/settings`             | Site settings                         |
+  | `/_emdash/api/menus/*`              | Navigation menus                      |
+  | `/_emdash/api/taxonomies/*`         | Categories, tags, custom taxonomies   |
+
+- Generates virtual modules so the bundler can resolve and tree-shake configuration and plugin code:
+
+  | Module                         | Purpose                             |
+  | ------------------------------ | ----------------------------------- |
+  | `virtual:emdash/config`        | Database and storage configuration  |
+  | `virtual:emdash/dialect`       | Database dialect factory            |
+  | `virtual:emdash/plugin-admins` | Static imports for plugin admin UIs |
+
+- Provides the Live Collections loader, manages migrations, and opens the storage connection.
+
+## Database-first schema
+
+Schema definitions live in the database, not in code. Two system tables track structure.
+
+`_emdash_collections` holds one row per collection:
+
+```sql
+CREATE TABLE _emdash_collections (
+  id TEXT PRIMARY KEY,
+  slug TEXT UNIQUE NOT NULL,        -- "posts", "products"
+  label TEXT NOT NULL,              -- "Blog Posts"
+  label_singular TEXT,              -- "Post"
+  description TEXT,
+  icon TEXT,
+  supports JSON,                    -- ["drafts", "revisions", "preview"]
+  source TEXT,                      -- how it was created
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT
+);
+```
+
+The `source` column records provenance: `manual` (admin UI), `template:<name>` (seed file), `import:wordpress` (importer), or `discovered` (auto-detected from existing tables).
+
+`_emdash_fields` holds one row per field, linked to its collection:
+
+```sql
+CREATE TABLE _emdash_fields (
+  id TEXT PRIMARY KEY,
+  collection_id TEXT REFERENCES _emdash_collections(id),
+  slug TEXT NOT NULL,               -- column name
+  label TEXT NOT NULL,
+  type TEXT NOT NULL,               -- field type
+  column_type TEXT NOT NULL,        -- TEXT, REAL, INTEGER, JSON
+  required INTEGER DEFAULT 0,
+  unique_field INTEGER DEFAULT 0,
+  default_value TEXT,
+  validation JSON,
+  widget TEXT,
+  options JSON,
+  sort_order INTEGER,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(collection_id, slug)
+);
+```
+
+### Per-collection content tables
+
+Each collection gets its own table, prefixed `ec_`. A `products` collection with `title` and `price` fields produces:
+
+```sql
+CREATE TABLE ec_products (
+  -- System columns, always present
+  id TEXT PRIMARY KEY,
+  slug TEXT UNIQUE,
+  status TEXT DEFAULT 'draft',
+  author_id TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  published_at TEXT,
+  deleted_at TEXT,                  -- soft delete
+  version INTEGER DEFAULT 1,        -- optimistic locking
+
+  -- Content columns, from field definitions
+  title TEXT NOT NULL,
+  price REAL
+);
+```
+
+Real columns (rather than one table with a JSON blob) give proper indexing, working foreign keys, a schema database tools can inspect, and no per-field JSON parsing.
+
+The concerns stay separated:
+
+| Concern  | Location                 | Tables                                  |
+| -------- | ------------------------ | --------------------------------------- |
+| Schema   | System tables            | `_emdash_collections`, `_emdash_fields` |
+| Content  | Per-collection tables    | `ec_posts`, `ec_products`, …            |
+| Media    | Separate table + storage | `media` table + R2/S3                   |
+| Settings | Options table            | `options` with a `site:` prefix         |
+
+### Runtime schema changes
+
+Adding a field through the admin UI runs three steps:
+
+<Steps>
+
+1. Insert a record into `_emdash_fields`.
+2. Run `ALTER TABLE ec_<collection> ADD COLUMN <name> <TYPE>`.
+3. Regenerate the Zod schema used for validation.
+
+</Steps>
+
+SQLite supports add, rename, and drop column (drop requires SQLite 3.35+) at runtime. Changing a column's type is not supported in place, so EmDash rebuilds the table transparently: create a new table, copy rows, drop the old table, rename the new one.
+
+### Runtime validation
+
+EmDash builds Zod schemas from the field definitions at startup and validates every create and update against them:
+
+```ts
+function buildSchema(fields: Field[]): ZodSchema {
+	const shape: Record<string, ZodType> = {};
+	for (const field of fields) {
+		let zodType = fieldTypeToZod(field.type);
+		if (field.required) zodType = zodType.required();
+		if (field.validation?.min !== undefined) zodType = zodType.min(field.validation.min);
+		shape[field.slug] = zodType;
+	}
+	return z.object(shape);
+}
+```
+
+## Data layer
+
+EmDash uses [Kysely](https://kysely.dev) for type-safe SQL across every supported database (SQLite, Cloudflare D1, libSQL). The dialect is selected by `virtual:emdash/dialect` from the configuration the site passes to the integration.
+
+## Live Collections loader
+
+Content is served at runtime through Astro's [Live Collections](https://docs.astro.build/en/reference/experimental-flags/live-content-collections/). `emdashLoader()` implements Astro's `LiveLoader` interface and is registered as a single `_emdash` collection:
+
+```ts title="src/live.config.ts"
+import { defineLiveCollection } from "astro:content";
+import { emdashLoader } from "emdash/runtime";
+
+export const collections = {
+	_emdash: defineLiveCollection({ loader: emdashLoader() }),
+};
+```
+
+The single `_emdash` collection wraps every content type; the loader filters by type when `getEmDashCollection("posts")` is called.
+
+## Request paths
+
+A content request from a page:
+
+<Steps>
+
+1. Astro receives the request and runs the page component.
+2. `getEmDashCollection()` calls Astro's `getLiveCollection()`.
+3. `emdashLoader` queries the relevant `ec_*` table through Kysely.
+4. Rows are mapped to Astro's entry format (`id`, `slug`, `data`).
+5. The component renders.
+
+</Steps>
+
+An admin request:
+
+<Steps>
+
+1. Middleware validates the session token.
+2. The API route runs CRUD through a repository.
+3. Lifecycle hooks fire (for example `content:beforeSave`).
+4. Kysely executes the SQL.
+5. The route returns JSON to the admin SPA.
+
+</Steps>
+
+## Admin panel internals
+
+The admin is one React island. Astro serves the shell and enforces authentication in middleware; everything inside is client-side, built on TanStack Router, TanStack Query, TanStack Table, React Hook Form + Zod, TipTap, and Kumo (Cloudflare's Base UI + Tailwind design system).
+
+The shell route gates access in middleware:
+
+```ts
+export async function onRequest({ request, locals }, next) {
+	const session = await getSession(request);
+	if (request.url.includes("/_emdash/admin")) {
+		if (!session?.user) return redirect("/_emdash/admin/login");
+		locals.user = session.user;
+	}
+	return next();
+}
+```
+
+### Manifest-driven UI
+
+The admin hardcodes nothing about collections or plugins. It fetches `GET /_emdash/api/manifest`, which returns the collections, plugins, and taxonomies the requesting user may access, filtered by role:
+
+```json
+{
+	"collections": [
+		{
+			"slug": "posts",
+			"label": "Blog Posts",
+			"icon": "file-text",
+			"supports": ["drafts", "revisions", "preview"],
+			"fields": [{ "slug": "title", "type": "string", "required": true }]
+		}
+	],
+	"plugins": [{ "id": "audit-log", "label": "Audit Log" }],
+	"taxonomies": [{ "name": "category", "label": "Categories", "hierarchical": true }],
+	"version": "abc123"
+}
+```
+
+Navigation, forms, and field editors are generated from this manifest, so schema and plugin changes appear without an admin rebuild, and Zod schemas stay server-side.
+
+### Plugin admin UIs
+
+Plugin admin entry points are collected into a generated virtual module of static imports so the bundler can resolve and tree-shake them:
+
+```ts title="virtual:emdash/plugin-admins (generated)"
+import * as pluginAdmin0 from "@emdash-cms/plugin-seo/admin";
+
+export const pluginAdmins = { seo: pluginAdmin0 };
+```
+
+### Rich text conversion
+
+Portable Text fields edit in TipTap (ProseMirror). Content is converted at the load and save boundaries by `portableTextToProsemirror()` and `prosemirrorToPortableText()`. Unknown blocks from plugins or imports are preserved as read-only placeholders.
+
+### Signed uploads
+
+Media uploads bypass Worker body-size limits with direct-to-storage signed URLs:
+
+<Steps>
+
+1. The client requests an upload URL (`POST /api/media/upload-url`).
+2. The client uploads directly to the signed URL (R2 or S3).
+3. The client confirms (`POST /api/media/:id/confirm`).
+4. The server extracts metadata (dimensions, MIME type).
+
+</Steps>
+
+## Extending the content importer
+
+The WordPress importer is built on a pluggable `ImportSource` interface. A custom source implements probe, analyze, and fetch:
+
+```ts
+interface ImportSource {
+	probe(input: ImportInput): Promise<ProbeResult>;
+	analyze(input: ImportInput): Promise<AnalysisResult>;
+	fetchContent(input: ImportInput): AsyncIterable<NormalizedEntry>;
+}
+```
+
+`probe` validates the input and reports what it found, `analyze` maps source post types to EmDash collections and flags schema gaps, and `fetchContent` streams normalized entries the import pipeline writes through the same repositories the admin uses. Built-in sources cover WordPress WXR, WordPress.com, and the WordPress REST API; register a custom source to import from another system.
diff --git a/docs/src/content/docs/contributing/translating.mdx b/docs/src/content/docs/contributing/translating.mdx
index b78971e4a..857d55fed 100644
--- a/docs/src/content/docs/contributing/translating.mdx
+++ b/docs/src/content/docs/contributing/translating.mdx
@@ -13,7 +13,7 @@ See the [translation dashboard](https://i18n.emdashcms.com) for current progress
 
 ## Who can translate
 
-Translations must come from **native or fluent speakers**. Machine-generated translations are not accepted. If you use AI tools to assist, you must review every string by hand and test the result in context (see [Testing your translations](#testing-your-translations) below).
+Every translation must be supervised by a **native or fluent speaker**. AI-generated translations are accepted, but only when a fluent speaker reviews every string and previews it in the running admin panel before submitting. Unsupervised machine output is not accepted. See [AI-assisted translations](#ai-assisted-translations) and [Testing your translations](#testing-your-translations) below.
 
 No translation is better than a bad one. A wrong translation is worse than showing the English fallback — it actively misleads users.
 
@@ -179,12 +179,12 @@ The admin UI uses a direct, professional tone. Match that in your language — a
 
 ### AI-assisted translations
 
-You may use AI tools to draft translations, but:
+You may generate translations with AI tools, including a full first pass, but a fluent speaker must supervise the result:
 
-- You **must** review every string yourself. AI tools make subtle errors that only a fluent speaker would catch — wrong register, unnatural phrasing, incorrect technical terms.
-- You **must** test the result in the running admin UI. AI tools have no awareness of layout constraints or UI context.
+- A fluent speaker **must** review every string. AI tools make subtle errors only a fluent speaker catches — wrong register, unnatural phrasing, incorrect technical terms.
+- A fluent speaker **must** preview the translations in the running admin UI. AI tools have no awareness of layout constraints or UI context.
 - Disclose AI usage in your PR description.
-- PRs with obvious unreviewed machine translations will be closed.
+- PRs with unsupervised machine translations will be closed.
 
 ## Partial translations
 
diff --git a/docs/src/content/docs/guides/preview.mdx b/docs/src/content/docs/guides/preview.mdx
index 92be40389..a99bea685 100644
--- a/docs/src/content/docs/guides/preview.mdx
+++ b/docs/src/content/docs/guides/preview.mdx
@@ -267,21 +267,13 @@ const { collection, id } = parseContentId("posts:my-draft-post");
 // { collection: "posts", id: "my-draft-post" }
 ```
 
-## Token Format
+## Token security
 
-Preview tokens use a compact format: `base64url(payload).base64url(signature)`
-
-The payload contains:
-
-- `cid` — Content ID in format `collection:id`
-- `exp` — Expiry timestamp (seconds since epoch)
-- `iat` — Issued-at timestamp (seconds since epoch)
-
-Tokens are signed with HMAC-SHA256 using your preview secret.
+Preview tokens are signed and time-limited. The CLI and the helper functions generate and verify them for you; you do not construct or parse them by hand. A token identifies one entry and stops working after it expires.
 
 <Aside type="caution">
-	Keep your `EMDASH_PREVIEW_SECRET` secure. Anyone with this secret can generate valid preview tokens for
-	any content.
+	Keep your `EMDASH_PREVIEW_SECRET` secret. Anyone who has it can generate a
+	valid preview token for any content.
 </Aside>
 
 ## Complete Example
diff --git a/docs/src/content/docs/migration/content-import.mdx b/docs/src/content/docs/migration/content-import.mdx
index f2adcdb3e..1b464e48a 100644
--- a/docs/src/content/docs/migration/content-import.mdx
+++ b/docs/src/content/docs/migration/content-import.mdx
@@ -182,67 +182,6 @@ After content, optionally import media:
 
 Media import uses content hashing (xxHash64) for deduplication. The same image used in multiple posts is stored once.
 
-## Source Interface
-
-Import sources implement a standard interface:
-
-```typescript
-interface ImportSource {
-	/** Unique identifier */
-	id: string;
-
-	/** Display name */
-	name: string;
-
-	/** Probe a URL (optional) */
-	probe?(url: string): Promise<SourceProbeResult | null>;
-
-	/** Analyze content from this source */
-	analyze(input: SourceInput, context: ImportContext): Promise<ImportAnalysis>;
-
-	/** Stream content items */
-	fetchContent(input: SourceInput, options: FetchOptions): AsyncGenerator<NormalizedItem>;
-}
-```
-
-### Input Types
-
-Sources accept different input types:
-
-```typescript
-// File upload (WXR)
-{ type: "file", file: File }
-
-// URL with optional token (REST API)
-{ type: "url", url: string, token?: string }
-
-// OAuth connection (WordPress.com)
-{ type: "oauth", url: string, accessToken: string }
-```
-
-### Normalized Output
-
-All sources produce the same normalized format:
-
-```typescript
-interface NormalizedItem {
-	sourceId: string | number;
-	postType: string;
-	status: "publish" | "draft" | "pending" | "private" | "future";
-	slug: string;
-	title: string;
-	content: PortableTextBlock[];
-	excerpt?: string;
-	date: Date;
-	author?: string;
-	authors?: string[];
-	categories?: string[];
-	tags?: string[];
-	meta?: Record<string, unknown>;
-	featuredImage?: string;
-}
-```
-
 ## API Endpoints
 
 The import system exposes these endpoints:
@@ -364,54 +303,9 @@ Import Complete
 
 Failed items are saved as drafts with original content in `_importError` for review.
 
-## Building Custom Sources
-
-Create a source for other platforms:
-
-```typescript title="src/import/custom-source.ts"
-import type { ImportSource } from "emdash/import";
-
-export const mySource: ImportSource = {
-	id: "my-platform",
-	name: "My Platform",
-	description: "Import from My Platform",
-	icon: "globe",
-	canProbe: true,
-
-	async probe(url) {
-		// Check if URL matches your platform
-		const response = await fetch(`${url}/api/info`);
-		if (!response.ok) return null;
-
-		return {
-			sourceId: "my-platform",
-			confidence: "definite",
-			detected: { platform: "my-platform" },
-			// ...
-		};
-	},
-
-	async analyze(input, context) {
-		// Parse and analyze content
-		// Return ImportAnalysis
-	},
-
-	async *fetchContent(input, options) {
-		// Yield NormalizedItem for each content piece
-		for (const item of items) {
-			yield {
-				sourceId: item.id,
-				postType: "post",
-				title: item.title,
-				content: convertToPortableText(item.body),
-				// ...
-			};
-		}
-	},
-};
-```
+## Custom sources
 
-Register the source in your EmDash configuration:
+To import from a platform the built-in sources do not cover, implement the `ImportSource` interface and register it on the integration:
 
 ```typescript title="astro.config.mjs"
 import { mySource } from "./src/import/custom-source";
@@ -419,14 +313,14 @@ import { mySource } from "./src/import/custom-source";
 export default defineConfig({
 	integrations: [
 		emdash({
-			import: {
-				sources: [mySource],
-			},
+			import: { sources: [mySource] },
 		}),
 	],
 });
 ```
 
+The interface (`probe`, `analyze`, `fetchContent`) and the normalized output shape are documented in [Architecture (internals)](/contributing/architecture/#extending-the-content-importer).
+
 ## Next Steps
 
 - **[WordPress Migration](/migration/from-wordpress/)** — Complete WordPress migration guide
diff --git a/docs/src/content/docs/reference/mcp-server.mdx b/docs/src/content/docs/reference/mcp-server.mdx
index 39ce4e3f4..b85540120 100644
--- a/docs/src/content/docs/reference/mcp-server.mdx
+++ b/docs/src/content/docs/reference/mcp-server.mdx
@@ -679,7 +679,7 @@ The `seo` object accepts:
 
 ## OAuth Discovery
 
-MCP clients that support OAuth 2.1 can automatically discover how to authenticate. The server publishes two metadata documents:
+Most MCP clients handle this for you; this section is for building an MCP client against EmDash directly. Clients that support OAuth 2.1 discover how to authenticate from two metadata documents the server publishes:
 
 ### Protected Resource Metadata
 

From cc6795b0391b1c9c9289e979aee9b17e7b80e7bf Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sat, 16 May 2026 13:02:52 +0100
Subject: [PATCH 3/8] docs: cut recency bias, straw-man framing, and
 definition-by-negation

Removes 'database-first/schema as data' framing from user-facing pages
(it described an internal decision, not a user capability) and reframes
around what the reader does. The mechanism stays only in the contributor
architecture doc. Removes definition-by-negation ('no migration to write',
'no rebuild', 'without code') in favour of positive statements of what
happens. Keeps honest, specific comparison only on the evaluation and
'coming from' orientation pages.

Adds 'What to emphasise', 'Evergreen, not changelog', and a
definition-by-negation rule to the style guide, and reorders its own
'EmDash specifics' so it models the principle rather than ranking by
recency. Corrects the translating policy (supervised AI translations
are accepted).
---
 .../src/content/docs/concepts/admin-panel.mdx |  2 +-
 .../content/docs/concepts/architecture.mdx    | 30 ++++---
 .../src/content/docs/concepts/collections.mdx |  2 +-
 .../content/docs/concepts/content-model.mdx   | 78 ++++++-------------
 .../docs/contributing/docs-style-guide.mdx    | 30 +++++--
 docs/src/content/docs/getting-started.mdx     |  2 +-
 .../src/content/docs/guides/create-a-blog.mdx |  2 +-
 .../content/docs/guides/querying-content.mdx  |  2 +-
 .../docs/guides/working-with-content.mdx      |  2 +-
 docs/src/content/docs/index.mdx               |  7 +-
 docs/src/content/docs/introduction.mdx        |  6 +-
 docs/src/content/docs/plugins/field-kit.mdx   |  2 +-
 docs/src/content/docs/plugins/installing.mdx  |  2 +-
 docs/src/content/docs/themes/overview.mdx     |  2 +-
 docs/src/content/docs/why-emdash.mdx          | 22 +++---
 15 files changed, 88 insertions(+), 103 deletions(-)

diff --git a/docs/src/content/docs/concepts/admin-panel.mdx b/docs/src/content/docs/concepts/admin-panel.mdx
index e8b3de08a..519d80e79 100644
--- a/docs/src/content/docs/concepts/admin-panel.mdx
+++ b/docs/src/content/docs/concepts/admin-panel.mdx
@@ -23,7 +23,7 @@ The admin panel is the content management interface for your site. It is served
 | `/settings`                | Site settings                   |
 | `/plugins/:pluginId/*`     | Plugin pages                    |
 
-Navigation is generated from your collections and installed plugins, so a schema or plugin change appears in the admin without a rebuild.
+Navigation is generated from your collections and installed plugins, so a schema or plugin change appears in the admin immediately.
 
 ## Roles
 
diff --git a/docs/src/content/docs/concepts/architecture.mdx b/docs/src/content/docs/concepts/architecture.mdx
index 1af742f17..ec566cdf7 100644
--- a/docs/src/content/docs/concepts/architecture.mdx
+++ b/docs/src/content/docs/concepts/architecture.mdx
@@ -1,6 +1,6 @@
 ---
 title: Architecture
-description: The mental model for building with EmDash — an Astro integration with database-first content and live queries.
+description: The mental model for building with EmDash — an Astro integration with a live, editable content model.
 ---
 
 import { Aside, Card, CardGrid } from "@astrojs/starlight/components";
@@ -29,31 +29,29 @@ EmDash is an Astro integration. You add it to `astro.config.mjs`, choose a datab
 
 You write pages and components as normal. EmDash provides the content, an admin panel for editing it, and the database and storage behind it. Editors work in the admin panel; your pages read the same content through query functions.
 
-## Database-first content
+## Your content model
 
-Your content model lives in the database, not in code. When someone adds a `products` collection with `title` and `price` in the admin panel, EmDash creates a real `products` table with real `title` and `price` columns.
-
-This is the decision that shapes everything else:
+You define collections and fields — in the admin panel or with the CLI — and EmDash stores content against them.
 
 <CardGrid>
-	<Card title="Change the model at runtime" icon="pencil">
-		Add or edit collections and fields in the admin panel. No code change, no
-		rebuild, no migration to write.
+	<Card title="Change it anytime" icon="pencil">
+		Add, rename, remove, or retype collections and fields whenever you need
+		to. Changes take effect immediately.
 	</Card>
-	<Card title="Set up without a developer" icon="seti:plan">
-		A non-developer can design the content model through the admin UI.
+	<Card title="No developer required" icon="seti:plan">
+		A content editor can design the whole model through the admin UI.
 	</Card>
-	<Card title="Real SQL underneath" icon="seti:db">
-		Each field is a real column with proper indexing and queries — useful if
-		you ever query the database directly.
+	<Card title="Typed" icon="approve-check">
+		Generate TypeScript types from the current model for autocomplete from
+		query to template.
 	</Card>
 	<Card title="Portable" icon="right-arrow">
-		Export the schema as a JSON seed file for version control, and apply it in
+		Export the model as a JSON seed file for version control, and apply it in
 		another environment.
 	</Card>
 </CardGrid>
 
-The trade-off you accept is that the source of truth for your schema is the database. Use [type generation](/concepts/content-model/#typescript-types) and [seed files](/themes/seed-files/) to keep that manageable in a code workflow.
+See the [content model](/concepts/content-model/) for how to define, change, type, and seed it.
 
 ## Content is live
 
@@ -107,7 +105,7 @@ See the [plugin overview](/plugins/overview/) to choose and install plugins, or
 		Define [content collections and field types](/concepts/collections/).
 	</Card>
 	<Card title="Content Model" icon="open-book">
-		Understand the [database-first content model](/concepts/content-model/).
+		Understand the [content model](/concepts/content-model/).
 	</Card>
 	<Card title="Admin Panel" icon="setting">
 		See what the [admin panel](/concepts/admin-panel/) offers editors and admins.
diff --git a/docs/src/content/docs/concepts/collections.mdx b/docs/src/content/docs/concepts/collections.mdx
index dfa248c7e..f0f16fd50 100644
--- a/docs/src/content/docs/concepts/collections.mdx
+++ b/docs/src/content/docs/concepts/collections.mdx
@@ -371,7 +371,7 @@ Field types map to SQLite column types as follows:
 
 <CardGrid>
 	<Card title="Content Model" icon="open-book">
-		Understand the [database-first approach](/concepts/content-model/).
+		Understand the [content model](/concepts/content-model/).
 	</Card>
 	<Card title="Taxonomies" icon="list-format">
 		Organize content with [categories and tags](/guides/taxonomies/).
diff --git a/docs/src/content/docs/concepts/content-model.mdx b/docs/src/content/docs/concepts/content-model.mdx
index 6d9478c83..01023c922 100644
--- a/docs/src/content/docs/concepts/content-model.mdx
+++ b/docs/src/content/docs/concepts/content-model.mdx
@@ -1,65 +1,37 @@
 ---
 title: Content Model
-description: How EmDash's database-first content model works for you — runtime schema changes, type generation, and seed files.
+description: How you shape and evolve your content model in EmDash — collections, fields, runtime changes, types, and seeds.
 ---
 
 import { Aside, Card, CardGrid, Steps } from "@astrojs/starlight/components";
 
-EmDash is **database-first**: your content model lives in the database, not in a code file. This page covers what that means for how you set up and evolve a site. For the table layouts and validation internals, see [Architecture (internals)](/contributing/architecture/#database-first-schema).
+Your content model is the set of collections and fields your site stores. You define it in the admin panel or with the CLI, change it whenever you need to, and optionally generate TypeScript types from it. This page covers how to work with it.
 
-## Schema as data
+## Collections and fields
 
-In many CMSs you declare a collection's fields in code:
+A **collection** is a type of content (posts, products, authors). Each collection has **fields** you define (a title, a body, a price). Every entry also has system fields EmDash manages for you.
 
-```ts
-const posts = collection({
-	fields: {
-		title: text({ required: true }),
-		content: richText(),
-	},
-});
-```
-
-EmDash stores that same structure in the database instead. You define collections and fields in the admin panel or with the CLI, and EmDash turns them into real tables and columns. The structure is the same; what changes is where it lives and how you modify it.
-
-## Why this matters
-
-<CardGrid>
-	<Card title="Change the model at runtime" icon="pencil">
-		Add, rename, or remove collections and fields whenever you need to. No
-		code change, no rebuild, no migration to write.
-	</Card>
-	<Card title="Set up without a developer" icon="seti:plan">
-		A content editor can design the whole data model through the admin UI.
-	</Card>
-	<Card title="Real SQL columns" icon="seti:db">
-		Each field is a real column with proper indexing and queries.
-	</Card>
-	<Card title="Portable" icon="right-arrow">
-		Export the schema as a JSON seed file for version control, and apply it in
-		another environment.
-	</Card>
-</CardGrid>
+You create and edit collections and fields visually in the admin panel under **Content Types**, or with the CLI. Changes take effect immediately, and a non-developer can do it.
 
 ## System fields
 
-Every entry has a set of fields EmDash manages for you, in addition to the fields you define. You do not declare these; they are always present:
+In addition to the fields you define, every entry has these, always present:
 
-| Field          | Purpose                                  |
-| -------------- | ---------------------------------------- |
-| `id`           | Stable unique identifier                 |
-| `slug`         | URL-safe identifier, unique per locale   |
-| `status`       | `draft`, `published`, or `scheduled`     |
-| `author_id`    | The user who created the entry           |
-| `created_at` / `updated_at` / `published_at` | Timestamps             |
-| `deleted_at`   | Set on soft delete; the row is kept      |
-| `version`      | Increments on each save                  |
+| Field                                        | Purpose                                |
+| -------------------------------------------- | -------------------------------------- |
+| `id`                                         | Stable unique identifier               |
+| `slug`                                       | URL-safe identifier, unique per locale |
+| `status`                                     | `draft`, `published`, or `scheduled`   |
+| `author_id`                                  | The user who created the entry         |
+| `created_at` / `updated_at` / `published_at` | Timestamps                             |
+| `deleted_at`                                 | Set on soft delete; the row is kept    |
+| `version`                                    | Increments on each save                |
 
-A deleted entry is soft-deleted: the row stays, with `deleted_at` set, so it can be restored.
+Deleting an entry is a soft delete: it can be restored.
 
-## Changing the model at runtime
+## Changing the model anytime
 
-You can add, rename, or remove a field on a live collection at any time, through the admin panel or the CLI. Existing content is preserved. Changing a field's type is also supported; EmDash handles the underlying data move for you.
+You can add, rename, remove, or retype a field on a live collection at any time, through the admin panel or the CLI. Existing content is preserved.
 
 <Aside type="tip">
 	Adding a field is always safe. Removing one drops its data. Rename rather
@@ -68,7 +40,7 @@ You can add, rename, or remove a field on a live collection at any time, through
 
 ## TypeScript types
 
-Type generation is optional but recommended. Generate types from the live schema:
+Type generation is optional but recommended. Generate types from your current model:
 
 ```bash
 npx emdash types
@@ -90,11 +62,11 @@ declare module "emdash" {
 }
 ```
 
-Re-run the command after changing the schema to keep types in sync.
+Re-run the command after changing the model to keep types in sync.
 
-## Developer and non-developer workflows
+## Workflows
 
-Both workflows modify the same content model.
+Both workflows change the same model.
 
 A non-developer uses the admin panel:
 
@@ -107,11 +79,11 @@ A non-developer uses the admin panel:
 
 </Steps>
 
-A developer can use the CLI to generate types and move the schema between environments:
+A developer can use the CLI to generate types and move the model between environments:
 
 ```bash
-npx emdash types               # generate TypeScript types
-npx emdash export-seed > seed.json   # export the schema as a seed file
+npx emdash types                     # generate TypeScript types
+npx emdash export-seed > seed.json   # export the model as a seed file
 ```
 
 ## Seed files
diff --git a/docs/src/content/docs/contributing/docs-style-guide.mdx b/docs/src/content/docs/contributing/docs-style-guide.mdx
index 2f5b3b663..87f3d1cd6 100644
--- a/docs/src/content/docs/contributing/docs-style-guide.mdx
+++ b/docs/src/content/docs/contributing/docs-style-guide.mdx
@@ -21,6 +21,24 @@ Document **how to build with EmDash**, not **how EmDash is built**. Implementati
 
 For non-EmDash topics — TypeScript, the AT Protocol, web fonts, SQL — link to a reputable source instead of explaining them. Document what someone needs to know to use the feature **in EmDash**.
 
+## What to emphasise
+
+A page's emphasis must be set by what the reader needs to do their task, never by what was interesting or recent to the people who built EmDash. Three habits to actively resist:
+
+- **Authoring-recency weight.** A decision being new, or fresh in the writer's mind, is not a reason to feature it. The most-changed thing is rarely the most important thing to a reader. Order sections, list items, and headlines by how often a reader needs them, not by when they were added. If you are documenting something because it just changed, you are probably writing a changelog entry, not a doc.
+
+- **Builder-salience over reader-salience.** Internal architecture and design decisions that were significant to *make* are usually invisible and irrelevant to *use*. State the capability the reader gets, not the mechanism behind it. A reader defining a collection does not need to know where the schema is stored, any more than they need to know the parser's language. If the mechanism genuinely helps someone working on EmDash, it belongs in the internals doc, not in a user-facing page.
+
+- **Straw-man self-definition.** Do not define EmDash by contrast with a caricature of other tools ("Unlike most CMSs…", "Traditional CMSs force you to…", "in many CMSs you declare X in code"). Describe what EmDash does, directly, and let it stand on its own. Comparison is allowed only when the comparison is *the reader's own question*: on the evaluation page and the "Coming from…" orientation pages. Even there it must be specific and fair — concrete behaviours and trade-offs, not a strawman the reader is invited to dislike.
+
+- **Definition by negation.** Framing a capability as the work you _don't_ have to do — "no migration to write", "no rebuild", "without touching code", "no separate service" — is a straw-man in disguise: it only lands for a reader who is carrying the alternative you have invented for them. State what the reader _does_ and what _happens_. "Add a field in the admin panel; it takes effect immediately" — not "add a field with no migration, no rebuild, no code". The exception is a concrete, reader-relevant behaviour stated positively: "content is served at runtime, so edits appear immediately" is a fact about EmDash; "no rebuilds needed" is the same fact phrased as someone else's absent pain — prefer the first.
+
+The test for any sentence: would a reader trying to finish their task be worse off if it were deleted? If not, delete it. If it only makes sense to a reader comparing EmDash to something else, it is in the wrong place or should be cut.
+
+## Evergreen, not changelog
+
+User-facing pages describe how EmDash works now, for a reader who has no prior version in their head. No "now", "no longer", "used to", "instead of the old", "this changed". Version-to-version differences live only in an [upgrade guide](#upgrade-and-migration-guides). A concept being recently introduced is never a reason to mention that it is recent.
+
 ## Voice and tone
 
 Write neutral, factual sentences. State facts directly.
@@ -36,8 +54,6 @@ Write neutral, factual sentences. State facts directly.
 - **Avoid whimsy, mascots, and cultural references.** They add reading effort and do not translate.
 - **Exclamation points are rare.** Use one only for something genuinely encouraging or surprising. When unsure, use a period.
 
-Do not describe the previous behaviour of EmDash in a regular guide ("this used to be called…", "no longer", "instead of the old…"). A guide documents how the software works now. Changes between versions belong in an [upgrade guide](#upgrade-and-migration-guides).
-
 ## Headings
 
 - Page title is the `<h1>` (from frontmatter `title`). Sections start at `<h2>`.
@@ -119,21 +135,23 @@ A breaking change is one that requires a change to the reader's project or it st
 
 ## EmDash specifics
 
+Conventions for recurring situations, ordered by how often a contributor hits them. This is a list of conventions, not a ranking of which features matter.
+
 ### Plugins: sandboxed vs native
 
 Sandboxed and native plugins are different formats with different authoring shapes. A change to one rarely affects the other. State which format a page or example is about. When editing a sandboxed-plugin page, do not change native-plugin examples, and the reverse.
 
-### Atmosphere accounts
+### Localization
 
-The portable, user-owned identity behind Bluesky and the wider AT Protocol network is an **Atmosphere account**. Use that term. Link the first mention to [the Atmosphere login guide](/guides/atmosphere-auth/) or [atmosphereaccount.com](https://atmosphereaccount.com). `did:plc:…` and handles are the concrete identifiers of an Atmosphere account; use them where a literal value is needed.
+Do not include `messages.po` changes in a docs PR. A workflow extracts catalogs on merge to `main`. Including them creates churn and merge conflicts.
 
 ### Experimental features
 
 A feature behind an experimental flag, or an unstable wire format under an RFC, can change without notice. Keep its documentation lean, flag it with a caution `<Aside>`, and point to the RFC or discussion as the source of truth. Do not document an unstable surface in exhaustive detail.
 
-### Localization
+### Atmosphere accounts
 
-Do not include `messages.po` changes in a docs PR. A workflow extracts catalogs on merge to `main`. Including them creates churn and merge conflicts.
+When the portable, user-owned identity behind Bluesky and the wider AT Protocol network comes up, call it an **Atmosphere account** and use that term consistently. Link the first mention to [the Atmosphere login guide](/guides/atmosphere-auth/) or [atmosphereaccount.com](https://atmosphereaccount.com). `did:plc:…` and handles are its concrete identifiers; use them where a literal value is needed.
 
 ## Docs are code
 
diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx
index 120c62759..babadbed6 100644
--- a/docs/src/content/docs/getting-started.mdx
+++ b/docs/src/content/docs/getting-started.mdx
@@ -106,7 +106,7 @@ Once your passkey is registered, you're logged in and redirected to the admin da
 
 4. Set the status to **Published** and click **Save**.
 
-5. Visit your site's homepage to see your post live. No rebuild is needed.
+5. Visit your site's homepage. The post appears immediately.
 
 </Steps>
 
diff --git a/docs/src/content/docs/guides/create-a-blog.mdx b/docs/src/content/docs/guides/create-a-blog.mdx
index a34c982ed..ab96dfe5c 100644
--- a/docs/src/content/docs/guides/create-a-blog.mdx
+++ b/docs/src/content/docs/guides/create-a-blog.mdx
@@ -48,7 +48,7 @@ The default posts collection includes:
 
 7. Click **Save**
 
-The post is now live. No rebuild is required.
+The post is now live and appears immediately.
 
 ## Display Posts on Your Site
 
diff --git a/docs/src/content/docs/guides/querying-content.mdx b/docs/src/content/docs/guides/querying-content.mdx
index 7b552a010..b192bd6ba 100644
--- a/docs/src/content/docs/guides/querying-content.mdx
+++ b/docs/src/content/docs/guides/querying-content.mdx
@@ -359,7 +359,7 @@ if (!post) {
 ```
 
 <Aside type="tip">
-	Server rendering shows content changes immediately without rebuilding. Use it for frequently
+	Server rendering shows content changes immediately. Use it for frequently
 	updated content.
 </Aside>
 
diff --git a/docs/src/content/docs/guides/working-with-content.mdx b/docs/src/content/docs/guides/working-with-content.mdx
index b78339f57..3afe5b3be 100644
--- a/docs/src/content/docs/guides/working-with-content.mdx
+++ b/docs/src/content/docs/guides/working-with-content.mdx
@@ -109,7 +109,7 @@ Type `/` to access quick insert commands:
 
 4. Click **Save**
 
-Changes to published content appear immediately on your site. No rebuild required.
+Changes to published content appear immediately on your site.
 
 ### Revision History
 
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
index c56a7e0cf..9fcfa0626 100644
--- a/docs/src/content/docs/index.mdx
+++ b/docs/src/content/docs/index.mdx
@@ -20,12 +20,11 @@ import { Card, CardGrid } from "@astrojs/starlight/components";
 
 <CardGrid stagger>
 	<Card title="Astro-Native" icon="astro">
-		Built on Astro 6's Live Content Collections. No rebuilds needed—content updates instantly at
-		runtime.
+		Built on Astro 6's Live Content Collections. Content updates appear instantly at runtime.
 	</Card>
 	<Card title="Type-Safe" icon="setting">
-		Schema defined in the database, TypeScript types generated automatically. Full type safety from
-		database to template.
+		Generate TypeScript types from your content model for full type safety and
+		autocomplete, from query to template.
 	</Card>
 	<Card title="Plugin Ecosystem" icon="puzzle">
 		WordPress-inspired plugin system with hooks, storage, and admin UI extensions. Agent-portable
diff --git a/docs/src/content/docs/introduction.mdx b/docs/src/content/docs/introduction.mdx
index 40d91f3de..12188a9da 100644
--- a/docs/src/content/docs/introduction.mdx
+++ b/docs/src/content/docs/introduction.mdx
@@ -9,12 +9,12 @@ EmDash is an **Astro-native content management system**. It brings familiar CMS
 
 ## What EmDash Is
 
-EmDash is a CMS built specifically for [Astro](https://astro.build). It uses Astro 6's Live Content Collections to serve content at runtime without rebuilds. Content is stored in SQLite-compatible databases (D1, libSQL, local SQLite) and media in S3-compatible storage (R2, local filesystem).
+EmDash is a CMS built specifically for [Astro](https://astro.build). It uses Astro 6's Live Content Collections to serve content at runtime, so edits appear immediately. Content is stored in SQLite-compatible databases (D1, libSQL, local SQLite) and media in S3-compatible storage (R2, local filesystem).
 
 **Key characteristics:**
 
-- **Database-first schema** — Collections and fields are defined in the database, not code. Create and modify content types from the admin UI.
-- **Live Collections** — Content changes are immediately available. No static rebuilds needed.
+- **Visual content modelling** — Define and change collections and fields from the admin UI; changes take effect immediately.
+- **Live Collections** — Content is served at runtime, so edits appear immediately.
 - **Plugin system** — WordPress-inspired hooks, storage, settings, and admin UI extensions.
 - **Cloud-portable** — Runs on Cloudflare (Workers + D1 + R2), Node.js, local SQLite, and any S3-compatible storage.
 
diff --git a/docs/src/content/docs/plugins/field-kit.mdx b/docs/src/content/docs/plugins/field-kit.mdx
index 8bb68cb43..7cce52eeb 100644
--- a/docs/src/content/docs/plugins/field-kit.mdx
+++ b/docs/src/content/docs/plugins/field-kit.mdx
@@ -8,7 +8,7 @@ import { Aside } from "@astrojs/starlight/components";
 EmDash's `json` field type stores arbitrary structured data, but the default editor is a single-line text input where you have to type raw JSON by hand. **Field Kit** is a first-party plugin that ships four composable widgets for `json` fields, configured entirely through seed `options` — no React required from site builders.
 
 <Aside type="tip">
-Field Kit widgets store **clean JSON**: removing the plugin leaves valid data in the database. No shape mutation, no new columns, no migration.
+Field Kit widgets store **clean JSON**: the stored value is plain content data, so removing the plugin leaves valid content behind.
 </Aside>
 
 ## Installation
diff --git a/docs/src/content/docs/plugins/installing.mdx b/docs/src/content/docs/plugins/installing.mdx
index 1069631a0..85902001a 100644
--- a/docs/src/content/docs/plugins/installing.mdx
+++ b/docs/src/content/docs/plugins/installing.mdx
@@ -123,7 +123,7 @@ Native plugins:
 - Cannot be installed or removed from the admin UI
 
 <Aside type="tip">
-  Use native plugins only when you need features that require build-time integration: React admin pages, Portable Text rendering components, or page fragment injection. For everything else, prefer sandboxed plugins -- they can be installed, updated, and removed without code changes or redeployments.
+  Use native plugins only when you need features that require build-time integration: React admin pages, Portable Text rendering components, or page fragment injection. For everything else, prefer sandboxed plugins -- they can be installed, updated, and removed from the admin panel.
 </Aside>
 
 ## Marketplace vs. config — when to use which
diff --git a/docs/src/content/docs/themes/overview.mdx b/docs/src/content/docs/themes/overview.mdx
index 1174f75e9..e42dd9650 100644
--- a/docs/src/content/docs/themes/overview.mdx
+++ b/docs/src/content/docs/themes/overview.mdx
@@ -130,7 +130,7 @@ After the Setup Wizard completes, the site is a standard Astro project. Customiz
 - Install Astro integrations
 - Deploy anywhere Astro runs
 
-The seed file is only used during initial setup. Once applied, the schema lives in the database.
+The seed file is only used during initial setup. After that, manage the content model in the admin panel or with the CLI.
 
 ## Next Steps
 
diff --git a/docs/src/content/docs/why-emdash.mdx b/docs/src/content/docs/why-emdash.mdx
index 4438873fb..8d80fc0f0 100644
--- a/docs/src/content/docs/why-emdash.mdx
+++ b/docs/src/content/docs/why-emdash.mdx
@@ -5,7 +5,7 @@ description: Understand what problems EmDash solves and how it compares to other
 
 import { Aside, Card, CardGrid } from "@astrojs/starlight/components";
 
-EmDash is an Astro-native CMS that combines traditional CMS patterns with modern web development: a content editing interface, Astro framework integration, and flexible deployment options.
+EmDash is a CMS built for Astro. It gives editors an admin interface, serves content to your Astro site at runtime, and runs on a range of databases and hosts.
 
 ## What Makes EmDash Different
 
@@ -28,12 +28,11 @@ EmDash is purpose-built for Astro. This tight integration enables type-safe quer
 		Content and frontend deploy together. One codebase, one deployment, one system to manage.
 	</Card>
 	<Card title="Type Safety" icon="approve-check">
-		Schema lives in the database. TypeScript types flow from database to template with full
-		autocomplete.
+		Generate TypeScript types from your content model for full autocomplete,
+		from query to template.
 	</Card>
 	<Card title="Live Updates" icon="star">
-		Built on Astro's Live Content Collections. Content changes appear instantly—no rebuilds
-		needed.
+		Built on Astro's Live Content Collections. Content changes appear instantly.
 	</Card>
 	<Card title="Cloud-Portable" icon="setting">
 		Runs on Cloudflare Workers with D1 and R2, and also works with Node.js, SQLite, and any
@@ -47,13 +46,12 @@ Different CMS approaches suit different needs:
 
 | Aspect              | Traditional CMS  | Headless CMS    | EmDash              |
 | ------------------- | ---------------- | --------------- | --------------------- |
-| **Architecture**    | Monolithic       | Decoupled       | Integrated with Astro |
-| **Content editing** | Built-in admin   | Built-in admin  | Built-in admin        |
-| **Frontend**        | Themes/templates | Bring your own  | Astro components      |
-| **Deployment**      | Single server    | CMS + frontend  | Single deployment     |
-| **Type safety**     | Runtime          | API types       | Full TypeScript       |
-| **Content updates** | Immediate        | Webhook/rebuild | Immediate (SSR)       |
-| **Plugin model**    | Same-process     | API extensions  | Sandboxed with hooks  |
+| **Architecture**    | Monolithic       | Decoupled       | Integrated with Astro    |
+| **Frontend**        | Themes/templates | Bring your own  | Astro components         |
+| **Deployment**      | Single server    | CMS + frontend  | Single deployment        |
+| **Type safety**     | Runtime          | API types       | Full TypeScript          |
+| **Content updates** | Immediate        | Webhook/rebuild | Immediate (SSR)          |
+| **Plugin model**    | Same-process     | API extensions  | Native or sandboxed hooks |
 
 ## Cloudflare Deployment
 

From 0a8ed579690e4301f9644114ed6ddb1b8a1e7a81 Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sat, 16 May 2026 13:13:44 +0100
Subject: [PATCH 4/8] docs: remove AI tropes (negation, em-dash drama,
 builder-salience leaks)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sweep against the AI-tropes reference across all in-scope pages. Mostly
definition-by-negation and straw-man self-definition still hiding in
intros and benefit cards ('no PHP', 'no API round-trips', 'without
rebuilds', 'no bundler, no manifest — just a regular npm package'),
restated as what the reader does or gets. Also: dramatic-pause em-dashes
split into sentences, prose pipeline arrows and a breadcrumb arrow
de-unicoded, a Kysely reference dropped from the introduction diagram,
and roadmap/changelog voice removed from the encryption-key and
auth-secret deployment notes. Definitional bold lists, appositive
em-dashes, UI breadcrumbs, code/diagram arrows, native plugin API code,
and honest comparison on evaluation/coming-from pages were preserved.
---
 .../docs/coming-from/astro-for-wp-devs.mdx    | 19 +++++++++----------
 docs/src/content/docs/coming-from/astro.mdx   | 10 +++++-----
 .../content/docs/coming-from/wordpress.mdx    | 16 +++++++---------
 .../content/docs/concepts/architecture.mdx    |  4 ++--
 .../src/content/docs/concepts/collections.mdx |  2 +-
 .../content/docs/contributing/translating.mdx |  2 +-
 .../content/docs/deployment/cloudflare.mdx    | 12 ++++++------
 docs/src/content/docs/deployment/nodejs.mdx   | 10 +++++-----
 docs/src/content/docs/getting-started.mdx     |  2 +-
 .../content/docs/guides/atmosphere-auth.mdx   |  4 ++--
 .../docs/guides/internationalization.mdx      |  6 +++---
 docs/src/content/docs/guides/page-layouts.mdx |  6 +++---
 docs/src/content/docs/guides/preview.mdx      |  8 ++++----
 .../content/docs/guides/querying-content.mdx  |  2 +-
 docs/src/content/docs/guides/sections.mdx     |  6 +-----
 .../src/content/docs/guides/x402-payments.mdx |  4 ++--
 docs/src/content/docs/introduction.mdx        | 16 ++++++++--------
 .../content/docs/migration/content-import.mdx |  2 +-
 .../content/docs/migration/from-wordpress.mdx |  2 +-
 .../creating-native-plugins/distributing.mdx  |  2 +-
 .../page-fragments.mdx                        |  2 +-
 .../your-first-native-plugin.mdx              |  6 +++---
 docs/src/content/docs/plugins/field-kit.mdx   |  4 ++--
 docs/src/content/docs/plugins/overview.mdx    |  6 +++---
 .../content/docs/reference/configuration.mdx  |  2 +-
 docs/src/content/docs/reference/hooks.mdx     |  4 ++--
 .../content/docs/themes/porting-wp-themes.mdx |  2 +-
 docs/src/content/docs/why-emdash.mdx          |  2 +-
 28 files changed, 78 insertions(+), 85 deletions(-)

diff --git a/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx b/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx
index 3e611785d..c4d23991f 100644
--- a/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx
+++ b/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx
@@ -331,7 +331,7 @@ Styles in a `<style>` tag are automatically scoped to that component:
 </style>
 ```
 
-The generated HTML includes unique class names to prevent style leakage. No more specificity wars.
+The generated HTML includes unique class names to prevent style leakage, so component styles stay contained without escalating selector specificity.
 
 ### Global Styles
 
@@ -477,8 +477,7 @@ const { post } = Astro.props;
 | `add_rewrite_rule()`                   | Create files or folders             |
 
 <Aside type="tip">
-	No more guessing which template WordPress will use. The URL `/posts/hello` always loads
-	`src/pages/posts/[slug].astro`.
+	Routing is explicit: the URL `/posts/hello` always loads `src/pages/posts/[slug].astro`.
 </Aside>
 
 ## Where WordPress Concepts Live
@@ -530,14 +529,14 @@ A reference for finding the Astro/EmDash equivalent of WordPress features:
 | Featured image         | Media reference field                 |
 | Gutenberg blocks       | Portable Text blocks                  |
 
-## Summary
+## Concept Mapping
 
-The jump from WordPress to Astro is significant but logical:
+The main WordPress-to-Astro shifts covered in this guide:
 
-1. **PHP templates → Astro components** — Same idea (server code + HTML), better organization
-2. **Template tags → Props and imports** — Explicit data flow instead of globals
-3. **Theme files → Pages directory** — URLs match file structure
-4. **Hooks → Slots and middleware** — More predictable insertion points
-5. **jQuery by default → Zero JS by default** — Add interactivity intentionally
+- PHP templates become Astro components: server code plus HTML, with explicit file organization.
+- Template tags become props and imports: data flows through arguments instead of globals.
+- Theme files become a pages directory: URLs match the file structure.
+- Hooks become slots and middleware: insertion points are defined where content is passed in.
+- jQuery loads by default in WordPress; Astro ships no JavaScript until you add it.
 
 Start with the [Getting Started](/getting-started/) guide to build your first EmDash site, or explore [Working with Content](/guides/working-with-content/) to learn how to query and render CMS data.
diff --git a/docs/src/content/docs/coming-from/astro.mdx b/docs/src/content/docs/coming-from/astro.mdx
index f1c847018..07aaf1e51 100644
--- a/docs/src/content/docs/coming-from/astro.mdx
+++ b/docs/src/content/docs/coming-from/astro.mdx
@@ -5,9 +5,9 @@ description: Add WordPress-style CMS features to your Astro site with EmDash
 
 import { Aside, Card, CardGrid, Tabs, TabItem } from "@astrojs/starlight/components";
 
-EmDash is a CMS built specifically for Astro—not a generic headless CMS with an Astro adapter. It extends your Astro site with database-backed content, a polished admin UI, and WordPress-style features (menus, widgets, taxonomies) while preserving the developer experience you expect.
+EmDash is a CMS built specifically for Astro. It extends your Astro site with database-backed content, a polished admin UI, and WordPress-style features (menus, widgets, taxonomies) while preserving the developer experience you expect.
 
-Everything you know about Astro still applies. EmDash enhances your site; it doesn't replace your workflow.
+Everything you know about Astro still applies. EmDash adds content management on top of your existing Astro workflow.
 
 ## What EmDash Adds
 
@@ -26,8 +26,8 @@ EmDash provides the content management features that file-based Astro sites lack
 | **Revisions**        | Content version history                              |
 
 <Aside type="tip">
-	Content changes appear immediately without rebuilding your site. EmDash sites run in SSR mode by
-	default.
+	EmDash sites run in SSR mode by default, so content is served at runtime and changes appear
+	immediately.
 </Aside>
 
 ## Astro Collections vs EmDash
@@ -330,7 +330,7 @@ export default definePlugin({
 
 ## Server Rendering
 
-EmDash sites run in SSR mode. Content changes appear immediately without rebuilds.
+EmDash sites run in SSR mode, so content is served at runtime and changes appear immediately.
 
 For static pages with `getStaticPaths`, content is fetched at build time:
 
diff --git a/docs/src/content/docs/coming-from/wordpress.mdx b/docs/src/content/docs/coming-from/wordpress.mdx
index e0d8c0b27..d217bb6d8 100644
--- a/docs/src/content/docs/coming-from/wordpress.mdx
+++ b/docs/src/content/docs/coming-from/wordpress.mdx
@@ -348,29 +348,27 @@ WordPress hooks (`add_action`, `add_filter`) become EmDash plugin hooks:
 
 <CardGrid>
 	<Card title="Type Safety" icon="seti:typescript">
-		TypeScript throughout. Collections, queries, and components are fully typed. No more guessing
-		field names or return types.
+		TypeScript throughout. Collections, queries, and components are fully typed, so field names and
+		return types autocomplete and are checked at build time.
 	</Card>
 	<Card title="Performance" icon="rocket">
-		No PHP overhead. Static generation by default. Server rendering when needed. Edge deployment
-		ready.
+		Static generation by default, with server rendering when needed. Edge deployment ready.
 	</Card>
 	<Card title="Modern DX" icon="laptop">
 		Hot module replacement. Component-based architecture. Modern tooling (Vite, TypeScript, ESLint).
 	</Card>
 	<Card title="Git-based Deployments" icon="github">
-		Code and templates in git. Content in the database. No FTP, no file permissions, no hacked
-		sites.
+		Code and templates live in git; content lives in the database. Deploy by pushing code.
 	</Card>
 </CardGrid>
 
 ### Preview Links
 
-EmDash generates secure preview URLs with HMAC-signed tokens. Content editors can preview drafts without logging into production—share a link, not credentials.
+EmDash generates secure preview URLs with HMAC-signed tokens. Content editors share a preview link to show a draft, so reviewers can see it without a production login.
 
-### No Plugin Conflicts
+### Isolated Plugins
 
-WordPress plugin conflicts disappear. EmDash plugins run in isolated contexts with explicit APIs. No global state pollution.
+EmDash plugins run in isolated contexts with explicit APIs. Each plugin reaches only the APIs it declares, so plugins do not share or overwrite each other's global state.
 
 ## Content Editor Experience
 
diff --git a/docs/src/content/docs/concepts/architecture.mdx b/docs/src/content/docs/concepts/architecture.mdx
index ec566cdf7..b12cfa321 100644
--- a/docs/src/content/docs/concepts/architecture.mdx
+++ b/docs/src/content/docs/concepts/architecture.mdx
@@ -38,7 +38,7 @@ You define collections and fields — in the admin panel or with the CLI — and
 		Add, rename, remove, or retype collections and fields whenever you need
 		to. Changes take effect immediately.
 	</Card>
-	<Card title="No developer required" icon="seti:plan">
+	<Card title="Editor-designed" icon="seti:plan">
 		A content editor can design the whole model through the admin UI.
 	</Card>
 	<Card title="Typed" icon="approve-check">
@@ -55,7 +55,7 @@ See the [content model](/concepts/content-model/) for how to define, change, typ
 
 ## Content is live
 
-EmDash serves content through Astro's Live Collections, so changes an editor makes are visible immediately without a static rebuild. You read content with two functions:
+EmDash serves content through Astro's Live Collections at runtime, so changes an editor makes are visible immediately. You read content with two functions:
 
 ```ts title="src/pages/blog.astro"
 import { getEmDashCollection, getEmDashEntry } from "emdash";
diff --git a/docs/src/content/docs/concepts/collections.mdx b/docs/src/content/docs/concepts/collections.mdx
index f0f16fd50..4fb577885 100644
--- a/docs/src/content/docs/concepts/collections.mdx
+++ b/docs/src/content/docs/concepts/collections.mdx
@@ -6,7 +6,7 @@ description: Define content types with collections and fields—supported field
 import { Aside, Card, CardGrid, Tabs, TabItem } from "@astrojs/starlight/components";
 import contentTypesImg from "../../../assets/screenshots/admin-content-types.png";
 
-Collections are the foundation of EmDash's content model. Each collection represents a content type (posts, pages, products) and contains field definitions that determine the shape of your data.
+A collection is a content type (posts, pages, products). Its field definitions set the shape of each entry's data.
 
 ## Creating collections
 
diff --git a/docs/src/content/docs/contributing/translating.mdx b/docs/src/content/docs/contributing/translating.mdx
index 857d55fed..46f946abb 100644
--- a/docs/src/content/docs/contributing/translating.mdx
+++ b/docs/src/content/docs/contributing/translating.mdx
@@ -15,7 +15,7 @@ See the [translation dashboard](https://i18n.emdashcms.com) for current progress
 
 Every translation must be supervised by a **native or fluent speaker**. AI-generated translations are accepted, but only when a fluent speaker reviews every string and previews it in the running admin panel before submitting. Unsupervised machine output is not accepted. See [AI-assisted translations](#ai-assisted-translations) and [Testing your translations](#testing-your-translations) below.
 
-No translation is better than a bad one. A wrong translation is worse than showing the English fallback — it actively misleads users.
+Leaving a string untranslated is better than translating it wrongly. A wrong translation misleads users; the English fallback only inconveniences them.
 
 ## File structure
 
diff --git a/docs/src/content/docs/deployment/cloudflare.mdx b/docs/src/content/docs/deployment/cloudflare.mdx
index 4a62cfaea..63e68aa26 100644
--- a/docs/src/content/docs/deployment/cloudflare.mdx
+++ b/docs/src/content/docs/deployment/cloudflare.mdx
@@ -149,11 +149,11 @@ See the [Authentication guide](/guides/authentication#cloudflare-access) for ful
 
 ### Recommended: encryption key
 
-`EMDASH_ENCRYPTION_KEY` is used to encrypt plugin secrets at rest
-(webhook tokens, Turnstile keys, etc.). The current release validates
-the key but does not yet use it — plugin secret encryption is rolling
-out and will start using this value automatically when available. Set
-it now so your deployment is ready.
+`EMDASH_ENCRYPTION_KEY` is the key for encrypting plugin secrets at
+rest (webhook tokens, Turnstile keys, etc.). The key is validated on
+startup; plugin secret encryption uses it once enabled. Set it on
+every deployment so secrets are protected without a later config
+change.
 
 The key is provided by you and never stored in the database; only
 encrypted ciphertext is. Losing it means losing every secret encrypted
@@ -184,7 +184,7 @@ needs to share the secret with your main site.
 | -------- | ------- |
 | `EMDASH_PREVIEW_SECRET` | Override for the auto-generated preview HMAC secret. |
 | `EMDASH_IP_SALT` | Override for the auto-generated commenter-IP hash salt. |
-| `EMDASH_AUTH_SECRET` | Legacy. No longer required. If set, it's used as the IP-salt source (unless `EMDASH_IP_SALT` is also set, which wins) so existing installs keep stable commenter-IP hashes across the upgrade. New installs should ignore this. |
+| `EMDASH_AUTH_SECRET` | Optional. If set, it is used as the IP-salt source (unless `EMDASH_IP_SALT` is also set, which takes precedence), keeping commenter-IP hashes stable for installs that already rely on it. Leave it unset for a new deployment. |
 
 Access environment variables in your configuration using `import.meta.env` or the Cloudflare `env` binding.
 
diff --git a/docs/src/content/docs/deployment/nodejs.mdx b/docs/src/content/docs/deployment/nodejs.mdx
index b79103902..63b3081b7 100644
--- a/docs/src/content/docs/deployment/nodejs.mdx
+++ b/docs/src/content/docs/deployment/nodejs.mdx
@@ -150,10 +150,10 @@ docker compose up -d
 
 ### Recommended: encryption key
 
-`EMDASH_ENCRYPTION_KEY` is used to encrypt plugin secrets at rest. The
-current release validates the key but does not yet use it — plugin
-secret encryption is rolling out and will start using this value
-automatically when available. Set it now so your deployment is ready.
+`EMDASH_ENCRYPTION_KEY` is the key for encrypting plugin secrets at
+rest. The key is validated on startup; plugin secret encryption uses
+it once enabled. Set it on every deployment so secrets are protected
+without a later config change.
 
 Generate a key and add the result to your environment:
 
@@ -177,7 +177,7 @@ process needs to share a secret with your main site.
 | -------- | ----------- |
 | `EMDASH_PREVIEW_SECRET` | Override for the auto-generated preview HMAC secret. |
 | `EMDASH_IP_SALT` | Override for the auto-generated commenter-IP hash salt. |
-| `EMDASH_AUTH_SECRET` | Legacy. No longer required. If set, used as the IP-salt source (unless `EMDASH_IP_SALT` is also set, which wins) so existing installs keep stable commenter-IP hashes across the upgrade. New installs should ignore this. |
+| `EMDASH_AUTH_SECRET` | Optional. If set, used as the IP-salt source (unless `EMDASH_IP_SALT` is also set, which takes precedence), keeping commenter-IP hashes stable for installs that already rely on it. Leave it unset for a new deployment. |
 
 ### Database and Storage
 
diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx
index babadbed6..c11d99b38 100644
--- a/docs/src/content/docs/getting-started.mdx
+++ b/docs/src/content/docs/getting-started.mdx
@@ -111,7 +111,7 @@ Once your passkey is registered, you're logged in and redirected to the admin da
 </Steps>
 
 <Aside type="tip">
-	EmDash uses Live Content Collections. Changes appear immediately without rebuilding your site.
+	EmDash uses Live Content Collections, so content is served at runtime and edits appear immediately.
 </Aside>
 
 ## Project Structure
diff --git a/docs/src/content/docs/guides/atmosphere-auth.mdx b/docs/src/content/docs/guides/atmosphere-auth.mdx
index e86e44187..095a3ac11 100644
--- a/docs/src/content/docs/guides/atmosphere-auth.mdx
+++ b/docs/src/content/docs/guides/atmosphere-auth.mdx
@@ -42,7 +42,7 @@ export default defineConfig({
 
 That's enough to put **Sign in with Atmosphere** on the login page and the setup wizard. With no allowlist configured, the first user becomes Admin and self-signup is closed for everyone after that — see [allowlists](#allowlists) to open it up.
 
-No environment variables, client secret, or OAuth-app registration is required. The provider is a public OAuth client and serves its own metadata document at `/.well-known/atproto-client-metadata.json`.
+The provider is a public OAuth client and serves its own metadata document at `/.well-known/atproto-client-metadata.json`, so it works with the configuration above alone — no environment variables, client secret, or OAuth-app registration to set up.
 
 ## Configuration
 
@@ -127,7 +127,7 @@ Then open `http://127.0.0.1:4321/_emdash/admin` for the whole flow.
 
 ## Production
 
-There's nothing extra to configure for production. The provider serves its own client metadata at:
+The same configuration works in production. The provider serves its own client metadata at:
 
 ```
 https://your-site.example.com/.well-known/atproto-client-metadata.json
diff --git a/docs/src/content/docs/guides/internationalization.mdx b/docs/src/content/docs/guides/internationalization.mdx
index 7e0e638ad..3f36044b5 100644
--- a/docs/src/content/docs/guides/internationalization.mdx
+++ b/docs/src/content/docs/guides/internationalization.mdx
@@ -11,7 +11,7 @@ Each translation is a full, independent content entry with its own slug, status,
 
 ## Configuration
 
-Enable i18n by adding an `i18n` block to your Astro config. EmDash reads this configuration automatically — there is no separate locale setup in EmDash.
+Enable i18n by adding an `i18n` block to your Astro config. EmDash reads this same configuration for its locale list, default locale, and fallback chain.
 
 ```js title="astro.config.mjs"
 import { defineConfig } from "astro/config";
@@ -56,7 +56,7 @@ This design means:
 - **Per-locale slugs** — `/blog/my-post` and `/fr/blog/mon-article` work naturally
 - **Per-locale publishing** — publish the English version while keeping French in draft
 - **Per-locale revisions** — each translation has its own revision history
-- **No cross-locale query complexity** — list queries return entries for one locale only
+- **Single-locale queries** — list queries return entries for one locale only
 
 ## Querying Translated Content
 
@@ -89,7 +89,7 @@ When no content exists for the requested locale, EmDash follows the fallback cha
 2. Try the fallback locale (`en`)
 3. Try the default locale
 
-Fallback only applies to single-entry queries. List queries return entries for the requested locale only — no cross-locale mixing.
+Fallback only applies to single-entry queries. List queries return entries for the requested locale only.
 
 <Aside>
   When a fallback is used, the response metadata includes `fallbackLocale` so your template can display a "this content is not yet translated" notice.
diff --git a/docs/src/content/docs/guides/page-layouts.mdx b/docs/src/content/docs/guides/page-layouts.mdx
index db2a4299b..f8e76297f 100644
--- a/docs/src/content/docs/guides/page-layouts.mdx
+++ b/docs/src/content/docs/guides/page-layouts.mdx
@@ -5,7 +5,7 @@ description: Let editors choose different layouts for individual pages using a t
 
 import { Aside } from '@astrojs/starlight/components';
 
-WordPress has "Page Templates" — a dropdown in the editor that lets you pick a layout per page (e.g. Default, Full Width, Landing Page). EmDash supports the same pattern using a `select` field.
+Let editors pick a layout per page (e.g. Default, Full Width, Landing Page) from a dropdown in the editor, using a `select` field mapped to layout components in your page route.
 
 ## How it works
 
@@ -13,7 +13,7 @@ WordPress has "Page Templates" — a dropdown in the editor that lets you pick a
 2. Create layout components for each option
 3. Map the field value to a layout in your page route
 
-No special system is needed — this uses EmDash's existing select field and Astro's component model.
+This uses EmDash's select field and Astro's component model.
 
 ## Add the field
 
@@ -134,7 +134,7 @@ Use human-readable option names like "Full Width" rather than slugs like "full-w
 
 ## Adding more layouts
 
-Common choices from WordPress themes:
+Common layout choices:
 
 - **Default** — narrow content column, good for reading
 - **Full Width** — wider content area, no sidebar
diff --git a/docs/src/content/docs/guides/preview.mdx b/docs/src/content/docs/guides/preview.mdx
index a99bea685..6ddddf92c 100644
--- a/docs/src/content/docs/guides/preview.mdx
+++ b/docs/src/content/docs/guides/preview.mdx
@@ -14,13 +14,13 @@ EmDash's preview system lets editors view unpublished content through secure, ti
 3. EmDash's middleware automatically verifies the token and sets up the request context
 4. Your template code calls `getEmDashEntry()` as normal — draft content is served automatically
 
-Preview is **implicit**. Your template code doesn't need to handle tokens or pass preview options — the middleware and query functions handle everything via `AsyncLocalStorage`.
+Preview is **implicit**. The middleware verifies the token and the query functions read it through `AsyncLocalStorage`, so the same template code serves draft content during a preview and published content otherwise.
 
 ## Setting Up Preview
 
-Preview works out of the box — EmDash auto-generates a per-site preview
-secret on first use and stores it in the database. No env vars required
-for the common case.
+Preview works as soon as EmDash is installed. On first use, EmDash
+generates a per-site preview secret and stores it in the database, so
+the common case needs no configuration.
 
 Set `EMDASH_PREVIEW_SECRET` in your environment only if you need to:
 
diff --git a/docs/src/content/docs/guides/querying-content.mdx b/docs/src/content/docs/guides/querying-content.mdx
index b192bd6ba..03718063d 100644
--- a/docs/src/content/docs/guides/querying-content.mdx
+++ b/docs/src/content/docs/guides/querying-content.mdx
@@ -250,7 +250,7 @@ Every entry returned by query functions includes an `edit` proxy for annotating
 </article>
 ```
 
-In edit mode, `{...entry.edit.title}` produces a `data-emdash-ref` attribute that the visual editing toolbar uses to enable inline editing. In production, the proxy spreads produce no output — zero runtime cost.
+In edit mode, `{...entry.edit.title}` produces a `data-emdash-ref` attribute that the visual editing toolbar uses to enable inline editing. In production, the proxy spreads produce no output.
 
 <Aside type="tip">
 	For string and text fields, inline editing uses `contenteditable`. For Portable Text fields, it
diff --git a/docs/src/content/docs/guides/sections.mdx b/docs/src/content/docs/guides/sections.mdx
index 2964831aa..b1626038f 100644
--- a/docs/src/content/docs/guides/sections.mdx
+++ b/docs/src/content/docs/guides/sections.mdx
@@ -85,11 +85,7 @@ Editors insert sections using the `/section` slash command in the rich text edit
 
 </Steps>
 
-The section's Portable Text content is copied into the document. This means:
-
-- Changes to the section don't affect already-inserted content
-- Editors can customize the inserted content
-- Content remains self-contained
+The section's Portable Text content is copied into the document. The inserted content is self-contained: editors can customize it, and later changes to the section do not affect copies already placed in content.
 
 <Aside type="tip">
   For content that should stay synchronized, consider using [Widget Areas](/guides/widgets/) with component widgets instead.
diff --git a/docs/src/content/docs/guides/x402-payments.mdx b/docs/src/content/docs/guides/x402-payments.mdx
index 84f4e1e7c..a029488c6 100644
--- a/docs/src/content/docs/guides/x402-payments.mdx
+++ b/docs/src/content/docs/guides/x402-payments.mdx
@@ -5,7 +5,7 @@ description: Monetize content with the x402 payment protocol — charge bots, no
 
 import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
 
-The `@emdash-cms/x402` package adds [x402 payment protocol](https://www.x402.org/) support to any Astro site on Cloudflare. It works standalone — no dependency on EmDash core — but pairs well with EmDash's CMS fields for per-page pricing.
+The `@emdash-cms/x402` package adds [x402 payment protocol](https://www.x402.org/) support to any Astro site on Cloudflare. It runs as a standalone Astro integration, and pairs with EmDash's CMS fields for per-page pricing when you use EmDash.
 
 x402 is an HTTP-native payment protocol. When a client requests a paid resource without payment, the server responds with `402 Payment Required` and machine-readable payment instructions. Agents and browsers that understand x402 can complete payment automatically and retry the request.
 
@@ -126,7 +126,7 @@ x402.applyHeaders(result, Astro.response);
 
 ## Per-Page Pricing with EmDash
 
-When using EmDash, you can add a `number` field to your collection for per-page pricing. No special schema or admin UI is needed — just a regular CMS field:
+When using EmDash, add a regular `number` field to your collection for per-page pricing and read it at request time:
 
 ```astro title="src/pages/posts/[...slug].astro"
 ---
diff --git a/docs/src/content/docs/introduction.mdx b/docs/src/content/docs/introduction.mdx
index 12188a9da..6e27c6f43 100644
--- a/docs/src/content/docs/introduction.mdx
+++ b/docs/src/content/docs/introduction.mdx
@@ -20,22 +20,22 @@ EmDash is a CMS built specifically for [Astro](https://astro.build). It uses Ast
 
 ## What EmDash Is Not
 
-- **Not a headless CMS** — EmDash is tightly integrated with Astro. It's not a separate service you call via API.
-- **Not WordPress-compatible** — No PHP, no WordPress plugins running directly. But WordPress content and concepts migrate cleanly.
-- **Not a page builder** — EmDash focuses on structured content. For visual page building, use Astro components.
+- **Not a headless CMS** — EmDash is tightly integrated with Astro and runs in the same deployment, rather than as a separate service you call over an API.
+- **Not WordPress-compatible** — It does not run PHP or WordPress plugins. WordPress content and concepts migrate to EmDash equivalents.
+- **Not a page builder** — EmDash manages structured content. Build visual layouts with Astro components.
 
 ## Who EmDash Is For
 
 <CardGrid>
 	<Card title="Agency developers" icon="laptop">
-		Spin up client sites quickly with reusable plugins and themes. No PHP security updates, no
-		plugin conflicts.
+		Spin up client sites quickly with reusable plugins and themes. Plugins run in isolated contexts
+		with explicit APIs.
 	</Card>
 	<Card title="Solo developers" icon="seti:todo">
-		Full-stack framework with CMS built in. No separate headless CMS to manage.
+		Content management is part of the Astro site, deployed and managed as one project.
 	</Card>
 	<Card title="Content editors" icon="pencil">
-		Intuitive admin panel. Create and edit content without touching code.
+		Create and edit content in the admin panel.
 	</Card>
 	<Card title="WordPress users" icon="right-arrow">
 		Migration path for content and plugins. Modern tooling, familiar concepts.
@@ -60,7 +60,7 @@ The following diagram shows how EmDash sits inside an Astro site, connecting the
 │  │                                                       │  │
 │  │  ┌───────────────────────────────────────────────────┐│  │
 │  │  │                  Data Layer                       ││  │
-│  │  │    SQLite/D1      ←→  Kysely  ←→  R2/S3/Local    ││  │
+│  │  │   Database (SQLite/D1)   +   Storage (R2/S3/local)││  │
 │  │  └───────────────────────────────────────────────────┘│  │
 │  └───────────────────────────────────────────────────────┘  │
 │                                                             │
diff --git a/docs/src/content/docs/migration/content-import.mdx b/docs/src/content/docs/migration/content-import.mdx
index 1b464e48a..c5ee4cef8 100644
--- a/docs/src/content/docs/migration/content-import.mdx
+++ b/docs/src/content/docs/migration/content-import.mdx
@@ -5,7 +5,7 @@ description: Import content from WordPress and other sources into EmDash.
 
 import { Aside, Card, CardGrid, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
 
-The EmDash import system is built on pluggable sources. Each source probes, analyzes, and fetches content from a specific platform.
+EmDash imports content from WordPress and other platforms. Each import source detects a platform, analyzes its content, and fetches it into your site.
 
 ## Import Sources
 
diff --git a/docs/src/content/docs/migration/from-wordpress.mdx b/docs/src/content/docs/migration/from-wordpress.mdx
index f23019a0b..5ad098162 100644
--- a/docs/src/content/docs/migration/from-wordpress.mdx
+++ b/docs/src/content/docs/migration/from-wordpress.mdx
@@ -5,7 +5,7 @@ description: Import your WordPress content into EmDash with a step-by-step guide
 
 import { Aside, Card, CardGrid, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
 
-EmDash provides a complete migration path from WordPress. Import your posts, pages, media, and taxonomies through the admin dashboard—no CLI required.
+EmDash migrates content from WordPress. Import your posts, pages, media, and taxonomies through the admin dashboard.
 
 ## Before You Begin
 
diff --git a/docs/src/content/docs/plugins/creating-native-plugins/distributing.mdx b/docs/src/content/docs/plugins/creating-native-plugins/distributing.mdx
index 4b4944c93..c749306db 100644
--- a/docs/src/content/docs/plugins/creating-native-plugins/distributing.mdx
+++ b/docs/src/content/docs/plugins/creating-native-plugins/distributing.mdx
@@ -5,7 +5,7 @@ description: Package and ship a native plugin via npm.
 
 import { Aside } from "@astrojs/starlight/components";
 
-Native plugins distribute via npm, not the marketplace. There's no bundler, no manifest, no security audit step — just a regular npm package that exports a descriptor factory plus `createPlugin`. Site operators install it with `npm install` and register it in `astro.config.mjs`.
+Native plugins distribute via npm. A native plugin is a regular npm package that exports a descriptor factory plus `createPlugin`. Site operators install it with `npm install` and register it in `astro.config.mjs`.
 
 ## Package layout
 
diff --git a/docs/src/content/docs/plugins/creating-native-plugins/page-fragments.mdx b/docs/src/content/docs/plugins/creating-native-plugins/page-fragments.mdx
index be4f1ec4a..a8ad4b0f6 100644
--- a/docs/src/content/docs/plugins/creating-native-plugins/page-fragments.mdx
+++ b/docs/src/content/docs/plugins/creating-native-plugins/page-fragments.mdx
@@ -180,4 +180,4 @@ If what you actually need is:
 - A canonical or alternate `<link>` → `page:metadata` with `kind: "link"`.
 - A JSON-LD graph → `page:metadata` with `kind: "jsonld"`.
 
-`page:metadata` works in sandboxed plugins, gets validation and deduplication for free, and avoids the trust burden of shipping raw HTML to visitors. Reach for `page:fragments` only when you genuinely need to ship JavaScript or HTML.
+`page:metadata` works in sandboxed plugins, gets validation and deduplication for free, and avoids the trust burden of shipping raw HTML to visitors. Reach for `page:fragments` only when you need to ship JavaScript or HTML.
diff --git a/docs/src/content/docs/plugins/creating-native-plugins/your-first-native-plugin.mdx b/docs/src/content/docs/plugins/creating-native-plugins/your-first-native-plugin.mdx
index 14365043b..e5d42847f 100644
--- a/docs/src/content/docs/plugins/creating-native-plugins/your-first-native-plugin.mdx
+++ b/docs/src/content/docs/plugins/creating-native-plugins/your-first-native-plugin.mdx
@@ -5,9 +5,9 @@ description: Build a native EmDash plugin with the descriptor + createPlugin pat
 
 import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
 
-This guide walks through building a native plugin from scratch. Native plugins run in the same process as your Astro site — no sandbox boundary, full access to the runtime, and access to features the sandbox can't provide (React admin pages, Portable Text components, page fragments).
+This guide walks through building a native plugin from scratch. Native plugins run in the same process as your Astro site with full access to the runtime, including React admin pages, Portable Text components, and page fragments.
 
-If you haven't decided yet whether you want a native plugin instead of a sandboxed one, read [Choosing a plugin format](/plugins/creating-plugins/choosing-a-format/) first. The native path is for the cases where the sandbox genuinely can't do what you need.
+If you haven't decided yet whether you want a native plugin instead of a sandboxed one, read [Choosing a plugin format](/plugins/creating-plugins/choosing-a-format/) first. Native is the format for plugins that need React admin pages, Portable Text rendering components, or page fragments.
 
 ## Two pieces, in one or two files
 
@@ -145,7 +145,7 @@ export default createPlugin;
 
 Key details of this configuration:
 
-- **`format: "native"` is required.** The default would otherwise be `"native"` too — but being explicit on every descriptor makes it easy to spot which format you're working with.
+- **`format: "native"` is required.** `"native"` is also the default, but stating it explicitly on every descriptor makes the format easy to spot.
 - **`entrypoint` is the package's main export.** EmDash imports it at runtime and calls the default export to construct the resolved plugin.
 - **`options` flow descriptor → `createPlugin`.** Anything the user passes when registering the plugin (`analyticsPlugin({ enabled: false })`) is preserved on the descriptor and forwarded to `createPlugin`. Sandboxed plugins don't have this surface — they read settings from KV instead.
 - **`id`, `version`, and `capabilities` appear twice.** Once on the descriptor, once on `definePlugin()`. They should match. The descriptor's copy is what `astro.config.mjs` sees at build time; the `definePlugin()` copy is what runs at request time.
diff --git a/docs/src/content/docs/plugins/field-kit.mdx b/docs/src/content/docs/plugins/field-kit.mdx
index 7cce52eeb..9c9a88584 100644
--- a/docs/src/content/docs/plugins/field-kit.mdx
+++ b/docs/src/content/docs/plugins/field-kit.mdx
@@ -5,7 +5,7 @@ description: Composable field widgets for json fields, configured through seed o
 
 import { Aside } from "@astrojs/starlight/components";
 
-EmDash's `json` field type stores arbitrary structured data, but the default editor is a single-line text input where you have to type raw JSON by hand. **Field Kit** is a first-party plugin that ships four composable widgets for `json` fields, configured entirely through seed `options` — no React required from site builders.
+EmDash's `json` field type stores arbitrary structured data, edited by default through a single-line text input that takes raw JSON. **Field Kit** is a first-party plugin that ships four composable widgets for `json` fields, configured entirely through seed `options` so site builders can use them with seed schema alone.
 
 <Aside type="tip">
 Field Kit widgets store **clean JSON**: the stored value is plain content data, so removing the plugin leaves valid content behind.
@@ -234,7 +234,7 @@ Renders rows like `Flour — 500g`. The template is plain string substitution 
 
 ## Data durability
 
-Field Kit widgets store plain JSON in the field's existing column. There are no plugin-specific tables, no foreign keys, no schema mutation. If you remove `@emdash-cms/plugin-field-kit` from your config, the data stays valid — only the editing UI changes back to the default `json` text input.
+Field Kit widgets store plain JSON in the field's existing column, using only that column. If you remove `@emdash-cms/plugin-field-kit` from your config, the data stays valid — the field reverts to the default `json` text input.
 
 This applies even when you change the widget shape: unknown keys on stored objects are preserved on the next write, so you can evolve a schema without losing data captured under an older field set.
 
diff --git a/docs/src/content/docs/plugins/overview.mdx b/docs/src/content/docs/plugins/overview.mdx
index af8841160..b941f78a3 100644
--- a/docs/src/content/docs/plugins/overview.mdx
+++ b/docs/src/content/docs/plugins/overview.mdx
@@ -5,7 +5,7 @@ description: Extend EmDash with hooks, storage, settings, admin pages, and API r
 
 import { Aside, Card, CardGrid, LinkCard } from "@astrojs/starlight/components";
 
-Plugins extend EmDash without modifying core code. They can react to content lifecycle events, store their own data, expose settings to administrators, add pages to the admin panel, and serve API routes.
+Plugins extend EmDash through a defined extension surface. They can react to content lifecycle events, store their own data, expose settings to administrators, add pages to the admin panel, and serve API routes.
 
 ## What plugins can do
 
@@ -34,8 +34,8 @@ Plugins extend EmDash without modifying core code. They can react to content lif
 
 EmDash plugins come in two formats:
 
-- **Sandboxed plugins** run in an isolated runtime managed by a configurable sandbox runner. They can be installed from the marketplace with one click, are subject to capability and resource enforcement, and can't reach anything they didn't explicitly declare. This is the recommended choice for most plugins.
-- **Native plugins** run in the same process as your Astro site. They have full access to the runtime, can ship React admin pages and Portable Text rendering components, and inject HTML into public pages — but can't be published to the marketplace and require a code change plus a deploy to install.
+- **Sandboxed plugins** run in an isolated runtime managed by a configurable sandbox runner. They can be installed from the marketplace with one click, are subject to capability and resource enforcement, and reach only the APIs they declare. This is the recommended choice for most plugins.
+- **Native plugins** run in the same process as your Astro site. They have full access to the runtime, can ship React admin pages and Portable Text rendering components, and inject HTML into public pages. They install via a code change plus a deploy, and run from npm rather than the marketplace.
 
 If you're installing a plugin someone else built, you almost always want sandboxed. If you're building one yourself, see [Choosing a plugin format](/plugins/creating-plugins/choosing-a-format/).
 
diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx
index a3e67980f..152a38743 100644
--- a/docs/src/content/docs/reference/configuration.mdx
+++ b/docs/src/content/docs/reference/configuration.mdx
@@ -534,7 +534,7 @@ Node process starts. Explicit values always take precedence.
 
 **Prerequisite:** install `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`
 in your project. EmDash core does not bundle the AWS SDK. See
-[Storage Options → S3-Compatible Storage](/deployment/storage/#s3-compatible-storage)
+[Storage Options: S3-Compatible Storage](/deployment/storage/#s3-compatible-storage)
 for details.
 
 | Option            | Type     | Description                         |
diff --git a/docs/src/content/docs/reference/hooks.mdx b/docs/src/content/docs/reference/hooks.mdx
index 7f445e563..b67cf7388 100644
--- a/docs/src/content/docs/reference/hooks.mdx
+++ b/docs/src/content/docs/reference/hooks.mdx
@@ -331,7 +331,7 @@ interface CronEvent {
 
 ## Email Hooks
 
-Email hooks form a pipeline: `email:beforeSend` → `email:deliver` → `email:afterSend`.
+Email hooks run in order: `email:beforeSend`, then `email:deliver`, then `email:afterSend`.
 
 ### `email:beforeSend`
 
@@ -404,7 +404,7 @@ hooks: {
 
 ## Comment Hooks
 
-Comment hooks form a pipeline: `comment:beforeCreate` → `comment:moderate` → `comment:afterCreate`. The `comment:afterModerate` hook fires separately when an admin changes a comment's status.
+Comment hooks run in order: `comment:beforeCreate`, then `comment:moderate`, then `comment:afterCreate`. The `comment:afterModerate` hook fires separately when an admin changes a comment's status.
 
 ### `comment:beforeCreate`
 
diff --git a/docs/src/content/docs/themes/porting-wp-themes.mdx b/docs/src/content/docs/themes/porting-wp-themes.mdx
index e67378ac0..63983774e 100644
--- a/docs/src/content/docs/themes/porting-wp-themes.mdx
+++ b/docs/src/content/docs/themes/porting-wp-themes.mdx
@@ -447,7 +447,7 @@ WordPress 5.9+ block themes use `theme.json` for design tokens and `templates/*.
 
 ### Page Builders
 
-Content built with Elementor, Divi, or similar is stored in post meta, not theme files. This content imports via WXR, not theme porting. Focus theme porting on the shell—page builder content renders through Portable Text after import.
+Content built with Elementor, Divi, or similar is stored in post meta, not theme files. This content imports via WXR, not theme porting. Focus theme porting on the shell. Page builder content renders through Portable Text after import.
 
 ## Next Steps
 
diff --git a/docs/src/content/docs/why-emdash.mdx b/docs/src/content/docs/why-emdash.mdx
index 8d80fc0f0..ce477da8b 100644
--- a/docs/src/content/docs/why-emdash.mdx
+++ b/docs/src/content/docs/why-emdash.mdx
@@ -11,7 +11,7 @@ EmDash is a CMS built for Astro. It gives editors an admin interface, serves con
 
 ### Astro-Native Architecture
 
-EmDash is built specifically for Astro, not adapted from a generic CMS. Content lives in the same deployment as your site, queried through Astro's Live Content Collections. No separate services, no API round-trips, no webhook synchronization.
+EmDash is built specifically for Astro, not adapted from a generic CMS. Content lives in the same deployment as your site and is queried through Astro's Live Content Collections within the same process.
 
 ### Familiar Content Model
 

From db97c078bae25485de8ff62d35a2acd01af6c024 Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sat, 16 May 2026 13:32:22 +0100
Subject: [PATCH 5/8] docs: fix factual errors found auditing claims against
 source

Verified each against packages/* source:
- getSections returns { items, nextCursor }, not Section[] (sections guide, api ref)
- removed fictional getSectionCategories / getSections({category}) from API ref
- getEmDashEntry options param, getSiteSetting("title"), isPreviewRequest/getPreviewToken take URL, search() returns { items } (api ref)
- content create flag is --draft (+ --locale/--translation-of), not --status (cli ref)
- r2/d1 import from @emdash-cms/cloudflare not emdash/astro|emdash/db; emdashLoader() takes no args; fonts list missing farsi (config ref)
- hook page:metadata link.rel allowlist + jsonld graph union (hooks ref)
- field type count 16 not 14; added url/repeater rows; corrected reserved field slugs (field-types ref, collections)
- REST: admin plugin paths, PUT not PATCH for collection/field/user updates, search response envelope, error codes (rest-api ref)
- MCP: 45 tools not 43, role requirements, error-envelope shape (mcp ref)
- media-library/architecture r2/local import paths; menus getMenus includes locale; widgets post.data.slug; admin-panel roles (no 'Developer' role)
---
 .../src/content/docs/concepts/admin-panel.mdx | 10 +----
 .../content/docs/concepts/architecture.mdx    |  3 +-
 .../src/content/docs/concepts/collections.mdx |  8 ++--
 .../src/content/docs/guides/media-library.mdx |  3 +-
 docs/src/content/docs/guides/menus.mdx        |  4 +-
 docs/src/content/docs/guides/sections.mdx     |  6 ++-
 docs/src/content/docs/guides/widgets.mdx      |  2 +-
 docs/src/content/docs/reference/api.mdx       | 33 +++++++-------
 docs/src/content/docs/reference/cli.mdx       | 16 ++++---
 .../content/docs/reference/configuration.mdx  | 17 +++----
 .../content/docs/reference/field-types.mdx    | 13 +++++-
 docs/src/content/docs/reference/hooks.mdx     | 14 +++++-
 .../src/content/docs/reference/mcp-server.mdx | 25 ++++++-----
 docs/src/content/docs/reference/rest-api.mdx  | 44 ++++++++++---------
 14 files changed, 112 insertions(+), 86 deletions(-)

diff --git a/docs/src/content/docs/concepts/admin-panel.mdx b/docs/src/content/docs/concepts/admin-panel.mdx
index 519d80e79..3af6c4d2e 100644
--- a/docs/src/content/docs/concepts/admin-panel.mdx
+++ b/docs/src/content/docs/concepts/admin-panel.mdx
@@ -27,15 +27,9 @@ Navigation is generated from your collections and installed plugins, so a schema
 
 ## Roles
 
-What a user sees depends on their role:
+What a user sees depends on their role. EmDash has five roles, from least to most access: Subscriber, Contributor, Author, Editor, Admin. See [User roles](/guides/authentication/#user-roles) for the full definitions.
 
-| Role      | Can access                                              |
-| --------- | ------------------------------------------------------- |
-| Editor    | Dashboard, assigned collections, media                  |
-| Admin     | The above, plus all collections, content types, settings |
-| Developer | The above, plus CLI access and generated types          |
-
-Editors only see the content they have permission to manage. The schema builder at `/content-types` is administrator-only.
+In the admin, lower roles see only the content they have permission to manage. The schema builder at `/content-types` and the settings screens are Admin-only. Type generation and the CLI are available to developers working on the project regardless of admin role.
 
 <Aside type="note">
 	The admin requires a signed-in user. Login is a separate page that
diff --git a/docs/src/content/docs/concepts/architecture.mdx b/docs/src/content/docs/concepts/architecture.mdx
index b12cfa321..fe8fdc69d 100644
--- a/docs/src/content/docs/concepts/architecture.mdx
+++ b/docs/src/content/docs/concepts/architecture.mdx
@@ -72,9 +72,8 @@ You pass a database and a storage backend to the integration. Everything else ha
 
 ```ts title="astro.config.mjs"
 import { defineConfig } from "astro/config";
-import emdash from "emdash/astro";
+import emdash, { local } from "emdash/astro";
 import { sqlite } from "emdash/db";
-import { local } from "emdash/storage";
 
 export default defineConfig({
 	integrations: [
diff --git a/docs/src/content/docs/concepts/collections.mdx b/docs/src/content/docs/concepts/collections.mdx
index 4fb577885..6e70f43d1 100644
--- a/docs/src/content/docs/concepts/collections.mdx
+++ b/docs/src/content/docs/concepts/collections.mdx
@@ -52,7 +52,7 @@ The following collection enables all four features:
 
 ## Field types
 
-EmDash supports 14 field types that map to SQLite column types.
+EmDash supports 16 field types that map to SQLite column types.
 
 ### Text fields
 
@@ -213,7 +213,7 @@ Every field supports these properties:
 | -------------- | ----------- | -------------------------------------------- |
 | `slug`         | `string`    | Column name in the database                  |
 | `label`        | `string`    | Display label in admin UI                    |
-| `type`         | `FieldType` | One of the 14 field types                    |
+| `type`         | `FieldType` | One of the 16 field types                    |
 | `required`     | `boolean`   | Whether the field must have a value          |
 | `unique`       | `boolean`   | Whether values must be unique across entries |
 | `defaultValue` | `unknown`   | Default value for new entries                |
@@ -225,7 +225,7 @@ Every field supports these properties:
 <Aside type="caution">
 	Some field slugs are reserved and cannot be used: `id`, `slug`, `status`, `author_id`,
 	`primary_byline_id`, `created_at`, `updated_at`, `published_at`, `scheduled_at`, `deleted_at`,
-	`version`, `live_revision_id`, `draft_revision_id`.
+	`version`, `live_revision_id`, `draft_revision_id`, `terms`, `bylines`, `byline`.
 </Aside>
 
 ## Validation rules
@@ -355,6 +355,7 @@ Field types map to SQLite column types as follows:
 | `string`       | `TEXT`      |                       |
 | `text`         | `TEXT`      |                       |
 | `slug`         | `TEXT`      |                       |
+| `url`          | `TEXT`      |                       |
 | `number`       | `REAL`      | 64-bit floating point |
 | `integer`      | `INTEGER`   | 64-bit signed integer |
 | `boolean`      | `INTEGER`   | 0 or 1                |
@@ -366,6 +367,7 @@ Field types map to SQLite column types as follows:
 | `file`         | `TEXT`      | Media ID              |
 | `reference`    | `TEXT`      | Entry ID              |
 | `json`         | `JSON`      | Arbitrary JSON        |
+| `repeater`     | `JSON`      | Array of sub-fields   |
 
 ## Next steps
 
diff --git a/docs/src/content/docs/guides/media-library.mdx b/docs/src/content/docs/guides/media-library.mdx
index 9a6636cb2..3f6838182 100644
--- a/docs/src/content/docs/guides/media-library.mdx
+++ b/docs/src/content/docs/guides/media-library.mdx
@@ -79,7 +79,8 @@ Files are stored in the `./uploads` directory. Suitable for development and sing
   <TabItem label="Cloudflare R2">
 ```js title="astro.config.mjs"
 import { defineConfig } from "astro/config";
-import emdash, { r2 } from "emdash/astro";
+import emdash from "emdash/astro";
+import { r2 } from "@emdash-cms/cloudflare";
 
 export default defineConfig({
   integrations: [
diff --git a/docs/src/content/docs/guides/menus.mdx b/docs/src/content/docs/guides/menus.mdx
index daf8f1eb8..ecaea1ea7 100644
--- a/docs/src/content/docs/guides/menus.mdx
+++ b/docs/src/content/docs/guides/menus.mdx
@@ -135,7 +135,7 @@ Use `getMenus()` to retrieve all menu definitions (without items):
 import { getMenus } from "emdash";
 
 const menus = await getMenus();
-// Returns: [{ id, name, label }, ...]
+// Returns: [{ id, name, label, locale }, ...]
 ```
 
 This is primarily useful for admin interfaces or debugging.
@@ -278,4 +278,4 @@ Fetch a menu by name with all items and resolved URLs.
 
 List all menu definitions without items.
 
-**Returns:** `Promise<Array<{ id: string; name: string; label: string }>>`
+**Returns:** `Promise<Array<{ id: string; name: string; label: string; locale: string }>>`
diff --git a/docs/src/content/docs/guides/sections.mdx b/docs/src/content/docs/guides/sections.mdx
index b1626038f..252b83aac 100644
--- a/docs/src/content/docs/guides/sections.mdx
+++ b/docs/src/content/docs/guides/sections.mdx
@@ -202,9 +202,11 @@ List sections with optional filters.
 
 **Parameters:**
 - `options.source` — Filter by source: `"theme"`, `"user"`, or `"import"`
-- `options.search` — Search title and keywords
+- `options.search` — Search title, description, and keywords
+- `options.limit` — Page size (default 50, max 100)
+- `options.cursor` — Pagination cursor from a previous `nextCursor`
 
-**Returns:** `Promise<Section[]>`
+**Returns:** `Promise<{ items: Section[]; nextCursor?: string }>`
 
 ## REST API
 
diff --git a/docs/src/content/docs/guides/widgets.mdx b/docs/src/content/docs/guides/widgets.mdx
index 9728bb078..791e69543 100644
--- a/docs/src/content/docs/guides/widgets.mdx
+++ b/docs/src/content/docs/guides/widgets.mdx
@@ -207,7 +207,7 @@ const { entries: posts } = await getEmDashCollection("posts", {
       {showThumbnails && post.data.featured_image && (
         <img src={post.data.featured_image} alt="" class="thumbnail" />
       )}
-      <a href={`/posts/${post.slug}`}>{post.data.title}</a>
+      <a href={`/posts/${post.data.slug}`}>{post.data.title}</a>
       {showDate && post.data.publishedAt && (
         <time datetime={post.data.publishedAt.toISOString()}>
           {post.data.publishedAt.toLocaleDateString()}
diff --git a/docs/src/content/docs/reference/api.mdx b/docs/src/content/docs/reference/api.mdx
index 9fec57a8e..59ed84125 100644
--- a/docs/src/content/docs/reference/api.mdx
+++ b/docs/src/content/docs/reference/api.mdx
@@ -104,8 +104,9 @@ if (!post) {
 | ------------ | -------- | ---------------- |
 | `collection` | `string` | Collection slug  |
 | `slugOrId`   | `string` | Entry slug or ID |
+| `options`    | `{ locale?: string }` | Optional. Locale for slug resolution |
 
-Preview mode is handled automatically — the middleware detects `_preview` tokens and serves draft content via `AsyncLocalStorage`. No options parameter is needed.
+Preview mode is handled automatically — the middleware detects `_preview` tokens and serves draft content via `AsyncLocalStorage`. The optional `options` parameter only accepts a `locale` for slug resolution; preview state requires no parameter.
 
 #### Returns
 
@@ -347,8 +348,8 @@ Check whether a request includes a preview token, then read it:
 ```ts
 import { isPreviewRequest, getPreviewToken } from "emdash";
 
-if (isPreviewRequest(Astro.request)) {
-	const token = getPreviewToken(Astro.request);
+if (isPreviewRequest(Astro.url)) {
+	const token = getPreviewToken(Astro.url);
 	// Verify and show preview content
 }
 ```
@@ -378,7 +379,7 @@ import { getSiteSettings, getSiteSetting } from "emdash";
 const settings = await getSiteSettings();
 
 // Get single setting
-const title = await getSiteSetting("siteTitle");
+const title = await getSiteSetting("title");
 ```
 
 Settings are read-only from the runtime API. Use the admin API to update them.
@@ -447,26 +448,24 @@ if (sidebar) {
 
 ## Sections
 
-Fetch sections, filter them, and read their categories:
+Fetch sections and filter them:
 
 ```ts
-import { getSection, getSections, getSectionCategories } from "emdash";
+import { getSection, getSections } from "emdash";
 
-// Get all sections
-const sections = await getSections();
+// Get all sections (paginated)
+const { items, nextCursor } = await getSections();
 
 // Filter sections
-const heroes = await getSections({ category: "hero" });
-const themeSections = await getSections({ source: "theme" });
-const results = await getSections({ search: "newsletter" });
+const { items: themeSections } = await getSections({ source: "theme" });
+const { items: results } = await getSections({ search: "newsletter" });
 
-// Get single section
+// Get a single section by slug
 const cta = await getSection("newsletter-cta");
-
-// Get categories
-const categories = await getSectionCategories();
 ```
 
+`getSections(options?)` returns `{ items: Section[]; nextCursor?: string }`. Options are `source` (`"theme" | "user" | "import"`), `search`, `limit` (default 50, max 100), and `cursor`.
+
 ## Search
 
 Run a global search or a collection-specific search. Results include highlighted snippets:
@@ -481,8 +480,8 @@ const results = await search("hello world", {
 	limit: 20,
 });
 
-// Results include snippets with highlights
-results.forEach(result => {
+// search() resolves to { items, nextCursor? }
+results.items.forEach(result => {
 	console.log(result.title);
 	console.log(result.snippet); // Contains <mark> tags
 	console.log(result.score);
diff --git a/docs/src/content/docs/reference/cli.mdx b/docs/src/content/docs/reference/cli.mdx
index 0e33536a5..ba1c98ab8 100644
--- a/docs/src/content/docs/reference/cli.mdx
+++ b/docs/src/content/docs/reference/cli.mdx
@@ -212,13 +212,15 @@ cat post.json | npx emdash content create posts --stdin
 
 | Option     | Description                    |
 | ---------- | ------------------------------ |
-| `--data`   | JSON string with content data  |
-| `--file`   | Read data from a JSON file     |
-| `--stdin`  | Read data from stdin           |
-| `--slug`   | Content slug                   |
-| `--status` | Initial status (draft, published) |
-
-Provide data via exactly one of `--data`, `--file`, or `--stdin`.
+| `--data`            | JSON string with content data                          |
+| `--file`            | Read data from a JSON file                             |
+| `--stdin`           | Read data from stdin                                   |
+| `--slug`            | Content slug                                           |
+| `--locale`          | Content locale                                         |
+| `--translation-of`  | ID of a content item to link this as a translation of  |
+| `--draft`           | Keep as draft instead of auto-publishing               |
+
+Provide data via exactly one of `--data`, `--file`, or `--stdin`. New items are auto-published unless `--draft` is set.
 
 #### `content update <collection> <id>`
 
diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx
index 152a38743..8a7b8ea31 100644
--- a/docs/src/content/docs/reference/configuration.mdx
+++ b/docs/src/content/docs/reference/configuration.mdx
@@ -13,8 +13,8 @@ Configure EmDash as an Astro integration in `astro.config.mjs`:
 
 ```js title="astro.config.mjs"
 import { defineConfig } from "astro/config";
-import emdash, { local, r2, s3 } from "emdash/astro";
-import { sqlite, libsql, d1 } from "emdash/db";
+import emdash, { local, s3 } from "emdash/astro";
+import { sqlite, libsql } from "emdash/db";
 
 export default defineConfig({
 	integrations: [
@@ -114,7 +114,7 @@ emdash({
 })
 ```
 
-The available scripts are `arabic`, `armenian`, `bengali`, `chinese-simplified`, `chinese-traditional`, `chinese-hongkong`, `devanagari`, `ethiopic`, `georgian`, `gujarati`, `gurmukhi`, `hebrew`, `japanese`, `kannada`, `khmer`, `korean`, `lao`, `malayalam`, `myanmar`, `oriya`, `sinhala`, `tamil`, `telugu`, `thai`, and `tibetan`.
+The available scripts are `arabic`, `armenian`, `bengali`, `chinese-simplified`, `chinese-traditional`, `chinese-hongkong`, `devanagari`, `ethiopic`, `farsi`, `georgian`, `gujarati`, `gurmukhi`, `hebrew`, `japanese`, `kannada`, `khmer`, `korean`, `lao`, `malayalam`, `myanmar`, `oriya`, `sinhala`, `tamil`, `telugu`, `thai`, and `tibetan`.
 
 Each script maps to the corresponding Noto Sans variant on Google Fonts (e.g. `"arabic"` loads Noto Sans Arabic). All font faces share a single `font-family` name and use `unicode-range` so the browser only downloads the files it needs for the characters on the page.
 
@@ -407,7 +407,7 @@ Uploads that exceed the configured limit are rejected with a `413 Payload Too La
 Import the adapters from `emdash/db`:
 
 ```js
-import { sqlite, libsql, postgres, d1 } from "emdash/db";
+import { sqlite, libsql, postgres } from "emdash/db";
 ```
 
 ### `sqlite(config)`
@@ -488,10 +488,11 @@ When `session` is `"auto"` or `"primary-first"`, EmDash uses the D1 Sessions API
 
 ## Storage adapters
 
-Import the adapters from `emdash/astro`:
+Import `local` and `s3` from `emdash/astro`. The `r2` adapter is imported from `@emdash-cms/cloudflare`:
 
 ```js
-import emdash, { local, r2, s3 } from "emdash/astro";
+import emdash, { local, s3 } from "emdash/astro";
+import { r2 } from "@emdash-cms/cloudflare";
 ```
 
 ### `local(config)`
@@ -589,10 +590,10 @@ export const collections = {
 
 ### Loader options
 
-The `emdashLoader()` function accepts an optional configuration object, reserved for future use:
+The `emdashLoader()` function takes no arguments:
 
 ```ts
-emdashLoader({});
+emdashLoader();
 ```
 
 ## Environment variables
diff --git a/docs/src/content/docs/reference/field-types.mdx b/docs/src/content/docs/reference/field-types.mdx
index 10d43fbf4..7ffad4e70 100644
--- a/docs/src/content/docs/reference/field-types.mdx
+++ b/docs/src/content/docs/reference/field-types.mdx
@@ -5,7 +5,7 @@ description: Complete reference for all EmDash field types.
 
 import { Aside } from "@astrojs/starlight/components";
 
-EmDash supports 14 field types for defining content schemas. Each type maps to a SQLite column type and provides appropriate admin UI.
+EmDash supports 16 field types for defining content schemas. Each type maps to a SQLite column type and provides appropriate admin UI.
 
 ## Overview
 
@@ -15,6 +15,7 @@ The following table lists every field type and its SQLite column:
 | -------------- | ------------- | -------------------------- |
 | `string`       | TEXT          | Short text input           |
 | `text`         | TEXT          | Multi-line text            |
+| `url`          | TEXT          | URL value                  |
 | `number`       | REAL          | Decimal number             |
 | `integer`      | INTEGER       | Whole number               |
 | `boolean`      | INTEGER       | True/false                 |
@@ -27,6 +28,7 @@ The following table lists every field type and its SQLite column:
 | `reference`    | TEXT          | Reference to another entry |
 | `json`         | JSON          | Arbitrary JSON data        |
 | `slug`         | TEXT          | URL-safe identifier        |
+| `repeater`     | JSON          | Repeating group of fields  |
 
 ## Text Types
 
@@ -398,11 +400,18 @@ These slugs are reserved and cannot be used:
 - `slug`
 - `status`
 - `author_id`
+- `primary_byline_id`
 - `created_at`
 - `updated_at`
 - `published_at`
+- `scheduled_at`
 - `deleted_at`
 - `version`
+- `live_revision_id`
+- `draft_revision_id`
+- `terms`
+- `bylines`
+- `byline`
 
 ## TypeScript types
 
@@ -414,6 +423,7 @@ import type { FieldType, Field, CreateFieldInput } from "emdash";
 const fieldTypes: FieldType[] = [
 	"string",
 	"text",
+	"url",
 	"number",
 	"integer",
 	"boolean",
@@ -426,5 +436,6 @@ const fieldTypes: FieldType[] = [
 	"reference",
 	"json",
 	"slug",
+	"repeater",
 ];
 ```
diff --git a/docs/src/content/docs/reference/hooks.mdx b/docs/src/content/docs/reference/hooks.mdx
index b67cf7388..c680878ba 100644
--- a/docs/src/content/docs/reference/hooks.mdx
+++ b/docs/src/content/docs/reference/hooks.mdx
@@ -556,8 +556,18 @@ hooks: {
 type PageMetadataContribution =
 	| { kind: "meta"; name: string; content: string; key?: string }
 	| { kind: "property"; property: string; content: string; key?: string }
-	| { kind: "link"; rel: string; href: string; hreflang?: string; key?: string }
-	| { kind: "jsonld"; id?: string; graph: Record<string, unknown> };
+	| {
+			kind: "link";
+			rel: "canonical" | "alternate" | "author" | "license" | "nlweb" | "site.standard.document";
+			href: string;
+			hreflang?: string;
+			key?: string;
+	  }
+	| {
+			kind: "jsonld";
+			id?: string;
+			graph: Record<string, unknown> | Array<Record<string, unknown>>;
+	  };
 ```
 
 The `key` field deduplicates contributions — only the last contribution with a given key is used.
diff --git a/docs/src/content/docs/reference/mcp-server.mdx b/docs/src/content/docs/reference/mcp-server.mdx
index b85540120..f8963a0b8 100644
--- a/docs/src/content/docs/reference/mcp-server.mdx
+++ b/docs/src/content/docs/reference/mcp-server.mdx
@@ -54,7 +54,8 @@ In addition to scopes, some tools require a minimum RBAC role. Both must be sati
 | Operation | Minimum role |
 | --- | --- |
 | Content read | Subscriber (10) for published items; Contributor (20) for drafts, scheduled, trash, and revisions |
-| Content create / edit own / delete own | Author (30) |
+| Content create | Contributor (20) |
+| Content edit own / delete own | Author (30) |
 | Content publish | Author (30) for own items; Editor (40) to act on others' items |
 | Schema read | Editor (40) |
 | Schema write | Admin (50) |
@@ -78,7 +79,7 @@ Responses follow the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) forma
 
 ## Tools
 
-The server exposes 43 tools across eight domains: content, schema, media, search, taxonomies, menus, revisions, and settings. Each tool returns results as JSON text content, or an error message with `isError: true` on failure.
+The server exposes 45 tools across eight domains: content, schema, media, search, taxonomies, menus, revisions, and settings. Each tool returns results as JSON text content, or an error message with `isError: true` on failure.
 
 ### Content Tools
 
@@ -746,25 +747,25 @@ This triggers the standard MCP client discovery flow.
 
 ## Error Handling
 
-Tool errors are returned as text content with `isError: true`:
+Tool errors are returned as text content with `isError: true`. The message is prefixed with a stable `[CODE]`, and the same code is repeated in `_meta.code`:
 
 ```json
 {
-  "content": [{ "type": "text", "text": "Collection 'nonexistent' not found" }],
-  "isError": true
+  "content": [{ "type": "text", "text": "[NOT_FOUND] Collection 'nonexistent' not found" }],
+  "isError": true,
+  "_meta": { "code": "NOT_FOUND" }
 }
 ```
 
-Scope and permission errors throw MCP protocol errors:
+Scope and permission errors use the same tool error envelope:
 
 ```json
 {
-  "jsonrpc": "2.0",
-  "error": {
-    "code": -32600,
-    "message": "Insufficient scope: requires content:write"
-  },
-  "id": 1
+  "content": [
+    { "type": "text", "text": "[INSUFFICIENT_SCOPE] Insufficient scope: requires content:write" }
+  ],
+  "isError": true,
+  "_meta": { "code": "INSUFFICIENT_SCOPE" }
 }
 ```
 
diff --git a/docs/src/content/docs/reference/rest-api.mdx b/docs/src/content/docs/reference/rest-api.mdx
index db7455192..1e38e9c00 100644
--- a/docs/src/content/docs/reference/rest-api.mdx
+++ b/docs/src/content/docs/reference/rest-api.mdx
@@ -382,7 +382,7 @@ Content-Type: application/json
 ### Update Collection
 
 ```http
-PATCH /_emdash/api/schema/collections/:slug
+PUT /_emdash/api/schema/collections/:slug
 Content-Type: application/json
 ```
 
@@ -428,7 +428,7 @@ Content-Type: application/json
 ### Update Field
 
 ```http
-PATCH /_emdash/api/schema/collections/:collectionSlug/fields/:fieldSlug
+PUT /_emdash/api/schema/collections/:collectionSlug/fields/:fieldSlug
 Content-Type: application/json
 ```
 
@@ -476,25 +476,25 @@ Returns TypeScript interfaces for all collections.
 ### List Plugins
 
 ```http
-GET /_emdash/api/plugins
+GET /_emdash/api/admin/plugins
 ```
 
 ### Get Plugin
 
 ```http
-GET /_emdash/api/plugins/:pluginId
+GET /_emdash/api/admin/plugins/:id
 ```
 
 ### Enable Plugin
 
 ```http
-POST /_emdash/api/plugins/:pluginId/enable
+POST /_emdash/api/admin/plugins/:id/enable
 ```
 
 ### Disable Plugin
 
 ```http
-POST /_emdash/api/plugins/:pluginId/disable
+POST /_emdash/api/admin/plugins/:id/disable
 ```
 
 ## Error Codes
@@ -511,8 +511,8 @@ POST /_emdash/api/plugins/:pluginId/disable
 | `CONTENT_DELETE_ERROR` | 500         | Failed to delete content |
 | `MEDIA_LIST_ERROR`     | 500         | Failed to list media     |
 | `MEDIA_CREATE_ERROR`   | 500         | Failed to create media   |
-| `SCHEMA_ERROR`         | 400         | Schema operation failed  |
-| `DUPLICATE_SLUG`       | 409         | Slug already exists      |
+| `SCHEMA_CREATE_ERROR`  | 500         | Schema operation failed  |
+| `SLUG_CONFLICT`        | 409         | Slug already exists      |
 | `RESERVED_SLUG`        | 400         | Slug is reserved         |
 
 ## Search Endpoints
@@ -537,17 +537,21 @@ GET /_emdash/api/search?q=hello+world
 
 ```json
 {
-  "results": [
-    {
-      "collection": "posts",
-      "id": "01HXK5MZSN...",
-      "slug": "hello-world",
-      "title": "Hello World",
-      "snippet": "...this is a <mark>hello</mark> <mark>world</mark> example...",
-      "score": 0.95
-    }
-  ],
-  "nextCursor": "eyJvZmZzZXQiOjIwfQ"
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "collection": "posts",
+        "id": "01HXK5MZSN...",
+        "slug": "hello-world",
+        "locale": "en",
+        "title": "Hello World",
+        "snippet": "...this is a <mark>hello</mark> <mark>world</mark> example...",
+        "score": 0.95
+      }
+    ],
+    "nextCursor": "eyJvZmZzZXQiOjIwfQ"
+  }
 }
 ```
 
@@ -859,7 +863,7 @@ GET /_emdash/api/admin/users/:id
 ### Update User
 
 ```http
-PATCH /_emdash/api/admin/users/:id
+PUT /_emdash/api/admin/users/:id
 Content-Type: application/json
 
 {

From 788a8daf7a5d0a00ff0431b709d63c099680e8c5 Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sat, 16 May 2026 13:42:23 +0100
Subject: [PATCH 6/8] docs: remove hallucinated APIs flagged in correctness
 audit

Confirmed against source as non-existent (not planned, not drift-to-real):
- auth config object { selfSignup, session, cloudflareAccess }: emdash({auth})
  takes an adapter (access() from @emdash-cms/cloudflare). Rewrote the
  configuration + authentication auth sections to the real AuthDescriptor /
  access() surface with accurate AccessConfig options; removed the invented
  selfSignup/session config; pointed self-signup at the real provider allowlists.
- reference/api.mdx: removed Database functions / Repositories / Schema
  registry sections (createDatabase is not a public export and there is no
  public Kysely handle) and the searchCollection example (wrong signature,
  needs a non-public db arg). Kept the verified-public search().
- guides/internationalization: removed the fictional 'emdash import wordpress
  --locale --translation-of-locale' (no import CLI command/flags); point to
  the real admin import flow + content create --locale --translation-of.
- configuration.mdx: dropped package.json emdash.description / emdash.preview
  (not read by any code; label/seed/url are).
---
 .../content/docs/guides/authentication.mdx    |  39 +----
 .../docs/guides/internationalization.mdx      |  16 +-
 docs/src/content/docs/reference/api.mdx       | 150 +-----------------
 .../content/docs/reference/configuration.mdx  | 101 +++---------
 4 files changed, 35 insertions(+), 271 deletions(-)

diff --git a/docs/src/content/docs/guides/authentication.mdx b/docs/src/content/docs/guides/authentication.mdx
index 364ca5f20..f9eeb01bc 100644
--- a/docs/src/content/docs/guides/authentication.mdx
+++ b/docs/src/content/docs/guides/authentication.mdx
@@ -260,44 +260,13 @@ Each user can have up to 10 passkeys registered.
 	log in.
 </Aside>
 
-## Self-Signup
+## Letting a group sign in without invites
 
-For team sites, you can enable self-signup for specific email domains:
+To let a group sign in without inviting each user, configure a [login provider](#login-providers) with an allowlist. The Atmosphere provider accepts `allowedHandles` and `allowedDIDs` (see [Atmosphere login](/guides/atmosphere-auth/)); the [Cloudflare Access](#cloudflare-access) adapter provisions users from your identity provider via `autoProvision` and `roleMapping`. Any configured provider can also create the initial admin account.
 
-```js title="astro.config.mjs"
-import { defineConfig } from "astro/config";
-import emdash from "emdash/astro";
+## Sessions
 
-export default defineConfig({
-	integrations: [
-		emdash({
-			auth: {
-				selfSignup: {
-					domains: ["example.com"],
-					defaultRole: "contributor",
-				},
-			},
-		}),
-	],
-});
-```
-
-Users with matching email domains can sign up without an invite. They'll receive a verification email and register a passkey to complete signup.
-
-## Session Configuration
-
-Sessions use secure HttpOnly cookies with sensible defaults:
-
-```js title="astro.config.mjs"
-emdash({
-	auth: {
-		session: {
-			maxAge: 30 * 24 * 60 * 60, // 30 days (default)
-			sliding: true, // Reset expiry on activity
-		},
-	},
-});
-```
+Sessions use secure, HttpOnly, SameSite=Lax cookies and last 30 days with sliding expiration — the expiry resets on activity.
 
 ## Security Notes
 
diff --git a/docs/src/content/docs/guides/internationalization.mdx b/docs/src/content/docs/guides/internationalization.mdx
index 3f36044b5..1c853ccdd 100644
--- a/docs/src/content/docs/guides/internationalization.mdx
+++ b/docs/src/content/docs/guides/internationalization.mdx
@@ -362,22 +362,16 @@ Use `getRelativeLocaleUrl` from `astro:i18n` to build correct URLs regardless of
 
 ## Importing Multilingual Content
 
-### WordPress with WPML or Polylang
+Import WordPress content through the admin migration tool — see [Content Import](/migration/content-import/) and [Migrate from WordPress](/migration/from-wordpress/). A WXR export does not carry the locale and translation-group structure that WPML or Polylang add, so imported content lands in your default locale.
 
-The WordPress plugin import source detects WPML and Polylang automatically. When detected, imported content includes locale and translation group metadata, preserving the multilingual structure.
-
-### WXR files
-
-WXR exports do not include WPML/Polylang metadata. Import as a single locale and create translations manually, or use the `--locale` flag to assign a locale to all imported items:
+To build translations from imported content, create the translated entry and link it to the original:
 
 ```bash
-# Import a French WXR export
-emdash import wordpress export-fr.xml --execute --locale fr
-
-# Match against existing English content by slug
-emdash import wordpress export-fr.xml --execute --locale fr --translation-of-locale en
+emdash content create posts --locale fr --translation-of 01ABC...
 ```
 
+This is the same `--locale` / `--translation-of` workflow shown in [Seeding multilingual content](#seeding-multilingual-content) above, applied after the import completes.
+
 ## Next Steps
 
 - [Querying Content](/guides/querying-content/) — Full query API reference
diff --git a/docs/src/content/docs/reference/api.mdx b/docs/src/content/docs/reference/api.mdx
index 59ed84125..1b334fa16 100644
--- a/docs/src/content/docs/reference/api.mdx
+++ b/docs/src/content/docs/reference/api.mdx
@@ -5,7 +5,7 @@ description: Programmatic API for querying and managing EmDash content.
 
 import { Aside } from "@astrojs/starlight/components";
 
-EmDash exports functions for querying content, managing media, and working with the database.
+EmDash exports functions for querying content and working with preview, settings, menus, taxonomies, widget areas, sections, and search.
 
 ## Content queries
 
@@ -169,144 +169,6 @@ The `data` object contains all content fields plus system fields:
 - `publishedAt` - ISO timestamp or null
 - Plus all custom fields defined in your collection schema
 
-## Database functions
-
-### `createDatabase()`
-
-Create a database connection. The following example connects to a local SQLite file:
-
-```ts
-import { createDatabase } from "emdash";
-
-const db = createDatabase({ url: "file:./data.db" });
-```
-
-<Aside type="caution">
-	Direct database access is for advanced use cases. Prefer the query functions for content access.
-</Aside>
-
-### `runMigrations()`
-
-Run pending database migrations. The following example applies migrations and logs the count:
-
-```ts
-import { createDatabase, runMigrations } from "emdash";
-
-const db = createDatabase({ url: "file:./data.db" });
-const { applied } = await runMigrations(db);
-console.log(`Applied ${applied.length} migrations`);
-```
-
-### `getMigrationStatus()`
-
-Check which migrations have been applied and which are pending:
-
-```ts
-import { createDatabase, getMigrationStatus } from "emdash";
-
-const db = createDatabase({ url: "file:./data.db" });
-const status = await getMigrationStatus(db);
-// { applied: ["0001_core", ...], pending: [] }
-```
-
-## Repositories
-
-Low-level data access through repositories.
-
-### `ContentRepository`
-
-The following example shows the full set of `ContentRepository` operations:
-
-```ts
-import { ContentRepository, createDatabase } from "emdash";
-
-const db = createDatabase({ url: "file:./data.db" });
-const repo = new ContentRepository(db);
-
-// Find many
-const { items, nextCursor } = await repo.findMany("posts", {
-	limit: 10,
-	where: { status: "published" },
-});
-
-// Find by ID
-const post = await repo.findById("posts", "01HXK5MZSN...");
-
-// Create
-const newPost = await repo.create({
-	type: "posts",
-	slug: "new-post",
-	data: { title: "New Post", content: [] },
-	status: "draft",
-});
-
-// Update
-const updated = await repo.update("posts", "01HXK5MZSN...", {
-	data: { title: "Updated Title" },
-});
-
-// Delete
-await repo.delete("posts", "01HXK5MZSN...");
-```
-
-### `MediaRepository`
-
-The following example lists, fetches, and records media:
-
-```ts
-import { MediaRepository, createDatabase } from "emdash";
-
-const db = createDatabase({ url: "file:./data.db" });
-const repo = new MediaRepository(db);
-
-// List media
-const { items } = await repo.findMany({ limit: 20 });
-
-// Get by ID
-const media = await repo.findById("01HXK5MZSN...");
-
-// Create (after upload)
-const newMedia = await repo.create({
-	filename: "photo.jpg",
-	mimeType: "image/jpeg",
-	size: 12345,
-	storageKey: "uploads/photo.jpg",
-});
-```
-
-## Schema registry
-
-Programmatic schema management. The following example lists collections, then creates a collection and a field:
-
-```ts
-import { SchemaRegistry, createDatabase } from "emdash";
-
-const db = createDatabase({ url: "file:./data.db" });
-const registry = new SchemaRegistry(db);
-
-// List collections
-const collections = await registry.listCollections();
-
-// Get collection with fields
-const postsSchema = await registry.getCollectionWithFields("posts");
-
-// Create collection
-await registry.createCollection({
-	slug: "products",
-	label: "Products",
-	labelSingular: "Product",
-	supports: ["drafts", "revisions"],
-});
-
-// Add field
-await registry.createField("products", {
-	slug: "price",
-	label: "Price",
-	type: "number",
-	required: true,
-});
-```
-
 ## Preview system
 
 ### `generatePreviewToken()`
@@ -468,12 +330,11 @@ const cta = await getSection("newsletter-cta");
 
 ## Search
 
-Run a global search or a collection-specific search. Results include highlighted snippets:
+Run a global search across collections. Results include highlighted snippets:
 
 ```ts
-import { search, searchCollection } from "emdash";
+import { search } from "emdash";
 
-// Global search across collections
 const results = await search("hello world", {
 	collections: ["posts", "pages"],
 	status: "published",
@@ -486,11 +347,6 @@ results.items.forEach(result => {
 	console.log(result.snippet); // Contains <mark> tags
 	console.log(result.score);
 });
-
-// Collection-specific search
-const posts = await searchCollection("posts", "typescript", {
-	limit: 10,
-});
 ```
 
 ## Error handling
diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx
index 8a7b8ea31..96a9b92ee 100644
--- a/docs/src/content/docs/reference/configuration.mdx
+++ b/docs/src/content/docs/reference/configuration.mdx
@@ -130,62 +130,38 @@ The admin CSS uses the `--font-emdash` CSS variable. This is set automatically b
 
 ### `auth`
 
-**Optional.** Authentication configuration. The following example shows self-signup, sessions, and Cloudflare Access together:
+**Optional.** An authentication adapter. EmDash's built-in login is passkeys; setting `auth` replaces them with an external provider. The Cloudflare Access adapter, `access()`, is provided by `@emdash-cms/cloudflare`:
 
 ```js
-import { github } from "emdash/auth/providers/github";
-import { google } from "emdash/auth/providers/google";
-import { atproto } from "@emdash-cms/auth-atproto";
+import { access } from "@emdash-cms/cloudflare";
 
 emdash({
-	auth: {
-		// Self-signup configuration
-		selfSignup: {
-			domains: ["example.com"],
-			defaultRole: 20, // Contributor
-		},
-
-		// Session configuration
-		session: {
-			maxAge: 30 * 24 * 60 * 60, // 30 days
-			sliding: true, // Reset expiry on activity
-		},
-
-		// OR use Cloudflare Access (exclusive mode)
-		cloudflareAccess: {
-			teamDomain: "myteam.cloudflareaccess.com",
-			audience: "your-app-audience-tag",
-			autoProvision: true,
-			defaultRole: 30,
-			syncRoles: false,
-			roleMapping: {
-				Admins: 50,
-				Editors: 40,
-			},
+	auth: access({
+		teamDomain: "myteam.cloudflareaccess.com",
+		audience: "your-app-audience-tag",
+		roleMapping: {
+			Admins: 50,
+			Editors: 40,
 		},
-	},
-	// Pluggable login providers (top-level, not nested under `auth`)
-	authProviders: [github(), google(), atproto()],
+	}),
 });
 ```
 
-#### `auth.selfSignup`
+Options for `access()`:
 
-Allow users to self-register if their email domain is allowed.
+| Option           | Type      | Default                | Description                                                                                  |
+| ---------------- | --------- | ---------------------- | -------------------------------------------------------------------------------------------- |
+| `teamDomain`     | `string`  | required               | Your Cloudflare Access team domain                                                           |
+| `audience`       | `string`  | —                      | Application Audience (AUD) tag. On Workers, prefer `audienceEnvVar`.                          |
+| `audienceEnvVar` | `string`  | `"CF_ACCESS_AUDIENCE"` | Environment variable to read the audience tag from at runtime                                |
+| `autoProvision`  | `boolean` | `true`                 | Create an EmDash user on first login                                                         |
+| `defaultRole`    | `number`  | `30`                   | Role level for users not matched by `roleMapping` (see [User roles](/guides/authentication/#user-roles)) |
+| `syncRoles`      | `boolean` | `false`                | Re-apply `roleMapping` on every login instead of only at provisioning                        |
+| `roleMapping`    | `object`  | —                      | Map IdP group names to EmDash role levels; first match wins                                  |
 
-| Option        | Type       | Default | Description               |
-| ------------- | ---------- | ------- | ------------------------- |
-| `domains`     | `string[]` | `[]`    | Allowed email domains     |
-| `defaultRole` | `number`   | `20`    | Role for self-signups     |
-
-The following example allows two domains and assigns the Contributor role:
-
-```js
-selfSignup: {
-  domains: ["example.com", "acme.org"],
-  defaultRole: 20, // Contributor
-}
-```
+<Aside>
+	When an auth adapter is configured it becomes the only auth method: passkeys are disabled.
+</Aside>
 
 ### `authProviders`
 
@@ -209,33 +185,6 @@ Built-in providers:
 
 Third-party packages can register their own providers using the same `AuthProviderDescriptor` shape — see [Login Providers](/guides/authentication/#login-providers).
 
-#### `auth.session`
-
-Session configuration.
-
-| Option    | Type      | Default           | Description                    |
-| --------- | --------- | ----------------- | ------------------------------ |
-| `maxAge`  | `number`  | `2592000` (30d)   | Session lifetime in seconds    |
-| `sliding` | `boolean` | `true`            | Reset expiry on activity       |
-
-#### `auth.cloudflareAccess`
-
-Use Cloudflare Access as the authentication provider instead of passkeys.
-
-| Option          | Type      | Default  | Description                    |
-| --------------- | --------- | -------- | ------------------------------ |
-| `teamDomain`    | `string`  | required | Your Access team domain        |
-| `audience`      | `string`  | required | Application Audience (AUD) tag |
-| `autoProvision` | `boolean` | `true`   | Create users on first login    |
-| `defaultRole`   | `number`  | `30`     | Default role for new users     |
-| `syncRoles`     | `boolean` | `false`  | Update role on each login      |
-| `roleMapping`   | `object`  | —        | Map IdP groups to roles        |
-
-<Aside>
-	When `cloudflareAccess` is configured, it becomes the exclusive auth method. Passkeys, OAuth,
-	magic links, and self-signup are disabled.
-</Aside>
-
 ### `siteUrl`
 
 **Optional.** The public browser-facing origin for the site (scheme + host + optional port, **no path**).
@@ -625,10 +574,8 @@ Templates and sites can declare optional metadata under an `emdash` key in `pack
 {
 	"emdash": {
 		"label": "My Blog Template",
-		"description": "A clean, minimal blog template",
 		"seed": ".emdash/seed.json",
-		"url": "https://my-site.pages.dev",
-		"preview": "https://emdash-blog.pages.dev"
+		"url": "https://my-site.pages.dev"
 	}
 }
 ```
@@ -636,10 +583,8 @@ Templates and sites can declare optional metadata under an `emdash` key in `pack
 | Option        | Description                        |
 | ------------- | ---------------------------------- |
 | `label`       | Template name for display          |
-| `description` | Template description               |
 | `seed`        | Path to seed JSON file             |
 | `url`         | Remote URL for schema sync         |
-| `preview`     | Demo site URL for template preview |
 
 ## TypeScript configuration
 

From 6f6b26f25d470073db6fbf3f936167f9677430f1 Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sat, 16 May 2026 14:39:40 +0100
Subject: [PATCH 7/8] docs: address Copilot review on #1060
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- installing.mdx: fix marketplace + config snippets — default import
  'emdash from emdash/astro', add missing defineConfig import,
  sandboxRunner is a module specifier string not a boolean
  (verified: EmDashConfig.sandboxRunner?: string)
- field-kit.mdx: integration imports from emdash/astro, not emdash
- contributing/docs-style-guide.mdx: 'memorise' -> 'memorize' (US spelling)
- themes/seed-files.mdx: correct the slug-validation summary (slug rules
  differ by type) instead of the misleading 'lowercase, underscores'

Field-type count (field-types/collections, '14' -> '16') was already
fixed in the earlier source-correctness pass; verified still correct.
---
 docs/src/content/docs/contributing/docs-style-guide.mdx | 2 +-
 docs/src/content/docs/plugins/field-kit.mdx             | 2 +-
 docs/src/content/docs/plugins/installing.mdx            | 7 ++++---
 docs/src/content/docs/themes/seed-files.mdx             | 2 +-
 4 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/src/content/docs/contributing/docs-style-guide.mdx b/docs/src/content/docs/contributing/docs-style-guide.mdx
index 87f3d1cd6..4eff9b5f8 100644
--- a/docs/src/content/docs/contributing/docs-style-guide.mdx
+++ b/docs/src/content/docs/contributing/docs-style-guide.mdx
@@ -3,7 +3,7 @@ title: Documentation Style Guide
 description: The writing, structure, and code-sample conventions for EmDash documentation.
 ---
 
-This guide defines how EmDash documentation is written. Contributions are edited to match it. You do not need to memorise it — reviewers and editors will help — but following it makes a contribution merge faster.
+This guide defines how EmDash documentation is written. Contributions are edited to match it. You do not need to memorize it — reviewers and editors will help — but following it makes a contribution merge faster.
 
 Documentation exists to help someone do something, then get back to their project. Write for a reader who is tired, in a hurry, reading in a second language, or new to the stack. Serve that reader above all else.
 
diff --git a/docs/src/content/docs/plugins/field-kit.mdx b/docs/src/content/docs/plugins/field-kit.mdx
index 9c9a88584..4f83bbafa 100644
--- a/docs/src/content/docs/plugins/field-kit.mdx
+++ b/docs/src/content/docs/plugins/field-kit.mdx
@@ -23,7 +23,7 @@ The following configuration registers the plugin:
 
 ```typescript title="astro.config.mjs"
 import { defineConfig } from "astro/config";
-import emdash from "emdash";
+import emdash from "emdash/astro";
 import { fieldKitPlugin } from "@emdash-cms/plugin-field-kit";
 
 export default defineConfig({
diff --git a/docs/src/content/docs/plugins/installing.mdx b/docs/src/content/docs/plugins/installing.mdx
index 85902001a..0d0134b09 100644
--- a/docs/src/content/docs/plugins/installing.mdx
+++ b/docs/src/content/docs/plugins/installing.mdx
@@ -18,13 +18,14 @@ To install marketplace plugins, your site needs:
 1. **Sandbox runner configured** — Marketplace plugins run in an isolated runtime, which requires the sandbox runner. The following configuration enables it:
 
    ```typescript title="astro.config.mjs"
-   import { emdash } from "emdash/astro";
+   import { defineConfig } from "astro/config";
+   import emdash from "emdash/astro";
 
    export default defineConfig({
      integrations: [
        emdash({
          marketplace: "https://marketplace.emdashcms.com",
-         sandboxRunner: true,
+         sandboxRunner: "@emdash-cms/sandbox-cloudflare",
        }),
      ],
    });
@@ -101,7 +102,7 @@ Native plugins — your own code, or packages installed via npm — are added di
 
 ```typescript title="astro.config.mjs"
 import { defineConfig } from "astro/config";
-import { emdash } from "emdash/astro";
+import emdash from "emdash/astro";
 import seoPlugin from "@emdash-cms/plugin-seo";
 
 export default defineConfig({
diff --git a/docs/src/content/docs/themes/seed-files.mdx b/docs/src/content/docs/themes/seed-files.mdx
index 2ceaa23ef..9ce91bf6b 100644
--- a/docs/src/content/docs/themes/seed-files.mdx
+++ b/docs/src/content/docs/themes/seed-files.mdx
@@ -648,7 +648,7 @@ warnings.forEach((w) => console.warn(w));
 Validation checks that:
 
 - Required fields are present
-- Slugs follow naming conventions (lowercase, underscores)
+- Slugs are valid for their type (collection and field slugs allow lowercase letters, digits, and underscores; other slugs also allow hyphens)
 - Field types are valid
 - References point to existing content
 - Hierarchical term parents exist

From 19d513de448b7ece70553701ad4778d3ea484c73 Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sat, 16 May 2026 14:49:51 +0100
Subject: [PATCH 8/8] =?UTF-8?q?docs:=20stop=20presenting=20EmDash=20as=20S?=
 =?UTF-8?q?QLite-only=20=E2=80=94=20PostgreSQL=20is=20a=20first-class=20ad?=
 =?UTF-8?q?apter?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

postgres() is exported from emdash/db alongside sqlite/libsql (verified
in source); only deployment/database + reference/configuration mentioned
it. Corrected the SQLite-only framing in the pages that enumerate
supported databases:

- introduction: 'SQLite-compatible databases (D1, libSQL, local
  SQLite)' / cloud-portable bullets / aside / diagram
- why-emdash: Cloud-Portable card + Cloudflare-deployment intro
- concepts/architecture: diagram + 'what you configure' bullet
- contributing/architecture: Kysely supported-dialect list
- coming-from/astro: two comparison-table cells
- deployment/nodejs: note libSQL/PostgreSQL also work, link to Database Options

Diagram lines re-padded to preserve box alignment. Opinionated SQLite
examples (getting-started, the nodejs walkthrough body) left as-is —
they demonstrate one choice, they don't claim it's the only one.
---
 docs/src/content/docs/coming-from/astro.mdx         |  4 ++--
 docs/src/content/docs/concepts/architecture.mdx     |  4 ++--
 docs/src/content/docs/contributing/architecture.mdx |  2 +-
 docs/src/content/docs/deployment/nodejs.mdx         |  2 +-
 docs/src/content/docs/introduction.mdx              | 10 +++++-----
 docs/src/content/docs/why-emdash.mdx                |  6 +++---
 6 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs/src/content/docs/coming-from/astro.mdx b/docs/src/content/docs/coming-from/astro.mdx
index 07aaf1e51..93e3cf804 100644
--- a/docs/src/content/docs/coming-from/astro.mdx
+++ b/docs/src/content/docs/coming-from/astro.mdx
@@ -16,7 +16,7 @@ EmDash provides the content management features that file-based Astro sites lack
 | Feature              | Description                                          |
 | -------------------- | ---------------------------------------------------- |
 | **Admin UI**         | Full WYSIWYG editing interface at `/_emdash/admin` |
-| **Database storage** | Content stored in SQLite, libSQL, or Cloudflare D1   |
+| **Database storage** | Content stored in SQLite, libSQL, Cloudflare D1, or PostgreSQL |
 | **Media library**    | Upload, organize, and serve images and files         |
 | **Navigation menus** | Drag-and-drop menu management with nesting           |
 | **Widget areas**     | Dynamic sidebars and footer regions                  |
@@ -36,7 +36,7 @@ Astro's `astro:content` collections are file-based and resolved at build time. E
 
 |                    | Astro Collections                    | EmDash Collections                 |
 | ------------------ | ------------------------------------ | ------------------------------------ |
-| **Storage**        | Markdown/MDX files in `src/content/` | SQLite/D1 database                   |
+| **Storage**        | Markdown/MDX files in `src/content/` | SQL database (SQLite, libSQL, D1, or Postgres) |
 | **Editing**        | Code editor                          | Admin UI                             |
 | **Content format** | Markdown with frontmatter            | Portable Text (structured JSON)      |
 | **Updates**        | Requires rebuild                     | Instant (SSR)                        |
diff --git a/docs/src/content/docs/concepts/architecture.mdx b/docs/src/content/docs/concepts/architecture.mdx
index fe8fdc69d..7362d6938 100644
--- a/docs/src/content/docs/concepts/architecture.mdx
+++ b/docs/src/content/docs/concepts/architecture.mdx
@@ -22,7 +22,7 @@ EmDash is an Astro integration. You add it to `astro.config.mjs`, choose a datab
 │   │  (your data)  │◄────►│ /_emdash/admin │   │
 │   └───────────────┘      └────────────────┘   │
 │        │                                      │
-│   Database (SQLite / D1 / libSQL)             │
+│   Database (SQLite / libSQL / D1 / Postgres)  │
 │   Media storage (local / R2 / S3)             │
 └──────────────────────────────────────────────┘
 ```
@@ -85,7 +85,7 @@ export default defineConfig({
 });
 ```
 
-- **Database**: SQLite for local development, Cloudflare D1, or libSQL. See [Database options](/deployment/database/).
+- **Database**: SQLite (local or libSQL), Cloudflare D1, or PostgreSQL. See [Database options](/deployment/database/).
 - **Storage**: the local filesystem, Cloudflare R2, or any S3-compatible storage for media. See [Storage options](/deployment/storage/).
 
 ## Extending with plugins
diff --git a/docs/src/content/docs/contributing/architecture.mdx b/docs/src/content/docs/contributing/architecture.mdx
index 93b37f45c..371cd1210 100644
--- a/docs/src/content/docs/contributing/architecture.mdx
+++ b/docs/src/content/docs/contributing/architecture.mdx
@@ -146,7 +146,7 @@ function buildSchema(fields: Field[]): ZodSchema {
 
 ## Data layer
 
-EmDash uses [Kysely](https://kysely.dev) for type-safe SQL across every supported database (SQLite, Cloudflare D1, libSQL). The dialect is selected by `virtual:emdash/dialect` from the configuration the site passes to the integration.
+EmDash uses [Kysely](https://kysely.dev) for type-safe SQL across every supported database (SQLite, libSQL, Cloudflare D1, and PostgreSQL). The dialect is selected by `virtual:emdash/dialect` from the configuration the site passes to the integration.
 
 ## Live Collections loader
 
diff --git a/docs/src/content/docs/deployment/nodejs.mdx b/docs/src/content/docs/deployment/nodejs.mdx
index 63b3081b7..543990e50 100644
--- a/docs/src/content/docs/deployment/nodejs.mdx
+++ b/docs/src/content/docs/deployment/nodejs.mdx
@@ -5,7 +5,7 @@ description: Deploy EmDash to any Node.js hosting platform.
 
 import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
 
-EmDash runs on any Node.js 22+ hosting platform. This guide covers deployment to common providers using SQLite and local or S3-compatible storage.
+EmDash runs on any Node.js 22+ hosting platform. This guide uses SQLite with local or S3-compatible storage; libSQL and PostgreSQL work the same way on Node.js — see [Database Options](/deployment/database/).
 
 ## Prerequisites
 
diff --git a/docs/src/content/docs/introduction.mdx b/docs/src/content/docs/introduction.mdx
index 6e27c6f43..52970846b 100644
--- a/docs/src/content/docs/introduction.mdx
+++ b/docs/src/content/docs/introduction.mdx
@@ -9,14 +9,14 @@ EmDash is an **Astro-native content management system**. It brings familiar CMS
 
 ## What EmDash Is
 
-EmDash is a CMS built specifically for [Astro](https://astro.build). It uses Astro 6's Live Content Collections to serve content at runtime, so edits appear immediately. Content is stored in SQLite-compatible databases (D1, libSQL, local SQLite) and media in S3-compatible storage (R2, local filesystem).
+EmDash is a CMS built specifically for [Astro](https://astro.build). It uses Astro 6's Live Content Collections to serve content at runtime, so edits appear immediately. Content is stored in a SQL database — SQLite, libSQL, Cloudflare D1, or PostgreSQL — and media in S3-compatible storage (R2 or the local filesystem).
 
 **Key characteristics:**
 
 - **Visual content modelling** — Define and change collections and fields from the admin UI; changes take effect immediately.
 - **Live Collections** — Content is served at runtime, so edits appear immediately.
 - **Plugin system** — WordPress-inspired hooks, storage, settings, and admin UI extensions.
-- **Cloud-portable** — Runs on Cloudflare (Workers + D1 + R2), Node.js, local SQLite, and any S3-compatible storage.
+- **Cloud-portable** — Runs on Cloudflare (Workers + D1 + R2) or Node.js, with SQLite, libSQL, or PostgreSQL and any S3-compatible storage.
 
 ## What EmDash Is Not
 
@@ -60,7 +60,7 @@ The following diagram shows how EmDash sits inside an Astro site, connecting the
 │  │                                                       │  │
 │  │  ┌───────────────────────────────────────────────────┐│  │
 │  │  │                  Data Layer                       ││  │
-│  │  │   Database (SQLite/D1)   +   Storage (R2/S3/local)││  │
+│  │  │Database (SQLite/libSQL/D1/Postgres) + media store ││  │
 │  │  └───────────────────────────────────────────────────┘│  │
 │  └───────────────────────────────────────────────────────┘  │
 │                                                             │
@@ -72,8 +72,8 @@ The following diagram shows how EmDash sits inside an Astro site, connecting the
 ```
 
 <Aside type="tip">
-	EmDash is Astro-native and cloud-portable. It runs on Cloudflare (D1 + R2 + Workers), Node.js,
-	local SQLite, and any S3-compatible storage.
+	EmDash is Astro-native and cloud-portable. It runs on Cloudflare (D1 + R2 + Workers) or Node.js,
+	with SQLite, libSQL, or PostgreSQL and any S3-compatible storage.
 </Aside>
 
 ## Core Concepts
diff --git a/docs/src/content/docs/why-emdash.mdx b/docs/src/content/docs/why-emdash.mdx
index ce477da8b..f7ed76b9f 100644
--- a/docs/src/content/docs/why-emdash.mdx
+++ b/docs/src/content/docs/why-emdash.mdx
@@ -35,8 +35,8 @@ EmDash is purpose-built for Astro. This tight integration enables type-safe quer
 		Built on Astro's Live Content Collections. Content changes appear instantly.
 	</Card>
 	<Card title="Cloud-Portable" icon="setting">
-		Runs on Cloudflare Workers with D1 and R2, and also works with Node.js, SQLite, and any
-		S3-compatible storage.
+		Runs on Cloudflare Workers with D1 and R2, and on Node.js with SQLite, libSQL, or
+		PostgreSQL and any S3-compatible storage.
 	</Card>
 </CardGrid>
 
@@ -55,7 +55,7 @@ Different CMS approaches suit different needs:
 
 ## Cloudflare Deployment
 
-EmDash runs on any platform with SQLite and S3-compatible storage. It also supports Cloudflare-specific features:
+EmDash runs on any platform with a supported SQL database (SQLite, libSQL, or PostgreSQL) and S3-compatible storage. It also supports Cloudflare-specific features:
 
 - **D1** — SQLite at the edge with automatic replication
 - **R2** — S3-compatible storage with no egress fees