@guiho/xdocs 0.3.0-alpha.2 → 0.4.2

package/library/agents.d.ts

@@ -38,7 +38,7 @@ export declare const detectAgentTools: (cwd: string) => XDocsAgentTool[];
  */
 export declare const resolveInstallTools: (cwd: string, toolFlag: string | undefined) => XDocsAgentTool[];
 /** The small AGENTS.md section announcing xdocs and pointing to the skill. */
-export declare const xdocsAgentsSection = "<!-- BEGIN XDOCS \u2014 DO NOT EDIT THIS SECTION -->\n## XDocs Structured Documentation\n\nThis project uses **xdocs** (`@guiho/xdocs`) for structured, machine-readable\ndocumentation. The repository has one root `XDOCS.md` index (no frontmatter),\nand each package/application has a root `.xdocs.md` file. Each module carries a\n`.docs.md` / `.xdocs.md` file with YAML frontmatter (`subject`, `description`,\n`parent`, `children`, `files`).\n\n**Load the `guiho-s-xdocs` agent skill** for any documentation work:\ncreating, updating, regenerating, scanning, merging, or navigating xdocs files.\nThe skill holds the full workflow, metadata schema, and CLI reference.\n\nBefore changing documentation, read `xdocs.config.toml` and respect `[ai].mode`:\n\n- **prompt** \u2014 announce which xdocs files need updating and wait for confirmation.\n- **auto** \u2014 update the relevant xdocs files immediately.\n\nUse the xdocs CLI for operations: `xdocs scan`, `xdocs tree`, `xdocs generate`,\n`xdocs list`, `xdocs merge`.\n<!-- END XDOCS -->";
+export declare const xdocsAgentsSection = "<!-- BEGIN XDOCS \u2014 DO NOT EDIT THIS SECTION -->\n## XDocs Structured Documentation\n\nThis project uses **xdocs** (`@guiho/xdocs`) for structured, machine-readable\ndocumentation. The repository has one root `XDOCS.md` index (no frontmatter),\nand each package/application has a root named `*.xdocs.md` descriptor file. Each\ndocumented module has exactly one named `*.xdocs.md` descriptor in its directory\nwith YAML frontmatter (`subject`, `description`, `parent`, `children`,\n`files`, `documents`, `tags`, `keywords`, `flags`). Same-directory plain\n`*.md` files are companion documents and must be listed in the descriptor's\n`documents` metadata map. Ordinary companion documents should also include\n`keywords` in their own frontmatter.\n\n**Load the `guiho-s-xdocs` agent skill** for any documentation work:\ncreating, updating, regenerating, scanning, merging, or navigating xdocs descriptors.\nThe skill holds the full workflow, metadata schema, and CLI reference.\n\nBefore changing documentation, read `xdocs.config.toml` and respect `[ai].mode`:\n\n- **prompt** \u2014 announce which xdocs descriptors need updating and wait for confirmation.\n- **auto** \u2014 update the relevant xdocs descriptors immediately.\n\nUse the xdocs CLI for operations: `xdocs scan`, `xdocs tree`, `xdocs generate`,\n`xdocs list`, `xdocs merge`.\n<!-- END XDOCS -->";
 type SkillPathOptions = {
     cwd?: string;
     homeDirectory?: string;
@@ -70,10 +70,9 @@ export declare const findAgentsFile: (cwd: string) => string | undefined;
 /** Resolve agent settings from the discovered xdocs config (defaults when absent). */
 export declare const resolveAgentSettings: (options: XDocsCliOptions) => Promise<XDocsAgentSettings>;
 /**
- * Config-gated automation run by normal commands. Does nothing outside an xdocs
- * project (no config discovered). When enabled, it keeps the AGENTS.md section
- * fresh (only if AGENTS.md already exists) and refreshes the global skill for
- * the configured tool from the bundled package copy.
+ * Agent automation run by bare and data commands. It always bootstraps the
+ * configured global skill from the bundled package copy; when config exists,
+ * it also keeps the AGENTS.md section fresh if enabled and AGENTS.md exists.
  */
 export declare const runAgentAutomation: (options: AgentAutomationOptions, notify?: (message: string) => void) => Promise<XDocsAgentAutomationResult>;
 /** Read a skill version from SKILL.md YAML frontmatter. */

package/library/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,eAAe,EACf,uBAAuB,EACvB,eAAe,EAChB,MAAM,YAAY,CAAA;AAInB,+CAA+C;AAC/C,eAAO,MAAM,cAAc,kBAAkB,CAAA;AAE7C,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAuB,CAAA;AAE1E;;iEAEiE;AACjE,eAAO,MAAM,iBAAiB,EAAE,MAS5B,CAAA;AAEJ,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,oBAAsC,CAAA;AAEpE,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,SAAS,cAAc,EAAyB,CAAA;AAE9E,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,EAAE,cAAyB,CAAA;AAEzD,2FAA2F;AAC3F,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,cAAc,EAKzE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,cAAc,EAK5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,EAAE,UAAU,MAAM,GAAG,SAAS,KAAG,cAAc,EAChC,CAAA;AAkB9D,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,mhCAoBV,CAAA;AAErB,KAAK,gBAAgB,GAAG;IACtB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,KAAK,mBAAmB,GAAG,gBAAgB,GAAG;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,sBAAsB,GAAG,eAAe,GAAG;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,MACnD,CAAA;AAO7D,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,OAC5D,CAAA;AAEpD,kEAAkE;AAClE,eAAO,MAAM,YAAY,GACvB,MAAM,cAAc,EACpB,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,CA6BjC,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,aAAa,GACxB,OAAO,SAAS,cAAc,EAAE,EAChC,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,EAAE,CAInC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAU,KAAK,MAAM,EAAE,gBAAc,KAAG,OAAO,CAAC,6BAA6B,CAkBjH,CAAA;AA4BD,sDAAsD;AACtD,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAWrD,CAAA;AAED,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,kBAAkB,CAI/F,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,sBAAsB,EAC/B,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,0BAA0B,CAmBpC,CAAA;AAED,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpE"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,eAAe,EACf,uBAAuB,EACvB,eAAe,EAChB,MAAM,YAAY,CAAA;AAInB,+CAA+C;AAC/C,eAAO,MAAM,cAAc,kBAAkB,CAAA;AAE7C,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAuB,CAAA;AAE1E;;iEAEiE;AACjE,eAAO,MAAM,iBAAiB,EAAE,MAS5B,CAAA;AAEJ,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,oBAAsC,CAAA;AAEpE,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,SAAS,cAAc,EAAyB,CAAA;AAE9E,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,EAAE,cAAyB,CAAA;AAEzD,2FAA2F;AAC3F,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,cAAc,EAKzE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,cAAc,EAK5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,EAAE,UAAU,MAAM,GAAG,SAAS,KAAG,cAAc,EAChC,CAAA;AAkB9D,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,w1CAwBV,CAAA;AAErB,KAAK,gBAAgB,GAAG;IACtB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,KAAK,mBAAmB,GAAG,gBAAgB,GAAG;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,sBAAsB,GAAG,eAAe,GAAG;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,MACnD,CAAA;AAO7D,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,OAC5D,CAAA;AAEpD,kEAAkE;AAClE,eAAO,MAAM,YAAY,GACvB,MAAM,cAAc,EACpB,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,CA6BjC,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,aAAa,GACxB,OAAO,SAAS,cAAc,EAAE,EAChC,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,EAAE,CAInC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAU,KAAK,MAAM,EAAE,gBAAc,KAAG,OAAO,CAAC,6BAA6B,CAkBjH,CAAA;AA4BD,sDAAsD;AACtD,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAWrD,CAAA;AAED,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,kBAAkB,CAI/F,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,sBAAsB,EAC/B,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,0BAA0B,CAgBpC,CAAA;AAED,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpE"}

