@guiho/xdocs 0.3.1 → 0.4.9

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # GUIHO XDocs Changelog
 
+## 0.4.9
+
+- Fix GitHub Actions artifact names for scoped package tags by using run IDs, allowing the native binary publish workflow to upload artifacts and continue to GitHub Release asset publication.
+
+## 0.4.8
+
+- Harden the direct Linux/macOS Bash installer and Windows PowerShell installer for native xdocs binaries, including baseline-first x64 fallback, explicit default/modern variants, downloaded binary validation, PATH setup, and shadowing warnings.
+- Verify the 12-asset native binary matrix during `bun run binaries` for Linux, macOS, and Windows arm64/x64 baseline/default/modern outputs.
+- Upload native binaries as CI workflow artifacts and publish/verify all 12 GitHub Release assets before npm publishing on version-tag releases.
+- Document native binary installation, PATH fallback commands, and the full release asset matrix in `README.md` and `DOCS.md`.
+
+## 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`.
 
@@ -86,11 +119,29 @@ Scanning walks the project tree and skips directories listed in `[scan].exclude`
 Direct native binary install (no Node.js or Bun required after installation):
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.sh | bash
 ```
 
 ```powershell
-irm https://raw.githubusercontent.com/CGuiho/xdocs/main/install.ps1 | iex
+irm https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.ps1 | iex
+```
+
+The Linux/macOS installer is a Bash script in `devops/install.sh`; the Windows
+installer is the PowerShell script in `devops/install.ps1`. Both download from
+GitHub Releases, install into `~/.local/bin` by default, and add that directory
+then fall back to the default and `modern` variants. Users can force a specific
+architecture or variant with `--arch` / `--variant` on Bash or `-Arch` /
+`-Variant` on PowerShell.
+
+Manual PATH fallback commands:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+```powershell
+$env:Path = "$HOME\.local\bin;$env:Path"
+[Environment]::SetEnvironmentVariable('Path', "$HOME\.local\bin;" + [Environment]::GetEnvironmentVariable('Path', 'User'), 'User')
 ```
 
 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:
@@ -169,7 +220,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 +231,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 +243,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 +254,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 +266,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 +282,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 +336,7 @@ Full configuration example:
 schema = 1
 
 [extensions]
-supported = [".docs.md", ".xdocs.md"]
+supported = [".xdocs.md"]
 
 [ai]
 mode = "prompt"
@@ -308,7 +359,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 +410,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 +472,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.
@@ -436,7 +487,7 @@ The API uses the same configuration discovery and validation as the CLI.
 
 ## Development Workflow
 
-Run package commands from `xdocs/`.
+Run package commands from the repository root.
 
 ```bash
 bun install
@@ -465,6 +516,7 @@ Current tests cover:
 - Tree construction, rendering, and integrity validation.
 - Config discovery, validation, and defaulting.
 - Agent settings normalization, skill path resolution, skill installation (local/global), tool detection, and AGENTS.md section insertion.
+- Package launcher execution from a source checkout without a native vendor binary.
 
 Run all tests:
 
@@ -500,15 +552,34 @@ bun run binaries
 
 Supported release asset matrix:
 
-- Linux x64: `xdocs-linux-x64`
+- Linux x64: `xdocs-linux-x64-baseline`, `xdocs-linux-x64`, `xdocs-linux-x64-modern`
 - Linux arm64: `xdocs-linux-arm64`
-- macOS x64: `xdocs-macos-x64`
+- macOS x64: `xdocs-macos-x64-baseline`, `xdocs-macos-x64`, `xdocs-macos-x64-modern`
 - macOS arm64: `xdocs-macos-arm64`
-- Windows x64: `xdocs-windows-x64.exe`
-
-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 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.
+- Windows x64: `xdocs-windows-x64-baseline.exe`, `xdocs-windows-x64.exe`, `xdocs-windows-x64-modern.exe`
+- Windows arm64: `xdocs-windows-arm64.exe`
+
+`bun run binaries` verifies that all 12 expected native assets are present and
+non-empty after compilation. CI builds the matrix and uploads `bin/xdocs-*` as a
+GitHub Actions artifact. The tag publish workflow has `contents: write`, rebuilds
+the same matrix, uploads it as a workflow artifact, publishes `bin/xdocs-*` to
+the matching GitHub Release before npm publishing, and verifies that the release
+contains exactly 12 `xdocs-*` assets.
+
+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 ships `scripts/xdocs-bin.ts` as the package
+`bin`. That launcher delegates to `vendor/xdocs` or `vendor/xdocs.exe` when the
+native binary exists. In source checkouts, it falls back to
+`source/guiho-xdocs-bin.ts` so local package execution tests the checked-out
+source without downloading a release artifact. In published package layouts, it
+calls `scripts/install-package.ts` during first run if the vendor binary 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
 
