@guiho/xdocs 0.3.1 → 0.4.2

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';

package/library/guiho-xdocs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guiho-xdocs.d.ts","sourceRoot":"","sources":["../source/guiho-xdocs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAGnD,YAAY,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,WAAW,EACX,eAAe,EACf,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,EACX,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,eAAe,EACf,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGzE,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,UAAU,EACV,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,WAAW,EACX,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAG5F,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAGpF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGnF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGtF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGjE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"guiho-xdocs.d.ts","sourceRoot":"","sources":["../source/guiho-xdocs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAGnD,YAAY,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,WAAW,EACX,eAAe,EACf,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,EACX,qBAAqB,EACrB,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,eAAe,EACf,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGzE,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,UAAU,EACV,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,WAAW,EACX,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAG5I,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAGpF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGnF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGtF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGjE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA"}

package/library/guiho-xdocs.js

@@ -8,7 +8,7 @@ export { parseArgs, stringFlag, booleanFlag, listFlag } from './flags.js';
 // Config
 export { createDefaultConfigContent, DEFAULT_AGENT_SETTINGS, defaultConfig, discoverConfig, loadConfig, loadConfigOrDefaults, normalizeAgentSettings, normalizeConfig, resolvePath, writeDefaultConfig, } from './config.js';
 // Discovery
-export { isXDocsFile, listDirectoryFiles, scanDirectory, scanProject } from './discovery.js';
+export { isPlainMarkdownDocument, isXDocsDescriptorFile, isXDocsFile, listDirectoryFiles, scanDirectory, scanProject } from './discovery.js';
 // Metadata
 export { extractFrontmatter, parseXDocsFile, validateMetadata } from './metadata.js';
 // Tree

package/library/help.js

@@ -26,12 +26,12 @@ Usage: xdocs <command> [options]
 
 Commands:
   init                  Initialize xdocs in a project
-  scan                  Scan the project for xdocs files
+  scan                  Scan for xdocs descriptors and Markdown documents
   generate [path]       Generate documentation for a directory or the project
   prompt                Output a ready-made prompt for AI
-  merge [path]          Merge xdocs files from a directory into one file
+  merge [path]          Merge xdocs descriptors from a directory into one file
   tree                  Display the project hierarchy tree
-  list [path]           List files with descriptions
+  list [path]           List documented files and documents
   agents                Install the guiho-s-xdocs skill and AGENTS.md instructions
 
 Global Flags:
@@ -82,12 +82,13 @@ Flags:
   --verbose               Show detailed output
 `.trim(),
     scan: `
-xdocs scan - Scan the project for xdocs files
+xdocs scan - Scan the project for xdocs descriptors
 
 Usage: xdocs scan
 
-Walks every directory and subdirectory (respecting exclude rules),
-matches files against configured extensions, and reports coverage.
+Walks every directory and subdirectory (respecting exclude rules), finds named
+*.xdocs.md descriptor files, and reports plain sibling *.md documents that those
+descriptors must list in their documents metadata.
 
 Flags:
   --format <format>       Output format: text, json (default: text)
@@ -100,7 +101,7 @@ xdocs generate - Generate documentation
 
 Usage: xdocs generate [path]
 
-When a path is given, generates an xdocs file for that directory/module.
+When a path is given, generates documentation for that directory/module.
 When no path is given, generates documentation for the entire project.
 
 Flags:
@@ -122,7 +123,7 @@ a specific xdocs task. Both flag styles are supported:
 
 Available prompts:
   write                   How to scan a directory and write xdocs documentation
-  update                  How to update existing xdocs files after code changes
+  update                  How to update existing xdocs descriptors after code changes
   agents                  How to update AGENTS.md with xdocs instructions
   generate                How to generate comprehensive documentation
 
@@ -132,12 +133,12 @@ Flags:
   --config <path>         Path to xdocs.config.toml
 `.trim(),
     merge: `
-xdocs merge - Merge xdocs files into a single file
+xdocs merge - Merge xdocs descriptors into a single file
 
 Usage: xdocs merge [path]
 
-Takes all xdocs files within the given directory and produces
-one consolidated Markdown document.
+Takes all xdocs descriptor files within the given directory and produces
+one consolidated Markdown document, including listed companion documents.
 
 Flags:
   --output <path>         Output file path (default: stdout)
@@ -150,7 +151,7 @@ xdocs tree - Display the project hierarchy tree
 
 Usage: xdocs tree
 
-Scans all xdocs files, reads their metadata, and assembles the
+Scans all xdocs descriptors, reads their metadata, and assembles the
 parent-child hierarchy. Shows modules only, not individual files.
 
 Flags:
