@guiho/runx 0.2.7 → 0.4.0

package/CHANGELOG.md

@@ -15,6 +15,33 @@ owner: runx
 
 # Changelog
 
+## 0.4.0 - 2026-07-18
+
+### Added
+
+- Added complete Developer Context help, the singular agent skill/instruction/prompt namespace, a detached TypeBox-validated update cache, and the canonical `guiho-i-runx` prompt.
+- Added a Node-compatible npm bootstrap, complete dual-tool direct installers, and exact verification for twelve native binaries plus two agent assets.
+
+### Changed
+
+- Rebuilt RunX around the complete RFC 0034 Bun, strict ESM TypeScript, raw Citty, and TypeBox contract.
+- Configuration now resolves only through `--config`, effective-cwd `runx.yaml`, then `~/.guiho/runx/runx.yaml`.
+- The startup banner, help modes, output streams, exit codes, upgrade catalog, release names, bundled skill, documentation, and workflows now follow the canonical RFC contract.
+
+### Removed
+
+- Removed the run command alias, root selector shorthand, `--file`, parent-directory discovery, plural agent namespace, arbitrary short flags, legacy platform asset names, and Bun-dependent npm launcher.
+
+## 0.3.0 - 2026-07-18
+
+### Added
+
+- Added transactional executable replacement and automatic rollback for both Windows and POSIX updates with a bounded 10-second verification timeout.
+- Added a complete GitHub release catalog parser that paginates all releases and implements SemVer prerelease precedence.
+- Added structured JSON progress events and equivalent console phase reporting.
+- Added exact-version recovery commands and process-stop commands to every upgrade outcome.
+- Added hardened direct installers (`install.ps1`/`install.sh`) that verify the installed version and support rollback.
+
 ## 0.2.7 - 2026-07-15
 
 ### Added

package/DOCS.md

@@ -1,156 +1,155 @@
 ---
 name: RunX Documentation
-purpose: Provide the canonical user-facing RunX CLI and manifest reference.
-description: Documents command behavior, manifest schema, safety model, agent workflow, and native distribution.
+purpose: Define the canonical supported RunX CLI contract.
+description: Complete reference for command routing, YAML configuration, startup, help, output, agents, upgrades, installation, and release assets.
 created: 2026-07-12
-flags: []
+flags:
+  - canonical
 tags:
-  - documentation
   - cli
+  - reference
 keywords:
-  - runx
-  - manifest
+  - RFC 0034
+  - runx.yaml
+  - agent namespace
+  - release assets
 owner: runx
 ---
 
 # RunX Documentation
 
