@inditextech/docouture-cli 0.1.0-SNAPSHOT.40.1

package/build/lib/doctor-checks.js

@@ -0,0 +1,240 @@
+'use strict';
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+function parseMajor(value) {
+    const match = /(\d+)/.exec(value);
+    return match ? Number(match[1]) : null;
+}
+/**
+ * Compares the Node version actually running `docouture` (the same one `npm
+ * run build`/`dev` will use) against the site's own `engines.node` — a
+ * range like `>=24.0.0`. Only the major version is compared: this package
+ * has no semver dependency (see antora-yml.ts's own comment on a similar
+ * tradeoff) and a major-version floor is what `engines.node` communicates
+ * in practice.
+ */
+export function checkNodeVersion(engineRange, actualVersion) {
+    const label = 'node version';
+    if (!engineRange) {
+        return { ok: true, label, message: `${actualVersion} (no engines.node requirement declared)` };
+    }
+    const wantMajor = parseMajor(engineRange);
+    const haveMajor = parseMajor(actualVersion);
+    if (wantMajor === null || haveMajor === null) {
+        return { ok: true, label, message: `${actualVersion} (could not parse '${engineRange}', skipping)` };
+    }
+    if (haveMajor >= wantMajor) {
+        return { ok: true, label, message: `${actualVersion} satisfies ${engineRange}` };
+    }
+    return {
+        ok: false,
+        label,
+        message: `${actualVersion} does not satisfy ${engineRange}`,
+        detail: `install Node ${wantMajor} or newer — this is what 'npm run build'/'docouture dev' will actually run under`,
+    };
+}
+/**
+ * The four names the docs-site-package skill documents as having to agree,
+ * or a site builds to zero pages, or dies on "start page not found" — see
+ * SKILL.md's "The four names that must agree" table. Returns one result per
+ * pair so a failure names exactly which two values drifted, not just that
+ * something, somewhere, did.
+ */
+export function checkNamesAgree(input) {
+    const results = [];
+    if (input.antoraYmlName && input.startPageComponent) {
+        results.push(input.antoraYmlName === input.startPageComponent
+            ? { ok: true, label: 'component name', message: `'${input.antoraYmlName}' matches site.start_page` }
+            : {
+                ok: false,
+                label: 'component name',
+                message: `docs/antora.yml name '${input.antoraYmlName}' != site.start_page component '${input.startPageComponent}'`,
+                detail: "site.start_page must be '<name>::index.adoc' using docs/antora.yml's own name",
+            });
+    }
+    if (input.startPath && input.descriptorPath) {
+        results.push(input.startPath === input.descriptorPath
+            ? {
+                ok: true,
+                label: 'content path',
+                message: `start_path '${input.startPath}' matches docs/antora.yml's location`,
+            }
+            : {
+                ok: false,
+                label: 'content path',
+                message: `playbook start_path '${input.startPath}' != actual docs/antora.yml location '${input.descriptorPath}' (both repo-root relative)`,
+                detail: 'content.sources[0].start_path must be the repository-root-relative directory that directly contains antora.yml',
+            });
+    }
+    if (input.packageName && input.antoraYmlName) {
+        if (input.antoraYmlName === 'ROOT') {
+            // `ROOT` is Antora's own reserved component name (dropped from every
+            // published URL — see how-antora-builds-urls's "Component segment"),
+            // set by `docouture new` when the "extra URL path segment" question/
+            // `--url-segment` flag is declined (the default) — see new.ts's own
+            // comment on TemplateValues.componentName. It is never derived from
+            // package.json's name, so the two are expected to differ here; only
+            // a real, chosen component name must still match package.json's own
+            // name, which is what the else branch below still enforces.
+            results.push({
+                ok: true,
+                label: 'package name',
+                message: `docs/antora.yml name is 'ROOT' (no URL segment) — package.json name '${input.packageName}' is independent`,
+            });
+        }
+        else {
+            results.push(input.packageName === input.antoraYmlName
+                ? {
+                    ok: true,
+                    label: 'package name',
+                    message: `package.json name '${input.packageName}' matches component name`,
+                }
+                : {
+                    ok: false,
+                    label: 'package name',
+                    message: `package.json name '${input.packageName}' != docs/antora.yml name '${input.antoraYmlName}'`,
+                    detail: 'docouture new sets both from the same value — if one was renamed by hand, rename the other to match',
+                });
+        }
+    }
+    return results;
+}
+/**
+ * Antora reads content from git — a repository with no commits resolves the
+ * content source to nothing and the site builds with zero pages, reported
+ * only as "Start page specified for site not found". Mirrors `just doctor`'s
+ * own check in the monorepo justfile.
+ */
+export function checkGitHasCommit(dir) {
+    const label = 'git history';
+    return new Promise((resolvePromise) => {
+        execFile('git', ['rev-parse', 'HEAD'], { cwd: dir }, (err) => {
+            resolvePromise(err
+                ? {
+                    ok: false,
+                    label,
+                    message: 'repository has no commits',
+                    detail: 'Antora reads content from git; with no commits the content source resolves to nothing and the site builds with zero pages — make an initial commit',
+                }
+                : { ok: true, label, message: 'repository has at least one commit' });
+        });
+    });
+}
+/**
+ * Confirms the two things a build actually needs are installed locally —
+ * `npm install` was run, in other words — rather than letting Antora's own
+ * `MODULE_NOT_FOUND` be the first sign of it.
+ */
+export function checkAntoraAvailable(siteRoot) {
+    const label = 'antora CLI';
+    const bin = join(siteRoot, 'node_modules', '.bin', 'antora');
+    const pkg = join(siteRoot, 'node_modules', 'antora');
+    if (existsSync(bin) && existsSync(pkg)) {
+        return { ok: true, label, message: 'antora is installed in node_modules' };
+    }
+    return {
+        ok: false,
+        label,
+        message: 'antora is not installed',
+        detail: "run 'npm install' in the site directory",
+    };
+}
+// Repo-root-relative paths `docouture new` scaffolds AGENTS.md/the skill
+// directories under — see new.ts's own AGENT_SUPPORT_PATHS, which this
+// mirrors. Kept as a separate literal here rather than imported: doctor-
+// checks.ts is a plain library module with fixture-driven unit tests (see
+// its own spec) and importing from commands/new.ts would pull the wizard
+// (@inquirer/prompts) into that dependency graph for no reason.
+const AGENT_SUPPORT_CHECK_PATHS = [
+    { path: 'AGENTS.md', label: 'AGENTS.md' },
+    { path: join('.opencode', 'skills', 'documenting-your-repo'), label: '.opencode/skills/documenting-your-repo' },
+    { path: join('.opencode', 'skills', 'writing-docs-pages'), label: '.opencode/skills/writing-docs-pages' },
+    { path: join('.opencode', 'skills', 'docs-internals'), label: '.opencode/skills/docs-internals' },
+    { path: join('.claude', 'skills', 'documenting-your-repo'), label: '.claude/skills/documenting-your-repo' },
+    { path: join('.claude', 'skills', 'writing-docs-pages'), label: '.claude/skills/writing-docs-pages' },
+    { path: join('.claude', 'skills', 'docs-internals'), label: '.claude/skills/docs-internals' },
+];
+/**
+ * Whether AGENTS.md and the two platform-mirrored skill directories `docouture
+ * new` scaffolds are still present at the repository root — advisory only,
+ * this is presence, not a content/drift diff (a site legitimately edits its
+ * own skills after scaffolding), so `commands/doctor.ts` reports these
+ * without folding them into the overall exit code the way the checks above
+ * do. `docs-versioning` is intentionally not checked here: it exists only
+ * under `--mode versioned`, and doctor has no reliable, cheap way to tell
+ * which mode a site is on from this function alone (see
+ * `commands/doctor.ts`'s own mode-detection comment, which reads the
+ * playbook — a concern this function deliberately stays out of).
+ */
+/** The label `docouture-release.yml`'s `pull_request.closed` trigger requires — see that workflow's own `if:` condition. */
+const RELEASE_LABEL = 'docs/release';
+/**
+ * Whether the `docs/release` GitHub label exists on this repository —
+ * best-effort, via the `gh` CLI, since there is no other way to ask GitHub
+ * this from a local checkout. `docouture new` never creates this label (GitHub
+ * does not create labels referenced by a workflow's `if:` condition on its
+ * own, and scaffolding is not a GitHub API call), so a repository fresh out
+ * of `docouture new` is missing it until someone runs `gh label create
+ * docs/release` — see main's own prerequisites.adoc, which covers this
+ * alongside the repository-public/GitHub-Pages-enablement steps a fresh
+ * site also needs. Without it, `docouture-release.yml`'s automatic
+ * merge-triggers-a-release path is a silent no-op; only its
+ * `workflow_dispatch` path still works.
+ *
+ * Advisory only, same as checkAgentFilesPresent above: `gh` may not be
+ * installed, not authenticated, or this may not be a GitHub-hosted
+ * repository at all, none of which this function treats as a real failure —
+ * only an actual label list that is missing the label is reported as
+ * `ok: false`.
+ */
+export function checkReleaseLabelExists(repoRoot) {
+    const label = 'docs/release label';
+    return new Promise((resolvePromise) => {
+        execFile('gh', ['label', 'list', '--json', 'name'], { cwd: repoRoot }, (err, stdout) => {
+            if (err) {
+                resolvePromise({
+                    ok: true,
+                    label,
+                    message: 'could not check (gh CLI unavailable, unauthenticated, or not a GitHub repo) — skipping',
+                });
+                return;
+            }
+            let names;
+            try {
+                const parsed = JSON.parse(stdout);
+                names = parsed.map((entry) => entry.name);
+            }
+            catch {
+                resolvePromise({ ok: true, label, message: "could not parse 'gh label list' output — skipping" });
+                return;
+            }
+            if (names.includes(RELEASE_LABEL)) {
+                resolvePromise({ ok: true, label, message: `'${RELEASE_LABEL}' exists` });
+                return;
+            }
+            resolvePromise({
+                ok: false,
+                label,
+                message: `'${RELEASE_LABEL}' does not exist`,
+                detail: "docouture-release.yml's merge-triggers-a-release path is a no-op without it — run " +
+                    `'gh label create ${RELEASE_LABEL}', or use workflow_dispatch instead`,
+            });
+        });
+    });
+}
+export function checkAgentFilesPresent(repoRoot) {
+    return AGENT_SUPPORT_CHECK_PATHS.map(({ path: relativePath, label }) => {
+        const absolutePath = join(repoRoot, relativePath);
+        const present = existsSync(absolutePath);
+        return present
+            ? { ok: true, label, message: 'present' }
+            : {
+                ok: false,
+                label,
+                message: 'missing',
+                detail: "run 'docouture upgrade' in this repository to regenerate it, or restore it from version control",
+            };
+    });
+}
+//# sourceMappingURL=doctor-checks.js.map

