@guiho/xdocs 0.3.0-alpha.2 → 0.4.2

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,15 +1,30 @@
 ---
 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.
+version: 0.4.0
+purpose: Teach AI agents how to maintain xdocs descriptor files, companion Markdown documents, metadata, and tree integrity.
+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 named `*.xdocs.md` descriptor as part of the change. This includes creating, updating, or regenerating `*.xdocs.md` descriptor files, companion Markdown documents, 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.
+created: 2026-07-06
+flags:
+  - automatic-documentation-maintenance
+  - companion-document-metadata
+tags:
+  - xdocs
+  - documentation
+  - agents
+keywords:
+  - xdocs
+  - structured documentation
+  - companion documents
+  - agent workflow
+owner: xdocs-guiho-s-xdocs-skill
 ---
 
 # GUIHO XDocs
 
-GUIHO XDocs is a deterministic CLI and TypeScript library for **structured documentation of codebases**. It lets an AI agent understand a project without reading every source file: each directory carries a small Markdown file with YAML frontmatter that describes its subject, purpose, files, and place in a parent-child hierarchy.
+GUIHO XDocs is a deterministic CLI and TypeScript library for **structured documentation of codebases**. It lets an AI agent understand a project without reading every source file: each documented directory carries one named `*.xdocs.md` descriptor with YAML frontmatter that describes its subject, purpose, files, companion Markdown documents, and place in a parent-child hierarchy.
 
 ```text
-source tree -> xdocs files (.docs.md / .xdocs.md) -> tree + metadata -> AI-readable map
+source tree -> named *.xdocs.md descriptors + companion *.md documents -> tree + metadata -> AI-readable map
 ```
 
 Use xdocs for documentation work instead of ad hoc README sprawl or re-reading the whole codebase. The value of xdocs is that the structure (subjects, descriptions, files, parent/child links) is machine-readable and stays close to the code it describes.
@@ -28,15 +43,16 @@ xdocs is a Bun/TypeScript ESM tool. Bun is the recommended runtime. The CLI neve
 
 ## Core Concepts
 
-- **xdocs file**: a Markdown file with YAML frontmatter that documents one directory/module. Default extensions are `.docs.md` and `.xdocs.md`. Extensions are configurable in `xdocs.config.toml`.
+- **xdocs descriptor**: a named Markdown file ending in `.xdocs.md` with YAML frontmatter that documents one directory/module. There is exactly one descriptor per documented directory. The file must have a name such as `authentication.xdocs.md`; a file named only `.xdocs.md` is invalid.
+- **Companion document**: a same-directory plain Markdown file ending in `.md` but not `.xdocs.md` and not `XDOCS.md`. Every companion document must be listed in the descriptor's `documents` metadata map, and ordinary companion documents should carry their own YAML frontmatter with `name`, `purpose`, `description`, `created`, `flags`, `tags`, `keywords`, and `owner`.
 - **Repository root index**: there is exactly one `XDOCS.md` per repository, at the repo root. It has **no frontmatter** — it is a plain index that lists the repository's packages and applications, and it is not itself a tree node.
 - **Package/application root**: each package or application has its own root `.xdocs.md` file (with frontmatter and `parent: null`) that is the top of that package's documentation tree. `XDOCS.md` lists these package roots.
-- **Tree**: a parent-child **containment** hierarchy (not a dependency graph), assembled from each `.xdocs.md` / `.docs.md` file's `subject` / `parent` / `children` fields. A module's `parent` is the `subject` of the module that contains it; a package/application root uses `parent: null`.
+- **Tree**: a parent-child **containment** hierarchy (not a dependency graph), assembled from each `.xdocs.md` descriptor's `subject` / `parent` / `children` fields. A module's `parent` is the `subject` of the module that contains it; a package/application root uses `parent: null`.
 - **AI mode**: `xdocs.config.toml` `[ai].mode` is either `"prompt"` (announce the documentation updates, then write them) or `"auto"` (write immediately). It governs *how* you write docs, not *whether* — documenting a changed module is always required (see Automatic Documentation Maintenance).
 
 ### Metadata schema (YAML frontmatter)
 
