@inditextech/docouture-cli 0.1.0-SNAPSHOT.68.1 → 0.1.0-SNAPSHOT.74.1

package/build/lib/branch-detect.js

@@ -0,0 +1,87 @@
+'use strict';
+// Branch-name derivation for git-flow support (GH #175) — deliberately not
+// persisted anywhere as its own config, the same way `docouture-release.yml`'s
+// "Detect mode" step derives standalone-vs-versioned live from
+// antora-playbook.yml's own `tags:` line rather than reading it back from a
+// stored value. Here the two branch *roles* are re-derived live from the
+// two files that actually carry them:
+//
+//   - prerelease branch: antora-playbook.yml's content.sources[0].branches
+//     (see lib/playbook-yml.ts's readBranches)
+//   - release branch: docouture-release.yml's checkout `ref:` (the same
+//     literal value it also pushes bump commits to, see that workflow's own
+//     "Checkout"/"Bump release descriptor" steps)
+//
+// `docs/package.json`'s `docouture.branching` field ('trunk-based' |
+// 'git-flow') is a cheap, redundant-by-design fast-path signal on top of
+// this — never the source of truth for the names themselves, only for
+// `docouture doctor`'s advisory check to compare this derivation against.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readBranches } from './playbook-yml.js';
+/**
+ * `docouture-release.yml`'s checkout target — the one literal `ref:` key this
+ * template file has (its "Checkout" step). Same regex-over-text idiom as
+ * playbook-yml.ts, not a real YAML parse: this file is only ever read here,
+ * matching how upgrade.ts already treats docs/antora.yml.
+ */
+export function readReleaseBranchFromWorkflow(workflowContent) {
+    const match = /^\s*ref:\s*(\S+?)\s*$/m.exec(workflowContent);
+    if (!match?.[1])
+        return null;
+    return match[1].replace(/^['"]|['"]$/g, '');
+}
+/**
+ * Reads both branch roles back from whatever is actually on disk right now
+ * — `antora-playbook.yml` under the site root, `docouture-release.yml` under
+ * the repository's `.github/workflows/`. Either side resolves to `null` if
+ * its file is missing or the expected line isn't found (a site scaffolded
+ * before this feature existed still resolves fine here, since both files'
+ * shapes predate GH #175 unchanged — this is not a "legacy fallback", it is
+ * the only path).
+ */
+export async function detectBranches(siteRoot, repoRoot) {
+    const playbookFile = join(siteRoot, 'antora-playbook.yml');
+    const releaseWorkflowFile = join(repoRoot, '.github', 'workflows', 'docouture-release.yml');
+    let prerelease = null;
+    try {
+        const content = await readFile(playbookFile, 'utf8');
+        prerelease = readBranches(content)?.[0] ?? null;
+    }
+    catch {
+        // No antora-playbook.yml at siteRoot — prerelease stays null.
+    }
+    let release = null;
+    try {
+        const content = await readFile(releaseWorkflowFile, 'utf8');
+        release = readReleaseBranchFromWorkflow(content);
+    }
+    catch {
+        // No docouture-release.yml under .github/workflows/ — release stays null.
+    }
+    return { prerelease, release };
+}
+/**
+ * Trunk-based is definitionally the degenerate case where both roles are
+ * the same branch (see the issue's own design note) — so this is a plain
+ * equality check, not a third independently-stored value. Returns `null`
+ * when either side couldn't be read, so callers can distinguish "genuinely
+ * ambiguous/unreadable" from a real answer.
+ */
+export function inferBranching(branches) {
+    if (!branches.prerelease || !branches.release)
+        return null;
+    return branches.prerelease === branches.release ? 'trunk-based' : 'git-flow';
+}
+/**
+ * docouture-kroki-cache-warm.yml's `on.push.branches` array content — see
+ * TemplateValues.cacheWarmBranchesYaml's own comment on why this workflow
+ * triggers on both roles unconditionally rather than just one. Collapses to
+ * a single glob when both roles are the same branch (trunk-based) instead
+ * of a literal, pointless duplicate.
+ */
+export function cacheWarmBranchesYaml(prereleaseBranch, releaseBranch) {
+    const branches = prereleaseBranch === releaseBranch ? [releaseBranch] : [releaseBranch, prereleaseBranch];
+    return branches.map((branch) => `'${branch}*'`).join(', ');
+}
+//# sourceMappingURL=branch-detect.js.map

package/build/lib/copy-template.js

@@ -27,6 +27,10 @@ const PLACEHOLDERS = {
     // TemplateValues.repoIgnoreGlob's own comment for why the whole-segment
     // trick doesn't survive here.
     __DOCOUTURE_REPO_IGNORE_GLOB__: 'repoIgnoreGlob',
+    __DOCOUTURE_PRERELEASE_BRANCH__: 'prereleaseBranch',
+    __DOCOUTURE_RELEASE_BRANCH__: 'releaseBranch',
+    __DOCOUTURE_BRANCHING__: 'branching',
+    __DOCOUTURE_CACHE_WARM_BRANCHES__: 'cacheWarmBranchesYaml',
 };
 // `<!-- prettier-ignore -->` directives exist only to stop prettier mangling a
 // placeholder token in the template source (e.g. `__DOCOUTURE_TITLE__` inside a

package/build/lib/dev-server.js

@@ -291,11 +291,25 @@ export async function startDevServer(options) {
             }
         }
     }
