@guiho/xdocs 0.2.3 → 0.3.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # GUIHO XDocs Changelog
 
+## 0.3.0-alpha.1
+
+- Remove external parser dependencies (`smol-toml`, `yaml`) and use Bun-native `Bun.TOML.parse` and `Bun.YAML.parse` instead.
+- Change the package-manager `xdocs` bin to point at a native binary path and add a `postinstall` downloader that installs the matching GitHub Release binary into `bin/xdocs.exe`; Node.js is used only during install by Node-based package managers, not at `xdocs` runtime.
+- Update build configuration to include Bun types for the library build.
+- Document the native package-manager install path and Bun-native parser behavior.
+
+## 0.3.0-alpha.0
+
+- Add native-binary-first distribution support for xdocs, including a Bun-powered release binary matrix for Linux x64/arm64, macOS x64/arm64, and Windows x64.
+- Add direct installers (`install.sh` and `install.ps1`) so users can install the native `xdocs` binary without requiring Node.js or Bun at runtime.
+- Add a native binary entrypoint that embeds prompts, the `guiho-as-xdocs` skill, and package version metadata so compiled binaries work without adjacent package files.
+- Update CI and the publish workflow to build the release binary matrix and publish native binaries as GitHub Release assets while keeping npm publishing intact.
+- Document the native binary distribution model in `DOCS.md`, `README.md`, `ARCHITECTURE.md`, and `AGENTS.md`.
+- Add xdocs metadata files for the package root, source module, and devops module.
+
 ## 0.2.3
 
 - `xdocs agents instructions` and config-gated AGENTS.md automation now tolerate formatter-only blank lines and trailing whitespace inside the managed xdocs block, preserving the user's formatted block when the actual text is unchanged.

package/DOCS.md

@@ -11,13 +11,15 @@ XDocs is a documentation tool, not a versioning tool. It never bumps versions or
 ## Package Overview
 
 - Package name: `@guiho/xdocs`
-- Runtime: Node (>= 18) and Bun (ESM)
+- Source/runtime during development: Bun and TypeScript (ESM)
+- Primary release runtime: compiled native Bun binary assets
+- Package-manager install path: Node.js is used only for `postinstall`; the installed `xdocs` command executes the native binary
 - Package type: ESM
 - Library entrypoint: `source/guiho-xdocs.ts`
 - CLI entrypoint: `source/guiho-xdocs-bin.ts`
 - TypeScript build output: `library/` (used by `main` and `types`)
-- Standalone binary output: `bin/xdocs` or `bin/xdocs.exe`
-- Dependencies: `smol-toml` (TOML config parsing), `yaml` (YAML frontmatter parsing)
+- Standalone binary output: `bin/xdocs-*` release assets
+- Runtime parser dependencies: none; xdocs uses Bun-native TOML and YAML parsing
 
 The public package exposes a CLI named `xdocs` and a TypeScript API for discovering xdocs files, parsing metadata, building the hierarchy tree, generating documentation, and installing the agent skill.
 
@@ -81,7 +83,17 @@ Scanning walks the project tree and skips directories listed in `[scan].exclude`
 
 ## Installation
 
-Install XDocs as a development dependency:
+Direct native binary install (no Node.js or Bun required after installation):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/install.sh | sh
+```
+
+```powershell
+irm https://raw.githubusercontent.com/CGuiho/xdocs/main/install.ps1 | iex
+```
+
+Install XDocs as a development dependency through a JavaScript package manager. This uses Node.js during `postinstall` to download the matching native binary, then the installed `xdocs` command executes the native binary:
 
 ```bash
 bun add -d @guiho/xdocs
