Sync with upstream Ghost v6.58.0

.agents/bin/docker

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec sudo --preserve-env=PUBLIC_URL /usr/bin/docker "$@"

.agents/resume

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! systemctl is-active --quiet amp-svc-docker.service || ! systemctl is-active --quiet amp-svc-ghost.service; then
+    amp orb services ensure
+fi

.agents/setup

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+node_version="$(cat .node-version)"
+node_dir="$HOME/.local/node-v${node_version}-linux-x64"
+
+if [[ ! -x "$node_dir/bin/node" ]]; then
+    archive="/tmp/node-v${node_version}-linux-x64.tar.xz"
+    curl -fsSLo "$archive" "https://nodejs.org/dist/v${node_version}/node-v${node_version}-linux-x64.tar.xz"
+    mkdir -p "$HOME/.local"
+    tar -xJf "$archive" -C "$HOME/.local"
+    rm -f "$archive"
+fi
+
+export PATH="$node_dir/bin:$PATH"
+corepack enable --install-directory "$node_dir/bin"
+pnpm setup
+
+profile_marker="# Ghost orb Node.js"
+profile_export="export PATH=\"$node_dir/bin:\$PATH\""
+if grep -Fqx "$profile_marker" "$HOME/.bash_profile" 2>/dev/null; then
+    sed -i "/^${profile_marker}$/ { n; c\\
+$profile_export
+    }" "$HOME/.bash_profile"
+else
+    cat >> "$HOME/.bash_profile" <<EOF
+
+$profile_marker
+$profile_export
+EOF
+fi
+
+if ! /usr/bin/docker compose version >/dev/null 2>&1; then
+    sudo install -m 0755 -d /etc/apt/keyrings
+    sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
+    sudo chmod a+r /etc/apt/keyrings/docker.asc
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
+    sudo apt-get update
+    sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+fi

.agents/skills/commit/SKILL.md

@@ -14,48 +14,16 @@ Use this skill whenever the user asks you to create a git commit for the current
    - `git diff`
    - `git log -5 --oneline`
 2. Only stage files relevant to the requested change. Do not include unrelated untracked files, generated files, or likely-local artifacts.
-3. Always follow Ghost's commit conventions (see below) for commit messages
-4. Run `git status --short` after committing and confirm the result.
+3. Read and follow `.github/CONTRIBUTING.md#commit-messages`. It is the
+   source of truth for Ghost's commit conventions.
+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
 - Keep commits focused and avoid bundling unrelated changes
 - If there are no relevant changes, do not create an empty commit
 - If hooks fail, fix the issue and create a new commit. Never bypass hooks.
-
-## Commit message format
-
-We have a handful of simple standards for commit messages which help us to generate readable changelogs. Please follow this wherever possible and mention the associated issue number.
-
-- **1st line:** Max 80 character summary
-   - Written in past tense e.g. “Fixed the thing” not “Fixes the thing”
-   - Start with one of: Fixed, Changed, Updated, Improved, Added, Removed, Reverted, Moved, Released, Bumped, Cleaned
-- **2nd line:** [Always blank]
-- **3rd line:** `ref <issue link>`, `fixes <issue link>`, `closes <issue link>` or blank
-- **4th line:** Why this change was made - the code includes the what, the commit message should describe the context of why - why this, why now, why not something else?
-
-If your change is **user-facing** please prepend the first line of your commit with **an emoji**.
-
-Because emoji commits are the release notes, it's important that anything that gets an emoji is a user-facing change that's significant and relevant for end-users to see.
-
-The first line of an emoji commit message should be from the perspective of the user. For example, 🐛 Fixed a race condition in the members service is technical and tells the user nothing, but 🐛 Fixed a bug causing active members to lose access to paid content tells the user reading the release notes “oh yeah, they fixed that bug I kept hitting.”
-
-###  Main emojis we are using:
-
-- ✨ Feature
-- 🎨 Improvement / change
-- 🐛 Bug Fix
-- 🌐 i18n (translation) submissions
-- 💡 Anything else flagged to users or whoever is writing release notes
-
-### Example
-
-```
-✨ Added config flag for disabling page analytics
-
-ref https://linear.app/tryghost/issue/ENG-1234/
-
-- analytics are brand new under development, therefore they need to be behind a flag
-- not using the developerExperiments flag as that is already in wide use and we aren't ready to deploy this anywhere yet
-- using the term `pageAnalytics` as this was discussed as best reflecting what this does
-```

.agents/skills/convert-internal-package-to-typescript/SKILL.md