package/library/agents.js

@@ -86,18 +86,22 @@ export const xdocsAgentsSection = `${AGENTS_BEGIN_MARKER}
 
 This project uses **xdocs** (\`@guiho/xdocs\`) for structured, machine-readable
 documentation. The repository has one root \`XDOCS.md\` index (no frontmatter),
-and each package/application has a root \`.xdocs.md\` file. Each module carries a
-\`.docs.md\` / \`.xdocs.md\` file with YAML frontmatter (\`subject\`, \`description\`,
-\`parent\`, \`children\`, \`files\`).
+and each package/application has a root named \`*.xdocs.md\` descriptor file. Each
+documented module has exactly one named \`*.xdocs.md\` descriptor in its directory
+with YAML frontmatter (\`subject\`, \`description\`, \`parent\`, \`children\`,
+\`files\`, \`documents\`, \`tags\`, \`keywords\`, \`flags\`). Same-directory plain
+\`*.md\` files are companion documents and must be listed in the descriptor's
+\`documents\` metadata map. Ordinary companion documents should also include
+\`keywords\` in their own frontmatter.
 
 **Load the \`${xdocsSkillName}\` agent skill** for any documentation work:
-creating, updating, regenerating, scanning, merging, or navigating xdocs files.
+creating, updating, regenerating, scanning, merging, or navigating xdocs descriptors.
 The skill holds the full workflow, metadata schema, and CLI reference.
 
 Before changing documentation, read \`xdocs.config.toml\` and respect \`[ai].mode\`:
 
-- **prompt** — announce which xdocs files need updating and wait for confirmation.
-- **auto** — update the relevant xdocs files immediately.
+- **prompt** — announce which xdocs descriptors need updating and wait for confirmation.
+- **auto** — update the relevant xdocs descriptors immediately.
 
 Use the xdocs CLI for operations: \`xdocs scan\`, \`xdocs tree\`, \`xdocs generate\`,
 \`xdocs list\`, \`xdocs merge\`.
@@ -208,19 +212,16 @@ export const resolveAgentSettings = async (options) => {
     return normalizeAgentSettings(discovered.raw?.agents);
 };
 /**
- * Config-gated automation run by normal commands. Does nothing outside an xdocs
- * project (no config discovered). When enabled, it keeps the AGENTS.md section
- * fresh (only if AGENTS.md already exists) and refreshes the global skill for
- * the configured tool from the bundled package copy.
+ * Agent automation run by bare and data commands. It always bootstraps the
+ * configured global skill from the bundled package copy; when config exists,
+ * it also keeps the AGENTS.md section fresh if enabled and AGENTS.md exists.
  */
 export const runAgentAutomation = async (options, notify = () => { }) => {
     const cwd = resolve(options.cwd);
     const discovered = await discoverConfig(cwd, options.config);
-    if (!discovered.raw)
-        return { settings: { ...normalizeAgentSettings(undefined) } };
-    const settings = normalizeAgentSettings(discovered.raw.agents);
+    const settings = normalizeAgentSettings(discovered.raw?.agents);
     const result = { settings };
-    if (settings.autoAgentsMd)
+    if (discovered.raw && settings.autoAgentsMd)
         result.agentsMd = await ensureAgentsInstructions(cwd, false);
     if (settings.autoSkillInstall) {
         const globalSkill = await installSkill(settings.skillTool, 'global', { cwd, homeDirectory: options.homeDirectory });

package/library/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAsBH,4BAA4B;AAC5B,eAAO,MAAM,MAAM,GAAU,UAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,IAAI,CA4DpF,CAAA;AAmBD,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,GAAU,UAAU,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAiB9E,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAsBH,4BAA4B;AAC5B,eAAO,MAAM,MAAM,GAAU,UAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,IAAI,CA6DpF,CAAA;AAmBD,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,GAAU,UAAU,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAiB9E,CAAA"}

package/library/cli.js

@@ -33,14 +33,15 @@ export const runCli = async (rawArgs = process.argv.slice(2)) => {
         }
         return;
     }
+    if (parsed.command && !validCommands.has(parsed.command)) {
+        throw new XDocsError(`Unknown command: ${parsed.command}\n\nRun \`xdocs --help\` for available commands.`);
+    }
+    const options = resolveOptions(parsed.flags);
     if (!parsed.command) {
+        await runAgentAutomation(options, (message) => process.stderr.write(message + '\n'));
         process.stdout.write(showHelp() + '\n');
         return;
     }
