@guiho/xdocs 0.4.2 → 0.4.9

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # GUIHO XDocs Changelog
 
+## 0.4.9
+
+- Fix GitHub Actions artifact names for scoped package tags by using run IDs, allowing the native binary publish workflow to upload artifacts and continue to GitHub Release asset publication.
+
+## 0.4.8
+
+- Harden the direct Linux/macOS Bash installer and Windows PowerShell installer for native xdocs binaries, including baseline-first x64 fallback, explicit default/modern variants, downloaded binary validation, PATH setup, and shadowing warnings.
+- Verify the 12-asset native binary matrix during `bun run binaries` for Linux, macOS, and Windows arm64/x64 baseline/default/modern outputs.
+- Upload native binaries as CI workflow artifacts and publish/verify all 12 GitHub Release assets before npm publishing on version-tag releases.
+- Document native binary installation, PATH fallback commands, and the full release asset matrix in `README.md` and `DOCS.md`.
+
 ## 0.4.0-alpha.0
 
 - Change the documentation model to one named `*.xdocs.md` descriptor per documented directory, with `XDOCS.md` reserved as the frontmatter-less repository index.

package/DOCS.md

@@ -119,11 +119,29 @@ Scanning walks the project tree and skips directories listed in `[scan].exclude`
 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
+curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.sh | bash
 ```
 
 ```powershell
-irm https://raw.githubusercontent.com/CGuiho/xdocs/main/install.ps1 | iex
+irm https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.ps1 | iex
+```
+
+The Linux/macOS installer is a Bash script in `devops/install.sh`; the Windows
+installer is the PowerShell script in `devops/install.ps1`. Both download from
+GitHub Releases, install into `~/.local/bin` by default, and add that directory
+then fall back to the default and `modern` variants. Users can force a specific
+architecture or variant with `--arch` / `--variant` on Bash or `-Arch` /
+`-Variant` on PowerShell.
+
+Manual PATH fallback commands:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+```powershell
+$env:Path = "$HOME\.local\bin;$env:Path"
+[Environment]::SetEnvironmentVariable('Path', "$HOME\.local\bin;" + [Environment]::GetEnvironmentVariable('Path', 'User'), 'User')
 ```
 
 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:
@@ -469,7 +487,7 @@ The API uses the same configuration discovery and validation as the CLI.
 
 ## Development Workflow
 
-Run package commands from `xdocs/`.
+Run package commands from the repository root.
 
 ```bash
 bun install
@@ -498,6 +516,7 @@ Current tests cover:
 - Tree construction, rendering, and integrity validation.
 - Config discovery, validation, and defaulting.
 - Agent settings normalization, skill path resolution, skill installation (local/global), tool detection, and AGENTS.md section insertion.
+- Package launcher execution from a source checkout without a native vendor binary.
 
 Run all tests:
 
@@ -533,15 +552,34 @@ bun run binaries
 
 Supported release asset matrix:
 
-- Linux x64: `xdocs-linux-x64`
+- Linux x64: `xdocs-linux-x64-baseline`, `xdocs-linux-x64`, `xdocs-linux-x64-modern`
 - Linux arm64: `xdocs-linux-arm64`
-- macOS x64: `xdocs-macos-x64`
+- macOS x64: `xdocs-macos-x64-baseline`, `xdocs-macos-x64`, `xdocs-macos-x64-modern`
 - 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 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.
+- Windows x64: `xdocs-windows-x64-baseline.exe`, `xdocs-windows-x64.exe`, `xdocs-windows-x64-modern.exe`
+- Windows arm64: `xdocs-windows-arm64.exe`
+
+`bun run binaries` verifies that all 12 expected native assets are present and
+non-empty after compilation. CI builds the matrix and uploads `bin/xdocs-*` as a
+GitHub Actions artifact. The tag publish workflow has `contents: write`, rebuilds
+the same matrix, uploads it as a workflow artifact, publishes `bin/xdocs-*` to
+the matching GitHub Release before npm publishing, and verifies that the release
+contains exactly 12 `xdocs-*` assets.
+
+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 ships `scripts/xdocs-bin.ts` as the package
+`bin`. That launcher delegates to `vendor/xdocs` or `vendor/xdocs.exe` when the
+native binary exists. In source checkouts, it falls back to
+`source/guiho-xdocs-bin.ts` so local package execution tests the checked-out
+source without downloading a release artifact. In published package layouts, it
+calls `scripts/install-package.ts` during first run if the vendor binary 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,15 +2,13 @@
 
 **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 named `*.xdocs.md` descriptors throughout your project so that AI agents (and humans) can navigate, understand, and work within a codebase without reading every file. Each descriptor describes the directory it lives in -- its purpose, searchable keywords, its files, its companion Markdown documents, and how it fits into the project hierarchy.
