@guiho/xdocs 0.3.0-alpha.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # GUIHO XDocs Changelog
 
+## 0.3.1
+
+- Fix bare `xdocs` invocations so they install or refresh the global `guiho-s-xdocs` skill before printing help, even without `xdocs.config.toml`, and remove legacy `guiho-as-xdocs` installs for that target.
+- Change the package-manager `xdocs` bin to a shipped Bun launcher (`scripts/xdocs-bin.ts`) that installs the native binary on first run when needed, matching GUIHO Mirror's `bun x` behavior.
+
+## 0.3.0
+
+- Stabilize the 0.3.0 release line, including native binary distribution, direct installers, package-manager native binary installation, and Bun-native TOML/YAML parsing.
+- Ship the renamed `guiho-s-xdocs` agent skill with versioned frontmatter, automatic refresh from the bundled package copy, and legacy `guiho-as-xdocs` cleanup.
+- Refresh README guidance and regression coverage for the stable release.
+
+## 0.3.0-alpha.2
+
+- Rename the bundled xdocs agent skill from `guiho-as-xdocs` to `guiho-s-xdocs` and add a frontmatter `version` field.
+- 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.

package/DOCS.md

@@ -13,7 +13,7 @@ XDocs is a documentation tool, not a versioning tool. It never bumps versions or
 - Package name: `@guiho/xdocs`
 - Source/runtime during development: Bun and TypeScript (ESM)
 - Primary release runtime: compiled native Bun binary assets
-- Package-manager install path: Node.js is used only for `postinstall`; the installed `xdocs` command executes the native binary
+- Package-manager install path: the shipped Bun launcher runs `postinstall` or first-run native binary installation, then executes the native binary
 - Package type: ESM
 - Library entrypoint: `source/guiho-xdocs.ts`
 - CLI entrypoint: `source/guiho-xdocs-bin.ts`
@@ -93,7 +93,7 @@ curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/install.sh | sh
 irm https://raw.githubusercontent.com/CGuiho/xdocs/main/install.ps1 | iex
 ```
 
-Install XDocs as a development dependency through a JavaScript package manager. This uses Node.js during `postinstall` to download the matching native binary, then the installed `xdocs` command executes the native binary:
+Install XDocs as a development dependency through a JavaScript package manager. Package-manager execution uses the shipped Bun launcher, which downloads the matching native binary during `postinstall` or on first run if the install hook did not run, then executes the native binary:
 
 ```bash
 bun add -d @guiho/xdocs
@@ -105,7 +105,7 @@ Or with npm:
 npm install -D @guiho/xdocs
 ```
 
-Use the direct installer when you do not want a JavaScript package manager involved. Use the package-manager install when you want project-local dependency management; after installation, `xdocs` still runs as a native binary.
+Use the direct installer when you do not want a JavaScript package manager or Bun involved at runtime. Use the package-manager install when you want project-local dependency management or `bunx` execution; the shipped Bun launcher ensures the native binary exists and delegates to it.
 
 ## Quick Start
 
@@ -156,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
@@ -245,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)
@@ -324,35 +324,38 @@ Optional. When present, must be `1`.
 
 ### `[agents]`
 
-Agent settings control skill installation and the automation that runs on data commands.
+Agent settings control skill installation and the automation that runs on bare and data commands.
 
 - `auto_agents_md`: Keep the `AGENTS.md` xdocs section fresh on normal commands when `AGENTS.md` already exists. Default: `true`.
-- `auto_skill_install`: Install 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
 
-When an `xdocs.config.toml` is present, the data commands (`scan`, `generate`, `merge`, `tree`, `list`) run config-gated agent automation before executing:
+Bare `xdocs` invocations and the data commands (`scan`, `generate`, `merge`, `tree`, `list`) run agent automation before executing:
 
-- If `auto_agents_md` is true and `AGENTS.md` exists, the xdocs section is kept fresh.
-- If `auto_skill_install` is true and the global skill is missing, XDocs installs it for the configured `skill_tool` and prints a one-line notice to stderr.
+- XDocs always bootstraps the global skill with default settings when no config is present, using the standard `agents` target.
+- When `xdocs.config.toml` is present and `auto_agents_md` is true, the xdocs section is kept fresh if `AGENTS.md` exists.
+- When config is present and `auto_skill_install` is true, XDocs ensures the configured global skill is current from the bundled package copy, removing legacy skill names and printing a one-line notice to stderr when it installs or refreshes anything.
 
-Automation does nothing outside an xdocs project (no config discovered). `init` and `agents` do not run this automation; they manage agent files explicitly.
+`--help` and `--version` stay read-only. `init` and `agents` do not run this automation; they manage agent files explicitly.
 
 ## AI Usage Workflow
 
@@ -394,11 +397,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:
@@ -425,10 +429,10 @@ The API uses the same configuration discovery and validation as the CLI.
 - `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
 
