@guiho/xdocs 0.3.0-alpha.1 → 0.3.0-alpha.2

package/CHANGELOG.md

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

package/DOCS.md

@@ -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)
@@ -327,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
@@ -350,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.
 
@@ -394,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:
@@ -425,10 +428,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 +507,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 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
 
@@ -550,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

@@ -50,7 +50,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 +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`
 
@@ -207,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)
@@ -261,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"
@@ -269,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
@@ -284,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.3.0-alpha.1",
+  "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,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;;;;;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,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 = {}) => {
@@ -191,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);
@@ -203,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/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.0-alpha.2",
   "type": "module",
   "main": "./library/guiho-xdocs.js",
   "types": "./library/guiho-xdocs.d.ts",

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.