+xdocs is a CLI tool that places named `*.xdocs.md` descriptors throughout your project so that AI agents (and humans) can navigate, understand, and work within a codebase without reading every file. Each descriptor describes the directory it lives in -- its purpose, searchable keywords, its files, its companion Markdown documents, and how it fits into the project hierarchy.
 
 ```text
 codebase -> named *.xdocs.md descriptors + companion *.md documents -> AI understands the project
 ```
 
-xdocs ships as compiled native binaries, a thin Bun launcher for package-manager and `bunx` execution, and a fully-typed TypeScript library.
+xdocs ships as a single native binary — no Node.js, Bun, or runtime required.
 
 ---
 
@@ -18,27 +16,74 @@ xdocs ships as compiled native binaries, a thin Bun launcher for package-manager
 
 ### Installation
 
-Direct native binary install (no Node.js or Bun required after installation):
+Download and run the installer:
+
+**Linux / macOS:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.ps1 | iex
+```
+
+The installers download native binaries from GitHub Releases, install `xdocs` into `~/.local/bin` by default, and add that directory to your user PATH when possible. x64 installs prefer the `baseline` variant first for maximum compatibility, then fall back to the default and `modern` variants.
+
+**Flags and options:**
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/CGuiho/xdocs/main/install.sh | sh
+# Pin a specific version
+curl .../install.sh | bash -s -- --version 0.4.7
+
+# Force architecture and variant
+curl .../install.sh | bash -s -- --arch arm64
+curl .../install.sh | bash -s -- --arch x64 --variant modern
+curl .../install.sh | bash -s -- --arch x64 --variant default
+
+# Custom install directory
+curl .../install.sh | bash -s -- --install-dir /usr/local/bin
 ```
 
+PowerShell examples:
+
 ```powershell
-irm https://raw.githubusercontent.com/CGuiho/xdocs/main/install.ps1 | iex
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.ps1))) -Version 0.4.7
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.ps1))) -Arch x64 -Variant baseline
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.ps1))) -InstallDir "$HOME\.local\bin"
+```
+
+Or download the script first and run with flags directly:
+```bash
+curl -O https://raw.githubusercontent.com/CGuiho/xdocs/main/devops/install.sh
+chmod +x install.sh
+./install.sh --version latest --arch x64 --variant baseline
 ```
 
-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.
+Native binaries are built and uploaded for all supported OS/architecture/variant combinations:
 
-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):
+| OS | ARM64 | x64 baseline | x64 default | x64 modern |
+| --- | --- | --- | --- | --- |
+| Linux | `xdocs-linux-arm64` | `xdocs-linux-x64-baseline` | `xdocs-linux-x64` | `xdocs-linux-x64-modern` |
+| macOS | `xdocs-macos-arm64` | `xdocs-macos-x64-baseline` | `xdocs-macos-x64` | `xdocs-macos-x64-modern` |
+| Windows | `xdocs-windows-arm64.exe` | `xdocs-windows-x64-baseline.exe` | `xdocs-windows-x64.exe` | `xdocs-windows-x64-modern.exe` |
+
+CI builds the same 12 native binaries and uploads them as a GitHub Actions artifact. Version-tag releases upload `bin/xdocs-*` to the matching GitHub Release and verify that all 12 assets are present.
+
+If your current shell does not see the updated PATH immediately, open a new terminal or run one of these commands:
 
 ```bash
-npm install -D @guiho/xdocs
-# or
-bun add -d @guiho/xdocs
+# bash/zsh
+export PATH="$HOME/.local/bin:$PATH"
+
+# fish
+fish_add_path "$HOME/.local/bin"
 ```
 
-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.
+```powershell
+$env:Path = "$HOME\.local\bin;$env:Path"
+[Environment]::SetEnvironmentVariable('Path', "$HOME\.local\bin;" + [Environment]::GetEnvironmentVariable('Path', 'User'), 'User')
+```
 
 ### Initializing
 
@@ -404,10 +449,9 @@ console.log(prompt?.body)
 
 ## Development
 
