@guiho/xdocs 0.2.3 → 0.3.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # GUIHO XDocs Changelog
 
+## 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.
+- Refresh installed skills from the bundled package copy, removing legacy `guiho-as-xdocs` skill directories and replacing stale `guiho-s-xdocs` installs when version or content differs.
+- Keep `[agents].auto_skill_install` defaulted to `true` and run global skill refresh during config-gated command automation.
+- Update the TypeScript API, tests, help text, README, architecture notes, AGENTS guidance, and canonical `DOCS.md` for the renamed skill behavior.
+
+## 0.3.0-alpha.1
+
+- Remove external parser dependencies (`smol-toml`, `yaml`) and use Bun-native `Bun.TOML.parse` and `Bun.YAML.parse` instead.
+- Change the package-manager `xdocs` bin to point at a native binary path and add a `postinstall` downloader that installs the matching GitHub Release binary into `bin/xdocs.exe`; Node.js is used only during install by Node-based package managers, not at `xdocs` runtime.
+- Update build configuration to include Bun types for the library build.
+- Document the native package-manager install path and Bun-native parser behavior.
+
+## 0.3.0-alpha.0
+
+- Add native-binary-first distribution support for xdocs, including a Bun-powered release binary matrix for Linux x64/arm64, macOS x64/arm64, and Windows x64.
+- Add direct installers (`install.sh` and `install.ps1`) so users can install the native `xdocs` binary without requiring Node.js or Bun at runtime.
+- Add a native binary entrypoint that embeds prompts, the `guiho-as-xdocs` skill, and package version metadata so compiled binaries work without adjacent package files.
+- Update CI and the publish workflow to build the release binary matrix and publish native binaries as GitHub Release assets while keeping npm publishing intact.
+- Document the native binary distribution model in `DOCS.md`, `README.md`, `ARCHITECTURE.md`, and `AGENTS.md`.
+- Add xdocs metadata files for the package root, source module, and devops module.
+
 ## 0.2.3
 
 - `xdocs agents instructions` and config-gated AGENTS.md automation now tolerate formatter-only blank lines and trailing whitespace inside the managed xdocs block, preserving the user's formatted block when the actual text is unchanged.

package/DOCS.md

@@ -11,13 +11,15 @@ XDocs is a documentation tool, not a versioning tool. It never bumps versions or
 ## Package Overview
 
 - Package name: `@guiho/xdocs`
-- Runtime: Node (>= 18) and Bun (ESM)
+- 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 type: ESM
 - Library entrypoint: `source/guiho-xdocs.ts`
 - CLI entrypoint: `source/guiho-xdocs-bin.ts`
 - TypeScript build output: `library/` (used by `main` and `types`)
-- Standalone binary output: `bin/xdocs` or `bin/xdocs.exe`
-- Dependencies: `smol-toml` (TOML config parsing), `yaml` (YAML frontmatter parsing)
+- 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.
 
@@ -81,7 +83,17 @@ Scanning walks the project tree and skips directories listed in `[scan].exclude`
 
 ## Installation
 
-Install XDocs as a development dependency:
+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
+```
+
+```powershell
+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:
 
 ```bash
 bun add -d @guiho/xdocs
@@ -93,7 +105,7 @@ Or with npm:
 npm install -D @guiho/xdocs
 ```
 
-Use the CLI through the package manager or through the installed `xdocs` binary.
+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.
 
 ## Quick Start
 
@@ -144,8 +156,8 @@ Initializes XDocs in a project. It:
 
 - Creates `xdocs.config.toml` with defaults (skips if it already exists).
 - Creates the root `XDOCS.md` (skips if it already exists).
-- Updates `AGENTS.md` with the xdocs section that points AI agents at the `guiho-as-xdocs` skill (creates `AGENTS.md` if absent; refreshes the section in place if present).
-- Installs the `guiho-as-xdocs` skill to the standard `.agents/skills` location.
+- Updates `AGENTS.md` with the xdocs section that points AI agents at the `guiho-s-xdocs` skill (creates `AGENTS.md` if absent; refreshes the section in place if present).
+- Installs or refreshes the `guiho-s-xdocs` skill to the standard `.agents/skills` location, removing legacy `guiho-as-xdocs` installs when present.
 
 ```bash
 xdocs init
@@ -233,7 +245,7 @@ Both `--name=value` and `--name value` forms are supported.
 
 ### `xdocs agents`
 
-Installs the `guiho-as-xdocs` agent skill and maintains the `AGENTS.md` instruction section.
+Installs the `guiho-s-xdocs` agent skill and maintains the `AGENTS.md` instruction section.
 
 ```bash
 xdocs agents install local            # install under the project (.agents/skills)
@@ -315,22 +327,24 @@ Optional. When present, must be `1`.
 Agent settings control skill installation and the automation that runs on 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 the standard skill globally when it is missing. Default: `true`.
+- `auto_skill_install`: Install or refresh the configured skill globally from the bundled package copy. Default: `true`.
 - `skill_tool`: Default target for auto-install. Supported values are `agents` (standard) and `claude`. Default: `agents`.
 
 ## Agent Skills and Automation
 
-XDocs ships the `guiho-as-xdocs` skill inside the package at `skills/guiho-as-xdocs/SKILL.md`. The skill is a large, on-demand instruction document; a small section in `AGENTS.md` tells an agent to load it.
+XDocs ships the `guiho-s-xdocs` skill inside the package at `skills/guiho-s-xdocs/SKILL.md`. The skill is a large, on-demand instruction document with a `version` field in its frontmatter; a small section in `AGENTS.md` tells an agent to load it.
 
 Installation is standard-first:
 
 | Target                    | Skill location                              | When installed                                                  |
 | ------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
-| `agents` (standard)       | `.agents/skills/guiho-as-xdocs/SKILL.md`    | Always (default). Read by OpenCode, Codex, Jules, and any AGENTS.md tool. |
-| `claude` (non-standard)   | `.claude/skills/guiho-as-xdocs/SKILL.md`    | Only when requested via `--tool`, or detected (a `.claude/` directory or `CLAUDE.md`). |
+| `agents` (standard)       | `.agents/skills/guiho-s-xdocs/SKILL.md`    | Always (default). Read by OpenCode, Codex, Jules, and any AGENTS.md tool. |
+| `claude` (non-standard)   | `.claude/skills/guiho-s-xdocs/SKILL.md`    | Only when requested via `--tool`, or detected (a `.claude/` directory or `CLAUDE.md`). |
 
 `local` scope installs under the project root; `global` scope installs under the user home directory (`~/.agents/skills/...`).
 
+Skill installation treats the bundled package skill as the source of truth. It removes legacy `guiho-as-xdocs` skill directories for the selected target, compares the installed `guiho-s-xdocs` version/content with the bundled copy, and replaces the installed skill whenever the version or content differs.
+
 The rule is: default to the standard target. Only write non-standard files (`.claude`, `CLAUDE.md`, etc.) when the user asks for them or when those files already exist.
 
 ### Automation
