@guiho/xdocs 0.3.1 → 0.4.9

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

@@ -23,33 +23,47 @@ if (await sourceEntrypoint.exists()) {
 
 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 candidates = detectAssetCandidates()
 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)
+for (const asset of candidates) {
+  const bundledAsset = Bun.file(new URL(`../bin/${asset}`, 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}`
+for (const asset of candidates) {
+  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)
+  console.log(`    Downloading ${asset} from GitHub Releases...`)
+  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)
+  if (!response.ok) {
+    if (candidates.length > 1 && asset !== candidates[candidates.length - 1]) {
+      console.log(`    ${asset} not available (${response.status}), trying next variant...`)
+      continue
+    }
+    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}`)
+  process.exit(0)
 }
 
-await Bun.write(destination, response)
-await makeExecutable(destination)
-console.log(`installed xdocs native binary: ${asset}`)
+console.error('error: no compatible xdocs binary found for this platform')
+process.exit(1)
 
 async function makeExecutable(path: URL) {
   if (process.platform === 'win32') return
@@ -66,10 +80,16 @@ async function makeExecutable(path: URL) {
   }
 }
 
-function detectAsset() {
+function detectAssetCandidates() {
   const os = detectOs()
   const arch = detectArch()
-  return `xdocs-${os}-${arch}${os === 'windows' ? '.exe' : ''}`
+  const ext = os === 'windows' ? '.exe' : ''
+
+  if (arch === 'x64') {
+    return [`xdocs-${os}-x64-baseline${ext}`, `xdocs-${os}-x64${ext}`, `xdocs-${os}-x64-modern${ext}`]
+  }
+
+  return [`xdocs-${os}-${arch}${ext}`]
 }
 
 function detectOs() {
@@ -85,4 +105,4 @@ function detectArch() {
   if (process.arch === 'arm64') return 'arm64'
   console.error(`error: unsupported architecture: ${process.arch}`)
   process.exit(1)
-}
+}

package/scripts/scripts.xdocs.md

@@ -4,17 +4,24 @@ description: Package-manager launcher and installation scripts for executing the
 parent: xdocs-package
 children: []
 files:
-  xdocs-bin.ts: Shipped Bun launcher used as the package bin; installs the native binary on first run when needed and delegates to it.
+  xdocs-bin.ts: Shipped Bun launcher used as the package bin; delegates to an installed native binary, falls back to the TypeScript CLI in source checkouts, and installs the native binary on first run for published packages.
   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 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.
+native binary is missing in a published package, it runs `install-package.ts` and
+then delegates to the downloaded binary in `vendor/`. Source checkouts run the
+TypeScript CLI directly when no vendor binary exists. Direct installers remain
+the no-Bun runtime path.

package/scripts/xdocs-bin.ts

@@ -6,10 +6,24 @@
  */
 
 const binaryPath = new URL(`../vendor/xdocs${process.platform === 'win32' ? '.exe' : ''}`, import.meta.url)
+const sourceEntrypointPath = new URL('../source/guiho-xdocs-bin.ts', import.meta.url)
 const executablePath = Bun.fileURLToPath(binaryPath)
 const binary = Bun.file(binaryPath)
+const args = process.argv.slice(2)
 
 if (!(await binary.exists())) {
+  const sourceEntrypoint = Bun.file(sourceEntrypointPath)
+
+  if (await sourceEntrypoint.exists()) {
+    const proc = Bun.spawn([process.execPath, Bun.fileURLToPath(sourceEntrypointPath), ...args], {
+      stdin: 'inherit',
+      stdout: 'inherit',
+      stderr: 'inherit',
+    })
+
+    process.exit(await proc.exited)
+  }
+
   const installerPath = new URL('install-package.ts', import.meta.url)
   const proc = Bun.spawn([process.execPath, Bun.fileURLToPath(installerPath)], {
     stdin: 'inherit',
@@ -24,10 +38,10 @@ if (!(await binary.exists())) {
   }
 }
 
-const proc = Bun.spawn([executablePath, ...process.argv.slice(2)], {
+const proc = Bun.spawn([executablePath, ...args], {
   stdin: 'inherit',
   stdout: 'inherit',
   stderr: 'inherit',
 })
 
-process.exit(await proc.exited)
+process.exit(await proc.exited)

package/skills/guiho-s-xdocs/SKILL.md

@@ -1,15 +1,30 @@
 ---
 name: guiho-s-xdocs
-version: 0.3.0
-description: Use this skill whenever the user works with xdocs (`@guiho/xdocs`) structured documentation, AND proactively whenever you create a new module or subdirectory or add/change/remove files in a directory of an xdocs project, so you create or update that directory's `.xdocs.md` as part of the change. This includes creating, updating, or regenerating `.docs.md` / `.xdocs.md` files, the root `XDOCS.md`, the project tree, scanning documentation coverage, merging docs, or maintaining xdocs metadata and AGENTS.md guidance, even when the user only says "document this module", "update the docs", or "what does this folder do" without naming xdocs.
+version: 0.4.0
+purpose: Teach AI agents how to maintain xdocs descriptor files, companion Markdown documents, metadata, and tree integrity.
+description: Use this skill whenever the user works with xdocs (`@guiho/xdocs`) structured documentation, AND proactively whenever you create a new module or subdirectory or add/change/remove files in a directory of an xdocs project, so you create or update that directory's named `*.xdocs.md` descriptor as part of the change. This includes creating, updating, or regenerating `*.xdocs.md` descriptor files, companion Markdown documents, the root `XDOCS.md`, the project tree, scanning documentation coverage, merging docs, or maintaining xdocs metadata and AGENTS.md guidance, even when the user only says "document this module", "update the docs", or "what does this folder do" without naming xdocs.
+created: 2026-07-06
+flags:
+  - automatic-documentation-maintenance
+  - companion-document-metadata
+tags:
+  - xdocs
+  - documentation
+  - agents
+keywords:
+  - xdocs
+  - structured documentation
+  - companion documents
+  - agent workflow
+owner: xdocs-guiho-s-xdocs-skill
 ---
 
 # GUIHO XDocs
 
-GUIHO XDocs is a deterministic CLI and TypeScript library for **structured documentation of codebases**. It lets an AI agent understand a project without reading every source file: each directory carries a small Markdown file with YAML frontmatter that describes its subject, purpose, files, and place in a parent-child hierarchy.
+GUIHO XDocs is a deterministic CLI and TypeScript library for **structured documentation of codebases**. It lets an AI agent understand a project without reading every source file: each documented directory carries one named `*.xdocs.md` descriptor with YAML frontmatter that describes its subject, purpose, files, companion Markdown documents, and place in a parent-child hierarchy.
 
 ```text
-source tree -> xdocs files (.docs.md / .xdocs.md) -> tree + metadata -> AI-readable map
+source tree -> named *.xdocs.md descriptors + companion *.md documents -> tree + metadata -> AI-readable map
 ```
 
 Use xdocs for documentation work instead of ad hoc README sprawl or re-reading the whole codebase. The value of xdocs is that the structure (subjects, descriptions, files, parent/child links) is machine-readable and stays close to the code it describes.
@@ -28,15 +43,16 @@ xdocs is a Bun/TypeScript ESM tool. Bun is the recommended runtime. The CLI neve
 
 ## Core Concepts
 
-- **xdocs file**: a Markdown file with YAML frontmatter that documents one directory/module. Default extensions are `.docs.md` and `.xdocs.md`. Extensions are configurable in `xdocs.config.toml`.
+- **xdocs descriptor**: a named Markdown file ending in `.xdocs.md` with YAML frontmatter that documents one directory/module. There is exactly one descriptor per documented directory. The file must have a name such as `authentication.xdocs.md`; a file named only `.xdocs.md` is invalid.
+- **Companion document**: a same-directory plain Markdown file ending in `.md` but not `.xdocs.md` and not `XDOCS.md`. Every companion document must be listed in the descriptor's `documents` metadata map, and ordinary companion documents should carry their own YAML frontmatter with `name`, `purpose`, `description`, `created`, `flags`, `tags`, `keywords`, and `owner`.
 - **Repository root index**: there is exactly one `XDOCS.md` per repository, at the repo root. It has **no frontmatter** — it is a plain index that lists the repository's packages and applications, and it is not itself a tree node.
 - **Package/application root**: each package or application has its own root `.xdocs.md` file (with frontmatter and `parent: null`) that is the top of that package's documentation tree. `XDOCS.md` lists these package roots.
-- **Tree**: a parent-child **containment** hierarchy (not a dependency graph), assembled from each `.xdocs.md` / `.docs.md` file's `subject` / `parent` / `children` fields. A module's `parent` is the `subject` of the module that contains it; a package/application root uses `parent: null`.
+- **Tree**: a parent-child **containment** hierarchy (not a dependency graph), assembled from each `.xdocs.md` descriptor's `subject` / `parent` / `children` fields. A module's `parent` is the `subject` of the module that contains it; a package/application root uses `parent: null`.
 - **AI mode**: `xdocs.config.toml` `[ai].mode` is either `"prompt"` (announce the documentation updates, then write them) or `"auto"` (write immediately). It governs *how* you write docs, not *whether* — documenting a changed module is always required (see Automatic Documentation Maintenance).
 
 ### Metadata schema (YAML frontmatter)
 
-Every `.xdocs.md` / `.docs.md` file carries frontmatter with these fields. The repository's single `XDOCS.md` is the exception: it has no frontmatter and is just an index.
+Every `*.xdocs.md` descriptor carries frontmatter with these fields. The repository's single `XDOCS.md` is the exception: it has no frontmatter and is just an index.
 
 | Field         | Type                  | Meaning                                                       |
 | ------------- | --------------------- | ------------------------------------------------------------ |
@@ -45,29 +61,74 @@ Every `.xdocs.md` / `.docs.md` file carries frontmatter with these fields. The r
 | `parent`      | string \| null        | `subject` of the containing module; `null` for a package/application root. |
 | `children`    | string[]              | `subject`s of directly contained modules.                    |
 | `files`       | map<string,string>    | Filename -> short description of each significant file.      |
+| `documents`   | map<string,string>    | Same-directory plain Markdown filename -> short description. |
 | `tags`        | string[]              | Free-form classification labels.                             |
+| `keywords`    | string[]              | Search terms and concepts agents can use to match requests.  |
 | `flags`       | string[]              | Behavioral markers for tools/agents.                         |
 | `status`      | string (optional)     | Lifecycle marker (e.g. `stable`, `draft`, `deprecated`).     |
 
-Keep `subject` values unique across the project, keep `parent`/`children` consistent in both directions, and keep `files` in sync with what is actually on disk.
+Keep `subject` values unique across the project, keep `parent`/`children` consistent in both directions, keep `files` in sync with implementation files, and keep `documents` in sync with same-directory plain Markdown files.
+
+### Companion document metadata (YAML frontmatter)
+
+Ordinary same-directory companion Markdown documents also use YAML frontmatter.
+This metadata makes the document useful before an agent reads the whole body.
+The `owner` field must be the `subject` of the same-directory xdocs descriptor
+that owns the document.
+
+```yaml
+---
+name: authentication-implementation
+purpose: Explain the implementation details and decisions behind authentication.
+description: Detailed notes for login, password verification, and session behavior.
+created: 2026-07-06
+flags: []
+tags:
+  - security
+keywords:
+  - login
+  - password verification
+  - sessions
+owner: auth
+---
+```
+
+Companion document fields:
+
+| Field         | Type       | Meaning                                                        |
+| ------------- | ---------- | -------------------------------------------------------------- |
+| `name`        | string     | Stable document name or title.                                 |
+| `purpose`     | string     | Why this document exists and what question it answers.         |
+| `description` | string     | One-line summary of the document's contents.                   |
+| `created`     | string     | Creation date in `YYYY-MM-DD` format.                          |
+| `flags`       | string[]   | Behavioral markers for tools/agents.                           |
+| `tags`        | string[]   | Free-form classification labels.                               |
+| `keywords`    | string[]   | Search terms and concepts agents can use to match requests.    |
+| `owner`       | string     | Owning xdocs descriptor `subject` in the same directory.        |
+
+Special-purpose Markdown files that already have a required host schema, such
+as prompt templates or `SKILL.md`, must preserve their required host fields.
+When compatible, add the companion metadata fields as well.
 
 ## Automatic Documentation Maintenance (core responsibility)
 
-Maintaining xdocs files is an **automatic, built-in responsibility — not a task the user has to request.** Treat it as part of the definition of done for every code change in an xdocs project. The user should never have to ask you to document a module; you do it as a reflex whenever you touch one.
+Maintaining xdocs descriptors is an **automatic, built-in responsibility — not a task the user has to request.** Treat it as part of the definition of done for every code change in an xdocs project. The user should never have to ask you to document a module; you do it as a reflex whenever you touch one.
 
-**Trigger.** Whenever you, as the agent, do any of the following, you must create or update the affected directory's xdocs file in the *same unit of work*, before you consider the task finished:
+**Trigger.** Whenever you, as the agent, do any of the following, you must create or update the affected directory's named xdocs descriptor in the *same unit of work*, before you consider the task finished:
 
 - Create a new directory, module, or subpackage.
 - Add, rename, move, or delete significant files in a directory.
+- Add, rename, move, or delete sibling plain Markdown documents in a directory.
 - Change what a module does, what it exposes, or how it relates to its parent or children.
 
 **Action.**
 
-- If the directory has **no** xdocs file, create one (for example `<name>.xdocs.md`) in that directory.
-- If it **already** has one, update it so it matches the new reality.
+- If the directory has **no** xdocs descriptor, create one named `<name>.xdocs.md` in that directory.
+- If it **already** has one, update it so it matches the new reality. If there is more than one descriptor, consolidate to one.
+- Never create or keep a descriptor named only `.xdocs.md`. `.xdocs.md` is the extension, not the whole filename.
 - Then fix the parent/child links and verify with `<xdocs> tree`.
 
-**What every module's xdocs file must capture:**
+**What every module's xdocs descriptor must capture:**
 
 - `subject` — the module's unique name in the tree.
 - `description` — the module's **purpose**: what it is for and what it does.
@@ -75,12 +136,16 @@ Maintaining xdocs files is an **automatic, built-in responsibility — not a tas
 - `parent` — the `subject` of the containing module (and add this module to that parent's `children`).
 - `children` — the `subject`s of the modules contained inside this one.
 
-**Do not wait to be asked.** After you finish creating or modifying a module or directory, create or update its xdocs file as part of the same change. A code change that adds or alters a module is **not complete** until its xdocs file and the affected parent/child links are updated.
+Every descriptor also includes `documents`, a map from each same-directory plain Markdown filename to the purpose of that companion document.
+Each ordinary companion document listed there should include its own frontmatter
+with `owner` equal to this descriptor's `subject`.
+
+**Do not wait to be asked.** After you finish creating or modifying a module or directory, create or update its xdocs descriptor as part of the same change. A code change that adds or alters a module is **not complete** until its xdocs descriptor, companion-document list, and affected parent/child links are updated.
 
 **How `[ai].mode` applies.** The mode controls only *how* you write the docs, never *whether* you write them and never whether the user must ask first:
 
-- `auto` — create/update the xdocs files immediately as part of the change, then report what changed.
-- `prompt` — state exactly which xdocs files you are creating or updating, then write them (honoring any pending confirmation). Announcing is for transparency; it does not make documentation optional and the user never has to request it.
+- `auto` — create/update the xdocs descriptors immediately as part of the change, then report what changed.
+- `prompt` — state exactly which xdocs descriptors you are creating or updating, then write them (honoring any pending confirmation). Announcing is for transparency; it does not make documentation optional and the user never has to request it.
 
 ### Example: documenting a new module
 
@@ -95,8 +160,14 @@ children: []
 files:
   login.ts: Email/password login flow; exports `login()` and `verifyPassword()`.
   session.ts: Session lifecycle; exports `createSession()` and `validateSession()`.
+documents:
+  authentication-implementation.md: Companion notes that explain implementation details and decisions.
 tags:
   - security
+keywords:
+  - authentication
+  - login
+  - sessions
 flags: []
 status: stable
 ---
@@ -105,7 +176,31 @@ Auth validates credentials and issues sessions. `login()` delegates password
 checks to `verifyPassword()`; sessions are created and validated in `session.ts`.
 ```
 
-Then add `auth` to the `children` list of the `src` module's xdocs file so the tree stays consistent.
+Then create or update `src/auth/authentication-implementation.md` with
+companion-document frontmatter:
+
+```markdown
+---
+name: authentication-implementation
+purpose: Explain authentication implementation details and decisions.
+description: Detailed notes for login, password verification, and session behavior.
+created: 2026-07-06
+flags: []
+tags:
+  - security
+keywords:
+  - authentication
+  - password verification
+  - session lifecycle
+owner: auth
+---
+
+# Authentication Implementation
+
+Describe the implementation details that are too long for `auth.xdocs.md`.
+```
+
+Then add `auth` to the `children` list of the `src` module's xdocs descriptor so the tree stays consistent.
 
 If the directory you are documenting is the **root of a package or application** (not a sub-module), set `parent: null` instead, and list that package's root `.xdocs.md` in the repository's single `XDOCS.md` index rather than in a parent module's `children`.
 
@@ -115,23 +210,26 @@ When you start working in a project that uses xdocs:
 
 1. Read the root `XDOCS.md` to learn the project's top-level subject and structure.
 2. Run `<xdocs> tree` to see the module hierarchy.
-3. Run `<xdocs> scan` to see documentation coverage and which directories are missing xdocs files.
-4. Read `xdocs.config.toml` and note `[ai].mode`, the supported `[extensions]`, and `[scan].exclude`.
-5. When you navigate into a module, read that module's xdocs file (frontmatter first, body only if you need more) instead of reading every source file.
+3. Run `<xdocs> scan` to see documentation coverage, invalid descriptors, and companion-document coverage.
+4. Read `xdocs.config.toml` and note `[ai].mode` and `[scan].exclude`; xdocs descriptors always use the `.xdocs.md` suffix.
+5. When you navigate into a module, read that module's named `*.xdocs.md` descriptor frontmatter first. Read listed companion documents only when their descriptions show they are relevant.
 
 ## Documentation Workflow (writing and updating)
 
 Follow this whenever the automatic trigger above fires, or when the user asks to document a directory:
 
-1. Determine the target directory and whether it already has an xdocs file (`<xdocs> scan` or `<xdocs> list <path>`).
+1. Determine the target directory and whether it already has exactly one named `*.xdocs.md` descriptor (`<xdocs> scan` or `<xdocs> list <path>`).
 2. Read the directory's actual files so the documentation reflects reality. Never invent files, modules, or behavior that is not present.
 3. Respect `[ai].mode` (it controls how you write, not whether you write):
-   - **prompt mode**: state exactly which xdocs files you are creating or updating, then write them (honor a pending confirmation, but never skip the documentation).
-   - **auto mode**: create or update the xdocs files immediately, then report what changed.
-4. Write or update the xdocs file with correct frontmatter:
-   - Set `subject` (unique), `description` (the module's purpose), and `files` (each real file -> short purpose, including key functions/exports).
+   - **prompt mode**: state exactly which xdocs descriptors you are creating or updating, then write them (honor a pending confirmation, but never skip the documentation).
+   - **auto mode**: create or update the xdocs descriptors immediately, then report what changed.
+4. Write or update the xdocs descriptor with correct frontmatter:
+   - Set `subject` (unique), `description` (the module's purpose), and `files` (each real implementation/configuration file -> short purpose, including key functions/exports).
+   - Set `documents` to every same-directory plain Markdown file -> short purpose. Use `{}` when there are no companion documents.
+   - Set `keywords` to search terms and concepts that should help agents match user requests to the module.
+   - For each ordinary companion document, add or update frontmatter with `name`, `purpose`, `description`, `created`, `flags`, `tags`, `keywords`, and `owner`; set `owner` to the descriptor's `subject`.
    - Set `parent` to the containing module's `subject`, and add this `subject` to that parent's `children`.
-   - Use `tags`/`flags`/`status` where useful.
+   - Use `tags`/`keywords`/`flags`/`status` where useful.
 5. Keep the tree consistent: if you add a module, update its parent's `children`; if you remove one, update both sides.
 6. Validate with `<xdocs> tree` (it reports duplicate subjects, orphans, and missing children) and fix any reported issues.
 
@@ -150,7 +248,8 @@ When generating from scratch, prefer `<xdocs> generate <path>` (one directory) o
 
 ## Safety Rules
 
-- Never leave a new or changed module undocumented. Creating or updating its xdocs file is part of finishing the work, not a separate request the user must make.
+- Never leave a new or changed module undocumented. Creating or updating its xdocs descriptor is part of finishing the work, not a separate request the user must make.
+- Never leave an ordinary companion Markdown document without useful frontmatter; it should identify its `owner`, purpose, tags, keywords, and flags.
 - Never fabricate files, modules, descriptions, or relationships. Documentation must match the repository.
 - Never edit generated or build outputs (`library/`, `bundle/`, `bin/`, `*.tgz`). They are ignored and regenerated.
 - In prompt mode, announce the xdocs changes you will make and honor a pending confirmation — but still treat documenting the change as required, never optional.
@@ -166,7 +265,7 @@ xdocs searches for configuration via `--config <path>`, `./xdocs.config.toml`, o
 schema = 1
 
 [extensions]
-supported = [".docs.md", ".xdocs.md"]
+supported = [".xdocs.md"]
 
 [ai]
 mode = "prompt"            # "prompt" (announce and wait) or "auto" (update immediately)
@@ -185,15 +284,17 @@ skill_tool = "agents"      # default tool for auto-install: agents (standard) or
 
 Agent automation options default to true. A bare `xdocs` invocation and normal data commands always bootstrap the standard global skill when no config is present; with config, set `auto_agents_md = false` to stop xdocs from touching AGENTS.md, and `auto_skill_install = false` to stop xdocs from installing or refreshing `guiho-s-xdocs` globally.
 
+The `[extensions]` section is retained for config compatibility, but the only supported descriptor suffix is `.xdocs.md`.
+
 ## CLI Reference
 
 ```bash
 xdocs init                     # create XDOCS.md + xdocs.config.toml, update AGENTS.md, install the skill
-xdocs scan                     # report xdocs coverage across the project
+xdocs scan                     # report descriptor and companion-document coverage
 xdocs tree                     # print the module hierarchy
-xdocs list <path>              # list files in a scope with descriptions
+xdocs list <path>              # list files and companion documents with descriptions
 xdocs generate [path]          # draft documentation for a directory or the whole project
-xdocs merge [path]             # merge a directory's xdocs files into one document
+xdocs merge [path]             # merge a directory's xdocs descriptors into one document
 xdocs prompt --name=<name>     # print a ready-made AI prompt (write|update|agents|generate)
 xdocs agents install local     # install guiho-s-xdocs into this project (.agents/skills/...)
 xdocs agents install global    # install guiho-s-xdocs into the user home skills directory
@@ -252,7 +353,7 @@ await ensureAgentsInstructions(process.cwd(), true)
 When reporting an xdocs result, include:
 
 - The command that ran and the target path.
-- Which xdocs files were created or changed, if any.
+- Which xdocs descriptors and companion documents were created or changed, if any.
 - Tree/coverage status (subjects added, orphans or duplicates resolved).
 - The configured AI mode, and — in prompt mode — exactly what you are waiting to write.
 

package/skills/guiho-s-xdocs/guiho-s-xdocs.xdocs.md

@@ -0,0 +1,26 @@
+---
+subject: xdocs-guiho-s-xdocs-skill
+description: Packaged guiho-s-xdocs agent skill that teaches AI agents how to maintain xdocs projects.
+parent: xdocs-skills
+children: []
+files: {}
+documents:
+  SKILL.md: Versioned xdocs workflow skill installed into .agents/skills or .claude/skills; defines descriptor, companion-document metadata, scan, tree, and maintenance rules.
+tags:
+  - skills
+  - agents
+  - documentation
+keywords:
+  - xdocs skill
+  - companion metadata
+  - agent workflow
+flags: []
+status: stable
+---
+
+The `guiho-s-xdocs/` directory contains the bundled agent skill shipped with the
+package. The installer treats `SKILL.md` as the source of truth and refreshes
+installed copies when the bundled version or content changes.
+The skill also documents the standard frontmatter fields expected on ordinary
+companion Markdown documents: `name`, `purpose`, `description`, `created`,
+`flags`, `tags`, `keywords`, and `owner`.

package/skills/skills.xdocs.md

@@ -2,13 +2,18 @@
 subject: xdocs-skills
 description: Bundled AI-agent skills shipped with @guiho/xdocs and installed by the xdocs agents commands.
 parent: xdocs-package
-children: []
-files:
-  guiho-s-xdocs/SKILL.md: Versioned xdocs workflow skill installed into .agents/skills or .claude/skills; replaces legacy guiho-as-xdocs installs when refreshed.
+children:
+  - xdocs-guiho-s-xdocs-skill
+files: {}
+documents: {}
 tags:
   - skills
   - agents
   - documentation
+keywords:
+  - agent skills
+  - bundled skill
+  - skill installation
 flags: []
 status: stable
 ---
@@ -16,4 +21,4 @@ status: stable
 The `skills/` directory contains the bundled `guiho-s-xdocs` agent skill. The
 installer treats this packaged skill as the current source of truth, removes
 legacy `guiho-as-xdocs` install directories, and refreshes installed copies when
-their frontmatter version or content differs from the bundled file.
+their frontmatter version or content differs from the bundled file.