@inditextech/docouture-cli 0.1.0-SNAPSHOT.46.1 → 0.1.0-SNAPSHOT.52.1

package/build/commands/new.js

@@ -45,21 +45,6 @@ const WORKFLOW_NAMES = [
     'docouture-pr-verify.yml',
     'docouture-kroki-cache-warm.yml',
 ];
-// Repo-root-relative paths `templates/agent-support/` lands under (see
-// new.ts's own copyTemplate call below) — kept as a literal list, same
-// reasoning as WORKFLOW_NAMES above, so the pre-flight conflict check can
-// name exactly what would be overwritten. `docs-versioning` is deliberately
-// absent here: it is scaffolded only under `--mode versioned` (see the
-// `.versioned`-marker copy further down), so an existing standalone-mode
-// site with no such directory yet is never blocked by this check on it.
-const AGENT_SUPPORT_PATHS = [
-    join('.opencode', 'skills', 'documenting-your-repo'),
-    join('.opencode', 'skills', 'writing-docs-pages'),
-    join('.opencode', 'skills', 'docs-internals'),
-    join('.claude', 'skills', 'documenting-your-repo'),
-    join('.claude', 'skills', 'writing-docs-pages'),
-    join('.claude', 'skills', 'docs-internals'),
-];
 function titleCase(name) {
     return name
         .split('-')
@@ -337,24 +322,18 @@ export async function runNew(argv, io = defaultIO()) {
             existingWorkflows.push(join('.github', 'workflows', workflowName));
         }
     }
-    const existingSkills = [];
-    for (const relativePath of AGENT_SUPPORT_PATHS) {
-        const absolutePath = join(target, relativePath);
-        if ((await exists(absolutePath)) && !(await isEmptyOrMissing(absolutePath)))
-            existingSkills.push(relativePath);
-    }
-    // AGENTS.md is never an all-or-nothing conflict the way a workflow file or
-    // a skill directory is: a foreign/human-written file (no docouture-managed
-    // block yet — see lib/agents-md.ts) is always safe to append docouture' own
-    // section to without asking. Only a file that already HAS a managed
-    // block counts as something this run would actually overwrite.
+    // AGENTS.md is never an all-or-nothing conflict the way a workflow file
+    // is: a foreign/human-written file (no docouture-managed block yet — see
+    // lib/agents-md.ts) is always safe to append docouture' own section to
+    // without asking. Only a file that already HAS a managed block counts as
+    // something this run would actually overwrite.
     let existingAgentsMd;
     let agentsMdConflict = false;
     if (await exists(agentsMdFile)) {
         existingAgentsMd = await readFile(agentsMdFile, 'utf8');
         agentsMdConflict = hasManagedSection(existingAgentsMd);
     }