-    if (!existsSync(root)) {
-        log('no build output yet, building the site');
-        if (!(await runBuild())) {
+    // Always build once up front, even when a prior `build/site` already
+    // exists on disk (a previous `docouture build`/`dev` session, or one this
+    // process's own file watcher hasn't caught up to yet) — serving stale
+    // output silently, with no visible sign anything is out of date, was a
+    // real footgun: a `docouture dev` started after content changed on disk
+    // since the last build would show the OLD site until the next watched
+    // change fired, which can look indistinguishable from "my edit didn't
+    // take" if that first edit is what's being tested. Only when there's
+    // truly nothing to fall back to (no prior `build/site` at all) does a
+    // failed initial build actually throw; if stale output already exists,
+    // this degrades exactly like a failed watch-triggered rebuild does
+    // below — log it and keep serving what's there.
+    const hadExistingBuild = existsSync(root);
+    log(hadExistingBuild ? 'building the site' : 'no build output yet, building the site');
+    if (!(await runBuild())) {
+        if (!hadExistingBuild) {
             throw new Error('initial build failed');
         }
+        logError('initial rebuild failed, serving the previous build');
     }
     await new Promise((resolvePromise, reject) => {
         server.once('error', reject);

package/build/lib/doctor-checks.js

@@ -227,4 +227,44 @@ export function checkAgentFilesPresent(repoRoot) {
             };
     });
 }
+/**
+ * Whether `docs/package.json`'s declared `docouture.branching` still agrees
+ * with what antora-playbook.yml/docouture-release.yml actually say — the
+ * same "names must agree" idiom as checkNamesAgree above, just for a single
+ * pair instead of four. Advisory only, same reasoning as
+ * checkReleaseLabelExists: a site predating GH #175 (no declared value yet)
+ * or one where the derivation itself failed (malformed/hand-edited
+ * templates) is reported as `ok: true` rather than a failure — only an
+ * actual, confident disagreement between the two is `ok: false`.
+ */
+export function checkBranchingAgrees(input) {
+    const label = 'branching model';
+    if (!input.declaredBranching) {
+        return {
+            ok: true,
+            label,
+            message: 'no docouture.branching declared in docs/package.json — skipping',
+        };
+    }
+    if (!input.actualBranching) {
+        return {
+            ok: true,
+            label,
+            message: 'could not derive the current branch names from antora-playbook.yml/docouture-release.yml — skipping',
+        };
+    }
+    if (input.declaredBranching === input.actualBranching) {
+        return {
+            ok: true,
+            label,
+            message: `docouture.branching '${input.declaredBranching}' matches what antora-playbook.yml/docouture-release.yml actually say`,
+        };
+    }
+    return {
+        ok: false,
+        label,
+        message: `docouture.branching '${input.declaredBranching}' != actual '${input.actualBranching}' (derived from antora-playbook.yml/docouture-release.yml)`,
+        detail: "run 'docouture branch-model <trunk-based|git-flow>' to re-sync everything, or fix docs/package.json's docouture.branching by hand if it's simply stale",
+    };
+}
 //# sourceMappingURL=doctor-checks.js.map

package/build/lib/playbook-yml.js

@@ -87,4 +87,55 @@ export function readSourceUrl(content) {
 export function readOutputDir(content) {
     return firstField(topLevelBlock(content, 'output'), 'dir');
 }
+/**
+ * `content.sources[0].branches` — an inline YAML array (e.g. `[main]`), not
+ * a scalar, so this reads it as one and splits it, unlike every other
+ * reader above. Used by lib/branch-detect.ts to derive the *prerelease*
+ * branch role (GH #175) — see that module's own comment on why this is
+ * derived live rather than stored anywhere.
+ */
+export function readBranches(content) {
+    const raw = firstField(topLevelBlock(content, 'content'), 'branches');
+    if (!raw)
+        return null;
+    const inner = raw.trim().replace(/^\[/, '').replace(/\]$/, '');
+    const values = inner
+        .split(',')
+        .map((value) => value.trim().replace(/^['"]|['"]$/g, ''))
+        .filter(Boolean);
+    return values.length > 0 ? values : null;
+}
+/**
+ * Rewrites `content.sources[0].branches`'s inline array to a single new
+ * branch name — the one write this module performs, used by `docouture
+ * branch-model` (GH #175) to update an existing site's playbook without a
+ * full re-scaffold. Mirrors topLevelBlock's own line-classification (blank/
+ * comment lines skipped, a non-indented line either continues or ends the
+ * block) so the same top-level-key scoping applies here as everywhere else
+ * in this file; returns `content` unchanged if no `branches:` line is found
+ * within `content:`'s block.
+ */
+export function writeBranches(content, branch) {
+    const lines = content.split('\n');
+    let inBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\s*(?:#.*)?$/.test(line))
+            continue;
+        if (/^\S/.test(line)) {
+            if (inBlock)
+                break;
+            inBlock = /^content:/.test(line);
+            continue;
+        }
+        if (inBlock) {
+            const match = /^(\s*(?:-\s*)?branches:\s*)\[[^\]]*\](.*)$/.exec(line);
+            if (match) {
+                lines[i] = `${match[1]}[${branch}]${match[2]}`;
+                return lines.join('\n');
+            }
+        }
+    }
+    return content;
+}
 //# sourceMappingURL=playbook-yml.js.map

package/build/templates/starter/antora-playbook.local.yml

@@ -10,20 +10,22 @@
 # Once this site adopts one of the two documented versioning modes (see the
 # docouture docs-site-package skill's reference/versioning-modes.md), the real
 # `antora-playbook.yml` aggregates content from more than just whatever is
-# checked out right now — versioned matches `branches: [main]` +
-# `tags: ['docs/v*']`, standalone matches `branches: [main]` + `tags: ['docs/stable']`.
-# A PR build (or a local build on a feature branch) is on a detached HEAD or
-# a branch that is neither of those, so `main` and the version tag(s) are
-# not resolved in that checkout — the real playbook either fails or silently
-# builds fewer versions than it should.
+# checked out right now — versioned matches `branches: [<prerelease branch>]` +
+# `tags: ['docs/v*']`, standalone matches `branches: [<prerelease branch>]` +
+# `tags: ['docs/stable']` (see the guides-branching-model guide for what
+# "prerelease branch" means — `main` for a trunk-based site, `develop` for a
+# git-flow one). A PR build (or a local build on a feature branch) is on a
+# detached HEAD or a branch that is neither of those, so the prerelease
+# branch and the version tag(s) are not resolved in that checkout — the real
+# playbook either fails or silently builds fewer versions than it should.
 #
 # This playbook points content aggregation at HEAD (the current worktree)
 # instead, so `docouture dev` (see src/lib/dev-server.ts) and
 # `docouture-pr-verify.yml` (see .github/workflows/) validate the current docs
-# content without needing `main` or any release ref. It intentionally never
-# changes shape when a site switches versioning mode, or adds a release:
-# there is always exactly one thing to validate, whatever is currently
-# checked out.
+# content without needing the prerelease branch or any release ref. It
+# intentionally never changes shape when a site switches versioning mode or
+# branching model, or adds a release: there is always exactly one thing to
+# validate, whatever is currently checked out.
 #
 # Publishing (`docouture-publish.yml`) uses the real `antora-playbook.yml`.
 #

package/build/templates/starter/antora-playbook.versioned.yml

@@ -55,15 +55,16 @@ content:
       # playbook's comment: the starter template's own nested `src/` lands
       # one level below this repository's `docs/`.
       start_path: docs/src
-      # Versioned (Full History): `main` aggregates as the prerelease
-      # version — docs/antora.yml on this branch says `version: prerelease`,
-      # `prerelease: true`, the same as the standalone mode's shape (this
-      # descriptor is identical for both modes on main — see docs/antora.yml's
-      # own comment). `tags: ['docs/v*']` matches every release tag (docs/v1.2.0,
-      # docs/v2.0.0, ...) docouture-release.yml cuts, each an immutable version with
-      # its own copy of docs/antora.yml — the version dropdown grows by one
-      # every release and nothing here ever needs editing again.
-      branches: [main]
+      # Versioned (Full History): __DOCOUTURE_PRERELEASE_BRANCH__ aggregates
+      # as the prerelease version — docs/antora.yml on this branch says
+      # `version: prerelease`, `prerelease: true`, the same as the
+      # standalone mode's shape (this descriptor is identical for both
+      # modes on this branch — see docs/antora.yml's own comment).
+      # `tags: ['docs/v*']` matches every release tag (docs/v1.2.0,
+      # docs/v2.0.0, ...) docouture-release.yml cuts, each an immutable version
+      # with its own copy of docs/antora.yml — the version dropdown grows by
+      # one every release and nothing here ever needs editing again.
+      branches: [__DOCOUTURE_PRERELEASE_BRANCH__]
       tags: ['docs/v*']
 
 ui:

package/build/templates/starter/antora-playbook.yml

@@ -58,14 +58,16 @@ content:
       # copied under this repository's `docs/`, so the descriptor ends up at
       # `docs/src/antora.yml`.
       start_path: docs/src
-      # Standalone: `main` aggregates as the prerelease version —
-      # docs/antora.yml on this branch permanently says `version: prerelease`,
-      # `prerelease: true`. `docs/stable` is a rolling tag that docouture-release.yml
-      # force-moves to a fresh one-off commit on every release, not a second
-      # long-lived branch. Until the first release, `docs/stable` does not exist
-      # yet and this site builds with just the one (prerelease) version —
-      # that is expected, not an error.
-      branches: [main]
+      # Standalone: __DOCOUTURE_PRERELEASE_BRANCH__ aggregates as the prerelease
+      # version — docs/antora.yml on this branch permanently says
+      # `version: prerelease`, `prerelease: true`. `docs/stable` is a rolling
+      # tag that docouture-release.yml force-moves to a fresh one-off commit
+      # on every release, cut from the (independently-named) release branch
+      # — see docouture-release.yml's own header and the
+      # guides-branching-model guide. Until the first release, `docs/stable`
+      # does not exist yet and this site builds with just the one
+      # (prerelease) version — that is expected, not an error.
+      branches: [__DOCOUTURE_PRERELEASE_BRANCH__]
       tags: ['docs/stable']
 
 ui:

package/build/templates/starter/package.json

@@ -20,10 +20,11 @@
     "@inditextech/docouture-asciidoc-extensions": "__DOCOUTURE_CLI_VERSION__",
     "@inditextech/docouture-antora-extensions": "__DOCOUTURE_CLI_VERSION__",
     "@inditextech/docouture-publish-gh-pages": "__DOCOUTURE_CLI_VERSION__",
-    "antora": "3.1.15",
+    "antora": "3.2.0",
     "linkinator": "8.0.4"
   },
   "docouture": {
+    "branching": "__DOCOUTURE_BRANCHING__",
     "publish": {
       "gh-pages": {}
     },

package/build/templates/starter/src/antora.yml

@@ -49,13 +49,13 @@ nav:
 # silently camelCased by Antora's content aggregator, which breaks any module
 # slug containing a hyphen.
 #
-# `icon` is `<group>/<name>` from the UI bundle's own vendored sprite
+# `icon` is a bare icon name from the UI bundle's own vendored sprite
 # (packages/ui-bundle/src/img/icons.yml) — an icon name is not free-form.
 nav_modules:
   - module: main
     title: Documentation
     description: Placeholder documentation module — replace with your own content.
-    icon: design/grid-outlined
+    icon: grid-3x3
 
 # Which module's navigation the generated 404 page's side menu shows, read
 # by @inditextech/docouture-antora-extensions. With a single module there is

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

@@ -328,7 +328,7 @@ Add a page, build the site, publish it.
 .xref:main:quickstart.adoc[Quickstart]
 The smallest path to a working result, as concrete steps.
 
-[card,icon="design/grid-outlined"]
+[card,icon="grid-3x3"]
 .xref:main:architecture.adoc[Architecture]
 This one carries a header icon instead of a subheader.
 ====
@@ -469,7 +469,7 @@ diagram source, as literal text, same as the fenced listing shows it above.
 
 ==== Styling
 
-Mermaid diagrams are themed to match the IOP Design System automatically — square
+Mermaid diagrams are themed to match this site automatically — square
 corners, black-on-white (light mode; inverted for dark), body typography — via a
 `%%{init: {...}}%%` directive this extension prepends to the diagram's own source
 before it ever reaches Kroki, not via CSS. Write your own `%%{init...}%%` as the

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

@@ -2,14 +2,15 @@ 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.
+# release-branch trigger) is ALWAYS scoped to that PR's own ephemeral merge
+# ref (`refs/pull/<N>/merge`), by design, even when it targets the release
+# branch 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
@@ -23,18 +24,30 @@ name: docouture-kroki-cache-warm
 # 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.
 #
+# Triggers on push to BOTH the prerelease and release branches,
+# unconditionally (a trunk-based site collapses this to one entry — see
+# TemplateValues.cacheWarmBranchesYaml in copy-template.ts) — this workflow
+# has no reliable way to know at scaffold time which of the two a git-flow
+# repo actually has configured as its GitHub default branch (the one whose
+# cache scope this whole mechanism depends on), so it warms both rather than
+# guessing wrong and silently losing the optimization. Whichever one really
+# is the configured default gets its cache entry written either way; the
+# other branch's push still produces a normal base-branch-scoped cache,
+# benefiting PRs targeting it specifically, so nothing is wasted.
+#
 # 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*']
+    branches: [__DOCOUTURE_CACHE_WARM_BRANCHES__]
 
-# Least-privilege default: this job only checks out `main`, warms the
-# Docker/Kroki image cache and writes it via actions/cache (a separate,
-# token-independent cache API, not repository contents) — it never uses
-# GITHUB_TOKEN itself, so it never needs more than read access. Declared
-# explicitly rather than left to inherit whatever the repository/
-# organization's default token permissions happen to be.
+# Least-privilege default: this job only checks out the release/prerelease
+# branch it happened to run against, warms the Docker/Kroki image cache and
+# writes it via actions/cache (a separate, token-independent cache API, not
+# repository contents) — it never uses GITHUB_TOKEN itself, so it never
+# needs more than read access. Declared explicitly rather than left to
+# inherit whatever the repository/organization's default token permissions
+# happen to be.
 permissions:
   contents: read
 
@@ -75,8 +88,9 @@ jobs:
       - 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
+      # This is whichever branch triggered this run's own real
+      # antora-playbook.yml (this workflow only ever runs on a push to the
+      # prerelease or release branch, 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

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

@@ -1,23 +1,25 @@
 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.
+# Rebuilds and republishes the prerelease (prerelease-branch) docs
+# automatically on every ordinary push to the prerelease branch 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:
+# A plain `on: push: branches: [<prerelease branch>*]` 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.
+#      descriptor" step pushes straight to the release branch directly (see
+#      that workflow's own comment on that step) — a bot commit that is not
+#      new docs content, and (trunk-based only, where prerelease and release
+#      are the same branch) 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
@@ -29,10 +31,13 @@ name: docouture-publish-prerelease
 #      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.
+#      duplicate it. (Only reachable at all in a trunk-based site, where the
+#      prerelease and release branches are the same one — under git-flow
+#      they're different branches, so a docs/release-labeled PR never
+#      targets the prerelease branch this workflow watches.)
 on:
   push:
-    branches: ['main*']
+    branches: ['__DOCOUTURE_PRERELEASE_BRANCH__*']
 
 permissions:
   contents: read
@@ -89,9 +94,9 @@ jobs:
       # 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.
+      # A direct push to the prerelease branch with no associated pull
+      # request (e.g. an admin pushing straight to it) simply resolves no
+      # labels and is never skipped here.
       - name: Check for docs/release label
         id: check
         run: |

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

@@ -29,7 +29,7 @@ name: docouture-publish
 # than a coincidence of two workflows independently reacting to the same
 # git push. `workflow_call` is what makes that direct call possible.
 # `workflow_dispatch` is kept alongside it for a manual rebuild+republish
-# of whatever is currently on `main`, without cutting a new release.
+# of whatever is currently checked out, without cutting a new release.
 on:
   workflow_call: {}
   workflow_dispatch: {}

package/build/templates/workflows/docouture-release-preview.yml

@@ -21,7 +21,7 @@ name: docouture-release-preview
 on:
   pull_request:
     types: [labeled, synchronize, ready_for_review, opened]
-    branches: ['main*']
+    branches: ['__DOCOUTURE_RELEASE_BRANCH__*']
 
 concurrency:
   group: release-preview
@@ -66,7 +66,8 @@ jobs:
 
       # Same signal docouture-release.yml's own "Detect mode" step reads:
       # antora-playbook.yml's content.sources[] tags, not docs/antora.yml
-      # (identical on main for both modes, so it carries no mode signal).
+      # (identical on the release branch for both modes, so it carries no
+      # mode signal).
       - name: Detect mode
         id: detect
         run: |