-Development requires Bun. Run from the `xdocs/` directory:
+Development requires Bun. Run from the repository root:
 
 ```bash
-cd xdocs
 bun install
 bun run typecheck
 bun test
@@ -419,4 +463,4 @@ bun run binary
 
 ## License
 
-MIT -- see [LICENSE.md](xdocs/LICENSE.md).
+MIT -- see [LICENSE.md](LICENSE.md).

package/docs/decisions/2026-07-09-package-launcher-source-fallback.md

@@ -0,0 +1,65 @@
+---
+name: Package Launcher Source Fallback
+purpose: Record the immediate repair decisions for broken xdocs package execution after the package moved to the repository root.
+description: Explains why the package launcher now falls back to the TypeScript CLI in source checkouts and why root package metadata/docs were corrected together.
+created: 2026-07-09T18:38:18Z
+flags:
+  - decision
+tags:
+  - cli
+  - package
+  - documentation
+keywords:
+  - xdocs-bin
+  - source checkout
+  - native binary
+  - vendor
+  - package root
+  - mirror.config.toml
+---
+
+# Package Launcher Source Fallback
+
+## Summary
+
+xdocs failed when the package launcher was executed from a source checkout with no
+`vendor/xdocs` native binary. `scripts/install-package.ts` correctly skips native
+binary download when `source/guiho-xdocs-bin.ts` exists, but
+`scripts/xdocs-bin.ts` still expected the vendor binary to appear and exited with
+an error.
+
+The selected fix is to make the package launcher prefer the native vendor binary
+when it exists, fall back to the TypeScript CLI when running from a source
+checkout, and only invoke the installer for published package layouts where the
+source entrypoint is absent.
+
+## Decisions
+
+1. Preserve native-binary-first execution for installed packages. Published npm
+   installs and `bunx` executions should still delegate to `vendor/xdocs` or
+   `vendor/xdocs.exe` after postinstall or first-run installation.
+2. Treat `source/guiho-xdocs-bin.ts` as the source-checkout fallback. This keeps
+   local development and repository-root package execution working without
+   downloading a release artifact.
+3. Keep package-root metadata consistent with the current layout. The package now
+   lives at the repository root, so `repository.directory`, `mirror.config.toml`,
+   `AGENTS.md`, `XDOCS.md`, and the root xdocs descriptor must not point at a
+   nested `xdocs/` package directory.
+
+## Rejected Alternatives
+
+1. Always download a native binary, even in source checkouts. This would make
+   development depend on an already-published release and would not test the
+   local TypeScript source being edited.
+2. Run `install-package.ts` first and infer its skip result from output. That
+   keeps the broken control flow indirect and noisy for normal source-checkout
+   commands.
+3. Remove the native launcher path entirely. That would regress the intended
+   CLI-only distribution where users can run the compiled binary without Node.js
+   or Bun at runtime after installation.
+
+## Validation
+
+The repair is validated by a regression test that executes
+`bun run scripts/xdocs-bin.ts --version` from the source checkout and asserts that
+it exits successfully without reporting a missing native binary.

package/docs/decisions/decisions.xdocs.md

@@ -0,0 +1,22 @@
+---
+subject: xdocs-decisions
+description: Decision records for xdocs implementation and operational repairs.
+parent: xdocs-docs
+children: []
+files: {}
+documents:
+  2026-07-09-package-launcher-source-fallback.md: Records the decision to make the package launcher fall back to the TypeScript CLI in source checkouts while published installs keep using native binaries.
+tags:
+  - documentation
+  - decisions
+keywords:
+  - decisions
+  - launcher
+  - source checkout
+flags: []
+status: stable
+---
+
+The `docs/decisions/` directory stores point-in-time technical decisions for
+xdocs. Each decision document captures context, selected behavior, rejected
+alternatives, and validation evidence for future agents and maintainers.

package/docs/docs.xdocs.md

@@ -2,7 +2,8 @@
 subject: xdocs-docs
 description: Durable project documentation for xdocs behavior, design notes, and implementation context.
 parent: xdocs-package
-children: []
+children:
+  - xdocs-decisions
 files: {}
 documents:
   2026-07-05-xdocs-document-model.md: Defines the named descriptor plus companion Markdown document model for xdocs modules.
@@ -17,6 +18,6 @@ flags: []
 status: stable
 ---
 
-The `docs/` directory stores durable xdocs project notes. Each plain Markdown
-document in this directory is listed in `documents` so agents can find the note
-from descriptor metadata before opening the full document.
+The `docs/` directory stores durable xdocs project notes. Plain Markdown
+documents directly in this directory are listed in `documents`; categorized
+subdirectories such as `decisions/` have their own xdocs descriptors.

package/jsr.json

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

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

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */

package/library/guiho-xdocs-bin.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/xdocs",
   "description": "Structured documentation system for codebases. Helps AI make sense of projects.",
-  "version": "0.4.2",
+  "version": "0.4.9",
   "type": "module",
   "main": "./library/guiho-xdocs.js",
   "types": "./library/guiho-xdocs.d.ts",
@@ -66,8 +66,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/CGuiho/xdocs.git",
-    "directory": "xdocs"
+    "url": "git+https://github.com/CGuiho/xdocs.git"
   },
   "homepage": "https://github.com/CGuiho/xdocs#readme",
   "bugs": {

package/scripts/install-package.ts

@@ -23,33 +23,47 @@ if (await sourceEntrypoint.exists()) {
 
 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 candidates = detectAssetCandidates()
 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)
+for (const asset of candidates) {
+  const bundledAsset = Bun.file(new URL(`../bin/${asset}`, 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}`
+for (const asset of candidates) {
+  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)
+  console.log(`    Downloading ${asset} from GitHub Releases...`)
+  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)
+  if (!response.ok) {
+    if (candidates.length > 1 && asset !== candidates[candidates.length - 1]) {
+      console.log(`    ${asset} not available (${response.status}), trying next variant...`)
+      continue
+    }
+    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}`)
+  process.exit(0)
 }
 
-await Bun.write(destination, response)
-await makeExecutable(destination)
-console.log(`installed xdocs native binary: ${asset}`)
+console.error('error: no compatible xdocs binary found for this platform')
+process.exit(1)
 
 async function makeExecutable(path: URL) {
   if (process.platform === 'win32') return
@@ -66,10 +80,16 @@ async function makeExecutable(path: URL) {
   }
 }
 
-function detectAsset() {
+function detectAssetCandidates() {
   const os = detectOs()
   const arch = detectArch()
-  return `xdocs-${os}-${arch}${os === 'windows' ? '.exe' : ''}`
+  const ext = os === 'windows' ? '.exe' : ''
+
+  if (arch === 'x64') {
+    return [`xdocs-${os}-x64-baseline${ext}`, `xdocs-${os}-x64${ext}`, `xdocs-${os}-x64-modern${ext}`]
+  }
+
+  return [`xdocs-${os}-${arch}${ext}`]
 }
 
 function detectOs() {
@@ -85,4 +105,4 @@ function detectArch() {
   if (process.arch === 'arm64') return 'arm64'
   console.error(`error: unsupported architecture: ${process.arch}`)
   process.exit(1)
-}
+}

package/scripts/scripts.xdocs.md

@@ -4,7 +4,7 @@ description: Package-manager launcher and installation scripts for executing the
 parent: xdocs-package
 children: []
 files:
-  xdocs-bin.ts: Shipped Bun launcher used as the package bin; installs the native binary on first run when needed and delegates to it.
+  xdocs-bin.ts: Shipped Bun launcher used as the package bin; delegates to an installed native binary, falls back to the TypeScript CLI in source checkouts, and installs the native binary on first run for published packages.
   install-package.ts: Package-manager install helper that downloads or copies the matching GitHub Release native binary into vendor/xdocs or vendor/xdocs.exe.
 documents: {}
 tags:
@@ -21,5 +21,7 @@ status: stable
 
 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.
+native binary is missing in a published package, it runs `install-package.ts` and
+then delegates to the downloaded binary in `vendor/`. Source checkouts run the
+TypeScript CLI directly when no vendor binary exists. Direct installers remain
+the no-Bun runtime path.

package/scripts/xdocs-bin.ts

@@ -6,10 +6,24 @@
  */
 
 const binaryPath = new URL(`../vendor/xdocs${process.platform === 'win32' ? '.exe' : ''}`, import.meta.url)
+const sourceEntrypointPath = new URL('../source/guiho-xdocs-bin.ts', import.meta.url)
 const executablePath = Bun.fileURLToPath(binaryPath)
 const binary = Bun.file(binaryPath)
+const args = process.argv.slice(2)
 
 if (!(await binary.exists())) {
+  const sourceEntrypoint = Bun.file(sourceEntrypointPath)
+
+  if (await sourceEntrypoint.exists()) {
+    const proc = Bun.spawn([process.execPath, Bun.fileURLToPath(sourceEntrypointPath), ...args], {
+      stdin: 'inherit',
+      stdout: 'inherit',
+      stderr: 'inherit',
+    })
+
+    process.exit(await proc.exited)
+  }
+
   const installerPath = new URL('install-package.ts', import.meta.url)
   const proc = Bun.spawn([process.execPath, Bun.fileURLToPath(installerPath)], {
     stdin: 'inherit',
@@ -24,10 +38,10 @@ if (!(await binary.exists())) {
   }
 }
 
-const proc = Bun.spawn([executablePath, ...process.argv.slice(2)], {
+const proc = Bun.spawn([executablePath, ...args], {
   stdin: 'inherit',
   stdout: 'inherit',
   stderr: 'inherit',
 })
 
-process.exit(await proc.exited)
+process.exit(await proc.exited)