@guiho/runx 0.4.1 → 0.5.2

package/CHANGELOG.md

@@ -15,6 +15,62 @@ owner: runx
 
 # Changelog
 
+## 0.5.2 - 2026-07-20
+
+### Fixed
+
+- Changed the Linux/macOS installer to download latest native and agent assets
+  through GitHub's stable `releases/latest/download` aliases, avoiding scoped
+  package-tag truncation during redirect parsing.
+- Changed the no-argument greeting to report Windows, Linux, or macOS according
+  to the runtime operating system.
+
+### Changed
+
+- Migrated RunX release configuration from legacy `mirror.config.toml` to
+  `mirror.yaml` while preserving package, commit, tag, push, and changelog
+  behavior.
+
+## 0.5.1 - 2026-07-19
+
+### Fixed
+
+- Enforced LF line endings for Bash scripts so Windows checkouts preserve
+  portable installer syntax.
+- Gave the detached agent-maintenance integration test an explicit
+  platform-appropriate timeout so slower Windows CI runners validate the full
+  workflow without changing runtime behavior.
+
+## 0.5.0 - 2026-07-19
+
+### Added
+
+- Added silent detached maintenance that keeps both global `guiho-s-runx`
+  skill installations current and reconciles one nearest managed `AGENTS.md`
+  block without changing foreground output or exit behavior.
+- Added explicit regression coverage for every upgrade recovery outcome,
+  executable stable/prerelease installer verification, and the Unicode
+  description-aligned command tree.
+
+### Changed
+
+- `runx upgrade list` now returns the complete published catalog, including
+  labeled prereleases, unless pagination is explicitly requested.
+- The Linux/macOS installer and generated recovery commands now use Bash with
+  `set -euo pipefail`; canonical documentation no longer invokes `sh`.
+- Release delivery now validates the exact twelve native binaries and two
+  Markdown agent assets and uses only the matching changelog version section
+  for GitHub Release notes.
+
+### Fixed
+
+- Fixed `runx upgrade list` and `runx upgrade check` so Citty does not execute
+  the parent upgrade action after the selected leaf or append a second JSON
+  document.
+- Fixed automatic agent-resource updates to use idempotent atomic writes,
+  preserve user-authored instructions, migrate legacy markers, and remain safe
+  under concurrent invocations.
+
 ## 0.4.1 - 2026-07-18
 
 ### Fixed

package/DOCS.md

@@ -27,9 +27,11 @@ before Bun is installed.
 No arguments prints exactly:
 
 ```text
-Hello Windows - runx v<version>
+Hello <Windows|Linux|macOS> - runx v<version>
 ```
 
+The platform label matches the runtime operating system.
+
 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:
@@ -99,6 +101,14 @@ Skill install, update, and uninstall default to global scope and target both:
 
 Use `--local` for the corresponding project-local paths.
 
+Ordinary RunX commands schedule a hidden detached worker that compares the
+bundled skill with both global copies and rewrites only missing or stale
+targets. The worker finds the nearest existing `AGENTS.md` from effective
+`--cwd`; when none exists in an ancestor, it creates `AGENTS.md` at effective
+cwd. Reconciliation is atomic, migrates legacy RunX markers, preserves content
+outside managed markers, and is silent when no change is required. Worker
+failures never change foreground output or exit status.
+
 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:
@@ -114,8 +124,10 @@ names; `agent prompt show <id>` prints only the raw prompt.
 ## Upgrade And Installation
 
 `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`.
+`--format`. x64 defaults to `baseline`. `upgrade list` returns the complete
+published catalog, including labeled prereleases, by default. Positive
+`--page` and `--per-page` values request an explicit view; `--pre-releases` is
+accepted but is unnecessary because prereleases are never hidden.
 
 Replacement is transactional: download, native-format validation, backup,
 replacement, version verification, rollback on failure, agent-skill refresh,
@@ -150,6 +162,16 @@ runx-windows-arm64.exe
 runx-windows-x64.exe
 runx-windows-x64-baseline.exe
 runx-windows-x64-modern.exe
