feat(release): publish the docs image without cutting a release

[thoda-dev]

What this changes

Closes #25

Adds pnpm release:docs, which builds docker/docs.Dockerfile alone and pushes it to both
registries under :latest and an immutable :sha-<short>. No version bump, no CHANGELOG entry, no
git tag, no GitHub release.

Why

A wording fix in the documentation had to wait for a release of shhh, because release.mjs publishes
both images on the same tag ladder. That coupling made sense as written — a reader can pin the app
and its documentation to the same tag — but it is only true of the version tags, and it is what
made a typo cost a version number.

Republishing shhh-docs:1.1.9 with new content would have been the quick way out, and it is the one
thing this must not do: it breaks the single guarantee a version tag makes, and it would leave the
image's revision label naming a commit that is not what is inside it.

What's in it

scripts/release-docs.mjs. Moves :latest, adds :sha-<short>, and never writes 1.1.9,
1.1 or 1. Those stay the property of pnpm release, so they keep meaning "the documentation as
it shipped with that version of the app".

Two preflight checks refuse to publish where it might not be obvious, and both exist for the same
reason — the image carries a sha- tag and a revision label, and neither is worth anything if the
commit is not fetchable by anyone else:

• a dirty working tree
• a branch not pushed to origin

org.opencontainers.image.version carries the sha tag rather than the app's version. Labelling it
1.1.9 would have re-introduced exactly the confusion the split is meant to remove.

The helpers are duplicated from release.mjs rather than extracted into a shared module. That is
deliberate and commented in the file: the release path works, and a convenience script is not a good
reason to edit it and find out at the next release.

1.installation.md. "under the same tags" was no longer true, so it now reads "under the same
version tags", followed by a paragraph on what moves and what does not — pull :latest for the
current documentation, a version tag to match a pinned instance.

Checks

• pnpm lint, pnpm typecheck and pnpm test pass (119 tests) — all three are scoped to
  apps/app, which this branch does not touch.
• Schema change? None
• Touches crypto, authorization, or the paste read counter? None of them.

The script itself is not covered by any of the above, so I exercised it by hand with --dry-run:
the dirty-tree guard, the unpushed-branch guard, and the resulting docker buildx build command
line. The push itself has not been run — first real use will be the first publication.

AI assistance

• An AI tool was used — Claude Code (Opus 5) wrote the script and the documentation paragraph,
  and ran the dry-run checks. The decision to leave the version tags immutable rather than
  republish them is mine.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The new release script’s preflight checks don’t reliably block publishing when origin/<branch> is missing (unpushed branch) and builder detection can false-positive, risking a failed/incorrect publish path.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR decouples documentation image publishing from the main application release flow by introducing a dedicated pnpm release:docs script that builds/pushes only the docs image with moving :latest plus an immutable :sha-<short> tag, while keeping version tags exclusively owned by pnpm release.

Changes:

• Add scripts/release-docs.mjs to publish the docs Docker image independently (latest + sha tags) with preflight checks and optional dry-run.
• Register release:docs in package.json scripts.
• Update self-hosting documentation to clarify that only version tags are shared, and that docs :latest can move between app releases.

File summaries

File	Description
scripts/release-docs.mjs	New standalone docs-image release script with preflight checks and multi-arch buildx push.
package.json	Adds release:docs script entry.
apps/docs/content/2.self-hosting/1.installation.md	Clarifies tag semantics and documents docs-only republishing behavior.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.