@@ -504,7 +508,7 @@ Supported release asset matrix:
 
 Windows arm64 is intentionally not published until Bun's compilation support is reliable enough for this project. Unsupported platforms should use a documented manual path: install Bun and run from source, or download a compatible release asset manually.
 
-The package-manager install path downloads a native binary to `bin/xdocs.exe` during `postinstall`, and the `xdocs` bin entry points to that native binary. The native binary entrypoint embeds prompt templates, the `guiho-as-xdocs` skill, and package version metadata before importing the CLI, so installed binaries do not need adjacent prompt or skill files at runtime.
+The package-manager install path ships `scripts/xdocs-bin.ts` as the package `bin`. That launcher calls `scripts/install-package.ts` during first run if `vendor/xdocs` or `vendor/xdocs.exe` is missing. The install helper downloads the matching GitHub Release asset, or copies a bundled asset when present. The native binary entrypoint embeds prompt templates, the `guiho-s-xdocs` skill, and package version metadata before importing the CLI, so installed binaries do not need adjacent prompt or skill files at runtime.
 
 ## Documentation Requirement Before Publishing
 
@@ -550,9 +554,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

@@ -2,13 +2,15 @@
 
 **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.
 
 ```text
 codebase -> xdocs files -> AI understands the project
 ```
 
-xdocs runs on **Bun** and **Node >= 20**. It ships as a compiled binary, a thin JS loader for `npx`/`bunx`, and a fully-typed TypeScript library.
+xdocs ships as compiled native binaries, a thin Bun launcher for package-manager and `bunx` execution, and a fully-typed TypeScript library.
 
 ---
 
@@ -28,7 +30,7 @@ irm https://raw.githubusercontent.com/CGuiho/xdocs/main/install.ps1 | iex
 
 Set `XDOCS_VERSION=0.2.3` (or the full tag `@guiho/xdocs@0.2.3`) before running an installer to pin a specific release instead of installing the latest.
 
-Package-manager install (convenient for JavaScript projects; downloads the matching native binary during `postinstall`, then runs the native binary):
+Package-manager install (convenient for JavaScript projects; downloads the matching native binary during `postinstall`, or on first run if the install hook did not run):
 
 ```bash
 npm install -D @guiho/xdocs
@@ -36,7 +38,7 @@ npm install -D @guiho/xdocs
 bun add -d @guiho/xdocs
 ```
 
-Native release assets are published for Linux x64/arm64, macOS x64/arm64, and Windows x64. Windows arm64 is not published yet. Package-manager installs require Node.js only during installation for the `postinstall` downloader; running `xdocs` afterwards executes the native binary.
+Native release assets are published for Linux x64/arm64, macOS x64/arm64, and Windows x64. Windows arm64 is not published yet. Direct installs run without Node.js or Bun at runtime. Package-manager and `bunx` execution use a shipped Bun launcher that ensures the matching native binary is installed, then delegates to it.
 
 ### Initializing
 
@@ -50,7 +52,7 @@ This creates:
 - `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
 
@@ -146,7 +148,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`
 
@@ -207,7 +209,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)
@@ -259,9 +261,9 @@ exclude = ["node_modules", ".git", "dist", "build", "library", "bin", "bundle"]
 name = "my-project"
 
 [agents]
-# Keep the xdocs section in AGENTS.md fresh on normal commands. Default: true
+# Keep the xdocs section in AGENTS.md fresh on bare and normal commands. Default: true
 auto_agents_md = true
-# Install 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"
@@ -269,14 +271,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
@@ -284,7 +286,9 @@ 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.
+
+A bare `xdocs` invocation and the normal data commands refresh the global skill before doing their usual work. Without `xdocs.config.toml`, xdocs uses the standard `agents` target; with config, `[agents].skill_tool` can choose the target and `[agents].auto_skill_install = false` can disable the refresh. If the legacy `guiho-as-xdocs` skill exists for that global target, xdocs removes it and writes the bundled `guiho-s-xdocs` skill.
 
 ---
 

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiho/xdocs",
-  "version": "0.3.0-alpha.1",
+  "version": "0.3.1",
   "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;
@@ -66,11 +70,12 @@ export declare const findAgentsFile: (cwd: string) => string | undefined;
 /** Resolve agent settings from the discovered xdocs config (defaults when absent). */
 export declare const resolveAgentSettings: (options: XDocsCliOptions) => Promise<XDocsAgentSettings>;
 /**
- * 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.
+ * Agent automation run by bare and data commands. It always bootstraps the
+ * configured global skill from the bundled package copy; when config exists,
+ * it also keeps the AGENTS.md section fresh if enabled and AGENTS.md exists.
  */
 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,MAS5B,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;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,sBAAsB,EAC/B,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,0BAA0B,CAgBpC,CAAA;AAED,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpE"}

