@guiho/xdocs 0.3.1 → 0.4.9

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-bin.d.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */

package/library/guiho-xdocs-bin.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */

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');
+};

package/library/tree.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, XDocsTreeNode, XDocsTreeValidation } from './types.js';
-/** Build a hierarchy tree from a list of xdocs files. */
+/** Build a hierarchy tree from a list of xdocs descriptors. */
 export declare const buildTree: (files: XDocsFile[]) => XDocsTreeNode;
 /** Validate tree integrity. */
 export declare const validateTree: (files: XDocsFile[]) => XDocsTreeValidation;

package/library/tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../source/tree.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAE/E,yDAAyD;AACzD,eAAO,MAAM,SAAS,GAAI,OAAO,SAAS,EAAE,KAAG,aA8D9C,CAAA;AAED,+BAA+B;AAC/B,eAAO,MAAM,YAAY,GAAI,OAAO,SAAS,EAAE,KAAG,mBAmCjD,CAAA;AAED,gDAAgD;AAChD,eAAO,MAAM,UAAU,GAAI,MAAM,aAAa,EAAE,eAAU,KAAG,MAe5D,CAAA;AAED,iCAAiC;AACjC,eAAO,MAAM,kBAAkB,GAAI,MAAM,aAAa,EAAE,eAAU,KAAG,MAWpE,CAAA"}
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../source/tree.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAE/E,+DAA+D;AAC/D,eAAO,MAAM,SAAS,GAAI,OAAO,SAAS,EAAE,KAAG,aA8D9C,CAAA;AAED,+BAA+B;AAC/B,eAAO,MAAM,YAAY,GAAI,OAAO,SAAS,EAAE,KAAG,mBAmCjD,CAAA;AAED,gDAAgD;AAChD,eAAO,MAAM,UAAU,GAAI,MAAM,aAAa,EAAE,eAAU,KAAG,MAe5D,CAAA;AAED,iCAAiC;AACjC,eAAO,MAAM,kBAAkB,GAAI,MAAM,aAAa,EAAE,eAAU,KAAG,MAWpE,CAAA"}

package/library/tree.js

