@inditextech/docouture-cli 0.1.0-SNAPSHOT.40.1

package/build/templates/agent-support/.opencode/skills/docs-internals/reference/page-patterns.md

@@ -0,0 +1,238 @@
+# Page patterns
+
+Two recurring shapes: a home page, and a handful of content-page structures. Both are
+patterns to copy, not a fixed schema Antora enforces — deviate when the content actually
+calls for it.
+
+## Home page
+
+The `ROOT` module's `index.adoc`, rendered through the UI bundle's `home` layout
+(`:page-layout: home`). Fixed section order — each block is optional, but when present
+they appear in this order:
+
+```adoc
+= Home
+:page-layout: home
+:page-nav-module: <module>                      which module's nav the side menu shows,
+                                                  since ROOT itself has none in a
+                                                  multi-module site — see below
+:description: One-line product description.
+:page-tags: tag-one, tag-two
+:page-action: Primary action
+:page-action-url: module:page.adoc
+:page-action-secondary: Secondary action
+:page-action-secondary-url: module:other.adoc
+:page-hero-image: /component/_images/hero.png
+:page-hero-image-alt: Alt text for the hero image.
+
+Intro paragraph, then a short bullet list of core capabilities.
+
+== Get started
+
+[cards,type=image-square,columns="1 s:2 m:4",width=container]
+====
+[card,subheader="Category"]
+.xref:module:page.adoc[Entry point]
+--
+image::card-image.png["Alt text"]
+
+Short description.
+--
+====
+
+== Key capabilities
+
+[feature-tabs]
+====
+[feature,label="Capability one"]
+--
+image::feature-one.png[Alt text]
+
+Prose.
+
+[.cta]
+xref:module:page.adoc[Learn more]
+--
+====
+
+== CTA
+
+[cta]
+====
+Prose making the case for the action.
+
+[.primary]
+https://example.com[Primary link]
+====
+
+== FAQ
+
+[accordion,aria-label="Frequently asked questions"]
+--
+.Question?
+[%collapsible]
+====
+Answer.
+====
+--
+```
+
+Block syntax for `[cards]`, `[feature-tabs]`, `[cta]` and `[accordion]` is in the
+`writing-docs-pages` skill's `reference/docouture-blocks.md`; this file is the section-order
+pattern, not the block reference.
+
+## Content pages
+
+Three shapes cover most content. Pick whichever fits, don't force every page into one.
+
+**Overview page** — orients a reader before they dig into a module:
+
+```adoc
+= Module Name
+:description: One-line description.
+
+Intro paragraph.
+
+[NOTE]
+====
+A callout worth surfacing immediately — a prerequisite, a link to a deeper page.
+====
+
+== Key features
+
+* *Capability one* — with an xref to where it's covered in depth
+* *Capability two*
+
+== FAQ
+
+.Question?
+[%collapsible]
+====
+Answer.
+====
+```
+
+Note: an overview page's FAQ is usually a run of _ungrouped_ `[%collapsible]` blocks —
+reach for `[accordion]` grouping (see `writing-docs-pages`) when the questions genuinely
+belong together as one unit, the way the home page's FAQ does.
+
+**Tutorial page** — a linear walkthrough:
+
+```adoc
+= Quickstart
+:description: Get to a working example in minutes.
+
+Intro paragraph.
+
+== Prerequisites
+
+Before you begin, ensure you meet the xref:module:requirements.adoc[requirements].
+
+== Step by step
+
+=== 1. First step
+
+Prose. Alternative commands (package managers, etc.) go in a [tabs] block:
+
+[tabs]
+--
+[tab,label="pnpm"]
+****
+[source,bash]
+----
+pnpm install
+----
+****
+
+[tab,label="npm"]
+****
+[source,bash]
+----
+npm install
+----
+****
+--
+
+=== 2. Second step
+
+. Ordered step
+. Another ordered step
++
+Attached content needs a `+` continuation.
+```
+
+Steps are plain nested `=== N. ...` subsections — there is no custom "steps" block here,
+just section nesting.
+
+**Reference/leaf page** — documents one thing (an API, a config option, a component):
+
+```adoc
+= Thing Name
+:description: One-line description.
+
+image::thing.png[Alt text]
+
+Prose describing what it is and when to use it.
+
+== Usage
+
+=== Import it
+
+[source,ts]
+----
+import { Thing } from "package"
+----
+
+=== Register it
+
+[source,ts]
+----
+const instance = new Thing() // <1>
+----
+<1> Explanation of this step.
+```
+
+## Mono-module vs. multi-module
+
+`docouture new` scaffolds a **mono-module** site by default: a single `modules/ROOT/` holding
+both the landing page and all content, no `nav_modules:` in `docs/src/antora.yml`. This
+is the right shape for a small site with one coherent topic.
+
+A **multi-module** site splits content into several modules, each with its own
+`nav.adoc`/`pages/`, switchable from the UI's module selector. Growing into this shape:
+
+1. Create `docs/src/modules/<name>/{nav.adoc,pages/}` for each module.
+2. List every module's `nav.adoc` under `docs/src/antora.yml`'s top-level `nav:` — but
+   **not** `ROOT`'s: in a multi-module site, `ROOT` holds only the landing page and is
+   deliberately absent from `nav:` (it has nothing to navigate; it borrows a module's own
+   nav via `:page-nav-module:` on its `index.adoc`, as shown above).
+3. Describe each module under `nav_modules:` (a **list**, not a map — see
+   `reference/antora-extensions.md` for why) so the UI's switcher can show one module's
+   nav at a time with a title, description and icon:
+
+```yaml
+nav:
+  - modules/framework/nav.adoc
+  - modules/sdk/nav.adoc
+
+nav_modules:
+  - module: framework
+    title: Framework
+    description: One-line description of this module.
+    icon: design/grid-outlined
+  - module: sdk
+    title: SDK
+    description: One-line description of this module.
+    icon: actions/code-block-outlined
+```
+
+A module's own `nav.adoc` can use a bare, unlinked list item purely to group xrefs under
+a heading with no page of its own:
+
+```adoc
+* Getting started
+* xref:module:requirements.adoc[Requirements]
+* xref:module:quickstart.adoc[Quickstart]
+* Reference
+* xref:module:api/index.adoc[API]
+```