@@ -161,12 +162,12 @@ Flags:
   --verbose               Show detailed output
 `.trim(),
     list: `
-xdocs list - List files with descriptions
+xdocs list - List documented files and documents
 
 Usage: xdocs list [path]
 
-Lists every file in the given scope with a short description
-of its purpose, pulled from xdocs metadata.
+Lists every source file and companion Markdown document in the given scope with
+a short description pulled from xdocs metadata.
 
 Flags:
   --format <format>       Output format: text, json (default: text)

package/library/metadata.d.ts

@@ -2,7 +2,7 @@
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import type { XDocsFile, XDocsMetadata } from './types.js';
-/** Parse an xdocs file from disk into an XDocsFile object. */
+/** Parse an xdocs descriptor from disk into an XDocsFile object. */
 export declare const parseXDocsFile: (filePath: string, cwd: string) => Promise<XDocsFile>;
 /** Extract YAML frontmatter and body from a Markdown string. */
 export declare const extractFrontmatter: (content: string) => {

package/library/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../source/metadata.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1D,8DAA8D;AAC9D,eAAO,MAAM,cAAc,GAAU,UAAU,MAAM,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,SAAS,CAqCrF,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAiB9F,CAAA;AAED,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,GAAI,QAAQ,OAAO,KAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CA4D9J,CAAA"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../source/metadata.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1D,oEAAoE;AACpE,eAAO,MAAM,cAAc,GAAU,UAAU,MAAM,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,SAAS,CA0CrF,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAiB9F,CAAA;AAED,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,GAAI,QAAQ,OAAO,KAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAwE9J,CAAA"}

package/library/metadata.js

@@ -2,11 +2,14 @@
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import { readFile } from 'node:fs/promises';
-import { dirname, relative } from 'node:path';
-/** Parse an xdocs file from disk into an XDocsFile object. */
+import { basename, dirname, relative } from 'node:path';
+/** Parse an xdocs descriptor from disk into an XDocsFile object. */
 export const parseXDocsFile = async (filePath, cwd) => {
     const content = await readFile(filePath, 'utf8');
     const errors = [];
+    if (basename(filePath).toLowerCase() === '.xdocs.md') {
+        errors.push('Invalid xdocs descriptor filename. Use a named file such as "authentication.xdocs.md"; ".xdocs.md" is only the extension.');
+    }
     const { frontmatter, body } = extractFrontmatter(content);
     let metadata = null;
     if (frontmatter) {
@@ -33,6 +36,7 @@ export const parseXDocsFile = async (filePath, cwd) => {
         relativePath: relative(cwd, filePath),
         directory: dirname(filePath),
         metadata,
+        documents: [],
         body,
         valid: metadata !== null && errors.length === 0,
         errors,
@@ -74,15 +78,24 @@ export const validateMetadata = (parsed) => {
     else if (record['children'].some((child) => typeof child !== 'string')) {
         errors.push('Invalid "children" field. All entries must be strings.');
     }
-    if (typeof record['files'] !== 'object' || record['files'] === null || Array.isArray(record['files'])) {
+    if (!isStringMap(record['files'])) {
         errors.push('Missing or invalid "files" field. Expected an object mapping filenames to descriptions.');
     }
+    if (!isStringMap(record['documents'])) {
+        errors.push('Missing or invalid "documents" field. Expected an object mapping sibling Markdown filenames to descriptions.');
+    }
     if (!Array.isArray(record['tags'])) {
         errors.push('Missing or invalid "tags" field. Expected an array of strings.');
     }
     else if (record['tags'].some((tag) => typeof tag !== 'string')) {
         errors.push('Invalid "tags" field. All entries must be strings.');
     }
+    if (!Array.isArray(record['keywords'])) {
+        errors.push('Missing or invalid "keywords" field. Expected an array of strings.');
+    }
+    else if (record['keywords'].some((keyword) => typeof keyword !== 'string')) {
+        errors.push('Invalid "keywords" field. All entries must be strings.');
+    }
     if (!Array.isArray(record['flags'])) {
         errors.push('Missing or invalid "flags" field. Expected an array of strings.');
     }
@@ -101,9 +114,16 @@ export const validateMetadata = (parsed) => {
             parent: record['parent'] ?? null,
             children: record['children'],
             files: record['files'],
+            documents: record['documents'],
             tags: record['tags'],
+            keywords: record['keywords'],
             flags: record['flags'],
             status: typeof record['status'] === 'string' ? record['status'] : undefined,
         },
     };
 };
+const isStringMap = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    return Object.entries(value).every(([key, description]) => typeof key === 'string' && typeof description === 'string');
+};