@guiho/xdocs 0.3.0-alpha.2 → 0.3.1

package/CHANGELOG.md

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

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
 
@@ -324,7 +324,7 @@ 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 or refresh the configured skill globally from the bundled package copy. Default: `true`.
@@ -349,12 +349,13 @@ The rule is: default to the standard target. Only write non-standard files (`.cl
 
 ### 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, 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.
+- 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
 
@@ -507,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-s-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
 

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
 
@@ -259,7 +261,7 @@ 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 or refresh the standard skill globally from the bundled copy. Default: true
 auto_skill_install = true
@@ -286,6 +288,8 @@ 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. 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.
+
 ---
 
 ## API Reference

package/jsr.json

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

package/library/agents.d.ts

@@ -70,10 +70,9 @@ 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 refreshes the global skill for
- * the configured tool from the bundled package copy.
+ * 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. */

package/library/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,eAAe,EACf,uBAAuB,EACvB,eAAe,EAChB,MAAM,YAAY,CAAA;AAInB,+CAA+C;AAC/C,eAAO,MAAM,cAAc,kBAAkB,CAAA;AAE7C,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAuB,CAAA;AAE1E;;iEAEiE;AACjE,eAAO,MAAM,iBAAiB,EAAE,MAS5B,CAAA;AAEJ,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,oBAAsC,CAAA;AAEpE,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,SAAS,cAAc,EAAyB,CAAA;AAE9E,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,EAAE,cAAyB,CAAA;AAEzD,2FAA2F;AAC3F,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,cAAc,EAKzE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,cAAc,EAK5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,EAAE,UAAU,MAAM,GAAG,SAAS,KAAG,cAAc,EAChC,CAAA;AAkB9D,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,mhCAoBV,CAAA;AAErB,KAAK,gBAAgB,GAAG;IACtB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,KAAK,mBAAmB,GAAG,gBAAgB,GAAG;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,sBAAsB,GAAG,eAAe,GAAG;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,MACnD,CAAA;AAO7D,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,OAC5D,CAAA;AAEpD,kEAAkE;AAClE,eAAO,MAAM,YAAY,GACvB,MAAM,cAAc,EACpB,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,CA6BjC,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,aAAa,GACxB,OAAO,SAAS,cAAc,EAAE,EAChC,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,EAAE,CAInC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAU,KAAK,MAAM,EAAE,gBAAc,KAAG,OAAO,CAAC,6BAA6B,CAkBjH,CAAA;AA4BD,sDAAsD;AACtD,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAWrD,CAAA;AAED,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,kBAAkB,CAI/F,CAAA;AAED;;;;;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"}
+{"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

@@ -208,19 +208,16 @@ 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 refreshes the global skill for
- * the configured tool from the bundled package copy.
+ * 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) {
         const globalSkill = await installSkill(settings.skillTool, 'global', { cwd, homeDirectory: options.homeDirectory });

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/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.2",
+  "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-s-xdocs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guiho-s-xdocs
-version: 0.3.0-alpha.2
+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.
 ---
 
@@ -178,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_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 or refreshing `guiho-s-xdocs` globally.
+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
 

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 })
-}