diff --git a/apps/web/app/docs/[...slug]/page.tsx b/apps/web/app/docs/[...slug]/page.tsx
index 019aa9a76..4412d1516 100644
--- a/apps/web/app/docs/[...slug]/page.tsx
+++ b/apps/web/app/docs/[...slug]/page.tsx
@@ -52,23 +52,13 @@ export default async function DocumentPage({ params }: PageProps) {
   return (
     <div className="xl:grid xl:grid-cols-[minmax(0,1fr)_13rem] xl:gap-12">
       <article className="min-w-0">
-        <header className="border-b border-border pb-8">
+        <header className="border-b border-border pb-5">
           {section ? (
             <Link href={`/docs#${entry.section}`} className="eyebrow hover:text-fg">
               {section.title}
             </Link>
           ) : null}
-          <h1 className="display mt-2 text-huge leading-[1.06]">{rendered.title ?? entry.title}</h1>
-          <p className="mt-4 max-w-[42rem] text-mid leading-relaxed text-fg-muted text-pretty">
-            {entry.blurb}
-          </p>
-
-          <div className="mt-5 flex flex-wrap items-center gap-x-5 gap-y-2 font-mono text-micro text-fg-subtle">
-            <a className="textlink" href={entry.generated ? '/docs/documentation' : sourceUrl}>
-              {entry.generated ? 'How to update this reference' : 'Edit this page'}
-            </a>
-            {entry.generated ? <span className="chip">generated from the code</span> : null}
-          </div>
+          <h1 className="doc-title mt-2">{rendered.title ?? entry.title}</h1>
         </header>
 
         {rendered.headings.length > 0 ? (
@@ -88,10 +78,16 @@ export default async function DocumentPage({ params }: PageProps) {
           </details>
         ) : null}
 
-        <div className="doc-body mt-10" dangerouslySetInnerHTML={{ __html: rendered.html }} />
+        <div className="doc-body mt-6" dangerouslySetInnerHTML={{ __html: rendered.html }} />
         <CodeCopyButtons />
         <MermaidDiagrams />
 
+        <p className="mt-8 text-sm text-fg-muted">
+          <a className="textlink" href={entry.generated ? '/docs/documentation' : sourceUrl}>
+            {entry.generated ? 'Update this reference' : 'Edit this page'}
+          </a>
+        </p>
+
         <nav aria-label="Nearby documents" className="doc-nav">
           {previous ? (
             <Link href={docHref(previous.slug)} className="doc-nav-link doc-nav-prev">
diff --git a/apps/web/app/docs/layout.tsx b/apps/web/app/docs/layout.tsx
index 94c4dcab6..bb8e0d63b 100644
--- a/apps/web/app/docs/layout.tsx
+++ b/apps/web/app/docs/layout.tsx
@@ -13,9 +13,9 @@ export default function DocsLayout({ children }: { children: React.ReactNode })
   }))
 
   return (
-    <div className="shell-wide py-10 lg:grid lg:grid-cols-[14rem_minmax(0,1fr)] lg:gap-12">
+    <div className="docs-layout shell-wide py-10 lg:grid lg:grid-cols-[14rem_minmax(0,1fr)] lg:gap-12">
       <details className="card mb-8 lg:hidden">
-        <summary className="cursor-pointer px-4 py-3 font-mono text-[0.75rem] tracking-[0.12em] text-fg-subtle uppercase">
+        <summary className="cursor-pointer px-4 py-3 font-mono text-[0.75rem] tracking-[0.12em] text-fg-muted uppercase">
           Browse documentation
         </summary>
         <div className="border-t border-border px-4 py-4">
diff --git a/apps/web/app/docs/page.tsx b/apps/web/app/docs/page.tsx
index 545793b5d..e9717aace 100644
--- a/apps/web/app/docs/page.tsx
+++ b/apps/web/app/docs/page.tsx
@@ -7,15 +7,13 @@ import { ogImage } from '../../src/og/card'
 
 export const metadata: Metadata = {
   title: 'Documentation',
-  description:
-    'Find step-by-step guides for members, community administrators, operators and developers.',
+  description: 'Meith setup, administration, operation and development guides.',
   alternates: { canonical: '/docs' },
   openGraph: {
     type: 'website',
     siteName: site.name,
     title: `${site.name} documentation`,
-    description:
-      'Find step-by-step guides for members, community administrators, operators and developers.',
+    description: 'Meith setup, administration, operation and development guides.',
     url: '/docs',
     images: ogImage('/docs/og/index', `${site.name} documentation`),
   },
@@ -25,45 +23,31 @@ export default function DocsIndexPage() {
   return (
     <div className="docs-landing">
       <header className="docs-landing-hero">
-        <p className="edition-label">DOCUMENTATION</p>
-        <h1>
-          Let’s get you <em>started.</em>
-        </h1>
-        <p>From your first board to your next big idea.</p>
-        <Link className="edition-button" href={docHref('quickstart')}>
-          Start the quickstart <span aria-hidden>↗</span>
+        <h1>Documentation</h1>
+        <Link className="textlink" href={docHref('quickstart')}>
+          Run a local preview <span aria-hidden>↗</span>
         </Link>
       </header>
 
       <div className="docs-landing-grid">
         {sections.map((section) => {
           const docs = documentsInSection(section.id)
-          const primary = docs.find((doc) => doc.primary)
           return (
             <section key={section.id} id={section.id} className="docs-landing-card">
               <h2>{section.title}</h2>
-              <p>{section.blurb}</p>
-              {primary ? (
-                <Link href={docHref(primary.slug)} className="textlink docs-landing-primary">
-                  {primary.title} <span aria-hidden>→</span>
-                </Link>
-              ) : null}
-              <details>
-                <summary>Browse {docs.length} guides</summary>
-                <ul>
-                  {docs.map((doc, index) => (
-                    <li key={doc.slug}>
-                      {doc.group !== undefined && doc.group !== docs[index - 1]?.group ? (
-                        <p className="eyebrow">{doc.group}</p>
-                      ) : null}
-                      <Link href={docHref(doc.slug)}>
-                        {doc.title}
-                        <span aria-hidden>↗</span>
-                      </Link>
-                    </li>
-                  ))}
-                </ul>
-              </details>
+              <ul>
+                {docs.map((doc, index) => (
+                  <li key={doc.slug}>
+                    {doc.group !== undefined && doc.group !== docs[index - 1]?.group ? (
+                      <p className="eyebrow">{doc.group}</p>
+                    ) : null}
+                    <Link className="textlink" href={docHref(doc.slug)}>
+                      {doc.title}
+                      <span aria-hidden>↗</span>
+                    </Link>
+                  </li>
+                ))}
+              </ul>
             </section>
           )
         })}
diff --git a/apps/web/content/docs.manifest.json b/apps/web/content/docs.manifest.json
index 3401f1795..0521a23c0 100644
--- a/apps/web/content/docs.manifest.json
+++ b/apps/web/content/docs.manifest.json
@@ -6,37 +6,37 @@
   "sections": [
     {
       "id": "start",
-      "title": "Start here",
-      "blurb": "Understand Meith and try a local preview."
+      "title": "Getting started",
+      "blurb": "Preview and deploy a board."
     },
     {
       "id": "members",
-      "title": "Use a community",
+      "title": "Members",
       "blurb": "Read, post, follow discussions and manage your account."
     },
     {
       "id": "administration",
-      "title": "Manage a community",
+      "title": "Administration",
       "blurb": "Set up forums, support members and moderate discussions."
     },
     {
       "id": "operations",
-      "title": "Install and operate",
-      "blurb": "Deploy, maintain, back up and recover a board."
+      "title": "Operations",
+      "blurb": "Configure, maintain, back up and recover a board."
     },
     {
       "id": "extensions",
-      "title": "Build extensions",
+      "title": "Extensions",
       "blurb": "Create, test and publish themes and plugins."
     },
     {
       "id": "integrations",
-      "title": "Use the API",
+      "title": "Integrations",
       "blurb": "Connect applications and receive signed board events."
     },
     {
       "id": "contributing",
-      "title": "Contribute to Meith",
+      "title": "Contributing",
       "blurb": "Develop, test, document and release Meith."
     }
   ],
@@ -45,8 +45,8 @@
       "slug": "introduction",
       "file": "start/introduction.md",
       "section": "start",
-      "title": "Start here",
-      "blurb": "Meith is forum software for running your own community.",
+      "title": "Meith documentation",
+      "blurb": "Choose a guide for your task.",
       "generated": false,
       "primary": true
     },
@@ -54,17 +54,67 @@
       "slug": "quickstart",
       "file": "start/quickstart.md",
       "section": "start",
-      "title": "Try Meith locally",
-      "blurb": "Create a local board with sample content.",
+      "title": "Local preview",
+      "blurb": "Run a board with sample data.",
       "generated": false,
       "primary": false
     },
+    {
+      "slug": "deployment",
+      "file": "operations/deployment.md",
+      "section": "start",
+      "title": "Deployment",
+      "blurb": "Choose a deployment route.",
+      "generated": false,
+      "primary": false,
+      "group": "Deploy a board"
+    },
+    {
+      "slug": "local-board",
+      "file": "operations/local-board.md",
+      "section": "start",
+      "title": "Writable local board",
+      "blurb": "Add PostgreSQL to a local preview.",
+      "generated": false,
+      "primary": false,
+      "group": "Deploy a board"
+    },
+    {
+      "slug": "coolify",
+      "file": "operations/coolify.md",
+      "section": "start",
+      "title": "Deploy with Coolify",
+      "blurb": "Deploy a generated board repository with Coolify.",
+      "generated": false,
+      "primary": false,
+      "group": "Deploy a board"
+    },
+    {
+      "slug": "docker-compose",
+      "file": "operations/docker-compose.md",
+      "section": "start",
+      "title": "Deploy with Docker Compose",
+      "blurb": "Run a board with Compose and a reverse proxy.",
+      "generated": false,
+      "primary": false,
+      "group": "Deploy a board"
+    },
+    {
+      "slug": "vercel",
+      "file": "operations/vercel.md",
+      "section": "start",
+      "title": "Deploy on Vercel",
+      "blurb": "Deploy with managed database, cache and storage.",
+      "generated": false,
+      "primary": false,
+      "group": "Deploy a board"
+    },
     {
       "slug": "member-guide",
       "file": "members/member-guide.md",
       "section": "members",
-      "title": "Use your community",
-      "blurb": "Open your community's Meith board in a browser.",
+      "title": "Read and post",
+      "blurb": "Read discussions, post and manage your profile.",
       "generated": false,
       "primary": true
     },
@@ -72,8 +122,8 @@
       "slug": "formatting",
       "file": "members/formatting.md",
       "section": "members",
-      "title": "Write and format posts",
-      "blurb": "Use Markdown in posts, replies and private messages.",
+      "title": "Format posts",
+      "blurb": "Markdown, quotes, attachments and previews.",
       "generated": false,
       "primary": false
     },
@@ -81,8 +131,8 @@
       "slug": "messages",
       "file": "members/messages.md",
       "section": "members",
-      "title": "Send messages and manage contacts",
-      "blurb": "Use private messages to contact other members when the community permits it.",
+      "title": "Messages and contacts",
+      "blurb": "Private messages, contacts and ignored members.",
       "generated": false,
       "primary": false
     },
@@ -90,8 +140,8 @@
       "slug": "notifications",
       "file": "members/notifications.md",
       "section": "members",
-      "title": "Follow discussions and manage notifications",
-      "blurb": "Choose which discussions to follow and how to receive updates.",
+      "title": "Notifications",
+      "blurb": "Subscriptions, email, digests and push preferences.",
       "generated": false,
       "primary": false
     },
@@ -99,8 +149,8 @@
       "slug": "account-security",
       "file": "members/account-security.md",
       "section": "members",
-      "title": "Manage your account security",
-      "blurb": "Manage your own sign-in methods and devices at /usercp/security.",
+      "title": "Account security",
+      "blurb": "Passwords, passkeys, two-factor authentication and sessions.",
       "generated": false,
       "primary": false
     },
@@ -108,8 +158,8 @@
       "slug": "organiser-guide",
       "file": "administration/organiser-guide.md",
       "section": "administration",
-      "title": "Community administration",
-      "blurb": "Use the admin panel to manage the people, content and settings of an installed board.",
+      "title": "Administration",
+      "blurb": "Manage board settings, members and content.",
       "generated": false,
       "primary": true,
       "group": "Get started"
@@ -118,8 +168,8 @@
       "slug": "first-steps",
       "file": "administration/first-steps.md",
       "section": "administration",
-      "title": "Set up your community",
-      "blurb": "Complete this checklist after installation, using the administrator account you created.",
+      "title": "Set up a community",
+      "blurb": "Configure and test a newly installed board.",
       "generated": false,
       "primary": false,
       "group": "Get started"
@@ -128,8 +178,8 @@
       "slug": "forums",
       "file": "administration/forums.md",
       "section": "administration",
-      "title": "Create forums and control access",
-      "blurb": "Create and arrange forums at Admin \u2192 Forums (/admin/forums).",
+      "title": "Forums and permissions",
+      "blurb": "Create forums and set access rules.",
       "generated": false,
       "primary": false,
       "group": "Community setup"
@@ -138,8 +188,8 @@
       "slug": "groups",
       "file": "administration/groups.md",
       "section": "administration",
-      "title": "Manage groups and promotions",
-      "blurb": "Groups grant permissions, set allowances and control member identity.",
+      "title": "Groups and promotions",
+      "blurb": "Permissions, display groups and automatic promotions.",
       "generated": false,
       "primary": false,
       "group": "Community setup"
@@ -148,8 +198,8 @@
       "slug": "manage-members",
       "file": "administration/manage-members.md",
       "section": "administration",
-      "title": "Manage members and registration",
-      "blurb": "Configure registration, welcome new members and manage their group memberships.",
+      "title": "Members and registration",
+      "blurb": "Registration, activation, staff and account actions.",
       "generated": false,
       "primary": false,
       "group": "Community setup"
@@ -158,8 +208,8 @@
       "slug": "appearance",
       "file": "administration/appearance.md",
       "section": "administration",
-      "title": "Change the board appearance",
-      "blurb": "Change the board name, logo, theme, colors and fonts through the admin panel.",
+      "title": "Appearance",
+      "blurb": "Set the name, logo, theme and palette.",
       "generated": false,
       "primary": false,
       "group": "Community setup"
@@ -168,8 +218,8 @@
       "slug": "community-communications",
       "file": "administration/community-communications.md",
       "section": "administration",
-      "title": "Announcements, navigation and community email",
-      "blurb": "Use the admin panel to publish announcements, arrange navigation and send community updates.",
+      "title": "Announcements, navigation and email",
+      "blurb": "Announcements, navigation, mass mail and digests.",
       "generated": false,
       "primary": false,
       "group": "Community setup"
@@ -178,8 +228,8 @@
       "slug": "moderation-guide",
       "file": "administration/moderation-guide.md",
       "section": "administration",
-      "title": "Moderate discussions",
-      "blurb": "Moderators approve content, handle reports and manage conversations within their assigned forums.",
+      "title": "Moderation",
+      "blurb": "Review reports and manage content and restrictions.",
       "generated": false,
       "primary": false,
       "group": "Moderation and settings"
@@ -188,8 +238,8 @@
       "slug": "antispam",
       "file": "administration/antispam.md",
       "section": "administration",
-      "title": "Configure spam controls",
-      "blurb": "Start under Board settings \u2192 Antispam.",
+      "title": "Spam controls",
+      "blurb": "Registration checks, flood limits and approval controls.",
       "generated": false,
       "primary": false,
       "group": "Moderation and settings"
@@ -198,8 +248,8 @@
       "slug": "search",
       "file": "administration/search.md",
       "section": "administration",
-      "title": "Configure search",
-      "blurb": "Open Board settings \u2192 Search at /admin/settings?group=search.",
+      "title": "Search settings",
+      "blurb": "Search language, indexing and limits.",
       "generated": false,
       "primary": false,
       "group": "Moderation and settings"
@@ -208,8 +258,8 @@
       "slug": "reputation",
       "file": "administration/reputation.md",
       "section": "administration",
-      "title": "Configure reputation and thanks",
-      "blurb": "Configure reputation under Board settings \u2192 Reputation (/admin/settings?group=reputation).",
+      "title": "Reputation and thanks",
+      "blurb": "Configure ratings, thanks and allowances.",
       "generated": false,
       "primary": false,
       "group": "Moderation and settings"
@@ -218,8 +268,8 @@
       "slug": "calendar",
       "file": "administration/calendar.md",
       "section": "administration",
-      "title": "Run community events",
-      "blurb": "The Calendar plugin adds events, recurring occurrences and member responses.",
+      "title": "Calendar",
+      "blurb": "Create events and manage responses.",
       "generated": false,
       "primary": false,
       "group": "Optional plugins"
@@ -228,8 +278,8 @@
       "slug": "awards-guide",
       "file": "administration/awards-guide.md",
       "section": "administration",
-      "title": "Give awards and achievements",
-      "blurb": "Awards recognizes contributions without granting permissions.",
+      "title": "Awards",
+      "blurb": "Grant awards and configure automatic achievements.",
       "generated": false,
       "primary": false,
       "group": "Optional plugins"
@@ -238,68 +288,18 @@
       "slug": "membership-guide",
       "file": "administration/membership-guide.md",
       "section": "administration",
-      "title": "Manage paid memberships with Dues",
-      "blurb": "Dues sells membership of an approved community group through Stripe.",
+      "title": "Paid memberships",
+      "blurb": "Plans, payments and group access through Dues.",
       "generated": false,
       "primary": false,
       "group": "Optional plugins"
     },
-    {
-      "slug": "deployment",
-      "file": "operations/deployment.md",
-      "section": "operations",
-      "title": "Choose a deployment",
-      "blurb": "Choose where the board will run before creating production data.",
-      "generated": false,
-      "primary": true,
-      "group": "Deploy a board"
-    },
-    {
-      "slug": "local-board",
-      "file": "operations/local-board.md",
-      "section": "operations",
-      "title": "Create a writable local board",
-      "blurb": "Turn a scaffolded preview into a board where you can register, post and use the admin panel.",
-      "generated": false,
-      "primary": false,
-      "group": "Deploy a board"
-    },
-    {
-      "slug": "coolify",
-      "file": "operations/coolify.md",
-      "section": "operations",
-      "title": "Deploy with Coolify",
-      "blurb": "Deploy a generated board repository on your server through Coolify.",
-      "generated": false,
-      "primary": false,
-      "group": "Deploy a board"
-    },
-    {
-      "slug": "docker-compose",
-      "file": "operations/docker-compose.md",
-      "section": "operations",
-      "title": "Deploy with Docker Compose",
-      "blurb": "Run Meith on a server using Docker Compose and a reverse proxy you manage.",
-      "generated": false,
-      "primary": false,
-      "group": "Deploy a board"
-    },
-    {
-      "slug": "vercel",
-      "file": "operations/vercel.md",
-      "section": "operations",
-      "title": "Deploy on Vercel",
-      "blurb": "Deploy the board web application on Vercel with managed PostgreSQL, Redis, upload storage and mail.",
-      "generated": false,
-      "primary": false,
-      "group": "Deploy a board"
-    },
     {
       "slug": "configuration",
       "file": "operations/configuration.md",
       "section": "operations",
       "title": "Board configuration",
-      "blurb": "Meith has three configuration layers.",
+      "blurb": "Repository files, environment and saved settings.",
       "generated": false,
       "primary": false,
       "group": "Configure"
@@ -309,7 +309,7 @@
       "file": "operations/environment.md",
       "section": "operations",
       "title": "Environment variables",
-      "blurb": "Use environment variables for infrastructure and secrets.",
+      "blurb": "Infrastructure variables and driver configuration.",
       "generated": false,
       "primary": false,
       "group": "Configure"
@@ -318,8 +318,8 @@
       "slug": "database-operations",
       "file": "operations/database-operations.md",
       "section": "operations",
-      "title": "Database migrations and connections",
-      "blurb": "Configure database connections and apply core migrations before serving a new build.",
+      "title": "Database operations",
+      "blurb": "Migrations, direct connections and pool limits.",
       "generated": false,
       "primary": false,
       "group": "Configure"
@@ -328,8 +328,8 @@
       "slug": "mail",
       "file": "operations/mail.md",
       "section": "operations",
-      "title": "Configure and troubleshoot email",
-      "blurb": "Set up outbound email and prove delivery before relying on registration, password reset or notifications.",
+      "title": "Email",
+      "blurb": "Configure delivery and diagnose failures.",
       "generated": false,
       "primary": false,
       "group": "Configure"
@@ -338,8 +338,8 @@
       "slug": "scheduled-tasks",
       "file": "operations/scheduled-tasks.md",
       "section": "operations",
-      "title": "Run scheduled tasks",
-      "blurb": "Scheduled work delivers queued notifications, maintains indexes, expires restrictions and performs other background jobs.",
+      "title": "Scheduled tasks",
+      "blurb": "Run the scheduler and inspect queued work.",
       "generated": false,
       "primary": false,
       "group": "Configure"
@@ -348,8 +348,8 @@
       "slug": "single-sign-on",
       "file": "operations/single-sign-on.md",
       "section": "operations",
-      "title": "Authentication settings",
-      "blurb": "Configure sign-in methods for a board you operate.",
+      "title": "Configure authentication",
+      "blurb": "Configure passwords, second factors and identity providers.",
       "generated": false,
       "primary": false,
       "group": "Configure"
@@ -358,8 +358,8 @@
       "slug": "web-push",
       "file": "operations/web-push.md",
       "section": "operations",
-      "title": "Enable browser notifications",
-      "blurb": "Enable web push for members who choose browser notifications.",
+      "title": "Web push",
+      "blurb": "Configure push keys and browser subscriptions.",
       "generated": false,
       "primary": false,
       "group": "Configure"
@@ -368,18 +368,18 @@
       "slug": "operating",
       "file": "operations/operating.md",
       "section": "operations",
-      "title": "Server operations",
-      "blurb": "Use this checklist when you take responsibility for a running board.",
+      "title": "Operations",
+      "blurb": "Routine maintenance and service checks.",
       "generated": false,
-      "primary": false,
+      "primary": true,
       "group": "Maintain and recover"
     },
     {
       "slug": "operator-cli",
       "file": "operations/operator-cli.md",
       "section": "operations",
-      "title": "Run operator commands",
-      "blurb": "Run maintenance commands from your board repository or a deployed container.",
+      "title": "Operator commands",
+      "blurb": "Command invocations and account recovery.",
       "generated": false,
       "primary": false,
       "group": "Maintain and recover"
@@ -388,8 +388,8 @@
       "slug": "monitoring",
       "file": "operations/monitoring.md",
       "section": "operations",
-      "title": "Monitor a running board",
-      "blurb": "Monitor the services and background work, not just whether the home page loads.",
+      "title": "Monitoring",
+      "blurb": "Health checks, logs and task failures.",
       "generated": false,
       "primary": false,
       "group": "Maintain and recover"
@@ -398,8 +398,8 @@
       "slug": "troubleshooting",
       "file": "operations/troubleshooting.md",
       "section": "operations",
-      "title": "Troubleshoot a running board",
-      "blurb": "Start with the symptom you can observe.",
+      "title": "Troubleshooting",
+      "blurb": "Diagnose startup, access and delivery failures.",
       "generated": false,
       "primary": false,
       "group": "Maintain and recover"
@@ -408,8 +408,8 @@
       "slug": "backups",
       "file": "operations/backups.md",
       "section": "operations",
-      "title": "Back up and restore a board",
-      "blurb": "Protect the database, uploaded files and deployment secrets.",
+      "title": "Backups and restore",
+      "blurb": "Create, store and restore backup bundles.",
       "generated": false,
       "primary": false,
       "group": "Maintain and recover"
@@ -418,8 +418,8 @@
       "slug": "upgrading",
       "file": "operations/upgrading.md",
       "section": "operations",
-      "title": "Upgrade Meith",
-      "blurb": "Update one board to a new release while keeping its packages, schema and plugins in step.",
+      "title": "Upgrade a board",
+      "blurb": "Back up, update, migrate and verify a release.",
       "generated": false,
       "primary": false,
       "group": "Maintain and recover"
@@ -428,8 +428,8 @@
       "slug": "disaster-recovery",
       "file": "operations/disaster-recovery.md",
       "section": "operations",
-      "title": "Recover after losing a server",
-      "blurb": "Restore a board on a replacement server.",
+      "title": "Disaster recovery",
+      "blurb": "Recover a board from a tested backup.",
       "generated": false,
       "primary": false,
       "group": "Maintain and recover"
@@ -438,8 +438,8 @@
       "slug": "scaling",
       "file": "operations/scaling.md",
       "section": "operations",
-      "title": "Run multiple web instances",
-      "blurb": "Multiple web instances must share PostgreSQL, a Redis-compatible cache and uploaded files.",
+      "title": "Multiple web instances",
+      "blurb": "Shared cache, storage and multi-instance operation.",
       "generated": false,
       "primary": false,
       "group": "Maintain and recover"
@@ -448,8 +448,8 @@
       "slug": "installing",
       "file": "operations/installing.md",
       "section": "operations",
-      "title": "Install plugins and themes",
-      "blurb": "Add extensions in the board repository, then build and deploy.",
+      "title": "Install extensions",
+      "blurb": "Install, register, disable or remove extensions.",
       "generated": false,
       "primary": false,
       "group": "Extensions and hosting"
@@ -459,7 +459,7 @@
       "file": "operations/stripe-setup.md",
       "section": "operations",
       "title": "Connect Dues to Stripe",
-      "blurb": "Configure payment keys, webhooks, receipts and the billing portal, then verify a complete checkout.",
+      "blurb": "Configure Stripe checkout, webhooks and the billing portal.",
       "generated": false,
       "primary": false,
       "group": "Extensions and hosting"
@@ -468,8 +468,8 @@
       "slug": "custom-board",
       "file": "operations/custom-board.md",
       "section": "operations",
-      "title": "Move from the stock image to a custom board",
-      "blurb": "Create a board repository when you need to build extensions into your deployment.",
+      "title": "Create a custom board from the stock image",
+      "blurb": "Export stock board configuration into a repository.",
       "generated": false,
       "primary": false,
       "group": "Extensions and hosting"
@@ -478,8 +478,8 @@
       "slug": "leaving-vercel",
       "file": "operations/leaving-vercel.md",
       "section": "operations",
-      "title": "Move a board away from Vercel",
-      "blurb": "Move an existing Vercel board to a server while preserving the database and uploads.",
+      "title": "Move from Vercel to a server",
+      "blurb": "Move a hosted board to a container deployment.",
       "generated": false,
       "primary": false,
       "group": "Extensions and hosting"
@@ -489,7 +489,7 @@
       "file": "operations/migrating.md",
       "section": "operations",
       "title": "Import MyBB or phpBB",
-      "blurb": "Import one legacy forum into an installed Meith board.",
+      "blurb": "Import MyBB or phpBB data and verify the result.",
       "generated": false,
       "primary": false,
       "group": "Import a forum"
@@ -498,8 +498,8 @@
       "slug": "mybb-parity",
       "file": "operations/mybb-parity.md",
       "section": "operations",
-      "title": "MyBB migration differences",
-      "blurb": "Read these differences before importing a MyBB community.",
+      "title": "MyBB migration checks",
+      "blurb": "MyBB migration scope and differences.",
       "generated": false,
       "primary": false,
       "group": "Import a forum"
@@ -508,8 +508,8 @@
       "slug": "phpbb-parity",
       "file": "operations/phpbb-parity.md",
       "section": "operations",
-      "title": "phpBB migration differences",
-      "blurb": "Review these changes before importing phpBB.",
+      "title": "phpBB migration checks",
+      "blurb": "phpBB migration scope and differences.",
       "generated": false,
       "primary": false,
       "group": "Import a forum"
@@ -518,8 +518,8 @@
       "slug": "authentication-reference",
       "file": "operations/authentication-reference.md",
       "section": "operations",
-      "title": "Authentication behavior and recovery",
-      "blurb": "Look up the behavior of two-factor authentication, sessions, sign-in providers and passkeys.",
+      "title": "Authentication reference",
+      "blurb": "Authentication checks, tokens and session boundaries.",
       "generated": false,
       "primary": false,
       "group": "Reference"
@@ -528,8 +528,8 @@
       "slug": "web-security",
       "file": "operations/web-security.md",
       "section": "operations",
-      "title": "Cookies and security headers",
-      "blurb": "Understand the cookies and browser security policy served by Meith.",
+      "title": "Cookies and browser security",
+      "blurb": "Cookies, headers, origins and request controls.",
       "generated": false,
       "primary": false,
       "group": "Reference"
@@ -538,8 +538,8 @@
       "slug": "vercel-configuration",
       "file": "operations/vercel-configuration.md",
       "section": "operations",
-      "title": "Vercel configuration and limits",
-      "blurb": "Use this reference alongside Deploy on Vercel.",
+      "title": "Vercel configuration",
+      "blurb": "Vercel service connections and runtime requirements.",
       "generated": false,
       "primary": false,
       "group": "Reference"
@@ -548,8 +548,8 @@
       "slug": "upgrade-notes",
       "file": "operations/upgrade-notes.md",
       "section": "operations",
-      "title": "Upgrade compatibility notes",
-      "blurb": "Check these compatibility notes before upgrading an older board.",
+      "title": "Upgrade compatibility",
+      "blurb": "Version-specific migration and configuration steps.",
       "generated": false,
       "primary": false,
       "group": "Reference"
@@ -558,8 +558,8 @@
       "slug": "mybb-permissions",
       "file": "operations/mybb-permissions.md",
       "section": "operations",
-      "title": "MyBB migration: permissions and moderation",
-      "blurb": "Compare MyBB permissions, moderation and staff access with Meith.",
+      "title": "Permissions and moderation after import",
+      "blurb": "Group grants, forum inheritance and moderation.",
       "generated": false,
       "primary": false,
       "group": "Reference"
@@ -568,8 +568,8 @@
       "slug": "mybb-content",
       "file": "operations/mybb-content.md",
       "section": "operations",
-      "title": "MyBB migration: posts and uploads",
-      "blurb": "Check which formatting, editing, poll and upload behavior changes when importing from MyBB.",
+      "title": "MyBB content conversion",
+      "blurb": "Imported posts, formatting and attachments.",
       "generated": false,
       "primary": false,
       "group": "Reference"
@@ -578,8 +578,8 @@
       "slug": "mybb-members",
       "file": "operations/mybb-members.md",
       "section": "operations",
-      "title": "MyBB migration: accounts and messages",
-      "blurb": "Review account, messaging, notification and reputation differences before inviting members to an imported board.",
+      "title": "Accounts and messages after import",
+      "blurb": "Accounts, profiles, messages and subscriptions.",
       "generated": false,
       "primary": false,
       "group": "Reference"
@@ -588,8 +588,8 @@
       "slug": "mybb-discovery",
       "file": "operations/mybb-discovery.md",
       "section": "operations",
-      "title": "MyBB migration: search and discovery",
-      "blurb": "Review search, discovery, feed visibility and spam-control differences on a board imported from MyBB.",
+      "title": "Discovery, feeds and search",
+      "blurb": "Search, feeds and discovery behaviour.",
       "generated": false,
       "primary": false,
       "group": "Reference"
@@ -598,8 +598,8 @@
       "slug": "extensions",
       "file": "extensions/extensions.md",
       "section": "extensions",
-      "title": "Build extensions",
-      "blurb": "Extend a board through a theme or plugin.",
+      "title": "Extension development",
+      "blurb": "Choose a theme or plugin development guide.",
       "generated": false,
       "primary": true,
       "group": "Get started"
@@ -608,8 +608,8 @@
       "slug": "first-plugin",
       "file": "extensions/first-plugin.md",
       "section": "extensions",
-      "title": "Write your first plugin",
-      "blurb": "Create a plugin, run its tests and load it into a development board.",
+      "title": "Create a plugin",
+      "blurb": "Create, register and test a local plugin.",
       "generated": false,
       "primary": false,
       "group": "Get started"
@@ -618,8 +618,8 @@
       "slug": "first-theme",
       "file": "extensions/first-theme.md",
       "section": "extensions",
-      "title": "Build your first theme",
-      "blurb": "Create a theme that inherits the default board, changes its palette and overrides the footer.",
+      "title": "Create a theme",
+      "blurb": "Create, register and test an inherited theme.",
       "generated": false,
       "primary": false,
       "group": "Get started"
@@ -628,8 +628,8 @@
       "slug": "plugins",
       "file": "extensions/plugins.md",
       "section": "extensions",
-      "title": "Plugin development",
-      "blurb": "A plugin registers behavior with definePlugin from @meith/plugin-kit.",
+      "title": "Plugins",
+      "blurb": "Plugin capabilities and reference guides.",
       "generated": false,
       "primary": false,
       "group": "Plugin guides"
@@ -639,7 +639,7 @@
       "file": "extensions/plugin-hooks-guide.md",
       "section": "extensions",
       "title": "Plugin hooks and lifecycle",
-      "blurb": "Choose the appropriate filter or event, understand execution order and failure isolation, and manage the lifecycle of an installed plugin.",
+      "blurb": "Filters, events, failures and lifecycle handlers.",
       "generated": false,
       "primary": false,
       "group": "Plugin guides"
@@ -648,8 +648,8 @@
       "slug": "plugin-presentation",
       "file": "extensions/plugin-presentation.md",
       "section": "extensions",
-      "title": "Plugin UI and content rendering",
-      "blurb": "Add interface content through the published regions and rendering APIs.",
+      "title": "Plugin UI and Markdown",
+      "blurb": "UI regions, Markdown, navigation and copy.",
       "generated": false,
       "primary": false,
       "group": "Plugin guides"
@@ -658,8 +658,8 @@
       "slug": "plugin-storage",
       "file": "extensions/plugin-storage.md",
       "section": "extensions",
-      "title": "Plugin storage, groups and migrations",
-      "blurb": "Store plugin data, apply forward-only migrations and work with explicitly grantable groups.",
+      "title": "Plugin storage and membership",
+      "blurb": "Namespaced data, migrations, users and group grants.",
       "generated": false,
       "primary": false,
       "group": "Plugin guides"
@@ -669,7 +669,7 @@
       "file": "extensions/plugin-pages.md",
       "section": "extensions",
       "title": "Plugin routes and pages",
-      "blurb": "Expose plugin HTTP routes and member, administrator or moderator pages.",
+      "blurb": "Routes, access checks, responses and panel pages.",
       "generated": false,
       "primary": false,
       "group": "Plugin guides"
@@ -679,7 +679,7 @@
       "file": "extensions/plugin-services.md",
       "section": "extensions",
       "title": "Plugin settings, notifications and tasks",
-      "blurb": "Declare settings, notify members and schedule background work through the plugin host.",
+      "blurb": "Settings, notifications and task schedules.",
       "generated": false,
       "primary": false,
       "group": "Plugin guides"
@@ -688,8 +688,8 @@
       "slug": "themes",
       "file": "extensions/themes.md",
       "section": "extensions",
-      "title": "Theme development",
-      "blurb": "A theme supplies presentation through @meith/theme-kit.",
+      "title": "Themes",
+      "blurb": "Theme contracts, tokens and testing guides.",
       "generated": false,
       "primary": false,
       "group": "Theme guides"
@@ -698,8 +698,8 @@
       "slug": "theme-contract",
       "file": "extensions/theme-contract.md",
       "section": "extensions",
-      "title": "Theme contracts and compatibility",
-      "blurb": "Understand the theme boundary, slot compatibility, translation and versioning rules before changing a theme implementation.",
+      "title": "Theme contract",
+      "blurb": "Slot composition, models and compatibility.",
       "generated": false,
       "primary": false,
       "group": "Theme guides"
@@ -708,8 +708,8 @@
       "slug": "theme-design",
       "file": "extensions/theme-design.md",
       "section": "extensions",
-      "title": "Theme tokens and shared controls",
-      "blurb": "Customize visual tokens and reuse the shared controls.",
+      "title": "Theme tokens and controls",
+      "blurb": "Palettes, shared controls and navigation.",
       "generated": false,
       "primary": false,
       "group": "Theme guides"
@@ -719,7 +719,7 @@
       "file": "extensions/theme-testing.md",
       "section": "extensions",
       "title": "Test a theme",
-      "blurb": "Check a theme against populated, empty and permission-dependent models, then verify it in a browser.",
+      "blurb": "Contract tests, fixtures and visual checks.",
       "generated": false,
       "primary": false,
       "group": "Theme guides"
@@ -728,8 +728,8 @@
       "slug": "internationalisation",
       "file": "extensions/internationalisation.md",
       "section": "extensions",
-      "title": "Translate Meith and extensions",
-      "blurb": "Use language catalogs to translate the board, themes and plugins.",
+      "title": "Translations",
+      "blurb": "Locale selection, catalogues and extension messages.",
       "generated": false,
       "primary": false,
       "group": "Share your work"
@@ -738,8 +738,8 @@
       "slug": "marketplace",
       "file": "extensions/marketplace.md",
       "section": "extensions",
-      "title": "Publish a theme or plugin",
-      "blurb": "Publish a tested extension package, then submit a listing for review.",
+      "title": "Publish an extension",
+      "blurb": "Prepare and submit an extension listing.",
       "generated": false,
       "primary": false,
       "group": "Share your work"
@@ -749,7 +749,7 @@
       "file": "reference/plugin-hooks.md",
       "section": "extensions",
       "title": "Plugin hooks",
-      "blurb": "Generated reference for hooks, payloads, and call sites.",
+      "blurb": "Hook signatures and region contexts from the code.",
       "generated": true,
       "primary": false,
       "group": "Reference"
@@ -759,7 +759,7 @@
       "file": "reference/theme-slots.md",
       "section": "extensions",
       "title": "Theme slots and view models",
-      "blurb": "Generated reference for the theme contract.",
+      "blurb": "Slot props, shared models and scheduled removals.",
       "generated": true,
       "primary": false,
       "group": "Reference"
@@ -768,8 +768,8 @@
       "slug": "api-quickstart",
       "file": "integrations/api-quickstart.md",
       "section": "integrations",
-      "title": "Make your first API request",
-      "blurb": "Read board data from another application using the REST API.",
+      "title": "REST API quickstart",
+      "blurb": "Create a scoped token and make a REST request.",
       "generated": false,
       "primary": true
     },
@@ -777,8 +777,8 @@
       "slug": "webhooks",
       "file": "integrations/webhooks.md",
       "section": "integrations",
-      "title": "Receive and verify webhooks",
-      "blurb": "Send board events to an HTTPS endpoint you operate.",
+      "title": "Webhooks",
+      "blurb": "Subscribe, verify signatures and handle retries.",
       "generated": false,
       "primary": false
     },
@@ -787,7 +787,7 @@
       "file": "reference/api.md",
       "section": "integrations",
       "title": "REST API v1",
-      "blurb": "Endpoint, scope, and rate-limit reference.",
+      "blurb": "Endpoints, authentication, rate limits and errors.",
       "generated": true,
       "primary": false
     },
@@ -795,8 +795,8 @@
       "slug": "development",
       "file": "contributing/development.md",
       "section": "contributing",
-      "title": "Contribute to Meith",
-      "blurb": "Use this guide to run the Meith source repository and prepare a change.",
+      "title": "Development setup",
+      "blurb": "Run the board and website from source.",
       "generated": false,
       "primary": true,
       "group": "Development workflow"
@@ -806,7 +806,7 @@
       "file": "contributing/architecture.md",
       "section": "contributing",
       "title": "Architecture",
-      "blurb": "Meith separates business rules, infrastructure and presentation.",
+      "blurb": "Request flow and package responsibilities.",
       "generated": false,
       "primary": false,
       "group": "Development workflow"
@@ -815,8 +815,8 @@
       "slug": "nextjs-conventions",
       "file": "contributing/nextjs-conventions.md",
       "section": "contributing",
-      "title": "Application conventions",
-      "blurb": "Use these conventions when changing apps/community.",
+      "title": "Next.js conventions",
+      "blurb": "Server rendering and native interaction rules.",
       "generated": false,
       "primary": false,
       "group": "Development workflow"
@@ -825,8 +825,8 @@
       "slug": "testing",
       "file": "contributing/testing.md",
       "section": "contributing",
-      "title": "Run and debug tests",
-      "blurb": "Choose the test layer for the behavior you are changing.",
+      "title": "Testing",
+      "blurb": "Unit, PostgreSQL, browser and screenshot checks.",
       "generated": false,
       "primary": false,
       "group": "Development workflow"
@@ -835,8 +835,8 @@
       "slug": "ui-conventions",
       "file": "contributing/ui-conventions.md",
       "section": "contributing",
-      "title": "Develop accessible interface components",
-      "blurb": "Use the shared design system for forms, panels and destructive actions.",
+      "title": "UI conventions",
+      "blurb": "Shared controls, feedback and confirmations.",
       "generated": false,
       "primary": false,
       "group": "Development workflow"
@@ -845,8 +845,8 @@
       "slug": "documentation",
       "file": "contributing/documentation.md",
       "section": "contributing",
-      "title": "Maintain the documentation",
-      "blurb": "Documentation source lives in docs/.",
+      "title": "Maintain documentation",
+      "blurb": "Write, register and validate documentation.",
       "generated": false,
       "primary": false,
       "group": "Development workflow"
@@ -856,7 +856,7 @@
       "file": "contributing/brand.md",
       "section": "contributing",
       "title": "Brand guidelines",
-      "blurb": "How Meith looks, sounds and spends its one colour.",
+      "blurb": "Logo, colour, typography and site layout rules.",
       "generated": false,
       "primary": false,
       "group": "Development workflow"
@@ -865,8 +865,8 @@
       "slug": "repository-checks",
       "file": "contributing/repository-checks.md",
       "section": "contributing",
-      "title": "Repository rules and checks",
-      "blurb": "Follow the repository contract and run the checks that enforce it.",
+      "title": "Repository checks",
+      "blurb": "Formatting, invariant gates and generated files.",
       "generated": false,
       "primary": false,
       "group": "Development workflow"
@@ -875,8 +875,8 @@
       "slug": "forms-and-actions",
       "file": "contributing/forms-and-actions.md",
       "section": "contributing",
-      "title": "Forms and Server Actions",
-      "blurb": "Build validated, permission-checked mutation flows that work with and without JavaScript.",
+      "title": "Forms and server actions",
+      "blurb": "Validation, authorization and progressive forms.",
       "generated": false,
       "primary": false,
       "group": "Implementation reference"
@@ -885,8 +885,8 @@
       "slug": "rendering-and-data",
       "file": "contributing/rendering-and-data.md",
       "section": "contributing",
-      "title": "Rendering, caching and view models",
-      "blurb": "Keep data access, cache invalidation and theme view models consistent across pages and actions.",
+      "title": "Rendering and data",
+      "blurb": "Caching, counters, slots and view models.",
       "generated": false,
       "primary": false,
       "group": "Implementation reference"
@@ -895,8 +895,8 @@
       "slug": "board-workspaces",
       "file": "contributing/board-workspaces.md",
       "section": "contributing",
-      "title": "Board workspaces and build materialization",
-      "blurb": "Understand the monorepo, external board workspaces and generated board registry.",
+      "title": "Board workspaces",
+      "blurb": "Board configuration, materialization and packaging.",
       "generated": false,
       "primary": false,
       "group": "Implementation reference"
@@ -905,8 +905,8 @@
       "slug": "marketplace-maintenance",
       "file": "contributing/marketplace-maintenance.md",
       "section": "contributing",
-      "title": "Maintain the marketplace feed",
-      "blurb": "Maintain listings and the feed consumed by boards.",
+      "title": "Marketplace maintenance",
+      "blurb": "Feed generation, update checks and delisting.",
       "generated": false,
       "primary": false,
       "group": "Implementation reference"
@@ -916,7 +916,7 @@
       "file": "reference/performance.md",
       "section": "contributing",
       "title": "Performance",
-      "blurb": "Recorded measurements and performance budgets.",
+      "blurb": "Recorded read timings, budgets and load results.",
       "generated": true,
       "primary": false,
       "group": "Implementation reference"
@@ -926,7 +926,7 @@
       "file": "contributing/release.md",
       "section": "contributing",
       "title": "Release Meith",
-      "blurb": "This procedure is for maintainers publishing Meith.",
+      "blurb": "Publish a version from a passing main commit.",
       "generated": false,
       "primary": false,
       "group": "Maintainers"
@@ -935,8 +935,8 @@
       "slug": "release-infrastructure",
       "file": "contributing/release-infrastructure.md",
       "section": "contributing",
-      "title": "Release infrastructure and version policy",
-      "blurb": "Understand what a release publishes and how packages, images and templates stay in step.",
+      "title": "Release infrastructure",
+      "blurb": "Version policy, registries, images and templates.",
       "generated": false,
       "primary": false,
       "group": "Maintainers"
diff --git a/apps/web/src/components/docs-nav.tsx b/apps/web/src/components/docs-nav.tsx
index 979a630b1..44827ff35 100644
--- a/apps/web/src/components/docs-nav.tsx
+++ b/apps/web/src/components/docs-nav.tsx
@@ -25,7 +25,7 @@ export function DocsNav({ sections }: DocsNavProps) {
       <Link
         href="/docs"
         className={`mb-6 block font-mono text-[0.75rem] tracking-[0.12em] uppercase transition-colors ${
-          pathname === '/docs' ? 'text-accent' : 'text-fg-subtle hover:text-fg'
+          pathname === '/docs' ? 'text-accent' : 'text-fg-muted hover:text-fg'
         }`}
       >
         Documentation home
@@ -47,7 +47,7 @@ export function DocsNav({ sections }: DocsNavProps) {
                   return (
                     <li key={doc.slug}>
                       {groupStarts ? (
-                        <p className="mt-2 mb-1 pl-3 font-mono text-[0.65rem] tracking-[0.1em] text-fg-subtle uppercase">
+                        <p className="mt-2 mb-1 pl-3 font-mono text-[0.65rem] tracking-[0.1em] text-fg-muted uppercase">
                           {doc.group}
                         </p>
                       ) : null}
diff --git a/apps/web/src/components/table-of-contents.tsx b/apps/web/src/components/table-of-contents.tsx
index fa93d1b55..9c5d7e2e7 100644
--- a/apps/web/src/components/table-of-contents.tsx
+++ b/apps/web/src/components/table-of-contents.tsx
@@ -84,7 +84,7 @@ export function TableOfContents({ headings }: TableOfContentsProps) {
                 } ${
                   active
                     ? 'border-accent text-accent'
-                    : 'border-transparent text-fg-subtle hover:border-border-strong hover:text-fg'
+                    : 'border-transparent text-fg-muted hover:border-border-strong hover:text-fg'
                 }`}
               >
                 {heading.text}
diff --git a/apps/web/src/content/facts.ts b/apps/web/src/content/facts.ts
index a8d8a60fe..12515857a 100644
--- a/apps/web/src/content/facts.ts
+++ b/apps/web/src/content/facts.ts
@@ -100,8 +100,8 @@ async function pluginFacts(): Promise<PluginFacts> {
   const [, hooks = '', filters = '', events = '', regions = '', wired = ''] = capture(
     file,
     source,
-    /\*\*(\d+)\s+hooks\*\*\s*[—–-]\s*(\d+)\s+filters,\s*(\d+)\s+events\s*[—–-]\s*and\s+(\d+)\s+UI regions\.\s*\*\*(\d+)\s+are wired\*\*/,
-    'its hook count (“**93 hooks** — 48 filters, 45 events — and 6 UI regions. **23 are wired**”)',
+    /(\d+) hooks: (\d+) filters and (\d+) events\. (\d+) UI regions\.\s+(\d+) hooks have call sites/,
+    'its hook, filter, event, region and call-site counts',
   )
 
   return {
diff --git a/apps/web/src/styles/globals.css b/apps/web/src/styles/globals.css
index ddd0f11a5..b4fc9be99 100644
--- a/apps/web/src/styles/globals.css
+++ b/apps/web/src/styles/globals.css
@@ -1289,7 +1289,7 @@ a:hover > span[aria-hidden] {
 
 .doc-heading {
   color: var(--fg);
-  font-weight: 640;
+  font-weight: 500;
   letter-spacing: -0.022em;
   line-height: 1.25;
   text-wrap: balance;
@@ -1298,14 +1298,14 @@ a:hover > span[aria-hidden] {
 
 .doc-body h2.doc-heading {
   font-size: var(--step-2);
-  margin-top: 2.6em;
+  margin-top: 2rem;
   padding-top: 1.1rem;
   border-top: 1px solid var(--border);
 }
 
 .doc-body h3.doc-heading {
   font-size: var(--step-1);
-  margin-top: 2em;
+  margin-top: 1.5rem;
 }
 
 .doc-body h4.doc-heading,
@@ -1366,7 +1366,7 @@ a:hover > span[aria-hidden] {
   content: "↗";
   font-size: 0.8em;
   margin-left: 0.15em;
-  color: var(--fg-subtle);
+  color: var(--fg-muted);
   vertical-align: 0.15em;
 }
 
@@ -1403,7 +1403,7 @@ a:hover > span[aria-hidden] {
 }
 
 .doc-body ol > li::marker {
-  color: var(--fg-subtle);
+  color: var(--fg-muted);
   font-family: var(--mono);
   font-size: 0.9em;
 }
@@ -1447,7 +1447,7 @@ a:hover > span[aria-hidden] {
   font-size: 0.68rem;
   letter-spacing: 0.12em;
   text-transform: uppercase;
-  color: var(--fg-subtle);
+  color: var(--fg-muted);
   pointer-events: none;
 }
 
@@ -1541,7 +1541,7 @@ a:hover > span[aria-hidden] {
   font-size: 0.68rem;
   letter-spacing: 0.08em;
   text-transform: uppercase;
-  color: var(--fg-subtle);
+  color: var(--fg-muted);
   background: var(--canvas);
   border: 1px solid var(--border);
   border-radius: 4px;
@@ -1596,7 +1596,7 @@ a:hover > span[aria-hidden] {
   font-size: 0.68rem;
   letter-spacing: 0.12em;
   text-transform: uppercase;
-  color: var(--accent-rule, var(--fg-subtle));
+  color: var(--accent-rule, var(--fg-muted));
   margin: 0 0 0.4rem;
 }
 
@@ -1655,7 +1655,7 @@ a:hover > span[aria-hidden] {
   font-size: 0.8em;
   text-transform: uppercase;
   letter-spacing: 0.08em;
-  color: var(--fg-subtle);
+  color: var(--fg-muted);
   font-weight: 400;
   background: var(--surface);
   white-space: nowrap;
@@ -1672,7 +1672,7 @@ a:hover > span[aria-hidden] {
 .doc-body blockquote {
   border-left: 2px solid var(--border-strong);
   padding-left: 1.1rem;
-  color: var(--fg-subtle);
+  color: var(--fg-muted);
   max-width: 42rem;
 }
 
diff --git a/apps/web/src/styles/marketing.css b/apps/web/src/styles/marketing.css
index 47a3dd299..85ed9e3b1 100644
--- a/apps/web/src/styles/marketing.css
+++ b/apps/web/src/styles/marketing.css
@@ -709,108 +709,79 @@
   line-height: 1.65;
 }
 
+.docs-layout .eyebrow {
+  color: var(--fg-muted);
+}
+
 .docs-landing {
   min-width: 0;
   padding-bottom: 3rem;
 }
 
 .docs-landing-hero {
-  padding-block: 0.5rem 3rem;
+  padding-block: 0.5rem 2rem;
 }
 
-.docs-landing-hero h1 {
-  margin-top: 1.25rem;
-  font-size: clamp(2.25rem, 1.8rem + 1.6vw, 3.5rem);
-  line-height: 1.15;
-  font-weight: 450;
-  letter-spacing: -0.025em;
-}
-
-.docs-landing-hero h1 em {
-  font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", Georgia, serif;
+.docs-landing-hero h1,
+.doc-title {
+  font-size: clamp(1.75rem, 1.5rem + 1vw, 2.25rem);
+  line-height: 1.2;
   font-weight: 400;
-  font-style: italic;
   letter-spacing: -0.025em;
-  color: var(--accent);
 }
 
-.docs-landing-hero > p:last-of-type {
-  margin-block: 1.25rem 1.75rem;
-  color: var(--fg-muted);
-  font-size: 1.125rem;
+.docs-landing-hero > a {
+  display: inline-block;
+  margin-top: 1rem;
 }
 
 .docs-landing-grid {
   display: grid;
   grid-template-columns: repeat(2, minmax(0, 1fr));
   align-items: start;
-  gap: 2.5rem;
+  gap: 2.25rem;
 }
 
 .docs-landing-card {
   min-width: 0;
-  padding-top: 1.5rem;
-  border-top: 1px solid var(--fg);
+  padding-top: 1.25rem;
+  border-top: 1px solid var(--border-strong);
   scroll-margin-top: 6rem;
 }
 
 .docs-landing-card h2 {
   font-size: 1.25rem;
   font-weight: 500;
-  line-height: 1.2;
-  letter-spacing: -0.02em;
-}
-
-.docs-landing-card > p {
-  min-height: 3.3em;
-  margin-top: 0.75rem;
-  color: var(--fg-muted);
-  font-size: 0.875rem;
-  line-height: 1.65;
-}
-
-.docs-landing-primary {
-  display: inline-block;
-  margin-block: 1.25rem 1.5rem;
-  font-size: 0.875rem;
-}
-
-.docs-landing-card details {
-  padding-top: 1rem;
-  border-top: 1px solid var(--border);
-  font-size: 0.8125rem;
-}
-
-.docs-landing-card summary {
-  color: var(--fg-muted);
-  cursor: pointer;
-}
-
-.docs-landing-card summary:hover {
-  color: var(--accent);
+  line-height: 1.25;
+  letter-spacing: -0.025em;
 }
 
-.docs-landing-card details ul {
+.docs-landing-card ul {
   display: grid;
-  gap: 0.5rem;
-  margin-top: 1.25rem;
+  gap: 0.25rem;
+  margin-top: 1rem;
 }
 
-.docs-landing-card details a {
+.docs-landing-card li > a {
   display: flex;
   justify-content: space-between;
   align-items: baseline;
   gap: 1rem;
-  padding-block: 0.25rem;
+  padding-block: 0.5rem;
+  font-size: 0.875rem;
 }
 
-.docs-landing-card details a:hover {
-  color: var(--accent);
+.docs-landing-card li > a span {
+  transition: transform 160ms ease;
+}
+
+.docs-landing-card li > a:hover span {
+  transform: translate(2px, -2px);
 }
 
-.docs-landing-card details .eyebrow {
+.docs-landing-card .eyebrow {
   margin-block: 1rem 0.5rem;
-  font-size: 0.625rem;
+  color: var(--fg-muted);
 }
 
 .doc-nav {
diff --git a/docs/README.md b/docs/README.md
index 12b60ee42..a08fbebc8 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,195 +1,169 @@
-# Meith documentation
+# Documentation
 
-Start with the guide for the task you want to complete. Member and administrator guides explain the browser interface; operator guides cover hosting and maintenance; developer guides cover extensions and contributions.
-
-| I want to… | Start here |
-|---|---|
-| Understand or try Meith | [Start here](./start/introduction.md) |
-| Use an existing community | [Member guide](./members/member-guide.md) |
-| Manage forums and members | [Community administration](./administration/organiser-guide.md) |
-| Deploy or maintain a board | [Choose a deployment](./operations/deployment.md) or [Server operations](./operations/operating.md) |
-| Build a plugin or theme | [Build extensions](./extensions/extensions.md) |
-| Connect another application | [Use the API](./integrations/api-quickstart.md) |
-| Change Meith's source | [Contribute to Meith](./contributing/development.md) |
+Meith setup, administration, operation and development guides.
 
 <!-- docs:index start — generated by pnpm site:docs; edit the manifest instead -->
 
-## Start here
-
-Understand Meith and try a local preview.
+## Getting started
 
-- [Start here](./start/introduction.md) — Meith is forum software for running your own community.
-- [Try Meith locally](./start/quickstart.md) — Create a local board with sample content.
+- [Meith documentation](./start/introduction.md)
+- [Local preview](./start/quickstart.md)
 
-## Use a community
+### Deploy a board
 
-Read, post, follow discussions and manage your account.
+- [Deployment](./operations/deployment.md)
+- [Writable local board](./operations/local-board.md)
+- [Deploy with Coolify](./operations/coolify.md)
+- [Deploy with Docker Compose](./operations/docker-compose.md)
+- [Deploy on Vercel](./operations/vercel.md)
 
-- [Use your community](./members/member-guide.md) — Open your community's Meith board in a browser.
-- [Write and format posts](./members/formatting.md) — Use Markdown in posts, replies and private messages.
-- [Send messages and manage contacts](./members/messages.md) — Use private messages to contact other members when the community permits it.
-- [Follow discussions and manage notifications](./members/notifications.md) — Choose which discussions to follow and how to receive updates.
-- [Manage your account security](./members/account-security.md) — Manage your own sign-in methods and devices at /usercp/security.
+## Members
 
-## Manage a community
+- [Read and post](./members/member-guide.md)
+- [Format posts](./members/formatting.md)
+- [Messages and contacts](./members/messages.md)
+- [Notifications](./members/notifications.md)
+- [Account security](./members/account-security.md)
 
-Set up forums, support members and moderate discussions.
+## Administration
 
 ### Get started
 
-- [Community administration](./administration/organiser-guide.md) — Use the admin panel to manage the people, content and settings of an installed board.
-- [Set up your community](./administration/first-steps.md) — Complete this checklist after installation, using the administrator account you created.
+- [Administration](./administration/organiser-guide.md)
+- [Set up a community](./administration/first-steps.md)
 
 ### Community setup
 
-- [Create forums and control access](./administration/forums.md) — Create and arrange forums at Admin → Forums (/admin/forums).
-- [Manage groups and promotions](./administration/groups.md) — Groups grant permissions, set allowances and control member identity.
-- [Manage members and registration](./administration/manage-members.md) — Configure registration, welcome new members and manage their group memberships.
-- [Change the board appearance](./administration/appearance.md) — Change the board name, logo, theme, colors and fonts through the admin panel.
-- [Announcements, navigation and community email](./administration/community-communications.md) — Use the admin panel to publish announcements, arrange navigation and send community updates.
+- [Forums and permissions](./administration/forums.md)
+- [Groups and promotions](./administration/groups.md)
+- [Members and registration](./administration/manage-members.md)
+- [Appearance](./administration/appearance.md)
+- [Announcements, navigation and email](./administration/community-communications.md)
 
 ### Moderation and settings
 
-- [Moderate discussions](./administration/moderation-guide.md) — Moderators approve content, handle reports and manage conversations within their assigned forums.
-- [Configure spam controls](./administration/antispam.md) — Start under Board settings → Antispam.
-- [Configure search](./administration/search.md) — Open Board settings → Search at /admin/settings?group=search.
-- [Configure reputation and thanks](./administration/reputation.md) — Configure reputation under Board settings → Reputation (/admin/settings?group=reputation).
+- [Moderation](./administration/moderation-guide.md)
+- [Spam controls](./administration/antispam.md)
+- [Search settings](./administration/search.md)
+- [Reputation and thanks](./administration/reputation.md)
 
 ### Optional plugins
 
-- [Run community events](./administration/calendar.md) — The Calendar plugin adds events, recurring occurrences and member responses.
-- [Give awards and achievements](./administration/awards-guide.md) — Awards recognizes contributions without granting permissions.
-- [Manage paid memberships with Dues](./administration/membership-guide.md) — Dues sells membership of an approved community group through Stripe.
+- [Calendar](./administration/calendar.md)
+- [Awards](./administration/awards-guide.md)
+- [Paid memberships](./administration/membership-guide.md)
 
-## Install and operate
-
-Deploy, maintain, back up and recover a board.
-
-### Deploy a board
-
-- [Choose a deployment](./operations/deployment.md) — Choose where the board will run before creating production data.
-- [Create a writable local board](./operations/local-board.md) — Turn a scaffolded preview into a board where you can register, post and use the admin panel.
-- [Deploy with Coolify](./operations/coolify.md) — Deploy a generated board repository on your server through Coolify.
-- [Deploy with Docker Compose](./operations/docker-compose.md) — Run Meith on a server using Docker Compose and a reverse proxy you manage.
-- [Deploy on Vercel](./operations/vercel.md) — Deploy the board web application on Vercel with managed PostgreSQL, Redis, upload storage and mail.
+## Operations
 
 ### Configure
 
-- [Board configuration](./operations/configuration.md) — Meith has three configuration layers.
-- [Environment variables](./operations/environment.md) — Use environment variables for infrastructure and secrets.
-- [Database migrations and connections](./operations/database-operations.md) — Configure database connections and apply core migrations before serving a new build.
-- [Configure and troubleshoot email](./operations/mail.md) — Set up outbound email and prove delivery before relying on registration, password reset or notifications.
-- [Run scheduled tasks](./operations/scheduled-tasks.md) — Scheduled work delivers queued notifications, maintains indexes, expires restrictions and performs other background jobs.
-- [Authentication settings](./operations/single-sign-on.md) — Configure sign-in methods for a board you operate.
-- [Enable browser notifications](./operations/web-push.md) — Enable web push for members who choose browser notifications.
+- [Board configuration](./operations/configuration.md)
+- [Environment variables](./operations/environment.md)
+- [Database operations](./operations/database-operations.md)
+- [Email](./operations/mail.md)
+- [Scheduled tasks](./operations/scheduled-tasks.md)
+- [Configure authentication](./operations/single-sign-on.md)
+- [Web push](./operations/web-push.md)
 
 ### Maintain and recover
 
-- [Server operations](./operations/operating.md) — Use this checklist when you take responsibility for a running board.
-- [Run operator commands](./operations/operator-cli.md) — Run maintenance commands from your board repository or a deployed container.
-- [Monitor a running board](./operations/monitoring.md) — Monitor the services and background work, not just whether the home page loads.
-- [Troubleshoot a running board](./operations/troubleshooting.md) — Start with the symptom you can observe.
-- [Back up and restore a board](./operations/backups.md) — Protect the database, uploaded files and deployment secrets.
-- [Upgrade Meith](./operations/upgrading.md) — Update one board to a new release while keeping its packages, schema and plugins in step.
-- [Recover after losing a server](./operations/disaster-recovery.md) — Restore a board on a replacement server.
-- [Run multiple web instances](./operations/scaling.md) — Multiple web instances must share PostgreSQL, a Redis-compatible cache and uploaded files.
+- [Operations](./operations/operating.md)
+- [Operator commands](./operations/operator-cli.md)
+- [Monitoring](./operations/monitoring.md)
+- [Troubleshooting](./operations/troubleshooting.md)
+- [Backups and restore](./operations/backups.md)
+- [Upgrade a board](./operations/upgrading.md)
+- [Disaster recovery](./operations/disaster-recovery.md)
+- [Multiple web instances](./operations/scaling.md)
 
 ### Extensions and hosting
 
-- [Install plugins and themes](./operations/installing.md) — Add extensions in the board repository, then build and deploy.
-- [Connect Dues to Stripe](./operations/stripe-setup.md) — Configure payment keys, webhooks, receipts and the billing portal, then verify a complete checkout.
-- [Move from the stock image to a custom board](./operations/custom-board.md) — Create a board repository when you need to build extensions into your deployment.
-- [Move a board away from Vercel](./operations/leaving-vercel.md) — Move an existing Vercel board to a server while preserving the database and uploads.
+- [Install extensions](./operations/installing.md)
+- [Connect Dues to Stripe](./operations/stripe-setup.md)
+- [Create a custom board from the stock image](./operations/custom-board.md)
+- [Move from Vercel to a server](./operations/leaving-vercel.md)
 
 ### Import a forum
 
-- [Import MyBB or phpBB](./operations/migrating.md) — Import one legacy forum into an installed Meith board.
-- [MyBB migration differences](./operations/mybb-parity.md) — Read these differences before importing a MyBB community.
-- [phpBB migration differences](./operations/phpbb-parity.md) — Review these changes before importing phpBB.
+- [Import MyBB or phpBB](./operations/migrating.md)
+- [MyBB migration checks](./operations/mybb-parity.md)
+- [phpBB migration checks](./operations/phpbb-parity.md)
 
 ### Reference
 
-- [Authentication behavior and recovery](./operations/authentication-reference.md) — Look up the behavior of two-factor authentication, sessions, sign-in providers and passkeys.
-- [Cookies and security headers](./operations/web-security.md) — Understand the cookies and browser security policy served by Meith.
-- [Vercel configuration and limits](./operations/vercel-configuration.md) — Use this reference alongside Deploy on Vercel.
-- [Upgrade compatibility notes](./operations/upgrade-notes.md) — Check these compatibility notes before upgrading an older board.
-- [MyBB migration: permissions and moderation](./operations/mybb-permissions.md) — Compare MyBB permissions, moderation and staff access with Meith.
-- [MyBB migration: posts and uploads](./operations/mybb-content.md) — Check which formatting, editing, poll and upload behavior changes when importing from MyBB.
-- [MyBB migration: accounts and messages](./operations/mybb-members.md) — Review account, messaging, notification and reputation differences before inviting members to an imported board.
-- [MyBB migration: search and discovery](./operations/mybb-discovery.md) — Review search, discovery, feed visibility and spam-control differences on a board imported from MyBB.
-
-## Build extensions
+- [Authentication reference](./operations/authentication-reference.md)
+- [Cookies and browser security](./operations/web-security.md)
+- [Vercel configuration](./operations/vercel-configuration.md)
+- [Upgrade compatibility](./operations/upgrade-notes.md)
+- [Permissions and moderation after import](./operations/mybb-permissions.md)
+- [MyBB content conversion](./operations/mybb-content.md)
+- [Accounts and messages after import](./operations/mybb-members.md)
+- [Discovery, feeds and search](./operations/mybb-discovery.md)
 
-Create, test and publish themes and plugins.
+## Extensions
 
 ### Get started
 
-- [Build extensions](./extensions/extensions.md) — Extend a board through a theme or plugin.
-- [Write your first plugin](./extensions/first-plugin.md) — Create a plugin, run its tests and load it into a development board.
-- [Build your first theme](./extensions/first-theme.md) — Create a theme that inherits the default board, changes its palette and overrides the footer.
+- [Extension development](./extensions/extensions.md)
+- [Create a plugin](./extensions/first-plugin.md)
+- [Create a theme](./extensions/first-theme.md)
 
 ### Plugin guides
 
-- [Plugin development](./extensions/plugins.md) — A plugin registers behavior with definePlugin from @meith/plugin-kit.
-- [Plugin hooks and lifecycle](./extensions/plugin-hooks-guide.md) — Choose the appropriate filter or event, understand execution order and failure isolation, and manage the lifecycle of an installed plugin.
-- [Plugin UI and content rendering](./extensions/plugin-presentation.md) — Add interface content through the published regions and rendering APIs.
-- [Plugin storage, groups and migrations](./extensions/plugin-storage.md) — Store plugin data, apply forward-only migrations and work with explicitly grantable groups.
-- [Plugin routes and pages](./extensions/plugin-pages.md) — Expose plugin HTTP routes and member, administrator or moderator pages.
-- [Plugin settings, notifications and tasks](./extensions/plugin-services.md) — Declare settings, notify members and schedule background work through the plugin host.
+- [Plugins](./extensions/plugins.md)
+- [Plugin hooks and lifecycle](./extensions/plugin-hooks-guide.md)
+- [Plugin UI and Markdown](./extensions/plugin-presentation.md)
+- [Plugin storage and membership](./extensions/plugin-storage.md)
+- [Plugin routes and pages](./extensions/plugin-pages.md)
+- [Plugin settings, notifications and tasks](./extensions/plugin-services.md)
 
 ### Theme guides
 
-- [Theme development](./extensions/themes.md) — A theme supplies presentation through @meith/theme-kit.
-- [Theme contracts and compatibility](./extensions/theme-contract.md) — Understand the theme boundary, slot compatibility, translation and versioning rules before changing a theme implementation.
-- [Theme tokens and shared controls](./extensions/theme-design.md) — Customize visual tokens and reuse the shared controls.
-- [Test a theme](./extensions/theme-testing.md) — Check a theme against populated, empty and permission-dependent models, then verify it in a browser.
+- [Themes](./extensions/themes.md)
+- [Theme contract](./extensions/theme-contract.md)
+- [Theme tokens and controls](./extensions/theme-design.md)
+- [Test a theme](./extensions/theme-testing.md)
 
 ### Share your work
 
-- [Translate Meith and extensions](./extensions/internationalisation.md) — Use language catalogs to translate the board, themes and plugins.
-- [Publish a theme or plugin](./extensions/marketplace.md) — Publish a tested extension package, then submit a listing for review.
+- [Translations](./extensions/internationalisation.md)
+- [Publish an extension](./extensions/marketplace.md)
 
 ### Reference
 
-- [Plugin hooks](./reference/plugin-hooks.md) — Generated reference for hooks, payloads, and call sites.
-- [Theme slots and view models](./reference/theme-slots.md) — Generated reference for the theme contract.
-
-## Use the API
+- [Plugin hooks](./reference/plugin-hooks.md)
+- [Theme slots and view models](./reference/theme-slots.md)
 
-Connect applications and receive signed board events.
+## Integrations
 
-- [Make your first API request](./integrations/api-quickstart.md) — Read board data from another application using the REST API.
-- [Receive and verify webhooks](./integrations/webhooks.md) — Send board events to an HTTPS endpoint you operate.
-- [REST API v1](./reference/api.md) — Endpoint, scope, and rate-limit reference.
+- [REST API quickstart](./integrations/api-quickstart.md)
+- [Webhooks](./integrations/webhooks.md)
+- [REST API v1](./reference/api.md)
 
-## Contribute to Meith
-
-Develop, test, document and release Meith.
+## Contributing
 
 ### Development workflow
 
-- [Contribute to Meith](./contributing/development.md) — Use this guide to run the Meith source repository and prepare a change.
-- [Architecture](./contributing/architecture.md) — Meith separates business rules, infrastructure and presentation.
-- [Application conventions](./contributing/nextjs-conventions.md) — Use these conventions when changing apps/community.
-- [Run and debug tests](./contributing/testing.md) — Choose the test layer for the behavior you are changing.
-- [Develop accessible interface components](./contributing/ui-conventions.md) — Use the shared design system for forms, panels and destructive actions.
-- [Maintain the documentation](./contributing/documentation.md) — Documentation source lives in docs/.
-- [Brand guidelines](./contributing/brand.md) — How Meith looks, sounds and spends its one colour.
-- [Repository rules and checks](./contributing/repository-checks.md) — Follow the repository contract and run the checks that enforce it.
+- [Development setup](./contributing/development.md)
+- [Architecture](./contributing/architecture.md)
+- [Next.js conventions](./contributing/nextjs-conventions.md)
+- [Testing](./contributing/testing.md)
+- [UI conventions](./contributing/ui-conventions.md)
+- [Maintain documentation](./contributing/documentation.md)
+- [Brand guidelines](./contributing/brand.md)
+- [Repository checks](./contributing/repository-checks.md)
 
 ### Implementation reference
 
-- [Forms and Server Actions](./contributing/forms-and-actions.md) — Build validated, permission-checked mutation flows that work with and without JavaScript.
-- [Rendering, caching and view models](./contributing/rendering-and-data.md) — Keep data access, cache invalidation and theme view models consistent across pages and actions.
-- [Board workspaces and build materialization](./contributing/board-workspaces.md) — Understand the monorepo, external board workspaces and generated board registry.
-- [Maintain the marketplace feed](./contributing/marketplace-maintenance.md) — Maintain listings and the feed consumed by boards.
-- [Performance](./reference/performance.md) — Recorded measurements and performance budgets.
+- [Forms and server actions](./contributing/forms-and-actions.md)
+- [Rendering and data](./contributing/rendering-and-data.md)
+- [Board workspaces](./contributing/board-workspaces.md)
+- [Marketplace maintenance](./contributing/marketplace-maintenance.md)
+- [Performance](./reference/performance.md)
 
 ### Maintainers
 
-- [Release Meith](./contributing/release.md) — This procedure is for maintainers publishing Meith.
-- [Release infrastructure and version policy](./contributing/release-infrastructure.md) — Understand what a release publishes and how packages, images and templates stay in step.
+- [Release Meith](./contributing/release.md)
+- [Release infrastructure](./contributing/release-infrastructure.md)
 
 <!-- docs:index end -->
-
-[Documentation maintenance](./contributing/documentation.md) explains editing, registration and generated references.
diff --git a/docs/administration/antispam.md b/docs/administration/antispam.md
index c5f0e205c..6c3edee16 100644
--- a/docs/administration/antispam.md
+++ b/docs/administration/antispam.md
@@ -1,63 +1,40 @@
-# Configure spam controls
+# Spam controls
 
-Start under **Board settings → Antispam**. Registration questions and content filters also have their own admin screens. Use a normal account to test a change before applying strict limits to the community.
+Open **Board settings → Antispam**. Test changes with an ordinary account.
 
-## Choose a control for the problem
-
-| Problem | Control |
+| Control | Use |
 |---|---|
-| Bots fill every field | Hidden-field trap, enabled by default |
-| Instant form submissions | Minimum fill time, default 3 seconds |
-| Scripted registration | Question challenge |
-| Spam from new accounts | Hold the first posts for approval |
-| Excessive posting, messaging or uploads | Hourly limits and group daily allowances |
-| Repeated community-reported content | Community flag threshold |
-| Prohibited words or patterns | Word filter |
-| Repeated unwanted registration identities | Ban filters |
-
-A short minimum fill time can also catch an autofilled legitimate form. Change one control at a time and inspect the result.
-
-## Configure registration questions
+| Hidden-field trap | Reject automated registration; on by default |
+| Minimum form time | Reject fast registration; default 3 seconds |
+| Registration question | Require an accepted answer |
+| Hold first posts | Review new-member content |
+| Hourly limits | Limit posts, messages, searches, reports and uploads |
+| Community flag threshold | Hold posts reported by enough distinct members |
+| Word and ban filters | Filter content or registration identities |
 
-Choose **Ask a question** as the registration challenge and maintain usable questions under `/admin/antispam`. Provide accepted answers. Matching trims text, ignores case and collapses repeated spaces.
+## Registration questions
 
-Questions deter generic scripts, not determined people. A challenge with no usable questions does not protect registration; the admin screen warns about it. Meith does not require a hosted CAPTCHA provider.
+Select **Ask a question** and add questions with accepted answers at `/admin/antispam`. Matching trims, ignores case and collapses repeated spaces. An empty question set does not protect registration.
 
-## Understand the pre-sign-in limits
+## Registration and reset limits
 
-| Setting | Default | Scope |
+| Key | Default | Scope |
 |---|---|---|
-| `antispam.register_ip_per_hour` | 10/hour | Requesting address range |
-| `antispam.reset_per_hour` | 5/hour | Target email address |
+| `antispam.register_ip_per_hour` | 10/hour | Address range |
+| `antispam.reset_per_hour` | 5/hour | Target email |
 | `antispam.reset_ip_per_hour` | 20/hour | Requesting address range |
-| `antispam.login_ip_attempts` | 100/window | Requesting address range |
-
-Address limits use IPv4 /24 or IPv6 /48 ranges. Members at a school, office or event can share a range, so account for legitimate shared access. Zero disables the corresponding limit.
-
-The password-reset form gives the same public response whether or not an account exists or a limit prevented sending. This avoids revealing account membership.
-
-## Review sign-in lockouts
-
-Failed sign-in counts against three buckets: account plus address, account across addresses, and address across accounts. Defaults are 5, 50 and 100 attempts within `security.lockout_minutes`, which defaults to 15.
-
-The account settings live under Security; the address-volume setting lives under Antispam. These controls are marked advanced. A successful sign-in clears the two account-specific buckets, not the shared address bucket.
-
-If legitimate people are locked out, inspect the actual cause. Do not disable every protection or assume the problem is a wrong password. A password reset has its own independent limits.
-
-## Set posting and upload limits
-
-A flood interval is the minimum time between actions. An hourly cap limits total activity in an hour. Group daily posting and messaging allowances are separate again.
+| `antispam.login_ip_attempts` | 100/window | Address range |
 
-The upload allowance covers attachments and avatars. PostgreSQL stores counters across instances; fixture mode does not provide a writable rate-limit test environment.
+Address ranges are IPv4 /24 or IPv6 /48. Shared networks share allowances. Zero disables a limit. Password reset returns the same public response for unknown accounts and limited requests.
 
-Use [Groups and promotions](groups.md) for daily allowances and [Search settings](search.md) for search-specific controls. Verify the trusted proxy configuration if many unrelated visitors appear to share an address.
+## Sign-in lockouts
 
-## Use flags and filters
+Failures count per account/address, per account across addresses and per address across accounts. Defaults are 5, 50 and 100 within `security.lockout_minutes` (15 minutes). Account limits are under Security; address limits are under Antispam. Success clears the account-specific buckets, not the shared address bucket.
 
-Community flagging can hide content when the configured threshold is reached. Keep a moderator available to review the queue and reverse incorrect decisions.
+## Posting and filters
 
-Use the word-filter screen for supported content substitutions or restrictions, and check its preview before saving. Ban-filter patterns are globs, not regular expressions. Review where each filter applies; adding a registration filter is not a bulk deletion or retroactive ban of existing members.
+Flood intervals, hourly caps and [group daily allowances](groups.md) are independent. Upload limits cover avatars and attachments. PostgreSQL retains counters across instances.
 
-## Diagnose blocked registration
+Review community-flagged posts in moderation. Check word-filter previews before saving. Ban patterns are globs, not regular expressions; registration filters do not retroactively ban accounts.
 
-Check whether registration is open, whether approval or email confirmation is required, whether a question has usable answers, and which rate-limit or filter message appears. Test from a normal browser session without repeatedly consuming the same limit. For missing confirmation mail, follow [Email](../operations/mail.md).
+For blocked registration, check registration policy, activation, question answers, filters and the displayed limit. For shared or incorrect client addresses, check [trusted proxies](../operations/web-security.md). For undelivered activation links, check [mail](../operations/mail.md).
diff --git a/docs/administration/appearance.md b/docs/administration/appearance.md
index ccb6f29a6..3a8741ce6 100644
--- a/docs/administration/appearance.md
+++ b/docs/administration/appearance.md
@@ -1,91 +1,34 @@
-# Change the board appearance
+# Appearance
 
-Change the board name, logo, theme, colors and fonts through the admin panel. You need permission to administer the board; installing a new theme package also needs an operator.
+## Name and images
 
-## Making the board look like yours
+Set **Board name**, description and **Logo alt text** at `/admin/settings?group=board`. Empty logo alt text uses the board name.
 
-Everything in this section changes on the running board, from the panel,
-with nothing redeployed.
+Upload light and dark logos at **Admin → Themes** (`/admin/themes`). PNG, JPEG, WebP and SVG are accepted up to 512 KiB. If only a light logo exists, both modes use it. Without a logo, the header displays the name.
 
-### The name
+Set **Favicon** under Board settings or on the themes page. It accepts the same formats and limit.
 
-The board's name — in the header, in every page title, and on outgoing
-mail — is **Board name** under **`/admin/settings?group=board`**. There
-is nowhere else it is written down, so changing it there changes it
-everywhere.
+| Asset | Fallback |
+|---|---|
+| Browser icon | Board initials in the default theme colour |
+| Home-screen icon | PNG/JPEG favicon, usable light logo, then initials |
+| Shared-link image | Logo, board name and description on the theme background |
 
-### The logo
+Generated assets follow identity and default-theme changes. SVG/WebP favicons still work in the browser tab but are not rasterized for home-screen icons.
 
-**Admin → Themes** (**`/admin/themes`**) takes a logo to show in place
-of the name, as **two uploads: light and dark** — one image that reads
-on a white page usually disappears on a black one. Upload only the light
-one and it is used everywhere. PNG, JPEG, WebP or SVG, up to 512 KiB.
+## Themes and tokens
 
-With no logo, the header shows the board's name in text — which is where
-every board starts and where most stay. The logo's alt text, for screen
-readers, is **Logo alt text** under the board settings; left empty it
-becomes the board's name.
+At **Admin → Themes**:
 
-### The tab icon, home-screen icon and shared links
+- Enable themes members may choose.
+- Set the default for visitors without a selection.
+- Edit light/dark colours, fonts, radius and spacing; check the preview.
+- Export overrides to a file or import them on another board.
 
-The browser-tab icon (favicon), the icon a phone saves when someone adds
-the board to their home screen, and the picture that appears when a board
-link is pasted into a chat or posted to a social network are **drawn from
-what you have already set** — the board name, the default theme's colours,
-and the logo when there is one — unless you upload a favicon of your own.
+**Reset** and **Import** replace all stored overrides and require password confirmation. Panel changes do not require deployment. [Installing another theme](../operations/installing.md) does.
 
-- The **favicon** is **Favicon** under **`/admin/settings?group=board`**,
-  the same square icon field the logo sits beside on the themes page —
-  PNG, JPEG, WebP or SVG, up to 512 KiB. Leave it empty and the **tab
-  icon** is a small square with the board's initials in the theme's
-  primary colour, following the reader's light or dark mode; upload one
-  and it is shown instead.
-- The **home-screen icon** — the board installs as a progressive web app
-  — uses the uploaded favicon when it is a PNG or JPEG, otherwise the
-  light logo, otherwise the initials, centred on the theme background.
-- The **link preview** (Open Graph and X/Twitter card) shows the logo,
-  the board name and its description on the theme background.
+The Clubhouse theme provides primary and trim colours and generates a crest when no logo is uploaded.
 
-Change the name, upload a favicon or a logo, or set a new default theme
-and all of these follow at once; there is no separate step and no cache to
-clear. The raster home-screen icons are drawn from a PNG or JPEG only — an
-SVG or WebP favicon still shows in the browser tab, and the home-screen
-icons fall back to the logo, then to the board's initials and name.
+## Installation prompt
 
-Installing is something a reader has to discover in their browser's menu,
-so the board can point at it for you: **Offer to install the board**, under
-**`/admin/settings?group=board`**, pins a dismissable bar to the bottom of
-small screens inviting the reader to add the board to their home screen —
-with an Install button that opens the browser's own prompt where one
-exists, and brief directions where none does. It never shows inside the
-installed app, dismissing it keeps it away on that device for a year, and
-it is off by default: turn it on while you want installs encouraged, and
-off again once the point is made.
-
-### Colours, fonts and themes
-
-The same **Admin → Themes** screen holds, per theme:
-
-- **On or off** — an enabled theme appears in the appearance control at
-  the foot of every page, and any member can pick it for themselves.
-- **The default** — what a visitor who has chosen nothing sees.
-- **Token values** — colours, corner radius, spacing and fonts, each
-  with separate light and dark values, with a sample that repaints as
-  you change them.
-- **Export and import** — a look can be saved as a file and moved to
-  another board.
-
-Most controls here are freely reversible. **Reset** and **Import** are
-the exceptions — each replaces every stored override in one press — so
-both ask for your password again.
-
-If your community has a crest and two colours — a sports club, say —
-the shipped **clubhouse** theme is built for exactly that: set the main
-colour and the trim colour on the theme screen and everything else
-stays neutral. With no logo uploaded it draws a crest from the board's
-name.
-
-> [!NOTE]
-> *Configuring* a theme is yours; *installing* a new one is not. A theme
-> is part of the deployed code, so adding one is a deploy — see the
-> [last section](manage-members.md#when-to-hand-it-to-somebody-technical).
+Enable **Offer to install the board** under Board settings to show a dismissible prompt on small screens. Supported browsers open their native install prompt; others show instructions. The prompt is hidden in the installed app. Dismissal lasts one year on that device. The setting is off by default.
diff --git a/docs/administration/awards-guide.md b/docs/administration/awards-guide.md
index 2c090c194..aa3da382c 100644
--- a/docs/administration/awards-guide.md
+++ b/docs/administration/awards-guide.md
@@ -1,33 +1,29 @@
-# Give awards and achievements
+# Awards
 
-Awards recognizes contributions without granting permissions. An operator must install `@meith/plugin-awards` and apply its migrations. Administrators then work under **Admin → Plugins → Awards**.
+Install `@meith/plugin-awards`, apply its migrations and open **Admin → Plugins → Awards**. Awards do not grant permissions.
 
-## Create an award
+## Create and grant
 
-Enter a name, description and icon. Supported icons include emoji, built-in names and image URLs; there is no icon upload. Remote images also need the board's remote-image setting.
+1. Create an award with name, description and icon (emoji, built-in name or image URL).
+2. Set its order and whether repeat grants are allowed.
+3. Open **Grant awards**, select it and enter comma-separated usernames and an optional reason.
 
-Choose display order and whether a member may hold the award more than once. Changing to single-only is refused while duplicates exist.
+There is no icon upload. Remote icons require remote-image permission. Unknown usernames stop the request; existing single-only grants are skipped. Switching to single-only is refused while duplicates exist.
 
-**Listed in the catalogue** controls discovery, not privacy: an unlisted award can still appear on a holder's profile. **Archive** hides it publicly and stops new grants while retaining history. Delete is available only when there are no grants.
+Unlisted awards still appear on profiles. **Archive** hides an award publicly and stops grants, preserving history. Delete requires no grants.
 
-## Grant or revoke an award
+Find and revoke grants in the recent-grants table. Notification failure does not undo a saved grant.
 
-Open **Grant awards**, choose the award, enter comma-separated usernames and an optional reason, then submit. Unknown names stop the request before assignment. Existing single-only awards are skipped.
+## Automatic achievements
 
-Use the recent grants table and username filter to find a grant and revoke it. Members can be notified according to the plugin setting and their delivery preferences. A notification failure does not undo an already saved grant.
+Create a rule using post, thread, reputation or days-registered thresholds. All configured thresholds must pass. Set at least one criterion. Blank criteria are ignored; zero is a valid threshold. Tenure uses elapsed 24-hour periods.
 
-## Create an automatic achievement
+Rules grant once per member while the grant exists. Changing or disabling a rule does not revoke awards. Revoked awards can be re-earned while the rule remains active.
 
-Under **Rules**, choose an award and enter one or more supported thresholds: posts, threads, reputation or days registered. Every configured threshold must be satisfied. Blank criteria are ignored; an explicit zero allows every member for that criterion. Tenure uses elapsed 24-hour periods.
+**Run now** processes one bounded batch. **Re-check everyone** resets the scan cursor. Check the cursor and completed-pass status on large boards.
 
-A rule grants once per member while its grant exists. Raising a threshold or disabling/deleting a rule does not revoke previous awards. If you revoke a rule-earned award while the rule remains enabled, it can be granted again when the member is evaluated.
+## Display
 
-**Run now** evaluates a bounded batch. **Re-check everyone** resets the full-scan cursor. Large boards need multiple scheduled runs; inspect the cursor and last completed pass rather than assuming one click evaluated every member.
+Verify `/plugins/awards`, profiles and posts. **Maximum awards beside each post** defaults to 5; zero hides them. Additional distinct awards use a +N link.
 
-## Check the member display
-
-Open `/plugins/awards`, a holder's profile and one of their posts. **Maximum awards beside each post** defaults to 5; zero hides them. Additional distinct awards appear through a +N link.
-
-**Show manual grant reasons publicly** is on by default. Turn it off when reasons should remain in administration. Award dates use UTC. Other application instances can show cached award information for up to a minute after changes.
-
-Account deletion removes grants; account merging moves them and collapses relevant duplicates. Awards do not provide repeating tiers, categories or automatic revocation when eligibility later falls.
+**Show manual grant reasons publicly** defaults on. Dates use UTC; other instances can cache changes for up to one minute. Account deletion removes grants; merging transfers them and collapses duplicates. Automatic revocation, repeating tiers and categories are unsupported.
diff --git a/docs/administration/calendar.md b/docs/administration/calendar.md
index ddb73487a..b5dd605ac 100644
--- a/docs/administration/calendar.md
+++ b/docs/administration/calendar.md
@@ -1,37 +1,29 @@
-# Run community events
+# Calendar
 
-The Calendar plugin adds events, recurring occurrences and member responses. An operator must install the plugin and apply its migrations before administrators configure it.
+Install the Calendar plugin and apply its migrations before configuration.
 
-## Open the calendar
+## Create events
 
-Use the board's Calendar navigation item. Open an occurrence to see its details and, when signed in, respond **Yes**, **No** or **Maybe**. You can change or clear your answer. Responses belong to that occurrence, not the whole series.
+Administrators manage the organiser roster in the plugin's admin pages. By default, only roster members create events. **Any member may add an event** permits all signed-in members. The creator and organisers may remove events.
 
-Counts are visible to board readers. Only the event creator and organiser roster can see the username-and-response list. Other members see their own response alongside the counts.
+Dates use UTC. Recurrence behaves as follows:
 
-## Choose who creates events
+| Frequency | Rule |
+|---|---|
+| Weekly/fortnightly | Fixed 7/14-day intervals; local times may shift at daylight-saving changes |
+| Monthly | Same UTC day; skips months without that date |
+| End date | Inclusive |
 
-Administrators manage the organiser roster in the plugin's admin pages. By default, only roster members create events. **Any member may add an event** permits all signed-in members; guests still cannot add one.
+Editing preserves responses on unchanged UTC dates. Occurrences moved to another UTC date need new responses. Deleting an event removes responses.
 
-The shipped plugin uses this roster, not an arbitrary community group. The event creator and organisers can remove an event.
+## Respond and export
 
-## Set dates and recurrence
+Open an occurrence and choose **Yes**, **No** or **Maybe**. Change or clear the answer on that occurrence. Readers see counts; only the creator and organisers see the full response list. Other members see their own response.
 
-Calendar forms and labels use **UTC**. Weekly and fortnightly series advance by fixed seven- or fourteen-day intervals; local clock times can shift at daylight-saving changes. Monthly series keep the UTC day and skip months without that date. The optional end date is inclusive.
+Download `.ics` to add the event to a calendar app. Recurring exports describe the series. Events without end times export with a one-hour duration. The event URL is used before any associated thread URL.
 
-Editing a series preserves responses on unchanged UTC dates. A moved occurrence needs new responses; removed occurrences no longer show their old responses. Deleting the event removes its responses.
+## Reminders
 
-Upcoming includes ongoing events; Past contains completed ones. Follow the pagination links for more occurrences, or browse a specific month.
+Set **Reminder lead time (hours)** from 0–168; default 2, zero disables. Yes/Maybe respondents receive a board notification. Email requires member opt-in.
 
-## Export to a calendar app
-
-Download the event's `.ics` file and open it in your calendar application. Recurring exports describe the series. The receiving application displays times in its configured zone. An event without an end time is exported with a one-hour duration.
-
-An event's own URL is preferred as the calendar link; otherwise the associated thread supplies it.
-
-## Configure reminders
-
-**Reminder lead time (hours)** defaults to 2 and accepts 0–168, including fractions. Set 0 to disable reminders. Members who answered Yes or Maybe receive a board notification before the occurrence. Email reminders are off by default and can be enabled in the member's notification preferences.
-
-The reminder task runs every five minutes when the board scheduler is running. It catches up only before the occurrence starts and processes a bounded batch, so a large backlog can delay delivery. A crash can cause a delivery retry; reminders are not an exactly-once guarantee.
-
-If reminders stop, have the operator check [Scheduled tasks](../operations/scheduled-tasks.md).
+The reminder task runs every five minutes with an active scheduler. It processes bounded batches and catches up only before the occurrence starts. Retries can duplicate delivery. See [Scheduled tasks](../operations/scheduled-tasks.md).
diff --git a/docs/administration/community-communications.md b/docs/administration/community-communications.md
index ba54c089f..664fd8129 100644
--- a/docs/administration/community-communications.md
+++ b/docs/administration/community-communications.md
@@ -1,109 +1,39 @@
-# Announcements, navigation and community email
-
-Use the admin panel to publish announcements, arrange navigation and send community updates. Choose the tool that matches where and when members should see the message.
-
-## Telling people things
-
-### Announcements
-
-**Admin → Content → Announcements** puts a dated notice above the
-forums. An announcement is not a pinned thread: nobody can reply to one,
-it disappears on its own end date, and removing it removes nothing
-anybody wrote — which is what makes it safe to delete when it is stale.
-
-Each one has a title, a Markdown message (rendered the same way a post
-is), a **From** date, an optional **Until** date (blank never expires),
-and a place: **the whole board**, or one forum — a forum's announcement
-is shown to whoever can see that forum, so an announcement on the
-organisers' forum reaches only the organisers. Dates are entered in UTC,
-and the screen says so. The list shows each announcement's state at a
-glance: showing now, scheduled, expired, or switched off.
-
-### The navigation menu
-
-**Admin → Content → Navigation** is the menu across the top of every
-page. A new board shows three items — Home, New posts and Search — and
-keeps the board's other five pages on the screen beside them, hidden:
-Unanswered, My posts, Who's online, Members and Staff. Tick **Shown in
-the menu** on any of them to add it. All eight are ordinary rows: rename
-one, move it, hide it, or delete it, and add links of your own beside
-them. A link can point at a page on the board or at any web address —
-the community's main site, the fixtures list, an events calendar.
-
-Each item can be shown to everyone, only signed-out visitors, only
-signed-in members, or only staff — and, more narrowly, only to members
-of groups you tick. Items can be nested one level deep into sub-menus by
-dragging.
-
-### The member list and the staff page
-
-**`/members`** lists every account on the board — searchable by name,
-sortable by name, post count or newest arrival — with each member's
-displayed groups beside their name. It is shown to anyone whose groups
-carry the *Browse the member list* permission, which every shipped group
-grants; untick it on Guests to keep the list to signed-in members.
-
-**`/staff`** is the other half of the [staff group flag](groups.md):
-every group marked as a staff group appears there in its display order,
-listing everyone who holds it — by primary group or live membership.
-A staff group nobody is in stays off the page.
-
-### Mass mail
-
-**Admin → Users → Mass mail** (**`/admin/users/mail`**) sends an e-mail
-to everybody, or to one group — the Committee group from earlier, say.
-Either way it reaches only accounts that are active, not closed, have a
-verified address **and have asked the board for its announcements**, and
-the screen shows the size of each audience beside it, so the figure next
-to a group is how many messages choosing it will queue.
-
-That last condition is the important one, and it is why a brand-new
-board's audience is nought. Nobody is enrolled by registering. A member
-asks for announcements by ticking the box on the registration form, or
-later on their own **Notifications → Preferences** screen; both start
-unticked, and the board records the date consent was given. Every
-message carries an unsubscribe link at its foot, so a member can stop
-them from the message itself, without signing in — and once they do,
-they are out of every campaign that follows, including one already half
-sent.
-
-So mass mail is the wrong tool for anything every member must see: it
-reaches the members who asked, not the membership. A pinned thread or an
-[announcement](#announcements) reaches everybody who visits.
-
-Mass mail is queued and delivered in the background, so it needs the
-board's mail working and its background worker running — if a mass mail
-sits unsent, that is one for the technical person, and
-[Operations § Mail](../operations/mail.md) is their page.
-
-### Board activity digest
-
-Every member's **Notifications → Preferences** screen lists a **board
-activity digest**, off by default like every other e-mail on that
-screen. A member who turns it on also picks how often — **weekly** or
-**monthly** — from the box beside it.
-
-The digest is not sent to everybody who turns it on: it is aimed
-specifically at members who have drifted away. A member is due one only
-once they have not visited the board for a run of days you set —
-**Admin → Settings → Board → "Board digest: days away before a member
-counts as lapsed"**, seven days out of the box — and even then only when
-their own chosen cadence has actually elapsed. A member who reads the
-board most days never gets one, however long they leave the feature
-switched on.
-
-What it lists is the busiest threads since that member's own last visit,
-built for them alone: the same forum permissions that decide what they
-can open on the board decide what a digest may name, so two members
-turned lapsed on the same day can receive two different digests, and
-neither ever sees a thread in a forum closed to them. Every digest
-carries its own unsubscribe link, and using it switches off only the
-board digest — every other notification preference, and the member's
-account, are untouched.
-
-### Closing for maintenance
-
-**Board offline**, under **`/admin/settings?group=board`**, replaces
-every board page with a message of your choosing until you switch it
-back. Signing in and the admin panel stay reachable, so you can always
-turn it off again.
+# Announcements, navigation and email
+
+## Announcements
+
+At **Admin → Content → Announcements**, enter a title, Markdown body, UTC start, optional end and target forum or whole board. A blank end never expires. Forum announcements follow forum visibility. Announcements cannot receive replies.
+
+## Navigation
+
+At **Admin → Content → Navigation**, add, rename, reorder, hide or delete links. **Shown in the menu** controls visibility. Links may target board pages or external URLs.
+
+Choose everyone, guests, members or staff, then optionally restrict by group. Drag items to create one level of submenus.
+
+New boards show Home, New posts and Search. Unanswered, My posts, Who's online, Members and Staff start hidden.
+
+## Member and staff lists
+
+`/members` requires **Browse the member list**. Remove this permission from Guests to require sign-in. Members can search by name and sort by name, posts or arrival date.
+
+`/staff` lists occupied staff-flagged groups in display order, including primary and active additional memberships.
+
+## Mass mail
+
+1. Open **Admin → Users → Mass mail** (`/admin/users/mail`).
+2. Choose all eligible members or a group; check the displayed audience count.
+3. Compose and queue the message.
+
+Recipients must be active, open accounts with verified email and announcement consent. Registration alone does not enrol them. Unsubscribing excludes a member from subsequent delivery, including a campaign already running.
+
+Mass mail needs working [mail](../operations/mail.md) and [scheduled tasks](../operations/scheduled-tasks.md). Use an announcement or thread for information all visitors must see.
+
+## Board activity digest
+
+Members opt in to weekly or monthly digests under **Notifications → Preferences**. A digest is due only after both the selected cadence and the configured absence period. Set **Board digest: days away before a member counts as lapsed** under Board settings; default 7 days.
+
+Digests list busy threads since the member's last visit, filtered by their permissions. Digest unsubscribe links disable only this digest.
+
+## Maintenance mode
+
+Enable **Board offline** at `/admin/settings?group=board` and enter the message to display. Sign-in and the admin panel remain accessible so an administrator can reopen the board.
diff --git a/docs/administration/first-steps.md b/docs/administration/first-steps.md
index 9d20e6578..37fc9f81f 100644
--- a/docs/administration/first-steps.md
+++ b/docs/administration/first-steps.md
@@ -1,37 +1,14 @@
-# Set up your community
+# Set up a community
 
-Complete this checklist after installation, using the administrator account you created. If the board is not running yet, start with [Choose a deployment](../operations/deployment.md).
+Complete [installation](../operations/deployment.md), then sign in as the administrator.
 
-## 1. Open the admin panel
+1. Open `/admin` and re-enter your password.
+2. Under **Board settings → Board**, set the name, description and public URL. Under **Themes**, choose the default theme and logo.
+3. Under **Board settings → Legal**, publish Rules & FAQ, terms and privacy text. Non-empty pages appear in the footer.
+4. At `/admin/settings?group=mail`, configure delivery and select **Send a test message to me**. Confirm receipt before requiring email activation.
+5. At `/admin/settings?group=registration`, choose whether registration is open and requires email confirmation, administrator approval or both.
+6. Create [forums](forums.md), set [group permissions](groups.md) and appoint moderators.
+7. Test registration, password reset, posting, attachments and private-forum visibility as an ordinary member and a guest.
+8. Confirm [scheduled work](../operations/scheduled-tasks.md), an off-site [backup](../operations/backups.md) and a successful restore rehearsal.
 
-Sign in and open `/admin`. Re-enter your password to start the panel's separate session. On a phone, open the panel menu to reach its sections.
-
-## 2. Set the identity and rules
-
-Under **Board settings → Board**, check the name, description and public address. Under **Themes**, select the default appearance and upload the logo. Use **Board settings → Legal** for the Rules & FAQ, terms and privacy pages.
-
-Open the board while signed out to check the header, footer and published rules. [Board appearance](appearance.md) covers colors, fonts and images.
-
-## 3. Prove email works
-
-Open `/admin/settings?group=mail`, save the sending configuration and select **Send a test message to me**. Confirm receipt in the mailbox.
-
-Only then choose the registration policy under `/admin/settings?group=registration`: open or closed, and whether accounts require email confirmation, administrator approval or both. Use [Email](../operations/mail.md) if the test fails.
-
-## 4. Create the initial forums
-
-Rename the first forum and add a small set of categories and forums at **Admin → Forums**. Give each a clear purpose. Follow [Forums and permissions](forums.md) for a private staff area.
-
-Appoint moderators to the relevant forums and give them the [moderation guide](moderation-guide.md). Check which actions each appointment permits.
-
-## 5. Test as an ordinary member
-
-Create a test member account and sign out to test as a guest too. Verify that each sees the intended forums, that posting works where allowed, and that private forums stay private. Administrator bypasses can hide mistakes in permission setup.
-
-Test registration, password reset, attachments, navigation and the rules links. Post a welcome thread describing where new members should begin. Share the [Member guide](../members/member-guide.md).
-
-## 6. Confirm the operational handover
-
-Ask the operator to demonstrate that scheduled work runs, an off-site backup exists and a restore has been tested. Record who handles hosting, account recovery and incidents.
-
-Continue with [Community administration](organiser-guide.md) for day-to-day work and [Server operations](../operations/operating.md) for the hosting checklist.
+Record who handles hosting and account recovery. Use [Administration](organiser-guide.md) for routine tasks.
diff --git a/docs/administration/forums.md b/docs/administration/forums.md
index b70085d33..091c9a247 100644
--- a/docs/administration/forums.md
+++ b/docs/administration/forums.md
@@ -1,66 +1,51 @@
-# Create forums and control access
+# Forums and permissions
 
-Create and arrange forums at **Admin → Forums** (`/admin/forums`). You need administrator access. After changing access, test with a normal member account and while signed out.
+Open **Admin → Forums** (`/admin/forums`).
 
-## Create and arrange forums
+## Create a forum
 
-Use **Add forum**, choose its type, enter a title and slug, and save.
+Select **Add forum**, choose a type, enter its title and slug, then save.
 
-| Type | Purpose |
+| Type | Content |
 |---|---|
-| Category | Groups related forums; can also hold threads when Allow new threads is enabled |
-| Forum | Holds threads and optional subforums |
-| Link | Sends the reader to another URL; cannot contain children |
+| Category | Forums; threads when **Allow new threads** is enabled |
+| Forum | Threads and optional subforums |
+| Link | Redirect URL; no children |
 
-Use drag handles or the up/down/in/out buttons to arrange the tree. The buttons also work without JavaScript. Moving a forum moves its descendants and changes the permissions they inherit from their parent. Re-parenting requires password confirmation.
+Arrange rows with drag handles or the up/down/in/out buttons. Moving a forum moves its descendants and changes inherited permissions. Re-parenting requires password confirmation. A forum cannot be its own descendant, sit inside a link or share a sibling's slug.
 
-A forum cannot become its own descendant, move inside a link row, or share a slug with a sibling.
+**Open for posting**, **Allow new threads** and **Allow replies** are separate switches. Group grants cannot override a closed forum. Set prefixes, polls, attachments and approval requirements on the forum page.
 
-## Configure posting
+## Set permissions
 
-Open a forum to change its description, posting switches, thread prefixes, polls, attachments and approval requirements. **Open for posting**, **Allow new threads** and **Allow replies** are separate controls.
+Open **Permissions**, edit the group columns and save. Each group uses the nearest explicit forum or ancestor value, then its group default. Multiple groups combine as follows:
 
-These forum options apply alongside member permissions. Granting a group permission does not make a closed forum accept posts.
-
-## Understand permission inheritance
-
-Open the forum's **Permissions** tab. Rows are permissions and columns are groups.
-
-For each group, the nearest explicit value on the forum or its ancestors wins; otherwise the group's default applies. The resulting group values are then combined:
-
-| Permission kind | Combination |
+| Kind | Result |
 |---|---|
-| Grant/deny switches | A grant from any group permits the action |
-| Numeric allowances | The most generous value wins; 0 means unlimited |
-| Requires approval | Approval is required only when all the member's groups require it |
+| Permission | Any grant allows the action |
+| Numeric allowance | Highest value wins; 0 is unlimited |
+| Approval requirement | Required only if every group requires it |
 
-**Inherit** leaves a value unset; it is not a denial. A blank numeric field inherits, while an explicit zero means unlimited. The matrix shows the effective inherited value beneath an unset control.
+**Inherit** is unset, not denied. A blank numeric field inherits; zero is unlimited. Denying one group cannot cancel another group's grant.
 
-> [!IMPORTANT]
-> Denying a permission to one group does not cancel a grant from another. Review every group held by the member.
+**Copy to subforums** replaces descendant overrides, including clearing values the source inherits. Review the preview before confirming your password.
 
-Save the matrix after editing. **Copy to subforums** replaces descendant overrides with the source's stored overrides, including clearing values the source inherits. Review its preview and confirm your password before applying it.
+## Make a private forum
 
-## Create a private staff forum
+1. Create the intended group and assign members.
+2. Create the forum.
+3. Deny viewing to Guests and every ordinary group that otherwise grants it.
+4. Grant the intended access to the private group.
+5. Test with guest, ordinary and authorised accounts.
 
-1. Create a staff group and assign the intended members.
-2. Create the forum in its intended position in the tree.
-3. In Permissions, deny viewing for Guests and every ordinary group that would otherwise grant it.
-4. Grant viewing and the intended posting rights to the staff group.
-5. Save, then check as a guest, an ordinary member and a staff member.
-
-An administrator account alone cannot prove the forum is private. Search, feeds and API reads use the same visibility rules, but verify the resulting audience through the ordinary member experience.
-
-For a support forum where members should read only their own threads, review **see threads started by other users** (`canViewOthersThreads`). Grant enough access to enter the forum and create threads, while denying that additional visibility where appropriate.
+For an own-thread-only support forum, allow entry and posting but restrict **see threads started by other users** (`canViewOthersThreads`).
 
 ## Appoint moderators
 
-Open the forum's moderator controls and appoint a member or group with only the required actions. Approval, editing, deletion, restoration, locking, pinning, moving, merging and splitting are separate capabilities.
-
-Ask moderators to check **My forums** at `/modcp/forums`. Appointments do not automatically grant every board-wide administrative capability. The [moderation guide](moderation-guide.md) explains the work they can perform.
+Appoint a member or group in the forum's moderator controls. Approval, editing, deletion, restoration, locking, pinning, moving, merging and splitting are separate grants. Check any cascade to subforums.
 
-## Verify changes
+Moderators can inspect their appointments at `/modcp/forums`. See [Moderation](moderation-guide.md).
 
-Check viewing, a new thread, a reply and any restricted action using representative accounts. If access is unexpected, inspect all groups, ancestor overrides, the forum's own options and moderator appointments before adding another override.
+## Diagnose access
 
-[Groups and promotions](groups.md) covers board-wide permissions and allowances. [Migration permissions](../operations/mybb-permissions.md) explains differences to check when importing a legacy board.
+Check all group memberships, ancestor overrides, forum switches and moderator appointments. Test with ordinary accounts; administrators can bypass restrictions. See [Groups](groups.md) and [Imported permissions](../operations/mybb-permissions.md).
diff --git a/docs/administration/groups.md b/docs/administration/groups.md
index 6c5f15434..6feb55656 100644
--- a/docs/administration/groups.md
+++ b/docs/administration/groups.md
@@ -1,49 +1,35 @@
-# Manage groups and promotions
+# Groups and promotions
 
-Groups grant permissions, set allowances and control member identity. Manage them at **Admin → Groups**. Use forum-specific overrides in [Forums and permissions](forums.md).
+Open **Admin → Groups**. Members have one primary group and can hold additional groups. Both contribute permissions.
 
-## Create or edit a group
+## Set permissions and allowances
 
-Open a group to set its title, permissions and limits. A member has a primary group and may hold additional groups. Review the combined permissions before adding a powerful group to an account.
+Any group can grant a permission. Numeric allowances use the highest value, with zero meaning unlimited. Approval is required only when every group requires it. [Forum overrides](forums.md) apply before groups combine.
 
-| Setting kind | How multiple groups combine |
+| Setting | Limit |
 |---|---|
-| Permission switch | Any group can grant it |
-| Numeric allowance | Most generous value wins; 0 means unlimited |
-| Approval requirement | A group that does not require approval can exempt the member |
+| `maxPostsPerDay` | Thread starts and replies per UTC day |
+| `maxPrivateMessagesPerDay` | Sends per UTC day; recipient count does not multiply it |
+| `privateMessageQuota` | Stored messages |
 
-Panel access and administrator authority are distinct permissions. Give only the role the member needs, then verify it with the member's account.
+Daily allowances are separate from flood intervals and hourly limits. Flood bypass does not remove daily allowances. Panel access and administrator authority are separate permissions.
 
-## Set posting and message allowances
+## Set display identity
 
-`maxPostsPerDay` limits thread starts and replies together. `maxPrivateMessagesPerDay` limits sends; one send counts once regardless of the number of recipients. Both use UTC days, and zero means unlimited.
+Set title, order, badge and light/dark name colours. The staff flag includes non-empty groups on `/staff`.
 
-These daily allowances are separate from flood intervals and hourly spam controls. Bypassing flood checks does not remove a group's daily allowance.
+Members can select an ordinary display group under **Account → Profile**. **Maximum displayed groups** controls the number of titles shown; the leading group supplies colour and badge. Staff authority remains visibly identified.
 
-`privateMessageQuota` controls stored messages, not the daily send rate. Increasing a send allowance does not free a full inbox.
+## Allow plugin grants
 
-## Configure group identity
-
-Choose a title, display order, badge and optional name colors. Check light and dark variants; a color that works on one background may not work on the other. The staff-group flag determines which groups appear on `/staff`.
-
-Members with a choice of ordinary groups can select a display group under **Account → Profile**. The board's **Maximum displayed groups** setting controls how many group titles appear. The leading group supplies the main name color and badge.
-
-Staff and groups carrying administrative or moderation authority remain visibly identified as staff. A purchased or selected display group must not hide that responsibility.
-
-## Let a plugin grant a group
-
-Enable **may be granted by plugins** only on groups intended for plugin-managed membership. Staff and power-carrying groups cannot be made grantable this way.
-
-A paid membership can grant access, a badge or other ordinary group benefits. Configure the group's permissions first, then select it in the plugin. Read [Dues](membership-guide.md) for paid memberships.
+Enable **may be granted by plugins** on ordinary groups a plugin may assign. Staff and other powerful groups cannot be grantable. Configure permissions before selecting the group in [Dues](membership-guide.md).
 
 ## Configure promotions
 
-Use the Promotions page to create rules that move eligible members into a group based on the supported activity, tenure and reputation criteria. Check whether the rule changes primary membership or adds membership, then test it on a representative account.
-
-Promotions depend on scheduled work. If a qualifying account does not change, inspect the rule, member values and scheduler status rather than repeatedly adding the group manually.
+Create activity, tenure or reputation rules under **Promotions**. Check whether the rule changes the primary group or adds membership. Review the eligible-member preview before applying it.
 
-## Move members or remove a group
+The preview stops at 50,000 members and reports truncation. Enabled rules run hourly in batches of 10,000, retaining their position between runs. Manual application does not change the schedule.
 
-Review memberships and affected permissions before moving accounts. Ensure members retain a valid primary group and that no paid plan or plugin grant still relies on a group you intend to remove. Follow the panel's validation and confirmation messages.
+## Remove a group
 
-After any structural change, check private forums and staff access using ordinary accounts.
+Check memberships, paid plans and plugin grants first. Keep a valid primary group for each account. After changing roles or deleting a group, test staff and private-forum access.
diff --git a/docs/administration/manage-members.md b/docs/administration/manage-members.md
index f2db4a966..a91278d1a 100644
--- a/docs/administration/manage-members.md
+++ b/docs/administration/manage-members.md
@@ -1,156 +1,38 @@
-# Manage members and registration
-
-Configure registration, welcome new members and manage their group memberships. Use a normal member account to check the result of permission changes.
-
-## Welcoming and managing members
-
-### Registration
-
-**`/admin/settings?group=registration`** holds the two settings that
-decide how people join:
-
-- **Allow new registrations** — off closes the board to new members:
-  the Register link goes, and the registration page says the board is
-  not taking new members. Existing members sign in as before, so it is
-  the switch to reach for during a spam wave, or for a board that is
-  meant to be invitation-only.
-- **Activation method** — what a new account must do before it can sign
-  in: nothing, follow an e-mailed confirmation link, wait for an
-  administrator's approval, or both.
-
-> [!IMPORTANT]
-> Requiring an e-mailed link on a board whose mail is not working is a
-> board nobody can join — the links are minted and never delivered. The
-> registration settings screen warns loudly while this is true. If you
-> see that warning, mail is the thing to fix first — see
-> [Operations § Mail](../operations/mail.md).
-
-The registration form also carries one optional, unticked box: whether
-the board may e-mail the new member its announcements. It is the consent
-[Mass mail](community-communications.md#mass-mail) runs on. Leaving it unticked costs the applicant
-nothing, and a member can change their mind either way at any time from
-**Notifications → Preferences**.
-
-Registration questions and the other anti-spam controls live at
-**Admin → Anti-spam**.
-
-An account stuck at "awaiting activation" — the member who never
-received their link — can be activated by hand: find them under
-**Admin → Users** and change the state on their screen.
-
-The user list also supports selecting up to 500 accounts on the current
-page. A selection can be banned with one shared staff reason, added to an
-additional group, or sent to the prune review screen. Pruning never closes
-accounts from the list itself: the review rechecks that each account has no
-content, ban or staff role, lists the eligible accounts, and asks for fresh
-admin authentication before closing them.
-
-Reversible user actions show an **Undo** control for ten minutes. The undo
-belongs to the administrator who performed the action, works once, and is
-recorded in the admin log. Actions that discard content or credentials —
-including pruning, merging accounts and clearing a second factor — stay
-confirmation-only because recreating the previous state would be misleading
-or unsafe.
-
-### Onboarding new members
-
-A member who has not posted yet sees a light, dismissible sequence of
-prompts, in order: a welcome notice below the header, then — once that
-is dismissed — a nudge to add an avatar and a bio if either is still
-missing, then, the first time they open the composer, a short notice
-above the form. None of it blocks posting, none of it needs
-JavaScript, and each prompt is remembered per browser once dismissed —
-it dismisses through a plain link, so it also works with JavaScript
-off. A member stops seeing all of it the moment they post.
-
-The composer notice links to a **Rules & FAQ** page when one is
-published. Write it at **`/admin/settings?group=legal`**, alongside
-the terms of service and privacy policy — like those two, it is
-Markdown, it is linked from the footer once non-empty, and it is
-unpublished (and the composer notice drops its link) while empty. It
-ships empty: there is no default text to edit around.
-
-### Roles are group memberships
-
-A member's rights come from the groups they are in. Every board starts
-with the same seeded groups — Guests, Registered, Administrators, Super
-Moderators, Moderators, Awaiting Activation, Banned — and you add your
-own beside them, like the Committee group above. Each member has one
-**primary** group and any number of **additional** ones, and both are
-edited on the member's screen under **Admin → Users**.
-
-Making somebody a moderator of one forum does not need a group at all:
-open the forum under **Admin → Forums** and appoint them there, ticking
-exactly the rights they should hold, optionally cascading to the forums
-beneath. Approving content, editing, deleting, restoring, locking,
-pinning, moving, merging and splitting are each a separate grant: ticking
-*Delete posts* does not give the undo, so tick *Restore posts* too if
-you mean both. A moderator sees exactly what they hold, forum by forum,
-under **`/modcp/forums`**. What each of the nine ticks decides is in
-[Forums and permissions § What an appointment grants](forums.md).
-
-Promotions that members *earn* — a "Veteran" group at 500 posts — can be
-automated under **Admin → Groups → Promotions**; the screen previews
-exactly who a rule would move before you enable it, and the button under
-that preview promotes exactly the members it lists. The preview reads
-the whole membership rather than a sample, which is not a cheap screen
-on a large board: it stops after 50,000 members and says on the page
-that it stopped, rather than keeping you waiting past that.
-
-An enabled rule also runs on its own, hourly, and pressing the button
-does not disturb that. The hourly task works through the membership
-10,000 members at a time and keeps its own place between runs, so on a
-board bigger than that a newly earned promotion arrives within a few
-runs rather than on the very next one.
-
-### When somebody steps back
-
-Accounts belong to people; roles are group memberships. That one
-sentence is most of a clean handover:
-
-- **Never share an account or a password.** Each organiser acts
-  from their own account, because the admin log records who did what,
-  and a shared login makes that record worthless.
-- **When somebody leaves**, take the *roles* off their *account*: remove
-  them from the Organisers group (and any staff group) on their member
-  screen, and remove any forum appointments on the forum screens. Their
-  account, their posts and their name stay theirs — they have simply
-  become an ordinary member again.
-- **When somebody joins**, add their own existing account to the groups
-  and appointments the role carries. There is nothing to hand over but
-  the group memberships.
-
-Keep more than one administrator. If the only administrator's account is
-ever lost, recovery is possible but needs the technical person — it is
-done from the server, not from the panel.
-
-## When to hand it to somebody technical
-
-Some jobs are about the machine the board runs on rather than the board,
-and they need the terminal. Hand these to whoever set the board up, with
-the page they need:
-
-| Job | Their page |
+# Members and registration
+
+## Configure registration
+
+Open `/admin/settings?group=registration`.
+
+| Setting | Effect |
 |---|---|
-| Backups — and proving a backup restores | [Backups](../operations/backups.md) — the schedule and the off-site bucket are settings you can turn on yourself; proving a restore still wants the terminal |
-| Upgrading to a new version | [Upgrading a board](../operations/upgrading.md) |
-| Setting up or changing how mail is sent | [Operations § Mail](../operations/mail.md) |
-| Installing a theme or a plugin | [The theme API](../extensions/themes.md), [The plugin API](../extensions/plugins.md) |
-| Recovering lost administrator access | [Operations § Account recovery](../operations/operator-cli.md#account-recovery) |
-
-Deciding *what* to install is yours, even when installing it is not. The
-public marketplace at [meith.dev/marketplace](https://www.meith.dev/marketplace)
-is a page per plugin and theme — what each does, its screenshots, and the
-exact command line whoever has the terminal will need. Your own board
-watches the same catalog for you: **Admin → Plugins** and **Admin →
-Themes** mark anything already installed **Update available** when a newer,
-compatible version is listed, so you learn what is worth chasing without
-browsing anything. Neither installs anything, so both cost nothing and
-need nobody technical yet.
-
-One of these is worth chasing rather than filing: **backups**. A board
-accumulates years of a community's writing, and the backup is the only
-way back from a bad day. Ask the person who runs the server two
-questions — is the database *and* the uploads folder being backed up
-somewhere off the machine, and has a restore ever been rehearsed. If
-either answer is no, point them at the page above.
+| **Allow new registrations** off | Hides registration; existing accounts can still sign in |
+| **Activation method** | None, email confirmation, administrator approval or both |
+
+Test [mail delivery](../operations/mail.md) before requiring confirmation. Configure questions and limits under [Spam controls](antispam.md).
+
+Announcement email requires separate opt-in during registration or at **Notifications → Preferences**. It starts unchecked.
+
+## Manage accounts
+
+Find the account under **Admin → Users** to change activation state, primary group or additional memberships.
+
+The user list supports up to 500 selected accounts for a shared-reason ban, additional-group assignment or prune review. Prune review rechecks that accounts have no content, ban or staff role and requires fresh authentication before closure.
+
+Reversible actions show **Undo** for ten minutes. Only the initiating administrator can use it, once. Pruning, merging and credential deletion require confirmation and cannot be undone this way.
+
+## Assign and remove staff
+
+Assign [groups](groups.md) for board-wide roles. For forum-specific moderation, appoint the member under **Admin → Forums** and select individual actions.
+
+When staff leave, remove their privileged memberships and forum appointments. Keep their personal account and posts. Use separate accounts for each administrator and retain more than one administrator for recovery.
+
+## Configure onboarding
+
+Members without posts see dismissible welcome, profile and composer prompts. Dismissals are stored per browser; posting ends the prompts. Set **Rules & FAQ** at `/admin/settings?group=legal` to add its composer and footer links. Empty legal pages remain unpublished.
+
+## Operator tasks
+
+Ask the operator to handle [backups](../operations/backups.md), [upgrades](../operations/upgrading.md), [mail](../operations/mail.md), [extension installation](../operations/installing.md) and [account recovery](../operations/operator-cli.md#account-recovery).
+
+Marketplace update notices identify available versions; they do not install packages.
diff --git a/docs/administration/membership-guide.md b/docs/administration/membership-guide.md
index be3fd8e7e..e76a67ddc 100644
--- a/docs/administration/membership-guide.md
+++ b/docs/administration/membership-guide.md
@@ -1,76 +1,52 @@
-# Manage paid memberships with Dues
+# Paid memberships
 
-Dues sells membership of an approved community group through Stripe. An operator installs the plugin, applies migrations and configures Stripe credentials and the webhook. Administrators then manage it under **Admin → Plugins → Dues**.
+Dues sells group membership through Stripe. Install the plugin, apply migrations and complete [Stripe setup](../operations/stripe-setup.md). Open **Admin → Plugins → Dues**.
 
-## Verify setup before selling
+## Before sales
 
-Open **Status** and check credentials, webhook receipt and items needing attention. Test the full purchase and membership flow on a separate staging board before configuring the production board with live credentials.
+Check **Status**, webhook delivery and attention items. Test checkout on a separate staging board. Test and live Stripe keys do not convert existing customers, prices or subscriptions.
 
-Create the group whose benefits the plan provides and mark it **may be granted by plugins**. Powerful staff groups cannot be granted this way. Set and verify the group's forum permissions before selling access.
+Create the benefit group, enable **may be granted by plugins** and verify its permissions. Staff groups cannot be granted. Configure currency and grace period; `DUES_CURRENCY` and `DUES_GRACE_DAYS` override saved defaults.
 
-## Complete payment setup
+## Plans
 
-Follow [Connect Dues to Stripe](../operations/stripe-setup.md) for keys, webhooks, receipts, the billing portal and a complete test checkout. Keep staging and production boards separate: changing keys does not convert stored Stripe customers, prices or subscriptions between accounts or modes.
+Enter a permanent key, name, description, group, currency and price. Prices use currency minor units: EUR 2500 is €25.00.
 
-Set the default currency and grace period in Dues settings. `DUES_CURRENCY` and `DUES_GRACE_DAYS` override the saved values when configured; individual plans have their own currencies.
-
-## Create a plan
-
-Open **Plans** and enter the key, name, description, group, currency and price. The key is permanent because records refer to it. Prices use the currency's minor units: for example, 2500 represents €25.00, not €2,500.
-
-| Plan | Billing | Giftable |
+| Type | Access | Giftable |
 |---|---|---|
-| Pass | One payment for a fixed duration | Yes |
+| Pass | Fixed duration, one payment | Yes |
 | Subscription | Monthly or yearly renewal | No |
-| Lifetime | One payment, no end date | Yes |
-
-For subscriptions, supply a compatible Stripe price or let the plugin create one from the form. Review the amount and interval before saving.
-
-Purchases snapshot their plan. Editing a price does not rewrite existing purchases or change the amount of an existing subscription. Archive a plan to stop new sales while preserving current memberships and history.
-
-## Explain the member experience
+| Lifetime | No end date, one payment | Yes |
 
-Members buy through the board's Membership page while signed in. **Your membership** shows their current access, renewal cancellation and the Stripe billing portal for payment details and receipts.
+For subscriptions, supply a compatible Stripe price or create one through the form. Purchases retain their plan snapshot; edits do not change existing subscription prices. Archive to stop new sales while preserving history.
 
-Passes extend an existing period. A lifetime holder cannot buy more time for the same group. A subscriber must cancel renewal before purchasing lifetime access. Staff keep their visible staff identity even when they buy another group membership.
+## Purchases and receipts
 
-## Help a member find a receipt
+Signed-in members buy through **Membership** and manage access through **Your membership**. Passes extend an existing period. Lifetime holders cannot buy more time for that group. Subscribers must cancel renewal before buying lifetime access.
 
-On **Your membership**, **Recent receipts** lists paid purchases with a Stripe payment reference among the buyer's 20 most recent orders. **View receipt** opens Stripe's hosted receipt. This includes one-time purchases and gifts the member bought; only the buyer can open it. Free purchases and unconfirmed payments have no receipt link.
-
-One-time payments have receipts without necessarily appearing in the billing portal's invoice history. Subscription renewal invoices remain in the portal. If Stripe has no receipt yet or cannot be reached, the member returns with an explanatory message. Dues retrieves the receipt URL when requested rather than storing it.
+**Recent receipts** includes eligible paid orders among the buyer's 20 most recent orders, including gifts. Only the buyer can open them. Free or unconfirmed purchases have no receipt link. Subscription renewal invoices are in the billing portal. Receipt links are retrieved from Stripe on request.
 
 ## Discounts and gifts
 
-Discount codes can be limited by plan, redemptions and UTC expiry. A subscription discount applies to the first payment; renewals use the normal amount. Open checkouts reserve capped redemptions until settled or released.
-
-A 100% discount on a pass or lifetime plan settles as a free membership without contacting Stripe. Other charges remain subject to the payment provider's currency minimums.
+Limit codes by plan, redemptions and UTC expiry. Subscription discounts apply only to the first payment. Open checkouts reserve capped redemptions until settled or released.
 
-A giftable pass or lifetime plan can be bought for another username. The recipient receives membership after payment confirmation; there is no separate claim step. Subscriptions cannot be gifted.
+A 100% discount on a pass or lifetime plan grants free membership without Stripe. Other amounts must meet provider minimums. Gifts grant the selected username membership after payment confirmation, without a claim step.
 
-## Handle daily administration
+## Administration
 
-| Action | Effect |
+| Action | Result |
 |---|---|
-| Extend | Adds 1–366 days without charging money |
-| Cancel renewal | Stops future renewal; retains access already paid for |
-| Revoke now | Removes access and stops subscription billing; does not itself refund money |
-| Clear the flag | Acknowledges an investigated attention item |
-
-Issue refunds in Stripe. Provider refund or chargeback events can revoke access; inspect the membership and webhook outcome rather than assuming a refund and a board revocation are the same operation.
-
-A failed renewal enters the configured grace period. Ask the member to update their payment method through the billing portal, then check subsequent events. The scheduler and webhook delivery must be working for membership state to catch up.
-
-## Reconcile and investigate
-
-Use **Memberships**, **Orders needing attention** and the ledger to trace a purchase from payment to group grant. The ledger records money movement; a manual access extension is not a charge. Repeated webhook delivery should not be treated as a separate purchase.
+| Extend | Add 1–366 days without charging |
+| Cancel renewal | Stop renewal; retain paid access |
+| Revoke now | Remove access and stop billing; no refund |
+| Clear the flag | Acknowledge an investigated issue |
 
-Ask the operator to investigate credentials, webhook signing, scheduler failures or incorrect public origins. Do not paste keys into support messages. Check the configured public URL before checkout and portal redirects are used.
+Issue refunds in Stripe and check resulting webhook and membership state. Refunds and chargebacks can revoke access. Failed renewal enters the grace period; the member should update payment details in the portal.
 
-## Understand access expiry
+Trace problems through **Memberships**, **Orders needing attention** and the ledger. Verify scheduler and webhook delivery. A redirect from checkout does not grant access; verified events or reconciliation do. Amount mismatches need investigation.
 
-Purchases normally make the purchased group primary and preserve the previous primary as a secondary membership. Members can choose another visible identity from their groups. Staff retain their staff identity. When the purchased grant expires, the board restores the prior primary group where appropriate.
+## Group expiry
 
-All plugin grants are bounded. Lifetime memberships depend on the plugin renewing the grant window; removing the plugin eventually ends that access. Checkout redirects do not grant access: verified payment events or reconciliation do. Amount mismatches require administrator investigation.
+Purchases normally make the paid group primary and retain the previous primary as an additional membership. Staff keep their visible identity. Expiry restores the prior primary where appropriate.
 
-The board records payment activity and group membership. Operators remain responsible for their pricing, tax, refund and cancellation policies.
+All plugin grants have bounded windows. Lifetime access requires continued renewal by the plugin; removing it eventually ends access. Configure pricing, tax, refund and cancellation policies separately.
diff --git a/docs/administration/moderation-guide.md b/docs/administration/moderation-guide.md
index 3b6e1dec2..35a7e9579 100644
--- a/docs/administration/moderation-guide.md
+++ b/docs/administration/moderation-guide.md
@@ -1,49 +1,30 @@
-# Moderate discussions
+# Moderation
 
-Moderators approve content, handle reports and manage conversations within their assigned forums. Open `/modcp` and check **My forums** (`/modcp/forums`) to see the actions you are allowed to perform.
+Open `/modcp`. Check `/modcp/forums` for your assigned forums and allowed actions.
 
-## Find the work
-
-| Page | Use it for |
+| Page | Task |
 |---|---|
-| `/moderation` | Threads and posts awaiting approval |
-| `/moderation/reports` | Reports from members |
-| `/modcp/forums` | Your appointments and allowed actions |
-| `/modcp/log` | Recorded moderation actions |
-| `/modcp/ip` | Address lookup, restricted to administrators and super-moderators |
-
-Thread pages also have **Moderator tools**. Forum and thread lists offer selection controls for bulk actions. The available controls reflect your permissions; access to the moderator panel does not itself grant every action.
-
-## Approve or reject held content
-
-Open the approval queue, read the content and select the intended items. Use **Approve selected** or **Reject selected**, then check the queue and the affected discussion.
-
-Content can be held because of new-member spam controls, a forum/group approval rule or a warning restriction. A moderate-posting warning applies even when the author would otherwise bypass approval as staff.
-
-## Handle a report
-
-Open a report, review the reported item and claim or handle it according to the available controls. Record the outcome and close the report when the work is complete. The reporter can be notified of the outcome.
-
-Reports can concern posts, threads, profiles or private messages. A private-message report makes that reported item available for staff review; it does not expose everybody's inbox.
-
-Community flagging may hide content after the configured threshold. Review the actual content before deciding to restore or remove it; a threshold is a signal for review, not proof of misconduct.
+| `/moderation` | Approve or reject held threads and posts |
+| `/moderation/reports` | Handle member reports |
+| `/modcp/log` | Review moderation actions |
+| `/modcp/ip` | Address lookup; administrators and super-moderators only |
 
-## Manage a discussion
+## Review content and reports
 
-Choose the smallest action that resolves the problem: edit, lock, pin, move, split, merge, delete or restore. Permissions are separate for each operation and can differ between source and destination forums.
+Read queued items, select them and choose **Approve selected** or **Reject selected**. New-member controls, forum rules and warnings can hold content. A moderate-posting warning also applies to staff.
 
-Before a move or merge, check the destination's audience. Moving a thread can change who may read it. A merge selects a surviving thread; a split creates a separate discussion from selected posts. Read the form's target and confirmation before submitting.
+Open a report, review the item, record the outcome and close it. Private-message reports expose the reported item, not general inbox access. Review community-flagged content before restoring or removing it.
 
-Deletion and restoration are different grants. Do not assume that permission to remove a post also permits restoring it.
+## Manage threads
 
-## Use warnings and bans
+Use **Moderator tools** or list selection controls to edit, lock, pin, move, split, merge, delete or restore content. Each action requires its own permission. Delete permission does not include restore permission.
 
-Warnings add points and can expire or be revoked. Configured warning levels may restrict posting, hold content for approval or ban the member. Read the selected warning's effect before applying it and explain the reason clearly.
+Before moving or merging, check the destination audience and required permissions. A merge retains the selected target thread and deletes the source thread’s poll, votes, ratings, subscriptions and read markers. Back up before a merge if those must be recoverable. A split creates a new thread from selected posts.
 
-Warning points are not percentages. Revoking points does not automatically undo every ban already imposed by a level; check the member's current restrictions. Ban expiry depends on scheduled work.
+## Warnings and bans
 
-Board-wide member management and ban settings may require an administrator. Escalate when the necessary action is outside your appointment.
+Warnings add points and may expire or be revoked. Warning levels can restrict posting, require approval or impose a ban. Check the effect before applying a warning.
 
-## Review the result
+Points are not percentages. Revoking them does not necessarily undo an imposed ban. Ban expiry needs scheduled work.
 
-Check the affected discussion and the moderator log. Confirm that content has the intended visibility and that another moderator can understand what happened. For an unexpected access denial, ask an administrator to inspect [forum permissions and appointments](forums.md).
+After an action, check content visibility, member restrictions and the log. Ask an administrator to adjust [appointments](forums.md) when required actions are unavailable.
diff --git a/docs/administration/organiser-guide.md b/docs/administration/organiser-guide.md
index d3e0715cd..0a4575f84 100644
--- a/docs/administration/organiser-guide.md
+++ b/docs/administration/organiser-guide.md
@@ -1,38 +1,23 @@
-# Community administration
+# Administration
 
-Use the admin panel to manage the people, content and settings of an installed board. Sign in to your community and open `/admin`; the panel asks for your password again because it has a separate session.
-
-For a new board, complete [Set up your community](first-steps.md) first. You do not need to edit source code for the tasks on this page.
-
-## Find a task
+Sign in and open `/admin`. Enter your password again to start the separate admin session.
 
 | Task | Guide |
 |---|---|
-| Create forums or make a staff area private | [Forums and permissions](forums.md) |
-| Give groups permissions or set promotion rules | [Groups and promotions](groups.md) |
-| Open registration or change a member's role | [Manage members](manage-members.md) |
-| Change the name, logo, colors or theme | [Board appearance](appearance.md) |
-| Publish announcements or change navigation | [Community communications](community-communications.md) |
-| Review posts, reports, warnings or bans | [Moderation](moderation-guide.md) |
-| Stop spam or diagnose blocked registration | [Spam controls](antispam.md) |
-| Set search language and limits | [Search settings](search.md) |
-| Configure ratings and thanks | [Reputation](reputation.md) |
-| Run events | [Calendar](calendar.md) |
-| Recognize members | [Awards](awards-guide.md) |
-| Offer paid membership | [Dues](membership-guide.md) |
-
-Calendar, Awards and Dues require their respective plugins. The operator installs plugin packages; the admin panel controls the installed features.
-
-## Check permissions as a member
-
-Administrators can bypass many forum restrictions. After changing groups or forum permissions, verify the result with an ordinary member account and while signed out. A forum that looks correct to an administrator may still expose content to the wrong audience.
-
-Appoint moderators through each forum's administration page. Give only the required actions and ask the moderator to check **My forums** at `/modcp/forums`.
-
-## Publish community rules
-
-Under **Board settings → Legal**, maintain the Rules & FAQ, terms and privacy pages. Non-empty pages appear in the footer. Check the published pages while signed out, and make sure the registration and contact instructions match how your community operates.
-
-## Work with the operator
-
-Ask the operator for deployment changes, email delivery problems, missing extensions, storage, backups and upgrades. Use [Server operations](../operations/operating.md) for the technical handover. If you manage both roles, keep deployment changes separate from ordinary panel settings so you know what requires a redeploy.
+| Configure a new board | [Setup checklist](first-steps.md) |
+| Create forums and control access | [Forums](forums.md) |
+| Set permissions and promotions | [Groups](groups.md) |
+| Registration and member roles | [Members](manage-members.md) |
+| Name, logo, colours and themes | [Appearance](appearance.md) |
+| Announcements, navigation and email | [Communications](community-communications.md) |
+| Reports, warnings and bans | [Moderation](moderation-guide.md) |
+| Registration and posting limits | [Spam controls](antispam.md) |
+| Search language and limits | [Search](search.md) |
+| Ratings and thanks | [Reputation](reputation.md) |
+| Events | [Calendar](calendar.md) |
+| Awards and achievements | [Awards](awards-guide.md) |
+| Paid memberships | [Dues](membership-guide.md) |
+
+Calendar, Awards and Dues require installed plugins. Package installation, deployment, storage and recovery require an operator; see [Operations](../operations/operating.md).
+
+After permission changes, test as a guest and an ordinary member. Administrator access can bypass restrictions.
diff --git a/docs/administration/reputation.md b/docs/administration/reputation.md
index 55fe2ea8c..f2817ef87 100644
--- a/docs/administration/reputation.md
+++ b/docs/administration/reputation.md
@@ -1,37 +1,25 @@
-# Configure reputation and thanks
+# Reputation and thanks
 
-Configure reputation under **Board settings → Reputation** (`/admin/settings?group=reputation`). Group permissions control who may rate and their daily allowance.
-
-## Choose the board settings
+Open `/admin/settings?group=reputation`.
 
 | Setting | Effect |
 |---|---|
-| Reputation enabled | Shows rating controls and totals; turning it off preserves existing ratings |
-| Allow negative ratings | Allows negative as well as positive ratings; off by default |
-| Require a comment | Requires an explanation and removes one-click Thanks |
-| Posts required before rating | Minimum post count; default 5, or 0 to remove the requirement |
+| Reputation enabled | Shows ratings and totals; disabling preserves existing ratings |
+| Allow negative ratings | Enables negative votes; off by default |
+| Require a comment | Removes one-click Thanks |
+| Posts required before rating | Default 5; 0 removes the requirement |
 
-A rating is −1, 0 or +1, without a group multiplier. Comments may contain up to 500 characters. Ratings can be associated with a post or a member profile.
+Ratings are −1, 0 or +1 without group multipliers. Comments accept up to 500 characters. Ratings can target a post or profile.
 
-## Understand the controls members see
+## Member controls
 
-| Negative ratings | Comment required | Post controls |
+| Negative ratings | Comment required | Controls |
 |---|---|---|
 | Off | No | Thanks |
 | Off | Yes | Rating form |
 | On | No | Thanks and rating form |
 | On | Yes | Rating form |
 
-Choose the combination that fits the community, save it, and check a post using an ordinary member account.
-
-## Set permissions and limits
-
-The member needs **Can give reputation**, enough posts and remaining daily allowance. Members cannot rate themselves. A group's numeric allowance combines with other groups using the most generous value; zero is unlimited. The day resets at midnight UTC.
-
-A member can withdraw a rating they gave. Totals are recomputed from current ratings when they change, including account merges; there is no operator recount step for ordinary rating changes.
-
-## Check related features
-
-Promotion rules and optional achievement plugins can use reputation as an eligibility criterion. Consider those rules before changing reputation policy.
+The member needs **Can give reputation**, sufficient posts and a remaining daily allowance. Self-ratings are blocked. [Group allowances](groups.md) combine using the highest value; zero is unlimited. The day resets at midnight UTC.
 
-For group settings, see [Groups and promotions](groups.md). For imported ratings, see [MyBB account differences](../operations/mybb-members.md).
+Members can withdraw their own ratings. Totals update automatically, including after account merges. Check promotion and achievement rules before changing reputation policy.
diff --git a/docs/administration/search.md b/docs/administration/search.md
index c50dbb132..56a957854 100644
--- a/docs/administration/search.md
+++ b/docs/administration/search.md
@@ -1,27 +1,19 @@
-# Configure search
+# Search settings
 
-Open **Board settings → Search** at `/admin/settings?group=search`. These settings control the board's search feature; members looking for discussions should start with the [Member guide](../members/member-guide.md).
+Open `/admin/settings?group=search`.
 
-## Choose the search language
+## Language
 
-Select the PostgreSQL text-search language matching the board's main content. It controls word stemming for both indexing and queries. English is the default. **No stemming (exact words)** is useful for mixed-language content, but does not match word forms through a shared stem.
+Select the PostgreSQL search language for the board's content. English is the default. **No stemming (exact words)** suits mixed-language content but does not match related word forms.
 
-Changing the language schedules a background reindex. Watch its pending count under **Admin → System**. Existing content remains available, but matches can differ until every post has been reindexed.
+A language change queues reindexing. Monitor the pending count under **Admin → System**; matches may vary until it finishes. If progress stops, check [scheduled tasks](../operations/scheduled-tasks.md).
 
-If the count does not progress, ask the operator to check [Scheduled tasks](../operations/scheduled-tasks.md).
+## Availability and limits
 
-## Enable or disable search
+Disabling search removes its navigation link and disables the page and API endpoint. The index remains maintained; re-enabling does not require a rebuild.
 
-Turning search off removes the navigation link and disables the search page and API search endpoint. It preserves the index and continues maintaining it. Turning search back on does not require rebuilding the index simply because it was disabled.
+Set the minimum word length and flood interval. At least one query word must meet the minimum. The hourly cap is under [Antispam](antispam.md).
 
-## Set query limits
+## Verify
 
-Set the minimum word length required for a query. At least one query word must meet that minimum; other short words can still be part of the query.
-
-The flood interval and hourly cap are different controls. The flood interval is under Search; the hourly cap is under [Spam controls](antispam.md). Review both before diagnosing a member who is asked to wait.
-
-## Verify results
-
-Search for known content using a normal member account, a guest and a member of a private group. Results respect content visibility and forum permissions. Filters narrow the permitted results rather than granting access to another forum.
-
-Ranking and result windows have limits; the [search behavior reference](../operations/mybb-discovery.md#search) explains the detailed behavior relevant when migrating from MyBB. For a manual rebuild, use [Operator commands](../operations/operator-cli.md).
+Search for known public and private content as a guest and representative members. Results must match their forum permissions. See [Search behaviour](../operations/mybb-discovery.md#search) for ranking and result limits, or [Operator commands](../operations/operator-cli.md) for rebuilding.
diff --git a/docs/contributing/architecture.md b/docs/contributing/architecture.md
index 712c99810..c7b26ece6 100644
--- a/docs/contributing/architecture.md
+++ b/docs/contributing/architecture.md
@@ -1,60 +1,36 @@
 # Architecture
 
-Meith separates business rules, infrastructure and presentation. Use this map to choose where a contribution belongs; [Development](development.md) covers setup and validation.
+## Request flow
 
-## Applications and processes
+1. The app parses and validates input.
+2. It resolves the actor and checks authorisation.
+3. A domain service applies the operation through repository interfaces.
+4. Infrastructure persists the result and transactional events.
+5. The app builds a public model, invalidates affected caches and returns or redirects.
 
-| Application | Responsibility |
-|---|---|
-| `apps/community` | Forum pages, Server Actions, route handlers and request composition |
-| `apps/worker` | Scheduled and queued work |
-| `apps/cli` | Operator migrations, backups, imports and maintenance |
-| `apps/web` | Marketing and documentation site |
-
-Applications compose domain operations with concrete repositories and drivers. Packages do not import application internals.
+Domain packages do not import Next.js, React, database drivers or app modules. `packages/runtime` composes services and concrete adapters. `packages/core` holds shared contracts; the theme and plugin kits expose extension contracts.
 
-## Package boundaries
+## Application boundaries
 
 | Layer | Responsibility |
 |---|---|
-| `packages/core` | Shared values, errors, permissions, environment validation and infrastructure ports |
-| Domain packages | Business behavior expressed through explicit inputs and interfaces |
-| `packages/db` | PostgreSQL schemas, queries and repository implementations |
-| `packages/drivers` | Queue, cache, file, mail and image implementations |
-| `packages/runtime` | Composition shared by web, worker and CLI |
-| `packages/ui` | Reusable presentation components |
-| Theme/plugin kits | Published extension contracts |
-
-Domain packages do not import Next.js, React, database clients, drivers or application internals. Dependency Cruiser and repository guards enforce these boundaries.
-
-## Follow a request
-
-1. A page, action or route receives framework input.
-2. Application code validates it and resolves the member and permission context.
-3. A domain operation receives explicit values and repository interfaces.
-4. An infrastructure adapter performs the durable work.
-5. The application refreshes the relevant cached state and returns a safe result.
-
-Read paths resolve authorized data before constructing a theme view model. Themes render those models; they do not fetch data or decide permissions. API routes use the same authorization concepts as pages.
-
-## Understand data and background work
-
-Fixture mode uses deterministic in-memory sample data for browsing and tests. PostgreSQL provides durable board state. Fixture mode does not simulate successful writes and cannot run the durable worker.
-
-The worker and HTTP tick use the shared runtime task bundle. Database claims coordinate concurrent work. Tasks process bounded batches and resume from persisted state where needed; a healthy web process alone does not prove the scheduler is progressing.
-
-For operations, use [Scheduled tasks](../operations/scheduled-tasks.md), [Database operations](../operations/database-operations.md) and [Scaling](../operations/scaling.md).
+| Routes and server actions | Request parsing, authentication, response handling |
+| Domain services | Business rules and permission-aware operations |
+| Repositories/drivers | Persistence and external services |
+| View models | Explicit serialisable fields for rendering |
+| Themes | Presentation of prepared models and regions |
+| Plugins | Declared hooks, routes, pages and services |
 
-## Boards and extensions
+Never expose database rows to components or API responses. Never cache actor-dependent results as global data.
 
-A board owns its static theme/plugin configuration and exact package pins. The stock image is built from `boards/stock`, using the external-board workspace shape. `apps/community` remains the in-repository development target.
+## Board configuration
 
-The `@board/config` and `@board/plugins` aliases let the web app and CLI read the selected board without hard-coded imports into another application's directory. Read [Board workspaces](board-workspaces.md) before changing packaging, materialization or these aliases.
+The board consumes its configuration through `@board/*` aliases. `apps/community` is the development board; `boards/stock` supplies the official image. External boards provide the same configuration files beside installed packages. See [Board workspaces](board-workspaces.md).
 
-Plugins use the host APIs and their own database namespace. Themes implement slots and inherit presentation. [Build extensions](../extensions/extensions.md) links to their contracts.
+Fixture mode supplies read-only sample data. PostgreSQL mode supplies durable storage, queue claims and scheduled tasks. Web, worker and CLI must use matching configuration and stores.
 
-## Validate a boundary change
+## Background work
 
-Extend an explicit port and implement it in infrastructure when business behavior needs a new capability. Keep framework wiring in application/runtime composition and document the invariant beside its contributor guide.
+Write content changes and outbox events in the same transaction. Delivery is at least once; handlers must be idempotent. Queue claims and task leases coordinate workers. Every denormalized counter needs a bounded, resumable recount.
 
-Run `pnpm depcruise`, relevant tests and the full `pnpm verify` gate before a PR. Regenerate API, theme and plugin references when changing their public source contracts.
+See [Rendering and data](rendering-and-data.md) for caching, models and event-handler rules, and [Forms and actions](forms-and-actions.md) for mutation handling.
diff --git a/docs/contributing/board-workspaces.md b/docs/contributing/board-workspaces.md
index ccff8e574..828636b8c 100644
--- a/docs/contributing/board-workspaces.md
+++ b/docs/contributing/board-workspaces.md
@@ -1,274 +1,44 @@
-# Board workspaces and build materialization
-
-Understand the monorepo, external board workspaces and generated board registry. This reference is for contributors changing packaging or the boundary between a board and the engine.
+# Board workspaces
 
 ## The workspace
 
-A pnpm workspace: applications in `apps/`, everything else in `packages/`,
-`themes/` and `plugins/`.
-
-| Directory | Package | What it is |
-|---|---|---|
-| `apps/community` | `@meith/web` | The board itself, and the in-repo dev target. `pnpm dev`, on port 3000. |
-| `apps/web` | `@meith/site` | meith.dev — the landing page and these documents. `pnpm site:dev`, on port 3100. |
-| `apps/worker` | `@meith/worker` | The background tick, as a long-running process. |
-| `apps/cli` | `@meith/cli` | The operator CLI. `pnpm meith …`. |
-| `boards/stock` | `@meith/board-stock` | A second, create-meith-shaped board — the workspace `docker/Dockerfile` builds the official image from. See [Architecture](architecture.md). |
-| `packages/*` | `@meith/*` | The domain: accounts, forums, posts, authorization, search, drivers, and the rest. |
-| `themes/*` | `@meith/theme-*` | The default theme, four bundled alternates (midnight, phasebook, raidframe, clubhouse) and `meith`, the editorial theme for meith.dev's own forum, which publishes to npm and is registered only behind `SHOWCASE_THEMES`, not in the stock theme set. |
-| `plugins/*` | `@meith/plugin-*` | Dues (paid membership through Stripe), calendar (shared events linked to threads) and the reference plugin. Outbound webhooks are a core feature — see [Webhooks](../integrations/webhooks.md). |
-| `examples/*` | — | Reference code to copy, not installed: `hello-plugin` and `iris-theme`. See [`examples/README.md`](https://github.com/meith-dev/meith/tree/main/examples). |
-
-> [!TIP]
-> The two directory names are easy to swap: `apps/community` is the board
-> (package `@meith/web`), while `apps/web` is the marketing site (package
-> `@meith/site`).
-
-Every `@meith/*` import resolves through tsconfig path aliases straight to
-`src/index.ts`. There is no build step between packages, which is why a
-typecheck is fast and why `pnpm workspace:check` exists — see
-[the checks that fail on purpose](repository-checks.md#the-checks-that-fail-on-purpose).
-
-Outside the workspace: `docker/` is the whole deployment interface — the
-compose files, the Dockerfiles, the entrypoint and the healthcheck. The
-compose files read their `.env` from beside them, which is why the deploy
-guides say `cd meith/docker`. The repository root is a registry, not a
-landing zone: every entry in it is listed in `scripts/root-check.mjs` with
-the reason it must live there, and `pnpm root:check` fails on a new root
-file until it is either moved into a folder or registered with a reason.
+| Path | Package/use |
+|---|---|
+| `apps/community` | `@meith/web`; development board and published framework |
+| `apps/web` | `@meith/site`; project website |
+| `boards/stock` | Board built into the official image |
+| `themes` | Default, Midnight, Phasebook, Raidframe, Clubhouse and Meith |
+| `plugins` | First-party plugins, including Dues, Calendar, Awards and the reference example |
+| `examples` | Source for generated plugin/theme tutorials |
 
-How the packages relate — the layers, what may import what, and why — is
-[Architecture](architecture.md).
+A board owns `meith.config.ts`, its plugin manifest and generated registry. Framework code accesses those through `@board/*`, not relative imports into a particular board.
 
 ## Consuming the board from a workspace
 
-`packages/create-meith` scaffolds a board whose `package.json` depends on
-`@meith/web` and `@meith/cli` and whose scripts call `forum-web` and
-`meith` — a board outside this monorepo, in a directory that holds only its
-own files: `meith.config.ts`, `board.plugins.json`, `meith.plugins.ts` and
-`package.json`. This section is how that actually runs, for anyone changing
-`apps/community`, `apps/cli` or the scaffold.
-
-**A Next.js app is not consumable as a bare dependency.** `next
-dev|build|start` need to run with the app's own directory as the project
-root, and the
-[board-config seam](architecture.md) —
-`@board/config` / `@board/plugins` — is a pair of tsconfig path aliases
-that, inside this monorepo, point at `apps/community`'s own files. Neither
-survives `npm install`ing `@meith/web` into somebody else's workspace. So
-`forum-web` (`apps/community/bin/forum-web.mjs`, `@meith/web`'s bin) and
-`meith` (`apps/cli/bin/meith.mjs`, `@meith/cli`'s bin) **materialize** the
-app on every invocation:
-
-1. Copy the package's own sources into `.meith/app/` (`.meith/cli/` for the
-   CLI) inside the invoking workspace — gitignored, rebuilt every run,
-   never a merge target. `public/` travels with them, so `/sw.js` and the
-   placeholder assets are served from the materialized app too.
-2. Write a fresh `tsconfig.json` there whose `paths` point `@board/config`
-   and `@board/plugins` at *that workspace's own* `meith.config.ts` /
-   `meith.plugins.ts`. A tsconfig path alias may name a target outside the
-   package — a Node subpath import may not — which is why the seam is an
-   alias in the first place.
-3. Run `next dev|build|start` (`forum-web`) or `tsx` against the
-   materialized entry point (`meith`) with that directory as the working
-   root.
-
-`.meith/app/` sits exactly two directories below the workspace root on
-purpose: `next.config.mjs` computes its own workspace root as two
-directories up from itself (for `.env` loading, `outputFileTracingRoot`
-and `turbopack.root`), and materializing at that depth keeps the
-computation correct whether the file runs in place here or copied into
-somebody else's workspace.
-
-**`forum-web build` stages `.next/static` and `public/` into the
-standalone tree** after `next build` finishes. `next.config.mjs` sets
-`output: 'standalone'` everywhere the board has to serve itself — that is
-everywhere except Vercel, which packages the build into its own functions —
-and Next's standalone output deliberately excludes both directories, so
-they are copied in beside the traced `server.js`. `forum-web start` only
-execs that already-staged tree. The official image (`docker/Dockerfile`)
-copies `.next/static` and `public/` into its slimmer runtime stage itself,
-straight from the build stage.
-
-**`outputFileTracingIncludes` carries one workaround.** Next's output
-tracer follows only the CJS half of `@swc/helpers` and misses the `esm/`
-variant its own require-hook resolves at runtime, so without the glob the
-standalone tree ships half a package and self-hosted boards fail at request
-time. The glob names the pnpm store path — version and all — because
-`next.config.mjs` is read from places where `@swc/helpers` does not resolve
-at all, so there is nothing to derive the version from;
-`scripts/workspace-check.mjs` fails any tree where the literal disagrees
-with an `@swc/helpers` pin, so a bump cannot leave the glob matching
-nothing. The unversioned glob beside it covers hoisted installs. The
-include is applied by Turbopack itself — `collectBuildTraces`, the only
-place `next/dist` reads the option, is skipped under Turbopack, so do not
-conclude from that code that the glob is dead; measured on this app's own
-builds it lands `esm/` entries in every route's `.nft.json`.
-
-**This assumes a hoisted `node_modules`** — npm, yarn classic, or pnpm with
-`node-linker=hoisted` (`create-meith`'s scaffold uses npm). The
-materialized app imports every `@meith/*` package by bare specifier,
-resolved by walking up from `.meith/app/` — which only reaches a dependency
-hoisted to the workspace root. That is also why
-`apps/community/next.config.mjs`'s `transpilePackages` names every
-`@meith/*` package the app's dependency graph reaches: in here the path
-aliases resolve them to source, but in a consuming workspace they arrive as
-`.ts` files inside `node_modules` and need the same source-compilation
-treatment or the build fails. (`@meith/web` names itself for the same
-reason — an external board's `meith.config.ts` imports the
-`@meith/web/config` subpath.) That list is a hand-written mirror of a
-dependency graph, so `scripts/workspace-check.mjs` holds the two in step:
-every reachable `@meith/*` package must appear in `transpilePackages` or
-`serverExternalPackages`, and a name nothing reaches any more fails too.
-
-**Fixture mode covers `forum-web dev`, `forum-web build` and `forum-web start`.**
-Running the built fixture server needs `AUTH_SECRET`; it serves the same
-read-only sample content without a database. PostgreSQL boards require a
-durable queue and scheduler secrets because queued work must survive restarts.
-
-**The CLI materializes for its own reason:** `apps/cli/src/index.ts`
-imports `@board/plugins` dynamically, so the `meith` bin must resolve the
-seam at run time against whichever workspace invoked it — unlike the
-image's bundled CLI, which bakes its board in at build time. **The worker
-is not part of this**: `apps/worker` imports no board config, and the
-scaffold does not depend on it today.
-
-Two smoke scripts prove all of this against real packed tarballs, since
-nothing else in `pnpm verify` builds a board from outside this repository:
-
-- **`pnpm board:workspace:smoke`** (`scripts/board-workspace-smoke.mts`,
-  CI's `board-workspace` job) packs `@meith/web`'s dependency closure with
-  `pnpm pack`, scaffolds a board with `create-meith`, installs it with
-  overrides pointing at the tarballs, runs `forum-web build`, applies
-  migrations, boots the standalone server against a disposable Postgres,
-  and fetches `/`, a real `/_next/static/*` asset and `/sw.js`. Because
-  answering 200 is not the same as working, it also fails if the rendered
-  page contains raw message keys (a board whose config forgot
-  `messages: defaultMessages`) or if the stylesheet lacks rules for classes
-  only `@meith/ui` and the default theme produce (a board Tailwind never
-  scanned). The whole run happens twice — once at `.meith/app`, the
-  self-host shape, and once with `--at-root`, the Vercel shape — because
-  every board bug found so far shipped through whichever depth the smoke
-  did not cover.
-- **`pnpm extension:workspace:smoke`** (`scripts/extension-workspace-smoke.mts`,
-  CI's `extension-workspace` job) is the same proof for extension authors:
-  it scaffolds a plugin and a theme with `create-meith --plugin`/`--theme`,
-  packs them the way `npm publish` would, tests and typechecks both against
-  the packed kits rather than workspace aliases, then installs both into a
-  scaffolded board and runs `forum-web build`. A kit whose `files`
-  allowlist rotted, or a scaffold that only compiles against
-  `workspace:*`, fails here before an author finds out.
-
-### Building where Vercel looks
-
-`forum-web build --at-root` materializes into the workspace root itself
-instead of `.meith/app`, so `next build` writes to `<root>/.next`. That is
-the one shape Vercel's Next.js preset can read, and the only reason the
-mode exists. Three constraints, none of them ours to change, close off
-every other arrangement: the builder reads `.next` under the project root
-and that location is not configurable for Next.js; the Root Directory
-cannot be `.meith/app`, because Vercel resolves it against the checkout
-before anything has materialized; and `.next` cannot be moved after the
-build, because `required-server-files.json` records the paths it was built
-at and the breakage would arrive at request time.
-
-So the app moves, not the output. Every path `forum-web` writes is computed
-from the materialization directory, so the seam works identically at either
-depth; three things that used to rely on the depth are told the answer
-instead:
+The `forum-web` and `meith` bins materialize framework sources into `.meith/app` and `.meith/cli`, configure `@board/*` aliases, then invoke Next.js or tsx. Build stages static/public files into the standalone output; start runs that output.
 
-- **`FORUM_WORKSPACE_ROOT` is always passed on** by `forum-web`, defaulting
-  to the invoking workspace's own root — at depth zero it is what stops the
-  copied `next.config.mjs` resolving a workspace root two directories
-  *above* the board.
-- **The `outputFileTracingIncludes` glob prefix** becomes `.` rather than
-  the empty string, which would read as an absolute path and silently match
-  nothing.
-- **`globals.css`'s Tailwind `@source` roots are rebased on every
-  materialization**, keeping each root only if it exists. Inside this
-  repository all four (`themes/`, `plugins/`, `examples/`,
-  `packages/ui/src`) exist; beside a scaffolded board none do — that code
-  lives under `node_modules/@meith`, which is substituted instead. The
-  rebase matters because Tailwind treats a scan root that resolves to
-  nothing as no error at all: it builds green and emits no utilities, which
-  is how scaffolded boards once shipped unstyled.
+Generated standalone boards use npm's hoisted dependency layout. The Meith pnpm workspace uses its configured aliases. Keep reachable framework packages in the appropriate transpilation/externalisation configuration.
 
-**Depth zero puts framework-owned names beside the board's own files**, so
-ownership is decided per file rather than per directory. `--at-root` treats
-a file as its own when the record in `.meith/materialized.json` says it
-wrote it before, or when what is on disk is byte-for-byte what it would
-write anyway (which is what makes a fresh checkout deployable — a clone has
-no record). Everything else is the board's: never removed, never
-overwritten, and a collision stops the build naming every file involved.
-`tsconfig.json` and `next-env.d.ts` are generated rather than copied, so
-they are replaced without asking. Files the record names that this run will
-not write — the framework stopped shipping them — are removed, and only
-those. One narrow hole is open deliberately: a board file byte-identical to
-a shipped one is indistinguishable from a materialized copy, and closing
-that would mean giving up the fresh-checkout case.
+The default source layout assumes two directory levels. `--at-root` and `FORUM_WORKSPACE_ROOT` support the alternate root layout. SWC helper tracing supports the checked isolated and hoisted layouts; update its version checks when changing the dependency.
 
-**`app/` and `src/` are the framework's alone.** A route dropped into
-`app/` is preserved per the rules above but gitignored by the scaffold, so
-it works locally and silently vanishes from a deploy built out of the
-checkout — `forum-web` warns at materialization time, naming every foreign
-file it finds there. A board extends the forum through plugins and themes.
-A board **can** own files under `public/` (`ads.txt`, `.well-known/`,
-domain verification): the Vercel target's `.gitignore` lists the
-framework's `public/` files by name rather than ignoring the directory, so
-a board's own additions are tracked normally.
-`scripts/workspace-check.mjs` fails if that list and `forum-web`'s own
-entries ever disagree.
+## Materialized files
 
-**Vercel detects Next.js by reading the root `package.json`**, not by
-resolving the package, so the scaffold declares `next` — and only `next`,
-at the version `@meith/web` builds with; `react` and `react-dom` still
-arrive by hoisting. `scripts/workspace-check.mjs` holds every manifest that
-pins `next`, `react` or `react-dom` (and `create-meith`'s `NEXT_VERSION`)
-to `@meith/web`'s pins, so upgrading Next in one place and not the others
-fails the check rather than shipping a scaffold that installs one version
-and builds with another.
+The at-root manifest `.meith/materialized.json` records owned files. Existing files are replaced only when ownership or exact generated bytes establish that they belong to the framework. Conflicting board files stop materialization.
 
-When updating Next.js, also align `packages/drivers/package.json`'s exact
-peer dependency and `create-meith`'s `NEXT_VERSION`, then run
-`pnpm board-installer:gen` and `pnpm install`. Leave the committed deploy
-templates unchanged until release; `pnpm release:bump` regenerates them.
-The release workflow checks template freshness before publishing npm packages;
-normal CI tests the generator without requiring the released trees to change.
-Conflicting Next.js installations can fail packed-board prerendering with
-`Expected workStore to be initialized` even when the repository build passes.
+Generated TypeScript configuration and Next environment files are overwritten. Stale owned files are removed; foreign files are retained and reported. Public assets are tracked per file so board additions survive.
 
-**The Vercel target turns the mode on; nothing else does.** `scaffold()`'s
-`target: 'vercel'` tree carries the flag in `vercel.json`'s `buildCommand`
-(`meith migrate && forum-web build --at-root`) and in its own scripts, so a
-board built locally and on the platform materialize to the same place. The
-self-host target is untouched. At release, `pnpm templates:gen:check` ties the
-generated `templates/self-host/` and `templates/vercel/` trees back to
-`scaffold()`.
+Keep custom application code outside generated framework directories. Never edit `.meith` as the source of a customisation.
 
-## The board plugin manifests
+## Plugin manifests
 
-This repository carries two boards, each with its own `board.plugins.json`
-and generated `meith.plugins.ts`: `apps/community`, the in-repo dev
-target, and `boards/stock`, the workspace the official image is built
-from. `tests/boards-stock.test.ts` requires the two manifests to stay
-identical, so a plugin installed into one and not the other fails
-`pnpm verify`. Installing a plugin in this checkout means adding the
-dependency to both boards — see
-[the plugin API](../extensions/plugins.md).
+`apps/community` and `boards/stock` use matching manifests, registered in `scripts/boards.json`. Add dependencies to both where required, then run `pnpm board:gen`. The generator owns `meith.plugins.ts` and validates the manifest shape.
 
-`scripts/boards.json` is the one place the list of boards is written down;
-both the generator (`pnpm board:gen`) and the CLI's
-`plugin:add`/`plugin:remove` read it. Those commands only know how to
-rewrite a manifest shaped `{ "plugins": [...] }` — one carrying any other
-top-level field is refused rather than silently rewritten without it.
-(`MEITH_BOARD_PLUGINS_ROOT` redirects the whole read/write root; only the
-tests set it, so a real add-and-remove round trip never edits a fixture
-tree's boards by accident — or vice versa.)
+`MEITH_BOARD_PLUGINS_ROOT` supports generator tests. `DUES_TEST_BOARD=1` adds test plugin definitions and local overrides through `meith.test.plugins`; it is not production configuration.
 
-## Board configuration and test plugins
+## Change the framework
 
-Application and CLI code import the selected board through `@board/config` and `@board/plugins`. Do not reach into `apps/community` with a relative import of `meith.config.ts`, `meith.plugins.ts` or `meith.test.plugins.ts`: external board workspaces provide their own files through those aliases. The configuration files may import each other as part of defining that board.
+Keep Next.js versions aligned across framework peers, scaffold and driver manifests. Regenerate the board installer and update the pnpm lockfile. Deploy template snapshots change during releases.
 
-`apps/community/meith.test.plugins.ts` supplies Awards, Calendar and test-configured Dues only when `DUES_TEST_BOARD=1`. Its Dues definition seeds test plans and permits the loopback payment service used by browser tests. These are test-board defaults, not production payment configuration. The generated registry combines the test plugins with manifest-installed plugins; keep this behavior when changing the generator.
+Validate packaging changes with `pnpm board:workspace:smoke` and extension changes with `pnpm extension:workspace:smoke`. These pack local dependencies and test generated consumers, including root materialization, styles and public assets.
 
-The `no-relative-board-config-import` guard enforces the import boundary. The stock and development manifests remain synchronized, while a scaffolded external board owns its own manifest.
+Fixture builds still require the configured auth secret. Writable boards require PostgreSQL and a scheduler. Scaffolded workers call the board's HTTP task endpoint; the monorepo worker is a separate process.
diff --git a/docs/contributing/brand.md b/docs/contributing/brand.md
index 647fe00f3..b7989f11a 100644
--- a/docs/contributing/brand.md
+++ b/docs/contributing/brand.md
@@ -1,32 +1,23 @@
 # Brand guidelines
 
-How Meith looks, sounds and spends its one colour, for anyone making a page, a post, a slide or a pull request that carries the name. The stylesheet is the brand: when this page and `apps/web/src/styles` disagree, the repository wins and this page is corrected.
-
-## The idea
-
-Meith takes its name from meitheal, the Irish tradition of neighbours coming together for shared work because the work benefits the group. The brand carries that idea quietly. It is never a craft or landscape identity: Meith is server software somebody is deciding whether to run, and it should look like it. Four ideas everything is checked against:
-
-- **Owned.** Your domain, your server, your database. The brand never implies a platform in the middle.
-- **Open.** MIT licensed and built in the open. Show the repository, the command, the real numbers.
-- **Plain-spoken.** Say what the software does in the words an operator would use. No hype, no mascots.
-- **Built to last.** Forums outlive chat. Restraint in colour, type and motion is how that reads on a page.
+Use the [Paper brand guidelines](https://app.paper.design/file/01M2XHWAP80F97J76E0QTY1CM6/p-2-0) and existing stylesheet tokens. The Paper guide identifies the repository styles as the source of truth when values differ.
 
 ## Logo
 
-The mark is a panel with two threads in it and a speech tail: a forum at icon size. It always takes the accent of the scheme it sits on, and the threads take the accent-contrast value. The wordmark is the name in lowercase, set in the sans at weight 450 with tracking −0.025em.
+Use the existing mark from `apps/web/src/components/logomark.tsx` or `public/icon.svg`. The board equivalent is in `themes/meith/src/shared.tsx`.
 
-- **Proportion.** Mark height 2rem beside type at 2.125rem, with a 0.6rem gap. Scale the lockup as one unit.
-- **Clear space.** Keep half the mark's height clear on every side.
-- **Minimum size.** 16px for the mark alone, 20px mark height for the lockup. Below that, use the mark without the word.
-- **Static assets.** Favicons and avatars cannot read tokens, so they use `#0b8f66`, which holds on light and dark. It is for icons only, never text.
-- **Do not** recolour the mark, decorate it with an outline, shadow, glow or container, set it on an accent fill, or retype the word in the serif or the mono. The social card is the one exception to the wordmark: it sets “Meith” at weight 600, as `apps/web/src/og/card.tsx` does.
+The mark uses the current accent; its threads use accent-contrast. Static icons use `#0b8f66`. Do not recolour, rotate, outline or decorate the mark, or put it on an accent fill.
 
-The site draws the mark in `apps/web/src/components/logomark.tsx` and `apps/web/public/icon.svg`; the theme draws the same mark in `themes/meith/src/shared.tsx`.
+| Property | Value |
+|---|---|
+| Wordmark | Lowercase `meith`, sans, weight 450, tracking −0.025em |
+| Lockup | 2rem mark, 2.125rem type, 0.6rem gap |
+| Clear space | Half the mark height |
+| Minimum | 16px mark alone; 20px mark in a lockup |
+| Social-card exception | `Meith`, weight 600 |
 
 ## Colour
 
-The ground is greyscale and the accent is a single green: a deep pine against white in light, emerald against near-black in dark. Dark is a first-class scheme, not an inversion. No single green clears 4.5:1 on both grounds, so each scheme carries its own step of the ramp.
-
 | Token | Light | Dark | Theme token |
 |---|---|---|---|
 | `--canvas` | `#fcfcfd` | `#08090c` | `background`, `card` |
@@ -41,135 +32,50 @@ The ground is greyscale and the accent is a single green: a deep pine against wh
 | `--border` | `#e4e6eb` | `#202430` | `border` |
 | `--border-strong` | `#d0d4dc` | `#2f3442` | `input` |
 
-The accent marks four things and nothing else:
-
-1. **The one primary action.** One filled button per screen. Its label takes `--accent-contrast`.
-2. **The current item.** The active row in a nav or list, and the hover state of a link or top rule.
-3. **A link's underline.** Text links stay in the text colour; the underline carries 60% accent until hover.
-4. **The emphasised word.** The serif italic word that closes a headline, and a measured bar in a chart.
+Use the accent for the primary action, current navigation, link underlines and marketing headline emphasis. Keep other surfaces neutral. Use token-derived washes and shadows rather than additional colours.
 
-Washes are mixed from the tokens, never picked: the hero glow is accent at 18% (22% in dark), the hero grid line is `--fg` at 6% (7% in dark). Shadows are neutral, mixed from `--fg`; the glow under the primary button is the only shadow that carries a hue. There are no new colours. Status, charts and illustrations use the greyscale ramp and the accent, so in the theme the pinned, locked, moderation and group marks sit on the ramp and the label carries the meaning.
-
-Measured pairs, against WCAG 2.1:
-
-| Pair | Light | Dark | Use for |
-|---|---|---|---|
-| `--fg` on `--canvas` | 18.96:1 | 17.94:1 | All text |
-| `--fg-muted` on `--canvas` | 7.31:1 | 8.45:1 | Body copy, labels |
-| `--accent` on `--canvas` | 5.35:1 | 10.36:1 | Links, emphasis, small text |
-| `--accent-contrast` on `--accent` | 5.48:1 | 9.69:1 | Primary button label |
-| `--fg-subtle` on `--canvas` | 3.72:1 | 4.24:1 | Large or non-essential text only |
-
-`--fg-subtle` fails for small text in both schemes, so it never carries meaning on its own.
+Small text needs at least 4.5:1 contrast. `--fg-subtle` does not meet that on the canvas in either scheme; use `--fg-muted` for meaningful labels. Status and selection must also have a non-colour indicator.
 
 ## Typography
 
-Three faces, no web font. The site carries no third-party request, so every face is a system stack with Inter named first.
+Use the site's system stacks: Inter followed by system sans, the system serif stack for marketing emphasis, and the mono stack for code and section labels. Do not add font downloads. Paper and rendered social cards use Lora Italic as a consistent serif substitute.
 
-- **Sans.** Everything by default: headlines at 400, sub-heads and buttons at 500, body at 400 in `--fg-muted`. `"Inter var", Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif`.
-- **Serif italic.** Emphasis only: one word or phrase per headline, always in the accent. Never upright, never body copy. `"Iowan Old Style", "Palatino Linotype", "Book Antiqua", Georgia, serif`.
-- **Mono.** Section labels in uppercase, commands, tokens and version numbers. `ui-monospace, "JetBrains Mono", "SF Mono", Menlo, Consolas, monospace`.
+Use weight 400 for headlines/body and 500 for subheads/buttons. Marketing headings may end in one accent-coloured serif italic phrase. Documentation headings use sentence case without that emphasis.
 
-The marketing scale:
+## Layout and controls
 
-| Step | Size | Weight · tracking · leading |
-|---|---|---|
-| Hero h1 | `clamp(3.5rem, 6.2vw, 6.5rem)` | 400 · −0.025em · 1.18 |
-| Section h2 | `clamp(2.1rem, 3.5vw, 3.35rem)` | 400 · −0.025em · 1.25 |
-| Item h3 | 1.02rem | 500 · 1.55 |
-| Body | 0.85–0.95rem | 400 · 1.8–1.9, `--fg-muted`, measure ≤ 34rem |
-| Label | mono 0.6rem | 0.075em, uppercase, `--fg-muted` |
+Use left alignment and 1px rules before adding filled panels. Marketing controls are square. Docs/app controls use 0.5rem radii and cards use 0.75rem.
 
-The theme keeps the weights, tracking and leading and scales the headline steps down for an application. Its labels run at 0.6875rem, because a board's labels (pinned, locked, moderation) carry meaning and must stay legible, and a post's body runs to 60rem so code blocks, tables and long paragraphs have room.
+The marketing shell is at most 72rem; the docs/header shell is at most 80rem, both with 2.5rem total outer space. Reuse the existing spacing scale.
 
-## Interface
+Preserve the 2px accent focus outline and 2px offset. Forward/outbound actions use ↗; hover moves the arrow, not the control. Transitions last 160–180ms and respect reduced motion. Reading and native navigation must work without scripts.
 
-- **Square on the page.** Marketing buttons and panels have no radius. The 0.5rem control and 0.75rem card radii belong to docs chrome and app UI.
-- **The arrow moves.** Every outbound or forward action ends in ↗, and nothing else does. On hover the arrow shifts 2px up and right; the control itself stays still.
-- **Rules before boxes.** Separate items with a 1px top rule in `--border-strong`. Reach for a filled panel only for code or a change of scheme.
-- **Left-aligned, always.** Headlines, copy and actions share a left edge. Intros split 1.05–1.15fr to 1fr, headline left, copy right.
-- **Works without script.** Most reading and posting works with JavaScript off. Brand moments never depend on animation or client code.
-- **Visible focus.** A 2px accent outline, offset 2px, on everything focusable. Never remove it, never restyle it per component.
-- **Quiet motion.** Transitions run 160–180ms and collapse under `prefers-reduced-motion`. Nothing loops, nothing autoplays.
-- **Never colour alone.** Current items also change weight or rule; links keep an underline; charts label their bars.
+## Documentation copy
 
-Layout measurements: the shell is `min(72rem, 100% − 2.5rem)`, the wide shell for the header and docs is `min(80rem, 100% − 2.5rem)`, the header runs wordmark and navigation from the left with search, scheme and the action from the right, bands pad 4.5rem block, grids gap 2.25rem and two-column intros 4rem, and the top beam is a 1px accent gradient, the first colour on the page.
+Use neutral, concise instructions, verified commands and actual UI labels. Omit slogans, opinions and promotional introductions. Follow [Documentation](documentation.md) for page structure.
 
-## Imagery
+Use Irish/British spelling in prose. Preserve code identifiers and UI labels. Write “Meith” for the product, “meith.dev” for the website, “board” for an installation, “forum” for a section, and “thread”/“post” for content. An operator runs infrastructure; an administrator manages the board.
 
-Meith has no illustration style, no stock photography and no mascot. The only imagery is the software itself: real screenshots of a real board, captured in both schemes, with sample data that reads like a community.
+## Screenshots
 
-- Every shot exists as `-light.png` and `-dark.png` in `apps/web/public/shots`, and the page swaps them with the scheme.
-- Desktop 2560 × 1640, phone 780 × 1560, both at 2×. Keep the browser chrome out; the frame is the 1px border.
-- Use the fixture board. Real-sounding thread titles, no celebrity names, no real member data.
-- Alt text describes what the screen shows and why it matters, in a sentence, in the voice.
+Use actual product captures with fixture data, descriptive alt text and paired light/dark images. Store site captures in `apps/web/public/shots`.
 
-Not in the brand: stock or generated imagery, landscape motifs (the fields, gorse and limewash identity was retired on purpose), device mockups, and decorative icons. The only glyphs are the mark, ↗ and the theme toggle. Diagrams are Mermaid, coloured from the tokens.
+| Capture | Pixels at 2× |
+|---|---|
+| Desktop | 2560 × 1640 |
+| Phone | 780 × 1560 |
 
-## Voice
+Exclude browser chrome, device mockups, stock/generated imagery, mascots and decorative icons. Use a flat screenshot with a border. Diagrams use the brand tokens.
 
-Meith talks to the person who will run the server. Short declarative sentences, concrete nouns, and a point of view about ownership. A headline states a position and lets its last word carry the weight: “Long live *the forum.*”, “A home you own. Not a platform you *rent.*”
+## Source files
 
-| Say | Not |
-|---|---|
-| It's a PostgreSQL database you can back up, move, or take apart. | Enterprise-grade data portability for modern communities. |
-| On your domain. On your terms. | The all-in-one community platform. |
-| `npx create-meith my-community` | Get started in minutes with our seamless onboarding. |
-| This preview uses sample data. Saving posts requires PostgreSQL. | Works out of the box for everyone. |
-
-House style:
-
-- **Spelling.** Irish and British English: colour, licence, organisation. Curly quotes and real apostrophes.
-- **The name.** “Meith” in prose, “meith” only in the wordmark and in commands. A forum installation is a “board”.
-- **Labels.** Section labels are two or three words in uppercase mono. Nothing else is uppercase.
-- **No hype.** No exclamation marks, no superlatives without a number, no emoji.
-- **Commands and code.** Set in mono, exactly as typed, lowercase. Never inside a sentence that ends with a full stop.
-- **Numbers and versions.** Versions as 0.37.5, no “v” in prose. Node.js, PostgreSQL, pnpm: each project's own capitalisation.
-- **Headings.** Sentence case. One italic emphasis at the end on marketing pages, none in docs.
-- **Punctuation.** Spaced em dashes used rarely. No ampersands in sentences.
-
-Terminology:
-
-| Term | Means | Not |
-|---|---|---|
-| Meith | The project and the software. Capitalised in prose. | MEITH, Meith.dev as the product name |
-| meith.dev | The website. Always lowercase, no www in copy. | Meith.dev, the Meith site |
-| Board | One running installation of Meith. | Instance, site, workspace, server |
-| Forum | A section of a board that holds threads. | Category, channel, room |
-| Thread · post | A discussion, and one message in it. | Topic, conversation · comment, message |
-| Member | Someone with an account on a board. | User (except in technical docs), customer |
-| Operator | The person who runs the server a board lives on. | Admin (a role on the board), owner |
-| Operator CLI | The command-line tool for backups, imports and upgrades. | Admin tool, the script |
-| Theme · plugin | Extensions that change how a board looks, or what it does. | Skin, template · add-on, module, app |
-| Marketplace | The listing at meith.dev/marketplace. | Store, shop |
-| Self-hosted | Runs on infrastructure the community controls. | On-prem, DIY |
-| Open source | MIT licensed. Two words as a noun, hyphenated before one. | OSS in headlines, “open” alone |
-
-## Where the truth lives
-
-| What | File |
+| Concern | Source under `apps/web` |
 |---|---|
-| Colour, type scale, radii, base controls | `apps/web/src/styles/globals.css` |
-| Homepage edition styles | `apps/web/src/styles/home.css` |
-| Header, wordmark, footer | `apps/web/src/styles/chrome.css` |
-| Inner marketing pages | `apps/web/src/styles/marketing.css` |
-| The mark | `apps/web/src/components/logomark.tsx`, `apps/web/public/icon.svg` |
-| Social card, its palette and fonts | `apps/web/src/og/card.tsx`, `palette.ts`, `fonts.ts` |
-| Name, tagline, descriptions, the story of the name | `apps/web/src/content/site.ts`, `about.ts` |
-| Screenshots | `apps/web/public/shots` |
-| The board theme | `themes/meith/src/tokens.ts`, `shared.tsx` |
-
-Tokens change in code first: update `globals.css`, then the theme tokens, then this page. Never introduce a colour the stylesheet does not have. Before anything public ships, check it against the list:
-
-- One accent, only on the action, current item, link underline or emphasised word.
-- Headline closes with one serif italic phrase, and only one.
-- Labels are uppercase mono; nothing else is uppercase.
-- Works in light and dark, and every screenshot has its pair.
-- Text pairs pass 4.5:1; `--fg-subtle` is not carrying meaning.
-- Corners are square on marketing surfaces.
-- Forward actions end in ↗, and nothing else does.
-- Copy is concrete, in Irish and British spelling, with no exclamation marks.
-- The name is “Meith” in prose and “meith” in the wordmark and commands.
-- Colours, type and spacing come from the theme tokens, not picked by eye.
-
-[Theme tokens and shared controls](../extensions/theme-design.md) describes how `themes/meith` maps these rules onto the board.
+| Palette, typography and controls | `src/styles/globals.css` |
+| Homepage | `src/styles/home.css` |
+| Header/footer | `src/styles/chrome.css` |
+| Inner pages | `src/styles/marketing.css` |
+| Social cards | `src/og/card.tsx`, `palette.ts`, `fonts.ts` |
+| Name and product copy | `src/content/site.ts`, `about.ts` |
+
+Check both schemes, focus, contrast and phone widths before publishing. For board palettes, see [Theme tokens](../extensions/theme-design.md).
diff --git a/docs/contributing/development.md b/docs/contributing/development.md
index 5cf44ada2..601726754 100644
--- a/docs/contributing/development.md
+++ b/docs/contributing/development.md
@@ -1,8 +1,8 @@
-# Contribute to Meith
+# Development setup
 
-Use this guide to run the Meith source repository and prepare a change. You need Node.js 22 or newer and pnpm 10. A generated board uses a different workflow; use [local board setup](../operations/local-board.md) if you are configuring your own community.
+Requires Node.js 22+ and pnpm 10. Run commands from the Meith repository root unless stated otherwise.
 
-## 1. Run the repository
+## Start with fixtures
 
 ```sh
 git clone https://github.com/meith-dev/meith.git
@@ -11,66 +11,53 @@ pnpm install
 pnpm dev
 ```
 
-Open <http://localhost:3000>. Without a database, this runs the sample board in fixture mode. It is suitable for browsing and presentation work, but does not save writes.
+Open `http://localhost:3000`. Fixtures require no database and do not save changes.
 
-## 2. Enable writes when needed
-
-For posting, installation or moderation work, start the development database:
+## Use PostgreSQL
 
 ```sh
 docker compose -f docker/compose.dev.yml up -d
 cp .env.example .env
 ```
 
-In `.env`, set `DATA_SOURCE=postgres`, `DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:55432/community_test`, and an independently generated `AUTH_SECRET` of at least 32 characters. `openssl rand -hex 32` generates a suitable secret. Keep the file out of git.
+Set these values in `.env`, including a random `AUTH_SECRET` of at least 32 characters:
 
-```sh
-pnpm meith migrate
-pnpm dev
+```dotenv
+DATA_SOURCE=postgres
+DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:55432/community_test
+AUTH_SECRET=replace-with-a-random-secret-at-least-32-characters
 ```
 
-Open `/install`, unlock it with `AUTH_SECRET`, and complete installation. Stop the development database before running the browser suite: both use port 55432.
-
-> [!CAUTION]
-> `docker compose -f docker/compose.dev.yml down -v` deletes the development volume and its data. Use ordinary `down` to stop it without deleting data.
-
-## 3. Find the code to change
-
-| Work | Location or guide |
-|---|---|
-| Business behavior | Domain packages under `packages/` |
-| Pages, forms and request handling | `apps/community`; [Next.js conventions](nextjs-conventions.md) |
-| Database and infrastructure | `packages/db`, `packages/drivers`, `packages/runtime` |
-| Shared interface components | `packages/ui`; [UI conventions](ui-conventions.md) |
-| Themes and plugins | [Build extensions](../extensions/extensions.md) |
-| Marketing and docs website | `apps/web`; start it with `pnpm site:dev` |
-| Packaging and generated boards | [Board workspaces](board-workspaces.md) |
-
-Read [Architecture](architecture.md) and the repository's `AGENTS.md` before editing. Domain packages do not import application or infrastructure internals.
-
-The site's Community links use `site.forum` and open [forum.meith.dev](https://forum.meith.dev), the live community running from its own template repository. Fixture boards are read-only development and screenshot previews.
+Run `pnpm meith migrate`, then `pnpm dev`. Open `/install`, unlock with `AUTH_SECRET` and create the board administrator. Use [Scheduled tasks](../operations/scheduled-tasks.md) for background work.
 
-The marketing site runs at <http://localhost:3100>. The homepage uses a neutral canvas, restrained typography and brief copy, with links to the live forum and dedicated audience guides. Below the audience guides, an ownership section sets out what a community keeps control of — its domain, server, database and roles. A technology section then names what a board is built on — Node.js, TypeScript, Next.js, Base UI and PostgreSQL — with the major version of each read when the site is built (`src/content/stack.ts`) from the pins in `apps/community/package.json`, `packages/ui/package.json`, `docker/Dockerfile` and `docker/compose.yml`, so an upgrade changes the page without anyone editing copy; the build fails, naming the file, if one of those stops stating a version. Customisation links explain how to build themes and plugins, and the extensions listing (served from the marketplace feed) provides starting points; first-party themes are examples of what the theme system supports. Keep detailed setup and product explanations in the documentation.
+Stop this database before running the self-contained browser suite if it uses the same port. `docker compose -f docker/compose.dev.yml down -v` deletes its data.
 
-The shared header links to Home, About, Who it’s for, Docs and Community, in that order. Community is the one external link — it opens the live forum and carries an arrow to say so. Its colour control cycles through System, Light and Dark; explicit choices persist in the browser. The mobile menu closes after navigation, Escape, outside interaction or a switch to the desktop layout.
+## Work on the website
 
-Social share cards are generated at `/og` and the matching routes under each section, sharing one editorial card built in `src/og/`. The homepage card carries the same wording as the hero; keep them in step when the hero copy changes.
+```sh
+pnpm site:dev
+```
 
-## 4. Validate the change
+Open `http://localhost:3100`. The site's forum links point to the configured live forum. Docs are loaded directly from `docs/`; see [Documentation](documentation.md).
 
-Run the relevant checks from [Testing](testing.md). Format only files you touched.
+## Repository layout
 
-For marketing site changes, run `pnpm exec playwright test --config apps/web/e2e/playwright.config.ts`. This starts the site on port 3100 and checks audience navigation, colour preference persistence, mobile navigation and page layouts. The board's `pnpm test:e2e` and `pnpm site:shots` use their own servers and configurations.
+| Path | Purpose |
+|---|---|
+| `apps/community` | Board application (`@meith/web`) |
+| `apps/web` | meith.dev (`@meith/site`) |
+| `apps/cli`, `apps/worker` | Operator commands and background worker |
+| `packages` | Domain, runtime, infrastructure and extension contracts |
+| `boards/stock` | Official image's board configuration |
+| `themes`, `plugins`, `examples` | Extensions and example source |
+| `docker` | Deployment files |
 
-Before opening a pull request:
+See [Architecture](architecture.md) and [Board workspaces](board-workspaces.md).
 
-```sh
-pnpm verify
-pnpm comments:check
-```
+## Validate changes
 
-Keep documentation in step with behavior. Explanations belong in docs, not inline code comments. [Repository rules](repository-checks.md) explains the enforced checks; [Documentation maintenance](documentation.md) explains the publishing workflow.
+Run focused tests while editing, then `pnpm verify` and `pnpm comments:check`. Use [Testing](testing.md) for browser and PostgreSQL tests. Format only touched files with `pnpm exec biome check --write <files>`.
 
-## 5. Submit a focused pull request
+No explanatory inline comments are allowed. Put explanations in `docs/`. Exceptions are `biome-ignore`, `@ts-expect-error`, compiler-read type annotations, and the six source files used for generated theme/plugin references. See [Repository checks](repository-checks.md).
 
-Use a Conventional Commit title such as `fix(posts): preserve attachments when editing`. Describe the behavior change, relevant tests and limitations. Leave package versions unchanged; maintainers use the [release procedure](release.md).
+Use Conventional Commits (`type(scope): summary`). Update docs with behaviour changes. Feature changes do not change versions.
diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md
index 0d9f044a4..2aa885024 100644
--- a/docs/contributing/documentation.md
+++ b/docs/contributing/documentation.md
@@ -1,59 +1,43 @@
-# Maintain the documentation
+# Maintain documentation
 
-Documentation source lives in `docs/`. The website publishes these Markdown files and uses `apps/web/content/docs.manifest.json` for navigation, titles, summaries and reading order.
+Source lives in `docs/`. The website renders the same files; `apps/web/content/docs.manifest.json` defines navigation and metadata.
 
-## Choose the reader and task
+## Writing rules
 
-Put a page in one reader path: Start here, Use a community, Manage a community, Install and operate, Build extensions, Use the API, or Contribute to Meith. Use the directory for that audience. Generated contract files remain under `reference/` and appear in the appropriate reader section.
+Write neutral instructions. Start with the task and prerequisites, then the steps and a way to check the result. Remove introductions, opinions, promotional language and repeated explanations. Keep setup guides complete from prerequisites through verification. Documentation checks must not impose minimum prose lengths.
 
-A tutorial teaches one working path. A task guide explains a concrete operation. A reference defines fields, commands or rules. An explanation describes why a system behaves as it does. Keep these purposes separate when their audiences or prerequisites differ.
+Use actual UI labels and commands verified against the code. State where commands run. Default to pnpm in the Meith workspace. Use npm for generated boards, whose tooling requires it, and for npm-specific publishing operations.
 
-Before adding a page, look for the existing home of the topic. Add a link to that home rather than repeating its full explanation elsewhere.
+Use short headings, numbered procedures and tables for fields or limits. Link to existing explanations instead of repeating them. Keep security boundaries, access requirements, data-loss warnings and recovery steps beside the relevant action.
 
-## Write a usable page
+Markdown, fenced code and tables are supported. Raw HTML is escaped. H2/H3 headings appear in contents and search; code fences are excluded from search text, so mention important commands and keys in prose too.
 
-Start with the outcome, required access and prerequisites. Use numbered steps for procedures and include a way to check success. State where a command runs: source checkout, board repository, container or hosting panel.
+## Add or move a page
 
-Use the actual UI labels, concrete examples and descriptive headings. Explain unfamiliar terms on first use. Keep implementation reasoning in contributor explanations and reference pages; keep member instructions focused on what the member can do.
+1. Put the file in its audience directory.
+2. Register its unique slug, title, short blurb, section and optional group in the manifest. Each section has one primary page.
+3. Use relative Markdown links between documents.
+4. Run `pnpm site:docs` to update `docs/README.md`.
+5. Update links and anchors in callers, including website content.
 
-Preserve security, permission and recovery constraints. Put destructive-operation warnings immediately before the action. Confirm commands and limits against implementation and tests; recheck provider-specific facts against official documentation.
+The docs home lists the guides. Previous/Next stays within the section. Long pages have desktop and mobile contents navigation. Historical heading anchors are not redirected.
 
-Use ordinary Markdown, fenced code, tables and supported callouts. Raw HTML is escaped by the site. H2 and H3 headings appear in the contents and search index. Include important command names and setting keys in prose or tables because fenced code is omitted from search text.
-
-## Register and link the page
-
-1. Add the Markdown file under its reader directory.
-2. Add its manifest entry with a unique slug, title, blurb, section and optional group. Each section has one primary page.
-3. Link to related pages with relative Markdown paths so links work on GitHub and the website.
-4. Run `pnpm site:docs` to regenerate the index in `docs/README.md`.
-5. Update links and site calls to action when moving or renaming a topic.
-
-The docs home gives each reader a starting point and an expandable complete index. Previous/Next stays inside the current reader path. Long pages have a desktop contents rail and a mobile contents control. No historical anchor redirects are maintained: update callers when restructuring a page.
-
-## Update generated references at source
+## Generated references
 
 | Reference | Source | Command |
 |---|---|---|
-| Theme slots and models | `packages/theme-kit/src/{slots,api,view-models}.ts` | `pnpm theme:docs` |
-| Plugin hooks | `packages/plugin-kit/src/{hooks,payloads,regions}.ts` and call sites | `pnpm plugin:docs` |
-| REST API and OpenAPI | `packages/api/src/` registry, schema and reference renderer | `pnpm api:docs` |
-| Performance | Recorded results and `packages/testkit/src/load/` budgets | `pnpm perf:docs` |
-| Documentation index | Documentation manifest | `pnpm site:docs` |
-
-Never hand-edit generated output. The six theme/plugin source files above are the explicit exception to the no-inline-comments rule because their prose becomes published reference material.
+| Theme slots/models | `packages/theme-kit/src/{slots,api,view-models}.ts` | `pnpm theme:docs` |
+| Plugin hooks/regions | `packages/plugin-kit/src/{hooks,payloads,regions}.ts` and call sites | `pnpm plugin:docs` |
+| REST/OpenAPI | `packages/api/src` registry, schema and renderer | `pnpm api:docs` |
+| Performance | Recorded results and load-test budgets | `pnpm perf:docs` |
+| Index | Documentation manifest | `pnpm site:docs` |
 
-Deploy template READMEs are generated from `packages/create-meith/src/scaffold.ts` with `pnpm templates:gen`. Extension README text is in `scaffold-extension.ts`; example source templates are regenerated with `pnpm extension:gen`.
+Edit sources, then regenerate. The six theme/plugin files are exceptions to the no-inline-comments rule because their prose is published documentation.
 
-## Verify the result
+Deploy README templates come from `packages/create-meith/src/scaffold.ts` through `pnpm templates:gen` at release time. Extension README templates live in `scaffold-extension.ts`; `pnpm extension:gen` updates the example source templates.
 
-```sh
-pnpm docs:index:check
-pnpm docs:links:check
-pnpm site:docs:check
-pnpm site:build
-pnpm comments:check
-```
+## Validate
 
-Run `pnpm verify` before a PR. Preview with `pnpm site:dev`; inspect the affected pages on desktop and phone widths, follow the steps as the intended reader, and try the words they would search for. A passing link check does not prove a procedure is understandable or correct.
+Run `pnpm docs:index:check`, `pnpm docs:links:check`, `pnpm site:docs:check`, `pnpm site:build` and `pnpm comments:check`. Run `pnpm verify` before a PR.
 
-Keep GitHub entry READMEs short and point them at the canonical docs. Do not add separate long-form manuals inside packages.
+Preview with `pnpm site:dev`. Check desktop and phone layouts, links, contents and search. Follow the procedure as its intended reader. Keep package/root READMEs short and link to canonical docs.
diff --git a/docs/contributing/forms-and-actions.md b/docs/contributing/forms-and-actions.md
index acd23ca89..484ac998b 100644
--- a/docs/contributing/forms-and-actions.md
+++ b/docs/contributing/forms-and-actions.md
@@ -1,234 +1,35 @@
-# Forms and Server Actions
+# Forms and server actions
 
-Build validated, permission-checked mutation flows that work with and without JavaScript. These conventions apply to Meith application code, not external themes or plugins.
+## Server actions
 
-## Server Actions
+Keep `"use server"` adapters in `apps/community/src/server/*-actions.ts` thin:
 
-Server Actions live in `src/server/*-actions.ts`, marked `'use server'` at
-the top of the file.
+1. Parse and validate submitted data.
+2. Resolve the actor and authorize the operation.
+3. Call the domain service.
+4. Convert expected errors into `FormState`.
+5. Invalidate affected data and redirect outside the error-catching block.
 
-### The adapter shape
+Every action checks its own access. A guarded layout or hidden button is not authorisation. Preauthentication and signed-token flows use their own explicit checks.
 
-An action is a **thin adapter**: parse `FormData`, validate, call a command
-in a domain package, redirect. The actions in `auth-actions.ts` all follow
-this shape, and new ones should look boring next to them:
+Use the core validation, forbidden, not-found, conflict and rate-limit errors. Log unexpected failures without exposing their details to the member.
 
-```ts
-export async function createThreadAction(
-  _prev: FormState,
-  form: FormData,
-): Promise<FormState> {
-  const title = field(form, 'title')          // 1. read FormData
-  const actor = await getActor()              // 2. who is asking
+Never return credentials in `FormState`. The development password-reset exception requires its explicit environment gate and must remain unavailable in production.
 
-  const { threads, authorizer } = getContainer()
-  try {
-    authorizer.require(actor, 'thread.post', target)   // 3. re-check authz
-    await threads.create({ ... })                      // 4. call the command
-  } catch (err) {
-    return toFormState(err, { title })                 // 5. domain error → state
-  }
+## Native forms
 
-  redirect(`/thread/${id}`)                            // 6. redirect on success
-}
-```
+Use a real `<form action={...}>`. Preserve submitted values after validation, except passwords and other secrets. Associate labels and errors with controls. Use the shared `FormError` focus behaviour.
 
-### Rules that are not negotiable
+`SubmitButton` and `PendingButton` use form status to prevent duplicate enhanced submissions. Server validation and idempotency still apply.
 
-**Every action re-checks authorization itself.** Rendering the form is not
-authorization — an action is a public HTTP endpoint, and nothing stops
-someone POSTing to it directly. `proxy.ts` is not a boundary either; it
-only decides whether to bounce a cookie-less request on a protected prefix
-to `/login`.
+## JavaScript enhancement
 
-In practice the check is a `require*()` call — `requireAdmin()`,
-`requireUserAdmin()` and their kin — that throws a `ForbiddenError` the
-`catch` turns into a `FormState`. It is often one hop down, in a helper the
-action delegates to rather than in the exported function itself, which is
-why this stays a review rule: no textual pattern separates an action that
-delegates its check from one that never had it. When you review an action,
-follow the hop. The actions that legitimately have no check are the
-pre-auth ones — login, register, password reset, install — and
-`unsubscribeByTokenAction`, where the token in the URL is the credential.
+Use `useActionState` and the existing progressive form helpers. `ProgressiveMarker` is set after enhancement mounts; `isEnhancedSubmit` selects the response path. Derive the authoritative result on the server before choosing state or redirect.
 
-**`redirect()` goes outside the `try`.** It works by throwing, so a `catch`
-that swallows it turns a successful action into a silent no-op. Look at
-`auth-actions.ts`: every `redirect` is after the `try/catch`, never inside.
+Do not replace native submission with an `onSubmit` transport or recompute permissions in the client. A scheme toggle may update its class immediately while saving the preference in the background.
 
-**Return a serialisable `FormState`, never throw to the client.** Domain
-errors (`ValidationError`, `ConflictError`, `ForbiddenError`) are the
-expected failure channel and become a message on the form. Anything
-unrecognised is logged and becomes a generic message — see the
-`toFormState` helpers each action file builds with `formStateReporter`.
+## Theme integration
 
-> [!CAUTION]
-> **Never return a credential in `FormState`.** It is serialised into the
-> client payload. This is not hypothetical: the password-reset action once
-> returned a live reset token to the browser, and it was an
-> account-takeover hole.
+The app builds forms and passes them into theme regions. Models contain serialisable data; server actions and authorisation logic stay in the app.
 
-The rule has exactly one exception in the codebase, and it is worth knowing
-about because it looks like the bug above. `requestResetAction` returns the
-reset token as `values.devToken` when `env.NODE_ENV === 'development'`, so
-a board run locally without a mailer can still finish the flow;
-`reset-request-form.tsx` renders it as a link. Two tests in
-`auth-actions.test.ts` pin both directions — the token is returned in
-development and withheld everywhere else.
-
-What makes it safe is the environment gate, so treat that gate as
-load-bearing. `NODE_ENV` defaults to `development` in
-`packages/core/src/env.ts` when unset; the shipped `Dockerfile` sets
-`production` explicitly. A deployment that runs the app some other way and
-leaves `NODE_ENV` unset serves reset tokens to anyone who submits the
-form. Nothing else in `FormState` gets this exception, and a second one
-should be argued for in the PR rather than copied from here.
-
----
-
-## Forms and `useActionState`
-
-Every page on the no-JavaScript list must work with JavaScript disabled.
-That is a hard requirement, not an aspiration, and it shapes how forms are
-written. The list is not prose: it is the `e2e/*-no-js.spec.ts` suite,
-which drives the real pages with scripting turned off. Adding a page to the
-list means adding a spec there.
-
-- The `<form action={...}>` must work as a native submit. No `onSubmit`, no
-  `preventDefault`, no client-side validation the server does not repeat.
-- `useActionState` renders the error the action returned. With JS off the
-  page re-renders server-side and shows the same message.
-- Echo the user's input back in `FormState.values` so a failed submit does
-  not blank the form — **except the password**.
-- `FormError` (and the install wizard's error summary) is a JS-on
-  enhancement: `useFocusOnFail`, in `form-controls.tsx`, moves focus to the
-  error region when a pending submit settles into a failure, so a keyboard
-  or screen-reader user lands on what went wrong instead of hunting for it.
-  With JS off the same message renders in place, unfocused, from the
-  server round-trip.
-- A submit is disabled while its action is in flight, so a double-click or an
-  impatient second press never fires the action twice. This too is a JS-on
-  enhancement built on `useFormStatus`, and every board action button carries
-  it: `SubmitButton` is the primary control — it disables and swaps to the
-  `form.working` label — and `PendingButton` is the same guard for every other
-  submit, from the composer's preview/save-draft/delete and the thanks toggle
-  to the account, admin, and moderation forms. Both disable *every* submit in
-  their form while any one of them is pending, so a reply, post, message, or
-  moderation command runs once and no sibling button races it. `PendingButton`
-  takes `showWorking` to swap a text button to `form.working` (omit it for
-  icon or compact command buttons); it reads that label from the board-wide
-  `CopyProvider`, so it works in a server-rendered form as a client island.
-  A form that already tracks `useActionState`'s `pending` itself (the install
-  wizard, the notification menu, the forum and navigation trees) keeps its own
-  handling. With JS off no button is ever disabled — the enhancement layers on
-  top of the native submit, it does not replace it.
-
-> [!IMPORTANT]
-> **Islands enhance; they never enable.** If removing a client component
-> breaks a page, it was not an island. Write the server path first and the
-> island second.
-
-### One-tap actions: the enhancement island
-
-Thanks, a poll vote, following a thread, and the dark-mode toggle share a
-shape: a single `<form action={serverAction}>` whose no-JS baseline is a
-POST, a redirect, and a full-page repaint. That baseline is correct and
-stays — the enhancement is a thin layer that, when JavaScript has loaded,
-swaps in the action's own return value instead of navigating, so pressing
-the star or the poll's radio button updates in place.
-
-**`ProgressiveMarker`** (`src/components/content/progressive-marker.tsx`) is
-the whole mechanism, and it is deliberately not a form wrapper — it renders
-one hidden field, mirroring the interception style of `quote-in-place.tsx`
-rather than replacing the form the way that file replaces a link:
-
-```tsx
-export function ProgressiveMarker() {
-  const [enhanced, setEnhanced] = useState(false)
-  useEffect(() => setEnhanced(true), [])
-  return enhanced ? <input type="hidden" name={PROGRESSIVE_FIELD} value="1" /> : null
-}
-```
-
-It renders nothing on the server and on first client paint — the same
-`enhanced` flip used by `LiveRegion` — so there is no hydration mismatch,
-and it adds the field to the DOM only once an effect has actually run,
-which is the one fact a native submit can never produce on its own. Drop it
-inside the existing `<form>`; nothing else about the form's markup or
-action changes.
-
-The action reads the field with `isEnhancedSubmit(form)`
-(`src/view/progressive-enhancement.ts`) and **branches on it**, not on
-whether the request looks like a fetch:
-
-```ts
-if (isEnhancedSubmit(form)) return { thanks: { thanked, count } }
-
-redirect(postLink(returnTo, postId))
-```
-
-A plain browser submit never carries the field, so the branch is unreachable
-without JavaScript and the redirect fires exactly as before — this is why
-the `*-no-js.spec.ts` suite needs no changes for an enhanced action. With
-JavaScript, `useActionState`'s own submit handling (never a hand-rolled
-`onSubmit`) invokes the action over fetch, the field is present, and the
-action returns fresh state instead of throwing a redirect — a
-`useActionState` action that redirects on success will navigate the
-enhanced path too, so the branch has to come before it, not around it.
-
-**The returned state is the only thing the island may render.** `thanks`,
-`pollVote`, and `subscribed` are additive fields on the same `FormState` (or
-a small dedicated type, for the poll) the action already returned on
-failure — extending a return type, never a parallel API route. The
-component reads `state.thanks?.count ?? count`, falling back to the
-server-rendered prop until an action actually runs. It never recomputes
-`mayCast`, `canVote`, or any other permission-shaped fact itself: the poll's
-results block versus its voting inputs is decided by `mayCast` inside
-`PollVoteView` (`src/view/poll-vote.ts`), computed identically on the
-initial server render and inside the action after a vote, so the same
-authorization decision that gated the no-JS page also gates what the
-island is allowed to show next. This is the same reasoning as
-`quote-in-place.tsx` fetching quoted markup from the server rather than
-reading it out of the DOM.
-
-The theme toggle is the one variant that does not wait on the round trip at
-all: its `onClick` sets `document.documentElement`'s class immediately —
-`SchemeToggle` in `src/components/shell/scheme-toggle.tsx` — and the form
-submit that follows only persists the cookie in the background. The
-server-decided class from `schemeClass()` stays the source of truth on the
-next full load; the click only avoids the one visible flash a full repaint
-would otherwise cost.
-
-A new one-tap action follows the same three steps: extend the action's
-`FormState` (or its own return type) with the minimal facts the island
-needs, branch on `isEnhancedSubmit` before any `redirect`, and drop a
-`<ProgressiveMarker />` in the form.
-
-### Forms that live in a theme slot
-
-A page whose whole content is a form — the composer, and every editor after
-it — splits in two: the **theme** renders the page around it, and the
-**app** renders the `<form>` into a region. The reason is mechanical rather
-than stylistic: the form element carries a Server Action reference, and
-those are not plain data, so they never cross the theme contract. Controls
-are built from the shared token-styled primitives in
-`src/components/auth/form-controls.tsx`, which is what keeps an app-owned
-form looking like part of the theme.
-
-A slot model should not carry a prop no theme can fill. If a value only
-exists after a submit — a preview of what was typed, a per-field error — it
-belongs inside the form region, not in the view model.
-
----
-
-## Errors
-
-Use the taxonomy in `@meith/core`: `ValidationError`, `ForbiddenError`,
-`NotFoundError`, `ConflictError`, `RateLimitedError`. Each maps to a
-status and a rendered page.
-
-Throwing a bare `Error` for a user-facing failure is a bug: callers key off
-the taxonomy. `saveSettings` once threw a plain `Error` on an invalid
-value, which would have shown "Something went wrong" in the admin panel
-instead of the actual problem.
-
----
+For destructive confirmations and success feedback, use [UI conventions](ui-conventions.md).
diff --git a/docs/contributing/marketplace-maintenance.md b/docs/contributing/marketplace-maintenance.md
index 474f7a74d..3f452d574 100644
--- a/docs/contributing/marketplace-maintenance.md
+++ b/docs/contributing/marketplace-maintenance.md
@@ -1,242 +1,42 @@
-# Maintain the marketplace feed
+# Marketplace maintenance
 
-Maintain listings and the feed consumed by boards. This is contributor reference; extension authors should use Publish to the marketplace.
+Extension authors should follow [Publish an extension](../extensions/marketplace.md).
 
-## The generator
+## Generate and validate
 
 ```sh
-pnpm marketplace:gen          # validates and writes the feed
-pnpm marketplace:gen:check    # validates and fails if the feed is stale
+pnpm marketplace:gen
+pnpm marketplace:gen:check
 ```
 
-`pnpm verify` runs the check. It fails, naming the file and the field, on
-a `kind` that is not `plugin` or `theme`, a `version` or `meith` range that
-does not parse, a `key` that would not pass `definePlugin` either, a
-screenshot the array names that does not exist under
-`marketplace/screenshots/`, or two listings claiming the same `key` or
-`package`. It also fails, separately, if the listings changed and nobody
-ran `pnpm marketplace:gen` to update the published feed — the same
-discipline as [the other generated documents](documentation.md).
-
-The output is deterministic: listings are sorted by `key` — by UTF-16 code
-point, not `String.localeCompare`, whose result follows the machine's own
-`LANG`/ICU collation and disagrees across machines on `[a-z0-9-]` strings
-— regardless of directory order, and nothing in it is time-stamped, so
-running the generator twice with unchanged listings produces
-byte-identical output on any machine, not only the one that generated it.
-
-The merged feed lands at `apps/web/public/marketplace/v1.json` — Next.js
-serves anything under a site's `public/` directory at the matching path,
-the same way `apps/web/public/shots` becomes the images on meith.dev's own
-pages — and the screenshots land beside it at
-`apps/web/public/marketplace/screenshots/`. Both are committed, exactly
-like `docs/reference/openapi.json`: a generated file `pnpm verify` checks for
-staleness rather than a build step that produces it fresh.
-
-The generator also verifies that these are the *only* files in play. Every
-screenshot actually present under `marketplace/screenshots/` must be
-referenced by some current listing's `screenshots` field, and every file
-under `apps/web/public/marketplace/` must be either the feed file or a
-referenced screenshot — nothing else. `pnpm marketplace:gen:check` fails,
-naming the file, on anything that does not fit that shape: a screenshot a
-deleted or renamed listing left behind, or a file dropped straight into
-the published directory rather than added as a reviewed listing.
-`pnpm marketplace:gen` deletes such orphans on both sides rather than
-leaving them for a human to notice — which is also why deleting a
-listing's screenshot from `marketplace/screenshots/` before running the
-generator, as [Delisting](#delisting) already asked for, does the right
-thing either way. Each screenshot is also checked as a file, not just as a
-name: its first 8 bytes must be a real PNG signature, and it must be under
-5,000,000 bytes, so a `*.png` filename with some other payload behind it
-never reaches meith.dev's public assets.
-
-## The feed URL is a contract
-
-`/marketplace/v1.json` is versioned in its path on purpose. A board built
-against today's shape can keep reading it after the shape changes,
-because that change ships as `/marketplace/v2.json` alongside it rather
-than in place of it.
-
-## Where a board operator browses it
-
-The catalog is browsed on the public marketplace at
-[meith.dev/marketplace](https://www.meith.dev/marketplace) — an index of
-every listing and a page per listing, built from this same feed at site
-build time (`apps/web/app/marketplace`), with the screenshots served from
-the site's own public assets. Each listing page carries the description,
-the screenshots, the compatibility it declares, and the exact steps to
-install it: `npm install <package>` and `meith plugin:add <package>`
-for a plugin, or the install plus a `meith.config.ts` line for a
-theme, and a link back here. It is a page to read, not a button that
-pretends to act, because nothing installs a package but the operator, in
-the board repository they own.
-
-Those steps name `npm`, never `pnpm add … --filter @meith/web`. What
-installs a listing is a *board*, and a board — scaffolded by
-`create-meith`, or graduated out of the stock image by `board:eject` — is
-a single `package.json` whose `forum-web` needs a hoisted `node_modules`,
-not this repository's pnpm workspace: the filter names a workspace that
-does not exist out there, and pnpm's default linker produces a tree the
-board cannot build from. The monorepo form belongs in [the plugin
-API](../extensions/plugins.md), whose reader really is in a checkout
-of this repository.
-
-## The board-side consumer: update checks
-
-The board does not browse the catalog; that is what the public pages
-above are for. What the board itself does with the feed is narrower and
-specific to what it already runs — it tells the operator when something
-installed has a newer version worth moving to.
-
-`marketplace.feed_url` is a board setting (**Settings → Board**, under
-**Show advanced**), defaulting to the URL above, so a self-hosted mirror
-serving the same shape works as a drop-in replacement. **The board fetches it, never the
-member's or the operator's browser** — a `marketplace.refresh_catalog`
-task (`packages/tasks`) fetches, validates against the same shape this
-document describes, and caches the result once a day; the **Check for
-updates** button on **Admin → Plugins** and **Admin → Themes** runs the
-identical pass on demand (`refreshCatalog` in `packages/marketplace`,
-called by both the task and the admin action — one implementation, not
-two). A board with no outbound network fails the fetch quietly — logged,
-not alarmed — and those pages carry a plain note that the marketplace
-could not be reached; whatever it last fetched successfully keeps
-informing the check.
-
-For each installed plugin and theme, the board compares the version it
-runs against the version the feed lists (`computeListingStatus` in
-`packages/marketplace`) and, when the feed's is newer and compatible with
-this build, marks that row **Update available** with the version to move
-to on the **Plugins** or **Themes** page. A plugin declares its version in
-`definePlugin`; a theme declares its in `defineTheme`, so the check covers
-themes exactly as it covers plugins. A newer version that is incompatible
-— its `apiVersion` or `meith` range fails against this build — is not
-offered, because installing it would not work.
-
-When the daily fetch first sees a newer, compatible version of an
-installed plugin or theme, administrators are notified through the board's
-own notification system (`marketplace.update_available`, a staff-audience
-kind next to `system.task_failed`) once per (key, version) ever —
-independent of whether that notification has since been read, which a
-bare dedupe key on the notification service is not.
-
-The daily task and an admin's **Check for updates** click can land on the
-same newly-seen version at the same moment, so "once ever" is enforced by
-claiming the (key, version) marker atomically before the notification
-is raised, not by checking it and writing it back afterwards — a
-`PostgresMarketplaceCacheRepository.claimNotified` call is a single
-`UPDATE ... WHERE NOT (already claimed)` against the one
-`marketplace_catalog` row, so a second, concurrent caller either blocks
-behind the row lock and then sees the marker already there, or loses the
-`WHERE` race outright; either way it reports the claim as already taken
-and `refreshCatalog` skips the notification. The marker is written before
-the notification is raised, on purpose: if raising the notification then
-throws, this build has claimed a (key, version) it never actually
-announced, and will not retry it — a missed notice, not a duplicate one.
-That is the accepted failure mode, because the update line on the Plugins
-and Themes pages is computed fresh from the cached feed on every read,
-independent of the notified-marker set; a missed notification is
-recoverable by the operator simply visiting those pages, where a duplicate
-notification for the same version, ever, is the one thing this system
-promises not to do.
-
-See [The organiser's guide § When to hand it to somebody
-technical](../administration/manage-members.md#when-to-hand-it-to-somebody-technical) for
-the operator-facing walkthrough.
-
-### Outbound fetches do not follow redirects
-
-The board's one outbound fetch to an untrusted host — the daily/on-demand
-catalog fetch (`packages/marketplace/src/fetch.ts`) — passes
-`redirect: 'manual'` and treats any non-2xx response, a redirect included,
-as a failed fetch, exactly like an unreachable host or a 503. The feed
-host is an admin-configured address (see below) that could answer with a
-`302` to a link-local or RFC1918 target; left unhandled, the fetch would
-follow it before its own shape validation caught the mismatch — usable as
-a reachability or timing probe into a network the feed host itself cannot
-otherwise reach. Refusing to follow closes that without changing how a
-redirect-free feed host behaves.
-
-The fetch also refuses to buffer a hostile body whole before enforcing its
-size cap. A `Content-Length` over the cap is rejected before any read
-begins; otherwise the body is read through `readCappedBody`
-(`packages/marketplace/src/fetch.ts`), which walks the response stream
-chunk by chunk and cancels it the moment the running total passes the cap,
-rather than accumulating the whole thing first. The existing 10-second
-abort timeout is unchanged.
-
-### The feed URL is an admin-trusted setting
-
-`marketplace.feed_url` (validated by `isUsableFeedUrl`,
-`packages/settings/src/origin.ts`) accepts any `https:` host, plus plain
-`http:` to a loopback address for local mirrors and tests. That
-deliberately permits internal addresses too: an admin can point it at an
-RFC1918 or link-local host, and the board will fetch it once a day and on
-demand from the **Check for updates** button — a standing SSRF pivot into
-whatever network the board can reach.
-
-This is accepted, not fixed, on purpose. `marketplace.feed_url` sits at
-the same trust tier as every other admin-only setting a board already
-trusts outright — a custom SMTP host, a webhook URL, an OAuth issuer
-origin — and an admin able to set it can already reach the network
-directly. The mail and webhook destinations are resolved-and-pinned before
-each connection, but they had to be: a mail endpoint is reached on a
-member's password-reset, and a webhook and a web-push endpoint carry
-member-supplied data outward, so those requests are made on a visitor's
-behalf and cannot inherit the admin's trust. The catalog fetch is
-different — it runs only from the daily task and the admin's own **Check
-for updates** button, never from a visitor's request. Guarding it would
-also buy less than it looks like: `isUsableFeedUrl` is a synchronous, isomorphic `zod`
-refinement shared between the browser-rendered settings form and the
-server-side save path (`packages/settings/src/definitions.ts`), so it has
-no way to resolve the hostname — Node's `dns` module does not exist in a
-browser bundle, and `refine` here is not async. Moved server-side and made
-async, a resolved-IP deny list would still only run once, at save time; it
-would not stop a host that resolves to a public address at that moment and
-a private one when the daily task or the **Check for updates** button
-actually fetches it (DNS rebinding), which is exactly the case a
-determined or compromised
-admin session would use. Given that, the honest fix here is naming the
-trust boundary, not a check that would mostly look like one without being
-one.
+The generator reads `marketplace/listings` and `marketplace/screenshots`, then writes the committed feed and images under `apps/web/public/marketplace`.
+
+It validates kind, key, version, compatibility range, unique keys/packages and referenced screenshots. Images must have a PNG signature and be smaller than 5,000,000 bytes. The check rejects orphan source or output files; generation deletes them. Output is sorted by key and has no timestamp.
+
+Keep `/marketplace/v1.json` compatible. Publish a changed schema at a new versioned path.
+
+## Board update checks
+
+The board fetches the configured `marketplace.feed_url` daily through `marketplace.refresh_catalog`, or on **Check for updates** in the plugin/theme panels. Fetch failures retain the last successful cache and appear in logs and the panel.
+
+An installed extension is offered an update only when the feed version is newer and its Meith/API requirements match. The board does not install packages automatically.
+
+Administrators receive `marketplace.update_available` once per key/version. An atomic claim prevents duplicate notices. The claim precedes delivery, so a failed notification is not retried; the panel still shows the available update.
+
+## Fetch boundary
+
+The URL setting accepts HTTPS and loopback HTTP. It is administrator-trusted and can target internal addresses; it is not a public-URL security boundary.
+
+Fetches reject redirects and non-2xx responses, enforce the size cap while streaming and use a 10-second timeout. Retain these controls when changing the consumer.
 
 ## Delisting
 
-A listing is removed — its file deleted from `marketplace/listings/`, its
-screenshot from `marketplace/screenshots/`, `pnpm marketplace:gen` run
-again — when:
-
-- it stops meeting the review bar above, on a later look;
-- the package is unpublished, abandoned, or its repository is gone;
-- a maintainer is told about a real problem — a vulnerability, undisclosed
-  network calls, a licence that turns out not to be what the listing
-  claimed — and confirms it.
-
-Removal is silent to any board already running the package: it stops
-appearing in `/marketplace/v1.json` on the next publish, and nothing
-reaches out to a board that installed it while it was listed. A board
-that wants to know whether a plugin it runs is still listed has to check
-the feed itself.
-
-## What is seeded today
-
-Nine first-party listings: **Dues**, **Calendar**, **Awards** and the six themes
-described in [Development](board-workspaces.md#the-workspace) — default,
-midnight, phasebook, raidframe, clubhouse and meith. Their `version` and `licence` fields
-are read from each package's own `package.json`, and `pnpm release:check`
-enforces the `version` field directly: for every listing whose `package`
-names a workspace package, the listing's `version` must equal that
-package's manifest version, the same lockstep [the release
-process](release-infrastructure.md#one-version-everywhere) holds every other published
-package to. `pnpm release:bump` moves the listings and runs `pnpm
-marketplace:gen` in the same pass, so a release always lands with a feed
-that already matches them. A third-party listing's `package` does not
-resolve to a workspace package, so the check leaves it alone — it tracks
-its own release, as [above](../extensions/marketplace.md) explains.
-
-**Their screenshots are placeholders** — a small solid-colour PNG per
-listing, generated rather than captured, standing in until real marketing
-screenshots exist. Nothing about them claims to show the product; they
-exist so the feed's screenshot pipeline (validate, copy, publish) has real
-files to prove itself against. Replacing one is the same pull request as
-any other listing update: a new PNG in `marketplace/screenshots/`, the
-filename changed in the listing, `pnpm marketplace:gen`.
+Remove the listing and its unused screenshots, then regenerate the feed. Delist confirmed unsafe, unlicensed, unavailable or unmaintained packages according to review findings.
+
+Delisting removes the public listing and feed entry. It does not uninstall or notify boards already running the package.
+
+## First-party listings
+
+Listings for workspace packages must match their manifest versions. `pnpm release:check` enforces this, and `pnpm release:bump` updates the feed. Third-party versions follow their own package releases.
+
+Replace screenshots in the source directory and regenerate. Do not edit public output directly. Use [Testing](testing.md#screenshots) for captures; inspect the actual image before treating it as a current product screenshot.
diff --git a/docs/contributing/nextjs-conventions.md b/docs/contributing/nextjs-conventions.md
index e2ce24e04..8115f1aa7 100644
--- a/docs/contributing/nextjs-conventions.md
+++ b/docs/contributing/nextjs-conventions.md
@@ -1,27 +1,14 @@
-# Application conventions
+# Next.js conventions
 
-Use these conventions when changing `apps/community`. Read its `AGENTS.md` and the installed Next.js documentation before relying on framework behavior; this repository's version may differ from one you previously used.
+Read the installed Next.js documentation referenced by the app's `AGENTS.md` before changing framework code.
 
-## Keep the layers separate
+Use Server Components for pages and layouts. Add client components only for the interaction that requires them. Keep native links and forms usable without JavaScript.
 
-Route files adapt framework input. Domain packages implement business behavior. Database repositories perform durable queries. View-model builders prepare authorized, serializable data for themes.
+| Work | Rules |
+|---|---|
+| Mutations | [Forms and actions](forms-and-actions.md) |
+| Reads, caching and view models | [Rendering and data](rendering-and-data.md) |
+| Controls and feedback | [UI conventions](ui-conventions.md) |
+| Validation | [Testing](testing.md), [Repository checks](repository-checks.md) |
 
-Use Server Components by default. Introduce a client component for actual browser interaction and keep the boundary small. Do not move a whole data-rendering surface to the client to add one control.
-
-## Handle writes consistently
-
-Validate form inputs at the boundary, resolve the actor, authorize the operation, call the domain function and refresh affected state. A hidden control is not authorization. Errors returned to the user must be safe and actionable.
-
-Forms must keep their native submission path where the product supports JavaScript-disabled operation. Pending and inline feedback enhance that path. Follow [Forms and Server Actions](forms-and-actions.md) for exact patterns.
-
-## Build shared presentation
-
-Use theme slots and shared UI primitives instead of page-specific presentation contracts. The member, moderator and administrator panels use the common panel framing. Keep navigation, empty states and destructive confirmations consistent.
-
-[Rendering and data](rendering-and-data.md) covers model builders, caching, event-driven counters and logging. [UI conventions](ui-conventions.md) covers controls, accessibility and design-system review.
-
-## Validate the change
-
-Test the business rule at the domain layer and the relevant page/form behavior through the existing application or browser tests. Check the ordinary-member case, denied access, empty state and JavaScript-disabled flow where supported.
-
-Run the repository gates from [Development](development.md). Update the relevant guide and regenerate contracts when a change affects themes, plugins or the API.
+Test ordinary, empty and denied states. Test the native path before adding an enhancement.
diff --git a/docs/contributing/release-infrastructure.md b/docs/contributing/release-infrastructure.md
index 93116031d..8e1f9cf78 100644
--- a/docs/contributing/release-infrastructure.md
+++ b/docs/contributing/release-infrastructure.md
@@ -1,493 +1,52 @@
-# Release infrastructure and version policy
+# Release infrastructure
 
-Understand what a release publishes and how packages, images and templates stay in step. Use the release procedure for the ordered maintainer actions.
+## Artifacts
 
-## What a release publishes
-
-| Artifact | What it is |
+| Artifact | Policy |
 |---|---|
-| `ghcr.io/meith-dev/meith:X.Y.Z` | The board image — web, worker, migrator and operator CLI in one, for `linux/amd64` and `linux/arm64`. This tag never moves again, and it is the only tag anything deploys: the Coolify compose file pins it exactly. |
-| `ghcr.io/meith-dev/meith:X.Y` | The release line, floating over its patches. A convenience for trying the image; nothing this repository ships deploys a floating tag. |
-| `ghcr.io/meith-dev/meith:latest` | The newest release, whatever line it is on. Same status: for trying, never for deploying. |
-| `ghcr.io/meith-dev/meith-base:X.Y.Z` | The framework base image a scaffolded custom board's own Dockerfile starts `FROM` — the `@meith/web`/`@meith/cli`/`@meith/theme-default` dependency closure, version-locked to this release, no board config and no secret (`docker/Dockerfile.base`). No floating tag: a board pins it exactly, the same way it pins the npm packages. See [Deploying by hand § Building somewhere else](../operations/docker-compose.md). |
-| The `@meith` packages on npm | The board, the kits, the first-party themes and plugins, `create-meith`, and their dependency closures — every non-private workspace package, at the release version, with provenance. See [what publishes to npm](#what-publishes-to-npm). |
-| The `release` branch | Fast-forwarded to the tag. The Quickstart points Coolify at this branch, so a board deployed by the guide follows releases and never sees `main` mid-cycle. |
-| A GitHub Release | Drafted by the workflow with generated notes and a header the maintainer must finish. |
-
-No image tag except `X.Y` and `latest` is ever re-pushed. A release that turns
-out to be broken gets a new patch release — cheaper than every operator
-wondering which `v0.1.2` they have.
+| `ghcr.io/meith-dev/meith:X.Y.Z` | Immutable board image for amd64/arm64; web, worker, migrator and CLI |
+| `meith:X.Y`, `meith:latest` | Floating convenience tags; shipped deployments use exact versions |
+| `ghcr.io/meith-dev/meith-base:X.Y.Z` | Exact framework dependency image for custom boards |
+| Public workspace packages | Published to npm at the release version |
+| `release` branch | Fast-forwarded to the released tag |
+| GitHub release | Drafted automatically; maintainer completes and publishes |
+| Template repositories | Mirrored from committed generated trees and tagged |
 
-## The version policy
+Never re-push immutable version tags.
 
-Semantic versioning, with the boundaries drawn by **migrations** rather than
-API surface, because a schema change is the one thing an operator cannot
-shrug off:
+## The version policy
 
-| Bump | May contain | May migrate? |
+| Bump | Contents | Migrations |
 |---|---|---|
-| **Patch** | Fixes only | **Never.** |
-| **Minor** | Features, new settings, new migrations | Yes — additive by strong preference. |
-| **Major** | Removals, renames, destructive backfills | Yes, including the kind that needs a two-step deploy. |
+| Patch | Fixes | None |
+| Minor | Features and additive changes | Allowed; prefer additive |
+| Major | Removals, renames, destructive backfills | Allowed; document staged deployment if needed |
 
-The patch rule is a promise: it is what makes "take the patch now, without
-ceremony" always the right advice, however many patches a board is behind. A
-fix that needs a migration is a minor release, whatever its size. (This is
-maintainer policy — no gate compares a version bump against the migrations
-directory — so it is a promise to keep, not a check to lean on.)
+A fix needing a migration requires a minor release. This is maintainer policy, not an automated migration/version comparison. Upgrades span at most two majors. Downgrades are refused; recovery uses a backup restore.
 
-Two other rules live in the code and bind releases:
+## One version, everywhere
 
-- **Upgrades span at most two majors** (`packages/upgrade`). Every major must
-  keep its migrations correct against schemas up to two majors back, and that
-  is the claim releases are tested against.
-- **Downgrades are refused.** There is no down migration; recovery is by
-  restore. Nothing in the release process may assume otherwise.
+All workspace manifests share the root version. `release:check` also validates source version constants, plugin manifests, first-party marketplace listings, the compose pin and the publishable dependency closure. Its `--tag` mode checks tag/tree agreement.
 
-## One version, everywhere
+Generated OpenAPI, installer, feed and template versions are checked by their generators. `pnpm release:bump` updates the version sources and generated output. Feature changes never move versions.
 
-The workspace releases in lockstep: the root `package.json` version is the
-release version, and every workspace manifest carries the same one. The
-packages are one tree at one commit — tested together, shipped together — and
-per-package versions would claim an independence none of them has.
+Images carry `MEITH_VERSION` and OCI metadata. Local builds default to `0.0.0-dev`.
 
-### Where the version is written
+## What publishes to npm
 
-Beyond the manifests, the version appears in places npm never reads. They
-divide into two kinds, and the difference decides how each is kept honest:
+Every workspace package without `private: true` publishes. Public dependencies, peers and optional dependencies must form a closed set: none can require a private workspace package.
 
-| Written in | What it is | Kept honest by |
-|---|---|---|
-| `apps/cli/src/upgrade.ts` (`CODE_VERSION`) | What `meith upgrade` records in the database | `release:check` |
-| `apps/community/src/server/upgrade-notice.ts` (`CODE_VERSION`) | What the admin panel compares the recorded version against | `release:check` |
-| `packages/create-meith/src/bin.ts` | The version written into a scaffolded project's dependencies | `release:check` |
-| `packages/marketplace/src/build-info.ts` (`MEITH_VERSION`) | This board's own version, checked against a listing's `meith` compatibility range | `release:check` |
-| Each first-party plugin's `definePlugin` manifest | What `/admin/plugins` shows — the only one of these an operator ever sees | `release:check`, over **every** directory under `plugins/` |
-| `docker/compose.coolify.yml` | The exact image tag the Coolify compose file pins | `release:check` |
-| `marketplace/listings/*.json` whose `package` names a workspace package | The first-party listings — see [the marketplace](../extensions/marketplace.md) | `release:check`, over **every** listing in the directory |
-| `docs/reference/openapi.json` | `info.version` of the generated API reference | `api:docs:check` |
-| `apps/web/public/create-board.sh` | The installer [the Quickstart](../operations/coolify.md) points operators at, so nobody needs Node.js on their own machine | `board-installer:gen:check` |
-| `templates/self-host` | The generated self-host deploy template (Coolify and Docker Compose) | `templates:gen:check` |
-| `templates/vercel` | The generated Vercel deploy template | `templates:gen:check` |
-| `apps/web/public/marketplace/v1.json` | The merged marketplace feed, a mirror of the listings above | `marketplace:gen:check` |
-
-The first group is compared textually by `pnpm release:check`. The second is
-*generated*, so a stale value is caught by the generator's own `--check`
-instead. `pnpm release:bump` moves the first group and re-runs every
-generator in the same command, so the release commit already carries fresh
-documents. Before that, a bump left them behind and CI failed on the release
-commit itself.
-
-**Nothing fails at runtime if these drift, but the drift is visible.** The
-plugin version once sat at `0.1.0` through two releases, so a board that had
-just upgraded cleanly displayed a plugin two releases old. It happened a
-second time — two plugins added after the check was written sat a release
-behind, because the check named its plugins in a hardcoded list and nobody
-extended it. So the plugin manifests and the marketplace listings are now
-**discovered** rather than listed: `release:check` walks `plugins/` and
-`marketplace/listings/` and covers whatever it finds, and a plugin whose
-version it cannot read is an error rather than a silent omission. Adding a
-plugin needs no edit here, which is the only version of this that stays true.
-
-`release:check` runs in `pnpm verify` and in CI, and the release workflow runs
-it with `--tag` so a tag that disagrees with its tree is refused before
-anything is built. Its final line is the count of everything it checked —
-that line, not this page, is the number to trust:
+`scripts/npm-publish.mjs` orders dependencies before dependents, skips existing versions and holds back packages whose dependencies cannot publish. It uses pnpm to pack and rewrite `workspace:` ranges, then npm for registry publication and trusted publishing.
 
-```
-✓ release coherence: 0.23.0 in the root manifest, 58 workspace manifests,
-  4 source constants, 4 plugin manifests, 8 first-party marketplace listings,
-  and the compose pin; 52 packages publish to npm and the set is closed
-```
+The dry run packs and checks every `files` entry and `bin` target without publishing. Build `create-meith` first so its bundled `dist/bin.mjs` exists. Other framework/theme/plugin packages ship TypeScript source compiled by the consuming board; keep their transpilation and Tailwind source discovery configured.
 
-The image additionally carries the version as `MEITH_VERSION` (an environment
-variable and OCI labels, stamped by the workflow). A local `docker build`
-leaves it at `0.0.0-dev`, and the entrypoint prints it at boot — so a
-container's log always says whether it came from a release or a checkout.
-
-### Why lockstep
-
-Every package publishes at the release version, including ones the release
-did not touch. That is a choice against per-package versioning, and the
-reason is what these packages are: none of them is independent software. The
-kits re-export the board's own contracts, the themes and plugins are compiled
-into the board's build, and CI only ever tests one combination — the tree at
-the tag. Lockstep makes the npm version state exactly what was tested:
-`@meith/theme-phasebook@0.1.4` is the theme as board 0.1.4 shipped it, and
-"board 0.1.4 with theme 0.1.2" is a mismatch anyone can see without a lookup
-table.
-
-The cost is that a version bump does not mean the package changed; the release
-notes carry that information, as they do for every lockstep monorepo on npm
-(Angular, Jest, the AWS SDK). A plugin's *schema* has its own version besides
-— the one in its `definePlugin` manifest, which migrations are recorded
-against — so "did this plugin's data model change" is already answered by a
-number that only moves when it did.
-
-The decision gets revisited the day something genuinely standalone joins the
-set. Going from lockstep to independent later is versions diverging from a
-shared point; the reverse is a renumbering nobody downstream enjoys, which is
-why lockstep is the right place to start.
+Generated boards pin engine packages exactly. `create-meith update` changes those pins explicitly. Extension API compatibility is separate from the package release version.
 
-## What publishes to npm
+## Registry authentication
 
-**Every workspace package that is not `private: true`**, on every release, at
-the release version. That is the whole rule — there is no allowlist to keep
-in step, and `release:check`'s closing line counts them (52 at 0.23.0).
+Each existing npm package configures GitHub Actions trusted publishing for organisation `meith-dev`, repository `meith`, workflow `release.yml`. Renaming that workflow requires updating every publisher configuration.
 
-| | What is in it |
-|---|---|
-| The board | `@meith/web`, `@meith/cli` — the Next.js app and the operator CLI. Each carries a bin (`forum-web`, `meith`) that materializes its sources into an external workspace and points the [board-config seam](architecture.md) at that workspace's own files — see [Consuming the board from a workspace](board-workspaces.md#consuming-the-board-from-a-workspace). Without these two on npm, `create-meith`'s scaffold would depend on a package that does not exist. |
-| The kits | `@meith/plugin-kit`, `@meith/theme-kit` — what a plugin or theme author writes against. |
-| The board's dependency closure | Every domain and infrastructure package under `packages/` that `@meith/web` or `@meith/cli` names in its own `dependencies`, transitively — `@meith/accounts` through `@meith/upgrade`. None is independently useful; each is here only because the board, or a theme in its closure, imports it. |
-| The themes | The five bundled themes: `default`, `midnight`, `phasebook`, `raidframe`, `clubhouse`; and `meith`, which publishes for meith.dev's own forum to install like any third-party theme. |
-| The plugins | The first-party plugins: `dues`, `reference`, `calendar`. |
-| The initializer | `create-meith` — `npx create-meith` scaffolds a board whose `package.json` depends on `@meith/web`, `@meith/cli` and `@meith/theme-default`. An npx-able initializer that is not itself on npm does not exist. |
-
-To ask whether a given package publishes, read its manifest: `private: true`
-or not. To list them, `pnpm release:check` counts them and
-`scripts/npm-publish.mjs --dry-run` names every one it would pack.
-
-### What stays private, and why
-
-- **`@meith/worker`** (`apps/worker`) — no [board-config seam](architecture.md)
-  import anywhere in its source, so it needs no per-installation
-  customization the way the web app and CLI do, and `create-meith`'s scaffold
-  does not depend on it. Something has to run the tick every minute (the
-  worker process, or `meith task:run`), but nothing about running it
-  requires `@meith/worker` on the registry. Giving it a bin for a scaffolded
-  workspace, the way `forum-web` and `meith` have one, is orthogonal
-  follow-up work.
-- **`@meith/site`** (`apps/web`) — meith.dev itself. The project's own
-  marketing site, not part of what an operator installs.
-- **`@meith/board-stock`** (`boards/stock`) — the workspace `docker/Dockerfile`
-  builds the official image from (see [the stock board](architecture.md)).
-  It is a board, not a library, so it stays private the same way
-  `apps/community` does; the version lockstep still applies to it, like every
-  workspace manifest.
-- **`@meith/testkit`** — it drags `@meith/db` and `@meith/drivers` behind it,
-  and that closure is most of the board.
-- **The examples** — `hello-plugin` and `iris-theme` are documentation. They
-  are copied, not installed, and their `definePlugin` versions are deliberately
-  their own rather than the release's.
-
-### How packages are packed and published
-
-`scripts/npm-publish.mjs` is the mechanism. Dependencies before dependents —
-a `dependencies`, `peerDependencies` or `optionalDependencies` edge, so a
-workspace-internal peer (the pattern themes and plugins already use for react)
-orders and holds back exactly like a plain dependency would. A version already
-on the registry is skipped rather than failed.
-
-Each package is packed by `pnpm` — which rewrites the `workspace:` ranges into
-real ones — and published by the `npm` CLI, which is what implements trusted
-publishing.
-
-**Every tarball is checked against its own manifest before anything is
-published**: every non-excluded entry in `files` must have put something in
-the tarball, and every `bin` target must be a real file in it. That is what
-catches the failure mode a bare version bump cannot — a `files` allowlist that
-still names a directory nothing is written into any more. Under `@meith/web`,
-`app/` and `public/` are the two worth being paranoid about: nothing exercises
-either externally except a board actually built from the published tarball,
-and a `public/` left out of the allowlist costs web push its service worker
-without failing anything inside this repository.
-
-`--dry-run` stops at the packing and the tarball check; it never reaches the
-registry. That is what makes it a gate a pull request can run at all — the
-tree between releases carries a version that is already published, so asking
-`npm publish --dry-run` about it would be told, correctly, that the version
-cannot be published over, on every package, every time. Nothing is lost by
-stopping earlier, because the failure this catches is a local disagreement
-between a manifest and the tarball its own `files` allowlist produces.
-
-CI's `static` job runs the dry run on every push and pull request
-(`.github/workflows/ci.yml`), building `create-meith`'s `dist` first —
-release.yml's `npm` job orders the same two steps the same way, since the dry
-run packs `create-meith` from disk and only `pnpm build` writes its
-`dist/bin.mjs`. That is the only packing coverage for a package outside the
-`board-workspace` job's closure: a `files`-allowlist or `bin`-path rot in, say,
-a theme or a domain package now fails on the pull request that caused it,
-rather than mid-release after both architecture image builds have already
-pushed tags.
-
-### The set is closed, and closing it is the cost of publishing
-
-A published package may not depend on a private one — that would be an `npm
-install` that resolves for nobody. `release-check` enforces the closure across
-`dependencies`, `peerDependencies` and `optionalDependencies` alike, so a
-workspace-internal peer is exactly as disqualifying as a plain dependency:
-publishing a package means deleting its `private: true`, and the check then
-names everything that decision drags with it. That is how `@meith/core` and
-`@meith/ui` entered the set — the kits and themes stand on them — and it is
-the friction that keeps the set deliberate.
-
-Dependency ranges between published packages are `workspace:^`, so a published
-manifest says `^X.Y.Z` — the release line again. A plugin published at 0.1.0
-accepts every 0.1 patch of the kits and refuses 0.2, the same compatibility
-promise the image tags make.
-
-### The npm surface is a compatibility commitment
-
-Publishing `@meith/web` and `@meith/cli` makes "install this version of the
-board, alongside this version of a theme or plugin" a real question with a
-real answer — until they were published, that pairing only ever existed inside
-this monorepo, at one commit. It is governed by the same policy that already
-backs `apiVersion` for themes and plugins
-([theme API versioning](../extensions/theme-contract.md#versioning),
-[plugin API versioning](../extensions/plugin-hooks-guide.md#versioning)): a minor may
-add capability, only a major may remove or rename it, and a package built
-against one major keeps working against every release on that major.
-
-`@meith/web`, `@meith/cli` and `@meith/theme-default` are not exempt from [the
-version policy](#the-version-policy) just because they are new to npm. A
-scaffolded board pins all three to an exact version rather than a range,
-deliberately: `create-meith`'s scaffold upgrades by `npx create-meith@latest
-update` — under the hood `npm install --save-exact @meith/web@latest
-@meith/cli@latest @meith/theme-default@latest`, plus the deploy-file rewrite —
-an explicit act, or an explicitly merged pull request from the scaffold's
-update workflow, never a silent range resolution on a board process holding
-a database migration. The scaffolded `.npmrc` sets `save-exact=true` so the same holds
-for an install run by hand, and the generated `build.yml` refuses to build
-from anything but an exact version regardless.
-
-A theme or plugin's `workspace:^` on the kits is the same policy stated as a
-version range instead. Same guarantee, different mechanism for the different
-risk: a board upgrade runs migrations, a theme or plugin upgrade does not.
-
-### They ship TypeScript source, deliberately
-
-A theme or plugin is only ever consumed inside a board's Next build, and that
-build compiles these packages **from source** wherever they come from — the
-workspace today (`transpilePackages` in the board's Next config, Tailwind's
-`@source` scan for class names), npm tomorrow. So the published tarball is the
-`src/` directory the monorepo tests, byte for byte, minus the test files.
-There is no dist step, which means there is no way for the published artifact
-to drift from what CI exercised.
-
-Two consequences bind whoever wires an npm-installed package into a board
-build — the same two the monorepo already handles for the first-party set:
-
-- the package's name must be in the board's `transpilePackages` — a workspace
-  package is compiled because it lives outside `node_modules`; an npm one is
-  not;
-- a theme or plugin needs a Tailwind `@source` entry for its `node_modules`
-  path, or its class names are silently dropped from the stylesheet and its
-  pages render unstyled with no error anywhere.
-
-The one package this does not describe is `create-meith`: its published `bin`
-runs under plain `node`, invoked by `npx` — never inside a board's Next build,
-so there is no bundler on the other end to compile it from source. Node's own
-native TypeScript support refuses to strip types for a file under
-`node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), which is where
-npm always installs a package before running its bin — so a `bin` entry
-pointing at raw `.ts` fails for every real `npx create-meith`, even though it
-runs fine from this repository's own tsx-driven tooling, where the failure
-would never surface. `create-meith`'s own `pnpm build` (esbuild, bundling
-`src/bin.ts` to `dist/bin.mjs`) is the one dist step in the published set, and
-the release workflow's `npm` job runs it immediately before
-`node scripts/npm-publish.mjs`.
-
-### How the workflow authenticates
-
-**Trusted publishing, not a token.** Each package on npmjs.com names this
-repository and the `release.yml` workflow as its trusted publisher. When the
-release workflow runs, npm exchanges the job's OIDC identity for a short-lived
-credential scoped to that publish, and provenance is generated automatically.
-There is no long-lived secret to leak, rotate, or scope too widely — a package
-can only be published by this repository's release workflow, and npmjs.com
-shows exactly that on the package page.
-
-Two consequences worth knowing:
-
-- **Configuration lives on npmjs.com, per package**: package → Settings →
-  Trusted Publisher → GitHub Actions, with the organisation (`meith-dev`),
-  repository (`meith`) and workflow filename (`release.yml`). Renaming the
-  workflow file breaks publishing until every one of those configurations is
-  updated; the failure is a clear authentication error at the npm job.
-- **A brand-new package cannot first-publish this way**, because trusted
-  publishing attaches to a package that already exists. The release does not
-  attempt it: a name the registry has never seen is skipped with a notice, and
-  the rest of the release goes out.
-
-## Deploy template repositories
-
-Two deploy routes start from a repository the operator clones rather than from
-this one: **[meith-dev/template](https://github.com/meith-dev/template)** is the
-"Use this template" repository behind the self-host Quickstart (Coolify and
-Docker Compose both), and
-**[meith-dev/vercel-template](https://github.com/meith-dev/vercel-template)** is
-what the Vercel Deploy Button clones. Their contents are *generated*, not
-hand-written: `templates/self-host/` and `templates/vercel/` here are the source
-of truth, regenerated by `pnpm release:bump` through `pnpm templates:gen`
-from `create-meith`'s `scaffold()`. Between releases the committed trees stay
-unchanged even when the scaffold or its dependencies change. The release
-workflow runs `pnpm templates:gen:check` before publishing npm packages;
-normal CI tests the generator and the released template structure without
-requiring those trees to match an unreleased scaffold.
-
-The `publish-templates` job in `release.yml` mirrors each committed tree into
-its repository on every release: it clones the repository, makes its tracked
-tree match `templates/<target>/` exactly — adding, updating and **deleting** so
-the two agree file for file — commits `chore(release): sync template to vX.Y.Z`
-when anything changed, and tags the repository `vX.Y.Z`. It runs after
-`publish`, so a release that did not ship never pushes a template, and it is
-idempotent: a re-run with nothing to change makes no commit.
-
-Those `vX.Y.Z` tags are more than provenance. `npx create-meith@latest
-update` fetches the tag of the version a board is *on* to tell the
-operator's edits from files the scaffold wrote — a file still matching that
-tree is the scaffold's to rewrite, one that differs is the operator's to
-keep ([Upgrading § Upgrading each deployment route](../operations/upgrading.md)).
-A release whose template sync did not run leaves the *next* update degraded:
-`package.json` still moves, but every other file is handed back to the
-operator to review. One more reason the App secrets belong in place before
-the first release that should propagate templates. The repository names are
-one constant, `TEMPLATE_REPOSITORIES` in `packages/create-meith/src/update.ts`,
-which both the mirror and the updater read — they cannot disagree about
-where a template lives.
-
-The tracked content of each repository is **owned entirely** by its
-`templates/<target>/` source — anything the source does not contain, the mirror
-removes. A file a repository needs, such as a `LICENSE`, belongs in the scaffold
-so the source carries it, never added to the repository by hand. `pnpm
-templates:sync:check` verifies in CI that the repositories still match the
-generated trees, so drift is a red build rather than a stale board a new adopter
-clones.
-
-**The push credential.** `GITHUB_TOKEN` grants write to this repository only, so
-the cross-repository push authenticates as a **GitHub App** — chosen because,
-unlike a personal access token, it does not expire and so needs no scheduled
-rotation. Create an organisation-owned App with the **Contents: read and write**
-and **Workflows: read and write** repository permissions — the mirror includes
-`.github/workflows/build.yml`, and GitHub rejects an App push that creates or
-updates any file under `.github/workflows/` without the Workflows permission, so
-`Contents` alone syncs every file until a workflow one changes and then fails the
-whole push. Install it on `meith-dev/template` and
-`meith-dev/vercel-template` (approving the Workflows permission on the
-installation if you add it later), and store its **App ID** and a generated
-**private key** as the Actions secrets `TEMPLATE_SYNC_APP_ID` and
-`TEMPLATE_SYNC_APP_PRIVATE_KEY` here. The `publish-templates` job mints a
-short-lived installation token from them on each run
-(`actions/create-github-app-token`, scoped to just those two repositories) and
-hands it to `templates:sync` as `TEMPLATE_SYNC_TOKEN`; the only stored secret is
-the key, and nothing expires on a clock. Without the App configured the job logs
-a warning and does nothing, so releases still succeed — add the two secrets
-before the first release that should propagate templates. The repositories are
-created once, up front, with `meith-dev/template` marked as a *template
-repository* in its settings so the "Use this template" button appears.
-
-## How each route consumes a release
-
-| Route | What it tracks | How an upgrade arrives |
-|---|---|---|
-| [Quickstart](../operations/coolify.md) (Coolify) | The `release` branch; the compose pin on the exact version, held per resource by `MEITH_IMAGE` | Every release moves the pin, so an upgrade is a **Redeploy** after the branch moves — or automatic, with the webhook on. Never from a push to `main`. Coolify's **Restart** re-runs the deployment from the branch head, so unpinned it upgrades too — the Quickstart has the operator pin `MEITH_IMAGE` so it cannot. |
-| A scaffolded, template or [by-hand](../operations/docker-compose.md) board ([Upgrading](../operations/upgrading.md)) | Its own `package.json`, pinned exact | Its `.github/workflows/update.yml` opens a pull request on its weekly run — or `npx create-meith@latest update` by hand, then `docker compose up -d --build` (or a Coolify Redeploy) to actually deploy it. Either moves the pins and the scaffold-owned deploy files together; the backup and `meith upgrade` stay the operator's. |
-| meith.dev | `main` | The project website redeploys on push, ahead of a release. |
-| [forum.meith.dev](https://forum.meith.dev) | Its own template repository, with exact package pins | The live community follows the template-board upgrade route. |
-
-### Deploys are deterministic, and that is load-bearing
-
-The compose file names an exact, immutable version. No deploy path resolves
-"the newest anything": a version change always has a commit on the `release`
-branch behind it, which is what makes "what is this board running, and since
-when" answerable from git history. It also keeps a bad release contained — a
-board that has not deployed the new pin is not running it.
-
-The determinism is per *commit*, though, not by itself per resource: Coolify
-re-reads the compose file from the branch head on every deploy action, and on
-a compose resource that includes the panel's **Restart** button, which re-runs
-the deployment rather than restarting containers. A crash or a reboot
-re-creates the running version; a button in the panel deploys whatever release
-the branch has moved to. What makes a *resource* deterministic is
-`MEITH_IMAGE` in its environment: it overrides the file's default, so Restart
-and Redeploy re-create exactly that version — which is why the Quickstart
-tells the operator to set it, and why holding back from a release is simply
-not moving it yet. The same variable serves the operator who wants a stronger
-pin than a tag: a digest, immune even to a re-pushed tag.
-
-The same reasoning runs through the rest of the pipeline. The base images —
-`node`, `postgres`, `valkey`, `alpine`, `curl` — are pinned by digest in the
-Dockerfiles and compose files, not by tag alone, and every action in the
-workflows is pinned to a full commit SHA with the version tag kept as a
-comment: the workflows hold publish rights, and a re-tagged action is code
-they would run. Dependabot moves all of these pins on the same weekly schedule
-as the npm dependencies, so the pinning costs review, not staleness.
-
-That last clause is what bounds where a pin belongs. The `docker` and
-`docker-compose` ecosystems in `.github/dependabot.yml` are scoped to
-`docker/`, so a digest written by hand anywhere else is a digest nothing ever
-moves — pinning costing staleness rather than review, which is the trade this
-section exists to avoid. Where something outside `docker/` needs one of these
-images, it therefore *reads* the pinned value instead of repeating it:
-`scripts/board-eject-smoke.mts` takes the `psql` client it shells out to from
-`docker/compose.yml`'s `postgres` service, through `pinnedComposeImage`
-(`scripts/compose-images.mts`), so the smoke runs a digest and still follows
-the weekly bump without carrying a second copy of it.
-
-The throwaway Postgres that GitHub Actions starts as a job's `services:`
-container is the deliberate exception, and stays on the bare
-`postgres:18-alpine` tag. It is created empty for one job and discarded with
-it, nothing it holds outlives the run, and no Dependabot ecosystem reads a
-workflow's `services:` block — so a digest there would rot in place while
-buying nothing. A bare tag in a `services:` block is a decision, not an
-oversight; a bare tag in a Dockerfile, a compose file, or a script that reads
-one is the bug.
-
-## One-time setup
-
-### The deploy key the cut workflow pushes with
-
-The cut workflow pushes straight to `main`, and a ruleset requiring pull
-requests blocks that (`GH013`, at the push step, before anything is tagged).
-Rulesets cannot grant bypass to the built-in Actions app, so the workflow
-pushes over SSH with a **deploy key** instead, which rulesets *can* bypass.
-The key solves a second problem at the same time: a tag pushed with
-`GITHUB_TOKEN` triggers no workflows (GitHub's recursion guard), while a
-deploy-key push starts the Release workflow the ordinary way.
-
-1. `ssh-keygen -t ed25519 -f meith-release -N ""` — anywhere; delete both
-   files once the two halves are stored.
-2. **Settings → Deploy keys → Add deploy key**: the public half
-   (`meith-release.pub`), with **Allow write access** ticked.
-3. **Settings → Secrets and variables → Actions → New repository secret**:
-   `RELEASE_DEPLOY_KEY`, the private half (the whole file, header and footer
-   included).
-4. **Settings → Rules → Rulesets → the rule on `main` → Bypass list → add
-   "Deploy keys"**.
-
-The protection keeps applying to people and to every app; the one thing
-allowed through is a key that exists only as this repository's secret, used
-only by this workflow, revocable in one click. The workflow is safe to re-run
-after a failure at any step: a tree already bumped, a commit already pushed,
-or a tag already made is skipped rather than refused.
-
-### The first release
-
-One-time steps around `v0.1.0`, in order:
-
-1. Tag and push; the workflow publishes the image and creates the `release`
-   branch by pushing it.
-2. **Make the GHCR package public.** The first push creates
-   `ghcr.io/meith-dev/meith` private, and a private package is a quickstart
-   that fails at `docker pull` with an authentication error no operator can
-   act on. Package settings → change visibility → public.
-3. **Create the npm organisation, and publish each package by hand once.** The
-   `meith` organisation owns the `@meith` scope, and a package's very first
-   publish is made from a maintainer's own machine — the workflow cannot make
-   one. [A package's first publish](#a-packages-first-publish) is the
-   procedure; from then on the workflow authenticates with trusted publishing
-   and no token exists to leak.
-4. Protect the `release` branch from manual pushes, so the workflow's
-   fast-forward is the only thing that moves it.
-
-### A package's first publish
-
-npm has no way to name a trusted publisher for a package that does not exist
-yet ([npm/cli#8544](https://github.com/npm/cli/issues/8544) is the open
-request), so a first publish comes from a person, once, and every release
-after it is ordinary OIDC. The shape of it — substitute the directory and
-name:
+First publication is a maintainer operation. Substitute the package directory/name:
 
 ```sh
 npm login
@@ -498,24 +57,42 @@ npm trust github @meith/theme-clubhouse \
   --repo meith-dev/meith --file release.yml --allow-publish
 ```
 
-Each line is load-bearing:
-
-- **`npm login`, not a token.** Creating a package is exactly the act that
-  should carry 2FA, and a CI token cannot answer a 2FA prompt — the only token
-  that publishes unattended is one marked *bypass 2FA*, which is a long-lived
-  secret with the run of the whole scope, the thing this arrangement exists to
-  avoid.
-- **`pnpm pack`, not `npm publish .`.** pnpm rewrites the `workspace:` ranges
-  into real ones. A manifest published with `workspace:^` still in it is an
-  `npm install` that resolves for nobody.
-- **`npm trust`** configures the trusted publisher from the terminal — the
-  same thing as the package's settings page on npmjs.com. It needs npm 12 or
-  newer. Without it the package publishes this once and then fails every
-  release after, at authentication.
-
-Do this **before** tagging and the release publishes the package like any
-other. Do it after and the package is one release behind — re-running the
-Release workflow against the tag catches it up, since a run publishes whatever
-is missing and skips whatever is already there. A package that *depends* on a
-skipped one is held back too, and the job says so; publishing the new package
-by hand and re-running the workflow clears both together.
+Use pnpm to pack so `workspace:` ranges become registry ranges. npm handles login, publication and trusted-publisher setup. Use a current npm release for [`npm trust`](https://docs.npmjs.com/cli/v11/commands/npm-trust/). The package settings page is an alternative for configuring trust.
+
+Complete first publication before tagging. If done afterward, rerun the release workflow to publish missing packages and their dependents.
+
+## Deploy templates
+
+`templates/self-host` and `templates/vercel` are generated from `create-meith` during a release. They mirror to `meith-dev/template` and `meith-dev/vercel-template`. Normal feature CI checks generator behaviour without requiring released snapshots to match unreleased scaffold changes.
+
+The mirror owns the entire tracked destination tree, including deletions. Add required files to the scaffold, not directly to a template repository. Synchronisation is idempotent and tags each repository `vX.Y.Z`.
+
+The updater uses those tags to distinguish generated files from operator edits. Missing tags degrade updates to manual deploy-file review even when package versions can move.
+
+Create an organisation GitHub App with **Contents: read/write** and **Workflows: read/write**, installed on both template repositories. Store `TEMPLATE_SYNC_APP_ID` and `TEMPLATE_SYNC_APP_PRIVATE_KEY` in this repository. The job creates a scoped installation token and passes it as `TEMPLATE_SYNC_TOKEN`.
+
+Without these secrets, synchronisation warns and skips. Inspect that job rather than treating overall release success as proof that templates moved. Mark `meith-dev/template` as a template repository.
+
+## Deployment pins
+
+Stock deployments use exact image versions. Pin `MEITH_IMAGE` per resource so a hosting-panel restart/redeploy cannot silently follow a moved release branch. Custom boards track exact package pins and receive update pull requests or run the updater manually. meith.dev deploys from `main`.
+
+Docker base images use digests maintained by Dependabot under `docker/`. Scripts needing the same images read those pins through `pinnedComposeImage`. Workflow actions use full commit SHAs. Disposable PostgreSQL job-service containers use the bare version tag because that workflow block is outside the digest update mechanism.
+
+## Release push credentials
+
+The cut workflow needs a write-enabled deploy key to push through the `main` ruleset and trigger the tag workflow.
+
+1. Generate an SSH key with `ssh-keygen -t ed25519 -f meith-release -N ""`.
+2. Add its public half under **Settings → Deploy keys**, with write access.
+3. Store the private half as `RELEASE_DEPLOY_KEY` in Actions secrets.
+4. Add **Deploy keys** to the ruleset bypass list for `main`.
+5. Delete the local key files after storing both halves securely.
+
+A `GITHUB_TOKEN` tag push does not trigger the release workflow. Rerunning the cut workflow skips already-completed bump, commit and tag steps.
+
+## Initial registry setup
+
+Make the GHCR packages public after first publication so operators can pull them. Create the npm scope and publish each package once, then configure trusted publishing. Protect the `release` branch from manual pushes.
+
+Use [Release Meith](release.md) for the regular procedure.
diff --git a/docs/contributing/release.md b/docs/contributing/release.md
index eb08f8b27..477b7d4f0 100644
--- a/docs/contributing/release.md
+++ b/docs/contributing/release.md
@@ -1,30 +1,18 @@
 # Release Meith
 
-This procedure is for maintainers publishing Meith. Board operators should use [Upgrade Meith](../operations/upgrading.md). A release is an immutable `vX.Y.Z` tag on a passing commit of `main`.
+Maintainers publish an immutable `vX.Y.Z` tag from a passing commit of `main`. Operators should use [Upgrade Meith](../operations/upgrading.md).
 
-## Before releasing
+## Prepare
 
-Confirm `main` passes CI, choose the version according to the [version policy](release-infrastructure.md), and check any one-time publishing setup. Feature PRs do not change versions.
+Confirm CI passes. Choose a version using the [release policy](release-infrastructure.md#the-version-policy). Review migrations, compatibility and required operator actions. Configure first publication for any new npm packages before cutting the release.
 
-Review migrations, compatibility and operator action required by the release. Make sure new public packages have the registry setup described in [Release infrastructure](release-infrastructure.md).
+## Publish
 
-## Cut the release
+1. Run **Actions → Cut a release** with `X.Y.Z`, without `v`.
+2. Wait for the version bump, generation, validation, commit and tag.
+3. Check every Release workflow job, including images, npm packages, generated-board smoke tests and template synchronisation.
+4. Complete the draft GitHub release with migration requirements, deployment steps, behaviour changes and known limitations. Publish it.
 
-1. Run **Actions → Cut a release** with `major.minor.patch`, without the leading `v`.
-2. Wait for the workflow to bump versions, regenerate stamped output, validate, commit and push the tag.
-3. Wait for the Release workflow to build, boot-test and publish its artifacts.
-4. Inspect the draft GitHub release. Fill in the migration information and explain the action an operator must take, then publish it.
+Do not move an existing tag or overwrite an immutable image. Fix a broken release in a new version. For interrupted publication, investigate and rerun the supported workflow; it skips already-published versions.
 
-Do not move an existing tag. A failed publication should be investigated and resumed through the supported workflow, not repaired by making the same version refer to different source.
-
-## Check the published artifacts
-
-The workflow checks tag/tree agreement, builds and boots board images against PostgreSQL, publishes npm packages in dependency order, builds the base image from published packages, and smoke-tests a generated board from the real registry. It also updates the release branch and drafts release notes.
-
-Inspect every job result. A new package skipped because it has not had its first registry publish can prevent downstream artifacts from being usable even when earlier jobs succeeded.
-
-## Write useful release notes
-
-State whether migrations run, which deployment or extension steps are required, and any behavior or default changes users will notice. Include known limitations and recovery implications. Link to [Upgrade Meith](../operations/upgrading.md) for the standard procedure instead of repeating it.
-
-The detailed package, authentication, image and template rules are in [Release infrastructure](release-infrastructure.md).
+A skipped first npm publication can block dependent packages and downstream artifacts. See [Release infrastructure](release-infrastructure.md).
diff --git a/docs/contributing/rendering-and-data.md b/docs/contributing/rendering-and-data.md
index 9885ed874..37e3245a8 100644
--- a/docs/contributing/rendering-and-data.md
+++ b/docs/contributing/rendering-and-data.md
@@ -1,301 +1,47 @@
-# Rendering, caching and view models
+# Rendering and data
 
-Keep data access, cache invalidation and theme view models consistent across pages and actions. Use this reference when a change crosses the request-to-presentation boundary.
+## Server rendering
 
-## Server Components by default
+Pages and layouts are Server Components. Use small client islands for interaction; framework error boundaries are client components. Pass serialisable props, with rendered React regions where the slot contract permits them.
 
-`"use client"` goes on **leaf interactive components only** — never a page,
-never a layout.
+The server prepares error-notice markup through the theme slot. `CrashNoticeProvider` supplies it to the client boundary, with a null fallback when unavailable. A request ID captured in the layout can reflect the initial request after client navigation.
 
-The rule exists because of one number: a guest thread page must ship
-near-zero JavaScript. Marking `PostBit` as a client component would send
-the entire post list to the browser and give away the product's main
-advantage. `theme-kit` declares a server/client kind per slot, and the
-build fails if a theme crosses it.
-
-In practice the split looks like the auth forms:
-
-- `src/components/auth/login-form.tsx` — `"use client"`, because it calls
-  `useActionState`.
-- `app/(auth)/login/page.tsx` — a Server Component that resolves
-  `searchParams` and renders the form.
-
-The page stays a Server Component even though its child is not. That is the
-shape to copy.
-
-The one file under `app/` that carries `"use client"` is `app/error.tsx`,
-and that is the framework's requirement rather than a judgement call: an
-error boundary has to be a client component to catch anything. It is
-neither a page nor a layout, so it is not the exception it looks like —
-but it is the only `"use client"` in the whole of `app/`, and a second one
-wants explaining.
-
-**Anything crossing into a client component must be plain serialisable
-data.** No class instances, no `Date` inside a nested object you have not
-checked, no functions other than Server Actions. Already-rendered markup is
-the exception the framework itself makes: a `ReactNode` produced by a
-Server Component travels as a prop, which is what lets a client boundary
-show server-rendered output it could never have built.
-
-### The error page renders through the theme
-
-`app/error.tsx` is a client component and therefore cannot resolve a theme:
-no `cookies()`, no `await`, no slot lookup. It gets the themed markup handed
-to it instead.
-
-`renderErrorNotice()` in `src/server/error-notice.tsx` resolves the active
-theme's `ErrorNotice` slot, runs the model through `view.error-notice`, and
-returns the rendered node. `not-found.tsx` calls it directly, because a
-Server Component can. The crash page cannot, so the root layout calls
-`crashNotice()` — the same work with the crash copy, swallowing a failure
-instead of throwing — and wraps the tree in `CrashNoticeProvider`, which
-sits above the error boundary. When the boundary catches, it reads markup a
-Server Component already produced and puts it on the page. Two error pages,
-one slot, same copy path.
-
-Three things follow:
-
-- **The notice is prepared on every request**, because by the time the
-  boundary runs, the request that needs it has already failed. The cost is
-  one slot render and one filter pass over a plain model — `ErrorNotice` is
-  specified to need no database read of its own, which is what keeps paying
-  it on every page affordable.
-- **A theme that cannot render its own error does not take the page with
-  it.** `crashNotice()` returns `null` rather than throwing, and
-  `CrashNotice` falls back to a plain bordered notice carrying the same copy
-  and the same request id. A crash page that crashes is worse than a plain
-  one.
-- **The request id belongs to the render that prepared the notice.** On a
-  full page load that is the request that failed. After a client-side
-  navigation the layout is not re-rendered, so the id is the one from the
-  load that put the frame there.
-
-The crash page has no "try again" button. Recovery is a client-only
-affordance, the slot is what the theme owns, and a themed page with one
-unthemed control on it is the problem this arrangement exists to solve.
-
----
-
-## Logging
-
-`logger()` is called **where you log**, never bound at module scope:
-
-```ts
-// Wrong — guarded by `no-module-scope-logger`.
-const log = logger({ module: 'x' })
-
-// Right.
-logger({ module: 'x' }).warn({ err }, 'something')
-```
-
-A module-level instance captures the request context once at import time
-(that is, empty), so every line loses its `requestId` — and it builds pino
-eagerly, which reads `env` and turns importing the module into an
-environment validation. That broke `next build` once.
-
-Never log a password, a token, or a full IP at default level. Pino's
-redaction covers `token`-shaped keys but **not** a token interpolated into
-a URL string, which is how one escaped.
-
----
+Call `logger()` where the event occurs, not at module scope. Module-level loggers lose request context and can trigger environment validation during imports. Never log passwords, tokens or full IP addresses at the default level. Redaction of structured keys does not redact a token embedded in a URL string.
 
 ## Caching
 
-Read `packages/core/src/cache.ts` before caching anything.
-
-- **Every tag name is spelled once**, in `CacheTags` — guarded by
-  `no-literal-cache-tag`. Never write a tag as a literal: a writer
-  invalidating `"forum-tree"` while a reader cached under `"forumTree"` is
-  stale data no test catches, because both sides pass in isolation and only
-  disagree in production.
-- **`cachedGlobal` is for global data only.** If a value varies by actor it
-  must not go through it.
+Use `CacheTags` from `packages/core/src/cache.ts`; do not invent literal tags at call sites.
 
-  > [!CAUTION]
-  > A cached permission-filtered page is how private forums leak. This is
-  > the reason the caching harness exists at all.
+- `cachedGlobal` is for actor-independent data only. Caching a permission-filtered result globally can expose private content.
+- Cached regions must not read cookies, headers or actor/user helpers.
+- Invalidate after a successful write. Invalidating before it can cache the old value again.
 
-- **Invalidate after the write, never before.** Clearing first opens a
-  window where a concurrent read repopulates from the pre-write state and
-  nothing clears it again. `CachedForumRepository` pins this ordering with
-  a test.
-- A cached region may not read `cookies()`, `headers()`, `getActor()` or
-  `getUserId()` — guarded by `no-request-state-in-cache`.
+## Counters and events
 
----
+Write counters and content in the same transaction. Emit outbox events in that transaction too. Every counter needs a bounded, resumable recount path.
 
-## Counters and event handlers
-
-A denormalised counter has three obligations, and a change that adds one
-has to satisfy all three — the thread and forum counters are the worked
-example:
-
-- **Write it in the transaction that writes the content.** Counters and
-  the row they describe move together or not at all.
-  `applyCreatedContentCounters()` takes the caller's transaction handle for
-  exactly this reason — it has no ambient database handle to reach for.
-- **Emit the event in the same transaction.** Anything that cannot be
-  afforded inside the request — an ancestor walk, a fan-out — goes through
-  the outbox, so a rolled-back write emits nothing.
-- **Give it a recount.** Incremental maintenance drifts. Every counter
-  needs a path back to a computed truth, batched and resumable
-  (`PostgresCounterRecount`). A counter with no recount is a number that is
-  wrong forever after one crash.
-
-Event handlers live in `packages/runtime/src/event-handlers.ts` and are
-built per container, never registered onto a module-level singleton —
-registration throws on a duplicate id, and a dev server re-evaluating the
-module would hit that on its second pass.
-
-**Handlers are idempotent, without exception.** The relay marks an outbox
-row dispatched after the enqueue returns, and the queue re-runs a job whose
-worker died mid-handler, so every handler is delivered at least once and
-sometimes twice. A handler that writes a *computed* value gets idempotency
-for free; one that applies a **delta** must record what it has applied —
-the counter roll-up ledger is the pattern to copy.
-
----
+Build event handlers per runtime container in `packages/runtime/src/event-handlers.ts`; do not register them on a module singleton. Delivery can repeat after a crash. Computed replacements must be safe to repeat; delta updates need an applied-event ledger.
 
 ## Theme slots
 
-Read `packages/theme-kit/src/slots.ts` before adding a page.
-
-**Every slot declares `server` or `client`, and there are two client
-slots.** Both are editor islands. Adding a third means editing the test
-that pins the set (`slots.test.ts`) — deliberate friction, because a client
-slot is bytes shipped to every viewer of the page it appears on.
-
-`pnpm slots:check` fails the build if a server slot's module starts with
-`"use client"` — *and* if a client slot's module does not. The second
-direction matters: such an island renders once and never becomes
-interactive, which looks correct in a screenshot and does nothing when
-clicked. Neither client slot is filled by a shipped theme today, so that
-second direction is currently exercised by `pnpm slots:probe` against a
-synthetic theme; the first theme to fill one is the first to test it for
-real.
-
-**A slot never renders another slot** — guarded by
-`no-slot-rendering-slot`, which refuses `requireSlot` and `hasSlot` inside
-a slot module. The page resolves both and passes the rendered one in:
-
-```tsx
-const ThreadView = requireSlot(theme, 'ThreadView')
-const PostBit = requireSlot(theme, 'PostBit')
-
-<ThreadView
-  thread={vm.thread}
-  forum={vm.forum}
-  replyHref={vm.replyHref}
-  regions={{
-    posts: vm.posts.map((post) => <PostBit key={post.id} post={post} regions={{ actions: … }} />),
-    pagination: <Pagination {...vm.pagination} />,
-    quickReply: null,
-  }}
-/>
-```
+Resolve slots in the page or app shell, never inside another slot. Pass nested output through `regions`. Use literal slot maps with imported identifiers so static checks can inspect them.
 
-If `ThreadView` imported `PostBit` itself, a child theme overriding
-`PostBit` would be ignored inside the parent's `ThreadView`. One place
-resolves slots, so an override applies everywhere.
+Server slot modules must remain server modules. Client slot modules must declare `"use client"`; `QuickReply` and `EditorToolbar` are the client slots. Run `pnpm slots:check` and `pnpm slots:probe` when changing their wiring.
 
-**Write the slot map literally in the manifest**, one bare imported
-identifier per slot. A map built by spreading cannot be statically checked,
-and `slots:check` fails rather than skipping it.
-
-**A component in `src/components/` may resolve a slot; a slot may not.**
-The guard is about slot modules, not the app — `PanelPage`, `PanelShell`
-and `AuthPage` in `src/components/shell/` are app components that resolve
-one slot each and hand it their props, which is what lets forty admin
-screens render through a themed frame without forty `requireSlot` calls.
-What they must not do is resolve a *second* slot to nest inside the first:
-that is the page's job, through `regions`.
-
-**Where the reader is comes from the request, not the router.** The panel
-rail needs the current path to say which section is open, and reading it
-with `usePathname` would make the whole rail a client component. `proxy.ts`
-sets `x-forum-path` and `x-forum-query` on every request,
-`currentLocation()` puts them back together, and `buildPanelNavModel`
-resolves the flags before anything renders. The rail is correct in the
-first response and costs no JavaScript.
-
----
+Panel location comes from `x-forum-path`/`x-forum-query`, set by the proxy and read through `currentLocation()`. Build active navigation on the server rather than making the panel a client component.
 
 ## View models
 
-Every page has a typed view model in `src/view/`. Pages resolve params,
-build a view model, and hand it to components; they do not pass rows
-around.
-
-**View models are JSON-shaped**: no `Date`, no `Map`, no functions.
-`theme-kit` proves this at compile time for every slot model. The reason is
-not React — it is that a view model is also the REST API's payload, and
-that a `Date` pushes formatting into every theme, where it becomes a
-timezone-dependent hydration mismatch. A timestamp crosses as `TimeModel`
-(`iso` plus a preformatted `label`); paging crosses as resolved hrefs,
-never a function that builds them.
-
-### Paging: one builder, and one page parameter
-
-Every paged list — the members list, the logs, the queues, the inbox, a
-forum's threads, a thread's posts, a search — pages by number. The page is
-`?page=N`, the rows come from `limit … offset`, and the pager is built by
-`buildOffsetPager` in `src/view/pager.ts` and handed to the `Pagination`
-slot. Pages do not hand-roll a "Next" link; that is how the board once
-ended up with eight of them, each with its own idea of which query
-parameters survive a page turn.
-
-Two helpers keep the arithmetic in one place: `readPage` reads the
-parameter and treats anything that is not a page (a zero, a negative, a
-word) as page one, and `offsetOf(page, size)` is what the repository is
-given. **The offset never comes from the URL** — only the page number
-does, so no address can ask a repository to skip an arbitrary number of
-rows.
-
-Every list's repository therefore answers two questions, and the count is
-of *the filter*, not of the table:
-
-```ts
-const [rows, total] = await Promise.all([
-  repository.list({ ...filter, limit: PAGE, offset: offsetOf(page, PAGE) }),
-  repository.count(filter),
-])
-```
-
-Some counts are already denormalised and need no query: a forum knows its
-`threadCount`, a thread its `replyCount`, and the queue and the report desk
-already count what is open for the badge in the rail. Use those rather
-than adding a second `count(*)` to a hot page.
+Define typed page models in `src/view/`. Use explicit public fields, never database rows. Models contain no dates, maps or functions. Supply timestamps as `TimeModel`, counts as `CountModel`, and links as resolved hrefs.
 
-**Keyset paging is still there, and is still the right answer for an
-API.** The cursors did not go away: `after` on a forum's thread listing, a
-thread's posts and the search results. The REST API pages with them,
-because a cursor cannot skip or repeat a row when the set changes
-underneath a client walking it. The screens page by number because a
-reader wants to jump to page 9 and hand somebody the address, and because
-"of 12" is a fact a reader can act on. `pageCountIsExact` tells a theme
-which of the two it has: `true` from `buildOffsetPager`, `false` from the
-cursor pager that remains for anything paging without a total.
+Use `<Page>ViewModel` for a page and plain model names for its parts. Model fields are public theme API: removals and renames require the [deprecation process](../extensions/theme-contract.md#versioning).
 
-The cost is the usual one: a deep offset makes Postgres walk the rows it
-is skipping. That is a real limit at page 900 of a hot table and not one
-this board's screens reach; when it is, the fix is a covering index or a
-hybrid that seeds the offset from a cursor — not a return to next-only
-links.
+## Pagination
 
-**Never link to a route that does not exist.** The user-panel builder
-earned this rule: while the profile and control-panel screens were
-unbuilt, `buildUserPanelModel` returned an empty link list rather than
-advertising pages that 404. The screens exist now and the list is
-populated — the rule outlives the example, so when a view model covers a
-page that is not built yet, render the absence.
+Screens use `?page=N`, `readPage`, `offsetOf` and `buildOffsetPager` from `src/view/pager.ts`. Invalid page values become page one. Never accept a raw offset from the URL.
 
-**Never expose a database row to a component or an API response.** Row
-shapes change with migrations, and a component reading `row.password_hash`
-because it was in scope is exactly the accident the rule prevents.
+List and count with the same filter. Reuse existing reliable counts where available. Pass the result to the `Pagination` slot; do not hand-build paging links.
 
-Naming: `<Page>ViewModel` for the page's model (`ThreadViewModel`), plain
-nouns for the pieces (`PostBitModel`). These are a **public API** for
-themes — adding a field is minor; renaming or removing one needs a
-deprecation cycle.
+REST endpoints retain cursor pagination. `pageCountIsExact` distinguishes counted offset pages from cursors without an exact total. Deep offsets cost database work; measure before adding an index or alternate paging strategy.
 
----
+Do not generate links to routes that do not exist.
diff --git a/docs/contributing/repository-checks.md b/docs/contributing/repository-checks.md
index 4a588b141..4c97632d6 100644
--- a/docs/contributing/repository-checks.md
+++ b/docs/contributing/repository-checks.md
@@ -1,189 +1,52 @@
-# Repository rules and checks
+# Repository checks
 
-Follow the repository contract and run the checks that enforce it. This reference explains the invariants behind the commands used in the contribution workflow.
+Run `pnpm verify` from the repository root before a pull request. It runs the static gates, lint, dependency checks, typechecks and unit tests. CI additionally runs coverage, PostgreSQL and browser checks.
 
-## The commands
+## Comments and formatting
 
-| Command | What it does |
-|---|---|
-| `pnpm dev` | The board, on port 3000. |
-| `pnpm site:dev` | meith.dev, on port 3100. |
-| `pnpm meith <command>` | The operator CLI against your `.env`. `--help` lists everything. |
-| `pnpm test` | The whole unit suite. `pnpm test:watch` while you work. |
-| `pnpm typecheck` | The workspace. `typecheck:app` and `typecheck:site` cover the two Next projects. |
-| `pnpm lint` | Biome: formatting, lint rules and import order, in one pass. `pnpm format` writes the fixes. |
-| `pnpm verify` | **The full static gate.** Run it before opening a pull request — see below. |
-| `pnpm test:e2e` | Playwright: the no-JavaScript paths, the staff panels, and the accessibility checks. It builds the board and runs the standalone output against its own databases — nothing to install. `pnpm test:e2e:build` is the build on its own. |
-| `pnpm site:shots` | Re-photographs meith.dev's theme and thread screenshots against the fixture board. Deliberate, never on CI — see [the site's screenshots](testing.md#the-sites-screenshots). |
-
-`pnpm verify` is the one that matters. It runs, in order: the workspace
-check and the verify/CI parity check, the root and release checks, the
-guards and their probes, the message-catalog check, the slot checks, the
-generated-document and documentation checks (`theme:docs`, `plugin:docs`,
-`board:gen`, `hooks:wired`, `regions:wired`, `api:docs`, `perf:docs`, `docs:index`,
-`docs:links`, `docs:redirects`, `site:docs`, `marketplace:gen`, `board-installer:gen`,
-`extension:gen`), lint, dependency-cruiser, all three
-typecheck projects, and the full test suite.
-
-**`pnpm verify` and CI's `static` job hold to each other.** `pnpm
-ci:parity:check` reads the `verify` script and the `static` job out of
-`.github/workflows/ci.yml` and fails, naming them, on any gate chained in
-one and missing from the other — it is itself a gate in both. The one
-exception is written out with its reason in `scripts/ci-parity.mjs`:
-`verify` ends on `pnpm test`, while `static` runs the same suite as `pnpm
-test:coverage` (a superset) and the `migrations` job runs it again against
-real Postgres. `static` also runs steps that need CI's machine rather than
-a developer's — packing every publishable tarball against its manifest,
-the Redis cache-driver contract, coverage thresholds — so run `pnpm
-test:coverage` yourself before a pull request that moves what is covered.
-CI's other jobs build the image, drive a browser, and run the migrations
-against real Postgres.
-
-Tests that validate future dates must fix the clock and restore it afterward,
-so fixtures do not expire as real time advances. The poll closing-time test
-fakes only `Date`, leaving asynchronous timers running normally.
-
-## No inline comments
-
-`AGENTS.md` carries the rule: an explanation belongs in the document under
-`docs/` that covers the behaviour, changed in the same commit, never in the
-code. A comment is invisible to everyone who is not already reading that
-function — an operator, a theme author, somebody deciding whether the
-software does what they need — and it rots unnoticed, because nothing
-checks a comment against the code beside it. A paragraph in `docs/` is read
-by all of them and is checked: the links gate holds its anchors, the index
-gate holds its registration, and the generated references fail when the
-contract they describe moves.
-
-The rule covers `/** */` as much as `//` — a JSDoc block that explains why
-is an inline comment with decorative syntax. Four kinds of comment are not,
-and are the only exceptions:
-
-- **`biome-ignore` suppressions**, which the linter reads and which must
-  carry a reason.
-- **`@ts-expect-error`**, which the compiler reads.
-- **Type annotations the compiler reads** — `@type`, `@satisfies`,
-  `/// <reference>` — mostly in `.mjs` files with no other way to say it.
-- **The prose in the six files a generated reference is built from**:
-  `packages/theme-kit/src/{slots,api,view-models}.ts`, published by
-  `pnpm theme:docs` as [the theme slot reference](../reference/theme-slots.md),
-  and `packages/plugin-kit/src/{hooks,payloads,regions}.ts`, published by
-  `pnpm plugin:docs` as [the plugin hook reference](../reference/plugin-hooks.md).
-  There the comment *is* the published document.
-
-### How it is enforced
-
-Three layers, none of them CI, in the order they catch something. All three
-scan with `scripts/comment-scan.mjs`, and compare against `HEAD` rather
-than a checked-in allowlist — which is what lets them stay quiet about
-comments already in the tree while refusing every new one.
-
-- **`pnpm comments:check`** lists every comment your change adds. Run it
-  before you finish.
-- **The git `pre-commit` hook** (`.githooks/pre-commit`) runs the same
-  check over the staged tree and refuses the commit, whoever or whatever
-  wrote the code — `pnpm install` arms it via `core.hooksPath`.
-  `git commit --no-verify` is the deliberate way past it.
-- **A `PostToolUse` hook** (`.claude/hooks/no-inline-comments.mjs`) rejects
-  a Claude Code file write on the spot — the fastest feedback, but it
-  covers one tool, which is why it is not the layer the rule rests on.
-
-Nothing in `pnpm verify` or CI checks for comments, deliberately: the rule
-is about how the codebase is written, so enforcement sits where the writing
-and committing happen, not on the branch.
-
-## Formatting and lint
-
-One tool does both: [Biome](https://biomejs.dev/), configured in
-`biome.json` at the root. `pnpm lint` checks formatting, the lint rules and
-import order and changes nothing; `pnpm format` writes the fixes.
-`pnpm verify` runs the check, so a badly formatted file fails CI the same
-way a lint error does.
-
-The formatter is not configurable per file: single quotes, no semicolons,
-two-space indent, 100 columns, and the version pinned exactly in
-`package.json`. It covers TypeScript, JSX, JSON and CSS — everything except
-the generator-written `docs/reference/perf-*.json` files. Markdown, YAML
-and SQL have no formatter: `docs/`, the workflows and the migrations are
-written by hand and reviewed as prose.
-
-Three rules carry an invariant rather than a preference:
-
-- **`style/noProcessEnv`.** `process.env` is read in
-  `packages/core/src/env.ts` and nowhere else, so every variable is
-  validated once at boot. `scripts/`, `apps/cli`, `apps/worker`, config
-  files and tests are exempt in `biome.json`; `pnpm guards` enforces the
-  same rule textually, catching reads in files Biome does not parse.
-- **`scripts/no-group-ids.grit`.** A Biome plugin that fails on any read of
-  `.groupIds` or `.primaryGroupId`. Group IDs must not leak outside
-  `@meith/authorization` — ask the Authorizer
-  `can(actor, action, target)` instead of branching on group membership.
-  The modules that legitimately carry a group id as data are named by path
-  in the plugin itself, because a plugin diagnostic cannot be suppressed on
-  one line.
-- **`suspicious/noConsole`.** The board logs through `logger()`. Processes
-  that *are* their output — the CLI, the worker, the scripts, the e2e
-  harness — are exempt.
-
-Everything else is Biome's recommended set. Where a recommended rule is off
-in `biome.json` it is because the codebase means the other thing — for
-instance, `noDangerouslySetInnerHtml` would fire on every rendered post
-body, and that safety argument is settled in `@meith/markdown`, the only
-place rendered HTML comes from; `noImgElement` would ask for `next/image`
-on a board that has to run without an image optimiser.
-
-When updating Biome, align the schema URL in `biome.json` with its package pin.
-
-A suppression is always a `biome-ignore` with a reason, never a blanket
-disable:
-
-```ts
-// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point
+Run `pnpm comments:check` before finishing. It checks added comments against `HEAD` and also runs in the git pre-commit hook. Explanations belong in `docs/`.
+
+Allowed exceptions are `biome-ignore` suppressions, `@ts-expect-error`, compiler-read type annotations, and documentation prose in:
+
+- `packages/theme-kit/src/{slots,api,view-models}.ts`
+- `packages/plugin-kit/src/{hooks,payloads,regions}.ts`
+
+Biome formats JavaScript, TypeScript, JSON and CSS. Use two spaces, single quotes, no semicolons and the configured 100-column width. Format only touched files:
+
+```sh
+pnpm exec biome check --write path/to/file.ts
 ```
 
-> [!IMPORTANT]
-> **Do not run `pnpm format` in a feature change.** It is safe — the output
-> is deterministic — but a whole-tree rewrite buries whatever you were
-> actually changing. Format the files you touched, or let your editor do it
-> on save.
+A suppression must name the rule and reason on the preceding line. Do not disable a rule globally to bypass one failure.
 
-## The checks that fail on purpose
+## Invariants
 
-Several gates in `pnpm verify` exist because something once passed every
-other check and broke on a clean install. Each checks a fact about the
-repository that nothing else reads:
+| Check | Enforces |
+|---|---|
+| `workspace:check`, `ci:parity:check` | Workspace inventory and agreement with CI gates |
+| `root:check` | Root file registry; new files normally belong in directories |
+| `release:check` | Lockstep versions and publishable dependency closure |
+| `guards`, `guards:probe` | Architecture and security patterns, including detection tests |
+| `i18n:check` | Translation keys and catalogue consistency |
+| `slots:check`, `slots:probe` | Static slot maps and server/client boundaries |
+| `hooks:wired`, `regions:wired` | Extension contract call sites |
+| `depcruise` | Package dependency boundaries |
 
-| Script | What it catches |
+Use the central environment module; direct `process.env` reads are restricted to designated adapters. Authorization uses permissions rather than hardcoded group IDs. Use the request logger instead of `console` in application code.
+
+## Generated files
+
+Run each generator after changing its source, then commit the output. Its `:check` counterpart rejects stale files.
+
+| Generator | Output |
 |---|---|
-| `workspace:check` | A package directory with sources and no `package.json`, or a manifest the lockfile has not seen. Both pass every other gate and fail `pnpm install --frozen-lockfile`, which is CI's first step. Also an `@meith/*` package a board installs that `next.config.mjs` does not compile — invisible in here, where the path aliases resolve to source, and red on every board-build job at once. |
-| `ci:parity:check` | A gate chained in `pnpm verify` that runs in no step of `ci.yml`'s `static` job — the shape of defect that let six gates pass for a developer and merge green on a pull request. See [the commands](#the-commands). |
-| `root:check` | A new file at the repository root. The root is an interface — every entry is registered with the reason it must live there. |
-| `release:check` | A version written anywhere that disagrees with the release version, or a published package depending on a private one. See [Releasing](release.md). |
-| `guards` | Textual invariants — the things a grep can prove and a type cannot. `guards:probe` proves each guard still fires. |
-| `i18n:check` | A message the code names and the catalog does not carry, a message nothing reads any more, a mirrored setting label that has drifted from the catalog, or a view builder that gained a hardcoded English string. See [Languages](../extensions/internationalisation.md). |
-| `slots:check` | The server/client boundary in theme slots, in both directions. |
-| `hooks:wired` | A hook fired by name that the registry does not declare — the typo that would otherwise be a call nothing listens to. It also derives the wired/unwired list that `pnpm plugin:docs` publishes. |
-| `regions:wired` | A UI region declared in the registry that no call site in `apps/community` renders — the asymmetry that let `admin.dashboard` sit in the reference while rendering nowhere. It also flags a call site that renders a region the registry does not declare. |
-| `theme:docs:check`, `plugin:docs:check`, `api:docs:check`, `perf:docs:check` | A generated reference that has drifted from the code it describes. |
-| `board:gen:check` | Either board's `meith.plugins.ts` out of step with its `board.plugins.json` — see [the board plugin manifests](board-workspaces.md#the-board-plugin-manifests). |
-| `marketplace:gen:check`, `board-installer:gen:check` | A published artifact generated from this repository that has drifted from its source: the marketplace feed meith.dev serves and the one-line board installer. |
-| `templates:gen:check` (release only) | A deploy template that differs from the scaffold being released. Templates stay at the last release between version bumps. |
-| `extension:gen:check` | `create-meith`'s plugin and theme scaffold templates out of step with `examples/hello-plugin` and `examples/iris-theme`, which they are generated from. |
-| `docs:index:check`, `site:docs:check` | A document in `docs/` that the index does not link, or that is neither published on the site nor explicitly repository-only. |
-| `docs:links:check` | An internal link or anchor under `docs/` that resolves to nothing — a renamed heading, a moved file, or a section that never existed. It also checks the `doc`/`anchor` pairs `apps/web` links back into `docs/`. See [documentation links](documentation.md). |
-| `docs:redirects:check` | A `/docs/…` redirect in `apps/web/next.config.mjs` whose source is also a published document. The redirect would shadow the real page, so a reader following a link to it lands on the redirect's target instead. |
-
-One check runs in CI but deliberately **not** in `pnpm verify`:
-`templates:sync:check` clones the two deploy-template repositories and
-diffs each against its generated `templates/<target>/` tree. It needs the
-network, which `verify` does not, so it lives in its own CI job — see
-[Releasing](release.md), "Deploy template repositories".
-
-Three of those gates read the working tree rather than the index, so a
-directory a tool leaves behind is a directory they scan. `root:check`
-tolerates an unregistered root entry only when git ignores that entry
-itself; `guards` and `i18n:check` share the walker in
-`scripts/repo-files.mjs`, which skips build and tooling output by name —
-`node_modules`, `dist`, `coverage`, `.meith`, `.claude` and their kind. A
-new tool that writes into the tree belongs in both that list and
-`.gitignore`, or every guard fires against copies of the repository.
+| `theme:docs`, `plugin:docs`, `api:docs`, `perf:docs` | Reference documents |
+| `site:docs` | Documentation index |
+| `board:gen` | Board plugin registry |
+| `marketplace:gen` | Marketplace feed and images |
+| `board-installer:gen` | Downloadable installer |
+| `extension:gen` | Extension scaffold source |
+
+`docs:index:check`, `docs:links:check` and `docs:redirects:check` verify document registration and links. Deploy template snapshots update during releases with `templates:gen`; `templates:sync:check` checks their remote repositories.
+
+Shared source walkers apply build-directory exclusions and gitignore rules. Keep new checks consistent with those walkers.
diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md
index 7c6ee8f17..6fda96246 100644
--- a/docs/contributing/testing.md
+++ b/docs/contributing/testing.md
@@ -1,196 +1,48 @@
-# Run and debug tests
+# Testing
 
-Choose the test layer for the behavior you are changing. This guide covers isolated databases, coverage, browser fixtures and the screenshots used by the website.
+Run commands from the repository root. Start with the tests affected by the change.
 
-## The database in tests
+## Unit and database tests
 
-`pnpm test` needs no database. Repository tests, migrations, anything
-asserting on real SQL — all of it runs against PGlite, a real Postgres
-compiled to WebAssembly, booted in-process per suite with the checked-in
-migration SQL applied.
+```sh
+pnpm test
+pnpm test:coverage
+```
+
+Most database suites create isolated PGlite databases and run real migration SQL. `*.pg.test.ts` suites need `TEST_DATABASE_URL`; without it they are skipped. Use PostgreSQL for driver, session-lock and pooled-queue behaviour.
+
+Coverage uses V8 and configured floors. Do not lower a floor to accommodate an untested change.
+
+## Browser tests
+
+```sh
+pnpm test:e2e
+```
+
+This builds the standalone test app, then starts the suite's database and server. The main board and installer use separate schemas. Running `pnpm exec playwright test` directly reuses the existing build and can test stale code.
 
-The `*.pg.test.ts` files are the exception — they need a real Postgres
-*server*, because the thing under test is behavior PGlite cannot
-reproduce: `packages/db/src/client.pg.test.ts` exercises the client driver
-PGlite bypasses, the migrate and install-repo tests need two connections
-contending for a session-level lock, and
-`packages/testkit/src/postgres-queue-pooled.pg.test.ts` needs each
-connection to own its own backend — a wire server in front of one PGlite
-funnels every client into a single backend whose one unnamed prepared
-statement the connections then overwrite for each other.
+Most tests run without JavaScript. Test enhancements separately. Use the fixture helpers for admin/member sessions; the test moderator is not an administrator.
 
-They all skip unless `TEST_DATABASE_URL` is set:
+The suite shares state and runs serially. Restore global settings changed by a test. Use fixed clocks where appropriate and allow for task scheduling and the single-connection pool. Do not hide intermittent failures with retries.
+
+Use the fake mailbox to retrieve mail tokens. Request-level tests should use the signed-header helper where HTTP/Secure-cookie behaviour differs from Chromium. Clear the intended cookie by name. Local passkey tests deliberately omit the board URL setting.
+
+## Website tests
 
 ```sh
-docker compose -f docker/compose.dev.yml up -d
-TEST_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:55432/community_test pnpm test
+pnpm exec playwright test --config apps/web/e2e/playwright.config.ts
 ```
 
-CI's `migrations` job sets it, so "it passed locally" covers everything
-except those seams — and CI covers them.
-
-## Coverage
-
-`pnpm test:coverage` runs the unit and integration suite with V8 coverage
-and writes the HTML report to `coverage/index.html`. CI's `static` job runs
-that command as its only pass over the suite — `--coverage` decides what is
-measured, never what is collected, so it is `pnpm test` plus the
-thresholds, not a second run.
-
-The global thresholds prevent repository-wide regressions, and separate
-floors for the worker, polls, attachments, and UI packages keep well-tested
-packages from hiding a decline in those areas. Thresholds are a ratchet:
-raise them when the measured baseline improves, and do not lower them
-without documenting the reason in the same change. (`packages/drafts` is
-interfaces only — erased at runtime, checked by `index.type-test.ts`, and
-due a floor when it grows runtime behavior.)
-
-## The browser suite
-
-`pnpm test:e2e` starts everything it needs: a PGlite serving the Postgres
-wire protocol, a built server running the standalone output against it, and
-a second database and server for `/install`. There is nothing to install
-and nothing to leave running.
-
-The build comes first (`e2e/support/board-build.ts`; `pnpm test:e2e:build`
-runs it alone) and needs no database — every route is dynamic, nothing is
-prerendered. A cold build takes about a minute and an unchanged rebuild a
-few seconds. Both servers run the same `server.js` from the same
-`.next-e2e/standalone` tree, staged with `static` and `public/` the same
-way `forum-web build` stages them, and differ only in `PORT`,
-`DATABASE_URL` and `UPLOADS_DIR`. Running `npx playwright test` directly
-skips the build and serves whatever was built last.
-
-The suite used to drive `next dev`, whose per-route compilation made late
-tests slow and CI shards fail under memory pressure; the built server
-removed that mechanism rather than containing it, and the CI retry went
-with it. **A browser test that fails intermittently now is a signal** —
-usually a real race in the test or the product — and should be read rather
-than retried. `e2e/support/flaky-notice.ts` stays wired so that if anyone
-runs with `--retries` during triage, a test that failed and then passed
-prints a warning instead of counting as plain green.
-
-Navigation ordering specs create their own neighbouring menu items and
-assert relative order and the intended submenu parent. They must not assume
-a fixed number of arrow clicks relative to a bundled plugin link: enabling
-another plugin legitimately adds a sibling to the navigation.
-
-The `/install` database carries the schema and no rows, which is the state
-a real board is in when someone opens `/install`: migrations run before the
-board serves anything, and the installer checks the schema rather than
-applying it.
-
-**Most specs run with JavaScript disabled** — two-thirds of the suite. That
-is the point rather than a flourish: the board's claim is that a native
-`<form>` does the work and the islands are optional, so a suite that tested
-only the enhanced path would prove the opposite. The JS-on specs are the
-ones whose subject needs scripting — accessibility, passkeys, the content
-security policy, the API, syndication, the screenshot tours — plus
-`admin-panel-live.spec.ts`, an exception the rule needs: with scripting off
-a form post is a full navigation, so a no-JS suite is blind to a panel
-screen that does not refresh its own cached list.
-
-A spec that needs a member **registers through the form**: the seeded
-accounts carry a hash nothing can match, so the only way in is the way a
-member takes. A spec that needs *staff* cannot do that, because a
-registration always lands in the Registered group, so two accounts are
-seeded with a real password, both named in `e2e/support/config.ts`:
-
-| Account | Group | For |
-|---|---|---|
-| `admin` | Administrators | The control panel. Bypasses forum permissions. |
-| `e2e_moderator` | Super Moderators | Moderation. Deliberately **not** an administrator, so the specs prove the moderator's own path rather than the bypass — and prove the panel is shut to them. |
-
-Use `signUp`, `signInAsModerator` and `enterAdminPanel` from
-`e2e/support/session.ts` rather than repeating the forms. `signUp` also
-asserts the username fits the board's 30-character maximum — the
-registration input silently truncates a longer one, and the sign-in that
-follows fails inexplicably.
-
-The two-factor specs read both halves of the no-JS contract at once: every
-authenticator-code field renders `OtpField`, a native text input that takes
-a six-digit or recovery code with scripting off and upgrades to the
-`@meith/ui` `InputOTP` boxes once scripting confirms.
-`two-factor-no-js.spec.ts` signs in through the fallback,
-`two-factor.spec.ts` through the widget, so the enhanced path is proven
-without the fallback being torn out from under it.
-
-**The suite shares one database across every spec, in file order** —
-`workers: 1`, `fullyParallel: false`. A spec that changes something every
-page shows (an announcement, a board setting, a pinned thread) must put it
-back, or a later file fails for a reason nothing in that file can explain.
-It shares the **scheduler** too: a spec that drives background work through
-`/api/system/tick` can find a task not yet due if an earlier spec ticked,
-so give such a spec its own `test.setTimeout` longer than the wait it asks
-for. And `DATABASE_POOL_MAX` is `1` for the suite, so queries made
-concurrent with `Promise.all` still serialise on the single connection.
-
-**Passing is not enough — the run also fails on what the board logged.**
-`e2e/support/server-errors.ts` reads the server's output and fails the run
-on any unhandled server error, however many tests passed. It exists because
-a green run once hid fifty-six of them.
-
-The specs are typechecked by `pnpm typecheck` along with everything else —
-Playwright transpiles without checking, so an uncompiled support file would
-otherwise never fail at all. **CI shards the suite across four runners**,
-each with its own databases and servers; every spec seeds what it needs, so
-the split is safe in any order. `.next-e2e` is deliberately not cached
-between CI runs — a restored build is the stale-cache problem, and a cold
-build is cheap.
-
-A built server is production, and three harness details follow from that:
-
-- Password-reset tokens are not readable off the page outside development,
-  so `account-security-no-js.spec.ts` reads the token out of the **e-mail**
-  instead: `MAIL_DRIVER=http` points the board at
-  `e2e/support/fake-mail.ts`, and `e2e/support/mailbox.ts` reads the inbox
-  back — exercising the reset mail end to end.
-- The e2e board deliberately does not know its own address:
-  `admin-panel-live.spec.ts` asserts the warning about that, and
-  `passkeys.spec.ts` needs to reach the board as `localhost`. The one test
-  that needs an address sets it through the panel and puts it back.
-- Production session cookies are `__Host-` prefixed and `Secure`. Chromium
-  sends them over `http://127.0.0.1`, but Playwright's `page.request` will
-  not — `signedHeaders()` in `e2e/support/session.ts` attaches the
-  context's cookies to those calls. To drop one cookie, prefer
-  `clearCookies({ name })` over rebuilding the jar.
-
-**A known pre-existing order dependency.** Run serially in one process,
-`admin-tabs-no-js.spec.ts` leaves something behind that makes
-`formatting-no-js.spec.ts`'s server-side highlighting and
-`formatting.spec.ts`'s attachment rendering fail. CI does not see it —
-those specs land in different shards — and it is recorded here rather than
-fixed because it is a separate bug.
-
-## The site's screenshots
-
-Every image on meith.dev is a screenshot of a real board, and
-`pnpm site:shots` is what takes them. They land in `apps/web/public/shots`,
-and the site references them by name, so a rename there is a broken image
-on the page.
-
-It photographs the populated fixture board as a guest on port 3003, using
-`e2e/screenshot-site.config.ts`. Theme previews and mobile thread captures use
-the same deterministic content as local development and hosted fixture previews.
-Search, Calendar and Dues need PostgreSQL and retain their existing screenshots;
-recapture those separately against the database-backed browser test board when
-those surfaces change.
-
-The capture does not run on CI. Re-take images when the board's appearance
-changes and commit only the images that differ. The script updates the captures
-it owns without deleting screenshots of other surfaces.
-
-For the marketplace's five theme previews, run
-`pnpm site:shots --grep marketplace`, then `pnpm marketplace:gen`.
-This writes light-mode captures at 1440 × 900 to `marketplace/screenshots`.
-Each capture checks for populated forums and keeps the board header visible.
-
-The Awards marketplace screenshot is captured by
-`pnpm test:e2e:build && pnpm exec playwright test e2e/awards-no-js.spec.ts`.
-The award workflow runs with JavaScript disabled; the screenshot uses a
-separate JavaScript-enabled context with the same session and checks that
-the account dropdown opens and closes. This captures the normal header
-instead of the intentional plain-link account navigation used without
-JavaScript. Copy the resulting `awards-light.png` from `test-results` to
-`marketplace/screenshots/awards-light.png`, then run `pnpm marketplace:gen`
-to update the published copy.
+The website suite is separate from the board suite. Use `pnpm site:build` to check static docs rendering.
+
+## Screenshots
+
+```sh
+pnpm site:shots
+```
+
+The screenshot server uses port 3003. Marketing images go in `apps/web/public/shots`; database-only surfaces retain their existing captures until captured against a writable board.
+
+For marketplace captures, use `pnpm site:shots --grep marketplace`, then `pnpm marketplace:gen`. Capture Awards with its browser spec against a built board before copying the resulting images and regenerating the feed.
+
+Inspect screenshots manually. They are not a substitute for interaction, accessibility or no-JavaScript tests.
diff --git a/docs/contributing/ui-conventions.md b/docs/contributing/ui-conventions.md
index 65e073479..ee29f362c 100644
--- a/docs/contributing/ui-conventions.md
+++ b/docs/contributing/ui-conventions.md
@@ -1,72 +1,23 @@
-# Develop accessible interface components
+# UI conventions
 
-Use the shared design system for forms, panels and destructive actions. Check keyboard, touch and JavaScript-disabled behavior when changing a user flow.
+Use shared `@meith/ui` components and theme tokens. Keep controls at least 44px on touch devices and preserve keyboard focus. See [Theme controls](../extensions/theme-design.md).
 
-## Reviewing the design system
+## Links and feedback
 
-Run the populated fixture review with:
+Use the shared `TextLink` recipe for inline links. Tooltips must also work on focus; controls still need an accessible name.
 
-```sh
-pnpm exec playwright test --config e2e/screenshot-ui-polish.config.ts
-```
+Success notices use `BoardNotice`: enhanced pages show a status toast, and the theme notice provides the no-JavaScript fallback. Keep validation errors next to their fields and focus the shared error summary when needed.
 
-It starts the fixture board on port 3003. Screenshots and a browsable gallery
-are written under `test-results/ui-polish/`. It covers all six registered themes in both
-schemes, forum and thread reading, profiles, and touch layouts. Database-backed
-workflows remain covered by the ordinary browser suite.
+## Destructive actions
 
-`e2e/ui-layout.spec.ts` keeps the important layout checks in the ordinary
-browser suite: all themes at phone, tablet and desktop widths, compact
-listing cards inside wide windows, and 44px touch controls. The shared
-components and recipes are documented in [The theme API](../extensions/theme-design.md#shared-design-system).
+Use `requireConfirmation` to return `state.confirm` with a snapshot of the intended action. The first submission must not mutate data.
 
-The UI regression suite also covers password visibility with and without
-JavaScript, Escape focus recovery in mobile navigation, hamburger drawers with
-right-side placement, top-bar triggers and expandable sub-sections across all
-six themes with JavaScript enabled and disabled,
-and search-filter touch targets. Drawer alignment is checked against the document
-content edge, which excludes the stable scrollbar gutter on platforms with
-classic scrollbars. Header branding checks target the home link, because the
-closed mobile drawer repeats the board name in its title. Run `e2e/ui-interactions.spec.ts` together with
-`e2e/mobile-nav.spec.ts` and `e2e/ui-layout.spec.ts` after changing these controls.
+`ConfirmDialog` supplies the native/no-script flow, which resubmits with `confirmed=1`; `AlertDialog` supplies the enhanced presentation. Recheck authorisation and submitted state on confirmation.
 
-## UI primitives and destructive actions
+Retain existing preview-and-undo or recent-password checks when they already protect the operation. Reversible logo, image and badge changes do not need an extra confirmation step.
 
-App components share the primitives in `@meith/ui` rather than re-declaring
-the same class strings. A link that is prose — underlined, not a button —
-is a `TextLink` (`@meith/ui`), whose `textLinkVariants` carries the one
-underline recipe the whole board used to repeat inline; a link-styled
-`<button>` reuses `textLinkVariants(...)` for the same reason. Reach for
-these instead of writing `underline decoration-border …` again.
+## Check layouts
 
-A **destructive action confirms itself, fallback-first.** The server action
-calls `requireConfirmation(form, message)` (`server/confirm.ts`): when the
-submission carries no `confirmed` field it returns the message and a
-snapshot of the submitted fields as `state.confirm` and does nothing else.
-The client `ConfirmDialog` renders that state two ways from one markup — a
-`@meith/ui/dialog` `AlertDialog` when scripting is on, and, under
-`<noscript>`, a plain interstitial that re-submits the snapshot with
-`confirmed=1`. **The interstitial is the real path; the dialog is the
-enhancement**, which is why the no-JS specs step through the confirm page
-rather than skipping it (empty trash and delete-forever in
-`undo-no-js.spec.ts`, post and thread deletion in `moderation-no-js.spec.ts`,
-token revocation on the enhanced path in `admin-panel-live.spec.ts`). It is
-applied to every destructive admin action that has no other guard: API
-token revocation, attachment / announcement / prefix / word-filter / smiley
-/ captcha-question / directive deletion, navigation-link deletion, and
-ban-filter removal. Admin operations already guarded by the
-preview-and-undo pattern (`admin-undo.tsx`) or a fresh-password re-check
-(group and promotion-rule deletion) keep those guards instead, and three
-one-click removals are deliberately left un-gated because they destroy
-nothing that cannot be put straight back — the favicon and logo (re-upload)
-and a badge definition.
+Test empty and long content, light/dark schemes, phone/desktop widths, keyboard use and JavaScript disabled. Use the existing `ui-interactions`, `mobile-nav` and `ui-layout` browser tests.
 
-A **notice is a toast, with the banner as its fallback.** Actions still
-redirect carrying the notice in the query string; `BoardNotice` renders the
-`@meith/ui/toast` `Toast` island — dismissible, auto-dismissing,
-`role="status"` — and keeps the theme's `Notice` banner under `<noscript>`,
-toggled by the same `data-`attribute-and-`<noscript>`-style pattern the
-notification and user menus use. **Tooltips** (`@meith/ui/tooltip`) label
-cramped icon controls such as the multiquote toggle; they open on hover and
-focus, so the control still needs its own accessible name for touch and
-screen readers.
+The UI screenshot suite uses port 3003 and writes to `test-results/ui-polish`. Inspect all shipped themes in both schemes. See [Testing](testing.md) for screenshot commands.
diff --git a/docs/extensions/extensions.md b/docs/extensions/extensions.md
index 487b9c276..707462782 100644
--- a/docs/extensions/extensions.md
+++ b/docs/extensions/extensions.md
@@ -1,27 +1,15 @@
-# Build extensions
+# Extension development
 
-Extend a board through a theme or plugin. You need Node.js, npm and a development board; changing Meith's core source is a separate [contribution workflow](../contributing/development.md).
+Use a theme to change presentation or a plugin to add behaviour. Both are installed in the board repository and compiled into its build.
 
-## Choose an extension
+| Task | Guide |
+|---|---|
+| Create a plugin | [First plugin](first-plugin.md) |
+| Add hooks, pages, storage or UI | [Plugins](plugins.md) |
+| Create a theme | [First theme](first-theme.md) |
+| Replace slots or change tokens | [Themes](themes.md) |
+| Add translations | [Translations](internationalisation.md) |
+| Submit a package listing | [Marketplace](marketplace.md) |
+| Install an existing extension | [Installation](../operations/installing.md) |
 
-| Goal | Extension | First tutorial |
-|---|---|---|
-| Change colors, layout or page presentation | Theme | [Build your first theme](first-theme.md) |
-| Add behavior, settings, pages or scheduled work | Plugin | [Write your first plugin](first-plugin.md) |
-| Add an existing package to your board | Installed theme or plugin | [Install extensions](../operations/installing.md) |
-
-Start by inheriting an existing theme or using the plugin scaffold. Both scaffolds come from the repository's tested examples.
-
-## Continue with the contracts
-
-For themes, read [Theme development](themes.md), [tokens and controls](theme-design.md), and the [slot and view-model reference](../reference/theme-slots.md).
-
-For plugins, read [Plugin development](plugins.md), [hooks and lifecycle](plugin-hooks-guide.md), and the [hook reference](../reference/plugin-hooks.md).
-
-The host provides the extension APIs. A theme does not fetch community data, and a plugin does not import the board's database or domain internals. Keep within those boundaries so upgrades remain possible.
-
-## Test and share
-
-Run the scaffold's tests and typecheck, then check the extension inside a board. Verify keyboard access, member permissions and the supported JavaScript-disabled flow. Add translations using [Translations](internationalisation.md).
-
-When the extension is ready for others, follow [Publish to the marketplace](marketplace.md). Publishing a package and installing it into a board are separate actions.
+Use pnpm in the Meith source workspace. Standalone board examples use npm because the generated board requires its dependency layout and tooling; see [Package management](../operations/configuration.md#board-files).
diff --git a/docs/extensions/first-plugin.md b/docs/extensions/first-plugin.md
index c1c78d2f3..6322e4fd2 100644
--- a/docs/extensions/first-plugin.md
+++ b/docs/extensions/first-plugin.md
@@ -1,10 +1,10 @@
-# Write your first plugin
+# Create a plugin
 
-Create a plugin, run its tests and load it into a development board. You need Node.js 22 or newer, npm and a [writable local board](../operations/local-board.md).
+Requires Node.js 22+, npm and a [local board with PostgreSQL](../operations/local-board.md).
 
-## 1. Scaffold the plugin
+## 1. Create the package
 
-From the directory that contains your board project:
+Run beside your board directory:
 
 ```sh
 npx create-meith --plugin first-light
@@ -14,48 +14,46 @@ npm test
 npm run typecheck
 ```
 
-The scaffold includes `src/plugin.tsx`, a test, an entry point and a marketplace listing. Its example declares hooks, a region, a setting, a migration, a scheduled task and an admin page. The entry point exports the `plugin` and `messages` names expected by the board.
+The package exports `plugin` and `messages`. Its example includes a hook, region, setting, migration, task and admin page.
 
-## 2. Change a hook
+## 2. Edit a hook
 
-Open `src/plugin.tsx` and find the `view.footer` filter. Change the label of its added link, then update the matching expectation in `src/plugin.test.ts`.
+In `src/plugin.tsx`, change the link label returned by `view.footer`. Update its expectation in `src/plugin.test.ts`, then rerun the tests and typecheck.
 
-A filter returns a new value; it must not mutate the model passed to it. An event such as `post.created` reacts to an action and its return value is ignored. The [hook reference](../reference/plugin-hooks.md) lists the supported names and payloads.
+Filters return a new value without mutating their input. Event return values are ignored. See the [hook reference](../reference/plugin-hooks.md).
 
-Run `npm test` and `npm run typecheck` again. A successful module import also checks the plugin definition: invalid keys, namespace violations and invalid settings are rejected.
+## 3. Register the plugin
 
-## 3. Register it in a board
-
-Install the local plugin from the board directory:
+Run from the board directory:
 
 ```sh
 cd ../my-board
 npm install ../first-light
 ```
 
-For this local tutorial, add the imports and entry to the board's `meith.plugins.ts`, preserving any existing plugins and the `installedPluginDefinitions` function:
+In `meith.plugins.ts`, add the import:
 
 ```ts
 import { messages as firstLightMessages, plugin as firstLightPlugin } from 'first-light'
 ```
 
-Add this object inside `INSTALLED_PLUGINS`:
+Add this entry to `INSTALLED_PLUGINS`, preserving existing entries and `installedPluginDefinitions`:
 
 ```ts
 { key: 'first-light', enabled: true, plugin: firstLightPlugin, messages: firstLightMessages }
 ```
 
-Also add the package to the `plugins` array in `board.plugins.json` so future registry generation retains it:
+Add the corresponding entry to the `plugins` array in `board.plugins.json`:
 
 ```json
 { "key": "first-light", "package": "first-light", "enabled": true }
 ```
 
-This is a local package installation. For published packages, use the [operator installation command](../operations/installing.md), which updates the manifest and registry together.
+For published packages, [use `plugin:add`](../operations/installing.md) to update both files automatically.
 
-## 4. Apply migrations and run
+## 4. Build and check
 
-With the board's development database configured, run from its directory:
+From the board directory, with its development database configured:
 
 ```sh
 npm run meith -- upgrade
@@ -63,12 +61,6 @@ npm run build
 npm run start
 ```
 
-`upgrade` applies core and registered plugin migrations. `migrate` alone applies core migrations and is not sufficient for the scaffold's plugin table.
-
-Open the board and check the footer link. Sign in as administrator and find the plugin under **Admin → Plugins**. Verify its settings and admin page. Background tasks need a [running scheduler](../operations/scheduled-tasks.md).
-
-## 5. Continue developing
-
-npm links a local directory installation, so edit the plugin and rebuild the board to see the change. Keep plugin tables in their namespace and leave applied migrations unchanged.
+`upgrade` applies core and plugin migrations; `migrate` alone does not apply plugin migrations. Check the footer and **Admin → Plugins**, including the example settings and page. Tasks require the [scheduler](../operations/scheduled-tasks.md).
 
-Continue with [Plugin development](plugins.md) for routes, storage, settings and UI. Use [Publish to the marketplace](marketplace.md) when the plugin is tested and ready to share.
+npm links the local package directory. Edit the plugin and rebuild the board to test changes. Do not modify applied migrations.
diff --git a/docs/extensions/first-theme.md b/docs/extensions/first-theme.md
index 1da190568..a045d196f 100644
--- a/docs/extensions/first-theme.md
+++ b/docs/extensions/first-theme.md
@@ -1,8 +1,10 @@
-# Build your first theme
+# Create a theme
 
-Create a theme that inherits the default board, changes its palette and overrides the footer. You need Node.js 22 or newer, npm and a scaffolded board beside the theme directory.
+Requires Node.js 22+, npm and a scaffolded board.
 
-## 1. Create and test the theme
+## 1. Create the package
+
+Run beside your board directory:
 
 ```sh
 npx create-meith --theme first-light
@@ -12,13 +14,11 @@ npm test
 npm run typecheck
 ```
 
-The scaffold comes from the tested Iris example. `src/theme.ts` declares the theme, `src/tokens.ts` holds light and dark palettes, and `src/slots/` holds the footer override.
-
-## 2. Customize the presentation
+The theme inherits the default theme. `src/theme.ts` defines it, `src/tokens.ts` defines its palettes, and `src/slots/` contains a footer override.
 
-Change a token in `src/tokens.ts` and edit the footer slot. Keep both color schemes readable. Use the [token and shared-control guide](theme-design.md) for the supported values.
+## 2. Change the theme
 
-Run the tests and typecheck again. Prefer inheriting a slot over copying it unchanged; the parent theme continues to supply the rest of the board.
+Edit the footer and light/dark tokens. Inherit unchanged slots. Rerun tests and typecheck. See [Tokens and controls](theme-design.md) for supported values.
 
 ## 3. Register the theme
 
@@ -29,13 +29,13 @@ cd ../my-board
 npm install ../first-light
 ```
 
-Add these imports to `meith.config.ts`:
+Add to `meith.config.ts`:
 
 ```ts
 import { BROWSER_THEME_COLOR, DARK_TOKENS, LIGHT_TOKENS, firstLightTheme } from 'first-light'
 ```
 
-The default scaffold already imports `defaultMessages` from `@meith/theme-default`. Add this entry to the existing `themes` map:
+Add this entry to the existing `themes` map. The board scaffold already imports `defaultMessages` from `@meith/theme-default`.
 
 ```ts
 'first-light': {
@@ -48,15 +48,13 @@ The default scaffold already imports `defaultMessages` from `@meith/theme-defaul
 },
 ```
 
-Set `defaultTheme` to `first-light` if it should be the default. Preserve other configured themes and plugins.
+Set `defaultTheme` to `first-light` to make it the default. Preserve existing themes and plugins.
 
-## 4. Build and inspect
+## 4. Check the result
 
 ```sh
 npm run build
 npm run start
 ```
 
-Select the theme from the board's appearance control, or open **Admin → Themes** on an installed board. Check the footer, a thread, a form and a panel in light and dark mode and at phone width.
-
-A fixture board is sufficient for presentation checks. Use a PostgreSQL-backed board for interactions that save data. Follow [Test a theme](theme-testing.md) for empty and permission-related states, and [Theme contracts](theme-contract.md) before replacing more slots.
+Select the theme in the appearance control or **Admin → Themes**. Check a thread, form, panel and footer in both schemes and at phone width. Fixtures cover presentation; saving data requires PostgreSQL. See [Theme testing](theme-testing.md).
diff --git a/docs/extensions/internationalisation.md b/docs/extensions/internationalisation.md
index 9186fa908..b0f549c22 100644
--- a/docs/extensions/internationalisation.md
+++ b/docs/extensions/internationalisation.md
@@ -1,53 +1,27 @@
-# Translate Meith and extensions
+# Translations
 
-Use language catalogs to translate the board, themes and plugins. Members choose their language at `/usercp/options`; search stemming is a separate [search setting](../administration/search.md).
+## Locale selection
 
-## Understand language selection
+The board uses the member's language preference, then browser language, then the configured default. Missing messages fall back to English.
 
-The first supported match wins: the member's explicit choice, then the browser's language preferences, then the board default. Unsupported message keys fall back through the language tag to English; a key missing everywhere is displayed as the key.
+Core catalogues live in `packages/i18n`. Copy the English catalogue, translate its values and register the locale in the catalogue index. Keep message keys unchanged. ICU plural/select messages require an `other` branch.
 
-Language and timezone are separate preferences. The selected language also sets the page's language and direction.
+`time.hourCycle` accepts `h23`, `h12` or `auto`.
 
-## Write messages
+## Extension messages
 
-Messages use dotted keys and the supported ICU MessageFormat syntax:
+Export locale-keyed message catalogues from a theme or plugin. Namespace keys to avoid collisions. The board merges core, theme, plugin and top-level override messages in that order; later values win.
 
-```json
-{
-  "nav.home": "Home",
-  "stats.posts": "{count, plural, one {# post} other {# posts}}",
-  "time.today": "Today, {time}"
-}
-```
-
-Preserve argument names when translating. Plural/select messages require an `other` branch; use the target language's valid categories. Message formatting supports substitutions, localized numbers, dates/times, plural and select branches. Validate patterns through the catalog tests rather than assuming every ICU extension is implemented.
-
-## Add a board language
-
-1. Copy `packages/i18n/src/catalogs/en.json` to the language tag's filename, such as `de.json`.
-2. Translate values while retaining keys and argument names. Missing translations can fall back to English.
-3. Register the catalog with a static import in `packages/i18n/src/catalogs/index.ts`.
-4. Select the language in a test account and inspect pages, dates, plural forms and direction.
-5. Run `pnpm i18n:check` and relevant tests.
-
-`time.hourCycle` is configuration: use `h23`, `h12` or `auto`. Month/day order and plural categories should match the language; do not force English order into translated strings.
-
-## Register extension messages
+Plugins use the supplied `t` and locale. Themes receive copy prepared by the app. Server code resolves translators; client components receive the required copy as serialisable values. Do not send the whole catalogue to the browser.
 
-A message bundle has the shape `{ locale: { key: pattern } }`. Register it with the theme or plugin in `meith.config.ts`. Catalog precedence is board catalog, themes, plugins, then the board configuration's top-level message overrides; later registrations win.
+Pass the selected locale to `Intl` formatting. Preserve placeholders and avoid joining translated fragments into sentences.
 
-Namespace extension keys, such as `calendar.reminder`, to avoid accidental collisions. Override a core key only when changing its wording intentionally.
+## Check translations
 
-Plugins render translated copy through `context.t`. Themes receive already prepared view models, including formatted count/time labels, and their own registered messages. They do not fetch a request-scoped translator.
+From the Meith source checkout:
 
-## Add application copy
-
-In a server component, use `getTranslator()` from `@/server/i18n`. Pass the translator into view builders and use the shared number/time helpers. Do not hard-code a locale at formatting call sites.
-
-Client components receive serializable copy records resolved on the server. Use the existing `src/view/*-copy.ts` pattern for static strings and the established parameterized-message helpers for values only known in the browser.
-
-Settings, error messages and notification definitions retain certain English metadata mirrored in the catalog. Keep both copies in sync; `i18n:check` enforces the relationship. Do not remove a mirror merely because it resembles duplicate prose.
-
-## Verify the reader experience
+```sh
+pnpm i18n:check
+```
 
-Check long labels, narrow screens, right-to-left layout where relevant, empty states and forms. Catalog validation catches mismatched keys and arguments, but a browser check catches clipped or confusing text.
+Test missing-key fallback, plural values, long labels and both hour cycles. Verify the rendered page as well as the catalogue check.
diff --git a/docs/extensions/marketplace.md b/docs/extensions/marketplace.md
index e5f498808..1e7369c26 100644
--- a/docs/extensions/marketplace.md
+++ b/docs/extensions/marketplace.md
@@ -1,41 +1,27 @@
-# Publish a theme or plugin
+# Publish an extension
 
-Publish a tested extension package, then submit a listing for review. A marketplace listing describes compatibility; it does not prove that an extension is safe or compatible with every board.
+The marketplace lists reviewed npm packages. Operators install packages in their own board repositories; a listing does not install or update code automatically.
 
 ## Prepare the package
 
-Run its tests and typecheck, then install it into a disposable board and verify the documented features. Declare the package version and supported Meith/API range honestly. Check permissions, migrations, secret handling, translations and accessibility.
+1. Test the extension against the declared Meith and API versions.
+2. Publish the package with its licence and source repository.
+3. Capture screenshots of the extension in a board.
+4. Add a listing under `marketplace/listings/` and PNG screenshots under `marketplace/screenshots/` in the Meith repository.
 
-The scaffold includes `listing.json`. Replace placeholders such as the repository URL and provide a real screenshot. Publishing the npm package is a deliberate release action; follow your package's release process when ready.
+Include the package's kind (`plugin` or `theme`), stable key, package name, version, API version, supported `meith` range and screenshot filenames. Follow an existing listing for the complete schema.
 
-## Complete the listing
+Compatibility declarations must match tested behaviour. A range accepted by the parser does not prove the package works on every matching release.
 
-| Field | Meaning |
-|---|---|
-| `kind` | `plugin` or `theme` |
-| `key` | Stable extension key using the accepted key format |
-| `package` | Published package name |
-| `version` | The listed package's version |
-| `apiVersion` | Theme-kit or plugin-kit major used |
-| `meith` | Tested board-version range |
-| `screenshots` | Filenames included in the repository's marketplace screenshots directory |
+## Submit the listing
 
-Third-party packages have their own version sequence. First-party listings track the repository release. The generator checks that ranges parse; you must establish actual compatibility through testing.
+From the Meith source checkout:
 
-## Submit a pull request
+```sh
+pnpm marketplace:gen
+pnpm marketplace:gen:check
+```
 
-1. Add the listing under `marketplace/listings/`.
-2. Add the referenced images under `marketplace/screenshots/`.
-3. Run `pnpm marketplace:gen` and inspect the resulting feed and assets.
-4. Run `pnpm marketplace:gen:check` and the repository's required checks.
-5. Explain the extension's behavior, permissions, compatibility and test results in the PR.
+Commit the listing, screenshots and generated feed, then open a pull request. Review covers functionality, compatibility, licence, declared network access and screenshot accuracy.
 
-The feed serves reviewed local screenshots rather than arbitrary third-party image URLs. Unused screenshots and stale generated output fail the gate.
-
-## Understand review and updates
-
-A review considers the published source, requested capabilities, data access, migration behavior and whether the listing matches what the package does. A listing is not a sandbox or a guarantee against malicious future package releases.
-
-For an update, publish and test the new package, then update the listing and compatibility evidence. Boards can report an available compatible update, but operators still choose to install and deploy it.
-
-Operators should use [Install extensions](../operations/installing.md). Contributors maintaining the feed should use [Marketplace maintenance](../contributing/marketplace-maintenance.md).
+Update the listing when publishing a new package version. Do not edit the generated public feed directly. See [Marketplace maintenance](../contributing/marketplace-maintenance.md) for validation and delisting.
diff --git a/docs/extensions/plugin-hooks-guide.md b/docs/extensions/plugin-hooks-guide.md
index e6c0adb90..b8b7f1809 100644
--- a/docs/extensions/plugin-hooks-guide.md
+++ b/docs/extensions/plugin-hooks-guide.md
@@ -1,254 +1,39 @@
 # Plugin hooks and lifecycle
 
-Choose the appropriate filter or event, understand execution order and failure isolation, and manage the lifecycle of an installed plugin. Start with the first-plugin tutorial if you have not run a plugin yet.
+Register hooks in `definePlugin`. The [generated hook reference](../reference/plugin-hooks.md) lists names, payloads and call sites.
 
-## Filters and events
+## Hook execution
 
-| | What it gets | What happens to the return value |
-|---|---|---|
-| **Filter** | A value | It is used. Filters chain: each plugin receives what the previous one returned. |
-| **Event** | A notification | Discarded. |
-
-> [!TIP]
-> Anything that only wants to *know* — logging, a webhook, a counter —
-> should be an event. An event handler cannot corrupt the thing it is
-> watching, even when it is wrong.
-
-Both kinds can reach this plugin's runtime, so an event handler is where a
-plugin reacts to the board durably: recording a row, queueing a delivery,
-raising a notification. See [reaching the runtime from a
-handler](#reaching-the-runtime-from-a-handler).
-
-### Reaching the runtime from a handler
-
-A handler's first two arguments are the value and the hook's own context.
-Its **third is a function that resolves this plugin's runtime** — the same
-`settings`, `logger`, `data`, `grants`, `users` and `notify` a task or a
-route is handed:
-
-```ts
-'post.created': async (post, context, runtime) => {
-  const { data } = await runtime()
-  await data.query(
-    'insert into plugin_example_outbox (post_id, queued_at) values ($1, now())',
-    [post.postId],
-  )
-},
-```
-
-It is a function, not a value, for two reasons. Hooks are the hot path —
-`view.*` filters run on every page and `postbit.badges` once per post — and
-a handler that never calls it costs nothing, so the overwhelmingly common
-pure-view filter pays for none of this. And acquiring the runtime can fail:
-on a fixture-mode board there is no database, and `await runtime()` rejects
-with a message that says so rather than handing back something that
-pretends. Within a single handler call the runtime is resolved once and
-reused, however many times it is asked for.
-
-The reach is the same one everything else in the plugin gets, and no
-larger: `data` still refuses anything outside `plugin_<key>_*`, `grants`
-still refuses a group the operator has not opened, and a throw is still
-contained and counted as [failure isolation](#failure-isolation) describes.
-Testing a handler that uses it needs no board — `unavailableHookRuntime()`
-stands in, and every capability on it refuses with the reason you pass:
-
-```ts
-filter(footer, viewer, unavailableHookRuntime('this test drives the filter directly'))
-```
-
-### Ordering
-
-Handlers run in **(priority, plugin key)** order. Lower priority runs first;
-the default is 100, so a plugin can insert on either side of an
-unopinionated one without negative numbers. Both halves are declared and
-total, so two plugins compose the same way on every request, on every
-instance, in every deployment.
-
-## Failure isolation
-
-Every handler runs inside the host's try/catch:
-
-| What happens | Result |
+| Kind | Contract |
 |---|---|
-| A filter throws | The value is left as it was, and the chain continues with the next plugin |
-| A filter returns `undefined` | Treated the same way — that is the shape of a handler that forgot to return |
-| An event throws | Recorded and forgotten |
-
-Nothing a plugin does propagates to the page. That makes plugin failures
-survivable, **not invisible**: every failure is counted, logged with the
-plugin key and the hook, and reported by `host.health()`.
-
-Two limits and one guarantee are worth stating plainly, because a promise
-with an unstated edge is worse than a smaller honest one:
+| Filter | Return the next value; do not mutate input. Each handler receives the previous result. |
+| Event | Perform a side effect; return values are ignored. |
 
-**Auto-disable is durable.** Every failure is counted in a `plugin_health`
-row, and the fifth switches the plugin off with the hook and the message
-that did it. The row is the answer, not this process's tally: it survives a
-restart, it is shared by every web instance and the worker, and each of them
-reconciles against it. A plugin that started failing at 2am is off when the
-platform recycles the instance at 3am, and off on the instance that never
-saw it fail.
+Handlers run by ascending priority (default `100`), then plugin key. Runtime access is lazy and cached per handler invocation. Fixture mode rejects services that need a database.
 
-Nothing re-enables it on its own. An operator clears the record — **Clear
-failures and re-enable** on `/admin/plugins`, which deletes the row and
-takes effect on the next request across the board. Deliberately manual: a
-plugin that fails five times and is switched back on by a timer fails five
-more times, and the board has learned nothing.
+A throwing filter or one returning `undefined` retains the preceding value. Event exceptions are logged. Both count toward plugin failure health. Execution time is recorded; this is not a JavaScript timeout.
 
-> [!NOTE]
-> A count that reaches the threshold is the *board's* count, not one
-> instance's, so a plugin failing twice on each of three instances is
-> switched off — which is the point of moving it out of memory.
+## Failures
 
-**Timing is measured, never enforced.** Each call is timed, and slow ones
-are logged and counted. There is no timeout, because JavaScript cannot abort
-a handler: a `Promise.race` that "times out" returns control while the
-handler keeps running, keeps its connection, and resolves later.
+`plugin_health` persists failures across processes. Five failures disable a plugin. An administrator must clear its failure state and enable it again; there is no timed reset.
 
-**UI contributions are isolated when they are built, not while they
-render.** The host calls your `render` function inside a try/catch, so a
-throw there drops your contribution and the region renders without it. A
-component that throws later, inside React's own render, cannot be contained
-from the server. So: build your markup in the function; do not return a
-component that does work.
+Region error handling catches failures during `render`, including awaited work. It cannot catch a React component that throws later when React renders the returned tree. Perform fallible work in the region's `render` function.
 
-## The lifecycle
+Scheduled-task failures use the scheduler's failure handling; they are not ordinary hook failures.
 
-Four callbacks, each with one moment it runs and its own answer to "what if it
-throws". All four are handed the same runtime context a task gets — resolved
-settings, a logger, and `grants`, `data`, `users` and `notify`.
+## Lifecycle
 
-| Callback | When | If it throws |
+| Handler | When it runs | Failure behaviour |
 |---|---|---|
-| `onInstall` | The first `meith upgrade` on a board that has never recorded this plugin, after its migrations | The upgrade stops |
-| `onEnable` | An operator switches the plugin on in the panel | The switch stands; counted as a plugin failure |
-| `onDisable` | An operator switches it off | The switch stands; counted as a plugin failure |
-| `onUninstall` | `meith plugin:purge <key>`, before anything is dropped | Nothing is dropped |
+| `onInstall` | After migrations, before the installed version is recorded | Stops installation; make retries safe |
+| `onEnable` | After an administrator enables the plugin | Logged and counted |
+| `onDisable` | After an administrator disables the plugin | Logged and counted |
+| `onUninstall` | Before purge deletes plugin data | Stops purge |
 
-None of them runs inside the host's try/catch. That isolation exists to keep a
-page rendering, and none of these is on a page.
+Automatic failure-based disabling does not invoke `onDisable`. Installation may be retried after partial progress, so `onInstall` must be idempotent.
 
-**`onInstall` runs once per board, not once per deploy.** The board records a
-`plugin:<key>` version row; no row means it has never seen the plugin. It runs
-after that plugin's migrations, so its tables exist, and before the version row
-is written, so a throw leaves the board able to try again. A throw stops the
-upgrade — a plugin that could not finish installing is not one the board should
-start serving.
-
-**`onEnable` and `onDisable` run on the operator's switch only.** They do not
-run on the host's own switch after repeated failures: a plugin that has just
-failed five times is not one to hand more work to. They run *after* the switch
-is written, so the callback sees the state it is being told about, and the
-switch stands whatever they do — a callback that throws is the plugin's fault,
-so it is counted and shown in the plugin's health row rather than reported to
-the operator as their action having failed.
-
-**`onUninstall` needs `meith plugin:purge`, and that is not a workaround.**
-Removing a plugin is `pnpm remove`, taking it out of `meith.plugins.ts`
-(`meith plugin:remove <key>` for a manifest entry, by hand for the escape
-hatch) and a redeploy — and at the moment the board would call `onUninstall`,
-the function is no longer in the build. There is no point in time where the
-host holds both "this plugin is gone" and "this plugin's code". So the
-operator says when:
-
-```sh
-meith plugin:purge dues          # says what it would do
-meith plugin:purge dues --yes    # runs onUninstall, then drops the data
-```
-
-It runs `onUninstall` first and drops nothing if that throws, then takes away
-the plugin's `plugin_<key>_*` tables, its settings, its migration records, its
-navigation items, its version row and its health row. Then you remove the code.
-Purging a plugin that is not in the build is refused, with that explanation:
-there would be no `onUninstall` left to run.
-
-The tables it drops are matched against the literal `plugin_<key>_` prefix, not a
-pattern — the `_` in the prefix stands for itself, so a two-letter key like `mi`
-takes only `plugin_mi_*` and never the board's own `plugin_migrations`. The
-board's `plugin_migrations` and `plugin_health` tables are excluded outright as
-well, so no key can reach them however short it is.
-
-> [!TIP]
-> Write these if the shape of your plugin wants them, but keep `onInstall`
-> **idempotent anyway**. It runs once per board, and a board restored from a
-> backup taken before the install is a board that will run it again.
+Disabling retains data. Purge removes the plugin's namespaced tables and settings, migration records, navigation, version and health records. Lifecycle cleanup requires the plugin definition to remain available. Back up before purging.
 
 ## Versioning
 
-`definePlugin` requires semver. The version is the plugin's own — it is
-what the admin panel shows and what its migration history is recorded
-against.
-
-`apiVersion` declares which plugin-kit major the plugin was written
-against. The same policy as the [theme API](theme-contract.md#versioning)
-applies: a minor adds hooks, payload fields and regions; a major may remove
-or rename one, and only after a deprecation cycle.
-
-## What is wired, and what is not
-
-An honest inventory, because the alternative is a document describing a
-system that does not run. It is derived rather than remembered:
-`scripts/hook-callsites.mjs` computes it by scanning the tree, so the
-generated reference's wired column cannot drift from the code.
-
-**All 102 hooks are wired.** Every entry in the registry has a call site in
-the board, and the generated reference's wired column — computed from the
-tree, not maintained by hand — says so. If that column ever reads anything
-else, believe the column: it is derived and this sentence is not.
-
-A hook that is declared but not wired would not be broken, only unfinished:
-registering a handler for one is legal and does nothing. The reference marks
-which is which so you find out before you ship, rather than after.
-
-**`plugins/reference` must handle every wired hook**, enforced by its own
-test. That is the ratchet: wiring a new call site into the board fails the
-reference plugin's test until a handler is added there, so a hook cannot
-join the running product without something proving it fires. The same
-plugin declares a route of every shape, a board page, a secret setting with
-an environment override and a select — and its tests drive each one, so
-none of those surfaces can silently rot either.
-
-### The descriptors execute
-
-Everything declared runs today, the four lifecycle callbacks included — see
-[the lifecycle](#the-lifecycle) for when each fires and what a throw costs.
-Migrations are applied by `meith upgrade` in
-dependency order, one transaction each. Settings are stored at
-`plugin.<key>.<name>` and edited in the control panel, with environment
-overrides resolved as described above. Tasks are registered as
-`plugin.<key>.<id>` and run on the same tick as everything else. Admin
-pages mount at `/admin/plugins/<key>/<path>`, routes at
-`/api/plugins/<key>/<path>` (admin routes at
-`/admin/api/plugins/<key>/<path>`), board pages at `/plugins/<key>/<path>`.
-The runtime capabilities — `grants`, `data`, `users`, `notify` — are live on
-every context; on a fixture-mode board they reject with a clear error
-instead of pretending.
-
-A few consequences, stated plainly:
-
-- **A page cannot reach anything a task cannot.** Both are handed the
-  runtime context — resolved settings and a logger — and neither gets the
-  `Actor`, the request, or a database handle. An admin page additionally
-  sees the panel URL's query string, which is what a post-redirect-get
-  notice needs and nothing more. There is no per-page permission to
-  declare, because a plugin does not get to make that decision; the acting
-  half lives on routes, where `access: 'admin'` is checked and logged by
-  the host.
-- **A task's failure is not swallowed.** Hooks are isolated because the
-  alternative is a plugin taking down a page render. A task has no page to
-  take down, and the scheduler already records failures and notifies
-  administrators — catching there would turn every failure into a
-  successful run of nothing.
-- **There is no plugin-run button for migrations**, and there will not be.
-  A schema change belongs to the deploy that shipped the code expecting
-  it. The panel reports which migrations have and have not been applied,
-  which is the part an operator cannot otherwise find out.
-- **Disabling is durable and immediate; uninstalling is a command, not a
-  button.** Both switches — the panel's and the host's own, after repeated
-  failures — write a row that every instance reconciles against on its next
-  request, so both survive a redeploy: the plugin somebody switched off at
-  2am is exactly the one that must stay off. Removing a plugin is still
-  `pnpm remove`, a line out of `meith.plugins.ts`, and a redeploy, with
-  `meith plugin:purge` before it when its data should go too. There is
-  no button, because a button that dropped the rows while the code kept
-  running would produce a state neither installing nor removing does.
+Declare the supported plugin API version. Additions use minor versions; removing or renaming a public contract requires a major version. Check compatibility before distributing a package. Package release versions and plugin API versions are separate.
diff --git a/docs/extensions/plugin-pages.md b/docs/extensions/plugin-pages.md
index 55958192a..8e7f03465 100644
--- a/docs/extensions/plugin-pages.md
+++ b/docs/extensions/plugin-pages.md
@@ -1,182 +1,36 @@
 # Plugin routes and pages
 
-Expose plugin HTTP routes and member, administrator or moderator pages. Match each route to its audience and validate inputs at the boundary.
+Define routes and pages in the plugin manifest. Access checks are enforced by the host; validate plugin-specific inputs and permissions in the handler.
 
 ## HTTP routes
 
-A plugin declares endpoints the way it declares everything else — as data —
-and the host mounts them under `/api/plugins/<key>/<path>`:
+| Mount | Use |
+|---|---|
+| `/api/plugins/<key>/<path>` | Public, member and staff routes |
+| `/admin/api/plugins/<key>/<path>` | Admin routes with live admin reauthentication |
 
-```ts
-routes: [
-  { path: 'hook/stripe', method: 'POST', access: 'anonymous', rawBody: true, handler },
-  { path: 'checkout',    method: 'POST', access: 'member',    handler },
-],
-allowedRedirectHosts: ['checkout.stripe.com'],
-```
+Paths match exactly. Disabled plugins and incorrect mounts return `404`. Member routes return `401` when signed out; staff routes require `modcp.access` and return `403` when denied. A per-forum moderator appointment alone does not grant that permission.
 
-A handler receives a `PluginRequest` — viewer, method, path, query, headers,
-a parsed or raw body, the board's URL — plus the same runtime context as
-every other surface, and answers with an envelope:
-`{ kind: 'json' | 'text' | 'redirect', … }`. A route declaring
-`rawBody: true` gets the exact request bytes, which is what webhook
-signature verification needs.
+Protected POST routes check the request origin. Admin POST routes create a `plugin.route` audit entry. The host strips authorisation and cookie headers before passing the request to a plugin.
 
-The host owns every decision a plugin must not:
+| Option | Behaviour |
+|---|---|
+| `rawBody: true` | Receives exact bytes for signature verification |
+| `maxBodyBytes` | Defaults to 64 KiB; at most 1 MiB |
+| `rateLimit` | Process-local sliding limit per caller; excess returns `429` with `Retry-After` |
 
-- **`access` is enforced before the handler runs.** `'member'` answers 401
-  to a guest; `'staff'` answers 403 to anyone without the `modcp.access`
-  permission — the same board-staff check a staff page makes, so a staff
-  page's form can post to its own route; `'admin'` answers 403 to anyone
-  without a live control-panel session — the same check the panel's own
-  screens make, including its re-authentication window. A `'staff'` route
-  mounts on the board, next to `'member'` routes, because that is where a
-  staff page's request comes from. The handler never sees a refused request.
-- **Admin routes mount under the panel, not the board.** An
-  `access: 'admin'` route answers at `/admin/api/plugins/<key>/<path>` and
-  is a 404 on the board mount, and the reverse. The panel's session token
-  is a cookie scoped to the `/admin` path precisely so it never rides an
-  ordinary board request, so an admin endpoint must live where that cookie
-  travels. An admin page's form posts there; `pluginAdminRoutePath` builds
-  the URL.
-- **A member or admin POST must come from the board's own origin.** The
-  `Origin` header is checked against the request's host; a cross-site form
-  post is a 403.
-- **An admin POST lands in the panel's action log** as `plugin.route`, with
-  the plugin key and path, next to every other administrative act. Admin
-  GETs are reads and stay out of the log.
-- **`cookie` and `authorization` never reach the handler**, and the
-  response envelope has no header or cookie field at all. That single
-  restriction is what stops a plugin route from becoming a second
-  authentication system.
-- **Redirects are allow-listed.** A relative path always passes; an
-  absolute URL must be https — plain http only to a loopback address, for a
-  test double — and its host must be declared in `allowedRedirectHosts`, so
-  a compromised setting cannot turn a board route into an open redirect.
-- **Bodies are capped** — 64 KiB by default, `maxBodyBytes` up to 1 MiB.
-- **Every response is `cache-control: no-store`.**
-- **A disabled plugin's routes 404** — operator-disabled and auto-disabled
-  alike. An off plugin has no endpoints, not broken ones.
-- **Failures count.** A route runs under the same accounting as a hook:
-  timed, logged against the plugin, and auto-disabling after repeated
-  failures.
-- **A route can declare its own rate limit** —
-  `rateLimit: { limit, windowSeconds }` — and the host enforces it before
-  the handler runs: a spent window answers 429 with a `retry-after` header.
-  The count is per caller (signed-in user id, else the client address) and
-  per instance, in process memory — abuse-pressure relief, not accounting.
-  A board that scales out multiplies the budget by its instance count;
-  declare limits with that in mind. Counting is sliding-window, weighing
-  the previous window's usage against how much of the current window has
-  elapsed, so a caller who spends a window's full budget cannot double it
-  by timing a second burst just after the window rolls over.
+Rate limits multiply across replicas. Use an external/shared control if the operation requires a global limit. Route failures count toward plugin health.
 
-One honest limit: route paths are exact matches — put ids in the query
-string, not the path.
+Return the supported JSON, text or redirect envelope. Plugins cannot set arbitrary response headers or cookies. Responses are `no-store`.
 
-> [!NOTE]
-> **A form POST cannot 303 off the board.** The board's CSP pins
-> `form-action` to `'self'`, and browsers hold a form submission's whole
-> redirect chain to it — so a member-form route answering a redirect to a
-> payment provider is blocked by the browser, not by the host. The pattern
-> that works, without weakening the policy: 303 to one of your own pages
-> with the target in the query, validate it there against your
-> `allowedRedirectHosts`, and render a meta refresh plus a fallback link.
-> An ordinary navigation is outside `form-action`'s remit. `plugins/dues`
-> ships this as its `go` page.
+Redirect destinations must be allowlisted HTTPS URLs; loopback HTTP is allowed for development. The board's `form-action 'self'` policy blocks cross-origin redirects after form submissions. Use a same-origin handoff page with a validated destination and fallback link; the Dues plugin provides an example.
 
 ## Admin pages
 
-`adminPages` are the operator-facing half, mounted at
-`/admin/plugins/<key>/<path>`. `render` gets a `PluginAdminPageContext` —
-the runtime context plus the panel URL's query string — and returns markup,
-which the panel frames so that the cards a page brings still read as
-raised.
-
-A plugin that declares any pages becomes a *place* in the panel rather than
-a row in a list:
-
-- **A tab bar across the top of every one of its screens**, the plugin's
-  own settings screen included (labelled `Settings`, the first tab). A
-  plugin with one page gets no tab bar, because a single tab is not a
-  choice.
-- **Its own section in the panel's rail**, headed with the plugin's name
-  and listing its pages, whenever the operator is anywhere under
-  `/admin/plugins/<key>`.
-- **Links on its row of `/admin/plugins`**, so the screens are reachable
-  before anyone opens the plugin at all.
-
-Declaring a page is the whole of it — there is nothing to register with the
-nav and no ordering to configure. Pages appear in the order the plugin
-declares them, and a page on a disabled plugin appears nowhere.
-
-**`title` is a label, so keep it short.** It becomes the tab, the rail
-entry and the page heading, and the plugin's name is already above all
-three — `'Plans'`, not `'Dues — plans'`.
+Declare a short title and stable page path. The host adds the page to the plugin's admin navigation and supplies runtime access and query parameters. Admin authentication remains required for each request and action.
 
 ## Board pages
 
-`pages` are the member-facing half, mounted at `/plugins/<key>/<path>` and
-rendered inside the board's shell with the page's declared title, so a
-plugin's screen looks like part of the board:
-
-```ts
-pages: [
-  { path: '',       title: 'Membership', access: 'member',    render },
-  { path: 'return', title: 'Confirming', access: 'anonymous', render },
-]
-```
-
-`render` gets a `PluginPageContext` — the runtime context plus the viewer,
-the path, the query and the board URL — and returns markup. The same
-containment as admin pages applies: a throw is logged and the page renders a
-plain failure notice in the shell, not a 500. `access: 'member'` sends a
-guest to the sign-in page and back afterwards. A page on a disabled plugin
-is a 404, exactly like a route.
-
-As with contributions: build your markup in the render function rather than
-returning a component that does work — the host's try/catch is around the
-call, and a component that throws later inside React's own render cannot be
-contained from the server.
-
-## Staff pages
-
-A board page marked `access: 'staff'` is a moderation-helper screen: the
-place for a plugin's triage list or its report tooling, above an ordinary
-member but below the operator. It is still a `pages` entry — the same
-`render`, the same `PluginPageContext` — with one difference in who may see
-it and where it appears.
-
-```ts
-pages: [
-  { path: 'triage', title: 'Triage', access: 'staff', render },
-]
-```
-
-- **The host enforces it before the render runs.** A staff page answers only
-  to a viewer who holds `modcp.access` — the same board-staff resolution the
-  moderation panel's own screens make (`resolveModCpAccess`), never a check
-  the plugin makes. Anyone else is a 404; the render is never called. This is
-  the page half of the rule that [a plugin never decides
-  authorization](plugins.md): a staff page changes *who* may
-  look at a screen, not *what* the plugin may do once they are looking.
-- **It mounts inside the moderation panel**, at
-  `/modcp/plugins/<key>/<path>`, framed by the modcp `PanelShell` and rail —
-  not on the board, where a `'staff'` page is a 404. A plugin with staff
-  pages becomes its own section in that rail, headed by the plugin's name,
-  exactly as `adminPages` do in the admin rail; declaring the pages is the
-  whole of it.
-- **The context does not widen.** A staff page gets the same
-  `PluginPageContext` as any other — locale, translator, and a `viewer` that
-  is still a `ViewerRef`, never an `Actor`. In particular `context.data` and
-  `context.users` are unchanged: standing in the moderation panel lets more
-  people *reach* the screen, it does not let the plugin *read* more. What a
-  plugin may query is decided where it always was, not by where its page is
-  mounted.
+Page handlers receive the viewer and parsed location. Member-only pages redirect signed-out readers to login. Staff pages appear under the moderator panel and require `modcp.access`.
 
-> [!NOTE]
-> **`modcp.access` is board-wide staff, and that is the whole of the gate in
-> this version.** A per-forum moderator who does not also hold `modcp.access`
-> will not see plugin staff pages, even in a forum they moderate. This is the
-> deliberate v1 boundary — the panel itself draws the same line — rather than
-> a finer per-forum gate a plugin could ask for.
+Use [shared controls](theme-design.md) for forms and navigation, and [plugin navigation entries](plugin-presentation.md#navigation) for links to declared pages.
diff --git a/docs/extensions/plugin-presentation.md b/docs/extensions/plugin-presentation.md
index f4b4c693f..f44b20a63 100644
--- a/docs/extensions/plugin-presentation.md
+++ b/docs/extensions/plugin-presentation.md
@@ -1,293 +1,55 @@
-# Plugin UI and content rendering
+# Plugin UI and Markdown
 
-Add interface content through the published regions and rendering APIs. Keep presentation accessible and translated, and use the host contracts instead of importing board internals.
+## Regions
 
-## UI regions
+Return React content from a declared region's `render` handler. Runtime, locale and translator access are provided by the host.
 
-Regions are not theme slots, and the distinction is deliberate. If a plugin
-could fill a slot, an installed plugin would decide what a post looks like —
-and two plugins filling the same slot would need resolving somehow.
+| Region | Placement |
+|---|---|
+| `header.notice` | Board header notice |
+| `index.footer` | Forum index footer |
+| `thread.header` | Thread header |
+| `postbit.badges` | Post author badges |
+| `postbit.footer` | Post footer |
+| `threadrow.badges` | Thread-list badges |
+| `profile.panel` | Member profile |
+| `admin.dashboard` | Admin dashboard |
 
-A region is the other arrangement: an explicit "plugins may add something
-here" point that a *theme* renders. The theme keeps control of **where**
-plugin output appears; the plugin keeps control of **what** it is; several
-plugins compose by concatenation, in the usual deterministic order.
+Post regions run per post. Avoid repeated queries. `threadrow.badges` receives the page's thread references once and returns a `Map` from thread ID to content. See the [region reference](../reference/plugin-hooks.md).
 
-There are eight: `header.notice`, `index.footer`, `thread.header`,
-`postbit.badges`, `postbit.footer`, `threadrow.badges`, `profile.panel` and
-`admin.dashboard` — described in [Plugin hooks](../reference/plugin-hooks.md).
-The list is short on purpose, because every region is a commitment every theme
-has to render or deliberately drop. `admin.dashboard` is the exception the theme
-never sees: it is rendered by the control panel, on the admin overview below the
-board's statistics. Each contribution there is wrapped in a plugin card.
+## Markdown
 
-**A contribution may be async, and may reach this plugin's runtime.** Its
-`render` receives the same lazy `runtime` accessor a [hook
-handler](plugin-hooks-guide.md#reaching-the-runtime-from-a-handler) does, and may return a
-promise:
+| Filter | When applied |
+|---|---|
+| `markdown.parse.text` | Before parsing |
+| `markdown.render.html` | During rendering |
+| `markdown.directives` | Builds the directive registry |
+| `smilies.list` | Builds the smilie registry |
+| `post.body.html`, `signature.html` | When reading rendered content |
+| `word-filter.patterns` | Builds word-filter patterns |
 
-```ts
-{
-  region: 'thread.header',
-  render: async ({ subjectId, runtime }) => {
-    const { data } = await runtime()
-    const row = await data.one('select title from plugin_example_event where thread_id = $1', [subjectId])
-    return row === null ? null : <EventCard title={String(row.title)} />
-  },
-}
-```
+Stored source remains unchanged. Changes to the rendering plugin signature schedule a backfill; stale content can be rendered on read until it completes.
 
-Mind **where** you do it. `thread.header` runs once per thread page, so a
-query there costs one query. `postbit.badges` runs once per *post* — a
-query there is fifty queries on a fifty-post page, and the region's own
-entry in the reference says so. A contribution that rejects is contained,
-counted and auto-disabled exactly like one that throws.
+HTML added by a plugin is trusted. Escape untrusted content yourself. Word filtering has already run before later HTML filters; inserted text does not receive another pass.
 
-`threadrow.badges` is the exception to the shape above, and its own
-contribution type says so. A forum page lists around twenty threads on a
-50ms budget, so a per-row region there would be twenty calls before the
-page had drawn a row. It runs **once per page** instead: its context carries
-`threads`, every visible row as a `{ threadId, authorId }`, and its `render`
-returns a `Map` keyed by thread id — a badge for the rows it wants to mark,
-nothing for the rest. That lets a plugin answer the whole page in one query
-of its own tables rather than twenty:
+## Editor buttons
 
-```ts
-{
-  region: 'threadrow.badges',
-  render: async ({ threads, runtime }) => {
-    const { data } = await runtime()
-    const rows = await data.query(
-      'select thread_id, kind from plugin_example_flag where thread_id = any($1)',
-      [threads.map((thread) => thread.threadId)],
-    )
-    return new Map(rows.map((row) => [Number(row.thread_id), <Flag kind={String(row.kind)} />]))
-  },
-}
-```
+Provide exactly one of a wrapping `tag` or an `insertion`. For a directive button, set `tag: null` and supply a block insertion such as `:::alert
 
-**A contribution's context also carries `locale` and `t`,** the reader's
-resolved language tag and a translator, the same pair a page context gets. A
-region contribution shows text the same way a page does — resolve a key through
-`t`, falling back to the plugin's own bundled string when the catalogue has not
-translated it — rather than rendering a fixed English literal that ignores the
-reader's language:
+:::`. Include the required label, title, shortcut, icon and placeholder fields, using `null` where permitted.
 
-```ts
-{
-  region: 'thread.header',
-  render: ({ t, locale }) => (
-    <p>{t.has('example.card.title') ? t.t('example.card.title') : en['example.card.title']}</p>
-  ),
-}
-```
+Use the kit's `applyInsertion` helper for wrap/block behaviour. Keep the ordinary textarea and form usable without JavaScript.
 
-## Changing how content renders
+## Navigation
 
-Seven filters reach the render pipeline, and they divide on **when** they
-run — which decides what a plugin can change and what it costs.
+Declare entries that link to the plugin's own pages. Give each a stable key, label and audience; one submenu level is supported.
 
-| Filter | When it runs | What it shapes |
-|---|---|---|
-| `markdown.parse.text` | Write | The source handed to the parser |
-| `markdown.render.html` | Write | The HTML the renderer constructed |
-| `markdown.directives` | Write | The `:::name` and `:name[…]` vocabulary |
-| `smilies.list` | Write | The smilie set substituted at render |
-| `post.body.html` | Read | One post's body, in the thread it is read in |
-| `signature.html` | Read | A member's signature, wherever it appears |
-| `word-filter.patterns` | Read | The render-time word filter's rules |
+Initial entries are seeded into board navigation. Administrators then control labels, order and visibility. Later code updates can change destinations without overwriting those choices. Disabled plugins are hidden; upgrade removes obsolete entries.
 
-**Write** means the filter runs where a body becomes HTML — a new thread or
-reply, an edit, a private message, a saved signature, the composer's
-preview — and its output is what the board stores. That is why those four
-carry no viewer: a stored render is shared by everybody who reads the post,
-so a set of smilies or a rewrite that depended on who was looking would be
-whichever reader happened to write the row first.
+## Copy and controls
 
-**Read** means the filter runs once per body per page view. Nothing is
-stored, so a change takes effect immediately and disappearing when the
-plugin is removed costs nothing.
+Namespace message keys by plugin. Catalogues merge in this order: core, themes, plugins, board overrides. Use the supplied translator and locale; pass that locale to `Intl` formatters.
 
-Two things follow that are worth knowing before you write one.
+Use server-safe exports from `@meith/ui` for static UI. `NavTabs` renders native links; `data-nav-tabs` and `aria-current` enable optional horizontal-tab behaviour. Use the shared plugin card styles for panel content. Import interactive controls from their explicit client subpaths.
 
-**The source is never touched.** `markdown.parse.text` changes what the
-parser is handed; the `message` column still holds exactly what the member
-typed, which is what quoting, editing and the next re-render start from. A
-plugin cannot rewrite somebody's post.
-
-**Installing or removing a formatting plugin re-renders the board.** The
-board records a *rendering signature* — the keys and versions of the
-installed plugins that register any of the four write-time filters. When it
-changes, the content revision is bumped, and `posts.render_backfill` walks
-the board re-rendering every post through the new pipeline. That is what
-makes a formatting plugin apply to the ten years of posts that were there
-before it, and what makes removing one take its markup back out. On a large
-board the sweep takes a while and reports its backlog in `/admin/system`;
-nothing looks broken while it runs, because a row the sweep has not reached
-is rendered in memory when somebody reads it.
-
-> [!WARNING]
-> What `markdown.render.html`, `post.body.html` and `signature.html` return
-> is **trusted output**: it is inserted as markup and nothing escapes it
-> afterwards. `post.body.html` runs after the board's word filter, so a
-> plugin's own additions are not filtered either. This is the same trust an
-> operator extends by installing the plugin at all — but it is the one
-> place where a mistake becomes markup on every page.
-
-### A directive with its own toolbar button
-
-`markdown.directives` only names the syntax; it does not give the member a
-button that writes it. A block directive with nothing to invoke it means
-typing `:::name` by hand, so a plugin that wants an affordance in the
-composer contributes to `view.editor-toolbar` too — the same filter the
-built-in bold, link and table buttons flow through:
-
-```ts
-hooks: {
-  'markdown.directives': (directives) => [...directives, { name: 'alert', block: true }],
-  'view.editor-toolbar': (toolbar) => ({
-    ...toolbar,
-    buttons: [
-      ...toolbar.buttons,
-      {
-        tag: null,
-        insertion: { kind: 'block', text: ':::alert\n\n:::' },
-        label: 'Alert',
-        title: 'Alert',
-        keyShortcut: null,
-        icon: null,
-        placeholder: null,
-      },
-    ],
-  }),
-},
-```
-
-A button carries either `tag` — one of the board's own commands — or
-`insertion`, never both. `EditorTag` is a closed union of the board's own
-formatting commands, so a plugin's own syntax has nothing to set `tag` to;
-`insertion` is the escape hatch, a small serialisable edit a theme runs the
-same way it runs a built-in one:
-
-- `{ kind: 'wrap', before, after }` wraps the selection, or, with nothing
-  selected, places the caret between `before` and `after` — for an inline
-  span like `:name[…]`.
-- `{ kind: 'block', text }` inserts a fixed snippet on its own lines,
-  replacing whatever was selected — for a block like `:::name` above.
-
-Both are plain data: a plugin hands the host a string to insert, never a
-function to call, which is what lets the button cross the RSC boundary into
-a client-rendered theme slot the same way every other view model does. A
-theme runs it with `applyInsertion(field, insertion)`, exported from
-`@meith/theme-kit` beside `applyEditorTag` — a theme that already reads a
-button's `tag` opaquely and hands it straight to `applyEditorTag` needs the
-same one-line addition to also try `insertion`, and the three bundled themes
-show it.
-
-**No extra escaping.** `:::alert\n\n:::` is Markdown typed on the member's
-behalf; once inserted it sits in the textarea exactly like anything typed by
-hand, and from there it flows through the ordinary parser and the ordinary
-`markdown.directives` render path. The button only saves a member from
-memorising the syntax — the directive still has to be registered for
-anything to render from it.
-
-## Asking for a place in the navigation
-
-A plugin with a member-facing page usually wants a link to it. `navigation`
-is how it asks:
-
-```ts
-navigation: [
-  { key: 'plans', label: 'Supporters', path: '', audience: 'members' },
-  { key: 'manage', label: 'Your membership', path: 'manage', audience: 'members', under: 'plans' },
-]
-```
-
-Each entry names one of the plugin's **own** `pages` by path, so a
-navigation item cannot point somewhere the plugin did not build. The host
-writes it into the board's navigation table under `plugin.<key>.<item>` the
-first time the board's menu is built after the plugin appears — no admin
-visit required — and from that moment **the operator owns it**: they rename
-it, reorder it, nest
-it under another item, restrict it to groups, or switch it off on
-`/admin/content/navigation`, exactly as they would a link they added
-themselves. Redeploying does not undo any of that — only the address is
-refreshed from the code, because that is the half the plugin knows better.
-
-The rest follows from it being a real row:
-
-- **`label` is a starting point, not a fixed string.** It is what the item
-  is called until somebody renames it. Give `labelKey` too and the board
-  translates it, until an operator types their own label — at which point
-  theirs wins in every language, which is what they asked for.
-- **`audience` is the default scope** (`all`, `guests`, `members`,
-  `staff`), and the operator can narrow it further to specific groups. It
-  is presentation, not permission: the page re-checks whoever arrives.
-- **`under` is the default nesting.** Name another of the plugin's own
-  items and this one is created as its sub-menu entry. The menu is one
-  level deep, so the item named must itself be top-level. Like `audience`
-  it only seeds the row: the operator re-nests or flattens it afterwards,
-  and a redeploy leaves their arrangement alone.
-- **The item disappears with the plugin.** Switch the plugin off and the
-  link stops rendering; take the plugin out of the build and the row goes
-  at the next `meith upgrade`. An operator's ordering is not lost in
-  between.
-
-Appending to `view.header` instead would put a link where no operator could
-reach it — unnameable, unmovable, and impossible to switch off without
-switching off the plugin.
-
-## Words of its own
-
-A plugin that shows text to a member ships a message catalog and is registered
-with it in `meith.config.ts`:
-
-```ts
-plugins: [{ key: 'dues', plugin: dues, messages: duesMessages }]
-```
-
-where `duesMessages` is `{ [locale]: { [key]: pattern } }`. Plugin catalogs are
-merged after the board's and after any theme's, so a plugin can reword either —
-which is a feature when you mean it and a collision when you do not. Namespace
-your keys with your plugin key, the way settings and tasks are namespaced, and
-name a board key only when overriding it is the point.
-
-A page context — and a [region contribution](#ui-regions)'s context — also
-carries `locale`, the language tag the board resolved for this reader, and `t`,
-the translator built from that language. A plugin renders arbitrary UI rather
-than filling a slot, so unlike a theme it formats its own dates and numbers —
-`new Intl.NumberFormat(context.locale)` rather than `toLocaleString()`, which the
-`no-fixed-locale-format` guard refuses.
-
-Nothing about a plugin's own text is required to be translatable; a plugin that
-ships only `en` works, and its messages fall back to English for every reader.
-[Languages](internationalisation.md) covers the message syntax, the plural
-categories, and how a translator adds a language.
-
-## The generated reference is a gate
-
-[Plugin hooks](../reference/plugin-hooks.md) is written by
-`scripts/plugin-hook-docs.mjs` from the registry. `pnpm verify` and CI run
-`pnpm plugin:docs:check`, which fails when the file and the code disagree.
-Hook documentation goes stale faster than most — a hook is added in the
-feature that needs it and documented, if at all, afterwards — which is why
-this one is a gate rather than a habit.
-
-If the check fails, run `pnpm plugin:docs` and commit the result.
-
-### Shared presentation recipes
-
-Plugin pages can import `buttonVariants`, `controlVariants`, `surfaceVariants`
-and `NavTabs` from `@meith/ui` to match the board's controls and surfaces.
-Navigation links scroll horizontally on smaller screens. `NavTabs` marks the
-strip for the shared enhancer to reveal its active link. Custom strips using
-`PLUGIN_TAB_LIST` should add `data-nav-tabs` and mark their active link with
-`aria-current="page"` for the same behavior.
-Declare `@meith/ui` as a dependency when importing it. The kit's existing
-`PLUGIN_CARD`, `PLUGIN_NOTE`, `PLUGIN_TAB_LIST` and `pluginTabClass` remain
-available and now use those same recipes. These are server-safe exports.
-
-The admin host provides the page heading and navigation. It gives the plugin
-an unstyled content region, so a plugin using `PLUGIN_CARD` does not acquire
-a second panel around its own cards. Calendar and Dues demonstrate shared
-fields, actions and surfaces on public pages and in administration.
+See [Translations](internationalisation.md) and [Tokens and controls](theme-design.md).
diff --git a/docs/extensions/plugin-services.md b/docs/extensions/plugin-services.md
index 068d06752..25a8c591a 100644
--- a/docs/extensions/plugin-services.md
+++ b/docs/extensions/plugin-services.md
@@ -1,167 +1,38 @@
 # Plugin settings, notifications and tasks
 
-Declare settings, notify members and schedule background work through the plugin host. These capabilities depend on the board configuration and its running scheduler.
-
-## Notifications
-
-`context.notify` — on every runtime context — sends a member a notification
-through the board's own system: the bell, an e-mail if the member wants one,
-and a [pushed notification](../operations/web-push.md#web-push) if the board offers push and the
-member asked for it. A plugin first declares its kinds as data:
-
-```ts
-notifications: [
-  { key: 'gift_received', title: 'Somebody gifts you a membership',
-    description: 'A member bought a membership in your name.' },
-  { key: 'renewal_trouble', title: 'A membership payment fails',
-    description: 'Your renewal did not go through; access holds while Stripe retries.',
-    emailByDefault: false, pushByDefault: true },
-],
-```
-
-and then sends against a declared kind:
-
-```ts
-await context.notify.send({
-  userId: recipient,
-  kind: 'gift_received',
-  subject: 'alice bought you a 90-day pass',
-  body: 'It starts the moment the payment confirmed.',
-  href: '/plugins/dues/manage',
-  dedupeKey: `order:${order.id}`,
-})
-```
-
-The host owns the decisions a plugin must not:
-
-- **Every kind is namespaced** — `plugin.<plugin>.<kind>` — and lands as its
-  own line on the member's notification preferences screen, where the
-  member decides which channels it reaches them by. `emailByDefault` and
-  `pushByDefault` set the starting positions — push starts off unless a
-  plugin asks otherwise — and the member's choice wins from then on.
-- **An undeclared kind refuses at send.** Declaring kinds is what makes
-  them legible to members; a plugin cannot invent one on the fly.
-- **The words travel as data.** The subject (up to 200 characters) and body
-  (up to 2,000) are rendered by the board on the bell and in the e-mail —
-  the same template and the same unsubscribe machinery as every core
-  notification.
-- **`href` stays on the board.** A notification links to a board path,
-  never off-site — the plugin's own pages are the place for anything
-  external.
-- **`dedupeKey` coalesces repeats** exactly as core kinds do: raising the
-  same key again bumps a counter instead of stacking rows.
-- **There is deliberately no fan-out primitive.** Sending is
-  member-to-member scale, not broadcast; a plugin that wants to tell
-  everyone something has the announcement system's front door like anybody
-  else.
+Access services through the runtime supplied to a handler. Database-dependent services are unavailable in fixtures.
 
 ## Settings
 
-A setting declares a `type` when its default cannot say enough: `'secret'`
-and `'select'` are strings with extra rules, `'number'` and `'boolean'` are
-usually inferred from the default's own JavaScript type, and `env` names an
-environment variable that overrides whatever the panel stores.
+Declare local setting keys such as `api_key`; the host stores them under `plugin.<plugin-key>.<setting-key>`. The host provides the admin form and validation.
 
-```ts
-settings: [
-  { key: 'secret_key', label: 'API secret', type: 'secret',
-    env: 'MYPLUGIN_SECRET_KEY', required: true, default: '' },
-  { key: 'mode', label: 'Mode', type: 'select', default: 'off',
-    options: [{ value: 'off', label: 'Off' }, { value: 'live', label: 'Live' }] },
-]
-```
+| Type or option | Behaviour |
+|---|---|
+| Secret | Empty default; write-only; a blank submitted value retains the stored secret |
+| Environment override | Takes precedence over the saved value, then the default |
+| Required | Reports missing configuration; does not itself block handlers |
+| Select | Trims and matches case-insensitively; returns the declared casing; invalid values fall back |
+| Number | Does not impose application-specific bounds; validate or clamp before use |
 
-- **Resolution is environment, then board, then default** — the same rule
-  as `APP_URL` and the mail settings. When the variable is set, the panel's
-  box goes inert and says which variable owns it, so nobody edits a field
-  that cannot take effect.
-- **A secret is write-only.** `definePlugin` refuses one with a shipped
-  default (a working fallback credential is a credential in the
-  repository). The panel shows *that* a value is set, never the value, and
-  a blank submit keeps what is stored — the form can never show the current
-  value to re-submit. A secret's value reaches the plugin's runtime context
-  and nowhere else.
-- **`required` reports, it does not block.** An unset required setting is a
-  named problem on the plugin's screen rather than a save that refuses
-  everything else, so a board mid-setup can still be configured a field at
-  a time.
-- **A `select`'s option values are matched case-insensitively and
-  trimmed**, so a stray `DUES_CURRENCY=EUR` or a trailing space from
-  copy-pasting an environment value still finds the option `'eur'`
-  declares — the resolved value is always the option's own declared
-  casing, never the raw input. Declare option values lowercase.
-- **A `select` whose stored value is no longer among its options** — an
-  older version of the plugin declared more — resolves to the default
-  instead of handing the plugin a value it never declared.
-- **A `number` has no minimum, maximum or step to declare.** An unparseable
-  stored or environment value resolves as if unset, falling through to the
-  next source in the same order as everything else; a plugin that needs a
-  bounded number clamps it itself when reading `context.settings` — see
-  `plugins/dues`'s grace-period setting for the pattern.
-- **A setting has no `descriptionArgs`** — unlike a plugin's own top-level
-  description, a setting's `description`/`descriptionKey` is translated with
-  no interpolation. A bound worth stating (a grace period's allowed range, a
-  number's units) belongs in the catalog text itself, kept in sync by hand
-  with whatever constant actually enforces it.
+Setting description translation keys take no arguments. Check required configuration before invoking an external service. Never put secrets in rendered models or logs.
 
-## Scheduled tasks
+## Notifications
 
-A task declares **exactly one** of two cadences, and `definePlugin` refuses
-one that sets neither or both:
+Declare each notification kind with `key`, `title`, `description` and optional `emailByDefault`/`pushByDefault` values. Members' preferences override the defaults.
 
-```ts
-tasks: [
-  { id: 'sweep', intervalSeconds: 900, run: async (ctx) => { /* … */ } },
-  { id: 'digest', schedule: '0 9 * * 1', run: async (ctx) => { /* … */ } },
-]
-```
+Send to a specific `userId` with the declared `kind`, a subject of at most 200 characters, a body of at most 2,000 characters and a same-board `href`. Use a deduplication key for retryable work. There is no unrestricted broadcast service.
 
-- **`intervalSeconds`** is a fixed cadence measured from the end of the last
-  run, with a 60-second floor — the tick is minute-granular at best, so
-  anything under a minute claims a frequency the scheduler cannot deliver.
-- **`schedule`** is a five-field cron expression — `minute hour
-  day-of-month month day-of-week` — **evaluated in UTC**. There is no board
-  timezone to evaluate it against (see [the default timezone is the
-  reader's](../operations/mybb-parity.md)), so UTC is the only honest anchor,
-  and it is stated in the type, in the error `definePlugin` throws, and here.
+## Scheduled tasks
 
-The expression is validated at `definePlugin` time, not at first tick — both
-that it parses and that it can ever occur, so a well-formed impossibility
-like `0 0 30 2 *` (February 30th) is refused rather than left to starve the
-tick when its next-run time cannot be computed. A board with a bad schedule
-fails to start rather than logging a stuck task weeks later. Fields are
-numeric (no `MON` or `JAN` names); `*`, ranges (`1-5`), lists (`0,30`) and
-steps (`*/15`) are understood; `0` and `7` both mean Sunday; and when both
-day-of-month and day-of-week are restricted a day matching **either** one
-runs, the standard cron rule.
+Choose one schedule:
 
-- **The 60-second floor holds for cron too.** A five-field expression is
-  minute-granular by construction — the finest it can ask for is
-  `* * * * *`, once a minute. A sixth (seconds) field is refused for exactly
-  that reason: it would ask for a cadence faster than the tick can deliver.
-- **A scheduled task's first run is its next matching time _after_ it is
-  registered.** It does not fire on install: a `0 9 * * 1` task added on a
-  Wednesday first runs the coming Monday at 09:00 UTC, not the moment it
-  ships.
-- **A missed window fires once, not once per occurrence.** If the worker is
-  down across one scheduled moment — or across several — the task runs a
-  single time on the next tick and is then scheduled forward to its next
-  future occurrence. There is no backfill; a weekly digest that slept
-  through two Mondays sends one digest, not two.
+| Schedule | Accepted value |
+|---|---|
+| Interval | At least 60 seconds |
+| Cron | Five fields, interpreted in UTC |
 
-> [!IMPORTANT]
-> **Task idempotency is unchanged, and a cron schedule does not relax it.**
-> The scheduler can still run a task more than once — two workers racing a
-> claim, a retried tick, a missed window collapsing to a single catch-up
-> run — so a task must be safe to double-fire and resumable from a partial
-> run. Make the work idempotent (upsert, mark-then-act, a claimed cursor);
-> the schedule decides _when_ a run may start, never that a run happens
-> exactly once.
+Cron supports numeric values, ranges, lists and steps; `0` and `7` both mean Sunday. When both day-of-month and day-of-week are restricted, either match is sufficient. Impossible dates are rejected.
 
-The admin panel and the scheduler's health view describe a scheduled task by
-a cadence derived from the gap between its upcoming runs, so a weekly task
-reads as weekly rather than as a task that has not run in seven days.
+A cron task first runs at its next matching time, not immediately on installation. Missed runs produce one catch-up execution. Handlers must be idempotent because work can be retried after a worker fails.
 
-> Core's own tasks are interval-only today. Giving them cron schedules is a
-> possible follow-up; this change adds the capability to the plugin API
-> without converting them.
+The board must run the [scheduler](../operations/scheduled-tasks.md). Use **Admin → Tasks** or `task:list` to inspect execution and failures.
diff --git a/docs/extensions/plugin-storage.md b/docs/extensions/plugin-storage.md
index 652fe46f9..c8e6367df 100644
--- a/docs/extensions/plugin-storage.md
+++ b/docs/extensions/plugin-storage.md
@@ -1,251 +1,44 @@
-# Plugin storage, groups and migrations
+# Plugin storage and membership
 
-Store plugin data, apply forward-only migrations and work with explicitly grantable groups. The namespace and visibility rules are part of the plugin security boundary.
+Use runtime repositories instead of importing the board's database connection. Plugins run in-process; database restrictions do not sandbox arbitrary plugin code.
 
-## Namespacing
+## Namespaces
 
-A plugin's key namespaces everything it registers, and the host builds the
-names, so a plugin cannot collide with another plugin or reach a core name:
-
-| Thing | Name it gets |
+| Resource | Namespace |
 |---|---|
-| Setting | `plugin.<key>.<setting>` |
-| Task | `plugin.<key>.<task>` |
-| Admin page | `/admin/plugins/<key>/<path>` |
-| Message | `<key>.<message>`, by convention rather than by construction |
-
-One name in that namespace belongs to the host: `plugin.<key>._enabled` is
-the operator's kill switch. A plugin cannot declare it — setting names
-cannot start with an underscore — so the collision is impossible rather
-than unlikely.
-
-`definePlugin` refuses a key, setting name, task id or page path that would
-not namespace cleanly: a dot in a plugin key would produce an ambiguous
-setting key, and a slash in a page path would escape the admin prefix.
-
-## Timed group grants
-
-`context.grants` — available on every runtime context — is the only write a
-plugin gets against the board's own data: it can put a member in a usergroup
-**until a date**. That is the whole API, deliberately. A usergroup already
-carries forum permissions, a badge and a name colour, so time-limited
-membership of one is a complete building block — a paid pass, a trial, a
-course cohort, an event's temporary access — and the host does not know or
-care which of these a plugin is building.
-
-```ts
-await context.grants.grant({ userId, groupKey: 'supporters', until, reason: 'order 42 paid' })
-await context.grants.extend({ userId, groupKey: 'supporters', until })
-await context.grants.revoke({ userId, groupKey: 'supporters', reason: 'refunded' })
-const granted = await context.grants.list(userId)
-const isSupporter = await context.grants.holds(userId, 'supporters')
-```
-
-What keeps this from being "a plugin deciding authorization" is the list of
-things the host refuses, checked on every call:
-
-- A group the operator has not marked **"may be granted by plugins"** on its
-  admin screen. The opt-in is per group and off by default.
-- A **system** or **staff** group, or any group whose permission set carries
-  administrative or moderation power. The admin checkbox refuses these too,
-  so the refusal is heard at setup time, not when the first grant fails.
-- A grant with no expiry, an expiry in the past, or one more than two years
-  out. Every grant lapses on its own.
-- A membership **someone else** granted — an administrator's, or another
-  plugin's. `grant` refuses it and `revoke` leaves it alone.
-- An empty `reason`. The reason is stored on the row; it is the audit
-  trail.
-
-A grant is an additive secondary membership by default: the member's primary
-and display groups are left alone, so the group leading their name does not
-change — though the granted group can appear as an extra title, as far as
-[Maximum displayed groups](../administration/groups.md)
-allows — and when the grant ends everything falls back to exactly what it
-was.
-
-**Expiry is true at the read, not enforced by a sweep.** Actor assembly
-skips a lapsed row, so access ends at the boundary even if no task ever runs
-again — uninstalling the plugin, stopping the tick, or the plugin's own bugs
-cannot leave anyone holding access they no longer have. A `groups.expire`
-task deletes lapsed rows afterwards and bumps the permission version so
-derived caches follow. Re-granting and extending only ever move an expiry
-**forward**: a stale or replayed call cannot shorten what a member already
-holds.
-
-### Reading whether a member holds a group
-
-`list` reports only the grants **this plugin** made. `holds` answers a
-different question — *does this member hold this group right now* — and it
-does not care how the membership arose: a primary group, a plain secondary,
-a grant from an administrator or from another plugin all count. The question
-is "holds", not "was granted by me".
-
-```ts
-const isSupporter = await context.grants.holds(userId, 'supporters')
-```
-
-It is **read-side of the same privacy line as the write.** A plugin is never
-handed group membership — the viewer on a payload is `{ userId, isGuest }`,
-never an `Actor` — and `holds` does not widen that. It reads only groups the
-operator has ticked **"may be granted by plugins"**, the same opt-in `grant`
-requires. Ticking it is the operator's consent to make that one group's
-membership plugin-visible, in both directions; every other group stays
-invisible.
-
-So the refusals mirror the write side:
-
-- A group the operator has **not** opted in returns `false` — the same answer
-  as a member who is not in it, and deliberately so. A plugin cannot tell an
-  opted-out group apart from one nobody holds, and cannot probe for a group's
-  existence. A group key that names nothing returns `false` for the same
-  reason.
-- A **system** or **staff** group, or one whose permissions carry
-  administrative or moderation power, is **refused** even if it has somehow
-  been marked grantable — membership of those is never a plugin's to read,
-  exactly as it is never a plugin's to grant.
-
-`holds` reads standing the same way the board itself does: a grant that has
-lapsed confers nothing from the moment it expires, before any sweep deletes
-its row, and a promotion whose grant has lapsed falls back to the group
-behind it. On a fixture-mode board, where there is no membership table, it
-refuses with a clear error rather than guessing.
+| Settings | `plugin.<key>.*`; `_enabled` is reserved |
+| Tables | `plugin_<key>_`; hyphens in the key become underscores |
 
-### Selling the group a member wears
+Keep ordered migrations in the plugin definition, with IDs such as `0001_create_entries`. Migrations run forward only. Never edit an applied migration. Store core identifiers as values rather than declaring foreign keys into core tables.
 
-`primary: true` on a grant asks for more than access — it asks for the group
-to become the member's **primary** one, which is usually what a paid
-membership means to the member buying it:
+## Queries and transactions
 
-```ts
-await context.grants.grant({ userId, groupKey: 'supporters', until, reason, primary: true })
-```
+Use parameterized `query`, `one` and `tx` calls. Nested transactions join the current transaction. Runtime SQL uses a statement timeout and a database role limited to the plugin's tables and sequences. It cannot access core/other-plugin tables or run DDL.
 
-The board does the swap, not the plugin, and it is reversible by
-construction:
+The database login must be able to provision the plugin roles, or an operator must pre-create them. Test migrations and permission boundaries against PostgreSQL before release.
 
-- The group the member was primary in becomes an ordinary secondary
-  membership with no expiry, and the granted row remembers it in
-  `previous_primary_group_id`.
-- A second promotion on top of a first still remembers the group behind
-  *both*, never a group that is itself only held until a date — so a member
-  cannot end up primary in a group they have stopped paying for.
-- On `revoke`, and when `groups.expire` collects the lapsed row, the
-  remembered group is made primary again and the secondary row it left
-  behind is removed.
-- Actor assembly does the same fallback at the read: a promoted primary
-  whose grant has lapsed confers nothing, and permissions are assembled
-  from the remembered group instead.
+## User lookup
 
-All the refusals above still apply, and one more: **a staff member's primary
-group is never displaced.** Where the buyer is already primary in a staff
-group, or a group carrying administrative or moderation power, the promotion
-is silently skipped — the grant still lands as a secondary membership, so
-they get everything the group carries, but their standing is left alone.
-This is not an error and nothing is reported; a plugin has no business
-branching on whether the buyer is a moderator.
-
-`grant` takes a plain `userId`, and nothing ties it to whoever is acting.
-Who may cause a grant for whom — a member for themselves, one member for
-another, an automated rule for anyone — is the plugin's own policy, decided
-in its own code with its own records.
-
-On a fixture-mode board there is no membership table, and every call rejects
-with a clear error rather than pretending.
-
-## A database of its own
-
-`context.data` — on every runtime context — reads and writes the tables this
-plugin's migrations created. Three methods, parameterised only:
-
-```ts
-await context.data.query('insert into plugin_example_entry (user_id, note) values ($1, $2)', [userId, note])
-const row = await context.data.one('select * from plugin_example_entry where user_id = $1', [userId])
-await context.data.tx(async (tx) => {
-  // everything in here commits together or not at all
-})
-```
-
-Three properties are the contract:
-
-- **Values travel as `$1`, `$2`, …** and are bound by the driver. There is
-  no string-building helper, on purpose — the ordinary path is the safe
-  one.
-- **Every call runs under a database-side `statement_timeout`** — short in a
-  page render, longer in a task. This is the one timeout in the plugin API
-  that actually holds, because Postgres can abort a query where JavaScript
-  cannot abort a handler.
-- **`tx` is a real transaction.** A throw rolls the whole body back; a
-  nested `tx` joins the outer one rather than opening a second.
-- **Every statement runs as this plugin's own database role**, which the
-  database only lets touch `plugin_<key>_*` tables — see [below](#the-namespace-is-a-database-boundary).
-
-### The namespace is a database boundary
-
-`definePlugin` refuses a migration whose statements create, alter, drop or
-fill anything not named `plugin_<key>_*` (hyphens in the key become
-underscores) — and refuses a foreign key that reaches outside that
-namespace, because a plugin table referencing a core one couples the
-plugin's schema to the board's and breaks the moment either migrates. Copy
-ids into plain columns instead; the reconcile-and-sweep pattern handles rows
-whose subject has since gone.
-
-`context.data` holds the same line at runtime, and Postgres enforces it.
-Each plugin owns a dedicated database role — `plugin_<key>` — that is granted
-nothing but `select`, `insert`, `update` and `delete` on its own
-`plugin_<key>_*` tables and their sequences. The host runs every
-`context.data` statement inside its transaction after `set local role
-plugin_<key>`, and the role resets when the transaction ends. A statement
-that reads a core table, touches another plugin's table, or attempts DDL is
-refused by the database with `permission denied`, whatever shape the SQL
-takes — so an author who trusts this guard and, by mistake, concatenates a
-request value into the statement text still cannot reach past their own
-tables with it. The role is created and its grants brought up to date when
-the plugin's migrations run, so a board's database user must be able to
-create roles (the bundled Postgres runs as a superuser and already can); a
-managed database whose login lacks that privilege needs the `plugin_<key>`
-roles created once by an administrator.
-
-Stated honestly: this bounds the documented channel, not the process.
-Plugin code runs in the host's process and can still open its own connection
-or read `DATABASE_URL` — installing a plugin extends that trust. What the
-role guarantees is the blast radius of a *bug*: anything issued through
-`context.data` can only ever touch this plugin's own tables.
-
-## Looking up a member
-
-`context.users` resolves a member to the pair a plugin is allowed to see —
-`{ userId, username }` — by name or by id:
-
-```ts
-const recipient = await context.users.byUsername(input)   // null if unknown
-```
-
-It exists because a plugin's own records point at members and its UI asks
-for them by name — "award this to @name" needs an id before anything can be
-stored. Deleted accounts do not resolve.
+| Service | Result |
+|---|---|
+| `byId`, `byUsername` | Minimal user identity; deleted or missing users return `null` |
+| `standing` | Public counts and registration dates for at most 200 users |
+| `scan` | ID-cursor pagination; limit clamped to 0–200 |
 
-`standing(userIds)` returns those pairs plus `postCount`, `threadCount`,
-`reputation` and `registeredAt` (a `Date`) for at most 200 ids; more ids
-throw. `scan({ afterUserId, limit })` returns the same shape in ascending
-user-id order, strictly after the cursor, with the limit clamped to 0–200.
-Both exclude deleted accounts. An empty scan marks the end of a pass; use
-the last returned user id to continue.
+These services do not expose account secrets or arbitrary database rows.
 
-These four public numbers do not move the privacy line: post and thread
-counts, reputation and registration date are already on every postbit.
-Nothing else is exposed — no e-mail, state or groups — for the same reason
-payloads carry a `ViewerRef` and not an `Actor`.
+## Group grants
 
-## Migrations
+The grants service supports `grant`, `extend`, `revoke`, `list` and `holds`. A grant requires a nonempty reason and a future expiry no more than two years away.
 
-Forward-only, like core's, and for the same reason: a down migration that
-drops a column is a data-loss button on a live board.
+An administrator must opt an ordinary group into plugin grants. Power groups are refused. Plugins can manage only their own grants.
 
-Ids look like `0001_add_table` and are applied in sort order.
+| Operation | Constraint |
+|---|---|
+| Grant secondary membership | Default behaviour |
+| Grant primary membership | Set `primary: true`; preserve the prior primary group; never displace staff privileges |
+| Extend | Move expiry forward only |
+| List | Returns grants owned by this plugin |
+| Holds | Returns false for missing or unapproved groups |
 
-> [!IMPORTANT]
-> `definePlugin` refuses a migration list that is not written in ascending
-> order, because the failure would otherwise be silent: a fresh board
-> applies everything, an upgraded board skips the id that sorts before the
-> last one applied, and the two boards end up with different schemas and no
-> error anywhere.
+Expired grants stop authorizing access on read even if the scheduler is stopped. The `groups.expire` task cleans up persisted membership. Test expiry, retries and overlapping membership before using grants for paid access.
diff --git a/docs/extensions/plugins.md b/docs/extensions/plugins.md
index 8eb9e30a6..e2c15616c 100644
--- a/docs/extensions/plugins.md
+++ b/docs/extensions/plugins.md
@@ -1,32 +1,16 @@
-# Plugin development
+# Plugins
 
-A plugin registers behavior with `definePlugin` from `@meith/plugin-kit`. Start with [Write your first plugin](first-plugin.md) to create and run a working example.
+Define a plugin with `definePlugin` from `@meith/plugin-kit`. Start with the [plugin tutorial](first-plugin.md); the generated package includes tests and example services.
 
-## Choose the capability
-
-| You want to… | Read |
+| Capability | Guide |
 |---|---|
-| Transform a view model or react to an event | [Hooks and lifecycle](plugin-hooks-guide.md) |
-| Put content in a page region or editor | [UI and content rendering](plugin-presentation.md) |
-| Store data or grant an approved group | [Storage, groups and migrations](plugin-storage.md) |
-| Handle requests or add board/staff/admin pages | [Routes and pages](plugin-pages.md) |
-| Expose settings, send notifications or run tasks | [Settings and services](plugin-services.md) |
-| Look up exact names and payloads | [Generated hook reference](../reference/plugin-hooks.md) |
-
-## Respect the host boundary
-
-Plugins use the host context and published interfaces. Do not import domain packages, database adapters or application internals. A plugin's tables stay in its own namespace; migrations must not alter core tables or create foreign keys to them.
-
-Validate input received through routes and forms. Staff pages and member pages have different access requirements. A plugin must not infer that being installed grants it permission to reveal a member, group or piece of content.
-
-Filters return a new value. Events react to a completed action; their return value is ignored. The host isolates failures, but you should still handle expected errors and make retryable work safe to repeat.
-
-## Register and deploy
-
-A plugin must be installed and statically registered in the board before a build. Follow [Install plugins and themes](../operations/installing.md). Commit the package and registry changes, build, deploy and apply its migrations before relying on stored plugin data.
-
-Disabling a plugin, removing its code and purging its data are different operations. Back up first and follow the removal procedure when data must be deleted.
+| Modify models or react to events | [Hooks and lifecycle](plugin-hooks-guide.md) |
+| Add HTTP endpoints and panel pages | [Routes and pages](plugin-pages.md) |
+| Read settings, notify members or schedule work | [Services](plugin-services.md) |
+| Store data or grant membership | [Storage](plugin-storage.md) |
+| Add regions, navigation or Markdown | [Presentation](plugin-presentation.md) |
+| Look up hook payloads | [Generated reference](../reference/plugin-hooks.md) |
 
-## Maintain compatibility
+Keep keys, settings and tables in the plugin's namespace. Use runtime services for board data and permission checks. Plugins execute inside the board process; install trusted code only.
 
-Version the plugin, retain applied migrations unchanged, and document configuration and permissions. Test the declared Meith compatibility range before [publishing a listing](marketplace.md).
+A plugin cannot replace a theme slot. Use a region or filter for additions and a [theme](themes.md) for structural changes.
diff --git a/docs/extensions/theme-contract.md b/docs/extensions/theme-contract.md
index e68ba9f30..5b20a8acf 100644
--- a/docs/extensions/theme-contract.md
+++ b/docs/extensions/theme-contract.md
@@ -1,421 +1,53 @@
-# Theme contracts and compatibility
+# Theme contract
 
-Understand the theme boundary, slot compatibility, translation and versioning rules before changing a theme implementation.
+A theme supplies React components for named slots. The app authorizes the request, builds models, resolves slots and passes rendered regions into them. See the [generated reference](../reference/theme-slots.md) for every slot and model.
 
-## What a theme renders
+## Slots and inheritance
 
-Every page a member, moderator or administrator can open is rendered through
-slots. The registry declares 36, all of them stable. They fall into four
-groups:
+Declare the slot map literally, with imported component identifiers. Child overrides take precedence; omitted slots come from the nearest ancestor.
 
-| Group | Slots | What it is |
-|---|---|---|
-| The frame | `Shell`, `Header`, `UserPanel`, `Navigation`, `Footer`, `Notice`, `ForumJump`, `ErrorNotice`, `RedirectNotice` | Wraps every page, including the error pages |
-| Reading | `BoardIndex`, `CategoryBlock`, `ForumRow`, `ForumDisplay`, `ThreadRow`, `ThreadView`, `PostBit`, `PostActions`, `QuickReply`, `Pagination`, `SubforumList`, `Announcement`, `BoardStats`, `WhoIsOnline`, `LatestThreads`, `LatestPosts`, `MemberProfile` | The board itself |
-| Finding | `SearchForm`, `SearchResults`, `DiscoveryView` | Search, and the "new posts" listings |
-| Doing | `PostForm`, `EditorToolbar`, `AuthPage`, `PanelShell`, `PanelNav`, `PanelPage`, `PanelSection` | Writing, signing in, and all three control panels |
+Slots must not read the database, request state or permissions, build destination URLs, or resolve other slots. The app resolves nested slots and passes their rendered output through `regions`, so child overrides apply consistently.
 
-**The three control panels are one set of slots, not three.** The member,
-moderator and administrator panels share a shape — a rail of sections beside
-a page with a heading — so they are `PanelShell` + `PanelNav` + `PanelPage` +
-`PanelSection` between them, and `PanelKind` (`usercp` / `modcp` /
-`admincp`) tells a theme which panel it is rendering. This is what makes the
-admin panel themeable at all: its forty-odd screens fill `PanelPage`'s body
-with app-rendered forms, and a theme restyles every one of them by
-overriding the frame once.
+`PanelPage` receives the panel kind (`user`, `mod` or `admin`) and a `panel` or `standalone` frame. Online, statistics and report pages can use the standalone frame. Forms are app-owned children; themes do not receive server actions as model fields.
 
-**`PanelPage` also frames three pages that are in no panel** — who's online,
-the board statistics and the report form are panel-shaped with no rail
-beside them. `PanelShell` centres the pages inside it, so a `PanelPage`
-rendered under one must not centre itself; the three standalone pages have
-no shell, so there it must. `PanelPageModel.frame` (`panel` /
-`standalone`) says which case a theme is rendering.
+## Server and client slots
 
-**What a theme does not own** is the body of an individual settings screen.
-A form posting to a Server Action never crosses the theme contract as data,
-so an admin screen's controls arrive as `children`, and a theme restyles
-them through the tokens the `@meith/ui` primitives read rather than by
-replacing their markup.
+Slots declare their execution mode. `QuickReply` and `EditorToolbar` are client slots; the remaining slots are server-rendered. Client slot modules need `"use client"`.
 
-## What a theme can and cannot do
+Use `QuickReply`'s provided form children and `EditorToolbar`'s prepared model. Preserve native submission and textarea behaviour when JavaScript is unavailable.
 
-**A theme may:**
+## Models and copy
 
-- Fill any slot in the registry with a component.
-- Inherit from another theme with `extends` and override only the slots it
-  cares about. Resolution is shallowest-wins per slot, and an override is
-  total.
-- Ship its own token values, which an operator can then override without
-  touching the theme.
-- Ship its own message catalog, and reword the board's messages with it.
+Models are serialisable values, without database rows, `Date` objects or functions. Use supplied `CountModel` and `TimeModel` labels; do not reformat them in the theme.
 
-**A theme cannot:**
+The app resolves theme copy before calling a slot. Use prepared labels instead of translator lookups inside components. Namespace theme message keys. Configured theme catalogues are merged even when a different theme is selected.
 
-| It cannot | Because |
-|---|---|
-| Read the database, the request, cookies or the session | `@meith/theme-kit` depends on no workspace package at all, and dependency-cruiser makes a theme's import of `@meith/db`, a driver or a domain package a hard error |
-| Decide anything about permissions | `ViewerModel.canAccessAdminCp` and its siblings are rendering hints the Authorizer has already resolved. Anything a viewer must not see is not in the model at all — CSS is not authorization |
-| Build a URL | Every href arrives resolved, so the board can change its URL shape without breaking installed themes |
-| Render another slot | Slots are flat. The page composes them and passes rendered output in `regions`; there is no way to reach the resolved theme from inside a slot |
-
-## Words and numbers
-
-A slot receives a view model and its own resolved words — nothing else. There
-is still no locale to reach for and no translator to call, in the same way
-there is no database. **The app formats; the theme renders.** Anything the app
-already knows arrives pre-written: a timestamp crosses as a `TimeModel`, and a
-counter as a `CountModel`.
-
-```tsx
-export function ForumRow({ forum }: { forum: ForumRowModel }) {
-  return (
-    <span>
-      {forum.postCount.label} {forum.postCount.value === 1 ? 'post' : 'posts'}
-    </span>
-  )
-}
-```
-
-`label` is the string — grouped by the reader's language, so `1,204` on an
-English board and `1.204` on a German one. `value` is the number, for the work
-a string cannot do: pluralising a noun, hiding a zero, sizing a bar. Rendering
-`value` directly is the bug this shape exists to prevent, and so is reaching
-for `toLocaleString` — with a locale it pins every board to one language,
-without one it follows the *host*, so the server and the browser disagree. The
-`no-fixed-locale-format` guard refuses both.
-
-A number your theme worked out for itself — "and 12 more" over a list you
-sliced — is yours to render as plain digits. The rule covers what the app hands
-you, and the app hands you a `memberCount` rather than making you count
-`members.length`.
-
-**Put your own words in a catalog, and read them through `copy`.** Every slot
-component takes a second prop, `copy: SlotCopy` — `Readonly<Record<string,
-string>>` — carrying whatever your theme registered for that slot, already
-resolved for the viewer:
-
-```tsx
-import { defineTheme } from '@meith/theme-kit'
-
-function whoIsOnlineCopy(t: Translator): SlotCopy {
-  return {
-    'clubhouse.whoIsOnline.heading': t.t('clubhouse.whoIsOnline.heading'),
-    'clubhouse.whoIsOnline.empty': t.t('clubhouse.whoIsOnline.empty'),
-  }
-}
-
-export const clubhouseTheme = defineTheme({
-  key: 'clubhouse',
-  title: 'Clubhouse',
-  slots: { WhoIsOnline },
-  copy: { WhoIsOnline: whoIsOnlineCopy },
-})
-```
-
-```tsx
-function WhoIsOnline({ total, copy }: WhoIsOnlineModel & { copy: SlotCopy }) {
-  return <h2>{copy['clubhouse.whoIsOnline.heading'] ?? 'clubhouse.whoIsOnline.heading'}</h2>
-}
-```
-
-A missing key renders as itself, the same fallback every other copy record in
-the app uses. The values themselves come from your theme's own message
-catalog — a `messages` bundle registered alongside `slots` and `copy` in
-`meith.config.ts`:
-
-```ts
-export const clubhouseMessages = {
-  en: { 'clubhouse.whoIsOnline.heading': 'In the clubhouse' },
-  de: { 'clubhouse.whoIsOnline.heading': 'Im Klubhaus' },
-}
-```
-
-Because a theme's catalog is merged over the board's, the same mechanism lets a
-theme reword the board itself — registering `nav.home` renames *Home*
-everywhere, in every language you supply it for. [Languages](internationalisation.md)
-has the message syntax and the merge order.
-
-**Namespace your own keys.** More than one theme can be registered on the same
-board — a member picks between them in *Your control panel → Appearance* — so
-two themes' catalogs are merged into the same registry at once. A bare key
-like `heading` collides the moment a second theme defines one; `clubhouse.
-whoIsOnline.heading` cannot, because no other theme owns the `clubhouse.`
-prefix. The app resolves your copy with its own translator — which already
-holds every registered theme's messages, not only the active one's — so it is
-your key names, not the merge, that keep themes apart.
-
-A slot your theme fills but has nothing of its own to say for gets `copy: {}`.
-There is nothing to register for it, and nothing to read.
-
-## Theme switching
-
-**A member can switch the whole theme, components included.** Every
-registered theme is in the bundle and resolved at module load — an `extends`
-chain cannot change between requests — but *which* resolved map a request
-renders is a per-request choice, made by `currentTheme()` from a cookie. The
-choice works with JavaScript off, and because the server reads it, the page
-arrives already correct: no flash, no second paint.
-
-**`?theme=<key>` on any page sets that cookie**, so a theme can be linked
-rather than described: `https://board.example/f/3-general?theme=phasebook`
-opens that forum in Phasebook and keeps it for the rest of the visit. The
-middleware writes the cookie and redirects to the same URL without the
-parameter, so what a reader shares is the page, not the paint. The key is
-validated in `currentThemeKey()`: a theme that is not registered, or that
-the board has disabled, falls back to the board default rather than
-erroring.
-
-Consequences for a theme author:
+## Selection and tokens
 
-- **`assertThemeContract` runs over every registered theme**, not only the
-  board's default. An incomplete theme used to be a latent 500 on whatever
-  page reached its missing slot; now that members can pick any enabled
-  theme, it is a boot failure naming the slots.
-- **A theme that fills no slots is a palette**, and that is a supported
-  shape: picking it repaints the board and leaves the markup to the default
-  theme. It is how a board offers three looks without maintaining three
-  sets of components.
-- **Pairing rules matter.** If a theme's `ForumRow` only makes sense inside
-  its own `CategoryBlock`, both must be overridden together — a member can
-  now switch to the theme and hit the combination an operator never would.
+The board's default theme is the fallback. Selecting a theme through the query parameter stores the choice in a cookie and redirects to remove the parameter. All registered themes must satisfy the slot contract.
 
-### The post anchor
+Tokens inherit from the parent theme. Override matching containers and rows together when changing their structure. See [Tokens and controls](theme-design.md).
 
-Resolving every href leaves the *other* end of a link to the theme.
-`PostBit` anchors each post at **`post-<post.number>`** — the number in its
-corner — and that is the whole scheme: `permalink` points at it, and so does
-every link the board writes once the thread page has resolved it.
+## Post links
 
-Nothing links a post by its id in a fragment. A link that has to survive
-deletions carries `?post=<id>` in the query instead, and the thread page
-turns that into the page holding the post plus this anchor. A theme that
-anchors a post by `post.id` leaves every such link at the top of the page.
-
-The anchor is also the one hook a theme has for showing *which* post a link
-landed on: the default theme paints the targeted card's border in `primary`
-through the `:target` pseudo-class (Tailwind's `target:` variant), so a
-reader arriving from a notification or a quote sees the post the link meant
-rather than only the scroll position. `globals.css` already gives every
-`:target` a `scroll-margin-block-start` of 5rem, so the highlighted card
-clears the top of the viewport — and the default theme's header, which is
-sticky and 3.5rem tall. A theme with a taller sticky header sets a larger
-margin on its own posts; a theme whose header scrolls away inherits the
-extra room and loses nothing.
-
-## What the freeze covers
-
-| Covered | Not covered |
-|---|---|
-| The name and `kind` of every **stable** slot | A **provisional** slot's name and `kind` are stable, but nothing today is provisional — see below |
-| The fields of the model a stable slot is handed | Fields of a provisional slot's model |
-| `defineTheme`, `resolveTheme`, `requireSlot`, `slotCopy`, `hasSlot`, `assertComplete`, `assertThemeContract`, `checkThemeContract` | Anything not re-exported from `packages/theme-kit/src/index.ts` |
-| `SLOTS`, `SLOT_NAMES`, `SLOT_STABILITY`, `isSlotName`, `slotKind` | The markup, class names and token *values* of the shipped themes |
-
-> [!IMPORTANT]
-> The last row is worth reading twice. `themes/default` is a reference
-> implementation, not an API. A theme that extends it inherits its markup
-> and therefore its changes. Copying it is supported and inheriting is
-> better — but neither makes its DOM a promise.
-
-### Provisional slots
-
-A slot is named in the registry as soon as it is designed, which can be
-before any page renders it. Naming it early keeps the slot list from being
-retrofitted onto a finished page later, but a props contract nobody has
-rendered yet is a guess — so a new slot ships `provisional` in
-`SLOT_STABILITY`, excluded from the freeze and from `assertThemeContract`,
-until a page actually hands its model to a component. Once that happens the
-slot is promoted to `stable` in the same change, per the shape that turned
-out to render rather than the one guessed at the outset.
-
-`QuickReply` and `EditorToolbar` — the registry's only client slots — carried
-this status the longest: named from early on, rendered by no page until
-`0.17`. Nothing is provisional today; every slot in the registry has been
-rendered at least once.
+Set each post's anchor to `post-${post.number}`. Durable links use the post ID in `?post=`, so they survive pagination changes. Keep `:target` visible below the header; the default scroll margin is 5rem. Adjust it if the header height changes.
 
 ## Versioning
 
-`THEME_API_VERSION` (currently `0.24`) is `major.minor`, and both halves are
-promises:
-
-| Bump | What may land | What it costs you |
-|---|---|---|
-| **minor** | Additive only: a new slot, a new optional model field, a new export | Nothing. Every existing theme keeps working; upgrading is a redeploy |
-| **major** | Removals and renames — but only for things scheduled through `DEPRECATIONS` at least one major earlier | Work you were warned about |
-
-There is no patch component: this is a type-level contract with no runtime
-behaviour of its own, so a bug fixed in `resolveTheme` is a package version,
-not an API version.
+The theme API is separate from the package release version. Additive optional fields use a minor API version. Required fields, removals and renames are breaking changes. Deprecated fields remain available through the documented deprecation cycle; use their replacement in new code.
 
-> [!NOTE]
-> **The major is `0`, and the freeze is still real — with one exception, so
-> far.** Meith has not shipped 1.0, so the major these rules count toward is
-> the one that ships with the product. Every minor up to `0.13` was additive
-> whatever the major said: `0.10` added five slots and removed nothing, `0.11`
-> through `0.13` added only optional model fields.
->
-> `0.14` is the exception and is recorded here rather than glossed. It retyped
-> every counter a theme renders — `postCount`, `replyCount`, `total` and the
-> rest — from `number` to [`CountModel`](../reference/theme-slots.md#countmodel), so a
-> theme written against `0.13` fails to compile against it. That is a major's
-> change landed in a minor, and it was landed that way because Meith is
-> pre-1.0 and no board runs on it: the alternative was carrying a second field
-> beside every counter until 1.0 to avoid breaking themes that do not exist.
->
-> `0.15` is back to ordinary: every slot component now receives a `copy` prop
-> beside its view model — the theme's own words, resolved server-side — but a
-> theme's existing implementation still compiles unchanged, because it was
-> never required to declare every prop it is handed. Only the app, which is
-> the sole caller of `requireSlot`, had to change: it now resolves `slotCopy()`
-> for every slot it renders. See [Words and numbers](#words-and-numbers).
->
-> `0.16` is additive again: [`LinkModel`](../reference/theme-slots.md#linkmodel) gained
-> `newTab` and `submenu`, both optional, because the board navigation is now a
-> list an administrator edits — its links may leave the board, and they may
-> have one level of links under them. A `linkTarget(link)` helper is exported
-> beside them: spread onto an anchor it writes the `target` and the `rel` that
-> has to accompany it. A theme that ignores both fields still compiles, and
-> renders the top level as an ordinary row of links.
-> [`UserPanelModel`](../reference/theme-slots.md#userpanel) also gained
-> `regions.notifications`, the app-rendered notifications menu — one control
-> that opens notifications, private messages and, for staff, the moderation
-> queue in tabs. A theme places it where the two unread counts used to sit; a
-> theme that ignores it falls back to `unreadNotifications` and
-> `unreadMessages`, which is what keeps the field additive.
->
-> `0.17` promotes [`QuickReply`](../reference/theme-slots.md#quickreply) and
-> [`EditorToolbar`](../reference/theme-slots.md#editortoolbar) from provisional to
-> stable: the thread page now renders the quick-reply island through
-> `QuickReply`, and the composer's formatting toolbar — bold, italic,
-> strikethrough, link, quote, code, spoiler, both list markers, heading, and
-> the attachment picker — renders through `EditorToolbar` on the new-thread,
-> reply and edit-post pages. Wiring them up found both models the wrong
-> shape, so both changed at the same time they froze — legitimate only
-> because neither had ever been rendered (see
-> [Provisional slots](#provisional-slots)):
-> [`QuickReplyModel`](../reference/theme-slots.md#quickreply) traded its unused `action`
-> URL for `children`, the app's reply form (Server Action, drafts, quoting,
-> attachments, unchanged) — the same reversal
-> [`PostFormModel`](../reference/theme-slots.md#postform) went through earlier.
-> [`EditorToolbarModel`](../reference/theme-slots.md#editortoolbar) gained `groupLabel`
-> and `attachment`, the picker's button, and its `buttons` are now
-> [`EditorToolbarButtonModel`](../reference/theme-slots.md#editortoolbarbuttonmodel) —
-> each one a `tag` naming a formatting command from the new `EditorTag`
-> export, plus a `title`, `keyShortcut` and `placeholder` a theme renders
-> without inventing any wording of its own. `applyEditorTag` and
-> `applyEditorEdit`, also new exports, are what a tag *does* to a textarea —
-> the other half of the boundary a client slot draws, since a theme's button
-> and the composer's own keyboard shortcut both have to run the same edit
-> without either one calling into the other's React tree.
->
-> `0.18` is additive: [`ThreadRowModel`](../reference/theme-slots.md#threadrow) gained
-> `visibility` — `'visible'`, `'unapproved'` or `'deleted'`. A forum listing only
-> ever carries a held or removed thread for a viewer allowed to see one, so a
-> theme that marks it — the built-ins add a badge and a faint tint — is drawing
-> something only staff will meet. The field is optional: a theme written against
-> `0.17` treats every row as visible, which is what its reader saw anyway.
->
-> `0.21` is additive: the `EditorTag` export gains three commands — `image`,
-> `taskList` and `table` — so the composer's `EditorToolbar` renders three more
-> buttons: an image by URL (`![alt](https://example.com/image.png)`), a task-list line (`- [ ]`), and a
-> 2×2 table skeleton. A theme reads a button's `tag` and hands it to
-> `applyEditorTag`, so a theme that treats the tag opaquely needs no change; a
-> theme that maps each tag to its own glyph adds three entries to render the new
-> buttons, the way the bundled themes do.
->
-> `0.22` is additive: [`ThreadRowSlotModel`](../reference/theme-slots.md#threadrow)
-> gained `regions.pluginBadges`, the `threadrow.badges` plugin region, so a
-> plugin can mark threads in a forum listing the way `postbit.badges` marks a
-> post's author. A theme places it beside the thread's own flags — the bundled
-> themes render it in the row's title line. It is optional: a theme written
-> against `0.21` compiles and simply shows no plugin badges. The region runs
-> once per page rather than once per row, so a listing of twenty threads costs
-> one call — a plugin detail the theme never sees, but the reason the field is
-> safe to render on the board's tightest listing.
->
-> `0.23` grows a field rather than only adding one, in the way `0.14` did, and
-> is recorded rather than glossed for the same reason:
-> [`EditorToolbarButtonModel`](../reference/theme-slots.md#editortoolbarbuttonmodel)'s
-> `tag` becomes `EditorTag | null`, and the model gains `insertion`, an
-> `EditorInsertion | null` carrying a plugin's own edit as data — for a
-> directive registered through `markdown.directives`, which has no
-> `EditorTag` to squat on. Exactly one of the two is ever set. Unlike `0.21`,
-> a theme that treats `tag` opaquely does **not** get to skip this one: every
-> theme renders `EditorToolbar` by handing a button's `tag` straight to
-> `applyEditorTag`, so `tag`'s new `null` case fails that call at compile
-> time regardless. It costs the three bundled themes two changes, not one: a
-> branch that tries `insertion` — run with the new `applyInsertion` export
-> the same way — when `tag` is `null`, and, because a plugin's button keys
-> and glyphs off no `EditorTag` at all, a `key` and a fallback glyph no
-> longer derived from `tag` alone. Neither is a reshaping of anything the
-> theme already draws, which is why it is a minor and not the major the
-> field-typing table above would otherwise call for: Meith is pre-1.0, so as
-> with `0.14`, the alternative was carrying a second, still-required field
-> beside `tag` until 1.0 for boards that do not exist yet.
->
-> The cost is not only the consumer's. `insertion` is **required**, so an
-> existing third-party plugin that already contributes a button through
-> `view.editor-toolbar` fails to compile too, until it adds `insertion: null`
-> beside the `tag` it was already setting — the producer side of the same
-> break, and the reason the standing note below now names plugins as well as
-> the app.
->
-> `0.24` is additive: [`ThreadViewModel`](../reference/theme-slots.md#threadview)
-> gains `watch`, a one-tap subscribe/unsubscribe control for the thread
-> header — following used to live only at the foot of the thread, a `<select>`
-> and a button past fifty posts a reader had to find first. `watch` is
-> `null` for a guest and on a board with no subscription service, and
-> optional the same way the foot-of-thread cadence picker in
-> `regions.afterContent` already was: a theme written against `0.23`
-> compiles and renders no toggle. The two controls are not the same thing —
-> `watch` is on/off only, always at the board's default cadence, and the
-> cadence picker it sits beside is still where a member reaches daily or
-> weekly digests.
-
-> [!NOTE]
-> Adding a **required** field to an existing model is a breaking change even
-> though nothing is removed. For every model but `EditorToolbarButtonModel`
-> the app is the only producer, and a theme cannot fail to supply one; a
-> plugin contributing through `view.editor-toolbar` is a second producer; see
-> `0.23` above for what a required field cost that one when it landed. In
-> practice new fields are added as optional, and themes — and, for this one
-> model, plugins — ignore them until they want them.
-
-## Deprecation
-
-No slot is currently deprecated. One field is: `PostBitModel.quoteSource`,
-deprecated in 0.5 and scheduled out at 1.0 in favour of
-`PostBitModel.post.id`. It is the first entry through this machinery — and
-it is machinery, not prose:
-
-1. **Mark and schedule.** The slot is marked `deprecated` in
-   `SLOT_STABILITY`, and an entry is added to `DEPRECATIONS` naming when it
-   was deprecated, which major removes it, what replaces it, and why.
-   `assertDeprecationPolicy` refuses a mark with no schedule and a schedule
-   with no mark.
-2. **It keeps working.** A deprecated slot is still required of a theme,
-   because a page still renders it in this version.
-3. **It is reported.** `checkThemeContract` lists deprecated slots a theme
-   still fills in `deprecatedInUse`, so the admin theme screen and a
-   theme's own CI can both see the removal coming. A deprecated *field* is
-   visible in the type and the generated reference instead — no runtime
-   report can tell whether a theme reads a prop.
-4. **It is removed at the scheduled major — and if it is not, the build
-   fails.** `assertDeprecationPolicy` throws once the current version
-   reaches `removeIn`. A deadline that can pass quietly is how a
-   deprecation becomes permanent, so this one cannot.
-
-A field is scheduled the same way, as `Model.field`. A whole model is never
-deprecated on its own: a model exists because a slot is handed it, so
-removing the slot *is* the deprecation.
-
-## The generated reference is a gate
-
-[Theme slots](../reference/theme-slots.md) is written by `scripts/theme-api-docs.mjs`
-from the source files that *are* the contract. `pnpm verify` and CI run
-`pnpm theme:docs:check`, which fails when the file and the code disagree —
-so a change to the theme contract cannot land without the documentation
-change appearing in the same diff, which is exactly when a reviewer should
-be asked whether the change is allowed at all.
-
-If the check fails, run `pnpm theme:docs` and commit the result.
+| API version | Contract change |
+|---|---|
+| 0.14 | Counts changed from numbers to `CountModel` |
+| 0.15 | Prepared copy fields |
+| 0.16 | Link `newTab`/submenu fields and user-panel notifications |
+| 0.17 | Stable `QuickReply` children and `EditorToolbar` model |
+| 0.18 | Thread visibility |
+| 0.21 | Image, task-list and table formatting |
+| 0.22 | Thread-row plugin badges |
+| 0.23 | Nullable toolbar `tag` and required `insertion`; plugin button producers must also update |
+| 0.24 | Watch controls |
+
+`PostBitModel.quoteSource` is deprecated since 0.5 and scheduled for removal in 1.0. Use `post.id` instead.
+
+Run the contract and deprecation checks when changing the API. Regenerate the reference with `pnpm theme:docs`; do not edit it directly.
diff --git a/docs/extensions/theme-design.md b/docs/extensions/theme-design.md
index 72bf7fea6..93bc98571 100644
--- a/docs/extensions/theme-design.md
+++ b/docs/extensions/theme-design.md
@@ -1,344 +1,47 @@
-# Theme tokens and shared controls
+# Theme tokens and controls
 
-Customize visual tokens and reuse the shared controls. Preserve readable contrast, touch targets and keyboard access across themes.
+## Palettes
 
-## Tokens
+Use token names from the default theme. Provide separate light and dark palettes; legacy flat overrides apply to both schemes.
 
-A theme ships `LIGHT_TOKENS` and `DARK_TOKENS` using the same **names** the
-default theme declares. `globals.css` maps each name to a Tailwind utility,
-so a renamed token is a utility pointing at nothing. The values are the
-theme's own.
+The compiled default palette is followed by the board default and its overrides in `:root`/`.dark`. Other themes emit scoped differences from that board default. Keep foreground/background pairs readable in both schemes.
 
-Only the default theme's values are compiled into the stylesheet. Any other
-theme's palette is emitted into `<head>` as the *difference* from that
-baseline, so a board on the default theme pays nothing for the mechanism,
-and a board on any other theme gets its colours without redeploying CSS.
+`BROWSER_THEME_COLOR` uses a hex background colour. Colour helpers support the documented hex and OKLCH forms and return `null` for unsupported input.
 
-The cascade, in order:
+Use semantic tokens for backgrounds, text, borders, focus and status. Avoid hardcoded colours that bypass the selected theme.
 
-```text
-compiled defaults                       (globals.css)
-  → the board default theme's values + its overrides + its custom CSS   :root / .dark
-    → each other enabled theme's difference from that   [data-theme="<key>"]
-```
+## Shared components
 
-The scoped blocks carry only what a theme disagrees with the *board
-default* about — not its difference from the compiled stylesheet — because
-the unscoped block is still in force when `data-theme` names another theme.
-Diffing against the wrong side is the bug that leaks one theme's brand
-colour into another's palette with nothing failing anywhere.
+The main `@meith/ui` barrel is server-safe. Interactive controls use explicit client subpaths.
 
-Operator overrides (`themes.token_overrides`) are keyed by colour scheme:
-
-```json
-{ "light": { "primary": "#1d4ed8" }, "dark": { "primary": "#93c5fd" } }
-```
-
-A flat `{ "primary": "…" }` map is still read and means both schemes —
-that is what rows written before per-scheme overrides existed hold, and
-what an exported version-1 document carries.
-
-`BROWSER_THEME_COLOR` is the one place a literal colour belongs in a theme:
-`<meta name="theme-color">` is ignored by Safari and older Chrome when
-given `oklch()`. Keep it equal to the two `background` tokens converted to
-hex — a test enforces the pair, because a hand-written copy goes stale
-silently.
-
-### Converting a token to sRGB
-
-`@meith/theme-kit` exports the colour maths the board itself uses on
-tokens — `parseColour`, `oklchToRgb`, `rgbToOklch`, `rgbToHex`,
-`formatOklch`, `relativeLuminance` and `colourToHex`, the last of which
-takes either notation and answers a six-digit hex or `null`.
-
-They are exported because more than one surface needs them and every copy
-is a copy that drifts: `<meta name="theme-color">`, the contrast readouts
-and the OKLCH picker on the theme screen, and **outgoing mail**, which
-must be hex because no mail client parses `oklch()`. A theme that computes
-a colour of its own should reach for these rather than carry its own
-matrices.
-
-`colourToHex` answers `null` for anything it cannot read — a named colour,
-an `rgb()` string, a `color-mix()` — so a caller falls back to a value it
-chose rather than emitting something a client will ignore.
-
-### The default palette is neutral on purpose
-
-Every greyscale token the default theme ships is at chroma zero. The one
-colour in the palette is `primary`, so a board brands itself by overriding
-one group — `primary`, `primary-hover`, `primary-foreground`, `ring`, or a
-single press of a brand preset on the theme screen — and nothing else in
-the palette carries a hue to clash with it.
-
-Two conventions follow, and both are conventions rather than contract:
-
-- **`accent` is a hover surface, not a highlight.** It carries shadcn/ui's
-  meaning here. Anything that needs to shout uses a semantic token.
-- **Body links are weight and an underline; `primary` marks the places a
-  reader navigates by, not the words they read.** The default theme spends
-  it on the board name and the bar above it, member names, post numbers,
-  the current tab, category headings and the avatar placeholder, and on
-  the hover state of every nav link and title. A thread title or a post
-  body stays `foreground` so an operator's brand choice never sits between
-  members and the words they are reading.
-
-A theme is free to disagree — deliberately. `themes/clubhouse` is the
-shipped disagreement: a club's colours are the point of a club's site, so
-`primary` marks a dozen surfaces there rather than four, and each one reads
-its text back as `primary-foreground`, the pair the contrast checks already
-measure.
-
-`themes/meith` is the other shipped example, and the opposite disagreement:
-the theme meith.dev runs on its own forum, published as `@meith/theme-meith`
-for a board to install like any third-party theme rather than bundled into the
-stock image. It follows the marketing site's editorial direction. The ground
-is the site's near-white and near-black at chroma zero, `primary` is the
-site's one green in each scheme, `radius` is `0rem`, `elevation` is `none`,
-and `card` equals `background`, so every inherited `Card` reads as a ruled
-region rather than a lifted box. Its own slots draw with three rules — a 2px
-`foreground` rule above a category, a post or a sidebar block, a 1px rule
-of `foreground` at 15% between forums, and a 1px `border` rule between
-threads — set headlines
-light with negative tracking, run labels in the mono face in small caps, and
-give the last word of a multi-word board name the italic serif accent the
-site uses in its own headlines; category and forum titles stay in
-`foreground`, because the green is reserved for emphasis. The green
-is spent the way the rebuilt landing page spends it and nowhere else: the
-board name carries the site's logomark, the one filled control on a screen
-is a `primary` block with a `↗` arrow, every link that goes somewhere ends
-in a muted arrow that turns `primary` under the pointer, the counts beside a
-listed item are `primary`, and a forum row's rule turns `primary` under the
-pointer. In a post, a 1px `border` rule stands between the byline column
-and the body. The header's sign-in is the same `primary` block, and the header and footer
-navigation run in the mono face as uppercase labels, as meith.dev's own do. Nothing glows,
-nothing is tinted and nothing is rounded. The semantic marks — pinned, locked,
-moderation and group tokens — sit on the greyscale ramp, so the label carries
-the meaning and the green stays reserved; the `accent` wash is `surface`.
-Transitions run 160–180ms. [Brand guidelines](../contributing/brand.md) holds
-the rules the theme follows. The theme fills every slot in the registry, so
-the sign-in, search, discovery, posting and panel screens draw with the same
-rules, labels and one filled action as the board index; only the form
-controls come from `@meith/ui`, and they take the tokens.
-In this repository it is registered only behind `SHOWCASE_THEMES`, so the
-contract tests, the fixture gallery and the browser suites cover it.
-
-## Components: `@meith/ui`
-
-`@meith/ui` is shadcn/ui's component vocabulary implemented on Base UI
-(`@base-ui/react`). It is available to themes, and the shipped default theme
-is built from it.
-
-The package is split by rendering cost, and the split is the thing to
-understand before importing from it:
-
-| Import | What it is |
+| Component or recipe | Use |
 |---|---|
-| `@meith/ui` | Everything that renders on the **server**: `Card`, `Badge`, `Alert`, `Avatar`, `Field`, `Input`, `NativeSelect`, `Separator`, `Empty`, `Disclosure`, `PageHeader`, `PageTitle`, `NavTabs`, plus the `buttonVariants`, `controlVariants` and `badgeVariants` class recipes |
-| `@meith/ui/nav-tabs-enhancer` | `NavTabsEnhancer` — keeps the current navigation link in view without moving the page |
-| `@meith/ui/password-input` | `PasswordInput` — an optional client island with localized `showLabel` and `hideLabel` props |
-| `@meith/ui/button` | The Base UI `Button` — a `"use client"` island |
-| `@meith/ui/menu` | The Base UI `Menu` — the other `"use client"` island |
-
-Nothing reachable from the main barrel declares `"use client"`, which is
-what makes it safe in a server slot. `PostBit` renders fifty times on a
-thread page; a design system that pulled a client boundary in behind a
-`<Card>` would give away the property the slot registry exists to protect.
+| `PageHeader`, `PageContent` | Page structure |
+| `PageTitle`, `PageDescription`, `PageActions` | Heading and actions |
+| `NavTabs` | Native linked tabs with optional enhancement |
+| `controlVariants` | Consistent control sizing and states |
+| `PasswordInput` | Password visibility control; compose with `Field`, not a wrapping label |
 
-That is also why `buttonVariants` is a separate export from `Button`. Most
-buttons on a forum are not buttons — "New thread" is a link, "Mark read" is
-a native form submit — and both want the class recipe on a plain element:
+Use 4px spacing increments. Standard controls are 40px and grow to 44px for coarse pointers; compact controls can be 32px on fine pointers. Preserve the 2px focus ring and disabled states. Touch inputs must compute to at least 16px to prevent browser zoom.
 
-```tsx
-<a href={newThreadHref} className={buttonVariants({ variant: 'primary' })}>
-  New thread
-</a>
-```
+Cards use container queries; `@3xl/card` is 48rem. Test narrow containers as well as narrow viewports. The standard board width is 1280px.
 
-Reach for `@meith/ui/button` only when the control genuinely lives in an
-island.
+## Navigation
 
-None of this is required. `@meith/theme-kit` is the only dependency a theme
-*needs*, and a theme that builds its own markup from scratch (as
-`themes/midnight` largely does) is a supported thing to be.
+Use the shared `NavigationDrawer` native popover for mobile navigation. Place it at the end edge. The header and panel use a single hamburger target, with localized copy and the shared `MobilePanelNav` structure.
 
-### Shared design system
+Navigation groups use native disclosures with an Overview link. Preserve desktop/mobile data markers on the expected direct children; layout tests use them.
 
-The default theme and app surfaces use the same foundation. New themes can
-change colours, typefaces, radius and elevation through tokens while reusing
-the layout and interaction components. Avoid copying a component's class
-recipe into a slot when the shared primitive already expresses it.
-
-| Foundation | Shared rule |
+| Enhancement marker | Optional behaviour |
 |---|---|
-| Spacing | Use the 4px scale: 8px within a control or field, 16–20px inside cards, 24px between page sections, and 32px of desktop page padding. |
-| Typography | `PageTitle` uses the heading token at 24px on small screens and 30px on larger screens. Card headings are 16px; body and form text are 14–16px; supporting metadata is 12px. |
-| Surfaces | Page uses `background`, cards use `card`, and card headers use a quieter `surface` band. Cards share token-derived corners, borders and elevation. |
-| Controls | Standard buttons, inputs and selects are at least 40px high; large actions are 44px. Compact controls are 32px on a fine pointer. Shared controls have a 44px minimum touch height. |
-| States | Primary actions use `primary` and `primary-hover`; keyboard focus uses an explicit 2px `ring` outline; invalid fields use `destructive` for border and focus. Disabled controls retain their label and reduce emphasis. |
-| Reading | Default post bodies fill the available content width inside the post padding, matching attachments and post actions. Long titles wrap without widening the page. |
-
-`PageHeader`, `PageHeaderContent`, `PageTitle`, `PageDescription` and
-`PageHeaderActions` compose a page introduction. Content and actions wrap
-when they cannot fit alongside each other. Use them for listings, search,
-composers and control panels; `className` overrides allow a theme's own
-heading treatment. Authentication uses the same pieces with a smaller title.
-
-```tsx
-<PageHeader>
-  <PageHeaderContent>
-    <PageTitle>{title}</PageTitle>
-    <PageDescription>{description}</PageDescription>
-  </PageHeaderContent>
-  <PageHeaderActions>{actions}</PageHeaderActions>
-</PageHeader>
-```
-
-`NavTabs` renders ordinary navigation links with `aria-current="page"`,
-optional counts and an optional aside. Its single row scrolls horizontally
-when space is limited, with padding for keyboard focus. It is server-rendered navigation,
-not an ARIA tab widget: links still navigate with JavaScript disabled.
-The app's `ViewTabs` and the default discovery screen use this one component.
-The root layout mounts `NavTabsEnhancer` once. It reveals the current link on
-initial render, when the active link changes, and when the strip resizes; it
-scrolls only the strip horizontally and leaves manual scrolling alone. This
-also handles navigation that arrives after the initial page render. Custom
-plugin strips opt in with `data-nav-tabs` and `aria-current` on the active link.
-Without JavaScript, the same native links remain horizontally scrollable.
-
-`controlVariants({ size: 'sm' })` supplies compact native controls, such as
-the appearance selector. `Input`, `NativeSelect` and `Textarea` use its
-standard recipe; native attributes and `className` remain available.
-`NativeSelect` also accepts `controlSize="sm"` independently of the native
-`size` attribute used by multiple-selection lists.
-
-`PasswordInput` preserves native input attributes, password manager autocomplete
-and the same field value when visibility changes. It starts masked; the localized
-visibility button appears only after hydration, so JavaScript-free forms do not
-show an inert control. Pair it with `Field` rather than placing the input and
-button together inside a wrapping label. Login, registration, reset and account
-password forms use this shared control.
-
-Search refinements use the same navigation and field recipes, stacking labeled
-filters on phones and using two columns when space allows. Poll composer inputs
-also use the standard field geometry.
-
-`surfaceVariants({ padded: true })` styles native forms and plugin sections
-with the same surface, spacing and depth as cards. The plugin kit's existing
-`PLUGIN_CARD`, `PLUGIN_NOTE`, `PLUGIN_TAB_LIST` and `pluginTabClass` exports
-now delegate to these shared recipes. Calendar and Dues use the same control
-and button recipes as the user, moderation and administration panels.
-
-Every `Card` establishes the named `card` size container. The default and
-Clubhouse forum and thread rows use `@3xl/card:` (48rem of card width),
-including their figures and column headings, to reveal desktop columns.
-A sidebar or narrow panel therefore retains the compact arrangement even
-on a wide browser. Use the same named container when adding a listing,
-and keep its title and metadata usable in the compact layout.
-
-Bundled themes start the board index with its announcements and forum
-listing, without a generic Community heading or introductory tagline. The
-mark-all-read control remains available to signed-in members. In every bundled
-theme it sits below the forum listing, aligned to its right edge, so it does
-not reserve a row above the forums and activity sidebar. The default shell
-shares a 1280px maximum width across its header, content, panels and
-footer. Its footer separates forum navigation from appearance preferences.
-Theme and scheme controls continue to submit native forms without scripting.
-
-### Form controls are 16px on a touch screen, whatever a theme asks for
-
-`globals.css` ends with one rule, outside every Tailwind layer, that sets
-`font-size: 1rem` on `input`, `select` and `textarea` under
-`@media (pointer: coarse)`. Being unlayered, it beats a utility class:
-`text-sm` on an input is honoured on a desktop and overruled on a phone.
-
-It is there because iOS Safari zooms the page in when a control with text
-smaller than 16px takes focus, and does not zoom back out afterwards. Every
-form on the board — signing in, registering, the reply box, search — was
-built at `text-sm`, so every one of them jumped on the way in and left the
-member on a page wider than their screen. The rule is scoped to coarse
-pointers, so a theme's density on a desktop is untouched.
-
-A theme that wants a larger control on a phone can still have one: the rule
-sets a size, it does not lock it, and a selector of higher specificity (or
-another unlayered rule loaded after) wins. Going *below* 16px is the thing
-that brings the zoom back.
-
-The same media query is the one to reach for on any other nav link or
-button a theme wants at least 44px tall on a touch screen: a Tailwind
-`pointer-coarse:h-11` (or `pointer-coarse:min-h-11`) alongside the desktop
-size, exactly as `Header`'s own nav links do in every shipped theme.
-
-### Panel navigation on phones
-
-`NavigationDrawer` from `@meith/ui` is a server-rendered hamburger trigger and
-drawer opening from the right (the inline end in RTL). `NavigationDrawerTrigger`
-can live separately in the top navigation bar by targeting the drawer ID; set
-`showTrigger={false}` on that drawer. Native `popover="auto"` controls open and close it, including an
-outside tap and Escape, even with JavaScript disabled. The board stylesheet
-keeps its header visible, scrolls the navigation independently, dims the page
-and respects reduced motion. It uses the browser's top layer to avoid clipping
-inside a panel or sticky header.
-
-All six themes share `MobilePanelNav` from `@meith/theme-default` while keeping
-their desktop rails. The drawer starts the current group expanded, highlights
-the current page, and gives other groups native disclosure controls. Every
-sub-section has a full-width touch target and wrapping text. Each expandable
-group includes an Overview link to the group's own page. `mobilePanelNavCopy`
-provides its localized labels when a theme supplies its own PanelNav copy.
-
-`PanelNavSectionModel.children` includes destinations from closed sections so
-readers can expand them without navigating to the parent. Record-specific
-items remain limited to their current page. Desktop rails continue to show
-children only when `isOpen` is true.
-
-### Mobile header navigation
-
-All six headers share `MobileHeaderNav` from `@meith/theme-default`, with
-localized labels supplied by `mobileHeaderNavCopy`. Below `lg`, the hamburger
-sits at the end of the top bar and opens the same right-side `NavigationDrawer`
-as the panels. The desktop navigation keeps each theme's own layout.
-
-On account and moderator pages, the header button targets the panel drawer.
-The stylesheet selects this button from the presence of the panel drawer ID,
-so there is one visible hamburger and no duplicate toolbar above the content.
-The admin header uses `NavigationDrawerTrigger` directly, alongside a compact
-sign-out icon on phones that retains its full accessible label. Custom headers should
-include `MobileHeaderNav` even when the board navigation array is empty, so
-panel navigation remains reachable.
+| `data-nav-tabs` | Horizontal tab navigation |
+| `data-nav-disclosure` | Focus and Escape handling |
+| `data-header-peek` | Header visibility while scrolling |
 
-Main navigation groups use native `<details>` with a full-width summary that
-expands the group. An Overview link inside the group reaches its parent page;
-child links wrap and have touch-sized targets. The drawer and its groups work
-with JavaScript disabled. Outside taps, Escape and the close button dismiss
-the drawer through native popover behavior. The scrollable body keeps the
-close button available on short screens.
+Without JavaScript, links, disclosures and the sticky header must remain usable. Do not hide required content behind an enhancement.
 
-Both desktop and mobile blocks render the same destinations. Their
-`data-nav-view="desktop"` and `data-nav-view="mobile"` markers let DOM-based
-tests select the intended copy. Keep the desktop marker on the list whose
-direct children contain the top-level links.
+## Forms and content
 
-A theme may go further and tag any disclosure it wants dismissed by an
-outside tap or <kbd>Escape</kbd> with `data-nav-disclosure`. `PageShell`
-mounts `NavDisclosureEnhancer` — an app-level, `"use client"` component,
-never a slot — once per page; it closes every open `[data-nav-disclosure]`
-on a pointer down outside it or an <kbd>Escape</kbd> keypress. Escape returns
-focus to the summary when focus was inside the closing disclosure. The admin
-shell mounts the same enhancer for any themed disclosures that opt in. This is
-strictly additive: a theme that never adds the attribute still has a working
-disclosure, just without the tap-outside convenience, and a slot itself must
-never become the client boundary — `Header` stays a plain, "use client"-free
-module exactly as the rule above requires; the enhancement lives beside it in
-the page shell, not inside it.
+Pass through app-owned forms and rendered regions. Keep native labels, validation messages and submit controls accessible. Preserve post anchors and target spacing from the [theme contract](theme-contract.md#post-links).
 
-The same shape gives a sticky header a "peek": a header tagged
-`data-header-peek` is watched by `HeaderPeekEnhancer`, which `PageShell`
-also mounts once per page. Once the reader has scrolled past the header's
-own height, scrolling down sets `data-peek` on it and scrolling up removes
-the attribute; near the top of the page, and whenever focus lands inside
-the header, it is always shown. The theme decides what a peeked-away header
-looks like — the default theme pairs the attribute with
-`data-peek:-translate-y-full` and a `motion-safe:` transition, so
-the bar slides away to give the content the whole viewport and slides back
-the moment the reader reverses. Without JavaScript the attribute is never
-set and the header simply stays sticky.
+Check long titles, empty states, tables, code blocks, error messages and translated labels. Follow [Theme testing](theme-testing.md) before publishing.
diff --git a/docs/extensions/theme-testing.md b/docs/extensions/theme-testing.md
index 9e7ac1741..dc51422d4 100644
--- a/docs/extensions/theme-testing.md
+++ b/docs/extensions/theme-testing.md
@@ -1,65 +1,25 @@
 # Test a theme
 
-Check a theme against populated, empty and permission-dependent models, then verify it in a browser. Fixture screens provide repeatable presentation states without modifying real community data.
+## Run contract tests
 
-## Testing a theme
+From the theme package, run its tests and typecheck. The generated contract test renders each registered stable slot and rejects invalid output, unexpected scripts and missing required content.
 
-### Browser fixtures
+Keep fixture definitions in `preview.fixture.ts` and gallery rendering in `gallery.fixture.tsx`. Use the sample English copy supplied by the fixtures.
 
-Run `pnpm dev` without a database and open `/fixtures` (the **Theme fixtures**
-link in the board navigation). Select any of the 36 slots and its sample state.
-The gallery uses the active registered theme and the normal appearance controls,
-so theme and light/dark choices persist while moving between samples. For all
-five bundled themes and the Meith theme, start with `SHOWCASE_THEMES=1 pnpm dev`.
+## Preview the slots
 
-The gallery reuses the contract models below and composes their regions with
-real slots and UI controls. Forum and thread rows sit inside their theme's own
-category and listing containers, including themes that use tables. Preview:
+From the Meith source checkout:
 
-- Populated and empty lists, pagination, long titles, link forums, unread,
-  pinned, locked, moved, unapproved and deleted threads.
-- Guest, member and staff controls; member profiles with and without optional
-  fields; posts with avatars, signatures, reputation, badges, image and file
-  attachments, rich formatting, edited notes and ignored placeholders.
-- Search results and refinements, empty searches, discovery refusals, presence,
-  statistics, announcements, every notice tone, and error/redirect screens.
-- New-thread, reply and edit composers with the real formatting toolbar,
-  attachment picker and editable fields; login, registration and reset forms;
-  user, moderator and administrator panel frames and standalone panel pages.
-- Poll results and thread ratings in `ThreadView`'s `poll` state, plus sample
-  plugin content in the extension regions.
+```sh
+pnpm dev
+```
 
-Direct links keep the slot and state, for example
-`/fixtures?slot=PostBit&variant=rich&theme=midnight` or
-`/fixtures?slot=PanelShell&variant=admincp`. Invalid slots or states return 404.
-The gallery is available only with `DATA_SOURCE=fixture`, including a hosted
-fixture board, and is excluded from search indexing. It never changes the
-request's actor or grants access to protected routes. Submissions are previews;
-JavaScript shows a read-only notice; native submissions redisplay the gallery
-and its read-only notice without storing the submitted fields.
-Sample prose is fixed English; the theme's own copy uses the normal translator.
+Open `/fixtures` on port 3000. Set `SHOWCASE_THEMES=1` to include the showcase theme. Use the fixture links to inspect each slot and variant. Fixtures are read-only and do not require a database.
 
-This covers visual development without accounts or a database. Use the
-[PostgreSQL development setup](../contributing/development.md)
-for persistence, permission workflows and plugin integrations. The gallery does
-not simulate those services. Add missing presentation states to
-`apps/community/src/theme/preview.fixture.ts`; contract tests render them across
-every registered theme. `gallery.fixture.tsx` supplies app-rendered regions.
+## Inspect states
 
+Check light/dark schemes, phone/desktop widths and JavaScript disabled. Cover empty lists, long labels, permission-dependent actions, notices, validation errors, pagination and plugin regions.
 
-`apps/community/src/theme/contract.test.ts` renders every theme registered
-in `meith.config.ts` through every stable slot with the same fixture
-models, and asserts the properties that are true of any theme:
+Confirm keyboard focus, native form controls, readable contrast, touch targets and overflow. A static render test does not verify interactions.
 
-- Required slots are filled.
-- Each one renders.
-- The values a reader is owed appear in the output.
-- Nothing renders `[object Object]`, `undefined`, or an empty `href`.
-- No server slot emits a script.
-
-Registering a theme enrols it — there is no list to add yourself to.
-
-The suite deliberately does not assert appearance. A theme is free to be a
-table, a card grid or a wall of text; a suite that required matching the
-default theme's markup would make the second theme's job "look like the
-first", which is the opposite of the point.
+Use a [PostgreSQL-backed board](../operations/local-board.md) for posting, editing, login and panel actions. See [Contributor testing](../contributing/testing.md) for browser tests and screenshots.
diff --git a/docs/extensions/themes.md b/docs/extensions/themes.md
index 18ef9e457..06dfaeae1 100644
--- a/docs/extensions/themes.md
+++ b/docs/extensions/themes.md
@@ -1,29 +1,13 @@
-# Theme development
+# Themes
 
-A theme supplies presentation through `@meith/theme-kit`. It receives view models from the host and renders named slots. Start with [Build your first theme](first-theme.md) for the scaffold-and-test workflow.
+Define a theme with `defineTheme` from `@meith/theme-kit`. Inherit an existing theme and override only the required slots and tokens.
 
-## Start with inheritance
-
-Extend the default theme and override only the slots you need. A palette change belongs in tokens; a markup change belongs in a slot. This leaves the rest of the board, including its member and staff panels, covered by the parent theme.
-
-The worked example is `examples/iris-theme`. The shipped themes provide larger examples, but copying a whole theme is unnecessary for a small customization.
-
-## Find the relevant contract
-
-| Task | Reference |
+| Task | Guide |
 |---|---|
-| Understand slots, view models and version compatibility | [Theme contracts](theme-contract.md) |
-| Choose tokens, fonts, colors and shared controls | [Tokens and shared controls](theme-design.md) |
-| Exercise populated, empty and restricted states | [Test a theme](theme-testing.md) |
-| Look up every slot and model field | [Generated slot reference](../reference/theme-slots.md) |
-| Translate or override messages | [Translations](internationalisation.md) |
-
-## Keep data and presentation separate
-
-A theme must not read the database, cookies, request or session. The board resolves data and permissions before building the model. Models contain serializable values, not executable access to the application.
-
-Declare slot maps statically so tooling can verify server/client boundaries. Preserve native forms and links where possible, and test the JavaScript-disabled experience. Use tokens for colors so administrators can restyle the board.
-
-## Make the theme available
+| Create and install a theme | [First theme](first-theme.md) |
+| Implement slots and models | [Theme contract](theme-contract.md) |
+| Set colours and use shared controls | [Tokens and controls](theme-design.md) |
+| Check layouts and states | [Theme testing](theme-testing.md) |
+| Look up slot props | [Generated reference](../reference/theme-slots.md) |
 
-Install the theme package in the board, register it in `meith.config.ts`, then rebuild and deploy. The [installation guide](../operations/installing.md) covers an existing theme; [marketplace publishing](marketplace.md) covers distribution.
+Themes render prepared models and regions. They do not read the database, authorize requests or implement mutations. Use a [plugin](plugins.md) for new behaviour.
diff --git a/docs/integrations/api-quickstart.md b/docs/integrations/api-quickstart.md
index 5ade403ca..ca98db8fb 100644
--- a/docs/integrations/api-quickstart.md
+++ b/docs/integrations/api-quickstart.md
@@ -1,43 +1,37 @@
-# Make your first API request
+# REST API quickstart
 
-Read board data from another application using the REST API. You need the board's public HTTPS URL. Private data requires a token with both the appropriate scope and an owner who can access that data.
+Use your board's HTTPS origin. Public reads use guest permissions; authenticated reads require both a token scope and an owner with access.
 
-## 1. Try a public read
-
-Replace `https://board.example` with your board's origin:
+## Read public forums
 
 ```sh
 curl --fail-with-body https://board.example/api/v1/forums
 ```
 
-A public board returns the forums visible to guests. Private forums remain hidden. If the board is offline or does not allow guest access, the response reflects that policy.
-
-## 2. Create a scoped token
+Only guest-visible forums are returned. Board access and maintenance policies still apply.
 
-An administrator opens **Admin → API tokens** at `/admin/api-tokens`, re-enters their password when requested, and issues a token with the scopes required by the integration. For the forum-list request, select `forums:read`.
+## Create a token
 
-Copy the token when it is shown and store it securely. Set an expiry appropriate to the integration, and revoke unused or exposed tokens. A token narrows its owner's permissions; it never grants access the owner lacks.
+In **Admin → API tokens** (`/admin/api-tokens`), issue a token with `forums:read`. Reauthenticate when requested. Copy the token when shown, set an appropriate expiry and store it in a secret store.
 
-## 3. Make an authenticated request
-
-Set `MEITH_TOKEN` in your terminal environment from your secret store, then run:
+Set `MEITH_TOKEN` in your environment, then run:
 
 ```sh
-curl --fail-with-body   -H "Authorization: Bearer $MEITH_TOKEN"   https://board.example/api/v1/forums
+curl --fail-with-body \
+  -H "Authorization: Bearer $MEITH_TOKEN" \
+  https://board.example/api/v1/forums
 ```
 
-Do not place a token in a URL, source code or browser-side application. An authenticated request needs the endpoint's scope even if the endpoint also permits anonymous reads.
+Tokens narrow their owner's permissions. Authenticated calls require the endpoint's scope even when anonymous reads are allowed. Keep tokens out of URLs, source code and browser-side applications; revoke unused or exposed tokens.
 
-## 4. Handle responses
+## Handle responses
 
-| Response | Check |
+| Response | Action |
 |---|---|
-| `401` | The token is valid, unexpired and not revoked |
-| Missing scope | The token includes the endpoint's required scope |
-| `403` or hidden content | Owner permissions, board policy and endpoint rules |
-| `429` | Rate-limit response headers; wait before retrying |
-| `503` | Board availability and maintenance state |
-
-Use the [REST reference](../reference/api.md) for exact endpoint parameters, response schemas, pagination and error shapes. The board publishes its OpenAPI schema at `/api/v1/openapi.json`.
+| `401` | Check token validity, expiry and revocation |
+| Missing scope | Issue a token with the required scope |
+| `403` or hidden content | Check owner permissions and board policy |
+| `429` | Follow rate-limit headers before retrying |
+| `503` | Check maintenance and availability |
 
-To receive events instead of polling, follow [Webhooks](webhooks.md).
+See the [API reference](../reference/api.md) for schemas and pagination. The board serves OpenAPI at `/api/v1/openapi.json`. Use [webhooks](webhooks.md) to receive events.
diff --git a/docs/integrations/webhooks.md b/docs/integrations/webhooks.md
index cf9d8345c..394a60239 100644
--- a/docs/integrations/webhooks.md
+++ b/docs/integrations/webhooks.md
@@ -1,38 +1,40 @@
-# Receive and verify webhooks
+# Webhooks
 
-Send board events to an HTTPS endpoint you operate. Deliveries are queued, signed and retried. You need administrator access to create a subscription and a receiver that can verify raw request bytes.
+Requires administrator access and an HTTPS receiver. Plain JSON deliveries are signed and queued.
 
-## Create a subscription
+## Subscribe
 
-Open **Admin → Webhooks**, enter the endpoint and choose at least one topic. Select Plain JSON for your own integration or the Discord format for a channel webhook. Enable delivery when the receiver is ready.
+1. Open **Admin → Webhooks**.
+2. Enter the endpoint and select topics.
+3. Choose Plain JSON for a custom receiver or Discord for a channel webhook.
+4. Copy the signing secret when shown; it is displayed once. Store it in the receiver's secret configuration.
+5. Enable delivery, trigger a test event and inspect Recent deliveries.
 
-Copy the signing secret when shown; it is displayed once. Store it in the receiver's secret configuration. Inspect Recent deliveries after triggering a controlled event.
+## Topics
 
-## Choose topics and understand visibility
-
-| Topic | Event |
+| Topic | Trigger |
 |---|---|
-| `thread.created` | A thread is created visible |
-| `post.created` | A first post or reply is created visible |
-| `post.edited` | A visible post is edited and remains visible |
-| `post.deleted` | A previously visible post is removed |
-| `user.registered` | An interactive registration or administrator-created account |
-| `report.created` | Content is reported |
+| `thread.created` | Visible thread created |
+| `post.created` | Visible first post or reply created |
+| `post.edited` | Visible post edited and still visible |
+| `post.deleted` | Previously visible post removed |
+| `user.registered` | Interactive or administrator-created account |
+| `report.created` | Content reported |
 
-Held content does not emit a creation event. Later approval and restoration do not re-emit creation. An edit that returns content to approval is quiet. Bulk import and fixture loading do not emit one registration event per member.
+Held content emits no creation event. Approval and restoration do not re-emit creation. Edits returning content to approval are quiet. Imports and fixtures do not emit registration events per member.
 
-Payloads contain event identifiers, not complete database rows. Fetch authorized details through the [REST API](../reference/api.md). A report includes its target kind and ID; a guest reporter can have a null ID.
+Payloads carry identifiers, not database rows. Fetch permitted details through the [API](../reference/api.md). Report payloads include target kind/ID; the guest reporter ID can be null.
 
-## Verify the request
+## Verify deliveries
 
-| Header | Purpose |
+| Header | Value |
 |---|---|
 | `x-forum-event` | Topic |
-| `x-forum-delivery` | Stable delivery ID for deduplication across retries |
-| `x-forum-timestamp` | Unix seconds included in the signature |
-| `x-forum-signature` | `sha256=<hex>` HMAC of `<timestamp>.<raw body>` |
+| `x-forum-delivery` | Stable ID across retries |
+| `x-forum-timestamp` | Unix seconds |
+| `x-forum-signature` | `sha256=<hex>` HMAC over `<timestamp>.<raw body>` |
 
-Verify before parsing or processing the body. Reject stale timestamps and compare signatures in constant time. This Node.js example expects the raw body as a Buffer and string-valued headers:
+Verify raw bytes before parsing. Reject stale timestamps and use constant-time comparison. This Node.js example accepts a Buffer and string-valued headers:
 
 ```js
 import { createHmac, timingSafeEqual } from 'node:crypto'
@@ -54,12 +56,12 @@ export function verify(secret, headers, rawBody, now = Math.floor(Date.now() / 1
 }
 ```
 
-Deduplicate using the delivery ID before applying a side effect. Signature verification establishes authenticity; it does not itself make processing idempotent. The Discord format is handled by Discord rather than your own signature receiver.
+Deduplicate by delivery ID before applying side effects. A valid signature does not prevent duplicate processing. Discord handles its own receiver format.
 
-## Handle retries
+## Retries and failures
 
-The `webhooks.deliver` task retries timeouts, connection failures, 5xx, 408 and 429 responses, backing off from 30 seconds up to an hour, for up to six attempts. Other 4xx responses are treated as permanent failures. Inspect retrying and dead-lettered deliveries in the panel.
+The `webhooks.deliver` task accepts 2xx responses as delivered. HTTP 410 and blocked destinations fail permanently. Network failures and other non-2xx responses retry, up to six attempts. Delays double from 30 seconds with ±25% jitter. Inspect retries and dead letters in the panel.
 
-The endpoint must resolve to an allowed public address. Production private-network delivery requires the explicit `WEBHOOK_ALLOW_PRIVATE_HOSTS` configuration; use it only for an intended internal endpoint.
+Destinations must resolve to allowed public addresses. `WEBHOOK_ALLOW_PRIVATE_HOSTS` explicitly permits intended internal endpoints in production.
 
-If deliveries stop, check [Scheduled tasks](../operations/scheduled-tasks.md), endpoint responses and subscription state. Pausing a subscription retains history but stops new deliveries.
+If delivery stops, check the [scheduler](../operations/scheduled-tasks.md), receiver response and subscription state. Pausing retains history and stops new events being queued. Pending deliveries continue.
diff --git a/docs/members/account-security.md b/docs/members/account-security.md
index 8dd651a8f..2737601d6 100644
--- a/docs/members/account-security.md
+++ b/docs/members/account-security.md
@@ -1,29 +1,25 @@
-# Manage your account security
+# Account security
 
-Manage your own sign-in methods and devices at `/usercp/security`. Options depend on the features your community enables. Keep access to your account email address and save recovery codes somewhere separate from your authenticator device.
+Open `/usercp/security`. Available options depend on board settings.
 
-## Reset a forgotten password
+## Reset a password
 
-Use the password-reset link on the sign-in page. Enter your email address, check the inbox and spam folder, and follow the link if it arrives. The form does not reveal whether an address belongs to an account.
+Use the reset link on the sign-in page, enter your email and follow the emailed link. Check spam folders. The response does not disclose whether the account exists. Contact an administrator if mail does not arrive.
 
-If no message arrives, contact the community's organisers. They can check delivery with the operator. Repeated requests do not solve a mail configuration problem.
+## Enable two-factor authentication
 
-## Set up two-factor authentication
+1. Start authenticator setup on the security page.
+2. Add the secret to your authenticator app.
+3. Confirm a code and save the recovery codes separately from your device.
 
-Open the security page and follow the authenticator setup. Confirm the code before leaving the page, then save the recovery codes securely. At future sign-ins, enter an authenticator code or an unused recovery code when prompted.
+Use an unused recovery code if you lose the authenticator. If both are lost, contact the administrators for identity verification and operator recovery. Clearing two-factor authentication revokes sessions; enrol again afterward.
 
-If you lose the authenticator, use a recovery code. If you lose both, contact the organisers; an operator must establish your identity before clearing the second factor. Clearing it signs your sessions out, and you must enroll again.
+## Add a passkey or provider
 
-## Use a passkey or sign-in provider
+Use the security page's registration or linking controls and follow the browser prompts. Keep a working sign-in method while testing a new one. A provider-verified email can link automatically to a matching board account; unverified email cannot.
 
-If the board offers passkeys, register one from the security page and follow your browser or device prompt. Keep another working sign-in method while testing a new one.
+## Review sessions
 
-If the board offers an external provider, use the supported link/unlink controls. Signing in at a provider is not a way to take over an existing board account with the same email address. Follow any verification or linking prompt shown by the board.
+Revoke devices you no longer use and inspect unexpected security events. Changing your password signs out other sessions. The admin panel uses a separate session and may request your password again.
 
-## Review sessions and security activity
-
-Review the devices or sessions listed on the security page and revoke ones you no longer use. Check recent security events if you see unexpected activity. Changing your password signs out other sessions.
-
-The admin panel has its own session and may ask for your password again even when you are already signed in to the board.
-
-Operators configuring these features should use [Authentication settings](../operations/single-sign-on.md).
+Operator setup: [Authentication](../operations/single-sign-on.md).
diff --git a/docs/members/formatting.md b/docs/members/formatting.md
index a8dfd40d9..820491cd2 100644
--- a/docs/members/formatting.md
+++ b/docs/members/formatting.md
@@ -1,32 +1,24 @@
-# Write and format posts
+# Format posts
 
-Use Markdown in posts, replies and private messages. The toolbar inserts syntax, but you can type it directly without JavaScript. Signatures allow a restricted subset of formatting.
+Posts, replies and private messages accept Markdown. The toolbar inserts the same syntax. Signatures support a restricted subset.
 
-## Basic formatting
+## Syntax
 
-| Write | Result |
+| Input | Result |
 |---|---|
-| `**bold**` | Bold text |
-| `*italic*` | Italic text |
+| `**bold**` | Bold |
+| `*italic*` | Italic |
 | `~~removed~~` | Strikethrough |
-| `[label](https://example.com)` | A named link |
+| `[label](https://example.com)` | Link |
 | `` `code` `` | Inline code |
-| `> quoted text` | A blockquote |
-| `- item` | A bulleted list |
-| `1. item` | A numbered list |
-| `## Heading` | A heading |
+| `> quoted text` | Quote |
+| `- item` | Bullet list |
+| `1. item` | Numbered list |
+| `## Heading` | Heading |
 
-Leave blank lines around paragraphs, lists and larger blocks. Use the composer's **Formatting help** for a reminder while writing.
+Separate paragraphs and blocks with blank lines. Use **Quote** on a post or type `@username` to mention a member. Mentions do not grant access to private content.
 
-## Quote or mention someone
-
-Use **Quote** on a post to bring its text into the reply composer, then keep the relevant part. Type `@username` to mention a member. With JavaScript enabled, suggestions help complete names; typed mentions still work without it.
-
-Suggestions respect the profiles you can see and your ignore list. A mention is not a way to grant someone access to a private thread.
-
-## Show code
-
-Put three backticks on separate lines around code and optionally name its language:
+## Code
 
 ````text
 ```ts
@@ -34,55 +26,45 @@ const answer = 42
 ```
 ````
 
-Recognized languages are highlighted when the post is rendered. An omitted or unrecognized language displays plain code.
+Supported languages receive syntax highlighting; other code displays as plain text.
 
-## Add tables and checklists
+## Tables and checklists
 
 ```text
 | Item | Status |
 | --- | --- |
 | Venue | Booked |
-```
 
-```text
 - [ ] Invite speakers
 - [x] Book the room
 ```
 
-Saved task-list boxes show a record of completion; readers cannot toggle them as interactive tasks.
+Saved checkboxes are read-only.
 
-## Hide a spoiler
+## Spoilers
 
 ```text
 :::spoiler
-The answer is inside this disclosure.
+Hidden text
 :::
 ```
 
-Spoilers use a disclosure that can be opened with a mouse or keyboard and works without JavaScript.
-
-## Add images and attachments
+Readers open the disclosure with a mouse or keyboard. JavaScript is not required.
 
-For an externally hosted image:
+## Images and attachments
 
 ```text
-![Describe the image](https://example.com/photo.png)
+![Image description](https://example.com/photo.png)
 ```
 
-Remote images only load when the board permits them. Provide a useful description for readers who cannot see the image.
-
-For a local file, use the attachment controls offered by the forum. Files normally appear beneath the post. **Insert attachment** uploads an image and inserts its `[attachment=id]` marker into the text; that toolbar enhancement requires JavaScript. With JavaScript disabled, use the ordinary attachment form and submit with the post.
+Remote images require board permission. Use descriptive alternative text.
 
-Only permitted attachments resolve. Removing an inline marker is not the same operation as deleting the attachment. When editing a post, use its attachment management controls to remove or retain files, then verify the saved result.
+Use the attachment form to upload files. With JavaScript, **Insert attachment** uploads an image and inserts `[attachment=id]`. Without JavaScript, submit files through the ordinary attachment form. Only permitted attachments render.
 
-## Use link previews
+Removing a marker does not delete its file. Use the post's attachment controls to delete files.
 
-On boards allowing remote images, a supported video URL on its own line can show a static preview card. A link inside a paragraph stays a link. Previews are not embedded video players.
+A supported video URL on its own line can show a static preview when remote images are allowed. It does not embed a player.
 
 ## Polls and drafts
 
-If the forum allows polls, use the new-thread poll controls and check the choices, multiple-selection limit and voter visibility before submitting. Later edits may be restricted once voting begins.
-
-Use saved drafts at `/usercp/drafts` to resume unfinished writing. Browser composer recovery is an enhancement, not a replacement for saving important text. Posting, editing and deletion remain subject to permissions and any time limit.
-
-See [Member guide](member-guide.md) for the posting workflow and [Notifications](notifications.md) for following replies.
+Check poll choices, selection limits and voter visibility before submitting. Editing may be restricted after voting starts. Resume saved drafts at `/usercp/drafts`; browser recovery does not replace saving a draft.
diff --git a/docs/members/member-guide.md b/docs/members/member-guide.md
index 4b857aa4a..6447a9b3f 100644
--- a/docs/members/member-guide.md
+++ b/docs/members/member-guide.md
@@ -1,53 +1,36 @@
-# Use your community
+# Read and post
 
-Open your community's Meith board in a browser. You do not need to install software to participate. Available forums and features depend on the community's settings and your permissions.
+Open the community's board in a browser. Available forums and actions depend on your account permissions.
 
-## Join and sign in
+## Join
 
-Choose **Register**, complete the form and follow the confirmation or approval message. If registration is closed, contact the organisers. Use the password-reset link if you already have an account.
+Select **Register**, complete the form and follow the activation instructions. If registration is closed, contact the administrators. For an existing account, use the sign-in or password-reset link.
 
-Keep recovery codes when enabling two-factor authentication. [Account security](account-security.md) explains passwords, passkeys, sign-in providers and devices.
+## Find discussions
 
-## Find a discussion
+Open a forum or use **New posts**, **Unanswered**, **My posts** or **Search**. Search filters can narrow results by forum, author, time and content type. Results include only content you may read.
 
-Open a forum and choose a thread. **New posts**, **Unanswered** and **My posts** help find activity; organisers may customize navigation labels.
+## Post
 
-Use **Search** to look for words, then narrow by forum, author, time or the other offered filters. Choose titles or whole posts and thread or post results as appropriate. You can only find content you are permitted to read.
+1. Open a forum and select **New thread**, or open a thread to reply.
+2. Enter the title and message. Use **Quote** to include an earlier post.
+3. Add permitted attachments or a poll.
+4. Submit. Posts held for approval appear after moderator review.
 
-If a forum or posting control is missing, check account activation and ask the organisers about access. A closed forum may allow reading but not new posts.
+See [Formatting](formatting.md) for Markdown. Resume saved drafts at `/usercp/drafts`. Editing and deletion may have permission or time limits.
 
-## Start a thread or reply
+## Account and activity
 
-1. Choose the forum and **New thread**.
-2. Enter a descriptive title and write the message.
-3. Add allowed attachments or a poll if needed.
-4. Review and submit. Content held for approval appears after moderator review.
-
-Reply in an existing thread to continue that discussion. Use **Quote** to show which post you are answering. [Write and format posts](formatting.md) covers Markdown and attachments. Saved drafts are under `/usercp/drafts`.
-
-Editing and deletion depend on permissions and any time limit. Contact a moderator when a correction is outside the controls available to you.
-
-## Stay in touch
-
-| Task | Guide or page |
+| Task | Page |
 |---|---|
-| Follow a thread or change email preferences | [Notifications](notifications.md) |
-| Send a private message or manage contacts | [Messages](messages.md) |
-| Change profile details, avatar or signature | Account panel at `/usercp` |
-| Set language, timezone or automatic following | `/usercp/options` |
-| Review sign-in methods and devices | [Account security](account-security.md) |
-| Respond to a community event | [Calendar](../administration/calendar.md) |
-
-Optional features such as awards and paid memberships appear only when the community enables them.
-
-## Ask for help or report a problem
-
-Use **Report** on content that needs moderator attention and explain the issue. For account access or community policy, use the organisers' published contact route.
-
-A Thanks or rating control recognizes a contribution. Whether it appears depends on the community's reputation settings and your eligibility.
+| Profile, avatar and signature | `/usercp` |
+| Language, timezone and automatic following | `/usercp/options` |
+| Follow discussions | [Notifications](notifications.md) |
+| Private messages and contacts | [Messages](messages.md) |
+| Passwords, passkeys and devices | [Account security](account-security.md) |
 
-## Membership payments and receipts
+Use **Report** on content requiring moderator review. Contact administrators for account or access problems.
 
-If your community offers paid membership, open **Membership** to view its plans. Use **Your membership** to manage access and renewals. **Recent receipts → View receipt** opens a receipt for an eligible paid purchase you made, including a gift you bought. Free purchases and payments awaiting confirmation have no receipt link. Subscription renewal invoices are in the billing portal.
+## Paid membership
 
-Contact the community's administrators if a payment or membership needs investigation. The [Dues guide](../administration/membership-guide.md) describes the available plans and administration tools.
+If Dues is enabled, open **Membership** to buy a plan and **Your membership** to manage it. **Recent receipts → View receipt** opens eligible paid-purchase receipts, including gifts you bought. Free or unconfirmed purchases have no receipt link. Subscription renewal invoices are in the billing portal.
diff --git a/docs/members/messages.md b/docs/members/messages.md
index 1a455d8c0..4bc7e9ece 100644
--- a/docs/members/messages.md
+++ b/docs/members/messages.md
@@ -1,30 +1,22 @@
-# Send messages and manage contacts
+# Messages and contacts
 
-Use private messages to contact other members when the community permits it. Open `/messages` after signing in.
+Sign in and open `/messages`.
 
 ## Send a message
 
-1. Open the compose page and choose the intended recipients.
-2. Write a subject and message.
-3. Review the recipients before sending.
-4. Open the conversation to confirm the sent message appears.
+1. Open the compose page.
+2. Select recipients and enter a subject and message.
+3. Check the recipients, then send.
+4. Open the conversation to confirm delivery to your sent view.
 
-The board may restrict messaging by group, daily allowance, storage quota or recipient preferences. If a recipient's inbox is full, the send can be refused; check the displayed message before retrying.
+**Reply** addresses the author. Check recipients before including other people. See [Formatting](formatting.md) for message syntax.
 
-Reply addresses the message's author. Review the recipient list when you intend to include other people.
+## Limits
 
-## Understand limits
+Group permissions, recipient preferences, daily send allowances and storage quotas can block delivery. One send counts once toward the daily allowance, regardless of recipient count. Deleting messages frees storage but does not reset that allowance. A full recipient inbox can prevent sending.
 
-A daily send allowance and a stored-message quota are separate controls. Deleting stored messages does not reset the day's send allowance. One send counts once toward the allowance even when it has several recipients.
+## Contacts and reports
 
-If you cannot message someone, ask the organisers whether a community restriction applies. Do not try to bypass another member's contact preferences.
+Manage buddies and ignored members at `/usercp/contacts`. Ignoring hides post bodies where supported; it does not delete posts or shared history.
 
-## Manage contacts
-
-Open `/usercp/contacts` to manage buddies and ignored members. Ignoring a member hides their post body where supported; it does not remove their posts from the discussion or delete shared history.
-
-## Report a message
-
-Use the report action when a message requires moderator attention. Reporting is the route by which staff can review a private message; staff do not receive general browsing access to everybody's inbox.
-
-For links, mentions and formatting, see [Write and format posts](formatting.md).
+Use **Report** on a message requiring staff review. Staff can review the reported message; reporting does not grant general access to inboxes.
diff --git a/docs/members/notifications.md b/docs/members/notifications.md
index abfe74dbf..8eaf610ea 100644
--- a/docs/members/notifications.md
+++ b/docs/members/notifications.md
@@ -1,31 +1,23 @@
-# Follow discussions and manage notifications
+# Notifications
 
-Choose which discussions to follow and how to receive updates. You need a signed-in account; email and browser delivery also depend on services enabled by the community.
+Sign in to manage subscriptions and delivery preferences.
 
-## Follow or stop following a thread
+| Task | Action |
+|---|---|
+| Follow a thread | Use its subscription control |
+| Manage followed threads | Open `/subscriptions` |
+| Automatically follow threads you post in | Set the option at `/usercp/options` |
+| Read notifications | Open `/notifications` |
+| Set email and digest delivery | Open `/notifications/preferences` |
 
-Use a thread's subscription control to follow replies. Manage followed discussions at `/subscriptions`. At `/usercp/options`, choose whether threads you participate in should be followed automatically.
+Unread events may be grouped. Disabling email leaves on-site notifications available. Unfollowing or muting a thread does not delete posts.
 
-Muting and unfollowing change what updates you receive; neither deletes your posts. An email unsubscribe action does not delete the thread.
+## Browser notifications
 
-## Read your notifications
+If web push is enabled, opt in through the board and grant browser permission. Browser permission alone does not subscribe you. Change permission later through the browser's site settings. See [Web push](../operations/web-push.md) for device requirements.
 
-Open `/notifications` to see activity directed to you. A repeated event may be grouped with an existing unread notification. Opening the notification follows its link to the relevant discussion or activity.
+## Stop or troubleshoot delivery
 
-On-site notifications remain available even when you turn email delivery off.
+Review both subscriptions and notification preferences. Email unsubscribe links change the relevant preference; keep those links private.
 
-## Choose email and digest preferences
-
-Open `/notifications/preferences` and review the available event types, subscriptions and digest choices. Save the settings and verify the next expected update.
-
-Instant delivery still depends on the board's scheduled work. If a whole community is waiting for mail, ask an organiser to check the scheduler and mail service. Password-reset delivery uses its own request path and should be diagnosed separately.
-
-## Enable browser notifications
-
-If the board offers web push, opt in through its controls and grant permission in your browser. Browser permission alone is not a board subscription. You can change the browser permission later through its site settings.
-
-For operator setup and device limitations, see [Web push](../operations/web-push.md).
-
-## Stop unwanted updates
-
-Review both thread subscriptions and notification preferences. Use the unsubscribe action in a legitimate board email where appropriate. Ask organisers about community mail you cannot identify rather than sharing a private unsubscribe link publicly.
+Delayed community-wide email can indicate a scheduler or mail-service problem. Ask an administrator to check it. Password-reset mail uses a separate request path.
diff --git a/docs/operations/authentication-reference.md b/docs/operations/authentication-reference.md
index 59a7f0c26..42a0a12f0 100644
--- a/docs/operations/authentication-reference.md
+++ b/docs/operations/authentication-reference.md
@@ -1,496 +1,93 @@
-# Authentication behavior and recovery
-
-Look up the behavior of two-factor authentication, sessions, sign-in providers and passkeys. Member instructions are in Account security; operator setup is in Authentication settings.
-
-## A second factor
-
-### What it is
-
-An authenticator app holds a secret shared with the board and turns it into
-a six-digit code that changes every thirty seconds. Asked for after the
-password — or after a federated sign-in — it means a leaked password, or a
-provider account somebody else has got hold of, is not on its own enough to
-open an account.
-
-The board implements the ordinary standard (RFC 6238: SHA-1, six digits, a
-thirty-second period), so any authenticator app works — Aegis, Ente Auth,
-1Password, Google Authenticator, whatever your members already have.
-
-### Board settings
-
-**Offer two-factor authentication** (`security.two_factor_enabled`) decides
-whether the surface exists at all. It is on by default, which costs a board
-nothing: nobody is asked for a code until they have set one up.
-
-It needs `AUTH_SECRET` set. The secret an authenticator app holds is a
-password equivalent — with it, anybody can mint that member's codes forever
-— so the board encrypts it with a key derived from `AUTH_SECRET` before
-storing it. With no key there is nowhere safe to put the secret, and the
-whole surface hides itself rather than pretending.
-
-> [!WARNING]
-> Changing `AUTH_SECRET` on a board where members have set up a second
-> factor strands every stored secret. They cannot be decrypted again, and
-> every affected member has to set up their app from scratch. The board
-> says so plainly rather than reporting a wrong code. Clearing a stranded
-> factor — from the panel or the CLI, [below](#when-the-app-and-the-codes-are-both-gone)
-> — needs no key, so a rotated secret does not lock those members out
-> permanently.
-
-**Require it of anyone who can reach the control panel**
-(`security.two_factor_required_for_staff`) is off by default. Turned on, an
-account with `admincp.access` is refused the panel until it has an
-authenticator app set up, and cannot turn its second factor off while it
-holds that access. The panel can rewrite the whole board; a password alone
-is a thin thing to protect that with.
-
-Turning **Offer two-factor authentication** back off does not release the
-members who already set one up: the sign-in gate asks for a code because the
-account holds a factor, not because the board offers the feature, so
-switching it off would otherwise lock those members in rather than out. They
-keep their panel on **/usercp/security** — enough of it to replace their
-recovery codes or turn the factor off — while nobody new is offered the
-setup.
-
-### What a member does
-
-From **/usercp/security**, a member presses *Set up an authenticator app*.
-The board shows a key to type into the app, and an `otpauth://` link that
-opens the app directly on a phone. They type back the code the app shows —
-which proves the two agree — and the board hands over **ten recovery
-codes**.
-
-The recovery codes are independent 128-bit random values, shown once and
-stored only as hashes. Each one signs in exactly once, in place of a code,
-for the day a phone is lost. A member can replace the set at any time (which
-retires the old set), and the page shows how many are left.
-
-The confirmation posts back to `/usercp/security?factor=setup`, and that
-response is the only place the fresh codes exist. The page therefore stays on
-the setup screen for as long as `?factor=setup` is in the address rather than
-swapping straight to the settled panel — otherwise a member browsing without
-JavaScript never sees the codes at all.
-
-A board can refuse the whole operation if the feature is switched off between
-the page rendering and the button being pressed. A refusal is reported on the page like any other
-form error; it never fails the request.
-
-Turning the second factor off — or replacing the recovery codes — asks for
-the password again. An account with no password (one that arrived through a
-provider, or holds only passkeys) gives a current code instead, which proves
-the same possession.
-
-### When the app and the codes are both gone
-
-A member who still has one recovery code has not lost anything: it signs
-them in, and they can replace the set from **/usercp/security** afterwards.
-A member who has lost the app *and* every code cannot get in on their own,
-and a password reset does not help — the reset changes the password, and the
-second screen still asks for a code.
-
-That is what an operator is for. **Admin → Members → the member → Second
-factor** clears it, and the panel asks for the administrator's own password
-first — and, when their account has a second factor, for a code on a screen
-of its own. Clearing signs every one of that member's sessions out and
-leaves the account on its password alone until they set an app up again; the
-board records it in the admin log and in the member's own security activity,
-where it reads as cleared by staff rather than by them. Nothing about it
-proves who asked — satisfy yourself that you are talking to the member
-before you press it.
-
-The panel cannot help the one case that matters most: the sole
-administrator of a board that requires a second factor of its staff, who has
-lost theirs. That is what the operator CLI is for, and it needs no panel
-session:
+# Authentication reference
+
+Members configure credentials at `/usercp/security`. Operators configure board policy under Security settings.
+
+## Two-factor authentication
+
+Meith uses TOTP (SHA-1, six digits, 30-second periods). `security.two_factor_enabled` defaults on; enrolment requires `AUTH_SECRET`, which encrypts stored authenticator secrets.
+
+> [!CAUTION]
+> Retain the original `AUTH_SECRET`. Replacing it makes existing authenticator secrets unreadable. Affected factors must be cleared and enrolled again.
+
+`security.two_factor_required_for_staff` defaults off. When enabled, accounts with `admincp.access` must enrol before entering the panel and cannot disable the factor while retaining that access. Turning off new enrolment does not remove the code requirement for enrolled accounts.
+
+Setup confirms one app code, then displays ten one-use 128-bit recovery codes. They are shown once and stored as hashes. Replacing the set invalidates the old codes. Disabling or replacing codes requires a password, or a current factor for passwordless accounts.
+
+### Recovery
+
+A password reset does not bypass two-factor authentication. After verifying identity, an administrator can clear the member's factor with fresh admin authentication, or an operator can run:
 
 ```sh
 meith user:2fa-clear --user ada
 ```
 
-It does the same work — clears the factor, ends every session, writes the
-same entry — from a shell on the host. See
-[the operator CLI](operator-cli.md#the-operator-cli) for how to reach it on
-your deployment.
-
-### What signing in looks like
-
-The password step is unchanged. When it succeeds and the account has a
-second factor, the board does not start a session: it holds the
-half-finished sign-in for ten minutes and asks for the code on a second
-screen. Only when that is satisfied does a session begin.
-
-A **federated sign-in** meets the same gate. A member who has an
-authenticator app set up is held for their code after the provider vouches
-for them — whether the identity was already linked, matched by a confirmed
-address, or the account was provisioned in an earlier visit — exactly as a
-password sign-in is. The provider proving who someone is does not, on its
-own, stand in for the second factor: a member who enrolled one is protected
-however they arrive. (A freshly provisioned account has no factor yet, so a
-first federated sign-up signs straight in.) The hold and its second screen
-are the same ones the password path uses.
-
-The hold is a random token in a strict, HTTP-only cookie, backed by a row
-that is spent exactly once. It is not a session and grants nothing: an
-account banned between the two steps is refused at the second, and giving
-the password again drops any earlier hold.
-
-The second screen accepts a code from the app, one of the recovery codes, or
-— if the member has a passkey — the passkey, which proves possession just as
-well. Wrong codes count against the same lockout thresholds the password
-uses, on their own counter. A code that has already been used is refused
-even within the thirty seconds it would otherwise be valid — anybody who
-reads a code over a shoulder has that window to race the member, and this
-closes it.
-
-**A passkey sign-in is the deliberate exception.** Signing in with a passkey
-does not then ask for the authenticator code, even on an account that has
-one enrolled. This is by design, not an oversight: a passkey is bound to the
-board's own address and needs the member's device and their presence on it,
-so it is already a phishing-resistant second factor in its own right, and
-stacking a TOTP code behind it would prove the same possession twice. The
-second factor stands in front of the two first-factor sign-ins — the
-password and a federated provider — that a code meaningfully adds to.
-
-### The control panel's own door
-
-The admin panel has always asked for the password again on the way in. It now
-does it in the same two steps the sign-in page uses: the password first, and
-only when the administrator's account has a second factor, the code on a
-screen of its own. An account without one is let in on the password alone —
-re-proving what it does not have would be theatre. When the board requires a
-second factor of its staff, an administrator who has not set one up is turned
-away at the password step rather than shown a code screen they cannot answer.
-
-The password step holds the half-finished sign-in the same way the sign-in
-page does: a random token in a strict, HTTP-only cookie scoped to the panel,
-backed by a row spent exactly once, good for ten minutes. It is not a panel
-session and grants nothing; giving the password again drops any earlier hold.
-Password and second-factor failures share a dedicated counter for the
-administrator and retained address prefix. It uses the board's configured
-login threshold and fixed lockout window, and clears only once the whole
-proof is complete — the code where one is owed, the password alone where it
-is not.
-
-## Where a member is signed in
-
-**/usercp/security** lists every live session on the account: the device it
-was started from, the truncated address, when it started, when it was last
-seen, and which one is the browser reading the page. Any of the others can
-be signed out one at a time, or all at once.
-
-Revocation is immediate — the session row is marked, and the next request it
-makes is refused. Device and address are recorded when a session starts, so
-sessions that predate this feature list as an unknown device until they are
-replaced.
-
-A member whose session was ended from another device still holds a cookie, so
-they reach the control panel as a guest rather than being stopped at the door.
-The panel answers that by sending them to the sign-in page with their
-destination attached, not with a 404 — the page has not gone, they have been
-signed out of it.
-
-"Sign out everywhere else" keeps the session reading the page and ends the
-rest. If the board cannot work out which session that is it refuses the whole
-operation rather than guessing, because the guess that ends everything would
-sign the member out of the page they are standing on.
-
-### Keeping a member signed in
-
-"Keep me signed in" issues a remember token alongside the session. Opening the
-board once the session has lapsed spends that token at **/auth/resume** and
-issues a fresh one — single use, so a token that turns up twice is evidence
-that a copy of it exists somewhere it should not, and the whole family plus
-every session on the account is ended.
-
-Session resumption and SSO accept top-level navigations forwarded by the board's
-service worker: these retain `Sec-Fetch-Mode: navigate` but can arrive with
-`Sec-Fetch-Dest: empty`. Ordinary background fetches and iframe navigations remain
-refused. The worker only intercepts top-level documents, leaving iframe fetch
-metadata intact for the same check.
-
-Two requests carrying the same token are not always theft, though. A browser
-restoring several tabs, a double-clicked link and a prefetch racing its own
-navigation all present the identical cookie within the same moment, and
-exactly one of them can win a single-use claim. Tokens are therefore honoured
-for **30 seconds** after their own rotation: inside that window the losers are
-issued their own fresh tokens and nobody is signed out, and outside it a
-replay is treated as theft as before. A family that has already been burned is
-refused inside the window as well — the board has made its decision about it.
-
-Because the requests race, the losing one can carry a timestamp from just
-before the winner marked the token spent. The window is measured in both
-directions for that reason; requiring the elapsed time to be positive would
-refuse the exact case the window exists to forgive.
-
-## What has happened to an account
-
-The board keeps a durable record of authentication events: password
-sign-ins and refused attempts, sign-outs, wrong second-factor codes,
-recovery codes used, password and e-mail changes, sessions revoked, a second
-factor cleared by staff, and every provider or passkey added or removed.
-
-A member sees their own record, newest first, at the bottom of
-**/usercp/security**. An operator sees the board's, filterable by kind, at
-**Admin → Sign-in activity**. It is deliberately separate from the admin
-log: that one records what was done by somebody already inside, this one
-records how they got in.
-
-Each entry keeps the truncated address and a shortened user-agent string,
-which is what makes "that was not me" answerable. Writing an event never
-blocks the thing it records: a sign-in that works but goes unrecorded is a
-gap in an audit trail, while a sign-in refused because the trail was
-unwritable would be an outage.
-
-A refused sign-in is filed against the account whose name or address was
-typed, when there is one, so the member reading their own page sees the
-attempts made on their account rather than only their own mistakes. What the
-board *answers* the person at the keyboard does not change: the response to
-a wrong password is the same whether or not the name exists, and the log is
-not a surface anybody outside can read.
-
-Two kinds of entry come from the panel rather than from the member: an
-address changed by staff, and a second factor cleared by staff. Both are
-filed against the member so they appear on their own page, and both are
-recorded without an address or a device — that would be the administrator's,
-not theirs. Who did it, and from where, is in the admin log.
-
-### How long it is kept
-
-**Days of sign-in activity to keep** (`security.auth_event_retention_days`,
-under **Admin → Settings → Security**) is **0** by default, which keeps every
-entry forever: an audit trail that deletes itself without being asked is one
-you cannot rely on. Set it to a number of days where a retention policy says
-you must, and the hourly `authevents.prune` task drops anything older, in
-batches, from then on. Lowering it deletes history that cannot be recovered
-without a restore.
+This revokes sessions and records recovery in admin and member security logs. Re-enrol afterwards. Use the [deployment invocation](operator-cli.md#the-operator-cli).
 
-## Federated sign-in
+### Sign-in gates
 
-### What a member sees
+Password and federated sign-ins on enrolled accounts create a ten-minute, single-use pending proof rather than a session. The second screen accepts an authenticator code, unused recovery code or enrolled passkey. It rechecks account standing. Wrong codes have separate lockout accounting; already-used TOTP codes are refused.
 
-The sign-in and registration pages grow a **Continue with …** button for
-each provider that is switched on and fully configured. Each button is a
-form that posts to this board first, so it works with JavaScript off and
-cannot be triggered by another site.
+Passkey sign-in satisfies the complete proof and does not additionally request TOTP. The admin panel independently requires password reauthentication and, when enrolled, a second factor. Its pending proof also expires after ten minutes.
 
-Between the button and the provider there is a page that says where the
-member is being sent, then follows itself immediately. That hop is not
-decoration: the board's content policy carries `form-action 'self'`, so a
-browser refuses to let a form submission
-end anywhere but this board — including through a redirect. Handing off from
-a page keeps that restriction intact, and leaves a plain link behind for any
-browser that does not follow the refresh.
+## Sessions
 
-Signing in this way for the first time either finds the member's existing
-account or opens a new one. After that it is simply another way in,
-alongside their password if they have one.
+The security page lists live sessions with device, truncated address, creation and last-use times. Revocation applies on the next request. **Sign out everywhere else** retains the current session and refuses if that session cannot be identified.
 
-### Turning a provider on
+**Keep me signed in** rotates one-use tokens at `/auth/resume`. Duplicate use within 30 seconds of rotation permits concurrent tabs; later reuse revokes the token family and all account sessions. Already-revoked families remain refused during the grace window.
 
-Every provider needs three things: a switch, a client ID and a client
-secret. The secret is stored like every other secret setting — written
-once, never shown again, and left alone when the box is submitted empty.
+Resumption and SSO accept top-level navigations, including service-worker forwarding with an empty destination. Background fetches and iframe navigations are refused.
 
-Each provider also needs a **callback URL**, which you give to the provider
-when you register the board as an application. It is your board's address
-followed by:
+## Security history
 
-| Provider | Callback URL |
-|---|---|
-| GitHub | `/auth/sso/github/callback` |
-| Google | `/auth/sso/google/callback` |
-| Any OpenID Connect provider | `/auth/sso/oidc/callback` |
-
-The board builds that URL from `APP_URL` if set, otherwise from **Board
-address** in the settings, falling back to the host the request arrived on.
-Set the board's address before configuring a provider: a callback the
-provider does not recognise is refused, and a callback built from a host
-header behind a misconfigured proxy is worse.
-
-#### GitHub
-
-Register an OAuth app in GitHub's developer settings. The board asks for
-`read:user` and `user:email`, and reads the primary verified address from
-the list GitHub returns. It keys the account on GitHub's numeric user ID,
-not the login, so a member who renames themselves on GitHub keeps their
-account here.
-
-If the member refuses the e-mail scope, the board falls back to whatever
-public address the profile carries and treats it as unconfirmed — enough to
-register a new account under the board's own e-mail confirmation, and not
-enough to be handed an existing one.
-
-#### Google
-
-Create an OAuth 2.0 client in the Google Cloud console. Nothing else needs
-configuring: Google is reached through the same OpenID Connect path as any
-other provider, with its issuer already known.
-
-#### Any other OpenID Connect provider
-
-This is the generic path, and usually the one an organisation wants: Entra
-ID, Okta, Keycloak, Authentik, Zitadel, or something you run yourself. Give
-the board the **issuer URL** — the one that answers at
-`{issuer}/.well-known/openid-configuration` — and it reads every endpoint
-and signing key from there. An issuer with a path works, which is what
-Keycloak realms and Entra tenants look like.
-
-**Scopes** default to `openid email profile`, the least an account can be
-built from; `openid` is always sent whether or not you list it.
-
-**What to call it** fills the gap in "Continue with …". Left empty, the
-button reads "Single sign-on", which tells a member nothing about which
-login they are about to be sent to — set it to the name your organisation
-uses.
-
-### Meeting an account that already exists
-
-A federated sign-in resolves to an account in one of three ways:
-
-1. **The identity is already linked.** The member is signed in to the
-   account holding that link. Nothing about the account changes.
-2. **The provider has confirmed an address that matches a member here.**
-   The two are linked and the member is signed in. The address must be
-   confirmed *by the provider*: an unconfirmed address is refused, with a
-   message telling the member to sign in with their password and link the
-   two themselves. Otherwise anybody able to set an unverified address at
-   any provider could claim any account on the board.
-3. **Neither.** A new account is opened — if the board is open to new
-   members.
-
-In the first two cases the account may already hold a second factor, and
-then "signed in" means the same thing it does after a password: the sign-in
-is held for the member's code before a session begins. See
-[what signing in looks like](#what-signing-in-looks-like).
-
-### What a new account inherits
-
-First-login provisioning goes through the same door as registration, not
-around it:
-
-- **Registration closed** refuses the sign-in. A closed board stays closed.
-- **The registration IP limit** is spent before the account is created, so
-  a federated route cannot outrun the anti-spam settings.
-- **Ban filters** are consulted exactly as for a typed registration — the
-  same check, against the username, the e-mail address and the address the
-  request came from.
-- **The activation method is honoured.** `none` opens an active account.
-  `email` accepts the provider's confirmation of the address in place of
-  the board's own, and sends the board's own confirmation link when the
-  provider will not vouch for it. `admin` holds the account for approval.
-  `both` records the address as confirmed and still waits for an
-  administrator.
-- **The default member group** is the same one registration uses, so group
-  promotions, permissions and held-first-post settings all apply
-  unchanged.
-
-The username comes from the provider's username, then its display name,
-then the local part of the address — folded through the same rules a typed
-username meets (allowed characters, length, the reserved list, the
-case-insensitive uniqueness check), with a number appended when the obvious
-name is taken. A provisioned account has **no password**: the password form
-refuses it until the member sets one, from the UserCP or through the
-password-reset flow to their confirmed address.
+Members see their security history at `/usercp/security`; administrators use **Sign-in activity**. Events include successful/refused sign-in, factor/recovery use, credential changes, sign-out and session revocation. Addresses are truncated and user-agent strings shortened. Audit-write failure does not block sign-in.
 
-### Linking and unlinking
+Set `security.auth_event_retention_days` under Security. Zero retains indefinitely; positive values let hourly `authevents.prune` delete older entries in batches. Deleted history requires a backup to recover.
 
-Adding a passkey or linking another SSO identity requires recent proof of a credential the member already controls. The proof is bound to the current session and remains valid for 10 minutes; another session, including one restored from a remember token, cannot reuse it.
+## Federated sign-in
+
+Enable each provider and set its client ID and secret. Secret fields are write-only; blank submission retains the stored value. Configure the board's public `APP_URL` or saved **Board address** before registering callbacks.
+
+| Provider | Callback | Additional configuration |
+|---|---|---|
+| GitHub | `/auth/sso/github/callback` | OAuth app; `read:user` and `user:email` |
+| Google | `/auth/sso/google/callback` | OAuth 2.0 client; known OIDC issuer |
+| OIDC | `/auth/sso/oidc/callback` | Issuer URL, button label and scopes |
 
-A member can prove a current password, an enrolled passkey, an authenticator or recovery code, or an already-linked SSO identity. Recovery-code proof consumes that code. Passkey registration and SSO linking check the same session-bound proof both when the flow starts and immediately before the new credential is persisted.
+OIDC discovery reads `{issuer}/.well-known/openid-configuration`. Scopes default to `openid email profile`; `openid` is always included. Private issuer networking requires the deliberate `OIDC_ALLOW_PRIVATE_HOSTS` override.
 
-A member manages their own links at **/usercp/security**: every linked
-provider, when it was linked, when it was last used, and a button to unlink
-it. A provider that is switched on and not yet linked appears as a
-**Link …** button, which starts the same handshake in linking mode.
+Resolution order:
 
-One provider identity only ever belongs to one account: trying to link an
-identity another member already holds is refused rather than moved.
+1. Use an already-linked provider identity.
+2. Link a provider-verified email to a matching board account.
+3. Otherwise provision a new account if registration permits it.
 
-Unlinking is refused when it would leave the account with no way in at all
-— no password, no passkey and no other link. Set a password first. Only
-credentials the board would accept *today* count: a passkey on a board that
-has switched passkeys off, or a link to a provider the operator has turned
-off, opens nothing and is not treated as a way back in.
+An unverified email cannot claim an existing account; the member must sign in and link manually. GitHub identities use numeric user IDs; a public fallback email is unverified.
+
+Provisioning honours registration closure, address limits, ban filters, activation policy and the default member group. Provider verification can satisfy email confirmation; administrator approval still applies. New accounts have normalised unique usernames and no password until one is set.
+
+### Linking and unlinking
 
-Operators who would rather members did not manage this themselves can turn
-off **Let members link and unlink their own sign-ins**. Existing links keep
-working; the page stops offering to change them.
+Adding a passkey or identity requires proof of an existing credential, bound to the current session for ten minutes and rechecked before persistence. Password, enrolled passkey, authenticator/recovery code or an already-linked identity can provide proof. Recovery proof consumes its code.
+
+One provider identity can belong to only one account. Removing the last currently usable credential is refused; disabled providers/passkeys do not count as usable. **Let members link and unlink their own sign-ins** can disable self-management without invalidating existing enabled links.
 
 ## Passkeys
 
-Turn on **Allow passkeys** and members can add one from
-**/usercp/security** — a fingerprint, a face, or a hardware security key,
-depending on the device. Adding and using one needs JavaScript, because the
-browser's credential API has no form equivalent; everything else on the
-page still works without it.
-
-A member may hold up to twenty passkeys, each with a label of their own
-choosing so one device can be told from another later. The list shows when
-each was added and last used, and removing one takes effect immediately. As
-with unlinking, the last remaining way into an account cannot be removed.
-
-Signing in with a passkey is a button on the sign-in page, shown when the
-browser supports them. The board accepts ES256, RS256 and Ed25519
-credentials, checks the signature against the stored public key, and
-refuses a signature counter it has already seen — the standard clone
-check.
-
-A passkey does not replace the member's password unless they clear it
-themselves, and it clears the account-standing bar in full: a banned or
-unactivated account is refused a passkey sign-in exactly as it is refused a
-password one. What a passkey sign-in does not do is then ask for the
-authenticator code — a passkey is a phishing-resistant factor already, so it
-is accepted as the whole proof. That exception is the passkey's alone; a
-password or a federated sign-in on an account with a second factor is still
-held for the code. [What signing in looks like](#what-signing-in-looks-like)
-sets out the reasoning.
-
-## How the handshake is kept honest
-
-- Every federated sign-in starts with a `POST` from a page on this board,
-  and the route refuses a request that did not come from here. A sign-in
-  cannot be started by a link on another site — which is what would
-  otherwise let somebody drop a victim into an account that is not theirs.
-- The hand-off page is reached only with a live handshake cookie, and the
-  address it forwards to is the one the board built a moment earlier —
-  never anything a query string carried in.
-- The state — and on the OpenID Connect path, the nonce and the PKCE
-  verifier — is drawn fresh per attempt and held in a short-lived,
-  HTTP-only cookie. The callback refuses anything whose state does not
-  match, and the cookie is cleared before the response is read either way.
-- On the OpenID Connect path, the identity token is verified against the
-  provider's published signing keys: signature, issuer, audience, expiry
-  and nonce, with a two-minute allowance for clock skew. An unsigned
-  token, or one signed with an algorithm the board does not accept, is
-  refused.
-- The post-sign-in destination is checked with the same helper every other
-  redirect on the board uses, so a crafted `next` parameter cannot bounce a
-  member off-site.
-- The passkey challenge is held in a strict, HTTP-only cookie and is bound
-  to the purpose it was issued for — a challenge issued for enrolment
-  cannot be answered with a sign-in, and one issued to finish a second
-  factor is scoped to that member's own credentials.
-- A half-finished sign-in is a token that grants nothing on its own: it
-  names the account waiting on its second factor, is spent exactly once,
-  and the account's standing is checked again before the session begins.
-
-## When something goes wrong
-
-Failures land the member back on the page they started from with a plain
-explanation, and the detail goes to the board's log under the `sso` or
-`passkeys` module. The board never puts a provider's own words on its
-pages.
-
-| What the member sees | Usually means |
+Enable **Allow passkeys**. Registration and use require browser support and JavaScript. Each member may hold up to 20 labelled passkeys. Removal is immediate and cannot remove the last usable credential.
+
+The board verifies ES256, RS256 or Ed25519 credentials, origin/purpose and signature counters. Banned or inactive accounts remain refused. A passkey can finish a pending second-factor challenge or sign in directly.
+
+## Protocol checks and failures
+
+SSO starts with a same-origin POST and uses a checked hand-off page. State, nonce and PKCE values are fresh per attempt. OIDC checks signature, issuer, audience, expiry and nonce with two minutes of clock-skew tolerance. Redirects stay within accepted destinations. Pending proofs grant no account access.
+
+| Failure | Check |
 |---|---|
-| That sign-in attempt had expired | More than ten minutes passed, or cookies were dropped between the two requests |
-| The sign-in was cancelled | The member said no at the provider |
-| That way of signing in is not switched on | The provider was turned off, or its credentials cleared, mid-handshake |
-| An account here already claims that identity | The provider account is linked to a different member |
-| The provider did not send enough to open an account with | No address came back — check the scopes |
-| That code is not right | The app's clock has drifted more than thirty seconds, or the code belongs to another account in the app |
-| That code has been used already | The same code was submitted twice — wait for the next one |
-
-A provider that has been switched off stops appearing and stops accepting
-callbacks. The links themselves are kept, so turning it back on restores
-every member's access without them doing anything.
+| Expired attempt | Ten-minute limit and retained cookies |
+| Provider unavailable | Enabled state and credentials |
+| Identity already claimed | Link belongs to another account |
+| Insufficient profile | Email scopes and provider response |
+| Wrong TOTP | Correct account and device clock |
+| Reused TOTP | Wait for a new code |
+
+Details are logged under `sso` or `passkeys`; provider error bodies are not displayed to members. Disabling a provider preserves its links for re-enabling.
diff --git a/docs/operations/backups.md b/docs/operations/backups.md
index 7df1a3efe..fa49becd8 100644
--- a/docs/operations/backups.md
+++ b/docs/operations/backups.md
@@ -1,86 +1,65 @@
-# Back up and restore a board
+# Backups and restore
 
-Protect the database, uploaded files and deployment secrets. A backup bundle covers data; it does not contain the environment. Use [Disaster recovery](disaster-recovery.md) when replacing a lost server.
-
-## Know what a bundle contains
-
-A `meith-backup-….tar.gz` bundle contains `db.dump`, `manifest.json` and, when included, `uploads.tar.gz`. Read the manifest to check the originating version, file driver and any missing objects.
-
-| Upload driver | Automatic inclusion |
-|---|---|
-| `local` | Included |
-| `blob` | Included |
-| `s3` | Skipped; select Always include for a self-contained bundle |
-
-An S3 bucket still needs its own recovery plan when excluded. A database-only restore cannot recreate missing attachments.
-
-Keep the original `AUTH_SECRET` and other credentials separately. Losing `AUTH_SECRET` prevents decryption of sealed settings and enrolled authenticator secrets.
+Protect PostgreSQL, uploads and the deployment environment. Bundles contain `db.dump`, `manifest.json` and optionally `uploads.tar.gz`; they do not contain deployment environment variables. Database-stored secrets remain in the dump, including sealed settings. Keep the original `AUTH_SECRET` separately to decrypt sealed settings and authenticator secrets.
 
 ## Schedule backups
 
 1. Open **Admin → Settings → Backups**.
-2. Choose daily or weekly backups and a time in UTC.
-3. Set count and age retention. Zero age means no age limit; the newest bundle is retained.
-4. Choose whether uploads are included.
-5. Configure and test an off-site destination.
-6. Open **Admin → System → Backups**, request a backup and inspect its completed run.
-
-Backups need a running worker. The screen records pending, running, completed and failed work. A successful local file with a failed off-site upload is still a failed run to investigate. Retention pruning does not discard the last good backups after a failed run.
+2. Select daily/weekly timing in UTC, count/age retention and upload inclusion.
+3. Configure and test an off-site destination.
+4. Request a backup under **Admin → System → Backups** and inspect completion.
 
-Off-site storage can use supported S3-compatible or WebDAV destinations. Configure through the panel or the appropriate `BACKUP_S3_*`/`BACKUP_WEBDAV_*` environment values. Environment credentials take precedence where supported. Use the destination test and actually list or fetch a saved bundle.
+A worker is required. Zero age disables age-based expiry; the newest bundle is retained. Failed off-site shipping is a failed run even if the local bundle exists. Failed runs do not prune the last good backups.
 
-## Configure an off-site destination
+Local and Blob uploads are included automatically; S3 uploads are skipped by default. Select **Always include** for a self-contained S3 bundle.
 
-Choose one destination. These variables are separate from the upload-store credentials:
+## Off-site configuration
 
-| Destination | Required values | Optional values |
+| Destination | Required | Optional |
 |---|---|---|
-| S3-compatible | `BACKUP_S3_BUCKET`, `BACKUP_S3_REGION`, `BACKUP_S3_ACCESS_KEY_ID`, `BACKUP_S3_SECRET_ACCESS_KEY` | `BACKUP_S3_ENDPOINT`, `BACKUP_S3_PREFIX` |
-| WebDAV | `BACKUP_WEBDAV_URL` pointing to a collection | `BACKUP_WEBDAV_USERNAME` and `BACKUP_WEBDAV_PASSWORD`, supplied together |
+| S3 | `BACKUP_S3_BUCKET`, `BACKUP_S3_REGION`, `BACKUP_S3_ACCESS_KEY_ID`, `BACKUP_S3_SECRET_ACCESS_KEY` | `BACKUP_S3_ENDPOINT`, `BACKUP_S3_PREFIX` |
+| WebDAV | `BACKUP_WEBDAV_URL` collection URL | `BACKUP_WEBDAV_USERNAME` and `BACKUP_WEBDAV_PASSWORD` together |
 
-A configured environment destination takes precedence over the saved destination. Incomplete credentials or simultaneous S3 and WebDAV destinations are rejected. Use HTTPS for remote WebDAV storage. A prefix separates this board's bundles within a shared bucket.
+Use HTTPS for remote WebDAV. Environment destinations override saved settings. Incomplete or simultaneous S3/WebDAV configurations are rejected. Backup credentials are separate from upload credentials. Verify an actual remote bundle, not only a connection test.
 
-## Take a manual backup
+## Manual backup
 
-From a generated board checkout with its production environment deliberately selected:
+In a board checkout configured for the intended database:
 
 ```sh
 npm run meith -- backup --out /secure/backups/board.tar.gz --uploads include
 ```
 
-The parent directory must exist and be writable. The output path must not already exist. Use a new filename for each manual backup.
-
-For a Compose deployment, mount a host destination and use the host user's permissions:
+The parent must exist; the output must not. Use a new filename each time. For Compose:
 
 ```sh
 mkdir -p backups
-docker compose run --rm --no-deps --user "$(id -u):$(id -g)" -v "$PWD/backups":/backup web \
+docker compose run --rm --no-deps --user "$(id -u):$(id -g)" \
+  -v "$PWD/backups":/backup web \
   meith backup --out /backup/board.tar.gz --uploads include
 ```
 
-The dump uses `DIRECT_DATABASE_URL` when provided. `--dir` writes a timestamped ring; `--keep` overrides retention and `--uploads include|skip` overrides inclusion. See `meith backup --help` for the installed version.
+`DIRECT_DATABASE_URL` is preferred for the dump. `--dir` writes a timestamped ring, `--keep` overrides retention, and `--uploads include|skip` overrides inclusion.
 
-Exit 0 means complete. Exit 2 means a bundle was written but its manifest lists missing objects. Preserve that bundle, investigate the named objects, and take a complete backup after repair. Other failures need investigation; an empty or truncated claimed output file is not a usable backup.
+Exit 0 means complete. Exit 2 means a bundle exists but its manifest names missing objects: preserve it, repair the cause and take another backup. Other failures require investigation; do not use empty or truncated files.
 
 ## Restore into a separate destination
 
 > [!CAUTION]
-> Restore into an empty destination. Keep the live board and original backup intact until the restored board has passed verification.
-
-For a fresh deployment, unlock `/install` and choose its restore flow. Select a local or off-site bundle, confirm that you retained the original `AUTH_SECRET`, and follow the checks. The installer refuses a populated board and unsupported newer backups.
+> Keep the source board and backup intact. CLI restore requires an empty database; do not run migrations or installation on that destination first.
 
-For a CLI restore, set `RESTORE_DATABASE_URL` to the empty destination, then run the installed CLI with the correct destination file-store environment:
+Set `RESTORE_DATABASE_URL` to the empty destination and configure its file store. Then, from a board checkout:
 
 ```sh
 npm run meith -- restore /secure/backups/board.tar.gz --uploads-dir /restore/uploads
 ```
 
-The explicit restore database variable is required; `DATABASE_URL` alone is not an instruction to overwrite the live board. Verify whether the bundle carries uploads and whether the destination uses local or remote storage before choosing flags.
+Use an empty upload directory. Omit `--uploads-dir` to use the destination's configured store. `DATABASE_URL` alone cannot select a restore target.
 
-## Rehearse and verify
+Alternatively, unlock `/install` on a fresh deployment and select its restore flow. This route can replace an uninstalled schema but refuses a board with members. Both routes reject unsupported newer backups. Restore applies missing migrations; inspect any partial-failure message before retrying against the now-populated target.
 
-Start the restored board privately. Check member sign-in, a private forum, a long thread, attachments, avatars and sealed settings. Confirm the expected version and counts. Record the elapsed recovery time and the result.
+## Verify
 
-Serverless deployments run backups and restores from an external machine with the required database tools and storage access. The admin backup process is unavailable inside those functions.
+Start privately and check accounts, private forums, old/recent posts, attachments, avatars and sealed settings. Record recovery time and results. Excluded uploads need a separate recovery copy.
 
-Before an upgrade, take a fresh backup. **Back up before migrating** can require one before pending core migrations, but this does not replace a tested recovery procedure.
+Run serverless backups/restores externally with PostgreSQL tools and storage access. **Back up before migrating** can require a pre-migration backup but does not replace restore testing. See [Disaster recovery](disaster-recovery.md).
diff --git a/docs/operations/configuration.md b/docs/operations/configuration.md
index 81cce4055..67dd7cfae 100644
--- a/docs/operations/configuration.md
+++ b/docs/operations/configuration.md
@@ -1,42 +1,32 @@
 # Board configuration
 
-Meith has three configuration layers. Choose the layer before changing a value; it determines whether you need a rebuild, a restart or only a save in the admin panel.
-
-## Choose the right layer
-
-| Layer | Examples | How changes take effect |
+| Layer | Values | Apply changes |
 |---|---|---|
-| Board repository | Engine version, installed themes and plugins | Build and deploy the board |
-| Environment | Database, infrastructure drivers, deployment secrets | Update the deployment environment and restart or redeploy affected services |
-| Database-backed settings | Board name, registration, spam controls, appearance | Save through the admin panel; no code deployment |
+| Repository | Engine, themes, plugins | Build and deploy |
+| Environment | Infrastructure and secrets | Restart/redeploy affected services |
+| Admin settings | Name, registration, permissions, appearance | Save in the panel |
 
-Where a setting also supports an environment override, the explicit environment value wins. Setting a value in the panel cannot override a value pinned in the environment.
+Supported explicit environment overrides take precedence over saved settings.
 
-## Understand the board repository
+## Board files
 
 | File | Purpose |
 |---|---|
 | `package.json` | Exact engine and dependency versions |
-| `meith.config.ts` | Themes, default theme and static plugin registration |
-| `board.plugins.json` | Plugin packages edited by `meith plugin:add` and `plugin:remove` |
-| `meith.plugins.ts` | Generated imports and installed-plugin registry |
+| `meith.config.ts` | Themes, default theme and static plugins |
+| `board.plugins.json` | Packages managed by `plugin:add`/`plugin:remove` |
+| `meith.plugins.ts` | Generated plugin imports and registry |
 
-Installable code must be present at build time. Adding a package to a running container does not add it permanently to the board. Follow [Install plugins and themes](installing.md), then commit and deploy the board files.
+Use pnpm for the Meith source workspace. Generated boards use npm: their build requires a hoisted dependency layout, and the updater, plugin installer and Docker builds use npm. Keep the generated `.npmrc` and commit `package-lock.json`.
 
-## Set the runtime environment
+Install code in the repository, not a running container. See [Install extensions](installing.md).
 
-Use your generated `.env.example` as the starting point. Keep credentials outside git and make sure web, worker and maintenance commands use the intended database and file store.
+## Runtime
 
-Run the check from the board checkout:
+Start from the generated `.env.example`, keep secrets out of git and use matching database/store configuration for web, worker and CLI.
 
 ```sh
 npm run meith -- env:check
 ```
 
-For container and hosted invocations, see [Operator commands](operator-cli.md). The command reports the resolved data source and redacts known secrets. Without `DATABASE_URL`, the board may be running the read-only sample dataset.
-
-Read [Environment variables](environment.md) for common settings and [Database connections](database-operations.md) for pooled/direct URLs.
-
-## Configure the community
-
-Use [Community administration](../administration/organiser-guide.md) for browser-managed settings. Forums, groups, posts, members and attachment metadata live in PostgreSQL; uploaded files live in the selected file store. Protect both with [backups](backups.md).
+Run from the board directory. The check reports the resolved data source and redacts known secrets. Without `DATABASE_URL`, development normally uses fixtures. See [Environment](environment.md), [Database connections](database-operations.md) and [Administration](../administration/organiser-guide.md).
diff --git a/docs/operations/coolify.md b/docs/operations/coolify.md
index 731fa2195..235d51d88 100644
--- a/docs/operations/coolify.md
+++ b/docs/operations/coolify.md
@@ -1,12 +1,21 @@
 # Deploy with Coolify
 
-Deploy a generated board repository on your server through Coolify. You need a working Coolify installation, a domain pointing to the server, and a Git repository Coolify can access.
+Deploy a generated board repository with PostgreSQL, persistent uploads and a background worker. Coolify builds and runs the Compose stack on your server.
 
-## 1. Prepare the server and repository
+## 1. Prepare the server
 
-Follow the official [Coolify installation instructions](https://coolify.io/docs/get-started/installation) and secure the panel. Use HTTPS for both the panel and the board.
+You need:
 
-Create a board from [meith-dev/template](https://github.com/meith-dev/template), or scaffold one locally with Node.js 22 or newer:
+- A working [Coolify installation](https://coolify.io/docs/get-started/installation) and a connected deployment server.
+- A domain such as `forum.example.com` pointing to that server, with ports 80 and 443 reachable for HTTPS.
+- A Git repository that Coolify can read.
+- Node.js 22+, npm and Git on your computer if you use the scaffold command below.
+
+Use a current Coolify release with support for generated variables in Git-based Compose deployments. Follow Coolify's [Docker Compose guide](https://coolify.io/docs/applications/builds/docker-compose) when connecting the repository.
+
+## 2. Create and push the board
+
+Run on your computer:
 
 ```sh
 npx create-meith my-board
@@ -14,43 +23,143 @@ cd my-board
 git commit -m "chore(board): scaffold my-board"
 ```
 
-Create an empty repository on GitHub, add it as the remote and push your board. Keep access to the repository and hosting accounts available to the community's operators.
+The scaffold creates the Git repository on `main`. Create an empty repository on GitHub, replace `YOUR_ACCOUNT` below and push:
+
+```sh
+git remote add origin git@github.com:YOUR_ACCOUNT/my-board.git
+git push -u origin main
+```
+
+Alternatively, create a repository from [meith-dev/template](https://github.com/meith-dev/template). Keep the generated Dockerfiles, Compose files and board configuration in the repository. Keep deployment secrets out of Git.
+
+The default deployment builds on the Coolify server. It does not require a successful GitHub Actions image build or a `MEITH_IMAGE` value. For a server that cannot build the image, use [prebuilt images](#use-a-prebuilt-image).
+
+## 3. Add the Coolify application
+
+In the intended Coolify project and environment, add an application from your Git repository. Authorise access to the repository if it is private, then select the deployment server.
+
+| Setting | Value |
+|---|---|
+| Build pack | Docker Compose |
+| Branch | `main` |
+| Base directory | `/` |
+| Compose file | `/docker-compose.yaml` |
+
+Save and let Coolify parse the Compose file. It defines four services: `postgres`, `migrate`, `web` and `worker`. Do not create a separate database resource for this setup.
+
+## 4. Set the domain and proxy
+
+Set the domain on **web**, using `https://forum.example.com:3000`. The `:3000` selects the internal container port; visitors use `https://forum.example.com` on the normal HTTPS port. Do not assign public domains to the other services. See [Coolify domain routing](https://coolify.io/docs/core/networking/domains).
+
+The generated Compose file declares `SERVICE_FQDN_WEB_3000` and sets `APP_URL` from `SERVICE_URL_WEB`. Verify that `APP_URL` resolves to the public HTTPS origin, without the internal port. If it does not, set the `APP_URL` entry in `web.environment` to the correct public URL and redeploy.
+
+For a board behind only Coolify's proxy, add this line to the existing `web.environment` list in the repository:
+
+```yaml
+- TRUSTED_PROXY_HOPS=1
+```
+
+Commit and push the change before deploying. If another proxy or CDN sits in front, use the actual trusted hop count. See [Trusted proxies](web-security.md#trusted-proxies). The generated stack does not publish database or web ports directly on the host.
 
-## 2. Configure the Coolify resource
+## 5. Check secrets and storage
 
-Add a Git repository resource and select Docker Compose as its build pack. Point it to the board repository, branch `main`, base directory `/`, and Compose file `/docker-compose.yaml`.
+Coolify generates these values and reuses them across services:
 
-Set the public domain, confirm DNS resolves to the server, and deploy. This route builds the image on the server.
+| Coolify variable | Used as |
+|---|---|
+| `SERVICE_PASSWORD_POSTGRES` | PostgreSQL password and the password in `DATABASE_URL` |
+| `SERVICE_BASE64_64_AUTH` | `AUTH_SECRET`; installer unlock and encrypted settings |
+| `SERVICE_BASE64_64_TICK` | `TICK_SECRET`; authentication between worker and web |
+
+Save the generated values in your password manager. Preserve the original `AUTH_SECRET` for backup recovery. Changing the PostgreSQL environment password alone does not change the password inside an existing database volume.
+
+Review the parsed persistent storage:
+
+| Volume | Container path | Contents |
+|---|---|---|
+| `pgdata` | `/var/lib/postgresql` in `postgres` | PostgreSQL data |
+| `uploads` | `/app/.uploads` in `web` and `migrate` | Attachments, avatars and board images |
+| `backups` | `/backups` in `web` and `migrate` | Local backup bundles |
+
+These mounts are defined in Compose. Keep them when redeploying; deleting the volumes deletes their data. Local volumes do not provide an off-site backup.
 
-If the server cannot complete the build, use `/docker-compose.prebuilt.yaml` instead. Wait for the board repository's **Build and push** workflow, then set `MEITH_IMAGE` to the image printed in its summary. Make the image accessible to Coolify. A commit-specific tag identifies one build; a moving tag can change on a later redeploy.
+## 6. Deploy and check the services
 
-## 3. Check the services and secrets
+Select **Deploy** and inspect the deployment log.
 
 | Service | Expected result |
 |---|---|
-| `postgres` | Healthy, with a persistent data volume |
-| `migrate` | Exited with code 0 after applying core migrations |
-| `web` | Running at the public HTTPS address |
-| `worker` | Running the HTTP tick loop |
+| `postgres` | Healthy |
+| `migrate` | Exits with code 0 after applying core migrations |
+| `web` | Starts after migration succeeds; readiness check passes |
+| `worker` | Remains running and calls the web tick approximately every minute |
+
+An exited `migrate` container is expected. If it fails, resolve its error before starting web. The worker logs failed HTTP calls; actual task execution logs are in `web`. A quiet worker log alone does not prove successful tasks.
+
+From your computer, check the public endpoints:
+
+```sh
+curl --fail-with-body https://forum.example.com/api/health
+curl --fail-with-body https://forum.example.com/api/ready
+```
 
-The scaffold worker calls the web service; task execution logs are in `web`. The worker logs failed calls and can otherwise be quiet.
+Both should return HTTP 200 with `ok: true`. Check the response body as well as the status.
 
-Coolify supplies the database password, `AUTH_SECRET`, `TICK_SECRET` and public URL. Check `APP_URL` and save the generated secrets outside the server. In the resource environment, the generated values are named `SERVICE_PASSWORD_POSTGRES`, `SERVICE_BASE64_64_AUTH` and `SERVICE_BASE64_64_TICK`.
+Compose redeployments can interrupt service. Coolify's application-level [rolling updates](https://coolify.io/docs/applications/deployments/rolling-updates) do not apply to Docker Compose applications.
 
-Expect an interruption during a Compose redeploy; a healthcheck does not by itself provide a rolling deployment.
+## 7. Complete installation
 
-## 4. Complete installation
+1. Open `https://forum.example.com/install`.
+2. Resolve any preflight errors and unlock with the generated `AUTH_SECRET` value.
+3. Enter the board name and administrator details. Choose your own username; reserved role names are not ordinary posting names.
+4. Configure email and verify the test message. The `log` driver records messages without delivering them.
+5. Complete installation and sign in. The installer is then sealed; `/install` returns 404.
 
-Open `https://your-domain/install`. Resolve preflight blockers, unlock with `AUTH_SECRET`, and enter the board name and administrator details. Choose your own username; reserved role names are not ordinary posting names.
+If you defer email, configure it at `/admin/settings?group=mail` before requiring email confirmation. Leave `MAIL_DRIVER` unset or `log` to use saved board settings; an explicit SMTP or HTTP driver overrides them. See [Email](mail.md).
 
-Configure email and check the test message before completing the installer. With the log driver, messages are logged but not delivered. If you skip mail, configure and test it later under `/admin/settings?group=mail` before requiring email confirmation.
+Complete [Set up a community](../administration/first-steps.md), including a normal member's registration, posting, attachment and private-forum checks.
 
-Installation creates the initial board and seals the installer. `/install` then returns 404. Core migrations must already have completed; the installer does not replace the migration service.
+## 8. Set up backups
 
-## 5. Protect and open the community
+1. Configure an off-site destination under **Admin → Settings → Backups**, or supply the `BACKUP_S3_*` or `BACKUP_WEBDAV_*` variables in Coolify and redeploy.
+2. Set the schedule, retention and upload inclusion.
+3. Request a backup under **Admin → System → Backups**. Confirm completion and the remote copy.
+4. Rehearse a restore into a separate database and upload store.
 
-Follow [Backups](backups.md) to configure off-site copies and rehearse a restore. Then complete [Set up your community](../administration/first-steps.md).
+The generated Compose files pass the backup environment variables to both `web` and `migrate`. Save secrets separately from bundles. Use [Backups and restore](backups.md) for destination fields and recovery commands.
 
-Use the resource's Terminal for deployed maintenance commands such as `meith env:check`. Package installation belongs in the board checkout, followed by commit, build and redeploy. See [Install extensions](installing.md) and [Upgrade Meith](upgrading.md).
+## Use a prebuilt image
 
-For a failed deployment, inspect the migration result and web logs, then use [Troubleshooting](troubleshooting.md).
+Use this route to build in GitHub Actions and pull the result on the Coolify server.
+
+1. Push the board to GitHub and wait for **Build and push** to succeed. The workflow uses the repository's `Dockerfile.prebuilt`.
+2. Copy the commit-specific image from the workflow summary, such as `ghcr.io/your-account/my-board:<commit-sha>`.
+3. Make the GHCR package public, or configure registry credentials that allow Coolify to pull it.
+4. Change the resource's Compose file to `/docker-compose.prebuilt.yaml` and set `MEITH_IMAGE` to that image.
+5. Carry any local Compose changes, including proxy trust, into the prebuilt file. Keep the same secrets and persistent volumes.
+6. Save, deploy and repeat the service and readiness checks.
+
+For each update, wait for the new workflow run and change `MEITH_IMAGE` to its commit-specific tag. A `latest` tag can select a different build on a later redeploy.
+
+## Maintenance and troubleshooting
+
+Open the resource's Terminal for the **web** container. The deployed CLI is on `PATH`:
+
+```sh
+meith env:check
+meith task:list
+```
+
+Check task timestamps and failures under **Admin → System**. Do not install packages in a running container: update the board repository, commit, push and redeploy. Follow [Install extensions](installing.md) and [Upgrade a board](upgrading.md), including backups and plugin migrations.
+
+| Problem | Check |
+|---|---|
+| Image build fails | Deployment log and server resources; use the prebuilt route if needed |
+| Image pull denied | GHCR visibility, pull credentials and `MEITH_IMAGE` tag |
+| Migration fails | `migrate` logs, database health and retained credentials |
+| Proxy error or wrong site | Domain belongs to `web`, targets port 3000 and resolves to this server |
+| Incorrect links or redirects | Resolved `APP_URL` uses the public HTTPS origin |
+| Mail or scheduled work stalls | `worker` is running; inspect task outcomes and `web` logs |
+| Uploads disappear after redeploy | The `uploads` volume is still mounted at `/app/.uploads` |
+
+See [Troubleshooting](troubleshooting.md) for application errors and [Disaster recovery](disaster-recovery.md) for a failed host or restore.
diff --git a/docs/operations/custom-board.md b/docs/operations/custom-board.md
index 36ba6f66d..deba4c7d7 100644
--- a/docs/operations/custom-board.md
+++ b/docs/operations/custom-board.md
@@ -1,31 +1,10 @@
-# Move from the stock image to a custom board
+# Create a custom board from the stock image
 
-Create a board repository when you need to build extensions into your deployment. The source changes; the existing database, upload storage and secrets must remain connected to the board.
+`board:eject` creates a repository matching the running image's exact release and plugins. It does not migrate the database. Back up first and retain the existing database, upload mounts and secrets when changing deployments.
 
-## Moving to a custom board
+## Export the workspace
 
-The stock image is fixed at the version it was built at — nothing can be
-installed into a running container, which is exactly why the public
-marketplace shows a listing's install steps and links here rather than
-offering an install button. Because the stock image is itself built from
-a workspace shaped like [`create-meith`](../contributing/board-workspaces.md#the-workspace)'s
-own scaffold (see [Quickstart § Create your
-board](coolify.md)), graduating to one is generating
-those same files from *this build's own state* and repointing the deploy
-— the database is untouched, because the board's identity lives in
-Postgres, not in the image.
-
-Three steps, nothing beyond a browser, a GitHub account and the server
-you already run.
-
-### 1. Eject
-
-This runs inside the stock image, the same way every other operator
-command runs (see [Operating a board § The operator
-CLI](operator-cli.md#the-operator-cli)) — with two additions this one
-needs and no other operator command does, because this is the one that
-writes a whole new workspace onto your host rather than only reading or
-writing the database:
+From the existing Compose directory:
 
 ```sh
 mkdir my-board
@@ -34,90 +13,21 @@ docker compose run --rm --user "$(id -u):$(id -g)" \
   web meith board:eject /data/my-board
 ```
 
-Run it from the same directory you already run `docker compose` in.
-Neither addition is optional:
-
-- **`-v "$PWD/my-board:/data/my-board"`** is what makes `/data/my-board`
-  land anywhere real. The image declares no volume at `/data`, and `--rm`
-  destroys the container's own filesystem — everything eject wrote —
-  the moment the command exits, so without a bind mount the workspace
-  eject just built is gone before you can use it.
-- **`mkdir my-board` first, then `--user "$(id -u):$(id -g)"`** is what
-  lets the container actually write into it. The image runs as a fixed,
-  non-root account (`nextjs`, uid 1001) that owns nothing on your host;
-  creating the mount point yourself, rather than leaving Docker to create
-  it, keeps it owned by you instead of root; and `--user` is what makes
-  this one-off container run as you too, so the account writing and the
-  account owning the directory are the same one. Skip either half and
-  eject fails with `EACCES: permission denied`.
-
-`/data/my-board` is the container's own name for the directory it writes
-to — on your host, once the command exits, it is `my-board`, exactly
-where `mkdir` made it.
+The bind mount preserves output after the container exits. Creating it first and using the host UID/GID avoids ownership errors. The destination must be empty.
 
-`my-board` becomes a complete workspace: `package.json` pinned to
-*this image's exact release version* — never `latest`, so graduating is
-never a surprise upgrade — the full deploy kit for all three routes onto
-a server (`Dockerfile`, `docker-compose.yaml`, `Dockerfile.prebuilt`,
-`docker-compose.prebuilt.yaml`, `.github/workflows/build.yml`,
-`docker-compose.byhand.yaml`, described
-in full in [Quickstart § Create your
-board](coolify.md)),
-`board.plugins.json` matching what this build actually compiled in, and
-`meith.config.ts` matching the stock configuration. Every plugin the
-manifest names is also added to `package.json`'s own `dependencies`, at
-that same exact version, so the ejected workspace's first build can
-actually resolve the imports `meith.plugins.ts` writes for it — a
-manifest package `create-meith`'s scaffold already pins (`@meith/web`,
-`@meith/cli`, `@meith/theme-default`) is left exactly where it is rather
-than duplicated. It refuses to write into a directory that already exists
-and is not empty, the same as `create-meith` itself — the empty directory
-`mkdir` just made, and that the bind mount leaves untouched, passes.
+Output includes exact package pins, board configuration, plugin registry and source/prebuilt/by-hand deploy files.
 
-### 2. Push it to GitHub
-
-`my-board` is a plain directory, not a git repository yet:
+## Publish and deploy
 
 ```sh
 cd my-board
-git init && git add -A && git commit -m "Graduate from the stock image"
+git init
+git add -A
+git commit -m "chore(board): export stock board"
 ```
 
-Push it to a new, empty repository on GitHub. No local Docker toolchain
-needed from here — `.github/workflows/build.yml`, already written, builds
-the image on GitHub's own runners the first time this repository's `main`
-branch is pushed to.
-
-### 3. Point Coolify at it and redeploy
-
-From here it is the same three-step advanced/prebuilt deploy
-[Quickstart § Set your domain and
-deploy](coolify.md)
-describes for any scaffolded board: check the GitHub package is public,
-point Coolify at the new repository with its **Compose file** field
-changed to `docker-compose.prebuilt.yaml`, and set `MEITH_IMAGE` to the
-image step 2 just pushed, then redeploy. (The workspace also carries
-`Dockerfile` and `docker-compose.yaml` for the quick-start path — Coolify
-building the image itself, from the repository — but step 2 already built
-one, so there is no reason to build it again on the server; delete the
-quick-start pair once you are settled on this path, or leave them.)
-
-### What does not move
+Push to an empty repository. The generated workflow builds an image on `main`. In Coolify, select the repository, use `docker-compose.prebuilt.yaml` and set `MEITH_IMAGE` to that build. Alternatively, build on the server with `docker-compose.yaml`.
 
-- **The database.** `board:eject` never touches it — the same Postgres,
-  the same connection string, before and after.
-- **Uploads.** Wherever the `uploads` volume already points, it keeps
-  pointing there.
-- **Every environment variable** — `AUTH_SECRET`, `TICK_SECRET`,
-  `DATABASE_URL`, mail settings, all of it. Only where the image comes
-  from changes.
+Preserve connection strings, upload volumes, `AUTH_SECRET`, tick and mail settings. Check sign-in and attachments after deployment.
 
-Once the redeploy is live, the board is an ordinary workspace — a single
-`package.json`, not a pnpm monorepo, so it is `npm install` from here, not
-`pnpm add`: `forum-web`'s own startup check (`apps/community/bin/forum-web.mjs`)
-requires a hoisted `node_modules`, which pnpm's default isolated linker does
-not produce. Installing the plugin that started this is `npm install
-<package>` and a line in `meith.plugins.ts` — the same concept [the
-plugin API](../extensions/plugins.md) describes for this
-repository's own pnpm checkout, just without its workspace machinery —
-followed by a commit, a push, and the same redeploy.
+Use npm for subsequent package changes; see [Configuration](configuration.md). Add plugins through [Extension installation](installing.md).
diff --git a/docs/operations/database-operations.md b/docs/operations/database-operations.md
index cc96640ec..b4c3ac67c 100644
--- a/docs/operations/database-operations.md
+++ b/docs/operations/database-operations.md
@@ -1,44 +1,34 @@
-# Database migrations and connections
-
-Configure database connections and apply core migrations before serving a new build. This page explains direct connections, migration locking and the separate plugin migration step.
+# Database operations
 
 ## Migrations
 
-Applying the schema is always a separate step from starting the board. Under Compose the one-shot `migrate` service does it and `web` waits for that service to exit 0. Where the deployment has no place to run a one-shot job — a platform that only builds and serves — the same step belongs in the build command, ahead of the build:
+Run core migrations before serving a new build:
 
 ```sh
-meith migrate && forum-web build
+npm run meith -- migrate
+npm run build
 ```
 
-`meith migrate` applies every migration the installed release has that the board does not, reports how many it applied, and exits 0 having done nothing when the schema is already current. It needs no build output and no running board, so either end of a deploy is a valid place for it. A failure exits non-zero, which is what stops the `&&` and fails the deployment instead of serving new code against an old schema.
-
-The runner compares migration file hashes with `drizzle.__drizzle_migrations`
-and applies missing migrations in journal order, within one transaction.
-A failed run rolls back. For boards upgraded through the older timestamp-based
-runner, see [migration recovery](upgrade-notes.md#meith-migrate-decides-by-hash-not-by-timestamp).
-
-Once the board is up, an admin can apply pending **plugin** migrations from **Admin → System** (**Version & migrations**) after a re-entered password — the setup a newly installed plugin needs, which the Compose `migrate` service (it runs `meith migrate`, core only) does not. Core schema migrations are not run from the panel: they belong to the deploy step, run against a direct connection before `web` serves, which is what keeps it from ever serving against an older schema. The panel does count them, though: the notice on **Admin → System** and the admin index asks the database which core migrations of the running release are not recorded, and names how many are missing — whatever version the board has recorded, so a schema that fell behind is reported even when the versions agree. While any are missing the panel's own upgrade refuses to run, naming them and pointing at `meith migrate`, rather than recording the code version over a schema that is not at it. A runtime that cannot reach the migration files (a build-and-serve platform's serverless function) is the one place the count is unavailable; the notice then falls back to comparing versions, and says so once in the log.
-
-### Two migrations at once
+Run these from the board directory. Compose's one-shot `migrate` service performs this step and must exit 0 before web starts. Function-hosted builds must also run migration before build.
 
-The runner takes a session-level PostgreSQL advisory lock on a fixed key, holds it for the whole run, and releases it when the run ends — including when the run fails. Overlapping migrations therefore queue rather than race: the second waits for the first to finish, then finds the schema current and applies nothing. Two builds triggered close together cannot apply the same core migration twice.
+The runner compares file hashes with `drizzle.__drizzle_migrations`, then applies missing migrations in journal order in one transaction. Failure rolls back; an up-to-date run applies nothing. See [Older migration recovery](upgrade-notes.md#meith-migrate-decides-by-hash-not-by-timestamp).
 
-The lock covers the core migration run and nothing after it. `meith upgrade` applies each installed plugin's migrations once `runMigrations()` has returned, which is to say once the lock is already released, so two upgrades running at the same instant are serialised through the core schema but not through the plugins'. Run one upgrade at a time.
-
-Nothing has to clean up after a crash. PostgreSQL drops a session-level lock when the connection goes, so a process killed mid-run leaves the lock released and the next attempt proceeds. The lock is held in the database rather than by the board, which is what makes it cover migrations started from different machines against the same database.
-
-### Which connection migrations use
-
-`meith migrate` and `meith backup` connect over `DIRECT_DATABASE_URL` when it is set and over `DATABASE_URL` when it is not. `meith restore` is the exception in the other direction: it writes to `RESTORE_DATABASE_URL` and refuses to run without it, so a restore can never be aimed at the live board by accident. Everything else — web, worker, the tick — always uses `DATABASE_URL`.
+`meith upgrade` additionally applies enabled plugin migrations and records versions. **Admin → System → Version & migrations** handles pending plugin migrations only and refuses while core migrations are missing. If runtime migration files are unavailable, the panel falls back to version comparison.
 
 ## Connection pooling
 
-A managed database (Neon, Supabase and their kind) hands out two connection strings for the same database: a transaction-mode pooler and a direct one. They are not interchangeable, and a board wants both.
+| Process | Connection |
+|---|---|
+| Web, worker, tick | `DATABASE_URL` |
+| Migration and backup | `DIRECT_DATABASE_URL`, otherwise `DATABASE_URL` |
+| Restore | Required `RESTORE_DATABASE_URL` |
+
+For a managed transaction pooler, set both pooled `DATABASE_URL` and direct `DIRECT_DATABASE_URL`. Migrations use a session advisory lock, which transaction pooling cannot preserve. A self-hosted PostgreSQL connection without a pooler can use `DATABASE_URL` alone.
 
-Use the **pooler** string for `DATABASE_URL`. Each web process opens up to `DATABASE_POOL_MAX` connections and the count multiplies with instances, so a board on the direct string works in testing and begins refusing connections under the first real traffic, reporting an error that names the database rather than the cause.
+Each process opens its own pool (`DATABASE_POOL_MAX`, default 3, maximum 20). Budget for all web replicas, workers and maintenance processes.
 
-Use the **direct** string for `DIRECT_DATABASE_URL`. The reason is the advisory lock, and it is the only reason. `pg_advisory_lock` arrives as its own implicit transaction, so a transaction-mode pooler considers the backend free the moment it returns: the lock is left on a connection the pooler then hands to somebody else, the migration runs with nothing serialising it, and the `pg_advisory_unlock` at the end reaches an arbitrary backend, finds no lock there, and fails silently — the runner sets `onnotice` to a no-op, so the warning PostgreSQL raises never reaches a log.
+## Concurrent migrations
 
-The migrations themselves are not the problem. Every pending migration runs inside one transaction, and pinning a single backend for a transaction's whole duration is what transaction mode *is*; the only statements outside it create a schema and a table `IF NOT EXISTS`. So do not reason from the size of a release — "this one only adds a column, a pooler is fine for it" is the wrong conclusion. The lock is taken on every run, and every run needs the direct string. Setting both variables gives each job the connection it needs, with no further configuration.
+Core migration runs acquire one PostgreSQL advisory lock. Concurrent runs wait, then recheck applied hashes. PostgreSQL releases the lock when the session ends, including after a crash.
 
-A PostgreSQL you run yourself, with a fixed number of processes in front of it, has no such split and needs no pooler: leave `DIRECT_DATABASE_URL` unset and migrations use `DATABASE_URL` like everything else.
+The lock ends before plugin migrations. Run only one full upgrade at a time. If migration hangs without another run, verify the direct connection rather than assuming lock contention.
diff --git a/docs/operations/deployment.md b/docs/operations/deployment.md
index 34bf2bdb8..6c51f0902 100644
--- a/docs/operations/deployment.md
+++ b/docs/operations/deployment.md
@@ -1,25 +1,15 @@
-# Choose a deployment
+# Deployment
 
-Choose where the board will run before creating production data. Every route needs PostgreSQL, persistent uploads, working email and a way to run scheduled work.
+A production board needs PostgreSQL, persistent uploads, email and scheduled tasks.
 
-## Compare the supported routes
+| Route | Requirements |
+|---|---|
+| [Coolify](coolify.md) | Server, domain and Git repository; deployment through a panel |
+| [Docker Compose](docker-compose.md) | Server, Docker, HTTPS proxy and deployment access |
+| [Vercel](vercel.md) | Managed database, cache, uploads, mail and HTTP scheduler |
 
-| Route | Choose it when | You manage |
-|---|---|---|
-| [Coolify](coolify.md) | You have a server and want a deployment panel | The server, backups and deployment settings |
-| [Docker Compose](docker-compose.md) | You want direct control of containers and the reverse proxy | Containers, HTTPS, secrets, storage and updates |
-| [Vercel](vercel.md) | You want functions backed by managed services | Connected services, scheduler cadence and platform limits |
+For development, use a [preview](../start/quickstart.md) or [writable local board](local-board.md).
 
-For a private experiment, use a [local preview](../start/quickstart.md) or a [writable local board](local-board.md). A preview is not a production installation.
+Prepare a public domain, credentials and off-site backups. To move an existing forum, rehearse the [import](migrating.md) before creating production content.
 
-## Prepare before installing
-
-Have a public domain, database and upload-storage plan, mail provider, and somewhere off-site to keep backups and secrets. Use the chosen guide's exact environment and command context: the Meith monorepo, a generated board checkout and a deployed container are different environments.
-
-If you already run MyBB or phpBB, read [Import an existing forum](migrating.md) before inviting members or creating production content. Rehearse the import into an isolated destination.
-
-## Finish the installation
-
-The deployment guide takes you to `/install`. Complete the installer, then work through [Set up your community](../administration/first-steps.md).
-
-Before opening registration, verify email delivery, ordinary-member permissions, scheduled tasks and a restorable backup. The [operations checklist](operating.md) covers the handover.
+After deployment, complete `/install` and the [community setup checklist](../administration/first-steps.md). Verify mail, member permissions, scheduled tasks and a restore before opening registration.
diff --git a/docs/operations/disaster-recovery.md b/docs/operations/disaster-recovery.md
index d920aed3f..3d874e072 100644
--- a/docs/operations/disaster-recovery.md
+++ b/docs/operations/disaster-recovery.md
@@ -1,47 +1,13 @@
-# Recover after losing a server
+# Disaster recovery
 
-Restore a board on a replacement server. You need a backup, the board repository or exact engine version, upload recovery material and saved deployment secrets. Keep the replacement private until verified.
+Requires the backup, matching board repository/version, uploads and saved secrets. Keep the replacement private until verified.
 
-## 1. Gather the recovery material
+1. Recover the original `AUTH_SECRET`, database/store credentials, mail settings and scheduler secrets. A new authentication secret cannot decrypt old sealed data.
+2. Recreate the board at the backup's version, including its themes and plugins. Upgrade after recovery.
+3. Prepare persistent storage and an empty database. For CLI restore, start PostgreSQL alone; running the migration service first makes the target non-empty. The installer restore route instead accepts an uninstalled schema.
+4. Follow [Restore](backups.md#restore-into-a-separate-destination). Confirm uploads are included or recover them separately. Inspect incomplete-bundle and partial-restore messages.
+5. Start privately. Test administrator/member sign-in, private forums, old/recent threads, attachments, avatars, public URL, sealed settings and controlled mail delivery.
+6. Switch DNS or proxy routing after verification. Check HTTPS externally and resume the intended scheduler; retire the obsolete scheduler.
+7. Configure off-site backups on the replacement, verify a new bundle and record losses and recovery time.
 
-| Material | Why it is needed |
-|---|---|
-| Database bundle | Accounts, posts, permissions, settings and task state |
-| Uploads or a surviving object store | Attachments, avatars and board images |
-| Original `AUTH_SECRET` | Decrypt sealed credentials and authenticator secrets |
-| Other deployment credentials | Access database, mail, uploads, backups and scheduler |
-| Board repository and version | Recreate installed plugins, themes and compatible code |
-
-A backup bundle does not include the environment. Exhaust secure copies before replacing a lost authentication secret; generating a different value does not decrypt the old data.
-
-## 2. Recreate the deployment
-
-Recover the board repository at the version used by the backup. If it is unavailable, scaffold that exact published version and restore the board's extension configuration. Follow the relevant [deployment guide](deployment.md).
-
-Recover first and upgrade afterward. Starting with a newer release introduces a separate schema change while you are still proving recovery.
-
-Restore the saved environment, check persistent storage and keep public DNS on the old location or a maintenance page until the new board is ready.
-
-## 3. Restore the database and files
-
-Use the [backup restore procedure](backups.md#restore-into-a-separate-destination). The destination must be empty. Choose the installer restore flow on a fresh deployment or the CLI with explicit `RESTORE_DATABASE_URL`.
-
-Confirm whether uploads are inside the bundle. If the old object store survives, verify access to it; otherwise restore its objects or included files to the destination store. Do not point a recovered database at an empty bucket and assume attachments are restored.
-
-Restart web and worker after the restore as required by the chosen deployment. Review any incomplete-bundle warnings before proceeding.
-
-## 4. Verify privately
-
-Check the version, expected members and forums, several old and recent threads, private-forum permissions, attachments and avatars. Test administrator and ordinary-member sign-in and the features that depend on sealed settings.
-
-Check the public-origin setting, but avoid sending test links pointing to an unintended preview domain. Validate email delivery using a controlled account.
-
-## 5. Cut over
-
-When checks pass, update the public DNS or proxy route. Verify HTTPS and canonical links from an external client. Resume the intended scheduler and confirm task progress without leaving an obsolete scheduler active against the wrong deployment.
-
-## 6. Restore protection
-
-Enable backups and off-site shipping on the replacement. Take and verify a new bundle, record what was lost and how long recovery took, and replace obsolete deployment credentials as needed.
-
-For partial failures, use [Troubleshooting](troubleshooting.md), [Operator commands](operator-cli.md) or [Email](mail.md). A broken mail setting does not call for restoring the entire database.
+Do not delete original data until recovery is verified. Use [Troubleshooting](troubleshooting.md) for isolated failures that do not require a full restore.
diff --git a/docs/operations/docker-compose.md b/docs/operations/docker-compose.md
index 2328eb88e..9304312a0 100644
--- a/docs/operations/docker-compose.md
+++ b/docs/operations/docker-compose.md
@@ -1,34 +1,31 @@
 # Deploy with Docker Compose
 
-Run Meith on a server using Docker Compose and a reverse proxy you manage. You need Docker with the Compose plugin, a domain pointing at the server, enough disk for data and backups, and capacity to build the image. A small server may need the prebuilt route described in the generated board README.
+Requires [Docker with Compose](https://docs.docker.com/engine/install/), a server, a domain and an HTTPS reverse proxy. Forward the proxy to `127.0.0.1:3000`, preserving host and forwarded protocol. Keep PostgreSQL and the web port off the public network.
 
-## 1. Prepare hosting
+## Create the board
 
-Install Docker using its [official platform instructions](https://docs.docker.com/engine/install/). Configure your firewall and remote access without locking yourself out. Public traffic should reach the HTTPS proxy; do not expose the database or the board's plain HTTP port directly.
-
-Use a maintained HTTPS reverse proxy on the server. The steps below assume it forwards requests to `127.0.0.1:3000` and preserves the original host and forwarded protocol.
-
-## 2. Create the board
-
-With Node.js 22 or newer:
+With Node.js 22+ and npm:
 
 ```sh
 npx create-meith my-board
 cd my-board
 ```
 
-Without Node on the server, use the published installer:
+Without Node on the server:
 
 ```sh
 curl -fsSL https://www.meith.dev/create-board.sh | bash -s -- my-board
 cd my-board
 ```
 
-This guide uses `docker-compose.byhand.yaml`. The scaffold's default `docker-compose.yaml` is for Coolify.
+This route uses `docker-compose.byhand.yaml`; the default Compose file targets Coolify.
 
-## 3. Create the environment once
+## Set the environment
 
-For a new board only, run from its directory:
+For a new board only, create `.env` in its directory:
+
+> [!CAUTION]
+> This command replaces `.env`. Do not run it over an existing deployment: changing stored database credentials or `AUTH_SECRET` can break access and sealed settings.
 
 ```sh
 cat > .env <<EOF
@@ -41,14 +38,9 @@ EOF
 chmod 600 .env
 ```
 
-Change `APP_URL` to the actual public HTTPS origin. Keep `.env` outside git and store a protected recovery copy off-site.
-
-> [!CAUTION]
-> Do not rerun this command on an installed board. It replaces secrets. PostgreSQL retains the password stored in its existing volume, and changing `AUTH_SECRET` breaks sealed credentials and two-factor enrollment.
+Use the actual public origin. Keep `.env` out of git and retain a protected off-site copy.
 
-`COMPOSE_FILE` selects the by-hand file for subsequent commands. Leave the web binding on loopback; publishing `3000` on every interface exposes a route around the HTTPS proxy. Docker's port rules may bypass host-firewall assumptions.
-
-## 4. Start and check the containers
+## Start
 
 ```sh
 docker compose up -d --build
@@ -56,22 +48,12 @@ docker compose ps
 docker compose logs --since 10m migrate web worker
 ```
 
-The database starts first, `migrate` applies core migrations and exits successfully, then web and the HTTP tick worker serve the board. An exited migration container with code 0 is expected. Uploads and database data must remain on their persistent volumes.
-
-If the build runs out of memory, build elsewhere using the generated prebuilt-image workflow. Do not delete volumes to fix a build failure.
-
-## 5. Configure HTTPS and trusted proxies
-
-Point the reverse proxy at the loopback web port and configure the certificate for your domain. Confirm the public URL uses HTTPS and that redirects return to that origin.
-
-Set `TRUSTED_PROXY_HOPS` to the actual number of trusted proxies in front of Meith. Count a CDN if it is in the path. An incorrect value can make address-based protections act on the wrong client address. Do not increase it without understanding the network path.
-
-## 6. Install and verify
+The database starts first. Core migrations must exit 0 before web and worker start. Keep database and upload volumes persistent. If a build exceeds server capacity, use the generated prebuilt-image workflow; do not remove data volumes.
 
-Open `/install` on the public domain and unlock it with `AUTH_SECRET`. Resolve preflight blockers, create the administrator account and configure mail. Check delivery before enabling email activation.
+## Proxy and installation
 
-Complete [Set up your community](../administration/first-steps.md), then verify [scheduled tasks](scheduled-tasks.md), [backups](backups.md) and a restore rehearsal.
+Configure HTTPS and set `TRUSTED_PROXY_HOPS` to the actual trusted proxy count, including any CDN. Keep the web port bound to loopback; published Docker ports can bypass host-firewall assumptions.
 
-## Maintain the deployment
+Open `/install`, unlock with `AUTH_SECRET` and create the administrator. Configure and test mail. Complete [Community setup](../administration/first-steps.md), [Scheduled tasks](scheduled-tasks.md) and a [backup/restore rehearsal](backups.md).
 
-Keep the board repository and deployment secrets backed up separately. Use [Upgrade Meith](upgrading.md) for releases, [Scaling](scaling.md) for multiple web instances and [Troubleshooting](troubleshooting.md) for failures. Never use `docker compose down -v` on data you intend to keep.
+Never run `docker compose down -v` on data you intend to retain. For maintenance, use [Upgrades](upgrading.md) and [Troubleshooting](troubleshooting.md).
diff --git a/docs/operations/environment.md b/docs/operations/environment.md
index 106512d22..d612fa1fc 100644
--- a/docs/operations/environment.md
+++ b/docs/operations/environment.md
@@ -1,46 +1,40 @@
 # Environment variables
 
-Use environment variables for infrastructure and secrets. Start from the `.env.example` emitted with your board and validate the resolved configuration with `meith env:check` using the [invocation for your deployment](operator-cli.md).
-
-This page groups the main controls. The complete validation schema is `packages/core/src/env.ts`; generated examples include the settings relevant to their hosting route.
+Start from the board's `.env.example`. Run `npm run meith -- env:check` in the board directory; use [container invocations](operator-cli.md) for deployed checks. The complete schema is `packages/core/src/env.ts`.
 
 ## Database and identity
 
 | Variable | Purpose |
 |---|---|
-| `DATABASE_URL` | Runtime PostgreSQL connection; without it a development board normally selects fixture mode |
-| `DIRECT_DATABASE_URL` | Direct connection for migrations and backups when the runtime URL uses a transaction-mode pooler |
-| `DATA_SOURCE` | Explicit `postgres` or `fixture` override |
-| `DATABASE_POOL_MAX` | Per-process database pool limit; default 3, maximum 20 |
-| `AUTH_SECRET` | Signing/sealing secret; retain the original value with your recovery material |
-| `APP_URL` | Public origin used for absolute links; overrides the stored board URL |
-| `TICK_SECRET`, `CRON_SECRET` | Accepted secrets for the scheduled HTTP tick; generate independently from `AUTH_SECRET` |
+| `DATABASE_URL` | Runtime PostgreSQL URL; absent in a fixture preview |
+| `DIRECT_DATABASE_URL` | Direct migration and backup connection |
+| `DATA_SOURCE` | Explicit `postgres` or `fixture` |
+| `DATABASE_POOL_MAX` | Connections per process; default 3, maximum 20 |
+| `AUTH_SECRET` | Signing/sealing secret; retain the original for recovery |
+| `APP_URL` | Public origin; overrides saved board address |
+| `TICK_SECRET`, `CRON_SECRET` | HTTP scheduler credentials, separate from `AUTH_SECRET` |
 
-Generate secrets with `openssl rand -hex 32`. Production PostgreSQL deployments require a protected scheduler and a durable queue. Read [Database operations](database-operations.md) before choosing pooled and direct connection strings.
+Generate secrets with `openssl rand -hex 32`. Production PostgreSQL requires a protected scheduler and durable queue. See [Database operations](database-operations.md).
 
-## Drivers and uploads
+## Drivers
 
-| Variable | Choices or purpose |
+| Variable | Values or purpose |
 |---|---|
-| `QUEUE_DRIVER` | `postgres` for durable work; `memory` for non-durable fixture/development use |
-| `CACHE_DRIVER` | `memory`, `next` or `redis`; multiple instances need a shared cache |
-| `REDIS_URL` | Redis-compatible connection URL |
-| `FILESTORE_DRIVER` | `local`, `s3` or `blob` |
-| `UPLOADS_DIR` | Persistent upload directory for local storage |
-| `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | S3-compatible upload-store configuration |
-| `S3_ENDPOINT`, `S3_PUBLIC_BASE_URL` | Optional endpoint and public base URL for the selected store |
-| `BLOB_STORE_ID`, `BLOB_READ_WRITE_TOKEN` | Blob-store identity or credential, depending on deployment |
+| `QUEUE_DRIVER` | `postgres` for durable work; `memory` for fixtures/development |
+| `CACHE_DRIVER` | `memory`, `next`, `redis` |
+| `REDIS_URL` | Shared cache URL |
+| `FILESTORE_DRIVER` | `local`, `s3`, `blob` |
+| `UPLOADS_DIR` | Persistent local upload directory |
+| `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | Upload bucket credentials |
+| `S3_ENDPOINT`, `S3_PUBLIC_BASE_URL` | Optional upload-store endpoints |
+| `BLOB_STORE_ID`, `BLOB_READ_WRITE_TOKEN` | Blob identity or token |
 
-Check [Scaling](scaling.md) before changing storage or cache on a running board. A local directory inside a disposable container is not persistent storage.
+Multiple instances need [shared cache and uploads](scaling.md). Changing a driver does not move files.
 
 ## Mail and backups
 
-`MAIL_DRIVER` chooses `log`, `http` or `smtp`. `log` writes messages to logs and does not deliver them. Configure sender/provider details through the installer or mail settings, or use the explicit mail environment overrides described in [Email](mail.md).
-
-`BACKUP_DIR` selects local bundle storage. `BACKUP_S3_*` or `BACKUP_WEBDAV_*` configure an off-site destination. These credentials are distinct from the upload-store credentials. See [Backups](backups.md) for the required fields, precedence, retention and upload inclusion.
-
-## Apply changes safely
+`MAIL_DRIVER` accepts `log`, `http` or `smtp`; `log` does not deliver. See [Mail](mail.md) for provider fields and override rules.
 
-Check which values are environment overrides and which are editable board settings. Recreate affected services after changing environment values, then run `env:check` and verify the actual feature. Keep web, worker and CLI environments consistent.
+`BACKUP_DIR` selects local bundle storage. `BACKUP_S3_*` and `BACKUP_WEBDAV_*` configure separate off-site credentials; see [Backups](backups.md).
 
-Never commit secrets or copy a production environment into an untrusted preview. Backups do not contain the environment, so store a protected recovery copy separately.
+Restart affected services after environment changes and verify the feature. Keep secrets outside git and separate from data backups, which do not include the environment.
diff --git a/docs/operations/installing.md b/docs/operations/installing.md
index 6344d02f0..a026654d0 100644
--- a/docs/operations/installing.md
+++ b/docs/operations/installing.md
@@ -1,37 +1,29 @@
-# Install plugins and themes
+# Install extensions
 
-Add extensions in the board repository, then build and deploy. You need repository and deployment access. The admin panel manages installed extensions but cannot install new package code into a running container.
+Run package changes in the board repository, then commit, build and deploy. The admin panel cannot install package code.
 
-## Install a published plugin
-
-Check the package's compatibility and permissions. From the generated board directory:
+## Plugin
 
 ```sh
 npm run meith -- plugin:add @meith/plugin-awards
 ```
 
-The command installs the package, updates `board.plugins.json` and regenerates `meith.plugins.ts`. Commit the package, lockfile and registry changes. Rebuild and deploy through the board's normal route.
-
-Apply plugin migrations with the deployed CLI's `meith upgrade`, or **Admin → System → Version & migrations** after core migrations have completed. `meith migrate` alone only handles core migrations.
-
-Open **Admin → Plugins** to confirm the plugin is present and configure its settings. Verify a representative member flow.
-
-## Install a theme
+Review compatibility first. The command installs the dependency, updates `board.plugins.json` and regenerates `meith.plugins.ts`. Commit these and the lockfile, then deploy.
 
-Install its exact package version, then add it to `meith.config.ts` using its exported theme, tokens, browser color and messages. Keep the existing theme entries you still need. The [first-theme tutorial](../extensions/first-theme.md#3-register-the-theme) shows the registry shape.
+Run `meith upgrade` with the [deployed CLI](operator-cli.md), or apply plugin migrations under **Admin → System → Version & migrations** after core migrations finish. `meith migrate` handles core migrations only.
 
-Set `defaultTheme` if appropriate, commit, rebuild and deploy. Check the theme under **Admin → Themes**, including mobile and light/dark appearance.
+Check **Admin → Plugins**, configure settings and test the member flow.
 
-## Update an extension
+## Theme
 
-Read its release notes, verify Meith compatibility and take a backup before schema changes. Update the package in the board checkout, review the lockfile, rebuild and deploy, then apply pending plugin migrations.
+Use `npm install --save-exact <package>@<version>`. Register its theme, tokens, browser colour and messages in `meith.config.ts`; see the [registration example](../extensions/first-theme.md#3-register-the-theme). Set `defaultTheme` if needed, then commit and deploy. Check mobile, light and dark modes under **Admin → Themes**.
 
-An update indication in the panel is information; it is not a background package installation.
+## Update or remove
 
-## Disable or remove a plugin
+Back up before schema changes. Update the package, review the lockfile, deploy and apply migrations. Panel update notices do not install code.
 
-Disabling a plugin stops its behavior but does not mean its data has been deleted. To remove its registration, use `meith plugin:remove <key>` in the board checkout, then commit and deploy.
+Disabling a plugin retains its data. `npm run meith -- plugin:remove <key>` removes registration; commit and deploy afterward.
 
-If you intend to permanently delete its data, back up first and follow the plugin purge workflow while its code is still installed. Purge needs the plugin definition to run its uninstall lifecycle. Removing code first can prevent that cleanup.
+To delete owned data permanently, back up and run the purge workflow while the plugin code is still installed. Removing code first prevents its uninstall hook from running.
 
-For a stock image that cannot include your package, first [create a custom board](custom-board.md). To write an extension, start with [Build extensions](../extensions/extensions.md).
+Stock-image users must first [create a custom board](custom-board.md).
diff --git a/docs/operations/leaving-vercel.md b/docs/operations/leaving-vercel.md
index de317395c..253f85083 100644
--- a/docs/operations/leaving-vercel.md
+++ b/docs/operations/leaving-vercel.md
@@ -1,168 +1,29 @@
-# Move a board away from Vercel
+# Move from Vercel to a server
 
-Move an existing Vercel board to a server while preserving the database and uploads. Rehearse the restore before changing the public domain.
+Rehearse the move before changing public routing. Keep the source deployment, database and upload store until the destination is verified.
 
-## Leaving Vercel
+## Export
 
-**This is the section that makes the rest of the page acceptable.** A board
-is a community's record of itself, and a route that cannot be walked back
-is not a route this project would document. Nothing above puts your board
-somewhere you cannot get it out of, and here is the whole exit.
-
-Everything durable is in PostgreSQL, in no proprietary format, with no
-export request to file with anybody. Neon and Upstash hand out ordinary
-Postgres and Redis connection strings that any host accepts.
-
-**The uploads are the one thing you have to carry out deliberately**, and
-how much care that takes depends on the choice made under
-[blob or a bucket](vercel-configuration.md):
-
-- On **`s3`**, the objects are already in a bucket you own. It outlives the
-  Vercel project and you can copy it with any S3 tool you like.
-- On **`blob`**, they are in a Vercel Blob store, and that *is*
-  Vercel-shaped state. There is no bucket to sync, no credential to hand a
-  second tool, and deleting the Vercel project deletes the attachments with
-  it. The backup bundle is the only copy you will ever have.
-
-Either way the command below produces one bundle holding both halves, and
-the rest of this section is identical.
-
-### 1. Take a bundle that carries both halves
-
-From a checkout of your board repository, with the production environment
-in front of it:
-
-```sh
-meith backup --uploads include
-```
-
-That runs `pg_dump` over `DIRECT_DATABASE_URL` when it is set, and pulls
-**every object out of the object store** into the same bundle.
-
-The `--uploads include` flag is what forces that, and whether you need to
-type it depends on the driver:
-
-| Driver | Default | Why |
-|---|---|---|
-| `s3` | *skips* the bucket | A bucket has its own backup story and is yours already, so the bundle does not duplicate it. `--uploads include` is **not optional here** if the bundle is meant to stand alone. |
-| `blob` | *includes* the store | A Blob store has no backup story you can drive yourself, so a bundle that skipped it would be a bundle that silently lost the attachments. |
-| `local` | *includes* the directory | Same reasoning. |
-
-Passing `--uploads include` is correct and harmless under all three, so
-pass it and stop having to remember which one you are on.
-
-**Read the last line the command prints.** `the database dump and the
-uploads` means the objects are in the bundle. `the database dump, no
-uploads` means they are not, and restoring that bundle gives a board whose
-posts have broken images — which on `blob` is unrecoverable, because there
-is nowhere else the objects still exist.
-
-**And check the exit code.** An object whose key the board cannot use is
-skipped rather than allowed to stop the run, so `meith backup` can
-exit **2**: the bundle was written, it names the objects it is missing in
-its manifest, and on `blob` those objects are gone once the project is.
-Read the list before you delete anything —
-[When a bundle is incomplete](backups.md)
-explains what to do about it.
-
-This runs from anywhere; it does not have to run on Vercel. Put the
-project's variables in front of it and it talks to Neon and to the Blob
-store over the network:
-
-```sh
-DATABASE_URL=…            # the pooled string
-DIRECT_DATABASE_URL=…     # the direct string, for the dump
-FILESTORE_DRIVER=blob
-BLOB_READ_WRITE_TOKEN=…   # create one on the store — see below
-meith backup --uploads include
-```
-
-That token is the one value here you make by hand. On the deployment the
-board reaches the store with `BLOB_STORE_ID` and the deployment's OIDC
-identity, and a command on your own machine has no such identity — so open
-the store under **Storage**, create a read-write token, and use it for the
-backup. [How the Blob store authenticates](vercel-configuration.md)
-has the whole of it.
-
-Copy the bundle somewhere that is none of the four vendors — or set the
-`BACKUP_S3_*` variables in front of the command and it ships there itself,
-which is also what makes the bundle appear on the board's own
-**Admin → System → Backups** screen. That screen cannot *take* a backup on
-this route: a function has no `pg_dump` and no disk, and the screen says
-so. Scheduling one is the cron on your own machine that runs the command
-above; [Backups](backups.md) is the reference.
-
-### 2. Stand up the destination
-
-Follow [Deploying by hand](docker-compose.md) — a server, the compose file,
-a `.env` and a proxy — or [Coolify](coolify.md) if you would
-rather have the panel. Write the `.env`, and then **bring up Postgres
-alone**:
-
-```sh
-docker compose up -d postgres
-```
-
-**Stop there.** Do not run `docker compose up -d --build` yet, and do not
-open `/install`. The full `up` starts the `migrate` container, which
-applies the schema and exits 0 — and `meith restore` refuses a target
-that already holds tables, saying so rather than writing over them. A
-fresh Postgres container gives you the empty database a restore insists
-on. This is the same sequence, for the same reason, as
-[Disaster recovery § Restore the board](disaster-recovery.md);
-follow that page if you want the commands spelled out against a running
-stack.
-
-You are restoring a board, not installing one — though the installer can
-do it for you: bring the whole stack up instead, set the `BACKUP_S3_*`
-values so the fresh board can see the bucket the bundle shipped to, open
-`/install`, unlock it with `AUTH_SECRET`, and pick the bundle under **Or restore a backup**. That route
-is [Restoring from the installer](backups.md);
-the one below is the same restore from a shell.
-
-### 3. Restore into it
+From a board checkout with production service credentials and PostgreSQL client tools:
 
 ```sh
-RESTORE_DATABASE_URL=postgres://… meith restore <bundle.tar.gz>
+npm run meith -- backup --uploads include
 ```
 
-`meith restore` refuses to run without `RESTORE_DATABASE_URL` and
-writes only there, so a restore can never be aimed at a live board by
-accident. It puts the uploads back where the **destination's** own
-`FILESTORE_DRIVER` says they go, whatever they came from — the local volume
-on a Compose deployment, a bucket if you set `FILESTORE_DRIVER=s3` and the
-`S3_*` values, or `--uploads-dir` to write them to a directory you name.
-Objects taken out of a Blob store go into a bucket or onto a disk with no
-conversion step: the keys are the same on either side.
+Use `DIRECT_DATABASE_URL` for the dump. Explicit upload inclusion creates a self-contained bundle for local, S3 or Blob storage. An external Blob command needs a supported read-write token; it cannot use the deployment's OIDC identity.
 
-It applies any migrations the bundle predates on its way through, so there
-is no separate migration step to remember. Bring up the rest of the stack,
-then verify sign-in, recent threads, uploads, mail and scheduled tasks
-**before** you move DNS. [Disaster recovery](disaster-recovery.md) is the
-complete runbook and applies unchanged; leaving a platform is the same
-operation as recovering from one, minus the urgency.
+Check exit status and manifest. Exit 2 names missing objects; repair and repeat before retiring the source. Copy the bundle outside the source hosting account. Save the original `AUTH_SECRET` and remaining environment separately.
 
-### 4. Turn the tick back into a worker
+## Restore
 
-The destination has a `worker` container, so drop `vercel.json`'s cron
-entry and let it do what Vercel's scheduler was standing in for. It ticks
-every 60 seconds without being asked, which is the cadence the daily-tick
-caveat above was costing you.
+1. Recreate the same board version using [Compose](docker-compose.md) or [Coolify](coolify.md).
+2. For CLI restore, start PostgreSQL alone with `docker compose up -d postgres`. Do not run core migrations or installation first.
+3. Set `RESTORE_DATABASE_URL` to the empty target and configure destination uploads. Follow [Restore](backups.md#restore-into-a-separate-destination). Included files retain their keys when moved from Blob to local or S3 storage.
+4. Alternatively, start the full fresh deployment and use the installer's restore flow, which accepts an uninstalled schema.
+5. Verify sign-in, private forums, old/recent posts, uploads, sealed settings, mail and scheduled work privately.
 
-That container presents `TICK_SECRET`, not `CRON_SECRET` — so make sure
-`TICK_SECRET` is set in the destination's `.env`, carrying over the value
-you were already advised to set on Vercel. `CRON_SECRET` stops being needed
-the moment the cron job is gone.
+## Cut over
 
-That is the whole move: a dump, the objects, and a guide that was already
-written. **The board stays yours** — which is the only condition under
-which running it on somebody else's functions is a reasonable thing to do.
+Stop source writes for the final export and restore. Switch DNS/proxy routing after checks pass. Use the destination worker with `TICK_SECRET`; disable the old cron. Verify HTTPS and task progress externally.
 
-One caveat, stated plainly because it is the only part of this route that
-does not survive neglect: on `blob`, that bundle is the sole copy of the
-attachments. A bucket sits there whether or not you ever think about it
-again; a Blob store goes when the project goes. If you are on `blob`, take
-a backup on a schedule rather than on the day you leave — see
-[Disaster recovery](disaster-recovery.md)
-— or move to `s3` while the board is still up, which is the same backup and
-restore run against a destination that keeps the objects.
+Configure destination off-site backups and retain the source until recovery is proven. Deleting a source upload store before verification can permanently lose attachments. See [Disaster recovery](disaster-recovery.md).
diff --git a/docs/operations/local-board.md b/docs/operations/local-board.md
index f692a5a31..1d9352b03 100644
--- a/docs/operations/local-board.md
+++ b/docs/operations/local-board.md
@@ -1,29 +1,20 @@
-# Create a writable local board
+# Writable local board
 
-Turn a scaffolded preview into a board where you can register, post and use the admin panel. You need the board from the quickstart and access to an empty PostgreSQL database. This is a development setup; use a deployment guide for a public community.
+Requires a [scaffolded board](../start/quickstart.md) and an empty PostgreSQL database.
 
-## 1. Configure the database
+## Configure
 
-In your board directory, stop the development server and copy the supplied environment example:
+Stop the development server. In the board directory:
 
 ```sh
 cp .env.example .env.local
-```
-
-Set `DATABASE_URL` to your PostgreSQL connection string. Generate two different secrets:
-
-```sh
 openssl rand -hex 32
 openssl rand -hex 32
 ```
 
-Save them as `AUTH_SECRET` and `TICK_SECRET` in `.env.local`. Leave secrets out of git. With a database URL present, Meith selects the PostgreSQL data source.
-
-If the database provider supplies a transaction-pooler URL and a direct URL, use the pooler for `DATABASE_URL` and the direct one for `DIRECT_DATABASE_URL`. See [Database connections](database-operations.md).
+Set `DATABASE_URL` in `.env.local`. Save the two different generated values as `AUTH_SECRET` and `TICK_SECRET`. Keep this file out of git. If the runtime URL uses a transaction pooler, also set a direct `DIRECT_DATABASE_URL`.
 
-## 2. Apply migrations and start
-
-From the board directory:
+## Install
 
 ```sh
 npm run meith -- env:check
@@ -31,23 +22,17 @@ npm run meith -- migrate
 npm run dev
 ```
 
-Open <http://localhost:3000/install>. Unlock the installer with `AUTH_SECRET`, enter the board and administrator details, and finish installation. The installer closes after a successful installation.
-
-## 3. Check that changes persist
+Open <http://localhost:3000/install>, unlock with `AUTH_SECRET`, enter board and administrator details, then finish. The installer closes afterward.
 
-Sign in, create a thread, restart the development server and open the thread again. It should still be present. If the board still shows only sample content, run `env:check` and confirm that it loaded your board's environment file and selected `postgres`.
+Create a thread and restart the server to verify persistence. If sample content remains, use `env:check` to confirm the resolved data source is `postgres`.
 
-Use [Set up your community](../administration/first-steps.md) to configure registration, permissions and mail. The default log mail driver records messages locally; it does not deliver email.
+## Run background work
 
-## 4. Exercise background work
-
-In another terminal, from the same board directory, run:
+In another terminal in the board directory:
 
 ```sh
 npm run meith -- task:list
 npm run meith -- task:run
 ```
 
-A manual run is useful during development. A deployed community needs a continuously running worker or an external scheduler; follow [Scheduled tasks](scheduled-tasks.md).
-
-Do not delete or reset a database to fix an installer problem if it contains data you want to keep. Use [Backups](backups.md) before replacing a database.
+Production needs a continuing [scheduler](scheduled-tasks.md). The default log mail driver does not deliver mail; configure [email](mail.md) before requiring activation. Follow [Community setup](../administration/first-steps.md). Do not reset a database containing data you need.
diff --git a/docs/operations/mail.md b/docs/operations/mail.md
index ee484de30..16f881649 100644
--- a/docs/operations/mail.md
+++ b/docs/operations/mail.md
@@ -1,51 +1,40 @@
-# Configure and troubleshoot email
+# Email
 
-Configure outbound email before opening registration or relying on password resets. Use **Admin → Settings → Mail** or the deployment environment. Web and worker must use the same provider configuration.
+Configure **Admin → Settings → Mail** and test delivery before requiring email activation. Keep web and worker configuration consistent.
 
-## Choose a delivery method
-
-| Driver | Required configuration | Result |
-|---|---|---|
-| `log` | None | Writes messages to logs; delivers nothing |
-| `http` | Sender, HTTPS endpoint and bearer token | Posts JSON to a compatible mail API |
-| `smtp` | Sender and SMTP host | Sends through an SMTP relay |
-
-The HTTP request uses `from`, `to`, `subject`, `text`, `html` and `reply_to`. A provider with a different API needs an adapter; an arbitrary HTTPS mail endpoint is not sufficient.
-
-For Resend provisioned by the Vercel deployment, see [Vercel configuration](vercel-configuration.md). Check domain verification before testing delivery.
+| Driver | Requirements |
+|---|---|
+| `log` | None; logs messages without delivery |
+| `http` | Sender, HTTPS endpoint and bearer token |
+| `smtp` | Sender and SMTP host; provider transport/authentication settings |
 
-## Configure environment overrides
+HTTP delivery posts `from`, `to`, `subject`, `text`, `html` and `reply_to`. Other API shapes need an adapter.
 
-These values override the corresponding saved settings. Prefer the admin panel when the deployment does not need to own the value.
+## Environment overrides
 
-| Variable | Use |
+| Variable | Value |
 |---|---|
-| `MAIL_DRIVER` | `log`, `http` or `smtp` |
-| `MAIL_FROM` | Sender email address |
-| `MAIL_HTTP_ENDPOINT` | HTTPS API endpoint |
-| `MAIL_HTTP_TOKEN` | API bearer token |
-| `MAIL_SMTP_HOST` | SMTP server hostname |
-| `MAIL_SMTP_PORT` | Provider's port |
-| `MAIL_SMTP_SECURITY` | `tls`, `starttls` or `none`; match the provider's configuration |
-| `MAIL_SMTP_USERNAME`, `MAIL_SMTP_PASSWORD` | Supply both when the relay requires authentication |
-| `MAIL_ALLOW_PRIVATE_HOSTS` | Allow an intentionally private relay in production |
+| `MAIL_DRIVER` | `http` or `smtp` pins the deployment driver; `log`/unset allows saved settings |
+| `MAIL_FROM` | Sender address |
+| `MAIL_HTTP_ENDPOINT`, `MAIL_HTTP_TOKEN` | Matching provider endpoint and token |
+| `MAIL_SMTP_HOST`, `MAIL_SMTP_PORT` | Relay address and port |
+| `MAIL_SMTP_SECURITY` | `tls`, `starttls` or `none` |
+| `MAIL_SMTP_USERNAME`, `MAIL_SMTP_PASSWORD` | Both when authentication is required |
+| `MAIL_ALLOW_PRIVATE_HOSTS` | Allow a deliberately private production relay |
 
-Set the HTTP endpoint and token together. Do not send a token issued by one provider to another provider's endpoint. Keep credentials out of the repository.
+Verify the provider's sender/domain requirements. Keep secrets out of git and use the intended provider's token only with its endpoint.
 
-## Test delivery
+## Test
 
-1. Save the panel settings, or recreate web and worker after changing environment variables.
-2. Run `meith env:check` using the [command for your deployment](operator-cli.md).
-3. Send a test from the Mail settings screen.
-4. Check the recipient's mailbox, spam folder and provider delivery log.
-5. Trigger a queued board notification and verify that the [scheduler](scheduled-tasks.md) delivers it too.
+1. Save settings, or restart affected services after environment changes.
+2. Run `meith env:check` using your [CLI invocation](operator-cli.md).
+3. Select **Send a test message** and check the inbox, spam folder and provider log.
+4. Trigger a queued notification and verify [scheduler](scheduled-tasks.md) delivery.
 
-A successful connection is not proof of delivery. If a test succeeds but notifications wait, inspect worker or tick results and the queue. If the driver is `log`, no delivery is attempted.
+If direct tests work but notifications wait, inspect task results and the queue.
 
 ## Private relays and outbound requests
 
-Production mail connections reject private, loopback, link-local and reserved addresses by default. DNS results are checked and pinned for the connection. HTTP endpoints must use HTTPS without embedded credentials. Requests have a total deadline and a bounded response body; upstream error bodies are not exposed through the admin test result.
-
-Use `MAIL_ALLOW_PRIVATE_HOSTS=true` only when the relay deliberately lives on a private network. Development relaxes this guard. SMTP authentication, transport security and the provider's sender policy still apply.
+Production rejects private, loopback, link-local and reserved destinations unless explicitly allowed. DNS is checked and pinned; requests have deadlines and response limits. HTTP requires HTTPS without embedded credentials. Upstream error bodies are not shown by the admin test.
 
-Webhooks, web push and OpenID Connect have separate outbound controls: `WEBHOOK_ALLOW_PRIVATE_HOSTS`, `PUSH_ALLOW_PRIVATE_HOSTS` and `OIDC_ALLOW_PRIVATE_HOSTS`. Changing the mail flag does not change those services. See [Webhooks](../integrations/webhooks.md), [Browser notifications](web-push.md) and [Authentication](single-sign-on.md).
+Use `MAIL_ALLOW_PRIVATE_HOSTS=true` only for an intended private relay. Separate overrides control [webhooks](../integrations/webhooks.md), [push](web-push.md) and [OIDC](authentication-reference.md): `WEBHOOK_ALLOW_PRIVATE_HOSTS`, `PUSH_ALLOW_PRIVATE_HOSTS`, `OIDC_ALLOW_PRIVATE_HOSTS`.
diff --git a/docs/operations/migrating.md b/docs/operations/migrating.md
index b47b8b3b1..e130797c3 100644
--- a/docs/operations/migrating.md
+++ b/docs/operations/migrating.md
@@ -1,82 +1,61 @@
 # Import MyBB or phpBB
 
-Import one legacy forum into an installed Meith board. Rehearse against a copy first. The importer reads the source and records progress in the destination; it is not a continuous synchronization service.
+Import into an installed Meith board using read-only MySQL/MariaDB source access. Rehearse in an isolated destination first. The importer is resumable, not continuous synchronisation.
 
-## Prepare the source and destination
+## Prepare
 
-You need an installed Meith board with its groups/settings, read-only access to a MySQL or MariaDB source, and the source uploads on the machine running the command. A phpBB database on another engine is outside this import path.
+Keep source database and file backups. For MyBB, provide `uploads/`; for phpBB, provide the installation root containing `files/` and `images/avatars/`.
 
-For MyBB, provide the old `uploads/` directory. For phpBB, provide the installation root so `files/` and `images/avatars/` are available. Keep untouched backups of the source database and files.
+Use one source board per destination. Progress keys contain entity kind and old ID, not source identity; unrelated boards collide.
 
-Use one legacy board per destination. The resume map is keyed by entity kind and old ID, not by source-board identity; importing several unrelated boards into one destination creates collisions.
+## Run
 
-Read [MyBB differences](mybb-parity.md) or [phpBB differences](phpbb-parity.md), then review the coverage below.
-
-## Run a rehearsal
-
-From a generated board checkout configured for the disposable Meith destination, provide `IMPORT_SOURCE_PASSWORD` through a protected environment or secret store. Run one of these, replacing host, database and file paths:
+In a generated board checkout configured for the destination, supply `IMPORT_SOURCE_PASSWORD` through protected environment configuration:
 
 ```sh
 npm run meith -- import --source mybb --host db.old --user reader --database mybb --uploads-dir /path/to/old/uploads
 ```
 
+For phpBB:
+
 ```sh
 npm run meith -- import --source phpbb --host db.old --user reader --database phpbb --prefix phpbb_ --uploads-dir /path/to/old-board
 ```
 
-Use `npm run meith -- import --help` for optional port, TLS, charset, budget and page-size settings. In a container, explicitly pass the source credential into the container and mount the source files; a path or variable on the host is not automatically available inside it.
-
-The default row budget is 2,000 per invocation. Run the same command again to resume until the report says it is complete. An interrupted run resumes from recorded progress.
-
-Without `--uploads-dir`, attachment metadata can be imported while files remain failed and avatars are skipped. Repeat with the correct directory to copy the files; inspect the resulting report.
-
-## Verify and prepare cutover
-
-Check representative accounts, private forums, old/recent posts, polls, private messages, attachments and avatars. Review skipped rows and conversion losses.
+Use `import --help` for port, TLS, charset, budget and page size. Containers need the credential explicitly passed and source files mounted.
 
-Every imported account starts in the ordinary registered group, including former staff. Restore administrator access deliberately with `meith user:promote`, then rebuild groups, forum permissions and moderator appointments. Do this before opening the destination to members.
+The default budget is 2,000 rows per invocation. Repeat the same command until the report says complete. Without uploads, attachment files fail and avatars are skipped; rerun with the correct directory and inspect results.
 
-The resume cursor picks up later IDs; it does not reread already imported rows that were subsequently edited. For final cutover, stop writes on the source before the final import. Use an isolated rehearsal destination and a clean, controlled final import so earlier rehearsal data does not hide changed source rows.
+## Coverage
 
-## Finish the destination
-
-Run with the destination board environment:
+| Data | MyBB | phpBB |
+|---|---|---|
+| Accounts/passwords | Legacy passwords supported | bcrypt, phpass and phpBB2 MD5 supported |
+| Forums, threads, posts | Imported | Imported; BBCode UID and stored smiley/link markup cleaned |
+| Private messages | Participant copies; no drafts | Shared message plus recipient copies |
+| Attachments | Supported files | Post attachments only; no PM attachments |
+| Avatars | Uploaded/gallery; no remote URLs | Uploaded/gallery; no remote URLs |
+| Subscriptions | Thread and forum | Thread and forum |
+| Polls | Options/votes; multiple becomes unlimited, public flag retained | Options/votes, choice cap and vote-change flag |
+| Reputation | Imported and totals recomputed | No source equivalent |
+| Warnings | Expiry/revocation; points recomputed | Limited source details |
+| Bans | Member bans; expiry through scheduled task | User bans; no email/IP exclusions |
+| Contacts | Buddies/ignore | Friends/foes |
+| Legacy URLs | MyBB original and rewritten routes | Topic, forum and member routes |
+
+Group ACLs, custom profile values, custom markup definitions, thread ratings, moderator logs and IP history do not transfer. Rebuild permissions and fields; review [MyBB](mybb-parity.md) or [phpBB](phpbb-parity.md) differences. Recreate MyBB announcements. phpBB announcements become sticky threads.
+
+## Cut over
+
+1. Review skipped rows, converted text, messages, polls and files.
+2. Restore staff access deliberately with `meith user:promote`. Imported accounts start without source staff privileges; rebuild groups, permissions and appointments.
+3. Stop source writes before the final import. Resume only reads later IDs, not edits to already-imported rows; use a clean final destination rather than the rehearsal database.
+4. Reconcile and index:
 
 ```sh
 npm run meith -- task:run counters.reconcile
 npm run meith -- search:reindex
 ```
 
-Confirm scheduled work completes. Enable **Redirect old forum URLs** in Board settings only after a successful import. Check several old links and verify the destination permissions as guests and ordinary members.
-
-Take a new backup, then switch DNS/proxy routing and invite members. Keep the source read-only and recoverable until the new board is verified.
-
-## What comes across, and what does not
-
-| Entity | MyBB | phpBB |
-|---|---|---|
-| Members, with working legacy passwords | yes | yes (bcrypt, phpass and phpBB2 MD5 hashes) |
-| Forum tree | yes | yes |
-| Threads and posts | yes | yes (bbcode uid markers and stored smiley/link markup cleaned) |
-| Private messages | yes (each member's copy; drafts are not) | yes (one message with every recipient copy) |
-| Attachments | yes | yes (post attachments; PM attachments are not) |
-| Avatars | uploaded and gallery; remote URLs are not | uploaded and gallery; remote URLs are not |
-| Thread and forum subscriptions | yes | yes |
-| Polls, options and votes | yes, every vote in a multiple-choice poll included; `multiple` arrives as an unlimited choice count and `public` as a public voter list | yes, including `poll_max_options` as the choice count and `poll_vote_change` as re-voting |
-| Reputation, with recomputed totals | yes | phpBB has none |
-| Warnings, with recomputed points | yes, including expiry and revocation | minimal — phpBB stores no points, titles or expiry |
-| Bans | yes (member moved to the banned group; expired bans lift on the next `bans.expire` run) | user bans; e-mail and IP bans are not |
-| Buddy and ignore lists | yes | friends and foes |
-| Legacy URL redirects | `showthread.php`, `forumdisplay.php`, `member.php` and rewritten routes | `viewtopic.php`, `viewforum.php`, `memberlist.php` |
-
-**Not imported from either source, and what to do instead:**
-
-| Left behind | Do this after the import |
-|---|---|
-| Group permission matrices | Rebuild your usergroups and forum permissions in `/admin` — a deliberate gap, not an oversight: MyBB's and phpBB's permission columns do not line up cleanly with Meith's (see [Permissions and groups](mybb-permissions.md#permissions-and-groups) if you are coming from MyBB), so a mechanical translation would produce permissions nobody chose. |
-| Custom profile-field values | Recreate the fields with `meith profile-field:add` (they start editable by every group; narrow that in `/admin` if you want the old restrictions). The values members typed are not imported — the field has to exist on this board before anybody can be asked to fill it in again. |
-| Announcements | Re-post them — Meith's announcements are not threads (see [Announcements are not sticky threads](mybb-content.md#announcements-are-not-sticky-threads) for why), so there is no source row to map them from. |
-| Smilies and custom BBCode/MyCode | Nothing to restore — Meith renders Markdown, not BBCode, and there is no admin-defined replacement-pattern equivalent. See [The markup language is Markdown, not BBCode](mybb-content.md#the-markup-language-is-markdown-not-bbcode) for exactly what survives the conversion and what does not. |
-| Thread ratings | Not carried over; there is no equivalent to recreate them from. |
-| Moderator logs | Historical only — Meith's own moderator log (`admin_log`) starts recording from the moment moderation happens on this board. |
-| Per-member IP history | Neither `regip` nor `lastip` is imported; a migrated member's address history starts at their first sign-in here. |
+5. Test guest/member/private-forum access. Enable **Redirect old forum URLs** and test old links.
+6. Take a new backup, switch routing and retain the read-only source until verified.
diff --git a/docs/operations/monitoring.md b/docs/operations/monitoring.md
index bce9e654d..2a9e58d32 100644
--- a/docs/operations/monitoring.md
+++ b/docs/operations/monitoring.md
@@ -1,52 +1,33 @@
-# Monitor a running board
+# Monitoring
 
-Monitor the services and background work, not just whether the home page loads. Start with **Admin → System**, then add external readiness checks and metrics where needed.
+Check **Admin → System** for migrations, task failures, queue state and search progress.
 
-## Inspect system status
+## Health
 
-Check migration state, scheduled-task progress, failures, search-index progress and queue health. Investigate the named task before retrying it repeatedly. The panel's maintenance controls include recounting, reindexing, cleanup and pending plugin migrations.
-
-## Check liveness and readiness
-
-| Endpoint | What it tells you |
+| Endpoint | Check |
 |---|---|
-| `/api/health` | The web process can answer a request |
-| `/api/ready` | The database and scheduler meet the board's readiness requirements |
-
-A liveness success does not prove that mail, backups or queued jobs are progressing. An individual failed task can need attention even when the board remains ready. Inspect the response and system page as well as the HTTP status.
+| `/api/health` | Web process responds |
+| `/api/ready` | Database and scheduler readiness |
+| `/api/system/tick` | Task execution; HTTP 200 can still contain `ok: false` |
 
-For HTTP scheduling, follow [Scheduled tasks](scheduled-tasks.md). The tick can return HTTP 200 with `ok: false` when a task failed; monitoring only the status code misses that condition.
+Read response bodies and task results. A working home page does not prove background delivery or backups work.
 
-## Enable metrics
+## Metrics
 
-Set `METRICS_ENABLED=1` and a separately generated `METRICS_TOKEN`, then restart the affected services. Production refuses enabled metrics without the token.
+Set `METRICS_ENABLED=1` and a separate `METRICS_TOKEN`, then restart. Production requires the token. Scrape `/api/metrics` with `Authorization: Bearer <token>` or `X-Metrics-Token`; disabled or unauthorised requests return 404.
 
-Scrape `/api/metrics` using `Authorization: Bearer <token>` or `X-Metrics-Token`. A disabled endpoint or invalid credential returns 404. Keep the token in the scraper's secret configuration.
-
-| Metric | Use |
+| Metric | Meaning |
 |---|---|
-| `meith_task_runs_total` | Task successes and failures |
+| `meith_task_runs_total` | Task success/failure counts |
 | `meith_task_run_duration_seconds` | Task duration |
-| `meith_http_request_duration_seconds` | REST API request duration by route |
-| `meith_queue_jobs` | Queued and dead-letter jobs |
-| `meith_db_connections_active` | Database connection pressure |
-
-Counters and histograms are per process. Scrape each relevant instance and aggregate rather than treating one replica as the whole board.
-
-## Choose actionable alerts
-
-Alert on repeated readiness failures, a growing queue with no progress, repeated task errors, missing backups and significant duration changes. Check disk space, database capacity and certificate expiry through the infrastructure tools you use.
-
-Document who receives alerts and what they should inspect. A queue of permanent failures needs investigation; automatic repeated retries can make an upstream failure worse.
-
-## Add tracing when diagnosing latency
-
-Set `OTEL_ENABLED=1` and `OTEL_EXPORTER_OTLP_ENDPOINT` for your collector, then restart. The web server and worker export task and REST API request spans through OTLP/HTTP. Protect and retain telemetry according to your deployment's needs.
+| `meith_http_request_duration_seconds` | REST latency by route |
+| `meith_queue_jobs` | Queue and dead-letter depth |
+| `meith_db_connections_active` | Database connection use |
 
-Tracing explains production requests; the [performance reference](../reference/performance.md) describes repeatable benchmark measurements.
+Counters and histograms are per process. Scrape and aggregate relevant instances. Alert on stalled queues, repeated failures, missing backups, disk/database capacity and certificate expiry.
 
-## Inspect logs
+## Traces and logs
 
-In Compose, run `docker compose logs --since 1h web worker` from the deployment directory. The generated board's worker is an HTTP caller, so task execution logs are in web. Use the task name and request context to connect a symptom to its failure.
+Set `OTEL_ENABLED=1` and `OTEL_EXPORTER_OTLP_ENDPOINT` for OTLP/HTTP task and REST traces.
 
-Start with [Troubleshooting](troubleshooting.md) when the board is unhealthy.
+For Compose, run `docker compose logs --since 1h web worker`. Generated workers call HTTP; execution logs are in web. Use [Troubleshooting](troubleshooting.md) to diagnose failures and [Performance](../reference/performance.md) for benchmarks.
diff --git a/docs/operations/mybb-content.md b/docs/operations/mybb-content.md
index 21d7dd51d..6159ebc54 100644
--- a/docs/operations/mybb-content.md
+++ b/docs/operations/mybb-content.md
@@ -1,486 +1,43 @@
-# MyBB migration: posts and uploads
+# MyBB content conversion
 
-Check which formatting, editing, poll and upload behavior changes when importing from MyBB. Preserve an untouched export so you can inspect content conversion before cutover.
+Keep an untouched source export. Compare representative posts and files before cutover.
 
-## Posting and Markdown
+## Markdown conversion
 
-### The markup language is Markdown, not BBCode
+| Source tags | Result |
+|---|---|
+| `b`, `i`, `s`, `url`, `email`, `img`, `quote`, `code`, `php`, `list` | Markdown equivalents; quote attribution retained |
+| `u`, `color`, `size` | Text retained; styling removed |
+| `font`, `align`, `hr`, `video`, `table`, custom MyCode | Literal escaped tags and text |
 
-**MyBB:** posts are BBCode: `b i u s color size font align url email img
-quote code php list hr video`, plus smilies, admin-defined custom MyCode,
-and auto-linking of bare URLs.
+Tag names are case-insensitive. Markdown punctuation in original text is escaped. Code fences expand to contain embedded backticks. Malformed and unknown tags retain their text; unsafe destinations are refused by the renderer.
 
-**Meith:** posts are Markdown. A board that upgrades or imports has its
-content **converted once**: posts are rewritten in the background by the
-render backfill, and private messages, signatures, announcements and
-drafts are converted when they are next read. There is no BBCode renderer
-left in the tree, and no board runs two markup languages at once.
+Raw HTML is escaped. Single newlines become line breaks; indented code blocks are unsupported. Posts are converted by render backfill; messages, signatures, announcements and drafts convert when read. There is no runtime BBCode renderer.
 
-This is the largest single divergence in this document, so what survives
-is worth stating precisely:
+Use `:::spoiler` for native spoiler disclosures. Imported custom `[spoiler]` tags are not converted. Directives declare syntax; arbitrary admin-defined HTML replacement patterns are unsupported. See [Formatting](../members/formatting.md).
 
-- **Converted with no loss:** `b i s url email img quote code php list`
-  all have a Markdown spelling, and the converter produces it. A quote
-  keeps its attribution — `[quote='Bob']` becomes
-  `> **[Bob](../../../../../../member/by-name/Bob) wrote:**` above the quoted lines — and
-  `[code]` and `[php]` bodies are fenced with a rail long enough that
-  their own backticks cannot close it.
-- **Converted with the styling dropped, the words kept:** `u`, `color`
-  and `size` have no Markdown spelling. `[color=red]stop[/color]` becomes
-  `stop`. **This is a real, permanent loss of presentation on an imported
-  board** — the one place in the migration where something a member wrote
-  does not come back. Nothing they *said* is lost, only how it was
-  coloured.
-- **Left as the text it was:** `font`, `align`, `hr`, `video`, `[table]`,
-  and any custom MyCode the old board defined. An unrecognised tag is
-  escaped and shown as the characters its author typed, so an imported
-  post reads as slightly plainer prose rather than as a hole.
-- **Gained:** headings, tables, task lists, thematic rules, fenced code
-  with a language, and auto-linking — which MyBB had and this board's
-  earlier BBCode renderer refused. Markdown resolves the ambiguity that
-  made it refusable: a bare URL ends at whitespace and gives back the
-  trailing punctuation that belongs to the sentence.
+## Quotes and announcements
 
-**Meith does not accept raw HTML**, which CommonMark says should pass
-through. Accepting it would need a sanitiser, and a sanitiser is a
-blocklist; this renderer constructs its output instead, which is why it
-has never had one. `<script>` in a post is seven escaped characters and a
-word. Two smaller deviations from CommonMark: a single newline is a line
-break, and there are no indented code blocks.
+Quotes resolve source posts by ID with visibility checks, then include member attribution and a durable post link. With JavaScript, Quote fills the current composer and multiquote selections persist in `sessionStorage` across pages. Without it, Quote opens the reply page; multiquote is unavailable.
 
-**A directive is not MyBB's custom MyCode.** MyBB's takes a *replacement
-pattern* — a regular expression and the HTML to put in its place — so an
-administrator can produce any markup from a form. Meith's chooses a
-**name** and whether it is inline or block; members write `:::note` …
-`:::` or `:note[…]`, and the element is constructed by
-`@meith/markdown`. That is a real capability difference and a deliberate
-one: a field that chooses output markup is a second markup language
-administered through a web form, which is how boards with custom MyCode
-acquire a permanent XSS surface. Anything needing bespoke markup is a
-plugin, where the code is reviewed rather than typed into a text box.
+Announcements are separate dated notices, not replyable threads. Recreate MyBB announcements under [Communications](../administration/community-communications.md#announcements). Dates use UTC; forum notices inherit forum visibility, without separate per-group controls.
 
-**`spoiler` is not a directive an administrator defines — it is built
-into the renderer**, on every board, and reveals with a native
-`<details>`/`<summary>` element that needs no JavaScript. MyBB's
-`[spoiler]` MyCode (never core, always a plugin) still falls into "left
-as the text it was" on import, same as any other custom MyCode; a member
-who wants a hidden section after the move writes `:::spoiler` … `:::`.
+## Editing and polls
 
-**Cost.** An operator promising a like-for-like move should promise it
-about the *text*, not the colours. Members who knew BBCode have to learn
-a different syntax — the composer's toolbar, shortcuts and formatting
-help exist for exactly that week.
+- The opening post cannot be deleted separately. Use thread deletion with `canDeleteOwnThreads`, or ask a moderator.
+- Edit windows are numeric permissions: the most generous group value wins, with zero unlimited.
+- A poll cannot become public after voting begins; it can become private.
+- Maximum choices use 1, N or 0 for unlimited. MyBB multiple-choice imports as 0.
+- Poll editing follows opening-post editing permission. Options may be added; options with votes cannot be removed.
 
-### Quoting fills the box you are looking at
+## Files
 
-**MyBB:** quotes by navigating to the reply page, with multiquote for
-collecting several posts first.
+Attachments accept PNG, JPEG, PDF and ZIP. PNG/JPEG are decoded and re-encoded; pending images are unavailable until processing completes. Original metadata is removed. PDF/ZIP are opaque downloads. Animated GIF and arbitrary additional formats are unsupported.
 
-**Meith:** does both and, with JavaScript on, neither navigates: clicking
-**Quote** puts the quote into the quick reply already on the page, opens
-it, and puts the caret under the quote.
+Downloads pass through the board, checking forum, post and thread visibility, with attachment disposition, `nosniff` and sandboxing policy. Keep the underlying store private.
 
-**Multiquote is a selection you can see.** **Multi-quote** is a toggle: it
-reports whether this post is in the selection, and a second click takes it
-out again. Above the reply box a strip names the count — "3 posts selected
-to quote" — and carries the two things you can do with it: **Add to reply**,
-which fetches the quotes and drops them in the box in the order they were
-selected, and **Clear**, which throws the selection away. Every change is
-announced to a screen reader as it happens, so the count is conveyed the
-same way it is shown. The selection lives in `sessionStorage`, so it
-survives turning the page and collects posts from more than one page of a
-thread; arriving at the full reply page spends it, exactly as clicking
-**Quote** does. Spending it and clearing it are the only two things that
-empty it.
+Native composer forms submit files with the post; validation failure requires reselecting them. The JavaScript **Insert attachment** enhancement also inserts inline markers. Editing permits adding files and removing existing ones; removing a marker alone does not delete a file.
 
-The strip is a client island, so it appears only where scripting does. With
-scripting off the **Multi-quote** button is not rendered at all and the
-**Quote** link is the whole feature, as below.
+Avatars are uploaded, re-encoded and fitted within 200×200 without cropping. Remote avatars and Gravatar are unsupported. Moderators lock avatars with a reason, retaining the image and preventing replacement until unlocked.
 
-**The quote comes from the server, by post id** — not read out of the page
-and turned back into markup in the browser. The server fetches the post
-through the same visibility lookup the reply page uses, so a reader
-cannot quote something they were never shown, and a moderator cannot
-republish a deleted post by quoting it.
-
-**A quote names its source twice.** The attribution links the member, and
-carries a link back to the post it was taken from. Both are written into
-the Markdown rather than held as attributes, so they survive the reply
-being edited, and the link back uses the post's durable id-based form
-rather than its position in the thread, which moves.
-
-**Cost.** One request per quote, where a board doing it in the browser
-makes none. With scripting off, the Quote link is a link to the reply
-page, exactly as it always was.
-
----
-
-## Announcements
-
-### Announcements are not sticky threads
-
-**MyBB:** has announcements, and boards frequently use a pinned thread for
-the same job anyway.
-
-**Meith:** has announcements that are deliberately *not* threads: nobody
-can reply to one, it has a start and an end date, and it lives above the
-forums rather than in the listing.
-
-**Why.** A sticky thread is a conversation — it belongs to its author,
-members reply to it, and taking it down deletes what they said. That is
-what leaves a three-year-old rules post pinned at the top of a forum. An
-announcement expires on its own, and removing it removes nothing anybody
-wrote.
-
-Two smaller differences follow. There is no per-group visibility on an
-announcement: a forum's announcement is shown to whoever can see that
-forum, resolved through the same filter as everything else, and a
-board-wide one to everybody. And the dates are entered in **UTC**, because
-the control submits wall-clock text with no zone and the alternative is an
-announcement appearing at a different hour depending on the container's
-`TZ`.
-
----
-
-## Editing and deleting
-
-### Markup that does not close
-
-**MyBB:** its regex passes leave an unmatched `[b]` as literal text, and can
-emit unbalanced HTML for crossed tags.
-
-**Meith:** cannot emit unbalanced markup at all: the renderer builds a tree
-and writes elements out of it, so no opening tag reaches the page without
-its closing one. An unmatched `**` is two asterisks, an unterminated
-`` ` `` is a backtick, and an unclosed fence ends at the end of the post
-rather than swallowing the thread.
-
-**Why.** Unbalanced output from a post body is the shape that lets
-formatting escape a post and affect the rest of the page, so this one is
-not negotiable regardless of parity. The visible outcome for the common
-mistake is the same as MyBB's: you see what you typed.
-
-### Deleting the first post of a thread
-
-**MyBB:** lets a member with `candeleteposts` delete any of their own
-posts, including the opening one — leaving the remaining replies under a
-first post that no longer exists.
-
-**Meith:** refuses it, with a message pointing at thread deletion instead.
-
-**Why.** The opening post *is* the thread as far as every listing is
-concerned — it supplies the title, the author, and the counters. The two
-ways to allow the click both lose: deleting only the post leaves a thread
-with a title and nothing to read; quietly deleting the whole thread means
-"delete my post" removes other people's replies without saying so.
-Refusing and naming the alternative is the only option that does what it
-says.
-
-**Cost.** A member who wants their thread gone needs `canDeleteOwnThreads`
-granted, or a moderator. An imported MyBB thread whose first post was
-deleted arrives with that post soft-deleted rather than missing — the
-moderator view shows it, the member view skips it.
-
-### Editing a post after the window closes
-
-**MyBB:** hides the edit control once `edittimelimit` has passed and
-refuses the submission server-side.
-
-**Meith:** does the same, with one difference: the window is a **numeric
-permission**, so the usual combination applies — `0` means unlimited and
-beats every other value across a member's groups. A member in a 30-minute
-group and an unlimited group gets unlimited.
-
-**Why.** It is the same rule every other numeric on the board follows. An
-edit window is an *allowance*, so MAX is the right rule and no special
-case is needed — unlike the flood interval above, where minimum-wins
-genuinely is correct and the field was therefore modelled as a setting.
-
----
-
-## Polls
-
-### Making a poll's voters public after voting has started
-
-**MyBB:** stores `public` on the poll and an administrator may switch it on
-at any point, including on a poll that has been running for a month. Every
-vote already cast becomes attributable.
-
-**Meith:** carries the same flag, and the same import, but refuses to turn
-it on once the first vote is in. It may be switched **off** at any time,
-and a poll created with public votes says so above the options before
-anybody picks one.
-
-**Why.** A public voter list is a disclosure a member consents to when
-they vote, and consent given to a secret ballot cannot be reinterpreted
-afterwards. Making the flag one-way in the risky direction is the only
-version of the feature that does not turn a past vote into something the
-voter did not agree to.
-
-**Cost.** A board that meant to run a public poll and forgot to tick the
-box cannot fix it in place once voting starts. The poll has to be closed
-and re-run.
-
-### A multiple-choice poll carries a maximum, not a flag
-
-**MyBB:** models multiple choice as the boolean `multiple`: a member either
-picks one option or picks as many as they like.
-
-**Meith:** stores a number — 1 for a single choice, N for up to N, and 0
-for no limit — so "pick your top three" is expressible. A MyBB poll with
-`multiple` set imports as 0, which is exactly what it meant.
-
-**Why.** The two useful polls MyBB cannot express are both caps, and the
-boolean is the degenerate case of the number rather than a separate idea.
-phpBB already stores `poll_max_options`, so the number is also what the
-other importer needs.
-
-**Cost.** None on import in either direction.
-
-### Who may edit a poll, and what they may change
-
-**MyBB:** has a `canmanagepolls` moderator right and lets the poll's author
-edit it inside the forum's edit window.
-
-**Meith:** drops the separate right — it granted nothing, as
-[Upgrading](upgrading.md) records — and authorises a poll edit exactly
-as it authorises editing the thread's opening post: the author inside the
-forum's edit window, and anybody who may edit others' posts at any time.
-Options may be added while a poll is running, and an option that already
-has votes cannot be removed.
-
-**Why.** A poll is part of the post it was attached to, so a second
-permission for it is a second thing to get wrong. Refusing to remove a
-voted-for option keeps the running totals meaning what they said they
-meant; adding options is safe because it cannot change a vote already
-cast.
-
-**Cost.** A board that gave a moderator poll rights without post-editing
-rights has to grant the post-editing right instead.
-
----
-
-## Attachments and avatars
-
-### An attachment is re-encoded, and until it is, it does not exist
-
-**MyBB:** an upload is checked against allowed extensions and MIME
-types, stored, and served as uploaded.
-
-**Meith:** PNG and JPEG are decoded to raw pixels and written back out
-by an encoder; the stored object is the encoder's output. The uploaded
-bytes are held in a separate, unservable object until that succeeds, and
-then deleted. A row is `pending` until the re-encode finishes, and
-nothing serves a `pending` row.
-
-**Why.** Validation cannot make a file safe. A valid PNG with a ZIP
-appended after its `IEND` chunk passes every check anyone could make,
-because the file genuinely *is* a valid PNG; so does one with a payload
-in an EXIF block aimed at whichever decoder opens it next. None of that
-survives a decode and re-encode, because the output is written from
-pixels and has never seen the original bytes.
-
-**Cost.** An image is not visible for as long as the queue takes —
-usually seconds, up to a minute on a board whose tick is the only
-worker. EXIF is gone, including the orientation tag and colour profile —
-a real loss for photographers, and a real gain for everybody who did not
-mean to publish where they took the picture. Animated GIF is not
-accepted at all rather than silently flattened to one frame.
-
-### Four file types, not an operator-configurable list
-
-**MyBB:** an attachment-types screen; an operator adds any extension and
-MIME type they like.
-
-**Meith:** PNG, JPEG, PDF and ZIP, as a constant. The images are
-re-encoded; PDF and ZIP are served as opaque downloads and never
-rendered.
-
-**Why.** A format is on the list only if the board can make a claim
-about the bytes it serves — "this was re-encoded", or "this is an
-opaque download". A configurable list is a way to accept a format
-nothing can process. `text/plain` is the instructive omission: it has
-no signature, so "is this a text file" can only ever be a guess.
-
-**Cost.** No `.docx`, no `.mp3`, no `.7z`, and no way to add one without
-a release. The admin screen configures *limits*, not *formats*.
-
-### The download is served by the board, not the object store
-
-**MyBB:** `attachment.php` streams the file through PHP after a
-permission check.
-
-**Meith:** the same — a route handler that re-checks
-`attachment.download` in the attachment's forum, checks the post and
-thread are visible to this viewer, and sets
-`Content-Disposition: attachment` with `nosniff` and a sandboxing CSP.
-The stored object is always private, even in a public forum, and a
-signed object-store URL is deliberately not used.
-
-**Why.** A signed URL is a bearer token that outlives the permission
-that issued it — move a thread into a private forum and every URL handed
-out in the last hour still works — and it carries the bucket's headers
-rather than the board's, which is where the safety of serving
-member-supplied bytes actually lives.
-
-**Cost.** The bytes go through the app, so a large attachment costs the
-board bandwidth. Revisit if the `FileStore` port ever grows the ability
-to sign with response headers.
-
-### Files are submitted with the post, in one form
-
-**MyBB:** the composer uploads each attachment over its own request,
-keyed to a post id or a "posthash" for a post that does not exist yet,
-with abandoned ones swept later.
-
-**Meith:** the file input is part of the reply form and the files arrive
-with the message. There is no upload step and no draft token. Editing a
-post follows the same rule: the edit form carries its own attachments
-field for new files and a checkbox per existing one to remove it, still
-one plain submission, never a token. Adding a file this way checks the
-same `attachment.upload` permission and spends the same hourly upload
-allowance a new post's attachments field does; taking one of the post's
-own files back out is gated on the right to edit the post, nothing more.
-
-**Why.** It works with JavaScript off, which the posthash flow does not
-without a round trip that loses the typed message. It also removes a
-whole class of state — a draft attachment waiting for a post that may
-never come — and with it the sweep for abandoned drafts.
-
-**Cost.** A browser cannot repopulate a file input, so a submission that
-fails validation loses the chosen files even though the message
-survives. That is true of every no-JS upload; an incremental upload
-belongs in the editor islands, as an enhancement over this path rather
-than a replacement for it.
-
-### An avatar is re-encoded and locked, never linked and never deleted
-
-**MyBB:** three ways to have one — upload, a remote URL, or Gravatar. A
-moderator's remedy is to delete it.
-
-**Meith:** upload only, decoded and re-encoded like every other image on
-the board, fitted to 200×200, unservable until that succeeds. A
-moderator locks it rather than deleting it, with a required reason the
-member is shown.
-
-**Why no remote URL.** Rendered directly, it is a tracking beacon
-reporting every reader's IP to a third party on every page view. Fetched
-server-side to avoid that, it is SSRF: an attacker supplies a URL and
-the board makes the request from inside whatever network it runs in.
-The only safe version ends at fetch-validate-re-encode-store — which is
-what the upload path already is. Gravatar is the remote-URL problem
-with a better-known third party.
-
-**Why a lock and not a delete.** The signature argument, stronger:
-deleting destroys the evidence, and an appeal about an image has
-nothing at all unless the file survives. Locking stops it rendering,
-stops the member replacing it, keeps the object, and records a reason.
-
-**Cost.** A member who wants their avatar from elsewhere downloads it
-and uploads it, and nobody's Gravatar follows them here. The image
-loses its EXIF, which is the point.
-
-### An avatar keeps its aspect ratio; it is not cropped to a square
-
-**Meith:** scaled to fit 200×200, aspect preserved, no crop.
-
-**Why.** Cropping decides for somebody which part of their picture
-matters, and a board cannot know. A theme that wants circles can have
-them in CSS, which is reversible; a crop at upload time is not.
-
-**Cost.** A wide image renders wide, so a theme laying out a fixed
-square has to say `object-fit: cover` rather than assuming. The default
-theme does.
-
----
-
-## The BBCode conversion
-
-The conversion corpus is `packages/markdown/src/bbcode.test.ts`: each
-difference below is asserted there, so this document and the converter
-cannot silently disagree. (URL safety is asserted in the renderer's own
-security tests, which the converted output flows through.)
-
-**No MyBB source artefacts are copied**, and that is not only a
-licensing rule: MyBB's parser is a pile of regular expressions
-accumulated over fifteen years, and reproducing them would reproduce
-their bugs as though the bugs were the specification. The corpus is
-written from the *observable* side — the BBCode people actually type —
-and every case is a claim about what a reader sees after the
-conversion.
-
-### Where the conversion is exact
-
-Bold, italic, strikethrough, both link forms, images, quotes with their
-attribution, code and PHP blocks, both kinds of list, and
-case-insensitive tag names. Case-insensitivity matters more than it
-looks: boards are full of `[B]`, and a converter that matched only
-lower case would turn fifteen years of emphasis into literal text.
-
-### Difference: the text is escaped on the way through
-
-**MyBB:** a post is BBCode; `*`, `_`, `#` and `[` in it are
-punctuation.
-
-**Meith:** those are Markdown syntax, so the converter escapes them. A
-post that said `a * b` still says `a * b`; a post that said `# 1 fan`
-is not a heading; a variable called `snake_case` does not come out half
-italic.
-
-**Why.** Without it, every post containing an asterisk changes meaning
-on the day of the upgrade — silently, and in a way nobody could find
-afterwards.
-
-**Cost.** An author who opens an old post in the editor sees
-backslashes where one was genuinely needed. That is the visible half of
-a guarantee whose alternative is invisible.
-
-### Difference: URLs and CSS this renderer refuses
-
-**MyBB:** has historically rendered `[url=javascript:…]`,
-`[img]data:…[/img]` and `[color=red;background:…]` with varying degrees
-of filtering by version.
-
-**Meith:** refused by the renderer. The link keeps its text and loses
-its destination — no anchor, no image element, no attribute.
-
-**Why.** Each is an XSS in a forum post, and "MyBB renders it" is a
-description of MyBB's history rather than a requirement.
-
-**Cost.** An imported post containing one shows the URL as text instead
-of a link — visible rather than silent, and intended.
-
-### Difference: malformed input is handled consistently
-
-**MyBB:** leaves an unclosed tag as literal text in some contexts and
-swallows it in others, depending on which regular expression ran
-first.
-
-**Meith:** the input is parsed, so the answer is the same everywhere.
-An unclosed tag converts to the text it is; a crossed pair keeps its
-content; a stray closing tag does not eat the line.
-
-**Why.** Consistency is worth more than bug-compatibility, and the rule
-is chosen so nothing is silently dropped — a post whose second half
-vanished is worse than a post with a visible `[b]` in it.
-
-### Difference: an unknown tag becomes text
-
-**MyBB:** drops unknown tags in some paths.
-
-**Meith:** an unknown tag is escaped and shown, and its content is
-kept.
-
-**Why.** Dropping is the worse default: a custom MyCode the old board
-defined would silently erase whatever it wrapped, and nobody would know
-which posts were affected.
-
-### Gap: tags this conversion does not translate
-
-`[table]`, `[align]`, `[font]`, `[video]`, and any custom MyCode. Their
-content survives as text, which is legible; a tag that vanished would
-take its content with it. `[table]` is the one most likely to matter —
-Markdown has tables, and a converter for MyBB's table syntax is a
-plausible later addition.
-
----
+Converter cases are tested in `packages/markdown/src/bbcode.test.ts`. Import omissions are listed in [Import](migrating.md).
diff --git a/docs/operations/mybb-discovery.md b/docs/operations/mybb-discovery.md
index 3b7742c8b..14d02636f 100644
--- a/docs/operations/mybb-discovery.md
+++ b/docs/operations/mybb-discovery.md
@@ -1,463 +1,48 @@
-# MyBB migration: search and discovery
+# Discovery, feeds and search
 
-Review search, discovery, feed visibility and spam-control differences on a board imported from MyBB.
+## Spam controls
 
-## Spam
+Reconfigure challenges after import. Meith provides a hidden-field trap, minimum registration time, question challenges, first-post moderation and hourly limits. No hosted or image CAPTCHA ships by default. Flood intervals and hourly caps are separate; see [Antispam](../administration/antispam.md).
 
-### No hosted captcha, and limits beside the interval
+## Activity and presence
 
-**MyBB:** ships a built-in image captcha, supports reCAPTCHA and hCaptcha,
-and models flood control as a per-usergroup interval.
+| View | Behaviour |
+|---|---|
+| `/discover/new` | Threads active within 24 hours |
+| `/discover/today` | Threads active since midnight in the reader's timezone |
+| `/discover/participated` | Participated threads without that time window |
+| `/discover/unread` | Signed-in member's unread threads |
 
-**Meith:** ships a honeypot, a fill-time floor, admin-defined question
-challenges and first-post moderation, plus hourly limits on posting,
-searching, private messages, reports and uploads. There is no image
-captcha and no hosted provider.
+Listings contain one row per thread. `?goto=unread` resolves the first visible post after thread/forum read markers; fully read threads fall back to the last page. With no read history it can land on the first post. Rendering a page marks the visited extent read.
 
-**Why.** Three separate reasons:
+Invisible members are omitted from both lists and counts for ordinary readers. Staff with `modcp.access` can see them; the historical peak counts everyone. Online locations are filtered by the viewer's permissions; inaccessible locations show a generic label. Query strings and admin locations are not exposed.
 
-- *No image captcha.* Generating one means rendering text to an image
-  (a dependency), the accessible fallback is an audio challenge (another),
-  and both are defeated by commercial solvers for less than they cost to
-  run. A question a regular can answer and a script cannot is weaker
-  against a determined human and stronger per unit of effort.
-- *No hosted provider by default.* hCaptcha and reCAPTCHA work, and they
-  mean every visitor's browser contacting a third party before they can
-  register. That is a decision about a board's members rather than a
-  setting, so the `CaptchaProvider` seam is shipped and the service is
-  not.
-- *Limits beside the interval, not instead of it.* An interval does
-  nothing about a script that posts every 31 seconds all night, so the
-  board adds a *limit* — how many in an hour — counted in the database so
-  every instance shares one allowance. The two answer different questions
-  and both are configured.
+Board totals refresh every five minutes and show their timestamp. Before the first run they report that counting has not completed.
 
-**Cost.** An imported board's captcha configuration does not carry over;
-the challenge has to be set up again and the questions written. Its flood
-settings map onto the interval; the hourly limits start at zero.
+## Feeds
 
----
+Tokenless RSS/Atom feeds always use guest visibility, regardless of cookies.
 
-## Reading and discovery
+Members can create one private feed token at **User CP → Security** and append `?token=…` to a board, forum or thread feed. The token uses the member's current permissions and approved visible content. Treat the URL as a credential.
 
-### "New posts" lists threads, and its window is a day, not your last visit
+Any request carrying `token` returns `private, no-store`. Missing, invalid or revoked credentials fall back to the guest feed. Reissuing or changing the password revokes the old token; bans prevent member access. Discovery links remain tokenless.
 
-**MyBB:** `search.php?action=getnew` runs a search for posts since
-`lastvisit` and shows the threads those posts are in.
+## URLs and categories
 
-**Meith:** `/discover/new` lists threads whose last post landed in the
-last 24 hours; `/discover/today` uses midnight in the member's own
-timezone. Both are thread listings ordered by last post,
-permission-filtered in SQL and keyset-paged.
+Categories have pages at `/{id}-{slug}`. **Allow new threads** lets them contain threads; disabling it hides the listing without deleting threads or their URLs.
 
-**Why.** A genuine "since your last visit" needs the per-thread read
-state, and folding that into this query means a join per row or a second
-query per page — against a screen with a p95 latency budget the load
-harness enforces. MyBB pays that cost as a full search run per page
-view, which is why the screen is one of the heaviest on a large board
-and why several hosts disable it.
+Each thread/forum page has its own canonical URL. Durable post links use `?post=<id>`, which resolves to the correct page and `#post-<number>` anchor. The number may change after deletions; the ID does not.
 
-**Cost.** A member who has been away a week sees a day, not a week. The
-label says so, and `/discover/participated` and the subscription list
-have no window at all.
-
-### A busy thread is one row, not forty
-
-**MyBB:** the "new posts" screens are searches over *posts*, so a thread
-with forty new replies contributes forty hits — collapsed by the
-template, but counted, paged and ranked as forty.
-
-**Meith:** every discovery view returns one row per thread, and the
-limit is a limit on threads.
-
-**Why.** "What is new" is a question about conversations. Paging over
-posts means a page of twenty hits can be three threads, and one busy
-thread buries the rest of the board.
-
-**Cost.** The row says when the last post was and who wrote it, but not
-how many of the replies are new to this reader. `/discover/unread`
-answers the coarser question — has anything landed here since I last
-read it — for a signed-in member, but a row on any other view still
-cannot say how many.
-
-### Jumping to what is new costs nothing until it is clicked
-
-**MyBB:** `newreply.php?tid=` with `goto=newpost` scans the thread's
-posts for the first one past `lastvisit` on every request, whether or
-not the link is ever followed.
-
-**Meith:** an unread row's link carries `?goto=unread` in the `href`
-itself — a plain query string a no-JavaScript reader can follow like
-any other. The thread route resolves it only when that request
-arrives: it reads the member's per-thread and per-forum markers, finds
-the first visible post past them, and redirects to the page holding it
-with a `#post-N` anchor; a thread that turns out to be fully read
-falls back to its last page. Reading it up to where it renders is
-separate — the thread page marks the visited page read as it builds
-the response, the same one write the view counter already makes, so the
-read is committed by the time the page arrives. A thread rendered to the
-end fully covers its own unread state this way; the "Mark read" button
-still exists for a member who wants to leave a thread without reading
-it all.
-
-**Why.** The forum, discovery, and board-index listings already know
-whether a thread is unread — that is one lookup per row anyway, needed
-for the badge — but *where* the first unread post sits still costs a
-query building the listing does not otherwise pay. Deferring that
-question to the click means the listing pays a fixed cost and the
-resolver runs only when its answer is actually wanted.
-
-**Cost.** A member who has never read a thread and follows `?goto=unread`
-gets its very first post — correct by definition, but a large thread
-that is only unread through one recent reply feels like the jump
-undershot.
-
-### Invisible browsing hides you from the count as well as the list
-
-**MyBB:** `users.invisible` removes a member from the online list; the
-"N users online" figure still counts them.
-
-**Meith:** the same setting removes the member from the **count** too,
-for everybody who cannot see them. Staff — anybody with `modcp.access` —
-see them listed and marked.
-
-**Why.** A member removed from the list but left in the total can be
-found by subtraction: "eleven online, ten listed" names an invisible
-member as surely as printing their name. Hiding somebody halfway is
-worse than not offering the setting.
-
-**Cost.** The visible total differs between staff and everybody else,
-which looks like a bug until you know why. The "most ever online" record
-counts everybody, invisible included — it is a fact about the board's
-traffic, not about who anybody may see — so the record can exceed any
-total a member has been shown.
-
-### The online list names a location only when the reader may know it
-
-**MyBB:** the online list shows each user's location resolved without
-reference to the reader — private forums leak by title through this
-screen on stock MyBB.
-
-**Meith:** the location is resolved **in the query, against the reader's
-own permissions**. A forum they cannot see arrives at the page as null
-and renders "Somewhere on the board" — there is no title in the data for
-a theme, a feed or a debug dump to print. A thread needs its forum to be
-nameable *and* the thread to be in the reader's content scope, so a
-moderator reading a soft-deleted thread does not put its title on the
-front page.
-
-**Why.** The alternative is fetching titles and letting the page decide,
-which puts the decision in every theme anybody writes, and one of them
-will get it wrong.
-
-**Cost.** The online list cannot be cached across readers — it is one
-query per reader, which is why it is one query. The location is stored
-without a query string, so "reading page 4" is not distinguishable from
-"reading page 1", and a member browsing the admin panel shows as
-somewhere on the board rather than in the panel.
-
-### Board totals are a rollup with a timestamp, not a live count
-
-**MyBB:** `datacache` holds the board statistics, updated on the write
-path — every new post, thread and member updates the cached figures.
-
-**Meith:** a scheduled task recomputes them every five minutes, and the
-page says when it last ran. Before the first run the panel says "not
-counted yet" rather than showing zeroes.
-
-**Why.** The member count is a count of `users`, and the board index is
-the most-requested page there is. Updating on the write path makes
-every post pay for a number nobody reads on the posting screen — plus a
-cache that drifts with no way to notice. The thread and post totals are
-summed from the root forums, whose counters have already accumulated
-the tree; the member count is what sets the shape.
-
-**Cost.** The numbers on the index can be five minutes old. They say
-so — and a brand-new board says "not counted yet" until the first tick,
-which is a truer statement than three zeroes.
-
----
-
-## Feeds, URLs and the sitemap
-
-### A feed shows what a signed-out visitor sees, whoever fetches it
-
-**MyBB:** `syndication.php` resolves the requesting user from their
-cookie and filters the feed against their permissions — a signed-in
-member's feed carries their private forums.
-
-**Meith:** every feed under its shared address is built from the
-**guest** scope, regardless of who asks — unless the reader appends their
-own **feed token** (below), which is the one way to get a personalised
-feed, and never from the cookie.
-
-**Why.** A feed URL is handed to software, not read in the browser that
-holds the cookie. Aggregators, corporate proxies and CDNs cache one
-response per URL and serve it to everybody who asks next — so a
-personalised feed under a shared address is a private forum served to a
-stranger, in somebody else's cache. MyBB's version is only safe because
-most readers never send the cookie at all.
-
-**The feed token.** A member mints one from *User CP → Security*, shown
-once, in the shape `forum_feed_<lookup>_<secret>` — the same design as a
-personal access token: a public lookup segment for an O(1) row lookup,
-and a secret kept only as its SHA-256 hash, never stored raw. Appending
-it as `?token=…` to any feed address — `/feed.xml`, `/atom.xml`, a
-forum's `/{id}-{slug}/feed.xml`, a thread's feed — builds that feed
-through the **same Authorizer and visibility filter a page view uses** for
-that member. The token is a restriction on an actor, never a grant: the
-feed carries exactly the forums the member can already see and no more,
-approved-and-visible content only (a "your threads only" forum narrows to
-the member's own threads, just as on the board).
-
-**No oracle.** A missing, malformed, guessed or revoked token is not an
-error. It resolves to the guest scope and returns the ordinary guest
-feed, with the same status and body a signed-out reader gets — there is
-no response that tells "wrong token" apart from "no token", so the
-address is neither an account- nor a token-validity oracle. Any request
-carrying a `token` parameter — valid or not — is answered
-`Cache-Control: private, no-store`, so a shared proxy never keeps a
-personalised copy, and because the header keys on the *presence* of the
-parameter rather than on whether the token was good, it cannot itself
-leak validity. Tokenless feeds stay guest-scoped and publicly cacheable,
-exactly as before.
-
-**Revocation.** One token is live per member; minting again retires the
-old one immediately. Changing the password drops the token too — the same
-event that signs out other devices — and a ban neutralises it at
-resolution time: a banned actor's audience is empty, so the token shows
-nothing until the ban lifts, without a stored flag to keep in step. The
-raw token is never written into page markup except its one-time reveal;
-the autodiscovery links a page advertises stay tokenless, so a member
-opts in to their private URL by copying it, never by loading a page.
-
-### A category is a page, not only a heading
-
-**MyBB:** a category is a heading on the index and a
-`forumdisplay.php?fid=` page of its own.
-
-**Meith:** the same — `/{id}-{slug}` on a category renders its forums,
-using the index's own blocks so the two never drift apart. It exists
-because the breadcrumb on every thread and forum page names the
-category, and a named ancestor that 404s is a trail that stops halfway.
-
-**Cost.** One more page per category to keep working. It shares the
-index's view model, so the cost is a route rather than a feature.
-
-### A category can hold threads of its own, if an admin says so
-
-**MyBB:** a category holds forums and nothing else.
-
-**Meith:** **Allow new threads** on a category — off on every category
-until an admin turns it on — makes it take threads as well as forums.
-Its page then lists them the way a forum's does, and it becomes a
-destination a thread can be moved into.
-
-**Why.** The difference between a category and a forum was never about
-what a member wanted to do there; it was about where the software would
-let them post. A small board is one heading with a handful of threads
-under it, and asking it to invent a forum inside a category is the
-software's filing system leaking into somebody's front page.
-
-**Off by default is the whole feature:** a category that takes threads
-without being asked has quietly become a forum.
-
-**Cost.** Turning it back off stops new threads and returns the page to
-its forums. Threads already posted keep their addresses and stay in
-search, but the category no longer lists them until it is turned back
-on — or they are moved.
-
-### Every page of a thread is its own canonical URL
-
-**MyBB:** emits no canonical link, leaving duplicate URLs for one page
-for the crawler to work out.
-
-**Meith:** every thread and forum page carries `rel="canonical"` naming
-**the page being read**, with the permalink, cursor and reveal
-parameters dropped.
-
-**Why.** The tempting version points every page at page 1, and it is
-worse than none: it asks a crawler to drop every page but the first
-from its index, which is why so many forums are searchable only for
-their opening posts. What a canonical is actually for here is
-collapsing `?post=`, `?after=` and `?reveal=` — three ways to reach one
-document.
-
-**Cost.** A permalink to post 812 is canonicalised to the page
-containing it, so a search result lands on the page rather than the
-post. The anchor still works for anybody who follows the original
-link.
-
-### A post is anchored by its number, and reached by its id
-
-**MyBB:** links a post as `showthread.php?pid=1234#pid1234` and prints
-`#6` beside it. The two never agree, and the one a reader copies is the
-one they cannot read.
-
-**Meith:** there is one anchor, `#post-6` — the number the corner
-shows. Everything the board writes — notifications, search hits, feed
-entries, last-post links, a quote's link back — links `?post=1234`
-instead, and the thread page answers that by finding the post and
-redirecting to the page holding it, anchored at its number.
-
-**Why.** The two jobs conflict. "The sixth post in this thread" is what
-a person means, and it moves when an earlier post is deleted; "post
-1234" is what a stored link means, and it must not move at all.
-Splitting them across the query and the fragment lets each be what it
-is. It is also the only way the link *lands*: a fragment is never sent
-to the server, so `#post-812` can only work when the post happens to be
-on the page that loaded — resolving `?post=812` server-side finds the
-page as well as the anchor.
-
-**Cost.** One redirect per link followed. A board that served the
-anchor directly makes none — and lands the reader at the top of page
-one whenever the post was not on it.
-
-### The sitemap is an index of chunks, ordered by id
-
-**MyBB:** ships no sitemap; plugins that add one generally emit a
-single document.
-
-**Meith:** `/sitemap.xml` is always an index. Chunks are 5,000 URLs,
-keyset-paged on the thread id ascending.
-
-**Why.** One document does not survive the target data volume, and
-switching shapes later means every crawler that cached the old one has
-to rediscover the new — so it is an index from the first thread. The
-ordering is by id rather than activity because a crawler works through
-the chunks over hours or days, and a boundary that moved whenever
-somebody posted would make the crawl skip threads and revisit others.
-
-**Cost.** A chunk request pays one skip into the primary-key index to
-find its starting id, because the index names the chunks by number
-before any of them exists. It is paid by crawlers, not readers.
-
----
+`/sitemap.xml` is an index of 5,000-URL chunks ordered by thread ID. A moved thread retains its ID and has no redirect stub in its former forum.
 
 ## Search
 
-### The search form has an advanced half
-
-**MyBB:** two forms — a one-line box in the header, and a full page
-with forums, an author, a date bound, "titles only", a sort column and
-a direction.
-
-**Meith:** one form, with the second half behind a disclosure that
-opens itself whenever anything in it is set. It carries the same axes,
-named for what they do: a forum (with **include subforums**, so a
-category is one click rather than eight), one or more authors, a date
-window, titles-only, post-or-thread results, and the order.
-
-**Why.** The plain box is what almost every search is, and a form that
-opens on eight controls asks a reader to answer questions they do not
-have. The disclosure state is the app's decision rather than the
-browser's, because a search that *was* narrowed and comes back looking
-unnarrowed is a bug report waiting to happen.
-
-### Results are filtered where they are read, not by searching again
-
-**MyBB:** the results page is a listing; narrowing it means going back
-to the form and running another search — another entry against the
-flood interval.
-
-**Meith:** the results page carries the filters with it. The stored
-search holds the words and the options it ran with; the results URL
-carries a *refinement* on top — a forum, an author, a window, an
-order — and the page re-runs the stored search with both applied.
-Anything already applied is also a chip, with an href that removes only
-itself.
-
-**Why.** A stored search is a token and a set of words, and re-running
-it is what the page already does on every open to re-check the reader's
-access. A filter in the URL is therefore free of everything a new
-search costs: no row, no flood interval, no lost link — and "clear
-filters" is a link rather than a re-type.
-
-### A refinement narrows and never widens
-
-**Meith:** a refinement can only make the result set smaller. A search
-run against one forum cannot be refined into another; a titles-only
-search cannot be refined back into whole posts; a past-week search
-cannot become a past-year one. Where the two disagree, the narrower
-wins; clearing the refinement is what returns the search to what it
-was.
-
-**Why.** The results URL is a link people paste, and a link that
-quietly returns *more* than the search it came from is one that leaks.
-The rule is small enough to hold in the head: this page shows a subset
-of that search, always.
-
-### Counts and breakdowns are bounded by the same window
-
-**MyBB:** counts the whole match set.
-
-**Meith:** counts the first 20,000 matches and says so when it stops
-there. The same pass produces the per-forum and per-author breakdowns
-the filter panel shows, and those counts deliberately ignore the forum
-and author refinements already applied, so the numbers beside the other
-forums hold still as a reader moves between them.
-
-**Cost.** On a board where a term matches more than twenty thousand
-posts, the total reads "more than 20,000" where MyBB printed an exact
-number, and the per-forum counts beside it are floors.
-
-### Sorting offers three orders, not six columns
-
-**MyBB:** sorts by relevance, subject, date, thread, forum or username,
-either direction.
-
-**Meith:** best match, newest, oldest.
-
-**Why.** Paging here is keyset, not `OFFSET` — `(rank, id)` for
-relevance, `id` for the date orders — so a reader paging through
-results cannot have rows shuffle or repeat underneath them when
-somebody posts. A sort by username or subject has no such key, and the
-honest implementations are an `OFFSET` pager over an unbounded ranked
-set or an index per column — neither worth what it costs to answer a
-question the filters answer better: a reader sorting by username wants
-one member's posts, which is what **posted by** does.
-
-**Cost.** A member who sorted by subject, thread, forum or username has
-no equivalent order and reaches the same set through **in** and
-**posted by** instead.
-
-### One row per thread is a grouping, not a second query
-
-**MyBB:** "display results as threads" returns thread rows.
-
-**Meith:** the same, and the row shown for a thread is its *best* match
-under the current order — the highest-ranked post for relevance, the
-newest for newest. Grouping is bounded by the same window as ranking.
-
-### Relevance is ranked within a window
-
-**MyBB:** ranks every matching post, however many there are.
+The advanced form supports forums/subforums, authors, dates, titles-only and post/thread results. Sort by best match, newest or oldest.
 
-**Meith:** ranks the **20,000 most recent matches** when sorting by
-relevance. Sorting by newest or oldest reads the whole corpus, unless
-the search groups by thread or asks for a count, both of which are
-bounded the same way.
+Results retain filters as URL refinements of a stored search. Refinements can only narrow its original scope. Clearing a refinement restores the original search without creating another search or consuming its flood interval.
 
-**Why.** `order by ts_rank_cd(...)` cannot use an index: a relevance
-score depends on the query, so there is nothing to have indexed in
-advance, and Postgres has to score every matching row before it can
-name the top twenty. The load run measured the cost on a board of
-2.3 million posts: a term matching 96% of them took a p95 of
-**5.5 seconds** — the GIN index present and used throughout; the cost
-was the ranking, not the lookup. A term matching 1,171 posts, through
-the same code, took 35 ms. Bounding the ranked set brought the first
-case to 98 ms.
+Relevance ranks the 20,000 most recent matches. Counts and thread grouping use a bounded window; totals report when they exceed it. Forum/author breakdowns ignore current forum/author refinements so alternative counts remain stable. Newest/oldest post listings can traverse the full corpus; their counts and thread grouping remain bounded.
 
-**Who this affects: almost nobody.** For any term matching fewer than
-20,000 posts the window contains the entire match set, so the results
-are *identical*. The difference appears only for a term so common that
-"the single most relevant post" is not a meaningful thing to ask for —
-and there the answer becomes "the most relevant of the recent ones",
-which is what a member searching a ubiquitous word actually wants. The
-alternative was a five-second page.
+Thread results show the best matching post for the selected order. Subject, username, forum and thread sort columns are unsupported. Use filters instead.
 
-**What was not done.** A search extension (RUM, or an external engine)
-would rank the whole corpus quickly and properly. It is a runtime
-dependency and, on most managed Postgres, an extension the operator
-cannot install — so it stays out until somebody has a board that needs
-it.
+Configure language, minimum word length and limits under [Search settings](../administration/search.md).
diff --git a/docs/operations/mybb-members.md b/docs/operations/mybb-members.md
index da74cffed..59e282e85 100644
--- a/docs/operations/mybb-members.md
+++ b/docs/operations/mybb-members.md
@@ -1,667 +1,49 @@
-# MyBB migration: accounts and messages
+# Accounts and messages after import
 
-Review account, messaging, notification and reputation differences before inviting members to an imported board.
+## Notifications
 
-## Notifications and digests
+Notifications are stored on the board even when email is disabled. The header combines unread notifications, messages and relevant moderation work; without JavaScript it provides count links.
 
-### A notification centre exists at all
+Repeated events with the same dedupe key coalesce while unread; after reading, a new event creates a new row. Report outcomes notify the reporter without disclosing moderator notes.
 
-**MyBB:** has no notification centre. What a member is told arrives as
-e-mail, plus the "You have N new messages" line. When the e-mail is
-filtered or never read, nothing on the board records that the member was
-told.
+Instant subscription delivery runs on the next scheduled task. Daily/weekly cadence is per member and cadence. Auto-follow for started/replied threads is separately configurable, off by default, and never overwrites an existing mute. Composer choices provide a per-post override.
 
-**Meith:** every notification is written to a `notifications` row first
-and delivered by e-mail second. The board's record is the row; the
-e-mail is one transport for it, and the transport can be declined.
+Board activity digests are separate, opt-in weekly/monthly mail for absent members. Content follows recipient permissions. Announcement consent is not imported from MyBB's opt-out field.
 
-**Why.** A warning that changes what a member may do has to be
-discoverable from the board itself. Making the record the primary
-artefact also gives every notifier — subscriptions, private messages,
-reputation — one place to write to rather than an e-mail template each.
-
-**Cost.** One more table on the read path — an unread count in the user
-panel on every page for a signed-in member, which is why its index is
-partial over unread rows.
-
-### The header carries one menu, not two counts
-
-**MyBB:** the header shows separate figures — a private-message count and,
-with a plugin, whatever else wants a number — each a link to its own page.
-
-**Meith:** the header carries a single notifications control. It shows one
-badge, the member's total unread across notifications, private messages
-and — for a moderator — the moderation work waiting on them, and opens a
-menu with a tab for each: **Notifications**, **Messages**, and — for a
-member who may reach the moderation panel — a **Mod** tab of the approval
-queue and the open reports. Each tab lists only what is still outstanding —
-unread notifications, unread messages, the open moderation work — links
-every one through to the thing it is about, and (for notifications and
-messages) marks entries seen without leaving the page; reading one drops it
-from the list, and the tab also links to the full page behind it. With scripting off the control falls back to
-the same unread-count links the header carried before, so nothing the menu
-adds is load-bearing.
-
-**Why.** Two counts that each open a different page make a member choose
-before they have seen anything; one badge answers "is there anything for
-me" and one menu shows what, sorted by the kind of thing it is. The **Mod**
-tab carries a moderator's actual outstanding work — the same approval-queue
-and open-report figures the moderation panel shows — rather than the run of
-their own notifications, so it counts what needs a decision.
-
-**Cost.** To fill its tabs the menu reads the first page of the
-notifications list and of the inbox, on top of the two unread counts the
-header already had; for a moderator it also reads the first page of the
-approval queue and of the open reports, alongside the counts the moderation
-panel already computes — a few short reads added to a signed-in page, and
-only for a member who is signed in.
-
-### On-site delivery cannot be switched off; e-mail can
-
-**MyBB:** every notification channel is opt-out.
-
-**Meith:** the preferences screen configures **e-mail only**. Every kind
-is recorded in the notification centre regardless.
-
-**Why.** The centre is the board's evidence that somebody was told. A
-member who could erase the record could later say they were never
-warned, with the board's own data agreeing — which is worse for the
-member too, since a moderator reviewing an appeal has nothing to look
-at. Declining e-mail costs nobody anything, because the record survives.
-
-**Cost.** A member who does not want to see a notification cannot remove
-it, only mark it read.
-
-### The reporter is told when their report is closed
-
-**MyBB:** tells the reporter nothing.
-
-**Meith:** closing a report raises `report.actioned` for the reporter,
-naming the outcome (actioned, or closed without action) and the captured
-label of what they reported. The moderator's private note is never
-included — the port that carries the notification has no field that
-could hold one.
-
-**Why.** A report button that silently swallows reports trains members to
-stop using it, and "we looked and decided not to act" is a legitimate
-outcome to communicate. E-mail for this kind is **off** by default,
-because reporting is exactly the act a member repeats.
-
-### A repeated notification is one row with a count
-
-**MyBB:** does not have the problem, having no notification store.
-
-**Meith:** a raise may carry a dedupe key. While the notification it
-produced is unread, further raises with the same key increment a counter
-and update the captured facts instead of writing a new row — enforced by
-a partial unique index rather than a read-then-write. Once the row is
-read, the next raise starts a fresh one.
-
-**Why.** The first notification the board raises without a human behind
-it is `system.task_failed`, and a task failing on every tick would
-otherwise write 1,440 rows a day per administrator, with an e-mail behind
-each. The count is also the more useful number: "this has failed 40
-times" is the difference between a blip and an outage.
-
-**Cost.** The first occurrence's details are replaced by the latest —
-deliberate for an operational alert, and why warnings carry no dedupe
-key: two warnings are two things that happened, and collapsing them
-would hide the one that crossed a threshold.
-
-### "Instant" notification means "within a tick"
-
-**MyBB:** sends a subscription e-mail during the request that created the
-post.
-
-**Meith:** the post commits, and the `subscriptions.instant` task tells
-the subscribers on its next run — at most a minute later on a board whose
-tick runs every minute.
-
-**Why.** Notifying inline is an unbounded loop inside the board's hottest
-write: one iteration per subscriber, each needing a permission re-check,
-each potentially a mail send. On a thread with 500 followers that is a
-posting request that takes seconds and fails when the mail provider is
-down.
-
-**Cost.** A subscriber can open a thread and see a reply before the
-notification about it arrives. That is strictly better than the failure
-it avoids, and the delay is bounded by the tick interval.
-
-### A digest's clock is per member, not per board
-
-**MyBB:** has no digests — every subscription is instant e-mail or
-nothing.
-
-**Meith:** a subscription's cadence is `instant`, `daily`, `weekly` or
-`none`, and the daily/weekly clock is stored per member *and* per
-cadence.
-
-**Why.** A board-wide "send the digests now" schedule delivers
-everybody's digest at whatever moment the tick fired, and hands somebody
-who subscribed on Sunday a "weekly" digest on Monday. Per member, the
-interval means what it says; per cadence as well, because one member can
-follow one thread daily and another weekly, and one clock cannot serve
-both.
-
-### Auto-following starts off, and never overrides a mute
-
-**MyBB:** `subscribemethod` is one admin setting, applied to every
-member alike — everybody who posts is subscribed at the same method, or
-nobody is. A member who wants "tell me about the threads I start" but
-not "the ones I reply to" has no way to ask for it.
-
-**Meith:** two member preferences, "Follow threads I start" and "Follow
-threads I reply to" (`/usercp/options`), each an independent cadence —
-`instant`, `daily`, `weekly` or `none`, the same four values a
-subscription itself can hold. Posting or replying while a preference is
-on creates a subscription at that cadence, but only if the thread
-carries none already: the insert is `on conflict do nothing`, never an
-overwrite, so a thread a member has explicitly muted (`none`) stays
-muted through their own reply. The composer's existing "Notify me of
-replies" checkbox reflects the preference by default and remains the
-per-post override — untick it and that post follows nothing, whatever
-the preference says.
-
-**Why.** A single board-wide switch cannot express "my own threads but
-not my replies," and a naive auto-subscribe that overwrote an existing
-subscription would silently un-mute a thread the moment its owner
-happened to reply to it.
-
-**Cost.** New boards seed both preferences to off, and no existing
-member is opted in when the feature ships — consent is asked, never
-inferred from a column's default. A member who wants the classic
-"always follow what I post in" turns both on themselves, once.
-
-### A digest can also nudge a member who has stopped visiting
-
-**MyBB:** has no notion of a member who has drifted away, and nothing to
-send one.
-
-**Meith:** `board.digest` is a notification kind of its own, separate
-from the follow-driven digest above — **e-mail off by default**, in
-keeping with the board's opt-in stance on mass mail (below). A member who
-turns it on also picks a cadence, weekly or monthly, and is sent one only
-once they have gone quiet for a run of days a board setting decides *and*
-their own cadence has elapsed — a member who visits daily never receives
-one, however long the feature has been on. Its content is built
-per recipient: the busiest threads since that member's own last visit,
-filtered through the same permission check as everything else, for the
-same reason as
-[the online list](mybb-discovery.md#the-online-list-names-a-location-only-when-the-reader-may-know-it) —
-a re-engagement e-mail is exactly the kind of thing that must never leak
-a private forum's existence to somebody it was written to bring back.
-
-**Why.** A digest that fires for everyone on the same schedule tells an
-active member about a thread they already read, and a re-engagement
-e-mail that leaks what it is inviting somebody back to see is worse than
-sending none.
-
-**Cost.** Two members who go quiet on the same day can receive visibly
-different digests — one may list threads the other's does not, because
-the forums behind them differ. That is the intended behaviour, not a bug
-to reconcile.
-
-### The unsubscribe link acts on POST, not on GET
-
-**MyBB:** unsubscribe links are GETs — following the URL removes the
-subscription.
-
-**Meith:** the link opens a page that says what unsubscribing would do
-and offers one button. The button is the act.
-
-**Why.** Mail clients, corporate link scanners and preview fetchers
-request every URL in a message. A GET that unsubscribed would mean a
-member unsubscribed by their own spam filter, never knowing why the
-notifications stopped.
-
-**Cost.** One extra click for somebody who genuinely wants out. The page
-needs no login and no JavaScript.
-
-### Mass mail is opt-in, and carries an unsubscribe link
-
-**MyBB:** a new account has *Receive e-mails from board administrators*
-switched on. Mass mail goes to everybody who has not found the setting
-and turned it off, and the message itself carries no way out.
-
-**Meith:** no account is in the mass-mail audience until the member asks
-to be. The registration form offers an unticked box, the member's
-notification preferences hold the same switch, and the board stores the
-moment consent was given. Every message carries an unsubscribe link that
-needs no login, and a member who uses it drops out of every campaign
-that follows — including one already half sent, because each batch
-re-reads the audience.
-
-**Why.** Consent that is assumed at registration is not consent, and a
-bulk message with no way out is not one either. Both are conditions of
-the GDPR, and neither can be bolted on by an administrator remembering
-to be careful.
-
-**Cost.** An imported board arrives with a mass-mail audience of nought:
-MyBB's `allownotices` is an opt-out, so importing it as consent would be
-recording an answer nobody gave. Members opt in from the board, or by
-one deliberate backfill the operator can defend.
-
-### Unsubscribing from a digest does not delete subscriptions
-
-**Meith:** the digest's unsubscribe link switches subscription **e-mail**
-off. Every subscription stays, and new posts still appear in the
-notification centre.
-
-**Why.** A digest covers many subscriptions, so "unsubscribe" cannot
-mean one of them — and taking it to mean "all of them" would delete a
-member's follow list because they wanted fewer e-mails. The per-thread
-link in an "as it happens" notification *does* end that one
-subscription, because there the member knows exactly which thread they
-are silencing.
-
----
+Unsubscribe URLs open a confirmation page; POST applies the change. Digest unsubscribe disables the relevant email channel without deleting the follow list; a per-thread instant unsubscribe ends that subscription. See [Notifications](../members/notifications.md).
 
 ## Accounts and profiles
 
-### Timezones are IANA names, never offsets
-
-**MyBB:** stores a numeric offset (`timezone = -5`) plus a DST flag.
-
-**Meith:** stores an IANA zone name (`America/New_York`), validated
-against the runtime's tz database. Offsets are refused even though
-`Intl` would accept them.
-
-**Why.** An offset cannot express summer time, so it is wrong for half
-the year in every zone that observes it — and MyBB's answer, a DST flag
-somebody has to flip, is wrong every year for anybody who forgets. The
-tz database already knows when the clocks change.
-
-**Cost.** Imported offsets do not map cleanly — `-5` is
-`America/New_York` in winter and `America/Chicago`'s summer, and neither
-is certain. The importer has to pick a representative zone per offset and
-say so.
-
-### The default timezone is the reader's, not the board's
-
-**MyBB:** has one board timezone that every guest and every member who has
-not changed it reads the board in.
-
-**Meith:** has no board timezone. A reader's own zone is detected in the
-browser and reported to the server in a cookie, so a guest in Auckland
-and a guest in Chicago see the same thread at their own two clocks. A
-member may pin a zone, and a pinned zone wins on every device.
-
-**Why.** A board timezone is right for whoever set it up and wrong for
-everybody else — most of all the guest who cannot change it and the
-member who does not know the setting exists. "Posted today at 09:14" has
-to mean the reader's today, or it is worse than a bare date.
-
-**Cost.** A reader with JavaScript off reports nothing and gets UTC —
-the footer names the zone precisely because that case exists. And the
-first page a new reader opens reloads once, after the cookie is written.
-
-### A password change signs out every other device
-
-**MyBB:** changing a password keeps other sessions alive.
-
-**Meith:** every session is revoked, and the device that made the change
-is immediately given a fresh one.
-
-**Why.** Changing a password is what somebody does when they think an
-account is compromised; one that leaves the attacker's session alive has
-done nothing. Re-issuing for the current device is what stops the safe
-behaviour from also being the annoying one.
-
-### Changing an e-mail address requires confirming the new one
-
-**MyBB:** with "verify e-mail" off — the default on many boards — the
-address changes immediately.
-
-**Meith:** the new address is held in a single-use token and adopted only
-when the link sent to it is followed. The current password is required
-to ask.
-
-**Why.** Two failures, and the second is the serious one: a typo strands
-an account at an address nobody owns, and an unattended session becomes
-a full takeover — change the address, request a password reset, done.
-Confirming the new address closes both.
-
-**Cost.** A member whose new address bounces keeps the old one, which is
-the safe direction. A board with no mail configured cannot change
-addresses at all.
-
-### A custom profile field's visibility is per group
-
-**MyBB:** `profilefields` carries `viewableby`/`editableby` as
-comma-separated group-id lists plus a `hidden` flag, resolved by
-substring check.
-
-**Meith:** a row per (field, group) with nullable `can_view` /
-`can_edit`, resolved by the same rule as everything else on this board:
-NULL abstains, any explicit grant wins.
-
-**Why.** The same shape as `forum_permissions`, so "who can see this"
-has one mental model. A NULL that abstains is also what makes "staff may
-edit this" one row instead of a row per group — and a comma-separated
-list of ids cannot express "no opinion" at all.
-
-**Cost.** MyBB's *deny by omission* does not survive: a group absent
-from `viewableby` becomes a group with no opinion, which inherits. The
-importer must write explicit deny rows, or set the field default and
-grant the listed groups.
-
-### Registration asks only for fields the new member can edit
-
-**MyBB:** a field marked `required` is asked at registration regardless
-of whether the registering member's group can edit it afterwards.
+| Area | Meith behaviour |
+|---|---|
+| Timezone | IANA name; imported offsets map to representative zones and need review |
+| Automatic timezone | Browser detection; explicit member choice wins; no-JavaScript fallback is UTC |
+| Password change | Revokes other sessions and replaces the current one |
+| Email change | Requires current password and confirmation at the new address |
+| Reset/confirmation | Public response does not reveal account existence or delivery outcome |
+| Activation | `users.state` and `email_verified_at`, independent of group membership |
+| Username length | Unicode code points, consistently across installations |
 
-**Meith:** `requiredAtRegistration` is intersected with what the board's
-default member group may edit, so a field they could never change is not
-asked for either.
-
-**Why.** "What you are asked at registration" and "what you may change
-afterwards" disagreeing is a trap — somebody types an answer they can
-never correct.
-
-**Cost.** An operator who marks a field required but forgets to let the
-registered group edit it gets a field that is silently never asked. The
-CLI's `profile-field:add` starts every new field editable by every
-group, the state where this cannot bite.
-
-### An emptied field is deleted, not stored as an empty string
-
-**MyBB:** a column per field, with text columns defaulting to `''` — so
-"not answered" and "answered with nothing" are the same value.
-
-**Meith:** a row per (member, field), and clearing an answer deletes the
-row.
-
-**Why.** Every read would otherwise have to treat two states as one, and
-one of them eventually forgets — a profile showing an empty "Pronouns:"
-row is the visible half. It also makes an unanswered field cost nothing
-on a board with twelve fields and ten thousand members who filled in
-two.
-
-**Cost.** A column-per-field table is one join cheaper to read — and a
-schema migration every time an operator adds a field, which is the trade
-MyBB made and this does not.
-
-### The reset and confirmation forms never say whether an address exists
-
-**MyBB:** the lost-password form answers "the e-mail address you entered
-was not found" for an unknown address.
-
-**Meith:** one sentence on every path. An unknown address, an
-already-active account, a failed send and a link that really went out
-all produce the same notice — and the rate limit is spent *before* the
-account is looked up, so its refusal cannot be provoked for one address
-and not another.
-
-**Why.** A form that answers "is there an account for this address?"
-answers it for anybody, one submission at a time — including for a list
-of addresses somebody bought. On a board where membership itself is
-sensitive, that is the whole game.
-
-**Cost.** Somebody who mistypes their own address is told a link was
-sent, and no link arrives. The resend screen names the address it used,
-which is the one place the typo becomes visible.
-
-### An unconfirmed account is a state on the row, not a usergroup
-
-**MyBB:** an account waiting for activation is a member of the "Awaiting
-Activation" usergroup, so activating somebody means moving them between
-groups.
-
-**Meith:** `users.state` carries `awaiting_activation`, the group is the
-board's default, and confirming an address stamps
-`users.email_verified_at`. Under the `both` activation method the stamp
-is what says "the address is proven, an administrator has not looked
-yet".
-
-**Why.** A group is how permissions are decided; lifecycle is not a
-permission. Modelling it as one makes every permission question silently
-depend on account state, and means a ban — implemented by capturing and
-restoring the group — cannot be reasoned about independently. It also
-keeps the two facts separable: an account can be proven and unapproved,
-which `both` needs and a single group membership cannot express.
-
-**Cost.** An operator cannot grant unactivated accounts a different
-permission set by editing a group, because there is no group to edit.
-
-### A username's length is counted in code points
-
-**MyBB:** measures with `my_strlen`, which counts characters where
-mbstring is available and bytes where it is not — the same name can be
-two lengths on two installations.
-
-**Meith:** `registration.username_min` and `registration.username_max`
-are counted in Unicode code points, on every board.
-
-**Why.** The accepted alphabet admits letters outside the Basic
-Multilingual Plane, and JavaScript's `String.length` counts UTF-16 code
-units — every such letter occupies two, so measuring with it made "your
-alphabet decides what the number means" the actual rule.
-
-**Cost.** None; Postgres counts character limits the same way.
-
----
+Custom profile values do not import. Recreate fields and access rules. Per-group field values can grant, deny or abstain; any grant wins. Registration asks only required fields the default member group can edit. Clearing an answer deletes its value row. `profile-field:add` starts fields editable by all groups; restrict them as needed.
 
 ## Private messages
 
-### A private message is stored once, not once per recipient
-
-**MyBB:** `privatemessages` holds a row per copy — the sender's Sent
-Items and each recipient's Inbox carry the full subject and body.
-
-**Meith:** `private_messages` holds the content and
-`private_message_copies` holds one small row per participant.
-
-**Why.** A message to twenty people is otherwise twenty copies of the
-text, and re-rendering one is twenty writes. It also makes the quota
-count *copies* — the thing a member can actually delete.
-
-**Cost.** A join on every folder listing, which the indexes exist for.
-And a message everybody has deleted leaves an orphan content row rather
-than disappearing by cascade — deliberately, because deleting *your*
-copy must not reach into somebody else's mailbox. (Nothing prunes those
-orphans today.)
-
-### The quota is storage; the daily cap is separate
-
-**MyBB:** `pmquota` caps stored messages, with no separate send rate for
-most groups.
-
-**Meith:** two numbers. `maxPrivateMessagesPerDay` caps sends;
-`privateMessageQuota` caps what a member may keep. Both are
-0-means-unlimited numerics combined by MAX across groups.
-
-**Why.** They answer different abuse questions: a rate limit slows a
-spammer; a storage limit bounds what the board pays to keep. Collapsing
-them means a board that wants a hundred stored messages must also allow
-a hundred a day.
-
-**Cost.** One more column on `usergroups`, and two numbers to think
-about. The seeded ladder sets both, so an unconfigured board behaves
-sensibly.
-
-### A full inbox refuses the whole send, and names who is full
-
-**MyBB:** a send to a member over quota fails and reports it.
-
-**Meith:** the same, extended to multiple recipients — if any one of
-them is full, **nothing is sent to anybody**, and every full recipient
-is named.
-
-**Why.** Partial delivery leaves the sender with a Sent copy claiming a
-message went somewhere it did not. Naming the full recipient trades a
-small disclosure against the much worse failure of a sender who
-believes they were heard.
-
-**Cost.** One member with a full box blocks a message to nine others
-until the sender removes their name — the intended outcome, and the
-message says which name to remove.
-
-### Reporting is the only way staff read a private message
-
-**MyBB:** a reported PM is copied into the report, and administrators
-with database access can read any message.
+Content is stored once with participant copies. Storage quota counts copies; daily allowance counts sends. Both combine as most-generous numeric permissions, with zero unlimited.
 
-**Meith:** there is no listing, no search and no browse path into
-private messages at all. The report path takes an id and is reached
-only from an existing report row, so a moderator reads exactly what was
-reported and nothing beside it. A message can only be reported by
-somebody who holds a copy of it.
+If any recipient is full, the whole send fails and identifies full recipients. Recipient blocking uses the same refusal as other messaging restrictions and does not disclose ignore status.
 
-**Why.** A moderation tool that can enumerate private messages is a
-surveillance tool with a moderation feature attached.
+Reply addresses the author only; there is no reply-all. Deleting your copy does not delete another participant's. Unreferenced content rows are not automatically pruned.
 
-**Cost.** A moderator cannot see the rest of a conversation for
-context — only the message that was reported. Reporting each message is
-the way to give them more, which is also the way the member chooses what
-staff see.
+### Staff access
 
-### Reply addresses the author, not everybody on the message
+The application exposes no staff inbox browser or search. A participant's report permits review of that message only. Additional context requires reporting additional messages. Database access remains outside this application-level boundary.
 
-**MyBB:** reply addresses the sender; "reply to all" addresses everyone.
+## Contacts and signatures
 
-**Meith:** reply addresses the author, and there is no reply-all.
+Ignoring withholds post bodies server-side but preserves numbered placeholders with reveal links. Buddy/ignore relations are directional and mutually exclusive per ordered pair.
 
-**Why.** Bcc. A recipient who was bcc'd is hidden from the others, and a
-reply-all composed by one of them would either leak that name or
-silently drop somebody — and whichever it did, it would do it without
-the member noticing.
-
-**Cost.** Answering a group conversation means typing the other names,
-which the composer shows in the "To" line of the message being replied
-to.
-
----
-
-## Buddies, ignoring and signatures
-
-### Ignoring hides a post's body; it does not remove the post
-
-**MyBB:** an ignored member's posts are collapsed client-side, with the
-body still in the HTML.
-
-**Meith:** the body is withheld **server-side** — it is not in the
-response at all — and the post keeps its place in the page and its
-number in the thread. A placeholder and a per-post reveal link take its
-place.
-
-**Why.** Shipping the text and hiding it with CSS is a preference rather
-than a feature. And filtering the post *out* instead would give every
-viewer a different page size, make "#12" mean different posts to
-different people, and land permalinks on the wrong page.
-
-**Cost.** A thread with an ignored member still has their posts in it,
-as placeholders. That is the intended reading: a conversation with holes
-in it is still a conversation, and a reader who wants the missing half
-is one click away.
-
-### Buddy and ignore are one table, and ignoring is not mutual
-
-**MyBB:** `userlist` with a `type` column — the same shape, but the
-ignore is often read as symmetric by the code around it.
-
-**Meith:** one row per **ordered** pair, primary-keyed, so the two lists
-are mutually exclusive by construction. `(me, them)` is my opinion of
-them and says nothing about theirs of me.
-
-**Why.** A mutual ignore lets anybody silence themselves in somebody
-else's eyes by ignoring them first — a griefing tool rather than a
-preference.
-
-**Cost.** Two people who both want to stop reading each other need a row
-each. One extra click, and the correct model.
-
-### A blocked private message is refused, not silently discarded
-
-**MyBB:** a message to somebody who ignores you is accepted and dropped.
-
-**Meith:** the send is refused, with the **same wording** as a
-permission refusal — "X cannot receive private messages" — so it does
-not disclose the ignore.
-
-**Why.** Silently discarding it leaves the sender believing they were
-heard, the worst outcome for both people. Naming the ignore would make
-the send path a way to read somebody's list. The ambiguous refusal is
-the only option honest to the sender without betraying the recipient.
-
-**Cost.** A sender cannot tell "they blocked me" from "their group
-cannot use PMs" — deliberately, for the reason above.
-
-### A signature's forbidden constructs render as text
-
-**MyBB:** per-group switches for images, links and HTML in signatures,
-enforced by stripping or refusing the save.
-
-**Meith:** a signature is parsed with a **narrower set of constructs** —
-emphasis, strong, strikethrough, code spans and links. Images, headings,
-quotes, lists, tables, rules and code blocks are off, so they come out
-as the characters somebody typed.
-
-**Why.** It cannot be bypassed by a construct the build does not know
-about, and it degrades — somebody pasting a signature from another board
-gets most of it rather than an error. The image is the one that
-matters: a remote image under every post is a tracking beacon reporting
-each reader's IP to whoever hosts it.
-
-**Cost.** An imported signature that used images loses them, visibly, as
-bracketed text the member can delete. The importer should strip the tags
-rather than leave them, and say how many it touched.
-
-### A signature is locked, not deleted
-
-**MyBB:** `suspendsignature` with an expiry, plus moderators simply
-clearing the text.
-
-**Meith:** a boolean lock with a required reason. The text is kept,
-shown back to the member with the reason on their own signature screen,
-and cannot be edited while locked.
-
-**Why.** An emptied signature can be retyped the next minute and says
-nothing about why it went. Keeping the text is also what lets an appeal
-look at what was actually there.
-
-**Cost.** No expiry — an unlock is a second deliberate act. MyBB's timed
-suspension is the nicer behaviour and needs a scheduled task; it belongs
-with the maintenance sweeps rather than being faked with a column
-nothing sweeps.
-
----
+Signatures support emphasis, strong, strikethrough, inline code and links. Images and block constructs display as text. A staff lock retains the signature and reason, hides it publicly and prevents editing; unlocking is manual, without timed expiry. Avatars use the same lock approach.
 
 ## Reputation
 
-### Reputation has no per-group power multiplier
-
-**MyBB:** `reputationpower` makes a moderator's vote worth more than a
-member's.
-
-**Meith:** every rating is worth −1, 0 or +1. The per-group settings are
-*whether* you may rate and *how many a day*.
-
-**Why.** A multiplier cannot obey the rule for numeric permissions — MAX
-across groups with 0 meaning unlimited — because "unlimited power" is
-meaningless. It is the same shape as the flood-interval problem above,
-and gets the same answer: leave it out rather than invert the
-combination rule for one field.
-
-**Cost.** A board that wants staff endorsements to carry weight cannot
-express it. An imported `reputationpower` is dropped, and the importer
-should say so rather than silently scaling totals.
-
-### Reputation totals are recomputed, not incremented
-
-**MyBB:** `users.reputation` is adjusted as ratings are added and
-removed.
-
-**Meith:** the column is rebuilt with a `sum` over the live rows, inside
-the same transaction as whatever changed them — a rating, a withdrawal,
-or an account merge, which recounts every affected account.
-`warning_points` is rebuilt the same way.
-
-**Why.** An incremented total cannot survive a rating being revised or
-withdrawn, and when it drifts nobody notices until somebody counts by
-hand — the same decision this board made for the thread and forum
-counters.
-
-**Cost.** One extra aggregate per rating, bounded by the number of
-ratings one member has. A rating is a deliberate act, not a hot path.
-
----
+New ratings are −1, 0 or +1 without group power multipliers. Groups control eligibility and daily allowance. Reputation and warning totals are recomputed from current rows on relevant changes, including merges. Review imported ratings and [reputation settings](../administration/reputation.md).
diff --git a/docs/operations/mybb-parity.md b/docs/operations/mybb-parity.md
index 8f1ba770b..3424f2dfc 100644
--- a/docs/operations/mybb-parity.md
+++ b/docs/operations/mybb-parity.md
@@ -1,26 +1,14 @@
-# MyBB migration differences
+# MyBB migration checks
 
-Read these differences before importing a MyBB community. The importer transfers supported data; it does not reproduce every MyBB permission, display rule or extension.
+Use the [import procedure](migrating.md), then review these areas before cutover:
 
-## Review the migration impact
-
-| Area | What to review before cutover |
+| Area | Check |
 |---|---|
-| [Permissions and moderation](mybb-permissions.md) | Group combinations, forum access, moderator appointments, warnings and audit logs |
-| [Posts and uploads](mybb-content.md) | BBCode conversion, lost styling, poll rules, editing, avatars and attachment handling |
-| [Accounts and messages](mybb-members.md) | Account state, profiles, private-message storage, notifications, ignoring and reputation |
-| [Search and discovery](mybb-discovery.md) | Visibility, new-post listings, search behavior, feeds, URLs and spam controls |
-
-## Rehearse with representative content
-
-Import into an isolated destination. Check ordinary and staff accounts, private forums, a long thread, a poll, attachments, signatures and private messages. Compare converted content with the untouched source export.
-
-Pay particular attention to permission combinations: denying one group does not cancel a grant from another. Test as guests and ordinary members, not only as an administrator.
-
-Markdown replaces BBCode. Some styling is lost and unsupported tags may remain visible as text. Review the detailed [content conversion differences](mybb-content.md) before promising identical rendering.
-
-## Perform the move
+| [Permissions](mybb-permissions.md) | Rebuild groups, forum access, appointments and warning rules |
+| [Content](mybb-content.md) | Review Markdown conversion, polls and supported uploads |
+| [Accounts](mybb-members.md) | Check profiles, messages, subscriptions and identity settings |
+| [Discovery](mybb-discovery.md) | Test search, unread views, feeds and redirects |
 
-Follow [Import MyBB or phpBB](migrating.md) for credentials, row budgets, resumability, attachments and cutover. Keep the old board and its uploads available until you have verified the new one and its backups.
+Rehearse with ordinary and staff accounts, private forums, long threads, polls, attachments, signatures and messages. Compare against an untouched source copy.
 
-After import, use [Community administration](../administration/organiser-guide.md) for normal Meith operations. The comparisons are migration references, not the starting point for learning the product.
+Do not assume source permissions or presentation survive. Any group grant can override another group's denial. BBCode styling may be removed and unsupported tags may remain as text.
diff --git a/docs/operations/mybb-permissions.md b/docs/operations/mybb-permissions.md
index 7a3018880..04b6024b6 100644
--- a/docs/operations/mybb-permissions.md
+++ b/docs/operations/mybb-permissions.md
@@ -1,520 +1,48 @@
-# MyBB migration: permissions and moderation
-
-Compare MyBB permissions, moderation and staff access with Meith. Review the migration costs before assigning groups or opening the imported board.
+# Permissions and moderation after import
 
 ## Permissions and groups
 
-### Flood intervals
-
-**MyBB:** stores `floodtime` and `searchfloodtime` as per-usergroup numeric
-columns, combined like any other numeric limit.
-
-**Meith:** does not model flood intervals as permission fields at all. The
-board settings `posting.flood_seconds` and `search.flood_seconds` hold the
-intervals, and the boolean permission `canBypassFloodCheck` exempts a group
-from them.
-
-**Why.** This board has one combination rule for all numeric permissions:
-take the maximum, with `0` meaning unlimited. That rule is correct for
-*allowances* — attachment size, posts per day — because a larger number is
-more permissive. It is exactly backwards for an *interval*, where the most
-permissive value is the smallest non-zero one: a member in a 30-second
-group and a 5-second group should get 5 seconds, and MAX would give them
-30. Keeping the field would have required a fourth combination kind used by
-two fields and a permanent footnote on the matrix. A setting plus a boolean
-(which combines by OR, giving the right answer) keeps the rule literally
-true for every field.
-
-**Cost.** An imported board loses per-group flood granularity: everyone is
-either subject to the board interval or exempt from it. Reintroducing
-granularity would mean adding a `numeric-min` kind to
-`packages/core/src/permissions.ts`.
-
-### Permission field naming
-
-**MyBB:** uses lowercase, unpunctuated column names (`canpostthreads`,
-`canviewthreads`).
-
-**Meith:** uses camelCase keys (`canPostThreads`) mapped to snake_case
-columns (`can_post_threads`).
-
-**Why.** The keys are consumed as TypeScript property names across three
-packages, and `canviewothersthreads` is genuinely ambiguous to read. The
-mapping is mechanical and lives in one file
-(`packages/db/src/schema/permission-columns.ts`), so importer code can
-translate a legacy column name in one place.
-
-### Separate `canAccessAdminCp` and `isAdministrator`
-
-**MyBB:** treats admin status and admin CP access as effectively the same
-thing.
-
-**Meith:** keeps them as two fields: `isAdministrator` grants the permission
-bypass, `canAccessAdminCp` grants the panel.
-
-**Why.** A bypass has to be explicit and logged. Splitting the fields makes
-it possible to grant a trusted role read access to the panel without also
-handing it the ability to bypass every forum permission — and it makes the
-audit log meaningful, because a bypass entry now implies a specific field.
-
----
-
-## Moderation
-
-### Who handles a report
-
-**MyBB:** has a dedicated permission, `canmanagereportedcontent`, separate
-from the moderator rights that decide what somebody can actually *do*
-about a report.
-
-**Meith:** scopes reports by the sets that already exist: a report about a
-post or thread is visible to the moderators of its forum (the same set
-that scopes the approval queue), and a report about a member — or a
-private message — is visible to board staff (`modcp.access`).
-
-**Why.** A third permission would let a board grant "can read reports
-about forum X" to somebody with no power to act on anything in forum X —
-a role whose only capability is reading complaints about their
-neighbours. Every report is about content or a person, and the people who
-can act are the people who should see it.
-
-**Cost.** An imported board's `canmanagereportedcontent` grants do not map
-one-to-one: anybody who held it without moderating a forum loses report
-access, and anybody who moderates a forum gains it.
-
-### What can be reported
-
-**MyBB:** allows reports against posts, threads, profiles, private
-messages and (with plugins) more.
-
-**Meith:** ships posts, threads, members and private messages. A private
-message can only be reported by somebody who holds a copy of it, and
-reporting is the *only* path by which staff can read one — see
-[private messages](mybb-members.md#reporting-is-the-only-way-staff-read-a-private-message).
-
-### Who can lock, pin and move threads
-
-**MyBB:** grants these through `moderators` rows (per forum, per right)
-plus the super-moderator and administrator bypasses. There is no
-usergroup column for them.
-
-**Meith:** does the same — and this is a parity entry only because it is
-the first place the permission model diverges from its own pattern: every
-other action reads a field off the resolved forum matrix, and the five
-thread-management rights (lock, stick, move, merge, split) read an
-appointment instead.
-
-**Why.** "May lock threads everywhere on the board" is a thing you are
-appointed to, or bypass into as staff. A usergroup checkbox for it would
-let a board grant board-wide thread control by adding somebody to a
-group, with no record of which forums anybody was ever meant to be
-responsible for.
-
-**Cost.** A board that wants a "junior moderators" group with lock rights
-everywhere has to appoint the group to each forum — `forum_moderators`
-accepts a `group_id`, so that is one row per forum rather than one per
-person, but it is not one checkbox.
-
-### Copying a thread
-
-**MyBB:** offers "copy thread" alongside move, duplicating every post and
-crediting the copies to their original authors — so one piece of writing
-raises its author's post count twice.
-
-**Meith:** offers it too, on the same thread tools as move, and makes the
-same choice about the counts — see
-[copying credits its authors twice](#copying-a-thread-credits-its-authors-twice)
-and
-[copy is authorised by `thread.move`, at both ends](#copy-is-authorised-by-threadmove-at-both-ends).
-Only visible posts are copied: copying held content would double the
-approval queue, and copying removed content would republish it.
-
-### Splitting a thread, and where the pieces land
-
-**MyBB:** splits by checkbox selection and lets the moderator choose a
-destination forum.
-
-**Meith:** offers two selections — "from this post onwards" on the thread
-tools, and a per-post checkbox selection through inline moderation — and
-the new thread always lands in the **same forum**.
-
-**Why the fixed destination.** Splitting and moving are two acts: a
-single operation with a second forum to authorise would let a moderator
-who may split here, but not post there, place content in a forum they
-have no standing in.
-
-**Cost.** A moderator who wants the split-off thread elsewhere splits,
-then moves — two operations and two audit rows instead of one.
-
-### Which thread survives a merge
-
-**MyBB:** merges by thread URL or id and keeps the thread the moderator is
-looking at, absorbing the one they name.
-
-**Meith:** goes the other way round, and the direction is the important
-sentence on this page: **the thread on screen is the one that is merged
-away.** Its posts move into the thread whose number the moderator types,
-and the thread they were looking at is the row that is deleted. The tools
-say so — the field reads "Merge into thread #" and the button reads
-"Merge away" — and the survivor is never inferred from anything else: not
-the older thread, not the one with more posts.
-
-**Why.** A merge destroys a thread row. Every heuristic for picking the
-survivor is right most of the time, and the times it is wrong are
-unrecoverable. Being explicit costs a moderator nothing, because they
-already know which one they mean.
-
-**What goes with the deleted thread.** Only its posts are carried across.
-Everything else hanging off the source row goes with it, by cascade and
-without a prompt: its **poll** and every vote in it, its **ratings**,
-every **subscription** to it, and every member's **read marker**. That is
-the part a moderator cannot undo, and the strongest reason to check the
-direction before pressing the button — merging a long-running poll thread
-into a two-post duplicate destroys the poll.
-
-**Cost.** Merging the wrong way round is still possible — it is a
-moderator's mistake to make, and it is logged with both thread ids and
-both forum ids so it can be seen. What is not possible is the software
-making the mistake for them.
-
-### What a merge does to post counts
-
-**MyBB:** moves the posts and leaves author post counts alone — correct,
-and worth stating because its neighbouring operation (copy) counts one
-piece of writing twice.
-
-**Meith:** matches MyBB on merge and split, for a reason it can state
-exactly: neither operation creates or destroys a post, so
-`users.post_count` never moves. Only `users.thread_count` moves, by one —
-a split creates a thread, a merge destroys one.
-
-### Copying a thread credits its authors twice
-
-**MyBB:** copying a thread duplicates its posts, and each copy counts
-toward its author's post count.
-
-**Meith:** the same, chosen deliberately.
-
-**Why.** Every other counter on this board holds to one definition —
-`users.post_count` means *posts written* — and merge and split were
-settled by that definition. Copy is the one tool that genuinely creates
-rows, so the definition and parity actually conflict, and parity won: an
-imported board's counts must not change under it, and a moderator using
-copy expects the arithmetic they know.
-
-**Cost.** After a copy, `post_count` means "posts attributed to you"
-rather than "posts you wrote". The counter recount counts rows, so it
-agrees rather than quietly undoing it — the board stays internally
-consistent.
-
-### Copy is authorised by `thread.move`, at both ends
-
-**MyBB:** copy is governed by the same "can manage threads" permission as
-move.
-
-**Meith:** `thread.copy` does not exist as a right. Copying reads
-`thread.move` in the source forum *and* in the destination, exactly as a
-move does.
-
-**Why.** Copying is moving that leaves the original behind: it puts
-content into the destination by the same mechanism, so the destination's
-moderators have precisely the same interest. A separate right would be a
-column on `forum_moderators` distinguishing two acts nobody grants
-separately. Unlike a move, the destination *may* be the source forum —
-forking a discussion in place is legitimate, and there is no pointer to
-repair because nothing left.
+Rebuild source permissions before opening the board. Meith resolves the nearest forum override per group, then combines groups: any grant wins, numeric allowances use the maximum with zero unlimited, and approval requires every group to require it.
 
-### Inline moderation offers no "unapprove"
+Flood intervals are board settings (`posting.flood_seconds`, `search.flood_seconds`), with `canBypassFloodCheck` as an exemption. There are no per-group intervals.
 
-**MyBB:** the inline dropdown on a forum listing includes *Unapprove
-threads*, which sends published content back to the queue.
+`canAccessAdminCp` grants panel access; `isAdministrator` grants the permission bypass. They are separate. TypeScript permission names are camelCase; schema columns are snake_case.
 
-**Meith:** it does not. Inline moderation offers approve, delete,
-restore, lock, unlock, pin, unpin and move; taking a visible thread off
-the board is `delete`, which `restore` reverses.
+## Reports and thread tools
 
-**Why.** `unapproved` and `deleted` are both "not counted, not visible" —
-they differ only in which list the content lands on. Sending a published
-thread back to the *approval queue* puts it in front of a moderator as
-something to decide, when the decision has already been made — and it
-makes the queue a mixture of "new content nobody has read" and "old
-content somebody removed", which its oldest-first ordering relies on not
-being true.
+Post/thread reports follow forum moderator scope. Member and private-message reports require board staff access. Only message participants can report a message; staff review only the reported item.
 
-**The one exception: community flagging.** When enough distinct members
-report the same visible post, the board holds it — an established post,
-already read, sent to the approval queue (see the
-[anti-spam guide](../administration/antispam.md)).
-This is a deliberate crack in the rule above, and it is the only one. It
-is justified precisely where a *moderator's* unapprove is not: the
-decision has **not** already been made — a crowd has raised a question
-about the post and nobody on staff has ruled on it yet — so putting it in
-front of a moderator to decide is exactly right, not redundant. A
-flag-held post is genuinely "content that needs a decision", which is
-what the queue is for; there is no second surface to invent for it, and
-holding it (rather than deleting it outright) keeps the members'
-accusation reversible by a single approve. The queue's oldest-first
-ordering still holds — a flag-held item enters at the moment it is held,
-like any other. What a moderator still cannot do is unapprove at will;
-only the community-flag threshold can move read content into the queue,
-and only by agreement of several members.
+Lock, pin, move, merge and split rights come from forum appointments or staff bypasses. Appoint a group to each required forum for group-wide moderation.
 
-### Bulk moderation chunks rather than refusing
+| Operation | Behaviour |
+|---|---|
+| Split | Selected posts form a thread in the same forum; move it separately if needed |
+| Merge | The displayed thread is removed; its posts enter the specified target |
+| Copy | Copies visible posts and increments attributed-author counts; requires `thread.move` at source and destination |
+| Move | Retains thread ID; creates no source redirect stub |
+| Delete/restore | Separate grants |
 
-**MyBB:** inline moderation acts on whatever was selected, in one
-request.
+> [!CAUTION]
+> Merging transfers posts only. The source thread's poll and votes, ratings, subscriptions and read markers are deleted. Check **Merge into thread #** before confirming.
 
-**Meith:** a selection is applied in transactions of 25, up to a ceiling
-of 500 per request. The approval queue keeps its hard refusal above 200.
+Merge/split do not change author post counts; they change thread counts. Copy creates new counted rows and may target the same forum.
 
-**Why.** The two surfaces have different shapes. Nobody hand-selects two
-hundred items from a queue, so refusing there is honest. A listing has a
-"select all", and a moderator clearing a spam run genuinely has hundreds.
-Chunking is safe because every transition is state-guarded — a bulk
-action that dies halfway is fixed by pressing the button again, and the
-chunks that already ran report "already in that state".
-
-### A moved thread leaves no redirect stub
-
-**MyBB:** moving a thread can leave a "Moved: <title>" row in the source
-forum, optionally expiring.
-
-**Meith:** a move just moves. The schema keeps `moved_to_thread_id` and
-`ThreadRowModel.isMoved` for a future implementation, and nothing writes
-them.
-
-**Why.** The stub is a second kind of row in every listing query — the
-board's most performance-sensitive read — that has to be filtered,
-counted and expired everywhere. What it buys is a reader who bookmarked a
-thread finding it, and search and the thread's own permalink already do
-that, because the thread keeps its id. Revisit if a real board reports
-people losing threads after moves.
-
----
+Inline moderation accepts up to 500 items in transactions of 25. Approval queues refuse more than 200. State guards permit retry after partial completion. Inline tools do not offer unapprove; community flag thresholds can still hold published posts for review.
 
 ## Warnings
 
-### Warning levels are points, not percentages
-
-**MyBB:** warning levels are a percentage of a configured maximum, and a
-member's level reads as "40%".
-
-**Meith:** levels and warnings are absolute points, and a member is on
-"6 points" with seeded thresholds at 4, 7 and 10.
-
-**Why.** A percentage needs a configured maximum to mean anything, and a
-board that never opens the admin screen would have every member
-permanently at 0% of nothing. Points are readable on their own, the
-seeded ladder works on a fresh board, and "2 points, expires after 90
-days" is a sentence a moderator can weigh before issuing it. An importer
-can convert a percentage against the source board's maximum.
-
-### A warning restriction outranks a moderation bypass
-
-**MyBB:** a user under a "moderate posts" warning has their posts held;
-staff permissions are resolved separately and can conflict.
-
-**Meith:** a warning-level restriction is applied *after*
-`bypassesModeration`, and wins. A moderator who is themselves under a
-moderate-posting warning has their posts held, in every forum, including
-ones they moderate.
-
-**Why.** The bypass means "this forum's approval queue does not apply to
-you"; the warning means "your posts are reviewed". They are different
-statements, and the second is a sanction a person received. Letting the
-first cancel the second would make the board's moderators the only
-members a warning could not reach.
-
-### Bans from a warning level are not lifted by revoking the warning
-
-**MyBB:** a warning that triggered a ban and is then revoked leaves the
-ban in place; an administrator lifts it.
-
-**Meith:** the same, deliberately.
-
-**Why.** The ban lifecycle owns the group the ban captured, so it can be
-restored at expiry; un-banning from the warning path would restore a
-group that feature never saw. More importantly, a ban is the heaviest
-thing the board does to somebody, and its removal should be a decision a
-human makes while looking. The revocation still lowers the points, so the
-level no longer applies.
-
----
-
-## The moderator log
-
-### The moderator log is an allow-list over one table
-
-**MyBB:** the moderator log and the administrator log are separate
-tables.
-
-**Meith:** they share `admin_log`, and the ModCP filters it by a named
-allow-list of moderation actions.
-
-**Why.** One table means one place a bypass, a settings change and a
-thread lock are all recorded — what an operator wants when reconstructing
-an incident. The filter is an allow-list rather than a deny-list because
-the table keeps growing row types: a deny-list turns every future
-administrative action into a moderator-visible disclosure the day
-somebody forgets to update it, whereas an allow-list turns a new
-moderation action into a missing row somebody notices.
-
-### Everything that changes something is logged, and nothing that does not
-
-**MyBB:** the moderator log records what the moderation tools do.
-Handling a report, deleting one post from inside a thread, or editing
-somebody else's post leaves nothing behind.
-
-**Meith:** every path that changes content, a member's presentation or a
-report writes a row, whichever screen it was reached from: closing a
-report (`report.resolve` / `report.reject`), deleting or restoring a
-single post from the postbit (`post.delete` / `post.restore`), editing
-somebody else's post (`post.edit`), locking a signature or an avatar,
-copying a thread. Each further 500-recipient batch of a mass mail writes
-a row in the admin log, so a campaign is not one row followed by silence.
-Where the change is a database write, the row is written in the same
-transaction — a moderation that rolls back leaves no row claiming it
-happened.
-
-**The boundary is authorship, and it is deliberate.** A member deleting
-or editing their own post writes nothing: it is not moderation, and
-logging it would bury the moderation in it. Taking a report or putting it
-back is not logged either — it moves nothing, and the report's own
-timeline already shows who holds it.
-
-**Cost.** A forum whose moderators edit heavily has a longer log than
-MyBB's, and every entry names a post rather than only a thread. The log
-has no retention policy, so `admin_log` grows with moderation rather
-than administration alone.
-
-### Every log row names the forums it concerns, when it is written
-
-**MyBB:** the moderator log carries an `fid` column, and the ModCP scopes
-the list by it.
-
-**Meith:** the writer puts the forums into the row's detail — `forumIds`,
-an array of every forum the action reached — and the reader scopes by
-that and nothing else. Single-forum actions also carry `forumId`; moves
-and merges carry `fromForumId` and `toForumId`.
-
-**Why.** The reader used to guess, taking the first of several detail
-keys that was present — and a split logs *thread* ids under `from`/`to`,
-so the guess could read a thread id as a forum id: the entry surfaced to
-whoever moderated the forum whose id happened to match, and stayed hidden
-from the forum's real moderators. Ids are only unambiguous where they are
-named, so they are named. The array also gets multi-forum actions right:
-a move concerns two forums, and every one of those forums' moderators
-sees the entry. A GIN index over the array keeps the scoping cheap.
-
-**Cost.** Rows written before this change have no `forumIds`. Ones that
-carried an unambiguous forum key are still scoped by it; an old split,
-merge or move row is visible only to the moderator who wrote it, because
-the alternative is the misattribution above. There is no backfill — a
-migration that guessed would write the bug into the table permanently.
-
-### A lock and an unlock are two actions, not one action with a flag
-
-**MyBB:** records `open`/`close` and `stick`/`unstick` as separate action
-names.
-
-**Meith:** the same — `thread.lock` / `thread.unlock`, `thread.stick` /
-`thread.unstick`.
-
-**Why.** One action name with a boolean in the detail gives the log one
-label to print, so unlocking a thread would read as "Locked a thread"
-with "Set to: false" underneath. A log is read by someone reconstructing
-what happened, and the first line has to be true on its own.
-
-### The address lookup finds ranges, not addresses
-
-**MyBB:** the ModCP's IP search matches full addresses, which MyBB
-stores.
-
-**Meith:** it matches the truncated prefix the board stores, and the
-screen says so.
-
-**Why.** Every address is truncated before it is written, so there is no
-full address to match — a consequence of the privacy invariant rather
-than a choice made here. The screen states it because the difference
-matters to what a moderator does next: "shares an address" reads as
-proof, "shares a range" reads as something to check, and only the second
-is what the data supports.
-
-**Two ranges are on record per account, written at two moments.**
-`registration_ip_prefix` is written once, by the registration;
-`last_ip_prefix` is rewritten by each successful sign-in. MyBB also
-stamps `lastip` on ordinary page views; Meith leaves the presence write
-alone, because the sign-in is the moment the board learns an account is
-being used from somewhere, and it costs one update per session rather
-than one per member per minute.
-
-**Cost.** Both columns are null for every account the board already had,
-and for every account an import creates — the importer does not carry
-`regip` or `lastip` across, so an imported board's lookups stay empty
-until its members sign in here. `posts.ip_prefix` exists in the schema
-and nothing writes it: a per-post trail would be a second address record
-to keep, not a second thing to search.
-
----
-
-## The control panel
-
-### The control panel has its own session, with its own timeout
-
-**MyBB:** an admin session keyed to the board login, with a configurable
-timeout.
-
-**Meith:** a row in `admin_sessions` minted by re-entering the password,
-with a 30-minute idle timeout, an 8-hour absolute ceiling, and its own
-cookie (`Path=/admin`, `SameSite=Strict`). A board password change
-revokes it.
-
-**Why.** The threat is an administrator's own browser being used by
-somebody else, not a password being guessed. A board session lasts days
-by design; an admin session that inherited that would make an unattended
-laptop a board takeover. Separating them is what lets the panel timeout
-be short enough to matter.
-
-**Cost.** An administrator types their password twice — once for the
-board, once for the panel — and again after half an hour away.
-
-### The re-authentication clock is separate from the activity clock
-
-**MyBB:** the admin session has one timestamp, refreshed on every
-request.
-
-**Meith:** `last_seen_at` moves with activity; `authenticated_at` moves
-only when the password is re-entered. Destructive operations read the
-second, over a fifteen-minute window.
-
-**Why.** With one timestamp, an administrator who has been clicking
-around for an hour has a "fresh" session and is never asked again —
-which makes re-authentication a formality that fires only for people who
-walked away.
+Warnings use absolute points, with seeded levels at 4, 7 and 10. Posting restrictions apply after staff approval bypass. Revoking a warning lowers points but does not automatically lift an imposed ban; inspect and manage the ban separately.
 
-**Cost.** A long panel session asks for the password more than once, and
-only for destructive operations.
+## Logs and address lookup
 
-### The address allowlist is prefixes in the environment, not CIDR in the database
+Moderator and administrator actions share `admin_log`; the moderator view exposes an action allowlist and forum-scoped records. Database changes and their log entries commit together. Members editing their own posts and report-claim changes are not moderation log entries.
 
-**MyBB:** `$config['superadmins']` and an optional IP check in
-`config.php`.
+Current records use `forumIds`, with named source/destination fields for cross-forum actions. Older ambiguous move/merge/split records are limited to their author. The log has no automatic retention policy.
 
-**Meith:** `ADMIN_IP_ALLOWLIST` — comma-separated whole addresses, or
-textual prefixes ending in `.` or `:`. Empty means no restriction.
+Address lookup uses retained prefixes, not full addresses. Registration and last-successful-sign-in prefixes are recorded; ordinary page views do not update them. Imported accounts have no source IP history. Matching a range is not proof of shared identity.
 
-**Why.** The environment rather than a setting, because the allowlist
-defends against a stolen administrator credential, and storing it where
-that credential could edit it defeats the point. Prefixes rather than
-CIDR, because a mask is a thing people get wrong by one bit, and the
-failure mode is locking yourself out. The check runs *before* the board
-session is read, so a request from outside the list cannot learn the
-panel exists.
+## Admin sessions
 
-**Cost.** No `/28`-style precision, and no way to change it without a
-redeploy — both deliberate. A deployment behind no proxy (where no
-forwarded address arrives) is refused outright when a list is
-configured: the documented failure direction, rather than a silent
-bypass.
+Panel sessions require reauthentication and have a 30-minute idle timeout and 8-hour maximum. Destructive actions require proof within 15 minutes; browsing does not refresh that proof. Password changes revoke panel sessions.
 
----
+`ADMIN_IP_ALLOWLIST` accepts comma-separated addresses or textual prefixes ending in `.` or `:`, not CIDR. Empty means unrestricted. The check runs before session lookup and refuses requests without a usable trusted client address. Configure [proxy trust](web-security.md) before enabling it.
diff --git a/docs/operations/operating.md b/docs/operations/operating.md
index 57a18a213..be5d0cc00 100644
--- a/docs/operations/operating.md
+++ b/docs/operations/operating.md
@@ -1,47 +1,31 @@
-# Server operations
+# Operations
 
-Use this checklist when you take responsibility for a running board. Community settings and moderation are covered in [Community administration](../administration/organiser-guide.md); this page is about keeping the services and data working.
+## Deployment checks
 
-## Check a deployment
+Verify public HTTPS, sign-in, completed migrations, scheduled-task progress, delivered test mail, uploads surviving a restart and a successful off-site restore rehearsal.
 
-1. Open the public HTTPS address and sign in with a test account.
-2. Confirm the database is reachable and the core migration step completed successfully.
-3. Confirm scheduled work runs. Pages can load while queued work is stalled.
-4. Send a test email and check the receiving mailbox.
-5. Upload a test attachment and confirm it survives a restart.
-6. Verify an off-site backup and rehearse a restore.
-
-For a Compose deployment, run from the directory containing its Compose file:
+For Compose, run in the deployment directory:
 
 ```sh
 docker compose ps
 docker compose logs --since 1h web worker
 ```
 
-The PostgreSQL, web and worker services should be healthy; the one-shot migration service should have exited successfully. Service names and worker implementation depend on the deployment files you use.
+Database, web and worker should run; the migration service should have exited 0.
 
-## Find the maintenance task
+## Procedures
 
 | Task | Guide |
 |---|---|
-| Run a CLI command or recover administrator access | [Operator commands](operator-cli.md) |
-| Change a runtime setting or driver | [Board configuration](configuration.md) and [environment variables](environment.md) |
-| Apply migrations or configure pooled connections | [Database operations](database-operations.md) |
-| Configure outgoing email | [Email](mail.md) |
-| Run the worker or a scheduled tick | [Scheduled tasks](scheduled-tasks.md) |
-| Diagnose readiness, logs or alerts | [Monitoring](monitoring.md) |
-| Take, copy or test a backup | [Backups](backups.md) |
-| Install a release | [Upgrade Meith](upgrading.md) |
-| Replace a lost server | [Disaster recovery](disaster-recovery.md) |
-| Run more web instances | [Scaling](scaling.md) |
-| Add an extension | [Install plugins and themes](installing.md) |
-| Configure sign-in providers | [Authentication settings](single-sign-on.md) |
-| Enable browser notifications | [Web push](web-push.md) |
-
-If something is failing, start with [Troubleshooting](troubleshooting.md). The [cookies and headers reference](web-security.md) covers browser security behavior.
-
-## Keep a recovery handover
-
-Record the deployed version, board repository, hosting route, database, upload store, backup destination and scheduler. Store secrets securely outside the server, including the original `AUTH_SECRET`; backup bundles do not contain the environment.
-
-Record the date and result of the most recent restore rehearsal. A backup file's existence alone does not prove the board can be recovered.
+| CLI and account recovery | [Operator commands](operator-cli.md) |
+| Settings and drivers | [Configuration](configuration.md), [Environment](environment.md) |
+| Migrations and pooling | [Database](database-operations.md) |
+| Delivery | [Mail](mail.md), [Scheduled tasks](scheduled-tasks.md) |
+| Health and failures | [Monitoring](monitoring.md), [Troubleshooting](troubleshooting.md) |
+| Data recovery | [Backups](backups.md), [Disaster recovery](disaster-recovery.md) |
+| Releases and packages | [Upgrades](upgrading.md), [Extensions](installing.md) |
+| Replicas | [Scaling](scaling.md) |
+| Sign-in and browser policy | [Authentication](single-sign-on.md), [Security](web-security.md) |
+| Browser notifications | [Web push](web-push.md) |
+
+Record the deployed version, repository, service locations, scheduler, backup destination and last tested restore. Keep credentials, including the original `AUTH_SECRET`, securely outside the server. Backup bundles do not include them.
diff --git a/docs/operations/operator-cli.md b/docs/operations/operator-cli.md
index b84657836..1bbaf4ac0 100644
--- a/docs/operations/operator-cli.md
+++ b/docs/operations/operator-cli.md
@@ -1,107 +1,60 @@
-# Run operator commands
+# Operator commands
 
-Run maintenance commands from your board repository or a deployed container. Use the command form for your deployment; commands act on the database selected by that environment.
+Commands act on the database selected by their environment. Check it before running maintenance.
 
 ## The operator CLI
 
-`meith` is the operator CLI, and every maintenance command on this page is one of its subcommands. How you reach it depends on the deployment:
-
-| Deployment | Invocation |
+| Context | Invocation |
 |---|---|
-| Compose, into the running board | `docker compose exec web meith <command>` |
-| Compose, as a fresh one-shot container | `docker compose run --rm web meith <command>` |
-| A local checkout of the board | `npm run meith -- <command>` |
-| A platform that only builds and serves | `meith <command>`, from a checkout of the board repository with the production environment in front of it — see [Running on Vercel](vercel.md) |
-
-`meith` is on `PATH` inside the board image, so `exec`-ing into the running `web` container is the quick way — nothing to build, and it shares the board the container is already serving. `run --rm` starts a fresh container instead, which is what you want when `web` is not up (a broken migration, say); `--rm` stops those accumulating, and `-T` is needed when the command reads standard input, as creating a user does under [Account recovery](#account-recovery). On Coolify, both run from the resource's **Terminal** with no SSH — see [Running commands on Coolify](coolify.md).
-
-On a platform that only builds and serves, there is no container to run a command inside, which is why it runs from a checkout instead; the one command that does not wait for an operator is `meith migrate`, which belongs in the build command ahead of the build — see [Migrations](database-operations.md#migrations).
+| Board checkout | `npm run meith -- <command>` |
+| Running Compose service | `docker compose exec web meith <command>` |
+| One-shot Compose container | `docker compose run --rm web meith <command>` |
+| Meith source checkout | `pnpm meith <command>` |
 
-The CLI reaches PostgreSQL directly and can recover administrator access when
-the web interface is unavailable. **Admin → System** can apply pending plugin
-migrations after core migrations have run during deployment. Core migrations
-must run from the CLI; see [Migrations](database-operations.md#migrations).
+Use `meith --help` through the appropriate invocation to list installed commands. In Coolify, use the resource Terminal. For function hosting, use a local board checkout with the hosted-service environment.
 
-`meith --help` lists what the installed release actually has. A command documented here that is missing there means the running image is older than the page — see [A documented command is unavailable](troubleshooting.md#a-documented-command-is-unavailable).
+Use `-T` for piped input. Run core migrations before serving new code; panel upgrades handle plugin migrations only.
 
 ## Account recovery
 
-Create a user with a password on standard input:
-
-```sh
-printf '%s' '<password>' | docker compose run --rm -T web meith user:create --username <name> --email <address>
-```
-
-Promote a user:
-
-```sh
-docker compose run --rm web meith user:promote --user <id-or-username> --group <key-or-id>
-```
-
-Clear a lost second factor and end that user's sessions:
+Verify the requester's identity before changing credentials. Create a user with a password on stdin:
 
 ```sh
-docker compose run --rm web meith user:2fa-clear --user <id-or-username>
+read -r -s RECOVERY_PASSWORD
+printf '%s' "$RECOVERY_PASSWORD" | docker compose run --rm -T web meith user:create --username ada --email ada@example.com
+unset RECOVERY_PASSWORD
 ```
 
-Record who requested any recovery change.
-
-## Search maintenance
-
-Rebuild missing full-text records with the resumable command:
+Promote an existing user or clear a lost second factor:
 
 ```sh
-docker compose run --rm web meith search:reindex
+docker compose run --rm web meith user:promote --user ada --group administrators
+docker compose run --rm web meith user:2fa-clear --user ada
 ```
 
-Use it after an import or when diagnostics show posts without search data. It is safe to repeat.
-
-## Import a legacy board
-
-Follow [Import MyBB or phpBB](migrating.md) before running an import. The guide covers credentials, mounting source uploads, the row budget, resuming and checking permissions before cutover.
-
-From a board checkout configured for the destination database:
-
-```sh
-npm run meith -- import --help
-```
+Use the intended group key or ID. Clearing two-factor authentication revokes the user's sessions. Record the recovery request.
 
-Supply the source password through `IMPORT_SOURCE_PASSWORD`; `MYBB_PASSWORD` remains supported. Use a protected environment or secret store rather than typing the value into a command recorded by shell history.
+## Search and import
 
-After the import completes, reconcile counters and rebuild search with the destination environment:
+`meith search:reindex` rebuilds missing full-text records and can be repeated. After an [import](migrating.md), run:
 
 ```sh
 npm run meith -- task:run counters.reconcile
 npm run meith -- search:reindex
 ```
 
-## Plugins
-
-Installing a manifest-eligible plugin — one that ships a zero-argument `plugin` export, see
-[Writing a plugin](../extensions/plugins.md) — is a change to the sources your
-image is built from, not something run against the deployed image. On your own board — scaffolded by
-`create-meith`, or graduated out of the stock image by `board:eject` — it is one command, which
-installs the package and registers it:
+Supply source passwords through a protected `IMPORT_SOURCE_PASSWORD` environment variable; `MYBB_PASSWORD` is also accepted.
 
-```sh
-meith plugin:add @meith/plugin-dues
-```
+## Plugins
 
-In a checkout of *this* repository, where the board is one workspace among many, the package is added
-by hand with `pnpm add @meith/plugin-dues --filter @meith/web` (and `--filter @meith/board-stock` for
-the stock board) first, then `meith plugin:add @meith/plugin-dues` records it across both. See
-[Installing plugins and themes](installing.md) for the board admin's walkthrough.
+In a board checkout, `npm run meith -- plugin:add <package>` installs and registers a zero-argument `plugin` export. Commit `board.plugins.json`, `meith.plugins.ts`, package and lockfile changes, then deploy.
 
-`plugin:add` and `plugin:remove` edit `board.plugins.json` and regenerate
-`meith.plugins.ts`; commit both and rebuild and redeploy the image for the change to take
-effect. A plugin that cannot yet satisfy the manifest's export convention stays a line in
-`meith.plugins.ts` you write by hand, exactly as before.
+In the Meith monorepo, add the dependency to `@meith/web` and, when applicable, `@meith/board-stock` with `pnpm add --filter`, then register it. Plugins needing constructor arguments require manual configuration.
 
-Before removing plugin code, purge its owned data through the lifecycle hook — this one *does*
-run against the deployed board, because it needs the live database:
+To permanently remove owned data, back up first and purge before removing code:
 
 ```sh
 docker compose run --rm web meith plugin:purge <key> --yes
 ```
 
-Removing files first can leave data without the code required to clean it up.
+See [Extension installation](installing.md).
diff --git a/docs/operations/phpbb-parity.md b/docs/operations/phpbb-parity.md
index 4f13c07b0..eec21e607 100644
--- a/docs/operations/phpbb-parity.md
+++ b/docs/operations/phpbb-parity.md
@@ -1,41 +1,19 @@
-# phpBB migration differences
-
-Review these changes before importing phpBB. The [import guide](migrating.md) contains commands, coverage and cutover checks. A supported database import does not reproduce phpBB's complete ACL or extension behavior.
-
-## Accounts and permissions
-
-Every imported member enters Meith's ordinary registered group, including former administrators. Re-promote staff and rebuild groups, forum permissions and appointments before opening the board.
-
-phpBB roles, user-level overrides and its allow/deny/never ACL do not translate automatically. Meith resolves each group's forum inheritance and combines the results; a denial in one group does not cancel another group's grant. Test representative accounts rather than assuming old roles survived.
-
-## Posts and formatting
-
-The importer removes phpBB-specific BBCode UID markers and unwraps stored smiley/link markup before converting content to Markdown. Smiley images become their typed codes. Custom BBCode and unsupported tags may remain as text, and presentation such as colors does not survive as identical styling.
-
-Review old content containing nested quotes, code, links and custom tags. [Content conversion details](mybb-content.md) describes the shared converter's behavior and limitations.
-
-## Announcements and moved topics
-
-Ordinary stickies, forum announcements and global announcements import as sticky threads. They do not become Meith's separate announcement feature. Recreate board-wide banners through the admin announcement controls where needed.
-
-phpBB shadow rows for moved topics are not imported as separate discussions. Check old-topic redirects after enabling the legacy URL feature.
-
-## Polls, warnings and bans
-
-Poll options and votes are supported, including the source maximum-choice count and vote-change setting. Verify polls whose behavior matters to the community.
-
-phpBB warnings provide less information than Meith's point/expiry model. Review imported warning effects and any escalation rules; missing source detail cannot be reconstructed.
-
-Only supported member bans transfer. Email/IP bans and exclusion rows need separate review and configuration. Expiry requires scheduled work.
-
-## Messages, contacts and history
-
-Private messages are stored once with their recipient copies. Post attachments transfer through the file import; private-message attachments do not. Uploaded and gallery avatars are supported, while remote avatar URLs are not copied.
-
-Friends and foes map to buddy/ignore relationships with Meith's own behavior. Ignoring does not delete posts or shared conversation history.
-
-phpBB has no built-in reputation data to import. Historic moderator logs and member IP history are not carried across. Meith starts recording its own activity after the move.
-
-## Verify before opening
-
-Follow the import guide's checklist, especially administrator access, private-forum visibility and upload checks. Use [Community administration](../administration/organiser-guide.md) for the new board's ongoing settings.
+# phpBB migration checks
+
+Follow [Import](migrating.md). The MySQL/MariaDB importer does not reproduce phpBB ACLs or extensions.
+
+| Area | Result and required action |
+|---|---|
+| Accounts | Re-promote staff and rebuild groups, ACLs and appointments; source roles and allow/deny/never rules do not transfer |
+| Formatting | BBCode UID markers and stored smiley/link wrappers are cleaned before Markdown conversion; review custom tags and lost styling |
+| Announcements | Stickies and forum/global announcements become sticky threads; recreate board banners separately |
+| Moved topics | Shadow rows are skipped; test legacy redirects |
+| Polls | Choice count and vote-change flag transfer; verify significant polls |
+| Warnings | Source lacks points, titles and expiry; review imported effects and escalation |
+| Bans | User bans transfer; email/IP bans and exclusions require separate configuration |
+| Messages | Shared content with participant copies; PM attachments do not transfer |
+| Avatars | Uploaded/gallery supported; remote URLs skipped |
+| Contacts | Friends/foes become buddy/ignore relations |
+| History | No reputation, historical moderator log or member IP history imported |
+
+Test private forums as guests and ordinary members, not only administrators. Verify files and converted posts before opening the destination. See [Content conversion](mybb-content.md) and [Administration](../administration/organiser-guide.md).
diff --git a/docs/operations/scaling.md b/docs/operations/scaling.md
index 0e18ebeb8..12152a649 100644
--- a/docs/operations/scaling.md
+++ b/docs/operations/scaling.md
@@ -1,48 +1,27 @@
-# Run multiple web instances
+# Multiple web instances
 
-Multiple web instances must share PostgreSQL, a Redis-compatible cache and uploaded files. Prepare those shared services before adding replicas.
+All instances must share PostgreSQL, cache and uploads. Sessions, core flood limits, queues and task claims are database-backed; sticky sessions are unnecessary. Plugin route limits are process-local and multiply across replicas.
 
-## Understand what is shared
+## Prepare shared services
 
-Sessions, rate limits, queues and scheduled-task claims live in PostgreSQL. Requests do not need sticky sessions. Workers can claim work concurrently without treating every replica as an independent queue.
+1. Configure `CACHE_DRIVER=redis` and `REDIS_URL`.
+2. Back up uploads and copy them to shared storage, preserving keys. Use a shared volume on one host or S3-compatible storage across hosts.
+3. Set the file-store environment and restart the existing instance.
+4. Verify old files, a new upload and settings before adding replicas.
 
-Process-local caches and local disks are different: another server cannot see an upload on the first one's disk, and local cached settings can lag after changes. Metrics are also per process and must be aggregated.
+Changing drivers does not copy data. Keep original uploads until verified. Redis is not the durable source, but an unavailable configured cache can fail requests.
 
-## 1. Prepare shared cache and storage
+## Add replicas
 
-Set `CACHE_DRIVER=redis` and `REDIS_URL` for the compatible server. Redis holds cache entries; PostgreSQL remains the durable source. Losing Redis does not delete posts, but an unavailable configured cache can fail requests, so monitor it as required infrastructure.
-
-Choose shared upload storage. Replicas on one machine may share a persistent volume. Across machines, configure an S3-compatible store with its bucket, region, credentials and optional endpoint. Back up before moving existing uploads.
-
-## 2. Migrate an existing instance
-
-1. Start the shared cache and verify connectivity.
-2. Copy existing uploads to the intended shared store, preserving keys.
-3. Change the board's cache and file-store environment.
-4. Recreate the existing web instance and verify old attachments and a new upload.
-5. Add replicas only after that instance works with the shared services.
-
-Keep the original upload copy until the migration is verified. Switching a driver does not copy files automatically.
-
-## 3. Configure the proxy and replicas
-
-For the generated by-hand Compose stack, the `redis` profile supplies a compatible cache. Configure the reverse proxy on the service network if scaling the web service: a fixed host port cannot be bound by several containers.
+Adapt the proxy to route on the service network and remove fixed host-port bindings before scaling. Then, for the generated by-hand stack:
 
 ```sh
 docker compose --profile redis up -d --build
 docker compose --profile redis up -d --scale web=3
 ```
 
-Use this only after adapting the proxy/port configuration and environment. Route to the web service without session affinity. Keep `TRUSTED_PROXY_HOPS` equal to the number of trusted proxies, not the number of web replicas.
-
-## 4. Budget database connections
-
-Each application process has its own pool. Multiply the per-process limit by potential web instances and include workers and maintenance commands. Use runtime pooling where appropriate and the direct connection for migrations and backups.
-
-Read [Database connections](database-operations.md). A burst of function instances can exhaust a database or cache connection limit even when one test instance works.
-
-## 5. Verify across instances
+Set `TRUSTED_PROXY_HOPS` to proxy count, not replica count.
 
-Change a setting, read it through another instance, upload a file and retrieve it through another instance, then check sign-in and private-forum visibility. Watch queues, errors and database connections under realistic load.
+Each process opens its own database pool. Include replicas, workers and maintenance in the [connection budget](database-operations.md).
 
-[Monitoring](monitoring.md) explains per-instance metrics. [Vercel configuration](vercel-configuration.md) covers function hosting; it is not the same deployment as scaling a persistent Compose service.
+Verify a setting change and upload across different instances, sign-in and private content. Aggregate [per-process metrics](monitoring.md) and monitor queue progress.
diff --git a/docs/operations/scheduled-tasks.md b/docs/operations/scheduled-tasks.md
index c176a18b6..03ea564cc 100644
--- a/docs/operations/scheduled-tasks.md
+++ b/docs/operations/scheduled-tasks.md
@@ -1,53 +1,39 @@
-# Run scheduled tasks
+# Scheduled tasks
 
-Scheduled work delivers queued notifications, maintains indexes, expires restrictions and performs other background jobs. A PostgreSQL-backed board needs a worker or an authenticated HTTP scheduler.
-
-## Choose one scheduling route
+A PostgreSQL board needs continuing scheduling for notifications, indexes, expiry and backups.
 
 | Deployment | Scheduler |
 |---|---|
-| Generated Compose/Coolify board | Its worker container calls the web tick endpoint |
-| Meith monorepo worker process | `apps/worker` runs scheduler loops directly |
-| Function hosting | An external or hosting-provided cron calls `/api/system/tick` |
-
-Use the worker shipped with your deployment where possible. A fixture board has no durable scheduler and returns 503 from the tick endpoint.
+| Generated Compose/Coolify | Worker calls the web tick |
+| Meith monorepo | `apps/worker` runs scheduler loops |
+| Function hosting | Cron calls `/api/system/tick` |
 
-## Call the HTTP tick
+## HTTP tick
 
-Configure `TICK_SECRET` or `CRON_SECRET` in the board environment and a matching credential in the scheduler. Generate at least 32 characters and keep the secret out of the URL.
+Set `TICK_SECRET` or `CRON_SECRET` to an independent secret of at least 32 characters. Give the scheduler the same credential through its secret store.
 
 ```sh
-curl --fail-with-body   -H "Authorization: Bearer $TICK_SECRET"   https://board.example/api/system/tick
+curl --fail-with-body \
+  -H "Authorization: Bearer $TICK_SECRET" \
+  https://board.example/api/system/tick
 ```
 
-Replace the origin and provide the secret from the scheduler's secret store. The endpoint also supports `X-Tick-Secret`; query-string secrets are not accepted.
-
-A minute cadence keeps the shortest-interval work responsive. Each task decides whether it is due. A less frequent tick delays processing; some time-sensitive features, such as reminders for an event that already started, cannot be made timely by catching up afterward.
-
-The Vercel template's daily schedule is a deployment starting point, not a promise of instant notifications. Choose a supported more frequent schedule when required.
+`X-Tick-Secret` is also accepted. Query-string secrets are rejected. Run every minute for responsive processing; each task checks its own due time. A sparse schedule delays delivery and may miss time-sensitive reminders. The Vercel template starts with a daily schedule.
 
-## Read the result
-
-| Result | Meaning |
+| Response | Meaning |
 |---|---|
-| `200`, `ok: true` | Tick completed without reported task failures |
-| `200`, `ok: false` | One or more tasks failed; inspect `ran` and the named task |
-| `404` | Missing or incorrect scheduler credential |
-| `503` | No durable scheduler, such as fixture mode |
-
-Do not retry a permanently failing task in a tight loop. Inspect **Admin → System** and logs, repair the cause, and allow the scheduler or a deliberate maintenance run to retry.
+| `200`, `ok: true` | No reported task failures |
+| `200`, `ok: false` | Inspect failed entries in `ran` and logs |
+| `404` | Missing/incorrect credential |
+| `503` | No durable scheduler, including fixture mode |
 
-## Run maintenance from the CLI
+## CLI and verification
 
-Use the invocation for your board from [Operator commands](operator-cli.md):
+From the board directory:
 
 ```sh
-meith task:list
-meith task:run
+npm run meith -- task:list
+npm run meith -- task:run
 ```
 
-Use the installed command's help before selecting a specific task. A manual run is a diagnostic tool, not a replacement for a continuing production scheduler.
-
-## Verify progress
-
-Check task timestamps, queue depth, search-index progress and a controlled notification. An HTTP worker can be healthy and quiet; verify completed work in the web logs and system page. [Monitoring](monitoring.md) covers readiness and alerts.
+A manual run does not replace production scheduling. Check **Admin → System**, task timestamps, queue depth and a test notification. Generated HTTP-worker task logs are in web. See [Monitoring](monitoring.md).
diff --git a/docs/operations/single-sign-on.md b/docs/operations/single-sign-on.md
index cb1c17551..7d758204b 100644
--- a/docs/operations/single-sign-on.md
+++ b/docs/operations/single-sign-on.md
@@ -1,27 +1,15 @@
-# Authentication settings
+# Configure authentication
 
-Configure sign-in methods for a board you operate. Members managing their own password, two-factor authentication or devices should use [Account security](../members/account-security.md).
+Verify HTTPS, the public board URL, mail delivery and an operator recovery route before changing sign-in settings.
 
-## Before changing sign-in
-
-Confirm that HTTPS, the public board URL and outgoing email work. Keep a tested administrator recovery route available before enabling additional restrictions. Do not treat a provider's email address as proof of account ownership without the supported linking flow.
-
-## Choose a feature
-
-| Feature | Configuration and behavior |
+| Feature | Setup/reference |
 |---|---|
-| Authenticator codes and recovery codes | [Two-factor authentication](authentication-reference.md#a-second-factor) |
-| Persistent sign-in and device sessions | [Sessions](authentication-reference.md#where-a-member-is-signed-in) |
-| Account security history | [Security activity](authentication-reference.md#what-has-happened-to-an-account) |
-| External identity providers | [Federated sign-in](authentication-reference.md#federated-sign-in) |
-| Device passkeys | [Passkeys](authentication-reference.md#passkeys) |
-
-Use the supported settings in the admin panel and the environment required by your provider. Check callback URLs against the board's public origin, then test with a separate member account before changing administrator access.
-
-## Verify recovery
-
-Check password-reset delivery, a normal sign-in, sign-out and a fresh sign-in using the configured method. For two-factor authentication, verify that recovery codes are saved separately from the authenticator device.
+| Authenticator and recovery codes | [Two-factor authentication](authentication-reference.md#two-factor-authentication) |
+| Sessions and persistent sign-in | [Sessions](authentication-reference.md#sessions) |
+| Security history | [Activity](authentication-reference.md#security-history) |
+| GitHub, Google or OIDC | [Federated sign-in](authentication-reference.md#federated-sign-in) |
+| Device credentials | [Passkeys](authentication-reference.md#passkeys) |
 
-If a member loses both the authenticator and recovery codes, an operator can use the [account recovery command](operator-cli.md#account-recovery) after establishing the member's identity. Clearing a second factor revokes the member's sessions; it is not a routine replacement for using recovery codes.
+Set provider callbacks against the permanent public origin. Test sign-in, sign-out, linking and recovery with a separate member before changing staff requirements.
 
-The [authentication reference](authentication-reference.md) explains linking, protocol boundaries and common failures.
+Members use [Account security](../members/account-security.md). If an authenticator and all recovery codes are lost, verify identity before [operator recovery](operator-cli.md#account-recovery); clearing the factor revokes sessions.
diff --git a/docs/operations/stripe-setup.md b/docs/operations/stripe-setup.md
index ed6045d3a..7941b71be 100644
--- a/docs/operations/stripe-setup.md
+++ b/docs/operations/stripe-setup.md
@@ -1,68 +1,31 @@
 # Connect Dues to Stripe
 
-Set up payments, webhook delivery and receipts for the Dues plugin. You need administrator access to the board and access to its Stripe account. First [install the plugin and run its migrations](installing.md); keep the worker or scheduled tick running. After setup, use [Manage paid memberships](../administration/membership-guide.md) for plans, discounts and day-to-day administration.
+Install [Dues and its migrations](installing.md), keep the scheduler running and use a separate staging board/database for test payments. Stored Stripe IDs belong to one account and mode; changing keys does not convert them.
 
-## Keep test and production separate
+## Board settings
 
-Use a separate staging board and database for Stripe sandbox/test purchases.
-Dues stores Stripe customer, price and subscription IDs in its database;
-those IDs belong to one Stripe account and mode. Switching a board that
-already contains test purchases to live keys does not convert those records.
-Keep the production board's records and credentials live, and the staging
-board's records and credentials in the same sandbox/test environment.
+Set the public HTTPS **Board address** or `APP_URL`. Stripe must reach the webhook without proxy authentication or browser challenges. Create an ordinary benefit group and enable **may be granted by plugins**.
 
-## 1. Set the public board address
+Under **Admin → Plugins → Dues**, configure:
 
-Set **Admin → Settings → Board address** to the board's public HTTPS origin,
-for example `https://forum.example.com`. If the deployment sets `APP_URL`,
-set that variable to the same public address; it takes precedence. Stripe
-must be able to reach the board without an admin login, a proxy password or
-a browser challenge. The webhook is a public endpoint whose requests are
-authenticated by their Stripe signature.
+| Setting | Value | Environment override |
+|---|---|---|
+| Stripe secret key | Account/mode API secret (`sk_test_…` or `sk_live_…`) | `DUES_STRIPE_SECRET_KEY` |
+| Webhook signing secret | Specific endpoint's `whsec_…` secret | `DUES_STRIPE_WEBHOOK_SECRET` |
 
-Create the membership group under **Admin → Groups**, enable **may be
-granted by plugins**, and give it the permissions and appearance you want
-to sell. Staff and system groups cannot be sold this way.
+Get API secrets from [Stripe API keys](https://docs.stripe.com/keys). Publishable `pk_…` keys and endpoint `we_…` IDs are not these secrets. Overrides win over panel values and must reach both web and worker; Compose `.env` values require service forwarding.
 
-## 2. Copy the Stripe API secret key
+Keep the API base at `https://api.stripe.com` and the plugin's default API version `2024-12-18.acacia` unless deliberately changing integration behaviour.
 
-In Stripe, select the account and sandbox/test environment for the staging
-board, then open [API keys](https://dashboard.stripe.com/apikeys). Find the
-**Secret key**, reveal it if available, or create one and copy it when Stripe
-shows it. A test secret starts with `sk_test_`; a live secret starts with
-`sk_live_`. A newly created live secret may only be shown once. See
-[Stripe's API key guide](https://docs.stripe.com/keys).
+## Webhook
 
-On the board, open **Admin → Plugins → Dues**, paste that value into
-**Stripe secret key**, and save. Dues calls Stripe from the server; the
-publishable `pk_…` key is not used here. The `whsec_…` value in the next step
-is a different secret and goes in a different field.
+Create a [Stripe webhook destination](https://docs.stripe.com/webhooks) for the same account/mode, using snapshot events and the API version configured in Dues. Target:
 
-| Board setting | Environment override | Where to get it |
-|---|---|---|
-| **Stripe secret key** | `DUES_STRIPE_SECRET_KEY` | Stripe → API keys → Secret key (`sk_test_…` or `sk_live_…`). |
-| **Webhook signing secret** | `DUES_STRIPE_WEBHOOK_SECRET` | The particular Stripe webhook endpoint's signing secret (`whsec_…`), after creating it below. |
-
-Environment values override saved settings. If the panel says a field is
-controlled by the environment, change that value in the deployment or
-remove the override before saving a value in the panel. Environment changes
-need to reach both the web process and worker, followed by a restart or
-redeploy. With Docker Compose, adding a variable to `.env` alone does not
-pass it to a container: it must also be forwarded by the service's
-`environment` or `env_file` configuration. Saving the keys in the admin
-panel avoids that extra wiring. Keep the secrets out of committed files.
-
-Leave **Stripe API base** at `https://api.stripe.com`. The advanced **Stripe
-API version** defaults to `2024-12-18.acacia`; leave it unchanged for this
-setup.
-
-## 3. Create the webhook destination in Stripe
-
-Stay in the same Stripe account and sandbox/test environment as the API
-key. Open [Workbench → Webhooks](https://dashboard.stripe.com/webhooks)
-and create an event destination. Choose events from **Your account**, use
-snapshot events and the API version configured in Dues, then select these
-ten event types:
+```text
+https://forum.example.com/api/plugins/dues/hook/stripe
+```
+
+Subscribe to these events, also listed in Dues **Status**:
 
 ```text
 checkout.session.completed
@@ -77,105 +40,44 @@ charge.refunded
 charge.dispute.created
 ```
 
-These are also listed on **Admin → Plugins → Dues → Status**. Continue,
-choose **Webhook endpoint**, and enter the complete public URL:
+Copy that destination's signing secret into Dues.
 
-```text
-https://forum.example.com/api/plugins/dues/hook/stripe
-```
+## Receipts and portal
+
+Enable successful-payment emails in Stripe's customer-email settings if needed. Test payments do not automatically send receipt emails; use the manual receipt action for testing. See [Stripe receipts](https://docs.stripe.com/receipts).
 
-Replace `https://forum.example.com` with your board's address. Save the
-destination, open its details, and reveal its **Signing secret**. Copy the
-whole `whsec_…` value into **Admin → Plugins → Dues → Webhook signing
-secret**, then save. Do not use the endpoint's `we_…` identifier or invent a
-random secret. Stripe and Dues must have the same signing secret for this
-specific endpoint. See [Stripe's webhook setup](https://docs.stripe.com/webhooks).
-
-## 4. Configure receipts and the billing portal
-
-In Stripe's [Customer emails settings](https://dashboard.stripe.com/settings/emails),
-enable **Successful payments** for emailed receipts; enable refund emails
-if wanted. Automatic receipt emails are not sent for test payments, so use
-Stripe's manual receipt action when testing email delivery. One-time
-receipts are also available through **Your membership → Recent receipts**;
-they do not require invoice creation. See [Stripe's receipts guide](https://docs.stripe.com/receipts).
-
-Open the [customer portal settings](https://dashboard.stripe.com/settings/billing/portal)
-in the same environment and save its configuration. Enable payment method
-updates and invoice history. Leave plan switching and quantity changes off:
-Dues sells the plans and group grants configured on the board. Dues already
-creates a portal session for the signed-in buyer and supplies its return
-address, so you do not need to paste a public portal link into the plugin.
-See [Stripe's portal settings](https://docs.stripe.com/customer-management/configure-portal).
-
-## 5. Complete a real Dues checkout in the sandbox
-
-Create a fixed-term plan under **Admin → Plugins → Dues → Plans**, priced
-above Stripe's minimum for its currency. Sign in as a member on the staging
-board, open **Membership**, and buy that plan through its checkout button.
-Use Stripe's test card `4242 4242 4242 4242`, a future expiry date and any
-three-digit CVC. These are [sandbox test details](https://docs.stripe.com/testing#cards),
-never details to use in live mode.
-
-After payment, check all of the following:
-
-- In Stripe's webhook destination, the checkout event's delivery returned
-  HTTP `200`.
-- In **Admin → Plugins → Dues → Status**, the checkout event appears with
-  outcome `granted` for the first paid pass. `deferred` means Dues recorded it but processing
-  failed; inspect the board logs and the worker's reconciliation.
-- The member's return page changes from **Confirming your payment…** to
-  **Paid, and done** after **Check again**; the membership and ledger entry
-  exist, and **Your membership → Recent receipts → View receipt** opens the
-  Stripe receipt.
-- **Open the billing portal** works. If you sell subscriptions, test a
-  subscription and cancellation as well.
-
-A generic event sent from Stripe's test tools may contain a Checkout Session
-that Dues never created. An `unmatched-session` outcome then checks delivery
-but does not prove a purchase grants membership. Start the checkout on the
-board for the complete test.
-
-For production, repeat the key, webhook and portal setup in Stripe's live
-mode on the production board. Copy its `sk_live_…` key and its live endpoint's
-own `whsec_…`; the sandbox's signing secret will not work. Create production
-subscription prices in live mode too, or let Dues create them when you add
-the production plans. Do not reuse a sandbox `price_…` ID.
-
-## Local development with Stripe CLI
-
-Use a PostgreSQL-backed development board with Dues installed; the default
-fixture mode is not a persistent payment test. Follow the
-[development setup](local-board.md), then install the
-[Stripe CLI](https://docs.stripe.com/cli/install) and run:
+Configure the [billing portal](https://docs.stripe.com/customer-management/configure-portal) in the same mode. Enable payment-method updates and invoice history; leave plan switching and quantity changes off. Dues supplies authenticated portal sessions and return URLs.
+
+## Test checkout
+
+Create a paid pass on the staging board, then buy it as a member using [Stripe test payment details](https://docs.stripe.com/testing#cards). Start checkout on the board; generic test events can return `unmatched-session` without testing a real order.
+
+Verify webhook HTTP 200, a `granted` outcome in **Status**, membership and ledger entries, the receipt link and portal access. `deferred` means processing needs investigation/reconciliation. Test subscription cancellation if selling subscriptions.
+
+Repeat setup on the production board with live keys, a live endpoint secret and live prices. Never reuse test IDs.
+
+## Local development
+
+Use a writable PostgreSQL board and [Stripe CLI](https://docs.stripe.com/cli/install):
 
 ```sh
 stripe login
 stripe listen --forward-to http://localhost:3000/api/plugins/dues/hook/stripe
 ```
 
-The listener prints a `whsec_…` signing secret. Save **that listener's
-secret** in the local board's webhook setting and use an API key from the
-same sandbox/test environment. Keep the listener running while buying a
-plan on the local board. A Dashboard endpoint's secret and the CLI
-listener's secret are different, even though both start with `whsec_`.
-See [Stripe's signature troubleshooting](https://docs.stripe.com/webhooks/signature).
+Save the listener's signing secret, not a Dashboard endpoint's secret, and keep the listener running during checkout.
 
-## If setup does not work
+## Troubleshoot
 
-| Symptom | What to check |
+| Symptom | Check |
 |---|---|
-| Both keys say **set**, but checkout fails | **Set** checks presence only. Check the key's account and mode, the public board address, and the server log for `dues: could not start checkout`. |
-| The settings form does not change the key in use | An environment override wins. Update it for the web and worker processes and redeploy, or remove it and use the saved setting. |
-| Stripe reports `404`, a redirect, or an HTML login page | Use the exact `/api/plugins/dues/hook/stripe` URL on the public HTTPS board. Check that Dues is enabled and that the proxy forwards this path directly. Opening it in a browser sends GET; Stripe needs POST. |
-| Stripe reports `503` with an unconfigured signing secret | Fill **Webhook signing secret**, or correct `DUES_STRIPE_WEBHOOK_SECRET` in the running deployment. |
-| Stripe reports `400` with a signature error | Copy the secret from the destination that sent this event. Check sandbox versus live and Dashboard versus CLI, the server clock, and that the proxy preserves the request body and `Stripe-Signature` header. |
-| Stripe reports `200`, but access is missing | Inspect the event outcome in Dues Status. An unmatched test event is not a board order; a deferred or flagged payment needs investigation. Ensure the worker or scheduled tick runs so reconciliation can recover failed processing. |
-| Stripe says a customer or price does not exist | The saved Stripe IDs and API key belong to different accounts or modes. Keep sandbox and live boards separate; changing the key does not migrate IDs. |
-| The portal has no invoice for a paid pass | One-time payments have receipts without invoices. Use **Recent receipts** on the membership page. |
-
-## Public origin and advanced configuration
-
-Checkout and billing-portal redirects use `APP_URL`, or the saved Board address when the environment does not override it. Without a configured address, these flows refuse to start. Exact loopback hosts (`127.0.0.1`, `localhost` and `::1`) are allowed for local development.
-
-The standard `dues` export needs no constructor arguments. A custom board can register `createDues({ extraRedirectHosts: ['proxy.example'] })` when it deliberately needs another redirect host; this is a code option, not an admin setting. The standard definition permits Stripe checkout, billing and hosted receipt destinations.
+| Keys set, checkout fails | Account/mode, public origin and `dues: could not start checkout` log |
+| Saved key has no effect | Environment override and restarted web/worker |
+| 404, redirect or login HTML | Exact public POST route, enabled plugin and proxy |
+| 503 | Missing signing secret |
+| 400 signature error | Sending endpoint's secret, test/live mode, clock and unchanged raw body/header |
+| 200 without access | Event outcome, matching board order and reconciliation task |
+| Missing customer/price | Stored ID and key account/mode mismatch |
+| Pass absent from portal invoices | Use **Your membership → Recent receipts** |
+
+Checkout/portal flows require a configured origin; exact loopback hosts are allowed locally. Custom `createDues({ extraRedirectHosts: [...] })` is a code-level option. See [Membership administration](../administration/membership-guide.md).
diff --git a/docs/operations/troubleshooting.md b/docs/operations/troubleshooting.md
index 2b46cadba..d29084c36 100644
--- a/docs/operations/troubleshooting.md
+++ b/docs/operations/troubleshooting.md
@@ -1,40 +1,23 @@
-# Troubleshoot a running board
+# Troubleshooting
 
-Start with the symptom you can observe. Run diagnostics in the affected deployment and verify the result after changing its configuration.
+## Migration does not complete
 
-## Troubleshooting
+Run `docker compose logs migrate`. Check database health, connection values, secrets and release version. Web waits for successful migration.
 
-### Migration does not complete
+Overlapping core migrations wait on an advisory lock. If no other migration is running, verify `DIRECT_DATABASE_URL` points directly to PostgreSQL, not a transaction pooler. See [Database operations](database-operations.md).
 
-```sh
-docker compose logs migrate
-```
+## Pages load but mail or tasks do not run
 
-Check database health, connection values, required secrets, and the selected release. Web and worker correctly wait when migration fails.
+Run `docker compose ps worker` and `docker compose logs --since 1h web worker`. Check tick credentials and response bodies, then the failing task and mail configuration. The generated worker calls web; it does not execute tasks itself.
 
-A run that produces no output and does not exit is waiting for the advisory lock, which means another migration holds it — an overlapping deploy, usually. Let it finish; the waiting run then applies nothing and exits 0. A run that hangs with no other migration in flight is a connection problem rather than a lock one: on a managed database, confirm `DIRECT_DATABASE_URL` names the direct connection string and not the pooler. See [Migrations](database-operations.md#migrations).
+## Uploads disappear after recreation
 
-### Pages load but mail or tasks do not run
+Check persistent storage mounts at `/app/.uploads` for services using local files. Files in disposable container layers are lost on recreation.
 
-```sh
-docker compose ps worker
-docker compose logs --since 1h worker
-```
+## Redirects use the wrong origin
 
-Validate the worker environment and its access to PostgreSQL and the configured mail endpoint.
+Set `APP_URL` to the public HTTPS origin, check proxy forwarding and recreate affected services.
 
-### Uploads disappear after recreation
+## A documented command is unavailable
 
-Confirm web and worker both mount the persistent upload volume at `/app/.uploads`. Container layers are replaceable and must not hold the only copy.
-
-### Redirects use the wrong origin
-
-Set `APP_URL` to the public HTTPS origin, not an internal container address. Check reverse-proxy forwarding and recreate affected services.
-
-### A documented command is unavailable
-
-```sh
-docker compose run --rm web meith --help
-```
-
-Use documentation and CLI output from the version you operate.
+Run `docker compose run --rm web meith --help`. Match the documentation and command to the installed release; follow [Upgrades](upgrading.md) if needed.
diff --git a/docs/operations/upgrade-notes.md b/docs/operations/upgrade-notes.md
index f8c52ae0d..d706eb826 100644
--- a/docs/operations/upgrade-notes.md
+++ b/docs/operations/upgrade-notes.md
@@ -1,467 +1,76 @@
-# Upgrade compatibility notes
+# Upgrade compatibility
 
-Check these compatibility notes before upgrading an older board. The upgrade guide contains the procedure; this reference records changes to settings, permissions and stored behavior.
+Use [Upgrade a board](upgrading.md) for the procedure. These notes cover behaviour changes in the 0.x series; review stored settings before upgrading an older board.
 
-## What recent releases changed
+## Defaults and configuration
 
-The rest of this page is the operator-facing change log for the 0.x
-series: defaults that moved, settings that started being enforced, and
-behaviour that changed shape. Skim the headings; each entry says whether
-a board that never touched the setting is affected.
-
-### Defaults that changed
-
-A board setting is stored only once somebody changes it, so a default
-that moves applies to every board that never touched the switch. There is
-nothing to run; the point of listing it is that behaviour changed without
-anybody on your board doing anything.
-
-| Setting | Was | Is | On a board that never set it |
-|---|---|---|---|
-| `reputation.comment_required` | on | off | Posts gain a one-press **Thanks** button; a rating no longer has to carry a reason. Set it back under **Settings → Reputation** if your board wants every rating to say why — the right choice for a board that allows negative ratings. |
-
-**The navigation menu starts smaller.** A new board shows Home, New posts
-and Search; Unanswered, My posts, Who's online, Members and Staff are
-still rows under **Admin → Content → Navigation**, hidden until somebody
-ticks **Shown in the menu**. The migration that ships this hides those
-five on an existing board too, but only where the row is untouched — its
-label still empty and still at the top level — so a menu somebody has
-renamed or reorganised keeps what it had. Tick the ones your board wants
-back; it is one press each.
-
-**`TRUSTED_PROXY_HOPS` now defaults to `0`, not `1`.** It was `1` because
-that matched the one documented reverse proxy in front of `compose.yml`;
-the trouble was any board that published the board's port directly, with
-nothing in front, inherited a default that trusted a header any visitor
-can set — forging the address the IP allowlist, the login lockout and the
-audit log key off. `compose.yml` and the Coolify compose files now set
-`TRUSTED_PROXY_HOPS=1` themselves, so a board deployed with one of them
-sees no change. **A board that never set the variable elsewhere** — a
-board on Vercel included, sitting behind that platform's own edge network
-— now has `X-Forwarded-For` ignored outright: set `TRUSTED_PROXY_HOPS=1`
-yourself to get it back. See
-[Deploying by hand § Count your proxies](docker-compose.md).
-
-### Configuration that moved out of the environment
-
-Two things that were environment variables and nothing else are board
-settings now. **Nothing changes for a board that had them set** — the
-environment still wins outright, and the settings screen says so. What
-changes is the board that never set them, which previously could not fix
-either without a redeploy:
-
-| | Was | Is |
-|---|---|---|
-| **Mail** | `MAIL_DRIVER` and friends, read at boot | `MAIL_DRIVER=http` or `=smtp` still wins. `log`, or unset, hands the decision to `/admin/settings?group=mail` — which has a **Send a test message** button that shows the provider's own refusal verbatim. |
-| **The board's address** | `APP_URL`, read at boot | `APP_URL` still wins. Unset, it comes from **Board address** on `/admin/settings?group=board`, and the installer asks for it on a fresh board. |
-
-Worth doing once after the upgrade: open `/admin/settings?group=mail` and
-press the test button. Mail is the subsystem where a misconfiguration is
-silent by construction, so "we believe mail works" and "a message
-arrived" are worth reconciling.
-
-**`MAIL_DRIVER=smtp` boots now.** It used to refuse to start, on purpose:
-there was no SMTP driver, and quietly downgrading to the log driver would
-have meant password resets vanishing with no error. There is a driver
-now; `MAIL_SMTP_HOST` and `MAIL_FROM` are required with it. If you have
-been running a separate relay to bridge the gap, it can go.
-
-**`TICK_DEADLINE_MS` and `TICK_MAX_JOBS` are gone.** They were read by
-nothing — declared, documented, and consulted by no code. Leaving them in
-your `.env` is harmless (unknown variables are ignored); delete them when
-convenient.
-
-### Settings that gained a reader
-
-A setting can also change behaviour by starting to be *read*. Nothing to
-run — but worth knowing which switches on your board were, until now,
-decorative.
-
-#### The silent edit window works
-
-`posting.edit_grace_seconds` had no reader: the *Last edited by* line
-rendered on every edit whatever the box said. It is read now, with a
-default of **300 seconds**, so an author fixing their own post within
-five minutes leaves no notice. **This is a visible change on a board that
-never touched the setting** — notices that used to appear on quick typo
-fixes stop appearing. `posting.edit_grace_seconds 0` restores the old
-behaviour exactly.
-
-Nothing is hidden that should not be: a moderator editing somebody
-else's post is never silent, the revision history is unchanged, and a
-silent edit does not clear a notice already on the post.
-
-#### The minimum search word length works
-
-`search.min_word_length` never reached the query parser, which carried a
-hard-coded 2 — a board that asked for 5 got 2, and a board that asked for
-1 also got 2. It is read now, **and its default moved from 3 to 2 in the
-same release**, so nothing changes on a board that never set it: 2 is
-what every board has actually been enforcing. A board that stored a
-number now gets that number, which is the change it asked for.
-
-The rule is *at least one word*, not *every word*: a search is refused
-only when every word in it is shorter than the setting, and short words
-in a search that also has a long one are passed to the index. The label
-now says so.
-
-#### `search.enabled` actually switches search off
-
-Another switch nobody read: the Search link was unconditional, `/search`
-ran queries, and the API answered them. It is read now, in all three
-places — the link goes, the search pages say search is off, and
-`GET /api/v1/search` answers 403. The default is on. **A board that
-stored `false` loses its search the moment it upgrades** — which is what
-it asked for, though worth telling your members. The index is still
-maintained while search is off, so switching back on needs no reindex.
-
-#### `registration.enabled` actually closes registration
-
-Whatever the switch said, `/register` rendered its form and the action
-created the account. It is read now: off takes the Register link away,
-replaces the form with a notice, and answers a direct POST with 403. The
-default is on, so an untouched board sees nothing change; **a board that
-stored `false` gets the closure it asked for on upgrade** — and if it has
-been quietly accepting registrations, its member list is worth a look.
-
-Neither the installer nor `meith user:create` consults it: an
-operator at a terminal cannot be locked out of the board they are
-installing. See
-[The organiser's guide § Registration](../administration/manage-members.md#registration).
-
-#### `registration.method` decides what a new account must do
-
-The activation dropdown stored its value and every account was created as
-though it said `none`. It is honoured everywhere now, **and its default
-moved to `none` in the same release**, which is what keeps this from
-changing anything under you:
-
-| Your board stored | Before | Now |
-|---|---|---|
-| Nothing — never opened the screen, *or* chose `email` while it did nothing | Accounts active immediately | Unchanged |
-| `none` | Accounts active immediately | Unchanged |
-| `admin` | Active immediately, **contrary to the setting** | Accounts wait for an administrator |
-| `both` | Active immediately, **contrary to the setting** | A confirmation link, then an administrator |
-
-The first row needs explaining: a value equal to its default is not
-stored, so an operator who selected `email` back when it did nothing has
-no row and is indistinguishable from somebody who never opened the
-screen. Defaulting to `email` would have switched confirmation on for
-both — on boards that very often had no mail configured, leaving them
-unable to register anybody. The default follows the behaviour every
-board actually had.
-
-**If you did want confirmed addresses, say so again — this time it
-works.** Configure mail first, prove it with the test button, then set
-the method under **Settings → Registration**.
-
-> [!IMPORTANT]
-> `email` or `both` on a board with no working mail is a board nobody can
-> join: the links are minted, written to the log, and never sent. The
-> registration settings screen and `/admin/system` both say so for as
-> long as it is true.
-
-Accounts stuck at *awaiting activation* can be activated by hand under
-**Admin → Members**, and anybody who never received a link can ask for
-another at `/verify/resend`.
-
-#### The password and username rules come from the settings screen
-
-`registration.min_password_length`, `registration.username_min` and
-`registration.username_max` were served from constants — the form went on
-enforcing 8, 3 and 30 whatever the settings said. They are read now, by
-the board **and by `meith user:create`** (a CLI that enforced
-different rules would create accounts the board itself would reject).
-
-The registry defaults are 10, 3 and 30, so an untouched board gets a
-**minimum password length of 10 rather than 8** — the one change here
-that can surprise somebody. It applies to new passwords only; existing
-passwords are untouched and nobody is locked out.
-
-> [!NOTE]
-> A minimum username length above the maximum is impossible to satisfy,
-> so the pair is ignored rather than enforced — both fall back to 3 and
-> 30 and the board keeps registering people. Fix the pair on the
-> settings screen.
-
-#### The security screen does something now
-
-The session lifetime, the failed-login count and the lockout duration
-were all stored and never read — the lockout ran on compiled-in
-constants. They are wired now, so a board that changed one of them at
-some point is about to get the behaviour it asked for. Worth a look
-before you deploy if you ever touched that screen.
-
-Two things moved as part of it: the session lifetime now says **14
-days** (which is what the board was actually doing), and
-`security.max_account_login_attempts` is new, defaulting to the 50 the
-code always used. See
-[Spam controls and rate limits § The three login counters](../administration/antispam.md).
-
-### Permissions that were lying, and are not any more
-
-#### "Restore posts" is a real moderator right
-
-Restoring a post or thread was gated on *Delete posts*, so a moderator
-ticked for restore alone could restore nothing, and one ticked for
-delete quietly got the undo too. Restoring now needs *Restore posts*.
-
-Nobody loses an undo they were using: a one-off migration granted
-*Restore posts* to every existing appointment that held *Delete posts*.
-**New appointments get exactly what is ticked** — tick both boxes if you
-mean both. See
-[Forums and permissions § What an appointment grants](../administration/forums.md)
-for the nine grants an appointment carries.
-
-#### Three dead moderator checkboxes are gone
-
-*Delete permanently*, *Manage polls* and *See posters' addresses* granted
-nothing — there is no hard-delete path, no per-forum poll management, and
-the address lookup is staff-only — so the checkboxes are gone and their
-columns dropped. Whatever was ticked in them was already inert; nothing
-observable changes.
-
-#### `canDeleteOwnThreads` is a real permission
-
-It read "delete a whole thread you started" and nothing read it. Granted,
-the thread's author now gets a **Delete thread** button that moves the
-thread to `visibility=deleted` — reversible, exactly as a moderator's
-delete is; restoring stays a moderator right. It is **off by default**
-and nothing changes until you tick it — read
-[letting members delete their own threads](../administration/forums.md)
-first, because a thread is deleted whole and takes other people's replies
-with it.
-
-#### `canDeleteOthersPosts` is gone
-
-It read "hard-delete anyone's post", and the board has never had a hard
-delete: removing somebody else's post has always gone through
-`canSoftDeletePosts`, which is reversible. The cell was a promise the
-board had no way to keep, so migration 0042 drops the column from
-`usergroups` and `forum_permissions`. Whatever was ticked was already
-inert.
-
-One knock-on: the column was one of the permissions that marked a group
-as *carrying power* (barring it from "may be granted by plugins" and
-forcing its members to display as staff). `canEditOthersPosts` and
-`canSoftDeletePosts` still cover that ground, so a group with real
-moderation power is still barred; a group whose *only* power was this
-dead column stops being treated as powerful — which is now the truth
-about it.
-
-#### `maxPostsPerDay` is enforced
-
-"Daily post cap. 0 = unlimited" was stored, resolved and displayed, and
-no write path looked at it — a group set to five posts a day could post
-five thousand. It is spent now, in the write path, against the same
-database counters the hourly limits use: threads and replies together,
-over a UTC day, on the REST API's endpoints as much as the forms.
-
-**Check your groups before deploying this.** `0` still means unlimited
-and is the default, so an untouched board is unaffected — but a board
-that set a number, believing it was doing something, will start
-enforcing a number nobody has looked at in a while. *Bypass flood check*
-does not lift this cap; to exempt a group, set its value to `0`. See
-[the daily post allowance](../administration/groups.md).
-
-#### `maxPrivateMessagesPerDay` is enforced
-
-The same story on its own counter. `0` remains the default and remains
-unlimited; check the number on any group where you set one. Do not
-confuse it with `privateMessageQuota`, which has always worked and caps
-what a member may *keep*, not what they may send in a day.
-
-### Behaviour that changed shape
-
-#### `meith migrate` decides by hash, not by timestamp
-
-A board that upgraded from 0.29.0–0.31.x to 0.32.0, 0.33.0 or 0.33.1
-is missing four migrations, and `meith migrate` on those releases says
-"already up to date" about it. The journal entries for `0059`–`0061`
-carry timestamps later than the migrations after them, and the runner
-took "newer than the newest one applied" as its test: it applied `0060`
-and `0061`, then skipped `0062`–`0065` as already done. A board
-installed fresh on any of those releases is not affected — an empty
-database applies the journal from the top — and neither is one that
-arrived from 0.28 or earlier.
-
-**What it looks like.** The hourly `board.digest_send` task fails on
-every tick with `column u.board_digest_cadence does not exist`; member
-feed tokens, the auto-watch settings and report categories fail the same
-way wherever a request reaches them. The admin notice on those releases
-did not report it — it compared the version the board had recorded, not
-the schema — so nothing said anything until a request hit the missing
-column. From this release the notice asks the database which core
-migrations are unrecorded and counts them, whatever the versions say,
-and the panel's upgrade refuses to record a version while any are
-missing.
-
-**What to do.** Take the release that carries this note and run
-`meith migrate` once — under Compose the `migrate` service does it on
-the redeploy. The runner now applies every migration whose file hash is
-not recorded in `drizzle.__drizzle_migrations`, in journal order, so it
-finds the four and applies them; a board that was never affected finds
-nothing to do. See [Migrations](database-operations.md#migrations) for the
-mechanism.
-
-#### Backup is a verb
-
-The [backup and restore](backups.md) page used to
-be commands you copied; it is now `meith backup` and
-`meith restore` — one bundle carrying the database dump and the
-uploads together, restored only into a new, empty database, with the
-post-restore checks run for you. Nothing changes for a cron built on
-`pg_dump`; the verb is the same dump with the uploads problem solved
-beside it, and CI restores one on every change.
-
-#### The stack's Postgres is 18
-
-The compose files pin `postgres:18-alpine` where they pinned
-`postgres:16-alpine`, and the board image carries the matching client
-tools. A running board does **not** cross a Postgres major by
-redeploying — the old data directory would be silently ignored, not
-upgraded — so follow
-[when a release moves Postgres](upgrading.md) the next
-time you take this release onto an existing board.
-
-#### Links into a post
-
-A post used to be anchored by its id (`#post-90`, under a corner reading
-`#6`); it is anchored by its number now (`#post-6`), and everything the
-board writes links `?post=90` instead — the thread page finds the post
-and redirects to the page holding it, anchored at its number. The board
-rebuilds its own links, so there is nothing to run; the gain is that a
-link to the four-hundredth post of a thread now lands *at the post*
-rather than at the top of page one.
-
-What changes without asking is a link already out in the world: an old
-`#post-90` now names the ninetieth post of that thread if it has one,
-and otherwise lands at the top — either way on the right thread. A theme
-you maintain must anchor posts by number:
-[the post anchor](../extensions/theme-contract.md#the-post-anchor) is the shape.
-
-Two notice parameters moved out of `?post=`'s way at the same time:
-deleting a post now returns to `?removed=post`, and restoring an
-already-visible one to `?unchanged=post`. They are notices on a redirect
-the board issues itself; nothing stores them.
-
-#### A category is a page
-
-A category used to 404 when opened directly — which the breadcrumb on
-every thread invited you to do. `/{id}-{slug}` on a category is now a
-section page: its forums, listed the way the index lists them. Nothing
-to run or configure.
-
-#### A category can be opened to threads
-
-**Allow new threads** on a category now means what it says. It is off on
-every category — the migration that ships with this makes that true for
-existing rows — so **a board that wants nothing to change does
-nothing**. Turn it on from the category's options; turning it off again
-stops new threads and returns the page to its forums (threads already
-posted keep their addresses and stay in search, but the category stops
-listing them).
-
-#### Times are shown in the reader's own zone
-
-The board now formats every timestamp in the zone the reader is actually
-in, detected from the browser and remembered in a cookie; a reader with
-JavaScript off gets UTC, and the footer says so. The migration moves
-every member whose stored timezone is `UTC` onto the new **Automatic**
-setting — before this, "chose UTC" and "never chose" were the same value,
-and leaving them all alone would have meant the change reached nobody
-with an existing account. Members who picked any other zone keep it. A
-member who genuinely wants UTC picks it once, under **UserCP → Options**.
+| Change | Action |
+|---|---|
+| `reputation.comment_required` defaults off | Re-enable to require rating comments and remove one-click Thanks |
+| Navigation defaults to Home, New posts, Search | Re-enable other entries under Content → Navigation; migration hides only untouched rows |
+| `TRUSTED_PROXY_HOPS` defaults to 0 | Set the actual trusted proxy count; the generated by-hand stack defaults to 1 |
+| Mail can be saved in the panel | Explicit HTTP/SMTP environment config still wins; test delivery |
+| Board address can be saved in the panel | `APP_URL` still wins |
+| SMTP driver is implemented | Set sender, relay and security/authentication fields |
+| `TICK_DEADLINE_MS`, `TICK_MAX_JOBS` removed | Remove unused variables |
 
-#### The visitor address is counted from the right
+Defaults affect settings without stored overrides.
 
-The board used to take the **left-most** `X-Forwarded-For` entry — which
-is whatever the caller put there. It now counts back from the right-hand
-end, and `TRUSTED_PROXY_HOPS` says how far. **A board behind one reverse
-proxy — the documented shape — needs nothing**: the default of `1`
-resolves the same address it always did. Behind more than one hop (a CDN
-in front of your proxy), set `TRUSTED_PROXY_HOPS=2` — leave it at `1`
-and every visitor resolves to the CDN, visible immediately as an
-allowlist that admits nobody and a moderator log full of one address.
-See
-[Deploying by hand § Count your proxies](docker-compose.md).
+## Newly enforced settings
 
-#### Four anti-spam limits arrive switched on
+| Setting | Current behaviour |
+|---|---|
+| `posting.edit_grace_seconds` | Default 300; suppresses new edit notices for timely self-edits, not moderator edits or revision history |
+| `search.min_word_length` | Default 2; at least one word must meet it |
+| `search.enabled` | Disables navigation, page and API search; maintains the index |
+| `registration.enabled` | Disables public form and POST; installer/CLI creation remain available |
+| `registration.method` | Enforces none, email, admin or both; default none preserves former behaviour |
+| Password minimum | Default 10 for new passwords; existing passwords remain valid |
+| Username bounds | Default 3–30 code points; invalid min/max pair falls back to these defaults |
+| Session/lockout settings | Enforced; default session 14 days and account-wide attempt limit 50 |
+| `maxPostsPerDay` | Threads and replies share a UTC-day allowance across forms/API |
+| `maxPrivateMessagesPerDay` | Daily sends; separate from stored-message quota |
 
-Everything else on the anti-spam screen ships off; these arrived on,
-because each bounds something a board cannot want unbounded and none is
-reachable by a member doing anything ordinary:
+A former email-activation choice equal to the old default may have no stored row. Configure working mail, then explicitly select email activation if required. Daily caps use zero unlimited; flood bypass does not lift them.
 
-| Setting | Default | Bounds |
-|---|---|---|
-| `antispam.register_ip_per_hour` | 10/hour per /24 | Registrations from one address range |
-| `antispam.reset_per_hour` | 5/hour per address | Reset mails sent to one e-mail address |
-| `antispam.reset_ip_per_hour` | 20/hour per /24 | Reset requests from one caller |
-| `antispam.login_ip_attempts` | 100 per lockout window | Failed logins from one address, whatever accounts they name |
+Registration/reset/address-login limits now default to 10 registrations/hour, 5 resets/email/hour, 20 resets/address-range/hour and 100 login failures/window. Review shared-network impact under [Antispam](../administration/antispam.md).
 
-The one to look at is the first, and only if your members share an
-address — a school, an office, a conference. `0` switches any of them
-off. See
-[the limits on pages nobody has signed in to](../administration/antispam.md).
+## Permissions
 
-#### `meith upgrade` now really applies plugin migrations
+- Restore now requires **Restore posts**. A migration grants it to existing delete-capable appointments; new appointments need both selected when intended.
+- Inert **Delete permanently**, **Manage polls** and **See posters' addresses** moderator fields were removed.
+- `canDeleteOwnThreads` now permits reversible whole-thread deletion, including replies; it defaults off.
+- Migration 0042 removes unused `canDeleteOthersPosts`; actual reversible moderation uses `canSoftDeletePosts`. Groups carrying only the removed field no longer count as powerful.
 
-The command used to pass no plugins at all, so a board could be told by
-the panel to run it and be no further on afterwards. It reads your
-board's plugin list now. If you have been running a plugin whose
-migrations the panel reported as pending, run `meith upgrade` once
-more — re-running is safe, since applying and recording a migration are
-one transaction and a re-run of an applied one is a no-op.
+## `meith migrate` decides by hash, not by timestamp
 
-#### The navigation menu is a list you edit
+Boards upgraded from 0.29.0–0.31.x to 0.32.0, 0.33.0 or 0.33.1 can lack migrations 0062–0065 because earlier journal timestamps were out of order. Fresh installs and upgrades from 0.28 or earlier are unaffected.
 
-The row of links across the top of the board used to be six items
-compiled into the app. They are rows in the database now, and the
-migration seeds exactly those six with their existing addresses,
-ordering and audiences — **an upgraded board's menu looks and behaves
-the way it did**, including Search disappearing when search is off and
-My posts staying away from signed-out visitors.
+Symptoms include missing `u.board_digest_cadence`, feed-token, auto-watch or report-category columns despite an up-to-date version notice. Upgrade to a release with the hash-based runner and run `meith migrate`. It applies missing hashes in journal order. The current panel checks missing migrations where files are available and refuses to record a version over a stale schema.
 
-What is new is that you can change it, under **Admin → Content →
-Navigation**: drag an item to reorder it, drag it to the right to hang it
-under the item above as a sub-menu, rename it, hide it, delete it, or add
-your own — to a chat server, a wiki, anything with an address. Items can
-be limited to an audience or to particular groups, and one marked as
-opening in a new tab does so in every theme that honours it. The screen
-works with JavaScript off: every drag has an arrow button beside it.
+## Data and display
 
-A theme you maintain still compiles unchanged. `LinkModel` gained two
-optional fields, `newTab` and `submenu`. A theme that ignores `submenu`
-renders the top level and drops the entries under it, so a theme meant to
-follow the board navigation should render one level of nested links,
-revealed on both `:hover` and `:focus-within`. See
-[the theme API](../extensions/theme-contract.md#versioning).
+| Change | Action |
+|---|---|
+| Bundled PostgreSQL 16 → 18 | Perform a separate database major upgrade; do not reuse the old volume with the new image |
+| `meith backup` / `restore` | Use bundles with uploads and explicit empty restore targets |
+| Post anchors use number | Themes use `post-<post.number>`; durable links use `?post=<id>`; old ID fragments may land differently |
+| Delete/restore notices | Use `?removed=post` and `?unchanged=post` |
+| Category pages/threads | Categories now render; thread creation remains opt-in |
+| Automatic timezone | Former UTC defaults move to browser detection; members wanting UTC must select it explicitly |
+| Plugin upgrades | `meith upgrade` reads installed plugin definitions and applies their migrations |
+| Editable navigation | Render optional `newTab` and one-level `submenu`; preserve no-JavaScript access |
 
-#### Webhooks moved into the board
+See [Theme compatibility](../extensions/theme-contract.md#versioning) for model changes.
 
-The `@meith/plugin-webhooks` plugin is gone; outbound webhooks are a core
-feature now, with an admin screen at **Admin → Webhooks** and more topics
-than the plugin carried. See [Webhooks](../integrations/webhooks.md). Nothing migrates
-automatically — the plugin stored its configuration in plugin settings, not
-in the board's tables — so recreate the plugin's single delivery as a
-subscription. It is a five-minute job, once:
+## Replace the old webhooks plugin
 
-| The plugin's setting | Recreate it as |
-|---|---|
-| **Endpoint** (`WEBHOOKS_ENDPOINT_URL`) | The subscription's **Endpoint**. Still `https://` only. |
-| **Payload format** (Discord / Plain JSON) | The subscription's **Payload format** — the same two choices, unchanged. |
-| **What to send** (new threads, or threads and replies) | The **Topics** checkboxes: `thread.created`, and `post.created` for replies too. |
-| **Signing secret** (`WEBHOOKS_SIGNING_SECRET`) | Generated for you and shown once when you add the subscription. Put the new secret into your receiver. |
-| **Board address** (`WEBHOOKS_BOARD_URL`) | Not needed — deliveries use the board's own configured address. |
+Core webhooks replace `@meith/plugin-webhooks`; settings are not migrated automatically.
 
-The signature is verified the same way, over the same
-`HMAC-SHA256(secret, "<timestamp>.<body>")` material, but the delivery
-headers are now `x-forum-event`, `x-forum-delivery`, `x-forum-timestamp`
-and `x-forum-signature` (the plugin sent `x-meith-*`). Update your
-receiver's header names when you move the secret across. After the
-subscription is delivering, remove the plugin from your board's plugin list
-and drop its `WEBHOOKS_*` environment variables.
+1. Create a subscription under **Admin → Webhooks** with the old endpoint and payload format.
+2. Select `thread.created` and, if needed, `post.created`.
+3. Save the new signing secret in the receiver.
+4. Change receiver headers from `x-meith-*` to `x-forum-event`, `x-forum-delivery`, `x-forum-timestamp` and `x-forum-signature`.
+5. Verify delivery, then remove the old plugin and `WEBHOOKS_*` variables.
 
-One Discord difference to expect: the plugin posted a rich embed (a titled
-card) for a new thread, while core posts a plain `content` link. The message
-still links straight to the thread; it is not boxed in an embed.
+HMAC material remains `<timestamp>.<raw body>`. Core uses the configured board origin and sends Discord content links rather than the old rich embed. See [Webhooks](../integrations/webhooks.md).
diff --git a/docs/operations/upgrading.md b/docs/operations/upgrading.md
index 924491059..2a66d9cad 100644
--- a/docs/operations/upgrading.md
+++ b/docs/operations/upgrading.md
@@ -1,59 +1,42 @@
-# Upgrade Meith
+# Upgrade a board
 
-Update one board to a new release while keeping its packages, schema and plugins in step. You need the board repository or deployment controls, the release notes and a verified backup.
+## Prepare
 
-## 1. Check compatibility and back up
-
-Read the release notes and [upgrade compatibility notes](upgrade-notes.md). Check installed plugin and theme compatibility. Take a fresh backup including uploads, and retain the original deployment environment.
+Read release notes and [compatibility notes](upgrade-notes.md), check extension compatibility and take a verified backup including uploads and secrets.
 
 > [!CAUTION]
-> Migrations are forward-only. Downgrading code against a migrated schema is not rollback. Recovery requires restoring a known-good backup into a suitable destination.
+> Migrations are forward-only. Downgrading code does not roll back the schema. Recovery requires restoring a known-good backup.
 
-The upgrade planner permits a jump of at most two major versions and refuses downgrades. If further behind, upgrade through supported intermediate releases, backing up and checking each stage. Use real published release versions; do not invent intermediate tags.
+The planner rejects downgrades and jumps over more than two major versions. Use published intermediate releases where required.
 
-## 2. Update the board's source
+## Update source
 
-In a generated board repository:
+In the generated board directory:
 
 ```sh
 npx create-meith@latest update
 npm install
 ```
 
-The updater moves the Meith package pins and matching Next.js version together and refreshes scaffold-owned deployment files. Read its output for files it leaves unchanged because you customized them. Review the diff and lockfile before committing.
-
-Do not independently bump only `@meith/web` or `next`. The board and framework versions must match. The generated update workflow can propose the same change in a PR; review it before merging.
-
-## 3. Build and deploy
+The updater changes Meith pins and the matching Next.js version together and refreshes scaffold-owned files. Review customized files it skips and commit the source and lockfile. Do not independently bump only `@meith/web` or `next`.
 
-| Deployment | Action |
-|---|---|
-| Coolify, source build | Push the reviewed changes and redeploy the resource |
-| Coolify, prebuilt image | Wait for the image build, select the intended image and redeploy |
-| Docker Compose | Build or pull the selected image, then recreate services using the board's deployment files |
-| Vercel | Deploy the reviewed board source with its intended database environment |
+## Deploy and migrate
 
-Core migrations run before the new web service is made available: the Compose migration service or the configured build/deploy command performs them. A preview must not accidentally migrate production.
+Push and redeploy through the chosen host. For prebuilt images, wait for the build and select its intended tag. Core migrations must finish before web serves; previews must not accidentally migrate production.
 
-Use a direct database connection for migrations when the runtime connection uses a transaction-mode pooler. The core migration lock does not serialize the later plugin migration phase; run one upgrade at a time.
-
-## 4. Apply plugin migrations and record the version
-
-Run the installed version of the CLI against the upgraded board:
+Use a direct migration connection. Run one upgrade at a time because the core lock does not cover plugin migrations. Through the [deployed CLI](operator-cli.md):
 
 ```sh
 meith upgrade --dry-run
 meith upgrade
 ```
 
-Use [Operator commands](operator-cli.md) for the container or board-checkout invocation. The upgrade applies missing core migrations, then enabled plugin migrations, then records plugin and core versions. `meith migrate` alone does not apply plugin migrations.
-
-**Admin → System → Version & migrations** can apply plugin migrations after the deployment has applied core migrations. It will not replace the core deployment step.
+This applies missing core and enabled-plugin migrations, then records versions. `meith migrate` alone is core-only. The admin system page can apply plugin migrations after core migration completes. Applied migrations are transactional and resumable; fix forward instead of editing an applied migration.
 
-Applied plugin migrations are recorded transactionally and can be resumed after interruption. Do not edit a migration that has already run; fix forward with a new one.
+## PostgreSQL major versions
 
-## 5. Verify and reopen
+Do not point a new PostgreSQL major at an old data volume. Restore a dump into a separate database using the new major and matching client tools, verify it, then switch the board connection. Keep the old volume and backup until verified.
 
-Check the displayed version, pending migrations, public pages, sign-in, writing, private-forum access, attachments, email and scheduled work. Review logs before reopening a board held for maintenance.
+## Verify
 
-If verification fails, preserve logs and the backup. Use the recorded recovery plan rather than switching the application to an older version over the changed database.
+Check version, pending migrations, sign-in, posting, private forums, attachments, mail, scheduled work and logs before reopening. If checks fail, use the restore plan rather than older code against the changed schema.
diff --git a/docs/operations/vercel-configuration.md b/docs/operations/vercel-configuration.md
index 173de0a46..96e808439 100644
--- a/docs/operations/vercel-configuration.md
+++ b/docs/operations/vercel-configuration.md
@@ -1,49 +1,29 @@
-# Vercel configuration and limits
+# Vercel configuration
 
-Use this reference alongside [Deploy on Vercel](vercel.md). The board requires managed database, cache, upload and mail services because functions do not provide a persistent local server.
+Use with [Vercel deployment](vercel.md).
 
-## Required service configuration
+## Services
 
-| Service | What to verify |
+| Service | Configuration |
 |---|---|
-| PostgreSQL | Runtime pooled URL plus direct migration/backup URL |
-| Redis-compatible cache | Shared access from every function instance |
-| Upload storage | Blob or an S3-compatible store with the intended visibility |
-| Mail | Verified sender and valid provider credentials |
-| Scheduler | Authenticated tick at a cadence suitable for the board |
+| PostgreSQL | Pooled runtime URL and direct migration/backup URL |
+| Redis | Shared cache reachable from every function |
+| Uploads | Blob or S3-compatible storage |
+| Mail | Provider credentials and verified sender |
+| Scheduler | Authenticated `/api/system/tick` calls |
 
-Meith derives supported configuration from connected-service environment variables when explicit settings are absent. Check `packages/core/src/env.ts` and the generated template's `.env.example` for the exact supported aliases. Explicit environment values take precedence; stale overrides can hide a correct connected-service value.
+Explicit environment values override connected-service aliases. `DATABASE_URL_UNPOOLED` and `POSTGRES_URL_NON_POOLING` can supply the direct database URL; `KV_URL` and `UPSTASH_REDIS_URL` can supply Redis. Use the template's `.env.example` and `meith env:check`; the full schema is `packages/core/src/env.ts`.
 
-`DATABASE_URL_UNPOOLED` and `POSTGRES_URL_NON_POOLING` can supply a direct database URL. `KV_URL` and `UPSTASH_REDIS_URL` are recognized cache sources. Blob configuration can use the linked store identity or supported token credentials. Do not invent a fallback credential when environment resolution fails; inspect the named missing value.
+## Build and scheduling
 
-## Build-time migrations
+The build runs `meith migrate` before `forum-web build --at-root`. Both preview and production builds migrate their configured database. Use the direct URL for migration locking. Keep customizations in board configuration, themes and plugins, outside generated framework directories.
 
-The template build command runs `meith migrate` before `forum-web build --at-root`. It materializes the framework at the project root for the hosting builder.
+The template schedules a daily tick. For more frequent work, check [Vercel cron limits](https://vercel.com/docs/cron-jobs/usage-and-pricing) or use an external scheduler. The tick route declares `maxDuration = 300`; check the project's [function limits](https://vercel.com/docs/functions/limitations). Verify completed work under **Admin → System**.
 
-Both production and preview builds run the migration command against the database provided to that build. Use separate preview databases when previews must not alter production. Runtime functions use the pooled connection; migrations need the direct connection for their session-level lock.
+## Uploads and recovery
 
-Do not add application customizations inside generated framework directories. Use themes and plugins registered in the board's own configuration.
+Platform request limits apply to the entire multipart request before Meith's attachment limit. Uploads and downloads also consume function memory. Test realistic sizes and private-forum downloads through the board. Verify the store's access policy separately.
 
-## Scheduler and function limits
+Run imports, backups and restores externally with database tools, staging disk and service credentials. Local Blob access needs supported token credentials; deployment identity is not available on an operator's laptop. See [Backups](backups.md) and [Migration off Vercel](leaving-vercel.md).
 
-The generated cron runs daily. More frequent work requires a scheduler plan or external caller that supports the desired cadence. Read the provider's current [cron limits](https://vercel.com/docs/cron-jobs/usage-and-pricing) rather than assuming every account accepts every expression.
-
-The tick route declares `maxDuration = 300`. Check the platform's current [function limits](https://vercel.com/docs/functions/limitations) and project settings before deployment. A declared duration is a ceiling, not evidence that a tick always finishes within it.
-
-A sparse tick delays queued work. Use [Scheduled tasks](scheduled-tasks.md) to verify completion and inspect failures.
-
-## Upload and storage limits
-
-Platform request/response limits apply before Meith's configured attachment allowance. Account for the entire multipart request, not just one file. Upload and download processing also use function memory.
-
-Verify bucket/store access policy. File credentials alone do not determine whether objects are public. Test private-forum attachments through the board rather than assuming a direct storage URL has the same authorization rules.
-
-## Backups, imports and operator commands
-
-Run long-lived backup, restore and import commands from an external machine or suitable job environment with access to the managed services. Keep local staging space and the required database tools available. They are not tasks to start inside an ordinary web function.
-
-Set the correct hosted-service environment in a board checkout before running its CLI. Use [Backups](backups.md), [Import a forum](migrating.md) or [Move away from Vercel](leaving-vercel.md) for the procedure.
-
-## Costs and verification
-
-Budget separately for functions, database, cache, uploads, mail and scheduling, using current provider plans. Before inviting members, verify realistic uploads, mail, scheduler latency and recovery. Local tests of a driver are not a live deployment test.
+Budget for each connected service and scheduler. Provider limits and prices can change.
diff --git a/docs/operations/vercel.md b/docs/operations/vercel.md
index ce8db53bb..7ad9f72cc 100644
--- a/docs/operations/vercel.md
+++ b/docs/operations/vercel.md
@@ -1,42 +1,13 @@
 # Deploy on Vercel
 
-Deploy the board web application on Vercel with managed PostgreSQL, Redis, upload storage and mail. Read [Vercel configuration and limits](vercel-configuration.md) before choosing this route, especially its upload and scheduling constraints.
+The [Vercel template](https://github.com/meith-dev/vercel-template) uses Neon PostgreSQL, Upstash Redis, Vercel Blob and Resend. Read [Configuration and limits](vercel-configuration.md) first.
 
-## 1. Create the deployment
+1. Use the template's Deploy button to create a repository and connect services.
+2. Generate two independent values with `openssl rand -hex 32`; set `AUTH_SECRET` and `CRON_SECRET`. Save a protected recovery copy.
+3. Check production and preview database URLs. The build runs migrations; previews must use separate databases if they must not change production.
+4. Deploy, open `/install`, unlock with `AUTH_SECRET` and create the administrator. Confirm the permanent public URL and test mail.
+5. Configure [scheduled tasks](scheduled-tasks.md). The template's daily cron delays work; use a plan-supported cadence or an external authenticated caller for more frequent ticks.
+6. Test registration, reset mail, posting, realistic uploads and private-forum access.
+7. Run [backups](backups.md) from an external machine; ordinary functions cannot run the local backup process.
 
-Open the Deploy button in the [Meith Vercel template](https://github.com/meith-dev/vercel-template). Create the board repository in your account and connect the services requested by the template.
-
-The standard template uses Neon PostgreSQL, Upstash Redis, Vercel Blob and Resend. Keep access to each service account and understand which one stores the community's data.
-
-## 2. Set independent secrets
-
-Generate two different values:
-
-```sh
-openssl rand -hex 32
-openssl rand -hex 32
-```
-
-Use them for `AUTH_SECRET` and `CRON_SECRET`. Meith requires at least 32 characters for these secrets. Store a protected recovery copy outside the deployment.
-
-Confirm that production and preview environments point to the databases you intend. The template build runs core migrations before building; a preview connected to production can therefore migrate the production schema.
-
-## 3. Deploy and install
-
-Deploy, then open `https://your-deployment/install`. Unlock the installer with `AUTH_SECRET`, review the public URL and mail configuration, and create the administrator account.
-
-The linked services provide environment values from which Meith resolves drivers and credentials. Use the [configuration reference](vercel-configuration.md) if a required value is missing. Do not copy a temporary preview origin into the permanent board URL.
-
-## 4. Arrange scheduled work
-
-The generated template contains a daily cron schedule. A daily tick can leave notifications and queued work delayed; an active community usually needs more frequent execution.
-
-Choose a scheduler cadence supported by your hosting plan, or use an external scheduler to call the authenticated tick endpoint. Follow [Scheduled tasks](scheduled-tasks.md) and verify actual task progress under **Admin → System**. Merely having a cron entry is not proof that tasks are running.
-
-## 5. Verify before inviting members
-
-Check registration and password-reset delivery, posting, attachment upload/download and ordinary-member visibility. Test with realistic attachment sizes; a board setting cannot override the hosting platform's request limits.
-
-Arrange backups from a suitable external machine; serverless functions do not run the board's local backup process. Follow [Backups](backups.md) and retain both database and upload recovery material.
-
-Complete [Set up your community](../administration/first-steps.md). For maintenance commands, run the CLI from a board checkout with the correct hosted-service environment. For moving to a server later, use [Move away from Vercel](leaving-vercel.md).
+Complete [Community setup](../administration/first-steps.md). Run maintenance commands from a board checkout with the hosted-service environment. See [Move away from Vercel](leaving-vercel.md) for export and restore.
diff --git a/docs/operations/web-push.md b/docs/operations/web-push.md
index fe8ef1da8..a74e8d14f 100644
--- a/docs/operations/web-push.md
+++ b/docs/operations/web-push.md
@@ -1,173 +1,48 @@
-# Enable browser notifications
-
-Enable web push for members who choose browser notifications. Configure the board first; each member must then opt in on their device.
-
-## Web push
-
-A pushed notification reaches a member who does not have the board open —
-the operating system's own notification, raised on a phone or laptop
-doing something else. The same machinery makes the board installable: a
-board that can push and sit on a home screen is treated as an
-application by the browsers, and on iOS it must be installed before it
-may push at all. Push is off until an operator turns it on, and then off
-for every member until they turn it on themselves, per browser. There is
-no way to be pushed at by accident.
-
-### What it costs a member's privacy
-
-A push travels from the board to **a push service run by the browser's
-maker** — Google for Chrome, Mozilla for Firefox, Apple for Safari — and
-from there to the device; there is no version of the standard where a
-board reaches a sleeping phone by itself. The push service learns that
-this board sent something to this endpoint, and when — nothing about
-what it said (the payload is encrypted end to end,
-[RFC 8291](https://www.rfc-editor.org/rfc/rfc8291), to a key only the
-browser holds) and nothing about who the member is (an endpoint is an
-opaque URL the browser minted). The board tells each member this on the
-preferences screen before they subscribe; repeat it in your privacy
-policy if your members would want it there.
-
-### Turning it on
-
-1. **Generate a VAPID key pair**
-   ([RFC 8292](https://www.rfc-editor.org/rfc/rfc8292)) — the public
-   half every browser stores when it subscribes, the private half signs
-   every send:
-
-   ```sh
-   docker compose run --rm web meith push:keys           # prints a pair to paste in
-   docker compose run --rm web meith push:keys --save    # generates and stores it
-   ```
-
-   > [!WARNING]
-   > Replacing a key pair that is already in use kills every stored
-   > subscription: the browsers hold the old public key and the push
-   > services will refuse the new signature. Each member's browser
-   > resubscribes on its next visit to the preferences screen, and until
-   > then they are pushed nothing. Generate once.
-
-2. **Fill in the settings** at `/admin/settings?group=push`:
-
-   | Setting | What it does |
-   |---|---|
-   | **Offer web push** | Off by default. On, members get a subscribe button on `/notifications/preferences` and a push column beside the e-mail one. |
-   | **VAPID public key** | The half every browser stores. |
-   | **VAPID private key** | The half that signs. Stored on the board, like the SMTP password. |
-   | **Contact for the push service** | A `mailto:` or `https:` address a push service can use to reach you. Left empty, the board sends the mail-from address, and failing that its own https address. With none of the three, push stays off, and the settings screen says so. |
-
-3. **Serve the board over HTTPS.** A service worker will not register
-   over plain HTTP, and without one there is no push and no install.
-   `localhost` is exempt, which is why development works without a
-   certificate.
-
-### What a member does
-
-On `/notifications/preferences`, a member subscribes the browser they
-are holding, ticks a push box per notification kind (independent of the
-e-mail box beside it), and can remove the subscription again. Every
-browser is subscribed separately — the subscription belongs to the
-browser, the per-kind preferences to the account. The subscribe button
-is the one part of the board that needs JavaScript to be useful, because
-a page cannot ask a browser for a push subscription in a form post;
-everything else on the screen is an ordinary no-JS form.
-
-On iPhone and iPad, Safari pushes only to a board that has been **added
-to the home screen**. Until then the subscribe button is refused by the
-browser; the board reports the refusal rather than pretending it worked,
-though Safari does not say the home-screen rule was the reason.
-
-### How a push is sent
-
-The path is the one notification mail already takes, with a second
-handler at the end: `raise()` writes the notification, an outbox row is
-written only when somebody wants the mail or the push, and the tick
-relays it to the `notifications.email` and `notifications.push` queue
-jobs — separate jobs, so a push service being down does not hold up the
-mail. A coalesced notification pushes nothing, on the same rule as mail;
-`push_sent_at` guards against a double send, exactly as `email_sent_at`
-does. Failures retry through the queue, and a push service answering
-`404` or `410` means the browser is gone for good — that subscription is
-pruned. The payload carries the notification's rendered subject and
-body in the member's own language, its id, the link it points at, and
-the member's unread count for the app badge — capped well under the 4 KB
-a push service will carry.
-
-One member's devices are pushed a few at a time rather than strictly one
-after another, so a single slow or hostile push service cannot hold up
-the rest of the batch; each request still carries the deadline, response
-cap and abort described under [the outbound address
-policy](mail.md#private-relays-and-outbound-requests). A member may register up to twenty
-push subscriptions; a browser re-subscribing an endpoint it already holds
-replaces that one rather than counting against the cap, but a twenty-first
-distinct browser is refused until one is removed.
-
-### The service worker and the manifest
-
-`public/sw.js` shows a notification when one is pushed and opens or
-focuses the right page when one is clicked, exactly as before. A click
-deep-links to the notification's own target and falls back to
-`/notifications`; off-origin links are refused.
-
-Its only other job is a navigation fallback for an installed board that
-opens with no connection. The `fetch` handler intercepts top-level navigation
-requests alone (`request.mode === 'navigate'` and `request.destination === 'document'`)
-and always tries the
-network first; it only steps in when that request fails outright,
-serving a precached, static `/offline` page instead of the browser's own
-error screen. Nothing else is cached or intercepted — the board's actual
-pages, its API responses, and its assets all still go straight to the
-network on every request. That restraint is deliberate: a cached page
-served to a signed-in member is a page with somebody else's name in the
-header, so the fallback carries no session state at all — the board's
-name, a short "you're offline" message, and a link that retries once the
-connection is back. `/offline` has no data dependency of its own for the
-same reason: it is a static route, styled with its own inlined copy of
-the default design tokens rather than the board's stylesheet, so it
-renders correctly with nothing else in cache.
-
-The offline page is precached once, at `install`, into a cache keyed by
-a version baked into `sw.js` (`meith-offline-v1`); `activate` deletes any
-differently-versioned copy left over from a previous deploy. A deploy
-that changes `sw.js` — bumping that version or not — always refetches
-`/offline` fresh at install time, so the cached fallback never drifts far
-from what a deploy last shipped. Every step here is wrapped so a failure
-falls back to a plain network request rather than breaking navigation:
-a service worker that throws on `fetch` can brick every reader until it
-updates, which is the one failure mode worth designing around.
-
-Two limitations follow from keeping this minimal. First, `/offline` is
-English-only by design — it has no data dependency of its own, and
-reading the viewer's locale is exactly the kind of dependency it avoids,
-so a non-English board still shows an English offline screen. Second,
-the `install`-time precache does not retry: if the very deploy that
-changes `sw.js` also happens to fail the fetch for `/offline` (a flaky
-network at that moment, not the reader being offline — the deploy itself
-needed a network to have reached the browser at all), that install
-proceeds with no cached fallback until the next deploy tries again. Until
-then, a reader who goes offline sees the browser's own error page rather
-than this one — the pre-existing behaviour, not a new failure.
-
-`/manifest.webmanifest` is generated per request from the board's own
-settings, so the installed application carries the board's name,
-description and theme colour and follows them when they change. It is
-served whether or not push is on.
-
-### When push does not work
-
-| What you see | What it is |
+# Web push
+
+## Configure
+
+Serve over HTTPS (localhost is allowed for development). Generate keys once:
+
+```sh
+docker compose run --rm web meith push:keys --save
+```
+
+Without `--save`, the command prints a pair for manual entry. At `/admin/settings?group=push`, enable **Offer web push** and verify the VAPID keys and contact address.
+
+The contact must be `mailto:` or `https:`. If unset, Meith tries the mail sender, then the board HTTPS address. Without a usable contact or key pair, push remains unavailable.
+
+> [!WARNING]
+> Replacing VAPID keys invalidates existing browser subscriptions. Members must resubscribe; the preferences page attempts this on their next visit.
+
+## Subscribe
+
+Members open `/notifications/preferences`, subscribe each browser and choose notification kinds independently of email. Browser registration requires JavaScript; the other preference forms do not. Up to 20 subscriptions are allowed per member.
+
+On iPhone/iPad, install the board on the home screen before subscribing. See [WebKit's web-push requirements](https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/).
+
+Push passes through the browser vendor's service. Payloads are encrypted under [RFC 8291](https://www.rfc-editor.org/rfc/rfc8291); the service still observes endpoint and delivery timing.
+
+## Delivery
+
+Scheduled outbox work creates separate email and push jobs. Coalesced events do not send again. Failed sends retry; HTTP 404/410 removes expired subscriptions. Payloads contain localized text, notification ID, same-origin target and unread count.
+
+Production outbound restrictions apply; `PUSH_ALLOW_PRIVATE_HOSTS` is only for an intended private endpoint. Check [Scheduled tasks](scheduled-tasks.md).
+
+## Service worker
+
+`public/sw.js` displays pushes and opens/focuses their same-origin target, falling back to `/notifications`. It intercepts only top-level document navigation, tries the network first and serves precached `/offline` after a network failure. It does not cache member pages, APIs or assets.
+
+The offline page is static English. A failed install-time precache leaves the browser's normal offline error until a subsequent worker installation. `/manifest.webmanifest` uses board settings and is available independently of push.
+
+## Troubleshoot
+
+| Symptom | Check |
 |---|---|
-| No subscribe button at all | **Offer web push** is off, or the keys or the contact are missing. With push on and something missing, `/admin/settings?group=push` says which. |
-| The button appears and the browser refuses | Notifications are blocked in the browser's own site settings — or, on iOS, the board is not on the home screen yet. |
-| Subscribed, and nothing arrives | Check the worker is running: push goes out on the **tick**, like notification mail. `meith task:list` shows when the outbox last relayed. |
-| It worked and then stopped, on one device | The push service dropped the endpoint and the board pruned it. The member resubscribes from the preferences screen. |
-| It worked and then stopped, for everybody | The VAPID key pair changed. See the warning above. |
-| Nothing on iOS, everything elsewhere | Safari pushes only to an installed board. |
-
-What is stored: `push_subscriptions` holds one row per subscribed
-browser — the endpoint, the browser's two keys, the member, and when it
-was last successfully pushed to — deleted with the member, deleted when
-the push service says the endpoint is gone, and moved to the surviving
-account on a merge. `notification_preferences` gains a nullable `push`
-column beside `email` (null means the registry's default for that kind),
-and `notifications` gains `push_sent_at`. Nothing here is readable by
-anybody but the board.
+| No subscribe button | Push setting, keys and contact |
+| Browser refuses | Site permission; home-screen installation on iOS |
+| Subscribed but no delivery | Member kind preferences, outbox and tick |
+| One device stops | Expired endpoint; resubscribe |
+| All devices stop | VAPID key change or shared delivery failure |
+
+Subscription records are removed with the account or expired endpoint and transferred during account merge.
diff --git a/docs/operations/web-security.md b/docs/operations/web-security.md
index 369df13c8..bc5da7a2c 100644
--- a/docs/operations/web-security.md
+++ b/docs/operations/web-security.md
@@ -1,59 +1,27 @@
-# Cookies and security headers
+# Cookies and browser security
 
-Understand the cookies and browser security policy served by Meith. Use this reference when diagnosing proxy or integration behavior; retain the protections when customizing a deployment.
+## Authentication cookies
 
-## Cookies and security headers
+All cookies below are first-party and `HttpOnly`, with `Secure` on HTTPS. Root-path cookies use `__Host-` names on HTTPS and unprefixed names in HTTP development. Admin cookies keep their unprefixed names because they are scoped to `/admin`.
 
-What the board puts in a visitor's browser, and what it tells the
-browser to refuse — the section to read when somebody asks what you
-store about them, when a cookie banner is being drafted, or when
-something on the board is being blocked and you need to know by what.
-None of it is configurable from the admin panel; the one thing that
-changes it is an environment variable, named below.
+| Base name | Purpose | SameSite | Lifetime |
+|---|---|---|---|
+| `fs_session` | Board session | Lax | Session expiry/sign-out |
+| `fs_remember` | Persistent sign-in | Lax | Remember period |
+| `fs_guest` | Anonymous presence | Lax | 1 day |
+| `fs_admin` | Panel session; `/admin` path | Strict | Panel session |
+| `fs_admin_2fa` | Pending panel proof; `/admin` path | Strict | 10 minutes |
+| `fs_2fa` | Pending board proof | Strict | 10 minutes |
+| `fs_sso` | Provider handshake | Lax | 10 minutes |
+| `fs_passkey` | Passkey handshake | Strict | 10 minutes |
 
-### The cookies
+`fs_guest` contains an opaque presence identifier, not an authenticated identity. These are authentication/presence cookies, not an exhaustive list of appearance, timezone or dismissal preferences. The stock board does not add advertising or analytics cookies.
 
-**The board sets no third-party cookies, runs no analytics, and stores
-nothing for advertising.** Every cookie below is first-party, set by the
-board itself, and there to make a specific thing work.
+## Content Security Policy
 
-| Cookie | What it is for | Lifetime |
-| --- | --- | --- |
-| `fs_session` | The signed-in session | Until it expires or you sign out |
-| `fs_remember` | *Remember me* on the sign-in form | The remember period |
-| `fs_guest` | Counts one reader once, for "who's online" | 1 day |
-| `fs_admin` | Admin-panel re-authentication | The admin session |
-| `fs_admin_2fa` | An admin sign-in that has given a password and owes a second factor | Short |
-| `fs_2fa` | A sign-in that has given a password and owes a second factor | Short |
-| `fs_sso` | The single sign-on handshake | 10 minutes |
-| `fs_passkey` | The passkey exchange | Short |
+Production pages use a fresh request nonce:
 
-Every one is **`HttpOnly`** — script cannot read any of them — and every
-one is **`Secure`** wherever the board is served over HTTPS, where they
-also carry the **`__Host-` prefix** (`__Host-fs_session` and so on),
-binding each cookie to the exact origin that set it. `SameSite` differs
-by purpose: **`Lax`** for the session, remember, guest and SSO cookies —
-the SSO one has to be, because an identity provider returns the member
-with a top-level navigation from another site, which a `Strict` cookie
-is not sent on — and **`Strict`** for the admin, second-factor and
-passkey cookies, whose exchanges never start on another site. The admin
-cookie is also scoped to `/admin`, so it is not sent with ordinary board
-requests at all.
-
-`fs_guest` is the only cookie a visitor gets without signing in, and it
-exists for one figure: "37 guests reading". It is **an opaque random
-value and nothing else** — no code path turns it into an identity, and
-the session lookup refuses a row with no user behind it. Whether it
-needs consent where you operate is a question for you, but "strictly
-necessary" is an argument you can actually make about it, which is not
-true of an analytics cookie.
-
-### The Content Security Policy
-
-Every page is served under a **nonce-based policy**, generated fresh per
-request:
-
-```
+```text
 default-src 'self';
 img-src 'self' data:;
 style-src 'self' 'unsafe-inline';
@@ -63,36 +31,20 @@ frame-ancestors 'self'; object-src 'none';
 base-uri 'self'; form-action 'self'
 ```
 
-In practice: an injected `<script>` does not run — it has no nonce, and
-`'strict-dynamic'` trusts only what the board's own nonced scripts load;
-nothing loads from another origin — no CDN, no font host, no embedded
-widget, and a theme or plugin that reaches for one is blocked, with the
-browser console saying so; a form on your board cannot be made to post
-somewhere else; and the board cannot be framed by another site.
-
-**One environment variable changes it.** `REMOTE_IMAGES=1` adds `https:`
-to `img-src`, which is what lets members hotlink images from elsewhere.
-It is off by default: allowing remote images means every post can make a
-reader's browser fetch from a third party, which leaks the reader's IP
-address to whoever hosts it.
+`REMOTE_IMAGES=1` adds `https:` to image sources. Remote hosts then receive readers' image requests and IP addresses. External scripts, widgets and off-origin form redirect chains remain restricted.
 
-The e2e suite asserts that every page carries the policy **and that
-nothing on the page is refused under it**, so a change that would have
-needed `unsafe-inline` fails before it ships.
+## Other headers
 
-### The other headers
+| Header | Value |
+|---|---|
+| `X-Content-Type-Options` | `nosniff` |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` |
+| `Strict-Transport-Security` | `max-age=63072000` |
+| `X-Frame-Options` | `SAMEORIGIN` |
+| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` |
 
-Sent on every response:
+Preserve these through the reverse proxy. See [Compose deployment](docker-compose.md).
 
-| Header | Value | What it stops |
-| --- | --- | --- |
-| `X-Content-Type-Options` | `nosniff` | A browser guessing a type and running an upload as script |
-| `Referrer-Policy` | `strict-origin-when-cross-origin` | A full path leaking to another site |
-| `Strict-Transport-Security` | `max-age=63072000` | A downgrade to HTTP for two years |
-| `X-Frame-Options` | `SAMEORIGIN` | Framing, for browsers older than `frame-ancestors` |
-| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` | Anything asking for hardware the board never uses |
+## Trusted proxies
 
-If you terminate TLS at a reverse proxy, it has to pass these through
-rather than replace them — see
-[Docker Compose](docker-compose.md) for
-the CSP note on proxying.
+`TRUSTED_PROXY_HOPS` defaults to 0. Set the actual trusted proxy count when the deployment supplies forwarded addresses. Meith counts from the right of `X-Forwarded-For`; incorrect trust changes rate-limit, allowlist and audit identities. Do not expose a direct route around the trusted proxy.
diff --git a/docs/reference/api.md b/docs/reference/api.md
index 619c71daa..a57e7668b 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -1,61 +1,26 @@
 # REST API v1
 
-<!--
-  GENERATED FILE — do not edit.
-
-  Written by scripts/api-docs.mts from the OpenAPI document the board serves,
-  which is itself generated from packages/api/src/{routes,schema,tokens}.ts. Run
-  `pnpm api:docs` after changing any of them; `pnpm verify` and CI run
-  `pnpm api:docs:check` and fail when this file, docs/reference/openapi.json and the code
-  disagree.
--->
+<!-- GENERATED FILE — do not edit. Run pnpm api:docs. -->
 
 21 endpoints, 13 scopes. Base path: `/api/v1`.
 
-The machine-readable form of everything below — request and response schemas,
-parameters, status codes, scopes and rate-limit costs — is the OpenAPI 3 document
-at [`docs/reference/openapi.json`](openapi.json), which a board also serves live at
-`/api/v1/openapi.json`. Point a generator at that rather than reading this table
-into code.
+Request/response schemas are in [`docs/reference/openapi.json`](openapi.json), also served at `/api/v1/openapi.json`.
 
 ## Authentication
 
-A bearer token in the `Authorization` header:
+Send a bearer token in the `Authorization` header:
 
-```
+```text
 Authorization: Bearer forum_pat_<lookup>_<secret>
 ```
 
-A token is a **restriction on an actor, never a grant to one**. Every request
-resolves the owner’s permissions and asks the Authorizer, exactly as a page does,
-*in addition to* checking the token’s scope. A token can therefore never reach
-anything its owner could not; revoking the owner’s access revokes the token’s in
-the same instant, because nothing is baked in at creation.
-
-Every authentication failure is one `401` with one message. The reason — expired,
-revoked, unknown, malformed — is in the board’s logs and not in the response:
-telling a caller "expired" confirms the token was real.
+Each request checks the token scope and the owner’s current permissions. Tokens cannot grant access their owner lacks. Invalid, expired and revoked tokens return the same `401`; diagnostic details stay in server logs.
 
 ## Reading without a token
 
-7 of the 21 endpoints answer an unauthenticated request. They are all reads,
-and they resolve as **the board’s guest** — the same actor a logged-out browser
-gets — through the same Authorizer and the same visibility filter as every other
-request. A forum a guest may not see is not in `GET /forums` for them, its threads
-404, and its posts never appear in search. A board whose forums are all closed to
-guests therefore has no anonymous API surface at all, without anything having to
-be configured for that to be true.
-
-An offline board answers `503` to an anonymous caller, exactly as it serves the
-offline page to a browser, and answers normally to a token whose owner may see a
-board that is offline.
-
-Sending a token to one of these endpoints is not the same as sending none: the
-token’s scope is still required, because a token only ever narrows what its
-owner could do. A token without `forums:read` gets `missing_scope` from
-`GET /forums` even though a stranger with no token at all gets an answer.
+7 endpoints support guest reads. Guest permissions and content visibility apply. All writes require authentication.
 
-Nothing writable is anonymous. Every write is `401` without a token.
+An offline board returns `503` unless the authenticated owner may view it. Supplying a token requires the endpoint scope even when the endpoint supports guest access.
 
 | Method | Path |
 |---|---|
@@ -83,51 +48,21 @@ Nothing writable is anonymous. Every write is `401` without a token.
 - `subscriptions:write`
 - `search:read`
 
-Every scope on that list is required by at least one endpoint below, and a test
-holds it that way: a scope no route consumes is a checkbox that grants nothing,
-which reads as a permission and is not one.
-
-There is deliberately no administrative scope at all. A token is a long-lived
-string in somebody’s CI configuration; reconfiguring a board should need a person
-at a keyboard with the admin panel’s re-authentication in front of them. For the
-same reason there is no moderation scope: removing somebody else’s post through
-the API is `posts:write` resolving to a moderator’s own permissions, not a
-separate grant a token can carry on its own.
-
-A token stored before a scope was retired keeps working. The scope is dropped as
-the token is read, so it simply no longer carries it — the endpoints it still has
-a scope for answer as before, and the rest answer `missing_scope`.
+There are no separate administration or moderation scopes. A content write still requires the owner’s applicable permissions. Retired scopes are removed when a stored token is read; remaining scopes continue to work.
 
 ## Issuing a token
 
-Tokens are issued from **API tokens** in the control panel. Issuing one is treated
-as a destructive operation: it asks for the administrator’s password again, on the
-same clock as banning a member or moving a forum, because a bearer string that
-leaves the building is at least as consequential. Revoking one does
-not ask — a revocation is the thing you want to be quick during an incident, and
-it is undone by issuing a new token rather than by recovering the old one.
-
-**Expires in (days)** takes a whole number of days, or nothing at all for a token
-that never expires. Anything else — a fraction, a word, a number in exponent
-notation — is refused and mints nothing, rather than being read as "never".
+Open **Admin → API tokens** and reauthenticate to issue a token. **Expires in (days)** accepts whole days or a blank value for no expiry. Revocation does not require reauthentication; revoked tokens cannot be restored.
 
 ## Rate limits
 
-Metered in **units of work, not requests** — a search is not a forum listing, and
-a limit that prices them the same invites the expensive call. Every response,
-refused or not, carries `x-ratelimit-limit`, `x-ratelimit-remaining` and
-`x-ratelimit-reset`; a refusal is `429` with `retry-after`.
+Authenticated budget: **600 units per 300 seconds** per token.
 
-A token spends against **600 units per 300 seconds**, held against the token. An
-unauthenticated caller has no token to hold a budget against, so theirs is held
-against their address prefix and is smaller: **120 units per 300 seconds**. The
-board’s ordinary anti-flood limits apply to writes on top of both, exactly as they
-do to the web forms.
+Guest budget: **120 units per 300 seconds** per address prefix.
 
-## Endpoints
+Endpoint costs consume units. Metered responses include `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset`. A budget refusal returns `429` and `retry-after`. Board posting/flood limits also apply.
 
-Full schemas for every request and response are in the OpenAPI document; this
-table is the map.
+## Endpoints
 
 | Method | Path | Scope | Cost | Token | Summary |
 |---|---|---|---|---|---|
@@ -155,65 +90,31 @@ table is the map.
 
 ## Errors
 
-Every error is the same shape, so a client parses one thing:
-
 ```json
 { "error": { "code": "missing_scope", "message": "…", "requestId": "…" } }
 ```
 
-`code` is stable and machine-readable; `message` is for a human reading a
-terminal. `requestId` is the board’s correlation id — quote it in a report and an
-operator can find the request in their logs.
-
-The API refuses a request before it reaches the board with these:
+Use `code` for handling, `message` for display and `requestId` to locate server logs.
 
 | Status | Code | Meaning |
 |---|---|---|
-| 400 | `bad_request` | A query parameter was missing or unusable. |
-| 401 | `unauthenticated` | No bearer token, or the token is not valid. |
-| 403 | `missing_scope` | Authenticated, but this token lacks the endpoint’s scope. |
-| 403 | `owner_unavailable` | The account the token belongs to can no longer act. |
-| 404 | `no_such_route` | No such endpoint. |
-| 404 | `not_found` | No such resource, or none this caller may see. |
-| 429 | `rate_limited` | Over the window budget. See `retry-after`. |
-| 501 | `not_implemented` | Declared in the registry, handler not yet written. |
-| 503 | `board_offline` | The board is offline and this caller may not see it. |
-
-Past that point a request is running the same domain command the web form runs,
-so it fails the way the web form fails, with the board’s own error codes and the
-message translated into the board’s language:
-
-| Status | Code | Meaning |
-|---|---|---|
-| 403 | `FORBIDDEN` | The owner’s permissions do not allow this, whatever the token carries. |
-| 404 | `NOT_FOUND` | The thing named in the request is not there. |
-| 409 | `CONFLICT` | Something else changed underneath the request. |
-| 422 | `VALIDATION` | The board’s posting rules refused the contents — too long, too soon, a subject missing. |
-| 429 | `RATE_LIMITED` | Over one of the board’s anti-flood limits, which are separate from the API budget. |
-
-A resource the caller may not see is `404`, never `403`. Telling a stranger that
-a thread exists but is not for them is the same leak as showing it to them. A
-`403` means the caller can see the thing and may not do this to it.
+| 400 | `bad_request` | Missing or invalid query parameter |
+| 401 | `unauthenticated` | Missing or invalid token |
+| 403 | `missing_scope` | Required scope absent |
+| 403 | `owner_unavailable` | Token owner cannot act |
+| 404 | `no_such_route` | Unknown endpoint |
+| 404 | `not_found` | Resource missing or hidden |
+| 429 | `rate_limited` | API budget exceeded |
+| 501 | `not_implemented` | Registered endpoint has no handler |
+| 503 | `board_offline` | Board unavailable to this caller |
+| 403 | `FORBIDDEN` | Domain permission denied |
+| 404 | `NOT_FOUND` | Domain resource missing |
+| 409 | `CONFLICT` | Conflicting state |
+| 422 | `VALIDATION` | Domain input/posting rule failed |
+| 429 | `RATE_LIMITED` | Board flood limit exceeded |
+
+Hidden resources return `404`; a visible resource can return `403` for an action the owner cannot perform. Domain messages use the board language.
 
 ## Webhooks
 
-The board POSTs a JSON body and four headers:
-
-| Header | Meaning |
-|---|---|
-| `x-forum-event` | The topic. |
-| `x-forum-delivery` | Stable across retries — de-duplicate on this. |
-| `x-forum-timestamp` | Unix seconds, and part of the signed material. |
-| `x-forum-signature` | `sha256=<hex>` of `HMAC(secret, "<timestamp>.<body>")`. |
-
-Verify by recomputing the HMAC over `` `${timestamp}.${rawBody}` `` and comparing in
-constant time — **and reject anything older than five minutes**. The timestamp is
-inside the signed material precisely so it cannot be edited; checking the
-signature without checking the age leaves every captured delivery replayable
-forever.
-
-Delivery is queued, never inline. Failures retry with exponential backoff and
-jitter (30s doubling, capped at an hour, six attempts) and then **dead-letter**
-rather than disappearing, so an operator can retry them once the receiver is
-fixed. A `410 Gone` stops the retries immediately: the receiver has said the
-endpoint is finished.
+Follow [Webhooks](../integrations/webhooks.md) to subscribe, verify signatures, deduplicate deliveries and handle retries.
diff --git a/docs/reference/performance.md b/docs/reference/performance.md
index 9c2e4a85e..9ad5bb325 100644
--- a/docs/reference/performance.md
+++ b/docs/reference/performance.md
@@ -10,17 +10,9 @@
   Regenerate with `pnpm perf:docs`; `pnpm verify` fails when this is stale.
 -->
 
-The p95 budgets for the pages a board’s traffic actually goes to, what the
-last recorded run measured against a full-scale board one read at a time,
-and what a board full of members reading at once measured on the same data.
+Recorded database-read timings, budgets and concurrent-load results. These are single-process measurements with an in-process cache and no Redis. Measure your own deployment; shared-cache results can differ.
 
-Every number here is measured on a **single-instance** board — one web
-process with the per-process cache, no Redis. That is the stock topology
-and the honest baseline. A board [scaled out](../operations/scaling.md) answers from a
-shared cache instead of an in-process map, so its numbers differ; measure
-your own rather than reading these across.
-
-## The board these numbers came from
+## Test environment
 
 | | |
 |---|---|
@@ -33,9 +25,7 @@ your own rather than reading these across.
 | Runtime | Node v22.22.2 on linux-x64 |
 | Measured | 2026-08-18 |
 
-The absolute numbers belong to that machine. What travels between machines
-is the **shape**: which scenarios sit near their budget, and whether a deep
-page costs more than a first page. Compare ratios, not milliseconds.
+Results apply to the recorded machine and workload; they are not a capacity guarantee.
 
 ## Budgets and measurements
 
@@ -54,17 +44,9 @@ page costs more than a first page. Compare ratios, not milliseconds.
 
 ## Under concurrent load
 
-Every measurement above is one read at a time. This is the same board with
-members on it: each one asks for a page every 10 seconds, drawn from the
-mix below, through the single connection pool one process has —
-**3 connections**, which is the shipped default and not a tuned number.
+Fixed-schedule traffic: one page per member every 10 seconds, using 3 database connections.
 
-Arrival times are on a fixed schedule rather than a request-then-sleep loop.
-That distinction is the whole measurement: a loop that sleeps *after* each
-response slows its own arrivals down exactly when the board gets slow, so it
-reports a queue as if it were an idle system. **Lateness** is what that loop
-cannot see — how long a request sat before it even started, because every
-connection was busy. It moves first, and it moves before the p95 does.
+Late p95 measures the delay before a scheduled request starts. Fixed arrivals expose queueing that a response-then-sleep loop would hide.
 
 | Active members | Offered | Served | Budget | | p50 | p95 | p99 | Late p95 |
 |---:|---:|---:|---:|---|---:|---:|---:|---:|
@@ -77,12 +59,11 @@ connection was busy. It moves first, and it moves before the p95 does.
 
 Each rung discards its first 10 seconds, then measures until it has both 400 requests and a steady window to put them in.
 
-## The same pages, under that load
+## Per-page load results
 
-From 50 members to 2,500 the p95 of the mix barely moves — 32.3 ms to 33.5 ms, across 50× the traffic. That flatness is not the board being idle; it is what a mixed p95 measures. A p95 is set by the slowest one request in twenty, and search and discovery are about that share of the traffic, so until the pool runs out the mixed p95 mostly reports which pages are in the mix rather than how many members are on the board.
+Mixed p95: 32.3 ms at 50 members to 33.5 ms at 2,500 members (50× traffic). The traffic mix affects this aggregate; inspect per-page timings too.
 
-The per-page breakdown is where load shows earlier, and says which pages it
-shows in first.
+Per-page p95 by active-member count:
 
 | Page | Share | 50 | 250 | 1,000 | 2,500 | 4,250 | 5,000 |
 |---|---:|---:|---:|---:|---:|---:|---:|
@@ -96,30 +77,15 @@ shows in first.
 | Search, rare term | 2% | 42.1 ms | 40.2 ms | 47.6 ms | 64.4 ms | 355.9 ms | 2072.3 ms |
 | Member profile | 5% | 2.6 ms | 1.9 ms | 5.2 ms | 10.6 ms | 107.3 ms | 691.1 ms |
 
-Every row is a p95 in milliseconds, and the column heading is how many members
-were on the board. A row that climbs left to right is a page that costs more
-when the board is busy; a row that does not is a page whose cost is its own.
-
-The scoped reads —
-*Latest threads*, *Search, near-universal term*, *Search, rare term* —
-pay the permission filter first, in the same request, exactly as a page does.
-Their numbers here are therefore the filter plus the read, and are not
-comparable with the single-read measurement of the same id above.
+Scoped reads (Latest threads, Search, near-universal term, Search, rare term) include permission filtering. They are not directly comparable to single-read timings.
 
 ### 5,000 active members
 
-Over the shoulder, and here to say where the shoulder is. This is a limit, not a target: five hundred requests a second is past what one process at the default pool of three absorbs, the requests still start on time — lateness stays near zero — and then they queue inside the pool, which is why the p95 goes to seconds while every rung below it is in milliseconds. It is recorded so the shoulder cannot move down quietly. Where it should be is an open question for whoever sizes a deployment: more processes, a larger pool, or accepting that a board this busy has outgrown one of them.
+At 500 requests per second, the recorded run queues inside the three-connection pool. This ceiling detects regressions; it is not a recommended operating load. Measure additional processes or pool capacity before deploying at this rate.
 
 ## Partial visible indexes
 
-`EXPLAIN` evidence that the partial `visibility` indexes are actually used.
-This is that evidence, and it is also a **check**: `pnpm perf explain`
-fails when the planner stops choosing one.
-
-That failure is the one worth guarding. A partial index only matches a query
-whose predicate the planner can prove implies it, so a read path that starts
-passing a variable visibility scope where it passed a literal falls silently
-onto a sequential scan of the largest table on the board. Nothing errors.
+`pnpm perf explain` checks that the planner uses the expected indexes.
 
 | Page | Index | Used | Warm |
 |---|---|---|---:|
@@ -129,70 +95,66 @@ onto a sequential scan of the largest table on the board. Nothing errors.
 | Thread page, as a moderator | `posts_thread_all_idx` | yes | 0.0 ms |
 | Moderation queue | `posts_forum_visibility_idx` | yes | 1.4 ms |
 
-Each partial index has an unfiltered twin, and the twins are checked too. A
-moderator seeing unapproved and deleted content *cannot* use the partial
-index — their predicate does not imply it — so without the twin their forum
-view is a sequential scan. That failure is invisible to every test written
-from a member’s point of view, which is most of them.
+Both visible-content partial indexes and their unfiltered counterparts are checked. Moderator queries need the unfiltered indexes when their scope includes hidden content.
 
-## What each scenario is and why it is measured
+## Scenarios
 
 ### Thread, page 1
 
 `thread-page-first` — listThread(limit 20) on a long thread.
 
-The single most requested page on any forum. Everything else is rounding.
+Baseline first-page thread read.
 
 ### Thread, deep page
 
 `thread-page-deep` — listThread(afterId) far into a long thread.
 
-The keyset claim. Under OFFSET this degrades with depth; it must not.
+Checks cursor pagination deep into a thread.
 
 ### Forum, page 1
 
 `forum-page-first` — listForum(limit 20) on the busiest forum.
 
-Sticky-first ordering over the largest thread set on the board.
+Checks pinned-first ordering in the largest forum.
 
 ### Forum, deep page
 
 `forum-page-deep` — listForum(after cursor) deep into the busiest forum.
 
-Same keyset claim on the other axis, and the one an archive crawler hits.
+Checks cursor pagination deep into a forum.
 
 ### Board index
 
 `board-index` — listListing() — every forum with its counters and last post.
 
-One query for the whole tree, and the page every visitor lands on.
+Checks the forum tree with stored counts and latest-post data.
 
 ### Permission filter
 
 `visible-forums` — forumIdsWhere(actor, thread.view).
 
-Every list page pays this before it reads anything, so its cost multiplies.
+Measures the authorisation scope used before content reads.
 
 ### Latest threads
 
 `discovery-latest` — Discovery page 1, scoped to visible forums.
 
-Ordered across the whole board rather than within one forum — the widest scan, and the most run-to-run variance of anything here. It was budgeted at 80ms against a typical p95 near 50, which is 1.6× and breaks the 2–3× rule stated at the top of this file; it duly went red on a noisy run at 110ms with a 621ms outlier. Raised to 150ms — not to make it pass, but because the original number was set tighter than the methodology the rest of the table follows.
+Checks cross-forum ordering with headroom for run-to-run variance.
 
 ### Search, near-universal term
 
 `search-common` — Relevance search for a term matching 96% of the board.
 
-The worst query a member can trigger, and the one budget the first load run failed. Relevance ordering is not indexable: `ts_rank_cd` has to score every matching row before it can name the top twenty, so a term matching 2.26M of 2.34M posts cost a p95 of 5.5 seconds with the GIN index present and used. The fix was to bound the ranked set to the most recent 20,000 matches, which measured 98ms — and changes nothing for any term selective enough that the window holds the whole match set, which is every real query. Recorded in mybb-parity.md.
+Measures relevance ranking for a broad match set. Ranking is bounded to the most recent 20,000 matches.
 
 ### Search, rare term
 
 `search-rare` — Full-text search for a term with ~1,000 matches.
 
-Separated because a fast rare-term search hides a slow common-term one, and here it did: before the window bound these two differed by a factor of 130, and only the pair made it visible that the cost was the match count rather than the code. They still differ, by about 5×, which is the residual and expected shape.
+Measures selective full-text search separately from common-term ranking.
 
 ### Member profile
 
 `member-profile` — Profile with counters for a prolific member.
 
-A post count computed live is an aggregate over the member's whole history.
+Checks profile reads using stored counters.
diff --git a/docs/reference/plugin-hooks.md b/docs/reference/plugin-hooks.md
index b0a7242c8..b32849ff2 100644
--- a/docs/reference/plugin-hooks.md
+++ b/docs/reference/plugin-hooks.md
@@ -9,29 +9,13 @@
   disagree.
 -->
 
-**104 hooks** — 59 filters, 45 events — and 8 UI regions. **104 are wired**: something in the board fires
-them today, and the rest are declared but not yet reached by a call site.
-
-The wired column is derived from the tree by `scripts/hook-callsites.mjs`, not
-maintained by hand — a registry entry with no call site is a promise about code
-that never runs, and it fails in the quietest possible way: the plugin installs,
-the handler registers, nothing happens. `plugins/reference` is required by its own
-test to handle every wired hook, so a hook cannot join that column without
-something proving it fires.
-
-A **filter** is handed a value and returns a replacement; its result is used, so a
-filter that throws or returns nothing leaves the value as it was and the chain
-carries on with the next plugin. An **event** is told what happened and its return
-value is discarded — which is why anything that only wants to observe should be one:
-it cannot corrupt the thing it is watching even when it is wrong.
-
-Handlers run in **(priority, plugin key)** order. Both halves are declared, so two
-plugins compose the same way on every request and on every instance.
-
-Every handler is called inside the host’s try/catch and is timed. Failures are
-counted in the database, so a plugin that fails repeatedly is switched off across
-the whole board and stays off until an operator clears the record. See
-[`plugins.md`](../extensions/plugins.md) for the policy, the lifecycle and the limits.
+104 hooks: 59 filters and 45 events. 8 UI regions.
+
+104 hooks have call sites in this build. The Wired column is generated from the source tree.
+
+Filters return replacement values; throwing or returning undefined retains the previous value. Event return values are ignored.
+
+Handlers run by priority, then plugin key. See [Hooks and lifecycle](../extensions/plugin-hooks-guide.md) for failures, runtime access and lifecycle rules.
 
 ## Content rendering
 
@@ -45,12 +29,12 @@ the whole board and stays off until an operator clears the record. See
 | `smilies.list` | filter | yes | `readonly { readonly code: string; readonly src: string; readonly alt?: string }[]` | `Record<string, never>` |
 | `word-filter.patterns` | filter | yes | `readonly { readonly pattern: string; readonly replacement: string; readonly wholeWord: boolean }[]` | `Record<string, never>` |
 
-- **`markdown.parse.text`** — The raw Markdown source, before it is parsed. Last chance to rewrite input.
-- **`markdown.render.html`** — Rendered HTML, after the renderer has constructed it. Anything added here is trusted output and nothing escapes it afterwards.
-- **`markdown.directives`** — The declarative directive list, so a plugin can add a `:::name` block or `:name[…]` span without core changes. Board-wide: rendered bodies are stored and shared, so the set cannot depend on who is reading.
-- **`post.body.html`** — One post’s rendered body, in the context of the thread it is being read in.
+- **`markdown.parse.text`** — Raw Markdown before parsing.
+- **`markdown.render.html`** — Rendered HTML. Replacement markup is trusted and is not escaped afterwards.
+- **`markdown.directives`** — Board-wide directives for `:::name` blocks and `:name[…]` spans. The list must not depend on the reader because rendered bodies are shared.
+- **`post.body.html`** — Rendered post body with thread and viewer context.
 - **`signature.html`** — A member’s rendered signature, wherever it appears.
-- **`smilies.list`** — The smilie set substituted at render. Board-wide, for the same reason the directive list is.
+- **`smilies.list`** — Board-wide smilie substitutions. The list must not depend on the reader.
 - **`word-filter.patterns`** — The render-time word filter’s pattern list.
 
 ## View models
@@ -98,38 +82,38 @@ the whole board and stays off until an operator clears the record. See
 - **`view.user-panel`** — The user panel model: greeting, counts, account links.
 - **`view.navigation`** — The breadcrumb trail.
 - **`view.footer`** — The footer model, including its link list.
-- **`view.forum-jump`** — The jump box model. A plugin adding a destination must give it a real forum id — the route re-authorises whatever is submitted.
-- **`view.announcement`** — One announcement, on its way to the theme. Its body is already rendered HTML from the boardu2019s own renderer, so a plugin replacing it is replacing trusted markup — the one hook where that is true of a body.
+- **`view.forum-jump`** — Forum jump options. Destinations require real forum IDs; the route rechecks permission on submission.
+- **`view.announcement`** — Announcement model with rendered HTML. Replacement body markup is trusted.
 - **`view.board-index`** — The index page model.
-- **`view.forum-row`** — One forum row in a listing. Runs once per row — keep it cheap.
+- **`view.forum-row`** — Forum listing row. Runs once per row.
 - **`view.thread-row`** — One thread row in a listing. Runs once per row.
-- **`view.post-bit`** — One post as the theme will receive it. The busiest hook on the board: it runs once per post on every thread page.
+- **`view.post-bit`** — Post model. Runs once per post on each thread page.
 - **`view.post-actions`** — The per-post control links. Adding one here does not create permission to use it.
 - **`view.member-profile`** — A member’s profile model, including its custom fields and action links.
 - **`view.board-stats`** — The board totals block.
 - **`view.who-is-online`** — The online list, already resolved against the reader.
-- **`view.latest-threads`** — The index sidebar’s newest-threads panel. Runs again on every refresh of the live region, not only on the page load — keep it cheap.
-- **`view.latest-posts`** — The index sidebar’s newest-posts panel. Same refresh cost as view.latest-threads.
+- **`view.latest-threads`** — Latest threads panel. Runs on initial render and each live refresh.
+- **`view.latest-posts`** — Latest posts panel. Runs on initial render and each live refresh.
 - **`view.pagination`** — A resolved page-link window.
 - **`view.search-form`** — The search form model, including its filter options.
-- **`view.search-results`** — One page of search results. Already checked against the reader — a hit a plugin adds here has not been, and will be shown to whoever asked.
-- **`view.discovery-view`** — A discovery listing — new posts, today, unanswered — with its tabs. Same warning as the search results: the rows arrive authorised.
-- **`view.auth-page`** — The sign-in, register and password-reset page around its form. The form itself is a region, not a value: nothing here can change what it posts to.
-- **`view.panel-shell`** — The frame around a control panel, including the links to the other panels this viewer may reach. Adding a link grants nothing.
-- **`view.panel-nav`** — A control panel’s section rail, with the current section already resolved. Runs on every panel page.
-- **`view.panel-page`** — One control-panel page’s heading block. Runs on every panel page.
-- **`view.panel-section`** — One labelled section inside a panel page. Runs once per section.
-- **`view.error-notice`** — The error page model. Runs on the page that renders when things are broken.
-- **`view.shell`** — The page frame’s model. Runs on every page including the error pages.
+- **`view.search-results`** — Search results authorised for the viewer. Added rows require separate visibility checks.
+- **`view.discovery-view`** — Discovery listing and tabs. Existing rows are authorised; added rows require separate visibility checks.
+- **`view.auth-page`** — Sign-in, registration or password-reset page. The app supplies the form as a rendered region.
+- **`view.panel-shell`** — Control panel frame and links. Adding links does not grant access.
+- **`view.panel-nav`** — Control panel navigation with the current section. Runs on each panel page.
+- **`view.panel-page`** — Control panel page heading. Runs on each panel page.
+- **`view.panel-section`** — Panel section. Runs once per section.
+- **`view.error-notice`** — Error page model.
+- **`view.shell`** — Page frame. Runs on every page, including error pages.
 - **`view.notice`** — A board notice or flash message, before the theme renders it.
 - **`view.category-block`** — One category on the index, with its rendered forum rows.
 - **`view.subforum-list`** — The compact child-forum list above a thread listing.
 - **`view.forum-display`** — A forum page’s model, including its rendered regions.
 - **`view.thread-view`** — A thread page’s model, including its rendered post list.
 - **`view.post-form`** — The composer page’s model. The form itself is app-rendered and arrives as a region.
-- **`view.quick-reply`** — The quick-reply island’s model, at the foot of a thread. The reply form itself is app-rendered and arrives as `children`.
+- **`view.quick-reply`** — Quick-reply model. The app supplies the reply form as `children`.
 - **`view.editor-toolbar`** — The composer’s formatting-toolbar model — its buttons and the attachment picker.
-- **`view.redirect-notice`** — The interstitial shown after a mutation, before the meta refresh fires. The target is re-checked against the board after the filter runs, so this cannot send a member off-site.
+- **`view.redirect-notice`** — Post-mutation redirect notice. The target is checked again after filtering and must remain on the board.
 
 ## Posting
 
@@ -166,7 +150,7 @@ the whole board and stays off until an operator clears the record. See
 - **`post.created`** — A reply was created and committed.
 - **`post.edit.before`** — An edit’s new body and reason, before the revision is written.
 - **`post.edited`** — A post was edited and a revision recorded.
-- **`post.delete.before`** — A post is about to be soft-deleted. Observation only: refusing is a permission.
+- **`post.delete.before`** — Post scheduled for soft deletion. Cannot veto deletion.
 - **`post.deleted`** — A post was soft-deleted.
 - **`post.restored`** — A soft-deleted post was restored.
 - **`thread.moved`** — A thread changed forum. Carries both forum ids.
@@ -174,11 +158,11 @@ the whole board and stays off until an operator clears the record. See
 - **`thread.split`** — Posts were split out into a new thread.
 - **`thread.locked`** — A thread was opened or closed.
 - **`thread.stickied`** — A thread was pinned or unpinned.
-- **`attachment.upload.validate`** — Validation messages for an upload, after the magic-byte check. A plugin may refuse a file core would accept; it can never accept one core refused.
-- **`attachment.uploaded`** — A file finished uploading and re-encoding.
+- **`attachment.upload.validate`** — Upload validation after file-type checks. Can reject an accepted file; cannot accept a file rejected by core.
+- **`attachment.uploaded`** — Upload stored. Image processing may still be pending.
 - **`attachment.deleted`** — An attachment was removed, by a member or by the orphan sweep.
 - **`poll.created`** — A poll was attached to a thread.
-- **`poll.voted`** — A vote was cast, once per option chosen. It fires again when a poll that allows re-voting takes a replacement.
+- **`poll.voted`** — Vote recorded. Runs for each chosen option, including replacement votes.
 - **`rating.recorded`** — A thread rating was recorded or changed.
 
 ## Moderation
@@ -193,7 +177,7 @@ the whole board and stays off until an operator clears the record. See
 | `warning.revoked` | event | yes | `{ readonly warningId: number; readonly userId: number }` | `ModerationRef` |
 | `moderation.logged` | event | yes | `{ readonly action: string; readonly targetId: number \| null }` | `ModerationRef` |
 
-- **`report.created`** — Something was reported. The hook a notifier or a webhook wants.
+- **`report.created`** — Report created.
 - **`report.resolved`** — A report was closed, with the resolution.
 - **`approval.queued`** — Content entered the approval queue.
 - **`approval.decided`** — Queued content was approved or rejected.
@@ -218,17 +202,17 @@ the whole board and stays off until an operator clears the record. See
 | `user.merged` | event | yes | `{ readonly keptUserId: number; readonly mergedUserId: number }` | `RequestRef` |
 | `user.deleted` | event | yes | `UserRef & { reason: 'pruned' \| 'deleted' }` | `RequestRef` |
 
-- **`user.register.validate`** — Validation messages for a registration. Where a custom question or an external blocklist belongs.
+- **`user.register.validate`** — Registration validation messages. Use for additional questions or blocklists.
 - **`user.registered`** — An account was created, before or after activation depending on the mode.
 - **`user.activated`** — An account finished activation.
-- **`user.login.attempted`** — A sign-in was attempted, with the outcome. Never carries the password or the session token.
+- **`user.login.attempted`** — Sign-in attempt and outcome. Excludes passwords and session tokens.
 - **`user.logged-in`** — A session was established.
 - **`user.logged-out`** — A session was ended, by the member or by revocation.
 - **`user.banned`** — A member was banned, with the expiry when there is one.
 - **`user.unbanned`** — A ban was lifted or expired and the prior group restored.
 - **`user.groups.changed`** — Primary or secondary group membership changed.
 - **`user.profile.updated`** — A member saved profile or option changes.
-- **`user.merged`** — Two accounts were merged. Carries the winner and the account that went.
+- **`user.merged`** — Account merge with retained and removed account IDs.
 - **`user.deleted`** — An account was pruned or deleted.
 
 ## Mail, notifications, messages
@@ -246,7 +230,7 @@ the whole board and stays off until an operator clears the record. See
 
 - **`notification.create.before`** — A notification about to be created. Returning `null` suppresses it.
 - **`notification.created`** — A notification was stored.
-- **`mail.send.before`** — A queued message, before it is handed to the mail driver. Subject, body and recipient; returning `null` drops it.
+- **`mail.send.before`** — Queued email before driver submission. Return `null` to suppress it.
 - **`mail.sent`** — A message was accepted by the driver. Not proof of delivery.
 - **`pm.send.before`** — A private message, before it is stored.
 - **`pm.sent`** — A private message was delivered to its recipients’ folders.
@@ -264,8 +248,8 @@ the whole board and stays off until an operator clears the record. See
 | `metadata.page` | filter | yes | `{ readonly title: string; readonly description: string \| null; readonly canonical: string; readonly imageUrl: string \| null }` | `{ readonly route: string }` |
 
 - **`search.query.before`** — The parsed search terms, before the query runs. The scope is not filterable.
-- **`search.results`** — A page of results, already permission-filtered in SQL. A plugin may reorder or drop; adding a row here would add one the viewer may not see.
-- **`feed.items`** — The items of a feed, rendered as a guest. Anything added is public.
+- **`search.results`** — Search results authorised in SQL. Reorder or remove rows; check visibility before adding any.
+- **`feed.items`** — Feed entries after visibility filtering. May contain private member content; do not share entries between requests. Added rows require separate visibility checks.
 - **`sitemap.entries`** — One chunk of the sitemap.
 - **`metadata.page`** — Title, description and social card for a page.
 
@@ -286,16 +270,12 @@ the whole board and stays off until an operator clears the record. See
 - **`task.run.before`** — A scheduled task is about to run.
 - **`task.run.after`** — A scheduled task finished, with its outcome and duration.
 - **`cache.invalidated`** — A cache tag was invalidated.
-- **`plugin.enabled`** — A plugin was enabled — including this one, which is how it learns it is on.
-- **`plugin.disabled`** — A plugin was disabled, by an operator or by the host after repeated failures. Carries the reason.
+- **`plugin.enabled`** — Plugin enabled. Includes the enabled plugin itself.
+- **`plugin.disabled`** — Plugin disabled by an operator or after repeated failures, with the reason.
 
 ## UI regions
 
-Regions are **not** theme slots. A theme owns its slots; a region is an explicit
-"plugins may add something here" point that a theme chooses to render, so the theme
-keeps control of where plugin output appears and the plugin keeps control of what it
-is. Several plugins contributing to one region compose by concatenation, in the same
-deterministic order as hooks.
+Themes place these regions. Enabled plugin contributions are concatenated in hook order.
 
 | Region | What it is handed |
 |---|---|
@@ -310,9 +290,9 @@ deterministic order as hooks.
 
 - **`header.notice`** — Directly below the board header, above the page body. Board-wide notices.
 - **`index.footer`** — The bottom of the board index, below the statistics block.
-- **`postbit.badges`** — Beside a post author’s name. Runs once per post on every thread page — the most expensive region on the board, and the one to keep trivial.
+- **`postbit.badges`** — Author badges. Runs once per post; avoid per-post queries.
 - **`postbit.footer`** — Below a post body, above its actions.
-- **`threadrow.badges`** — Beside a thread’s title in a listing, to mark threads across a forum page. A batch region: unlike every other region it runs once per page, not once per row — a listing of twenty threads is one call, returning a badge per thread id — because a forum page is on a tight budget and a per-row region there is twenty calls before the page has drawn a thing.
-- **`thread.header`** — Above the first post of a thread, below its title. Runs once per thread page, so unlike postbit.* it can afford to read from the plugin’s own tables.
+- **`threadrow.badges`** — Thread-list badges. Runs once per page with visible thread references; returns badges keyed by thread ID.
+- **`thread.header`** — Below the thread title and above the first post. Runs once per thread page.
 - **`profile.panel`** — A panel on a member’s profile, below the standard fields.
 - **`admin.dashboard`** — A card on the admin dashboard. Only rendered for administrators.
diff --git a/docs/reference/theme-slots.md b/docs/reference/theme-slots.md
index f9dca8b44..806bd5110 100644
--- a/docs/reference/theme-slots.md
+++ b/docs/reference/theme-slots.md
@@ -10,11 +10,9 @@
 
 **theme-kit v0.24.** 36 slots: 36 stable, 0 provisional, 0 deprecated.
 
-What the marks mean, and how something is removed, is in
-[`themes.md`](../extensions/themes.md). In short: a **stable** slot and the fields of its
-model do not change before the next major; a **provisional** slot is named but not yet rendered
-by any page, so its model may change in a minor release; a **deprecated** slot still
-works and has a removal scheduled below.
+Stable contracts retain existing fields until a major release. Provisional models may change in a minor. Deprecated contracts remain available until their scheduled removal.
+
+See [Theme contract](../extensions/theme-contract.md) for implementation and versioning rules.
 
 ## Every slot
 
@@ -63,7 +61,7 @@ works and has a removal scheduled below.
 
 `server` · stable
 
-The outermost frame: skip link, header, main landmark, footer. Wraps every page including the error pages.
+Page frame with skip link, header, main landmark and footer, including error pages.
 
 Props: `ShellModel`
 
@@ -87,14 +85,14 @@ Props: `HeaderModel`
 | `homeHref` | `string` |  |
 | `viewer` | `ViewerModel` |  |
 | `navigation` | `readonly LinkModel[]` |  |
-| `logo` | `LogoModel \| undefined` | optional — The board's logo, when it has one. A theme that ignores this renders the board's name and is still correct — which is what makes the field additive rather than breaking. A theme that uses it should keep the name as the link's accessible content when there is no logo, because the header is the only link home on most pages. |
+| `logo` | `LogoModel \| undefined` | optional — Optional board logo. Use the supplied alternative text and dimensions; fall back to the board name when absent. |
 | `children` | `ReactNode` | optional |
 
 ### UserPanel
 
 `server` · stable
 
-Greeting and account links, or the sign-in prompt for a guest. Varies by actor, which is why no page wrapping it may be cached globally.
+Actor-specific greeting and account links, or guest sign-in prompt. Do not cache globally.
 
 Props: `UserPanelModel`
 
@@ -104,14 +102,14 @@ Props: `UserPanelModel`
 | `links` | `readonly LinkModel[]` | Sign-in / register, or account links. Resolved by the app. |
 | `unreadNotifications` | `CountModel` | `value` is `0` when there is nothing to show. |
 | `unreadMessages` | `CountModel` |  |
-| `notificationsHref` | `string` | optional — Where the two counts above lead, so a theme can make them clickable. A count that cannot be acted on is a notification the reader has to go hunting for. Both are absent for a guest, who has neither. Themes read these rather than searching `links` for the one labelled "Notifications", which two of them were doing and which breaks the moment that label is reworded or translated. |
+| `notificationsHref` | `string` | optional — Destinations for the unread notification and message counts. Use the resolved hrefs. |
 | `messagesHref` | `string` | optional |
 | `regions` | `{ readonly notifications?: ReactNode }` | optional |
-| `children` | `ReactNode` | optional — Account controls the app supplies — today, the log-out form. Log out cannot be a `LinkModel`: it is a POST to a Server Action, because a GET that ends a session is fired by every prefetcher and link scanner that touches the page. A Server Action reference is also not plain data and could never cross this contract, so the app renders the form and the theme decides where in the panel it sits. |
+| `children` | `ReactNode` | optional — App-rendered account controls, including the POST logout form. Place the supplied form; do not replace logout with a GET link. |
 
 **`regions.notifications`**
 
-The notifications menu the app supplies — a single control that opens the reader's notifications, private messages and, for staff, the moderation queue in tabs, marks them seen and links each one through (0.16). It is app-rendered rather than modelled field by field because it is an interactive island carrying Server Actions — the same reason logging out arrives as `children` and the quick-reply island as a region. A theme places it where the two unread counts used to sit; the island renders its own no-JavaScript fallback, so a theme that renders this needs no separate badge markup. Absent for a guest and on a board with neither service, and a theme that ignores it falls back to `unreadNotifications` and `unreadMessages`, which is what makes the field additive.
+App-rendered notification menu with messages and permitted moderation content, including a no-JavaScript fallback. Render instead of separate unread-count controls when present. Optional since 0.16.
 
 ### Navigation
 
@@ -138,14 +136,14 @@ Props: `FooterModel`
 | `boardTitle` | `string` |  |
 | `links` | `readonly LinkModel[]` |  |
 | `timezoneLabel` | `string` | Which zone `TimeModel.label`s were formatted in, for the footer note. |
-| `poweredBy` | `LinkModel` | optional — What the board runs on, and where to read about it (0.8). A `LinkModel` and not a hardcoded string in each theme, for the reason every other piece of footer text is one: the app owns the words and the URL, so they are written once and a theme that wants to place the attribution somewhere else in its layout can, without owning a copy of them. Optional, which is what makes it a minor rather than a major: a theme written against 0.7 compiles and runs unchanged, and simply does not render it. The two themes in this repository do. |
-| `regions` | `{ readonly controls?: ReactNode }` | optional — App-rendered controls the footer hosts: the forum-jump form and the appearance switcher (0.20). Both used to be full-width bars of their own stacked above the footer, which left the foot of every page reading as three separate rules. They are a GET form and Server-Action forms the app owns, so they cross the contract the way the log-out form does — as a rendered node the theme places, not data it could rebuild. Optional the way `poweredBy` is: a theme written against 0.19 compiles and runs unchanged — but one that never renders it costs its readers the jump box and the appearance controls, so place it rather than drop it. The bundled themes render it as a right-aligned row above the footer's own line of text. |
+| `poweredBy` | `LinkModel` | optional — Optional software attribution link supplied by the app. Added in 0.8. |
+| `regions` | `{ readonly controls?: ReactNode }` | optional — Optional app-rendered forum-jump and appearance controls. Place both in the footer. Added in 0.20. |
 
 ### Notice
 
 `server` · stable
 
-A board-wide announcement or a flash message. Server-rendered so a notice is present in the first response, not after hydration.
+Server-rendered flash message or board notice.
 
 Props: `NoticeModel`
 
@@ -159,7 +157,7 @@ Props: `NoticeModel`
 
 `server` · stable
 
-One announcement: a dated, authored notice shown above the forums. Distinct from Notice, which is a flash message about what the viewer just did — these are for everybody and last until they expire.
+Dated, authored announcement shown above forums until expiry.
 
 Props: `AnnouncementModel`
 
@@ -190,15 +188,15 @@ One `CategoryBlock` per top-level category, already rendered.
 
 **`regions.latest`**
 
-The self-refreshing pair: newest threads and newest posts, already rendered, or absent on a board that cannot answer either question. **One region rather than two, and that is the contract rather than a convenience.** The pair is refreshed by a single round trip while the page is open, so it arrives as one node; two regions would be two polls of the same board for the same reason, or one poll that could only update half of what a theme had placed. A theme places it — the default puts it at the top of a sidebar — but does not take it apart. Optional, so a theme written against an earlier minor compiles and simply does not show it. Same rule as every other region field here.
+App-rendered newest-thread/post region, refreshed together in one request. Place it as a unit. Absent when unavailable.
 
 **`regions.plugins`**
 
-The `index.footer` region: whatever plugins contributed, already rendered and ordered by the host. Optional, which is what makes this a **minor** addition under the versioning policy — a theme written against 0.1 keeps compiling and simply does not render plugin output. Every region field below follows the same rule.
+Optional, pre-rendered index.footer plugin contributions in host order.
 
 **`regions.announcements`**
 
-Live announcements, already rendered — one `Announcement` per row, or absent when there are none. Optional for the same reason the plugin region is, and under the same policy: a theme written against an earlier minor compiles and simply does not show them.
+Optional, pre-rendered live announcements. Absent when there are none.
 
 ### CategoryBlock
 
@@ -239,7 +237,7 @@ Props: `BoardStatsModel`
 | `postCount` | `CountModel` |  |
 | `memberCount` | `CountModel` |  |
 | `newestMember` | `UserRefModel \| null` |  |
-| `computedAt` | `TimeModel \| null` | When the totals were last rolled up, or null before the first run. Part of the contract rather than a detail the app hides, because a theme that shows the numbers should be able to say how old they are — and "computed ten minutes ago" is the difference between a number that is stale and one that is wrong. |
+| `computedAt` | `TimeModel \| null` | Last counter-rollup time, or null before the first run. Display it to identify the age of the totals. |
 
 ### WhoIsOnline
 
@@ -263,7 +261,7 @@ Props: `WhoIsOnlineModel`
 
 `server` · stable
 
-The newest threads on the board, for the index sidebar. Server, not client, even though the panel refreshes itself: the app polls a Server Action that renders this slot again, so the live half is one island around the region rather than a client component per panel.
+Newest threads, rendered on the server and refreshed through the app’s shared live region.
 
 Props: `LatestThreadsModel`
 
@@ -276,7 +274,7 @@ Props: `LatestThreadsModel`
 
 `server` · stable
 
-The newest posts on the board, with an excerpt of each. Same server rendering and same refresh path as LatestThreads.
+Newest posts and excerpts, refreshed with LatestThreads.
 
 Props: `LatestPostsModel`
 
@@ -302,7 +300,7 @@ Props: `ForumDisplayModel`
 
 **`regions.tools`**
 
-Controls scoped to this forum — the thread ordering, and the follow form for a member who may subscribe. Rendered by the route because both carry a Server Action or a URL contract the theme does not own. **A theme renders this under its heading, not above it.** That placement is the reason the field exists: these were app-rendered strips stacked *before* `ForumDisplay`, so the first thing on a forum page was a filter with nothing yet to say what it filtered. A control belongs after the thing it acts on has been named. Optional, which is what makes it a **minor** addition under the versioning policy — a theme written against 0.3 keeps compiling. Only what acts on the listing *below* it belongs here. Following the forum is in `afterContent`, for the reason given there.
+App-rendered forum ordering controls. Place below the heading and above the listing. Subscription controls are in `afterContent`.
 
 **`regions.threads`**
 
@@ -314,7 +312,7 @@ This forum's announcements *and* the board's — an announcement being board-wid
 
 **`regions.afterContent`**
 
-Controls for somebody who has finished with the page — today, the form that follows this forum. A theme renders it after the listing. "Do you want to hear about this forum?" is a question you can only answer once you have seen what is in it, and asked above the threads it is a panel between a reader and the thing they came for. The ordering tabs stay at the top in `tools`, because those act on the list underneath them.
+App-rendered forum subscription controls. Place after the listing.
 
 ### ThreadRow
 
@@ -332,7 +330,7 @@ Props: `ThreadRowSlotModel`
 
 **`regions.pluginBadges`**
 
-The `threadrow.badges` region, beside the thread's title (0.22). Filled from a single per-page call rather than one per row — a forum page lists twenty threads on a tight budget, so the region runs once with the whole page and hands each row its badges. Optional, which is what makes it additive: a theme written against 0.21 compiles and simply shows no plugin badges. Absent on a row no plugin marked; a theme places it wherever a thread's own flags (pinned, locked) sit.
+Optional thread-row plugin badges, supplied by one batched call per page. Place beside the thread flags. Added in 0.22.
 
 ### SubforumList
 
@@ -350,7 +348,7 @@ Props: `SubforumListModel`
 
 `server` · stable
 
-Page links. Server-rendered and href-based: paging must work with JavaScript disabled, so this can never become an island.
+Resolved page links that work without JavaScript.
 
 Props: `PaginationModel`
 
@@ -358,7 +356,7 @@ Props: `PaginationModel`
 |---|---|---|
 | `page` | `number` |  |
 | `pageCount` | `number` |  |
-| `pageCountIsExact` | `boolean` | Whether `pageCount` is the real number of pages or only what has been proved so far. A keyset-paged list knows the page it is on and whether another one follows; it does not know how many there are, and counting rows to find out is the query the cursor exists to avoid. So `pageCount` is a floor when this is `false`, and a theme that prints "3 of 4" from it is telling the reader something nobody checked. Print the page on its own instead, and keep "of N" for the lists that do know. |
+| `pageCountIsExact` | `boolean` | True when `pageCount` is an exact total. Otherwise it is a lower bound: display the current page without “of N”. |
 | `pages` | `readonly { readonly page: number; readonly href: string; readonly isCurrent: boolean }[]` |  |
 | `previousHref` | `string \| null` |  |
 | `nextHref` | `string \| null` |  |
@@ -377,12 +375,12 @@ Props: `ThreadViewModel`
 | `forum` | `LinkModel` |  |
 | `replyHref` | `string \| null` |  |
 | `markReadAction` | `string \| null` | A native POST target for the last visible post on this page. |
-| `watch` | `ThreadWatchModel \| null` | optional — The header's watch toggle, or `null` for a guest — who cannot subscribe to anything — and on a board running without the subscription service. Optional under the versioning policy: a theme written against 0.23 compiles and renders no toggle, the same as it already does for the cadence picker in `regions.afterContent`. |
+| `watch` | `ThreadWatchModel \| null` | optional — Optional watch toggle. Null for guests or without the subscription service. |
 | `regions` | `{ readonly tools?: ReactNode; readonly posts: ReactNode; readonly pagination: ReactNode; readonly afterContent?: ReactNode; readonly quickReply: ReactNode }` |  |
 
 **`regions.tools`**
 
-Controls scoped to this thread — following it, rating it, its poll, and the moderator's thread tools. Rendered by the route, for the reason every app-rendered region exists: each one carries a Server Action. **A theme renders this under its heading, not above it**, and the same history is behind this field as behind `ForumDisplayModel`'s. Four of these strips used to stack before `ThreadView`, so a thread opened on a phone began with a follow control, a star rating and a poll, and the title of the thing being followed, rated and voted on was a screen further down. Only what belongs *before* the posts: the moderator's bar, and the poll, which is content rather than a control. Rating and following are in `afterContent`. Optional under the versioning policy: a theme written against 0.3 compiles and simply does not offer them.
+App-rendered moderator tools and poll. Place below the title and above posts. Rating and subscription controls are in `afterContent`.
 
 **`regions.posts`**
 
@@ -390,7 +388,7 @@ One `PostBit` per post on this page.
 
 **`regions.afterContent`**
 
-Controls for a reader who has reached the end — rating the thread, and following it. A theme renders it after the posts and **before** the quick reply, which is the order the two are wanted in: somebody who has just read fifty posts is deciding what they think and whether to keep hearing about it, and then whether to answer. Both used to be above the first post, where they were asking for a verdict on something the reader had not read yet.
+App-rendered rating and subscription controls. Place after posts and before quick reply.
 
 **`regions.quickReply`**
 
@@ -400,7 +398,7 @@ The quick-reply island, or `null` when the viewer may not reply — in which cas
 
 `server` · stable
 
-One post: author block, body, footer. **The** load-bearing server slot — see this file’s header for what marking it `client` costs.
+Post author, body and footer, rendered on the server.
 
 Props: `PostBitSlotModel`
 
@@ -434,7 +432,7 @@ Props: `PostActionsSlotModel`
 |---|---|---|
 | `actions` | `PostActionsModel` |  |
 | `postId` | `number` |  |
-| `children` | `ReactNode` | optional — App-rendered controls that belong beside the post's own actions — today, the multi-quote island. It is `children` for the reason logging out is: the button is a client island holding browser state, and neither a component nor a handler can cross this contract as data. Before this field the page had nowhere to put it but `PostBitModel.regions.pluginFooter`, so every post on the board carried a second bordered row containing one control — the plugin region used as a parking space, and a visible band of furniture per post as the price. Additive under the versioning policy, and `children` is already exempt from the plain-data rule. |
+| `children` | `ReactNode` | optional — App-rendered post controls, including the multi-quote island. Place beside the post’s action links. |
 
 ### QuickReply
 
@@ -475,7 +473,7 @@ The app-rendered `<form>` carrying the Server Action and its controls.
 
 **`regions.toolbar`**
 
-Kept for a theme that wants a toolbar affordance of its own at the top of the composer. The built-in composer no longer fills it: a formatting toolbar belongs against the box it formats, not at the head of a card a subject field and a prefix picker can sit below, so the `EditorToolbar` island renders inside `form`, joined to the message textarea, and this is `null` there. A `null` must leave a working plain-textarea form: the island enhances, it never enables.
+Optional toolbar region. The built-in composer supplies null because its toolbar is inside `form`, beside the textarea. A null toolbar must leave the form usable.
 
 ### EditorToolbar
 
@@ -490,7 +488,7 @@ Props: `EditorToolbarModel`
 | `textareaId` | `string` | The textarea's `id`; the island attaches to it rather than owning it. |
 | `groupLabel` | `string` | Accessible name for the toolbar's `role="group"`. |
 | `buttons` | `readonly EditorToolbarButtonModel[]` |  |
-| `attachment` | `{ readonly inputId: string; readonly label: string } \| null` | The attachment picker, or `null` where this composer takes none. `inputId` names an app-rendered `<input type="file" hidden>` elsewhere on the page — the upload itself is a Server Action the app owns, so a theme never handles the file. A button that calls `.click()` on the element that id names opens the picker; like every other button here, that is an enhancement over a plain-textarea form, not what makes the form work. |
+| `attachment` | `{ readonly inputId: string; readonly label: string } \| null` | Attachment picker or null. `inputId` targets the app-owned hidden file input. An enhanced button may activate it; the app owns upload handling. |
 | `previewAction` | `string \| null` |  |
 
 ### MemberProfile
@@ -506,7 +504,7 @@ Props: `MemberProfileModel`
 | `user` | `UserRefModel` |  |
 | `avatarUrl` | `string \| null` |  |
 | `title` | `string \| null` | The member's group, shown under their name. The same rule the postbit follows: `users.display_group_id` where the member has chosen one, and their primary group otherwise. `null` only where the group behind it has gone. |
-| `groups` | `readonly GroupTagModel[] \| undefined` | optional — Every group shown with this member's name, on the same terms as `PostAuthorModel.groups`: display group first, the rest in display order, capped by the board's *Maximum displayed groups* setting. Render it instead of `title` when it is non-empty; fall back to `title` otherwise. |
+| `groups` | `readonly GroupTagModel[] \| undefined` | optional — Displayed groups, with display group first, then display order, capped by Maximum displayed groups. Use title only when groups is empty. |
 | `joinedAt` | `TimeModel` |  |
 | `lastVisitAt` | `TimeModel \| null` |  |
 | `postCount` | `CountModel` |  |
@@ -523,7 +521,7 @@ The `profile.panel` region.
 
 `server` · stable
 
-The search form. A GET form with named inputs, so a search is a URL that can be linked and cached.
+GET search form with supplied input names.
 
 Props: `SearchFormModel`
 
@@ -537,13 +535,13 @@ Props: `SearchFormModel`
 | `sorts` | `readonly OptionModel[]` |  |
 | `hint` | `string \| null` | Guidance for an empty form: quoting, exclusion. `null` once submitted. |
 | `errorMessage` | `string \| null` |  |
-| `advanced` | `SearchAdvancedModel` | optional — The rest of the form: who posted it, when, where to look, and what a result is. Optional, and a theme that ignores it still submits a working search — every control in here is a narrowing the app defaults for a form that leaves it out. |
+| `advanced` | `SearchAdvancedModel` | optional — Optional author, date, forum and result-type controls. Omitted controls use the default search scope. |
 
 ### SearchResults
 
 `server` · stable
 
-The results page for one search: what matched, an excerpt of each hit, and the form that narrows the set. Separate from SearchForm because a result list is a listing and shares nothing with a filter panel but the word "search".
+Search hits, excerpts and filtering controls.
 
 Props: `SearchResultsModel`
 
@@ -552,10 +550,10 @@ Props: `SearchResultsModel`
 | `terms` | `string` | What was searched for, as the reader typed it. |
 | `searchedAt` | `TimeModel` |  |
 | `hits` | `readonly SearchHitModel[]` |  |
-| `nextHref` | `string \| null` | The next page of this same search, or `null` at the end. Superseded by `regions.pagination`, which walks backwards as well and says which page this is. Both are populated: a theme written before the region existed keeps working, and one that renders the region should not also render this link or the page carries two pagers. |
+| `nextHref` | `string \| null` | Legacy next-page link, or null at the end. Prefer `regions.pagination`; render only one pager. |
 | `nextLabel` | `string` |  |
 | `newSearchHref` | `string` | Back to an empty form. Always offered: a search that found nothing needs it most. |
-| `within` | `{ readonly action: string; readonly field: string; readonly value: string; readonly label: string; readonly hint: string; readonly submitLabel: string; readonly hidden?: readonly HiddenFieldModel[] }` | The narrow-this-search form. A GET form, like `SearchForm` and for the same reason — the narrowed search is a URL of its own, not a state this page holds. `hidden` carries the advanced options this search was run with, one input per entry, so that narrowing it keeps them; a theme that drops them narrows within the words alone. |
+| `within` | `{ readonly action: string; readonly field: string; readonly value: string; readonly label: string; readonly hint: string; readonly submitLabel: string; readonly hidden?: readonly HiddenFieldModel[] }` | GET filter form. Preserve each `hidden` input so narrowing retains the original advanced options. |
 | `refine` | `SearchRefineModel` | optional — Filtering and sorting for the set on screen. Optional: a theme that ignores it shows the results as the search asked for them. |
 | `regions` | `{ readonly pagination?: ReactNode }` | optional |
 
@@ -567,7 +565,7 @@ The `Pagination` for this result set, rendered by the page.
 
 `server` · stable
 
-The body of a discovery listing — new posts, today, unanswered, and a member’s own threads and replies. One slot for all of them: they differ in what the query selected, never in what a reader is looking at.
+Discovery listing with the viewer’s available tabs.
 
 Props: `DiscoveryViewModel`
 
@@ -581,13 +579,13 @@ Props: `DiscoveryViewModel`
 | `nextHref` | `string \| null` |  |
 | `nextLabel` | `string` |  |
 | `emptyMessage` | `string` | What to say when `rows` is empty — different at the end of a paged list ("you have reached the end") from at the start of one ("nothing here yet"). |
-| `refusal` | `{ readonly message: string; readonly signInHref: string; readonly signInLabel: string } \| null` | Set when the view refused rather than failed: a guest asking for their own threads. The listing is empty and this says why, with `signInHref` to fix it. Not an error — a themed page, not the error page. |
+| `refusal` | `{ readonly message: string; readonly signInHref: string; readonly signInLabel: string } \| null` | Access notice for a refused discovery view. Results are empty; signInHref provides the sign-in action. |
 
 ### PanelShell
 
 `server` · stable
 
-The frame around a control panel: the navigation rail, the links to the other panels a viewer may reach, and the page beside them. Rendered for the member, moderator and admin panels alike — `panel` says which.
+Member, moderator or admin panel frame with navigation and content.
 
 Props: `PanelShellModel`
 
@@ -607,7 +605,7 @@ The `PanelNav` for this panel.
 
 `server` · stable
 
-A control panel’s section navigation. Server, not client: which section is open is resolved from the request path before rendering, so the rail arrives correct rather than after hydration, and a panel needs no JavaScript to know where it is.
+Panel navigation with current state resolved by the app before rendering.
 
 Props: `PanelNavModel`
 
@@ -622,7 +620,7 @@ Props: `PanelNavModel`
 
 `server` · stable
 
-One control-panel page: its heading, the line under it, the controls beside it, and the body. Also the frame for the account, moderation and messaging pages that are panel-shaped without being in a panel.
+Panel page heading, supporting text, actions and body.
 
 Props: `PanelPageModel`
 
@@ -631,7 +629,7 @@ Props: `PanelPageModel`
 | `panel` | `PanelKind \| null` |  |
 | `title` | `string` |  |
 | `back` | `LinkModel \| null` | Where this page was reached from, when it is a page under another. |
-| `frame` | `'panel' \| 'standalone'` | optional — `panel` when a `PanelShell` is already around this page — it has centred the column and set the gutters, and the page fills what the rail leaves. `standalone` when nothing wraps the page and it has to find its own middle: who's online, the board statistics, the report form. Absent reads as `panel`, which is what a theme that ignores this renders today. |
+| `frame` | `'panel' \| 'standalone'` | optional — `panel` fills an existing PanelShell; `standalone` supplies its own centred frame for pages such as online, statistics and reports. Defaults to panel. |
 | `width` | `'reading' \| 'wide'` | `reading` for prose and forms, `wide` for a table nobody can read at reading width. The theme decides what each measures. |
 | `gap` | `'normal' \| 'loose'` | `loose` for a page built of `PanelSection`s, `normal` for a page that is one thing. The theme decides what each measures; the distinction is whether the body has internal headings that need air around them. |
 | `regions` | `{ readonly lede?: ReactNode; readonly meta?: ReactNode; readonly actions?: ReactNode }` |  |
@@ -653,14 +651,14 @@ Controls that act on the whole page, beside the heading.
 
 `server` · stable
 
-A labelled section inside a panel page. Rendered by the page among its content rather than around it, which is why it is not part of PanelPage.
+Labelled content section inside a panel page.
 
 Props: `PanelSectionModel`
 
 | Field | Type | Notes |
 |---|---|---|
 | `title` | `string` |  |
-| `headingId` | `string` | The id the heading takes, so the section's landmark can point at it. Given by the page because the page is where the section is named twice — once as a heading and once as the region's accessible name. |
+| `headingId` | `string` | Heading ID used by the section landmark. |
 | `regions` | `{ readonly description?: ReactNode; readonly actions?: ReactNode }` |  |
 | `children` | `ReactNode` | optional |
 
@@ -668,7 +666,7 @@ Props: `PanelSectionModel`
 
 `server` · stable
 
-Signing in, registering, resetting a password, asking for a new confirmation link. One slot for all of them: the same card with a different form in it, and the form itself is an app-rendered region because every one of them posts to a Server Action.
+Authentication-page frame with an app-rendered form.
 
 Props: `AuthPageModel`
 
@@ -695,7 +693,7 @@ Standing advice beside the form — where to look before asking again.
 
 `server` · stable
 
-The jump box at the foot of every page. A GET form with a submit control, never a select that navigates on change — choosing an option is not committing to it, and arrow-keying through one would teleport a keyboard user to the first forum in the list.
+GET forum selector with a submit button; keyboard selection must not navigate automatically.
 
 Props: `ForumJumpModel`
 
@@ -711,7 +709,7 @@ Props: `ForumJumpModel`
 
 `server` · stable
 
-The MyBB-style interstitial: "your post was made, continuing in a moment", with a real link for anyone the meta refresh does not carry.
+Post-action notice with a meta-refresh destination and fallback link.
 
 Props: `RedirectNoticeModel`
 
@@ -725,7 +723,7 @@ Props: `RedirectNoticeModel`
 
 `server` · stable
 
-The themed body of an error or not-found page. Must not depend on the database: it is what renders when the database is the thing that failed.
+Error or not-found content. Must render without database access.
 
 Props: `ErrorNoticeModel`
 
@@ -739,20 +737,19 @@ Props: `ErrorNoticeModel`
 
 ## Shared models
 
-Referenced by the models above. Same promise: a field of a shared model reached
-from a stable slot is stable.
+Fields reached from a stable slot share its stability guarantee.
 
 ### AuthLinkModel
 
-A link out of an authentication page, with the sentence that introduces it. "New here? **Create an account**" is one thought and two pieces of markup. `lead` carries the first half so the copy stays the app's and the layout stays the theme's — a theme that renders links as a plain list can drop it, and one that renders them as sentences has the sentence.
+Authentication-page link and its optional introductory copy. The theme may present the link alone or with its `lead`.
 
 | Field | Type | Notes |
 |---|---|---|
 | `label` | `string` | from `LinkModel` |
 | `href` | `string` | from `LinkModel` |
-| `group` | `string` | from `LinkModel` — optional — Which run of links this one belongs to, for themes that separate them. Compare it for *change*, never for value: a theme draws a rule wherever consecutive links disagree, and the strings themselves stay the app's business. Absent everywhere is the normal case and renders as one run. |
-| `newTab` | `boolean` | from `LinkModel` — optional — Whether the link leaves the board, and should open in its own tab (0.16). Set by the app for a link an administrator marked as off-site — a chat server, a shop, a wiki. A theme that ignores it renders an ordinary link and is still correct, which is what keeps the field additive. A theme that honours it must pair `target="_blank"` with `rel="noopener noreferrer"`, because the opened page can otherwise reach back through `window.opener`. |
-| `submenu` | `readonly LinkModel[]` | from `LinkModel` — optional — Links that belong under this one, for a menu that opens a level (0.16). One level only: the app never nests a submenu inside a submenu, so a theme that renders one level renders every menu there is. Absent is the normal case. A theme that ignores it drops those links from the page entirely rather than flattening them, so a theme meaning to support the board navigation should render them — under `:hover` and `:focus-within`, both, because a menu that only opens to a mouse is closed to a keyboard. |
+| `group` | `string` | from `LinkModel` — optional — Link group. Insert a separator when consecutive values differ; do not depend on specific values. Absent values form one group. |
+| `newTab` | `boolean` | from `LinkModel` — optional — Open in a new tab when true. Pair `target="_blank"` with `rel="noopener noreferrer"`. Optional since 0.16. |
+| `submenu` | `readonly LinkModel[]` | from `LinkModel` — optional — One level of child links. Render them with keyboard and pointer access. The app does not nest submenus. Optional since 0.16. |
 | `lead` | `string \| null` |  |
 
 ### CountModel
@@ -781,7 +778,7 @@ One row in a discovery listing.
 
 ### EditorToolbarButtonModel
 
-One control in an `EditorToolbar`. Exactly one of `tag` and `insertion` is set, never both and never neither. `tag` names one of the board's own commands — `applyEditorTag(field, tag, placeholder)` from `@meith/theme-kit` runs it, and a theme that reads `tag` opaquely and hands it straight to `applyEditorTag` needs no change when a new one is added. `insertion` is a plugin's own: a directive registered through `markdown.directives` has no `EditorTag` to squat on, so a button contributed through the `view.editor-toolbar` filter carries the edit itself as data — `applyInsertion(field, insertion)` runs it the same way, sharing the caret and selection mechanics `applyEditorTag` uses. Both are plain JSON, so a plugin never hands the host a function to call.
+Editor control. Exactly one of `tag` and `insertion` is set. Use `applyEditorTag` for a built-in tag or `applyInsertion` for a plugin insertion; both operate on serializable edit data.
 
 | Field | Type | Notes |
 |---|---|---|
@@ -790,8 +787,8 @@ One control in an `EditorToolbar`. Exactly one of `tag` and `insertion` is set,
 | `label` | `string` |  |
 | `title` | `string` | `label`, plus the keyboard shortcut when this tag has one, already formatted. |
 | `keyShortcut` | `string \| null` | `aria-keyshortcuts`, e.g. `"Control+b"`, or `null` for a tag with no shortcut. |
-| `icon` | `string \| null` | A themed icon's name, for a theme that draws one — see `PanelNavIcon` for the same idea. Always `null` today: nothing in the default palette names one yet, so every theme renders its own glyph from `tag` or `label`. The field stays in the contract for the theme that wants to key off it once one does. |
-| `placeholder` | `string \| null` | Fills a wrap or spoiler tag when nothing is selected; `null` for a tag that does not need one, and for every `insertion` button — its strings are already fixed, so there is nothing left for a placeholder to fill. |
+| `icon` | `string \| null` | Optional theme icon name. Unknown or null names render no icon; the text label remains accessible. |
+| `placeholder` | `string \| null` | Placeholder for an empty wrap/spoiler selection. Null when unnecessary and for insertion buttons. |
 
 ### ForumJumpOption
 
@@ -822,7 +819,7 @@ Submitted as the form value. Opaque to the theme. readonly value: string readonl
 
 ### GroupTagModel
 
-One of the groups shown with a member's name. `nameClass` works exactly like `UserRefModel.nameClass` and exists for the same reason: the group's colour differs between light and dark, so it arrives as a class the app's `<head>` stylesheet defines rather than as a colour. Put it on whatever renders the title; a theme that ignores it shows the title in its ordinary text colour and is still correct.
+A displayed membership group. Apply `nameClass` to its name and use the supplied title and badge.
 
 | Field | Type | Notes |
 |---|---|---|
@@ -859,12 +856,12 @@ One post in the index's "latest posts" panel.
 | `href` | `string` | `/thread/12-slug?post=34` — the post, not the top of its thread. |
 | `forum` | `LinkModel` |  |
 | `author` | `UserRefModel` |  |
-| `excerpt` | `string` | The post as text: flattened out of its Markdown source and cut on a word boundary, the same way a feed entry's summary is. Flattened rather than rendered, because the board's HTML carries quotes, directives and attachment markup whose meaning is lost in two lines — and because a theme dropping raw post HTML into a sidebar is one plugin away from being an injection point. |
+| `excerpt` | `string` | Plain-text post excerpt, flattened from Markdown and cut at a word boundary. Render as text. |
 | `postedAt` | `TimeModel` |  |
 
 ### LatestThreadModel
 
-One thread in the index's "latest threads" panel. Every row carries its forum, because these two panels are the only lists on the board that cross it: without the forum, two identically-titled threads in two forums are the same row printed twice.
+Latest thread with its forum identity.
 
 | Field | Type | Notes |
 |---|---|---|
@@ -883,37 +880,37 @@ A resolved link. Themes never build hrefs; the app owns URL shape.
 |---|---|---|
 | `label` | `string` |  |
 | `href` | `string` |  |
-| `group` | `string` | optional — Which run of links this one belongs to, for themes that separate them. Compare it for *change*, never for value: a theme draws a rule wherever consecutive links disagree, and the strings themselves stay the app's business. Absent everywhere is the normal case and renders as one run. |
-| `newTab` | `boolean` | optional — Whether the link leaves the board, and should open in its own tab (0.16). Set by the app for a link an administrator marked as off-site — a chat server, a shop, a wiki. A theme that ignores it renders an ordinary link and is still correct, which is what keeps the field additive. A theme that honours it must pair `target="_blank"` with `rel="noopener noreferrer"`, because the opened page can otherwise reach back through `window.opener`. |
-| `submenu` | `readonly LinkModel[]` | optional — Links that belong under this one, for a menu that opens a level (0.16). One level only: the app never nests a submenu inside a submenu, so a theme that renders one level renders every menu there is. Absent is the normal case. A theme that ignores it drops those links from the page entirely rather than flattening them, so a theme meaning to support the board navigation should render them — under `:hover` and `:focus-within`, both, because a menu that only opens to a mouse is closed to a keyboard. |
+| `group` | `string` | optional — Link group. Insert a separator when consecutive values differ; do not depend on specific values. Absent values form one group. |
+| `newTab` | `boolean` | optional — Open in a new tab when true. Pair `target="_blank"` with `rel="noopener noreferrer"`. Optional since 0.16. |
+| `submenu` | `readonly LinkModel[]` | optional — One level of child links. Render them with keyboard and pointer access. The app does not nest submenus. Optional since 0.16. |
 
 ### LogoModel
 
-A board's logo, already resolved for this reader's colour scheme. Optional, and absent on most boards: a board with no logo renders its name in text, which is what every board did before this field existed. **The app resolves the scheme, not the theme.** A theme cannot do it, and the obvious attempt is wrong in the commonest case: `dark:hidden` matches the `.dark` class, and a reader who has chosen "system" has no class — their dark mode comes from a media query. They would get the light logo on a black page, which is the exact failure two images exist to prevent. The server knows the answer, so it gives one.
+Board logo sources prepared for the reader’s colour preference. If no logo is supplied, render the board name. Honour the optional dark source for system colour mode.
 
 | Field | Type | Notes |
 |---|---|---|
 | `src` | `string` | The image to render. Already the right one for a forced colour scheme. |
-| `darkSrc` | `string \| null` | A dark-scheme source, or `null`. Non-null means "wrap it in a `<picture>` and put this behind `(prefers-color-scheme: dark)`" — the reader is on "system" and has two images to choose between. Null covers three different situations a theme does not need to tell apart: one image, or a reader who has forced a scheme, in which case `src` is already the right one. |
+| `darkSrc` | `string \| null` | Optional dark source for a `<picture>` with `(prefers-color-scheme: dark)`. Use the primary source as its fallback. |
 | `alt` | `string` | Never empty — the board's name when the operator has set nothing. |
 
 ### OnlineMemberModel
 
-One visitor in the online list. `location` is **already resolved against the reader**: a forum they may not see arrives as the bare label, never as a title with a link. The theme renders what it is given and cannot leak what it was not.
+Online visitor. Location titles and links are filtered by reader permissions.
 
 | Field | Type | Notes |
 |---|---|---|
 | `userId` | `number \| null` | from `UserRefModel` — `null` when the account was deleted; `username` is still shown. |
 | `username` | `string` | from `UserRefModel` |
 | `profileHref` | `string \| null` | from `UserRefModel` |
-| `nameClass` | `string \| null \| undefined` | from `UserRefModel` — optional — A class carrying this member's group colour, or `null` for most members. **A theme should put this on whatever renders the name**, wherever a name appears. It is a class rather than a colour because the value has to differ between light and dark, and a `style` attribute cannot hold two answers — a reader on "system" has no `.dark` class at all, so the only place both can live is the stylesheet the app emits into `<head>`. A theme that ignores it renders the name in the ordinary text colour and is still correct, which is what makes the field additive. It will simply not show the board's own hierarchy, which most boards will notice. |
+| `nameClass` | `string \| null \| undefined` | from `UserRefModel` — optional — CSS class for the member’s group colour in both schemes, or null. Apply it to the member name. |
 | `location` | `{ readonly label: string; readonly href: string \| null }` | Where they are, as this reader may be told. Never null — see `label`. |
 | `isInvisible` | `boolean` | True only for staff, who see hidden members marked rather than absent. |
 | `lastSeen` | `TimeModel` |  |
 
 ### OptionModel
 
-One choice in a `<select>` or a radio group, with the current one marked. `isSelected` rather than a separate `selected` field on the parent: a theme renders options in a loop, and "which of these is current" answered per option is one comparison the theme does not have to write — and cannot write wrongly by comparing a string to a number.
+Select or radio option with its current state in `isSelected`. Render the provided value and label.
 
 | Field | Type | Notes |
 |---|---|---|
@@ -930,7 +927,7 @@ One choice in a `<select>` or a radio group, with the current one marked. `isSel
 | `icon` | `PanelNavIcon \| null` | What this item is about, for a themed icon. `null` on a child item. |
 | `count` | `number \| null` | A waiting count — the approval queue, unread messages — or `null`. |
 | `current` | `PanelNavCurrent \| null` | `null` when the reader is somewhere else entirely. |
-| `isRecord` | `boolean` | A page reached from elsewhere rather than from the rail — warning a member, editing one forum. It is shown as where you are and it is not a link, because a link to the page you are on that also needs an argument you no longer have is a dead end. Only ever present while the reader is on it. |
+| `isRecord` | `boolean` | Current contextual page reached outside the rail, such as a forum editor. Render as a label rather than a link. |
 
 ### PanelNavSectionModel
 
@@ -941,7 +938,7 @@ One choice in a `<select>` or a radio group, with the current one marked. `isSel
 | `icon` | `PanelNavIcon \| null` | from `PanelNavItemModel` — What this item is about, for a themed icon. `null` on a child item. |
 | `count` | `number \| null` | from `PanelNavItemModel` — A waiting count — the approval queue, unread messages — or `null`. |
 | `current` | `PanelNavCurrent \| null` | from `PanelNavItemModel` — `null` when the reader is somewhere else entirely. |
-| `isRecord` | `boolean` | from `PanelNavItemModel` — A page reached from elsewhere rather than from the rail — warning a member, editing one forum. It is shown as where you are and it is not a link, because a link to the page you are on that also needs an argument you no longer have is a dead end. Only ever present while the reader is on it. |
+| `isRecord` | `boolean` | from `PanelNavItemModel` — Current contextual page reached outside the rail, such as a forum editor. Render as a label rather than a link. |
 | `children` | `readonly PanelNavItemModel[]` | Available destinations, including those in closed sections so a menu can expand them without navigation. A record child appears only on its page. |
 | `isOpen` | `boolean` | The reader is on this section or inside it. |
 | `isOverview` | `boolean` | The panel's front page, which sits above the sections rather than among them. Exactly one section carries this. |
@@ -952,12 +949,12 @@ One choice in a `<select>` or a radio group, with the current one marked. `isSel
 |---|---|---|
 | `quoteHref` | `string \| null` |  |
 | `editHref` | `string \| null` |  |
-| `restoreHref` | `string \| null` | Where a soft-deleted post is put back. A separate field rather than a second meaning for `editHref`, because the two are never both offered: a deleted post cannot be edited, and a visible one has nothing to restore. A theme that renders both gets exactly one. |
+| `restoreHref` | `string \| null` | Restore action for a soft-deleted post. Mutually exclusive with editHref. |
 | `historyHref` | `string \| null` | optional |
 | `reportHref` | `string \| null` |  |
-| `warnHref` | `string \| null` | Warn this post's author, citing this post. Present for moderators only, and `null` for a post whose author is the viewer or a deleted account. Separate from `moderateHref` because a warning is aimed at the *person* and the post is only the evidence ��� which is also why the link carries the post id rather than living on the post's own moderation controls. |
-| `moderateHref` | `string \| null` | Reserved for per-post moderation controls that are not inline. Still `null` everywhere: per-post moderation is on checkboxes and a bar rather than a per-post link, so nothing fills this yet. It stays in the contract because the moderation control panel is where such a *page* would live, and removing a public field to add it back next feature is worse than a documented `null`. |
-| `rateHref` | `string \| null` | Rate this post's author, for this post. Null on your own post, on a board with reputation off, and for anybody without the permission. It carries the post so the rating is attached to *this* post rather than to the author generally — which is what makes one rating per post a meaningful rule. |
+| `warnHref` | `string \| null` | Link to warn the author about this post. Null for self, guests or insufficient permissions. |
+| `moderateHref` | `string \| null` | Reserved for non-inline moderation controls; currently null. Inline selection uses its separate model. |
+| `rateHref` | `string \| null` | Post-specific reputation action. Null for the current author, disabled reputation or insufficient permission. |
 
 ### PostAttachmentModel
 
@@ -983,17 +980,17 @@ The author block beside a post.
 | `userId` | `number \| null` | from `UserRefModel` — `null` when the account was deleted; `username` is still shown. |
 | `username` | `string` | from `UserRefModel` |
 | `profileHref` | `string \| null` | from `UserRefModel` |
-| `nameClass` | `string \| null \| undefined` | from `UserRefModel` — optional — A class carrying this member's group colour, or `null` for most members. **A theme should put this on whatever renders the name**, wherever a name appears. It is a class rather than a colour because the value has to differ between light and dark, and a `style` attribute cannot hold two answers — a reader on "system" has no `.dark` class at all, so the only place both can live is the stylesheet the app emits into `<head>`. A theme that ignores it renders the name in the ordinary text colour and is still correct, which is what makes the field additive. It will simply not show the board's own hierarchy, which most boards will notice. |
+| `nameClass` | `string \| null \| undefined` | from `UserRefModel` — optional — CSS class for the member’s group colour in both schemes, or null. Apply it to the member name. |
 | `avatarUrl` | `string \| null` |  |
-| `title` | `string \| null` | The display group's title, or a custom user title. Was `null` on every post the board has ever rendered — the field was in the contract from the start and nothing populated it, so every theme's postbit had a place for a member's standing and nothing to put in it. It comes from `users.display_group_id`, falling back to the primary group. |
-| `groups` | `readonly GroupTagModel[] \| undefined` | optional — Every group shown with this member's name — the display group first, then the rest of the groups they hold in display order, cut off at the board's *Maximum displayed groups* setting. `title` is always the first entry's title, so a theme written before this field existed keeps showing the display group and is still correct; a theme that renders this list should render it *instead of* `title`, not as well. Empty where the board resolved no groups at all — fall back to `title` there, which is also what carries a custom user title. |
-| `badge` | `LogoModel \| null \| undefined` | optional — The board's badge for this member's group, or `null`. Shaped exactly like `LogoModel` and for the same reason: the app has already chosen which of the two images this reader gets, so `darkSrc` is non-null only for a reader on "system", where the server cannot know. |
+| `title` | `string \| null` | Display-group title or custom member title; null when absent. |
+| `groups` | `readonly GroupTagModel[] \| undefined` | optional — Displayed groups, starting with the display group and limited by the board setting. Render this list instead of `title` when nonempty; otherwise use `title`, including custom titles. |
+| `badge` | `LogoModel \| null \| undefined` | optional — Group badge, or null. Uses LogoModel; darkSrc is provided only for the system colour scheme. |
 | `reputation` | `CountModel \| null \| undefined` | optional — This member's reputation, or `null` when the board has it switched off. A denormalised counter on `users`, so it costs the postbit nothing. |
 | `postCount` | `CountModel` |  |
 | `joinedAt` | `TimeModel \| null` |  |
 | `signatureHtml` | `string \| null` | Pre-rendered Markdown. Trusted output of the board's own renderer. |
-| `isOnline` | `boolean` | Whether this author has been active inside the online window. Already resolved against the reader, the same way the who's-online list is: an author browsing invisibly reads as offline for everyone without `modcp.access`, so a theme renders this flag as given and cannot light up a dot the board means to keep dark. |
-| `fields` | `readonly { readonly label: string; readonly value: string }[]` | Custom profile fields, for the ones an operator marked for the postbit and this viewer may see. The same `{label, value}` shape `MemberProfileModel.fields` uses, and **plain text** for the same reason: it is rendered as text by the theme, and a field that could carry markup is stored XSS on the board's heaviest page. Empty on a board with no custom fields, which is most of them. |
+| `isOnline` | `boolean` | Online status visible to this reader. Invisible authors appear offline without modcp.access. Render as supplied. |
+| `fields` | `readonly { readonly label: string; readonly value: string }[]` | Profile fields configured for post display and permitted for this viewer. Render labels and values as text. |
 
 ### PostBitModel
 
@@ -1004,13 +1001,13 @@ The author block beside a post.
 | `permalink` | `string` | `/thread/12-slug#post-3` — anchored by `number`, so the link says what the corner says. |
 | `author` | `PostAuthorModel` |  |
 | `bodyHtml` | `string` | Pre-rendered Markdown. |
-| `quoteSource` | `string` | @deprecated Since theme API 1.4, removed in 2.0. Use `post.id`. It existed so the client could assemble a quote out of the page. Quoting asks the server for a post **by id** now, which re-checks who may see it and cannot hand back what a deleted post used to say — so this is a copy of every post's source in the HTML of every thread page, for nobody. Still populated, because a theme could have read it; see `DEPRECATIONS`. |
+| `quoteSource` | `string` | @deprecated Since theme API 0.5; removal scheduled for 1.0. Use `post.id` to request a server-authorized quote. |
 | `postedAt` | `TimeModel` |  |
 | `editedNote` | `string \| null` | "Last edited by X on Y", already assembled, or `null`. |
 | `isFirstPost` | `boolean` |  |
 | `visibility` | `'visible' \| 'unapproved' \| 'deleted'` | A moderator sees deleted and unapproved posts, marked as such. |
-| `ignored` | `{ readonly authorUsername: string; readonly revealHref: string } \| null` | Set when this viewer ignores the author and has not revealed this post; `null` otherwise, which is the case on almost every post. The body is **withheld server-side** when this is set — `bodyHtml` is empty, the signature and custom fields are gone — rather than hidden with CSS, because "ignored" that ships the text to the browser is a preference rather than a feature. The post keeps its place and its number: filtering it out would give every viewer a different page size and make "#12" mean different posts to different people. A theme renders the placeholder and the link. Both are required — a hidden post with no way to see it is a hole in a conversation. |
-| `attachments` | `readonly PostAttachmentModel[]` | The files attached to this post. Empty on almost every post, and empty rather than absent so a theme has one shape to render. **Every entry is already downloadable**: a `pending` upload — one whose re-encode has not finished — and a failed one are not in this list, because a link to a file that is not there yet is worse than the file appearing a minute later. `thumbnailHref` is `null` for anything that is not an image, and for an image small enough that a thumbnail would be the same picture again. A theme showing an image inline uses `thumbnailHref ?? href` and gets the right answer in both cases. |
+| `ignored` | `{ readonly authorUsername: string; readonly revealHref: string } \| null` | Ignored-author placeholder, or null. When set, the app withholds body, signature and custom fields while preserving post position and numbering. Render the placeholder and reveal link. |
+| `attachments` | `readonly PostAttachmentModel[]` | Downloadable attachments only; pending and failed uploads are excluded. Use `thumbnailHref ?? href` for an inline image. Non-images and images without a smaller preview have a null thumbnail. |
 | `actions` | `PostActionsModel` |  |
 
 **`ignored.revealHref`**
@@ -1028,7 +1025,7 @@ A thread prefix; `token` supplies its styling.
 
 ### SearchAdvancedModel
 
-The advanced half of the search form. `isOpen` is the app saying whether the reader has anything in here — a returning search with an author or a date window set opens the panel so the narrowing that produced the results is visible rather than hidden behind a closed disclosure. A theme is free to render the panel open always; it must not render it *closed* when `isOpen` is true.
+Advanced search controls. Keep open when `isOpen` is true so applied filters are visible. Always-open rendering is also supported.
 
 | Field | Type | Notes |
 |---|---|---|
@@ -1049,7 +1046,7 @@ A filter that is on, and the href that turns it off.
 
 ### SearchChoiceModel
 
-One `<select>` in a search form or a results filter: the name to submit it under, a label, and the options with the current one marked. A theme renders these as it is handed them and in the order it is handed them. Which axes a search has is the app's decision, not a theme's, and a theme that enumerated them would lose one the day the app gained it.
+Select control with its submitted name, label and options. Render controls in the supplied order.
 
 | Field | Type | Notes |
 |---|---|---|
@@ -1059,7 +1056,7 @@ One `<select>` in a search form or a results filter: the name to submit it under
 
 ### SearchHitModel
 
-One search result: where it goes, and enough of it to decide whether to go. `excerptHtml` is the only HTML in this model, and it is the app's own: the search engine returns the matching fragment with the matched words wrapped in `<b>`, and nothing else survives — the post's own markup is stripped before the excerpt is cut, so a theme is styling emphasis, not rendering a post.
+Search result with destination and excerpt. `excerptHtml` contains app-generated match emphasis; source markup is stripped. Render other fields as text.
 
 | Field | Type | Notes |
 |---|---|---|
@@ -1072,7 +1069,7 @@ One search result: where it goes, and enough of it to decide whether to go. `exc
 
 ### SearchRefineModel
 
-Filtering and sorting for a results page, in the order of how often it is used: the count, the order, what is already narrowing the page, and — folded away until wanted — the filters themselves. ## Why the order is links and the filters are a form Changing the order is one decision and the commonest one, so `sorts` are links: one click, nothing to submit, and each href carries the filters already applied. Filtering is several decisions at once — a forum *and* a date, say — so `choices` are a GET form with one submit, and the result is a URL. `applied` is the reverse of both: one chip per filter that is on, each with an href that removes only itself. A reader with JavaScript off gets all three, because all three are ordinary HTML. ## The space this is allowed to take Keep the count, sort links and applied filters together above the results. Labeled controls can use columns on wider screens and stack on phones so long forum and author names remain readable. Preserve visible labels and usable touch targets without making the page scroll horizontally. ## Counts, and what they count An option's label carries the number of results it would leave, counted against the search *without* the forum and author filters applied — so the counts stay put as a reader moves between forums instead of collapsing to the one they are already in. `note` carries the caveat when the board is big enough that the count is a floor rather than a total.
+Results filters: count, sort links, applied-filter removal links and a GET form. Preserve existing filters in supplied hrefs and hidden inputs. Option counts exclude forum/author narrowing; `note` identifies lower-bound counts. Keep labels, touch targets and long values readable without horizontal page scrolling.
 
 | Field | Type | Notes |
 |---|---|---|
@@ -1112,7 +1109,7 @@ A checkbox: on when `isOn`, submitted as `value` under `field`.
 
 ### SelectionModel
 
-One inline-moderation checkbox, or `null` when this viewer has no business selecting rows. Plain data, and it has to be: the *form* it belongs to carries a Server Action reference, and such references never cross the theme contract. So the app renders the form — below the listing, where a bar of buttons belongs — and the theme renders a checkbox that says which form it belongs to. `formId` is the whole trick, and it is why this works with scripting off. HTML's `form` attribute associates a control with a form **by id, anywhere in the document**, so the checkboxes can live inside table rows, list items or article elements without the listing having to be wrapped in a `<form>` — which it cannot be, because `ForumDisplay` already renders a mark-read form and nested forms are not a thing browsers will parse.
+Inline-moderation checkbox or null when unavailable. Associate it with the app-owned form using `formId` and HTML’s `form` attribute. Do not nest forms around listings.
 
 | Field | Type | Notes |
 |---|---|---|
@@ -1146,12 +1143,12 @@ One tab in a strip of view tabs.
 | `isLocked` | `boolean` |  |
 | `isUnread` | `boolean` |  |
 | `isMoved` | `boolean` | Set when the thread is a move stub; the row renders as a redirect. |
-| `visibility` | `'visible' \| 'unapproved' \| 'deleted'` | optional — Whether this thread is hidden from ordinary members. `'visible'` on almost every row; a listing only ever carries `'unapproved'` or `'deleted'` for a viewer allowed to see held or removed threads, so a theme that marks them — a badge, a tint — is drawing something only staff will meet. Optional: a theme written before this field treats every row as visible, which is what the reader saw anyway. |
+| `visibility` | `'visible' \| 'unapproved' \| 'deleted'` | optional — Thread visibility. Unapproved/deleted rows are supplied only when the viewer is permitted to see them. Render the corresponding state. |
 | `lastPost` | `LastPostModel \| null` |  |
 
 ### ThreadWatchModel
 
-`ThreadViewModel.watch` — the header's one-tap subscribe/unsubscribe toggle. `action` is already resolved to whichever direction flips `subscribed`: a theme never branches on `subscribed` to pick a URL, only to pick a label — "Watch" over `action` when `false`, "Watching" over the same `action` when `true`. Subscribing this way always uses the board's default cadence; a member who wants a slower one still has the cadence picker in `ThreadViewModel.regions.afterContent`, which this toggle sits beside rather than replaces.
+Thread watch toggle. Submit the supplied `action`; use `subscribed` for the label/state. It uses the board’s default cadence. The full cadence selector remains in `afterContent`.
 
 | Field | Type | Notes |
 |---|---|---|
@@ -1176,7 +1173,7 @@ A user as they appear attached to content.
 | `userId` | `number \| null` | `null` when the account was deleted; `username` is still shown. |
 | `username` | `string` |  |
 | `profileHref` | `string \| null` |  |
-| `nameClass` | `string \| null \| undefined` | optional — A class carrying this member's group colour, or `null` for most members. **A theme should put this on whatever renders the name**, wherever a name appears. It is a class rather than a colour because the value has to differ between light and dark, and a `style` attribute cannot hold two answers — a reader on "system" has no `.dark` class at all, so the only place both can live is the stylesheet the app emits into `<head>`. A theme that ignores it renders the name in the ordinary text colour and is still correct, which is what makes the field additive. It will simply not show the board's own hierarchy, which most boards will notice. |
+| `nameClass` | `string \| null \| undefined` | optional — CSS class for the member’s group colour in both schemes, or null. Apply it to the member name. |
 
 ### ViewerModel
 
@@ -1190,9 +1187,8 @@ Who is looking. The only actor data a theme is given.
 | `profileHref` | `string \| null` |  |
 | `avatarUrl` | `string \| null` |  |
 | `canAccessAdminCp` | `boolean` | Whether to render the admin-panel link. A *rendering* hint, resolved by the Authorizer already — a theme must never conclude anything about permissions on its own, and themes stay out of authorization entirely. |
-| `canAccessModCp` | `boolean` | Whether to render the moderation link. Same shape and same rule as `canAccessAdminCp`: a rendering hint the Authorizer has already decided. Group-level only, which is a real limitation rather than an oversight: a per-forum appointee's queue exists and is reachable, but answering "does this person moderate anything" for them costs the tree, and the shell renders on every page. The moderation control panel is where that link earns its query. |
+| `canAccessModCp` | `boolean` | Rendering hint for moderator-panel access, already resolved by the Authorizer. The destination still checks access; this field does not grant it. |
 
 ## Scheduled removals
 
-Nothing is deprecated in v0.24. Nothing can be: this is the first
-frozen contract, so there is no earlier promise to withdraw.
+No deprecations in v0.24.
diff --git a/docs/start/introduction.md b/docs/start/introduction.md
index d5d0a50dd..0fec58915 100644
--- a/docs/start/introduction.md
+++ b/docs/start/introduction.md
@@ -1,34 +1,24 @@
-# Start here
+# Meith documentation
 
-Meith is forum software for running your own community. Members read discussions, write posts and send messages; moderators look after conversations; administrators manage the community; operators maintain the hosting.
+Meith is forum software. A board contains forums; forums contain threads; threads contain posts and replies.
 
-## Choose what you want to do
-
-| I want to… | Start with |
+| Task | Guide |
 |---|---|
-| See how Meith works | [Try a local preview](quickstart.md) |
-| Join or use an existing board | [Member guide](../members/member-guide.md) |
-| Set up hosting | [Choose a deployment](../operations/deployment.md) |
-| Open a newly installed community | [Launch checklist](../administration/first-steps.md) |
-| Manage members, forums or moderation | [Community administration](../administration/organiser-guide.md) |
-| Maintain an existing server | [Server operations](../operations/operating.md) |
-| Move from another forum | [Import MyBB or phpBB](../operations/migrating.md) |
-| Build a plugin or theme | [Build extensions](../extensions/extensions.md) |
-| Connect another application | [Make your first API request](../integrations/api-quickstart.md) |
-| Work on Meith's source code | [Contribute to Meith](../contributing/development.md) |
-
-## Learn the vocabulary
-
-A **board** is one community's website. A **category** groups related forums. A **forum** contains **threads**, and a thread contains the opening **post** and its replies. A **group** gives members permissions and allowances.
-
-An **administrator** manages the board through its admin panel. A **moderator** has permission to manage content in particular forums. An **operator** looks after deployment, backups and infrastructure. One person can hold several roles, but each role has a different set of tasks.
-
-## Understand what you install
+| Try a preview | [Quickstart](quickstart.md) |
+| Read and post | [Member guide](../members/member-guide.md) |
+| Install a board | [Deployment](../operations/deployment.md) |
+| Configure a new community | [Setup checklist](../administration/first-steps.md) |
+| Manage forums and members | [Administration](../administration/organiser-guide.md) |
+| Maintain hosting | [Operations](../operations/operating.md) |
+| Import MyBB or phpBB | [Migration](../operations/migrating.md) |
+| Create a theme or plugin | [Extensions](../extensions/extensions.md) |
+| Connect an application | [API quickstart](../integrations/api-quickstart.md) |
+| Change Meith's source | [Development](../contributing/development.md) |
 
-A board repository chooses the Meith version, themes and plugins. PostgreSQL stores community data. Uploaded files need persistent storage and their own backup coverage. A worker or scheduled tick processes background work.
+## Requirements
 
-A **theme** changes presentation. A **plugin** adds capabilities such as a calendar, awards or paid memberships. Features available on a board depend on what its operator has installed and enabled.
+A deployed board needs PostgreSQL, persistent upload storage, email delivery and a worker or scheduler. Its repository selects the Meith version, themes and plugins.
 
-Most reading and posting works without JavaScript. Optional enhancements include previews, suggestions and browser notifications.
+Administrators manage settings and members. Moderators manage content in assigned forums. Operators maintain hosting, backups and upgrades. One person can perform several roles.
 
-For the technical layout, read [Architecture](../contributing/architecture.md).
+Themes control appearance; plugins add features. Most reading and posting works without JavaScript.
diff --git a/docs/start/quickstart.md b/docs/start/quickstart.md
index 9912597cb..3877f8fd3 100644
--- a/docs/start/quickstart.md
+++ b/docs/start/quickstart.md
@@ -1,10 +1,6 @@
-# Try Meith locally
+# Local preview
 
-Create a local board with sample content. You need Node.js 22 or newer and npm. No database, hosting account or Docker installation is required for this preview.
-
-## Create and start the preview
-
-Run these commands in a terminal, in the directory where you keep projects:
+Requires Node.js 22 or newer and npm. Run in your projects directory:
 
 ```sh
 npx create-meith my-board
@@ -13,18 +9,11 @@ npm install
 npm run dev
 ```
 
-Open <http://localhost:3000>. Browse the forums, threads, profiles and search screens. Stop the development server with Ctrl+C.
-
-## Understand the sample data
-
-Without `DATABASE_URL`, the board uses **fixture mode**: a fixed sample dataset for browsing and visual development. It does not save posts or provide a working installer, member accounts or plugin storage.
-
-If you want to register, write posts or try moderation, continue with [Create a writable local board](../operations/local-board.md). If you want other people to use the community, [choose a deployment](../operations/deployment.md).
-
-## Find your board files
-
-`package.json` pins the engine and installed packages. `meith.config.ts` selects themes and plugins. `board.plugins.json` records plugin packages; `meith.plugins.ts` is its generated registry. The scaffold also includes deployment files.
+Open <http://localhost:3000>. Stop the server with Ctrl+C.
 
-[Board configuration](../operations/configuration.md) explains what belongs in code, environment variables and the admin panel.
+Without `DATABASE_URL`, Meith uses fixed sample data. The preview does not save posts, create accounts or provide writable plugin storage.
 
-To change Meith itself, use the separate [contributor setup](../contributing/development.md).
+- To register and post, [connect a local database](../operations/local-board.md).
+- To host a community, [choose a deployment](../operations/deployment.md).
+- To change themes and plugins, see [Board configuration](../operations/configuration.md).
+- To develop Meith itself, use the [source checkout](../contributing/development.md).
diff --git a/packages/api/src/reference.ts b/packages/api/src/reference.ts
index adf160998..74dea744f 100644
--- a/packages/api/src/reference.ts
+++ b/packages/api/src/reference.ts
@@ -52,62 +52,27 @@ export function renderReference(document: OpenApiDocument): string {
   push(
     '# REST API v1',
     '',
-    '<!--',
-    '  GENERATED FILE — do not edit.',
-    '',
-    '  Written by scripts/api-docs.mts from the OpenAPI document the board serves,',
-    '  which is itself generated from packages/api/src/{routes,schema,tokens}.ts. Run',
-    '  `pnpm api:docs` after changing any of them; `pnpm verify` and CI run',
-    '  `pnpm api:docs:check` and fail when this file, docs/reference/openapi.json and the code',
-    '  disagree.',
-    '-->',
+    '<!-- GENERATED FILE — do not edit. Run pnpm api:docs. -->',
     '',
     `${routes.length} endpoints, ${scopes.length} scopes. Base path: \`/api/v1\`.`,
     '',
-    'The machine-readable form of everything below — request and response schemas,',
-    'parameters, status codes, scopes and rate-limit costs — is the OpenAPI 3 document',
-    'at [`docs/reference/openapi.json`](openapi.json), which a board also serves live at',
-    '`/api/v1/openapi.json`. Point a generator at that rather than reading this table',
-    'into code.',
+    'Request/response schemas are in [`docs/reference/openapi.json`](openapi.json), also served at `/api/v1/openapi.json`.',
     '',
     '## Authentication',
     '',
-    'A bearer token in the `Authorization` header:',
+    'Send a bearer token in the `Authorization` header:',
     '',
-    '```',
+    '```text',
     'Authorization: Bearer forum_pat_<lookup>_<secret>',
     '```',
     '',
-    'A token is a **restriction on an actor, never a grant to one**. Every request',
-    'resolves the owner’s permissions and asks the Authorizer, exactly as a page does,',
-    '*in addition to* checking the token’s scope. A token can therefore never reach',
-    'anything its owner could not; revoking the owner’s access revokes the token’s in',
-    'the same instant, because nothing is baked in at creation.',
-    '',
-    'Every authentication failure is one `401` with one message. The reason — expired,',
-    'revoked, unknown, malformed — is in the board’s logs and not in the response:',
-    'telling a caller "expired" confirms the token was real.',
+    'Each request checks the token scope and the owner’s current permissions. Tokens cannot grant access their owner lacks. Invalid, expired and revoked tokens return the same `401`; diagnostic details stay in server logs.',
     '',
     '## Reading without a token',
     '',
-    `${anonymous.length} of the ${routes.length} endpoints answer an unauthenticated request. They are all reads,`,
-    'and they resolve as **the board’s guest** — the same actor a logged-out browser',
-    'gets — through the same Authorizer and the same visibility filter as every other',
-    'request. A forum a guest may not see is not in `GET /forums` for them, its threads',
-    '404, and its posts never appear in search. A board whose forums are all closed to',
-    'guests therefore has no anonymous API surface at all, without anything having to',
-    'be configured for that to be true.',
-    '',
-    'An offline board answers `503` to an anonymous caller, exactly as it serves the',
-    'offline page to a browser, and answers normally to a token whose owner may see a',
-    'board that is offline.',
-    '',
-    'Sending a token to one of these endpoints is not the same as sending none: the',
-    'token’s scope is still required, because a token only ever narrows what its',
-    'owner could do. A token without `forums:read` gets `missing_scope` from',
-    '`GET /forums` even though a stranger with no token at all gets an answer.',
+    `${anonymous.length} endpoints support guest reads. Guest permissions and content visibility apply. All writes require authentication.`,
     '',
-    'Nothing writable is anonymous. Every write is `401` without a token.',
+    'An offline board returns `503` unless the authenticated owner may view it. Supplying a token requires the endpoint scope even when the endpoint supports guest access.',
     '',
     '| Method | Path |',
     '|---|---|',
@@ -117,51 +82,21 @@ export function renderReference(document: OpenApiDocument): string {
     '',
     ...scopes.map((scope) => `- \`${scope}\``),
     '',
-    'Every scope on that list is required by at least one endpoint below, and a test',
-    'holds it that way: a scope no route consumes is a checkbox that grants nothing,',
-    'which reads as a permission and is not one.',
-    '',
-    'There is deliberately no administrative scope at all. A token is a long-lived',
-    'string in somebody’s CI configuration; reconfiguring a board should need a person',
-    'at a keyboard with the admin panel’s re-authentication in front of them. For the',
-    'same reason there is no moderation scope: removing somebody else’s post through',
-    'the API is `posts:write` resolving to a moderator’s own permissions, not a',
-    'separate grant a token can carry on its own.',
-    '',
-    'A token stored before a scope was retired keeps working. The scope is dropped as',
-    'the token is read, so it simply no longer carries it — the endpoints it still has',
-    'a scope for answer as before, and the rest answer `missing_scope`.',
+    'There are no separate administration or moderation scopes. A content write still requires the owner’s applicable permissions. Retired scopes are removed when a stored token is read; remaining scopes continue to work.',
     '',
     '## Issuing a token',
     '',
-    'Tokens are issued from **API tokens** in the control panel. Issuing one is treated',
-    'as a destructive operation: it asks for the administrator’s password again, on the',
-    'same clock as banning a member or moving a forum, because a bearer string that',
-    'leaves the building is at least as consequential. Revoking one does',
-    'not ask — a revocation is the thing you want to be quick during an incident, and',
-    'it is undone by issuing a new token rather than by recovering the old one.',
-    '',
-    '**Expires in (days)** takes a whole number of days, or nothing at all for a token',
-    'that never expires. Anything else — a fraction, a word, a number in exponent',
-    'notation — is refused and mints nothing, rather than being read as "never".',
+    'Open **Admin → API tokens** and reauthenticate to issue a token. **Expires in (days)** accepts whole days or a blank value for no expiry. Revocation does not require reauthentication; revoked tokens cannot be restored.',
     '',
     '## Rate limits',
     '',
-    'Metered in **units of work, not requests** — a search is not a forum listing, and',
-    'a limit that prices them the same invites the expensive call. Every response,',
-    'refused or not, carries `x-ratelimit-limit`, `x-ratelimit-remaining` and',
-    '`x-ratelimit-reset`; a refusal is `429` with `retry-after`.',
+    `Authenticated budget: **${window.window.budget} units per ${window.window.seconds} seconds** per token.`,
     '',
-    `A token spends against **${window.window.budget} units per ${window.window.seconds} seconds**, held against the token. An`,
-    'unauthenticated caller has no token to hold a budget against, so theirs is held',
-    `against their address prefix and is smaller: **${window.anonymousWindow.budget} units per ${window.anonymousWindow.seconds} seconds**. The`,
-    'board’s ordinary anti-flood limits apply to writes on top of both, exactly as they',
-    'do to the web forms.',
+    `Guest budget: **${window.anonymousWindow.budget} units per ${window.anonymousWindow.seconds} seconds** per address prefix.`,
     '',
-    '## Endpoints',
+    'Endpoint costs consume units. Metered responses include `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset`. A budget refusal returns `429` and `retry-after`. Board posting/flood limits also apply.',
     '',
-    'Full schemas for every request and response are in the OpenAPI document; this',
-    'table is the map.',
+    '## Endpoints',
     '',
     '| Method | Path | Scope | Cost | Token | Summary |',
     '|---|---|---|---|---|---|',
@@ -178,69 +113,34 @@ export function renderReference(document: OpenApiDocument): string {
     '',
     '## Errors',
     '',
-    'Every error is the same shape, so a client parses one thing:',
-    '',
     '```json',
     '{ "error": { "code": "missing_scope", "message": "…", "requestId": "…" } }',
     '```',
     '',
-    '`code` is stable and machine-readable; `message` is for a human reading a',
-    'terminal. `requestId` is the board’s correlation id — quote it in a report and an',
-    'operator can find the request in their logs.',
-    '',
-    'The API refuses a request before it reaches the board with these:',
+    'Use `code` for handling, `message` for display and `requestId` to locate server logs.',
     '',
     '| Status | Code | Meaning |',
     '|---|---|---|',
-    '| 400 | `bad_request` | A query parameter was missing or unusable. |',
-    '| 401 | `unauthenticated` | No bearer token, or the token is not valid. |',
-    '| 403 | `missing_scope` | Authenticated, but this token lacks the endpoint’s scope. |',
-    '| 403 | `owner_unavailable` | The account the token belongs to can no longer act. |',
-    '| 404 | `no_such_route` | No such endpoint. |',
-    '| 404 | `not_found` | No such resource, or none this caller may see. |',
-    '| 429 | `rate_limited` | Over the window budget. See `retry-after`. |',
-    '| 501 | `not_implemented` | Declared in the registry, handler not yet written. |',
-    '| 503 | `board_offline` | The board is offline and this caller may not see it. |',
-    '',
-    'Past that point a request is running the same domain command the web form runs,',
-    'so it fails the way the web form fails, with the board’s own error codes and the',
-    'message translated into the board’s language:',
-    '',
-    '| Status | Code | Meaning |',
-    '|---|---|---|',
-    '| 403 | `FORBIDDEN` | The owner’s permissions do not allow this, whatever the token carries. |',
-    '| 404 | `NOT_FOUND` | The thing named in the request is not there. |',
-    '| 409 | `CONFLICT` | Something else changed underneath the request. |',
-    '| 422 | `VALIDATION` | The board’s posting rules refused the contents — too long, too soon, a subject missing. |',
-    '| 429 | `RATE_LIMITED` | Over one of the board’s anti-flood limits, which are separate from the API budget. |',
-    '',
-    'A resource the caller may not see is `404`, never `403`. Telling a stranger that',
-    'a thread exists but is not for them is the same leak as showing it to them. A',
-    '`403` means the caller can see the thing and may not do this to it.',
+    '| 400 | `bad_request` | Missing or invalid query parameter |',
+    '| 401 | `unauthenticated` | Missing or invalid token |',
+    '| 403 | `missing_scope` | Required scope absent |',
+    '| 403 | `owner_unavailable` | Token owner cannot act |',
+    '| 404 | `no_such_route` | Unknown endpoint |',
+    '| 404 | `not_found` | Resource missing or hidden |',
+    '| 429 | `rate_limited` | API budget exceeded |',
+    '| 501 | `not_implemented` | Registered endpoint has no handler |',
+    '| 503 | `board_offline` | Board unavailable to this caller |',
+    '| 403 | `FORBIDDEN` | Domain permission denied |',
+    '| 404 | `NOT_FOUND` | Domain resource missing |',
+    '| 409 | `CONFLICT` | Conflicting state |',
+    '| 422 | `VALIDATION` | Domain input/posting rule failed |',
+    '| 429 | `RATE_LIMITED` | Board flood limit exceeded |',
+    '',
+    'Hidden resources return `404`; a visible resource can return `403` for an action the owner cannot perform. Domain messages use the board language.',
     '',
     '## Webhooks',
     '',
-    'The board POSTs a JSON body and four headers:',
-    '',
-    '| Header | Meaning |',
-    '|---|---|',
-    '| `x-forum-event` | The topic. |',
-    '| `x-forum-delivery` | Stable across retries — de-duplicate on this. |',
-    '| `x-forum-timestamp` | Unix seconds, and part of the signed material. |',
-    '| `x-forum-signature` | `sha256=<hex>` of `HMAC(secret, "<timestamp>.<body>")`. |',
-    '',
-    // biome-ignore lint/suspicious/noTemplateCurlyInString: prose about the signed material, not an interpolation
-    'Verify by recomputing the HMAC over `` `${timestamp}.${rawBody}` `` and comparing in',
-    'constant time — **and reject anything older than five minutes**. The timestamp is',
-    'inside the signed material precisely so it cannot be edited; checking the',
-    'signature without checking the age leaves every captured delivery replayable',
-    'forever.',
-    '',
-    'Delivery is queued, never inline. Failures retry with exponential backoff and',
-    'jitter (30s doubling, capped at an hour, six attempts) and then **dead-letter**',
-    'rather than disappearing, so an operator can retry them once the receiver is',
-    'fixed. A `410 Gone` stops the retries immediately: the receiver has said the',
-    'endpoint is finished.',
+    'Follow [Webhooks](../integrations/webhooks.md) to subscribe, verify signatures, deduplicate deliveries and handle retries.',
     '',
   )
 
diff --git a/packages/plugin-kit/src/hooks.test.ts b/packages/plugin-kit/src/hooks.test.ts
index 5672c985c..b44e40e45 100644
--- a/packages/plugin-kit/src/hooks.test.ts
+++ b/packages/plugin-kit/src/hooks.test.ts
@@ -17,7 +17,7 @@ describe('the hook registry', () => {
     for (const name of HOOK_NAMES) {
       const spec = HOOKS[name]
       expect(['filter', 'event']).toContain(spec.kind)
-      expect(spec.purpose.length).toBeGreaterThan(20)
+      expect(spec.purpose.trim()).not.toBe('')
     }
   })
 
diff --git a/packages/plugin-kit/src/hooks.ts b/packages/plugin-kit/src/hooks.ts
index b3bea2182..96dc14d6d 100644
--- a/packages/plugin-kit/src/hooks.ts
+++ b/packages/plugin-kit/src/hooks.ts
@@ -62,23 +62,20 @@ export const HOOKS = {
   /* ---- Content rendering ---- */
   'markdown.parse.text': {
     kind: 'filter',
-    purpose: 'The raw Markdown source, before it is parsed. Last chance to rewrite input.',
+    purpose: 'Raw Markdown before parsing.',
   },
   'markdown.render.html': {
     kind: 'filter',
-    purpose:
-      'Rendered HTML, after the renderer has constructed it. Anything added here is ' +
-      'trusted output and nothing escapes it afterwards.',
+    purpose: 'Rendered HTML. Replacement markup is trusted and is not escaped afterwards.',
   },
   'markdown.directives': {
     kind: 'filter',
     purpose:
-      'The declarative directive list, so a plugin can add a `:::name` block or ' +
-      '`:name[…]` span without core changes. Board-wide: rendered bodies are stored and shared, so the set cannot depend on who is reading.',
+      'Board-wide directives for `:::name` blocks and `:name[…]` spans. The list must not depend on the reader because rendered bodies are shared.',
   },
   'post.body.html': {
     kind: 'filter',
-    purpose: 'One post’s rendered body, in the context of the thread it is being read in.',
+    purpose: 'Rendered post body with thread and viewer context.',
   },
   'signature.html': {
     kind: 'filter',
@@ -86,9 +83,7 @@ export const HOOKS = {
   },
   'smilies.list': {
     kind: 'filter',
-    purpose:
-      'The smilie set substituted at render. Board-wide, for the same reason ' +
-      'the directive list is.',
+    purpose: 'Board-wide smilie substitutions. The list must not depend on the reader.',
   },
   'word-filter.patterns': {
     kind: 'filter',
@@ -115,15 +110,11 @@ export const HOOKS = {
   'view.forum-jump': {
     kind: 'filter',
     purpose:
-      'The jump box model. A plugin adding a destination must give it a real ' +
-      'forum id — the route re-authorises whatever is submitted.',
+      'Forum jump options. Destinations require real forum IDs; the route rechecks permission on submission.',
   },
   'view.announcement': {
     kind: 'filter',
-    purpose:
-      'One announcement, on its way to the theme. Its body is already rendered ' +
-      'HTML from the board\u2019s own renderer, so a plugin replacing it is ' +
-      'replacing trusted markup — the one hook where that is true of a body.',
+    purpose: 'Announcement model with rendered HTML. Replacement body markup is trusted.',
   },
   'view.board-index': {
     kind: 'filter',
@@ -131,7 +122,7 @@ export const HOOKS = {
   },
   'view.forum-row': {
     kind: 'filter',
-    purpose: 'One forum row in a listing. Runs once per row — keep it cheap.',
+    purpose: 'Forum listing row. Runs once per row.',
   },
   'view.thread-row': {
     kind: 'filter',
@@ -139,9 +130,7 @@ export const HOOKS = {
   },
   'view.post-bit': {
     kind: 'filter',
-    purpose:
-      'One post as the theme will receive it. The busiest hook on the board: it ' +
-      'runs once per post on every thread page.',
+    purpose: 'Post model. Runs once per post on each thread page.',
   },
   'view.post-actions': {
     kind: 'filter',
@@ -161,13 +150,11 @@ export const HOOKS = {
   },
   'view.latest-threads': {
     kind: 'filter',
-    purpose:
-      'The index sidebar’s newest-threads panel. Runs again on every refresh ' +
-      'of the live region, not only on the page load — keep it cheap.',
+    purpose: 'Latest threads panel. Runs on initial render and each live refresh.',
   },
   'view.latest-posts': {
     kind: 'filter',
-    purpose: 'The index sidebar’s newest-posts panel. Same refresh cost as view.latest-threads.',
+    purpose: 'Latest posts panel. Runs on initial render and each live refresh.',
   },
   'view.pagination': {
     kind: 'filter',
@@ -180,48 +167,41 @@ export const HOOKS = {
   'view.search-results': {
     kind: 'filter',
     purpose:
-      'One page of search results. Already checked against the reader — a hit ' +
-      'a plugin adds here has not been, and will be shown to whoever asked.',
+      'Search results authorised for the viewer. Added rows require separate visibility checks.',
   },
   'view.discovery-view': {
     kind: 'filter',
     purpose:
-      'A discovery listing — new posts, today, unanswered — with its tabs. ' +
-      'Same warning as the search results: the rows arrive authorised.',
+      'Discovery listing and tabs. Existing rows are authorised; added rows require separate visibility checks.',
   },
   'view.auth-page': {
     kind: 'filter',
     purpose:
-      'The sign-in, register and password-reset page around its form. The form ' +
-      'itself is a region, not a value: nothing here can change what it posts to.',
+      'Sign-in, registration or password-reset page. The app supplies the form as a rendered region.',
   },
   'view.panel-shell': {
     kind: 'filter',
-    purpose:
-      'The frame around a control panel, including the links to the other ' +
-      'panels this viewer may reach. Adding a link grants nothing.',
+    purpose: 'Control panel frame and links. Adding links does not grant access.',
   },
   'view.panel-nav': {
     kind: 'filter',
-    purpose:
-      'A control panel’s section rail, with the current section already ' +
-      'resolved. Runs on every panel page.',
+    purpose: 'Control panel navigation with the current section. Runs on each panel page.',
   },
   'view.panel-page': {
     kind: 'filter',
-    purpose: 'One control-panel page’s heading block. Runs on every panel page.',
+    purpose: 'Control panel page heading. Runs on each panel page.',
   },
   'view.panel-section': {
     kind: 'filter',
-    purpose: 'One labelled section inside a panel page. Runs once per section.',
+    purpose: 'Panel section. Runs once per section.',
   },
   'view.error-notice': {
     kind: 'filter',
-    purpose: 'The error page model. Runs on the page that renders when things are broken.',
+    purpose: 'Error page model.',
   },
   'view.shell': {
     kind: 'filter',
-    purpose: 'The page frame’s model. Runs on every page including the error pages.',
+    purpose: 'Page frame. Runs on every page, including error pages.',
   },
   'view.notice': {
     kind: 'filter',
@@ -249,9 +229,7 @@ export const HOOKS = {
   },
   'view.quick-reply': {
     kind: 'filter',
-    purpose:
-      'The quick-reply island’s model, at the foot of a thread. The reply form itself is ' +
-      'app-rendered and arrives as `children`.',
+    purpose: 'Quick-reply model. The app supplies the reply form as `children`.',
   },
   'view.editor-toolbar': {
     kind: 'filter',
@@ -260,8 +238,7 @@ export const HOOKS = {
   'view.redirect-notice': {
     kind: 'filter',
     purpose:
-      'The interstitial shown after a mutation, before the meta refresh fires. The target is re-checked against the board after the filter runs, so this ' +
-      'cannot send a member off-site.',
+      'Post-mutation redirect notice. The target is checked again after filtering and must remain on the board.',
   },
 
   /* ---- Posting ---- */
@@ -299,7 +276,7 @@ export const HOOKS = {
   },
   'post.delete.before': {
     kind: 'event',
-    purpose: 'A post is about to be soft-deleted. Observation only: refusing is a permission.',
+    purpose: 'Post scheduled for soft deletion. Cannot veto deletion.',
   },
   'post.deleted': {
     kind: 'event',
@@ -332,12 +309,11 @@ export const HOOKS = {
   'attachment.upload.validate': {
     kind: 'filter',
     purpose:
-      'Validation messages for an upload, after the magic-byte check. A plugin may ' +
-      'refuse a file core would accept; it can never accept one core refused.',
+      'Upload validation after file-type checks. Can reject an accepted file; cannot accept a file rejected by core.',
   },
   'attachment.uploaded': {
     kind: 'event',
-    purpose: 'A file finished uploading and re-encoding.',
+    purpose: 'Upload stored. Image processing may still be pending.',
   },
   'attachment.deleted': {
     kind: 'event',
@@ -349,9 +325,7 @@ export const HOOKS = {
   },
   'poll.voted': {
     kind: 'event',
-    purpose:
-      'A vote was cast, once per option chosen. It fires again when a poll that allows ' +
-      're-voting takes a replacement.',
+    purpose: 'Vote recorded. Runs for each chosen option, including replacement votes.',
   },
   'rating.recorded': {
     kind: 'event',
@@ -361,7 +335,7 @@ export const HOOKS = {
   /* ---- Moderation ---- */
   'report.created': {
     kind: 'event',
-    purpose: 'Something was reported. The hook a notifier or a webhook wants.',
+    purpose: 'Report created.',
   },
   'report.resolved': {
     kind: 'event',
@@ -391,9 +365,7 @@ export const HOOKS = {
   /* ---- Identity ---- */
   'user.register.validate': {
     kind: 'filter',
-    purpose:
-      'Validation messages for a registration. Where a custom question or an ' +
-      'external blocklist belongs.',
+    purpose: 'Registration validation messages. Use for additional questions or blocklists.',
   },
   'user.registered': {
     kind: 'event',
@@ -405,9 +377,7 @@ export const HOOKS = {
   },
   'user.login.attempted': {
     kind: 'event',
-    purpose:
-      'A sign-in was attempted, with the outcome. Never carries the password or the ' +
-      'session token.',
+    purpose: 'Sign-in attempt and outcome. Excludes passwords and session tokens.',
   },
   'user.logged-in': {
     kind: 'event',
@@ -435,7 +405,7 @@ export const HOOKS = {
   },
   'user.merged': {
     kind: 'event',
-    purpose: 'Two accounts were merged. Carries the winner and the account that went.',
+    purpose: 'Account merge with retained and removed account IDs.',
   },
   'user.deleted': {
     kind: 'event',
@@ -453,9 +423,7 @@ export const HOOKS = {
   },
   'mail.send.before': {
     kind: 'filter',
-    purpose:
-      'A queued message, before it is handed to the mail driver. Subject, body and ' +
-      'recipient; returning `null` drops it.',
+    purpose: 'Queued email before driver submission. Return `null` to suppress it.',
   },
   'mail.sent': {
     kind: 'event',
@@ -486,12 +454,12 @@ export const HOOKS = {
   'search.results': {
     kind: 'filter',
     purpose:
-      'A page of results, already permission-filtered in SQL. A plugin may reorder or ' +
-      'drop; adding a row here would add one the viewer may not see.',
+      'Search results authorised in SQL. Reorder or remove rows; check visibility before adding any.',
   },
   'feed.items': {
     kind: 'filter',
-    purpose: 'The items of a feed, rendered as a guest. Anything added is public.',
+    purpose:
+      'Feed entries after visibility filtering. May contain private member content; do not share entries between requests. Added rows require separate visibility checks.',
   },
   'sitemap.entries': {
     kind: 'filter',
@@ -525,13 +493,11 @@ export const HOOKS = {
   },
   'plugin.enabled': {
     kind: 'event',
-    purpose: 'A plugin was enabled — including this one, which is how it learns it is on.',
+    purpose: 'Plugin enabled. Includes the enabled plugin itself.',
   },
   'plugin.disabled': {
     kind: 'event',
-    purpose:
-      'A plugin was disabled, by an operator or by the host after repeated failures. ' +
-      'Carries the reason.',
+    purpose: 'Plugin disabled by an operator or after repeated failures, with the reason.',
   },
 } as const satisfies Readonly<Record<string, HookSpec>>
 
diff --git a/packages/plugin-kit/src/payloads.ts b/packages/plugin-kit/src/payloads.ts
index 9fec89b5d..90cd1f315 100644
--- a/packages/plugin-kit/src/payloads.ts
+++ b/packages/plugin-kit/src/payloads.ts
@@ -417,7 +417,7 @@ export interface HookSignatures {
       readonly publishedAt: string
       readonly summary: string
     }[]
-    /** Always a guest: a feed is cached under a shared URL. */
+    /** Scope only; entries may use guest or private member visibility. */
     context: { readonly feed: 'board' | 'forum' | 'thread' }
   }
   'sitemap.entries': {
diff --git a/packages/plugin-kit/src/regions.ts b/packages/plugin-kit/src/regions.ts
index 30ec68829..b748cbaed 100644
--- a/packages/plugin-kit/src/regions.ts
+++ b/packages/plugin-kit/src/regions.ts
@@ -17,9 +17,7 @@ export const PLUGIN_REGIONS = {
     context: 'The viewer, with the reader’s locale and a translator.',
   },
   'postbit.badges': {
-    purpose:
-      'Beside a post author’s name. Runs once per post on every thread page — the ' +
-      'most expensive region on the board, and the one to keep trivial.',
+    purpose: 'Author badges. Runs once per post; avoid per-post queries.',
     context:
       'The viewer, the post id and the author id, with the reader’s locale and a translator.',
   },
@@ -30,19 +28,13 @@ export const PLUGIN_REGIONS = {
   },
   'threadrow.badges': {
     purpose:
-      'Beside a thread’s title in a listing, to mark threads across a forum page. A ' +
-      'batch region: unlike every other region it runs once per page, not once per ' +
-      'row — a listing of twenty threads is one call, returning a badge per thread ' +
-      'id — because a forum page is on a tight budget and a per-row region there is ' +
-      'twenty calls before the page has drawn a thing.',
+      'Thread-list badges. Runs once per page with visible thread references; returns badges keyed by thread ID.',
     context:
       'The viewer and the page’s visible threads, each as a thread id and its author ' +
       'id, with the reader’s locale and a translator.',
   },
   'thread.header': {
-    purpose:
-      'Above the first post of a thread, below its title. Runs once per thread page, ' +
-      'so unlike postbit.* it can afford to read from the plugin’s own tables.',
+    purpose: 'Below the thread title and above the first post. Runs once per thread page.',
     context:
       'The viewer, the thread id and the thread author’s id, with the reader’s locale and ' +
       'a translator.',
diff --git a/packages/testkit/src/load/budgets.ts b/packages/testkit/src/load/budgets.ts
index 6ce6257cd..431a76205 100644
--- a/packages/testkit/src/load/budgets.ts
+++ b/packages/testkit/src/load/budgets.ts
@@ -16,7 +16,7 @@ export const BUDGETS: readonly Budget[] = [
     work: 'listThread(limit 20) on a long thread',
     p95Ms: 50,
     kind: 'target',
-    why: 'The single most requested page on any forum. Everything else is rounding.',
+    why: 'Baseline first-page thread read.',
   },
   {
     id: 'thread-page-deep',
@@ -24,7 +24,7 @@ export const BUDGETS: readonly Budget[] = [
     work: 'listThread(afterId) far into a long thread',
     p95Ms: 60,
     kind: 'target',
-    why: 'The keyset claim. Under OFFSET this degrades with depth; it must not.',
+    why: 'Checks cursor pagination deep into a thread.',
   },
   {
     id: 'forum-page-first',
@@ -32,7 +32,7 @@ export const BUDGETS: readonly Budget[] = [
     work: 'listForum(limit 20) on the busiest forum',
     p95Ms: 50,
     kind: 'target',
-    why: 'Sticky-first ordering over the largest thread set on the board.',
+    why: 'Checks pinned-first ordering in the largest forum.',
   },
   {
     id: 'forum-page-deep',
@@ -40,7 +40,7 @@ export const BUDGETS: readonly Budget[] = [
     work: 'listForum(after cursor) deep into the busiest forum',
     p95Ms: 60,
     kind: 'target',
-    why: 'Same keyset claim on the other axis, and the one an archive crawler hits.',
+    why: 'Checks cursor pagination deep into a forum.',
   },
   {
     id: 'board-index',
@@ -48,7 +48,7 @@ export const BUDGETS: readonly Budget[] = [
     work: 'listListing() — every forum with its counters and last post',
     p95Ms: 80,
     kind: 'target',
-    why: 'One query for the whole tree, and the page every visitor lands on.',
+    why: 'Checks the forum tree with stored counts and latest-post data.',
   },
   {
     id: 'visible-forums',
@@ -56,7 +56,7 @@ export const BUDGETS: readonly Budget[] = [
     work: 'forumIdsWhere(actor, thread.view)',
     p95Ms: 40,
     kind: 'target',
-    why: 'Every list page pays this before it reads anything, so its cost multiplies.',
+    why: 'Measures the authorisation scope used before content reads.',
   },
   {
     id: 'discovery-latest',
@@ -64,13 +64,7 @@ export const BUDGETS: readonly Budget[] = [
     work: 'Discovery page 1, scoped to visible forums',
     p95Ms: 150,
     kind: 'target',
-    why:
-      'Ordered across the whole board rather than within one forum — the widest scan, ' +
-      'and the most run-to-run variance of anything here. It was budgeted at 80ms ' +
-      'against a typical p95 near 50, which is 1.6× and breaks the 2–3× rule stated ' +
-      'at the top of this file; it duly went red on a noisy run at 110ms with a 621ms ' +
-      'outlier. Raised to 150ms — not to make it pass, but because the original number ' +
-      'was set tighter than the methodology the rest of the table follows.',
+    why: 'Checks cross-forum ordering with headroom for run-to-run variance.',
   },
   {
     id: 'search-common',
@@ -78,14 +72,7 @@ export const BUDGETS: readonly Budget[] = [
     work: 'Relevance search for a term matching 96% of the board',
     p95Ms: 300,
     kind: 'target',
-    why:
-      'The worst query a member can trigger, and the one budget the first load run failed. ' +
-      'Relevance ordering is not indexable: `ts_rank_cd` has to score every matching ' +
-      'row before it can name the top twenty, so a term matching 2.26M of 2.34M posts ' +
-      'cost a p95 of 5.5 seconds with the GIN index present and used. The fix was to ' +
-      'bound the ranked set to the most recent 20,000 matches, which measured 98ms — ' +
-      'and changes nothing for any term selective enough that the window holds the ' +
-      'whole match set, which is every real query. Recorded in mybb-parity.md.',
+    why: 'Measures relevance ranking for a broad match set. Ranking is bounded to the most recent 20,000 matches.',
   },
   {
     id: 'search-rare',
@@ -93,11 +80,7 @@ export const BUDGETS: readonly Budget[] = [
     work: 'Full-text search for a term with ~1,000 matches',
     p95Ms: 200,
     kind: 'target',
-    why:
-      'Separated because a fast rare-term search hides a slow common-term one, and here ' +
-      'it did: before the window bound these two differed by a factor of 130, and only ' +
-      'the pair made it visible that the cost was the match count rather than the code. ' +
-      'They still differ, by about 5×, which is the residual and expected shape.',
+    why: 'Measures selective full-text search separately from common-term ranking.',
   },
   {
     id: 'member-profile',
@@ -105,7 +88,7 @@ export const BUDGETS: readonly Budget[] = [
     work: 'Profile with counters for a prolific member',
     p95Ms: 60,
     kind: 'target',
-    why: "A post count computed live is an aggregate over the member's whole history.",
+    why: 'Checks profile reads using stored counters.',
   },
 ]
 
diff --git a/packages/testkit/src/load/cohorts.test.ts b/packages/testkit/src/load/cohorts.test.ts
index 15f9281fb..7a28558e1 100644
--- a/packages/testkit/src/load/cohorts.test.ts
+++ b/packages/testkit/src/load/cohorts.test.ts
@@ -73,7 +73,7 @@ describe('the cohort ladder', () => {
 
   it('explains why every rung is on the ladder', () => {
     for (const cohort of COHORTS) {
-      expect(cohort.why.length).toBeGreaterThan(40)
+      expect(cohort.why.trim()).not.toBe('')
     }
   })
 
@@ -85,10 +85,10 @@ describe('the cohort ladder', () => {
     expect(last?.members).toBeGreaterThanOrEqual(first!.members * 10)
   })
 
-  it('makes every limit say it is a limit and point at the decision', () => {
+  it('identifies limits as unsuitable operating targets and requires measurement', () => {
     for (const cohort of COHORTS.filter((c) => c.kind === 'limit')) {
-      expect(cohort.why).toMatch(/limit, not a target/)
-      expect(cohort.why).toMatch(/open question/)
+      expect(cohort.why).toMatch(/not a recommended operating load/)
+      expect(cohort.why).toMatch(/Measure additional processes or pool capacity/)
     }
   })
 
diff --git a/packages/testkit/src/load/cohorts.ts b/packages/testkit/src/load/cohorts.ts
index c55969c88..42172acf8 100644
--- a/packages/testkit/src/load/cohorts.ts
+++ b/packages/testkit/src/load/cohorts.ts
@@ -36,66 +36,42 @@ export const COHORTS: readonly Cohort[] = [
     members: 50,
     p95Ms: 80,
     kind: 'target',
-    why:
-      'A quiet evening on a small board. Five requests a second against a pool three ' +
-      'deep never waits for a connection, which makes this rung the control: a p95 ' +
-      'here is the mix itself, and every rung above it is measured against this one.',
+    why: 'Baseline at five requests per second.',
   },
   {
     id: 'members-250',
     members: 250,
     p95Ms: 80,
     kind: 'target',
-    why:
-      'A busy hour on an established board. Twenty-five requests a second is the ' +
-      'first rung where two reads are routinely in flight at once, and the pool has ' +
-      'three connections to serve them with.',
+    why: 'Measures 25 requests per second.',
   },
   {
     id: 'members-1000',
     members: 1000,
     p95Ms: 80,
     kind: 'target',
-    why:
-      'What being linked to from somewhere large puts on one process. A hundred ' +
-      'requests a second, and the budget is deliberately the same number as the two ' +
-      'quieter rungs: this load is not supposed to cost a member anything.',
+    why: 'Measures 100 requests per second against the baseline budget.',
   },
   {
     id: 'members-2500',
     members: 2500,
     p95Ms: 100,
     kind: 'target',
-    why:
-      'Two hundred and fifty requests a second through one process. The last rung ' +
-      'that behaves like an idle board, and the one to read as the headroom figure.',
+    why: 'Measures 250 requests per second.',
   },
   {
     id: 'members-4250',
     members: 4250,
     kind: 'target',
     p95Ms: 300,
-    why:
-      'Four hundred and twenty-five requests a second, and the last rung that still ' +
-      'behaves. The budget is wider than the rungs below it not because this load is ' +
-      'expected to cost more — it measures around 90ms — but because it is close ' +
-      'enough to the shoulder that the number moves between runs, and a budget set to ' +
-      'the good runs would fail on the ordinary ones.',
+    why: 'Measures 425 requests per second near the recorded saturation point.',
   },
   {
     id: 'members-5000',
     members: 5000,
     kind: 'limit',
     p95Ms: 4_000,
-    why:
-      'Over the shoulder, and here to say where the shoulder is. This is a limit, not ' +
-      'a target: five hundred requests a second is past what one process at the ' +
-      'default pool of three absorbs, the requests still start on time — lateness ' +
-      'stays near zero — and then they queue inside the pool, which is why the p95 ' +
-      'goes to seconds while every rung below it is in milliseconds. It is recorded ' +
-      'so the shoulder cannot move down quietly. Where it should be is an open ' +
-      'question for whoever sizes a deployment: more processes, a larger pool, or ' +
-      'accepting that a board this busy has outgrown one of them.',
+    why: 'At 500 requests per second, the recorded run queues inside the three-connection pool. This ceiling detects regressions; it is not a recommended operating load. Measure additional processes or pool capacity before deploying at this rate.',
   },
 ]
 
diff --git a/packages/theme-kit/src/api.ts b/packages/theme-kit/src/api.ts
index c5571e29c..38a59b196 100644
--- a/packages/theme-kit/src/api.ts
+++ b/packages/theme-kit/src/api.ts
@@ -70,12 +70,7 @@ export const DEPRECATIONS: readonly Deprecation[] = [
     since: '0.5',
     removeIn: '1.0',
     replacement: 'PostBitModel.post.id',
-    reason:
-      'It carried a post’s Markdown source to the client so the multiquote ' +
-      'button could assemble a quote in the browser. Quoting resolves a post ' +
-      'by id on the server now — which re-checks who may see it and cannot go ' +
-      'stale — so this ships every post’s full source to every reader for ' +
-      'nobody. No theme has ever rendered it; the field says so itself.',
+    reason: 'Quote by post ID on the server to recheck visibility and retrieve current content.',
   },
 ]
 
diff --git a/packages/theme-kit/src/slots.ts b/packages/theme-kit/src/slots.ts
index 8c8480041..73267f674 100644
--- a/packages/theme-kit/src/slots.ts
+++ b/packages/theme-kit/src/slots.ts
@@ -8,9 +8,7 @@ export interface SlotSpec {
 export const SLOTS = {
   Shell: {
     kind: 'server',
-    purpose:
-      'The outermost frame: skip link, header, main landmark, footer. Wraps ' +
-      'every page including the error pages.',
+    purpose: 'Page frame with skip link, header, main landmark and footer, including error pages.',
   },
   Header: {
     kind: 'server',
@@ -19,8 +17,7 @@ export const SLOTS = {
   UserPanel: {
     kind: 'server',
     purpose:
-      'Greeting and account links, or the sign-in prompt for a guest. Varies ' +
-      'by actor, which is why no page wrapping it may be cached globally.',
+      'Actor-specific greeting and account links, or guest sign-in prompt. Do not cache globally.',
   },
   Navigation: {
     kind: 'server',
@@ -32,17 +29,12 @@ export const SLOTS = {
   },
   Notice: {
     kind: 'server',
-    purpose:
-      'A board-wide announcement or a flash message. Server-rendered so a ' +
-      'notice is present in the first response, not after hydration.',
+    purpose: 'Server-rendered flash message or board notice.',
   },
 
   Announcement: {
     kind: 'server',
-    purpose:
-      'One announcement: a dated, authored notice shown above the forums. ' +
-      'Distinct from Notice, which is a flash message about what the viewer ' +
-      'just did — these are for everybody and last until they expire.',
+    purpose: 'Dated, authored announcement shown above forums until expiry.',
   },
 
   BoardIndex: {
@@ -69,16 +61,11 @@ export const SLOTS = {
   LatestThreads: {
     kind: 'server',
     purpose:
-      'The newest threads on the board, for the index sidebar. Server, not ' +
-      'client, even though the panel refreshes itself: the app polls a Server ' +
-      'Action that renders this slot again, so the live half is one island ' +
-      'around the region rather than a client component per panel.',
+      'Newest threads, rendered on the server and refreshed through the app’s shared live region.',
   },
   LatestPosts: {
     kind: 'server',
-    purpose:
-      'The newest posts on the board, with an excerpt of each. Same server ' +
-      'rendering and same refresh path as LatestThreads.',
+    purpose: 'Newest posts and excerpts, refreshed with LatestThreads.',
   },
 
   ForumDisplay: {
@@ -95,9 +82,7 @@ export const SLOTS = {
   },
   Pagination: {
     kind: 'server',
-    purpose:
-      'Page links. Server-rendered and href-based: paging must work with ' +
-      'JavaScript disabled, so this can never become an island.',
+    purpose: 'Resolved page links that work without JavaScript.',
   },
 
   ThreadView: {
@@ -106,9 +91,7 @@ export const SLOTS = {
   },
   PostBit: {
     kind: 'server',
-    purpose:
-      'One post: author block, body, footer. **The** load-bearing server ' +
-      'slot — see this file’s header for what marking it `client` costs.',
+    purpose: 'Post author, body and footer, rendered on the server.',
   },
   PostActions: {
     kind: 'server',
@@ -143,85 +126,53 @@ export const SLOTS = {
 
   SearchForm: {
     kind: 'server',
-    purpose:
-      'The search form. A GET form with named inputs, so a search is a URL ' +
-      'that can be linked and cached.',
+    purpose: 'GET search form with supplied input names.',
   },
   SearchResults: {
     kind: 'server',
-    purpose:
-      'The results page for one search: what matched, an excerpt of each hit, ' +
-      'and the form that narrows the set. Separate from SearchForm because a ' +
-      'result list is a listing and shares nothing with a filter panel but the ' +
-      'word "search".',
+    purpose: 'Search hits, excerpts and filtering controls.',
   },
 
   DiscoveryView: {
     kind: 'server',
-    purpose:
-      'The body of a discovery listing — new posts, today, unanswered, and a ' +
-      'member’s own threads and replies. One slot for all of them: they differ ' +
-      'in what the query selected, never in what a reader is looking at.',
+    purpose: 'Discovery listing with the viewer’s available tabs.',
   },
 
   PanelShell: {
     kind: 'server',
-    purpose:
-      'The frame around a control panel: the navigation rail, the links to the ' +
-      'other panels a viewer may reach, and the page beside them. Rendered for ' +
-      'the member, moderator and admin panels alike — `panel` says which.',
+    purpose: 'Member, moderator or admin panel frame with navigation and content.',
   },
   PanelNav: {
     kind: 'server',
-    purpose:
-      'A control panel’s section navigation. Server, not client: which section ' +
-      'is open is resolved from the request path before rendering, so the rail ' +
-      'arrives correct rather than after hydration, and a panel needs no ' +
-      'JavaScript to know where it is.',
+    purpose: 'Panel navigation with current state resolved by the app before rendering.',
   },
   PanelPage: {
     kind: 'server',
-    purpose:
-      'One control-panel page: its heading, the line under it, the controls ' +
-      'beside it, and the body. Also the frame for the account, moderation and ' +
-      'messaging pages that are panel-shaped without being in a panel.',
+    purpose: 'Panel page heading, supporting text, actions and body.',
   },
   PanelSection: {
     kind: 'server',
-    purpose:
-      'A labelled section inside a panel page. Rendered by the page among its ' +
-      'content rather than around it, which is why it is not part of PanelPage.',
+    purpose: 'Labelled content section inside a panel page.',
   },
 
   AuthPage: {
     kind: 'server',
-    purpose:
-      'Signing in, registering, resetting a password, asking for a new ' +
-      'confirmation link. One slot for all of them: the same card with a ' +
-      'different form in it, and the form itself is an app-rendered region ' +
-      'because every one of them posts to a Server Action.',
+    purpose: 'Authentication-page frame with an app-rendered form.',
   },
 
   ForumJump: {
     kind: 'server',
     purpose:
-      'The jump box at the foot of every page. A GET form with a submit ' +
-      'control, never a select that navigates on change — choosing an option ' +
-      'is not committing to it, and arrow-keying through one would teleport a ' +
-      'keyboard user to the first forum in the list.',
+      'GET forum selector with a submit button; keyboard selection must not navigate automatically.',
   },
 
   RedirectNotice: {
     kind: 'server',
-    purpose:
-      'The MyBB-style interstitial: "your post was made, continuing in a ' +
-      'moment", with a real link for anyone the meta refresh does not carry.',
+    purpose: 'Post-action notice with a meta-refresh destination and fallback link.',
   },
   ErrorNotice: {
     kind: 'server',
-    purpose:
-      'The themed body of an error or not-found page. Must not depend on the ' +
-      'database: it is what renders when the database is the thing that failed.',
+    purpose: 'Error or not-found content. Must render without database access.',
   },
 } as const satisfies Readonly<Record<string, SlotSpec>>
 
diff --git a/packages/theme-kit/src/view-models.ts b/packages/theme-kit/src/view-models.ts
index 6ee109a6c..549488c80 100644
--- a/packages/theme-kit/src/view-models.ts
+++ b/packages/theme-kit/src/view-models.ts
@@ -1,38 +1,4 @@
-/**
- * The view models slots are handed, and the rule they all obey.
- *
- * These types are the **public API for themes**. Per docs/contributing/nextjs-conventions.md
- * adding a field is a minor change; renaming or removing one needs a deprecation
- * cycle. The theme-kit slot contract freezes them.
- *
- * ## The rule: view models are plain JSON-shaped data
- *
- * No `Date`, no `Map`/`Set`, no class instances, no functions. Not because
- * React's Flight protocol cannot carry them — React 19 can serialise a `Date`
- * perfectly well — but because a view model has three consumers and only the
- * JSON subset survives all three:
- *
- *  1. a **server slot**, which renders it;
- *  2. a **client slot**, across the RSC boundary;
- *  3. the **public REST API**, which returns view models as JSON.
- *
- * A `Date` also pushes formatting into every theme, and formatting a date is
- * timezone- and locale-dependent: the server does not know the viewer's zone,
- * so a theme calling `toLocaleString()` renders one string on the server and a
- * different one in the browser — a hydration mismatch that appears only for
- * users outside the server's timezone. So a timestamp crosses as `TimeModel`:
- * the machine value for `<time datetime>`, and the string the app already
- * formatted using the viewer's stored zone.
- *
- * The rule is not a convention. `_PlainDataCheck` below is a compile-time proof
- * over every model in this file, and `view-models.type-test.ts` proves the proof
- * still has teeth.
- *
- * **Field-level scope.** These models carry what Phases 2–3 render. They are
- * deliberately narrow: a field added later is additive, whereas a field invented
- * now to seem complete is a guess that themes will have written markup against
- * by the time it turns out to be wrong.
- */
+/** Public theme models contain JSON-shaped data. Use TimeModel for timestamps and prepared labels for locale-dependent values. `_PlainDataCheck` and the type tests enforce this contract. Additive fields follow the API version policy; removals and renames require deprecation. */
 
 import type { ReactNode } from 'react'
 
@@ -43,24 +9,7 @@ import type { SlotName } from './slots'
  * The plain-data constraint
  * ------------------------------------------------------------------ */
 
-/**
- * `T` with everything that is not JSON-shaped mapped to `never`.
- *
- * Used as a *predicate*, not a transform: if `T` is already plain data then
- * `Serialisable<T>` equals `T` and `T extends Serialisable<T>` holds. If any
- * field is a `Date`, a function, a `Map` or a `Promise`, that field becomes
- * `never` and the assignment fails, naming the offending model.
- *
- * **`Date`, `Map`, `Set`, `RegExp` and `Promise` are all rejected** — by the
- * function clause, not by a clause of their own. Every one of them exposes its
- * entire API as methods, so mapping it produces an object whose members are
- * `never` and the assignment fails. An explicit branch naming those five was
- * written first and then deleted: no mutation could make it matter, and a clause
- * no test can kill is a clause that will quietly stop being true.
- *
- * **Limit, stated plainly:** a class instance with only data fields is
- * structurally indistinguishable from a plain object, so this cannot catch one.
- */
+/** Maps non-JSON-shaped fields to `never` for compile-time validation. Methods reject Date, Map, Set, RegExp and Promise values. Data-only class instances are structurally indistinguishable from plain objects and cannot be detected. */
 export type Serialisable<T> = T extends string | number | boolean | null | undefined
   ? T
   : T extends readonly (infer E)[]
@@ -71,34 +20,7 @@ export type Serialisable<T> = T extends string | number | boolean | null | undef
         ? { readonly [K in keyof T]: Serialisable<T[K]> }
         : never
 
-/**
- * Two keys are exempt — `children` and `regions` — and nothing else.
- *
- * A `ReactNode` is not plain data, but passing rendered children through a
- * component is a first-class React capability rather than a loophole: the parent
- * renders the tree and the RSC boundary carries it.
- *
- * ## Why `regions` exists at all: slots are flat
- *
- * **A slot never renders another slot.** `ThreadView` does not call `PostBit`;
- * the page does, and hands `ThreadView` the rendered list. The reason is
- * mechanical: rendering a slot requires the *resolved theme*, and there is no way
- * to get one inside a slot — React Context is not available to Server
- * Components, and threading the theme through props would put a map of functions
- * into a contract whose whole point is that it holds none.
- *
- * It also keeps inheritance honest. If `ThreadView` imported `PostBit` directly,
- * a child theme overriding `PostBit` would be ignored inside the parent's
- * `ThreadView` — inheritance that works for some slots and silently not others.
- * With composition in the page, exactly one place resolves slots, so an override
- * applies everywhere.
- *
- * A container therefore declares its nested regions as `ReactNode` under
- * `regions`, and the page fills them. The cost, stated: a theme can restyle
- * within a region and re-order the regions it is given, but cannot invent a new
- * relationship between two slots — for that it overrides the container and the
- * page composition stays as it is. This is revisited if a real theme needs more.
- */
+/** `children` and `regions` may carry rendered React nodes. The app resolves and renders nested slots; a slot must not resolve another slot. This preserves child-theme overrides without passing theme functions through models. */
 type ModelData<T> = Omit<T, 'children' | 'regions'>
 
 type IsPlainData<T> = ModelData<T> extends Serialisable<ModelData<T>> ? true : false
@@ -127,34 +49,11 @@ export interface CountModel {
 export interface LinkModel {
   readonly label: string
   readonly href: string
-  /**
-   * Which run of links this one belongs to, for themes that separate them.
-   *
-   * Compare it for *change*, never for value: a theme draws a rule wherever
-   * consecutive links disagree, and the strings themselves stay the app's
-   * business. Absent everywhere is the normal case and renders as one run.
-   */
+  /** Link group. Insert a separator when consecutive values differ; do not depend on specific values. Absent values form one group. */
   readonly group?: string
-  /**
-   * Whether the link leaves the board, and should open in its own tab (0.16).
-   *
-   * Set by the app for a link an administrator marked as off-site — a chat
-   * server, a shop, a wiki. A theme that ignores it renders an ordinary link
-   * and is still correct, which is what keeps the field additive. A theme that
-   * honours it must pair `target="_blank"` with `rel="noopener noreferrer"`,
-   * because the opened page can otherwise reach back through `window.opener`.
-   */
+  /** Open in a new tab when true. Pair `target="_blank"` with `rel="noopener noreferrer"`. Optional since 0.16. */
   readonly newTab?: boolean
-  /**
-   * Links that belong under this one, for a menu that opens a level (0.16).
-   *
-   * One level only: the app never nests a submenu inside a submenu, so a theme
-   * that renders one level renders every menu there is. Absent is the normal
-   * case. A theme that ignores it drops those links from the page entirely
-   * rather than flattening them, so a theme meaning to support the board
-   * navigation should render them — under `:hover` and `:focus-within`, both,
-   * because a menu that only opens to a mouse is closed to a keyboard.
-   */
+  /** One level of child links. Render them with keyboard and pointer access. The app does not nest submenus. Optional since 0.16. */
   readonly submenu?: readonly LinkModel[]
 }
 
@@ -172,15 +71,7 @@ export interface ViewerModel {
    * on its own, and themes stay out of authorization entirely.
    */
   readonly canAccessAdminCp: boolean
-  /**
-   * Whether to render the moderation link. Same shape and same rule as
-   * `canAccessAdminCp`: a rendering hint the Authorizer has already decided.
-   *
-   * Group-level only, which is a real limitation rather than an oversight: a
-   * per-forum appointee's queue exists and is reachable, but answering "does
-   * this person moderate anything" for them costs the tree, and the shell
-   * renders on every page. The moderation control panel is where that link earns its query.
-   */
+  /** Rendering hint for moderator-panel access, already resolved by the Authorizer. The destination still checks access; this field does not grant it. */
   readonly canAccessModCp: boolean
 }
 
@@ -190,31 +81,11 @@ export interface UserRefModel {
   readonly userId: number | null
   readonly username: string
   readonly profileHref: string | null
-  /**
-   * A class carrying this member's group colour, or `null` for most members.
-   *
-   * **A theme should put this on whatever renders the name**, wherever a name
-   * appears. It is a class rather than a colour because the value has to differ
-   * between light and dark, and a `style` attribute cannot hold two answers — a
-   * reader on "system" has no `.dark` class at all, so the only place both can
-   * live is the stylesheet the app emits into `<head>`.
-   *
-   * A theme that ignores it renders the name in the ordinary text colour and is
-   * still correct, which is what makes the field additive. It will simply not
-   * show the board's own hierarchy, which most boards will notice.
-   */
+  /** CSS class for the member’s group colour in both schemes, or null. Apply it to the member name. */
   readonly nameClass?: string | null | undefined
 }
 
-/**
- * One of the groups shown with a member's name.
- *
- * `nameClass` works exactly like `UserRefModel.nameClass` and exists for the
- * same reason: the group's colour differs between light and dark, so it
- * arrives as a class the app's `<head>` stylesheet defines rather than as a
- * colour. Put it on whatever renders the title; a theme that ignores it shows
- * the title in its ordinary text colour and is still correct.
- */
+/** A displayed membership group. Apply `nameClass` to its name and use the supplied title and badge. */
 export interface GroupTagModel {
   readonly title: string
   readonly nameClass?: string | null | undefined
@@ -235,14 +106,7 @@ export interface PrefixModel {
   readonly token: string | null
 }
 
-/**
- * One choice in a `<select>` or a radio group, with the current one marked.
- *
- * `isSelected` rather than a separate `selected` field on the parent: a theme
- * renders options in a loop, and "which of these is current" answered per option
- * is one comparison the theme does not have to write — and cannot write wrongly
- * by comparing a string to a number.
- */
+/** Select or radio option with its current state in `isSelected`. Render the provided value and label. */
 export interface OptionModel {
   /** Submitted as the form value. Opaque to the theme. */
   readonly value: string
@@ -282,41 +146,16 @@ export interface ThreadRowModel {
   readonly isUnread: boolean
   /** Set when the thread is a move stub; the row renders as a redirect. */
   readonly isMoved: boolean
-  /**
-   * Whether this thread is hidden from ordinary members. `'visible'` on almost
-   * every row; a listing only ever carries `'unapproved'` or `'deleted'` for a
-   * viewer allowed to see held or removed threads, so a theme that marks them —
-   * a badge, a tint — is drawing something only staff will meet. Optional: a
-   * theme written before this field treats every row as visible, which is what
-   * the reader saw anyway.
-   */
+  /** Thread visibility. Unapproved/deleted rows are supplied only when the viewer is permitted to see them. Render the corresponding state. */
   readonly visibility?: 'visible' | 'unapproved' | 'deleted'
   readonly lastPost: LastPostModel | null
 }
 
-/**
- * Paging, fully resolved.
- *
- * The obvious API — a page count plus a function to build an href — is
- * impossible here, and that is the constraint doing its job: a function cannot
- * cross to a client slot or into an API response. The app resolves the window
- * and hands over links, which also means paging is plain anchors and therefore
- * works with JavaScript disabled.
- */
+/** Resolved pagination labels and hrefs. Render links as provided; do not construct URLs in the theme. */
 export interface PaginationModel {
   readonly page: number
   readonly pageCount: number
-  /**
-   * Whether `pageCount` is the real number of pages or only what has been
-   * proved so far.
-   *
-   * A keyset-paged list knows the page it is on and whether another one
-   * follows; it does not know how many there are, and counting rows to find
-   * out is the query the cursor exists to avoid. So `pageCount` is a floor
-   * when this is `false`, and a theme that prints "3 of 4" from it is telling
-   * the reader something nobody checked. Print the page on its own instead,
-   * and keep "of N" for the lists that do know.
-   */
+  /** True when `pageCount` is an exact total. Otherwise it is a lower bound: display the current page without “of N”. */
   readonly pageCountIsExact: boolean
   readonly pages: readonly {
     readonly page: number
@@ -334,34 +173,11 @@ export interface PaginationModel {
 /** The author block beside a post. */
 export interface PostAuthorModel extends UserRefModel {
   readonly avatarUrl: string | null
-  /**
-   * The display group's title, or a custom user title.
-   *
-   * Was `null` on every post the board has ever rendered — the field was in the
-   * contract from the start and nothing populated it, so every theme's postbit
-   * had a place for a member's standing and nothing to put in it. It comes from
-   * `users.display_group_id`, falling back to the primary group.
-   */
+  /** Display-group title or custom member title; null when absent. */
   readonly title: string | null
-  /**
-   * Every group shown with this member's name — the display group first, then
-   * the rest of the groups they hold in display order, cut off at the board's
-   * *Maximum displayed groups* setting.
-   *
-   * `title` is always the first entry's title, so a theme written before this
-   * field existed keeps showing the display group and is still correct; a
-   * theme that renders this list should render it *instead of* `title`, not as
-   * well. Empty where the board resolved no groups at all — fall back to
-   * `title` there, which is also what carries a custom user title.
-   */
+  /** Displayed groups, starting with the display group and limited by the board setting. Render this list instead of `title` when nonempty; otherwise use `title`, including custom titles. */
   readonly groups?: readonly GroupTagModel[] | undefined
-  /**
-   * The board's badge for this member's group, or `null`.
-   *
-   * Shaped exactly like `LogoModel` and for the same reason: the app has
-   * already chosen which of the two images this reader gets, so `darkSrc` is
-   * non-null only for a reader on "system", where the server cannot know.
-   */
+  /** Group badge, or null. Uses LogoModel; darkSrc is provided only for the system colour scheme. */
   readonly badge?: LogoModel | null | undefined
   /**
    * This member's reputation, or `null` when the board has it switched off.
@@ -373,68 +189,24 @@ export interface PostAuthorModel extends UserRefModel {
   readonly joinedAt: TimeModel | null
   /** Pre-rendered Markdown. Trusted output of the board's own renderer. */
   readonly signatureHtml: string | null
-  /**
-   * Whether this author has been active inside the online window.
-   *
-   * Already resolved against the reader, the same way the who's-online list
-   * is: an author browsing invisibly reads as offline for everyone without
-   * `modcp.access`, so a theme renders this flag as given and cannot light up
-   * a dot the board means to keep dark.
-   */
+  /** Online status visible to this reader. Invisible authors appear offline without modcp.access. Render as supplied. */
   readonly isOnline: boolean
-  /**
-   * Custom profile fields, for the ones an operator marked for the postbit and
-   * this viewer may see.
-   *
-   * The same `{label, value}` shape `MemberProfileModel.fields` uses, and
-   * **plain text** for the same reason: it is rendered as text by the theme,
-   * and a field that could carry markup is stored XSS on the board's heaviest
-   * page. Empty on a board with no custom fields, which is most of them.
-   */
+  /** Profile fields configured for post display and permitted for this viewer. Render labels and values as text. */
   readonly fields: readonly { readonly label: string; readonly value: string }[]
 }
 
 export interface PostActionsModel {
   readonly quoteHref: string | null
   readonly editHref: string | null
-  /**
-   * Where a soft-deleted post is put back.
-   *
-   * A separate field rather than a second meaning for `editHref`, because the
-   * two are never both offered: a deleted post cannot be edited, and a visible
-   * one has nothing to restore. A theme that renders both gets exactly one.
-   */
+  /** Restore action for a soft-deleted post. Mutually exclusive with editHref. */
   readonly restoreHref: string | null
   readonly historyHref?: string | null
   readonly reportHref: string | null
-  /**
-   * Warn this post's author, citing this post.
-   *
-   * Present for moderators only, and `null` for a post whose author is the
-   * viewer or a deleted account. Separate from `moderateHref` because a warning
-   * is aimed at the *person* and the post is only the evidence ��� which is also
-   * why the link carries the post id rather than living on the post's own
-   * moderation controls.
-   */
+  /** Link to warn the author about this post. Null for self, guests or insufficient permissions. */
   readonly warnHref: string | null
-  /**
-   * Reserved for per-post moderation controls that are not inline.
-   *
-   * Still `null` everywhere: per-post moderation is on checkboxes and a
-   * bar rather than a per-post link, so nothing fills this yet. It stays in the
-   * contract because the moderation control panel is where such a *page* would
-   * live, and removing a public field to add it back next feature is worse
-   * than a documented `null`.
-   */
+  /** Reserved for non-inline moderation controls; currently null. Inline selection uses its separate model. */
   readonly moderateHref: string | null
-  /**
-   * Rate this post's author, for this post.
-   *
-   * Null on your own post, on a board with reputation off, and for anybody
-   * without the permission. It carries the post so the rating is attached to
-   * *this* post rather than to the author generally — which is what makes one
-   * rating per post a meaningful rule.
-   */
+  /** Post-specific reputation action. Null for the current author, disabled reputation or insufficient permission. */
   readonly rateHref: string | null
 }
 
@@ -447,15 +219,7 @@ export interface PostBitModel {
   readonly author: PostAuthorModel
   /** Pre-rendered Markdown. */
   readonly bodyHtml: string
-  /**
-   * @deprecated Since theme API 1.4, removed in 2.0. Use `post.id`.
-   *
-   * It existed so the client could assemble a quote out of the page. Quoting
-   * asks the server for a post **by id** now, which re-checks who may see it
-   * and cannot hand back what a deleted post used to say — so this is a copy of
-   * every post's source in the HTML of every thread page, for nobody. Still
-   * populated, because a theme could have read it; see `DEPRECATIONS`.
-   */
+  /** @deprecated Since theme API 0.5; removal scheduled for 1.0. Use `post.id` to request a server-authorized quote. */
   readonly quoteSource: string
   readonly postedAt: TimeModel
   /** "Last edited by X on Y", already assembled, or `null`. */
@@ -463,39 +227,13 @@ export interface PostBitModel {
   readonly isFirstPost: boolean
   /** A moderator sees deleted and unapproved posts, marked as such. */
   readonly visibility: 'visible' | 'unapproved' | 'deleted'
-  /**
-   * Set when this viewer ignores the author and has not revealed this
-   * post; `null` otherwise, which is the case on almost every post.
-   *
-   * The body is **withheld server-side** when this is set — `bodyHtml` is
-   * empty, the signature and custom fields are gone — rather than hidden with
-   * CSS, because "ignored" that ships the text to the browser is a preference
-   * rather than a feature. The post keeps its place and its number: filtering
-   * it out would give every viewer a different page size and make "#12" mean
-   * different posts to different people.
-   *
-   * A theme renders the placeholder and the link. Both are required — a hidden
-   * post with no way to see it is a hole in a conversation.
-   */
+  /** Ignored-author placeholder, or null. When set, the app withholds body, signature and custom fields while preserving post position and numbering. Render the placeholder and reveal link. */
   readonly ignored: {
     readonly authorUsername: string
     /** Same page, this post revealed. A GET: revealing changes nothing. */
     readonly revealHref: string
   } | null
-  /**
-   * The files attached to this post.
-   *
-   * Empty on almost every post, and empty rather than absent so a theme has one
-   * shape to render. **Every entry is already downloadable**: a `pending`
-   * upload — one whose re-encode has not finished — and a failed one are not in
-   * this list, because a link to a file that is not there yet is worse than the
-   * file appearing a minute later.
-   *
-   * `thumbnailHref` is `null` for anything that is not an image, and for an
-   * image small enough that a thumbnail would be the same picture again. A
-   * theme showing an image inline uses `thumbnailHref ?? href` and gets the
-   * right answer in both cases.
-   */
+  /** Downloadable attachments only; pending and failed uploads are excluded. Use `thumbnailHref ?? href` for an inline image. Non-images and images without a smaller preview have a null thumbnail. */
   readonly attachments: readonly PostAttachmentModel[]
   readonly actions: PostActionsModel
 }
@@ -532,31 +270,11 @@ export interface ShellModel {
 }
 
 /** `children` is the user panel, so a theme decides where in the header it sits. */
-/**
- * A board's logo, already resolved for this reader's colour scheme.
- *
- * Optional, and absent on most boards: a board with no logo renders its name in
- * text, which is what every board did before this field existed.
- *
- * **The app resolves the scheme, not the theme.** A theme cannot do it, and the
- * obvious attempt is wrong in the commonest case: `dark:hidden` matches the
- * `.dark` class, and a reader who has chosen "system" has no class — their dark
- * mode comes from a media query. They would get the light logo on a black page,
- * which is the exact failure two images exist to prevent. The server knows the
- * answer, so it gives one.
- */
+/** Board logo sources prepared for the reader’s colour preference. If no logo is supplied, render the board name. Honour the optional dark source for system colour mode. */
 export interface LogoModel {
   /** The image to render. Already the right one for a forced colour scheme. */
   readonly src: string
-  /**
-   * A dark-scheme source, or `null`.
-   *
-   * Non-null means "wrap it in a `<picture>` and put this behind
-   * `(prefers-color-scheme: dark)`" — the reader is on "system" and has two
-   * images to choose between. Null covers three different situations a theme
-   * does not need to tell apart: one image, or a reader who has forced a
-   * scheme, in which case `src` is already the right one.
-   */
+  /** Optional dark source for a `<picture>` with `(prefers-color-scheme: dark)`. Use the primary source as its fallback. */
   readonly darkSrc: string | null
   /** Never empty — the board's name when the operator has set nothing. */
   readonly alt: string
@@ -567,14 +285,7 @@ export interface HeaderModel {
   readonly homeHref: string
   readonly viewer: ViewerModel
   readonly navigation: readonly LinkModel[]
-  /**
-   * The board's logo, when it has one.
-   *
-   * A theme that ignores this renders the board's name and is still correct —
-   * which is what makes the field additive rather than breaking. A theme that
-   * uses it should keep the name as the link's accessible content when there is
-   * no logo, because the header is the only link home on most pages.
-   */
+  /** Optional board logo. Use the supplied alternative text and dimensions; fall back to the board name when absent. */
   readonly logo?: LogoModel | undefined
   readonly children?: ReactNode
 }
@@ -586,43 +297,14 @@ export interface UserPanelModel {
   /** `value` is `0` when there is nothing to show. */
   readonly unreadNotifications: CountModel
   readonly unreadMessages: CountModel
-  /**
-   * Where the two counts above lead, so a theme can make them clickable.
-   *
-   * A count that cannot be acted on is a notification the reader has to go
-   * hunting for. Both are absent for a guest, who has neither. Themes read
-   * these rather than searching `links` for the one labelled "Notifications",
-   * which two of them were doing and which breaks the moment that label is
-   * reworded or translated.
-   */
+  /** Destinations for the unread notification and message counts. Use the resolved hrefs. */
   readonly notificationsHref?: string
   readonly messagesHref?: string
   readonly regions?: {
-    /**
-     * The notifications menu the app supplies — a single control that opens the
-     * reader's notifications, private messages and, for staff, the moderation
-     * queue in tabs, marks them seen and links each one through (0.16).
-     *
-     * It is app-rendered rather than modelled field by field because it is an
-     * interactive island carrying Server Actions — the same reason logging out
-     * arrives as `children` and the quick-reply island as a region. A theme
-     * places it where the two unread counts used to sit; the island renders its
-     * own no-JavaScript fallback, so a theme that renders this needs no separate
-     * badge markup. Absent for a guest and on a board with neither service, and
-     * a theme that ignores it falls back to `unreadNotifications` and
-     * `unreadMessages`, which is what makes the field additive.
-     */
+    /** App-rendered notification menu with messages and permitted moderation content, including a no-JavaScript fallback. Render instead of separate unread-count controls when present. Optional since 0.16. */
     readonly notifications?: ReactNode
   }
-  /**
-   * Account controls the app supplies — today, the log-out form.
-   *
-   * Log out cannot be a `LinkModel`: it is a POST to a Server Action, because a
-   * GET that ends a session is fired by every prefetcher and link scanner that
-   * touches the page. A Server Action reference is also not plain data and could
-   * never cross this contract, so the app renders the form and the theme decides
-   * where in the panel it sits.
-   */
+  /** App-rendered account controls, including the POST logout form. Place the supplied form; do not replace logout with a GET link. */
   readonly children?: ReactNode
 }
 
@@ -635,33 +317,9 @@ export interface FooterModel {
   readonly links: readonly LinkModel[]
   /** Which zone `TimeModel.label`s were formatted in, for the footer note. */
   readonly timezoneLabel: string
-  /**
-   * What the board runs on, and where to read about it (0.8).
-   *
-   * A `LinkModel` and not a hardcoded string in each theme, for the reason every
-   * other piece of footer text is one: the app owns the words and the URL, so
-   * they are written once and a theme that wants to place the attribution
-   * somewhere else in its layout can, without owning a copy of them.
-   *
-   * Optional, which is what makes it a minor rather than a major: a theme
-   * written against 0.7 compiles and runs unchanged, and simply does not render
-   * it. The two themes in this repository do.
-   */
+  /** Optional software attribution link supplied by the app. Added in 0.8. */
   readonly poweredBy?: LinkModel
-  /**
-   * App-rendered controls the footer hosts: the forum-jump form and the
-   * appearance switcher (0.20).
-   *
-   * Both used to be full-width bars of their own stacked above the footer,
-   * which left the foot of every page reading as three separate rules. They
-   * are a GET form and Server-Action forms the app owns, so they cross the
-   * contract the way the log-out form does — as a rendered node the theme
-   * places, not data it could rebuild. Optional the way `poweredBy` is: a
-   * theme written against 0.19 compiles and runs unchanged — but one that
-   * never renders it costs its readers the jump box and the appearance
-   * controls, so place it rather than drop it. The bundled themes render it
-   * as a right-aligned row above the footer's own line of text.
-   */
+  /** Optional app-rendered forum-jump and appearance controls. Place both in the footer. Added in 0.20. */
   readonly regions?: {
     readonly controls?: ReactNode
   }
@@ -673,16 +331,7 @@ export interface NoticeModel {
   readonly dismissHref: string | null
 }
 
-/**
- * One announcement.
- *
- * **Not a `NoticeModel`, and the two are worth telling apart.** A notice is a
- * flash — the result of what the viewer just did, gone on the next page. An
- * announcement is a dated, authored, board-wide statement that is there for
- * everybody until it expires. They look similar and behave nothing alike, so
- * styling them identically is a choice a theme should make on purpose rather
- * than one the contract makes for it.
- */
+/** Dated, authored announcement, visible until expiry. Flash feedback uses NoticeModel. */
 export interface AnnouncementModel {
   readonly title: string
   /**
@@ -704,38 +353,11 @@ export interface BoardIndexModel {
     readonly categories: ReactNode
     readonly stats: ReactNode
     readonly online: ReactNode
-    /**
-     * The self-refreshing pair: newest threads and newest posts, already
-     * rendered, or absent on a board that cannot answer either question.
-     *
-     * **One region rather than two, and that is the contract rather than a
-     * convenience.** The pair is refreshed by a single round trip while the page
-     * is open, so it arrives as one node; two regions would be two polls of the
-     * same board for the same reason, or one poll that could only update half of
-     * what a theme had placed. A theme places it — the default puts it at the
-     * top of a sidebar — but does not take it apart.
-     *
-     * Optional, so a theme written against an earlier minor compiles and simply
-     * does not show it. Same rule as every other region field here.
-     */
+    /** App-rendered newest-thread/post region, refreshed together in one request. Place it as a unit. Absent when unavailable. */
     readonly latest?: ReactNode
-    /**
-     * The `index.footer` region: whatever plugins contributed, already
-     * rendered and ordered by the host.
-     *
-     * Optional, which is what makes this a **minor** addition under the
-     * versioning policy — a theme written against 0.1 keeps compiling and simply
-     * does not render plugin output. Every region field below follows the same rule.
-     */
+    /** Optional, pre-rendered index.footer plugin contributions in host order. */
     readonly plugins?: ReactNode
-    /**
-     * Live announcements, already rendered — one `Announcement` per row,
-     * or absent when there are none.
-     *
-     * Optional for the same reason the plugin region is, and under the same
-     * policy: a theme written against an earlier minor compiles and simply does
-     * not show them.
-     */
+    /** Optional, pre-rendered live announcements. Absent when there are none. */
     readonly announcements?: ReactNode
   }
 }
@@ -751,24 +373,11 @@ export interface BoardStatsModel {
   readonly postCount: CountModel
   readonly memberCount: CountModel
   readonly newestMember: UserRefModel | null
-  /**
-   * When the totals were last rolled up, or null before the first run.
-   *
-   * Part of the contract rather than a detail the app hides, because a theme
-   * that shows the numbers should be able to say how old they are — and
-   * "computed ten minutes ago" is the difference between a number that is
-   * stale and one that is wrong.
-   */
+  /** Last counter-rollup time, or null before the first run. Display it to identify the age of the totals. */
   readonly computedAt: TimeModel | null
 }
 
-/**
- * One visitor in the online list.
- *
- * `location` is **already resolved against the reader**: a forum they may not
- * see arrives as the bare label, never as a title with a link. The theme
- * renders what it is given and cannot leak what it was not.
- */
+/** Online visitor. Location titles and links are filtered by reader permissions. */
 export interface OnlineMemberModel extends UserRefModel {
   /** Where they are, as this reader may be told. Never null — see `label`. */
   readonly location: { readonly label: string; readonly href: string | null }
@@ -790,13 +399,7 @@ export interface WhoIsOnlineModel {
   readonly fullListHref: string
 }
 
-/**
- * One thread in the index's "latest threads" panel.
- *
- * Every row carries its forum, because these two panels are the only lists on
- * the board that cross it: without the forum, two identically-titled threads in
- * two forums are the same row printed twice.
- */
+/** Latest thread with its forum identity. */
 export interface LatestThreadModel {
   readonly title: string
   readonly href: string
@@ -807,15 +410,7 @@ export interface LatestThreadModel {
   readonly startedAt: TimeModel
 }
 
-/**
- * The newest threads on the board.
- *
- * `capturedAt` is not decoration. This panel refreshes itself while somebody is
- * looking at it, and a list that changes with nothing saying when it was read is
- * a list nobody can tell apart from one that has frozen. It is the same
- * argument `BoardStatsModel.computedAt` makes about a rollup, applied to the
- * opposite problem: that one is old and says so, this one is new and says so.
- */
+/** Newest threads with `capturedAt` indicating the read time. The app refreshes this server-rendered model. */
 export interface LatestThreadsModel {
   readonly threads: readonly LatestThreadModel[]
   readonly capturedAt: TimeModel
@@ -829,15 +424,7 @@ export interface LatestPostModel {
   readonly href: string
   readonly forum: LinkModel
   readonly author: UserRefModel
-  /**
-   * The post as text: flattened out of its Markdown source and cut on a word
-   * boundary, the same way a feed entry's summary is.
-   *
-   * Flattened rather than rendered, because the board's HTML carries quotes,
-   * directives and attachment markup whose meaning is lost in two lines — and
-   * because a theme dropping raw post HTML into a sidebar is one plugin away
-   * from being an injection point.
-   */
+  /** Plain-text post excerpt, flattened from Markdown and cut at a word boundary. Render as text. */
   readonly excerpt: string
   readonly postedAt: TimeModel
 }
@@ -853,23 +440,7 @@ export interface ForumDisplayModel {
   readonly newThreadHref: string | null
   readonly markReadAction: string | null
   readonly regions: {
-    /**
-     * Controls scoped to this forum — the thread ordering, and the follow
-     * form for a member who may subscribe. Rendered by the route because both
-     * carry a Server Action or a URL contract the theme does not own.
-     *
-     * **A theme renders this under its heading, not above it.** That placement
-     * is the reason the field exists: these were app-rendered strips stacked
-     * *before* `ForumDisplay`, so the first thing on a forum page was a filter
-     * with nothing yet to say what it filtered. A control belongs after the
-     * thing it acts on has been named.
-     *
-     * Optional, which is what makes it a **minor** addition under the
-     * versioning policy — a theme written against 0.3 keeps compiling.
-     *
-     * Only what acts on the listing *below* it belongs here. Following the
-     * forum is in `afterContent`, for the reason given there.
-     */
+    /** App-rendered forum ordering controls. Place below the heading and above the listing. Subscription controls are in `afterContent`. */
     readonly tools?: ReactNode
     readonly subforums: ReactNode
     /** One `ThreadRow` per thread. Empty-state markup is the theme's. */
@@ -881,16 +452,7 @@ export interface ForumDisplayModel {
      * the page fewest people arrive on.
      */
     readonly announcements?: ReactNode
-    /**
-     * Controls for somebody who has finished with the page — today, the form
-     * that follows this forum.
-     *
-     * A theme renders it after the listing. "Do you want to hear about this
-     * forum?" is a question you can only answer once you have seen what is in
-     * it, and asked above the threads it is a panel between a reader and the
-     * thing they came for. The ordering tabs stay at the top in `tools`,
-     * because those act on the list underneath them.
-     */
+    /** App-rendered forum subscription controls. Place after the listing. */
     readonly afterContent?: ReactNode
   }
 }
@@ -899,17 +461,7 @@ export interface SubforumListModel {
   readonly forums: readonly ForumRowModel[]
 }
 
-/**
- * `ThreadViewModel.watch` — the header's one-tap subscribe/unsubscribe toggle.
- *
- * `action` is already resolved to whichever direction flips `subscribed`: a
- * theme never branches on `subscribed` to pick a URL, only to pick a label —
- * "Watch" over `action` when `false`, "Watching" over the same `action` when
- * `true`. Subscribing this way always uses the board's default cadence; a
- * member who wants a slower one still has the cadence picker in
- * `ThreadViewModel.regions.afterContent`, which this toggle sits beside
- * rather than replaces.
- */
+/** Thread watch toggle. Submit the supplied `action`; use `subscribed` for the label/state. It uses the board’s default cadence. The full cadence selector remains in `afterContent`. */
 export interface ThreadWatchModel {
   readonly subscribed: boolean
   /** A native POST target that flips `subscribed`. */
@@ -922,49 +474,15 @@ export interface ThreadViewModel {
   readonly replyHref: string | null
   /** A native POST target for the last visible post on this page. */
   readonly markReadAction: string | null
-  /**
-   * The header's watch toggle, or `null` for a guest — who cannot subscribe
-   * to anything — and on a board running without the subscription service.
-   *
-   * Optional under the versioning policy: a theme written against 0.23
-   * compiles and renders no toggle, the same as it already does for the
-   * cadence picker in `regions.afterContent`.
-   */
+  /** Optional watch toggle. Null for guests or without the subscription service. */
   readonly watch?: ThreadWatchModel | null
   readonly regions: {
-    /**
-     * Controls scoped to this thread — following it, rating it, its poll, and
-     * the moderator's thread tools. Rendered by the route, for the reason
-     * every app-rendered region exists: each one carries a Server Action.
-     *
-     * **A theme renders this under its heading, not above it**, and the same
-     * history is behind this field as behind `ForumDisplayModel`'s. Four of
-     * these strips used to stack before `ThreadView`, so a thread opened on a
-     * phone began with a follow control, a star rating and a poll, and the
-     * title of the thing being followed, rated and voted on was a screen
-     * further down.
-     *
-     * Only what belongs *before* the posts: the moderator's bar, and the
-     * poll, which is content rather than a control. Rating and following are
-     * in `afterContent`.
-     *
-     * Optional under the versioning policy: a theme written against 0.3 compiles
-     * and simply does not offer them.
-     */
+    /** App-rendered moderator tools and poll. Place below the title and above posts. Rating and subscription controls are in `afterContent`. */
     readonly tools?: ReactNode
     /** One `PostBit` per post on this page. */
     readonly posts: ReactNode
     readonly pagination: ReactNode
-    /**
-     * Controls for a reader who has reached the end — rating the thread, and
-     * following it.
-     *
-     * A theme renders it after the posts and **before** the quick reply, which
-     * is the order the two are wanted in: somebody who has just read fifty
-     * posts is deciding what they think and whether to keep hearing about it,
-     * and then whether to answer. Both used to be above the first post, where
-     * they were asking for a verdict on something the reader had not read yet.
-     */
+    /** App-rendered rating and subscription controls. Place after posts and before quick reply. */
     readonly afterContent?: ReactNode
     /**
      * The quick-reply island, or `null` when the viewer may not reply — in which
@@ -974,24 +492,8 @@ export interface ThreadViewModel {
   }
 }
 
-/**
- * The composer, for both new threads and replies.
- *
- * `action` is a URL string, not a Server Action reference: a slot receiving a
- * function could not cross to a client island, and a URL is what a native form
- * needs anyway. The app's `<form action={serverAction}>` wraps the slot.
- */
-/**
- * The composer page.
- *
- * The form *element* is a region rather than a set of value props, and that is
- * a deliberate reversal of this model's first shape. A composer submits to a
- * Server Action, and a Server Action reference is not plain data — which settled
- * that such references never cross the theme contract, which is why logging out
- * is also a form the app renders into a slot. So the theme owns the page around
- * the form (heading, error, preview, where "cancel" goes) and the app owns the
- * controls.
- */
+/** Composer for new threads and replies. action is a URL; the app supplies the enclosing form. */
+/** Composer page model. The app owns the submitted form; the theme places its heading, errors, preview, form and cancel link. */
 export interface PostFormModel {
   readonly mode: 'thread' | 'reply' | 'edit'
   /** e.g. "Post a new thread in General". */
@@ -1011,31 +513,12 @@ export interface PostFormModel {
   readonly regions: {
     /** The app-rendered `<form>` carrying the Server Action and its controls. */
     readonly form: ReactNode
-    /**
-     * Kept for a theme that wants a toolbar affordance of its own at the top of
-     * the composer. The built-in composer no longer fills it: a formatting
-     * toolbar belongs against the box it formats, not at the head of a card a
-     * subject field and a prefix picker can sit below, so the `EditorToolbar`
-     * island renders inside `form`, joined to the message textarea, and this is
-     * `null` there. A `null` must leave a working plain-textarea form: the
-     * island enhances, it never enables.
-     */
+    /** Optional toolbar region. The built-in composer supplies null because its toolbar is inside `form`, beside the textarea. A null toolbar must leave the form usable. */
     readonly toolbar: ReactNode
   }
 }
 
-/**
- * The inline reply island at the foot of a thread.
- *
- * `children` carries the app's own reply form — the Server Action, its
- * validation, quoting, drafts and attachments, unchanged by whichever theme
- * is active — so `QuickReply` is what draws the boundary between the
- * server-rendered `ThreadView` around it and the client form inside it. The
- * plain fields stay alongside it rather than folding into `children`: a
- * theme that wants a lighter affordance of its own — a one-line teaser that
- * expands, say — can build one from `placeholder`, `submitLabel` and
- * `fullReplyHref` without ever inspecting what `children` contains.
- */
+/** Quick-reply island. `children` carries the app’s form, including validation, quoting, drafts and attachments. Labels and `fullReplyHref` support alternate presentations without inspecting the form. */
 export interface QuickReplyModel {
   readonly threadId: number
   readonly placeholder: string
@@ -1045,20 +528,7 @@ export interface QuickReplyModel {
   readonly children?: ReactNode
 }
 
-/**
- * One control in an `EditorToolbar`.
- *
- * Exactly one of `tag` and `insertion` is set, never both and never neither.
- * `tag` names one of the board's own commands — `applyEditorTag(field, tag,
- * placeholder)` from `@meith/theme-kit` runs it, and a theme that reads `tag`
- * opaquely and hands it straight to `applyEditorTag` needs no change when a
- * new one is added. `insertion` is a plugin's own: a directive registered
- * through `markdown.directives` has no `EditorTag` to squat on, so a button
- * contributed through the `view.editor-toolbar` filter carries the edit
- * itself as data — `applyInsertion(field, insertion)` runs it the same way,
- * sharing the caret and selection mechanics `applyEditorTag` uses. Both are
- * plain JSON, so a plugin never hands the host a function to call.
- */
+/** Editor control. Exactly one of `tag` and `insertion` is set. Use `applyEditorTag` for a built-in tag or `applyInsertion` for a plugin insertion; both operate on serializable edit data. */
 export interface EditorToolbarButtonModel {
   /** One of the board's own commands, or `null` for a plugin's `insertion`. */
   readonly tag: EditorTag | null
@@ -1069,19 +539,9 @@ export interface EditorToolbarButtonModel {
   readonly title: string
   /** `aria-keyshortcuts`, e.g. `"Control+b"`, or `null` for a tag with no shortcut. */
   readonly keyShortcut: string | null
-  /**
-   * A themed icon's name, for a theme that draws one — see `PanelNavIcon` for
-   * the same idea. Always `null` today: nothing in the default palette names
-   * one yet, so every theme renders its own glyph from `tag` or `label`. The
-   * field stays in the contract for the theme that wants to key off it once
-   * one does.
-   */
+  /** Optional theme icon name. Unknown or null names render no icon; the text label remains accessible. */
   readonly icon: string | null
-  /**
-   * Fills a wrap or spoiler tag when nothing is selected; `null` for a tag
-   * that does not need one, and for every `insertion` button — its strings
-   * are already fixed, so there is nothing left for a placeholder to fill.
-   */
+  /** Placeholder for an empty wrap/spoiler selection. Null when unnecessary and for insertion buttons. */
   readonly placeholder: string | null
 }
 
@@ -1091,15 +551,7 @@ export interface EditorToolbarModel {
   /** Accessible name for the toolbar's `role="group"`. */
   readonly groupLabel: string
   readonly buttons: readonly EditorToolbarButtonModel[]
-  /**
-   * The attachment picker, or `null` where this composer takes none.
-   *
-   * `inputId` names an app-rendered `<input type="file" hidden>` elsewhere on
-   * the page — the upload itself is a Server Action the app owns, so a theme
-   * never handles the file. A button that calls `.click()` on the element
-   * that id names opens the picker; like every other button here, that is an
-   * enhancement over a plain-textarea form, not what makes the form work.
-   */
+  /** Attachment picker or null. `inputId` targets the app-owned hidden file input. An enhanced button may activate it; the app owns upload handling. */
   readonly attachment: { readonly inputId: string; readonly label: string } | null
   readonly previewAction: string | null
 }
@@ -1115,12 +567,7 @@ export interface MemberProfileModel {
    * where the group behind it has gone.
    */
   readonly title: string | null
-  /**
-   * Every group shown with this member's name, on the same terms as
-   * `PostAuthorModel.groups`: display group first, the rest in display order,
-   * capped by the board's *Maximum displayed groups* setting. Render it
-   * instead of `title` when it is non-empty; fall back to `title` otherwise.
-   */
+  /** Displayed groups, with display group first, then display order, capped by Maximum displayed groups. Use title only when groups is empty. */
   readonly groups?: readonly GroupTagModel[] | undefined
   readonly joinedAt: TimeModel
   readonly lastVisitAt: TimeModel | null
@@ -1135,22 +582,7 @@ export interface MemberProfileModel {
   }
 }
 
-/**
- * The search form, reshaped at the slot-contract freeze.
- *
- * It was originally declared as `{ action, query, forums: LinkModel[], errorMessage }`
- * and never rendered — the search page grew its own form instead, so the slot was
- * a contract nothing had ever tested. Wiring it up is what found the shape wrong:
- * a filter is a `<select>`, and an option is a value and a label, not an href.
- * A theme handed `LinkModel[]` would have had to invent the value, most likely by
- * parsing it out of the URL.
- *
- * **`fields` carries the query-parameter names.** Themes never build hrefs (see
- * `LinkModel`), and a `name="q"` typed into a theme is the same rule broken from
- * the other end: it hardcodes the app's URL contract into markup the app does not
- * own, and renaming the parameter silently breaks every installed theme's form
- * while the page keeps rendering.
- */
+/** Search form. Use the supplied `fields` for input names and supplied option values. Do not hardcode query-parameter names or derive them from URLs. */
 export interface SearchFormModel {
   /** Where the form submits. A GET form: a search is a URL. */
   readonly action: string
@@ -1169,23 +601,11 @@ export interface SearchFormModel {
   /** Guidance for an empty form: quoting, exclusion. `null` once submitted. */
   readonly hint: string | null
   readonly errorMessage: string | null
-  /**
-   * The rest of the form: who posted it, when, where to look, and what a result
-   * is. Optional, and a theme that ignores it still submits a working search —
-   * every control in here is a narrowing the app defaults for a form that
-   * leaves it out.
-   */
+  /** Optional author, date, forum and result-type controls. Omitted controls use the default search scope. */
   readonly advanced?: SearchAdvancedModel
 }
 
-/**
- * One `<select>` in a search form or a results filter: the name to submit it
- * under, a label, and the options with the current one marked.
- *
- * A theme renders these as it is handed them and in the order it is handed
- * them. Which axes a search has is the app's decision, not a theme's, and a
- * theme that enumerated them would lose one the day the app gained it.
- */
+/** Select control with its submitted name, label and options. Render controls in the supplied order. */
 export interface SearchChoiceModel {
   readonly field: string
   readonly label: string
@@ -1209,15 +629,7 @@ export interface SearchTextFieldModel {
   readonly hint: string
 }
 
-/**
- * The advanced half of the search form.
- *
- * `isOpen` is the app saying whether the reader has anything in here — a
- * returning search with an author or a date window set opens the panel so the
- * narrowing that produced the results is visible rather than hidden behind a
- * closed disclosure. A theme is free to render the panel open always; it must
- * not render it *closed* when `isOpen` is true.
- */
+/** Advanced search controls. Keep open when `isOpen` is true so applied filters are visible. Always-open rendering is also supported. */
 export interface SearchAdvancedModel {
   readonly label: string
   readonly isOpen: boolean
@@ -1232,38 +644,7 @@ export interface SearchChipModel {
   readonly removeHref: string
 }
 
-/**
- * Filtering and sorting for a results page, in the order of how often it is
- * used: the count, the order, what is already narrowing the page, and — folded
- * away until wanted — the filters themselves.
- *
- * ## Why the order is links and the filters are a form
- *
- * Changing the order is one decision and the commonest one, so `sorts` are
- * links: one click, nothing to submit, and each href carries the filters
- * already applied. Filtering is several decisions at once — a forum *and* a
- * date, say — so `choices` are a GET form with one submit, and the result is a
- * URL. `applied` is the reverse of both: one chip per filter that is on, each
- * with an href that removes only itself.
- *
- * A reader with JavaScript off gets all three, because all three are ordinary
- * HTML.
- *
- * ## The space this is allowed to take
- *
- * Keep the count, sort links and applied filters together above the results.
- * Labeled controls can use columns on wider screens and stack on phones so
- * long forum and author names remain readable. Preserve visible labels and
- * usable touch targets without making the page scroll horizontally.
- *
- * ## Counts, and what they count
- *
- * An option's label carries the number of results it would leave, counted
- * against the search *without* the forum and author filters applied — so the
- * counts stay put as a reader moves between forums instead of collapsing to
- * the one they are already in. `note` carries the caveat when the board is big
- * enough that the count is a floor rather than a total.
- */
+/** Results filters: count, sort links, applied-filter removal links and a GET form. Preserve existing filters in supplied hrefs and hidden inputs. Option counts exclude forum/author narrowing; `note` identifies lower-bound counts. Keep labels, touch targets and long values readable without horizontal page scrolling. */
 export interface SearchRefineModel {
   /** Where the filters submit: this same results page. */
   readonly action: string
@@ -1289,14 +670,7 @@ export interface HiddenFieldModel {
   readonly value: string
 }
 
-/**
- * One search result: where it goes, and enough of it to decide whether to go.
- *
- * `excerptHtml` is the only HTML in this model, and it is the app's own: the
- * search engine returns the matching fragment with the matched words wrapped in
- * `<b>`, and nothing else survives — the post's own markup is stripped before
- * the excerpt is cut, so a theme is styling emphasis, not rendering a post.
- */
+/** Search result with destination and excerpt. `excerptHtml` contains app-generated match emphasis; source markup is stripped. Render other fields as text. */
 export interface SearchHitModel {
   readonly postId: number
   readonly threadTitle: string
@@ -1307,47 +681,18 @@ export interface SearchHitModel {
   readonly postedAt: TimeModel
 }
 
-/**
- * The results of one search.
- *
- * ## Why the results are a slot of their own
- *
- * `SearchForm` is a filter panel and this is a listing; they share a page and
- * nothing else. Rendering the results *inside* `SearchForm` would mean a theme
- * that wants a different result row has to reimplement the form to get at it.
- *
- * ## `searchedAt`, and why results are not simply cached
- *
- * A search is stored and its results page is re-checked against the viewer's
- * access every time it is opened, so what a link to a result set shows depends
- * on who opens it. The timestamp is in the model because a theme should be able
- * to say when the search was run — a result page that looks live and is a week
- * old is the failure this field exists to prevent.
- */
+/** Search results with their original `searchedAt` timestamp. Visibility is checked again for the current viewer when opening a stored result set. */
 export interface SearchResultsModel {
   /** What was searched for, as the reader typed it. */
   readonly terms: string
   readonly searchedAt: TimeModel
   readonly hits: readonly SearchHitModel[]
-  /**
-   * The next page of this same search, or `null` at the end.
-   *
-   * Superseded by `regions.pagination`, which walks backwards as well and says
-   * which page this is. Both are populated: a theme written before the region
-   * existed keeps working, and one that renders the region should not also
-   * render this link or the page carries two pagers.
-   */
+  /** Legacy next-page link, or null at the end. Prefer `regions.pagination`; render only one pager. */
   readonly nextHref: string | null
   readonly nextLabel: string
   /** Back to an empty form. Always offered: a search that found nothing needs it most. */
   readonly newSearchHref: string
-  /**
-   * The narrow-this-search form. A GET form, like `SearchForm` and for the same
-   * reason — the narrowed search is a URL of its own, not a state this page
-   * holds. `hidden` carries the advanced options this search was run with, one
-   * input per entry, so that narrowing it keeps them; a theme that drops them
-   * narrows within the words alone.
-   */
+  /** GET filter form. Preserve each `hidden` input so narrowing retains the original advanced options. */
   readonly within: {
     readonly action: string
     readonly field: string
@@ -1381,22 +726,7 @@ export interface DiscoveryRowModel {
   readonly lastPostUsername: string | null
 }
 
-/**
- * A discovery listing: "new posts", "today", "unread", "unanswered", and the
- * two personal views.
- *
- * One slot rather than five. The views differ in which threads the query
- * returned and in the sentence under the heading; the reader is looking at the
- * same thing in every one of them, and a theme that had to fill five slots to
- * restyle one row would fill four of them by copy and paste.
- *
- * ## `tabs` are given, not built
- *
- * Which views exist depends on whether the viewer is signed in — "my posts" is
- * not offered to a guest — and that is a decision the app has already made.
- * A theme renders the tabs it is handed and marks the current one; it never
- * enumerates the views itself.
- */
+/** Discovery listing for new, today, unread, unanswered or personal content. Render the supplied tabs and current state; available tabs depend on the viewer. */
 export interface DiscoveryViewModel {
   readonly title: string
   /** One line saying what this view selected, e.g. "Threads nobody has replied to yet". */
@@ -1411,11 +741,7 @@ export interface DiscoveryViewModel {
    * ("you have reached the end") from at the start of one ("nothing here yet").
    */
   readonly emptyMessage: string
-  /**
-   * Set when the view refused rather than failed: a guest asking for their own
-   * threads. The listing is empty and this says why, with `signInHref` to fix
-   * it. Not an error — a themed page, not the error page.
-   */
+  /** Access notice for a refused discovery view. Results are empty; signInHref provides the sign-in action. */
   readonly refusal: {
     readonly message: string
     readonly signInHref: string
@@ -1433,14 +759,7 @@ export interface TabModel {
 /** Which control panel a shell or a page belongs to. */
 export type PanelKind = 'usercp' | 'modcp' | 'admincp'
 
-/**
- * The frame around a control panel.
- *
- * `panel` is in the model because the three panels are the same shape and not
- * the same place: a theme can give the admin panel its own accent without
- * needing three slots, and the default theme uses it to decide how far down the
- * rail starts — the admin panel carries a header of its own above this.
- */
+/** Control-panel frame. Use `panel` to distinguish member, moderator and administrator layouts. */
 export interface PanelShellModel {
   readonly panel: PanelKind
   /**
@@ -1456,34 +775,11 @@ export interface PanelShellModel {
   readonly children?: ReactNode
 }
 
-/**
- * Where the reader is, relative to one navigation item.
- *
- * `here` is the page being rendered; `under` is an item the reader is inside
- * but not on — a forum's permission screen under "Forums". The distinction is
- * `aria-current="page"` against `aria-current="true"`, and both are the answer
- * to "where am I", which is the only question a rail exists to answer.
- */
+/** Navigation position: `here` uses `aria-current="page"`; `under` uses `aria-current="true"` for an ancestor section. */
 export type PanelNavCurrent = 'here' | 'under'
 
-/**
- * One item in a panel's navigation.
- *
- * `current` is resolved by the app from the request path — the theme is told
- * where the reader is, it does not work it out. That is what lets this slot
- * render on the server: the alternative is `usePathname`, which makes the whole
- * rail a client component and ships a router hook to a board that needs none.
- */
-/**
- * What one rail item is about, named rather than drawn.
- *
- * The app knows a section is the member list; only the theme knows what a
- * member looks like in its own hand. Passing a name instead of an `<svg>` is
- * what keeps the icon set a theme's decision — a theme that wants none ignores
- * this, and one with its own drawing does not have to match anybody else's line
- * weight. A name a theme has no drawing for is drawn as nothing, never as a
- * broken box.
- */
+/** Panel navigation item. The app resolves `current` from the request path; no client router lookup is needed. */
+/** Semantic icon name. The theme chooses its graphic or omits it. Unknown names render nothing. */
 export type PanelNavIcon =
   | 'antispam'
   | 'avatar'
@@ -1518,12 +814,7 @@ export interface PanelNavItemModel {
   readonly count: number | null
   /** `null` when the reader is somewhere else entirely. */
   readonly current: PanelNavCurrent | null
-  /**
-   * A page reached from elsewhere rather than from the rail — warning a member,
-   * editing one forum. It is shown as where you are and it is not a link,
-   * because a link to the page you are on that also needs an argument you no
-   * longer have is a dead end. Only ever present while the reader is on it.
-   */
+  /** Current contextual page reached outside the rail, such as a forum editor. Render as a label rather than a link. */
   readonly isRecord: boolean
 }
 
@@ -1554,29 +845,13 @@ export interface PanelNavModel {
   readonly currentTitle: string | null
 }
 
-/**
- * One control-panel page: heading, the line under it, its controls, its body.
- *
- * ## Why the heading is data and everything around it is a region
- *
- * `title` is a string because a page title is a string — it is also the
- * document title, and a model that allowed markup here would let a theme's
- * `<h1>` and the browser tab disagree. The lede and the controls are regions
- * because the app fills them with forms carrying Server Actions and links it
- * has resolved, neither of which crosses this contract as data.
- */
+/** Panel page title and app-rendered supporting text, actions and body. The title remains plain text for the page heading and browser title. */
 export interface PanelPageModel {
   readonly panel: PanelKind | null
   readonly title: string
   /** Where this page was reached from, when it is a page under another. */
   readonly back: LinkModel | null
-  /**
-   * `panel` when a `PanelShell` is already around this page — it has centred
-   * the column and set the gutters, and the page fills what the rail leaves.
-   * `standalone` when nothing wraps the page and it has to find its own
-   * middle: who's online, the board statistics, the report form. Absent reads
-   * as `panel`, which is what a theme that ignores this renders today.
-   */
+  /** `panel` fills an existing PanelShell; `standalone` supplies its own centred frame for pages such as online, statistics and reports. Defaults to panel. */
   readonly frame?: 'panel' | 'standalone'
   /**
    * `reading` for prose and forms, `wide` for a table nobody can read at
@@ -1600,22 +875,10 @@ export interface PanelPageModel {
   readonly children?: ReactNode
 }
 
-/**
- * One labelled section within a control-panel page.
- *
- * A separate slot from `PanelPage` because it is rendered *by the page*, in
- * among the page's own content, rather than around it — a page is a heading and
- * a body, and the body may be three of these or none. A theme that restyled the
- * page frame and not the headings inside it would have one visual language
- * outside the content and the default theme's inside.
- */
+/** Labelled section within a panel page, rendered among the page’s content. */
 export interface PanelSectionModel {
   readonly title: string
-  /**
-   * The id the heading takes, so the section's landmark can point at it. Given
-   * by the page because the page is where the section is named twice — once as
-   * a heading and once as the region's accessible name.
-   */
+  /** Heading ID used by the section landmark. */
   readonly headingId: string
   readonly regions: {
     readonly description?: ReactNode
@@ -1624,35 +887,12 @@ export interface PanelSectionModel {
   readonly children?: ReactNode
 }
 
-/**
- * A link out of an authentication page, with the sentence that introduces it.
- *
- * "New here? **Create an account**" is one thought and two pieces of markup.
- * `lead` carries the first half so the copy stays the app's and the layout
- * stays the theme's — a theme that renders links as a plain list can drop it,
- * and one that renders them as sentences has the sentence.
- */
+/** Authentication-page link and its optional introductory copy. The theme may present the link alone or with its `lead`. */
 export interface AuthLinkModel extends LinkModel {
   readonly lead: string | null
 }
 
-/**
- * The sign-in, register, reset and confirm pages.
- *
- * ## Why one slot and not five
- *
- * They are the same page: a card, a heading, a form, and the ways out of it.
- * What differs is the form, and a form carrying a Server Action never crosses
- * this contract as data — so it arrives as a region and the four pages become
- * one slot with four things in the hole.
- *
- * ## `alert` is not `Notice`
- *
- * `Notice` is a flash message on a page that has a shell around it; this is the
- * page telling you the link that brought you here is no longer any good, and it
- * has to be readable above the form it concerns. It is a string rather than a
- * model because there is exactly one kind of it.
- */
+/** Sign-in, registration, reset and confirmation frame. Place the app-rendered form and links. Show `alert` above the form when supplied. */
 export interface AuthPageModel {
   readonly title: string
   /** `null` unless something about the way in went wrong. */
@@ -1668,29 +908,7 @@ export interface AuthPageModel {
   }
 }
 
-/**
- * The forum jump box — MyBB's `<select>` at the foot of every page.
- *
- * ## Why a form and a button rather than a `<select>` that navigates
- *
- * The obvious implementation is an `onChange` handler that sets
- * `location.href`. It is also inaccessible and does not work without
- * JavaScript, and it fails in the same way for both reasons: **choosing an
- * option is not the same act as committing to it.** A keyboard user moving
- * through a `<select>` with the arrow keys changes the value on every
- * keystroke, so an auto-navigating jump box teleports them to the first forum
- * in the list before they reach the one they wanted.
- *
- * So the model carries an `action` and a submit label, and the theme renders a
- * real `method="get"` form. A theme is free to *also* auto-submit for pointer
- * users; the button is what must always be there.
- *
- * ## `depth` rather than a pre-indented label
- *
- * The app gives the tree's shape and the theme decides how to show it. Baking
- * `— — Subforum` into the label would make the indentation impossible to
- * restyle and would put non-breaking spaces into what a screen reader announces.
- */
+/** Forum selector in a real GET form with a submit button. Do not navigate on keyboard selection changes. Use `depth` to indent options without modifying their labels. */
 export interface ForumJumpModel {
   /** Where the form submits. GET, because a jump is a navigation. */
   readonly action: string
@@ -1729,23 +947,7 @@ export interface ErrorNoticeModel {
   readonly requestId: string | null
 }
 
-/**
- * One inline-moderation checkbox, or `null` when this viewer has no
- * business selecting rows.
- *
- * Plain data, and it has to be: the *form* it belongs to carries a Server
- * Action reference, and such references never cross the theme
- * contract. So the app renders the form — below the listing, where a bar of
- * buttons belongs — and the theme renders a checkbox that says which form it
- * belongs to.
- *
- * `formId` is the whole trick, and it is why this works with scripting off.
- * HTML's `form` attribute associates a control with a form **by id, anywhere
- * in the document**, so the checkboxes can live inside table rows, list items
- * or article elements without the listing having to be wrapped in a `<form>` —
- * which it cannot be, because `ForumDisplay` already renders a mark-read form
- * and nested forms are not a thing browsers will parse.
- */
+/** Inline-moderation checkbox or null when unavailable. Associate it with the app-owned form using `formId` and HTML’s `form` attribute. Do not nest forms around listings. */
 export interface SelectionModel {
   /** The field name every checkbox shares. */
   readonly name: string
@@ -1780,16 +982,7 @@ export interface ThreadRowSlotModel {
   /** The inline-moderation checkbox, or `null`. */
   readonly select: SelectionModel | null
   readonly regions?: {
-    /**
-     * The `threadrow.badges` region, beside the thread's title (0.22).
-     *
-     * Filled from a single per-page call rather than one per row — a forum page
-     * lists twenty threads on a tight budget, so the region runs once with the
-     * whole page and hands each row its badges. Optional, which is what makes it
-     * additive: a theme written against 0.21 compiles and simply shows no plugin
-     * badges. Absent on a row no plugin marked; a theme places it wherever a
-     * thread's own flags (pinned, locked) sit.
-     */
+    /** Optional thread-row plugin badges, supplied by one batched call per page. Place beside the thread flags. Added in 0.22. */
     readonly pluginBadges?: ReactNode
   }
 }
@@ -1797,21 +990,7 @@ export interface ThreadRowSlotModel {
 export interface PostActionsSlotModel {
   readonly actions: PostActionsModel
   readonly postId: number
-  /**
-   * App-rendered controls that belong beside the post's own actions — today,
-   * the multi-quote island.
-   *
-   * It is `children` for the reason logging out is: the button is a client
-   * island holding browser state, and neither a component nor a handler can
-   * cross this contract as data. Before this field the page had nowhere to put
-   * it but `PostBitModel.regions.pluginFooter`, so every post on the board
-   * carried a second bordered row containing one control — the plugin region
-   * used as a parking space, and a visible band of furniture per post as the
-   * price.
-   *
-   * Additive under the versioning policy, and `children` is already exempt from the
-   * plain-data rule.
-   */
+  /** App-rendered post controls, including the multi-quote island. Place beside the post’s action links. */
   readonly children?: ReactNode
 }
 
@@ -1819,12 +998,7 @@ export interface PostActionsSlotModel {
  * The slot → model map
  * ------------------------------------------------------------------ */
 
-/**
- * What each slot is handed. Every key here must be a slot in `SLOTS`, and every
- * slot in `SLOTS` must have a key here — both directions are asserted below, so
- * adding a slot without a model (or the reverse) fails `pnpm typecheck` rather
- * than surfacing as an `any` in a theme.
- */
+/** Slot-to-model map. Type checks require one entry per registered slot and reject unregistered entries. */
 export interface SlotModels {
   Shell: ShellModel
   Header: HeaderModel
diff --git a/scripts/i18n-baseline.json b/scripts/i18n-baseline.json
index 87b9e307d..36323c11a 100644
--- a/scripts/i18n-baseline.json
+++ b/scripts/i18n-baseline.json
@@ -55,7 +55,7 @@
   "packages/admin/src/index.ts": 1,
   "packages/antispam/src/challenge.ts": 5,
   "packages/api/src/openapi.ts": 21,
-  "packages/api/src/reference.ts": 93,
+  "packages/api/src/reference.ts": 32,
   "packages/api/src/routes.ts": 108,
   "packages/api/src/schema.ts": 118,
   "packages/attachments/src/service.ts": 4,
@@ -110,9 +110,9 @@
   "packages/moderation/src/warnings.ts": 1,
   "packages/notifications/src/kinds.ts": 28,
   "packages/notifications/src/push.ts": 2,
-  "packages/plugin-kit/src/hooks.ts": 117,
+  "packages/plugin-kit/src/hooks.ts": 104,
   "packages/plugin-kit/src/plugin.ts": 1,
-  "packages/plugin-kit/src/regions.ts": 21,
+  "packages/plugin-kit/src/regions.ts": 17,
   "packages/plugin-kit/src/runtime.ts": 4,
   "packages/relations/src/service.ts": 2,
   "packages/runtime/src/backup-before-migrating.ts": 2,
@@ -124,8 +124,8 @@
   "packages/settings/src/search-languages.ts": 1,
   "packages/subscriptions/src/modes.ts": 4,
   "packages/tasks/src/builtin.ts": 117,
-  "packages/theme-kit/src/api.ts": 9,
-  "packages/theme-kit/src/slots.ts": 64,
+  "packages/theme-kit/src/api.ts": 5,
+  "packages/theme-kit/src/slots.ts": 40,
   "packages/theme-kit/src/theme.ts": 6,
   "packages/ui/src/disclosure.tsx": 1,
   "packages/ui/src/menu.tsx": 4,
diff --git a/scripts/perf-docs.mjs b/scripts/perf-docs.mjs
index e6fa50fe9..3dd631c63 100644
--- a/scripts/perf-docs.mjs
+++ b/scripts/perf-docs.mjs
@@ -192,17 +192,13 @@ function renderLoad({ budgets, cohorts, mix, load }) {
 
   const think = (load.thinkMs / 1_000).toFixed(0)
 
-  out.push(`Every measurement above is one read at a time. This is the same board with`)
-  out.push(`members on it: each one asks for a page every ${think} seconds, drawn from the`)
-  out.push('mix below, through the single connection pool one process has —')
-  out.push(`**${load.poolMax} connections**, which is the shipped default and not a tuned number.`)
+  out.push(
+    `Fixed-schedule traffic: one page per member every ${think} seconds, using ${load.poolMax} database connections.`,
+  )
   out.push('')
-  out.push('Arrival times are on a fixed schedule rather than a request-then-sleep loop.')
-  out.push('That distinction is the whole measurement: a loop that sleeps *after* each')
-  out.push('response slows its own arrivals down exactly when the board gets slow, so it')
-  out.push('reports a queue as if it were an idle system. **Lateness** is what that loop')
-  out.push('cannot see — how long a request sat before it even started, because every')
-  out.push('connection was busy. It moves first, and it moves before the p95 does.')
+  out.push(
+    'Late p95 measures the delay before a scheduled request starts. Fixed arrivals expose queueing that a response-then-sleep loop would hide.',
+  )
   out.push('')
 
   out.push('| Active members | Offered | Served | Budget | | p50 | p95 | p99 | Late p95 |')
@@ -226,26 +222,19 @@ function renderLoad({ budgets, cohorts, mix, load }) {
       `until it has both ${load.minRequests} requests and a steady window to put them in.`,
   )
   out.push('')
-  out.push('## The same pages, under that load')
+  out.push('## Per-page load results')
   out.push('')
 
   const flat = flatRange(cohorts, seen)
   if (flat !== null) {
     const rise = (flat.to.members / flat.from.members).toFixed(0)
     out.push(
-      `From ${flat.from.members.toLocaleString()} members to ` +
-        `${flat.to.members.toLocaleString()} the p95 of the mix barely moves — ` +
-        `${ms(flat.fromP95)} to ${ms(flat.toP95)}, across ${rise}× the traffic. That flatness ` +
-        'is not the board being idle; it is what a mixed p95 measures. A p95 is set by the ' +
-        'slowest one request in twenty, and search and discovery are about that share of ' +
-        'the traffic, so until the pool runs out the mixed p95 mostly reports which pages ' +
-        'are in the mix rather than how many members are on the board.',
+      `Mixed p95: ${ms(flat.fromP95)} at ${flat.from.members.toLocaleString()} members to ${ms(flat.toP95)} at ${flat.to.members.toLocaleString()} members (${rise}× traffic). The traffic mix affects this aggregate; inspect per-page timings too.`,
     )
     out.push('')
   }
 
-  out.push('The per-page breakdown is where load shows earlier, and says which pages it')
-  out.push('shows in first.')
+  out.push('Per-page p95 by active-member count:')
   out.push('')
 
   out.push(`| Page | Share | ${cohorts.map((c) => c.members.toLocaleString()).join(' | ')} |`)
@@ -260,18 +249,11 @@ function renderLoad({ budgets, cohorts, mix, load }) {
   }
 
   out.push('')
-  out.push('Every row is a p95 in milliseconds, and the column heading is how many members')
-  out.push('were on the board. A row that climbs left to right is a page that costs more')
-  out.push('when the board is busy; a row that does not is a page whose cost is its own.')
-  out.push('')
-
   const filtered = mix.filter((entry) => entry.filtered)
   if (filtered.length > 0) {
-    out.push('The scoped reads —')
-    out.push(`${filtered.map((entry) => `*${page.get(entry.id) ?? entry.id}*`).join(', ')} —`)
-    out.push('pay the permission filter first, in the same request, exactly as a page does.')
-    out.push('Their numbers here are therefore the filter plus the read, and are not')
-    out.push('comparable with the single-read measurement of the same id above.')
+    out.push(
+      `Scoped reads (${filtered.map((entry) => page.get(entry.id) ?? entry.id).join(', ')}) include permission filtering. They are not directly comparable to single-read timings.`,
+    )
     out.push('')
   }
 
@@ -302,15 +284,9 @@ function render({ budgets, cohorts, mix, load, results, indexes, plans }) {
   out.push('  Regenerate with `pnpm perf:docs`; `pnpm verify` fails when this is stale.')
   out.push('-->')
   out.push('')
-  out.push('The p95 budgets for the pages a board’s traffic actually goes to, what the')
-  out.push('last recorded run measured against a full-scale board one read at a time,')
-  out.push('and what a board full of members reading at once measured on the same data.')
-  out.push('')
-  out.push('Every number here is measured on a **single-instance** board — one web')
-  out.push('process with the per-process cache, no Redis. That is the stock topology')
-  out.push('and the honest baseline. A board [scaled out](../operations/scaling.md) answers from a')
-  out.push('shared cache instead of an in-process map, so its numbers differ; measure')
-  out.push('your own rather than reading these across.')
+  out.push(
+    'Recorded database-read timings, budgets and concurrent-load results. These are single-process measurements with an in-process cache and no Redis. Measure your own deployment; shared-cache results can differ.',
+  )
   out.push('')
 
   if (results === null) {
@@ -321,7 +297,7 @@ function render({ budgets, cohorts, mix, load, results, indexes, plans }) {
     out.push('')
   } else {
     const env = results.environment ?? {}
-    out.push('## The board these numbers came from')
+    out.push('## Test environment')
     out.push('')
     out.push('| | |')
     out.push('|---|---|')
@@ -340,9 +316,9 @@ function render({ budgets, cohorts, mix, load, results, indexes, plans }) {
     out.push(`| Runtime | Node ${env.node} on ${env.platform} |`)
     out.push(`| Measured | ${String(results.measuredAt).slice(0, 10)} |`)
     out.push('')
-    out.push('The absolute numbers belong to that machine. What travels between machines')
-    out.push('is the **shape**: which scenarios sit near their budget, and whether a deep')
-    out.push('page costs more than a first page. Compare ratios, not milliseconds.')
+    out.push(
+      'Results apply to the recorded machine and workload; they are not a capacity guarantee.',
+    )
     out.push('')
   }
 
@@ -364,11 +340,8 @@ function render({ budgets, cohorts, mix, load, results, indexes, plans }) {
 
   const limits = budgets.filter((b) => b.kind === 'limit')
   if (limits.length > 0) {
-    out.push('A **target** is a number the page is expected to meet, set with headroom over')
-    out.push('what was measured. A **limit** is a number that was measured, is not considered')
-    out.push('good, and is recorded anyway so it cannot get worse quietly — a debt with a')
     out.push(
-      `number on it, not a pass mark. ${limits.length === 1 ? 'One entry is a limit' : `${limits.length} entries are limits`}:`,
+      'A target is the expected ceiling. A limit records an existing slow path to detect regressions; meeting it does not resolve that performance issue.',
     )
     out.push('')
     for (const limit of limits) out.push(`- **${limit.page}** — ${limit.work}.`)
@@ -379,14 +352,7 @@ function render({ budgets, cohorts, mix, load, results, indexes, plans }) {
 
   out.push('## Partial visible indexes')
   out.push('')
-  out.push('`EXPLAIN` evidence that the partial `visibility` indexes are actually used.')
-  out.push('This is that evidence, and it is also a **check**: `pnpm perf explain`')
-  out.push('fails when the planner stops choosing one.')
-  out.push('')
-  out.push('That failure is the one worth guarding. A partial index only matches a query')
-  out.push('whose predicate the planner can prove implies it, so a read path that starts')
-  out.push('passing a variable visibility scope where it passed a literal falls silently')
-  out.push('onto a sequential scan of the largest table on the board. Nothing errors.')
+  out.push('`pnpm perf explain` checks that the planner uses the expected indexes.')
   out.push('')
 
   const seen = new Map((indexes?.results ?? []).map((r) => [r.id, r]))
@@ -400,14 +366,12 @@ function render({ budgets, cohorts, mix, load, results, indexes, plans }) {
     )
   }
   out.push('')
-  out.push('Each partial index has an unfiltered twin, and the twins are checked too. A')
-  out.push('moderator seeing unapproved and deleted content *cannot* use the partial')
-  out.push('index — their predicate does not imply it — so without the twin their forum')
-  out.push('view is a sequential scan. That failure is invisible to every test written')
-  out.push('from a member’s point of view, which is most of them.')
+  out.push(
+    'Both visible-content partial indexes and their unfiltered counterparts are checked. Moderator queries need the unfiltered indexes when their scope includes hidden content.',
+  )
   out.push('')
 
-  out.push('## What each scenario is and why it is measured')
+  out.push('## Scenarios')
   out.push('')
 
   for (const budget of budgets) {
diff --git a/scripts/plugin-hook-docs.mjs b/scripts/plugin-hook-docs.mjs
index e28ff10f2..811626f3b 100644
--- a/scripts/plugin-hook-docs.mjs
+++ b/scripts/plugin-hook-docs.mjs
@@ -156,30 +156,13 @@ function render({ hooks, signatures, regions, wired }) {
     '  disagree.',
     '-->',
     '',
-    `**${hooks.length} hooks** — ${filters} filters, ${hooks.length - filters} events — and ` +
-      `${regions.length} UI regions. **${wired.size} are wired**: something in the board fires`,
-    'them today, and the rest are declared but not yet reached by a call site.',
+    `${hooks.length} hooks: ${filters} filters and ${hooks.length - filters} events. ${regions.length} UI regions.`,
     '',
-    'The wired column is derived from the tree by `scripts/hook-callsites.mjs`, not',
-    'maintained by hand — a registry entry with no call site is a promise about code',
-    'that never runs, and it fails in the quietest possible way: the plugin installs,',
-    'the handler registers, nothing happens. `plugins/reference` is required by its own',
-    'test to handle every wired hook, so a hook cannot join that column without',
-    'something proving it fires.',
+    `${wired.size} hooks have call sites in this build. The Wired column is generated from the source tree.`,
     '',
-    'A **filter** is handed a value and returns a replacement; its result is used, so a',
-    'filter that throws or returns nothing leaves the value as it was and the chain',
-    'carries on with the next plugin. An **event** is told what happened and its return',
-    'value is discarded — which is why anything that only wants to observe should be one:',
-    'it cannot corrupt the thing it is watching even when it is wrong.',
+    'Filters return replacement values; throwing or returning undefined retains the previous value. Event return values are ignored.',
     '',
-    'Handlers run in **(priority, plugin key)** order. Both halves are declared, so two',
-    'plugins compose the same way on every request and on every instance.',
-    '',
-    'Every handler is called inside the host’s try/catch and is timed. Failures are',
-    'counted in the database, so a plugin that fails repeatedly is switched off across',
-    'the whole board and stays off until an operator clears the record. See',
-    '[`plugins.md`](../extensions/plugins.md) for the policy, the lifecycle and the limits.',
+    'Handlers run by priority, then plugin key. See [Hooks and lifecycle](../extensions/plugin-hooks-guide.md) for failures, runtime access and lifecycle rules.',
     '',
   )
 
@@ -207,11 +190,7 @@ function render({ hooks, signatures, regions, wired }) {
   push(
     '## UI regions',
     '',
-    'Regions are **not** theme slots. A theme owns its slots; a region is an explicit',
-    '"plugins may add something here" point that a theme chooses to render, so the theme',
-    'keeps control of where plugin output appears and the plugin keeps control of what it',
-    'is. Several plugins contributing to one region compose by concatenation, in the same',
-    'deterministic order as hooks.',
+    'Themes place these regions. Enabled plugin contributions are concatenated in hook order.',
     '',
     '| Region | What it is handed |',
     '|---|---|',
diff --git a/scripts/site-docs.mjs b/scripts/site-docs.mjs
index 4805ccf1e..786be8a82 100644
--- a/scripts/site-docs.mjs
+++ b/scripts/site-docs.mjs
@@ -94,14 +94,14 @@ for (const section of manifest.sections) {
 function renderIndex() {
   const lines = [START, '']
   for (const section of manifest.sections) {
-    lines.push(`## ${section.title}`, '', section.blurb, '')
+    lines.push(`## ${section.title}`, '')
     let previousGroup
     for (const doc of manifest.documents.filter((entry) => entry.section === section.id)) {
       if (doc.group !== undefined && doc.group !== previousGroup) {
-        if (previousGroup !== undefined) lines.push('')
+        if (lines.at(-1) !== '') lines.push('')
         lines.push(`### ${doc.group}`, '')
       }
-      lines.push(`- [${doc.title}](./${doc.file}) — ${doc.blurb}`)
+      lines.push(`- [${doc.title}](./${doc.file})`)
       previousGroup = doc.group
     }
     lines.push('')
diff --git a/scripts/theme-api-docs.mjs b/scripts/theme-api-docs.mjs
index dcb4fd5dc..dbc848318 100644
--- a/scripts/theme-api-docs.mjs
+++ b/scripts/theme-api-docs.mjs
@@ -334,11 +334,9 @@ function render({ slots, freeze, models, slotModels }) {
     `**theme-kit v${freeze.version}.** ${slots.length} slots: ${counts.stable} stable, ` +
       `${counts.provisional} provisional, ${counts.deprecated} deprecated.`,
     '',
-    'What the marks mean, and how something is removed, is in',
-    '[`themes.md`](../extensions/themes.md). In short: a **stable** slot and the fields of its',
-    'model do not change before the next major; a **provisional** slot is named but not yet rendered',
-    'by any page, so its model may change in a minor release; a **deprecated** slot still',
-    'works and has a removal scheduled below.',
+    'Stable contracts retain existing fields until a major release. Provisional models may change in a minor. Deprecated contracts remain available until their scheduled removal.',
+    '',
+    'See [Theme contract](../extensions/theme-contract.md) for implementation and versioning rules.',
     '',
     '## Every slot',
     '',
@@ -395,11 +393,7 @@ function render({ slots, freeze, models, slotModels }) {
   for (const name of slotModelNames) shared.delete(name)
 
   push('## Shared models', '')
-  push(
-    'Referenced by the models above. Same promise: a field of a shared model reached',
-    'from a stable slot is stable.',
-    '',
-  )
+  push('Fields reached from a stable slot share its stability guarantee.', '')
   for (const name of [...shared].sort()) {
     push(`### ${name}`, '')
     const doc = models.get(name)?.doc ?? ''
@@ -409,11 +403,7 @@ function render({ slots, freeze, models, slotModels }) {
 
   push('## Scheduled removals', '')
   if (freeze.deprecations.length === 0) {
-    push(
-      `Nothing is deprecated in v${freeze.version}. Nothing can be: this is the first`,
-      'frozen contract, so there is no earlier promise to withdraw.',
-      '',
-    )
+    push(`No deprecations in v${freeze.version}.`, '')
   } else {
     push('| What | Deprecated in | Removed in | Replacement | Reason |', '|---|---|---|---|---|')
     for (const entry of freeze.deprecations) {