@inditextech/docouture-cli 0.1.0-SNAPSHOT.40.1

package/build/templates/agent-support/.claude/skills/writing-docs-pages/reference/language-basics.md

@@ -0,0 +1,402 @@
+# AsciiDoc language basics
+
+Ordered by how often it comes up, not by upstream nav order. Antora-specific behaviour is
+called out inline; everything else is plain AsciiDoc as Asciidoctor implements it.
+
+Upstream base URL for every link below: `https://docs.asciidoctor.org/asciidoc/latest/`
+
+## Document structure
+
+A page is a header (optional), then blocks. The header is everything above the first
+blank line.
+
+```adoc
+= Page Title
+:description: Shown in the meta description and in search results.
+:page-tags: one, two
+
+Preamble paragraph — content before the first section title.
+
+== First Section
+
+Body.
+
+=== Nested Section
+```
+
+- **One level-0 title per page.** `=` is the document title; `==` is the first real
+  section. A second `=` is an error in `doctype: article` (the default).
+- Section levels must not skip: `==` then `====` is a warning, and a warning fails the
+  build here.
+- Attribute entries (`:name: value`) in the header apply to the whole page. Placed in the
+  body they apply from that point on.
+- `page-*` attributes are Antora's convention: they are lifted onto the UI model and are
+  available to templates rather than to the content.
+
+`document-structure/`, `document/header/`, `sections/titles-and-levels/`
+
+## Blocks
+
+A block is delimited by four or more repeated characters, or implied by a blank line
+(paragraph).
+
+| delimiter | block                                   |
+| --------- | --------------------------------------- |
+| `----`    | listing / source                        |
+| `....`    | literal                                 |
+| `====`    | example (and, with a style, admonition) |
+| `****`    | sidebar                                 |
+| `____`    | quote                                   |
+| `--`      | open (exactly two hyphens)              |
+| `\|===`   | table                                   |
+| `++++`    | passthrough                             |
+| `////`    | comment                                 |
+
+Metadata sits directly above the delimiter, no blank line between:
+
+```adoc
+.A block title
+[#custom-id.role-one.role-two%option,attr=value]
+----
+content
+----
+```
+
+- `.Title` — block title.
+- `#id` — the ID, in the attribute list shorthand.
+- `.role` — a CSS class. Repeatable.
+- `%option` — an option, e.g. `%collapsible`, `%header`, `%autowidth`.
+- The first positional attribute is the **block style**, which can make one delimiter
+  behave as another (`[quote]` on `====`, `[source]` on `----`). This is _block
+  masquerading_.
+
+`blocks/`, `blocks/delimited/`, `attributes/element-attributes/`, `blocks/masquerading/`
+
+## Text formatting
+
+| markup                          | result                  | note                               |
+| ------------------------------- | ----------------------- | ---------------------------------- |
+| `*bold*` / `**bold**`           | bold                    | double form required mid-word      |
+| `_italic_` / `__italic__`       | italic                  | same                               |
+| `` `mono` ``                    | monospace               | subs still apply inside            |
+| `` `+literal+` ``               | monospace, no subs      | use for anything with `{}` or `<>` |
+| `#highlight#` / `##highlight##` | mark                    |                                    |
+| `[.role]#text#`                 | span with a class       | the general escape hatch           |
+| `~sub~` / `^sup^`               | subscript / superscript |                                    |
+
+The single-mark ("constrained") form only applies when the marks sit at a word boundary.
+`hard*coded*text` is literal asterisks; `hard**coded**text` is bold. This is the single
+most common formatting surprise.
+
+`text/`, `text/troubleshoot-unconstrained-formatting/`
+
+## Lists
+
+```adoc
+* first
+* second
+** nested
++
+Attached paragraph — the `+` continuation binds it to the item above.
+
+. ordered
+. ordered
+
+term:: definition
+another term:: definition
+
+* [ ] unchecked task
+* [x] checked task
+```
+
+- Nesting is marker repetition (`*`, `**`, `***`), not indentation.
+- A blank line alone does not end a list; adjacent non-list content does. Two adjacent
+  lists that should stay separate need `//-` (an empty comment line) between them.
+- Anything other than a plain paragraph attached to an item needs `+` on its own line
+  before it — including nested blocks, source blocks and admonitions.
+
+`lists/unordered/`, `lists/ordered/`, `lists/description/`, `lists/continuation/`,
+`lists/checklist/`, `lists/separating/`
+
+## Links and cross references
+
+```adoc
+https://example.com[Link text]
+https://example.com[Link text^]              open in a new tab
+link:https://example.com[Text]               explicit macro; needed when the URL is not bare
+mailto:a@example.com[Mail us]
+
+xref:page.adoc[Text]                          Antora resource ID — see writing-docs-pages SKILL.md
+xref:page.adoc#section-id[Text]
+xref:#local-section[Text]                     same page
+<<local-section,Text>>                        same page, alternate form
+```
+
+- Empty xref text (`xref:page.adoc[]`) renders the target page's title. Prefer it — it
+  stays correct when the title changes.
+- A URL containing `[`, `]` or a trailing `.` needs the `link:` macro or attribute
+  wrapping.
+- Antora validates every xref. An unresolved one fails the build.
+
+`macros/links/`, `macros/xref/`, `macros/inter-document-xref/`
+
+## Images and icons
+
+```adoc
+image::name.png[Alt text,640,480]             block image
+image:name.png[Alt text,24,24]                inline image (single colon)
+image::name.png[Alt,link=https://example.com]
+icon:check[]                                  font icon — icons=font is set
+kbd:[Ctrl+C]                                  requires experimental (it is set)
+btn:[Save]
+menu:File[Save As]
+```
+
+Antora resolves `image::name.png[]` against the module's `images/` directory. Do not
+write `../images/name.png` and do not set `:imagesdir:` — Antora manages it.
+
+`macros/images/`, `macros/icons/`, `macros/keyboard-macro/`, `macros/ui-macros/`
+
+## Source blocks
+
+```adoc
+[source,typescript]
+----
+const answer = 42
+----
+
+[source,json,highlight=2..3]
+----
+{ "a": 1 }
+----
+```
+
+- `source-highlighter=highlight.js` is Antora's default and is in force here. The
+  language token must be one highlight.js knows.
+- `[,typescript]` (empty first positional) is shorthand for `[source,typescript]`.
+- Callouts mark lines with `<1>` and are explained in a following colon list:
+
+```adoc
+[source,js]
+----
+const x = 1 // <1>
+----
+<1> Explanation.
+```
+
+- Attribute references are **not** substituted inside a source block unless the block
+  carries `subs=attributes+`.
+
+`verbatim/source-blocks/`, `verbatim/callouts/`, `verbatim/highlight-lines/`
+
+## Admonitions
+
+```adoc
+NOTE: One-line form.
+
+[WARNING]
+====
+Multi-line form. Any blocks can go inside.
+====
+```
+
+Five types only: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`. A custom type needs a
+role plus CSS.
+
+`blocks/admonitions/`
+
+## Tables
+
+```adoc
+.Optional title
+[cols="1,2,1",options="header",%autowidth]
+|===
+|Column A |Column B |Column C
+
+|cell
+|cell
+|cell
+|===
+```
+
+- `cols` takes proportional widths (`1,2,1`), percentages (`25%,50%,25%`), or a repeat
+  (`3*` = three equal columns).
+- A column or cell specifier prefixes the width: alignment `<` `^` `>` (horizontal),
+  `.<` `.^` `.>` (vertical), and a style suffix:
+
+| suffix | cell content treated as                          |
+| ------ | ------------------------------------------------ |
+| `a`    | AsciiDoc — the only way to nest blocks in a cell |
+| `l`    | literal                                          |
+| `m`    | monospace                                        |
+| `h`    | header                                           |
+| `s`    | strong                                           |
+| `d`    | default (prose)                                  |
+
+- Spans: `2+|` spans two columns, `.3+|` three rows, `2.3+|` both. `3*|` duplicates a
+  cell across three columns.
+- A cell containing a `|` needs it escaped as `\|`.
+
+`tables/build-a-basic-table/`, `tables/format-column-content/`, `tables/span-cells/`,
+`tables/table-ref/`
+
+## Includes
+
+```adoc
+include::partial$intro.adoc[]
+include::example$config.json[]
+include::partial$file.adoc[tag=setup]
+include::example$app.ts[lines=10..20]
+include::partial$chapter.adoc[leveloffset=+1]
+include::example$snippet.js[indent=0]
+```
+
+Tagged regions are marked in the _included_ file with comments in that file's own comment
+syntax:
+
+```js
+// tag::setup[]
+const app = createApp()
+// end::setup[]
+```
+
+- `leveloffset=+1` demotes every section title in the included file — required when
+  including a file that has its own `=` title.
+- `indent=0` normalises leading whitespace, so a tagged region extracted from indented
+  code renders flush left.
+- Antora restricts targets to the resource families. `include::../other.adoc[]` and
+  `include::https://…[]` do not work.
+
+`directives/include/`, `directives/include-tagged-regions/`,
+`directives/include-lines/`, `directives/include-with-leveloffset/`
+
+## Conditionals
+
+```adoc
+ifdef::experimental[]
+Shown when the attribute is set.
+endif::[]
+
+ifndef::backend-html5[]
+Shown when it is not set.
+endif::[]
+
+ifeval::[{sectnumlevels} > 2]
+Shown when the expression is true.
+endif::[]
+```
+
+`ifdef::attr-one,attr-two[]` is OR; `ifdef::attr-one+attr-two[]` is AND. The single-line
+form `ifdef::attr[content]` exists for one line of content.
+
+`directives/conditionals/`, `directives/ifdef-ifndef/`, `directives/ifeval/`
+
+## Substitutions
+
+Applied to normal blocks in this fixed order:
+
+1. `specialchars` — `<`, `>`, `&` escaped
+2. `quotes` — the formatting marks above
+3. `attributes` — `{name}` references resolved
+4. `replacements` — `(C)`, `--`, `...` and friends
+5. `macros` — link, image, icon, xref
+6. `post_replacements` — the `+` line break
+
+Verbatim blocks (`----`, `....`) get `specialchars` and `callouts` only. Passthrough gets
+nothing.
+
+Override per block or per inline span:
+
+```adoc
+[subs="attributes+"]                incremental — add to the defaults
+[subs="+macros,-callouts"]          add one, remove another
+[subs="verbatim,quotes"]            absolute — replaces the defaults entirely
+```
+
+Escape a single substitution with a leading backslash (`\{attr}`, `\*not bold*`), or use
+an inline passthrough:
+
+```adoc
++literal text+                       no subs
+pass:[<b>raw</b>]                    no subs, raw output
+pass:attributes[{version}]           only the listed subs
+```
+
+`subs/`, `subs/apply-subs-to-blocks/`, `subs/prevent/`, `pass/`
+
+## Attributes
+
+```adoc
+:name: value
+:name!:                              unset
+:!name:                              unset, alternate form
+:name: {other} suffix                references resolve at definition time
+```
+
+Precedence, highest first: CLI/API → playbook `asciidoc.attributes` → `antora.yml` →
+page header. A playbook attribute ending in `@` becomes _soft-set_ and can be overridden
+by a page; without `@` it cannot.
+
+`attributes/document-attributes/`, `attributes/assignment-precedence/`,
+`attributes/document-attributes-ref/`
+
+## Other blocks worth knowing
+
+```adoc
+[%collapsible]
+====
+Rendered as a <details> element.
+====
+
+[quote,Author,Source]
+____
+Quotation.
+____
+
+[sidebar]                            or ****
+****
+Aside content.
+****
+
+--
+An open block — groups content with no semantics of its own. The usual way to
+attach several blocks to one list item.
+--
+
+toc::[]                              macro TOC; needs :toc: in the header
+```
+
+`blocks/collapsible/`, `blocks/blockquotes/`, `blocks/sidebars/`, `blocks/open-blocks/`,
+`toc/`
+
+## URL index — the long tail
+
+Not summarised above; fetch when needed.
+
+| topic                                                         | page                                    |
+| ------------------------------------------------------------- | --------------------------------------- |
+| Syntax quick reference                                        | `syntax-quick-reference/`               |
+| Document attributes reference (every built-in)                | `attributes/document-attributes-ref/`   |
+| Character replacements (`(C)`, `->`, …)                       | `attributes/character-replacement-ref/` |
+| Text span and built-in roles                                  | `text/text-span-built-in-roles/`        |
+| Quotation marks and apostrophes                               | `text/quotation-marks-and-apostrophes/` |
+| Footnotes                                                     | `macros/footnote/`                      |
+| Audio and video                                               | `macros/audio-and-video/`               |
+| SVG images                                                    | `macros/image-svg/`                     |
+| Image sizing / positioning reference                          | `macros/image-ref/`                     |
+| STEM (equations, formulas)                                    | `stem/`                                 |
+| Docinfo files                                                 | `docinfo/`                              |
+| Book parts, chapters, appendix, glossary, bibliography, index | `sections/styles/`                      |
+| Special section titles and numbering                          | `sections/special-section-titles/`      |
+| Verses                                                        | `blocks/verses/`                        |
+| CSV / TSV / DSV table data                                    | `tables/data-format/`                   |
+| Nested tables                                                 | `tables/nested/`                        |
+| Hard line breaks                                              | `blocks/hard-line-breaks/`              |
+| Discrete headings                                             | `blocks/discrete-headings/`             |
+| Preamble and lead style                                       | `blocks/preamble-and-lead/`             |
+| AsciiDoc vs Markdown                                          | `asciidoc-vs-markdown/`                 |
+| Glossary of terms                                             | `glossary/`                             |
+| FAQ                                                           | `faq/`                                  |
+
+Antora's own layer — resource IDs, families, nav, page attributes, the content catalog —
+is documented separately at `https://docs.antora.org/antora/latest/`.

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

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

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