@guiho/xdocs 0.3.0-alpha.2 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # GUIHO XDocs Changelog
 
+## 0.4.0-alpha.0
+
+- Change the documentation model to one named `*.xdocs.md` descriptor per documented directory, with `XDOCS.md` reserved as the frontmatter-less repository index.
+- Add first-class same-directory Markdown companion documents through the required `documents` metadata map, and validate descriptor/document alignment during scan.
+- Reject nameless `.xdocs.md` descriptors, reject non-`.xdocs.md` descriptor extensions, and flag multiple descriptors in one directory.
+- Update `scan`, `list`, `generate`, and `merge` output to surface both implementation files and companion Markdown documents.
+- Add required `keywords` metadata to xdocs descriptors, surface descriptor keywords in scan/generate/merge output, and document companion Markdown `keywords` frontmatter.
+- Refresh the bundled `guiho-s-xdocs` skill, prompt templates, README, architecture notes, AGENTS guidance, canonical `DOCS.md`, and package xdocs descriptors for the new model.
+
+## 0.3.1
+
+- Fix bare `xdocs` invocations so they install or refresh the global `guiho-s-xdocs` skill before printing help, even without `xdocs.config.toml`, and remove legacy `guiho-as-xdocs` installs for that target.
+- Change the package-manager `xdocs` bin to a shipped Bun launcher (`scripts/xdocs-bin.ts`) that installs the native binary on first run when needed, matching GUIHO Mirror's `bun x` behavior.
+
+## 0.3.0
+
+- Stabilize the 0.3.0 release line, including native binary distribution, direct installers, package-manager native binary installation, and Bun-native TOML/YAML parsing.
+- Ship the renamed `guiho-s-xdocs` agent skill with versioned frontmatter, automatic refresh from the bundled package copy, and legacy `guiho-as-xdocs` cleanup.
+- Refresh README guidance and regression coverage for the stable release.
+
 ## 0.3.0-alpha.2
 
 - Rename the bundled xdocs agent skill from `guiho-as-xdocs` to `guiho-s-xdocs` and add a frontmatter `version` field.

package/DOCS.md

@@ -1,9 +1,9 @@
 # GUIHO XDocs Documentation -- @guiho/xdocs
 
-GUIHO XDocs is a deterministic CLI and TypeScript library for structured documentation of codebases. Each directory carries a small Markdown file with YAML frontmatter that describes its subject, purpose, files, and place in a parent-child hierarchy, so an AI agent (or a human) can understand a project without reading every source file.
+GUIHO XDocs is a deterministic CLI and TypeScript library for structured documentation of codebases. Each documented directory carries exactly one named `*.xdocs.md` descriptor with YAML frontmatter that describes its subject, purpose, files, companion Markdown documents, and place in a parent-child hierarchy, so an AI agent (or a human) can understand a project without reading every source file.
 
 ```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
 ```
 
 XDocs is a documentation tool, not a versioning tool. It never bumps versions or mutates `package.json` version fields. Versioning for this project is handled separately by GUIHO Mirror.
@@ -13,7 +13,7 @@ XDocs is a documentation tool, not a versioning tool. It never bumps versions or
 - Package name: `@guiho/xdocs`
 - Source/runtime during development: Bun and TypeScript (ESM)
 - Primary release runtime: compiled native Bun binary assets
-- Package-manager install path: Node.js is used only for `postinstall`; the installed `xdocs` command executes the native binary
+- Package-manager install path: the shipped Bun launcher runs `postinstall` or first-run native binary installation, then executes the native binary
 - Package type: ESM
 - Library entrypoint: `source/guiho-xdocs.ts`
 - CLI entrypoint: `source/guiho-xdocs-bin.ts`
@@ -21,24 +21,25 @@ XDocs is a documentation tool, not a versioning tool. It never bumps versions or
 - Standalone binary output: `bin/xdocs-*` release assets
 - Runtime parser dependencies: none; xdocs uses Bun-native TOML and YAML parsing
 
