@inditextech/docouture-cli 0.1.0-SNAPSHOT.40.1

package/build/templates/starter/src/modules/main/pages/getting-started.adoc

@@ -0,0 +1,169 @@
+= Getting started
+
+If this site is meant to end up published on GitHub Pages, see
+xref:main:prerequisites.adoc[Prerequisites] first — the repository needs to
+be public, GitHub Pages needs to be pointed at `gh-pages`, and the
+`docs/release` label needs to exist, none of which `docouture new` can set up on
+your behalf.
+
+== Start the local dev server
+
+[tabs]
+--
+[tab,label="pnpm"]
+****
+[,console]
+----
+$ pnpm install
+$ pnpm run dev
+----
+****
+
+[tab,label="npm"]
+****
+[,console]
+----
+$ npm install
+$ npm run dev
+----
+****
+--
+
+`docouture dev` (what either script above wraps) builds the site once, serves it
+on http://localhost:5000, and rebuilds and reloads the browser on every
+change under `docs/` or to `antora-playbook.local.yml` — pass `--port` to
+use a different one. See xref:main:components.adoc[] for what the built-in
+blocks (tabs, cards, accordion, …) actually look like while you write.
+
+For a single, non-watching build instead — what CI itself runs — use
+`docouture build`, a thin wrapper around `npm run build`/`pnpm run build`
+(`antora --fetch antora-playbook.yml`). Either way, the generated site is
+written to `build/site`.
+
+== Add a page
+
+Create an AsciiDoc file under `modules/<module>/pages/`, then add it to that
+module's `nav.adoc` so it appears in the navigation:
+
+[,asciidoc]
+----
+* xref:my-new-page.adoc[My new page]
+----
+
+A page that is not listed in the navigation is still published; it just
+cannot be reached by browsing. This page itself is listed — see `main`'s own
+`nav.adoc` — and is also linked directly from the landing's `Get started`
+action (xref:ROOT:index.adoc[]'s `:page-action:` attribute) and its first
+quicklink card.
+
+== Release the docs
+
+A release is cut by running `.github/workflows/docouture-release.yml`
+(scaffolded by `docouture new`), not by hand-editing anything in this directory.
+Two ways to trigger it:
+
+* **Manually** — Actions tab → "docouture-release" → Run workflow. Works
+  immediately, nothing to set up first.
+* **Automatically** — merge a pull request into `main` carrying the
+  `docs/release` label. Requires that label to already exist — see
+  xref:main:prerequisites.adoc[] — otherwise the merge is a silent no-op.
+
+Under the hood this bumps the version recorded in `docs/antora.yml` and
+moves the `stable` tag (or, in Versioned mode, cuts a new `vX.Y.Z` tag) —
+see that workflow's own header comment for the full mechanism.
+
+In *Versioned* mode, the target version for the *next* release is not typed
+into a form — it comes from `docs/.release-version`, a plain-text file
+`docouture new` already seeded (e.g. `0.1.0`). To release `1.0.0`:
+
+. Edit `docs/.release-version` so it contains `1.0.0`
+. Open a pull request with that change, labeled `docs/release`
+. Merge it — `docouture-release.yml` reads the file, tags `v1.0.0`, and bumps
+  `docs/.release-version` forward to the next patch version afterwards so
+  the file is always ready for whatever comes next
+
+(Or skip the PR: run `docouture-release.yml` manually via `workflow_dispatch` and
+type the version into its `version` input.) *Standalone* mode has no such
+file — every release always targets the same `stable` tag, so there is
+nothing to set beforehand.
+
+`docouture version <value>` is a different, narrower tool: it directly
+rewrites `docs/antora.yml`'s `version:`/`prerelease:` fields in place and
+leaves everything else in this directory untouched. It is what
+`docouture-release.yml` itself uses internally, and it's useful for local,
+throwaway testing of how a given version renders — but running it yourself
+does not cut a release, on either mode, and in particular it never touches
+`docs/.release-version`:
+
+[,console]
+----
+$ docouture version 1.0.0
+$ docouture version 1.1.0-rc.0 --prerelease
+----
+
+== Publish the docs
+
+`docouture new` already scaffolded two workflows that build this site and run
+`docouture publish gh-pages`:
+
+* **`docouture-publish-prerelease.yml`** — runs automatically on every ordinary
+  push to `main` that touches actual docs content, no label needed. This is
+  what keeps the prerelease version up to date after a normal merge.
+* **`docouture-publish.yml`** — not triggered by push itself; `docouture-release.yml`
+  calls it directly once a release is actually cut (see `== Release the
+  docs` above), and it stays available for a manual rebuild+republish of
+  whatever is currently on `main` via its own `workflow_dispatch`.
+
+Two things are still required before either of these actually publishes
+anything (see xref:main:prerequisites.adoc[] for the repository/GitHub-Pages
+side of this):
+
+. Add `@inditextech/docouture-publish-gh-pages` to this package's own
+  `devDependencies` — already present in the scaffolded `package.json` — and
+  install so it resolves.
+. Set `site.url` in `antora-playbook.yml` to this site's public URL. For a
+  GitHub Pages project page, that is `https://<org>.github.io/<repo>` — the
+  repository name has to be baked in as a path segment, or generated asset
+  URLs come out wrong.
+
+Optional: a custom domain is a `cname` string under this package's own
+`"docouture": { "publish": { "gh-pages": { "cname": "docs.example.com" } } }` in
+`package.json` (see the scaffolded stub there) — `docouture publish` writes it as
+a `CNAME` file alongside the built site. Leave the block empty, as scaffolded,
+for a plain `github.io` URL.
+
+The empty block is not "no config" — `@inditextech/docouture-publish-gh-pages`
+defaults `nojekyll` to `true` regardless, writing a `.nojekyll` file at the
+published branch's root. Without it, GitHub Pages' own Jekyll processing
+silently drops every `_`-prefixed path — exactly where the UI bundle's own
+assets live (`/_/css/...`, `/_/js/...`) — and the published site loads
+unstyled. Only worth touching if something else needs Jekyll processing on;
+pass `"nojekyll": false` in that same block to opt back into it.
+
+To publish once manually, from this directory:
+
+[tabs]
+--
+[tab,label="pnpm"]
+****
+[,console]
+----
+$ pnpm run build
+$ pnpm exec docouture publish gh-pages
+----
+****
+
+[tab,label="npm"]
+****
+[,console]
+----
+$ npm run build
+$ npx docouture publish gh-pages
+----
+****
+--
+
+`GITHUB_TOKEN` (set automatically in the Actions workflow) authenticates the
+push; running this locally needs a token of your own with `repo` scope,
+passed as the `GITHUB_TOKEN` environment variable.
+

package/build/templates/starter/src/modules/main/pages/glossary.adoc

@@ -0,0 +1,8 @@
+= Glossary
+
+Define project-specific terms here, one per section, so other pages can
+link to a definition instead of re-explaining it inline.
+
+== Example term
+
+A short definition of the term goes here. Replace with real terminology.

package/build/templates/starter/src/modules/main/pages/index.adoc

@@ -0,0 +1,9 @@
+= About
+
+This is the `main` module — a placeholder content module scaffolded by
+`docouture new`, structured the way a real documentation set typically is:
+an overview, a getting-started path, a section for the thing being
+documented, and additional reference material.
+
+Replace this page with a real introduction to what __DOCOUTURE_TITLE__ is and
+who it is for.

package/build/templates/starter/src/modules/main/pages/prerequisites.adoc

@@ -0,0 +1,55 @@
+= Prerequisites
+
+Before following xref:main:getting-started.adoc[Getting started] through to a
+published site, three things need to be true about this repository and its
+GitHub settings. None of them are things `docouture new` can do on your behalf —
+they all require repository-admin access this CLI never has.
+
+== The repository must be public
+
+GitHub Pages serves a `gh-pages` branch to the public internet on a free
+plan only for a public repository — a private one needs GitHub Enterprise
+(GitHub Pages on a paid plan can be restricted to organisation members, but
+is still not the "publish this to the world" flow `docouture-publish.yml`
+assumes). If this repository is private and is meant to stay that way,
+publishing to GitHub Pages is not the right target — use `docouture build` and
+ship `build/site` some other way instead.
+
+== Enable GitHub Pages, serving from `gh-pages`
+
+Settings → Pages → **Build and deployment** → **Source**: "Deploy from a
+branch" → **Branch**: `gh-pages` / `/ (root)`.
+
+The `gh-pages` branch does not exist yet on a brand-new repository — it is
+created the first time `docouture publish gh-pages` (or the scaffolded
+`.github/workflows/docouture-publish.yml`, which calls it) actually runs. Publish
+once first — either by pushing to `main` and letting that workflow run, or
+manually per xref:main:getting-started.adoc[Getting started]'s own "Publish
+the docs" section — then come back and point Pages at the branch it created.
+Turning Pages on before that branch exists just leaves the picker with
+nothing to select.
+
+== Create the `docs/release` label
+
+`.github/workflows/docouture-release.yml` (scaffolded by `docouture new`) can cut a
+release two ways: `workflow_dispatch` (run it by hand from the Actions tab —
+works immediately, nothing to set up), or automatically whenever a pull
+request merges into `main` carrying a `docs/release` label.
+
+That label is not created automatically — GitHub does not create labels
+referenced by a workflow's `if:` condition, and `docouture new` does not call the
+GitHub API on your behalf. Until the label exists, only the manual
+`workflow_dispatch` path works; a PR merged with what would otherwise be the
+intended label name is a silent no-op, not an error.
+
+Create it once, from this repository:
+
+[,console]
+----
+$ gh label create docs/release --description "Merging this PR cuts a release" --color 0E8A16
+----
+
+Or via the GitHub UI: repository → Issues or Pull requests → Labels → New
+label, named exactly `docs/release`. `docouture doctor` warns (without failing)
+if it does not find this label, when the `gh` CLI is available and
+authenticated.

package/build/templates/starter/src/modules/main/pages/quickstart.adoc

@@ -0,0 +1,21 @@
+= Quickstart
+
+Walk through the smallest path to a working result, as concrete steps.
+
+== 1. Install
+
+[,console]
+----
+$ echo "replace with the real install command"
+----
+
+== 2. Run
+
+[,console]
+----
+$ echo "replace with the real run command"
+----
+
+== 3. Verify
+
+Describe what success looks like here.

package/build/templates/starter/src/modules/main/pages/release-notes/index.adoc

@@ -0,0 +1,9 @@
+= Release notes
+
+Summarize what changed for users in each release here, newest first — in
+contrast to xref:main:changelog/index.adoc[Changelog], which is the
+unabridged commit-level record.
+
+== v0.1.0
+
+Placeholder entry. Replace with the real first release's notes.

package/build/templates/starter/src/modules/main/pages/requirements.adoc

@@ -0,0 +1,8 @@
+= Requirements
+
+List the prerequisites someone needs before following the
+xref:main:quickstart.adoc[Quickstart] — tooling, versions, accounts, or
+access.
+
+* Requirement one
+* Requirement two

package/build/templates/starter/src/modules/main/pages/roadmap.adoc

@@ -0,0 +1,4 @@
+= Roadmap
+
+Describe what is planned next here — in enough detail to set expectations,
+without promising dates this page will have to walk back.

package/build/templates/starter/src/modules/main/pages/structure.adoc

@@ -0,0 +1,5 @@
+= Structure
+
+Describe the project's own structure here — the layout of its repository,
+packages, or modules, and where a contributor would look for a given piece
+of functionality.

package/build/templates/starter/src/release-version.versioned

@@ -0,0 +1 @@
+0.1.0

package/build/templates/workflows/docouture-kroki-cache-warm.yml

@@ -0,0 +1,101 @@
+name: docouture-kroki-cache-warm
+
+# GitHub Actions' cache is scoped to the branch/ref a run executes under, not
+# just the key string — and a `pull_request`-triggered run (docouture-release.yml's
+# main trigger) is ALWAYS scoped to that PR's own ephemeral merge ref
+# (`refs/pull/<N>/merge`), by design, even when it targets `main` and even
+# after it merges. See GitHub's own docs ("Restrictions for accessing a
+# cache"): "Caches created by a pull_request run are already scoped to the
+# merge ref ... and cannot be written to the default branch's scope." That
+# means every release PR gets its own throwaway cache scope — release #12's
+# warm Kroki image cache is invisible to release #13, #14, etc., even though
+# the cache KEY (kroki-compose.yml's own hash) never changes between them.
+#
+# The one sanctioned way around this (same docs, "Cache access for low-trust
+# workflow triggers"): "ensure there is a trusted workflow that keeps the
+# cache updated, for example a CI build triggered by a push to the default
+# branch." `push` is on GitHub's trusted-trigger allowlist, so a run
+# triggered this way writes into the DEFAULT BRANCH's cache scope — and any
+# other run in this repo (any PR, any ref, `pull_request: closed` included)
+# automatically falls back to that scope on its own cache lookup, no
+# `restore-keys` needed, since the key string is already identical
+# everywhere. That's this workflow's only job: keep that default-branch-scoped
+# entry warm, so docouture-pr-verify.yml/docouture-release.yml/docouture-publish.yml's own
+# (unmodified) cache steps get a real hit instead of a cold pull on every run.
+#
+# Gated on `kroki-enabled` the same way those three are — no point warming a
+# cache for images a disabled site's build will never touch.
+on:
+  push:
+    branches: ['main*']
+
+concurrency:
+  group: docouture-kroki-cache-warm
+  cancel-in-progress: true
+
+jobs:
+  warm:
+    name: Warm Kroki image cache
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # `docouture new` scaffolds this site's package.json, antora-playbook.yml
+    # etc. under docs/ (not the repository root) — see the docs-site-package
+    # skill's reference/versioning-modes.md. Every step below runs from
+    # there; only .github/workflows itself has to live at the true repo
+    # root, since that is the one path GitHub Actions requires.
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # __DOCOUTURE_PM_SETUP_STEP__
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          # Reads engines.node from docs/package.json — no separate version
+          # file to keep in sync.
+          node-version-file: docs/package.json
+          cache: __DOCOUTURE_PM_CACHE__
+          # `defaults.run.working-directory: docs` above only applies to
+          # `run:` steps, not to this action's own inputs — without this,
+          # setup-node looks for a lockfile from the repo root and fails.
+          cache-dependency-path: docs/__DOCOUTURE_LOCKFILE__
+
+      - name: Install dependencies
+        run: __DOCOUTURE_INSTALL_CI__
+
+      # This is `main`'s own real antora-playbook.yml (this workflow only
+      # ever runs on a push to main, so there's no local/tag ambiguity to
+      # worry about the way docouture-release.yml's build step has) — see
+      # docouture-pr-verify.yml's own comment on the `kroki-enabled` attribute.
+      - name: Kroki / Detect enabled
+        id: kroki-check
+        run: |
+          if grep -qE "^\s*kroki-enabled:\s*['\"]?true['\"]?\s*(#.*)?$" antora-playbook.yml; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Same cache key as docouture-pr-verify.yml/docouture-release.yml/
+      # docouture-publish.yml — the point of this job is only WHERE it's written
+      # from (a trusted `push` trigger, landing in the default branch's cache
+      # scope), never a different key. No load/consume step below: nothing
+      # else in this job needs the images locally, it only needs the cache
+      # entry to exist for those other workflows to fall back to.
+      - name: Kroki / Docker image cache
+        id: kroki-cache
+        if: steps.kroki-check.outputs.enabled == 'true'
+        uses: actions/cache@v4
+        with:
+          path: /tmp/kroki-images.tar
+          key: ${{ runner.os }}-kroki-images-${{ hashFiles('**/kroki-compose.yml') }}
+
+      - name: Kroki / Pull and save images
+        if: steps.kroki-check.outputs.enabled == 'true' && steps.kroki-cache.outputs.cache-hit != 'true'
+        run: |
+          compose_file="$(find . -name kroki-compose.yml 2>/dev/null | head -1)"
+          docker compose -f "$compose_file" pull
+          docker save -o /tmp/kroki-images.tar $(docker compose -f "$compose_file" config --images)

package/build/templates/workflows/docouture-pr-verify.yml

@@ -0,0 +1,120 @@
+name: docouture-pr-verify
+
+# Validates that the docs still build on a pull request. Deliberately builds
+# only the PR's own HEAD — not whichever refs this site's versioning mode
+# (see the docs-site-package skill's versioning-modes.md) publishes from:
+#
+#   - Versioned (Full History): not the prerelease branch, not any `v*`
+#     release tag.
+#   - Standalone (Stable + Prerelease): not the prerelease branch, not the
+#     rolling `stable` tag.
+#
+# A PR checkout is on a detached HEAD or a feature branch — neither of those
+# refs — so building the real `antora-playbook.yml` here would either fail
+# (the refs it names are not reachable from a shallow, single-ref checkout)
+# or silently validate the wrong content. `antora-playbook.local.yml` (see
+# that file's own header) exists for exactly this: one content source,
+# `branches: HEAD`, so this always validates whatever the PR actually
+# changed — no `fetch-depth: 0` needed, since no other ref is ever read.
+on:
+  pull_request: {}
+
+concurrency:
+  group: docouture-pr-verify-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: Verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # `docouture new` scaffolds this site's package.json, antora-playbook.yml
+    # etc. under docs/ (not the repository root) — see the docs-site-package
+    # skill's reference/versioning-modes.md. Every step below runs from
+    # there; only .github/workflows itself has to live at the true repo
+    # root, since that is the one path GitHub Actions requires.
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # __DOCOUTURE_PM_SETUP_STEP__
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          # Reads engines.node from docs/package.json — no separate version
+          # file to keep in sync.
+          node-version-file: docs/package.json
+          cache: __DOCOUTURE_PM_CACHE__
+          # `defaults.run.working-directory: docs` above only applies to
+          # `run:` steps, not to this action's own inputs — without this,
+          # setup-node looks for a lockfile from the repo root and fails.
+          cache-dependency-path: docs/__DOCOUTURE_LOCKFILE__
+
+      - name: Install dependencies
+        run: __DOCOUTURE_INSTALL_CI__
+
+      # This build's antora-playbook.local.yml (the file Build actually reads
+      # below) may or may not have `kroki-enabled: true` — a site can turn it
+      # off (see that attribute's own comment). When it's off, the Build
+      # step's implicit Kroki startup never runs, so priming a Docker image
+      # store for it would just waste time on every single PR run; this step
+      # checks that up front and gates the three Kroki steps below on it.
+      - name: Kroki / Detect enabled
+        id: kroki-check
+        run: |
+          if grep -qE "^\s*kroki-enabled:\s*['\"]?true['\"]?\s*(#.*)?$" antora-playbook.local.yml; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # When enabled: the Build step below renders real diagrams through a
+      # local Kroki service that `@inditextech/docouture-antora-extensions`'
+      # `kroki-prewarm.js` starts itself (docker compose) the moment it finds
+      # nothing listening yet — no explicit setup needed for that. These two
+      # steps only prime the runner's Docker image store first, so that
+      # implicit startup finds everything already pulled instead of doing it
+      # cold on every run. Cache key is the compose file's own hash (images
+      # are pinned by digest, not `:latest` — see that file's own header), so
+      # it only invalidates when the actual pinned images change.
+      - name: Kroki / Docker image cache
+        id: kroki-cache
+        if: steps.kroki-check.outputs.enabled == 'true'
+        uses: actions/cache@v4
+        with:
+          path: /tmp/kroki-images.tar
+          key: ${{ runner.os }}-kroki-images-${{ hashFiles('**/kroki-compose.yml') }}
+
+      - name: Kroki / Load cached images
+        if: steps.kroki-check.outputs.enabled == 'true' && steps.kroki-cache.outputs.cache-hit == 'true'
+        run: docker load -i /tmp/kroki-images.tar
+
+      - name: Kroki / Pull and save images
+        if: steps.kroki-check.outputs.enabled == 'true' && steps.kroki-cache.outputs.cache-hit != 'true'
+        run: |
+          # docs/kroki-compose.yml if this site has ejected it (see that
+          # file's own header), else the bundled default under node_modules.
+          compose_file="$(find . -name kroki-compose.yml 2>/dev/null | head -1)"
+          docker compose -f "$compose_file" pull
+          docker save -o /tmp/kroki-images.tar $(docker compose -f "$compose_file" config --images)
+
+      - name: Build
+        run: npx antora --fetch antora-playbook.local.yml
+
+      # Antora's own `runtime.log.failure_level: warn` (see
+      # antora-playbook.yml's own comment) already fails the Build step above
+      # on a broken cross-reference — but that only covers refs Antora
+      # itself resolves. Raw http(s) links in content are invisible to it, so
+      # `check-links` (package.json's own script, see scripts/check-links.mjs)
+      # crawls the built HTML separately to catch those before they reach a
+      # PR reviewer. It only fails on a broken EXTERNAL link — a broken local
+      # one is printed as a warning, never a failure, since this job builds
+      # with antora-playbook.local.yml (a single, HEAD-only source) and
+      # content generated from config (the module switcher, the footer) can
+      # legitimately point at another version/component this reduced build
+      # doesn't have. See that script's own header comment.
+      - name: Check links
+        run: __DOCOUTURE_PM__ run check-links

package/build/templates/workflows/docouture-publish-prerelease.yml

@@ -0,0 +1,122 @@
+name: docouture-publish-prerelease
+
+# Rebuilds and republishes the prerelease (main-branch) docs automatically on
+# every ordinary push to main* that actually touches content — no
+# docs/release label needed, unlike docouture-release.yml. This exists
+# specifically so ordinary content merges show up without anyone having to
+# fall back to docouture-publish.yml's own workflow_dispatch every time.
+#
+# A plain `on: push: branches: [main*]` used to live directly on
+# docouture-publish.yml and was removed for two reasons — see that file's own
+# header comment. Both are avoided here by construction rather than by
+# reintroducing the same trigger in the same place:
+#
+#   1. An unrelated commit shouldn't kick off a rebuild with nothing new to
+#      publish. `check-changes-in-paths` (below) gates on real content paths
+#      only. In particular this deliberately excludes docs/.release-version:
+#      that file is the ONLY thing docouture-release.yml's own "Bump release
+#      descriptor" step pushes straight to main directly (see that
+#      workflow's own comment on that step) — a bot commit that is not new
+#      docs content and would otherwise fire this workflow for nothing.
+#
+#   2. Firing twice for one release — once from a docs/release-labeled
+#      merge's own content, and again from docouture-release.yml's chained
+#      docouture-publish.yml call once the tag is actually cut — is not a race
+#      (the two are sequential, not simultaneous: this workflow's own push
+#      event fires at merge time, before docouture-release.yml's job even
+#      starts), just a redundant rebuild. `check-release-label` (below)
+#      closes that gap directly: if the commit that triggered this push came
+#      from a merged pull request carrying the docs/release label,
+#      docouture-release.yml is already about to publish the definitive
+#      post-release build itself, so this workflow skips rather than
+#      duplicate it.
+on:
+  push:
+    branches: ['main*']
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: docouture-publish-prerelease
+  cancel-in-progress: true
+
+jobs:
+  check-changes-in-paths:
+    name: Check for changes in corresponding paths
+    runs-on: ubuntu-latest
+    outputs:
+      detected: ${{ steps.changes.outputs.paths }}
+    steps:
+      # dorny/paths-filter diffs github.event.before -> github.sha via local
+      # git history on a push trigger (unlike a pull_request trigger, where
+      # it can resolve the base from the GitHub API alone) — needs an actual
+      # checkout first, or there is no .git to diff against at all
+      # (`git` exits 128, "not a git repository"/"bad revision"). fetch-depth
+      # 0 rather than a shallow default: a batched push can carry more
+      # commits than a shallow clone's history would contain, and `before`
+      # must be reachable locally for the diff to succeed.
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for changed files in specific paths
+        id: changes
+        uses: dorny/paths-filter@ebc4d7e9ebcb0b1eb21480bb8f43113e996ac77a # v3
+        with:
+          filters: |
+            paths:
+              - 'docs/src/**'
+              - 'docs/antora-playbook*.yml'
+              - 'docs/supplemental-ui/**'
+              # docs/.release-version is deliberately NOT listed — see this
+              # file's own header comment, point 1.
+
+  check-release-label:
+    name: Check for docs/release label on the triggering pull request
+    needs: check-changes-in-paths
+    if: needs.check-changes-in-paths.outputs.detected == 'true'
+    runs-on: ubuntu-latest
+    outputs:
+      skip: ${{ steps.check.outputs.skip }}
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      # Resolves the merged pull request (if any) that produced this push's
+      # HEAD commit, regardless of merge strategy (merge commit, squash, or
+      # rebase) — GitHub tracks this association itself rather than this
+      # step having to guess from the SHA, see
+      # https://docs.github.com/en/rest/commits/commits#list-pull-requests-associated-with-a-commit.
+      # A direct push to main with no associated pull request (e.g. an admin
+      # pushing straight to main) simply resolves no labels and is never
+      # skipped here.
+      - name: Check for docs/release label
+        id: check
+        run: |
+          labels=$(gh api "repos/${{ github.repository }}/commits/${{ github.sha }}/pulls" \
+            --jq '.[0].labels[].name' 2>/dev/null || echo "")
+
+          if echo "$labels" | grep -qx 'docs/release'; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "This push came from a docs/release-labeled merge — docouture-release.yml will publish the definitive build itself, skipping here."
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  publish:
+    name: Publish
+    needs: [check-changes-in-paths, check-release-label]
+    if: needs.check-changes-in-paths.outputs.detected == 'true' && needs.check-release-label.outputs.skip != 'true'
+    # docouture-publish.yml's own `publish` job requests `contents: write` (only
+    # ever used by @inditextech/docouture-publish-gh-pages, pushing to the
+    # `gh-pages` branch) — a reusable workflow can never be granted more than
+    # its caller job holds, so without this the call is rejected outright as
+    # a permissions escalation rather than merely losing write access at
+    # runtime. The two gate jobs above stay read-only; only this job, which
+    # actually calls through, needs the elevated grant.
+    permissions:
+      contents: write
+    uses: ./.github/workflows/docouture-publish.yml
+    secrets: inherit