-## Purpose
-
-RunX makes project operations visible and documented. A `runx.yaml` file is a
-single local command catalog; RunX discovers the nearest catalog, validates it,
-lists its commands, and runs exactly one selected command.
-
-## Commands
-
-| Command | Purpose |
-| --- | --- |
-| `runx` | Show the home page and usage without loading a manifest. |
-| `runx -h`, `runx --help` | Show Citty-generated usage without loading a manifest. Append help to a command for command-specific usage. |
-| `runx -v`, `runx --version` | Show the installed version without loading a manifest. |
-| `runx init [--cwd <path>]` | Interactively create an empty `runx.yaml` catalog in the selected directory. |
-| `runx list` | List all manifest commands. Add `--format json` for structured output. |
-| `runx describe <selector>` | Show one command's description and operational metadata. |
-| `runx check` | Validate discovery and the manifest without execution. |
-| `runx run <selector>` | Execute a selected command. |
-| `runx r <selector>` | Short alias for `runx run`. |
-| `runx <selector>` | Human shorthand for `runx run <selector>` when no built-in name conflicts. |
-| `runx agents install <local|global>` | Install `guiho-s-runx`; add `--tool agents|claude|all` when needed. |
-| `runx agents instructions` | Add or refresh the managed RunX section in `AGENTS.md`. |
-| `runx upgrade` | Replace a native installed executable when a newer release is available. |
-| `runx upgrade check` | Check whether a newer release is available. |
-| `runx upgrade list` | List recent release versions. |
-| `runx uninstall [--dry-run]` | Remove a native installed executable. |
-
-Global flags: `--cwd <path>`, `--file <path>`, `--format <text|json>`,
-`--verbose`, `-v`/`--version`, `-h`/`--help`, `--help-tree`, and
-`--help-docs`. Applicable command flags include `--dry-run`, `--yes`, and
-`--tool <agents|claude|all>`. Options may appear before or after their command.
-Unknown options and missing required arguments produce command usage instead
-of falling through to manifest discovery.
-
-`runx init` is intentionally an interactive text workflow: it accepts `--cwd`
-to select the target project, but rejects `--file` (the target is always
-`runx.yaml`) and `--format json`. It previews the exact file, requires a final
-confirmation, asks before replacing an existing file, and leaves no partial
-file when cancelled. It creates the manifest only; the configured scripts
-directory is created later when the first script is added.
-
-Citty is the CLI parser, command router, alias registry, and ordinary usage
-renderer. RunX keeps its home page, extended command tree, and manifest guide
-as the explicit `runx`, `--help-tree`, and `--help-docs` surfaces.
-
-## Manifest
-
-RunX searches upward from the current directory for `runx.yaml`. Use `--file`
-to select an explicit manifest. RunX does not merge files.
-
-```yaml
-version: "1.0.0"
-project:
-  name: example
-scripts:
-  directory: scripts
-groups:
-  public:
-    summary: Default public project commands.
-  development:
-    summary: Local development work.
-  release:
-    summary: Explicit release actions.
-commands:
-  - uid: example-check
-    id: check
-    group: development
-    summary: Type-check the project.
-    description: Runs the project's static type checker without emitting build files.
-    command: bun run typecheck
-    cwd: .
-    shell: auto
-    tags: [validation]
-  - uid: example-release
-    id: release
-    group: release
-    summary: Build the release artifact.
-    description: Builds the release artifact after the project has passed its required checks.
-    command: bun run build
-    confirm: always
+## Runtime Contract
+
+RunX uses Bun, strict ESM TypeScript, raw Citty, and TypeBox. Core source is
+Bun-only. The isolated npm bootstrap is Node-compatible because it must work
+before Bun is installed.
+
+No arguments prints exactly:
+
+```text
+Hello Windows - runx v<version>
+```
+
+The foreground reads `~/.guiho/runx/cache.json` and never waits for network
+work. A detached worker validates GitHub release data and atomically refreshes
+that cache. When a decoded cache announces an update, RunX prints:
+
+```text
+New version available. Run this command to upgrade: runx upgrade
 ```
 
-`version` is a Semantic Versioning string. RunX currently supports major
-version `1`, including valid prerelease and build metadata forms. Every manifest
-also requires `scripts.directory`, which must be a relative subdirectory inside
-the manifest directory, and a `public` group with a non-empty summary. A
-catalog may start with `commands: []`; every command added later must explicitly
-name an existing group (normally `public`).
+## Configuration
+
+RunX loads YAML only. Resolution is:
+
+1. `--config <path>`;
+2. `<effective-cwd>/runx.yaml`;
+3. `~/.guiho/runx/runx.yaml`.
+
+Whenever loaded, the absolute path is reported as:
+
+```text
+configuration file loaded: <absolute-path>
+```
+
+The complete manifest and nested records are TypeBox-decoded. Invalid or absent
+configuration exits `3`.
+
+## Commands And Help
 
-Required command fields are `uid`, `id`, `group`, `summary`, `description`,
-and `command`. `uid` and `id` begin with a lowercase letter and use lowercase
-letters, digits, and hyphens. `uid` is globally unique; the group and ID pair
-is also unique.
+The public command tree is the catalog shown in [README.md](README.md). Citty is
+the only parser and router. The only short flags are `-h` and root `-v`.
 
-Optional command fields are `cwd`, `shell`, `tags`, and `confirm`. `cwd` is
-relative to the manifest and cannot escape its directory. Shell values are
-`auto`, `bash`, `sh`, `powershell`, and `cmd`. Confirmation values are `never`
-and `always`.
+Every root, group, and leaf supports:
 
-## Selectors and Safety
+- standard help with usage, description, positionals, flags, and examples;
+- `--help-tree`, using Unicode box-drawing branches;
+- `--help-tree-depth <positive-integer>`;
+- redirect-safe Markdown through `--help-docs`.
 
-RunX resolves selectors in this order: exact UID, exact `group/id`, one-based
-manifest index, then an unambiguous bare ID. Use UIDs in automation. An index is
-only stable until commands are reordered, and an ambiguous bare ID fails rather
-than selecting a command.
+Only `runx run <selector>` executes catalog code. Listing, describing, checking,
+help, initialization, agent operations, upgrade inspection, and dry runs do not.
 
-`list`, `describe`, `check`, and `run --dry-run` never execute a configured
-command. A real run streams stdout/stderr and uses the child process exit code.
-`confirm: always` requires the user to add `--yes`.
+## Output And Exit Codes
 
-Manifests are executable local code. Do not place secrets in a manifest and do
-not assume a group name determines safety.
+Text results use stdout and diagnostics use stderr. JSON mode emits one valid
+JSON document on stdout; configuration reports and diagnostics remain on
+stderr.
 
-## Agent Skill
+| Code | Meaning |
+| ---: | --- |
+| `0` | Success |
+| `1` | Unexpected operational failure |
+| `2` | Usage or structured flag validation failure |
+| `3` | Configuration resolution or decoding failure |
+| `4` | Release or network failure |
+| `5` | Installation, upgrade, or filesystem mutation failure |
+| `130` | Interruption |
 
-The bundled `guiho-s-runx` skill directs agents to validate and list a catalog,
-select a UID, inspect unfamiliar commands, use dry runs, and obtain explicit
-authorization before `--yes` for high-impact commands. Install it with:
+An executed catalog command preserves its exact delegated exit code.
+
+## Agent Integration
+
+Skill install, update, and uninstall default to global scope and target both:
+
+```text
+~/.agents/skills/guiho-s-runx
+~/.claude/skills/guiho-s-runx
+```
+
+Use `--local` for the corresponding project-local paths.
+
+Instruction actions manage both `AGENTS.md` and `CLAUDE.md` when both exist,
+the existing one when only one exists, and create `AGENTS.md` when neither
+exists. The exact idempotent boundaries are:
 
 ```text