@@ -93,7 +105,7 @@ Or with npm:
 npm install -D @guiho/xdocs
 ```
 
-Use the CLI through the package manager or through the installed `xdocs` binary.
+Use the direct installer when you do not want a JavaScript package manager involved. Use the package-manager install when you want project-local dependency management; after installation, `xdocs` still runs as a native binary.
 
 ## Quick Start
 
@@ -355,7 +367,7 @@ Maintaining xdocs files is an automatic responsibility for an agent working in a
 
 ## Prompts
 
-Prompt templates live in `prompts/*.md` and are embedded at build time via Bun text imports. Each prompt file has its own YAML frontmatter with `name` and `description`. The CLI exposes them through `xdocs prompt --name=<name>`. Available names: `write`, `update`, `agents`, `generate`.
+Prompt templates live in `prompts/*.md` and are read from disk at runtime relative to `import.meta.url`. Each prompt file has its own YAML frontmatter with `name` and `description`. The CLI exposes them through `xdocs prompt --name=<name>`. Available names: `write`, `update`, `agents`, `generate`.
 
 ## TypeScript API
 
@@ -401,12 +413,14 @@ The API uses the same configuration discovery and validation as the CLI.
 
 - `source/guiho-xdocs.ts`: public library export surface.
 - `source/guiho-xdocs-bin.ts`: CLI binary entrypoint.
+- `source/guiho-xdocs-native-bin.ts`: Bun-compiled native binary entrypoint that registers embedded resources before importing the CLI.
+- `source/embedded-resources.ts`: prompt, skill, and package metadata text imports used only for native binary embedding.
 - `source/cli.ts`: argument parsing, command dispatch, config-gated automation, and process-facing error handling.
 - `source/config.ts`: TOML discovery, schema validation, defaulting, default config generation, and agent-settings normalization.
 - `source/discovery.ts`: filesystem scanning and xdocs file matching.
 - `source/metadata.ts`: YAML frontmatter extraction and metadata validation.
 - `source/tree.ts`: tree assembly, integrity checks, and rendering (text, markdown).
-- `source/prompts.ts`: prompt loader (imports `prompts/*.md` as text via Bun).
+- `source/prompts.ts`: prompt loader (reads `prompts/*.md` from disk at runtime relative to `import.meta.url`).
 - `source/help.ts`: help text and version display.
 - `source/flags.ts`: argument/flag parsing utilities.
 - `source/errors.ts`: `XDocsError` with stable exit codes and the `invariant` helper.
@@ -468,13 +482,29 @@ Build the library:
 bun run build
 ```
 
-Compile the standalone binary:
+Compile the host standalone binary:
 
 ```bash
 bun run binary
 ```
 
-The library reads the prompt templates and the `guiho-as-xdocs` skill from the package's `prompts/` and `skills/` directories at runtime (via `readFileSync` relative to `import.meta.url`), so the published package works under both Node and Bun.
+Compile the supported release binary matrix:
+
+```bash
+bun run binaries
+```
+
+Supported release asset matrix:
+
+- Linux x64: `xdocs-linux-x64`
+- Linux arm64: `xdocs-linux-arm64`
+- macOS x64: `xdocs-macos-x64`
+- macOS arm64: `xdocs-macos-arm64`
+- Windows x64: `xdocs-windows-x64.exe`
+
+Windows arm64 is intentionally not published until Bun's compilation support is reliable enough for this project. Unsupported platforms should use a documented manual path: install Bun and run from source, or download a compatible release asset manually.
+
+The package-manager install path downloads a native binary to `bin/xdocs.exe` during `postinstall`, and the `xdocs` bin entry points to that native binary. The native binary entrypoint embeds prompt templates, the `guiho-as-xdocs` skill, and package version metadata before importing the CLI, so installed binaries do not need adjacent prompt or skill files at runtime.
 
 ## Documentation Requirement Before Publishing
 
@@ -494,10 +524,11 @@ Before publishing a new version:
 4. Run `bun run typecheck`.
 5. Run `bun test`.
 6. Run `bun run build`.
-7. Run `bun run binary` when the CLI binary is part of release validation.
+7. Run `bun run binary` and `bun run binaries` when the CLI binary is part of release validation.
 8. Build the Mirror release plan: `bun x @guiho/mirror version plan <target>`.
 9. Commit release-documentation updates before applying the version bump.
 10. Apply the bump with GUIHO Mirror: `bun x @guiho/mirror version apply <target> --yes`.
+11. Confirm the tag workflow uploads native binary assets to the GitHub Release and publishes the npm package.
 
 Versioning itself is handled by GUIHO Mirror via `mirror.config.toml`; XDocs never edits version fields directly.
 

package/README.md

@@ -16,12 +16,28 @@ xdocs runs on **Bun** and **Node >= 20**. It ships as a compiled binary, a thin
 
 ### Installation
 
+Direct native binary install (no Node.js or Bun required after installation):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/install.sh | sh
+```
+
+```powershell
+irm https://raw.githubusercontent.com/CGuiho/xdocs/main/install.ps1 | iex
+```
+
+Set `XDOCS_VERSION=0.2.3` (or the full tag `@guiho/xdocs@0.2.3`) before running an installer to pin a specific release instead of installing the latest.
+
+Package-manager install (convenient for JavaScript projects; downloads the matching native binary during `postinstall`, then runs the native binary):
+
 ```bash
 npm install -D @guiho/xdocs
 # or
 bun add -d @guiho/xdocs
 ```
 
+Native release assets are published for Linux x64/arm64, macOS x64/arm64, and Windows x64. Windows arm64 is not published yet. Package-manager installs require Node.js only during installation for the `postinstall` downloader; running `xdocs` afterwards executes the native binary.
+
 ### Initializing
 
 Set up xdocs in your project:
@@ -31,7 +47,7 @@ xdocs init
 ```
 
 This creates:
-- `XDOCS.md` -- the root documentation file for the project
+- `XDOCS.md` -- the single frontmatter-less repository index listing packages/applications
 - `xdocs.config.toml` -- configuration with sensible defaults
 - Updates `AGENTS.md` with instructions for AI agents
 - Installs the `guiho-as-xdocs` agent skill (standard `.agents/skills`)

package/jsr.json

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

package/library/agents.d.ts.map

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

package/library/agents.js

@@ -21,6 +21,9 @@ export const xdocsSkillName = 'guiho-as-xdocs';
  * runtime (relative to this module) so the compiled library works under both
  * Node and Bun. The file ships with the package in `skills/`. */
 export const xdocsSkillContent = (() => {
+    const embedded = globalThis.__XDOCS_EMBEDDED_RESOURCES__?.skill;
+    if (embedded)
+        return embedded;
     try {
         return readFileSync(new URL('../skills/guiho-as-xdocs/SKILL.md', import.meta.url), 'utf8');
     }

package/library/config.d.ts.map

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

package/library/config.js

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

package/library/embedded-resources.d.ts

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

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

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

package/library/embedded-resources.js

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

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

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

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

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

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

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

package/library/help.d.ts.map

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

package/library/help.js

@@ -4,6 +4,9 @@
 import { readFileSync } from 'node:fs';
 /** Read the package version from package.json. */
 export const readPackageVersion = () => {
+    const embedded = globalThis.__XDOCS_EMBEDDED_RESOURCES__?.version;
+    if (embedded)
+        return embedded;
     try {
         const raw = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
         const pkg = JSON.parse(raw);

package/library/metadata.d.ts.map

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

package/library/metadata.js

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

package/library/prompts.d.ts.map

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

package/library/prompts.js

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

package/package.json

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

package/scripts/install-native.cjs

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

package/scripts/scripts.xdocs.md

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