-The public package exposes a CLI named `xdocs` and a TypeScript API for discovering xdocs files, parsing metadata, building the hierarchy tree, generating documentation, and installing the agent skill.
+The public package exposes a CLI named `xdocs` and a TypeScript API for discovering xdocs descriptors and companion Markdown documents, parsing metadata, building the hierarchy tree, generating documentation, and installing the agent skill.
 
 ## Core Model
 
 XDocs describes a repository as a containment hierarchy of documented modules.
 
 - Project: the repository being documented.
-- xdocs file: a Markdown file with YAML frontmatter that documents one directory/module.
+- xdocs descriptor: a named Markdown file ending in `.xdocs.md` with YAML frontmatter that documents one directory/module. 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`. Companion documents are listed in the descriptor's `documents` metadata map.
 - Repository root index: exactly one `XDOCS.md` per repository, at the repo root. It has **no frontmatter** and is not a tree node; it is a plain index that lists the repository's packages and applications.
 - 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.
+- Tree: a parent-child containment hierarchy (not a dependency graph) assembled from each `.xdocs.md` descriptor's `subject` / `parent` / `children` fields.
 - AI mode: how an agent should behave when documentation needs updating, configured by `[ai].mode`.
 
-The tree is the main mental model. A module's xdocs file names the module (`subject`), points up to its container (`parent`), and lists the modules it contains (`children`). A package root sets `parent: null`. Reading metadata first, and the body only when needed, lets an agent navigate a project cheaply.
+The tree is the main mental model. A module's xdocs descriptor names the module (`subject`), points up to its container (`parent`), lists the modules it contains (`children`), and lists sibling companion documents (`documents`). A package root sets `parent: null`. Reading metadata first, and companion documents only when relevant, lets an agent navigate a project cheaply.
 
-## xdocs Files and Metadata
+## xdocs Descriptors and Metadata
 
-A module's xdocs file is Markdown with a YAML frontmatter block delimited by `---`. The body below the frontmatter is free-form Markdown. (The repository's single `XDOCS.md` is the one exception — it has no frontmatter and is just an index.)
+A module's xdocs descriptor is Markdown with a YAML frontmatter block delimited by `---`. The body below the frontmatter is free-form Markdown. The repository's single `XDOCS.md` is the one exception: it has no frontmatter and is just an index.
 
 ```markdown
 ---
@@ -51,8 +52,14 @@ children:
 files:
   login.ts: Email/password login handler.
   session.ts: Session creation and validation.
+documents:
+  authentication-implementation.md: Detailed implementation notes and decisions.
 tags:
   - security
+keywords:
+  - authentication
+  - login
+  - sessions
 flags: []
 status: stable
 ---
@@ -69,15 +76,41 @@ Frontmatter fields:
 | `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, for example `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 on disk.
+Keep `subject` values unique across the project, keep `parent`/`children` consistent in both directions, keep `files` in sync with implementation/configuration files, keep `documents` in sync with same-directory plain Markdown files, and keep `keywords` useful for search/matching.
 
 ## File Discovery and Extensions
 
-XDocs discovers documentation files by extension. The default recognized extensions are `.docs.md` and `.xdocs.md`, configurable in `[extensions].supported`. The root `XDOCS.md` is always recognized.
+XDocs discovers module descriptors by the fixed `.xdocs.md` suffix. Descriptors must be named, for example `authentication.xdocs.md`; `.xdocs.md` by itself is invalid. The root `XDOCS.md` is always recognized only as the repository index.
+
+XDocs also discovers same-directory plain Markdown documents ending in `.md` that are not `*.xdocs.md` and not `XDOCS.md`. Each plain Markdown companion document must be listed in the containing directory descriptor's `documents` metadata map.
+
+Ordinary companion Markdown documents should also have YAML frontmatter so agents
+can decide whether to read the body. The standard companion fields are `name`,
+`purpose`, `description`, `created`, `flags`, `tags`, `keywords`, and `owner`.
+The `owner` value is the owning descriptor's `subject`.
+
+```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
+---
+```
 
 Scanning walks the project tree and skips directories listed in `[scan].exclude`. The default exclusions are `node_modules`, `.git`, `dist`, `build`, `library`, `bin`, and `bundle`.
 