-Every `.xdocs.md` / `.docs.md` file carries frontmatter with these fields. The repository's single `XDOCS.md` is the exception: it has no frontmatter and is just an index.
+Every `*.xdocs.md` descriptor carries frontmatter with these fields. The repository's single `XDOCS.md` is the exception: it has no frontmatter and is just an index.
 
 | Field         | Type                  | Meaning                                                       |
 | ------------- | --------------------- | ------------------------------------------------------------ |
@@ -45,29 +61,74 @@ Every `.xdocs.md` / `.docs.md` file carries frontmatter with these fields. The r
 | `parent`      | string \| null        | `subject` of the containing module; `null` for a package/application root. |
 | `children`    | string[]              | `subject`s of directly contained modules.                    |
 | `files`       | map<string,string>    | Filename -> short description of each significant file.      |
+| `documents`   | map<string,string>    | Same-directory plain Markdown filename -> short description. |
 | `tags`        | string[]              | Free-form classification labels.                             |
+| `keywords`    | string[]              | Search terms and concepts agents can use to match requests.  |
 | `flags`       | string[]              | Behavioral markers for tools/agents.                         |
 | `status`      | string (optional)     | Lifecycle marker (e.g. `stable`, `draft`, `deprecated`).     |
 
-Keep `subject` values unique across the project, keep `parent`/`children` consistent in both directions, and keep `files` in sync with what is actually on disk.
+Keep `subject` values unique across the project, keep `parent`/`children` consistent in both directions, keep `files` in sync with implementation files, and keep `documents` in sync with same-directory plain Markdown files.
+
+### Companion document metadata (YAML frontmatter)
+
+Ordinary same-directory companion Markdown documents also use YAML frontmatter.
+This metadata makes the document useful before an agent reads the whole body.
+The `owner` field must be the `subject` of the same-directory xdocs descriptor
+that owns the document.
+
+```yaml
+---
+name: authentication-implementation
+purpose: Explain the implementation details and decisions behind authentication.
+description: Detailed notes for login, password verification, and session behavior.
+created: 2026-07-06
+flags: []
+tags:
+  - security
+keywords:
+  - login
+  - password verification
+  - sessions
+owner: auth
+---
+```
+
+Companion document fields:
+
+| Field         | Type       | Meaning                                                        |
+| ------------- | ---------- | -------------------------------------------------------------- |
+| `name`        | string     | Stable document name or title.                                 |
+| `purpose`     | string     | Why this document exists and what question it answers.         |
+| `description` | string     | One-line summary of the document's contents.                   |
+| `created`     | string     | Creation date in `YYYY-MM-DD` format.                          |
+| `flags`       | string[]   | Behavioral markers for tools/agents.                           |
+| `tags`        | string[]   | Free-form classification labels.                               |
+| `keywords`    | string[]   | Search terms and concepts agents can use to match requests.    |
+| `owner`       | string     | Owning xdocs descriptor `subject` in the same directory.        |
+
+Special-purpose Markdown files that already have a required host schema, such
+as prompt templates or `SKILL.md`, must preserve their required host fields.
+When compatible, add the companion metadata fields as well.
 
 ## Automatic Documentation Maintenance (core responsibility)
 
-Maintaining xdocs files is an **automatic, built-in responsibility — not a task the user has to request.** Treat it as part of the definition of done for every code change in an xdocs project. The user should never have to ask you to document a module; you do it as a reflex whenever you touch one.
+Maintaining xdocs descriptors is an **automatic, built-in responsibility — not a task the user has to request.** Treat it as part of the definition of done for every code change in an xdocs project. The user should never have to ask you to document a module; you do it as a reflex whenever you touch one.
 
