@inditextech/docouture-cli 0.1.0-SNAPSHOT.40.1

package/build/templates/agent-support/.claude/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.

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

@@ -0,0 +1,112 @@
+---
+name: writing-docs-pages
+description: "How to author AsciiDoc content in this Antora documentation site — the content tree, xref: references, nav.adoc, admonitions, code blocks, and this site's own custom blocks (tabs, cards, accordion, feature-tabs, cta, label:/mono: macros). USE WHEN writing or editing a .adoc page, adding a page to the nav, fixing a broken xref, or reaching for a block like tabs/cards/accordion. EXAMPLES: 'add a page', 'my xref doesn't resolve', 'the build fails on a warning', 'add tabs for pnpm/npm/yarn commands', 'group these FAQ items', 'add a card grid'."
+---
+
+# Writing docs pages
+
+Every page here is AsciiDoc, parsed by **Asciidoctor** and orchestrated by **Antora**.
+Antora restricts and reinterprets parts of the language (includes, xrefs, image paths);
+where this skill and the upstream Asciidoctor docs differ, follow this skill.
+
+- `reference/language-basics.md` — the AsciiDoc language itself: document structure,
+  blocks, text formatting, lists, links/xrefs, images, source blocks, admonitions, tables,
+  includes, conditionals, substitutions, attributes — plus a URL index into
+  `https://docs.asciidoctor.org/asciidoc/latest/` for anything not covered.
+- `reference/docouture-blocks.md` — this site's own custom blocks, registered via
+  `@inditextech/docouture-asciidoc-extensions` (see `antora-playbook.yml`'s
+  `asciidoc.extensions`): `[tabs]`, `[cards]`, `[accordion]`, `[feature-tabs]`, `[cta]`,
+  `label:`/`mono:` inline macros, and a few table/video sizing attributes.
+
+For the home page vs. content page patterns, mono- vs. multi-module sites, and the
+playbook/component-descriptor mechanics, see the `docs-internals` skill.
+
+## Where content lives
+
+```
+docs/src/
+  antora.yml                  component descriptor: name, title, version, nav
+  modules/
+    ROOT/                     the default module; its name is omitted from resource IDs
+      nav.adoc                the navigation tree for this module
+      pages/*.adoc            one page per file — these become site URLs
+```
+
+Only `pages/` exists in a freshly scaffolded site. The other family directories are
+created when first needed, with these exact names — Antora keys off them and ignores
+anything else:
+
+| directory      | family        | referenced as                  |
+| -------------- | ------------- | ------------------------------ |
+| `pages/`       | `page$`       | `xref:name.adoc[]`             |
+| `partials/`    | `partial$`    | `include::partial$name.adoc[]` |
+| `examples/`    | `example$`    | `include::example$name.json[]` |
+| `images/`      | `image$`      | `image::name.png[]`            |
+| `attachments/` | `attachment$` | `xref:attachment$file.pdf[]`   |
+
+## Resource IDs
+
+Antora addresses content by resource ID, not by relative path:
+
+```
+version@component:module:family$relative/path.adoc#fragment
+```
+
+Everything left of the filename is optional and defaults to the current page's context.
+Inside the same module:
+
+| reference                        | means                                                                        |
+| -------------------------------- | ---------------------------------------------------------------------------- |
+| `xref:index.adoc[Home]`          | a page in the same module                                                    |
+| `xref:guide/setup.adoc[]`        | a page in a subdirectory of `pages/` — empty text uses the target's title    |
+| `xref:other-module:index.adoc[]` | a page in another module — only in a multi-module site, see `docs-internals` |
+| `xref:index.adoc#install[]`      | a fragment on another page                                                   |
+| `include::partial$intro.adoc[]`  | a partial from the same module                                               |
+
+`../` path traversal between pages is not how this works — a page one directory deep
+still addresses its sibling as `xref:guide/other.adoc[]`, module-relative, never
+file-relative.
+
+## Where a change goes
+
+| you want to                    | do                                                                                                                                             |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| add a page                     | create `docs/src/modules/<module>/pages/name.adoc` **and** add an `xref:` to that module's `nav.adoc`                                          |
+| add a section to the nav       | edit `nav.adoc` — nesting is list depth (`*`, `**`, `***`); a bare, unlinked list item can group xrefs under a heading with no page of its own |
+| reuse a chunk of prose         | `docs/src/modules/<module>/partials/name.adoc`, included as `partial$name.adoc`                                                                |
+| add an image                   | `docs/src/modules/<module>/images/name.png`, referenced as `image::name.png[Alt]`                                                              |
+| set a site-wide attribute      | `asciidoc.attributes` in `antora-playbook.yml`                                                                                                 |
+| set a component-wide attribute | `asciidoc.attributes` in `docs/src/antora.yml`                                                                                                 |
+| set a page-scoped attribute    | an attribute entry in the page header, above the first blank line                                                                              |
+
+## Constraints that fail silently
+
+- **A warning is a build failure.** `antora-playbook.yml` sets
+  `runtime.log.failure_level: warn`. A broken xref, a missing include target, an
+  undefined attribute reference or a bad image path exits non-zero.
+- **A page missing from `nav.adoc` still builds.** It publishes at its URL, renders with
+  an empty navigation context and is reachable only by direct link. Nothing warns.
+- **`include::` cannot read arbitrary paths.** Antora installs its own include processor
+  that resolves targets against the content catalog, so only the family forms
+  (`partial$`, `example$`, page IDs) work. A filesystem path fails at build time.
+- **Attribute references are not substituted inside verbatim blocks.** `{version}`
+  inside `----`/`....` renders literally unless the block carries `subs=attributes+`.
+- **Unconstrained formatting needs doubled marks.** `**bold**` mid-word, `__italic__`
+  mid-word. The single-mark form adjacent to a word character is not formatting at all.
+- **A cross-module xref only resolves inside a multi-module site**, and only once both
+  modules are listed under `docs/src/antora.yml`'s `nav:` — see `docs-internals`.
+
+## Page attributes the UI reads
+
+| attribute                                             | effect                                                                                                                                                  |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description`                                         | hero excerpt (below the title) AND `<meta name="description">`                                                                                          |
+| `page-tags`                                           | comma-separated; one label pill each in the hero                                                                                                        |
+| `page-action` / `page-action-url`                     | primary hero button — renders only when BOTH are set                                                                                                    |
+| `page-action-secondary` / `page-action-secondary-url` | secondary hero button, same rule                                                                                                                        |
+| `page-hero-image` / `page-hero-image-alt`             | hero illustration                                                                                                                                       |
+| `page-nav-module`                                     | which module's nav tree the side menu shows for this page — set on `ROOT`'s own landing page in a multi-module site, since `ROOT` has no nav of its own |
+| `page-layout: home`                                   | the marketing home-page layout — see `docs-internals`'s page-patterns reference                                                                         |
+| `page-role: -hero`                                    | suppresses the hero entirely                                                                                                                            |
+| `page-role: -toc`                                     | suppresses the right-hand table of contents                                                                                                             |
+| `page-pagination`                                     | enables the previous/next footer links                                                                                                                  |

package/build/templates/agent-support/.claude/skills/writing-docs-pages/reference/docouture-blocks.md

@@ -0,0 +1,170 @@
+# This site's custom blocks
+
+Registered by `@inditextech/docouture-asciidoc-extensions`, listed under
+`antora-playbook.yml`'s `asciidoc.extensions`. Everything below is authored content with
+no plain-AsciiDoc equivalent — the extension only emits markup, all styling comes from
+the UI bundle's CSS. Every block here degrades to plain, readable HTML with JavaScript
+off (sequential sections for tabs, `<details>` for accordions, real `<a href>`s).
+
+## Tabs
+
+A switcher for equivalent alternatives — package-manager commands, config formats, etc.
+
+```adoc
+[tabs]
+--
+[tab,label="pnpm"]
+****
+[source,bash]
+----
+pnpm add some-package
+----
+****
+
+[tab,label="npm"]
+****
+[source,bash]
+----
+npm install some-package
+----
+****
+--
+```
+
+`[tabs]` is an open block (`--`); each `[tab,label="…"]` child is its own sidebar block
+(`****`), never an example block (`====`) — this lets a tab hold anything, including a
+titled source block or another nested block, without a delimiter-nesting trap.
+
+## Cards
+
+A grid of entry-point cards — landing "Get started" rows, or a content page pointing at
+related pages.
+
+```adoc
+[cards,type=image-square,columns="1 s:2 m:4",width=container]
+====
+[card,subheader="Category"]
+.xref:module:page.adoc[Card title]
+--
+image::card-image.png["Alt text"]
+
+Card description.
+--
+
+[card]
+.xref:module:other.adoc[No-image card]
+A card with just a title and description — no image, no open block needed.
+====
+```
+
+- `type`: `no-image` (default), `image-landscape`, `image-square`, `image-portrait`.
+- `columns`: base count, then breakpoint-prefixed overrides (`s:`, `m:`, `l:`), e.g.
+  `"1 s:2 m:4"` — max 4.
+- `width`: `content` (default) or `container`.
+- The block title (`.xref:...[Title]`) carries the link — the whole card is that link.
+- A card with an image needs the open-block form (`--`/`--`); a text-only card can be a
+  plain paragraph under `[card]`.
+
+## Accordion (grouped FAQ)
+
+Groups a run of `[%collapsible]` blocks with proper `role=group` semantics and,
+optionally, single-open behaviour — the native `[%collapsible]` on its own (see
+`language-basics.md`) still works for one-off collapsibles; group them with `[accordion]`
+when several belong together, e.g. an FAQ section.
+
+```adoc
+[accordion%single-open,aria-label="Frequently asked questions"]
+--
+.Question one?
+[%collapsible]
+====
+Answer one.
+====
+
+.Question two?
+[%collapsible]
+====
+Answer two.
+====
+--
+```
+
+- `%single-open` (an option, like `%collapsible`'s own) makes opening one item close the
+  others; omit it and items are independent (the default).
+- Give the group an `aria-label=` (or a block `.Title`) — a `role=group` with no
+  accessible name is flagged.
+- `[accordion]` is an open block (`--`) so its `[%collapsible]` children stay ordinary
+  `====` blocks, unchanged from how they'd read standalone.
+
+## Feature tabs
+
+A media-plus-prose switcher for a handful of top-level capabilities — used on the home
+page (see the `docs-internals` skill's `reference/page-patterns.md`).
+
+```adoc
+[feature-tabs]
+====
+[feature,label="Capability one"]
+--
+image::feature-one.png[Alt text]
+
+Prose describing this capability.
+
+[.cta]
+xref:module:page.adoc[Learn more]
+--
+
+[feature,label="Capability two"]
+--
+image::feature-two.png[Alt text]
+
+Prose describing this capability.
+--
+====
+```
+
+## CTA
+
+A single call-to-action block — prose plus one prominent link.
+
+```adoc
+[cta]
+====
+Prose making the case for the action.
+
+[.primary]
+https://example.com/signup[Get started]
+====
+```
+
+## Inline macros: `label:` and `mono:`
+
+```adoc
+label:red[Blocked]        a coloured pill — variants: white, grey, red, orange, green,
+                           blue, purple, pink, teal (grey is the default, label:[Text])
+mono:[className]          plain monospaced text with no code-chip styling — for a
+                           table cell whose entire content is a bare name/token
+```
+
+`` `backtick code` `` (see `language-basics.md`) keeps its usual code-chip styling;
+`mono:[]` is the deliberate opt-out for a column where every cell is a token and the chip
+would just be noise.
+
+## Table and video sizing attributes
+
+```adoc
+[table-width=720px,cols="1,1"]        |=== an absolute CSS width, bypassing Asciidoctor's
+|===                                   own width= (which is percentage-only, clamped 1-100)
+
+[cols="1,3,2",nowrap-cols="1,2"]      pins white-space: nowrap to specific columns
+|===
+...
+|===
+
+video::demo[youtube,640,360]          sets both dimensions and locks the aspect ratio
+                                        at any narrower viewport (no CSS-only fix exists
+                                        for an iframe/video the way there is for <img>)
+```
+
+These aren't new blocks, just extra attributes Asciidoctor's own table/video macros don't
+support natively — safe to ignore if you never need an absolute width or a nowrap column.