@@ -93,7 +126,7 @@ curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/install.sh | sh
 irm https://raw.githubusercontent.com/CGuiho/xdocs/main/install.ps1 | iex
 ```
 
-Install XDocs as a development dependency through a JavaScript package manager. This uses Node.js during `postinstall` to download the matching native binary, then the installed `xdocs` command executes the native binary:
+Install XDocs as a development dependency through a JavaScript package manager. Package-manager execution uses the shipped Bun launcher, which downloads the matching native binary during `postinstall` or on first run if the install hook did not run, then executes the native binary:
 
 ```bash
 bun add -d @guiho/xdocs
@@ -105,7 +138,7 @@ Or with npm:
 npm install -D @guiho/xdocs
 ```
 
-Use the direct installer when you do not want a JavaScript package manager involved. Use the package-manager install when you want project-local dependency management; after installation, `xdocs` still runs as a native binary.
+Use the direct installer when you do not want a JavaScript package manager or Bun involved at runtime. Use the package-manager install when you want project-local dependency management or `bunx` execution; the shipped Bun launcher ensures the native binary exists and delegates to it.
 
 ## Quick Start
 
@@ -169,7 +202,7 @@ Flags: `--tool <agents|claude|all>`, `--global`, `--cwd`, `--verbose`.
 
 ### `xdocs scan`
 
-Walks every directory (respecting `[scan].exclude`), matches files against the configured extensions, and reports coverage: total files, total directories, covered vs uncovered directories, and the discovered xdocs files with validity status. Use `--verbose` to list per-file errors and uncovered directories.
+Walks every directory (respecting `[scan].exclude`), finds named `*.xdocs.md` descriptors and sibling plain `*.md` companion documents, and reports coverage: total files, total directories, companion-document count, covered vs uncovered directories, and discovered xdocs descriptors with validity status. JSON output includes descriptor keywords. Use `--verbose` to list per-file errors, discovered companion documents, and uncovered directories.
 
 ```bash
 xdocs scan
@@ -180,7 +213,7 @@ Flags: `--format <text|json>`, `--cwd`, `--config`, `--verbose`.
 
 ### `xdocs generate [path]`
 
-Generates Markdown documentation. With no path, it produces a project-level document containing the hierarchy and a section per module. With a path, it produces a module-level document for that directory. Output goes to stdout unless `--output <path>` is given.
+Generates Markdown documentation. With no path, it produces a project-level document containing the hierarchy and a section per module, including keywords, files, and companion documents. With a path, it produces a module-level document for that directory. Output goes to stdout unless `--output <path>` is given.
 
 ```bash
 xdocs generate                       # whole project to stdout
@@ -192,7 +225,7 @@ Flags: `--output <path>`, `--cwd`, `--config`, `--verbose`.
 
 ### `xdocs merge [path]`
 
-Concatenates all xdocs files within a directory into a single Markdown document, each section prefixed with a `<!-- source: ... -->` marker. Output goes to stdout unless `--output <path>` is given.
+Concatenates all xdocs descriptors within a directory into a single Markdown document, each section prefixed with a `<!-- source: ... -->` marker and including keywords plus both `files` and `documents` metadata. Output goes to stdout unless `--output <path>` is given.
 
 ```bash
 xdocs merge ./src/domain
@@ -203,7 +236,7 @@ Flags: `--output <path>`, `--cwd`, `--config`, `--verbose`.
 
 ### `xdocs tree`
 
-Scans all xdocs files, reads their metadata, and assembles the parent-child hierarchy (modules only, not individual files). With `--verbose`, tree integrity warnings and errors (duplicate subjects, orphans, missing children) are printed to stderr.
+Scans all xdocs descriptors, reads their metadata, and assembles the parent-child hierarchy (modules only, not individual files or companion documents). With `--verbose`, tree integrity warnings and errors (duplicate subjects, orphans, missing children) are printed to stderr.
 
 ```bash
 xdocs tree
@@ -215,7 +248,7 @@ Flags: `--format <text|markdown|json>`, `--output <path>`, `--cwd`, `--config`,
 
 ### `xdocs list [path]`
 
-Lists every documented file in a scope with a short description pulled from the `files` metadata field.
+Lists every documented implementation file and companion Markdown document in a scope with short descriptions pulled from the `files` and `documents` metadata fields. JSON entries include a `kind` field with `file` or `document`.
 
 ```bash
 xdocs list