-    if (!validCommands.has(parsed.command)) {
-        throw new XDocsError(`Unknown command: ${parsed.command}\n\nRun \`xdocs --help\` for available commands.`);
-    }
-    const options = resolveOptions(parsed.flags);
     const command = parsed.command;
     if (automationCommands.has(command)) {
         await runAgentAutomation(options, (message) => process.stderr.write(message + '\n'));

package/library/commands/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../source/commands/generate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAMnE,gCAAgC;AAChC,eAAO,MAAM,WAAW,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CA2BjG,CAAA"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../source/commands/generate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAa,eAAe,EAAE,MAAM,aAAa,CAAA;AAM9E,gCAAgC;AAChC,eAAO,MAAM,WAAW,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CA2BjG,CAAA"}

package/library/commands/generate.js

@@ -55,6 +55,9 @@ const generateProjectDoc = async (projectName, xdocsFiles, _cwd) => {
         lines.push(`### ${file.metadata.subject}`, '');
         lines.push(file.metadata.description, '');
         lines.push(`Location: \`${file.relativePath}\``, '');
+        if (file.metadata.keywords.length > 0) {
+            lines.push(`Keywords: ${file.metadata.keywords.map((keyword) => `\`${keyword}\``).join(', ')}`, '');
+        }
         const fileEntries = Object.entries(file.metadata.files);
         if (fileEntries.length > 0) {
             lines.push('Files:', '');
@@ -63,6 +66,14 @@ const generateProjectDoc = async (projectName, xdocsFiles, _cwd) => {
             }
             lines.push('');
         }
+        const documentEntries = Object.entries(file.metadata.documents);
+        if (documentEntries.length > 0) {
+            lines.push('Documents:', '');
+            for (const [name, desc] of documentEntries) {
+                lines.push(`- \`${name}\`: ${desc}`);
+            }
+            lines.push('');
+        }
         if (file.body.trim()) {
             lines.push(file.body.trim(), '');
         }