-runx agents install local
+<!-- BEGIN RUNX — DO NOT EDIT THIS SECTION -->
+<!-- END RUNX -->
 ```
 
-## Native Install, Upgrade, and Uninstall
+The canonical prompt is `guiho-i-runx`. `agent prompt list --names` prints raw
+names; `agent prompt show <id>` prints only the raw prompt.
+
+## Upgrade And Installation
 
-`devops/install.ps1` installs Windows assets and `devops/install.sh` installs
-macOS/Linux assets from GitHub Releases into the user's local bin directory.
-`runx upgrade` uses the matching release asset and replaces a native executable.
-On Windows it renames the running executable, installs and verifies the target
-version at the original path, and restores the previous executable if replacement
-fails. Only cleanup of the renamed old image is deferred until RunX exits.
-`runx uninstall` removes the same native executable and supports `--dry-run`.
+`runx upgrade` accepts `--version`, `--arch`, `--variant`, `--dry-run`, and
+`--format`. x64 defaults to `baseline`. `upgrade list` supports positive
+`--page` and `--per-page` plus `--pre-releases`.
 
-When the latest GitHub Release matches the installed version, `runx upgrade` prints `Already up to date.` and exits successfully without downloading or scheduling executable replacement. JSON output reports `upToDate: true`.
+Replacement is transactional: download, native-format validation, backup,
+replacement, version verification, rollback on failure, agent-skill refresh,
+instruction reconciliation, then cleanup.
 
-CI validates code and compiles the local executable plus the native release
-matrix. Protected `@guiho/runx@*` tags run the `production` publish workflow,
-which uploads twelve native assets to GitHub Releases and publishes the public
-npm package through OIDC trusted publishing.
+Both direct installers show target metadata and download progress, configure
+PATH, install both global skill copies, reconcile project instructions, and
+verify the final version.
+
+## Npm Bootstrap
+
+`scripts/runx-bin.mjs` detects platform and architecture, chooses the exact
+versioned native asset, caches it under `~/.guiho/runx/npm/<version>/`, applies
+Unix execute permissions, delegates args/stdin/stdout/stderr/environment, and
+preserves the native exit code. It contains no RunX domain logic.
+
+## Release Assets
+
+Every release contains exactly fourteen assets: twelve native binaries and two
+agent assets.
+
+```text
+runx-linux-arm64
+runx-linux-x64
+runx-linux-x64-baseline
+runx-linux-x64-modern
+runx-darwin-arm64
+runx-darwin-x64
+runx-darwin-x64-baseline
+runx-darwin-x64-modern
+runx-windows-arm64.exe
+runx-windows-x64.exe
+runx-windows-x64-baseline.exe
+runx-windows-x64-modern.exe
+guiho-s-runx
+guiho-i-runx
+```

package/README.md

@@ -1,108 +1,89 @@
 ---
 name: RunX README
-purpose: Introduce RunX and give users the shortest installation and command-catalog path.
-description: Public overview, direct installation commands, quick manifest example, and documentation links.
+purpose: Introduce RunX and provide the supported RFC 0034 installation and quick-start workflow.
+description: Public overview of the RunX YAML command catalog, native CLI, agent integration, and release channels.
 created: 2026-07-12
-flags: []
+flags:
+  - public
 tags:
-  - documentation
   - cli
-keywords:
   - runx
-  - readme
+keywords:
+  - runx.yaml
+  - native binary
+  - command catalog
 owner: runx
 ---
 
-# GUIHO RunX
+# RunX
 
-RunX is a local, language-agnostic command catalog. Put documented commands in
-`runx.yaml`; use `runx list` to discover them and `runx run` to execute one.
-It works for Bun, Python, Go, shell, and mixed repositories because it executes
-local shell commands rather than package-manager scripts.
+RunX is a language-agnostic command catalog backed by a strict `runx.yaml`
+file. It makes project operations discoverable and keeps execution explicit:
+only `runx run <selector>` spawns a configured command.
 
 ## Install
 
-RunX is distributed as a native executable from GitHub Releases and as the
-public `@guiho/runx` package on npm. The npm launcher requires Bun.
-
-```sh
-bun add --global @guiho/runx
-```
+PowerShell:
 
 ```powershell
 irm https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.ps1 | iex
 ```
 
+POSIX:
+
 ```sh