@@ -231,8 +264,8 @@ Outputs a ready-made, self-contained instruction prompt for an AI agent. The pro
 
 Available prompts:
 
-- `write`: Scan a directory and write xdocs documentation.
-- `update`: Update existing xdocs files after code changes.
+- `write`: Scan a directory and write a named xdocs descriptor.
+- `update`: Update existing xdocs descriptors after code or document changes.
 - `agents`: Update `AGENTS.md` with xdocs instructions.
 - `generate`: Generate comprehensive documentation.
 
@@ -285,7 +318,7 @@ Full configuration example:
 schema = 1
 
 [extensions]
-supported = [".docs.md", ".xdocs.md"]
+supported = [".xdocs.md"]
 
 [ai]
 mode = "prompt"
@@ -308,7 +341,7 @@ Optional. When present, must be `1`.
 
 ### `[extensions]`
 
-- `supported`: Array of file extensions recognized as xdocs files. Default: `[".docs.md", ".xdocs.md"]`.
+- `supported`: Compatibility field for descriptor suffixes. The only supported value is `[".xdocs.md"]`; other extensions are rejected.
 
 ### `[ai]`
 
@@ -324,7 +357,7 @@ Optional. When present, must be `1`.
 
 ### `[agents]`
 
-Agent settings control skill installation and the automation that runs on data commands.
+Agent settings control skill installation and the automation that runs on bare and data commands.
 
 - `auto_agents_md`: Keep the `AGENTS.md` xdocs section fresh on normal commands when `AGENTS.md` already exists. Default: `true`.
 - `auto_skill_install`: Install or refresh the configured skill globally from the bundled package copy. Default: `true`.