-    const conflicts = [...existingWorkflows, ...existingSkills, ...(agentsMdConflict ? [AGENTS_MD_FILENAME] : [])];
+    const conflicts = [...existingWorkflows, ...(agentsMdConflict ? [AGENTS_MD_FILENAME] : [])];
     if (conflicts.length > 0) {
         if (skipWizard) {
             // Non-interactive (--yes, or no TTY) — nobody to confirm with, so this
@@ -424,23 +403,19 @@ export async function runNew(argv, io = defaultIO()) {
     // workflows anywhere else.
     await copyTemplate(starterDir, docsDir, values);
     await copyTemplate(workflowsTemplateDir, workflowsDir, values);
-    // AGENTS.md and both platforms' skill directories also land at the true
-    // repo root, same as workflows — an agent reads them from there, not from
-    // inside docs/. copyTemplate's own VERSIONED_MARKER/SKIP_FILENAMES skips
-    // (see copy-template.ts) leave docs-versioning.versioned and AGENTS.md
-    // untouched here; docs-versioning is copied under its real name below,
-    // only in versioned mode, and AGENTS.md is merged separately next — see
-    // lib/agents-md.ts for why it can't go through the generic overwrite walk
-    // every other file here does.
-    await copyTemplate(agentSupportDir, target, values);
+    // AGENTS.md lands at the true repo root, same as workflows — an agent
+    // reads it from there, not from inside docs/. Skill directories are
+    // deliberately not scaffolded here at all: docouture new only opinionates
+    // on the starter site and its GitHub workflows — skills are a separate,
+    // self-serve install via `npx skills add InditexTech/docouture`, kept
+    // decoupled from scaffolding so they can be installed, updated or removed
+    // independently of it (see /skills at this repo's own root).
+    await copyTemplate(workflowsTemplateDir, workflowsDir, values);
     const renderedAgentsMd = await renderTemplateFile(join(agentSupportDir, AGENTS_MD_FILENAME), values);
     await writeFile(agentsMdFile, mergeAgentsMd(existingAgentsMd, renderedAgentsMd), 'utf8');
     if (mode === 'versioned') {
         await writeTemplateFile(join(starterDir, 'antora-playbook.versioned.yml'), join(docsDir, 'antora-playbook.yml'), values);
         await writeTemplateFile(join(starterDir, 'src', 'release-version.versioned'), join(docsDir, '.release-version'), values);
-        for (const platform of ['.opencode', '.claude']) {
-            await copyTemplate(join(agentSupportDir, platform, 'skills', 'docs-versioning.versioned'), join(target, platform, 'skills', 'docs-versioning'), values);
-        }
     }
     printNextSteps({ mode, pm, target, docsDir, workflowsDir, ghPagesUrl: githubPagesUrl(target) });
     return 0;
@@ -465,14 +440,18 @@ function printNextSteps(args) {
     console.log(created(writtenAt(docsDir)));
     console.log(created(writtenAt(workflowsDir)));
     console.log(created(writtenAt(join(target, 'AGENTS.md'))));
-    console.log(created(writtenAt(join(target, '.opencode', 'skills'))));
-    console.log(created(writtenAt(join(target, '.claude', 'skills'))));
     console.log('');
     console.log(theme.bold('Next steps:'));
     console.log('  cd docs');
     console.log(`  ${pm.installCmd}`);
     console.log(`  ${pm.devCmd}`);
     console.log('');
+    console.log(theme.bold('Docs-authoring skills:'));
+    console.log('  npx skills@latest add InditexTech/docouture --all');
+    console.log('  (or --skill <name> for one at a time — installs docouture-getting-started,');
+    console.log('  docouture-documenting-changes, docouture-writing-docs-pages, docouture-docs-internals');
+    console.log('  and, for a versioned-mode site, docouture-docs-versioning)');
+    console.log('');
     if (mode === 'versioned') {
         console.log(theme.bold('Versioning: Versioned (Full History)'));
         console.log('  main is the prerelease channel.');
@@ -486,7 +465,7 @@ function printNextSteps(args) {
         console.log('  (or skip the label/PR entirely: run docouture-release.yml manually via workflow_dispatch');
         console.log('  and type the version)');
         console.log('');
-        console.log('  See the docs-versioning skill (.opencode/skills, .claude/skills) for the full mechanism.');
+        console.log('  See the docouture-docs-versioning skill (npx skills add InditexTech/docouture) for the full mechanism.');
     }
     else {
         console.log(theme.bold('Versioning: Standalone (Stable + Prerelease)'));

package/build/commands/upgrade.js

@@ -119,27 +119,29 @@ export async function runUpgrade(argv) {
     const workflowsDir = join(target, '.github', 'workflows');
     const agentsMdFile = join(target, AGENTS_MD_FILENAME);
     // Unlike `new.ts`, this command's whole purpose is to overwrite what's
-    // already there — workflows and agent skills are meant to be regenerable
-    // from the template on every upgrade, not merged with local edits (there
-    // is no content-hash/diff tracking anywhere in this CLI to tell a stock
-    // file from a user-edited one). `docs/` itself — the starter content a
-    // site has since written its own pages into — is never touched here.
-    // AGENTS.md is the one exception: copyTemplate's own SKIP_FILENAMES skip
-    // (see copy-template.ts) leaves it untouched by the walk above, and it's
-    // merged instead — see lib/agents-md.ts for why a blind overwrite here
-    // would silently destroy the 'Documentation state' table
-    // `documenting-your-repo` maintains outside docouture' own managed section.
+    // already there — workflows are meant to be regenerable from the
+    // template on every upgrade, not merged with local edits (there is no
+    // content-hash/diff tracking anywhere in this CLI to tell a stock file
+    // from a user-edited one). `docs/` itself — the starter content a site
+    // has since written its own pages into — is never touched here. Skills
+    // are never touched here either: `docouture upgrade` only re-syncs the
+    // starter site and its GitHub workflows, same as `docouture new` only
+    // scaffolds them — skills are a separate, self-serve install via
+    // `npx skills add InditexTech/docouture`. AGENTS.md is the one exception:
+    // copyTemplate's own SKIP_FILENAMES skip (see copy-template.ts) leaves it
+    // untouched by the walk above, and it's merged instead — see
+    // lib/agents-md.ts for why a blind overwrite here would silently destroy
+    // the 'Documentation state' table the docouture-documenting-changes skill
+    // maintains outside docouture' own managed section.
     if (dryRun) {
         const plannedWorkflows = await copyTemplate(workflowsTemplateDir, workflowsDir, values, { dryRun: true });
-        const plannedAgentSupport = await copyTemplate(agentSupportDir, target, values, { dryRun: true });
         console.log('would write:');
-        for (const path of [...plannedWorkflows, ...plannedAgentSupport, agentsMdFile]) {
+        for (const path of [...plannedWorkflows, agentsMdFile]) {
             console.log(`  ${relative(target, path)}`);
         }
         return 0;
     }
     await copyTemplate(workflowsTemplateDir, workflowsDir, values);
-    await copyTemplate(agentSupportDir, target, values);
     const existingAgentsMd = (await exists(agentsMdFile)) ? await readFile(agentsMdFile, 'utf8') : undefined;
     const renderedAgentsMd = await renderTemplateFile(join(agentSupportDir, AGENTS_MD_FILENAME), values);
     await writeFile(agentsMdFile, mergeAgentsMd(existingAgentsMd, renderedAgentsMd), 'utf8');
@@ -149,8 +151,6 @@ export async function runUpgrade(argv) {
     // are actually just '.github/workflows', 'AGENTS.md' etc. at the root.
     console.log(`updated ${relative(target, workflowsDir)}`);
     console.log(`updated ${relative(target, agentsMdFile)}`);
-    console.log(`updated ${relative(target, join(target, '.opencode', 'skills'))}`);
-    console.log(`updated ${relative(target, join(target, '.claude', 'skills'))}`);
     return 0;
 }
 //# sourceMappingURL=upgrade.js.map

package/build/lib/agents-md.js

@@ -2,7 +2,7 @@
 // AGENTS.md is the one scaffolded file `docouture new`/`docouture upgrade` never
 // treat as all-or-nothing: unlike a workflow file or a skill directory, a
 // repository may well already have its own AGENTS.md before `docouture new`
-// ever runs, and the `documenting-your-repo` skill edits this file's own
+// ever runs, and the `docouture-documenting-changes` skill edits this file's own
 // '## Documentation state' table over time as a repo's docs grow — content
 // no template regenerates. Rather than clobber the whole file (today's
 // behavior for every other scaffolded file) or refuse outright, docouture' own

package/build/lib/doctor-checks.js

@@ -140,32 +140,22 @@ export function checkAntoraAvailable(siteRoot) {
         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' },
-];
+// Repo-root-relative paths `docouture new` scaffolds 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. Skills are deliberately absent here: the
+// CLI never scaffolds them (see new.ts's own comment) — a user installs
+// them independently via `npx skills add InditexTech/docouture`, which is
+// outside anything `docouture doctor` can or should check for.
+const AGENT_SUPPORT_CHECK_PATHS = [{ path: 'AGENTS.md', label: 'AGENTS.md' }];
 /**
- * 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).
+ * Whether AGENTS.md is still present at the repository root — advisory
+ * only, this is presence, not a content/drift diff (a repository
+ * legitimately edits AGENTS.md's own free-form notes), so
+ * `commands/doctor.ts` reports this without folding it into the overall
+ * exit code the way the checks above do.
  */
 /** The label `docouture-release.yml`'s `pull_request.closed` trigger requires — see that workflow's own `if:` condition. */
 const RELEASE_LABEL = 'docs/release';

package/build/templates/agent-support/AGENTS.md

@@ -16,12 +16,14 @@ docs/
   src/
     antora.yml                 component descriptor: name, title, version, nav
     modules/
-      ROOT/                    the default module
+      ROOT/                    the home page only — no nav.adoc of its own
+      main/                    the default content module — every other page starts here
         nav.adoc               the navigation tree
         pages/*.adoc           one page per file — these become site URLs
 ```
 
-The nesting (`docs/src/...`) is intentional — see the `docs-internals` skill.
+The nesting (`docs/src/...`) is intentional, and so is `ROOT` + `main` both existing from
+the start — see the `docouture-docs-internals` skill (below).
 
 ## Commands
 
@@ -49,23 +51,36 @@ go through the `docouture` CLI.
 
 ## Skills
 
-- **`documenting-your-repo`** — start here: planning what to document, sourcing content
-  from wherever it actually lives (existing docs, README, or the code itself), and the
-  long-term loop that keeps docs in sync as the repo grows. Hands off to the two skills
-  below for mechanics once a decision is made.
-- **`writing-docs-pages`** — authoring AsciiDoc content: the language itself, `xref:`
-  references, `nav.adoc`, admonitions, code blocks, and this site's own custom blocks
-  (`[tabs]`, `[cards]`, `[accordion]`, …).
-- **`docs-internals`** — the playbook, the component descriptor, the four names that must
-  agree, the home-page vs. content-page patterns, and mono-module vs. multi-module sites.
-- **`docs-versioning`** — only present when this site was scaffolded with
+Docs-authoring skills are not scaffolded here — `docouture new`/`docouture upgrade` only
+opinionate on the starter site and its GitHub workflows. Install them yourself, once, with:
+
+```
+npx skills@latest add InditexTech/docouture --all
+```
+
+(or `--skill <name>` for one at a time). This installs:
+
+- **`docouture-getting-started`** — start here on a brand-new site: scaffolding (if not done
+  yet), planning what to document, sourcing content from wherever it actually lives
+  (existing docs, README, or the code itself). Hands off to the two skills below for
+  mechanics once a decision is made.
+- **`docouture-documenting-changes`** — the re-entry point once the site exists: a feature,
+  change, deprecation or fix landed in the repo, and the docs need to catch up. This is
+  the one to reach for day to day, not `docouture-getting-started`.
+- **`docouture-writing-docs-pages`** — authoring AsciiDoc content: the language itself,
+  `xref:` references, `nav.adoc`, admonitions, code blocks, and this site's own custom
+  blocks (`[tabs]`, `[cards]`, `[accordion]`, …).
+- **`docouture-docs-internals`** — the playbook, the component descriptor, the four names
+  that must agree, the home-page vs. content-page patterns, and how a site grows beyond
+  its default `ROOT` + `main` modules.
+- **`docouture-docs-versioning`** — only relevant when this site was scaffolded with
   `--mode versioned`: cutting releases, `docouture version`, and `docs/.release-version`.
 
 <!-- docouture:end -->
 
 ## Documentation state
 
-<!-- maintained by the documenting-your-repo skill — do not hand-edit structure, only content -->
+<!-- maintained by the docouture-documenting-changes skill — do not hand-edit structure, only content -->
 
 | doc page          | derived from          | status |
 | ----------------- | --------------------- | ------ |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inditextech/docouture-cli",
-  "version": "0.1.0-SNAPSHOT.46.1",
+  "version": "0.1.0-SNAPSHOT.52.1",
   "description": "Command-line tool for docouture documentation sites: scaffold a new site and set its Antora version outside the monorepo",
   "repository": {
     "type": "git",

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

@@ -1,53 +0,0 @@
----
-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

@@ -1,54 +0,0 @@
-# @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.

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

@@ -1,41 +0,0 @@
-# The four names that must agree
-
-Four independent files each carry a name that has to match another one, or the site
-builds to zero pages, or fails outright with "start page not found". `docouture doctor` checks
-every pair automatically — run it after any rename.
-
-| name           | set in                                                  | must match                                                                                                                                 |
-| -------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| component name | `docs/src/antora.yml` → `name`                          | the `<component>::` prefix of the playbook's `site.start_page`                                                                             |
-| start page     | `antora-playbook.yml` → `site.start_page`               | a real file under `modules/ROOT/pages/` (or whichever module it names)                                                                     |
-| content path   | `antora-playbook.yml` → `content.sources[0].start_path` | where `docs/src/antora.yml` actually is, repo-root relative — `docs/src` for a site scaffolded as-is                                       |
-| package name   | `docs/package.json` → `name`                            | no hard requirement on its own, but conventionally matches the component name — this is what `docouture new <name>` sets both to initially |
-
-## Why each one matters
-
-- **Component name vs. start page.** `site.start_page: my-site::index.adoc` names a
-  component (`my-site`) and a page (`index.adoc`) inside it. If `docs/src/antora.yml`'s
-  own `name:` says something else, Antora has no component by that name to serve the
-  start page from — the whole site 404s at `/`.
-- **Start page vs. an actual file.** `site.start_page` must point at a page that exists
-  under that component's `pages/` tree (respecting the module, if the reference names
-  one: `my-site:some-module:index.adoc`). A typo here is "start page not found" at build
-  time, not a runtime 404.
-- **Content path vs. where the descriptor really is.** `content.sources[0].start_path` is
-  repo-root relative. Move `docs/src/antora.yml` (or rename the outer `docs/` directory)
-  without updating `start_path` and Antora aggregates zero pages — no error, just an
-  empty site, because the path it looked in wasn't a component root at all.
-- **Package name.** Not load-bearing for Antora itself, but drift here is a strong signal
-  something else drifted too (a manual rename that missed a file) — `docouture doctor` flags
-  it for that reason.
-
-## Fixing a drift
-
-Renaming the site after scaffolding means touching three of the four in lockstep:
-
-1. `docs/src/antora.yml` → `name:`
-2. `antora-playbook.yml` → `site.start_page`'s component prefix
-3. `docs/package.json` → `name`
-
-`content.sources[0].start_path` only needs touching if the _directory_ moved, not if just
-the component's `name:` changed.