# AGENTS.md

This file provides guidance to AI Agents when working with code in this repository.

## 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.

## Monorepo Structure

Ghost is a pnpm + Nx monorepo with four workspace groups:

### ghost/* - Core Ghost packages
- **ghost/core** - Main Ghost application (Node.js/Express backend)
  - Core server: `ghost/core/core/server/`
  - Frontend rendering: `ghost/core/core/frontend/`

### apps/* - React-based UI applications
Two categories of apps:

**Admin Apps** (embedded in Ghost Admin):
- `ember-admin` - Ember.js admin client (legacy, being migrated to React)
- `admin` - The consolidated React admin shell, organized by domain (`src/{analytics,members,posts,tags,comments,automations,settings,...}`)
- `activitypub` - ActivityPub integration (route-composed into `admin`)
- Built with Vite + React + `@tanstack/react-query`

**Public Apps** (served to site visitors):
- `portal`, `comments-ui`, `signup-form`, `sodo-search`, `announcement-bar`
- Built as UMD bundles, loaded via CDN in site themes

**Foundation Libraries**:
- `admin-x-framework` - Shared API hooks, routing, utilities
- `admin-x-design-system` - Legacy design system (being phased out)
- `shade` - New design system (shadcn/ui + Radix UI + react-hook-form + zod)

### koenig/* - Ghost editor (Koenig) packages
Merged from the former TryGhost/Koenig repo with full git history:

- **koenig-lexical** - The Lexical-based rich text editor UI. Bundled into
  Ghost Admin at build time (`apps/ember-admin` copies its UMD build into admin
  assets; `apps/admin` imports it directly)
- **kg-*** - Editor support packages: server-side renderers and converters
  consumed by `ghost/core` (kg-default-nodes, kg-lexical-html-renderer,
  kg-html-to-lexical, ...) plus frontend helpers (kg-unsplash-selector)

All Koenig packages resolve via `workspace:` — nothing in dev, CI, or the
release archive installs them from npm. They are published to npm for
external consumers only, automatically as part of the Ghost release lane
(see `publish_koenig_packages` in ci.yml).

**Zero-build dev via the `source` export condition.** The `kg-*` libraries
consumed by `ghost/core` declare a `source` condition in their `package.json`
`exports` that points at the raw `src/*.ts`, listed *before*
`types`/`import`/`require`:

```jsonc
".": {
  "source": "./src/index.ts",     // dev/test: read raw TS
  "types": "./build/esm/index.d.ts",
  "import": "./build/esm/index.js",
  "require": "./build/cjs/index.js" // prod/published: compiled JS
}
```

`ghost/core`'s dev runner (`nodemon.json`: `node --conditions=source --import=tsx`)
and its Vitest configs (`resolve.conditions: ['source', 'node']` +
`--import tsx --conditions=source`) activate this condition, so a source change
in a `kg-*` package is picked up with **no `tsc` rebuild**. Production and the
published npm tarball run plain `node`, which ignores `source` and uses
`build/` — and `src/` is excluded from each package's `files` array, so it is
never shipped. The separate ESM and CommonJS outputs are part of Koenig's public
package contract; new internal packages use the ESM-only shape documented below.

### packages/* - Shared workspace libraries
Backend and shared libraries. Internal packages are consumed via `workspace:*`;
selected adapter bases also have supported public releases:

Read [`packages/README.md`](packages/README.md) before creating or modernizing an
internal package. It is the canonical lifetime contract; `packages/_template`
is its scaffold.

