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

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.5.0 - 2026-10-21
+
+### Added
+
+- `adoc-books.config.mjs` accepts `documentRoot`: how far books may include files, relative to the workspace root (default `.`). A workspace that lives inside a project repository declares the project root (`".."`) so books can include the project's own code. Reader source paths and the `// file:` markers of copied source are relative to it. It must be a path string that contains the workspace root.
+- `adoc-books.config.mjs` accepts `includeResolvers`: `{ prefix, resolve }` objects in the shape `asciidoc-abundant-tree` 0.2.1 accepts. One resolver serves both the HTML build and the reader data, so `include::<prefix>…[]` shows the same lines in both. The runtime checks that a resolver returns real lines of a file inside `documentRoot`; the Configure section of the default workspace README lists the rules a resolver follows.
+
+### Changed
+
+- Generated workspaces depend on `asciidoc-abundant-tree` `^0.2.1` (Asciidoctor.js 4 inside, asynchronous parsing). HTML is still rendered by `@asciidoctor/core` 3.
+- A book whose include graph `asciidoc-abundant-tree` cannot parse now fails `build` and `check`, and the error starts with the book id. Previously the runtime printed one warning and fell back to a cover-only reader page while the build succeeded. If a book includes files outside the workspace, declare `documentRoot`.
+- Xref targets and anchors are checked only on the generated HTML. The source-level codes `XREF_TARGET_MISSING` and `MISSING_ANCHOR` are gone; a missing target or anchor is reported as `HTML_RESOURCE_MISSING` or `HTML_ANCHOR_MISSING`. An xref to a non-entry `.adoc` file of another book (for example `parts/…/x.adoc`) now fails, because no HTML page is generated for it; link `book.adoc#<id>` instead.
+
+### Fixed
+
+- Cross-book xrefs to IDs declared as `[.role#id]`, `[[id]]`, `[id=id]`, or generated from a title no longer fail `check` with `MISSING_ANCHOR`.
+
+### Upgrading an existing workspace
+
+A generated workspace owns its `tools/adoc-books.mjs`. To adopt this release, create a temporary workspace with `pnpm create asciidoc-multi-book-workspace@0.5.0 tmp-books`, copy its `tools/adoc-books.mjs` over yours, set `"asciidoc-abundant-tree": "^0.2.1"` in your `package.json`, and run `pnpm install`.
+
+## 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/runtime/adoc-books.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -8,8 +9,6 @@ import { parseAbundantTree } from "asciidoc-abundant-tree";
 const require = createRequire(import.meta.url);
 const DIAGRAM_BLOCK_PATTERN = /^\[(?:actdiag|blockdiag|bpmn|bytefield|c4plantuml|d2|dbml|ditaa|erd|excalidraw|graphviz|mermaid|nomnoml|nwdiag|packetdiag|pikchr|plantuml|rackdiag|seqdiag|svgbob|symbolator|umlet|vega|vegalite|wavedrom|structurizr|diagramsnet|wireviz)(?:,|\])/m;
 const CATALOG_BOOK_XREF_PATTERN = /xref:books\/([^/\]]+)\/book\.adoc(?:#[^\[]+)?\[/g;
-const XREF_PATTERN = /xref:([^\[#]+)(?:#([A-Za-z0-9_-]+))?\[/g;
-const ANCHOR_PATTERN = /^\[#([A-Za-z0-9_-]+)(?:[.,][^\]]*)?\]$/gm;
 const LOCAL_TARGET_PATTERN = /\b(href|src)="([^"]+)"/g;
 const HTML_ANCHOR_PATTERN = /\b(?:id|name)="([^"]+)"/g;
 const SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
@@ -35,15 +34,12 @@ function stringValue(value, fallback) {
 }
 async function loadRuntimeConfig(rootDir) {
     const configPath = path.join(rootDir, CONFIG_FILE);
-    if (!await existsFile(configPath))
-        return DEFAULT_CONFIG;
-    const configUrl = pathToFileURL(configPath);
-    configUrl.search = `mtime=${(await stat(configPath)).mtimeMs}`;
-    const module = await import(configUrl.href);
-    const rawConfig = objectValue(module.default ?? module);
+    const rawConfig = await existsFile(configPath) ? await importConfig(configPath) : {};
     const rawRootIndex = objectValue(rawConfig.rootIndex);
     const rawHomeLink = objectValue(rawConfig.homeLink);
     return {
+        documentRoot: documentRootValue(rootDir, rawConfig.documentRoot),
+        includeResolvers: includeResolversValue(rawConfig.includeResolvers),
         rootIndex: {
             redirectTo: stringValue(rawRootIndex.redirectTo, DEFAULT_CONFIG.rootIndex.redirectTo),
             title: stringValue(rawRootIndex.title, DEFAULT_CONFIG.rootIndex.title)
@@ -54,6 +50,41 @@ async function loadRuntimeConfig(rootDir) {
         }
     };
 }
+async function importConfig(configPath) {
+    const configUrl = pathToFileURL(configPath);
+    configUrl.search = `mtime=${(await stat(configPath)).mtimeMs}`;
+    const module = await import(configUrl.href);
+    return objectValue(module.default ?? module);
+}
+// 相对工作区根解析：配置文件就在工作区根，".." 即项目根。书要 include ../../shared/attributes.adoc，所以根必须
+// 包含工作区；不合规的值直接报错，悄悄退回默认值时，使用者只会看到 include 越界，想不到是配置没生效。
+function documentRootValue(rootDir, value) {
+    if (value === undefined)
+        return rootDir;
+    if (typeof value !== "string" || value === "") {
+        throw new Error(`${CONFIG_FILE}: documentRoot must be a path string relative to the workspace root`);
+    }
+    const documentRoot = path.resolve(rootDir, value);
+    if (!isWithin(documentRoot, rootDir)) {
+        throw new Error(`${CONFIG_FILE}: documentRoot must contain the workspace root ${rootDir}, got ${documentRoot}`);
+    }
+    return documentRoot;
+}
+function isWithin(root, filePath) {
+    const relative = path.relative(root, filePath);
+    return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function includeResolversValue(value) {
+    if (value === undefined)
+        return [];
+    const valid = Array.isArray(value) && value.every((resolver) => {
+        const entry = objectValue(resolver);
+        return typeof entry.prefix === "string" && entry.prefix !== "" && typeof entry.resolve === "function";
+    });
+    if (!valid)
+        throw new Error(`${CONFIG_FILE}: includeResolvers must be an array of { prefix, resolve } objects`);
+    return value;
+}
 async function existsFile(filePath) {
     try {
         const stats = await stat(filePath);
@@ -138,6 +169,112 @@ function createAsciidoctor(loadKroki) {
     }
     return asciidoctor;
 }
+// 书架登记的 include 解析器，在 HTML 这一侧由 Asciidoctor 的 include 处理器调用；阅读数据一侧由 aat 调用同一份，
+// 两侧读同一份行（DESIGN.adoc 的 Workspace Configuration）。每次构建单独一个 registry：Asciidoctor 3 的全局扩展
+// 在进程里一直留着，登记在全局会把上一个工作区的解析器带进下一个。
+function includeResolverRegistry(asciidoctor, config) {
+    if (config.includeResolvers.length === 0)
+        return asciidoctor.Extensions.create();
+    const claiming = (target) => config.includeResolvers.find((resolver) => target.startsWith(resolver.prefix));
+    // 以分组登记：registry 每绑定一个文档就重置一次，只有分组会重新登记。catalog 与各本书共用这一个 registry，
+    // 直接调 registry.includeProcessor 时只有第一个文档用得上；之后的文档把 include::前缀:… 当作 URI，
+    // 悄悄转成链接，不报任何消息。
+    return asciidoctor.Extensions.create(function () {
+        this.includeProcessor(function () {
+            this.handles((target) => claiming(target) !== undefined);
+            this.process((document, reader, target, attributes) => {
+                const resolver = claiming(target);
+                const cursor = reader.getCursor();
+                const sourcePath = cursor.getFile();
+                // 游标已越过 directive 这一行。
+                const location = `include::${target}[] in ${sourcePath}: line ${cursor.getLineNumber() - 1}`;
+                let resolution;
+                try {
+                    resolution = resolver.resolve({
+                        target: target.slice(resolver.prefix.length),
+                        // aat 一侧对留空的位置属性同样交 null，它的类型声明没有写出来。
+                        attributes: includeAttributes(attributes),
+                        sourcePath
+                    });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`include resolver '${resolver.prefix}' failed for ${location}: ${message}`, { cause: error });
+                }
+                if (typeof objectValue(resolution).then === "function") {
+                    // 不再等它：它若 reject，没人接住就成了进程级的未处理 rejection。
+                    Promise.resolve(resolution).catch(() => { });
+                    throw new Error(`include resolver '${resolver.prefix}' returned a Promise for ${location}; ` +
+                        "the HTML build runs on Asciidoctor.js 3, whose include processors are synchronous");
+                }
+                const { text, absolutePath, startLine } = checkedResolution(resolution, config.documentRoot, `include resolver '${resolver.prefix}'`, location);
+                // 显示用的路径照 Asciidoctor 自己 include 文件时的写法，相对文档的 base_dir。
+                const displayPath = path.relative(document.getBaseDir(), absolutePath).split(path.sep).join("/");
+                reader.pushInclude(text, absolutePath, displayPath, startLine, attributes);
+            });
+        });
+    });
+}
+// 解析器交回的是来源文件里从 startLine 起连续的整行。这里逐行核对：两侧读同一份行的前提是 origin 就是 text 的
+// 出处——aat 把 origin 指向的文件全文收进复制纯文本，HTML 只用 text，两者对不上时构建也会成功，读者却看到两份
+// 不同的东西（aat 对此只报 warning）。
+function checkedResolution(resolution, documentRoot, who, location) {
+    const shaped = objectValue(resolution);
+    const origin = objectValue(shaped.origin);
+    const startLine = origin.startLine;
+    if (typeof shaped.text !== "string" || typeof origin.path !== "string" || !Number.isInteger(startLine) || startLine < 1) {
+        throw new Error(`${who} returned an invalid result for ${location}; expected { text, origin: { path, startLine } }`);
+    }
+    const absolutePath = path.resolve(documentRoot, origin.path);
+    // 来源是根之内的一个文件，不能是根本身；aat 同样拒绝。
+    if (absolutePath === documentRoot || !isWithin(documentRoot, absolutePath)) {
+        throw new Error(`${who} returned a source outside documentRoot ${documentRoot} for ${location}: ${absolutePath}`);
+    }
+    const text = withoutFinalNewline(shaped.text);
+    if (text !== "") {
+        const lines = text.split(/\r?\n/u);
+        let source;
+        try {
+            source = readFileSync(absolutePath, "utf8");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`${who} returned a source that cannot be read for ${location}: ${message}`, { cause: error });
+        }
+        const sourceLines = withoutFinalNewline(source).split(/\r?\n/u);
+        const first = startLine - 1;
+        const mismatch = lines.findIndex((line, index) => sourceLines[first + index] !== line);
+        if (mismatch !== -1) {
+            const lineNumber = first + mismatch + 1;
+            const detail = lineNumber > sourceLines.length
+                ? `the file has only ${sourceLines.length} lines`
+                : `line ${lineNumber} is ${shown(sourceLines[lineNumber - 1])}, the resolver returned ${shown(lines[mismatch])}`;
+            throw new Error(`${who} returned text that is not lines ${first + 1}-${first + lines.length} of ${absolutePath} for ${location}: ${detail}`);
+        }
+    }
+    return { text, absolutePath, startLine: startLine };
+}
+// 末尾的换行是最后一行的结束，不是多出来的一行：留着会让 Reader 多切出一个空行（aat 同样去掉一个）。来源文件按同一
+// 规则切行，文件最后一行之后才不会多出一个并不存在的空行。
+function withoutFinalNewline(text) {
+    return text.replace(/\r?\n$/u, "");
+}
+// 消息里的一行：截短，BOM 与控制字符写成可见的转义，行尾空白看得出来。
+function shown(line) {
+    const clipped = line.length > 60 ? `${line.slice(0, 60)}…` : line;
+    return JSON.stringify(clipped).replaceAll("", "\\uFEFF");
+}
+// Asciidoctor.js 3 把位置属性放在 $positional 列表里；aat 跑在 4 上，位置属性以 "1"、"2" 为键。
+// 解析器只认后一种形状，同一个解析器才能服务两侧。留空的位置属性（[,x]）在 3 里是 undefined、在 4 里是 null，
+// 这里交 null；中间留空（[a,,b]）时 3 已把空位丢掉、编号与 4 不同，无从还原，规约写明位置属性不能留空。
+function includeAttributes(attributes) {
+    const { $positional, ...named } = attributes;
+    const positional = Array.isArray($positional) ? $positional : [];
+    return {
+        ...Object.fromEntries(positional.map((value, index) => [String(index + 1), value === undefined ? null : String(value)])),
+        ...Object.fromEntries(Object.entries(named).map(([name, value]) => [name, String(value)]))
+    };
+}
 function shouldFetchDiagrams() {
     const value = process.env[FETCH_DIAGRAMS_ENV];
     return value === "1" || value === "true";
@@ -181,7 +318,7 @@ function formatAsciidoctorMessage(message) {
     const text = messageText(message);
     return location ? `${severity}: ${location}: ${text}` : `${severity}: ${text}`;
 }
-function convertFile(asciidoctor, input, outputFile, baseDir, attributes = {}) {
+function convertFile(asciidoctor, extensionRegistry, input, outputFile, baseDir, attributes = {}) {
     const loggerManager = asciidoctor.LoggerManager;
     const defaultLogger = loggerManager.getLogger();
     const memoryLogger = asciidoctor.MemoryLogger.create();
@@ -192,6 +329,7 @@ function convertFile(asciidoctor, input, outputFile, baseDir, attributes = {}) {
             base_dir: baseDir,
             to_file: outputFile,
             mkdirs: true,
+            extension_registry: extensionRegistry,
             attributes
         });
     }
@@ -203,13 +341,13 @@ function convertFile(asciidoctor, input, outputFile, baseDir, attributes = {}) {
         throw new Error(`AsciiDoc strict check failed for ${input}\n${messages.map(formatAsciidoctorMessage).join("\n")}`);
     }
 }
-async function buildHtml(rootDir, books, asciidoctor, useKroki, fetchDiagrams) {
+async function buildHtml(rootDir, books, asciidoctor, extensionRegistry, useKroki, fetchDiagrams) {
     await mkdir(path.join(rootDir, "build", "html"), { recursive: true });
-    convertFile(asciidoctor, path.join(rootDir, "catalog.adoc"), path.join(rootDir, "build", "html", "catalog.html"), rootDir);
+    convertFile(asciidoctor, extensionRegistry, path.join(rootDir, "catalog.adoc"), path.join(rootDir, "build", "html", "catalog.html"), rootDir);
     await pruneStaleBookHtmlDirs(rootDir, books);
     for (const book of books) {
         await mkdir(book.htmlOutputDir, { recursive: true });
-        convertFile(asciidoctor, book.input, path.join(book.htmlOutputDir, "book.html"), book.bookDir, {
+        convertFile(asciidoctor, extensionRegistry, book.input, path.join(book.htmlOutputDir, "book.html"), book.bookDir, {
             ...(useKroki && fetchDiagrams ? { "kroki-fetch-diagram": "", "kroki-http-method": "post" } : {})
         });
     }
@@ -316,50 +454,29 @@ function assertNoToolErrors(bookId, diagnostics) {
         }
     }
 }
-function sourceBundleFromDocument(document, fallbackPath, fallbackSource) {
+function sourceBundleFromDocument(document) {
     const sourceFiles = Array.isArray(document.sourceFiles) ? document.sourceFiles : [];
     const files = sourceFiles.filter((file) => typeof file.relativePath === "string" && typeof file.raw === "string");
-    if (files.length === 0)
-        return fallbackSource;
     return files.map((file) => {
         const body = file.raw?.endsWith("\n") ? file.raw : `${file.raw ?? ""}\n`;
-        return `// file: ${file.relativePath ?? fallbackPath}\n${body}`;
+        return `// file: ${file.relativePath}\n${body}`;
     }).join("\n");
 }
-function fallbackReaderBookData(rootDir, book, fallbackSource, reason) {
-    console.warn(`${book.bookId}: reader page map fell back to cover-only mode: ${reason}`);
-    const entry = path.relative(rootDir, book.input).split(path.sep).join("/");
-    return {
-        pageMap: {
-            version: 1,
-            book: {
-                id: book.bookId,
-                title: book.bookId,
-                entry
-            },
-            pages: [{
-                    id: "cover",
-                    kind: "cover",
-                    title: book.bookId,
-                    anchors: [],
-                    toc: []
-                }]
-        },
-        sourceBundle: fallbackSource
-    };
-}
-function buildReaderBookData(rootDir, book, fallbackSource) {
+// 解析失败就让构建失败，不退回只有封面的阅读页：退回时 include 越过 documentRoot 只剩一条 warning，
+// 构建照常成功，没有人发现阅读页坏了（DESIGN.adoc 的 Workspace Contract Checks）。
+async function buildReaderBookData(config, book) {
     let document;
     try {
-        document = parseAbundantTree({
+        document = await parseAbundantTree({
             sourcePath: book.input,
             mode: "book-entry",
-            documentRoot: rootDir
+            documentRoot: config.documentRoot,
+            includeResolvers: config.includeResolvers
         });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return fallbackReaderBookData(rootDir, book, fallbackSource, message);
+        throw new Error(`${book.bookId}: ${message}`, { cause: error });
     }
     const diagnostics = Array.isArray(document.toolDiagnostics) ? document.toolDiagnostics : [];
     assertNoToolErrors(book.bookId, diagnostics);
@@ -421,13 +538,13 @@ function buildReaderBookData(rootDir, book, fallbackSource) {
         book: {
             id: book.bookId,
             title: pages[0].title,
-            entry: path.relative(rootDir, book.input).split(path.sep).join("/")
+            entry: path.relative(config.documentRoot, book.input).split(path.sep).join("/")
         },
         pages
     };
     return {
         pageMap,
-        sourceBundle: sourceBundleFromDocument(document, pageMap.book.entry, fallbackSource)
+        sourceBundle: sourceBundleFromDocument(document)
     };
 }
 function readerStyles() {
@@ -943,15 +1060,14 @@ ${readerStyles()}
 <script>${readerScript()}</script>`;
     return `${html.slice(0, insertAt)}${withReaderScript}${html.slice(insertAt)}`;
 }
-async function addHomeLinks(rootDir, books, homeLink) {
+async function addHomeLinks(rootDir, books, config) {
     const catalog = path.join(rootDir, "build", "html", "catalog.html");
     for (const book of books) {
         const htmlFile = path.join(book.htmlOutputDir, "book.html");
         const html = await readFile(htmlFile, "utf8");
         const href = path.relative(path.dirname(htmlFile), catalog);
-        const fallbackSource = await combinedBookSource(book.bookDir);
-        const readerData = buildReaderBookData(rootDir, book, fallbackSource);
-        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, homeLink, readerData.sourceBundle, readerData.pageMap, book.bookId), "utf8");
+        const readerData = await buildReaderBookData(config, book);
+        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, config.homeLink, readerData.sourceBundle, readerData.pageMap, book.bookId), "utf8");
     }
 }
 async function writeRootIndex(rootDir, rootIndex) {
@@ -977,27 +1093,12 @@ function extractCatalogBookIds(catalogSource) {
         ids.add(match[1]);
     return [...ids].sort((a, b) => a.localeCompare(b));
 }
-function explicitAnchors(source) {
-    const anchors = new Set();
-    for (const match of source.matchAll(ANCHOR_PATTERN))
-        anchors.add(match[1]);
-    return anchors;
-}
-function attributesFromBookSource(bookSource) {
-    const attributes = new Map();
-    for (const line of bookSource.split(/\r?\n/)) {
-        const match = line.match(/^:([A-Za-z0-9_-]+):\s+(.+)$/);
-        if (match)
-            attributes.set(match[1], match[2]);
-    }
-    return attributes;
-}
-function expandXrefTarget(target, attributes) {
-    return target.replaceAll(/\{([A-Za-z0-9_-]+)\}/g, (_, name) => attributes.get(name) ?? `{${name}}`);
-}
 function issue(code, detail) {
     return { code, detail };
 }
+// xref 的目标与锚点不在这里查：Asciidoctor 把它们写成 HTML 里的链接与 ID，missingLocalResources 在生成的 HTML 上
+// 核对（DESIGN.adoc 的 Workspace Contract Checks）。ID 有 [#id]、[.role#id]、[[id]]、[id=id] 与标题生成等写法，
+// 只有 Asciidoctor 认得全。
 async function workspaceContractIssues(rootDir, books) {
     const issues = [];
     const catalogSource = await readIfExists(path.join(rootDir, "catalog.adoc"));
@@ -1014,31 +1115,8 @@ async function workspaceContractIssues(rootDir, books) {
     }
     for (const book of books) {
         const bookSource = await readFile(book.input, "utf8");
-        const allSource = await combinedBookSource(book.bookDir);
-        const attributes = attributesFromBookSource(bookSource);
         if (!/^:doctype:\s+book$/m.test(bookSource))
             issues.push(issue("MISSING_DOCTYPE", book.bookId));
-        for (const match of allSource.matchAll(XREF_PATTERN)) {
-            const [, target, anchor] = match;
-            if (/^https?:/.test(target))
-                continue;
-            const expandedTarget = expandXrefTarget(target, attributes);
-            if (!expandedTarget.endsWith(".adoc"))
-                continue;
-            const resolved = path.resolve(book.bookDir, expandedTarget);
-            if (!await existsFile(resolved)) {
-                issues.push(issue("XREF_TARGET_MISSING", `${book.bookId} -> ${expandedTarget}`));
-                if (anchor)
-                    issues.push(issue("MISSING_ANCHOR", `${book.bookId} -> ${expandedTarget}#${anchor}`));
-                continue;
-            }
-            if (anchor) {
-                const targetSource = await combinedBookSource(path.dirname(resolved));
-                if (!explicitAnchors(targetSource).has(anchor)) {
-                    issues.push(issue("MISSING_ANCHOR", `${book.bookId} -> ${expandedTarget}#${anchor}`));
-                }
-            }
-        }
     }
     return issues;
 }
@@ -1125,9 +1203,9 @@ export async function buildWorkspace(rootDir = process.cwd()) {
     const useKroki = await workspaceUsesDiagrams(rootDir, books);
     const fetchDiagrams = shouldFetchDiagrams();
     const asciidoctor = createAsciidoctor(useKroki);
-    await buildHtml(rootDir, books, asciidoctor, useKroki, fetchDiagrams);
+    await buildHtml(rootDir, books, asciidoctor, includeResolverRegistry(asciidoctor, config), useKroki, fetchDiagrams);
     await copyAssets(rootDir, books);
-    await addHomeLinks(rootDir, books, config.homeLink);
+    await addHomeLinks(rootDir, books, config);
     await writeRootIndex(rootDir, config.rootIndex);
     await assertNoIssues("HTML local resource check", await missingLocalResources(rootDir));
     await assertNoIssues("workspace contract check", await workspaceContractIssues(rootDir, books));

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.5.0",
   "description": "Create a complete AsciiDoc multi-book workspace.",
   "license": "Apache-2.0",
   "author": {
@@ -54,7 +54,7 @@
   "devDependencies": {
     "@asciidoctor/core": "^3.0.4",
     "@types/node": "^24.10.1",
-    "asciidoc-abundant-tree": "^0.1.18",
+    "asciidoc-abundant-tree": "^0.2.1",
     "asciidoctor-kroki": "^0.18.1",
     "playwright": "^1.59.1",
     "typescript": "^5.9.3"

package/templates/default-workspace/README.md

@@ -35,7 +35,50 @@ ADOC_BOOKS_FETCH_DIAGRAMS=1 pnpm run build
 pnpm run check
 ```
 
-This checks the current catalog, existing books, book doctypes, cross-book xrefs, anchors, and local HTML resources.
+This checks the current catalog, existing books, book doctypes, cross-book xrefs, anchors, and local HTML resources, and that every book's includes stay within `documentRoot` (see Configure).
+
+## Configure
+
+An optional `adoc-books.config.mjs` at the workspace root adjusts the build. Every key is optional:
+
+```js
+export default {
+  // Where build/html/index.html redirects, and its page title.
+  rootIndex: { redirectTo: "catalog.html", title: "My Books" },
+  // The catalog link at the top of every book.
+  homeLink: { label: "Back to catalog", subtitle: "My Books" },
+  // How far books may include files, relative to this directory. Default: "." (this workspace).
+  // documentRoot: "..",
+};
+```
+
+`documentRoot` matters when this workspace lives inside a project repository. Set it to the project root (`".."` when the workspace is a direct subdirectory) and books can include the project's own code instead of a copy of it. Source paths in the reader and the `// file:` markers of copied source then start at that root. It must contain this workspace. An include that leaves `documentRoot` fails `pnpm run check` and names the book.
+
+`includeResolvers` lets books include lines chosen by your own code, for example one function out of a source file:
+
+```js
+import path from "node:path";
+
+export default {
+  includeResolvers: [{
+    prefix: "symbol:",
+    // include::symbol:src/math.ts[add] arrives as { target: "src/math.ts", attributes: { 1: "add" }, sourcePath }.
+    resolve({ target, attributes, sourcePath }) {
+      const file = path.resolve(import.meta.dirname, target); // this resolver reads targets from the workspace root
+      // ...read file and find the lines of the function named attributes[1]...
+      return { text, origin: { path: file, startLine } };
+    },
+  }],
+};
+```
+
+The same resolver serves the HTML build and the reader, so both show the same lines. When you write one:
+
+- End `prefix` with a separator such as `:`. Prefixes match the start of the include target, so `snip` would also take `include::snippets/x.adoc[]`.
+- Decide what `target` is relative to. The example uses the workspace root; for Asciidoctor's own rule use `path.dirname(sourcePath)`.
+- Return whole consecutive lines of one file inside `documentRoot`, that file's path (absolute, or relative to `documentRoot`), and the line number (from 1) where the text starts. The build checks that the text is exactly those lines of that file, trailing spaces and a leading byte order mark included, and names the first line that differs. Build messages about those lines point into the file. Copied source includes that whole file.
+- Return the result directly, not a Promise, and return the same result every time: `resolve` runs twice per directive, once for the HTML and once for the reader.
+- Attribute values are strings, except that an empty leading positional attribute (`[,x]`) is `null`. Do not leave a positional attribute empty between others (`[a,,b]`); the two sides would number them differently.
 
 ## Clean
 

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/default-workspace/package.json.template

@@ -13,7 +13,7 @@
   },
   "devDependencies": {
     "@asciidoctor/core": "^3.0.4",
-    "asciidoc-abundant-tree": "^0.1.18",
+    "asciidoc-abundant-tree": "^0.2.1",
     "asciidoctor-kroki": "^0.18.1"
   }
 }

package/templates/solo-workspace/README.md

@@ -0,0 +1,40 @@
+# 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
+```
+
+## Configure
+
+An optional `adoc-books.config.mjs` at the workspace root adjusts the build. When this workspace lives inside a
+project repository, declare the project root so books can include the project's own code:
+
+```js
+export default {
+  documentRoot: "..", // relative to this directory; default "."
+};
+```
+
+The file also accepts `rootIndex: { redirectTo, title }`, `homeLink: { label, subtitle }`, and
+`includeResolvers: [{ prefix, resolve }]` for include directives whose lines your own code selects.
+The rules a resolver follows are in the
+[Configure section of the default workspace README](https://github.com/MichengLiang/asciidoc-multi-book-workspace/blob/main/templates/default-workspace/README.md#configure).
+
+## 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 和附加字段的结构化写法。