@guiho/xdocs 0.3.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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.

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.
@@ -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`.
 
@@ -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]`
 
@@ -359,13 +392,13 @@ Bare `xdocs` invocations and the data commands (`scan`, `generate`, `merge`, `tr
 
 ## 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
@@ -421,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.
@@ -544,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

@@ -4,10 +4,10 @@
 
 **npm package:** [@guiho/xdocs](https://www.npmjs.com/package/@guiho/xdocs)
 
-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.
+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 ships as compiled native binaries, a thin Bun launcher for package-manager and `bunx` execution, and a fully-typed TypeScript library.
@@ -57,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
@@ -80,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
 ---
@@ -99,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: []
 ---
 
@@ -108,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                                                   |
@@ -117,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)
@@ -152,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
@@ -176,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
@@ -201,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
@@ -240,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.
@@ -311,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
@@ -328,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.1",
+  "version": "0.4.0-alpha.0",
   "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}\``);