@guiho/runx 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -15,6 +15,22 @@ 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

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:

package/devops/devops.xdocs.md

@@ -8,9 +8,9 @@ files:
   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 installer progress, resources, exact stable/prerelease normalization, executable version matching, Markdown rejection, and no POSIX Bun dependency.
+  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: Bash installer for Linux or Darwin with strict mode, 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

package/devops/install.sh

@@ -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() {
@@ -148,7 +159,12 @@ 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() {
@@ -201,9 +217,8 @@ 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.md"
-  prompt_url="${tag_base%/}/${encoded_tag}/guiho-i-runx.md"
+  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.md" || fail 'could not download guiho-s-runx.md'
   verify_markdown_asset "$TMP/guiho-s-runx.md" 'guiho-s-runx'
@@ -248,15 +263,14 @@ main() {
   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
@@ -274,7 +288,7 @@ 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

package/devops/installers.spec.ts

@@ -24,11 +24,13 @@ describe('RunX direct installers', () => {
     expect(script).toContain('not valid UTF-8 text')
   })
 
-  test('Bash installer selects Darwin assets and has no runtime Bun dependency', async () => {
+  test('Bash installer selects Darwin assets and resolves latest assets without parsing redirect tags', async () => {
     const script = await Bun.file(new URL('./install.sh', import.meta.url)).text()
     expect(script).toStartWith('#!/usr/bin/env bash\nset -euo pipefail')
     expect(script).toContain("Darwin) printf 'darwin")
     expect(script).toContain('--progress-bar')
+    expect(script).toContain('/releases/latest/download/')
+    expect(script).not.toContain("write-out '%{url_effective}'")
     expect(script).toContain('guiho-s-runx.md')
     expect(script).toContain('guiho-i-runx.md')
     expect(script).toContain('.agents/skills/guiho-s-runx')
@@ -68,6 +70,14 @@ describe('RunX direct installers', () => {
         'prerelease=$(normalize_version @guiho/runx@1.3.0-alpha.2)',
         'test "$stable" = 1.2.3',
         'test "$prerelease" = 1.3.0-alpha.2',
+        'VERSION=latest',
+        'TARGET_VERSION=$(resolve_target_version)',
+        'latest=$(build_asset_url runx-linux-x64-baseline)',
+        'test "$latest" = https://github.com/CGuiho/runx/releases/latest/download/runx-linux-x64-baseline',
+        'VERSION=@guiho/runx@1.3.0-alpha.2',
+        'TARGET_VERSION=$(resolve_target_version)',
+        'exact=$(build_asset_url runx-linux-x64-baseline)',
+        'test "$exact" = https://github.com/CGuiho/runx/releases/download/%40guiho%2Frunx%401.3.0-alpha.2/runx-linux-x64-baseline',
         'TARGET_VERSION=$(bun --version)',
         'verify_installed_version "$(command -v bun)"',
       ].join('; '),

package/docs/plans/linux-installer-latest-release.md

@@ -0,0 +1,43 @@
+---
+name: Latest RunX Bash Installer Plan
+purpose: Sequence the GitHub issue 20 installer fix from URL resolution through public release verification.
+description: Replaces redirect-tag parsing with latest-download aliases while preserving exact releases and transactional installation.
+created: 2026-07-20
+flags:
+  - approved
+  - implemented
+owner: runx-plans
+tags:
+  - installer
+  - linux
+keywords:
+  - issue 20
+  - latest download
+  - regression test
+---
+
+# Latest RunX Bash Installer Plan
+
+## Unit 1: Replace Fragile Latest-Tag Discovery
+
+1. Keep exact-version normalization for explicit stable and prerelease inputs.
+2. Route `latest` binary and agent assets through
+   `releases/latest/download/<asset>`, matching the proven XDocs installer.
+3. Verify the installed executable's semantic version and report the resolved
+   version after installation.
+
+## Unit 2: Prove The Regression
+
+1. Assert that latest URLs use the stable GitHub download alias.
+2. Assert that redirect `url_effective` parsing is absent.
+3. Preserve exact encoded-tag URL coverage, Bash syntax, piping, native payload
+   validation, agent-asset validation, and executable version checks.
+4. Run focused tests, then the full RunX typecheck, test, build, binary, asset,
+   and XDocs gates.
+
+## Unit 3: Release And Close
+
+1. Prepare a Mirror patch release with version-only changelog notes.
+2. Publish exactly fourteen assets.
+3. Execute the public Linux installer path against the release.
+4. Post evidence to issue 20 and close it only after the public install passes.

package/docs/plans/plans.xdocs.md

@@ -8,8 +8,10 @@ files:
   automatic-agent-maintenance.md: Implements non-blocking automatic global skill and nearest AGENTS.md reconciliation for issue 11.
   citty-cli-migration.md: Executes the full Citty command-tree migration, compatibility validation, protected delivery, and patch release.
   interactive-init-manifest.md: Sequences the SemVer manifest, public group, scripts directory, and interactive initializer delivery.
+  linux-installer-latest-release.md: Replaces redirect-tag parsing with latest-download aliases, regression tests the URLs, and sequences public issue verification.
   mirror-automatic-push.md: Enables automatic Mirror release pushes with a synchronized protected-main safety gate.
   npm-trusted-publishing-release.md: Sequences workflow implementation, protected delivery, Mirror patching, and public trusted-publishing verification.
+  platform-aware-startup-greeting.md: Centralizes Windows, Linux, and macOS greeting rendering, deterministic tests, documentation, release, and issue closure.
   rfc-0034-cli-compliance-migration.md: Executes the breaking full RFC 0034 migration across runtime, configuration, help, agents, upgrades, distribution, release assets, documentation, and validation.
   windows-self-upgrade.md: Sequences synchronous Windows replacement, rollback coverage, validation, issue closure, and patch delivery.
   upgrade-reliability-implementation.md: Sequences release discovery, streamed progress, transactional replacement, recovery, installers, and validation.
@@ -18,8 +20,10 @@ documents:
   automatic-agent-maintenance.md: Approved automatic agent-maintenance implementation plan.
   citty-cli-migration.md: Active plan for replacing handwritten CLI parsing and routing with Citty and delivering its patch release.
   interactive-init-manifest.md: Approved implementation plan for the RunX interactive init manifest feature.
+  linux-installer-latest-release.md: Approved implementation plan for GitHub issue 20.
   mirror-automatic-push.md: Approved plan for configuring, validating, and merging Mirror push=true without applying another release.
   npm-trusted-publishing-release.md: Approved executable plan for the RunX 0.2.1 trusted-publishing release trial.
+  platform-aware-startup-greeting.md: Approved implementation plan for GitHub issue 21.
   rfc-0034-cli-compliance-migration.md: Approved step-by-step plan for making RunX fully compliant with the GUIHO CLI engineer contract.
   windows-self-upgrade.md: Approved executable plan for fixing Windows native self-upgrade and delivering its patch.
   upgrade-reliability-implementation.md: Approved executable plan for GitHub issues 12 and 13.

package/docs/plans/platform-aware-startup-greeting.md

@@ -0,0 +1,43 @@
+---
+name: Platform-Aware RunX Greeting Plan
+purpose: Sequence the GitHub issue 21 greeting fix from pure rendering through released Linux verification.
+description: Centralizes supported platform labels, deterministic tests, documentation, patch release, and issue closure.
+created: 2026-07-20
+flags:
+  - approved
+  - implemented
+owner: runx-plans
+tags:
+  - cli
+  - startup
+keywords:
+  - issue 21
+  - platform label
+  - regression test
+---
+
+# Platform-Aware RunX Greeting Plan
+
+## Unit 1: Centralize Greeting Rendering
+
+1. Add a pure greeting renderer to the existing Citty CLI module.
+2. Map `win32`, `linux`, and `darwin` to Windows, Linux, and macOS.
+3. Route the no-argument command through the renderer without changing cached
+   update notice ordering.
+
+## Unit 2: Prove Every Supported Platform
+
+1. Add deterministic renderer assertions for Windows, Linux, and macOS.
+2. Update child-process expectations to use the runtime platform.
+3. Run the focused CLI suite and retry only independently diagnosed timing
+   flakes.
+4. Run the full RunX validation gates.
+
+## Unit 3: Document, Release, And Close
+
+1. Replace literal-Windows startup guidance in repository instructions and CLI
+   documentation.
+2. Update the owning XDocs descriptors.
+3. Include the correction in the same Mirror patch as issue 20.
+4. Verify the released Linux binary prints `Hello Linux`, post evidence to
+   issue 21, and close it.

package/docs/reviews/implementation/implementation.xdocs.md

@@ -7,6 +7,8 @@ files:
   bash-installer-review.md: Accepts the canonical Bash shebang, strict mode, recovery invocation, and executable shell tests for GitHub issue 15.
   citty-cli-migration-review.md: Reviews the implemented Citty command tree, compatibility adapter, tests, documentation, packaging, and release readiness.
   interactive-init-manifest-review.md: Reviews the implemented RunX initializer, strict manifest contract, tests, documentation, and delivery readiness.
+  linux-installer-latest-release-review.md: Accepts latest-download alias resolution, exact-version preservation, transactional safeguards, tests, and GitHub issue 20 release readiness.
+  platform-aware-startup-greeting-review.md: Accepts centralized Windows, Linux, and macOS startup labels, deterministic tests, documentation, and GitHub issue 21 release readiness.
   windows-self-upgrade-review.md: Reviews synchronous Windows replacement, rollback, cleanup, tests, CI coverage, and release readiness.
   rfc-0034-cli-compliance-migration-review.md: Accepts the RFC 0034 migration after independent upgrade-routing, cached-notice, prompt-output, asset, and release-readiness corrections.
   automatic-agent-maintenance-review.md: Accepts atomic global skill and nearest AGENTS.md reconciliation, detached failure isolation, command boundaries, and regression evidence.
@@ -17,6 +19,8 @@ documents:
   bash-installer-review.md: Accepted implementation review for the RunX Bash installer.
   citty-cli-migration-review.md: Accepted implementation review for the full Citty CLI migration.
   interactive-init-manifest-review.md: Accepted implementation review for the RunX interactive init manifest feature.
+  linux-installer-latest-release-review.md: Accepted implementation review for GitHub issue 20.
+  platform-aware-startup-greeting-review.md: Accepted implementation review for GitHub issue 21.
   windows-self-upgrade-review.md: Accepted implementation review for the Windows native self-upgrade fix.
   rfc-0034-cli-compliance-migration-review.md: Accepted implementation and independent correction review for RX-01 through RX-16.
   automatic-agent-maintenance-review.md: Accepted implementation review for GitHub issue 11 automatic agent maintenance.

package/docs/reviews/implementation/linux-installer-latest-release-review.md

@@ -0,0 +1,49 @@
+---
+name: Latest RunX Bash Installer Implementation Review
+purpose: Review the GitHub issue 20 installer correction against its approved plan and acceptance signals.
+description: Confirms latest-download URL resolution, exact version preservation, transactional safeguards, tests, and release readiness.
+created: 2026-07-20
+flags:
+  - accepted
+tags:
+  - review
+  - installer
+keywords:
+  - issue 20
+  - latest release
+  - install.sh
+owner: runx-implementation-reviews
+---
+
+# Latest RunX Bash Installer Implementation Review
+
+## Verdict
+
+Accepted for patch release.
+
+## Findings
+
+No blocking findings.
+
+## Acceptance Criteria Check
+
+- Latest binaries and Markdown assets use
+  `releases/latest/download/<asset>`.
+- Explicit stable and prerelease versions retain encoded RunX tag URLs.
+- Redirect `url_effective` parsing was removed.
+- Transactional replacement, rollback, native validation, Markdown validation,
+  dual skill installation, instruction reconciliation, PATH setup, and final
+  executable verification remain present.
+- Focused and full regression suites pass.
+
+## Residual Risk
+
+The Windows host cannot execute the Linux binary locally. Public Linux
+installation and greeting behavior must be verified after the patch assets are
+published.
+
+## References
+
+- [Task specification](../../todo/linux-installer-latest-release.md)
+- [Implementation plan](../../plans/linux-installer-latest-release.md)
+- [GitHub issue 20](https://github.com/CGuiho/runx/issues/20)

package/docs/reviews/implementation/platform-aware-startup-greeting-review.md

@@ -0,0 +1,51 @@
+---
+name: Platform-Aware RunX Greeting Implementation Review
+purpose: Review the GitHub issue 21 greeting correction against its approved plan and acceptance signals.
+description: Confirms centralized platform labels, deterministic coverage, update-notice ordering, and release readiness.
+created: 2026-07-20
+flags:
+  - accepted
+tags:
+  - review
+  - cli
+keywords:
+  - issue 21
+  - platform greeting
+  - startup
+owner: runx-implementation-reviews
+---
+
+# Platform-Aware RunX Greeting Implementation Review
+
+## Verdict
+
+Accepted for patch release.
+
+## Findings
+
+No blocking findings.
+
+## Acceptance Criteria Check
+
+- One pure renderer maps Windows, Linux, and macOS deterministically.
+- The no-argument Citty route uses the renderer.
+- Cached update notices remain before the greeting.
+- Version, help, routing, diagnostics, and exit behavior are unchanged.
+- Tests assert all three supported operating-system labels and runtime
+  child-process behavior.
+- Repository instructions and CLI documentation describe the new contract.
+
+## Deviation
+
+The historical RFC 0034 literal-Windows banner is intentionally superseded by
+the developer-approved platform-aware contract.
+
+## Residual Risk
+
+The released Linux binary must be smoke-tested after publication.
+
+## References
+
+- [Task specification](../../todo/platform-aware-startup-greeting.md)
+- [Implementation plan](../../plans/platform-aware-startup-greeting.md)
+- [GitHub issue 21](https://github.com/CGuiho/runx/issues/21)

package/docs/todo/linux-installer-latest-release.md

@@ -0,0 +1,47 @@
+---
+name: Resolve The Latest RunX Bash Install
+purpose: Track the Linux and macOS latest-release installer correction requested by GitHub issue 20.
+description: Defines stable latest-download resolution, exact version behavior, installer safeguards, regression coverage, and public verification.
+created: 2026-07-20
+flags:
+  - testing
+owner: runx-todo
+tags:
+  - installer
+  - linux
+  - github
+keywords:
+  - issue 20
+  - latest release
+  - install.sh
+---
+
+# Resolve The Latest RunX Bash Install
+
+## Outcome
+
+The Bash installer installs the latest stable RunX release on Linux and macOS
+without parsing a redirected release tag whose package name contains a slash.
+
+## External Tracker
+
+- [CGuiho/runx#20](https://github.com/CGuiho/runx/issues/20)
+
+## Acceptance Signals
+
+- `latest` assets resolve through GitHub's stable
+  `releases/latest/download/<asset>` endpoint.
+- Exact stable and prerelease versions continue to use encoded RunX tags.
+- Binary, skill, and instruction assets use the same release selector.
+- Bash syntax, piped startup, exact-version, and executable-verification tests
+  pass.
+- The public installer succeeds against the released patch before issue
+  closure.
+
+## Watch-Outs
+
+- Do not recover a latest tag from the final redirect URL segment. The RunX tag
+  contains `@guiho/runx@...`; the slash can become a path separator and discard
+  the package scope.
+- Preserve transactional replacement, Markdown validation, PATH setup, dual
+  skill installation, and final executable verification.

package/docs/todo/platform-aware-startup-greeting.md

@@ -0,0 +1,41 @@
+---
+name: Use The Runtime Platform In The RunX Greeting
+purpose: Track the platform-aware no-argument greeting requested by GitHub issue 21.
+description: Defines Windows, Linux, and macOS greeting labels, output ordering, regression coverage, and public verification.
+created: 2026-07-20
+flags:
+  - testing
+owner: runx-todo
+tags:
+  - cli
+  - startup
+keywords:
+  - issue 21
+  - operating system
+  - greeting
+---
+
+# Use The Runtime Platform In The RunX Greeting
+
+## Outcome
+
+`runx` with no arguments names the operating system it is actually running on:
+Windows, Linux, or macOS.
+
+## External Tracker
+
+- [CGuiho/runx#21](https://github.com/CGuiho/runx/issues/21)
+
+## Acceptance Signals
+
+- Windows prints `Hello Windows - runx v<version>`.
+- Linux prints `Hello Linux - runx v<version>`.
+- macOS prints `Hello macOS - runx v<version>`.
+- Cached update notices remain before the greeting.
+- Help, version, command routing, output channels, and exit codes are unchanged.
+- Deterministic tests cover all three supported platform labels.
+
+## Contract Note
+
+This issue intentionally replaces the historical RFC 0034 literal-Windows
+banner. The developer explicitly approved the platform-aware behavior.

package/docs/todo/todo.xdocs.md

@@ -5,6 +5,7 @@ parent: runx-docs
 children: []
 files:
   bash-installer.md: Completes the GitHub issue 15 Bash shebang, invocation, strict-mode, and executable test contract.
+  linux-installer-latest-release.md: Defines GitHub issue 20 latest-release alias resolution and public Bash installer acceptance.
   automatic-agent-maintenance.md: Defines issue 11 automatic agent-resource maintenance outcomes and acceptance signals.
   automatic-agent-maintenance-implementation.md: Records the delivered issue 11 reconciler, hidden worker, command boundaries, tests, and release handoff.
   protect-branches-and-tag-creation.md: Records the verified active GitHub branch and release-tag rulesets for RunX.
@@ -12,8 +13,10 @@ files:
   rfc-0034-cli-compliance-migration-implementation.md: Records the delivered RX units, implementation map, test-hang diagnosis, and independent audit corrections.
   upgrade-reliability.md: Completes GitHub issues 12 and 13 for verified replacement, complete listing, exact recovery, and direct installers.
   unicode-help-tree.md: Completes GitHub issue 17 with Unicode branches, nested guides, aligned descriptions, and legacy ASCII rejection.
+  platform-aware-startup-greeting.md: Defines GitHub issue 21 Windows, Linux, and macOS no-argument greeting behavior.
 documents:
   bash-installer.md: Completed task specification for the canonical RunX Bash installer.
+  linux-installer-latest-release.md: Task specification for reliable latest RunX Bash installation.
   automatic-agent-maintenance.md: Task specification for automatic RunX skill and AGENTS.md maintenance.
   automatic-agent-maintenance-implementation.md: Completed implementation record for automatic RunX agent maintenance.
   protect-branches-and-tag-creation.md: Completed task specification with active RunX ruleset IDs, protected patterns, and verification evidence.
@@ -21,6 +24,7 @@ documents:
   rfc-0034-cli-compliance-migration-implementation.md: Completed implementation, independent correction, and validation handoff for TODO task 1.
   upgrade-reliability.md: Completed task specification for RunX upgrade reliability.
   unicode-help-tree.md: Completed task specification for the RunX Unicode help tree.
+  platform-aware-startup-greeting.md: Task specification for the platform-aware RunX greeting.
 tags:
   - todo
 keywords:

package/docs/validation/linux-installer-latest-release.md

@@ -0,0 +1,50 @@
+---
+name: Latest RunX Bash Installer Validation
+purpose: Record verification evidence for GitHub issue 20.
+description: Captures Bash syntax, installer regression tests, full package checks, release assets, public latest-alias resolution, and remaining live-install verification.
+created: 2026-07-20
+flags:
+  - release-ready
+tags:
+  - validation
+  - installer
+keywords:
+  - issue 20
+  - latest download
+  - fourteen assets
+owner: runx-validation
+---
+
+# Latest RunX Bash Installer Validation
+
+## Summary
+
+The implementation is ready for patch release. Public installation against the
+new patch remains the final closure gate.
+
+## Commands Run
+
+| Check | Result |
+| --- | --- |
+| `bash -n devops/install.sh` | Passed |
+| `bun test devops/installers.spec.ts` | Passed: 5 tests, 39 expectations |
+| `bun run typecheck` | Passed |
+| `bun test` | Passed: 54 tests, 373 expectations |
+| `bun run build` | Passed |
+| `bun run binary` | Passed |
+| `bun run binaries` | Passed: 12 native binaries |
+| `bun run verify-assets` | Passed: exactly 14 assets |
+| Public `releases/latest/download/runx-linux-x64-baseline` headers | Passed: redirects to the current RunX release asset and returns HTTP 200 |
+| XDocs strict metadata, tree, and doctor | Passed |
+
+## Regression Evidence
+
+- The script contains the stable latest-download endpoint.
+- The script does not inspect `url_effective`.
+- Sourced Bash tests prove latest and exact encoded-tag URL shapes.
+- Existing payload, Markdown, and executable checks remain green.
+
+## Remaining Gate
+
+After publication, execute the public Bash installer on Linux, verify the
+reported version, and record the result in issue 20 before closure.

package/docs/validation/platform-aware-startup-greeting.md

@@ -0,0 +1,50 @@
+---
+name: Platform-Aware RunX Greeting Validation
+purpose: Record verification evidence for GitHub issue 21.
+description: Captures deterministic platform assertions, runtime smoke tests, full package checks, and remaining released-Linux verification.
+created: 2026-07-20
+flags:
+  - release-ready
+tags:
+  - validation
+  - cli
+keywords:
+  - issue 21
+  - Windows
+  - Linux
+  - macOS
+owner: runx-validation
+---
+
+# Platform-Aware RunX Greeting Validation
+
+## Summary
+
+The implementation is ready for patch release. The published Linux executable
+is the final platform-specific closure gate.
+
+## Commands Run
+
+| Check | Result |
+| --- | --- |
+| Focused `bun test source/cli.spec.ts` banner assertions | Passed |
+| Independently rerun background-maintenance timing test | Passed |
+| `bun run typecheck` | Passed |
+| `bun test` | Passed: 54 tests, 373 expectations |
+| `bun run build` | Passed |
+| `bun run binaries` | Passed |
+| Compiled `runx-windows-x64-baseline.exe` no arguments | Passed: `Hello Windows - runx v0.5.1` |
+| Compiled Windows `--version` | Passed: `0.5.1` |
+| XDocs strict metadata, tree, and doctor | Passed |
+
+## Deterministic Assertions
+
+- `win32` renders `Hello Windows`.
+- `linux` renders `Hello Linux`.
+- `darwin` renders `Hello macOS`.
+- Cached update output remains before the startup greeting.
+
+## Remaining Gate
+
+After publication, run the released Linux binary without arguments and record
+`Hello Linux - runx v<released-version>` in issue 21 before closure.

package/docs/validation/validation.xdocs.md

@@ -8,6 +8,8 @@ files:
   alpha-implementation-summary.md: Records the completed alpha implementation, checks, and release boundaries.
   citty-cli-migration.md: Records the complete local validation gate for the Citty command-tree migration.
   interactive-init-manifest.md: Records validation evidence for the interactive initializer and strict manifest contract.
+  linux-installer-latest-release.md: Records Bash syntax, latest and exact URL regression coverage, full tests, builds, exact assets, public alias resolution, and the issue 20 live-install gate.
+  platform-aware-startup-greeting.md: Records deterministic platform assertions, runtime smoke tests, full package checks, and the issue 21 released-Linux gate.
   windows-self-upgrade.md: Records Windows replacement, rollback, cleanup, native build, CI, and XDocs validation evidence.
   upgrade-reliability.md: Summarizes completed current-main validation for GitHub issues 12 and 13.
   rfc-0034-cli-compliance-migration.md: Records passing RFC tests, live upgrade/startup/prompt regressions, builds, bootstrap, installers, import scan, and fourteen-asset evidence.
@@ -20,6 +22,8 @@ documents:
   alpha-implementation-summary.md: Validation summary for the first RunX implementation.
   citty-cli-migration.md: Validation evidence for TypeScript, tests, native assets, npm packaging, CLI behavior, and XDocs.
   interactive-init-manifest.md: Validation evidence for the RunX interactive init manifest feature.
+  linux-installer-latest-release.md: Patch-release validation report for GitHub issue 20.
+  platform-aware-startup-greeting.md: Patch-release validation report for GitHub issue 21.
   npm-trusted-publishing-0.2.2.md: Validation evidence for the blocked 0.2.2 npm trusted-publishing retry.
   windows-self-upgrade.md: Validation evidence for GitHub issues #9 and #1 and the Windows self-upgrade patch.
   upgrade-reliability.md: Completed umbrella validation for GitHub issues 12 and 13.

package/library/cli.d.ts

@@ -2,7 +2,8 @@
  * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import type { CommandDef } from 'citty';
-export { runCli, runCliWithErrorHandling, runxCommand, };
+export { renderStartupBanner, runCli, runCliWithErrorHandling, runxCommand, };
+declare function renderStartupBanner(platform?: NodeJS.Platform, version?: string): string;
 declare const runxCommand: CommandDef<any>;
 declare function runCli(rawArgs?: string[]): Promise<void>;
 declare function runCliWithErrorHandling(rawArgs?: string[]): Promise<void>;

package/library/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AA+BH,OAAO,KAAK,EAAkB,UAAU,EAAkB,MAAM,OAAO,CAAA;AAIvE,OAAO,EACL,MAAM,EACN,uBAAuB,EACvB,WAAW,GACZ,CAAA;AAyPD,QAAA,MAAiB,WAAW,iBAAwB,CAAA;AAEpD,iBAAe,MAAM,CAAC,OAAO,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC9E;AAMD,iBAAe,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAexE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AA+BH,OAAO,KAAK,EAAkB,UAAU,EAAkB,MAAM,OAAO,CAAA;AAIvE,OAAO,EACL,mBAAmB,EACnB,MAAM,EACN,uBAAuB,EACvB,WAAW,GACZ,CAAA;AAuDD,iBAAS,mBAAmB,CAAC,QAAQ,kBAAmB,EAAE,OAAO,SAAgB,GAAG,MAAM,CAEzF;AAyMD,QAAA,MAAiB,WAAW,iBAAwB,CAAA;AAEpD,iBAAe,MAAM,CAAC,OAAO,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC9E;AAMD,iBAAe,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAexE"}

package/library/cli.js

@@ -17,7 +17,7 @@ import { fetchReleaseCatalog, paginateReleaseCatalog, resolveUpgradePlatform } f
 import { checkForLatestVersion, uninstallSelf, upgradeSelf } from './self-management.js';
 import { readCachedUpdateNotice, runUpdateWorker, spawnUpdateWorker } from './update-cache.js';
 import { renderReleaseCatalog, renderUpgradeEvent, renderUpgradeHeading, renderUpgradePlan, renderUpgradeResult } from './upgrade-reporting.js';
-export { runCli, runCliWithErrorHandling, runxCommand, };
+export { renderStartupBanner, runCli, runCliWithErrorHandling, runxCommand, };
 class CliHandled extends Error {
 }
 class CliUsageError extends Error {
@@ -32,6 +32,14 @@ const formatSchema = Type.Union([Type.Literal('text'), Type.Literal('json')]);
 const archSchema = Type.Union([Type.Literal('x64'), Type.Literal('arm64')]);
 const variantSchema = Type.Union([Type.Literal('baseline'), Type.Literal('default'), Type.Literal('modern')]);
 const positiveIntegerSchema = Type.Integer({ minimum: 1 });
+const platformLabels = {
+    darwin: 'macOS',
+    linux: 'Linux',
+    win32: 'Windows',
+};
+function renderStartupBanner(platform = process.platform, version = readVersion()) {
+    return `Hello ${platformLabels[platform] ?? platform} - runx v${version}\n`;
+}
 const helpArgs = {
     help: { type: 'boolean', alias: 'h', description: 'Show command help.' },
     'help-tree': { type: 'boolean', description: 'Show this command hierarchy.' },
@@ -174,7 +182,7 @@ function createCommandTree() {
         },
         run: ({ args }) => {
             if (args._.length === 0)
-                write(`Hello Windows - runx v${readVersion()}\n`);
+                write(renderStartupBanner());
         },
     });
     state.commands.set('', root);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/runx",
   "description": "A language-agnostic, documented command catalog and local CLI executor.",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "type": "module",
   "main": "./library/guiho-runx.js",
   "types": "./library/guiho-runx.d.ts",