@guiho/xdocs 0.3.0-alpha.2 → 0.4.2

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.0-alpha.2",
+  "version": "0.4.2",
   "type": "module",
   "main": "./library/guiho-xdocs.js",
   "types": "./library/guiho-xdocs.d.ts",
@@ -12,7 +12,7 @@
     }
   },
   "bin": {
-    "xdocs": "./bin/xdocs.exe"
+    "xdocs": "scripts/xdocs-bin.ts"
   },
   "files": [
     "README.md",
@@ -40,6 +40,9 @@
     "url": "https://guiho.co/cg"
   },
   "sideEffects": false,
+  "trustedDependencies": [
+    "@guiho/mirror"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -49,7 +52,7 @@
     "binary": "bun build source/guiho-xdocs-native-bin.ts --compile --outfile bin/xdocs",
     "binaries": "bun run devops/build-binaries.ts",
     "bundle": "rm -rf bundle && bun build source/guiho-xdocs-bin.ts --outdir bundle --target node --sourcemap=linked",
-    "postinstall": "node ./scripts/install-native.cjs",
+    "postinstall": "bun run scripts/install-package.ts",
     "typecheck": "tsc -p . --noEmit",
     "clean": "rm -rf .temp",
     "clean-build": "rm -rf build library bundle bin",

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.

package/prompts/prompts.xdocs.md

@@ -0,0 +1,27 @@
+---
+subject: xdocs-prompts
+description: Runtime prompt templates used by xdocs prompt commands and embedded into native binaries.
+parent: xdocs-package
+children: []
+files: {}
+documents:
+  agents.md: Prompt for updating AGENTS.md with xdocs instructions.
+  generate.md: Prompt for generating comprehensive documentation from xdocs metadata.
+  update.md: Prompt for updating existing xdocs descriptors after code or document changes.
+  write.md: Prompt for writing a named xdocs descriptor for a module.
+tags:
+  - prompts
+  - ai
+  - documentation
+keywords:
+  - prompts
+  - AI instructions
+  - documentation generation
+flags: []
+status: stable
+---
+
+The `prompts/` directory contains Markdown prompt templates loaded by
+`source/prompts.ts` at runtime and embedded by `source/embedded-resources.ts` for
+native binaries. They are plain companion documents, so this descriptor lists
+each prompt under `documents`.

package/prompts/update.md

@@ -1,6 +1,10 @@
 ---
 name: update
-description: Update existing xdocs files after code changes.
+description: Update existing xdocs descriptors after code or document changes.
+keywords:
+  - update descriptor
+  - synchronize metadata
+  - documentation maintenance
 ---
 
 # xdocs: Update Documentation
@@ -10,22 +14,30 @@ You are an AI assistant tasked with updating existing xdocs documentation after
 ## Instructions
 
 1. Identify which files have changed in the recent modifications.
-2. Find the xdocs files that document the directories containing those changes.
-3. For each affected xdocs file:
+2. Find the named `*.xdocs.md` descriptor files that document the directories
+   containing those changes. There must be exactly one descriptor per directory,
+   and it must not be named only `.xdocs.md`.
+3. For each affected xdocs descriptor:
    a. Re-read the files listed in the metadata to check if descriptions are still accurate.
    b. Check if new files were added that need to be listed.
    c. Check if files were removed that should be unlisted.
-   d. Update the description if the module's purpose has changed.
-   e. Update children if subdirectories were added or removed.
-   f. Update the body content if significant changes occurred.
-4. Preserve the existing structure and style of the xdocs file.
+   d. Check if sibling plain `*.md` documents were added or removed, and keep
+      the `documents` metadata map exact.
+   e. Update the description if the module's purpose has changed.
+   f. Update `keywords` if the module's searchable concepts changed.
+   g. Update children if subdirectories were added or removed.
+   h. Update the body content if significant changes occurred.
+4. Preserve the existing structure and style of the xdocs descriptor.
 5. Do not remove information that is still accurate.
 
 ## Checklist
 
 - [ ] All new files are listed in the files metadata
 - [ ] Removed files are no longer listed
+- [ ] All sibling plain Markdown documents are listed in the documents metadata
+- [ ] Removed Markdown documents are no longer listed
 - [ ] File descriptions are accurate
 - [ ] Module description reflects current state
+- [ ] Keywords reflect current searchable concepts
 - [ ] Children list matches actual subdirectories
 - [ ] Parent reference is still correct

package/prompts/write.md

@@ -1,6 +1,10 @@
 ---
 name: write
-description: Scan a directory and write a new xdocs documentation file for it.
+description: Scan a directory and write a new named xdocs descriptor for it.
+keywords:
+  - write descriptor
+  - xdocs metadata
+  - module documentation
 ---
 
 # xdocs: Write Documentation
@@ -12,19 +16,25 @@ You are an AI assistant tasked with writing xdocs documentation for a directory/
 1. Scan the target directory and all its subdirectories.
 2. Read every source file to understand what it does.
 3. Identify the purpose of this module/directory.
-4. Create an xdocs file with YAML frontmatter containing:
+4. Create a named xdocs descriptor with YAML frontmatter containing:
    - subject: A short identifier for this module
    - description: A concise description of what this module does
    - parent: The parent module's subject (or null if this is a root module)
    - children: List of child module subjects
    - files: Map of filename to short description for each file
+   - documents: Map of same-directory plain Markdown filename to short description
    - tags: Relevant tags (empty array if none)
+   - keywords: Search terms and concepts that should help agents match requests
    - flags: Relevant flags (empty array if none)
 5. Write a Markdown body below the frontmatter with:
    - An overview section explaining the module in more detail
    - Usage examples if relevant
    - Any important notes or caveats
-6. Name the file as `<module-name>.xdocs.md` in the target directory.
+6. Name the file as `<module-name>.xdocs.md` in the target directory. Never name
+   a file only `.xdocs.md`; `.xdocs.md` is the extension, not the full filename.
+7. Use only `.xdocs.md` for xdocs descriptors. Do not create `.docs.md` files.
+8. If the directory contains sibling plain `*.md` files, list each one under
+   `documents` in this descriptor.
 
 ## Frontmatter Template
 
@@ -37,9 +47,12 @@ children:
   - child-a
   - child-b
 files:
-  - file-a.ts: What file-a does.
-  - file-b.ts: What file-b does.
+  file-a.ts: What file-a does.
+  file-b.ts: What file-b does.
+documents:
+  implementation-notes.md: What this companion document explains.
 tags: []
+keywords: []
 flags: []
 ---
 ```

package/scripts/install-package.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env bun
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ *
+ * Package-manager install helper for xdocs.
+ *
+ * This script downloads the platform-native xdocs binary into `vendor/xdocs` or
+ * `vendor/xdocs.exe`. Package-manager installs use the small Bun launcher in
+ * `scripts/xdocs-bin.ts`; direct installers remain the no-Bun runtime path.
+ */
+
+type PackageJson = {
+  version?: string
+}
+
+const packageJson = await Bun.file(new URL('../package.json', import.meta.url)).json() as PackageJson
+const sourceEntrypoint = Bun.file(new URL('../source/guiho-xdocs-bin.ts', import.meta.url))
+
+if (await sourceEntrypoint.exists()) {
+  console.log('source checkout detected; skipping native binary download')
+  process.exit(0)
+}
+
+const version = process.env['XDOCS_VERSION'] ?? packageJson.version ?? 'latest'
+const repo = process.env['XDOCS_REPO'] ?? 'CGuiho/xdocs'
+const asset = detectAsset()
+const bundledAsset = Bun.file(new URL(`../bin/${asset}`, import.meta.url))
+const destination = new URL(`../vendor/xdocs${process.platform === 'win32' ? '.exe' : ''}`, import.meta.url)
+
+if (await bundledAsset.exists()) {
+  await Bun.write(destination, bundledAsset)
+  await makeExecutable(destination)
+  console.log(`installed bundled xdocs native binary: ${asset}`)
+  process.exit(0)
+}
+
+const tag = version === 'latest' ? 'latest' : `@guiho/xdocs@${version}`
+const url = tag === 'latest'
+  ? `https://github.com/${repo}/releases/latest/download/${asset}`
+  : `https://github.com/${repo}/releases/download/${encodeURIComponent(tag)}/${asset}`
+
+const response = await fetch(url)
+
+if (!response.ok) {
+  console.error(`error: failed to download ${url}`)
+  console.error(`status: ${response.status} ${response.statusText}`)
+  process.exit(1)
+}
+
+await Bun.write(destination, response)
+await makeExecutable(destination)
+console.log(`installed xdocs native binary: ${asset}`)
+
+async function makeExecutable(path: URL) {
+  if (process.platform === 'win32') return
+
+  const result = Bun.spawn(['chmod', '755', Bun.fileURLToPath(path)], {
+    stdout: 'ignore',
+    stderr: 'inherit',
+  })
+  const exitCode = await result.exited
+
+  if (exitCode !== 0) {
+    console.error('error: failed to make xdocs native binary executable')
+    process.exit(exitCode)
+  }
+}
+
+function detectAsset() {
+  const os = detectOs()
+  const arch = detectArch()
+  return `xdocs-${os}-${arch}${os === 'windows' ? '.exe' : ''}`
+}
+
+function detectOs() {
+  if (process.platform === 'linux') return 'linux'
+  if (process.platform === 'darwin') return 'macos'
+  if (process.platform === 'win32') return 'windows'
+  console.error(`error: unsupported OS: ${process.platform}`)
+  process.exit(1)
+}
+
+function detectArch() {
+  if (process.arch === 'x64') return 'x64'
+  if (process.arch === 'arm64') return 'arm64'
+  console.error(`error: unsupported architecture: ${process.arch}`)
+  process.exit(1)
+}

package/scripts/scripts.xdocs.md

@@ -1,18 +1,25 @@
 ---
 subject: xdocs-scripts
-description: Package-manager installation scripts for installing the native xdocs binary.
+description: Package-manager launcher and installation scripts for executing the native xdocs binary.
 parent: xdocs-package
 children: []
 files:
-  install-native.cjs: npm postinstall helper that downloads the matching GitHub Release native binary into bin/xdocs.exe.
+  xdocs-bin.ts: Shipped Bun launcher used as the package bin; installs the native binary on first run when needed and delegates to it.
+  install-package.ts: Package-manager install helper that downloads or copies the matching GitHub Release native binary into vendor/xdocs or vendor/xdocs.exe.
+documents: {}
 tags:
   - install
   - native-binary
   - package-manager
+keywords:
+  - package launcher
+  - native binary
+  - vendor install
 flags: []
 status: stable
 ---
 
-The `scripts/` directory contains package-manager lifecycle helpers. These
-scripts are used during install only; the resulting `xdocs` command executes the
-downloaded native binary directly and does not require Node.js at runtime.
+The `scripts/` directory contains the package-manager launcher and install
+helper. Package-manager and `bunx` execution start in `xdocs-bin.ts`; if the
+native binary is missing, it runs `install-package.ts` and then delegates to the
+downloaded binary in `vendor/`. Direct installers remain the no-Bun runtime path.