package/build/templates/agent-support/.opencode/skills/docs-versioning.versioned/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: docs-versioning
+description: "How to cut a release or a prerelease on this Antora documentation site, scaffolded with Versioned (Full History) mode: docouture version, docs/.release-version, and the docouture-release.yml workflow. USE WHEN bumping a version, cutting a release, configuring what a release tag contains, or asking how versioning works on this site. EXAMPLES: 'cut a release', 'bump the docs version', 'what does docs/.release-version do', 'how do I release a new version of the docs'."
+---
+
+# Docs versioning (Versioned — Full History)
+
+This site was scaffolded with `docouture new --mode versioned`. `main` is permanently the
+prerelease/preview channel; every release is its own immutable `vX.Y.Z` git tag, and all
+of them stay in the version dropdown forever — the shape to use when consumers pin an old
+version and need its docs to keep existing unchanged.
+
+See `reference/releasing.md` for the full mechanism (what each file says on `main` vs. on
+a release tag, and what the release workflow actually does).
+
+## The short version
+
+- **`docs/src/antora.yml`** on `main` always says `version: prerelease`,
+  `prerelease: true` — never edit this by hand to "cut" a release; it doesn't change on
+  `main` at all. A release tag gets its _own_ copy of this file, with `version: '1.2.0'`,
+  `prerelease: false`.
+- **`docouture version <value>`** is the one piece of this the CLI does for you locally — it
+  patches `docs/src/antora.yml`'s `version:`/`prerelease:` fields. Useful for testing a
+  version bump locally; the actual release workflow uses the same command internally.
+- **`docs/.release-version`** holds the next planned version (e.g. `1.2.0`) as plain
+  text. It's what a merged, `docs/release`-labeled pull request uses to tell the release
+  workflow what to tag — review it like any other file in that PR's diff.
+- **Cutting a release** happens through the `docouture-release.yml` GitHub Actions workflow
+  (`.github/workflows/`), not a local CLI command — see `reference/releasing.md` for why.
+  Trigger it either by:
+  - running it by hand (`workflow_dispatch`), giving the target version as input, or
+  - merging a pull request labeled `docs/release` into `main` — it reads the target
+    version from `docs/.release-version`.
+- After a genuine new release (not a republish of an existing tag), the workflow bumps
+  `docs/.release-version` forward to the next patch version automatically and commits
+  that to `main` — you shouldn't normally need to edit it yourself except to set an
+  intentionally different next target (e.g. jumping to a new minor).