-guiho-s-runx
-guiho-i-runx
+guiho-s-runx.md
+guiho-i-runx.md
 ```
+
+The Markdown suffix is part of the public GitHub Release filename contract.
+Installers retain the standard installed skill filename `SKILL.md` and use the
+instruction asset contents when reconciling managed instruction blocks. Before
+either write, installers reject empty, executable, binary, invalid UTF-8, or
+misidentified Markdown payloads.
+
+Release descriptions contain only the matching `## <version> - <date>`
+changelog section. The publish workflow fails closed when that exact section is
+missing and refreshes the notes when rerunning an existing release.

package/README.md

@@ -32,13 +32,18 @@ irm https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.ps1 | iex
 POSIX:
 
 ```sh
-curl --proto '=https' --tlsv1.2 -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 | bash
 ```
 
 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.
 
+After installation, ordinary RunX invocations schedule a silent background
+maintenance worker. It repairs missing or stale global skill copies and keeps
+one compact RunX block in the nearest `AGENTS.md` without delaying or changing
+the requested command's output.
+
 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.

package/devops/build-binaries.ts

@@ -31,7 +31,7 @@ const binaryTargets: readonly BinaryTarget[] = [
   { bunTarget: 'bun-windows-x64-modern', assetName: 'runx-windows-x64-modern.exe' },
 ]
 