-**Trigger.** Whenever you, as the agent, do any of the following, you must create or update the affected directory's xdocs file in the *same unit of work*, before you consider the task finished:
+**Trigger.** Whenever you, as the agent, do any of the following, you must create or update the affected directory's named xdocs descriptor in the *same unit of work*, before you consider the task finished:
 
 - Create a new directory, module, or subpackage.
 - Add, rename, move, or delete significant files in a directory.
+- Add, rename, move, or delete sibling plain Markdown documents in a directory.
 - Change what a module does, what it exposes, or how it relates to its parent or children.
 
 **Action.**
 
-- If the directory has **no** xdocs file, create one (for example `<name>.xdocs.md`) in that directory.
-- If it **already** has one, update it so it matches the new reality.
+- If the directory has **no** xdocs descriptor, create one named `<name>.xdocs.md` in that directory.
+- If it **already** has one, update it so it matches the new reality. If there is more than one descriptor, consolidate to one.
+- Never create or keep a descriptor named only `.xdocs.md`. `.xdocs.md` is the extension, not the whole filename.
 - Then fix the parent/child links and verify with `<xdocs> tree`.
 
-**What every module's xdocs file must capture:**
+**What every module's xdocs descriptor must capture:**
 
 - `subject` — the module's unique name in the tree.
 - `description` — the module's **purpose**: what it is for and what it does.