@@ -349,22 +382,23 @@ The rule is: default to the standard target. Only write non-standard files (`.cl
 
 ### Automation
 
-When an `xdocs.config.toml` is present, the data commands (`scan`, `generate`, `merge`, `tree`, `list`) run config-gated agent automation before executing:
+Bare `xdocs` invocations and the data commands (`scan`, `generate`, `merge`, `tree`, `list`) run agent automation before executing:
 
-- If `auto_agents_md` is true and `AGENTS.md` exists, the xdocs section is kept fresh.
-- If `auto_skill_install` is true, XDocs ensures the configured global skill is current from the bundled package copy, removing legacy skill names and printing a one-line notice to stderr when it installs or refreshes anything.
+- XDocs always bootstraps the global skill with default settings when no config is present, using the standard `agents` target.
+- When `xdocs.config.toml` is present and `auto_agents_md` is true, the xdocs section is kept fresh if `AGENTS.md` exists.
+- When config is present and `auto_skill_install` is true, XDocs ensures the configured global skill is current from the bundled package copy, removing legacy skill names and printing a one-line notice to stderr when it installs or refreshes anything.
 
-Automation does nothing outside an xdocs project (no config discovered). `init` and `agents` do not run this automation; they manage agent files explicitly.
+`--help` and `--version` stay read-only. `init` and `agents` do not run this automation; they manage agent files explicitly.
 
 ## AI Usage Workflow
 
-Maintaining xdocs files is an automatic responsibility for an agent working in an xdocs project, not something the user has to request. The intended workflow:
+Maintaining xdocs descriptors is an automatic responsibility for an agent working in an xdocs project, not something the user has to request. The intended workflow:
 
 1. On entering a project, read `XDOCS.md`, run `xdocs tree`, and run `xdocs scan` to understand the structure and coverage.
-2. On navigating to a module, read that module's xdocs file (frontmatter first, body only if needed) instead of reading every source file.
-3. On creating a new module or subdirectory, create that directory's xdocs file (for example `<name>.xdocs.md`) describing its purpose, its files (with their key functions/exports), and its `parent`/`children` links — as part of the same change, without being asked.
-4. On modifying a module (adding, renaming, moving, or removing files, or changing what it does), update its xdocs file and the affected parent/child links so the documentation matches reality.
-5. `[ai].mode` governs only how the agent writes: `prompt` announces the xdocs changes then writes them; `auto` writes immediately. It never makes documentation optional. A code change is not complete until the affected xdocs files are updated and `xdocs tree` is consistent.
+2. On navigating to a module, read that module's named `*.xdocs.md` descriptor frontmatter first. Use `documents` to decide which companion Markdown files to open, instead of reading every source file.
+3. On creating a new module or subdirectory, create that directory's named xdocs descriptor (for example `authentication.xdocs.md`) describing its purpose, searchable `keywords`, its files (with their key functions/exports), its companion `documents`, and its `parent`/`children` links -- as part of the same change, without being asked.
+4. On modifying a module (adding, renaming, moving, or removing files or sibling Markdown documents, or changing what it does), update its xdocs descriptor, companion document frontmatter, and the affected parent/child links so the documentation matches reality.
+5. `[ai].mode` governs only how the agent writes: `prompt` announces the xdocs changes then writes them; `auto` writes immediately. It never makes documentation optional. A code change is not complete until the affected xdocs descriptors are updated and `xdocs tree` is consistent.
 6. On request, use `xdocs generate`, `xdocs merge`, and `xdocs tree` to produce documentation artifacts.
 
 ## Prompts
@@ -420,8 +454,8 @@ The API uses the same configuration discovery and validation as the CLI.
 - `source/embedded-resources.ts`: prompt, skill, and package metadata text imports used only for native binary embedding.
 - `source/cli.ts`: argument parsing, command dispatch, config-gated automation, and process-facing error handling.
 - `source/config.ts`: TOML discovery, schema validation, defaulting, default config generation, and agent-settings normalization.
-- `source/discovery.ts`: filesystem scanning and xdocs file matching.
-- `source/metadata.ts`: YAML frontmatter extraction and metadata validation.
+- `source/discovery.ts`: filesystem scanning, xdocs descriptor matching, companion Markdown discovery, and descriptor/document validation.
+- `source/metadata.ts`: YAML frontmatter extraction, metadata validation, and nameless descriptor rejection.
 - `source/tree.ts`: tree assembly, integrity checks, and rendering (text, markdown).
 - `source/prompts.ts`: prompt loader (reads `prompts/*.md` from disk at runtime relative to `import.meta.url`).
 - `source/help.ts`: help text and version display.
@@ -507,7 +541,7 @@ Supported release asset matrix:
 
 Windows arm64 is intentionally not published until Bun's compilation support is reliable enough for this project. Unsupported platforms should use a documented manual path: install Bun and run from source, or download a compatible release asset manually.
 
-The package-manager install path downloads a native binary to `bin/xdocs.exe` during `postinstall`, and the `xdocs` bin entry points to that native binary. The native binary entrypoint embeds prompt templates, the `guiho-s-xdocs` skill, and package version metadata before importing the CLI, so installed binaries do not need adjacent prompt or skill files at runtime.
+The package-manager install path ships `scripts/xdocs-bin.ts` as the package `bin`. That launcher calls `scripts/install-package.ts` during first run if `vendor/xdocs` or `vendor/xdocs.exe` is missing. The install helper downloads the matching GitHub Release asset, or copies a bundled asset when present. The native binary entrypoint embeds prompt templates, the `guiho-s-xdocs` skill, and package version metadata before importing the CLI, so installed binaries do not need adjacent prompt or skill files at runtime.
 
 ## Documentation Requirement Before Publishing
 
@@ -543,7 +577,7 @@ Run `xdocs init` from the project root, or pass `--config <path>`.
 
 ### A directory shows as uncovered
 
-Add an xdocs file (`.docs.md` or `.xdocs.md`) to the directory, or adjust `[extensions].supported`. Confirm the directory is not in `[scan].exclude`.
+Add one named xdocs descriptor such as `authentication.xdocs.md` to the directory and list same-directory plain Markdown files in `documents`. Confirm the directory is not in `[scan].exclude`.
 
 ### Tree warnings or errors
 

package/README.md

@@ -2,13 +2,15 @@
 
 **Structured documentation system for codebases. Helps AI make sense of projects.**
 
-xdocs is a CLI and TypeScript library that places structured documentation files throughout your project so that AI agents (and humans) can navigate, understand, and work within a codebase without reading every file. Each xdocs file describes the directory it lives in -- its purpose, its files, and how it fits into the project hierarchy.
+**npm package:** [@guiho/xdocs](https://www.npmjs.com/package/@guiho/xdocs)
+
+xdocs is a CLI and TypeScript library that places named `*.xdocs.md` descriptors throughout your project so that AI agents (and humans) can navigate, understand, and work within a codebase without reading every file. Each descriptor describes the directory it lives in -- its purpose, searchable keywords, its files, its companion Markdown documents, and how it fits into the project hierarchy.
 
 ```text
-codebase -> xdocs files -> AI understands the project
+codebase -> named *.xdocs.md descriptors + companion *.md documents -> AI understands the project
 ```
 
-xdocs runs on **Bun** and **Node >= 20**. It ships as a compiled binary, a thin JS loader for `npx`/`bunx`, and a fully-typed TypeScript library.
+xdocs ships as compiled native binaries, a thin Bun launcher for package-manager and `bunx` execution, and a fully-typed TypeScript library.
 
 ---
 
@@ -28,7 +30,7 @@ irm https://raw.githubusercontent.com/CGuiho/xdocs/main/install.ps1 | iex
 
 Set `XDOCS_VERSION=0.2.3` (or the full tag `@guiho/xdocs@0.2.3`) before running an installer to pin a specific release instead of installing the latest.
 
-Package-manager install (convenient for JavaScript projects; downloads the matching native binary during `postinstall`, then runs the native binary):
+Package-manager install (convenient for JavaScript projects; downloads the matching native binary during `postinstall`, or on first run if the install hook did not run):
 
 ```bash
 npm install -D @guiho/xdocs
@@ -36,7 +38,7 @@ npm install -D @guiho/xdocs
 bun add -d @guiho/xdocs
 ```
 
-Native release assets are published for Linux x64/arm64, macOS x64/arm64, and Windows x64. Windows arm64 is not published yet. Package-manager installs require Node.js only during installation for the `postinstall` downloader; running `xdocs` afterwards executes the native binary.
+Native release assets are published for Linux x64/arm64, macOS x64/arm64, and Windows x64. Windows arm64 is not published yet. Direct installs run without Node.js or Bun at runtime. Package-manager and `bunx` execution use a shipped Bun launcher that ensures the matching native binary is installed, then delegates to it.
 
 ### Initializing
 
@@ -55,7 +57,7 @@ This creates:
 ### Typical Workflow
 
 ```bash
-# Scan the project for existing xdocs files
+# Scan the project for xdocs descriptors and companion Markdown documents
 xdocs scan
 
 # Generate documentation for a specific module
@@ -78,11 +80,11 @@ When AI works on a codebase, most of the structural knowledge lives in the head
 
 ### The Solution
 
-xdocs solves this by placing documentation files throughout the project. Each xdocs file describes the directory it lives in, acting as a self-contained map of that module. Instead of opening every file to understand a directory, the AI reads its xdocs file.
+xdocs solves this by placing named descriptors throughout the project. Each `*.xdocs.md` descriptor describes the directory it lives in, acting as a self-contained map of that module. Instead of opening every file to understand a directory, the AI reads descriptor frontmatter first and opens listed companion documents only when relevant.
 
 ### File Format
 
-xdocs files are Markdown with YAML frontmatter. A file is recognized as an xdocs file if it ends with one of the configured extensions (default: `.docs.md`, `.xdocs.md`).
+xdocs descriptors are Markdown files with YAML frontmatter and a required name before the `.xdocs.md` suffix, such as `authentication.xdocs.md`. A file named only `.xdocs.md` is invalid. Same-directory plain `*.md` files are companion documents and must be listed in `documents`.
 
 ```markdown
 ---
@@ -97,7 +99,13 @@ files:
   authenticate.ts: Validates credentials and returns a session token.
   register.ts: Creates a new user account with email verification.
   session.ts: Manages session creation, validation, and expiration.
+documents:
+  authentication-implementation.md: Detailed implementation notes and decisions.
 tags: []
+keywords:
+  - authentication
+  - sessions
+  - identity
 flags: []
 ---
 
@@ -106,6 +114,27 @@ flags: []
 The authentication module handles all identity verification flows...
 ```
 
+Ordinary same-directory companion `.md` files should also have YAML
+frontmatter. Use `owner` to point back to the owning descriptor `subject`, and
+include `keywords` for search/matching:
+
+```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: authentication
+---
+```
+
 #### Metadata Fields
 
 | Field         | Type                  | Required | Description                                                   |
@@ -115,13 +144,15 @@ The authentication module handles all identity verification flows...
 | `parent`      | `string \| null`      | Yes      | The parent subject in the hierarchy. `null` for the root.     |
 | `children`    | `string[]`            | Yes      | Child subjects (submodules) contained within this module.     |
 | `files`       | `map<string, string>` | Yes      | Files in this directory. Key = filename, value = description. |
+| `documents`   | `map<string, string>` | Yes      | Same-directory plain Markdown documents. Key = filename, value = description. |
 | `tags`        | `string[]`            | Yes      | Tags for categorization and search.                           |
+| `keywords`    | `string[]`            | Yes      | Search terms and concepts agents can use to match requests.   |
 | `flags`       | `string[]`            | Yes      | Flags for marking attributes or states.                       |
 | `status`      | `string`              | No       | Module status (e.g., `active`, `deprecated`, `experimental`). |
 
 ### The Tree
 
-xdocs files form a hierarchy through their `subject`, `parent`, and `children` fields. The tree represents containment -- not dependencies -- and is computed by scanning all xdocs files.
+xdocs descriptors form a hierarchy through their `subject`, `parent`, and `children` fields. The tree represents containment -- not dependencies -- and is computed by scanning all named `*.xdocs.md` descriptors.
 
 ```
 project (root)
@@ -150,7 +181,7 @@ Initializes xdocs in a project. Creates the root `XDOCS.md`, the `xdocs.config.t
 
 #### `xdocs scan`
 
-Scans the project for xdocs files. Reports which directories have coverage and which are missing documentation.
+Scans the project for named `*.xdocs.md` descriptors and sibling plain Markdown companion documents. Reports descriptor validity, directory coverage, and companion-document coverage.
 
 ```bash
 xdocs scan
@@ -174,15 +205,15 @@ xdocs generate
 Outputs a ready-made prompt for AI agents. Each prompt is a self-contained instruction for a specific xdocs task. Prompts are selected by the `--name` flag, not by subcommand.
 
 ```bash
-xdocs prompt --name=write      # How to write xdocs documentation
-xdocs prompt --name=update     # How to update existing xdocs files
+xdocs prompt --name=write      # How to write a named xdocs descriptor
+xdocs prompt --name=update     # How to update existing xdocs descriptors
 xdocs prompt --name=agents     # How to update AGENTS.md
 xdocs prompt --name=generate   # How to generate comprehensive docs
 ```
 
 #### `xdocs merge [path]`
 
-Merges xdocs files from a directory into a single consolidated document.
+Merges xdocs descriptors from a directory into a single consolidated document.
 
 ```bash
 xdocs merge ./src/domain
@@ -199,7 +230,7 @@ xdocs tree --format markdown --output tree.md
 
 #### `xdocs list [path]`
 
-Lists files in a scope with descriptions pulled from xdocs metadata.
+Lists implementation files and companion Markdown documents in a scope with descriptions pulled from xdocs metadata.
 
 ```bash
 xdocs list ./src/auth
@@ -238,9 +269,8 @@ xdocs looks for configuration at `./xdocs.config.toml`, `./config/xdocs.config.t
 schema = 1
 
 [extensions]
-# File extensions recognized as xdocs files.
-# Default: [".docs.md", ".xdocs.md"]
-supported = [".docs.md", ".xdocs.md"]
+# Descriptor suffix recognized by xdocs. Only ".xdocs.md" is supported.
+supported = [".xdocs.md"]
 
 [ai]
 # How the AI handles documentation updates.
@@ -259,7 +289,7 @@ exclude = ["node_modules", ".git", "dist", "build", "library", "bin", "bundle"]
 name = "my-project"
 
 [agents]
-# Keep the xdocs section in AGENTS.md fresh on normal commands. Default: true
+# Keep the xdocs section in AGENTS.md fresh on bare and normal commands. Default: true
 auto_agents_md = true
 # Install or refresh the standard skill globally from the bundled copy. Default: true
 auto_skill_install = true
@@ -286,6 +316,8 @@ xdocs agents instructions      # insert/refresh the AGENTS.md section
 
 `xdocs init` runs this automatically for the standard target (`local` scope). `local` scope installs under the project; `global` installs under your home directory. The default is always the standard target -- non-standard files are written only when you ask (`--tool`) or when they are already present. Installation removes legacy `guiho-as-xdocs` skill directories and replaces `guiho-s-xdocs` when the bundled version or content differs.
 
+A bare `xdocs` invocation and the normal data commands refresh the global skill before doing their usual work. Without `xdocs.config.toml`, xdocs uses the standard `agents` target; with config, `[agents].skill_tool` can choose the target and `[agents].auto_skill_install = false` can disable the refresh. If the legacy `guiho-as-xdocs` skill exists for that global target, xdocs removes it and writes the bundled `guiho-s-xdocs` skill.
+
 ---
 
 ## API Reference
@@ -307,16 +339,19 @@ const configOrDefaults = await loadConfigOrDefaults({ cwd: process.cwd(), format
 ### Discovery and Scanning
 
 ```ts
-import { scanProject, scanDirectory, isXDocsFile } from '@guiho/xdocs'
+import { scanProject, scanDirectory, isPlainMarkdownDocument, isXDocsDescriptorFile, isXDocsFile } from '@guiho/xdocs'
 
 // Scan the entire project
 const result = await scanProject(config)
 console.log(result.totalFiles)           // Total files found
 console.log(result.xdocsFiles)           // Array of XDocsFile objects
+console.log(result.markdownDocuments)    // Companion Markdown documents found
 console.log(result.uncoveredPaths)       // Directories without xdocs coverage
 
-// Check if a file is an xdocs file
-isXDocsFile('auth.xdocs.md', ['.docs.md', '.xdocs.md'])  // true
+// Check descriptor and companion document files
+isXDocsFile('auth.xdocs.md')                 // true
+isXDocsDescriptorFile('auth.xdocs.md')       // true
+isPlainMarkdownDocument('auth-notes.md')     // true
 ```
 
 ### Metadata Parsing
@@ -324,7 +359,7 @@ isXDocsFile('auth.xdocs.md', ['.docs.md', '.xdocs.md'])  // true
 ```ts
 import { parseXDocsFile, extractFrontmatter, validateMetadata } from '@guiho/xdocs'
 
-// Parse an xdocs file from disk
+// Parse an xdocs descriptor from disk
 const file = await parseXDocsFile('/path/to/auth.xdocs.md', process.cwd())
 console.log(file.metadata?.subject)       // "authentication"
 console.log(file.metadata?.description)   // "Handles user login..."

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/docs.xdocs.md

@@ -0,0 +1,22 @@
+---
+subject: xdocs-docs
+description: Durable project documentation for xdocs behavior, design notes, and implementation context.
+parent: xdocs-package
+children: []
+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. Each plain Markdown
+document in this directory is listed in `documents` so agents can find the note
+from descriptor metadata before opening the full document.

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiho/xdocs",
-  "version": "0.3.0-alpha.2",
+  "version": "0.4.0-alpha.0",
   "exports": "./source/guiho-xdocs.ts",
   "publish": {
     "include": [