code · pull · Aug 16, 2026 · Aug 16, 2026 · Aug 16, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -11,6 +11,7 @@ Start with:
 
 - [Development setup](docs/contributing/development-setup.md)
 - [Contribution workflow](docs/contributing/workflow.md)
+- [Writing codebase documentation](docs/contributing/documentation.md)
 - [Testing](docs/contributing/testing.md)
 - [Shipping](docs/contributing/shipping.md)
 - [Monorepo structure](docs/codebase/monorepo-structure.md)

diff --git a/docs/README.md b/docs/README.md
@@ -90,11 +90,17 @@ Practice and contributor guides explain how to make and verify changes:
 - [API design](practices/api-design.md)
 - [Database migrations](practices/database-migrations.md)
 - [Browser E2E testing](contributing/e2e-testing.md)
+- [Codebase documentation](contributing/documentation.md)
 - [Email testing](contributing/testing-email.md)
 - [Error handling](practices/error-handling.md)
 - [Internationalization](practices/internationalization.md)
 - [Performance testing](contributing/performance-testing.md)
 
+Reference guides provide tables and other information to look up while working
+on Ghost:
+
+- [Node.js compatibility](reference/node-compatibility.md)
+
 ### Finding Issues to Work On
 
 - [Good First Issues](https://github.com/TryGhost/Ghost/labels/good%20first%20issue) - Great for newcomers

diff --git a/docs/contributing/development-setup.md b/docs/contributing/development-setup.md
@@ -15,6 +15,9 @@ Install:
 - [Corepack](https://nodejs.org/api/corepack.html), included with supported
   Node.js distributions
 
+For Node.js support in older Ghost releases, see the
+[Node.js compatibility reference](../reference/node-compatibility.md).
+
 The default environment binds ports `80`, `2368`, `3306`, `6379`, `8025`, and
 `8026`. Stop local services using those ports before starting Ghost.
 

diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md
@@ -0,0 +1,98 @@
+# Writing Codebase Documentation
+
+Ghost's codebase documentation explains how to understand, change, test, and
+ship this repository. It is public and reviewed alongside the code it
+describes.
+
+## Choose the Right Home
+
+Give each topic one canonical home. Link to that source instead of copying it
+into another documentation surface.
+
+| Content | Home |
+| --- | --- |
+| Codebase-wide setup, workflow, architecture, and practices | `/docs` |
+| Package, service, app, or test-suite details | A README beside the code |
+| Canonical domain language | A `CONTEXT.md` beside the domain |
+| Relationships between bounded contexts | The root `CONTEXT-MAP.md` |
+| Contribution policy and the contributor entry point | `.github/CONTRIBUTING.md` |
+| Agent-only execution rules and constraints | The nearest `AGENTS.md` or repository skill |
+| Product, API, theme, and self-hosting documentation | [ghost.org/docs](https://ghost.org/docs/) |
+| Proposals, company process, private operations, and temporary work | The internal Ghost workspace |
+
+- Keep the root README focused on introducing Ghost and directing contributors
+  to the codebase documentation.
+- Use `/docs` for guidance that crosses workspace or domain boundaries.
+- Keep package or service details beside the code and link to them from an
+  overview where useful.
+
+## Context Files
+
+- A `CONTEXT.md` is a glossary for a bounded context: its important terms,
+  precise meanings, and terms to avoid.
+- Keep architecture and implementation details in the nearby README or an
+  appropriate codebase guide.
+- Add each bounded context and its relationships to the root `CONTEXT-MAP.md`.
+
+## Who Should Update the Docs?
+
+Whoever changes or introduces a documented concept is responsible for updating
+its documentation.
+
+- Update the docs in the same pull request as the code, workflow, command, or
+  behaviour they describe.
+- Check the nearest README, `/docs`, and agent guidance when a change crosses
+  those surfaces.
+- Update both the overview and focused guide when readers need both.
+- Ask an owner of the affected area to review specialist guidance, but do not
+  leave the documentation work for them to discover later.
+
+## Write for the Current Codebase
+
+- Check guidance against the current code, scripts, tests, and configuration.
+- Run or otherwise verify commands and paths where practical.
+- Leave one canonical answer and link to it instead of copying it.
+- Use direct language, short sections, and examples from real commands or code.
+- Keep critical information in an overview, then link with “For more detail” to
+  a focused guide.
+- Use relative repository links and link to stable files or symbols rather than
+  line numbers.
+- Copy public-safe images into the repository instead of using expiring Notion
+  URLs.
+
+## Keep Public and Private Guidance Separate
+
+- Keep repository documentation public and useful to contributors.
+- Never include credentials, secrets, customer or site data, private repository
+  details, internal hostnames, or incident and operational procedures.
+- Document public integration boundaries where contributors need them; keep
+  private deployment and operations in the internal workspace.
+- Review private source material before the first commit. Never commit it and
+  remove the sensitive parts later.
+
+## Keep Human and Agent Guidance in Sync
+
+- Treat human-readable documentation as the source of truth for facts and
+  conventions shared by people and agents.
+- Keep `AGENTS.md` focused on directions to canonical docs and agent-specific
+  execution constraints.
+- Link repository skills to the canonical guide instead of repeating it.
+- Update human documentation and any agent entry points that need to discover
+  it in the same pull request.
+
+## Check Your Change
+
+Run the repository hygiene check before submitting documentation changes:
+
+```bash
+pnpm check
+pnpm lint:docs
+git diff --check origin/main...HEAD
+```
+
+- Check links manually; `pnpm lint:docs` does not currently validate Markdown
+  links.
+- Confirm another document does not give a different answer.
+- Confirm no private or temporary material is being published.
+- After a migrated guide is live, replace links to its Notion source and retire
+  the old page.
diff --git a/docs/reference/node-compatibility.md b/docs/reference/node-compatibility.md
@@ -0,0 +1,81 @@
+# Ghost, Node.js, and Ghost-CLI compatibility
+
+Ghost, Node.js, and Ghost-CLI have independent release cycles. This reference
+records the points where their supported version ranges changed.
+
+Use the versions pinned in [`.nvmrc`](../../.nvmrc) and
+[`package.json`](../../ghost/core/package.json) when working on the current
+Ghost codebase. Use this history when maintaining or upgrading an older Ghost
+installation.
+
+There are two different compatibility relationships:
+
+- Ghost's `engines.node` and `engines.cli` fields define the Node.js versions
+  that can run that Ghost release and the minimum Ghost-CLI version it accepts.
+- Ghost-CLI's own `engines.node` field defines the Node.js versions that can run
+  that Ghost-CLI release.
+
+## Ghost compatibility
+
+Rows record compatibility changes and useful final-version milestones. A blank
+Node.js or Ghost-CLI cell means that value did not change in that release.
+
+| Release date | Ghost release | Node.js support | Minimum Ghost-CLI | Change |
+| --- | --- | --- | --- | --- |
+| 2017-12-05 | >= 1.18.3 | `^4.5.0 \|\| ^6.9.0 \|\| ^8.9.0` | | |
+| 2018-04-17 | >= 1.22.3 | | `^1.7.0` | Added Ghost-CLI compatibility requirement |
+| 2018-05-04 | >= 1.22.5 | `^6.9.0 \|\| ^8.9.0` | | Removed Node.js 4 |
+| 2018-07-24 | 1.25.0 | | | Last 1.x migrations |
+| 2019-12-18 | 1.26.2 | | | Last 1.x version |
+| 2018-08-16 | 2.0.0 | | `^1.9.0` | Initial 2.x support |
+| 2018-10-30 | >= 2.4.0 | `^6.9.0 \|\| ^8.9.0 \|\| ^10.12.0` | | Added Node.js 10 |
+| 2018-11-07 | >= 2.5.0 | `^6.9.0 \|\| ^8.9.0 \|\| ^10.13.0` | | Bumped Node.js 10 minimum |
+| 2019-06-04 | >= 2.23.2 | `^8.9.0 \|\| ^10.13.0` | | Removed Node.js 6 |
+| 2019-07-16 | >= 2.25.7 | `^8.10.0 \|\| ^10.13.0` | | Bumped Node.js 8 minimum |
+| 2019-10-14 | 2.37.0 | | | Last 2.x migrations |
+| 2021-01-29 | 2.38.3 | | | Last 2.x version |
+| 2019-10-22 | 3.0.0 | `^8.16.0 \|\| ^10.13.0 \|\| ^12.10.0` | `^1.12.0` | Initial 3.x support; added Node.js 12 |
+| 2020-03-02 | >= 3.9.0 | `^10.13.0 \|\| ^12.10.0` | | Removed Node.js 8 |
+| 2020-11-03 | >= 3.37.0 | `^10.13.0 \|\| ^12.10.0 \|\| ^14.15.0` | | Added Node.js 14 |
+| 2021-01-26 | 3.41.0 | | | Last 3.x migrations |
+| 2022-01-22 | 3.42.9 | | | Last 3.x version |
+| 2021-03-15 | 4.0.0 | | `^1.16.0` | Initial 4.x support |
+| 2021-05-11 | >= 4.5.0 | `^12.22.1 \|\| ^14.16.1` | `^1.17.0` | Removed Node.js 10 |
+| 2021-10-29 | >= 4.21.0 | `^12.22.1 \|\| ^14.17.0 \|\| ^16.13.0` | | Added Node.js 16 |
+| 2022-04-22 | >= 4.45.0 | `^14.17.0 \|\| ^16.13.0` | | Removed Node.js 12 |
+| 2022-05-23 | 5.0.0 | `^14.17.0 \|\| ^16.13.0` | `^1.17.0` | Initial 5.x support |
+| 2022-12-02 | >= 5.25.0 | `^14.17.0 \|\| ^16.13.0 \|\| ^18.0.0` | | Added Node.js 18 |
+| 2023-01-05 | >= 5.27.0 | `^14.18.0 \|\| ^16.13.0 \|\| ^18.12.1` | | Bumped Node.js 14 and 18 minimums |
+| 2023-05-05 | >= 5.47.0 | `^16.13.0 \|\| ^18.12.1` | | Removed Node.js 14 |
+| 2023-07-14 | >= 5.54.1 | `^16.14.0 \|\| ^18.12.1` | | Bumped Node.js 16 minimum |
+| 2023-10-04 | >= 5.67.0 | | `^1.25.0` | Bumped Ghost-CLI minimum |
+| 2023-10-27 | >= 5.71.0 | `^18.12.1` | | Removed Node.js 16 |
+| 2024-04-19 | >= 5.82.3 | `^18.12.1 \|\| ^20.11.1` | `^1.26.0` | Added Node.js 20 and bumped Ghost-CLI minimum |
+| 2025-02-21 | >= 5.110.0 | `^18.12.1 \|\| ^20.11.1 \|\| ^22.13.1` | `^1.27.0` | Added Node.js 22 and bumped Ghost-CLI minimum |
+| 2025-08-04 | 6.0.0 | `^22.13.1` | `^1.27.0` | Initial 6.x support; removed Node.js 18 and 20 |
+| 2026-04-13 | >= 6.29.0 | | `^1.29.1` | Bumped Ghost-CLI minimum |
+| 2026-06-19 | >= 6.46.0 | `^22.18.0` | | Bumped Node.js 22 minimum |
+| 2026-07-17 | >= 6.53.0 | `^22.23.1` | | Bumped Node.js 22 minimum |
+
+## Ghost-CLI Node.js compatibility
+
+This table describes the Node.js runtime required to execute Ghost-CLI. It is
+separate from the minimum Ghost-CLI version accepted by Ghost above.
+
+| Release date | Ghost-CLI release | Node.js support | Change |
+| --- | --- | --- | --- |
+| 2017-07-22 | 1.0.0 | `^4.5.0 \|\| ^6.5.0` | Initial 1.x support |
+| 2017-10-09 | 1.1.3 | `^4.5.0 \|\| ^6.9.0` | Bumped Node.js 6 minimum |
+| 2017-10-30 | 1.2.0 | `^4.5.0 \|\| ^6.9.0 \|\| ^8.8.0` | Added Node.js 8 |
+| 2017-11-10 | 1.2.1 | `^4.5.0 \|\| ^6.9.0 \|\| ^8.9.0` | Bumped Node.js 8 minimum |
+| 2018-05-01 | 1.7.2 | `^6.9.0 \|\| ^8.9.0` | Removed Node.js 4 |
+| 2018-10-30 | 1.9.7 | `^6.9.0 \|\| ^8.9.0 \|\| ^10.12.0` | Added Node.js 10 |
+| 2018-11-07 | 1.9.8 | `^6.9.0 \|\| ^8.9.0 \|\| ^10.13.0` | Bumped Node.js 10 minimum |
+| 2019-10-21 | 1.12.0 | `^8.16.0 \|\| ^10.13.0 \|\| ^12.10.0` | Added Node.js 12; removed Node.js 6; bumped Node.js 8 minimum |
+| 2021-03-01 | 1.16.0 | `^10.13.0 \|\| ^12.10.0 \|\| ^14.15.0` | Added Node.js 14; removed Node.js 8 |
+| 2021-10-28 | 1.18.0 | `^12.22.1 \|\| ^14.17.0 \|\| ^16.13.0` | Added Node.js 16; removed Node.js 10; bumped minimums |
+| 2022-12-02 | 1.24.0 | `^12.22.1 \|\| ^14.17.0 \|\| ^16.13.0 \|\| ^18.0.0` | Added Node.js 18 |
+| 2024-03-19 | 1.26.0 | `^12.22.1 \|\| ^14.17.0 \|\| ^16.13.0 \|\| ^18.0.0 \|\| ^20.11.1` | Added Node.js 20 |
+| 2025-02-13 | 1.27.0 | `^12.22.1 \|\| ^14.17.0 \|\| ^16.13.0 \|\| ^18.0.0 \|\| ^20.11.1 \|\| ^22.11.0` | Added Node.js 22 |
+| 2026-03-23 | 1.28.6 | `^20.11.1 \|\| ^22.11.0 \|\| ^24.0.0` | Added Node.js 24; removed Node.js 12, 14, 16, and 18 |
+| 2026-07-09 | 1.30.0 | `^22.13.0 \|\| ^24.0.0` | Removed Node.js 20; bumped Node.js 22 minimum |