@@ -62,6 +62,9 @@ Use the subject `Changed <package> file extensions to TypeScript`.
 Apply the package contract from `packages/README.md`: shared config packages,
 minimal package-local config, ESM metadata and exports, standard scripts, and a
 single compiled output unless a verified consumer requires an exception.
+Replace the package's `migration` status with
+`ghostPackage.goldenPath: compliant` only after every mechanical golden-path
+check passes.
 
 Use the subject `Converted <package> to TypeScript`.
 

.agents/skills/create-database-migration/SKILL.md

@@ -5,20 +5,27 @@ description: Create a database migration to add a table, add columns to an exist
 
 # Create Database Migration
 
+Read the canonical human guidance in
+[`docs/practices/database-migrations.md`](../../../docs/practices/database-migrations.md)
+before making a migration. This skill is the executable checklist that
+accompanies it.
+
 ## Instructions
 
 1. Create a new, empty migration file: `cd ghost/core && pnpm migrate:create <kebab-case-slug>`. IMPORTANT: do not create the migration file manually; always use this script to create the initial empty migration file. The slug must be kebab-case (e.g. `add-column-to-posts`).
 2. The above command will create a new directory in `ghost/core/core/server/data/migrations/versions` if needed, create the empty migration file with the appropriate name, and bump the core and admin package versions to RC if this is the first migration after a release.
 3. Update the migration file with the changes you want to make in the database, following the existing patterns in the codebase. Where appropriate, prefer to use the utility functions in `ghost/core/core/server/data/migrations/utils/*`.
 4. Update the schema definition file in `ghost/core/core/server/data/schema/schema.js`, and make sure it aligns with the latest changes from the migration.
 5. Test the migration manually: `cd ghost/core && pnpm knex-migrator migrate --v {version directory} --force`
-6. If adding or dropping a table, update `ghost/core/core/server/data/exporter/table-lists.js` as appropriate.
-7. If adding or dropping a table, also add or remove the table name from the expected tables list in `ghost/core/test/integration/exporter/exporter.test.js`. This test has a hardcoded alphabetically-sorted array of all database tables — it runs in CI integration tests (not unit tests) and will fail if the new table is missing.
-8. Run the schema integrity test, and update the hash: `cd ghost/core && pnpm test:single test/unit/server/data/schema/integrity.test.js`
-9. Run unit tests in Ghost core, and iterate until they pass: `cd ghost/core && pnpm test:unit`
+6. Roll the migration back to test `down()`: `cd ghost/core && pnpm knex-migrator rollback --v {previous version} --force`, then migrate forward again.
+7. Run the migration integration test, which covers initialization, rollback, forward migration, and idempotency: `cd ghost/core && pnpm test:single test/integration/migrations/migration.test.js`. Migrations must pass the database-backed suites against both MySQL and SQLite.
+8. If adding or dropping a table, update `ghost/core/core/server/data/exporter/table-lists.js` as appropriate. The consistency assertion in `ghost/core/test/unit/server/data/exporter/index.test.js` checks that every schema table is classified in the exporter lists.
+9. Run the focused exporter unit test when the table lists change: `cd ghost/core && pnpm test:single test/unit/server/data/exporter/index.test.js`.
+10. Run the schema integrity test, and update the hash: `cd ghost/core && pnpm test:single test/unit/server/data/schema/integrity.test.js`
+11. Run unit tests in Ghost core, and iterate until they pass: `cd ghost/core && pnpm test:unit`
 
 ## Examples
 See [examples.md](examples.md) for example migrations.
 
 ## Rules
-See [rules.md](rules.md) for rules that should always be followed when creating database migrations.
+See [rules.md](rules.md) for rules that should always be followed when creating database migrations.

.agents/skills/migrate-internal-package/SKILL.md

@@ -19,6 +19,28 @@ Explain every cross-repository or administrative action before it happens.
   PR, deprecating npm versions, or force-pushing.
 - Never ask for, display, or store credentials or OTPs.
 
+## Work in isolated checkouts
+
+Never manipulate history in a checkout containing unrelated work. Fetch both
+repositories, confirm the source checkout is clean, and create a dedicated
+Ghost worktree from the freshly fetched `origin/main`.
+
+Run history-changing commands individually or in a fail-fast shell. A failed
+`git worktree add` must not be followed by `git subtree add` in whichever
+checkout happens to be current. Before choosing a branch or path, list existing
+worktrees and matching local and remote branches. Use a migration-specific slug,
+for example `codex/import-<package>-from-<source>`, rather than a generic name.
+
+If the destination branch or path already exists, stop and inspect its
+cleanliness, base, divergence, source split and attached worktree. Do not mutate,
+delete or silently reuse it. Present the evidence and ask the user whether to
+resume, preserve and supersede, or remove it when more than one choice is
+reasonable. A previous attempt can contain valid unmerged history even when its
+remote branch is gone.
+
+Before importing, record and compare the destination `HEAD` and `origin/main`;
+they must match. Recheck the first parent immediately after the subtree commit.
+
 ## Confirm this workflow applies
 
 Before changing either repository, record the source repository, its default