- **i18n** - Centralized internationalization for all apps
- **parse-email-address** - Email address parsing
- **adapters/** - Adapter base classes (`adapter-base-*`: scheduling, storage,
  SSO, redirects, route settings)
- **custom-field-types**, **testing** - Shared field-type definitions and test
  helpers
- **_template** - Scaffold for new packages; excluded from the workspace

### e2e/ - End-to-end tests
- Playwright-based E2E tests with Docker container isolation
- See `e2e/CLAUDE.md` for detailed testing guidance

## Common Commands

### Development
```bash
corepack enable pnpm           # Enable corepack to use the correct pnpm version
pnpm run setup                 # First-time setup (installs deps + submodules + builds workspace packages)
pnpm dev                       # Start development (Docker backend + host frontend dev servers)
```

> **Fresh worktree / first run — run `pnpm setup` before anything else.** It installs deps and syncs submodules. `pnpm fix` does a clean reinstall if anything misbehaves after a branch switch.

### Building
```bash
pnpm build                     # Build all packages (Nx handles dependencies)
pnpm build:clean               # Clean build artifacts and rebuild
```

### Testing
```bash
# Unit tests (from root)
pnpm test:unit                 # Run all unit tests in all packages
pnpm test:watch                # Watch mode — unified Vitest watcher (ghost/core + all apps)

# Ghost core tests (from ghost/core/)
cd ghost/core
pnpm test:unit                 # Unit tests only (Vitest, run once)
pnpm test:watch                # Watch mode — ghost/core unit tests only
pnpm test:integration          # Integration tests
pnpm test:e2e                  # Server-side e2e suites (webhooks/server/frontend/api) — not browser
pnpm test:all                  # All test types

# These run on sqlite with no extra services. The Redis/MinIO/S3 adapter suites
# probe for their service and auto-skip when it's down (run `pnpm dev:storage`
# etc. to exercise them); they always run in CI, which starts the services.

# E2E browser tests (from root)
pnpm test:e2e                  # Run e2e/ Playwright tests

# Running a single test
cd ghost/core
pnpm test:single test/unit/path/to/test.test.js   # routes test/unit/* → unit config, test/* → DB config

# Watch a single DB-backed file (integration/e2e) — the default test:watch only
# covers unit tests, so point it at the DB config explicitly:
pnpm exec vitest -c vitest.config.db.ts test/integration/path/to/test.test.js

# Ember Admin tests (from the repository root)
pnpm nx run ghost-admin:test

# Run one Ember Admin test file. Paths are relative to apps/ember-admin.
# The explicit `1` supplies the numeric value required by the test script's
# trailing `--parallel` option before additional Ember Exam arguments.
pnpm nx run ghost-admin:test -- 1 --file-path=tests/acceptance/editor/publish-flow-test.js
```

> **Always run Ember Admin tests through Nx.** Running `ember test` or
> `ember exam` directly from `apps/ember-admin` skips the dependency build
> graph and commonly fails in fresh worktrees with missing outputs such as
> `koenig-lexical.umd.js`, `@tryghost/admin-x-framework/hooks`, or
> `@tryghost/kg-converters`. For focused runs, use Ember Exam's `--file-path`
> as shown above rather than appending `--filter` to the package script.

### Linting
```bash
pnpm lint                      # Lint all packages
cd ghost/core && pnpm lint     # Lint Ghost core (server, shared, frontend, tests)
cd apps/ember-admin && pnpm lint    # Lint Ember admin
```

### Database
```bash
pnpm knex-migrator migrate     # Run database migrations
pnpm reset:data                # Reset database with test data (1000 members, 100 posts) (requires pnpm dev running)
pnpm reset:data:empty          # Reset database with no data (requires pnpm dev running)
```

### Docker
```bash
pnpm docker:build              # Build Docker images
pnpm docker:clean              # Stop containers, remove volumes and local images
pnpm docker:down               # Stop containers
```

### How `pnpm dev` works

The `pnpm dev` command uses a **hybrid Docker + host development** setup:

**What runs in Docker:**
- Ghost Core backend (with hot-reload via mounted source)
- MySQL, Redis, Mailpit
- Caddy gateway/reverse proxy

**What runs on host by default:**
- Admin, legacy Ember admin, Portal, and foundation library dev watchers
- Optional public UMD app watchers can be added when needed

**Setup:**
```bash
# Start Ghost backend, Admin, Portal, and Docker services
pnpm dev

# Add optional public apps (comments-ui, sodo-search, signup-form, admin-toolbar)
pnpm dev:public

# Develop the Koenig editor against Ghost Admin (adds a koenig-lexical rebuild
# watcher + preview server; Admin loads the editor from your local build)
pnpm dev:lexical

# With optional services (uses Docker Compose file composition)
pnpm dev:analytics             # Include Tinybird analytics
pnpm dev:storage               # Include MinIO S3-compatible object storage
pnpm dev:stripe                # Include Stripe webhook forwarding
pnpm dev:full                  # Include analytics, storage, Stripe, and public app watchers

# Everything available
pnpm dev:all                   #
```

**Accessing Services:**
- Ghost: `http://localhost:2368` (database: `ghost_dev`)
- Mailpit UI: `http://localhost:8025` (email testing)
- MySQL: `localhost:3306`
- Redis: `localhost:6379`
- Tinybird: `http://localhost:7181` (when analytics enabled)
- MinIO Console: `http://localhost:9001` (when storage enabled)
- MinIO S3 API: `http://localhost:9000` (when storage enabled)

## 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.js` 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`.

### 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`

### 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/`

### 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/`

## Troubleshooting

### Build Issues
```bash
pnpm fix                       # Clean cache + node_modules + reinstall
pnpm build:clean               # Clean build artifacts
pnpm nx reset                  # Reset Nx cache
```

### Test Issues
- **E2E failures:** Check `e2e/CLAUDE.md` for debugging tips
- **Docker issues:** `pnpm docker:clean && pnpm docker:build`