code · pull · Aug 15, 2026 · Aug 15, 2026
diff --git a/apps/admin-toolbar/README.md b/apps/admin-toolbar/README.md
@@ -1,9 +1,7 @@
 # Admin Toolbar
 
-Frontend staff toolbar for Ghost sites. Uses Preact (~3KB) instead of React
-(~40KB) since this is a lightweight public-facing widget that only needs basic
-rendering and hooks — the same rationale applies to any future small public
-scripts where bundle size matters more than ecosystem compatibility.
+Frontend staff toolbar for Ghost sites. It uses Preact to keep the public-facing
+bundle small while providing the rendering and hooks the toolbar needs.
 
 ## Development
 
@@ -26,6 +24,21 @@ that URL to `/ghost/assets/admin-toolbar/admin-toolbar.min.js`, which the dev
 gateway serves straight off disk from this package's `umd/` directory — so the
 watcher's output is picked up on the next request.
 
+## Release
+
+Patch releases are automatic. When Admin Toolbar changes on `main`, CI publishes
+the next patch version to npm and clears the jsDelivr cache. Sites using that
+major/minor line receive the patch without a Ghost release.
+
+For an intentional minor or major release:
+
+1. From a clean branch, run `pnpm ship` and select a minor or major version
+2. Merge the release commit to `main`
+3. Wait for a public Ghost release to ship the new default version line
+
+`pnpm ship` updates both the package version and Ghost's default Admin Toolbar
+version.
+
 # Copyright & License
 
 Copyright (c) 2013-2026 Ghost Foundation - Released under the [MIT license](https://github.com/TryGhost/Ghost/blob/main/LICENSE).
diff --git a/apps/admin-toolbar/package.json b/apps/admin-toolbar/package.json
@@ -2,6 +2,7 @@
   "name": "@tryghost/admin-toolbar",
   "type": "module",
   "version": "0.1.11",
+  "description": "Frontend staff toolbar for Ghost sites",
   "license": "MIT",
   "repository": "https://github.com/TryGhost/Ghost",
   "author": "Ghost Foundation",

diff --git a/apps/announcement-bar/README.md b/apps/announcement-bar/README.md
@@ -1,5 +1,7 @@
 # Announcement Bar
 
+Announcement banner injected into Ghost sites.
+
 ## Development
 
 ### Pre-requisites
@@ -14,25 +16,28 @@ Start Ghost with the public-app watchers enabled:
 pnpm dev:public
 ```
 
-This starts the standard development environment and the Announcement Bar watcher. To run only the package's build watcher, use `pnpm dev` from this directory.
-
-## Release
+This starts the standard development environment and the Announcement Bar
+watcher. To work on this package by itself, run these commands from this
+directory:
 
-A patch release can be rolled out instantly in production, whereas a minor/major release requires the Ghost monorepo to be updated and released.
-In either case, you need sufficient permissions to release `@tryghost` packages on NPM.
+```bash
+pnpm build    # one-off build
+pnpm dev      # watch and rebuild the UMD bundle
+pnpm test     # run unit tests once
+pnpm lint     # lint source and tests
+```
 
-### Patch release
+## Release
 
-1. Run `pnpm ship` and select a patch version when prompted
-2. Merge the release commit to `main`
+Patch releases are automatic. When Announcement Bar changes on `main`, CI publishes the next patch version to npm and clears the jsDelivr cache. Sites using that major/minor line receive the patch without a Ghost release.
 
-### Minor / major release
+For an intentional minor or major release:
 
-1. Run `pnpm ship` and select a minor or major version when prompted
+1. From a clean branch, run `pnpm ship` and select a minor or major version
 2. Merge the release commit to `main`
-3. Wait until a new version of Ghost is released
+3. Wait for a public Ghost release to ship the new default version line
 
-To use the new version of Announcement Bar in Ghost, update the version in Ghost core's default configuration (currently at `core/shared/config/default.json`)
+`pnpm ship` updates both the package version and Ghost's default Announcement Bar version.
 
 # Copyright & License 
 

diff --git a/apps/announcement-bar/package.json b/apps/announcement-bar/package.json
@@ -2,6 +2,7 @@
     "name": "@tryghost/announcement-bar",
     "type": "module",
     "version": "1.1.28",
+    "description": "Announcement banner for Ghost sites",
     "license": "MIT",
     "repository": "https://github.com/TryGhost/Ghost",
     "author": "Ghost Foundation",

diff --git a/apps/comments-ui/README.md b/apps/comments-ui/README.md
@@ -16,26 +16,28 @@ Start Ghost with the public-app watchers enabled:
 pnpm dev:public
 ```
 
-This starts the standard development environment and the Comments UI watcher. To run only the package's build watcher, use `pnpm dev` from this directory.
+This starts the standard development environment and the Comments UI watcher.
+To work on this package by itself, run these commands from this directory:
 
-## Release
-
-A patch release can be rolled out instantly in production, whereas a minor/major release requires the Ghost monorepo to be updated and released. In either case, you need sufficient permissions to release `@tryghost` packages on NPM.
+```bash
+pnpm build              # one-off build
+pnpm dev                # watch and rebuild the UMD bundle
+pnpm test               # run type checks and unit tests
+pnpm test:acceptance    # run browser acceptance tests
+pnpm lint               # lint code and check types
+```
 
-### Patch release
+## Release
 
-1. Run `pnpm ship` and select a patch version when prompted
-2. Merge the release commit to `main`
+Patch releases are automatic. When Comments changes on `main`, CI publishes the next patch version to npm and clears the jsDelivr cache. Sites using that major/minor line receive the patch without a Ghost release.
 
-### Minor / major release
+For an intentional minor or major release:
 
-1. Run `pnpm ship` and select a minor or major version when prompted
+1. From a clean branch, run `pnpm ship` and select a minor or major version
 2. Merge the release commit to `main`
-3. Wait until a new version of Ghost is released
+3. Wait for a public Ghost release to ship the new default version line
 
-### JsDelivr cache
-If the CI doesn't clear JsDelivr cache to get the new version out instantly, you may want to do it yourself manually ([docs](https://www.notion.so/ghost/How-to-clear-jsDelivr-CDN-cache-2930bdbac02946eca07ac23ab3199bfa?pvs=4)). Typically, you'll need to open `https://purge.jsdelivr.net/ghost/comments-ui@~${COMMENTS_UI_VERSION}/umd/comments-ui.min.js` and
-`https://purge.jsdelivr.net/ghost/comments-ui@~${COMMENTS_UI_VERSION}/umd/main.css` in your browser, where `COMMENTS_UI_VERSION` is the latest minor version in `ghost/core/core/shared/config/defaults.json` ([code](https://github.com/TryGhost/Ghost/blob/0aef3d3beeebcd79a4bfd3ad27e0ac67554b5744/ghost/core/core/shared/config/defaults.json#L198))
+`pnpm ship` updates both the package version and Ghost's default Comments version.
 
 # Copyright & License
 

diff --git a/apps/comments-ui/package.json b/apps/comments-ui/package.json
@@ -2,6 +2,7 @@
     "name": "@tryghost/comments-ui",
     "type": "module",
     "version": "1.6.0",
+    "description": "Comments interface for Ghost posts",
     "license": "MIT",
     "repository": "https://github.com/TryGhost/Ghost",
     "author": "Ghost Foundation",

diff --git a/apps/portal/README.md b/apps/portal/README.md
@@ -6,9 +6,11 @@
 
 ## Usage
 
-Ghost automatically injects Portal script on all sites running Ghost 4 or higher.
+Ghost automatically injects the Portal script on all sites running Ghost 4 or
+higher.
 
-Alternatively, Portal can be enabled on non-ghost pages directly by inserting the below script on the page.
+Alternatively, Portal can be enabled on pages outside Ghost by adding this
+script:
 
 ```html
 <script defer src="https://unpkg.com/@tryghost/portal@latest/umd/portal.min.js" data-ghost="https://mymemberssite.com"></script>
@@ -20,7 +22,10 @@ The `data-ghost` attribute expects the URL for your Ghost site, which is the onl
 
 By default, the script adds a default floating trigger button on the bottom right of your page which is used to trigger the popup on screen.
 
-Its possible to add custom trigger button of your own by adding data attribute `data-portal` to any HTML tag on page, and also specify a specific [page](https://github.com/TryGhost/Ghost/blob/main/ghost/portal/src/pages.js#L13-L22) to open from it by using it as `data-portal=signup`.
+You can add a custom trigger by adding the `data-portal` attribute to any HTML
+element. Set its value to choose a specific
+[Portal page](https://github.com/TryGhost/Ghost/blob/main/apps/portal/src/pages.js),
+for example `data-portal="signup"`.
 
 Share modal can be opened with `data-portal="share"` (or `#/share`).
 
@@ -38,62 +43,65 @@ Troubleshooting missing preview metadata:
 1. Verify the template includes `{{ghost_head}}`.
 2. Verify rendered HTML contains canonical + OG/Twitter tags.
 
-The script also adds custom class names to this element for open and close state of popup - `gh-portal-open` and `gh-portal-close`, allowing devs to update its UI based on popup state.
+The script adds `gh-portal-open` and `gh-portal-close` classes to custom triggers
+to reflect the popup state.
 
-Refer the [docs](https://ghost.org/help/setup-members/#customize-portal-settings) to read about ways in which Portal can be customized for your site.
+See the [Portal settings documentation](https://ghost.org/help/setup-members/#customize-portal-settings)
+for ways to customize Portal for your site.
 
 ## Develop
 
-Portal runs automatically when using Ghost's development command from the monorepo root:
-```
+Portal runs automatically with Ghost's standard development command from the
+monorepo root:
+
+```bash
 pnpm dev
 ```
 
-This starts all frontend apps (including Portal.) Portal is served via the dev gateway at `http://localhost:2368/ghost/assets/portal/portal.min.js` and is loaded into theme pages on the dev site.
+This starts Ghost, Admin, and Portal. Portal is served through the development
+gateway at `http://localhost:2368/ghost/assets/portal/portal.min.js` and loaded
+into theme pages on the development site. Use `pnpm dev:public` when changing
+Portal alongside the other public apps.
 
 ## Build
 
-To create a production minified bundle in `umd/portal.min.js`:
-```
+From this directory, create a production minified bundle in
+`umd/portal.min.js` with:
+
+```bash
 pnpm build
 ```
 
 ## Test
 
-To run tests in watch mode:
-```
+From this directory, run unit tests once or in watch mode with:
+
+```bash
 pnpm test
+pnpm test:watch
 ```
 
 ### Ghost e2e tests
 
-Portal is primarily tested via Ghost's e2e Playwright tests in the `e2e/` directory. Run them from the monorepo root:
-```
+Portal is primarily tested through Ghost's Playwright tests in the `e2e/`
+directory. Run them from the monorepo root:
+```bash
 pnpm test:e2e
 ```
 
 ## Release
 
-A patch release can be rolled out instantly in production, whereas a minor/major release requires the Ghost monorepo to be updated and released. In either case, you need sufficient permissions to release `@tryghost` packages on NPM.
+Patch releases are automatic. When Portal changes on `main`, CI publishes the next patch version to npm and clears the jsDelivr cache. Sites using that major/minor line receive the patch without a Ghost release.
 
 If you're releasing new code that should not immediately go live _always_ use a minor or major version when publishing.
 
-In order to have Ghost's e2e tests run against the new code on CI or to test the new code in staging, you need to publish to npm following the Minor / major release process below.
-
-### Patch release
-
-1. Run `pnpm ship` and select a patch version when prompted
-2. Merge the release commit to `main`
-
-### Minor / major release
+For an intentional minor or major release:
 
-1. Run `pnpm ship` and select a minor or major version when prompted
+1. From a clean branch, run `pnpm ship` and select a minor or major version
 2. Merge the release commit to `main`
-3. Wait until a new version of Ghost is released
+3. Wait for a public Ghost release to ship the new default version line
 
-### JsDelivr cache
-If the CI doesn't clear JsDelivr cache to get the new version out instantly, you may want to do it yourself manually ([docs](https://www.notion.so/ghost/How-to-clear-jsDelivr-CDN-cache-2930bdbac02946eca07ac23ab3199bfa?pvs=4)). Typically, you'll need to open `https://purge.jsdelivr.net/ghost/portal@~${PORTAL_VERSION}/umd/portal.min.js` and
-`https://purge.jsdelivr.net/ghost/portal@~${PORTAL_VERSION}/umd/main.css` in your browser, where `PORTAL_VERSION` is the latest minor version in `ghost/core/core/shared/config/defaults.json` ([code](https://github.com/TryGhost/Ghost/blob/0aef3d3beeebcd79a4bfd3ad27e0ac67554b5744/ghost/core/core/shared/config/defaults.json#L185))
+`pnpm ship` updates both the package version and Ghost's default Portal version.
 
 # Copyright & License
 

diff --git a/apps/portal/package.json b/apps/portal/package.json
@@ -2,6 +2,7 @@
     "name": "@tryghost/portal",
     "type": "module",
     "version": "2.69.16",
+    "description": "Drop-in membership interface for Ghost sites",
     "license": "MIT",
     "repository": "https://github.com/TryGhost/Ghost",
     "author": "Ghost Foundation",

diff --git a/apps/signup-form/README.md b/apps/signup-form/README.md
@@ -20,41 +20,43 @@ This starts the standard development environment and the Signup Form watcher.
 
 ### Running the standalone demo page
 
-Run `pnpm dev:standalone` (in this package folder) to start the standalone development server with HMR for testing/developing the form in isolation.
-- This serves the demo page at http://localhost:6173
+Run `pnpm dev:standalone` from this directory to start the standalone
+development server with HMR. It serves the demo page at
+<http://localhost:6173>.
 
 `pnpm dev` on its own (in this package folder) only builds `umd/signup-form.min.js` and watches for changes — it does not bind a port. The UMD is served by Caddy at http://localhost:2368/ghost/assets/signup-form/signup-form.min.js when you run `pnpm dev:public` from the monorepo root.
 
 ### Using the UMD build during development
 
-Vite by default only supports HRM with an ESM output. But when loading a script on a site as a ESM module (`<script type="module" src="...">`), you don't have access to `document.currentScript` inside the script, which is required to determine the location to inject the iframe. In development mode we use a workaround for this to make the ESM HMR work. But this workaround is not suitable for production.
+Vite's development server uses an ESM output for HMR. When a script is loaded as
+an ESM module (`<script type="module" src="...">`), `document.currentScript` is
+not available. Signup Form needs it to determine where to inject the iframe, so
+development mode uses a workaround that is not suitable for production.
 
-To test the real production behaviour without this hack, you can use http://localhost:6173/preview.html (served by `pnpm dev:standalone`). The page loads the production UMD via `<script src="http://localhost:2368/ghost/assets/signup-form/signup-form.min.js">`, which is served by Caddy when `pnpm dev:public` is also running from the monorepo root. Both processes need to be up at the same time.
+To test the production behavior, open <http://localhost:6173/preview.html> while
+`pnpm dev:standalone` is running. The page loads the UMD bundle from the
+development gateway, so `pnpm dev:public` must also be running from the monorepo
+root.
 
 ## Test
 
-- `pnpm lint` run just eslint
-- `pnpm test:acceptance` run acceptance tests on Chromium
-- `pnpm test:acceptance:slowmo` run acceptance tests visually (headed) and slower on Chromium
-- `pnpm test:acceptance:full` run acceptance tests on all configured browsers
+- `pnpm lint` runs ESLint.
+- `pnpm test:acceptance` runs acceptance tests on Chromium.
+- `pnpm test:acceptance:slowmo` runs acceptance tests headed and slowed down on
+  Chromium.
+- `pnpm test:acceptance:full` runs acceptance tests on all configured browsers.
 
 ## Release
 
-A patch release can be rolled out instantly in production, whereas a minor/major release requires the Ghost monorepo to be updated and released.
-In either case, you need sufficient permissions to release `@tryghost` packages on NPM.
+Patch releases are automatic. When Signup Form changes on `main`, CI publishes the next patch version to npm and clears the jsDelivr cache. Sites using that major/minor line receive the patch without a Ghost release.
 
-### Patch release
+For an intentional minor or major release:
 
-1. Run `pnpm ship` and select a patch version when prompted
+1. From a clean branch, run `pnpm ship` and select a minor or major version
 2. Merge the release commit to `main`
+3. Wait for a public Ghost release to ship the new default version line
 
-### Minor / major release
-
-1. Run `pnpm ship` and select a minor or major version when prompted
-2. Merge the release commit to `main`
-3. Wait until a new version of Ghost is released
-
-To use the new version of signup form in Ghost, update the version in Ghost core's default configuration (currently at `core/shared/config/default.json`)
+`pnpm ship` updates both the package version and Ghost's default Signup Form version.
 
 # Copyright & License
 

diff --git a/apps/signup-form/package.json b/apps/signup-form/package.json
@@ -2,6 +2,7 @@
     "name": "@tryghost/signup-form",
     "type": "module",
     "version": "0.3.34",
+    "description": "Embeddable signup form for Ghost sites",
     "license": "MIT",
     "repository": "https://github.com/TryGhost/Ghost",
     "author": "Ghost Foundation",

diff --git a/apps/sodo-search/README.md b/apps/sodo-search/README.md
@@ -1,5 +1,7 @@
 # Sodo Search
 
+Search interface injected into Ghost sites.
+
 ## Development
 
 ### Pre-requisites
@@ -14,25 +16,27 @@ Start Ghost with the public-app watchers enabled:
 pnpm dev:public
 ```
 
-This starts the standard development environment and the Sodo Search watcher. To run only the package's build watcher, use `pnpm dev` from this directory.
-
-## Release
+This starts the standard development environment and the Sodo Search watcher.
+To work on this package by itself, run these commands from this directory:
 
-A patch release can be rolled out instantly in production, whereas a minor/major release requires the Ghost monorepo to be updated and released. 
-In either case, you need sufficient permissions to release `@tryghost` packages on NPM.
+```bash
+pnpm build    # one-off build
+pnpm dev      # watch and rebuild the UMD JavaScript and CSS
+pnpm test     # run unit tests once
+pnpm lint     # lint source and tests
+```
 
-### Patch release
+## Release
 
-1. Run `pnpm ship` and select a patch version when prompted
-2. Merge the release commit to `main`
+Patch releases are automatic. When Sodo Search changes on `main`, CI publishes the next patch version to npm and clears the jsDelivr cache. Sites using that major/minor line receive the patch without a Ghost release.
 
-### Minor / major release
+For an intentional minor or major release:
 
-1. Run `pnpm ship` and select a minor or major version when prompted
+1. From a clean branch, run `pnpm ship` and select a minor or major version
 2. Merge the release commit to `main`
-3. Wait until a new version of Ghost is released
+3. Wait for a public Ghost release to ship the new default version line
 
-To use the new version of Sodo-Search in Ghost, update the version in Ghost core's default configuration (currently at `core/shared/config/default.json`)
+`pnpm ship` updates both the package version and Ghost's default Sodo Search version.
 
 # Copyright & License