@@ -544,7 +615,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,15 +2,13 @@
 
 **Structured documentation system for codebases. Helps AI make sense of projects.**
 
-**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 tool 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.
+xdocs ships as a single native binary — no Node.js, Bun, or runtime required.
 
 ---
 
@@ -18,27 +16,74 @@ xdocs ships as compiled native binaries, a thin Bun launcher for package-manager
 
 ### Installation
 
-Direct native binary install (no Node.js or Bun required after installation):
+Download and run the installer:
 
+**Linux / macOS:**
 ```bash
-curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.sh | bash
 ```
 
+**Windows (PowerShell):**
 ```powershell
-irm https://raw.githubusercontent.com/CGuiho/xdocs/main/install.ps1 | iex
+irm https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.ps1 | iex
+```
+
+The installers download native binaries from GitHub Releases, install `xdocs` into `~/.local/bin` by default, and add that directory to your user PATH when possible. x64 installs prefer the `baseline` variant first for maximum compatibility, then fall back to the default and `modern` variants.
+
+**Flags and options:**
+
+```bash
+# Pin a specific version
+curl .../install.sh | bash -s -- --version 0.4.7
+
+# Force architecture and variant
+curl .../install.sh | bash -s -- --arch arm64
+curl .../install.sh | bash -s -- --arch x64 --variant modern
+curl .../install.sh | bash -s -- --arch x64 --variant default
+
+# Custom install directory
+curl .../install.sh | bash -s -- --install-dir /usr/local/bin
 ```
 
-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.
+PowerShell examples:
 
-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):
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.ps1))) -Version 0.4.7
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.ps1))) -Arch x64 -Variant baseline
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.ps1))) -InstallDir "$HOME\.local\bin"
+```
 
+Or download the script first and run with flags directly:
 ```bash
-npm install -D @guiho/xdocs
-# or
-bun add -d @guiho/xdocs
+curl -O https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.sh
+chmod +x install.sh
+./install.sh --version latest --arch x64 --variant baseline
 ```
 
-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.
+Native binaries are built and uploaded for all supported OS/architecture/variant combinations:
+
+| OS | ARM64 | x64 baseline | x64 default | x64 modern |
+| --- | --- | --- | --- | --- |
+| Linux | `xdocs-linux-arm64` | `xdocs-linux-x64-baseline` | `xdocs-linux-x64` | `xdocs-linux-x64-modern` |
+| macOS | `xdocs-macos-arm64` | `xdocs-macos-x64-baseline` | `xdocs-macos-x64` | `xdocs-macos-x64-modern` |
+| Windows | `xdocs-windows-arm64.exe` | `xdocs-windows-x64-baseline.exe` | `xdocs-windows-x64.exe` | `xdocs-windows-x64-modern.exe` |
+
+CI builds the same 12 native binaries and uploads them as a GitHub Actions artifact. Version-tag releases upload `bin/xdocs-*` to the matching GitHub Release and verify that all 12 assets are present.
+
+If your current shell does not see the updated PATH immediately, open a new terminal or run one of these commands:
+
+```bash
+# bash/zsh
+export PATH="$HOME/.local/bin:$PATH"
+
+# fish
+fish_add_path "$HOME/.local/bin"
+```
+
+```powershell
+$env:Path = "$HOME\.local\bin;$env:Path"
+[Environment]::SetEnvironmentVariable('Path', "$HOME\.local\bin;" + [Environment]::GetEnvironmentVariable('Path', 'User'), 'User')
+```
 
 ### Initializing
 
@@ -57,7 +102,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 +125,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 +144,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 +159,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 +189,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 +226,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 +250,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 +275,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 +314,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 +384,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 +404,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..."
@@ -373,10 +449,9 @@ console.log(prompt?.body)
 
 ## Development
 
-Development requires Bun. Run from the `xdocs/` directory:
+Development requires Bun. Run from the repository root:
 
 ```bash
-cd xdocs
 bun install
 bun run typecheck
 bun test
@@ -388,4 +463,4 @@ bun run binary
 
 ## License
 
-MIT -- see [LICENSE.md](xdocs/LICENSE.md).
+MIT -- see [LICENSE.md](LICENSE.md).