@guiho/xdocs 0.3.1 → 0.4.9

package/docs/2026-07-05-xdocs-document-model.md

@@ -0,0 +1,77 @@
+---
+name: xdocs Document Model
+purpose: Record the descriptor-plus-companion-document model for future xdocs implementation work.
+description: Explains how named xdocs descriptors, root XDOCS.md, and same-directory Markdown companion documents work together for AI navigation.
+created: 2026-07-05
+keywords:
+  - xdocs descriptors
+  - companion documents
+  - AI navigation
+---
+
+# xdocs Document Model
+
+## Summary
+
+xdocs now treats a directory as documented by exactly one named `*.xdocs.md`
+descriptor. The root of a repository still uses `XDOCS.md` as a plain index with
+no frontmatter, but normal modules use a descriptor such as
+`authentication.xdocs.md`. A file named only `.xdocs.md` is invalid because
+`.xdocs.md` is the extension, not the filename.
+
+## Descriptor Metadata
+
+The descriptor is the AI-facing map for a module. Its YAML frontmatter contains
+the module identity, parent/child tree links, implementation files, and sibling
+Markdown companion documents.
+
+```yaml
+---
+subject: authentication
+description: Authentication implementation and session behavior.
+parent: backend
+children: []
+files:
+  login.ts: Email/password login flow.
+  session.ts: Session lifecycle and validation.
+documents:
+  authentication-implementation.md: Detailed implementation notes and decisions.
+tags:
+  - security
+keywords:
+  - authentication
+  - sessions
+  - implementation notes
+flags: []
+status: stable
+---
+```
+
+`files` is for implementation, configuration, and asset files. `documents` is
+only for same-directory plain `*.md` files that are not `*.xdocs.md` descriptors
+and not `XDOCS.md`.
+
+`keywords` is for search terms and concepts an agent can use to match a user
+request to the right descriptor. Companion Markdown documents use the same idea
+in their own frontmatter.
+
+## AI Workflow
+
+Agents should use `xdocs scan` to locate named `*.xdocs.md` descriptors, read
+frontmatter first, and use the `documents` map to decide which companion
+Markdown files are worth opening. When a user asks about a module, the agent can
+find the relevant module by descriptor metadata before reading source files.
+
+When changing a directory, an agent must update the directory descriptor so the
+`files`, `documents`, `keywords`, `parent`, and `children` fields match disk. If a sibling
+plain Markdown file is added, renamed, or removed, the descriptor's `documents`
+map changes in the same unit of work.
+
+## CLI Rules
+
+`xdocs scan` reports descriptor coverage and validates that every sibling plain
+Markdown file is listed in `documents`. It also marks a directory invalid when it
+has multiple `*.xdocs.md` descriptors or a nameless `.xdocs.md` file.
+
+`xdocs list`, `xdocs generate`, and `xdocs merge` surface both implementation
+files and companion documents, keeping the two categories separate.

package/docs/decisions/2026-07-09-package-launcher-source-fallback.md

@@ -0,0 +1,65 @@
+---
+name: Package Launcher Source Fallback
+purpose: Record the immediate repair decisions for broken xdocs package execution after the package moved to the repository root.
+description: Explains why the package launcher now falls back to the TypeScript CLI in source checkouts and why root package metadata/docs were corrected together.
+created: 2026-07-09T18:38:18Z
+flags:
+  - decision
+tags:
+  - cli
+  - package
+  - documentation
+keywords:
+  - xdocs-bin
+  - source checkout
+  - native binary
+  - vendor
+  - package root
+  - mirror.config.toml
+---
+
+# Package Launcher Source Fallback
+
+## Summary
+
+xdocs failed when the package launcher was executed from a source checkout with no
+`vendor/xdocs` native binary. `scripts/install-package.ts` correctly skips native
+binary download when `source/guiho-xdocs-bin.ts` exists, but
+`scripts/xdocs-bin.ts` still expected the vendor binary to appear and exited with
+an error.
+
+The selected fix is to make the package launcher prefer the native vendor binary
+when it exists, fall back to the TypeScript CLI when running from a source
+checkout, and only invoke the installer for published package layouts where the
+source entrypoint is absent.
+
+## Decisions
+
+1. Preserve native-binary-first execution for installed packages. Published npm
+   installs and `bunx` executions should still delegate to `vendor/xdocs` or
+   `vendor/xdocs.exe` after postinstall or first-run installation.
+2. Treat `source/guiho-xdocs-bin.ts` as the source-checkout fallback. This keeps
+   local development and repository-root package execution working without
+   downloading a release artifact.
+3. Keep package-root metadata consistent with the current layout. The package now
+   lives at the repository root, so `repository.directory`, `mirror.config.toml`,
+   `AGENTS.md`, `XDOCS.md`, and the root xdocs descriptor must not point at a
+   nested `xdocs/` package directory.
+
+## Rejected Alternatives
+
+1. Always download a native binary, even in source checkouts. This would make
+   development depend on an already-published release and would not test the
+   local TypeScript source being edited.
+2. Run `install-package.ts` first and infer its skip result from output. That
+   keeps the broken control flow indirect and noisy for normal source-checkout
+   commands.
+3. Remove the native launcher path entirely. That would regress the intended
+   CLI-only distribution where users can run the compiled binary without Node.js
+   or Bun at runtime after installation.
+
+## Validation
+
+The repair is validated by a regression test that executes
+`bun run scripts/xdocs-bin.ts --version` from the source checkout and asserts that
+it exits successfully without reporting a missing native binary.