@@ -36,6 +58,22 @@ Publication or download counts alone do not prove that a package must remain a
 supported public API. If supported external consumers still need new releases,
 stop: this internal-only workflow is the wrong publishing model.
 
+For the public-consumer audit, check npm metadata, first-party repositories and
+documentation, plus GitHub code search for package dependencies and runtime
+imports. Classify results as first-party consumers, independent integrations,
+Ghost forks, or deployed Ghost installation snapshots. Forks and installation
+snapshots show historical presence only. Require a recent update, current
+deployment, active dependency or another freshness signal before treating them
+as evidence of continued installation needs; even then, they do not establish
+an independently supported API. Record the evidence and confidence behind the
+ownership decision; stop and ask if current support expectations remain
+unclear.
+
+Run registry-only `npm view` commands from a neutral temporary directory. A
+repository's `devEngines` policy can reject the host Node version before npm
+contacts the registry, which is unrelated to the package metadata audit. Record
+that failure separately if using a neutral directory does not resolve it.
+
 ## Produce these work products in order
 
 1. A green Ghost import PR with reachable source history.
@@ -63,14 +101,48 @@ commits manually.
 After the subtree commit, add focused integration commits that:
 
 - make the package private with an internal placeholder version;
+- set `ghostPackage.goldenPath` to `migration` and `ghostPackage.reason` to a
+  concise explanation of the remaining modernization work;
 - switch Ghost consumers to `workspace:*`;
 - update the lockfile with `pnpm`;
 - minimally adapt configuration and tests to work in Ghost;
 - retain runtime behavior for the later modernization PR.
 
+Before editing package metadata, map each source `workspace:*` dependency to
+its destination state:
+
+- use `workspace:*` when the dependency already exists in Ghost;
+- use `catalog:` when Ghost's catalog version satisfies the imported package;
+- add a named migration catalog with the exact published version when changing
+  the shared catalog would broaden the migration or alter runtime behavior;
+- stop if a required dependency is unpublished or exists only in the source
+  workspace.
+
+Document temporary named-catalog entries for the modernization follow-up. Never
+inline dependency versions; Ghost's strict catalog policy still applies. Do not
+import additional packages implicitly.
+
+If the package is legacy JavaScript or CommonJS, read
+[`references/legacy-integration.md`](references/legacy-integration.md)
+completely before creating integration commits.
+
 Verify that the subtree commit has two parents and that representative file
 history crosses into the source repository before opening the PR.
 
+Before opening the PR, also verify the source split is reachable from the branch
+tip, the consumer resolves the workspace package through its production import
+path, package lint and tests pass through Nx, relevant consumer tests pass, the
+full build passes, and the Ghost archive contains the internal package. Record
+the exact commit IDs and commands in the handoff.
+
+For a pilot or first use, include a structured gap report in the handoff:
+
+- `Observed`: the exact failure or ambiguity and the command/state that exposed it;
+- `Worked around`: the safe action taken, without hiding the original gap;
+- `Skill change`: the concrete instruction, preflight or script improvement;
+- `Tooling change`: anything that cannot be solved within this repository;
+- `Confidence`: high, medium or low, with unresolved evidence called out.
+
 ## 2. Merge the import without rewriting history
 
 This is the exceptional PR. It must use GitHub's **Create a merge commit**

.agents/skills/migrate-internal-package/references/history-and-merge.md

@@ -4,32 +4,83 @@ Read this reference before creating the Ghost import PR.
 
 ## Create package-only source history
 
-Work from an up-to-date clone of the source repository. Use its actual default
+Work from an up-to-date, clean, full clone of the source repository. Shallow and
+partial clones can complete `git subtree split` while still failing later when
+Ghost fetches the split, because the local source cannot serve promised objects.
+Reject them before splitting:
+
+```bash
+set -euo pipefail
+
+test "$(git rev-parse --is-shallow-repository)" = "false"
+test -z "$(git config --local --get extensions.partialClone || true)"
+```
+
+If either check fails, create a fresh full clone without `--depth`,
+`--filter` or sparse/partial clone options. Use the source's actual default
 branch and a temporary branch name that cannot be confused with a product