@@ -90,6 +101,9 @@ const generateModuleDoc = async (moduleName, xdocsFiles, _cwd, targetPath) => {
                 continue;
             lines.push(`## ${file.metadata.subject}`, '');
             lines.push(file.metadata.description, '');
+            if (file.metadata.keywords.length > 0) {
+                lines.push(`Keywords: ${file.metadata.keywords.map((keyword) => `\`${keyword}\``).join(', ')}`, '');
+            }
             const fileEntries = Object.entries(file.metadata.files);
             if (fileEntries.length > 0) {
                 lines.push('### Files', '');
@@ -98,6 +112,14 @@ const generateModuleDoc = async (moduleName, xdocsFiles, _cwd, targetPath) => {
                 }
                 lines.push('');
             }
+            const documentEntries = Object.entries(file.metadata.documents);
+            if (documentEntries.length > 0) {
+                lines.push('### Documents', '');
+                for (const [name, desc] of documentEntries) {
+                    lines.push(`- \`${name}\`: ${desc}`);
+                }
+                lines.push('');
+            }
             if (file.metadata.children.length > 0) {
                 lines.push('### Submodules', '');
                 for (const child of file.metadata.children) {
@@ -111,7 +133,7 @@ const generateModuleDoc = async (moduleName, xdocsFiles, _cwd, targetPath) => {
         }
     }
     else {
-        lines.push(`No xdocs files found in this directory.`, '');
+        lines.push(`No xdocs descriptors found in this directory.`, '');
         lines.push('### Directory contents', '');
         for (const entry of dirEntries) {
             lines.push(`- \`${entry}\``);

package/library/commands/list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../source/commands/list.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAInE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CA2C7F,CAAA"}
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../source/commands/list.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAInE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CAsD7F,CAAA"}

package/library/commands/list.js

@@ -10,13 +10,22 @@ export const runList = async (options, parsed) => {
     const targetPath = parsed.positionals[0] ? resolve(options.cwd, parsed.positionals[0]) : options.cwd;
     const result = await scanProject(config);
     const relevantFiles = result.xdocsFiles.filter((f) => f.path.startsWith(targetPath));
-    // Collect all files with descriptions from metadata
+    // Collect all source files and Markdown companion documents from metadata.
     const fileList = [];
     for (const xdocsFile of relevantFiles) {
         if (!xdocsFile.metadata)
             continue;
         for (const [fileName, description] of Object.entries(xdocsFile.metadata.files)) {
             fileList.push({
+                kind: 'file',
+                file: fileName,
+                description,
+                source: xdocsFile.relativePath,
+            });
+        }
+        for (const [fileName, description] of Object.entries(xdocsFile.metadata.documents)) {
+            fileList.push({
+                kind: 'document',
                 file: fileName,
                 description,
                 source: xdocsFile.relativePath,
@@ -29,13 +38,14 @@ export const runList = async (options, parsed) => {
     }
     if (fileList.length === 0) {
         const scope = targetPath === options.cwd ? 'project' : relative(options.cwd, targetPath);
-        process.stdout.write(`No documented files found in ${scope}.\n`);
+        process.stdout.write(`No documented files or documents found in ${scope}.\n`);
         return;
     }
     const scope = targetPath === options.cwd ? 'project' : relative(options.cwd, targetPath);
-    process.stdout.write(`\nfiles in ${scope}:\n\n`);
+    process.stdout.write(`\nentries in ${scope}:\n\n`);
     for (const entry of fileList) {
-        process.stdout.write(`  ${entry.file}: ${entry.description}\n`);
+        const label = entry.kind === 'document' ? 'document' : 'file';
+        process.stdout.write(`  ${label} ${entry.file}: ${entry.description}\n`);
     }
     process.stdout.write('\n');
 };

package/library/commands/merge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../source/commands/merge.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAKnE,6BAA6B;AAC7B,eAAO,MAAM,QAAQ,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CAyD9F,CAAA"}
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../source/commands/merge.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAKnE,6BAA6B;AAC7B,eAAO,MAAM,QAAQ,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CAsE9F,CAAA"}

package/library/commands/merge.js

@@ -14,7 +14,7 @@ export const runMerge = async (options, parsed) => {
     const result = await scanProject(config);
     const relevantFiles = result.xdocsFiles.filter((f) => f.path.startsWith(targetPath));
     if (relevantFiles.length === 0) {
-        process.stdout.write('No xdocs files found in the specified path.\n');
+        process.stdout.write('No xdocs descriptors found in the specified path.\n');
         return;
     }
     const lines = [];
@@ -23,6 +23,9 @@ export const runMerge = async (options, parsed) => {
         if (file.metadata) {
             lines.push(`# ${file.metadata.subject}`, '');
             lines.push(file.metadata.description, '');
+            if (file.metadata.keywords.length > 0) {
+                lines.push(`Keywords: ${file.metadata.keywords.map((keyword) => `\`${keyword}\``).join(', ')}`, '');
+            }
             const fileEntries = Object.entries(file.metadata.files);
             if (fileEntries.length > 0) {
                 lines.push('## Files', '');
@@ -31,6 +34,14 @@ export const runMerge = async (options, parsed) => {
                 }
                 lines.push('');
             }
+            const documentEntries = Object.entries(file.metadata.documents);
+            if (documentEntries.length > 0) {
+                lines.push('## Documents', '');
+                for (const [name, desc] of documentEntries) {
+                    lines.push(`- \`${name}\`: ${desc}`);
+                }
+                lines.push('');
+            }
             if (file.metadata.children.length > 0) {
                 lines.push('## Submodules', '');
                 for (const child of file.metadata.children) {

package/library/commands/scan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../source/commands/scan.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAInE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,SAAS,eAAe,KAAG,OAAO,CAAC,IAAI,CAqD9F,CAAA"}
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../source/commands/scan.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAInE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,SAAS,eAAe,KAAG,OAAO,CAAC,IAAI,CAiE9F,CAAA"}

package/library/commands/scan.js

@@ -11,25 +11,31 @@ export const runScan = async (options, _parsed) => {
         process.stdout.write(JSON.stringify({
             totalFiles: result.totalFiles,
             totalDirectories: result.totalDirectories,
+            totalMarkdownDocuments: result.totalMarkdownDocuments,
             coveredDirectories: result.coveredDirectories,
             uncoveredDirectories: result.uncoveredDirectories,
             xdocsFiles: result.xdocsFiles.map((f) => ({
                 path: f.relativePath,
                 valid: f.valid,
                 subject: f.metadata?.subject ?? null,
+                keywords: f.metadata?.keywords ?? null,
+                documents: f.metadata?.documents ?? null,
+                discoveredDocuments: f.documents.map((document) => document.relativePath),
                 errors: f.errors,
             })),
+            markdownDocuments: result.markdownDocuments.map((document) => document.relativePath),
             uncoveredPaths: result.uncoveredPaths,
         }, null, 2) + '\n');
         return;
     }
     process.stdout.write(`\nxdocs scan\n\n`);
-    process.stdout.write(`extensions: ${config.extensions.supported.join(', ')}\n`);
+    process.stdout.write(`descriptor extension: ${config.extensions.supported.join(', ')}\n`);
     process.stdout.write(`total files scanned: ${result.totalFiles}\n`);
     process.stdout.write(`total directories: ${result.totalDirectories}\n`);
+    process.stdout.write(`markdown documents found: ${result.totalMarkdownDocuments}\n`);
     process.stdout.write(`covered directories: ${result.coveredDirectories}\n`);
     process.stdout.write(`uncovered directories: ${result.uncoveredDirectories}\n`);
-    process.stdout.write(`xdocs files found: ${result.xdocsFiles.length}\n`);
+    process.stdout.write(`xdocs descriptors found: ${result.xdocsFiles.length}\n`);
     if (result.xdocsFiles.length > 0) {
         process.stdout.write(`\nfiles:\n`);
         for (const file of result.xdocsFiles) {
@@ -42,6 +48,11 @@ export const runScan = async (options, _parsed) => {
                     process.stdout.write(`    error: ${error}\n`);
                 }
             }
+            if (options.verbose && file.documents.length > 0) {
+                for (const document of file.documents) {
+                    process.stdout.write(`    document: ${document.name}\n`);
+                }
+            }
         }
     }
     if (options.verbose && result.uncoveredPaths.length > 0) {

package/library/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../source/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAA+B,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAU/H,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,EAAE,kBAIpC,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,GAAI,KAAK,cAAc,CAAC,QAAQ,CAAC,KAAG,kBAgBtE,CAAA;AAQD,2CAA2C;AAC3C,eAAO,MAAM,cAAc,GAAU,KAAK,MAAM,EAAE,eAAe,MAAM,KAAG,OAAO,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,cAAc,CAAA;CAAE,CAaxH,CAAA;AAED,kDAAkD;AAClD,eAAO,MAAM,UAAU,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,WAAW,CAS9E,CAAA;AAED,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,WAAW,CAOxF,CAAA;AAED,4DAA4D;AAC5D,eAAO,MAAM,eAAe,GAAI,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,aAAa,MAAM,KAAG,WA8BvF,CAAA;AAED,sDAAsD;AACtD,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,WAQ1C,CAAA;AAEF,sDAAsD;AACtD,eAAO,MAAM,0BAA0B,GAAI,KAAK,MAAM,KAAG,MAsBxD,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,GAAU,KAAK,MAAM,EAAE,mBAAiB,KAAG,OAAO,CAAC,MAAM,CASvF,CAAA;AAuBD,sDAAsD;AACtD,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,WACP,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../source/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAA+B,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAU/H,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,EAAE,kBAIpC,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,GAAI,KAAK,cAAc,CAAC,QAAQ,CAAC,KAAG,kBAgBtE,CAAA;AAQD,2CAA2C;AAC3C,eAAO,MAAM,cAAc,GAAU,KAAK,MAAM,EAAE,eAAe,MAAM,KAAG,OAAO,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,cAAc,CAAA;CAAE,CAaxH,CAAA;AAED,kDAAkD;AAClD,eAAO,MAAM,UAAU,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,WAAW,CAS9E,CAAA;AAED,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,WAAW,CAOxF,CAAA;AAED,4DAA4D;AAC5D,eAAO,MAAM,eAAe,GAAI,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,aAAa,MAAM,KAAG,WAkCvF,CAAA;AAED,sDAAsD;AACtD,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,WAQ1C,CAAA;AAEF,sDAAsD;AACtD,eAAO,MAAM,0BAA0B,GAAI,KAAK,MAAM,KAAG,MAsBxD,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,GAAU,KAAK,MAAM,EAAE,mBAAiB,KAAG,OAAO,CAAC,MAAM,CASvF,CAAA;AAuBD,sDAAsD;AACtD,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,WACP,CAAA"}

package/library/config.js

@@ -5,7 +5,7 @@ import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { basename, isAbsolute, resolve } from 'node:path';
 import { XDocsError } from './errors.js';
-const DEFAULT_EXTENSIONS = ['.docs.md', '.xdocs.md'];
+const DEFAULT_EXTENSIONS = ['.xdocs.md'];
 const DEFAULT_EXCLUDE = ['node_modules', '.git', 'dist', 'build', 'library', 'bin', 'bundle'];
 const DEFAULT_AI_MODE = 'prompt';
 const CONFIG_FILENAME = 'xdocs.config.toml';
@@ -83,6 +83,10 @@ export const normalizeConfig = (raw, cwd, configPath) => {
     if (!Array.isArray(extensions) || extensions.some((ext) => typeof ext !== 'string')) {
         throw new XDocsError('Invalid extensions.supported. Expected an array of strings.');
     }
+    const normalizedExtensions = extensions.map((ext) => ext.toLowerCase());
+    if (normalizedExtensions.length !== 1 || normalizedExtensions[0] !== '.xdocs.md') {
+        throw new XDocsError('Invalid extensions.supported. xdocs supports only named "*.xdocs.md" descriptor files.');
+    }
     const exclude = raw.scan?.exclude ?? DEFAULT_EXCLUDE;
     if (!Array.isArray(exclude) || exclude.some((dir) => typeof dir !== 'string')) {
         throw new XDocsError('Invalid scan.exclude. Expected an array of strings.');
@@ -91,7 +95,7 @@ export const normalizeConfig = (raw, cwd, configPath) => {
         schema: 1,
         cwd,
         configPath,
-        extensions: { supported: extensions },
+        extensions: { supported: DEFAULT_EXTENSIONS },
         ai: { mode: aiMode ?? DEFAULT_AI_MODE },
         scan: { exclude },
         project: { name: raw.project?.name ?? basename(cwd) },
@@ -114,7 +118,7 @@ export const createDefaultConfigContent = (cwd) => {
     return `schema = 1
 
 [extensions]
-supported = [".docs.md", ".xdocs.md"]
+supported = [".xdocs.md"]
 
 [ai]
 mode = "prompt"

package/library/discovery.d.ts

@@ -2,11 +2,15 @@
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import type { XDocsConfig, XDocsFile, XDocsScanResult } from './types.js';
-/** Scan the project for xdocs files matching configured extensions. */
+/** Scan the project for xdocs descriptor files and sibling Markdown documents. */
 export declare const scanProject: (config: XDocsConfig) => Promise<XDocsScanResult>;
-/** Check if a file path matches any of the configured xdocs extensions. */
-export declare const isXDocsFile: (filePath: string, extensions: string[]) => boolean;
-/** Scan a specific directory (not recursive) for xdocs files. */
+/** Check if a file path is a root index or xdocs descriptor file. */
+export declare const isXDocsFile: (filePath: string, _extensions?: string[]) => boolean;
+/** Check if a file path is an xdocs module descriptor. */
+export declare const isXDocsDescriptorFile: (filePath: string) => boolean;
+/** Check if a file path is a companion Markdown document, not an xdocs descriptor. */
+export declare const isPlainMarkdownDocument: (filePath: string) => boolean;
+/** Scan a specific directory (not recursive) for xdocs descriptors. */
 export declare const scanDirectory: (dirPath: string, config: XDocsConfig) => Promise<XDocsFile[]>;
 /** List all files in a directory (non-recursive). */
 export declare const listDirectoryFiles: (dirPath: string, config: XDocsConfig) => Promise<string[]>;

package/library/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../source/discovery.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGzE,uEAAuE;AACvE,eAAO,MAAM,WAAW,GAAU,QAAQ,WAAW,KAAG,OAAO,CAAC,eAAe,CA2C9E,CAAA;AAED,2EAA2E;AAC3E,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,EAAE,YAAY,MAAM,EAAE,KAAG,OAOpE,CAAA;AAmCD,iEAAiE;AACjE,eAAO,MAAM,aAAa,GAAU,SAAS,MAAM,EAAE,QAAQ,WAAW,KAAG,OAAO,CAAC,SAAS,EAAE,CAqB7F,CAAA;AAED,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,GAAU,SAAS,MAAM,EAAE,QAAQ,WAAW,KAAG,OAAO,CAAC,MAAM,EAAE,CAiB/F,CAAA"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../source/discovery.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAyB,eAAe,EAAE,MAAM,YAAY,CAAA;AAMhG,kFAAkF;AAClF,eAAO,MAAM,WAAW,GAAU,QAAQ,WAAW,KAAG,OAAO,CAAC,eAAe,CA4D9E,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,EAAE,cAAa,MAAM,EAAiC,KAAG,OACtB,CAAA;AAE/E,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,GAAI,UAAU,MAAM,KAAG,OACc,CAAA;AAEvE,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,GAAI,UAAU,MAAM,KAAG,OAI1D,CAAA;AAmCD,uEAAuE;AACvE,eAAO,MAAM,aAAa,GAAU,SAAS,MAAM,EAAE,QAAQ,WAAW,KAAG,OAAO,CAAC,SAAS,EAAE,CA6B7F,CAAA;AAED,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,GAAU,SAAS,MAAM,EAAE,QAAQ,WAAW,KAAG,OAAO,CAAC,MAAM,EAAE,CAiB/F,CAAA"}

package/library/discovery.js

@@ -2,24 +2,32 @@
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import { readdir, stat } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { parseXDocsFile } from './metadata.js';
-/** Scan the project for xdocs files matching configured extensions. */
+const XDOCS_DESCRIPTOR_EXTENSION = '.xdocs.md';
+const ROOT_XDOCS_FILENAME = 'XDOCS.md';
+/** Scan the project for xdocs descriptor files and sibling Markdown documents. */
 export const scanProject = async (config) => {
     const xdocsFiles = [];
+    const markdownDocuments = [];
+    const markdownDocumentsByDirectory = new Map();
     const allDirectories = [];
-    const coveredDirectories = new Set();
     let totalFiles = 0;
-    await walkDirectory(config.cwd, config, async (filePath, dir) => {
+    await walkDirectory(config.cwd, config, async (filePath, _dir) => {
         totalFiles += 1;
-        if (isXDocsFile(filePath, config.extensions.supported)) {
+        if (isXDocsDescriptorFile(filePath)) {
             const file = await parseXDocsFile(filePath, config.cwd);
             xdocsFiles.push(file);
-            coveredDirectories.add(dir);
+            return;
+        }
+        if (isPlainMarkdownDocument(filePath)) {
+            const document = createMarkdownDocument(filePath, config.cwd);
+            markdownDocuments.push(document);
+            addMarkdownDocument(markdownDocumentsByDirectory, document.directory, document);
         }
     }, allDirectories);
     // The root XDOCS.md is always recognized
-    const rootXDocs = join(config.cwd, 'XDOCS.md');
+    const rootXDocs = join(config.cwd, ROOT_XDOCS_FILENAME);
     const rootAlreadyFound = xdocsFiles.some((f) => f.path === rootXDocs);
     if (!rootAlreadyFound) {
         try {
@@ -27,30 +35,43 @@ export const scanProject = async (config) => {
             if (rootStat.isFile()) {
                 const file = await parseXDocsFile(rootXDocs, config.cwd);
                 xdocsFiles.push(file);
-                coveredDirectories.add(config.cwd);
             }
         }
         catch {
             // Root XDOCS.md does not exist, that's fine
         }
     }
+    enrichDescriptorFiles(xdocsFiles, markdownDocumentsByDirectory);
+    const coveredDirectories = new Set();
+    if (xdocsFiles.some((file) => file.path === rootXDocs))
+        coveredDirectories.add(config.cwd);
+    for (const file of xdocsFiles) {
+        if (file.path === rootXDocs)
+            continue;
+        if (file.valid)
+            coveredDirectories.add(file.directory);
+    }
     const uncoveredPaths = allDirectories.filter((dir) => !coveredDirectories.has(dir));
     return {
         totalFiles,
         totalDirectories: allDirectories.length,
+        totalMarkdownDocuments: markdownDocuments.length,
         coveredDirectories: coveredDirectories.size,
         uncoveredDirectories: uncoveredPaths.length,
         xdocsFiles,
+        markdownDocuments,
         uncoveredPaths,
     };
 };
-/** Check if a file path matches any of the configured xdocs extensions. */
-export const isXDocsFile = (filePath, extensions) => {
-    const lower = filePath.toLowerCase();
-    // Root XDOCS.md is always recognized
-    if (lower.endsWith('/xdocs.md') || lower.endsWith('\\xdocs.md'))
-        return true;
-    return extensions.some((ext) => lower.endsWith(ext.toLowerCase()));
+/** Check if a file path is a root index or xdocs descriptor file. */
+export const isXDocsFile = (filePath, _extensions = [XDOCS_DESCRIPTOR_EXTENSION]) => basename(filePath) === ROOT_XDOCS_FILENAME || isXDocsDescriptorFile(filePath);
+/** Check if a file path is an xdocs module descriptor. */
+export const isXDocsDescriptorFile = (filePath) => basename(filePath).toLowerCase().endsWith(XDOCS_DESCRIPTOR_EXTENSION);
+/** Check if a file path is a companion Markdown document, not an xdocs descriptor. */
+export const isPlainMarkdownDocument = (filePath) => {
+    const name = basename(filePath);
+    const lower = name.toLowerCase();
+    return lower.endsWith('.md') && lower !== 'xdocs.md' && !isXDocsDescriptorFile(filePath);
 };
 /** Recursively walk a directory, skipping excluded directories. */
 const walkDirectory = async (dir, config, onFile, allDirectories) => {
@@ -76,9 +97,10 @@ const walkDirectory = async (dir, config, onFile, allDirectories) => {
 };
 /** Check if a directory name is in the exclude list. */
 const isExcluded = (name, exclude) => exclude.includes(name) || name.startsWith('.');
-/** Scan a specific directory (not recursive) for xdocs files. */
+/** Scan a specific directory (not recursive) for xdocs descriptors. */
 export const scanDirectory = async (dirPath, config) => {
     const files = [];
+    const markdownDocumentsByDirectory = new Map();
     let entries;
     try {
         entries = await readdir(dirPath, { withFileTypes: true });
@@ -90,11 +112,17 @@ export const scanDirectory = async (dirPath, config) => {
         if (!entry.isFile())
             continue;
         const fullPath = join(dirPath, entry.name);
-        if (isXDocsFile(fullPath, config.extensions.supported)) {
+        if (isXDocsDescriptorFile(fullPath) || isRootXDocsFile(fullPath, config.cwd)) {
             const file = await parseXDocsFile(fullPath, config.cwd);
             files.push(file);
+            continue;
+        }
+        if (isPlainMarkdownDocument(fullPath)) {
+            const document = createMarkdownDocument(fullPath, config.cwd);
+            addMarkdownDocument(markdownDocumentsByDirectory, document.directory, document);
         }
     }
+    enrichDescriptorFiles(files, markdownDocumentsByDirectory);
     return files;
 };
 /** List all files in a directory (non-recursive). */
@@ -116,3 +144,65 @@ export const listDirectoryFiles = async (dirPath, config) => {
     }
     return result;
 };
+const isRootXDocsFile = (filePath, cwd) => resolve(filePath) === resolve(cwd, ROOT_XDOCS_FILENAME);
+const createMarkdownDocument = (filePath, cwd) => ({
+    path: filePath,
+    relativePath: relative(cwd, filePath),
+    directory: dirname(filePath),
+    name: basename(filePath),
+});
+const addMarkdownDocument = (documentsByDirectory, directory, document) => {
+    const documents = documentsByDirectory.get(directory) ?? [];
+    documents.push(document);
+    documentsByDirectory.set(directory, documents);
+};
+const enrichDescriptorFiles = (files, documentsByDirectory) => {
+    const descriptorsByDirectory = new Map();
+    for (const file of files) {
+        if (!isXDocsDescriptorFile(file.path))
+            continue;
+        const descriptors = descriptorsByDirectory.get(file.directory) ?? [];
+        descriptors.push(file);
+        descriptorsByDirectory.set(file.directory, descriptors);
+    }
+    for (const descriptors of descriptorsByDirectory.values()) {
+        if (descriptors.length <= 1)
+            continue;
+        for (const file of descriptors) {
+            file.errors.push('Multiple xdocs descriptors found in this directory. Keep exactly one named "*.xdocs.md" file per directory.');
+            file.valid = false;
+        }
+    }
+    for (const file of files) {
+        if (!isXDocsDescriptorFile(file.path))
+            continue;
+        file.documents = documentsByDirectory.get(file.directory) ?? [];
+        validateDocumentReferences(file);
+        if (file.errors.length > 0)
+            file.valid = false;
+    }
+};
+const validateDocumentReferences = (file) => {
+    if (!file.metadata)
+        return;
+    const actualDocuments = new Set(file.documents.map((document) => document.name));
+    const declaredDocuments = file.metadata.documents;
+    for (const document of file.documents) {
+        if (Object.hasOwn(declaredDocuments, document.name))
+            continue;
+        file.errors.push(`Undocumented Markdown document: "${document.name}" must be listed in the "documents" metadata map.`);
+    }
+    for (const name of Object.keys(declaredDocuments)) {
+        if (!isPlainMarkdownDocumentName(name)) {
+            file.errors.push(`Invalid document entry: "${name}" must be a sibling plain "*.md" filename, not an xdocs descriptor or path.`);
+            continue;
+        }
+        if (!actualDocuments.has(name)) {
+            file.errors.push(`Missing Markdown document: "${name}" is listed in metadata but does not exist beside the descriptor.`);
+        }
+    }
+};
+const isPlainMarkdownDocumentName = (name) => {
+    const lower = name.toLowerCase();
+    return !name.includes('/') && !name.includes('\\') && lower.endsWith('.md') && lower !== 'xdocs.md' && !lower.endsWith(XDOCS_DESCRIPTOR_EXTENSION);
+};

package/library/flags.d.ts

@@ -10,7 +10,7 @@ import type { XDocsParsedArgs } from './types.js';
  * - Long flags with value: `--name=write` or `--name write`
  * - Long boolean flags: `--verbose`
  * - Short flags: `-h`, `-v`
- * - List values as comma-separated: `--extensions=.docs.md,.xdocs.md`
+ * - List values as comma-separated: `--extensions=.xdocs.md,.custom.md`
  * - Positional arguments after the command
  */
 export declare const parseArgs: (rawArgs: string[]) => XDocsParsedArgs;

package/library/flags.js

@@ -24,7 +24,7 @@ const listFlags = new Set([
  * - Long flags with value: `--name=write` or `--name write`
  * - Long boolean flags: `--verbose`
  * - Short flags: `-h`, `-v`
- * - List values as comma-separated: `--extensions=.docs.md,.xdocs.md`
+ * - List values as comma-separated: `--extensions=.xdocs.md,.custom.md`
  * - Positional arguments after the command
  */
 export const parseArgs = (rawArgs) => {

package/library/guiho-xdocs.d.ts

@@ -2,10 +2,10 @@
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 export { XDocsError, invariant } from './errors.js';
-export type { XDocsAgentAutomationResult, XDocsAgentSettings, XDocsAgentTool, XDocsAgentsInstructionsResult, XDocsAiMode, XDocsCliOptions, XDocsCommand, XDocsConfig, XDocsFile, XDocsFormat, XDocsMetadata, XDocsParsedArgs, XDocsPrompt, XDocsPromptName, XDocsRawConfig, XDocsScanResult, XDocsSkillInstallResult, XDocsSkillScope, XDocsTreeNode, XDocsTreeValidation, } from './types.js';
+export type { XDocsAgentAutomationResult, XDocsAgentSettings, XDocsAgentTool, XDocsAgentsInstructionsResult, XDocsAiMode, XDocsCliOptions, XDocsCommand, XDocsConfig, XDocsFile, XDocsFormat, XDocsMarkdownDocument, XDocsMetadata, XDocsParsedArgs, XDocsPrompt, XDocsPromptName, XDocsRawConfig, XDocsScanResult, XDocsSkillInstallResult, XDocsSkillScope, XDocsTreeNode, XDocsTreeValidation, } from './types.js';
 export { parseArgs, stringFlag, booleanFlag, listFlag } from './flags.js';
 export { createDefaultConfigContent, DEFAULT_AGENT_SETTINGS, defaultConfig, discoverConfig, loadConfig, loadConfigOrDefaults, normalizeAgentSettings, normalizeConfig, resolvePath, writeDefaultConfig, } from './config.js';
-export { isXDocsFile, listDirectoryFiles, scanDirectory, scanProject } from './discovery.js';
+export { isPlainMarkdownDocument, isXDocsDescriptorFile, isXDocsFile, listDirectoryFiles, scanDirectory, scanProject } from './discovery.js';
 export { extractFrontmatter, parseXDocsFile, validateMetadata } from './metadata.js';
 export { buildTree, renderTree, renderTreeMarkdown, validateTree } from './tree.js';
 export { readPackageVersion, showCommandHelp, showHelp, showVersion } from './help.js';