package/build/lib/global-flags.js

@@ -0,0 +1,31 @@
+'use strict';
+/**
+ * Recognises the three global flags (--json, --verbose, --no-color/--color)
+ * anywhere in argv — before or after the command name, so both
+ * `docouture --verbose dev` and `docouture dev --verbose` work — strips them out,
+ * and returns what's left for command dispatch. Kept separate from
+ * lib/args.ts's per-command parser: these are process-wide concerns (see
+ * lib/cli-context.ts), never a value a specific command's own flags need to
+ * see, and separate from bin.ts itself so it's testable without triggering
+ * bin.ts's own top-level `main()` call.
+ */
+export function extractGlobalFlags(argv) {
+    const rest = [];
+    let json = false;
+    let verbose = false;
+    let noColor = false;
+    for (const arg of argv) {
+        if (arg === '--json')
+            json = true;
+        else if (arg === '--verbose')
+            verbose = true;
+        else if (arg === '--no-color')
+            noColor = true;
+        else if (arg === '--color')
+            noColor = false;
+        else
+            rest.push(arg);
+    }
+    return { json, verbose, noColor, rest };
+}
+//# sourceMappingURL=global-flags.js.map

package/build/lib/kroki-compose.js

@@ -0,0 +1,54 @@
+'use strict';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { exists } from './copy-template.js';
+// Shared by `docouture eject kroki` and `docouture teardown kroki` — GH-44. Both
+// need to locate the `docker compose` file @inditextech/docouture-antora-
+// extensions' `kroki-prewarm.js`/`kroki-docker.js` use to run Kroki; kept in
+// one place so the two commands can never disagree about where that file is.
+export const PACKAGE_NAME = '@inditextech/docouture-antora-extensions';
+export const RESOURCE = 'resources/kroki-compose.yml';
+export const OVERRIDE_FILENAME = 'kroki-compose.yml';
+/**
+ * The package's own bundled default — what `docouture eject kroki` copies out,
+ * regardless of whether a site has already ejected/customized one of its
+ * own. Resolved from the SITE's own installed copy of the package (via
+ * `createRequire` against its `package.json`, exactly like `publish.ts`'s
+ * `loadDriver` resolves a publish driver), not from any copy this CLI
+ * itself might depend on — this CLI has no dependency on
+ * @inditextech/docouture-antora-extensions at all, since a plain `docouture` install
+ * has no reason to carry every package a scaffolded site might use.
+ *
+ * @param {string} packageJsonFile - the SITE's `package.json` (`docs/package.json`).
+ * @returns {string} an absolute path to the bundled compose file.
+ * @throws if the package (or this resource within it) cannot be resolved —
+ *   not installed, or an old version predating this feature.
+ */
+export function resolveBundledComposeFile(packageJsonFile) {
+    return createRequire(packageJsonFile).resolve(`${PACKAGE_NAME}/${RESOURCE}`);
+}
+/**
+ * Whichever compose file a build actually used — `kroki-docker.js`'s own
+ * resolution order, reproduced here: an ejected override at the site root
+ * first, the bundled default otherwise. Used by `docouture teardown kroki`,
+ * which has to target the file that's actually running, not necessarily the
+ * bundled one.
+ *
+ * @param {string} siteRoot - `docs/`, the directory containing `antora-playbook.yml`
+ *   (== `playbook.dir` on the Antora side).
+ * @returns {Promise<string | null>} the resolved path, or `null` if neither
+ *   an override nor a resolvable bundled default exists.
+ */
+export async function resolveEffectiveComposeFile(siteRoot) {
+    const override = join(siteRoot, OVERRIDE_FILENAME);
+    if (await exists(override))
+        return override;
+    const packageJsonFile = join(siteRoot, 'package.json');
+    try {
+        return resolveBundledComposeFile(packageJsonFile);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=kroki-compose.js.map

package/build/lib/playbook-yml.js

@@ -0,0 +1,90 @@
+'use strict';
+// Regex-based reader for the handful of `antora-playbook.yml` fields `docouture
+// dev` and `docouture doctor` need — deliberately not a YAML parser, matching
+// the style of antora-yml.ts (this package) and scripts/dev.mjs's own
+// readSiteBasePath (the monorepo dev server this reasoning was lifted from).
+// Every value here is only ever read, never rewritten, so a full parse/dump
+// round trip buys nothing and would cost the file's comments.
+//
+// Values live at different nesting depths — `site.start_page` is a direct
+// child of a top-level key, `content.sources[0].start_path` is a field on
+// the first item of a list nested under one — but both are found the same
+// way: narrow to the top-level key's own line range first (stopping at the
+// next top-level key, so a same-named field belonging to a different block
+// is never picked up by accident), then take the first indented line
+// matching the field, whatever its exact depth.
+function topLevelBlock(content, key) {
+    const lines = content.split('\n');
+    const out = [];
+    let inBlock = false;
+    for (const line of lines) {
+        if (/^\s*(?:#.*)?$/.test(line)) {
+            if (inBlock)
+                out.push(line);
+            continue;
+        }
+        if (/^\S/.test(line)) {
+            if (inBlock)
+                break;
+            inBlock = new RegExp(`^${key}:`).test(line);
+            continue;
+        }
+        if (inBlock)
+            out.push(line);
+    }
+    return out;
+}
+function firstField(lines, key) {
+    // The optional `-\s*` accounts for a YAML list item's first field, e.g.
+    // `content.sources[0].url` is written `    - url: ..` — every other field
+    // on that same item (start_path, branches, ...) is indented the same but
+    // without the dash, which the `?` also covers.
+    const re = new RegExp(`^\\s*(?:-\\s*)?${key}:\\s*(.+?)\\s*$`);
+    for (const line of lines) {
+        const match = re.exec(line);
+        if (match?.[1])
+            return match[1].replace(/^['"]|['"]$/g, '');
+    }
+    return null;
+}
+/** `site.url` — unset while developing locally, so this is commonly null. */
+export function readSiteUrl(content) {
+    return firstField(topLevelBlock(content, 'site'), 'url');
+}
+/** `site.start_page`, e.g. `my-site::index.adoc`. */
+export function readStartPage(content) {
+    return firstField(topLevelBlock(content, 'site'), 'start_page');
+}
+/** The component-name prefix of `site.start_page`, before its `::`. */
+export function readStartPageComponent(content) {
+    const startPage = readStartPage(content);
+    if (!startPage)
+        return null;
+    const separator = startPage.indexOf('::');
+    return separator === -1 ? null : startPage.slice(0, separator);
+}
+/**
+ * `content.sources[0].start_path` — repository-root relative directory
+ * holding `docs/antora.yml`. Only the first source is read: every shape
+ * `docouture new` generates has exactly one, and doctor only needs to catch the
+ * common single-source misconfiguration, not aggregate every source in a
+ * hand-authored multi-source playbook.
+ */
+export function readStartPath(content) {
+    return firstField(topLevelBlock(content, 'content'), 'start_path');
+}
+/** `content.sources[0].url` — see this package's own comment on why it must
+ * be `..`, not `.`, when the playbook does not sit at the repository root. */
+export function readSourceUrl(content) {
+    return firstField(topLevelBlock(content, 'content'), 'url');
+}
+/**
+ * `output.dir` — where `antora build` writes the built site. Unset in every
+ * playbook `docouture new` scaffolds (Antora's own default, `build/site`,
+ * applies), so `docouture publish` falls back to that same default rather than
+ * treating a missing value as an error.
+ */
+export function readOutputDir(content) {
+    return firstField(topLevelBlock(content, 'output'), 'dir');
+}
+//# sourceMappingURL=playbook-yml.js.map

package/build/lib/repo-root.js

@@ -0,0 +1,21 @@
+'use strict';
+import { execFile } from 'node:child_process';
+/**
+ * Resolves the git repository root containing `startDir` — so `docouture dev`,
+ * `docouture build` and `docouture doctor` work from anywhere inside a scaffolded
+ * repository (its root, inside `docs/`, in a nested page directory, ...),
+ * not only when `--dir`/cwd happens to already be the repository root.
+ *
+ * Returns `startDir` itself when it is not inside a git repository at all —
+ * callers then fail with their own "no site found at ..." message instead of
+ * a git error, which is the more useful failure for someone who simply
+ * hasn't run `docouture new` yet.
+ */
+export function findRepoRoot(startDir) {
+    return new Promise((resolvePromise) => {
+        execFile('git', ['rev-parse', '--show-toplevel'], { cwd: startDir }, (err, stdout) => {
+            resolvePromise(err ? startDir : stdout.trim());
+        });
+    });
+}
+//# sourceMappingURL=repo-root.js.map

package/build/lib/run-script.js

@@ -0,0 +1,50 @@
+'use strict';
+import { spawn } from 'node:child_process';
+import { debugLog } from './debug-log.js';
+/**
+ * Runs `npm run <script>` in `cwd` with inherited stdio, resolving the exit
+ * code. Used by `docouture build` — a genuine thin wrapper, unlike `docouture dev`,
+ * which owns its server logic directly (see lib/dev-server.ts) rather than
+ * shelling out to a copy of it.
+ */
+export function runNpmScript(script, options) {
+    return new Promise((resolvePromise, reject) => {
+        const args = ['run', script, ...(options.args?.length ? ['--', ...options.args] : [])];
+        // On Windows, npm is installed as `npm.cmd` — a bare `spawn('npm', ...)`
+        // without `shell: true` resolves nothing and throws ENOENT. Using the
+        // platform-specific binary name avoids that without opting into a full
+        // shell (and its own quoting/escaping rules) just to launch one command.
+        const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+        debugLog(`spawning: ${npmCmd} ${args.join(' ')} (cwd=${options.cwd})`);
+        const child = spawn(npmCmd, args, {
+            cwd: options.cwd,
+            stdio: 'inherit',
+            env: options.env ? { ...process.env, ...options.env } : process.env,
+        });
+        // Forward SIGINT/SIGTERM to the child so `docouture build` sent a signal
+        // directly (not just a terminal Ctrl-C, which already reaches the whole
+        // foreground process group on its own) still gives npm/antora a chance
+        // to shut down cleanly instead of being silently orphaned.
+        const onSigint = () => {
+            child.kill('SIGINT');
+        };
+        const onSigterm = () => {
+            child.kill('SIGTERM');
+        };
+        process.once('SIGINT', onSigint);
+        process.once('SIGTERM', onSigterm);
+        function cleanup() {
+            process.removeListener('SIGINT', onSigint);
+            process.removeListener('SIGTERM', onSigterm);
+        }
+        child.on('close', (code) => {
+            cleanup();
+            resolvePromise(code ?? 1);
+        });
+        child.on('error', (err) => {
+            cleanup();
+            reject(err);
+        });
+    });
+}
+//# sourceMappingURL=run-script.js.map

package/build/lib/theme.js

@@ -0,0 +1,51 @@
+'use strict';
+import { getContext } from './cli-context.js';
+// A small themed colour layer, replacing both bin.ts/new.ts's direct use of
+// picocolors and doctor.ts's own hand-rolled raw ANSI escapes (see their old
+// comments) with one place that: (a) has a single, consistent set of
+// semantic roles (success/error/warn/info/muted/bold) instead of each file
+// picking its own raw colour, and (b) decides whether colour is on fresh on
+// every single call rather than once at import time.
+//
+// That second point is why this doesn't just re-export picocolors: picocolors
+// (like most colour libraries) computes `isColorSupported` once, when the
+// module is first imported — which happens before bin.ts has even parsed
+// --no-color off argv. Re-checking `getContext().noColor` on every call
+// means --no-color (and NO_COLOR/FORCE_COLOR, which can't change at runtime
+// either way) are honoured for every single line printed, not just the ones
+// printed by a module that happened to import picocolors after the flag was
+// known.
+const CODES = {
+    reset: '\u001b[0m',
+    bold: '\u001b[1m',
+    dim: '\u001b[2m',
+    red: '\u001b[31m',
+    green: '\u001b[32m',
+    yellow: '\u001b[33m',
+    cyan: '\u001b[36m',
+};
+function colourEnabled() {
+    if (getContext().noColor)
+        return false;
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return process.stdout.isTTY === true;
+}
+function wrap(code) {
+    return (text) => (colourEnabled() ? `${code}${text}${CODES.reset}` : text);
+}
+export const theme = {
+    bold: wrap(CODES.bold),
+    dim: wrap(CODES.dim),
+    success: wrap(CODES.green),
+    error: wrap(CODES.red),
+    warn: wrap(CODES.yellow),
+    info: wrap(CODES.cyan),
+};
+/** Exposed for callers (doctor.ts) that need a plain yes/no rather than a wrapped string. */
+export function isColourEnabled() {
+    return colourEnabled();
+}
+//# sourceMappingURL=theme.js.map

package/build/templates/agent-support/.claude/skills/docs-internals/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: docs-internals
+description: "How this Antora documentation site is put together: the playbook, the docs/antora.yml component descriptor, the four names that must agree, mono-module vs. multi-module layout, and the home-page vs. content-page patterns. USE WHEN adding a page or module, renaming the site/component, choosing between a single-module and multi-module layout, building a landing/home page, or diagnosing a site that builds with zero pages or fails with 'start page not found'. EXAMPLES: 'add a new module', 'rename this docs site', 'build a marketing home page', 'the site builds but has no pages', 'start page not found', 'should this be one module or several'."
+---
+
+# Site structure
+
+This site was scaffolded by `docouture new` (`@inditextech/docouture-cli`). This skill covers the
+pieces that make it hang together — where each name is set, how a page becomes reachable,
+and the two page patterns (home vs. content) worth copying rather than reinventing.
+
+- `reference/naming.md` — the four names that must agree, and how to fix them when they
+  don't (`docouture doctor` checks this automatically).
+- `reference/page-patterns.md` — the home-page block structure and the recurring
+  content-page shapes, plus mono-module vs. multi-module layout.
+- `reference/antora-extensions.md` — what `@inditextech/docouture-antora-extensions` (a
+  different kind of extension from the authoring blocks in `writing-docs-pages`) provides:
+  the module switcher, site footer, search index and `llms.txt` generation.
+
+For AsciiDoc authoring itself — xrefs, admonitions, code blocks, this site's custom
+blocks — see the `writing-docs-pages` skill.
+
+## The moving pieces
+
+```
+docs/
+  antora-playbook.yml          site title, content source, UI bundle, asciidoc/antora extensions
+  antora-playbook.local.yml    same shape, but content.sources[] is just `branches: HEAD` —
+                                 what `docouture dev` and PR verification build against, since a
+                                 PR/feature-branch checkout doesn't have `main` or a release tag
+  package.json                 name, devDependencies (docouture-cli, ui-bundle, the two extension
+                                 packages), the `build`/`dev` scripts
+  src/
+    antora.yml                 component descriptor: name, title, version, nav
+    modules/<module>/nav.adoc  navigation tree, one per module
+```
+
+The whole starter template — `package.json`, both playbooks, the nested `src/` — was
+copied under this repository's own `docs/`, so `antora-playbook.yml` lives at
+`<repo-root>/docs/antora-playbook.yml` and the component descriptor ends up one level
+further down, at `docs/src/antora.yml`. That's why `antora-playbook.yml`'s
+`content.sources[0]` reads `url: ..` (this repo's root, one level up from `docs/`) and
+`start_path: docs/src`.
+
+## Versioning
+
+`docs/antora.yml`'s `version`/`prerelease` fields are identical on `main` regardless of
+which versioning mode this site uses (`version: prerelease`, `prerelease: true`) — what
+differs is only which git refs `antora-playbook.yml`'s `content.sources[0]` aggregates
+from (`tags: ['stable']` vs. `tags: ['v*']`). If this site was scaffolded with
+`--mode versioned`, see the `docs-versioning` skill for cutting a release; a
+**standalone**-mode site (the default) has no separate skill for this — `docouture doctor`
+and the `docouture-release.yml` workflow are all that's needed.

package/build/templates/agent-support/.claude/skills/docs-internals/reference/antora-extensions.md

@@ -0,0 +1,54 @@
+# @inditextech/docouture-antora-extensions
+
+Registered under `antora-playbook.yml`'s **`antora.extensions`** key — a different key,
+and a different kind of extension, from `writing-docs-pages`' `asciidoc.extensions`
+(`@inditextech/docouture-asciidoc-extensions`). This one hooks Antora's own site-generation
+pipeline rather than the AsciiDoc processor; listing either package under the other's key
+makes Antora log a warning and skip it.
+
+One package require registers five sub-extensions together — they can't be enabled
+individually:
+
+| sub-extension         | reads                                                             | does                                                                                                                                                                                                                                                                                                   |
+| --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| module switcher       | `nav_modules:` in `docs/src/antora.yml`                           | stamps each nav tree with its module/title/description/icon, so the UI can show one module's nav at a time with a switcher — see `reference/page-patterns.md`'s "Mono-module vs. multi-module" section. A no-op until `nav_modules:` is authored                                                       |
+| site footer           | `footer:` in `docs/src/antora.yml`                                | resolves a structured `footer: groups: […]` list of link groups and attaches it to the component version, for the UI's footer partial. A no-op until `footer:` is authored                                                                                                                             |
+| search index          | (nothing authored)                                                | builds a full-text search index at build time, published per component version. **This is what the UI bundle's own search dialog reads** — without this extension registered, the search UI renders but has nothing to search                                                                          |
+| `llms.txt` generation | `llms:` in `docs/src/antora.yml` (optional `summary`/`exclude`)   | generates `llms.txt` and `llms-full.txt` at the site root — a Markdown index and full dump, meant for LLM ingestion (see `https://llmstxt.org`), so an AI agent (or another tool) can read the site without scraping rendered HTML                                                                     |
+| Shiki prewarm         | `asciidoc.attributes.source-highlighter` in `antora-playbook.yml` | pre-builds the Shiki syntax highlighter once, up front. Only useful if `source-highlighter: shiki` is actually set — this site keeps Antora's default `highlight.js` instead, so this sub-extension runs unconditionally but has nothing to prewarm for. Harmless, just a small unused build-time cost |
+
+## Authoring the optional keys
+
+All three authored keys (`nav_modules`, `footer`, `llms`) live in `docs/src/antora.yml`,
+not the playbook — `site.keys` there is declared as a flat primitive map and can't carry
+a nested list, so the component descriptor is the one place a nested structure can be
+authored:
+
+```yaml
+# docs/src/antora.yml
+nav_modules:
+  - module: framework
+    title: Framework
+    description: One-line description.
+    icon: design/grid-outlined
+
+footer:
+  groups:
+    - title: Resources
+      links:
+        - text: Home
+          url: ROOT:index.adoc
+        - text: Repository
+          url: https://github.com/example/example
+
+llms:
+  summary: >-
+    One or two sentences describing what this site documents — becomes the
+    blockquote under the site title in the generated llms.txt.
+  # exclude:
+  #   - module:some-internal-page.adoc
+```
+
+`url`/`links[].url` values are either a page ID (the same string `xref:...[]` accepts) or
+a literal URL — a page ID that resolves to nothing is dropped with a warning rather than
+rendered dead.