package/library/agents.js

@@ -5,19 +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 { 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 = (() => {
@@ -25,12 +27,14 @@ export const xdocsSkillContent = (() => {
     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). */
@@ -65,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.
@@ -99,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));
@@ -109,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 = {}) => {
@@ -189,27 +208,50 @@ export const resolveAgentSettings = async (options) => {
     return normalizeAgentSettings(discovered.raw?.agents);
 };
 /**
- * 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.
+ * Agent automation run by bare and data commands. It always bootstraps the
+ * configured global skill from the bundled package copy; when config exists,
+ * it also keeps the AGENTS.md section fresh if enabled and AGENTS.md exists.
  */
 export const runAgentAutomation = async (options, notify = () => { }) => {
     const cwd = resolve(options.cwd);
     const discovered = await discoverConfig(cwd, options.config);
-    if (!discovered.raw)
-        return { settings: { ...normalizeAgentSettings(undefined) } };
-    const settings = normalizeAgentSettings(discovered.raw.agents);
+    const settings = normalizeAgentSettings(discovered.raw?.agents);
     const result = { settings };
-    if (settings.autoAgentsMd)
+    if (discovered.raw && 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/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAsBH,4BAA4B;AAC5B,eAAO,MAAM,MAAM,GAAU,UAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,IAAI,CA4DpF,CAAA;AAmBD,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,GAAU,UAAU,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAiB9E,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAsBH,4BAA4B;AAC5B,eAAO,MAAM,MAAM,GAAU,UAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,IAAI,CA6DpF,CAAA;AAmBD,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,GAAU,UAAU,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAiB9E,CAAA"}

package/library/cli.js

@@ -33,14 +33,15 @@ export const runCli = async (rawArgs = process.argv.slice(2)) => {
         }
         return;
     }
+    if (parsed.command && !validCommands.has(parsed.command)) {
+        throw new XDocsError(`Unknown command: ${parsed.command}\n\nRun \`xdocs --help\` for available commands.`);
+    }
+    const options = resolveOptions(parsed.flags);
     if (!parsed.command) {
+        await runAgentAutomation(options, (message) => process.stderr.write(message + '\n'));
         process.stdout.write(showHelp() + '\n');
         return;
     }
-    if (!validCommands.has(parsed.command)) {
-        throw new XDocsError(`Unknown command: ${parsed.command}\n\nRun \`xdocs --help\` for available commands.`);
-    }
-    const options = resolveOptions(parsed.flags);
     const command = parsed.command;
     if (automationCommands.has(command)) {
         await runAgentAutomation(options, (message) => process.stderr.write(message + '\n'));

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/embedded-resources.js

@@ -13,7 +13,7 @@ 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-as-xdocs/SKILL.md' with { type: 'text' };
+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 = () => {

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.js

@@ -32,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
@@ -69,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
@@ -175,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>]
@@ -187,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/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.3.0-alpha.1",
+  "version": "0.3.1",
   "type": "module",
   "main": "./library/guiho-xdocs.js",
   "types": "./library/guiho-xdocs.d.ts",
@@ -12,7 +12,7 @@
     }
   },
   "bin": {
-    "xdocs": "./bin/xdocs.exe"
+    "xdocs": "scripts/xdocs-bin.ts"
   },
   "files": [
     "README.md",
@@ -49,7 +49,7 @@
     "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",
+    "postinstall": "bun run scripts/install-package.ts",
     "typecheck": "tsc -p . --noEmit",
     "clean": "rm -rf .temp",
     "clean-build": "rm -rf build library bundle bin",

package/scripts/install-package.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env bun
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ *
+ * Package-manager install helper for xdocs.
+ *
+ * This script downloads the platform-native xdocs binary into `vendor/xdocs` or
+ * `vendor/xdocs.exe`. Package-manager installs use the small Bun launcher in
+ * `scripts/xdocs-bin.ts`; direct installers remain the no-Bun runtime path.
+ */
+
+type PackageJson = {
+  version?: string
+}
+
+const packageJson = await Bun.file(new URL('../package.json', import.meta.url)).json() as PackageJson
+const sourceEntrypoint = Bun.file(new URL('../source/guiho-xdocs-bin.ts', import.meta.url))
+
+if (await sourceEntrypoint.exists()) {
+  console.log('source checkout detected; skipping native binary download')
+  process.exit(0)
+}
+
+const version = process.env['XDOCS_VERSION'] ?? packageJson.version ?? 'latest'
+const repo = process.env['XDOCS_REPO'] ?? 'CGuiho/xdocs'
+const asset = detectAsset()
+const bundledAsset = Bun.file(new URL(`../bin/${asset}`, import.meta.url))
+const destination = new URL(`../vendor/xdocs${process.platform === 'win32' ? '.exe' : ''}`, import.meta.url)
+
+if (await bundledAsset.exists()) {
+  await Bun.write(destination, bundledAsset)
+  await makeExecutable(destination)
+  console.log(`installed bundled xdocs native binary: ${asset}`)
+  process.exit(0)
+}
+
+const tag = version === 'latest' ? 'latest' : `@guiho/xdocs@${version}`
+const url = tag === 'latest'
+  ? `https://github.com/${repo}/releases/latest/download/${asset}`
+  : `https://github.com/${repo}/releases/download/${encodeURIComponent(tag)}/${asset}`
+
+const response = await fetch(url)
+
+if (!response.ok) {
+  console.error(`error: failed to download ${url}`)
+  console.error(`status: ${response.status} ${response.statusText}`)
+  process.exit(1)
+}
+
+await Bun.write(destination, response)
+await makeExecutable(destination)
+console.log(`installed xdocs native binary: ${asset}`)
+
+async function makeExecutable(path: URL) {
+  if (process.platform === 'win32') return
+
+  const result = Bun.spawn(['chmod', '755', Bun.fileURLToPath(path)], {
+    stdout: 'ignore',
+    stderr: 'inherit',
+  })
+  const exitCode = await result.exited
+
+  if (exitCode !== 0) {
+    console.error('error: failed to make xdocs native binary executable')
+    process.exit(exitCode)
+  }
+}
+
+function detectAsset() {
+  const os = detectOs()
+  const arch = detectArch()
+  return `xdocs-${os}-${arch}${os === 'windows' ? '.exe' : ''}`
+}
+
+function detectOs() {
+  if (process.platform === 'linux') return 'linux'
+  if (process.platform === 'darwin') return 'macos'
+  if (process.platform === 'win32') return 'windows'
+  console.error(`error: unsupported OS: ${process.platform}`)
+  process.exit(1)
+}
+
+function detectArch() {
+  if (process.arch === 'x64') return 'x64'
+  if (process.arch === 'arm64') return 'arm64'
+  console.error(`error: unsupported architecture: ${process.arch}`)
+  process.exit(1)
+}

package/scripts/scripts.xdocs.md

@@ -1,10 +1,11 @@
 ---
 subject: xdocs-scripts
-description: Package-manager installation scripts for installing the native xdocs binary.
+description: Package-manager launcher and installation scripts for executing 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.
+  xdocs-bin.ts: Shipped Bun launcher used as the package bin; installs the native binary on first run when needed and delegates to it.
+  install-package.ts: Package-manager install helper that downloads or copies the matching GitHub Release native binary into vendor/xdocs or vendor/xdocs.exe.
 tags:
   - install
   - native-binary
@@ -13,6 +14,7 @@ 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.
+The `scripts/` directory contains the package-manager launcher and install
+helper. Package-manager and `bunx` execution start in `xdocs-bin.ts`; if the
+native binary is missing, it runs `install-package.ts` and then delegates to the
+downloaded binary in `vendor/`. Direct installers remain the no-Bun runtime path.

package/scripts/xdocs-bin.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ *
+ * Small package-manager launcher for the downloaded native xdocs binary.
+ */
+
+const binaryPath = new URL(`../vendor/xdocs${process.platform === 'win32' ? '.exe' : ''}`, import.meta.url)
+const executablePath = Bun.fileURLToPath(binaryPath)
+const binary = Bun.file(binaryPath)
+
+if (!(await binary.exists())) {
+  const installerPath = new URL('install-package.ts', import.meta.url)
+  const proc = Bun.spawn([process.execPath, Bun.fileURLToPath(installerPath)], {
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  })
+
+  const exitCode = await proc.exited
+  if (exitCode !== 0 || !(await Bun.file(binaryPath).exists())) {
+    console.error('error: xdocs native binary is missing. Reinstall @guiho/xdocs or run `bun run scripts/install-package.ts`.')
+    process.exit(exitCode || 1)
+  }
+}
+
+const proc = Bun.spawn([executablePath, ...process.argv.slice(2)], {
+  stdin: 'inherit',
+  stdout: 'inherit',
+  stderr: 'inherit',
+})
+
+process.exit(await proc.exited)

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
 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.
 ---
 
@@ -177,12 +178,12 @@ exclude = ["node_modules", ".git", "dist", "build", "library", "bin", "bundle"]
 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_agents_md = true      # keep the xdocs section in AGENTS.md up to date on bare and normal commands
+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. A bare `xdocs` invocation and normal data commands always bootstrap the standard global skill when no config is present; with config, set `auto_agents_md = false` to stop xdocs from touching AGENTS.md, and `auto_skill_install = false` to stop xdocs from installing or refreshing `guiho-s-xdocs` globally.
 
 ## 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.

package/scripts/install-native.cjs

@@ -1,101 +0,0 @@
-#!/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 })
-}