package/build/templates/agent-support/.opencode/skills/docs-versioning.versioned/reference/releasing.md

@@ -0,0 +1,106 @@
+# How releasing works
+
+## What each file says, where
+
+| name                | set in                                       | scope                                                       |
+| ------------------- | -------------------------------------------- | ----------------------------------------------------------- |
+| `version`           | `docs/src/antora.yml`                        | per git ref — a ref's own checkout declares its own version |
+| `prerelease`        | `docs/src/antora.yml`                        | per git ref — `true`/`false`                                |
+| `branches` / `tags` | `antora-playbook.yml` → `content.sources[0]` | which refs the _build_ aggregates content from at all       |
+
+`docs/src/antora.yml` is read once per matched ref — `main` and each release tag get
+their own checkout, and therefore their own copy of that file, even though it's "the same
+file" in the sense that both trace back to the same path in git history.
+
+**On `main`:**
+
+```yaml
+name: my-site
+title: My Site
+version: prerelease
+prerelease: true
+```
+
+**On a release tag** (e.g. checked out at `v1.2.0`):
+
+```yaml
+name: my-site
+title: My Site
+version: '1.2.0'
+prerelease: false
+```
+
+**Playbook**, `content.sources[0]`:
+
+```yaml
+content:
+  sources:
+    - url: ..
+      start_path: docs/src
+      branches: [main]
+      tags: ['v*']
+```
+
+`tags: ['v*']` matches every tag shaped `v1.2.0`, `v2.0.0`, etc. — each becomes its own
+version because each tag's own `docs/src/antora.yml` carries a different `version:`.
+`branches: [main]` contributes the single prerelease version on top. How many past
+versions show up is purely a function of how many tags exist and match the glob — delete
+or rename a tag and it drops out of the aggregate on the next build.
+
+## Cutting a release: `docouture-release.yml`
+
+**Triggers**, both deliberate acts rather than a side effect of an ordinary push:
+
+- `workflow_dispatch` — run by hand from the Actions tab. Its `version` input must be a
+  real version (e.g. `1.2.0`) — the workflow fails before touching anything if it's left
+  at the default (that default is meant for a standalone-mode site, which this isn't).
+- `pull_request`, `types: [closed]`, `branches: ['main*']` — fires automatically when a
+  pull request merges into a branch matching that glob, but only actually proceeds when
+  the PR was genuinely merged **and** carries the `docs/release` label. Any other close
+  (not merged, or merged without the label) is a no-op run.
+
+**Where the target version comes from** differs by trigger: `workflow_dispatch` has a
+form field for it; the `pull_request` trigger has none, so it reads
+`docs/.release-version` instead — the plain-text file committed as part of the
+merged PR, containing just the target version.
+
+**The release itself**: `docouture version <value>` patches `docs/src/antora.yml` on a
+one-off commit built on top of `main`'s current tip, `git tag v<value>` is created there,
+and the tag is pushed — a GitHub Release is also created from it. `main` itself is never
+advanced or touched by this step; its own `docs/src/antora.yml` permanently keeps saying
+`version: prerelease`, `prerelease: true`.
+
+**Every release tag is force-recreated if it already exists** — a republish (fixing a
+released version, e.g. a docs typo caught after the tag went out) is a deliberate,
+ordinary act, not something needing a separate flag.
+
+## `docs/.release-version` after a release
+
+Nothing clears it — it's bumped forward instead, except on a republish. On a genuine
+forward release (the target tag was new), a final step in the workflow advances the file
+to the next patch version and commits that directly to `main` — so the file always holds
+a sane next target rather than a stale, already-released value. This step is **skipped**
+on a republish (the target tag already existed): that run's target version was typically
+already superseded by whatever the file currently holds as the next planned target, so
+bumping forward from the republished version would clobber that already-planned value.
+
+## Why there's no `docouture release` command
+
+`docouture-release.yml`'s own steps depend on CI-only concerns a portable local CLI command
+would either have to assume or re-implement badly: a token with `contents: write` +
+`pull-requests: write`, reading which label a merged PR carried, creating a GitHub
+Release. None of that has a sane local equivalent. The CLI's release-adjacent surface
+stays deliberately narrow: `docouture version` is the one piece of actual logic the workflow
+reuses locally-testable, because patching `docs/src/antora.yml`'s fields genuinely is
+portable; everything else about _cutting_ a release stays in the workflow.
+
+## URL routing
+
+This site gets a component-scoped version segment for free — `/my-site/1.2.0/…`,
+`/my-site/prerelease/…` — Antora always includes the version in the URL unless told
+otherwise. `urls.latest_version_segment: latest` (an optional playbook key, not set by
+default here) gives whichever version Antora computes as "latest" an _additional_, stable
+alias URL (`/my-site/latest/…`) alongside its real version path — useful when most inbound
+links should track "whatever the newest release is" without editing them on every tag.
+"Latest" is Antora's own semver-aware computation among non-prerelease versions, not
+something either file above sets directly.

package/build/templates/agent-support/.opencode/skills/documenting-your-repo/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: documenting-your-repo
+description: "How to plan, populate and maintain documentation for this repo end-to-end — deciding what modules/pages should exist, sourcing content from wherever it actually lives (existing docs, README, code comments, API signatures, CLI definitions, config schemas — no fixed assumption about location), and keeping docs in sync as the repo grows. USE WHEN starting documentation from scratch, deciding what to document, checking whether docs coverage is complete, or documenting a newly added feature. EXAMPLES: 'build docs for this repo', 'what should my docs cover', 'is anything undocumented', 'document this new feature', 'my docs feel out of date'."
+---
+
+# Documenting your repo
+
+This is the entry point for turning an empty (or half-empty) `docs/` site — scaffolded by
+`docouture new` — into real, maintained documentation. It's a planning and orchestration
+skill, not a syntax reference: once a decision is made here, it hands off to the two
+mechanics skills:
+
+- **`docs-internals`** — once you know a module/page needs to exist, this is how
+  `antora.yml`, `nav.adoc` and the home-page pattern actually work.
+- **`writing-docs-pages`** — once you know what a page should say, this is the AsciiDoc
+  syntax, xrefs and this site's custom blocks (`[tabs]`, `[cards]`, `[accordion]`, …).
+
+Use this skill repeatedly, not just once — it's the loop that keeps documentation honest
+as the repo evolves, not a one-shot wizard that's done after the first pass.
+
+- `reference/structure-planning.md` — mono- vs. multi-module decision, the module menu,
+  signals worth checking in the repo to shape it, and the home page's special (structure
+  now, content later) treatment.
+- `reference/content-sourcing.md` — where content comes from when nothing is prescribed:
+  priority order across existing docs, README/CONTRIBUTING, and the repo's code itself
+  (exports, doc-comments, CLI definitions, config schemas, tests-as-examples) — including
+  the all-code, zero-prose case.
+- `reference/maintenance-loop.md` — how to re-enter this skill later: the `AGENTS.md`
+  documentation-state ledger, what counts as drift, and when to revisit the home page.
+
+## The loop, in short
+
+1. **Base check** — confirm identity/branding `docouture new` already seeded (title, product
+   name, description, favicon, light/dark logo). Look for existing brand assets elsewhere
+   in the repo before asking the user to supply new ones.
+2. **Structure planning** — decide mono- vs. multi-module and which modules exist. See
+   `reference/structure-planning.md`. The home page's slot is asserted here — its content
+   is not, see below.
+3. **Content sourcing & drafting** — for every planned page, find where its content
+   actually lives (don't assume — a repo with no `README` at all still has an API surface,
+   a CLI, a config schema) and draft it. See `reference/content-sourcing.md`. Draft a rough
+   home page early from whatever one-line description exists; treat it as unfinished.
+4. **Maintenance loop** — re-run this skill whenever code grows a new surface (exported
+   function, CLI command, config key) with nothing documenting it, whenever nav no longer
+   matches the modules that exist, or periodically to refresh the home page once enough
+   content exists to summarize well. See `reference/maintenance-loop.md`.
+
+## What this skill does not opinionate about
+
+Where in the repo the "real" information lives is entirely up to the repo itself — a
+doc-comment, a type signature, a schema file, a test, a `--help` string, an existing
+`README.md`, are all fair game and equally valid sources. This skill does not prescribe a
+required location or format for source material; it only prescribes _that_ every
+documented surface is traceable to something real, and _where in `AGENTS.md`_ that
+traceability is recorded (see `reference/maintenance-loop.md`).