-curl -fsSL https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.sh | sh
+curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.sh | sh
 ```
 
-## Quick Start
+The direct installers select and verify a native asset, install `runx` on PATH,
+install `guiho-s-runx` into both global agent-tool directories, and reconcile
+RunX instructions in the current project.
 
-Start with the interactive initializer:
+The npm package is a Node-compatible bootstrap that downloads and delegates to
+the version-matched native binary. Bun is not required for npm installation or
+first execution.
+
+## Quick Start
 
 ```text
 runx init
+runx check
+runx list
+runx describe app-dev
+runx run app-dev --dry-run
+runx run app-dev
 ```
 
-It writes only `runx.yaml`—not an empty `scripts/` directory. The resulting
-catalog starts with a SemVer `1.x` manifest version, a configurable scripts
-directory, the required `public` group, and no commands. Add commands directly
-or ask an agent to add a script under the configured directory and its command
-entry together.
-
-For example, a catalog with a development command can look like this:
-
-```yaml
-version: "1.0.0"
-project:
-  name: example
-scripts:
-  directory: scripts
-groups:
-  public:
-    summary: Default public project commands.
-  development:
-    summary: Local development commands.
-commands:
-  - uid: app-dev
-    id: dev
-    group: development
-    summary: Start the application locally.
-    description: Starts the application in local development mode until interrupted.
-    command: bash scripts/dev.sh
-    shell: bash
-    tags: [local, watch]
-```
+Configuration resolves in this exact order:
 
-Then use RunX:
+1. `--config <path>`;
+2. `<effective-cwd>/runx.yaml`;
+3. `~/.guiho/runx/runx.yaml`.
 
-```text
-runx                         Show the home page and usage.
-runx -h                      Show Citty-generated command help.
-runx -v                      Show the installed version without loading a manifest.
-runx init                    Interactively create an empty runx.yaml catalog.
-runx list                    List commands in the nearest manifest.
-runx describe app-dev        Explain one command without execution.
-runx run app-dev --dry-run   Inspect the execution plan.
-runx run app-dev             Execute the command.
-runx r app-dev               Use the short run alias.
-runx app-dev                 Use the human selector shorthand.
-```
+RunX never searches parent directories.
 
-Use `confirm: always` for commands that should require an explicit `--yes`.
-Use `runx list --format json` and stable UIDs for agent automation.
-RunX uses Citty for argument parsing, aliases, command routing, and ordinary
-usage text, so conventional `-h`/`--help` and `-v`/`--version` work outside a
-configured project.
+## Command Catalog
 
-## Documentation
-
-- [Full CLI and manifest reference](DOCS.md)
-- [Contributing](CONTRIBUTING.md)
-- [Security policy](SECURITY.md)
-- [Changelog](CHANGELOG.md)
+```text
+runx
+├── list
+├── describe <selector>
+├── run <selector>
+├── check
+├── init
+├── agent
+│   ├── skill install|uninstall|update|list|show
+│   ├── instruction apply|remove|update|show
+│   └── prompt list|show
+├── upgrade
+│   ├── check
+│   └── list
+└── uninstall
+```
 
-## License
+Every scope supports `--help`, `-h`, `--help-tree`,
+`--help-tree-depth <positive-integer>`, and `--help-docs`. Only root
+`--version` also has `-v`.
 
-[MIT](LICENSE.md)
+See [DOCS.md](DOCS.md) for configuration, output, exit codes, agent resources,
+upgrade behavior, installers, npm bootstrap, and the exact release matrix.

package/devops/build-binaries.ts

@@ -1,57 +1,53 @@
 /**
- * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
- *
- * Build release binaries for the supported RunX platform matrix.
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 
-import { mkdir, rm, stat } from 'node:fs/promises'
-import { join } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { $ } from 'bun'
+import { joinPath } from '../source/path-utils.js'
+
+export {
+  agentAssetNames,
+  binaryTargets,
+  expectedReleaseAssetNames,
+}
 
 type BinaryTarget = {
   readonly bunTarget: string
   readonly assetName: string
 }
 
-const targets: readonly BinaryTarget[] = [
+const binaryTargets: readonly BinaryTarget[] = [
   { bunTarget: 'bun-linux-arm64', assetName: 'runx-linux-arm64' },
   { bunTarget: 'bun-linux-x64', assetName: 'runx-linux-x64' },
   { bunTarget: 'bun-linux-x64-baseline', assetName: 'runx-linux-x64-baseline' },
   { bunTarget: 'bun-linux-x64-modern', assetName: 'runx-linux-x64-modern' },
-  { bunTarget: 'bun-darwin-arm64', assetName: 'runx-macos-arm64' },
-  { bunTarget: 'bun-darwin-x64', assetName: 'runx-macos-x64' },
-  { bunTarget: 'bun-darwin-x64-baseline', assetName: 'runx-macos-x64-baseline' },
-  { bunTarget: 'bun-darwin-x64-modern', assetName: 'runx-macos-x64-modern' },
+  { bunTarget: 'bun-darwin-arm64', assetName: 'runx-darwin-arm64' },
+  { bunTarget: 'bun-darwin-x64', assetName: 'runx-darwin-x64' },
+  { bunTarget: 'bun-darwin-x64-baseline', assetName: 'runx-darwin-x64-baseline' },
+  { bunTarget: 'bun-darwin-x64-modern', assetName: 'runx-darwin-x64-modern' },
   { bunTarget: 'bun-windows-arm64', assetName: 'runx-windows-arm64.exe' },
   { bunTarget: 'bun-windows-x64', assetName: 'runx-windows-x64.exe' },
   { bunTarget: 'bun-windows-x64-baseline', assetName: 'runx-windows-x64-baseline.exe' },
   { bunTarget: 'bun-windows-x64-modern', assetName: 'runx-windows-x64-modern.exe' },
 ]
 
-const expectedAssetCount = 12
-const assetNames = targets.map((target) => target.assetName)
-const uniqueAssetNames = new Set(assetNames)
+const agentAssetNames = ['guiho-s-runx', 'guiho-i-runx'] as const
+const expectedReleaseAssetNames = [...binaryTargets.map((target) => target.assetName), ...agentAssetNames]
 
-if (targets.length !== expectedAssetCount) {
-  throw new Error(`Expected ${expectedAssetCount} binary targets, found ${targets.length}`)
+if (expectedReleaseAssetNames.length !== 14 || new Set(expectedReleaseAssetNames).size !== 14) {
+  throw new Error('RunX release matrix must contain exactly fourteen unique assets.')
 }
 
-if (uniqueAssetNames.size !== assetNames.length) {
-  throw new Error('Binary target matrix contains duplicate asset names')
-}
-
-const root = fileURLToPath(new URL('..', import.meta.url))
-const binDirectory = join(root, 'bin')
-const bunExecutable = process.execPath
-
-await rm(binDirectory, { recursive: true, force: true })
-await mkdir(binDirectory, { recursive: true })
+if (import.meta.main) {
+  const root = Bun.fileURLToPath(new URL('..', import.meta.url))
+  const bin = joinPath(root, 'bin')
+  await $`rm -rf ${bin}`.quiet()
+  await $`mkdir -p ${bin}`.quiet()
 
-const builds = targets.map(async (target) => {
-  const outputPath = join(binDirectory, target.assetName)
-  const proc = Bun.spawn({
-    cmd: [
-      bunExecutable,
+  for (const target of binaryTargets) {
+    const output = joinPath(bin, target.assetName)
+    const child = Bun.spawn([
+      process.execPath,
       'build',
       'source/guiho-runx-native-bin.ts',
       '--compile',
@@ -61,39 +57,25 @@ const builds = targets.map(async (target) => {
       '--target',
       target.bunTarget,
       '--outfile',
-      outputPath,
-    ],
-    cwd: root,
-    stdout: 'pipe',
-    stderr: 'pipe',
-  })
-
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ])
-
-  if (exitCode !== 0) {
-    throw new Error([
-      `Failed to build ${target.bunTarget} -> ${target.assetName}`,
-      stdout.trim(),
-      stderr.trim(),
-    ].filter(Boolean).join('\n'))
+      output,
+    ], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ])
+    if (exitCode !== 0) throw new Error([`Failed to build ${target.assetName}`, stdout, stderr].filter(Boolean).join('\n'))
+    if ((await Bun.file(output).size) === 0) throw new Error(`Built binary is empty: ${target.assetName}`)
+    process.stdout.write(`built: ${target.assetName}\n`)
   }
 
-  process.stdout.write(`built: ${target.bunTarget} -> bin/${target.assetName}\n`)
-})
-
-await Promise.all(builds)
+  await Bun.write(joinPath(bin, 'guiho-s-runx'), Bun.file(joinPath(root, 'skills', 'guiho-s-runx', 'SKILL.md')))
+  await Bun.write(joinPath(bin, 'guiho-i-runx'), Bun.file(joinPath(root, 'prompts', 'guiho-i-runx.md')))
 
-for (const target of targets) {
-  const outputPath = join(binDirectory, target.assetName)
-  const output = await stat(outputPath)
-
-  if (output.size === 0) {
-    throw new Error(`Built binary is empty: bin/${target.assetName}`)
+  const observed = [...new Bun.Glob('*').scanSync({ cwd: bin, onlyFiles: true })].sort()
+  const expected = [...expectedReleaseAssetNames].sort()
+  if (JSON.stringify(observed) !== JSON.stringify(expected)) {
+    throw new Error(`Release asset mismatch.\nExpected: ${expected.join(', ')}\nObserved: ${observed.join(', ')}`)
   }
+  process.stdout.write('verified exactly 14 release assets\n')
 }
-
-process.stdout.write(`verified ${targets.length} native binary assets\n`)

package/devops/devops.xdocs.md

@@ -4,9 +4,11 @@ description: Native release-asset compilation and direct RunX installer scripts.
 parent: runx
 children: []
 files:
-  build-binaries.ts: Cross-compiles supported Bun native executable assets.
-  install.ps1: Installs the latest Windows executable from GitHub Releases.
-  install.sh: Installs the latest macOS or Linux executable from GitHub Releases.
+  build-binaries.ts: Cross-compiles twelve RFC-named native binaries and adds the two exact agent assets.
+  verify-release-assets.ts: Fails on any missing, duplicate, extra, or legacy release asset name.
+  installers.spec.ts: Verifies both installers expose progress, validation, dual-tool skills, instruction reconciliation, and no POSIX Bun dependency.
+  install.ps1: Resolves an exact Windows release, downloads and validates a compatible asset, transactionally replaces the canonical executable, verifies its version, and rolls back on failure.
+  install.sh: POSIX installer for Linux or Darwin with progress, validation, PATH, dual skills, instructions, verification, and rollback.
 documents: {}
 tags:
   - devops
@@ -15,11 +17,12 @@ tags:
 keywords:
   - runx
   - windows
-  - macos
+  - darwin
   - linux
   - native binary
 flags: []
 status: stable
 ---
 
-These scripts support direct native installation without an npm publication.
+These scripts build and verify the exact fourteen-asset release and support
+direct installation without npm or Bun.