diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md
index 0825b057c45..c9716f87489 100644
--- a/.agents/skills/commit/SKILL.md
+++ b/.agents/skills/commit/SKILL.md
@@ -16,7 +16,11 @@ Use this skill whenever the user asks you to create a git commit for the current
 2. Only stage files relevant to the requested change. Do not include unrelated untracked files, generated files, or likely-local artifacts.
 3. Read and follow `.github/CONTRIBUTING.md#commit-messages`. It is the
    source of truth for Ghost's commit conventions.
-4. Run `git status --short` after committing and confirm the result.
+4. For publishable packages, check whether a release intent is required. A
+   package `README.md` is published and requires a release; repository-only
+   Markdown such as `AGENTS.md`, `CLAUDE.md`, changelogs, and package-local
+   `docs/` does not.
+5. Run `git status --short` after committing and confirm the result.
 
 ## Important
 - Do not push to remote unless the user explicitly asks
diff --git a/.changeset/loose-pans-argue.md b/.changeset/loose-pans-argue.md
new file mode 100644
index 00000000000..2da772de325
--- /dev/null
+++ b/.changeset/loose-pans-argue.md
@@ -0,0 +1,5 @@
+---
+"@tryghost/koenig-lexical": patch
+---
+
+Updated Koenig Lexical testing documentation.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index f96ce800a6d..01af2f04490 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -90,6 +90,10 @@ This records which packages changed and the bump type (patch / minor / major); t
 pnpm change --bump none
 ```
 
+A package `README.md` is published with the package and requires a release.
+Repository-only Markdown such as `AGENTS.md`, `CLAUDE.md`, changelogs, and
+package-local `docs/` does not.
+
 CI enforces this — the **Check app version bump** job fails a pull request that affects a publishable package without a covering changeset. The pre-commit hook prints a non-blocking reminder locally, and `pnpm change status` shows what's currently pending.
 
 For more detail, see the [contribution workflow](../docs/contributing/workflow.md).
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7df90c7bba3..ba606ade48e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -173,9 +173,6 @@ jobs:
               - '.github/workflows/ci.yml'
             core:
               - *shared
-              # Documentation and ownership metadata do not affect Ghost
-              # runtime behaviour, even when they live inside a project root.
-              - '!**/*.md'
               - '!.github/CODEOWNERS'
               - 'ghost/**'
               - '!ghost/core/core/server/data/tinybird/**'
@@ -192,6 +189,10 @@ jobs:
               - '!koenig/kg-unsplash-selector/**'
               - '!koenig/kg-simplemde/**'
               - '!koenig/*/test/**'
+              # Documentation does not affect Ghost runtime behaviour, even
+              # when it lives inside a project root. Keep this after every
+              # positive pattern so micromatch cannot add Markdown files back.
+              - '!**/*.md'
             unit-test-globals:
               - 'vitest.config.mjs'
             core-unit-test-globals:
diff --git a/AGENTS.md b/AGENTS.md
index 3c5d55fb57c..002fae02d6e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,11 +1,8 @@
 # AGENTS.md
 
-This file provides guidance to AI Agents when working with code in this repository.
-
-Human-readable setup, workflow, testing, shipping, and architecture guidance
-lives in the [codebase documentation](docs/README.md). Treat those guides and
-nearby package READMEs as the source of truth for facts shared by humans and
-agents. This file adds agent-specific execution rules and code constraints.
+Agent-specific execution guidance for the Ghost monorepo. Human-readable setup,
+workflow, architecture, and practice guidance lives in the
+[codebase documentation](docs/README.md) and nearby package READMEs.
 
 Start with:
 
@@ -16,192 +13,54 @@ Start with:
 - [Shipping](docs/contributing/shipping.md)
 - [Monorepo structure](docs/codebase/monorepo-structure.md)
 
-## Package Manager
-
-**Always use `pnpm` for all commands.** This repository uses pnpm workspaces, not npm.
-
-Shared dependency versions are pinned in `pnpm-workspace.yaml` under `catalog:` and referenced as `"pkg": "catalog:"` (or `catalog:<name>` for named catalogs). `catalogMode` is `strict`, so `pnpm add` routes new deps into the catalog automatically — don't inline the version.
-
-## Required Workflow
+## Required workflow
 
+- Always use `pnpm`, never npm or Yarn. External dependency versions belong in
+  the catalogs in `pnpm-workspace.yaml`; workspace dependencies use
+  `workspace:` versions.
 - Run `pnpm setup` before other commands in a fresh checkout or worktree.
-- Use `pnpm check` as the default full validation command. Follow the
-  [testing guide](docs/contributing/testing.md) for focused commands and the
-  browser E2E and Ember Admin suites that run separately.
-- Read the nearest `AGENTS.md`, `CLAUDE.md`, and README files before changing a
-  package or subsystem. More specific instructions override this file.
-
-## Architecture Patterns
-
-### Admin Apps Integration (Micro-Frontend)
-
-**Build Process:**
-1. Admin-x React apps build to `apps/*/dist` using Vite
-2. `apps/ember-admin/lib/asset-delivery` copies them to `ghost/core/core/built/admin/assets/*`
-3. Ghost admin serves from `/ghost/assets/{app-name}/{app-name}.js`
-
-**Runtime Loading:**
-- Ember admin uses `AdminXComponent` to dynamically import React apps
-- React components wrapped in Suspense with error boundaries
-- Apps receive config via `additionalProps()` method
-
-### Public Apps Integration
-
-- Built as UMD bundles to `apps/*/umd/*.min.js`
-- Loaded via `<script>` tags in theme templates (injected by `{{ghost_head}}`)
-- Configuration passed via data attributes
-
-### i18n Architecture
-
-**Centralized Translations:**
-- Single source: `packages/i18n/locales/{locale}/{namespace}.json`
-- Namespaces: `ghost`, `portal`, `signup-form`, `comments`, `search`
-- 60+ supported locales
-- Context descriptions: `packages/i18n/locales/context.json` — every key must have a non-empty description
-
-**Translation Workflow:**
-```bash
-pnpm --filter @tryghost/i18n translate          # Extract keys from source, update all locale files + context.json
-pnpm --filter @tryghost/i18n lint:translations   # Validate interpolation variables across locales
-```
-
-`translate` is run as part of `pnpm --filter @tryghost/i18n test`. In CI, it fails if translation keys or `context.json` are out of date (`failOnUpdate: process.env.CI`). Always run `pnpm --filter @tryghost/i18n translate` after adding or changing `t()` calls.
-
-**Rules for Translation Keys:**
-1. **Never split sentences across multiple `t()` calls.** Translators cannot reorder words across separate keys. Instead, use `@doist/react-interpolate` to embed React elements (links, bold, etc.) within a single translatable string.
-2. **Always provide context descriptions.** When adding a new key, add a description in `context.json` explaining where the string appears and what it does. CI will reject empty descriptions.
-3. **Use interpolation for dynamic values.** Ghost uses `{variable}` syntax: `t('Welcome back, {name}!', {name: firstname})`
-4. **Use `<tag>` syntax for inline elements.** Combined with `@doist/react-interpolate`: `t('Click <a>here</a> to retry')` with `mapping={{ a: <a href="..." /> }}`
-
-**Correct pattern (using Interpolate):**
-```jsx
-import Interpolate from '@doist/react-interpolate';
-
-<Interpolate
-    mapping={{ a: <a href={link} /> }}
-    string={t('Could not sign in. <a>Click here to retry</a>')}
-/>
-```
-
-**Incorrect pattern (split sentences):**
-```jsx
-// BAD: translators cannot reorder "Click here to retry" relative to the first sentence
-{t('Could not sign in.')} <a href={link}>{t('Click here to retry')}</a>
-```
-
-See `apps/portal/src/components/pages/email-receiving-faq.jsx` for a canonical example of correct `Interpolate` usage.
-
-### Build Dependencies (Nx)
-
-Critical build order (Nx handles automatically):
-1. `shade` + `admin-x-design-system` build
-2. `admin-x-framework` builds (depends on #1)
-3. Admin apps build (depend on #2)
-4. `apps/ember-admin` builds (depends on #3, copies via asset-delivery)
-5. `ghost/core` serves admin build
-
-## CSS Architecture
-
-### TailwindCSS v4 Setup
-
-Ghost Admin uses **TailwindCSS v4** via the `@tailwindcss/vite` plugin. CSS processing is centralized — only `apps/admin/vite.config.ts` loads the `@tailwindcss/vite` plugin. Embedded React apps (activitypub) are scanned from this single entry point alongside admin's own source.
-
-### Entry Point
-
-`apps/admin/src/index.css` is the main CSS entry point. It contains:
-- `@source` directives that scan class usage in shade, activitypub, admin-x-framework, and kg-unsplash-selector
-- `@import "@tryghost/shade/styles.css"` which loads the Shade design system styles
-
-### Shade Styles
-
-`apps/shade/styles.css` uses **unlayered** Tailwind imports:
-```css
-@import "tailwindcss/theme.css";
-@import "./preflight.css";
-@import "tailwindcss/utilities.css";
-@import "tw-animate-css";
-@import "./tailwind.theme.css";
-```
-
-**Why unlayered:** Ember's legacy CSS (`.flex`, `.hidden`, etc.) is unlayered. If Tailwind utilities were in a `@layer`, they would lose to Ember's unlayered CSS in the cascade. Keeping both unlayered means source order determines specificity.
-
-Theme tokens/variants/animations are defined in CSS (`apps/shade/tailwind.theme.css` + runtime vars in `styles.css`), so there is no JS `@config` bridge in the Admin runtime lane. `tw-animate-css` is the v4 replacement for `tailwindcss-animate`.
-
-### Critical Rule: Embedded Apps Must NOT Import Shade Independently
-
-Apps consumed via `@source` (activitypub) must **NOT** import `@tryghost/shade/styles.css` in their own CSS. Doing so causes duplicate Tailwind utilities and cascade conflicts. All Tailwind CSS is generated once via the admin entry point.
-
-### Public Apps
-
-Public-facing apps (`comments-ui`, `signup-form`, `sodo-search`, `portal`, `announcement-bar`) remain on **TailwindCSS v3**. They are built as UMD bundles for CDN distribution and are independent of the admin CSS pipeline.
-
-## Code Guidelines
-
-### Repository Skills
-
-Repository skills live in `.agents/skills/<skill-name>`. When adding a skill,
-also add `.claude/skills/<skill-name>` as a symlink to
-`../../.agents/skills/<skill-name>` so Claude can discover the same canonical
-skill without duplicating it. Run `pnpm lint:agent-skills` to verify every
-repository skill is linked correctly; CI runs the same check.
-
-### Commit Messages
-When the user asks you to create a commit or draft a commit message, load and
-follow the `commit` skill from `.agents/skills/commit`. Read the canonical
-[commit message guidelines](.github/CONTRIBUTING.md#commit-messages), and apply
-the subject convention carefully to PR titles and proposed squash commits.
-Local hook notices on intermediate commits are best-effort guidance.
-
-### ESLint Config
-Source of truth: two internal config packages — [`@internal/cfg-eslint`](configs/eslint/index.mjs) (shared rule atoms + the `nodeLibConfig` factory for Node libs) and [`@internal/cfg-eslint-react`](configs/eslint-react/index.mjs) (the `reactAppConfig` factory for every `apps/*` workspace). Both factories are synchronous and have full JSDoc with `@example`s; hover the call site in your editor. Consume them by name — declare the package as a `workspace:*` devDependency.
-
-Minimal example for a new admin React app (`apps/new-feature/eslint.config.js`):
-
-```js
-import {reactAppConfig} from '@internal/cfg-eslint-react';
-export default reactAppConfig({
-    tailwindCssPath: `${import.meta.dirname}/../admin/src/index.css`,
-    shadeRestricted: true
-});
-```
-
-Conventions:
-- **Rules are `'error'` or `'off'` — never `'warn'`.** Warnings get ignored and pollute output. Applies to every workspace covered by the factories above + the standalones; `e2e/` has its own setup (see [e2e/CLAUDE.md](e2e/CLAUDE.md)) and currently still uses warn-level Playwright rules — a separate cleanup.
-- **Params prefixed `legacy*`** (`legacyTailwindV3ConfigPath`, `legacyJsTsSplit`) are escape hatches for migrations that haven't shipped yet. Intentional and visible — PRs to remove them are scoped.
-- **Standalone configs** (`ghost/core`, `apps/ember-admin`, `apps/admin-toolbar`) exist because their rule sets genuinely don't fit a factory — read the file directly. They import shared atoms (`correctnessRules`, `nodeLibRules`, `localFilenamesPlugin`, `strictLinterOptions`) from `@internal/cfg-eslint`.
-- **Plugin deps**: a workspace must declare every eslint plugin its config resolves. Two cases:
-  - *Factory consumers* only import a factory, which supplies its plugins as objects from the config package — so they need just the config package (`@internal/cfg-eslint` / `@internal/cfg-eslint-react`) as a `workspace:*` devDependency, not the individual plugins.
-  - *Hand-rolled configs* (the standalones above, plus the inline configs in `koenig/kg-*` and `e2e/`) `import` plugins directly, so each must list those plugins in its own `devDependencies` — most commonly `eslint-plugin-ghost: catalog:`. Don't rely on the root hoisting a plugin for you; there are no eslint plugins left in the root `package.json` (only `eslint` itself and `globals`, which the root config uses).
-  - Exception: Tailwind — a workspace that uses it must list `tailwindcss` as its own (dev)Dependency regardless (the settings-based resolver requires it locally), and the legacy v3 apps pin `eslint-plugin-tailwindcss` via `catalog:tailwind3`.
-
-### When Working on Admin UI
-- **New features:** Build in React in `apps/admin` (domain folders under `src/`)
-- **Use:** `admin-x-framework` for API hooks (`useBrowse`, `useEdit`, etc.)
-- **Use:** `shade` design system for new components (not admin-x-design-system)
-- **Translations:** Add to `packages/i18n/locales/en/ghost.json`
-- **Deploy skew:** Ghost Admin and Ghost core deploy independently. New admin UI that depends on new settings, endpoints, or config must feature-detect backend support (e.g. settings-key presence in the browse response, as in `social-accounts.tsx`) and hide or no-op when absent. Labs flags alone are not a deploy-skew guard. Add an acceptance test for the “backend not deployed yet” case.
-
-### When Working on Public UI
-- **Edit:** `apps/portal`, `apps/comments-ui`, etc.
-- **Translations:** Separate namespaces (`portal.json`, `comments.json`)
-- **Build:** UMD bundles for CDN distribution
-
-### When Working on Backend
-- **Core logic:** `ghost/core/core/server/`
-- **Database Schema:** `ghost/core/core/server/data/schema/`
-- **API routes:** `ghost/core/core/server/api/`
-- **Services:** `ghost/core/core/server/services/`
-- **Models:** `ghost/core/core/server/models/`
-- **Frontend & theme rendering:** `ghost/core/core/frontend/`
-- **TypeScript by default:** New code under `ghost/core/core/server/services/` is TypeScript unless extending an existing JS module. Follow the gifts/donations pattern: domain logic as `.ts` with named exports; thin CJS `index.js` / `*-wrapper.js` only where boot/`require` still needs them.
-- **Service init:** New services get an explicit `init()` call from `ghost/core/core/boot.js` (same Promise.all as donations/gifts). Keep the wrapper’s `init()` idempotent so early callers are safe, but boot owns construction — not first request.
-
-### Design System Usage
-- **New components:** Use `shade` (shadcn/ui-inspired)
-- **Legacy:** `admin-x-design-system` (being phased out, avoid for new work)
-
-### Analytics (Tinybird)
-- **Local development:** `pnpm dev:analytics` (starts Tinybird + MySQL)
-- **Config:** Add Tinybird config to `ghost/core/config.development.json`
-- **Scripts:** `ghost/core/core/server/data/tinybird/scripts/`
-- **Datafiles:** `ghost/core/core/server/data/tinybird/`
+- Use `pnpm check` as the default full validation command. Browser E2E and Ember
+  Admin tests run separately; follow the testing guide.
+- Read the nearest `AGENTS.md`, `CLAUDE.md`, and README before changing a package
+  or subsystem. More specific guidance overrides this file.
+- When committing, load and follow `.agents/skills/commit/SKILL.md`.
+
+## Repository skills
+
+Repository skills live under `.agents/skills/`. When adding one, also add the
+matching `.claude/skills/<name>` symlink to
+`../../.agents/skills/<name>`. Run `pnpm lint:agent-skills` to verify discovery.
+
+Use the relevant repository skill before adding an Admin API endpoint, database
+migration, private feature flag, Shade component, or internal package.
+
+## Task routing and important warnings
+
+- **Admin UI:** read [`apps/admin/README.md`](apps/admin/README.md) and
+  [`apps/shade/AGENTS.md`](apps/shade/AGENTS.md). Build new features in React,
+  use `admin-x-framework` for APIs, and use Shade for UI. Admin and Core deploy
+  independently, so feature-detect backend support and test the older-backend
+  case.
+- **Embedded Admin CSS:** do not import `@tryghost/shade/styles.css` from an
+  embedded app. Admin owns the single Tailwind and Shade CSS lane.
+- **Translations:** follow the
+  [internationalization guide](docs/practices/internationalization.md). Run the
+  extraction command after changing `t()` calls and never split one sentence
+  across translation calls.
+- **Public apps:** read the app's README and the
+  [shipping guide](docs/contributing/shipping.md). Their release and CSS lanes
+  differ from Admin.
+- **Ghost Core:** use the [server map](docs/codebase/monorepo-structure.md#ghost-core)
+  and read the [services guide](ghost/core/core/server/services/README.md) before
+  adding a service. New standalone services use TypeScript; keep CommonJS only
+  at existing `require()` boundaries. Boot owns service initialization; do not
+  initialize on the first request.
+- **ESLint:** use the shared factories and dependency rules in the
+  [ESLint configuration README](configs/eslint/README.md). A hand-written config
+  must declare every plugin it imports locally.
+- **Analytics:** start with `pnpm dev:analytics` and follow the nearby Tinybird
+  READMEs under `ghost/core/core/server/data/tinybird/`.
+
+Keep shared facts in human documentation. This file should contain only routing,
+agent execution constraints, and high-value warnings that prevent recurring
+mistakes.
diff --git a/apps/admin/README.md b/apps/admin/README.md
index 882920b1e5c..e4eddfe27d4 100644
--- a/apps/admin/README.md
+++ b/apps/admin/README.md
@@ -9,6 +9,39 @@ Uses an **Ember Bridge** system for smooth migration:
 - Unported routes fall back to the existing Ember admin
 - Both share the same UI space seamlessly
 
+The React application uses `admin-x-framework` for API hooks, routing, and the
+bridge to Ember. Shade provides its application wrapper and design system.
+Embedded React applications are built before Ember Admin; Ember's asset-delivery
+addon copies their production output and the Admin assets into
+`ghost/core/core/built/admin/` for Ghost Core to serve.
+
+### CSS
+
+`src/index.css` is the single Tailwind CSS entry point for Admin. It imports
+Shade's styles and uses `@source` directives to scan Admin, Shade, ActivityPub,
+Admin Framework, and the embedded Koenig selector. Only this app loads the
+`@tailwindcss/vite` plugin for the embedded Admin CSS lane.
+
+Embedded Admin apps must not import `@tryghost/shade/styles.css` themselves.
+Doing so generates duplicate utilities and creates cascade conflicts with
+Ember's legacy CSS.
+
+Shade's Tailwind imports are unlayered because Ember's legacy CSS is also
+unlayered. This lets source order resolve overlapping utilities. Do not move
+Shade's imports into a CSS layer without accounting for the legacy cascade.
+
+### Deploy compatibility
+
+Ghost Admin and Ghost Core can deploy at different times. New Admin UI that
+depends on a new setting, endpoint, or configuration value must detect backend
+support and hide or safely disable the feature when it is absent. A Labs flag
+alone is not a compatibility check because the flag may exist before the
+supporting backend version is live.
+
+Add an acceptance test for the older-backend case. The social accounts settings
+and membership tiers tests contain current examples of hiding controls until
+their supporting settings are present.
+
 ## Development
 
 ```bash
@@ -16,6 +49,11 @@ Uses an **Ember Bridge** system for smooth migration:
 pnpm dev
 ```
 
+Build new Admin features in this React app. Use `admin-x-framework` for API
+access and Shade for UI rather than adding new `admin-x-design-system`
+components. Product copy belongs in the `ghost` namespace; follow the
+[internationalization guide](../../docs/practices/internationalization.md).
+
 ## Testing
 
 - **Unit tests** (`pnpm test:unit`): Vitest + jsdom, colocated `*.test.ts(x)` files.
@@ -30,4 +68,3 @@ pnpm nx run @tryghost/admin:build
 ```
 
 This outputs to `apps/admin/dist/` and updates the assets in `ghost/core/core/built/admin/`.
-
diff --git a/configs/eslint/README.md b/configs/eslint/README.md
new file mode 100644
index 00000000000..bff13f8b784
--- /dev/null
+++ b/configs/eslint/README.md
@@ -0,0 +1,47 @@
+# Shared ESLint configuration
+
+Ghost's shared ESLint rules live in two internal packages:
+
+- `@internal/cfg-eslint` provides shared rule atoms and `nodeLibConfig()` for
+  Node.js libraries.
+- `@internal/cfg-eslint-react` provides `reactAppConfig()` for React apps under
+  `apps/`.
+
+Both factories are synchronous and document their options with JSDoc and
+examples in their `index.mjs` files. Add the relevant package as a
+`workspace:*` development dependency and consume the factory by name.
+
+```js
+import {reactAppConfig} from '@internal/cfg-eslint-react';
+
+export default reactAppConfig({
+    tailwindCssPath: `${import.meta.dirname}/../admin/src/index.css`,
+    shadeRestricted: true
+});
+```
+
+## Rules and exceptions
+
+Factory consumers use `error` or `off`, not `warn`. Parameters prefixed with
+`legacy`, including `legacyTailwindV3ConfigPath` and `legacyJsTsSplit`, mark
+temporary migration exceptions rather than defaults for new work.
+
+Ghost Core, Ember Admin, and Admin Toolbar keep standalone configurations
+because their rule sets do not fit a shared factory. Read those files directly.
+They can still import shared atoms such as `correctnessRules`, `nodeLibRules`,
+`localFilenamesPlugin`, and `strictLinterOptions` from `@internal/cfg-eslint`.
+
+## Plugin dependencies
+
+A workspace must declare every ESLint plugin that its configuration resolves.
+
+- A factory consumer only needs the config package because the factory supplies
+  its plugins as objects.
+- A hand-written config that imports a plugin directly must declare that plugin
+  in its own `devDependencies`. Do not rely on root dependency hoisting.
+- A workspace using Tailwind must declare `tailwindcss` locally. Legacy
+  Tailwind v3 apps also use the `tailwind3` catalog entry for
+  `eslint-plugin-tailwindcss`.
+
+Run the workspace's `pnpm lint` target after changing its config. Run the root
+lint when changing shared rule atoms or either factory.
diff --git a/docs/README.md b/docs/README.md
index 053c6ccdf49..5d45f49e242 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -84,6 +84,7 @@ Codebase guides explain how the main systems fit together:
 - [Post analytics](codebase/post-analytics.md)
 - [Site UUID](codebase/site-uuid.md)
 - [Stripe flows](codebase/stripe-flows.md)
+- [Theme compatibility](codebase/theme-compatibility.md)
 
 Practice and contributor guides explain how to make and verify changes:
 
diff --git a/docs/codebase/database.md b/docs/codebase/database.md
index 88b47248324..b8ba833c38c 100644
--- a/docs/codebase/database.md
+++ b/docs/codebase/database.md
@@ -6,6 +6,9 @@ current shape expected after every migration has run. Bookshelf models in
 [`models/`](../../ghost/core/core/server/models/) define relationships and
 application behavior; do not infer those rules from the table shape alone.
 
+The sections below are domain maps, not a replacement for the schema. They
+explain why related tables exist and where to start when changing them.
+
 ## Posts
 
 Post statuses are `draft`, `scheduled`, `published`, and `sent`. Sent posts are
@@ -34,6 +37,68 @@ their referrer fields record the source, medium, and URL where available.
 The `source` on a member-created event records what created the member. Its
 values are `member`, `import`, `system`, `api`, and `admin`.
 
+## Members
+
+`members` is the central record for a reader. It stores identity, status,
+profile information, email engagement totals, and communication preferences.
+Related data is separated by responsibility:
+
+| Responsibility | Tables |
+| --- | --- |
+| Labels | `labels`, `members_labels` |
+| Custom fields | `members_custom_fields`, `members_custom_field_values` |
+| Newsletter subscriptions | `newsletters`, `members_newsletters` |
+| Tiers and access | `products`, `members_products`, `subscriptions` |
+| Stripe state | `members_stripe_customers`, `members_stripe_customers_subscriptions`, `members_current_subscription`, `stripe_products`, `stripe_prices` |
+| Offers | `offers`, `offer_redemptions` |
+| Lifecycle and attribution history | the `members_*_events` tables |
+
+`labels` has a many-to-many relationship with `members` through
+`members_labels`. Newsletter subscriptions use the same pattern through
+`members_newsletters`. Custom-field definitions are stored once in
+`members_custom_fields`; `members_custom_field_values` stores the values a
+member has supplied.
+
+Ghost keeps a provider-independent subscription in `subscriptions`. The Stripe
+tables cache the provider records needed to synchronize paid membership state.
+`members_current_subscription` is the one-row-per-member lookup used to expose
+the resolved Stripe subscription in Admin and member filtering. Read the member
+model, the resolved-subscription view, and the Stripe service as well as the
+schema before changing these relationships.
+
+The event tables are append-oriented history used for attribution, analytics,
+and changes to member or subscription state. They are not alternative sources
+of truth for the current member record.
+
+## Newsletters and email
+
+A newsletter send is represented across four main tables:
+
+| Table | Purpose |
+| --- | --- |
+| `emails` | One send for one post, including rendered content, recipient filter, aggregate counts, tracking options, and overall status |
+| `email_batches` | Provider submissions for an email, including the member segment, provider identifier, status, and batch-level errors |
+| `email_recipients` | The recipients selected for a send, their batch, a snapshot of member identity, and processing/delivery/open/failure timestamps |
+| `email_recipient_failures` | Structured temporary or permanent delivery failure information for a recipient |
+
+This split answers three different questions: `emails` records what Ghost sent,
+`email_batches` records how it was submitted to the provider, and
+`email_recipients` records who was included and what happened to each delivery.
+Do not reconstruct a historical recipient list from current member or segment
+state; the recipient rows are the send-time record.
+
+`posts.newsletter_id` and `emails.newsletter_id` associate the content and send
+with a newsletter. The `newsletters` table owns newsletter identity, sender
+configuration, subscription defaults, and presentation settings.
+
+`email_spam_complaint_events` records complaint events associated with a member
+and email. Member rows also cache aggregate engagement values for browsing and
+filtering; the per-send and per-recipient tables remain the detailed record.
+
+Automated emails use a separate set of `automation_*`,
+`welcome_email_automation_*`, and `automated_email_recipients` tables. They do
+not create newsletter `emails` and `email_recipients` rows.
+
 ## Link redirects and clicks
 
 `redirects` stores the source path, destination, and associated post or
@@ -49,3 +114,5 @@ amount, and payment-provider links.
 For changing this structure, follow the
 [database migrations guide](../practices/database-migrations.md). Keep the
 schema definition, migration, exporter table lists, and integrity tests in sync.
+For initial data and settings defaults, see the
+[schema and default data guide](../../ghost/core/core/server/data/schema/README.md).
diff --git a/docs/codebase/monorepo-structure.md b/docs/codebase/monorepo-structure.md
index 55ffc4331ee..435582eed92 100644
--- a/docs/codebase/monorepo-structure.md
+++ b/docs/codebase/monorepo-structure.md
@@ -34,6 +34,10 @@ service before changing it.
 - `shade/` is the current Admin design system.
 - `admin-x-framework/` provides shared Admin API hooks, routing, and utilities.
 
+The public apps build browser bundles loaded with script tags and read runtime
+configuration from data attributes. Ghost Core renders these integrations
+through theme helpers such as `{{ghost_head}}` and `{{comments}}`.
+
 Admin combines the React and Ember applications into one interface. See
 [`apps/admin/README.md`](../../apps/admin/README.md) for the current integration
 boundary.
@@ -54,6 +58,9 @@ Built Admin assets are copied into `ghost/core/core/built/admin/` for the Ghost
 release. Treat `built/`, `build/`, `dist/`, and `umd/` as generated output unless
 a nearby README says otherwise.
 
+For conventions used when adding a Ghost Core service, see the
+[services README](../../ghost/core/core/server/services/README.md).
+
 ## Koenig
 
 `koenig/` contains the Lexical editor UI and the `kg-*` packages used to store,
@@ -77,6 +84,8 @@ modernizing an internal package. New internal packages start from
 
 `configs/` contains shared configuration packages. Workspaces depend on them by
 package name instead of copying configuration into each project.
+The [shared ESLint README](../../configs/eslint/README.md) explains the Node and
+React factories, standalone exceptions, and plugin dependency rules.
 
 ## Workspace dependencies
 
diff --git a/docs/codebase/theme-compatibility.md b/docs/codebase/theme-compatibility.md
new file mode 100644
index 00000000000..8a0a55831c9
--- /dev/null
+++ b/docs/codebase/theme-compatibility.md
@@ -0,0 +1,107 @@
+# Theme compatibility
+
+Ghost themes use Handlebars templates and helpers provided by Ghost. When Ghost
+adds a theme feature and a theme starts using it, that theme is not compatible
+with older Ghost versions that do not provide the feature. When Ghost removes
+or changes a theme feature, older themes may stop working on the new version.
+
+Incompatibility does not always produce a clear error. A feature may do nothing,
+content may disappear, the output may look wrong, or a page may return an
+error. People also commonly install the latest release of a theme on an older
+Ghost version, or update Ghost without first checking their theme.
+
+[GScan](https://github.com/TryGhost/gscan) validates themes against the rules
+for a Ghost major version. Ghost runs GScan when it loads or uploads a theme and
+shows the results in Admin. Theme developers can also use
+[gscan.ghost.org](https://gscan.ghost.org/) or the GScan command-line tool.
+
+## Why Ghost uses GScan
+
+Ghost originally relied on theme developers declaring the supported Ghost
+version in `package.json`:
+
+```json
+{
+  "engines": {
+    "ghost": "^5.5.0"
+  }
+}
+```
+
+That requires a theme developer to know which Ghost release introduced every
+feature the theme uses and to keep the declaration current. In practice, the
+version was often wrong and people still experienced broken or missing output.
+
+GScan moves that compatibility knowledge into rules. It can recognize features
+that Ghost may add later, as well as features Ghost has removed or changed, and
+give people a clear explanation of what changed and how to respond. Usually the
+answer is to update Ghost or update the theme.
+
+## Compatibility messages
+
+GScan supports messages at four levels:
+
+- **Recommendation** provides information for theme developers.
+- **Warning** gives advance notice that a feature will be removed or changed.
+- **Error** identifies a change that may cause unexpected output.
+- **Fatal error** identifies a change that will cause Ghost to return an error
+  while rendering a page.
+
+Most GScan messages are non-fatal errors. They are shown when a theme is
+installed, but the user can choose to ignore them. Fatal errors prevent the
+theme from being activated.
+
+Use a fatal error only when a theme would throw an error while rendering a page,
+and introduce one only in a major Ghost version. Warnings are shown in Admin in
+development, and when GScan is run directly, but are hidden in Admin in
+production.
+
+## Changing the theme layer
+
+Changes to helpers, templates, `package.json` fields, assets, translations, or
+rendered markup may need a corresponding GScan change. Before changing a public
+theme contract:
+
+1. Decide which Ghost versions the old and new behaviour supports.
+2. Add or update a rule in the appropriate GScan check and version spec.
+3. Give the rule a clear description of what changed and how to fix it.
+4. Test the rule in GScan, then release GScan.
+5. Update the `gscan` dependency in `ghost/core/package.json` and run Ghost's
+   theme tests. Theme fixtures may also need updating.
+
+Version specs inherit the helpers and rules from the preceding major version.
+Add new compatibility information to the spec for the first Ghost major that
+uses it rather than rewriting an older version's contract.
+
+## Adding a Handlebars helper
+
+Theme-facing helpers live in
+[`ghost/core/core/frontend/helpers/`](../../ghost/core/core/frontend/helpers/),
+with unit tests in
+[`ghost/core/test/unit/frontend/helpers/`](../../ghost/core/test/unit/frontend/helpers/).
+
+Adding the implementation is not enough. GScan must know the helper name or it
+will report valid theme usage as an unknown helper. To add one:
+
+1. Add the helper and its unit tests in Ghost.
+2. Add its name to `knownHelpers` in the current major-version spec in GScan,
+   with GScan tests where needed.
+3. Release GScan and update `ghost/core/package.json` to that version.
+4. Run the Ghost helper registration and GScan compatibility test:
+
+   ```bash
+   pnpm --dir ghost/core test:unit \
+       test/unit/frontend/services/theme-engine/handlebars/helpers.test.js
+   ```
+
+The compatibility test compares theme-facing helper files with GScan's
+`knownHelpers` list. A helper that is deliberately internal or experimental
+must be explicitly excluded there with a reason.
+
+## Default themes
+
+[Casper](https://github.com/TryGhost/Casper) and
+[Source](https://github.com/TryGhost/Source) are included in this repository as
+Git submodules under `ghost/core/content/themes/`. Changes to Ghost's theme
+contract must remain compatible with these themes, and the Ghost theme tests
+must pass after a GScan update.
diff --git a/docs/contributing/workflow.md b/docs/contributing/workflow.md
index 14f2397bd57..f18ee7ec1bc 100644
--- a/docs/contributing/workflow.md
+++ b/docs/contributing/workflow.md
@@ -63,6 +63,10 @@ Choose patch, minor, or major according to the package's public compatibility
 impact. The summary becomes the changelog entry, so describe the result for the
 package's consumers.
 
+A package `README.md` is included when the package is published, so changing it
+requires a release. Repository-only Markdown such as `AGENTS.md`, `CLAUDE.md`,
+changelogs, and files under a package's `docs/` directory does not.
+
 If a changed publishable package genuinely requires no release—for example, a
 test-only or internal tooling change—record that explicitly:
 
diff --git a/ghost/core/core/server/data/schema/README.md b/ghost/core/core/server/data/schema/README.md
new file mode 100644
index 00000000000..03a8b11ca60
--- /dev/null
+++ b/ghost/core/core/server/data/schema/README.md
@@ -0,0 +1,87 @@
+# Schema and default data
+
+This directory defines the database shape and the records a new Ghost database
+starts with.
+
+## Sources of truth
+
+- `schema.js` is the final table and index structure expected after every
+  migration has run.
+- `fixtures/fixtures.json` contains durable records and relationships required
+  by a new site, including roles, permissions, the owner, starter content,
+  tiers, and a newsletter.
+- `default-settings/default-settings.json` defines the settings a site starts
+  with, grouped by responsibility.
+
+The initialization migrations create the tables and then use the fixture
+manager to add missing fixture records. The settings model flattens the grouped
+default-settings file and inserts settings missing from the database. Some
+values, such as signing keys and secrets, are generated when the defaults are
+populated rather than stored in the JSON file.
+
+Fixtures and default settings are different mechanisms. Fixtures create model
+records and relationships; default settings describe rows in the `settings`
+table.
+
+## Fixtures
+
+Fixture entries are added through their Bookshelf models. The fixture manager
+checks for an existing record before inserting it, adds roles and the owner
+before dependent records, and then creates the declared relationships.
+
+Use fixtures only for records every new Ghost installation requires. Sample
+development data belongs in the data generator, not in `fixtures.json`.
+
+When changing fixtures:
+
+1. Update `fixtures/fixtures.json`.
+2. Add a database migration when existing installations need the same change.
+3. Update affected models, exporter lists, and tests.
+4. Run the schema integrity test documented in the
+   [database migrations guide](../../../../../../docs/practices/database-migrations.md).
+
+## Default settings
+
+The top-level keys in `default-settings/default-settings.json` become setting
+groups. Each setting has a `defaultValue` and `type`, and may also declare
+validation and flags. The settings model adds the group and key when it
+flattens the file.
+
+Supported setting types include `string`, `number`, `boolean`, `array`, and
+`object`. Values are stored in the database in the representation expected by
+the settings model and cache.
+
+The flags used by settings migrations are:
+
+- `PUBLIC`: identifies a setting intended for a public settings surface.
+- `RO`: identifies a read-only setting.
+- `PUBLIC,RO`: applies both flags.
+
+Flags are part of the setting's stored contract, but each API surface still
+controls which settings it selects and how they may be changed. Check the
+relevant endpoint and serializer rather than assuming the flag alone grants
+access.
+
+The `core` group is restricted to internal access. Other groups organize
+settings that are commonly read or edited together; they do not by themselves
+make a setting public.
+
+When adding or changing a default setting:
+
+1. Update `default-settings/default-settings.json` for new installations.
+2. Add a migration for existing installations. Use the settings migration
+   utilities rather than inserting a row by hand.
+3. Update validation, API serializers, and tests when the setting's behaviour
+   requires it.
+4. Run the schema integrity test.
+
+Do not put environment-specific configuration in default settings. Runtime
+configuration belongs in Ghost's configuration system; see the
+[configuration guide](../../../../../../docs/codebase/configuration.md).
+
+## Schema changes
+
+Changing `schema.js` alone does not update an existing database. Every schema
+change needs a migration that moves an installed database to the new shape.
+Follow the [database migrations guide](../../../../../../docs/practices/database-migrations.md)
+for generation, iteration, testing, and review requirements.
diff --git a/ghost/core/core/server/services/README.md b/ghost/core/core/server/services/README.md
new file mode 100644
index 00000000000..101fd4fbf7c
--- /dev/null
+++ b/ghost/core/core/server/services/README.md
@@ -0,0 +1,30 @@
+# Ghost Core services
+
+Services under this directory own domain and integration logic used by Ghost
+Core. Follow an existing service in the same area when extending established
+code. New standalone service logic should be TypeScript unless it must extend an
+existing JavaScript module.
+
+The gifts, donations, and related services show the current transition pattern:
+domain logic uses TypeScript with named exports, while a thin CommonJS
+`index.js` or wrapper remains only where boot code or an existing `require()`
+boundary needs it.
+
+## Initialization
+
+Ghost's boot sequence owns service construction. A new service that requires
+initialization must expose an explicit `init()` and be called from
+`ghost/core/core/boot.js` in the appropriate boot phase. Do not make the first
+request responsible for constructing the service.
+
+Keep wrapper initialization idempotent when callers may safely reach it more
+than once. Add shutdown or cleanup handling to the boot lifecycle when the
+service owns resources that must be released.
+
+## Related guidance
+
+- [Monorepo structure](../../../../../docs/codebase/monorepo-structure.md)
+- [Configuration](../../../../../docs/codebase/configuration.md)
+- [Database migrations](../../../../../docs/practices/database-migrations.md)
+- [API design](../../../../../docs/practices/api-design.md)
+- [Error handling](../../../../../docs/practices/error-handling.md)
diff --git a/koenig/koenig-lexical/AGENTS.md b/koenig/koenig-lexical/AGENTS.md
index 5bb1242072f..b78a8d52cf7 100644
--- a/koenig/koenig-lexical/AGENTS.md
+++ b/koenig/koenig-lexical/AGENTS.md
@@ -1,26 +1,17 @@
-# Koenig Lexical Test Guide
+# Koenig Lexical agent guidance
 
-## Test Commands
+Read the [`README.md`](./README.md), especially its development, testing, and
+editor-integration sections, before changing this package.
 
-### Unit Tests
-```bash
-pnpm test:unit          # Run unit tests once
-pnpm test:unit:watch    # Run unit tests in watch mode
-```
+## Required workflow
 
-### Acceptance Tests (Playwright)
-```bash
-pnpm test:acceptance           # Run Playwright tests (headless, list reporter)
-pnpm test:acceptance:quiet     # Minimal output, failures only
-pnpm test:acceptance:headed    # Run with browser UI visible
-pnpm test:acceptance:report    # Run with HTML report
-pnpm test:slowmo               # Slow motion + UI
-```
-
-### All Tests
-```bash
-pnpm test               # Run unit + acceptance tests, then lint
-```
+- Always use `pnpm`.
+- These Playwright tests are package-level acceptance tests. Ghost's browser
+  E2E suite lives in the repository-level `e2e/` workspace.
+- Use `pnpm test:unit:watch` for focused unit-test development and
+  `pnpm test:acceptance:quiet` when concise acceptance-test output is useful.
+- Run the relevant focused tests while iterating, then run `pnpm test` and
+  `pnpm lint` before submitting changes.
 
 ## AI-Friendly Testing
 
@@ -31,30 +22,8 @@ The test runner has been configured to work well with AI agents:
 - **Clean exit**: Tests complete without hanging processes or opening browsers
 - **Clear output**: List reporter provides clear pass/fail information
 
-## Human-Friendly Testing
-
-For debugging and development:
-
-- Use `pnpm test:acceptance:headed` to see the browser UI
-- Use `pnpm test:acceptance:report` to generate an HTML report
-- Use `pnpm test:slowmo` for slow-motion debugging
-
-## Environment Variables
-
-- `PLAYWRIGHT_HEADED=true` - Show browser UI
-- `PLAYWRIGHT_HTML_REPORT=true` - Generate HTML report
-- `PLAYWRIGHT_SLOWMO=100` - Slow motion delay (ms)
-
-## Test Structure
-
-- `test/unit/` - Unit tests (Vitest)
-- `test/e2e/` - Package-level acceptance tests (Playwright,
-  `test:acceptance` target); Ghost's end-to-end suite lives in the repository's
-  top-level `e2e/` directory
-- `test/utils/` - Shared test utilities
-
-## Development Workflow
-
-1. Run unit tests during development: `pnpm test:unit:watch`
-2. Run acceptance tests before committing: `pnpm test:acceptance`
-3. Use headed mode for debugging: `pnpm test:acceptance:headed`
+- Use `pnpm test:acceptance:headed`, `pnpm test:acceptance --ui`, or
+  `pnpm test:slowmo` only when interactive debugging is useful; do not leave a
+  browser or report server running after validation.
+- Update the README when the package's shared commands or testing workflow
+  changes; do not duplicate that guidance here.
diff --git a/koenig/koenig-lexical/README.md b/koenig/koenig-lexical/README.md
index 2a42709e7e8..22bc5339d32 100644
--- a/koenig/koenig-lexical/README.md
+++ b/koenig/koenig-lexical/README.md
@@ -76,6 +76,9 @@ We use [Vitest](https://vitest.dev) for unit tests and
 end-to-end test suite lives in the repository's top-level
 [`e2e/`](../../e2e/) directory.
 
+Package tests live in `test/unit/` and `test/e2e/`, with shared test helpers in
+`test/utils/`.
+
 - `pnpm test` runs all tests and exits
 - `pnpm test:unit` runs unit tests
 - `pnpm test:unit:watch` runs unit tests and starts a test watcher that re-runs tests on file changes
@@ -89,6 +92,12 @@ end-to-end test suite lives in the repository's top-level
 - `pnpm test:slowmo` runs headed acceptance tests with a 100ms delay between
   instructions (some tests may fail or time out due to the added delays)
 
+The acceptance-test commands use these environment variables:
+
+- `PLAYWRIGHT_HEADED=true` shows the browser UI.
+- `PLAYWRIGHT_HTML_REPORT=true` generates an HTML report.
+- `PLAYWRIGHT_SLOWMO=100` adds a delay in milliseconds between browser actions.
+
 Before tests are started we build a version of the demo app that is used for the unit tests.
 
 When developing it can be useful to limit unit tests to specific keywords (taken from `describe` or `it/test` names). That's possible using the `-t` param and works with any of the above test commands, e.g.:
diff --git a/scripts/test/ci-path-filters.test.js b/scripts/test/ci-path-filters.test.js
new file mode 100644
index 00000000000..9e9f846b0e3
--- /dev/null
+++ b/scripts/test/ci-path-filters.test.js
@@ -0,0 +1,28 @@
+import {describe, it} from 'node:test';
+import assert from 'node:assert';
+import {readFile} from 'node:fs/promises';
+import yaml from 'js-yaml';
+
+async function getFilterPatterns(filterName) {
+    const workflow = yaml.load(await readFile(new URL('../../.github/workflows/ci.yml', import.meta.url), 'utf8'));
+    const filterStep = workflow.jobs.job_setup.steps.find(step => step.id === 'changed');
+    const filters = yaml.load(filterStep.with.filters);
+
+    return filters[filterName].flat(Infinity);
+}
+
+describe('CI path filters', () => {
+    it('excludes Markdown after all positive core patterns', async () => {
+        const patterns = await getFilterPatterns('core');
+        const markdownExclusion = patterns.indexOf('!**/*.md');
+        const positivePatterns = patterns
+            .map((pattern, index) => ({pattern, index}))
+            .filter(({pattern}) => !pattern.startsWith('!'));
+
+        assert.notStrictEqual(markdownExclusion, -1);
+        assert.ok(
+            positivePatterns.every(({index}) => index < markdownExclusion),
+            'Markdown exclusions must follow positive patterns so later patterns cannot add docs back'
+        );
+    });
+});