create-asciidoc-multi-book-workspace 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0 - 2026-10-21
+
+### Added
+
+- Add `--solo` to the `create` command and export `initSoloWorkspace` from the package root: generate a workspace that contains only the structured writing conventions book, shelved as book 01.
+- Add the chapter "声明本书的约定" (declaring the book's conventions) to the structured writing conventions sample: `.convention` headings with `declares=roles|relations|values|fields` write a book's controlled vocabularies in the book itself, so readers, check scripts, and query tools read one source. A `fields` declaration can carry `id-prefix` for roles whose address labels are existing technical addresses.
+
+### Changed
+
+- Show in the structured writing conventions sample how a field value attaches a code block or table with `+`, and list every way a description list stops counting as fields: an unattached block, another block between the heading and the list, block attributes on the list, or a nested description list. It also shows how to keep a description list under a heading as body text.
+- State that a heading's role scope is a reading context: projection, checks, and query tools read only the role written on each heading.
+- Add a decision tree for declaring and maintaining conventions, and update the quick reference, glossary, and part introductions.
+
 ## 0.3.1 - 2026-10-15
 
 ### Changed

package/README.md

@@ -13,6 +13,14 @@ pnpm install
 pnpm run build
 ```
 
+For a workspace with only the structured writing conventions book (shelved as book 01), add `--solo`:
+
+```bash
+pnpm create asciidoc-multi-book-workspace my-book --solo
+```
+
+See [Solo Workspace](#solo-workspace).
+
 npm users can run:
 
 ```bash
@@ -36,6 +44,8 @@ console.log(result.targetDir);
 
 The host CLI owns command parsing and user-facing output. This package owns the workspace files it creates.
 
+`initSoloWorkspace` takes the same options and creates the [solo workspace](#solo-workspace).
+
 The generated workspace contains:
 
 ```text
@@ -58,6 +68,23 @@ shared/images/workspace-map.svg
 
 It does not include this repository's `test/`, `.github/`, `src/`, `dist/`, `DESIGN.adoc`, or maintainer release checks.
 
+## Solo Workspace
+
+The solo workspace holds one book: sample book `07-structured-writing-conventions`, shelved as
+`books/01-structured-writing-conventions`, with a short catalog and README written for it:
+
+```text
+README.md
+catalog.adoc
+package.json
+.gitignore
+tools/adoc-books.mjs
+books/01-structured-writing-conventions
+shared/attributes.adoc
+```
+
+The other sample books stay in the template and are generated only by the default workspace.
+
 ## Generated Workspace
 
 The generated `package.json` directly lists the AsciiDoc toolchain:
@@ -81,6 +108,7 @@ pnpm run clean
 ```text
 src/                         # TypeScript initializer and user runtime source
 templates/default-workspace/ # true source for the generated user workspace
+templates/solo-workspace/    # catalog and README written for the solo workspace
 test/                        # maintainer tests
 DESIGN.adoc                  # maintainer design specification
 .github/                     # maintainer CI

package/dist/create.js

@@ -1,13 +1,20 @@
 #!/usr/bin/env node
 import path from "node:path";
-import { initWorkspace } from "./init-workspace.js";
+import { initSoloWorkspace, initWorkspace } from "./init-workspace.js";
 function usage() {
     return [
         "Usage:",
-        "  create-asciidoc-multi-book-workspace <target>",
+        "  create-asciidoc-multi-book-workspace <target> [--solo] [--force]",
+        "",
+        "Options:",
+        "  --solo   one book only: the structured writing conventions sample, shelved as",
+        "           books/01-structured-writing-conventions",
+        "  --force  write into a non-empty target; template output paths are overwritten,",
+        "           other files are kept",
         "",
         "Examples:",
         "  pnpm create asciidoc-multi-book-workspace my-books",
+        "  pnpm create asciidoc-multi-book-workspace my-book --solo",
         "  npm create asciidoc-multi-book-workspace@latest my-books"
     ].join("\n");
 }
@@ -23,7 +30,8 @@ async function main() {
         process.exitCode = 1;
         return;
     }
-    const result = await initWorkspace({ targetDir: target, force: args.includes("--force") });
+    const init = args.includes("--solo") ? initSoloWorkspace : initWorkspace;
+    const result = await init({ targetDir: target, force: args.includes("--force") });
     const displayTarget = path.relative(process.cwd(), result.targetDir) || ".";
     console.log(`Created AsciiDoc multi-book workspace in ${displayTarget}`);
     console.log("");

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { initWorkspace } from "./init-workspace.js";
+export { initSoloWorkspace, initWorkspace } from "./init-workspace.js";
 export type { InitWorkspaceOptions, InitWorkspaceResult } from "./init-workspace.js";

package/dist/index.js

@@ -1 +1 @@
-export { initWorkspace } from "./init-workspace.js";
+export { initSoloWorkspace, initWorkspace } from "./init-workspace.js";

package/dist/init-workspace.d.ts

@@ -7,3 +7,4 @@ export interface InitWorkspaceResult {
     packageName: string;
 }
 export declare function initWorkspace(options: InitWorkspaceOptions): Promise<InitWorkspaceResult>;
+export declare function initSoloWorkspace(options: InitWorkspaceOptions): Promise<InitWorkspaceResult>;

package/dist/init-workspace.js

@@ -1,10 +1,10 @@
 import { cp, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { defaultWorkspaceTemplate, templatePackageNamePlaceholder } from "./template-manifest.js";
+import { defaultWorkspaceCopies, packageJsonTemplate, soloWorkspaceCopies, templatePackageNamePlaceholder } from "./template-manifest.js";
 const sourceDir = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(sourceDir, "..");
-const templateRoot = path.join(packageRoot, "templates", defaultWorkspaceTemplate);
+const templatesRoot = path.join(packageRoot, "templates");
 const runtimeScript = path.join(packageRoot, "dist", "runtime", "adoc-books.mjs");
 async function exists(filePath) {
     try {
@@ -32,27 +32,29 @@ function safePackageName(rawName) {
         .replaceAll(/^-+|-+$/g, "");
     return normalized || "asciidoc-books";
 }
-async function copyTemplatePath(name, targetDir) {
-    await cp(path.join(templateRoot, name), path.join(targetDir, name), {
-        force: true,
-        recursive: true
-    });
-}
-export async function initWorkspace(options) {
+async function createWorkspace(options, copies) {
     const targetDir = path.resolve(options.targetDir);
     const targetExists = await exists(targetDir);
     if (targetExists && !options.force && !await isEmptyDirectory(targetDir)) {
         throw new Error(`target directory is not empty: ${targetDir}`);
     }
     await mkdir(targetDir, { recursive: true });
-    for (const name of ["README.md", "catalog.adoc", "books", "shared"]) {
-        await copyTemplatePath(name, targetDir);
+    for (const { from, to } of copies) {
+        await cp(path.join(templatesRoot, from), path.join(targetDir, to), {
+            force: true,
+            recursive: true
+        });
     }
-    const packageTemplate = await readFile(path.join(templateRoot, "package.json.template"), "utf8");
+    const packageTemplate = await readFile(path.join(templatesRoot, packageJsonTemplate), "utf8");
     const packageName = safePackageName(path.basename(targetDir));
     await writeFile(path.join(targetDir, "package.json"), packageTemplate.replaceAll(templatePackageNamePlaceholder, packageName), "utf8");
-    await writeFile(path.join(targetDir, ".gitignore"), await readFile(path.join(templateRoot, "gitignore.template"), "utf8"), "utf8");
     await mkdir(path.join(targetDir, "tools"), { recursive: true });
     await cp(runtimeScript, path.join(targetDir, "tools", "adoc-books.mjs"), { force: true });
     return { targetDir, packageName };
 }
+export async function initWorkspace(options) {
+    return createWorkspace(options, defaultWorkspaceCopies);
+}
+export async function initSoloWorkspace(options) {
+    return createWorkspace(options, soloWorkspaceCopies);
+}

package/dist/template-manifest.d.ts

@@ -1,3 +1,10 @@
-export declare const defaultWorkspaceTemplate = "default-workspace";
+export interface TemplateCopy {
+    /** Path under `templates/`. */
+    from: string;
+    /** Path inside the generated workspace. */
+    to: string;
+}
 export declare const templatePackageNamePlaceholder = "{{name}}";
-export declare const fixedTemplateOutputPaths: readonly ["README.md", "catalog.adoc", "package.json", ".gitignore", "tools/adoc-books.mjs", "books", "shared"];
+export declare const packageJsonTemplate = "default-workspace/package.json.template";
+export declare const defaultWorkspaceCopies: readonly TemplateCopy[];
+export declare const soloWorkspaceCopies: readonly TemplateCopy[];

package/dist/template-manifest.js

@@ -1,11 +1,26 @@
-export const defaultWorkspaceTemplate = "default-workspace";
 export const templatePackageNamePlaceholder = "{{name}}";
-export const fixedTemplateOutputPaths = [
-    "README.md",
-    "catalog.adoc",
-    "package.json",
-    ".gitignore",
-    "tools/adoc-books.mjs",
-    "books",
-    "shared"
+// Rendered with the target's package name instead of copied, so it stays outside the copy
+// tables; every workspace shape renders this same file.
+export const packageJsonTemplate = "default-workspace/package.json.template";
+// A copy table is the complete list of template content a workspace shape receives;
+// the initializer adds only the rendered package.json and tools/adoc-books.mjs.
+// `gitignore.template` exists because npm drops `.gitignore` files from published packages.
+export const defaultWorkspaceCopies = [
+    { from: "default-workspace/README.md", to: "README.md" },
+    { from: "default-workspace/catalog.adoc", to: "catalog.adoc" },
+    { from: "default-workspace/books", to: "books" },
+    { from: "default-workspace/shared", to: "shared" },
+    { from: "default-workspace/gitignore.template", to: ".gitignore" }
+];
+// One book on its own shelf: sample book 07 is shelved as 01. The catalog and README are
+// written for this shelf; shared/images/ stays behind because only the sample catalog uses it.
+export const soloWorkspaceCopies = [
+    { from: "solo-workspace/README.md", to: "README.md" },
+    { from: "solo-workspace/catalog.adoc", to: "catalog.adoc" },
+    {
+        from: "default-workspace/books/07-structured-writing-conventions",
+        to: "books/01-structured-writing-conventions"
+    },
+    { from: "default-workspace/shared/attributes.adoc", to: "shared/attributes.adoc" },
+    { from: "default-workspace/gitignore.template", to: ".gitignore" }
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciidoc-multi-book-workspace",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Create a complete AsciiDoc multi-book workspace.",
   "license": "Apache-2.0",
   "author": {

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/appendix-a.adoc

@@ -44,9 +44,15 @@
 |`[.example, owner=writing-team]`
 |role 和 named attributes 保留标题的作用与附加字段。
 
+|`[.convention, declares=roles]`
+|约定声明。标题下的描述列表是本书的 role 词表；`declares` 还可以取 `relations`、`values`（配 `for` 与 `field`）和 `fields`（配 `for`）。
+
 |`summary::` + 下一行说明文本
 |标题下描述列表字段。用于较多字段或多行字段值。
 
+|字段文字之后的 `+` + 块
+|把代码块、表格等挂到字段上，块属于字段值。字段之间不插入不带 `+` 的块。
+
 |`pass:[xref:标题[显示文本]]`
 |显示为链接，投影为 references。
 

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/appendix-b-decision-trees.adoc

@@ -68,7 +68,8 @@
    └─ 是：评估语境连续性。
 
 2. 当前子标题承载的认知角色是否与父标题声明的 role 相同？
-   ├─ 是：不重复声明 role；下级标题默认属于同一角色范围。流程结束。
+   ├─ 是：写作时可以不重复声明 role，读者按语境理解为同一角色范围。
+   │      工具只读标题自己写下的 role：想让检查核对它的字段、让查询列出它，就自己写上 role。流程结束。
    └─ 否：从受控词表中选取匹配新语境的 role，显式写入当前标题 attrlist。
           该声明完成语境切换。流程结束。
 ----
@@ -116,8 +117,37 @@
    │      例如 `[owner=writing-team, status=active]`。流程结束。
    └─ 字段较多，或包含多行字段值：
           写入紧随标题下方的第一个连续描述列表。
-          例如 `key:: value`。流程结束。
+          例如 `key:: value`。进入块评估。
+
+3. 字段值是否需要附带代码块、表格或另一段正文？
+   ├─ 是：在字段文字之后写一行 `+`，再写块；块属于字段值。
+   │      字段之间不插入不带 `+` 的块，否则字段列表在块前结束。流程结束。
+   └─ 否：流程结束。
+----
+
+== 约定的声明与维护
+
+触发场景:: 作者为本书引入或修改 role、rel 谓词、字段取值或字段。
+
+[source,text]
 ----
+1. 本书是否已有对应的约定声明？
+   ├─ 是：在该声明的描述列表中增加、修改或删除 term；进入类型评估。
+   └─ 否：新建声明标题，放在读者最先读到约定的地方（例如前言里专设一节“本书的书写约定”），
+          写 `[.convention, declares=...]`；进入类型评估。
+
+2. 声明的是什么？
+   ├─ role：`declares=roles`。
+   ├─ rel 谓词：`declares=relations`。
+   ├─ 某个 role 的附加字段取值：`declares=values, for=<role>, field=<字段名>`。
+   └─ 某个 role 的标题下描述列表字段：`declares=fields, for=<role>`。
+
+3. term 是否写成写作时使用的那个词？
+   ├─ 否：去掉点号与反引号，例如 `.concept` 写成 `concept`；回到本步重新判断。
+   └─ 是：在描述中写出这个词的含义。流程结束。
+----
+
+约定变化时只改声明。检查脚本和查询工具从声明读出词表，不另外维护一份。
 
 == 源文件物理编排与编号运算
 

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/glossary.adoc

@@ -16,3 +16,4 @@ relation predicate:: xref `rel` 字段选择的边谓词。
 source heading:: xref 所在的标题。
 target heading:: xref selector 指向的标题。
 surface field:: 源文档表面的附加字段。标题字段可来自标题 attrlist 或标题下描述列表；xref 边字段来自 xref named attributes。
+约定声明:: 带 `.convention` role 的标题。`declares` 字段说明它声明 role、rel 谓词、字段取值还是字段；标题下的描述列表是词表，term 是词，描述是含义。

package/templates/default-workspace/books/07-structured-writing-conventions/book.adoc

@@ -60,6 +60,8 @@ include::parts/030-fields-and-terminology/010-surface-fields.adoc[]
 
 include::parts/030-fields-and-terminology/020-glossary.adoc[]
 
+include::parts/030-fields-and-terminology/030-declaring-conventions.adoc[]
+
 [appendix]
 include::backmatter/appendix-a.adoc[]
 

package/templates/default-workspace/books/07-structured-writing-conventions/parts/010-source-surface/020-heading-address-and-xref.adoc

@@ -39,7 +39,7 @@
 2. 按照书籍结构，跨越 `= 书名`、`= 卷/部`、`== 章` 这些大跨度的指代均需要使用 `xref` 手动标注，平衡隐式上下文的阅读压力。
 ====
 
-标题声明角色后，其下级标题默认属于同一角色范围。下级标题可声明不同角色以切换语境。
+标题声明角色后，其下级标题默认属于同一角色范围。下级标题可声明不同角色以切换语境。角色范围是阅读上的语境；投影、检查和查询工具只读标题自己写下的 role，下级标题不会因此被当作同一 role 的标题核对字段或列出。
 
 例如:
 

package/templates/default-workspace/books/07-structured-writing-conventions/parts/020-names-roles-and-relations/020-heading-roles.adoc

@@ -32,4 +32,6 @@ role 写在标题 attrlist 的点号 token 位置。
 
 一本书使用的 role 种类和数量，取决于该领域的概念结构。每种 role 的语义在全书中保持唯一。
 
+全书的 role 词表写成约定声明，见 xref:declaring-conventions[声明本书的约定]。
+
 读者和工具链可以依据 role 进行导航文本和提取结构。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/020-names-roles-and-relations/030-relation-predicate.adoc

@@ -13,6 +13,8 @@
 
 `rel` 可以被读者和工具当作关系谓词，所以在全书范围内，每种 `rel` 谓词的语义需要保持唯一且不变。
 
+全书采用的 rel 谓词写成约定声明，见 xref:declaring-conventions[声明本书的约定]。下面列出常用的几种：
+
 [horizontal]
 depends-on:: 当前标题的判断、规则或操作以目标标题为依据。阅读顺序和先读建议使用普通 xref 表达。
 illustrates:: 当前标题提供目标标题的示例。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-terminology/010-surface-fields.adoc

@@ -30,7 +30,31 @@ summary::
 示例规则正文从这里开始。
 ----
 
-`priority:: normal` 和 `summary::` 属于 `示例规则` 标题的附加字段。投影时它们成为标题字段，例如 `aat:priority` 和 `aat:summary`。
+`priority:: normal` 和 `summary::` 属于 `示例规则` 标题的附加字段。投影时它们成为标题字段，例如 `aat:priority` 和 `aat:summary`；`情况` 这样不是 ASCII 标识符的字段名投影为 `aat:field-` 加百分号编码。
+
+字段值需要附带代码块、表格或另一段正文时，用 `+` 把块挂到字段上。挂上来的块属于这个字段的值。
+
+[source,asciidoc]
+------
+[.rule, verdict=adapt]
+== 关闭标签
+
+情况:: 关闭当前标签。
+规则:: 先结束输入法的组字，再关闭。
+出处:: `editorCommands.ts:835-839`。
++
+[source,ts]
+----
+closeActiveEditor()
+----
+判定:: 改写。
+------
+
+`出处` 的值是出处那一行文字和挂上来的代码块。字段值按作者写下的原文保存：反引号、xref 和 include 指令都保留原样。
+
+没有 `+` 的块不属于字段。字段列表在那个块之前结束，块和它之后的内容都是标题的正文；块之后再写的描述列表也不再是字段。字段之间需要代码时，用 `+` 挂上，不要直接插入代码块。
+
+另有三种写法让整串描述列表都不算字段，标题一个字段也得不到：标题与描述列表之间有别的块（段落、提示块、代码块、图片等）；描述列表带 style（如 `[horizontal]`）、ID、块标题或其他块属性；某个条目里嵌套了描述列表。这时描述列表是标题的正文。反过来，要让标题正下方的描述列表是正文而不是字段，就在它前面放一段导语，或给它加 `[horizontal]` 等 style。
 
 字段名和字段值来自本书自己的约定。同一本书使用附加字段时，应保持字段写法和字段含义稳定。
 

package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-terminology/030-declaring-conventions.adoc

@@ -0,0 +1,70 @@
+[#declaring-conventions]
+== 声明本书的约定
+
+一本书采用的 role、rel、字段取值和字段构成它的约定。约定写在书里：读者从这里知道每个词的含义，检查脚本和查询工具从同一处读出受控词表。词表只写这一处，书和工具不会各说各的。
+
+声明约定的标题带 `.convention` role 和 `declares` 字段。声明的内容写成标题下的第一个连续描述列表：每个 term 是一个词，描述是这个词的含义。
+
+[source,asciidoc]
+----
+[.convention, declares=roles]
+=== 标题的 role
+
+concept:: 概念：本书使用的一个词及其含义。
+rule:: 规则：一条可检查的写法规定。
+example:: 示例：用一个具体场景说明抽象判断。
+convention:: 约定：声明本书的 role、rel、字段取值或字段。
+
+[.convention, declares=relations]
+=== 关系谓词
+
+depends-on:: 当前标题的判断、规则或操作以目标标题为依据。
+illustrates:: 当前标题提供目标标题的示例。
+----
+
+`declares` 的取值说明描述列表里的 term 是什么：
+
+[horizontal]
+roles:: role 名称。写作时用在 `[.concept]` 的位置。
+relations:: rel 谓词。写作时用在 `rel=depends-on` 的位置。
+values:: 某个 role 的某个附加字段允许的取值。`for` 写这个 role，`field` 写字段名。
+fields:: 某个 role 的标题下描述列表要写出的字段。`for` 写这个 role。这个 role 的标题带显式寻址标签、标签本身又是已有的技术地址时（例如规则的标签同时是测试的名字），可以再写 `id-prefix`，规定标签的开头，例如 `id-prefix=rule-`；一旦写了，这个 role 的每个标题都要写出以它开头的标签。
+
+字段取值和字段用同样的写法声明：
+
+[source,asciidoc]
+----
+[.convention, declares=values, for=rule, field=verdict]
+==== 规则的判定
+
+adopt:: 照搬：理由成立，形式也照搬。
+adapt:: 改写：理由成立，形式换成本项目更顺手的写法。
+skip:: 不搬：只服务于原来的处境。
+
+[.convention, declares=fields, for=rule]
+==== 规则的格式
+
+情况:: 在什么情况下。
+规则:: 发生什么。
+出处:: 依据的源文件与行号。
+----
+
+`规则的判定` 说明：带 `.rule` 的标题写 `verdict` 字段，取值是 `adopt`、`adapt` 或 `skip`。`规则的格式` 说明：带 `.rule` 的标题，标题下的描述列表写出 `情况`、`规则` 和 `出处`。xref:surface-fields[附加字段] 中的 `关闭标签` 就是一条符合这两项声明的规则；它多写的 `判定` 字段不在声明里，声明只规定必须写出的字段。
+
+声明的写法：
+
+* term 写词本身：写 `concept`，不写 `.concept`，也不加反引号。term 就是写作时使用的那个词。
+* 声明的描述列表紧跟在声明标题之下，与标题之间没有别的块（段落、提示块、图片等）；它不带 `[horizontal]` 等 style，也不带 ID、块标题或其他块属性，条目里不嵌套描述列表。违反任何一条，整串描述列表都是正文，声明标题读不出任何词。导语写在上一级标题里。
+* 一个声明标题只声明一种内容。同一个 role 的取值和字段分开声明。
+* `convention` 本身也写进 role 词表，因为声明标题使用这个 role。
+
+声明通常放在读者最先读到约定的地方，例如前言里的“本书的书写约定”一节；某个 role 的格式也可以放在最先使用这个 role 的部分。工具按 `.convention` role 找到声明，不依赖位置。
+
+检查脚本读出声明以后，对每个带 role 的标题核对，不论它写没写寻址标签：
+
+* role 在 role 词表中。
+* `declares=values` 声明的字段写了，取值在列表中。没有声明的附加字段（如 `owner`）不受约束；`.convention` 标题例外，它只带 `declares`、`for`、`field` 和 `id-prefix`。
+* `declares=fields` 声明的字段全部写出。
+* 声明了 `id-prefix` 时，标题写出寻址标签，标签以它开头。
+
+正文中的每个 xref，若带 `rel`，谓词在关系谓词词表中。约定变化时只改声明，检查跟着变。

package/templates/default-workspace/books/07-structured-writing-conventions/parts/030-fields-and-terminology/_partintro.adoc

@@ -1 +1 @@
-字段补充标题与引用已经表达的内容；术语表统一全书采用的名称。
+字段补充标题与引用已经表达的内容；术语表统一全书采用的名称；约定声明把本书的 role、rel 和字段写成工具可读的词表。

package/templates/solo-workspace/README.md

@@ -0,0 +1,24 @@
+# My Books
+
+An AsciiDoc multi-book workspace that starts with one book: `books/01-structured-writing-conventions`.
+
+## Commands
+
+```bash
+pnpm install
+pnpm run build   # writes build/html/index.html
+pnpm run check   # checks the catalog, books, xrefs, anchors, and local HTML resources
+pnpm run clean   # removes build/
+```
+
+To fetch diagram images into the local HTML output instead of linking Kroki URLs:
+
+```bash
+ADOC_BOOKS_FETCH_DIAGRAMS=1 pnpm run build
+```
+
+## Add A Book
+
+Copy `books/01-structured-writing-conventions` to `books/<NN-book-id>`, edit its `book.adoc`, then add an
+`xref:books/<NN-book-id>/book.adoc[...]` line to `catalog.adoc`.
+`pnpm run check` fails until `catalog.adoc` and `books/` list the same books.

package/templates/solo-workspace/catalog.adoc

@@ -0,0 +1,7 @@
+= AsciiDoc 书架
+:idprefix:
+:idseparator: -
+
+== 书目
+
+* xref:books/01-structured-writing-conventions/book.adoc[01 结构化书写约定标本]：标题、引用、role、xref、rel 和附加字段的结构化写法。