package/docs/decisions/decisions.xdocs.md

@@ -0,0 +1,22 @@
+---
+subject: xdocs-decisions
+description: Decision records for xdocs implementation and operational repairs.
+parent: xdocs-docs
+children: []
+files: {}
+documents:
+  2026-07-09-package-launcher-source-fallback.md: Records the decision to make the package launcher fall back to the TypeScript CLI in source checkouts while published installs keep using native binaries.
+tags:
+  - documentation
+  - decisions
+keywords:
+  - decisions
+  - launcher
+  - source checkout
+flags: []
+status: stable
+---
+
+The `docs/decisions/` directory stores point-in-time technical decisions for
+xdocs. Each decision document captures context, selected behavior, rejected
+alternatives, and validation evidence for future agents and maintainers.

package/docs/docs.xdocs.md

@@ -0,0 +1,23 @@
+---
+subject: xdocs-docs
+description: Durable project documentation for xdocs behavior, design notes, and implementation context.
+parent: xdocs-package
+children:
+  - xdocs-decisions
+files: {}
+documents:
+  2026-07-05-xdocs-document-model.md: Defines the named descriptor plus companion Markdown document model for xdocs modules.
+tags:
+  - documentation
+  - design
+keywords:
+  - document model
+  - design notes
+  - companion documents
+flags: []
+status: stable
+---
+
+The `docs/` directory stores durable xdocs project notes. Plain Markdown
+documents directly in this directory are listed in `documents`; categorized
+subdirectories such as `decisions/` have their own xdocs descriptors.

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiho/xdocs",
-  "version": "0.3.1",
+  "version": "0.4.9",
   "exports": "./source/guiho-xdocs.ts",
   "publish": {
     "include": [

package/library/agents.d.ts

@@ -38,7 +38,7 @@ export declare const detectAgentTools: (cwd: string) => XDocsAgentTool[];
  */
 export declare const resolveInstallTools: (cwd: string, toolFlag: string | undefined) => XDocsAgentTool[];
 /** The small AGENTS.md section announcing xdocs and pointing to the skill. */
-export declare const xdocsAgentsSection = "<!-- BEGIN XDOCS \u2014 DO NOT EDIT THIS SECTION -->\n## XDocs Structured Documentation\n\nThis project uses **xdocs** (`@guiho/xdocs`) for structured, machine-readable\ndocumentation. The repository has one root `XDOCS.md` index (no frontmatter),\nand each package/application has a root `.xdocs.md` file. Each module carries a\n`.docs.md` / `.xdocs.md` file with YAML frontmatter (`subject`, `description`,\n`parent`, `children`, `files`).\n\n**Load the `guiho-s-xdocs` agent skill** for any documentation work:\ncreating, updating, regenerating, scanning, merging, or navigating xdocs files.\nThe skill holds the full workflow, metadata schema, and CLI reference.\n\nBefore changing documentation, read `xdocs.config.toml` and respect `[ai].mode`:\n\n- **prompt** \u2014 announce which xdocs files need updating and wait for confirmation.\n- **auto** \u2014 update the relevant xdocs files immediately.\n\nUse the xdocs CLI for operations: `xdocs scan`, `xdocs tree`, `xdocs generate`,\n`xdocs list`, `xdocs merge`.\n<!-- END XDOCS -->";
+export declare const xdocsAgentsSection = "<!-- BEGIN XDOCS \u2014 DO NOT EDIT THIS SECTION -->\n## XDocs Structured Documentation\n\nThis project uses **xdocs** (`@guiho/xdocs`) for structured, machine-readable\ndocumentation. The repository has one root `XDOCS.md` index (no frontmatter),\nand each package/application has a root named `*.xdocs.md` descriptor file. Each\ndocumented module has exactly one named `*.xdocs.md` descriptor in its directory\nwith YAML frontmatter (`subject`, `description`, `parent`, `children`,\n`files`, `documents`, `tags`, `keywords`, `flags`). Same-directory plain\n`*.md` files are companion documents and must be listed in the descriptor's\n`documents` metadata map. Ordinary companion documents should also include\n`keywords` in their own frontmatter.\n\n**Load the `guiho-s-xdocs` agent skill** for any documentation work:\ncreating, updating, regenerating, scanning, merging, or navigating xdocs descriptors.\nThe skill holds the full workflow, metadata schema, and CLI reference.\n\nBefore changing documentation, read `xdocs.config.toml` and respect `[ai].mode`:\n\n- **prompt** \u2014 announce which xdocs descriptors need updating and wait for confirmation.\n- **auto** \u2014 update the relevant xdocs descriptors immediately.\n\nUse the xdocs CLI for operations: `xdocs scan`, `xdocs tree`, `xdocs generate`,\n`xdocs list`, `xdocs merge`.\n<!-- END XDOCS -->";
 type SkillPathOptions = {
     cwd?: string;
     homeDirectory?: string;

package/library/agents.d.ts.map

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

package/library/agents.js

@@ -86,18 +86,22 @@ export const xdocsAgentsSection = `${AGENTS_BEGIN_MARKER}
 
 This project uses **xdocs** (\`@guiho/xdocs\`) for structured, machine-readable
 documentation. The repository has one root \`XDOCS.md\` index (no frontmatter),
-and each package/application has a root \`.xdocs.md\` file. Each module carries a
-\`.docs.md\` / \`.xdocs.md\` file with YAML frontmatter (\`subject\`, \`description\`,
-\`parent\`, \`children\`, \`files\`).
+and each package/application has a root named \`*.xdocs.md\` descriptor file. Each
+documented module has exactly one named \`*.xdocs.md\` descriptor in its directory
+with YAML frontmatter (\`subject\`, \`description\`, \`parent\`, \`children\`,
+\`files\`, \`documents\`, \`tags\`, \`keywords\`, \`flags\`). Same-directory plain
+\`*.md\` files are companion documents and must be listed in the descriptor's
+\`documents\` metadata map. Ordinary companion documents should also include
+\`keywords\` in their own frontmatter.
 
 **Load the \`${xdocsSkillName}\` agent skill** for any documentation work:
-creating, updating, regenerating, scanning, merging, or navigating xdocs files.
+creating, updating, regenerating, scanning, merging, or navigating xdocs descriptors.
 The skill holds the full workflow, metadata schema, and CLI reference.
 
 Before changing documentation, read \`xdocs.config.toml\` and respect \`[ai].mode\`:
 
-- **prompt** — announce which xdocs files need updating and wait for confirmation.
-- **auto** — update the relevant xdocs files immediately.
+- **prompt** — announce which xdocs descriptors need updating and wait for confirmation.
+- **auto** — update the relevant xdocs descriptors immediately.
 
 Use the xdocs CLI for operations: \`xdocs scan\`, \`xdocs tree\`, \`xdocs generate\`,
 \`xdocs list\`, \`xdocs merge\`.

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

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

package/library/commands/generate.js

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

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

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

package/library/commands/list.js

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

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

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

package/library/commands/merge.js

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

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

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

package/library/commands/scan.js

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

package/library/config.d.ts.map

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

package/library/config.js

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

package/library/discovery.d.ts

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

package/library/discovery.d.ts.map

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