package/build/templates/agent-support/.opencode/skills/documenting-your-repo/reference/content-sourcing.md

@@ -0,0 +1,55 @@
+# Content sourcing
+
+Once the structure is planned (`structure-planning.md`), every page needs real content
+from somewhere. This is deliberately not prescriptive about _where_ — a repo with a rich
+`docs/` wiki export and a repo with nothing but source code both need to end up
+documented, through different paths.
+
+## Priority order
+
+For each planned page, look in this order and use the first thing that actually exists:
+
+1. **Existing docs** — a pre-existing `docs/` tree, wiki export, Notion/Confluence dump
+   committed somewhere, or hand-written prose already sitting in the repo. Adapt it into
+   the page structure/blocks from `writing-docs-pages`, don't just paste it verbatim if the
+   shape doesn't fit (e.g. a wall of prose where a `[tabs]` or ordered steps would serve
+   the reader better).
+2. **README / CONTRIBUTING / inline package docs** — often covers getting-started and
+   contributing ground well, rarely covers the full API/reference surface.
+3. **The code itself, directly** — when neither of the above exists, or doesn't cover a
+   given surface, read the actual repo to derive the page. This is the case worth
+   designing for, not treating as a fallback edge case:
+   - exported functions/classes and their doc-comments (JSDoc/TSDoc, docstrings, godoc,
+     rustdoc, whatever the language uses) → `reference` pages, one per public symbol or
+     coherent group of them
+   - CLI command definitions, `--help` output, argument parsers → `guides`/`reference`
+     entries for CLI usage
+   - config schema files, typed config objects, environment variable reads in code →
+     `configuration` pages
+   - OpenAPI/GraphQL/protobuf definitions → `reference` pages, one per
+     endpoint/type/service or a sensible grouping of them
+   - tests and examples in the repo → real, working usage patterns worth lifting into a
+     tutorial or reference page's "Usage" section, since they're the most likely to be
+     accurate and up to date
+4. **Nothing found** — write the page as an explicit stub: enough structure to be useful
+   (title, one-line description, an empty section per anticipated topic) plus a visible
+   `TODO` note of what's missing and what would need to be true in the repo for the note to
+   go away (e.g. "TODO: document once this CLI subcommand exists / is exported").
+
+Don't force step 3 to imitate step 1/2's tone if there's nothing to imitate — a
+code-derived reference page reads differently from a hand-written guide, and that's fine.
+
+## No fixed assumption about location
+
+Never assume "the code lives here" or "the API surface is always in `src/`" — every repo
+is laid out differently. Look at what's actually there (package manifests, build config,
+directory structure, language-appropriate entry points) rather than pattern-matching
+against one expected shape.
+
+## Recording what a page is based on
+
+Once a page is drafted from the code itself (step 3 above, not steps 1/2/4), record it in
+`AGENTS.md`'s documentation-state ledger — see `maintenance-loop.md` for the exact shape.
+This is what lets a later pass tell "still matches the code" apart from "needs a look"
+without re-deriving every page from scratch each time, and what stops a later pass from
+overwriting a page a human has since hand-edited.