@@ -1,7 +1,7 @@
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
-/** Build a hierarchy tree from a list of xdocs files. */
+/** Build a hierarchy tree from a list of xdocs descriptors. */
 export const buildTree = (files) => {
     const nodeMap = new Map();
     // Create nodes for every file with valid metadata
@@ -47,7 +47,7 @@ export const buildTree = (files) => {
     if (!root) {
         root = {
             subject: '(root)',
-            description: 'No root xdocs file found.',
+            description: 'No root xdocs descriptor found.',
             path: null,
             children: [...nodeMap.values()].filter((node) => !files.some((f) => f.metadata && f.metadata.children.includes(node.subject))),
         };

package/library/types.d.ts

@@ -61,23 +61,33 @@ export type XDocsAgentSettings = {
     autoSkillInstall: boolean;
     skillTool: XDocsAgentTool;
 };
-/** YAML frontmatter metadata from an xdocs file. */
+/** YAML frontmatter metadata from an xdocs descriptor. */
 export type XDocsMetadata = {
     subject: string;
     description: string;
     parent: string | null;
     children: string[];
     files: Record<string, string>;
+    documents: Record<string, string>;
     tags: string[];
+    keywords: string[];
     flags: string[];
     status?: string;
 };
-/** A discovered xdocs file with its path and parsed metadata. */
+/** A sibling Markdown document listed by a module descriptor. */
+export type XDocsMarkdownDocument = {
+    path: string;
+    relativePath: string;
+    directory: string;
+    name: string;
+};
+/** A discovered xdocs descriptor with its path and parsed metadata. */
 export type XDocsFile = {
     path: string;
     relativePath: string;
     directory: string;
     metadata: XDocsMetadata | null;
+    documents: XDocsMarkdownDocument[];
     body: string;
     valid: boolean;
     errors: string[];
@@ -112,9 +122,11 @@ export type XDocsCliOptions = {
 export type XDocsScanResult = {
     totalFiles: number;
     totalDirectories: number;
+    totalMarkdownDocuments: number;
     coveredDirectories: number;
     uncoveredDirectories: number;
     xdocsFiles: XDocsFile[];
+    markdownDocuments: XDocsMarkdownDocument[];
     uncoveredPaths: string[];
 };
 /** Available prompt names for xdocs prompt --name. */

package/library/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/xdocs",
   "description": "Structured documentation system for codebases. Helps AI make sense of projects.",
-  "version": "0.3.1",
+  "version": "0.4.9",
   "type": "module",
   "main": "./library/guiho-xdocs.js",
   "types": "./library/guiho-xdocs.d.ts",
@@ -40,6 +40,9 @@
     "url": "https://guiho.co/cg"
   },
   "sideEffects": false,
+  "trustedDependencies": [
+    "@guiho/mirror"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -63,8 +66,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/CGuiho/xdocs.git",
-    "directory": "xdocs"
+    "url": "git+https://github.com/CGuiho/xdocs.git"
   },
   "homepage": "https://github.com/CGuiho/xdocs#readme",
   "bugs": {

package/prompts/agents.md

@@ -1,6 +1,10 @@
 ---
 name: agents
 description: Update AGENTS.md with xdocs instructions for AI agents.
+keywords:
+  - AGENTS.md
+  - agent instructions
+  - xdocs skill
 ---
 
 # xdocs: Update AGENTS.md
@@ -14,8 +18,11 @@ You are an AI assistant tasked with updating the AGENTS.md file to include xdocs
 3. If the section exists, update it with the current xdocs configuration.
 4. If the section does not exist, add it at the end of the file.
 5. The xdocs section should instruct AI agents to:
-   - Read XDOCS.md and xdocs files when entering the project
+   - Read XDOCS.md and named `*.xdocs.md` descriptor files when entering the project
    - Respect the configured AI behavior mode (prompt or auto)
    - Use the xdocs CLI for documentation operations
-   - Maintain xdocs files when modifying code
+   - Maintain xdocs descriptors and companion-document metadata when modifying code
+   - Use only named `*.xdocs.md` descriptors, never nameless `.xdocs.md` files
+   - List every same-directory plain `*.md` companion document in the descriptor's `documents` metadata map
+   - Maintain `keywords` in both descriptor and companion Markdown frontmatter
    - Follow the metadata schema for frontmatter

package/prompts/generate.md

@@ -1,6 +1,10 @@
 ---
 name: generate
 description: Generate comprehensive documentation for a domain or entire project.
+keywords:
+  - generate documentation
+  - comprehensive docs
+  - project summary
 ---
 
 # xdocs: Generate Comprehensive Documentation
@@ -9,18 +13,22 @@ You are an AI assistant tasked with generating comprehensive documentation for a
 
 ## Instructions
 
-1. Scan all xdocs files in the target scope (directory or project).
-2. Read every source file in the scope.
+1. Scan all xdocs descriptors in the target scope (directory or project).
+2. Read every named `*.xdocs.md` descriptor's YAML frontmatter first, then read
+   source files and same-directory plain `*.md` documents only when needed.
 3. Build a complete understanding of:
    - The module hierarchy
    - The purpose of each module
    - How modules relate to each other
    - What each file does
+   - Which companion Markdown documents belong to each module
+   - Which keywords identify each module and companion document
 4. Generate a single comprehensive Markdown document that includes:
    - Project or domain overview
    - Complete hierarchy tree
    - Detailed description of each module
    - File listings with descriptions
+   - Companion document listings with descriptions
    - Cross-references between related modules
 5. The output should be a self-contained document that fully describes the scope.
 6. Use clear headings, consistent formatting, and concise language.