@@ -75,12 +136,16 @@ Maintaining xdocs files is an **automatic, built-in responsibility — not a tas
 - `parent` — the `subject` of the containing module (and add this module to that parent's `children`).
 - `children` — the `subject`s of the modules contained inside this one.
 
-**Do not wait to be asked.** After you finish creating or modifying a module or directory, create or update its xdocs file as part of the same change. A code change that adds or alters a module is **not complete** until its xdocs file and the affected parent/child links are updated.
+Every descriptor also includes `documents`, a map from each same-directory plain Markdown filename to the purpose of that companion document.
+Each ordinary companion document listed there should include its own frontmatter
+with `owner` equal to this descriptor's `subject`.
+
+**Do not wait to be asked.** After you finish creating or modifying a module or directory, create or update its xdocs descriptor as part of the same change. A code change that adds or alters a module is **not complete** until its xdocs descriptor, companion-document list, and affected parent/child links are updated.
 
 **How `[ai].mode` applies.** The mode controls only *how* you write the docs, never *whether* you write them and never whether the user must ask first:
 
-- `auto` — create/update the xdocs files immediately as part of the change, then report what changed.
-- `prompt` — state exactly which xdocs files you are creating or updating, then write them (honoring any pending confirmation). Announcing is for transparency; it does not make documentation optional and the user never has to request it.
+- `auto` — create/update the xdocs descriptors immediately as part of the change, then report what changed.
+- `prompt` — state exactly which xdocs descriptors you are creating or updating, then write them (honoring any pending confirmation). Announcing is for transparency; it does not make documentation optional and the user never has to request it.
 
 ### Example: documenting a new module
 
@@ -95,8 +160,14 @@ children: []
 files:
   login.ts: Email/password login flow; exports `login()` and `verifyPassword()`.
   session.ts: Session lifecycle; exports `createSession()` and `validateSession()`.
+documents:
+  authentication-implementation.md: Companion notes that explain implementation details and decisions.
 tags:
   - security
+keywords:
+  - authentication
+  - login
+  - sessions
 flags: []
 status: stable
 ---
@@ -105,7 +176,31 @@ Auth validates credentials and issues sessions. `login()` delegates password
 checks to `verifyPassword()`; sessions are created and validated in `session.ts`.
 ```
 
-Then add `auth` to the `children` list of the `src` module's xdocs file so the tree stays consistent.
+Then create or update `src/auth/authentication-implementation.md` with
+companion-document frontmatter:
+
+```markdown
+---
+name: authentication-implementation
+purpose: Explain authentication implementation details and decisions.
+description: Detailed notes for login, password verification, and session behavior.
+created: 2026-07-06
+flags: []
+tags:
+  - security
+keywords:
+  - authentication
+  - password verification
+  - session lifecycle
+owner: auth
+---
+
+# Authentication Implementation
+
+Describe the implementation details that are too long for `auth.xdocs.md`.
+```
+
+Then add `auth` to the `children` list of the `src` module's xdocs descriptor so the tree stays consistent.
 
 If the directory you are documenting is the **root of a package or application** (not a sub-module), set `parent: null` instead, and list that package's root `.xdocs.md` in the repository's single `XDOCS.md` index rather than in a parent module's `children`.
 
@@ -115,23 +210,26 @@ When you start working in a project that uses xdocs:
 
 1. Read the root `XDOCS.md` to learn the project's top-level subject and structure.
 2. Run `<xdocs> tree` to see the module hierarchy.
-3. Run `<xdocs> scan` to see documentation coverage and which directories are missing xdocs files.
-4. Read `xdocs.config.toml` and note `[ai].mode`, the supported `[extensions]`, and `[scan].exclude`.
-5. When you navigate into a module, read that module's xdocs file (frontmatter first, body only if you need more) instead of reading every source file.
+3. Run `<xdocs> scan` to see documentation coverage, invalid descriptors, and companion-document coverage.
+4. Read `xdocs.config.toml` and note `[ai].mode` and `[scan].exclude`; xdocs descriptors always use the `.xdocs.md` suffix.
+5. When you navigate into a module, read that module's named `*.xdocs.md` descriptor frontmatter first. Read listed companion documents only when their descriptions show they are relevant.
 
 ## Documentation Workflow (writing and updating)
 
 Follow this whenever the automatic trigger above fires, or when the user asks to document a directory:
 
-1. Determine the target directory and whether it already has an xdocs file (`<xdocs> scan` or `<xdocs> list <path>`).
+1. Determine the target directory and whether it already has exactly one named `*.xdocs.md` descriptor (`<xdocs> scan` or `<xdocs> list <path>`).
 2. Read the directory's actual files so the documentation reflects reality. Never invent files, modules, or behavior that is not present.
 3. Respect `[ai].mode` (it controls how you write, not whether you write):
-   - **prompt mode**: state exactly which xdocs files you are creating or updating, then write them (honor a pending confirmation, but never skip the documentation).
-   - **auto mode**: create or update the xdocs files immediately, then report what changed.
-4. Write or update the xdocs file with correct frontmatter:
-   - Set `subject` (unique), `description` (the module's purpose), and `files` (each real file -> short purpose, including key functions/exports).
+   - **prompt mode**: state exactly which xdocs descriptors you are creating or updating, then write them (honor a pending confirmation, but never skip the documentation).
+   - **auto mode**: create or update the xdocs descriptors immediately, then report what changed.
+4. Write or update the xdocs descriptor with correct frontmatter:
+   - Set `subject` (unique), `description` (the module's purpose), and `files` (each real implementation/configuration file -> short purpose, including key functions/exports).
+   - Set `documents` to every same-directory plain Markdown file -> short purpose. Use `{}` when there are no companion documents.
+   - Set `keywords` to search terms and concepts that should help agents match user requests to the module.
+   - For each ordinary companion document, add or update frontmatter with `name`, `purpose`, `description`, `created`, `flags`, `tags`, `keywords`, and `owner`; set `owner` to the descriptor's `subject`.
    - Set `parent` to the containing module's `subject`, and add this `subject` to that parent's `children`.
-   - Use `tags`/`flags`/`status` where useful.
+   - Use `tags`/`keywords`/`flags`/`status` where useful.
 5. Keep the tree consistent: if you add a module, update its parent's `children`; if you remove one, update both sides.
 6. Validate with `<xdocs> tree` (it reports duplicate subjects, orphans, and missing children) and fix any reported issues.
 
@@ -150,7 +248,8 @@ When generating from scratch, prefer `<xdocs> generate <path>` (one directory) o
 
 ## Safety Rules
 
-- Never leave a new or changed module undocumented. Creating or updating its xdocs file is part of finishing the work, not a separate request the user must make.
+- Never leave a new or changed module undocumented. Creating or updating its xdocs descriptor is part of finishing the work, not a separate request the user must make.
+- Never leave an ordinary companion Markdown document without useful frontmatter; it should identify its `owner`, purpose, tags, keywords, and flags.
 - Never fabricate files, modules, descriptions, or relationships. Documentation must match the repository.
 - Never edit generated or build outputs (`library/`, `bundle/`, `bin/`, `*.tgz`). They are ignored and regenerated.
 - In prompt mode, announce the xdocs changes you will make and honor a pending confirmation — but still treat documenting the change as required, never optional.
@@ -166,7 +265,7 @@ xdocs searches for configuration via `--config <path>`, `./xdocs.config.toml`, o
 schema = 1
 
 [extensions]
-supported = [".docs.md", ".xdocs.md"]
+supported = [".xdocs.md"]
 
 [ai]
 mode = "prompt"            # "prompt" (announce and wait) or "auto" (update immediately)
@@ -178,22 +277,24 @@ 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.
+
+The `[extensions]` section is retained for config compatibility, but the only supported descriptor suffix is `.xdocs.md`.
 
 ## CLI Reference
 
 ```bash
 xdocs init                     # create XDOCS.md + xdocs.config.toml, update AGENTS.md, install the skill
-xdocs scan                     # report xdocs coverage across the project
+xdocs scan                     # report descriptor and companion-document coverage
 xdocs tree                     # print the module hierarchy
-xdocs list <path>              # list files in a scope with descriptions
+xdocs list <path>              # list files and companion documents 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 merge [path]             # merge a directory's xdocs descriptors into one document
 xdocs prompt --name=<name>     # print a ready-made AI prompt (write|update|agents|generate)
 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
@@ -252,7 +353,7 @@ await ensureAgentsInstructions(process.cwd(), true)
 When reporting an xdocs result, include:
 
 - The command that ran and the target path.
-- Which xdocs files were created or changed, if any.
+- Which xdocs descriptors and companion documents were created or changed, if any.
 - Tree/coverage status (subjects added, orphans or duplicates resolved).
 - The configured AI mode, and — in prompt mode — exactly what you are waiting to write.
 

package/skills/guiho-s-xdocs/guiho-s-xdocs.xdocs.md

@@ -0,0 +1,26 @@
+---
+subject: xdocs-guiho-s-xdocs-skill
+description: Packaged guiho-s-xdocs agent skill that teaches AI agents how to maintain xdocs projects.
+parent: xdocs-skills
+children: []
+files: {}
+documents:
+  SKILL.md: Versioned xdocs workflow skill installed into .agents/skills or .claude/skills; defines descriptor, companion-document metadata, scan, tree, and maintenance rules.
+tags:
+  - skills
+  - agents
+  - documentation
+keywords:
+  - xdocs skill
+  - companion metadata
+  - agent workflow
+flags: []
+status: stable
+---
+
+The `guiho-s-xdocs/` directory contains the bundled agent skill shipped with the
+package. The installer treats `SKILL.md` as the source of truth and refreshes
+installed copies when the bundled version or content changes.
+The skill also documents the standard frontmatter fields expected on ordinary
+companion Markdown documents: `name`, `purpose`, `description`, `created`,
+`flags`, `tags`, `keywords`, and `owner`.

package/skills/skills.xdocs.md

@@ -2,13 +2,18 @@
 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.
+children:
+  - xdocs-guiho-s-xdocs-skill
+files: {}
+documents: {}
 tags:
   - skills
   - agents
   - documentation
+keywords:
+  - agent skills
+  - bundled skill
+  - skill installation
 flags: []
 status: stable
 ---
@@ -16,4 +21,4 @@ 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.
+their frontmatter version or content differs from the bundled file.

package/scripts/install-native.cjs

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