package/build/templates/agent-support/.opencode/skills/documenting-your-repo/reference/maintenance-loop.md

@@ -0,0 +1,68 @@
+# Maintenance loop
+
+This skill is meant to be re-entered, not run once and abandoned. This file is how a later
+pass picks up where an earlier one left off, without re-deriving everything from zero.
+
+## The documentation-state ledger, in `AGENTS.md`
+
+`AGENTS.md` (this repo's own copy, at the repository root) carries a `## Documentation
+state` section — a table of every page this skill has drafted from the code itself, what
+it was derived from, and its last-known status:
+
+```markdown
+## Documentation state
+
+<!-- maintained by the documenting-your-repo skill — do not hand-edit structure, only content -->
+
+| doc page              | derived from              | status  |
+| --------------------- | ------------------------- | ------- |
+| reference/client.adoc | src/api/client.ts exports | current |
+| guides/cli-usage.adoc | src/cli/*.ts command defs | current |
+| index.adoc (home)     | manual (hand-written)     | —       |
+```
+
+Rules for this table:
+
+- Add a row **only** for pages sourced from the repo's code (content-sourcing.md's step
+  3). A page sourced from existing docs/README, or written by hand, gets `derived from:
+manual` and `status: —` — this marks it as human-owned; never regenerate it from code
+  without being asked.
+- `derived from` should be specific enough that a future pass can check whether it's still
+  accurate — a file path, an export list, a schema file, a command name — not just "the
+  code".
+- `status` is one of: `current` (checked recently, still matches), `stale` (the source has
+  changed since this page was last touched), `new` (a source exists with no page yet — see
+  below).
+- This skill is the only thing that edits this section. If a human directly edits a
+  code-derived page's prose, that's fine and expected — but flip its `status` to something
+  worth re-checking next time rather than silently trusting the table, since the ledger
+  itself won't have seen the edit.
+
+## What counts as drift, on re-entry
+
+On each re-entry, before drafting anything new:
+
+1. Re-scan the repo's surface the same way `content-sourcing.md` step 3 describes —
+   exports, CLI commands, config keys, API definitions.
+2. Diff that surface against the ledger's `derived from` entries: a new export/command/key
+   with no matching row is `new` (undocumented); a row whose source has materially changed
+   (signature changed, command removed, config key renamed) is `stale`.
+3. Also check `nav.adoc` against the modules/pages that actually exist — a module or page
+   present in the ledger or on disk but absent from `nav.adoc` is unreachable, not just
+   undocumented (see `docs-internals`).
+4. Handle `new` and `stale` rows before anything else; leave `current` and `manual` rows
+   alone.
+
+## Revisiting the home page
+
+The home page is drafted early (rough) and deliberately left unfinished — see
+`structure-planning.md`. Revisit and tighten it:
+
+- once every planned module/page from the first structure pass exists with real content,
+  not stubs, or
+- whenever a re-entry adds or removes a whole module (the home page's "key capabilities"
+  section should reflect what the site now actually covers).
+
+There is no ledger row requirement for the home page itself when it's substantially
+hand-written — mark it `manual` once someone has actually rewritten its prose, same as any
+other hand-authored page.

package/build/templates/agent-support/.opencode/skills/documenting-your-repo/reference/structure-planning.md

@@ -0,0 +1,102 @@
+# Structure planning
+
+Decide what the site's shape should be before drafting any content. This builds on
+`docs-internals`'s mechanics — read that skill for how `nav.adoc`/`antora.yml` actually
+work; this file is about which structure to choose in the first place.
+
+## The target nav structure
+
+This is the default shape to aim for — six ordered sections, each page tagged with how
+essential it is. Not every repo needs every page in one pass; the tags say which ones to
+skip without asking and which ones to check for before skipping:
+
+- 🔴 required — every documented repo should end up with this page.
+- 🟠 recommended — include unless there's a specific reason not to.
+- 🔵 conditional — include only if the repo actually has the surface it covers; skip
+  cleanly (no stub) if it doesn't.
+- ⚪ optional — nice to have, include when it adds value, otherwise leave out.
+
+```
+docs
+├── 1. Overview
+│   ├── about                              🔴
+│   ├── architecture                       🔴
+│   └── glossary (or basic terms)          ⚪
+├── 2. Getting started
+│   ├── prerequisites                      🔴
+│   └── quickstart                         🔴
+├── 3. Guides
+│   ├── overview                           🔴
+│   ├── <task-name> / <feature>            🔴 (≥1, repeatable pattern, i.e. "How to setup [feature]", "How to use [feature]", etc.)
+│   └── development                        🟠
+├── 4. Reference
+│   ├── overview                           🔴
+│   ├── configuration                      🔵 (repo has a configuration surface)
+│   └── api / sdk / cli                    🔵 (repo has an API/SDK/CLI surface, it can be ≥1)
+├── 5. Additional information
+│   ├── overview                           🔴
+│   ├── changelog                          🔴
+│   │   ├── overview                       🔴 (menu to each changelog, grouped by major if possible if standalone version, by date of publishing)
+│   │   └── vX.Y.Z / stable / prerelease   🔴 (the changelog notes of the version)
+│   ├── release-notes                      🔴
+│   │   ├── overview                       🔴 (menu to each release, grouped by major if possible if standalone version, by date of publishing)
+│   │   └── vX.Y.Z / stable / prerelease   🔴 (the real release notes of a version)
+│   ├── faq                                🟠
+│   ├── security                           🟠
+│   └── eol / migration-guides             🔵 (repo has deprecations/major-version history)
+└── 6. Contributing
+    └── overview                           🔴
+```
+
+## Mapping the tree onto modules
+
+`docouture new` scaffolds mono-module by default (single `ROOT`, one `nav.adoc`). For a small
+or early-stage repo, keep the whole tree above inside `ROOT`: each numbered section becomes
+a bare, unlinked list item in `nav.adoc` grouping its pages under a heading with no page of
+its own (see `docs-internals/reference/page-patterns.md`'s grouping example) — sections 1,
+2, 5 and 6 stay this way even in a mature, fully multi-module site, since none of them ever
+needed a "home" of their own.
+
+**Guides** and **Reference** are the pair worth promoting to real modules once the site
+outgrows `ROOT`, because they're the two sections that need a landing page a reader can
+land on directly (via the module switcher) rather than always arriving through `ROOT`'s
+own home page. Promote them independently and only when it earns its keep — a repo with
+five guide pages and one reference page doesn't need Reference split out yet.
+
+When in doubt, start mono-module — it's cheap to split later, see `docs-internals/
+reference/page-patterns.md`'s own mono→multi migration steps. Splitting too early just
+adds a module switcher nobody needs; splitting too late means a `ROOT` full of unrelated
+content with no clean way to navigate it.
+
+## Signals worth checking against the 🔵 conditional pages
+
+Don't assume where these live — check what's actually in the repo, in whatever form it
+takes there:
+
+- A `bin` field in `package.json`, or a `cli`/`cmd` directory → an API/CLI surface, wants
+  **Reference → api (or commands)**, and likely a **Guides** task page for common usage.
+- An OpenAPI/GraphQL schema, or a REST/RPC handler directory → an API surface, wants
+  **Reference → api**.
+- A config file schema (`.schema.json`, a typed config object, documented env vars in
+  code) → wants **Reference → configuration**.
+- A changelog file, deprecation notices, major-version breaks, or an existing upgrade
+  guide → wants **Additional information → eol / migration-guides**.
+- Multiple independently publishable packages in a monorepo → consider one **Reference**
+  module per package rather than forcing them into one.
+- An existing `docs/`, `README.md`, `CONTRIBUTING.md`, wiki export, or similar → these
+  inform which pages already have real content to source from (see
+  `content-sourcing.md`), not just which pages to create.
+
+Confirm the proposed set of 🔵/⚪ pages with whoever's driving before committing pages to
+it — auto-detected signals can be wrong (a `bin` field for an internal-only dev tool
+doesn't need a user-facing CLI guide, for instance).
+
+## The home page: structure now, content later
+
+The home page's _existence and slot_ is fixed and non-negotiable, asserted in this phase:
+`ROOT`'s `pages/index.adoc`, using the `page-layout: home` pattern (see `docs-internals/
+reference/page-patterns.md`). It sits outside the six-section tree above — it's the site's
+entry point, not a member of "Overview". Do not skip creating it, and do not spend long
+drafting its real copy yet — its content is a _summary_ of everything else, so it's better
+drafted roughly here (from whatever one-line description already exists) and properly
+finished in the content-sourcing phase, once there's something real to summarize.