@@ -338,7 +352,7 @@ The rule is: default to the standard target. Only write non-standard files (`.cl
 When an `xdocs.config.toml` is present, the data commands (`scan`, `generate`, `merge`, `tree`, `list`) run config-gated 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 and the global skill is missing, XDocs installs it for the configured `skill_tool` and prints a one-line notice to stderr.
+- 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.
 
 Automation does nothing outside an xdocs project (no config discovered). `init` and `agents` do not run this automation; they manage agent files explicitly.
 
@@ -355,7 +369,7 @@ Maintaining xdocs files is an automatic responsibility for an agent working in a
 
 ## Prompts
 
-Prompt templates live in `prompts/*.md` and are embedded at build time via Bun text imports. Each prompt file has its own YAML frontmatter with `name` and `description`. The CLI exposes them through `xdocs prompt --name=<name>`. Available names: `write`, `update`, `agents`, `generate`.
+Prompt templates live in `prompts/*.md` and are read from disk at runtime relative to `import.meta.url`. Each prompt file has its own YAML frontmatter with `name` and `description`. The CLI exposes them through `xdocs prompt --name=<name>`. Available names: `write`, `update`, `agents`, `generate`.
 
 ## TypeScript API
 
@@ -382,11 +396,12 @@ import { extractFrontmatter, parseXDocsFile, validateMetadata } from '@guiho/xdo
 Agent skill and AGENTS.md automation:
 
 ```ts
-import { installSkill, ensureAgentsInstructions, runAgentAutomation } from '@guiho/xdocs'
+import { installSkill, ensureAgentsInstructions, runAgentAutomation, xdocsSkillVersion } from '@guiho/xdocs'
 
 await installSkill('agents', 'local', { cwd: process.cwd() })
 await ensureAgentsInstructions(process.cwd(), true)
 await runAgentAutomation({ cwd: process.cwd(), format: 'text', verbose: false })
+console.log(xdocsSkillVersion)
 ```
 
 Configuration:
@@ -401,20 +416,22 @@ The API uses the same configuration discovery and validation as the CLI.
 
 - `source/guiho-xdocs.ts`: public library export surface.
 - `source/guiho-xdocs-bin.ts`: CLI binary entrypoint.
+- `source/guiho-xdocs-native-bin.ts`: Bun-compiled native binary entrypoint that registers embedded resources before importing 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/tree.ts`: tree assembly, integrity checks, and rendering (text, markdown).
-- `source/prompts.ts`: prompt loader (imports `prompts/*.md` as text via Bun).
+- `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.
 - `source/flags.ts`: argument/flag parsing utilities.
 - `source/errors.ts`: `XDocsError` with stable exit codes and the `invariant` helper.
 - `source/types.ts`: public and internal TypeScript types.
-- `source/agents.ts`: agent skill installation (standard/claude, local/global), AGENTS.md section management, detection, and config-gated automation. Reads `skills/guiho-as-xdocs/SKILL.md` from disk at runtime relative to `import.meta.url`.
+- `source/agents.ts`: agent skill installation (standard/claude, local/global), legacy skill-name removal, version/content refresh, AGENTS.md section management, detection, and config-gated automation. Reads `skills/guiho-s-xdocs/SKILL.md` from disk at runtime relative to `import.meta.url`.
 - `source/commands/*.ts`: one file per CLI command (`init`, `scan`, `generate`, `prompt`, `merge`, `tree`, `list`, `agents`).
 - `prompts/*.md`: prompt templates embedded at build time.
-- `skills/guiho-as-xdocs/SKILL.md`: bundled AI-agent skill installed by `xdocs agents` commands.
+- `skills/guiho-s-xdocs/SKILL.md`: bundled versioned AI-agent skill installed by `xdocs agents` commands.
 
 ## Development Workflow
 
@@ -468,13 +485,29 @@ Build the library:
 bun run build
 ```
 
-Compile the standalone binary:
+Compile the host standalone binary:
 
 ```bash
 bun run binary
 ```
 
-The library reads the prompt templates and the `guiho-as-xdocs` skill from the package's `prompts/` and `skills/` directories at runtime (via `readFileSync` relative to `import.meta.url`), so the published package works under both Node and Bun.
+Compile the supported release binary matrix:
+
+```bash
+bun run binaries
+```
+
+Supported release asset matrix:
+
+- Linux x64: `xdocs-linux-x64`
+- Linux arm64: `xdocs-linux-arm64`
+- macOS x64: `xdocs-macos-x64`
+- 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 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.
 
 ## Documentation Requirement Before Publishing
 
@@ -494,10 +527,11 @@ Before publishing a new version:
 4. Run `bun run typecheck`.
 5. Run `bun test`.
 6. Run `bun run build`.
-7. Run `bun run binary` when the CLI binary is part of release validation.
+7. Run `bun run binary` and `bun run binaries` when the CLI binary is part of release validation.
 8. Build the Mirror release plan: `bun x @guiho/mirror version plan <target>`.
 9. Commit release-documentation updates before applying the version bump.
 10. Apply the bump with GUIHO Mirror: `bun x @guiho/mirror version apply <target> --yes`.
+11. Confirm the tag workflow uploads native binary assets to the GitHub Release and publishes the npm package.
 
 Versioning itself is handled by GUIHO Mirror via `mirror.config.toml`; XDocs never edits version fields directly.
 
@@ -519,9 +553,9 @@ Run `xdocs tree --verbose`. Resolve duplicate `subject` values, orphaned modules
 
 The standard target is `.agents/skills` (or `~/.agents/skills` for `--global`). The Claude target (`.claude/skills`) is only used with `--tool claude`/`all` or when a `.claude/` directory or `CLAUDE.md` is detected. Use `XDOCS_AGENT_HOME` to redirect the global home in tests.
 
-### A normal command modified AGENTS.md or installed a global skill unexpectedly
+### A normal command modified AGENTS.md or installed/refreshed a global skill unexpectedly
 
-That is the config-gated automation. Set `[agents].auto_agents_md = false` to stop AGENTS.md edits, and `[agents].auto_skill_install = false` to stop global skill installation.
+That is the config-gated automation. Set `[agents].auto_agents_md = false` to stop AGENTS.md edits, and `[agents].auto_skill_install = false` to stop global skill installation and refresh.
 
 ### Prompt not found
 

package/README.md

@@ -16,12 +16,28 @@ xdocs runs on **Bun** and **Node >= 20**. It ships as a compiled binary, a thin
 
 ### Installation
 
+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
+```
+
+```powershell
+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):
+
 ```bash
 npm install -D @guiho/xdocs
 # or
 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.
+
 ### Initializing
 
 Set up xdocs in your project:
@@ -31,10 +47,10 @@ xdocs init
 ```
 
 This creates:
-- `XDOCS.md` -- the root documentation file for the project
+- `XDOCS.md` -- the single frontmatter-less repository index listing packages/applications
 - `xdocs.config.toml` -- configuration with sensible defaults
 - Updates `AGENTS.md` with instructions for AI agents
-- Installs the `guiho-as-xdocs` agent skill (standard `.agents/skills`)
+- Installs the `guiho-s-xdocs` agent skill (standard `.agents/skills`)
 
 ### Typical Workflow
 
@@ -130,7 +146,7 @@ The CLI validates tree integrity: no orphan subjects, no missing parents, no cyc
 
 #### `xdocs init`
 
-Initializes xdocs in a project. Creates the root `XDOCS.md`, the `xdocs.config.toml` configuration, updates `AGENTS.md`, and installs the `guiho-as-xdocs` skill to the standard `.agents/skills` location.
+Initializes xdocs in a project. Creates the root `XDOCS.md`, the `xdocs.config.toml` configuration, updates `AGENTS.md`, and installs or refreshes the `guiho-s-xdocs` skill to the standard `.agents/skills` location.
 
 #### `xdocs scan`
 
@@ -191,7 +207,7 @@ xdocs list ./src/auth
 
 #### `xdocs agents`
 
-Installs the `guiho-as-xdocs` agent skill and maintains the `AGENTS.md` section.
+Installs the `guiho-s-xdocs` agent skill and maintains the `AGENTS.md` section.
 
 ```bash
 xdocs agents install local     # install the skill under the project (.agents/skills)
@@ -245,7 +261,7 @@ name = "my-project"
 [agents]
 # Keep the xdocs section in AGENTS.md fresh on normal commands. Default: true
 auto_agents_md = true
-# Install the standard skill globally when missing. Default: true
+# Install or refresh the standard skill globally from the bundled copy. Default: true
 auto_skill_install = true
 # Default target for skill auto-install: "agents" (standard) or "claude". Default: "agents"
 skill_tool = "agents"
@@ -253,14 +269,14 @@ skill_tool = "agents"
 
 ### Agent Skills
 
-xdocs ships the `guiho-as-xdocs` agent skill that teaches AI tools how to work with xdocs -- when to create, update, or regenerate documentation, how to use the CLI, and how to respect the configured AI behavior mode. The skill is large and loaded on demand; a small section in `AGENTS.md` points the agent at it.
+xdocs ships the `guiho-s-xdocs` agent skill that teaches AI tools how to work with xdocs -- when to create, update, or regenerate documentation, how to use the CLI, and how to respect the configured AI behavior mode. The skill is versioned in its frontmatter, large, and loaded on demand; a small section in `AGENTS.md` points the agent at it.
 
 Installation is **standard-first**:
 
 | Target                    | Location                                            | When installed                                                  |
 | ------------------------- | --------------------------------------------------- | --------------------------------------------------------------- |
-| **agents** (standard)     | `.agents/skills/guiho-as-xdocs/SKILL.md`            | Always (default). Read by OpenCode, Codex, Jules, and any AGENTS.md tool. |
-| **claude** (non-standard) | `.claude/skills/guiho-as-xdocs/SKILL.md`            | When `--tool claude` is given, or a `.claude/` dir or `CLAUDE.md` is detected. |
+| **agents** (standard)     | `.agents/skills/guiho-s-xdocs/SKILL.md`            | Always (default). Read by OpenCode, Codex, Jules, and any AGENTS.md tool. |
+| **claude** (non-standard) | `.claude/skills/guiho-s-xdocs/SKILL.md`            | When `--tool claude` is given, or a `.claude/` dir or `CLAUDE.md` is detected. |
 
 ```bash
 xdocs agents install local     # standard target, under the project
@@ -268,7 +284,7 @@ xdocs agents install global    # standard target, under ~/.agents/skills
 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.
+`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.
 
 ---
 

package/jsr.json

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

package/library/agents.d.ts

@@ -5,17 +5,21 @@
  *
  * Two distinct things live here:
  *  1. The small AGENTS.md section that tells any AI agent that xdocs structured
- *     documentation exists and that it should load the guiho-as-xdocs skill.
- *  2. The large guiho-as-xdocs skill file, installed (local or global) into the
+ *     documentation exists and that it should load the guiho-s-xdocs skill.
+ *  2. The large guiho-s-xdocs skill file, installed (local or global) into the
  *     skills directory of one or more AI tools.
  */
 import type { XDocsAgentAutomationResult, XDocsAgentSettings, XDocsAgentTool, XDocsAgentsInstructionsResult, XDocsCliOptions, XDocsSkillInstallResult, XDocsSkillScope } from './types.js';
 /** Canonical name of the xdocs agent skill. */
-export declare const xdocsSkillName = "guiho-as-xdocs";
-/** Raw contents of the bundled guiho-as-xdocs/SKILL.md, read from disk at
+export declare const xdocsSkillName = "guiho-s-xdocs";
+/** Previous skill names that should be removed during install/refresh. */
+export declare const legacyXdocsSkillNames: readonly string[];
+/** Raw contents of the bundled guiho-s-xdocs/SKILL.md, read from disk at
  * runtime (relative to this module) so the compiled library works under both
  * Node and Bun. The file ships with the package in `skills/`. */
 export declare const xdocsSkillContent: string;
+/** Version declared by the bundled skill frontmatter. */
+export declare const xdocsSkillVersion: string | undefined;
 /** All AI tools the skill can be installed for. `agents` is the standard. */
 export declare const xdocsAgentTools: readonly XDocsAgentTool[];
 /** The standard, always-default skill target (AGENTS.md + .agents/skills). */
@@ -34,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-as-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 `.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 -->";
 type SkillPathOptions = {
     cwd?: string;
     homeDirectory?: string;
@@ -68,9 +72,11 @@ export declare const resolveAgentSettings: (options: XDocsCliOptions) => Promise
 /**
  * Config-gated automation run by normal commands. Does nothing outside an xdocs
  * project (no config discovered). When enabled, it keeps the AGENTS.md section
- * fresh (only if AGENTS.md already exists) and installs the global skill for the
- * configured tool when it is missing.
+ * fresh (only if AGENTS.md already exists) and refreshes the global skill for
+ * the configured tool from the bundled package copy.
  */
 export declare const runAgentAutomation: (options: AgentAutomationOptions, notify?: (message: string) => void) => Promise<XDocsAgentAutomationResult>;
+/** Read a skill version from SKILL.md YAML frontmatter. */
+export declare function readSkillVersion(content: string): string | undefined;
 export {};
 //# sourceMappingURL=agents.d.ts.map

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,mBAAmB,CAAA;AAE9C;;iEAEiE;AACjE,eAAO,MAAM,iBAAiB,EAAE,MAM5B,CAAA;AAEJ,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,ohCAoBV,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,MAG/G,CAAA;AAED,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,CAajC,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;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,sBAAsB,EAC/B,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,0BAA0B,CAkBpC,CAAA"}
+{"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;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,sBAAsB,EAC/B,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,0BAA0B,CAmBpC,CAAA;AAED,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpE"}

package/library/agents.js

@@ -5,29 +5,36 @@
  *
  * Two distinct things live here:
  *  1. The small AGENTS.md section that tells any AI agent that xdocs structured
- *     documentation exists and that it should load the guiho-as-xdocs skill.
- *  2. The large guiho-as-xdocs skill file, installed (local or global) into the
+ *     documentation exists and that it should load the guiho-s-xdocs skill.
+ *  2. The large guiho-s-xdocs skill file, installed (local or global) into the
  *     skills directory of one or more AI tools.
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import { discoverConfig, normalizeAgentSettings } from './config.js';
 import { XDocsError } from './errors.js';
 /** Canonical name of the xdocs agent skill. */
-export const xdocsSkillName = 'guiho-as-xdocs';
-/** Raw contents of the bundled guiho-as-xdocs/SKILL.md, read from disk at
+export const xdocsSkillName = 'guiho-s-xdocs';
+/** Previous skill names that should be removed during install/refresh. */
+export const legacyXdocsSkillNames = ['guiho-as-xdocs'];
+/** Raw contents of the bundled guiho-s-xdocs/SKILL.md, read from disk at
  * runtime (relative to this module) so the compiled library works under both
  * Node and Bun. The file ships with the package in `skills/`. */
 export const xdocsSkillContent = (() => {
+    const embedded = globalThis.__XDOCS_EMBEDDED_RESOURCES__?.skill;
+    if (embedded)
+        return embedded;
     try {
-        return readFileSync(new URL('../skills/guiho-as-xdocs/SKILL.md', import.meta.url), 'utf8');
+        return readFileSync(new URL('../skills/guiho-s-xdocs/SKILL.md', import.meta.url), 'utf8');
     }
     catch {
         return '';
     }
 })();
+/** Version declared by the bundled skill frontmatter. */
+export const xdocsSkillVersion = readSkillVersion(xdocsSkillContent);
 /** All AI tools the skill can be installed for. `agents` is the standard. */
 export const xdocsAgentTools = ['agents', 'claude'];
 /** The standard, always-default skill target (AGENTS.md + .agents/skills). */
@@ -62,7 +69,7 @@ export const resolveInstallTools = (cwd, toolFlag) => toolFlag ? parseAgentTools
 /**
  * Skill directory for each tool, relative to the scope root (project root for
  * `local`, home directory for `global`). The skill is written to
- * `<root>/<dir>/guiho-as-xdocs/SKILL.md`.
+ * `<root>/<dir>/guiho-s-xdocs/SKILL.md`.
  *
  * `agents` is the cross-tool standard (OpenCode, Codex, Jules, and any AGENTS.md
  * tool read it). `claude` is the non-standard Claude Code location.
@@ -96,9 +103,10 @@ Use the xdocs CLI for operations: \`xdocs scan\`, \`xdocs tree\`, \`xdocs genera
 \`xdocs list\`, \`xdocs merge\`.
 ${AGENTS_END_MARKER}`;
 /** Resolve the on-disk path of the skill file for a tool and scope. */
-export const resolveSkillPath = (tool, scope, options = {}) => {
+export const resolveSkillPath = (tool, scope, options = {}) => resolveNamedSkillPath(tool, scope, xdocsSkillName, options);
+const resolveNamedSkillPath = (tool, scope, skillName, options = {}) => {
     const root = scope === 'local' ? resolve(options.cwd ?? process.cwd()) : resolveAgentHome(options.homeDirectory);
-    return resolve(root, skillDirectories[tool], xdocsSkillName, 'SKILL.md');
+    return resolve(root, skillDirectories[tool], skillName, 'SKILL.md');
 };
 /** Whether the skill is already installed for a tool and scope. */
 export const isSkillInstalled = (tool, scope, options = {}) => existsSync(resolveSkillPath(tool, scope, options));
@@ -106,14 +114,28 @@ export const isSkillInstalled = (tool, scope, options = {}) => existsSync(resolv
 export const installSkill = async (tool, scope, options = {}) => {
     const path = resolveSkillPath(tool, scope, options);
     const exists = existsSync(path);
-    if (exists && options.overwrite === false)
-        return { tool, scope, path, installed: false, updated: false };
     const current = exists ? await readFile(path, 'utf8') : undefined;
-    if (current === xdocsSkillContent)
-        return { tool, scope, path, installed: false, updated: false };
+    const previousVersion = current ? readSkillVersion(current) : undefined;
+    const bundledVersion = xdocsSkillVersion;
+    if (exists && options.overwrite === false) {
+        return { tool, scope, path, installed: false, updated: false, removedLegacyPaths: [], previousVersion, bundledVersion };
+    }
+    const removedLegacyPaths = [];
+    for (const legacyName of legacyXdocsSkillNames) {
+        const legacyPath = resolveNamedSkillPath(tool, scope, legacyName, options);
+        if (!existsSync(legacyPath))
+            continue;
+        await rm(dirname(legacyPath), { recursive: true, force: true });
+        removedLegacyPaths.push(legacyPath);
+    }
+    if (current === xdocsSkillContent) {
+        return { tool, scope, path, installed: false, updated: false, removedLegacyPaths, previousVersion, bundledVersion };
+    }
+    if (exists)
+        await rm(dirname(path), { recursive: true, force: true });
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, xdocsSkillContent, 'utf8');
-    return { tool, scope, path, installed: !exists, updated: exists };
+    return { tool, scope, path, installed: !exists, updated: exists, removedLegacyPaths, previousVersion, bundledVersion };
 };
 /** Install the skill for several tools at once. */
 export const installSkills = async (tools, scope, options = {}) => {
@@ -188,8 +210,8 @@ export const resolveAgentSettings = async (options) => {
 /**
  * Config-gated automation run by normal commands. Does nothing outside an xdocs
  * project (no config discovered). When enabled, it keeps the AGENTS.md section
- * fresh (only if AGENTS.md already exists) and installs the global skill for the
- * configured tool when it is missing.
+ * fresh (only if AGENTS.md already exists) and refreshes the global skill for
+ * the configured tool from the bundled package copy.
  */
 export const runAgentAutomation = async (options, notify = () => { }) => {
     const cwd = resolve(options.cwd);
@@ -200,13 +222,39 @@ export const runAgentAutomation = async (options, notify = () => { }) => {
     const result = { settings };
     if (settings.autoAgentsMd)
         result.agentsMd = await ensureAgentsInstructions(cwd, false);
-    if (settings.autoSkillInstall && !isSkillInstalled(settings.skillTool, 'global', { cwd, homeDirectory: options.homeDirectory })) {
-        const path = resolveSkillPath(settings.skillTool, 'global', { cwd, homeDirectory: options.homeDirectory });
-        notify(`notice: ${xdocsSkillName} skill not found globally; xdocs is installing it at ${path}`);
-        result.globalSkill = await installSkill(settings.skillTool, 'global', { cwd, homeDirectory: options.homeDirectory, overwrite: false });
+    if (settings.autoSkillInstall) {
+        const globalSkill = await installSkill(settings.skillTool, 'global', { cwd, homeDirectory: options.homeDirectory });
+        const changed = globalSkill.installed || globalSkill.updated || globalSkill.removedLegacyPaths.length > 0;
+        if (changed)
+            notify(`notice: ${xdocsSkillName} skill refreshed globally at ${globalSkill.path}`);
+        result.globalSkill = globalSkill;
     }
     return result;
 };
+/** Read a skill version from SKILL.md YAML frontmatter. */
+export function readSkillVersion(content) {
+    return readSkillFrontmatterValue(content, 'version');
+}
+function readSkillFrontmatterValue(content, key) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return undefined;
+    const frontmatter = match[1];
+    if (frontmatter === undefined)
+        return undefined;
+    for (const line of frontmatter.split(/\r?\n/)) {
+        const separator = line.indexOf(':');
+        if (separator === -1)
+            continue;
+        if (line.slice(0, separator).trim() !== key)
+            continue;
+        const value = line.slice(separator + 1).trim();
+        if (!value)
+            return undefined;
+        return value.replace(/^['"]|['"]$/g, '');
+    }
+    return undefined;
+}
 const resolveAgentHome = (homeDirectory) => {
     const value = homeDirectory ?? process.env['XDOCS_AGENT_HOME'] ?? homedir();
     return isAbsolute(value) ? value : resolve(process.cwd(), value);

package/library/commands/agents.js

@@ -22,7 +22,7 @@ export const runAgents = async (options, parsed) => {
         throw new XDocsError(`Missing agents subcommand.\n\n${USAGE}`);
     throw new XDocsError(`Unknown agents subcommand: "${sub}"\n\n${USAGE}`);
 };
-/** Install the guiho-as-xdocs skill for one or more tools. */
+/** Install the guiho-s-xdocs skill for one or more tools. */
 const runInstall = async (options, parsed) => {
     const scope = parseScope(parsed.positionals[1]);
     const tools = resolveInstallTools(options.cwd, stringFlag(parsed.flags, 'tool'));
@@ -60,5 +60,8 @@ const formatInstall = (result) => [
     `path: ${result.path}`,
     `installed: ${result.installed}`,
     `updated: ${result.updated}`,
+    `bundled_version: ${result.bundledVersion ?? ''}`,
+    `previous_version: ${result.previousVersion ?? ''}`,
+    `removed_legacy: ${result.removedLegacyPaths.join(', ')}`,
     '',
 ].join('\n');

package/library/commands/init.js

@@ -46,7 +46,7 @@ export const runInit = async (options, parsed) => {
         await writeFile(xdocsPath, createRootXDocsContent(basename(cwd)), 'utf8');
         process.stdout.write(`created: XDOCS.md\n`);
     }
-    // 3. Update AGENTS.md (announce xdocs + point AI at the guiho-as-xdocs skill)
+    // 3. Update AGENTS.md (announce xdocs + point AI at the guiho-s-xdocs skill)
     const agentsExisted = findAgentsFile(cwd) !== undefined;
     const agentsResult = await ensureAgentsInstructions(cwd, true);
     if (!agentsExisted) {
@@ -58,7 +58,7 @@ export const runInit = async (options, parsed) => {
     else {
         process.stdout.write(`exists: AGENTS.md (xdocs section already present)\n`);
     }
-    // 4. Install the guiho-as-xdocs agent skill (standard by default; non-standard
+    // 4. Install the guiho-s-xdocs agent skill (standard by default; non-standard
     //    tools only when explicitly requested via --tool or detected in the project)
     const scope = booleanFlag(parsed.flags, 'global') ? 'global' : 'local';
     const tools = resolveInstallTools(cwd, stringFlag(parsed.flags, 'tool'));
@@ -68,7 +68,7 @@ export const runInit = async (options, parsed) => {
         if (result.installed) {
             process.stdout.write(`installed: ${xdocsSkillName} skill (${tool}, ${scope}) -> ${where}\n`);
         }
-        else if (result.updated) {
+        else if (result.updated || result.removedLegacyPaths.length > 0) {
             process.stdout.write(`updated: ${xdocsSkillName} skill (${tool}, ${scope})\n`);
         }
         else {

package/library/config.d.ts.map

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

package/library/config.js

@@ -4,7 +4,6 @@
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { basename, isAbsolute, resolve } from 'node:path';
-import { parse as parseToml } from 'smol-toml';
 import { XDocsError } from './errors.js';
 const DEFAULT_EXTENSIONS = ['.docs.md', '.xdocs.md'];
 const DEFAULT_EXCLUDE = ['node_modules', '.git', 'dist', 'build', 'library', 'bin', 'bundle'];
@@ -148,7 +147,7 @@ const readConfigFile = async (path) => {
     const content = await readFile(path, 'utf8');
     let parsed;
     try {
-        parsed = parseToml(content);
+        parsed = Bun.TOML.parse(content);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/library/embedded-resources.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ *
+ * Embedded resources used only by Bun-compiled native binaries. The Node-safe
+ * library build reads these files from disk instead.
+ */
+export type XDocsEmbeddedResources = {
+    prompts: Record<string, string>;
+    skill: string;
+    version: string;
+};
+declare global {
+    var __XDOCS_EMBEDDED_RESOURCES__: XDocsEmbeddedResources | undefined;
+}
+/** Register prompt/skill/package resources for a native compiled binary. */
+export declare const registerEmbeddedResources: () => void;
+//# sourceMappingURL=embedded-resources.d.ts.map

package/library/embedded-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded-resources.d.ts","sourceRoot":"","sources":["../source/embedded-resources.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,4BAA4B,EAAE,sBAAsB,GAAG,SAAS,CAAA;CACrE;AAED,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,QAAO,IAW5C,CAAA"}

package/library/embedded-resources.js

@@ -0,0 +1,30 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ *
+ * Embedded resources used only by Bun-compiled native binaries. The Node-safe
+ * library build reads these files from disk instead.
+ */
+// @ts-expect-error -- Bun text import for native binary embedding.
+import writePrompt from '../prompts/write.md' with { type: 'text' };
+// @ts-expect-error -- Bun text import for native binary embedding.
+import updatePrompt from '../prompts/update.md' with { type: 'text' };
+// @ts-expect-error -- Bun text import for native binary embedding.
+import agentsPrompt from '../prompts/agents.md' with { type: 'text' };
+// @ts-expect-error -- Bun text import for native binary embedding.
+import generatePrompt from '../prompts/generate.md' with { type: 'text' };
+// @ts-expect-error -- Bun text import for native binary embedding.
+import xdocsSkill from '../skills/guiho-s-xdocs/SKILL.md' with { type: 'text' };
+import packageJson from '../package.json' with { type: 'json' };
+/** Register prompt/skill/package resources for a native compiled binary. */
+export const registerEmbeddedResources = () => {
+    globalThis.__XDOCS_EMBEDDED_RESOURCES__ = {
+        prompts: {
+            write: writePrompt,
+            update: updatePrompt,
+            agents: agentsPrompt,
+            generate: generatePrompt,
+        },
+        skill: xdocsSkill,
+        version: typeof packageJson.version === 'string' ? packageJson.version : '0.0.0',
+    };
+};

package/library/guiho-xdocs-native-bin.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export {};
+//# sourceMappingURL=guiho-xdocs-native-bin.d.ts.map

package/library/guiho-xdocs-native-bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guiho-xdocs-native-bin.d.ts","sourceRoot":"","sources":["../source/guiho-xdocs-native-bin.ts"],"names":[],"mappings":";AACA;;GAEG"}

package/library/guiho-xdocs-native-bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { registerEmbeddedResources } from './embedded-resources.js';
+registerEmbeddedResources();
+const { runCliWithErrorHandling } = await import('./cli.js');
+await runCliWithErrorHandling();

package/library/guiho-xdocs.d.ts

@@ -10,6 +10,6 @@ export { extractFrontmatter, parseXDocsFile, validateMetadata } from './metadata
 export { buildTree, renderTree, renderTreeMarkdown, validateTree } from './tree.js';
 export { readPackageVersion, showCommandHelp, showHelp, showVersion } from './help.js';
 export { getPrompt, getPromptNames, prompts } from './prompts.js';
-export { detectAgentTools, ensureAgentsInstructions, findAgentsFile, installSkill, installSkills, isSkillInstalled, parseAgentTools, resolveAgentSettings, resolveInstallTools, resolveSkillPath, runAgentAutomation, standardAgentTool, xdocsAgentsSection, xdocsAgentTools, xdocsSkillContent, xdocsSkillName, } from './agents.js';
+export { detectAgentTools, ensureAgentsInstructions, findAgentsFile, installSkill, installSkills, isSkillInstalled, legacyXdocsSkillNames, parseAgentTools, readSkillVersion, resolveAgentSettings, resolveInstallTools, resolveSkillPath, runAgentAutomation, standardAgentTool, xdocsAgentsSection, xdocsAgentTools, xdocsSkillContent, xdocsSkillName, xdocsSkillVersion, } from './agents.js';
 export { runCli, runCliWithErrorHandling } from './cli.js';
 //# sourceMappingURL=guiho-xdocs.d.ts.map

package/library/guiho-xdocs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guiho-xdocs.d.ts","sourceRoot":"","sources":["../source/guiho-xdocs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAGnD,YAAY,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,WAAW,EACX,eAAe,EACf,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,EACX,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,eAAe,EACf,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGzE,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,UAAU,EACV,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,WAAW,EACX,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAG5F,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAGpF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGnF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGtF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGjE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,cAAc,GACf,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"guiho-xdocs.d.ts","sourceRoot":"","sources":["../source/guiho-xdocs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAGnD,YAAY,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,WAAW,EACX,eAAe,EACf,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,EACX,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,eAAe,EACf,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGzE,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,UAAU,EACV,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,WAAW,EACX,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAG5F,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAGpF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGnF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGtF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGjE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA"}

package/library/guiho-xdocs.js

@@ -18,6 +18,6 @@ export { readPackageVersion, showCommandHelp, showHelp, showVersion } from './he
 // Prompts
 export { getPrompt, getPromptNames, prompts } from './prompts.js';
 // Agents
-export { detectAgentTools, ensureAgentsInstructions, findAgentsFile, installSkill, installSkills, isSkillInstalled, parseAgentTools, resolveAgentSettings, resolveInstallTools, resolveSkillPath, runAgentAutomation, standardAgentTool, xdocsAgentsSection, xdocsAgentTools, xdocsSkillContent, xdocsSkillName, } from './agents.js';
+export { detectAgentTools, ensureAgentsInstructions, findAgentsFile, installSkill, installSkills, isSkillInstalled, legacyXdocsSkillNames, parseAgentTools, readSkillVersion, resolveAgentSettings, resolveInstallTools, resolveSkillPath, runAgentAutomation, standardAgentTool, xdocsAgentsSection, xdocsAgentTools, xdocsSkillContent, xdocsSkillName, xdocsSkillVersion, } from './agents.js';
 // CLI
 export { runCli, runCliWithErrorHandling } from './cli.js';

package/library/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../source/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,QAAO,MAQrC,CAAA;AAED,qCAAqC;AACrC,eAAO,MAAM,WAAW,QAAO,MAAyC,CAAA;AAExE,+BAA+B;AAC/B,eAAO,MAAM,QAAQ,QAAO,MAgCpB,CAAA;AAER,wCAAwC;AACxC,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAIjD,CAAA"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../source/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,QAAO,MAWrC,CAAA;AAED,qCAAqC;AACrC,eAAO,MAAM,WAAW,QAAO,MAAyC,CAAA;AAExE,+BAA+B;AAC/B,eAAO,MAAM,QAAQ,QAAO,MAgCpB,CAAA;AAER,wCAAwC;AACxC,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAIjD,CAAA"}

package/library/help.js

@@ -4,6 +4,9 @@
 import { readFileSync } from 'node:fs';
 /** Read the package version from package.json. */
 export const readPackageVersion = () => {
+    const embedded = globalThis.__XDOCS_EMBEDDED_RESOURCES__?.version;
+    if (embedded)
+        return embedded;
     try {
         const raw = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
         const pkg = JSON.parse(raw);
@@ -29,7 +32,7 @@ Commands:
   merge [path]          Merge xdocs files from a directory into one file
   tree                  Display the project hierarchy tree
   list [path]           List files with descriptions
-  agents                Install the guiho-as-xdocs skill and AGENTS.md instructions
+  agents                Install the guiho-s-xdocs skill and AGENTS.md instructions
 
 Global Flags:
   -h, --help            Show help for a command
@@ -66,7 +69,7 @@ Creates:
   - XDOCS.md              Root documentation file
   - xdocs.config.toml     Configuration with defaults
   - Updates AGENTS.md     Adds the xdocs section pointing AI at the skill
-  - Installs the skill    guiho-as-xdocs into .agents/skills (standard, local)
+  - Installs the skill    guiho-s-xdocs into .agents/skills (standard, local)
 
 By default the skill is installed for the standard target (AGENTS.md +
 .agents/skills). The non-standard claude target (.claude/skills) is added only
@@ -172,7 +175,7 @@ Flags:
   --verbose               Show detailed output
 `.trim(),
     agents: `
-xdocs agents - Install the guiho-as-xdocs skill and AGENTS.md instructions
+xdocs agents - Install the guiho-s-xdocs skill and AGENTS.md instructions
 
 Usage:
   xdocs agents install <local|global> [--tool <tool>]
@@ -184,8 +187,8 @@ Subcommands:
   instructions            Insert or refresh the xdocs section in AGENTS.md
 
 Skill locations:
-  agents (standard)       <root>/.agents/skills/guiho-as-xdocs/SKILL.md
-  claude (non-standard)   <root>/.claude/skills/guiho-as-xdocs/SKILL.md
+  agents (standard)       <root>/.agents/skills/guiho-s-xdocs/SKILL.md
+  claude (non-standard)   <root>/.claude/skills/guiho-s-xdocs/SKILL.md
 
 <root> is the project for local scope, or the user home directory for global.
 Without --tool, the standard agents target is installed, plus claude when a

package/library/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../source/metadata.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1D,8DAA8D;AAC9D,eAAO,MAAM,cAAc,GAAU,UAAU,MAAM,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,SAAS,CAqCrF,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAiB9F,CAAA;AAED,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,GAAI,QAAQ,OAAO,KAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CA4D9J,CAAA"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../source/metadata.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1D,8DAA8D;AAC9D,eAAO,MAAM,cAAc,GAAU,UAAU,MAAM,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,SAAS,CAqCrF,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAiB9F,CAAA;AAED,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,GAAI,QAAQ,OAAO,KAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CA4D9J,CAAA"}

package/library/metadata.js

@@ -3,7 +3,6 @@
  */
 import { readFile } from 'node:fs/promises';
 import { dirname, relative } from 'node:path';
-import { parse as parseYaml } from 'yaml';
 /** Parse an xdocs file from disk into an XDocsFile object. */
 export const parseXDocsFile = async (filePath, cwd) => {
     const content = await readFile(filePath, 'utf8');
@@ -13,7 +12,7 @@ export const parseXDocsFile = async (filePath, cwd) => {
     if (frontmatter) {
         let parsed;
         try {
-            parsed = parseYaml(frontmatter);
+            parsed = Bun.YAML.parse(frontmatter);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/library/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../source/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAmC7C,4CAA4C;AAC5C,eAAO,MAAM,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAWjD,CAAA;AAEJ,gDAAgD;AAChD,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,WAAW,GAAG,SACpC,CAAA;AAEnB,4BAA4B;AAC5B,eAAO,MAAM,cAAc,QAAO,MAAM,EACnB,CAAA"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../source/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAsC7C,4CAA4C;AAC5C,eAAO,MAAM,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAWjD,CAAA;AAEJ,gDAAgD;AAChD,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,WAAW,GAAG,SACpC,CAAA;AAEnB,4BAA4B;AAC5B,eAAO,MAAM,cAAc,QAAO,MAAM,EACnB,CAAA"}

package/library/prompts.js

@@ -12,6 +12,9 @@ import { extractFrontmatter } from './metadata.js';
 const PROMPT_NAMES = ['write', 'update', 'agents', 'generate'];
 /** Read a prompt file's raw contents, or undefined when it cannot be read. */
 const readPromptFile = (name) => {
+    const embedded = globalThis.__XDOCS_EMBEDDED_RESOURCES__?.prompts[name];
+    if (embedded)
+        return embedded;
     try {
         return readFileSync(new URL(`../prompts/${name}.md`, import.meta.url), 'utf8');
     }

package/library/types.d.ts

@@ -7,7 +7,7 @@ export type XDocsFormat = 'text' | 'json' | 'markdown';
 export type XDocsAiMode = 'prompt' | 'auto';
 /** Command names recognized by the CLI. */
 export type XDocsCommand = 'init' | 'scan' | 'generate' | 'prompt' | 'merge' | 'tree' | 'list' | 'agents';
-/** AI tools the guiho-as-xdocs skill can be installed for.
+/** AI tools the guiho-s-xdocs skill can be installed for.
  *
  * `agents` is the standard target (AGENTS.md + .agents/skills) and the default.
  * `claude` is a non-standard target (.claude/skills) used only when explicitly
@@ -125,13 +125,16 @@ export type XDocsPrompt = {
     description: string;
     body: string;
 };
-/** Result of installing the guiho-as-xdocs skill for one tool/scope. */
+/** Result of installing the guiho-s-xdocs skill for one tool/scope. */
 export type XDocsSkillInstallResult = {
     tool: XDocsAgentTool;
     scope: XDocsSkillScope;
     path: string;
     installed: boolean;
     updated: boolean;
+    removedLegacyPaths: string[];
+    previousVersion?: string;
+    bundledVersion?: string;
 };
 /** Result of ensuring the xdocs section exists in AGENTS.md. */
 export type XDocsAgentsInstructionsResult = {

package/library/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/xdocs",
   "description": "Structured documentation system for codebases. Helps AI make sense of projects.",
-  "version": "0.2.3",
+  "version": "0.3.0-alpha.2",
   "type": "module",
   "main": "./library/guiho-xdocs.js",
   "types": "./library/guiho-xdocs.d.ts",
@@ -12,12 +12,13 @@
     }
   },
   "bin": {
-    "xdocs": "./library/guiho-xdocs-bin.js"
+    "xdocs": "./bin/xdocs.exe"
   },
   "files": [
     "README.md",
     "library/",
     "prompts/",
+    "scripts/",
     "skills/",
     "docs/",
     "jsr.json",
@@ -45,8 +46,10 @@
   "scripts": {
     "dev": "bun run --watch source/guiho-xdocs-bin.ts",
     "build": "rm -rf library && tsc -p tsconfig.build.json",
-    "binary": "bun build source/guiho-xdocs-bin.ts --compile --outfile bin/xdocs",
+    "binary": "bun build source/guiho-xdocs-native-bin.ts --compile --outfile bin/xdocs",
+    "binaries": "bun run devops/build-binaries.ts",
     "bundle": "rm -rf bundle && bun build source/guiho-xdocs-bin.ts --outdir bundle --target node --sourcemap=linked",
+    "postinstall": "node ./scripts/install-native.cjs",
     "typecheck": "tsc -p . --noEmit",
     "clean": "rm -rf .temp",
     "clean-build": "rm -rf build library bundle bin",
@@ -67,10 +70,7 @@
   "bugs": {
     "url": "https://github.com/CGuiho/xdocs/issues"
   },
-  "dependencies": {
-    "smol-toml": "^1.6.1",
-    "yaml": "^2.9.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@guiho/mirror": "^3.1.2",
     "@types/bun": "1.3.14",

package/scripts/install-native.cjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/*
+ * Install the platform-native xdocs binary for package-manager installs.
+ * Node is used only during installation. The installed `xdocs` command points
+ * directly at the downloaded native binary and does not require Node at runtime.
+ */
+
+const { createWriteStream, existsSync, mkdirSync, chmodSync } = require('node:fs')
+const { readFile } = require('node:fs/promises')
+const { get } = require('node:https')
+const { join } = require('node:path')
+
+const root = join(__dirname, '..')
+const packagePath = join(root, 'package.json')
+const targetPath = join(root, 'bin', 'xdocs.exe')
+
+main().catch((error) => {
+  console.error(`xdocs: failed to install native binary: ${error.message}`)
+  process.exit(1)
+})
+
+async function main() {
+  if (process.env.XDOCS_SKIP_NATIVE_INSTALL === '1') {
+    console.warn('xdocs: skipping native binary installation because XDOCS_SKIP_NATIVE_INSTALL=1')
+    return
+  }
+
+  if (existsSync(join(root, 'source'))) {
+    console.warn('xdocs: skipping native binary installation in a source checkout')
+    return
+  }
+
+  const packageJson = JSON.parse(await readFile(packagePath, 'utf8'))
+  const version = packageJson.version
+  if (typeof version !== 'string' || version.length === 0) throw new Error('package.json version is missing')
+
+  const asset = assetName()
+  const tag = `@guiho/xdocs@${version}`
+  const url = `https://github.com/CGuiho/xdocs/releases/download/${encodeURIComponent(tag)}/${asset}`
+
+  mkdirSync(join(root, 'bin'), { recursive: true })
+  await download(url, targetPath)
+  if (process.platform !== 'win32') chmodSync(targetPath, 0o755)
+
+  console.log(`xdocs: installed native binary ${asset}`)
+}
+
+function assetName() {
+  if (process.platform === 'linux') {
+    if (process.arch === 'x64') return 'xdocs-linux-x64'
+    if (process.arch === 'arm64') return 'xdocs-linux-arm64'
+  }
+
+  if (process.platform === 'darwin') {
+    if (process.arch === 'x64') return 'xdocs-macos-x64'
+    if (process.arch === 'arm64') return 'xdocs-macos-arm64'
+  }
+
+  if (process.platform === 'win32') {
+    if (process.arch === 'x64') return 'xdocs-windows-x64.exe'
+  }
+
+  throw new Error(`unsupported platform: ${process.platform}/${process.arch}`)
+}
+
+function download(url, destination) {
+  return new Promise((resolve, reject) => {
+    const request = get(url, (response) => {
+      if (response.statusCode === 302 || response.statusCode === 301) {
+        const location = response.headers.location
+        if (!location) {
+          reject(new Error(`redirect from ${url} did not include a Location header`))
+          return
+        }
+
+        download(location, destination).then(resolve, reject)
+        return
+      }
+
+      if (response.statusCode !== 200) {
+        reject(new Error(`download failed (${response.statusCode}) from ${url}`))
+        return
+      }
+
+      const file = createWriteStream(destination)
+      response.pipe(file)
+      file.on('finish', () => {
+        file.close(resolve)
+      })
+      file.on('error', reject)
+    })
+
+    request.on('error', reject)
+    request.end()
+  })
+}
+
+// Keep npm pack from treating this package as broken before postinstall runs.
+if (!existsSync(targetPath)) {
+  mkdirSync(join(root, 'bin'), { recursive: true })
+}

package/scripts/scripts.xdocs.md

@@ -0,0 +1,18 @@
+---
+subject: xdocs-scripts
+description: Package-manager installation scripts for installing the native xdocs binary.
+parent: xdocs-package
+children: []
+files:
+  install-native.cjs: npm postinstall helper that downloads the matching GitHub Release native binary into bin/xdocs.exe.
+tags:
+  - install
+  - native-binary
+  - package-manager
+flags: []
+status: stable
+---
+
+The `scripts/` directory contains package-manager lifecycle helpers. These
+scripts are used during install only; the resulting `xdocs` command executes the
+downloaded native binary directly and does not require Node.js at runtime.

package/skills/{guiho-as-xdocs → guiho-s-xdocs}/SKILL.md

@@ -1,5 +1,6 @@
 ---
-name: guiho-as-xdocs
+name: guiho-s-xdocs
+version: 0.3.0-alpha.2
 description: Use this skill whenever the user works with xdocs (`@guiho/xdocs`) structured documentation, AND proactively whenever you create a new module or subdirectory or add/change/remove files in a directory of an xdocs project, so you create or update that directory's `.xdocs.md` as part of the change. This includes creating, updating, or regenerating `.docs.md` / `.xdocs.md` files, the root `XDOCS.md`, the project tree, scanning documentation coverage, merging docs, or maintaining xdocs metadata and AGENTS.md guidance, even when the user only says "document this module", "update the docs", or "what does this folder do" without naming xdocs.
 ---
 
@@ -178,11 +179,11 @@ name = "my-project"
 
 [agents]
 auto_agents_md = true      # keep the xdocs section in AGENTS.md up to date on normal commands
-auto_skill_install = true  # install the guiho-as-xdocs skill globally when missing
+auto_skill_install = true  # install or refresh the guiho-s-xdocs skill globally
 skill_tool = "agents"      # default tool for auto-install: agents (standard) or claude
 ```
 
-Agent automation options default to true. Set `auto_agents_md = false` to stop xdocs from touching AGENTS.md, and `auto_skill_install = false` to stop xdocs from installing `guiho-as-xdocs` globally when it is missing.
+Agent automation options default to true. Set `auto_agents_md = false` to stop xdocs from touching AGENTS.md, and `auto_skill_install = false` to stop xdocs from installing or refreshing `guiho-s-xdocs` globally.
 
 ## CLI Reference
 
@@ -194,8 +195,8 @@ xdocs list <path>              # list files in a scope with descriptions
 xdocs generate [path]          # draft documentation for a directory or the whole project
 xdocs merge [path]             # merge a directory's xdocs files into one document
 xdocs prompt --name=<name>     # print a ready-made AI prompt (write|update|agents|generate)
-xdocs agents install local     # install guiho-as-xdocs into this project (.agents/skills/...)
-xdocs agents install global    # install guiho-as-xdocs into the user home skills directory
+xdocs agents install local     # install guiho-s-xdocs into this project (.agents/skills/...)
+xdocs agents install global    # install guiho-s-xdocs into the user home skills directory
 xdocs agents instructions      # insert/refresh the xdocs section in AGENTS.md
 ```
 
@@ -203,7 +204,7 @@ Global flags: `--help`, `--version`, `--cwd <path>`, `--config <path>`, `--forma
 
 ## Agent Skill Installation
 
-xdocs ships this `guiho-as-xdocs` skill. The **standard** target is `AGENTS.md`
+xdocs ships this `guiho-s-xdocs` skill. The **standard** target is `AGENTS.md`
 plus `.agents/skills`, which OpenCode, Codex, Jules, and any AGENTS.md-aware tool
 read. A **non-standard** Claude Code target exists and is used only when it is
 explicitly requested (`--tool claude`) or detected (a `.claude` directory or
@@ -211,8 +212,8 @@ explicitly requested (`--tool claude`) or detected (a `.claude` directory or
 
 | Target                  | Skill location (local)                      |
 | ----------------------- | ------------------------------------------- |
-| **agents** (standard)   | `.agents/skills/guiho-as-xdocs/SKILL.md`    |
-| **claude** (non-standard) | `.claude/skills/guiho-as-xdocs/SKILL.md`  |
+| **agents** (standard)   | `.agents/skills/guiho-s-xdocs/SKILL.md`    |
+| **claude** (non-standard) | `.claude/skills/guiho-s-xdocs/SKILL.md`  |
 
 `local` scope installs under the current project; `global` scope installs under
 the user home directory (`~/.agents/skills/...`). The small section in `AGENTS.md`

package/skills/skills.xdocs.md

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