-const agentAssetNames = ['guiho-s-runx', 'guiho-i-runx'] as const
+const agentAssetNames = ['guiho-s-runx.md', 'guiho-i-runx.md'] as const
 const expectedReleaseAssetNames = [...binaryTargets.map((target) => target.assetName), ...agentAssetNames]
 
 if (expectedReleaseAssetNames.length !== 14 || new Set(expectedReleaseAssetNames).size !== 14) {
@@ -69,8 +69,8 @@ if (import.meta.main) {
     process.stdout.write(`built: ${target.assetName}\n`)
   }
 
-  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')))
+  await Bun.write(joinPath(bin, 'guiho-s-runx.md'), Bun.file(joinPath(root, 'skills', 'guiho-s-runx', 'SKILL.md')))
+  await Bun.write(joinPath(bin, 'guiho-i-runx.md'), Bun.file(joinPath(root, 'prompts', 'guiho-i-runx.md')))
 
   const observed = [...new Bun.Glob('*').scanSync({ cwd: bin, onlyFiles: true })].sort()
   const expected = [...expectedReleaseAssetNames].sort()

package/devops/devops.xdocs.md

@@ -4,11 +4,13 @@ description: Native release-asset compilation and direct RunX installer scripts.
 parent: runx
 children: []
 files:
-  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.
+  build-binaries.ts: Cross-compiles twelve RFC-named native binaries and adds the two exact .md agent assets.
+  extract-release-notes.ts: Extracts one exact version section from CHANGELOG.md and fails closed when the heading or notes are missing.
+  extract-release-notes.spec.ts: Verifies exact heading boundaries and exclusion of frontmatter and other release sections.
+  verify-release-assets.ts: Fails on missing, duplicate, extra, legacy, empty, binary, or misidentified release assets.
+  installers.spec.ts: Verifies latest-alias and exact-tag URLs, installer progress, resources, executable version matching, Markdown rejection, 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.
+  install.sh: Bash installer for Linux or Darwin with stable latest-download resolution, exact tagged releases, progress, validation, PATH, dual skills, instructions, verification, and rollback.
 documents: {}
 tags:
   - devops
@@ -24,5 +26,6 @@ flags: []
 status: stable
 ---
 
-These scripts build and verify the exact fourteen-asset release and support
-direct installation without npm or Bun.
+These scripts build and verify the exact fourteen-asset release, validate the
+downloaded Markdown resource contract, create exact version-only GitHub Release
+notes, and support direct installation without npm or Bun.

package/devops/extract-release-notes.spec.ts

@@ -0,0 +1,54 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import { describe, expect, test } from 'bun:test'
+import { extractReleaseNotes } from './extract-release-notes.js'
+
+describe('extractReleaseNotes', () => {
+  test('extracts only the exact unbracketed version section', () => {
+    const changelog = `---
+name: Example
+---
+
+# Changelog
+
+## 0.4.10 - 2026-07-20
+
+### Fixed
+
+- Newer patch.
+
+## 0.4.1 - 2026-07-18
+
+### Fixed
+
+- Requested patch.
+
+## 0.4.0 - 2026-07-18
+
+### Added
+
+- Older release.
+`
+
+    expect(extractReleaseNotes(changelog, '0.4.1')).toBe(`## 0.4.1 - 2026-07-18
+
+### Fixed
+
+- Requested patch.
+`)
+  })
+
+  test('fails closed when the exact version heading is absent', () => {
+    expect(() => extractReleaseNotes('## 0.4.1 - 2026-07-18\n\n- Fixed.\n', '0.4.2')).toThrow(
+      'Expected exactly one changelog heading for version 0.4.2.',
+    )
+  })
+
+  test('rejects an empty version section', () => {
+    expect(() => extractReleaseNotes('## 0.4.2 - 2026-07-19\n## 0.4.1 - 2026-07-18\n\n- Older.\n', '0.4.2')).toThrow(
+      'Changelog section for version 0.4.2 has no release notes.',
+    )
+  })
+})

package/devops/extract-release-notes.ts

@@ -0,0 +1,40 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+export {
+  extractReleaseNotes,
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function extractReleaseNotes(changelog: string, version: string): string {
+  const normalized = changelog.replace(/\r\n/g, '\n')
+  const heading = new RegExp(`^## ${escapeRegExp(version)} - .+$`, 'gm')
+  const matches = [...normalized.matchAll(heading)]
+  if (matches.length !== 1 || matches[0]?.index === undefined) {
+    throw new Error(`Expected exactly one changelog heading for version ${version}.`)
+  }
+
+  const start = matches[0].index
+  const nextHeading = normalized.indexOf('\n## ', start + matches[0][0].length)
+  const section = normalized.slice(start, nextHeading === -1 ? normalized.length : nextHeading).trim()
+  if (!section.includes('\n')) {
+    throw new Error(`Changelog section for version ${version} has no release notes.`)
+  }
+
+  return `${section}\n`
+}
+
+if (import.meta.main) {
+  const [version, outputPath] = Bun.argv.slice(2)
+  if (!version || !outputPath) {
+    throw new Error('Usage: bun run devops/extract-release-notes.ts <version> <output-path>')
+  }
+
+  const changelog = await Bun.file(new URL('../CHANGELOG.md', import.meta.url)).text()
+  await Bun.write(outputPath, extractReleaseNotes(changelog, version))
+  process.stdout.write(`wrote release notes for ${version}: ${outputPath}\n`)
+}

package/devops/install.ps1

@@ -78,6 +78,25 @@ function Test-NativeBinary {
   finally { $stream.Dispose() }
 }
 
+function Test-MarkdownAsset {
+  param([string]$Path, [string]$ExpectedName)
+  $bytes = [System.IO.File]::ReadAllBytes($Path)
+  if ($bytes.Length -eq 0) { throw "Downloaded Markdown asset is empty: $Path" }
+  if ($bytes.Length -ge 2 -and $bytes[0] -eq 0x4D -and $bytes[1] -eq 0x5A) {
+    throw "Downloaded Markdown asset has a Windows executable header: $Path"
+  }
+  if ($bytes -contains 0) { throw "Downloaded Markdown asset contains binary NUL bytes: $Path" }
+  try {
+    $text = ([System.Text.UTF8Encoding]::new($false, $true)).GetString($bytes).Replace("`r`n", "`n")
+  } catch {
+    throw "Downloaded Markdown asset is not valid UTF-8 text: $Path"
+  }
+  if (-not $text.StartsWith("---`n")) { throw "Downloaded Markdown asset does not begin with YAML frontmatter: $Path" }
+  if ($text -notmatch "(?m)^name:\s*$([Regex]::Escape($ExpectedName))\s*$") {
+    throw "Downloaded Markdown asset identity does not match $ExpectedName`: $Path"
+  }
+}
+
 function Test-InstalledVersion {
   param([string]$Path, [string]$ExpectedVersion)
   $startInfo = New-Object System.Diagnostics.ProcessStartInfo
@@ -156,6 +175,8 @@ function Test-Shadowing {
   }
 }
 
+if ($env:RUNX_INSTALLER_SOURCE_ONLY -eq '1') { return }
+
 $detectedArch = if ($Arch) { $Arch } else { switch ($env:PROCESSOR_ARCHITECTURE) { 'AMD64' { 'x64' } 'ARM64' { 'arm64' } default { throw "Unsupported architecture: $env:PROCESSOR_ARCHITECTURE" } } }
 if ($detectedArch -notin @('x64', 'arm64')) { throw "Invalid architecture: $detectedArch" }
 if (-not [Environment]::Is64BitOperatingSystem) { throw 'Unsupported platform: Windows 32-bit is not supported.' }
@@ -208,13 +229,15 @@ try {
   if (-not $downloadedPath) { throw "No compatible RunX $targetVersion binary found at https://github.com/$Repo/releases" }
   Write-Host 'Replacing...'
   Install-Transactional -DownloadedPath $downloadedPath -Destination $destination -ExpectedVersion $targetVersion
-  $skillAsset = Join-Path $temporaryDirectory 'guiho-s-runx'
-  $promptAsset = Join-Path $temporaryDirectory 'guiho-i-runx'
+  $skillAsset = Join-Path $temporaryDirectory 'guiho-s-runx.md'
+  $promptAsset = Join-Path $temporaryDirectory 'guiho-i-runx.md'
   $assetBase = if ($DownloadBaseUrl) { "$DownloadBaseUrl/$encodedTag" } else { "https://github.com/$Repo/releases/download/$encodedTag" }
-  Write-Host "Downloading skill asset: $assetBase/guiho-s-runx"
-  Invoke-WebRequest -Uri "$assetBase/guiho-s-runx" -OutFile $skillAsset -UseBasicParsing
-  Write-Host "Downloading instruction asset: $assetBase/guiho-i-runx"
-  Invoke-WebRequest -Uri "$assetBase/guiho-i-runx" -OutFile $promptAsset -UseBasicParsing
+  Write-Host "Downloading skill asset: $assetBase/guiho-s-runx.md"
+  Invoke-WebRequest -Uri "$assetBase/guiho-s-runx.md" -OutFile $skillAsset -UseBasicParsing
+  Test-MarkdownAsset -Path $skillAsset -ExpectedName 'guiho-s-runx'
+  Write-Host "Downloading instruction asset: $assetBase/guiho-i-runx.md"
+  Invoke-WebRequest -Uri "$assetBase/guiho-i-runx.md" -OutFile $promptAsset -UseBasicParsing
+  Test-MarkdownAsset -Path $promptAsset -ExpectedName 'guiho-i-runx'
   foreach ($skillRoot in @((Join-Path $HOME '.agents\skills\guiho-s-runx'), (Join-Path $HOME '.claude\skills\guiho-s-runx'))) {
     New-Item -ItemType Directory -Force -Path $skillRoot | Out-Null
     Copy-Item -LiteralPath $skillAsset -Destination (Join-Path $skillRoot 'SKILL.md') -Force

package/devops/install.sh

@@ -1,5 +1,5 @@
-#!/usr/bin/env sh
-set -eu
+#!/usr/bin/env bash
+set -euo pipefail
 
 REPO="${RUNX_REPO:-CGuiho/runx}"
 VERSION="${RUNX_VERSION:-latest}"
@@ -10,6 +10,7 @@ VARIANT_OVERRIDE=""
 OS=""
 ARCH=""
 TARGET_VERSION=""
+INSTALLED_VERSION=""
 TMP=""
 
 cleanup() { [ -z "$TMP" ] || rm -rf -- "$TMP"; }
@@ -76,11 +77,21 @@ normalize_version() {
 
 resolve_target_version() {
   if [ "$VERSION" != latest ]; then normalize_version "$VERSION"; return; fi
-  printf 'Resolving latest stable RunX release...\n' >&2
-  effective=$(curl --fail --location --silent --show-error --proto '=https' --tlsv1.2 --output /dev/null --write-out '%{url_effective}' "https://github.com/${REPO}/releases/latest")
-  tag=${effective##*/}
-  tag=$(printf '%s' "$tag" | sed 's/%40/@/g; s/%2[Ff]/\//g')
-  normalize_version "$tag"
+  printf 'latest\n'
+}
+
+build_asset_url() {
+  asset=$1
+  if [ -n "$DOWNLOAD_BASE_URL" ]; then
+    printf '%s/%s\n' "${DOWNLOAD_BASE_URL%/}" "$asset"
+    return
+  fi
+  if [ "$TARGET_VERSION" = latest ]; then
+    printf 'https://github.com/%s/releases/latest/download/%s\n' "$REPO" "$asset"
+    return
+  fi
+  encoded_tag="%40guiho%2Frunx%40${TARGET_VERSION}"
+  printf 'https://github.com/%s/releases/download/%s/%s\n' "$REPO" "$encoded_tag" "$asset"
 }
 
 build_candidates() {
@@ -106,6 +117,25 @@ verify_native_binary() {
   esac
 }
 
+verify_markdown_asset() {
+  path=$1
+  expected_name=$2
+  [ -s "$path" ] || fail "downloaded Markdown asset is empty: $path"
+  magic=$(od -An -tx1 -N2 "$path" 2>/dev/null | tr -d ' \n')
+  [ "$magic" != 4d5a ] || fail "downloaded Markdown asset has a Windows executable header: $path"
+  if od -An -tx1 "$path" 2>/dev/null | grep -Eq '(^|[[:space:]])00([[:space:]]|$)'; then
+    fail "downloaded Markdown asset contains binary NUL bytes: $path"
+  fi
+  iconv -f UTF-8 -t UTF-8 "$path" >/dev/null 2>&1 || fail "downloaded Markdown asset is not valid UTF-8 text: $path"
+  first_line=$(sed -n '1{s/\r$//;p;}' "$path")
+  [ "$first_line" = '---' ] || fail "downloaded Markdown asset does not begin with YAML frontmatter: $path"
+  awk -v expected="$expected_name" '
+    { sub(/\r$/, "") }
+    $0 == "name: " expected { found=1 }
+    END { exit(found ? 0 : 1) }
+  ' "$path" || fail "downloaded Markdown asset identity does not match $expected_name: $path"
+}
+
 verify_installed_version() {
   verify_output=$(mktemp "${TMPDIR:-/tmp}/runx-version.XXXXXX") || return 1
   "$1" --version >"$verify_output" 2>&1 &
@@ -129,16 +159,21 @@ verify_installed_version() {
   fi
   actual=$(cat "$verify_output")
   rm -f -- "$verify_output"
-  [ "$actual" = "$TARGET_VERSION" ] || { printf 'error: installed RunX reported %s; expected %s\n' "${actual:-<empty>}" "$TARGET_VERSION" >&2; return 1; }
+  normalized=$(normalize_version "$actual") || return 1
+  if [ "$TARGET_VERSION" != latest ] && [ "$normalized" != "$TARGET_VERSION" ]; then
+    printf 'error: installed RunX reported %s; expected %s\n' "${actual:-<empty>}" "$TARGET_VERSION" >&2
+    return 1
+  fi
+  INSTALLED_VERSION=$normalized
 }
 
 ensure_path() {
   PATH="$INSTALL_DIR:$PATH"; export PATH
   profile="$HOME/.profile"
-  case "${SHELL##*/}" in zsh) profile="$HOME/.zshrc" ;; bash) profile="$HOME/.bashrc" ;; fish) profile="$HOME/.config/fish/config.fish" ;; esac
+  case "${SHELL:-bash}" in */zsh|zsh) profile="$HOME/.zshrc" ;; */bash|bash) profile="$HOME/.bashrc" ;; */fish|fish) profile="$HOME/.config/fish/config.fish" ;; esac
   mkdir -p -- "$(dirname "$profile")"
   if ! grep -Fq "$INSTALL_DIR" "$profile" 2>/dev/null; then
-    if [ "${SHELL##*/}" = fish ]; then printf '\n# Added by runx installer\nfish_add_path %s\n' "$INSTALL_DIR" >>"$profile"
+    if [ "${SHELL:-bash}" = fish ] || [ "${SHELL:-bash}" = */fish ]; then printf '\n# Added by runx installer\nfish_add_path %s\n' "$INSTALL_DIR" >>"$profile"
     else printf '\n# Added by runx installer\nexport PATH=%s:$PATH\n' "$INSTALL_DIR" >>"$profile"; fi
   fi
 }
@@ -182,16 +217,17 @@ install_transactional() {
 }
 
 install_agent_assets() {
-  tag_base=${DOWNLOAD_BASE_URL:-"https://github.com/${REPO}/releases/download"}
-  skill_url="${tag_base%/}/${encoded_tag}/guiho-s-runx"
-  prompt_url="${tag_base%/}/${encoded_tag}/guiho-i-runx"
+  skill_url=$(build_asset_url guiho-s-runx.md)
+  prompt_url=$(build_asset_url guiho-i-runx.md)
   printf 'Downloading skill asset: %s\n' "$skill_url"
-  download_asset "$skill_url" "$TMP/guiho-s-runx" || fail 'could not download guiho-s-runx'
+  download_asset "$skill_url" "$TMP/guiho-s-runx.md" || fail 'could not download guiho-s-runx.md'
+  verify_markdown_asset "$TMP/guiho-s-runx.md" 'guiho-s-runx'
   printf 'Downloading instruction asset: %s\n' "$prompt_url"
-  download_asset "$prompt_url" "$TMP/guiho-i-runx" || fail 'could not download guiho-i-runx'
+  download_asset "$prompt_url" "$TMP/guiho-i-runx.md" || fail 'could not download guiho-i-runx.md'
+  verify_markdown_asset "$TMP/guiho-i-runx.md" 'guiho-i-runx'
   for skill_root in "$HOME/.agents/skills/guiho-s-runx" "$HOME/.claude/skills/guiho-s-runx"; do
     mkdir -p -- "$skill_root"
-    install -m 0644 "$TMP/guiho-s-runx" "$skill_root/SKILL.md"
+    install -m 0644 "$TMP/guiho-s-runx.md" "$skill_root/SKILL.md"
     printf 'Installed skill: %s\n' "$skill_root/SKILL.md"
   done
   targets=""
@@ -214,7 +250,7 @@ install_agent_assets() {
       cat "$clean_file"
       [ ! -s "$clean_file" ] || printf '\n'
       printf '<!-- BEGIN RUNX — DO NOT EDIT THIS SECTION -->\n'
-      cat "$TMP/guiho-i-runx"
+      cat "$TMP/guiho-i-runx.md"
       printf '\n<!-- END RUNX -->\n'
     } >"$instruction_file"
   done
@@ -222,20 +258,19 @@ install_agent_assets() {
 
 main() {
   parse_args "$@"
-  for command in awk cat curl date dirname grep head install mktemp mv od rm sed tr uname; do require_command "$command"; done
+  for command in awk cat curl date dirname grep head iconv install mktemp mv od rm sed tr uname; do require_command "$command"; done
   OS=$(detect_os); ARCH=$(detect_arch); TARGET_VERSION=$(resolve_target_version)
   TMP=$(mktemp -d "${TMPDIR:-/tmp}/runx-install.XXXXXX")
   mkdir -p -- "$INSTALL_DIR"
   destination="$INSTALL_DIR/runx"
-  encoded_tag="%40guiho%2Frunx%40${TARGET_VERSION}"
   downloaded=""
   first_asset=$(build_candidates | head -n 1)
-  source_url="${DOWNLOAD_BASE_URL:-https://github.com/${REPO}/releases/download}/${encoded_tag}/${first_asset}"
+  source_url=$(build_asset_url "$first_asset")
   printf 'Initiating GUIHO CLI Upgrade / Installation Sequence...\n'
   printf 'Target Version: v%s\nArchitecture:   %s\nVariant:        %s\nSource URL:     %s\n' "$TARGET_VERSION" "$ARCH" "${VARIANT_OVERRIDE:-baseline}" "$source_url"
   build_candidates | while IFS= read -r asset; do printf '%s\n' "$asset"; done >"$TMP/candidates"
   while IFS= read -r asset; do
-    if [ -n "$DOWNLOAD_BASE_URL" ]; then url="${DOWNLOAD_BASE_URL%/}/${encoded_tag}/${asset}"; else url="https://github.com/${REPO}/releases/download/${encoded_tag}/${asset}"; fi
+    url=$(build_asset_url "$asset")
     candidate="$TMP/$asset"
     printf 'Downloading %s\n' "$url"
     if download_asset "$url" "$candidate"; then :; else
@@ -253,7 +288,11 @@ main() {
   install_agent_assets
   [ "${RUNX_SKIP_PATH_UPDATE:-0}" = 1 ] || ensure_path
   printf 'Final verification: %s --version\n' "$destination"
-  printf 'Installed and verified RunX %s at %s\n' "$TARGET_VERSION" "$destination"
+  printf 'Installed and verified RunX %s at %s\n' "$INSTALLED_VERSION" "$destination"
 }
 
+if [ "${RUNX_INSTALLER_SOURCE_ONLY:-0}" = 1 ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
 main "$@"