-branch. For example, when the default branch is `main`:
+branch.
+
+`git subtree split` may inspect thousands of commits and run for several
+minutes. Use `--quiet` in agent or CI-style runners so its progress stream does
+not flood or interrupt the runner. Run it on its own, keep the process alive
+until it returns an exit status, and do not mistake an output timeout for
+completion. For example, when the default branch is `main`:
 
 ```bash
+set -euo pipefail
+
 git fetch origin
 git switch --detach origin/main
+test -z "$(git status --porcelain)"
 git subtree split \
+  --quiet \
   --prefix=<source-package-path> \
-  -b migrate-<package>-history
+  -b migrate-<package>-history \
+  origin/main
 ```
 
-Record the split tip and inspect the resulting package-only history:
+Confirm the branch was actually created, then record the split tip and inspect
+the resulting package-only history:
 
 ```bash
-git rev-parse migrate-<package>-history
-git log --oneline --reverse migrate-<package>-history
+git show-ref --verify refs/heads/migrate-<package>-history
+source_split_tip=$(git rev-parse migrate-<package>-history)
+git log --oneline --reverse "$source_split_tip"
 ```
 
 `git subtree split` retains the relevant commit authorship and chronology while
 excluding unrelated source-repository paths.
 
 ## Attach the history to Ghost
 
-From a branch based on freshly fetched Ghost `origin/main`, fetch the local
-source split and add it without `--squash`:
+Before creating the worktree, inspect collisions rather than discovering them
+halfway through the import:
+
+```bash
+git fetch --prune origin
+git worktree list --porcelain
+git branch --list 'codex/import-<package>*'
+git branch --remotes --list 'origin/codex/import-<package>*'
+```
+
+If a match exists, record its worktree, cleanliness, base/divergence, imported
+split and remote state. Do not delete or overwrite it without an explicit user
+decision. Otherwise create or enter a dedicated Ghost worktree, then verify its
+branch, cleanliness, base and empty destination before attaching history:
+
+```bash
+set -euo pipefail
+
+test "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)"
+test "$(git branch --show-current)" = "codex/import-<package>-from-<source>"
+test -z "$(git status --porcelain)"
+test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
+test ! -e "packages/<ghost-directory>"
+```
+
+Fetch the local source split and add it without `--squash`. Run these as
+separate checked operations and stop immediately if either fails:
 
 ```bash
 git fetch /absolute/path/to/source-repository migrate-<package>-history
@@ -49,13 +100,40 @@ git-subtree-split: <source-split-tip>
 Verify the topology before adding integration commits:
 
 ```bash
-git show --no-patch --format='%H%nparents: %P%n%B' HEAD
+set -euo pipefail
+
+source_split_tip="<recorded-source-split-tip>"
+subtree_commit=$(git rev-parse HEAD)
+ghost_parent=$(git rev-parse HEAD^1)
+imported_parent=$(git rev-parse HEAD^2)
+source_path="path/to/representative-file"
+destination_path="packages/<ghost-directory>/$source_path"
+
+test "$ghost_parent" = "$(git rev-parse origin/main)"
+test "$imported_parent" = "$source_split_tip"
+git merge-base --is-ancestor "$source_split_tip" HEAD
+
+source_history=$(git log --full-history --format=%H "$source_split_tip" -- "$source_path")
+destination_history=$(git log --full-history --format=%H -- "$destination_path")
+test -n "$source_history"
+test -n "$destination_history"
+test "$(git rev-parse "$source_split_tip:$source_path")" = \
+  "$(git rev-parse "$subtree_commit:$destination_path")"
+
+git show --no-patch --format='%H%nparents: %P%n%B' "$subtree_commit"
 git log --graph --oneline --decorate --all --max-count=40
-git log --follow -- packages/<ghost-directory>/path/to/representative-file
+git log --full-history --oneline -- "$destination_path"
+git log --full-history --oneline "$source_split_tip" -- "$source_path"
 ```
 
-The subtree commit must have two parents, and its second parent must equal the
-recorded split tip.
+The subtree commit must have two parents: its first parent must equal the
+recorded Ghost base and its second parent must equal the recorded split tip.
+Checking the prefixed destination path with `--full-history` and the unprefixed
+split path separately is more reliable around merge boundaries than relying on
+ordinary path history or `--follow`, either of which may show only the subtree
+merge. Requiring non-empty histories and equal blob IDs makes a missing or
+mismatched representative file stop the import before integration edits obscure
+the source state.
 
 The Admin API schema migration from TryGhost/SDK is a known-good example: