@guiho/runx 0.4.1 → 0.5.2

package/devops/installers.spec.ts

@@ -3,29 +3,186 @@
  */
 
 import { describe, expect, test } from 'bun:test'
+import { $ } from 'bun'
 
 describe('RunX direct installers', () => {
   test('PowerShell installer exposes the complete RFC sequence', async () => {
     const script = await Bun.file(new URL('./install.ps1', import.meta.url)).text()
     expect(script).toContain('Initiating GUIHO CLI Upgrade / Installation Sequence...')
-    expect(script).toContain('guiho-s-runx')
-    expect(script).toContain('guiho-i-runx')
+    expect(script).toContain('guiho-s-runx.md')
+    expect(script).toContain('guiho-i-runx.md')
     expect(script).toContain('.agents\\skills\\guiho-s-runx')
     expect(script).toContain('.claude\\skills\\guiho-s-runx')
     expect(script).toContain('BEGIN RUNX — DO NOT EDIT THIS SECTION')
     expect(script).toContain('Test-NativeBinary')
     expect(script).toContain('Install-Transactional')
+    expect(script).toContain('function Test-MarkdownAsset')
+    expect(script).toContain("Test-MarkdownAsset -Path $skillAsset -ExpectedName 'guiho-s-runx'")
+    expect(script).toContain("Test-MarkdownAsset -Path $promptAsset -ExpectedName 'guiho-i-runx'")
+    expect(script).toContain('Windows executable header')
+    expect(script).toContain('binary NUL bytes')
+    expect(script).toContain('not valid UTF-8 text')
   })
 
-  test('POSIX installer selects Darwin assets and has no 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('guiho-s-runx')
-    expect(script).toContain('guiho-i-runx')
+    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')
     expect(script).toContain('.claude/skills/guiho-s-runx')
+    expect(script).toContain('verify_markdown_asset()')
+    expect(script).toContain("verify_markdown_asset \"$TMP/guiho-s-runx.md\" 'guiho-s-runx'")
+    expect(script).toContain("verify_markdown_asset \"$TMP/guiho-i-runx.md\" 'guiho-i-runx'")
+    expect(script).toContain('Windows executable header')
+    expect(script).toContain('binary NUL bytes')
+    expect(script).toContain('iconv -f UTF-8 -t UTF-8')
     expect(script).toContain('BEGIN RUNX — DO NOT EDIT THIS SECTION')
     expect(script).not.toContain(' bun ')
   })
+
+  test('Bash installer passes syntax, piped startup, exact versions, and executable verification', async () => {
+    const bash = await bashExecutable()
+    const script = Bun.fileURLToPath(new URL('./install.sh', import.meta.url))
+    const syntax = Bun.spawnSync([bash, '-n', script])
+    expect(syntax.exitCode).toBe(0)
+
+    const piped = Bun.spawnSync([
+      bash,
+      '-c',
+      'cat "$1" | RUNX_INSTALLER_SOURCE_ONLY=1 bash -s --',
+      'bash',
+      script,
+    ])
+    expect(piped.exitCode).toBe(0)
+    expect(piped.stderr.toString()).toBe('')
+
+    const functions = Bun.spawnSync([
+      bash,
+      '-c',
+      [
+        'RUNX_INSTALLER_SOURCE_ONLY=1 source "$1"',
+        'stable=$(normalize_version v1.2.3)',
+        '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('; '),
+      'bash',
+      script,
+    ])
+    expect(functions.exitCode).toBe(0)
+  })
+
+  test('platform installer rejects a PE payload disguised as Markdown', async () => {
+    const temporaryDirectory = `${Bun.env.TEMP ?? Bun.env.TMPDIR ?? '/tmp'}/runx-markdown-${crypto.randomUUID()}`
+    const validAsset = `${temporaryDirectory}/valid.md`
+    const executableAsset = `${temporaryDirectory}/payload.md`
+    await $`mkdir -p ${temporaryDirectory}`
+    try {
+      await Bun.write(validAsset, '---\nname: guiho-s-runx\n---\n\n# Skill\n')
+      await Bun.write(executableAsset, new Uint8Array([0x4d, 0x5a, 0x00, 0x00]))
+
+      if (process.platform === 'win32') {
+        const script = Bun.fileURLToPath(new URL('./install.ps1', import.meta.url))
+        const valid = Bun.spawnSync([
+          'powershell',
+          '-NoLogo',
+          '-NoProfile',
+          '-NonInteractive',
+          '-ExecutionPolicy',
+          'Bypass',
+          '-Command',
+          `$env:RUNX_INSTALLER_SOURCE_ONLY='1'; . '${script.replaceAll("'", "''")}'; Test-MarkdownAsset -Path '${validAsset.replaceAll("'", "''")}' -ExpectedName 'guiho-s-runx'`,
+        ])
+        const invalid = Bun.spawnSync([
+          'powershell',
+          '-NoLogo',
+          '-NoProfile',
+          '-NonInteractive',
+          '-ExecutionPolicy',
+          'Bypass',
+          '-Command',
+          `$env:RUNX_INSTALLER_SOURCE_ONLY='1'; . '${script.replaceAll("'", "''")}'; Test-MarkdownAsset -Path '${executableAsset.replaceAll("'", "''")}' -ExpectedName 'guiho-s-runx'`,
+        ])
+        expect(valid.exitCode).toBe(0)
+        expect(invalid.exitCode).not.toBe(0)
+        expect(invalid.stderr.toString()).toContain('Windows executable header')
+      } else {
+        const script = Bun.fileURLToPath(new URL('./install.sh', import.meta.url))
+        const bash = await bashExecutable()
+        const valid = Bun.spawnSync([
+          bash,
+          '-c',
+          `RUNX_INSTALLER_SOURCE_ONLY=1 . "$1"; verify_markdown_asset "$2" guiho-s-runx`,
+          'bash',
+          script,
+          validAsset,
+        ])
+        const invalid = Bun.spawnSync([
+          bash,
+          '-c',
+          `RUNX_INSTALLER_SOURCE_ONLY=1 . "$1"; verify_markdown_asset "$2" guiho-s-runx`,
+          'bash',
+          script,
+          executableAsset,
+        ])
+        expect(valid.exitCode).toBe(0)
+        expect(invalid.exitCode).not.toBe(0)
+        expect(invalid.stderr.toString()).toContain('Windows executable header')
+      }
+    } finally {
+      await $`rm -rf ${temporaryDirectory}`
+    }
+  })
+
+  if (process.platform === 'win32') {
+    test('PowerShell installer accepts exact stable and prerelease versions and verifies the executable', () => {
+      const script = Bun.fileURLToPath(new URL('./install.ps1', import.meta.url)).replaceAll("'", "''")
+      const bun = process.execPath.replaceAll("'", "''")
+      const command = [
+        "$env:RUNX_INSTALLER_SOURCE_ONLY='1'",
+        `. '${script}'`,
+        "$stable = Resolve-TargetVersion -RequestedVersion 'v1.2.3'",
+        "$prerelease = Resolve-TargetVersion -RequestedVersion '@guiho/runx@1.3.0-alpha.2'",
+        "if ($stable -ne '1.2.3' -or $prerelease -ne '1.3.0-alpha.2') { throw 'exact version normalization failed' }",
+        `Test-InstalledVersion -Path '${bun}' -ExpectedVersion '${process.versions.bun}'`,
+        "$mismatchRejected = $false",
+        `try { Test-InstalledVersion -Path '${bun}' -ExpectedVersion '0.0.0-impossible' } catch { $mismatchRejected = $true }`,
+        "if (-not $mismatchRejected) { throw 'version mismatch was not rejected' }",
+      ].join('; ')
+      const result = Bun.spawnSync([
+        'powershell',
+        '-NoLogo',
+        '-NoProfile',
+        '-NonInteractive',
+        '-ExecutionPolicy',
+        'Bypass',
+        '-Command',
+        command,
+      ])
+      expect(result.exitCode).toBe(0)
+    })
+  }
 })
+
+async function bashExecutable(): Promise<string> {
+  const gitBash = 'C:\\Program Files\\Git\\bin\\bash.exe'
+  if (process.platform === 'win32' && await Bun.file(gitBash).exists()) return gitBash
+  const bash = Bun.which('bash')
+  if (!bash) throw new Error('Bash is required to validate devops/install.sh.')
+  return bash
+}

package/devops/verify-release-assets.ts

@@ -14,4 +14,18 @@ if (JSON.stringify(observed) !== JSON.stringify(expected)) {
   throw new Error(`Expected exactly ${expected.length} release assets.\nExpected: ${expected.join(', ')}\nObserved: ${observed.join(', ')}`)
 }
 
+for (const [assetName, expectedName] of [
+  ['guiho-s-runx.md', 'guiho-s-runx'],
+  ['guiho-i-runx.md', 'guiho-i-runx'],
+] as const) {
+  const bytes = await Bun.file(joinPath(bin, assetName)).bytes()
+  if (bytes.length === 0 || (bytes[0] === 0x4d && bytes[1] === 0x5a) || bytes.includes(0)) {
+    throw new Error(`Release Markdown asset is empty or binary: ${assetName}`)
+  }
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes).replace(/\r\n/g, '\n')
+  if (!text.startsWith('---\n') || !new RegExp(`^name:\\s*${expectedName}\\s*$`, 'm').test(text)) {
+    throw new Error(`Release Markdown asset has invalid frontmatter identity: ${assetName}`)
+  }
+}
+
 process.stdout.write(`${JSON.stringify({ count: observed.length, assets: observed }, null, 2)}\n`)

package/docs/architecture/architecture.xdocs.md

@@ -1,6 +1,6 @@
 ---
 subject: runx-architecture
-description: Technical architecture for the RunX manifest, Citty command tree, agent skill, and native distribution.
+description: Technical architecture for the RunX manifest, Citty command tree, automatic agent maintenance, and native distribution.
 parent: runx-docs
 children: []
 files:
@@ -14,6 +14,7 @@ keywords:
   - bun
   - cli
   - citty
+  - agent maintenance
 flags: []
 status: stable
 ---

package/docs/architecture/cli-architecture.md

@@ -20,13 +20,18 @@ owner: runx-architecture
 
 ## Flow
 
-`cli.ts` defines a Citty command tree. Citty parses options and positionals,
-resolves nested commands and aliases, and renders ordinary usage. A bounded
-command-map adapter preserves the legacy `runx <selector>` shorthand while
-known Citty commands retain precedence. Manifest commands use `manifest.ts` to
-discover the nearest `runx.yaml`, parse YAML, validate a strict TypeBox schema,
-and resolve a selector. `render.ts` presents text or JSON. `executor.ts` spawns
-exactly one configured shell command only for a real run.
+`cli.ts` defines one Citty command tree. Citty parses options and positionals,
+resolves nested commands, and renders usage. Manifest commands use
+`configuration.ts` to resolve `runx.yaml` by explicit path, effective cwd, then
+global fallback; TypeBox validates the complete shape. `render.ts` presents
+text or JSON. `executor.ts` spawns exactly one configured shell command only for
+a real `runx run`.
+
+After an ordinary command routes through Citty, `agent-maintenance.ts` receives
+the decoded effective cwd and detaches a hidden worker. The worker compares
+embedded skill content with both global copies and atomically reconciles one
+nearest `AGENTS.md` block. Explicit agent-resource and uninstall commands are
+excluded so intentional removal is not reversed.
 
 ## Boundaries
 
@@ -34,8 +39,12 @@ exactly one configured shell command only for a real run.
 - Help, version, and CLI usage failures do not discover a manifest.
 - `source/flags.ts` no longer exists; RunX has no second token parser or manual
   execution router behind Citty.
-- `agents.ts` copies the embedded or packaged skill into the requested standard
-  or Claude-compatible skill location.
+- `agents.ts` owns explicit dual-tool actions plus idempotent, legacy-aware
+  automatic skill and instruction reconciliation.
+- `storage.ts` performs same-directory temporary writes and atomic replacement
+  for automatic resource maintenance.
+- Hidden update and agent-maintenance routes never appear in public help and
+  cannot recursively schedule themselves.
 - `self-management.ts` queries GitHub Releases and only replaces/removes a
   native executable, never a Bun development process.
 - Native builds register `embedded-resources.ts`, which includes the skill.

package/docs/decisions/decisions.xdocs.md

@@ -7,6 +7,7 @@ files:
   alpha-boundaries.md: Captures accepted alpha scope, safety, distribution, and compatibility decisions.
   citty-cli-migration.md: Defines the accepted full migration from handwritten parsing and routing to Citty.
   interactive-init-manifest.md: Defines interactive initialization, Semantic Versioning, the public group, and the scripts directory contract.
+  markdown-release-assets-and-version-scoped-notes.md: Defines .md agent release filenames, downloaded-resource validation, and exact-version idempotent GitHub Release notes.
   mirror-automatic-push.md: Defines automatic Mirror release pushes with a synchronized protected-main gate.
   npm-trusted-publishing.md: Defines the accepted npm OIDC publishing workflow and protected-branch patch-release trial.
   windows-self-upgrade.md: Defines synchronous Windows executable replacement, verification, rollback, and cleanup.
@@ -14,6 +15,7 @@ documents:
   alpha-boundaries.md: Decision record for RunX alpha boundaries.
   citty-cli-migration.md: Decision record for the complete Citty CLI parser and router migration.
   interactive-init-manifest.md: Accepted manifest and interactive initialization decision for runx init.
+  markdown-release-assets-and-version-scoped-notes.md: Accepted public asset filename, validation, and release-description policy.
   mirror-automatic-push.md: Accepted release-policy decision for Mirror push=true and protected delivery ordering.
   npm-trusted-publishing.md: Decision record for GitHub Actions npm trusted publishing and the first automated patch release.
   windows-self-upgrade.md: Accepted design for synchronous and recoverable Windows native self-upgrade.
@@ -25,6 +27,8 @@ keywords:
   - runx init
   - scripts directory
   - mirror push
+  - markdown release assets
+  - version-scoped release notes
   - windows self-upgrade
 flags: []
 status: stable

package/docs/decisions/markdown-release-assets-and-version-scoped-notes.md

@@ -0,0 +1,84 @@
+---
+name: RunX Markdown Release Assets And Version-Scoped Notes
+purpose: Preserve the accepted RunX GitHub Release filename and release-description policy.
+description: Records the project override requiring .md agent asset filenames and exact-version changelog sections for idempotent GitHub Release notes.
+created: 2026-07-19
+flags:
+  - accepted
+  - release-policy
+tags:
+  - decisions
+  - releases
+  - cli
+keywords:
+  - guiho-s-runx.md
+  - guiho-i-runx.md
+  - GitHub Release notes
+  - changelog extraction
+owner: runx-decisions
+---
+
+# RunX Markdown Release Assets And Version-Scoped Notes
+
+## Status
+
+Accepted by the developer on 2026-07-19.
+
+## Context
+
+The bundled RFC 0034 skill originally named the two Markdown release artifacts
+without extensions. That makes their content type less obvious and conflicts
+with the explicit RunX release contract chosen by the developer. The publish
+workflow also passed the complete changelog to GitHub, causing one release to
+describe unrelated versions.
+
+## Decision
+
+Every RunX GitHub Release contains exactly fourteen assets: twelve native
+binaries plus `guiho-s-runx.md` and `guiho-i-runx.md`.
+
+The `.md` suffixes are public filename requirements. Installers download those
+names, install the skill content as `SKILL.md`, and use the instruction asset
+content for managed instruction blocks.
+
+Release notes contain only the exact `## <version> - <date>` section from
+`CHANGELOG.md`, ending before the next `## ` heading. Publishing fails closed
+when the exact section is missing or empty. Rerunning a tag updates the existing
+release notes before replacing its assets.
+
+Downloaded agent artifacts are treated as untrusted release inputs. Installers
+reject empty payloads, Windows executable headers, NUL-containing binary data,
+invalid UTF-8, missing YAML frontmatter, and mismatched resource identities
+before writing any global skill or project instruction file.
+
+## Alternatives Considered
+
+- Extensionless agent assets: rejected because the developer explicitly
+  requires recognizable Markdown filenames.
+- Full-changelog release notes: rejected because they include unrelated release
+  history.
+- Creating notes only on first publish: rejected because reruns must repair
+  stale release descriptions idempotently.
+- Trusting the filename extension alone: rejected because a `.md` download can
+  still contain an executable or corrupted payload.
+
+## Consequences
+
+- RunX intentionally differs from the original extensionless RFC asset spelling.
+- All build, verification, workflow, installer, test, and public documentation
+  surfaces must use the `.md` filenames.
+- Every version tag requires an exact matching changelog heading before its
+  protected publish workflow can succeed.
+- Installer validation must complete before any downloaded agent resource is
+  copied or applied.
+
+## Reversal Or Revisit Conditions
+
+Revisit only through an explicit developer decision that changes the public
+release contract and migrates all consumers together.
+
+## References
+
+- [RFC migration plan](../plans/rfc-0034-cli-compliance-migration.md)
+- [RFC task specification](../todo/rfc-0034-cli-compliance-migration.md)
+- [RunX documentation](../../DOCS.md)

package/docs/plans/automatic-agent-maintenance.md

@@ -0,0 +1,120 @@
+---
+name: RunX Automatic Agent Maintenance Plan
+purpose: Define executable units for GitHub issue 11 automatic skill and AGENTS.md maintenance.
+description: Sequences atomic resource reconciliation, a hidden worker, startup integration, regression coverage, documentation, review, and validation.
+created: 2026-07-19
+flags:
+  - approved
+  - implementation-ready
+  - implemented
+tags:
+  - planning
+  - cli
+  - agents
+keywords:
+  - RunX
+  - issue 11
+  - background worker
+  - atomic writes
+  - AGENTS.md
+owner: runx-plans
+---
+
+# RunX Automatic Agent Maintenance Plan
+
+## Outcome
+
+Every ordinary RunX invocation schedules a hidden, non-blocking,
+failure-isolated worker that reconciles the bundled `guiho-s-runx` skill in
+both global tool locations and one compact managed block in the nearest
+applicable `AGENTS.md`. Current resources remain untouched, stale or legacy
+resources converge to bundled content, and foreground text, JSON, help,
+version, command execution, and exit behavior remain deterministic.
+
+## Authority
+
+- GitHub issue [#11](https://github.com/CGuiho/runx/issues/11) is the accepted
+  behavior requirement.
+- `guiho-a-0001-swe` coordinates execution.
+- `guiho-s-0034-cli-engineer`, `guiho-s-0023-plan-executor`,
+  `guiho-s-0015-bun`, `guiho-s-0019-typescript`, `guiho-s-0011-typebox`, and
+  `guiho-s-xdocs` govern implementation.
+- The approved RFC breaking boundary remains: the namespace is singular
+  `runx agent`; no plural compatibility alias will be restored.
+
+## Unit AM-01 - Atomic Reconciliation Primitives
+
+- Goal: reconcile only missing or stale agent resources without partial writes.
+- Expected files: `source/storage.ts`, `source/agents.ts`, colocated tests.
+- Actions:
+  1. Add same-directory temporary-file writes followed by atomic replacement.
+  2. Compare both global skill targets with the bundled skill before writing.
+  3. Find the nearest existing `AGENTS.md` from effective cwd; create one at
+     effective cwd only when no ancestor contains it.
+  4. Replace current or legacy RunX blocks without duplicating them.
+  5. Preserve user-authored content outside recognized markers.
+- Acceptance:
+  - Missing and stale resources are repaired.
+  - Current resources report no change and are not rewritten.
+  - Concurrent reconciliations converge to identical content.
+  - Failures do not leave a truncated destination.
+
+## Unit AM-02 - Hidden Worker Lifecycle
+
+- Goal: schedule maintenance without blocking or polluting foreground output.
+- Expected files: new `source/agent-maintenance.ts`, `source/cli.ts`, tests.
+- Dependencies: AM-01.
+- Actions:
+  1. Add one hidden exact worker route absent from public help/tree/docs.
+  2. Pass the Citty-decoded effective cwd to the detached worker.
+  3. Disable recursive scheduling in the worker process.
+  4. Ignore worker stdout/stderr and isolate spawn/worker failures.
+  5. Exclude explicit agent-resource and uninstall commands so explicit removal
+     is not immediately reversed.
+- Acceptance:
+  - Plain RunX and ordinary catalog commands schedule the worker.
+  - The foreground does not wait for reconciliation.
+  - Text and JSON output and exit codes remain unchanged.
+  - Hidden worker execution cannot recursively spawn itself.
+
+## Unit AM-03 - Acceptance Regressions
+
+- Goal: prove every issue criterion with temporary homes and projects.
+- Expected files: `source/agent-maintenance.spec.ts`, `source/cli.spec.ts`.
+- Dependencies: AM-01 and AM-02.
+- Tests:
+  - missing, current, and outdated skills in both global tool locations;
+  - nearest `AGENTS.md` insertion and stale/legacy block replacement;
+  - preservation of user-authored content;
+  - two concurrent reconciliations;
+  - worker spawn failure and maintenance failure isolation;
+  - plain invocation scheduling and effective `--cwd` routing;
+  - stable text/JSON output and hidden help tree.
+- Acceptance:
+  - The full suite exits cleanly with no real global mutation.
+
+## Unit AM-04 - Documentation, Review, And Validation
+
+- Goal: close durable state and provide issue-resolution evidence.
+- Dependencies: AM-03.
+- Actions:
+  1. Document automatic behavior and explicit-command boundaries.
+  2. Review implementation against every issue checkbox.
+  3. Run typecheck, tests, build, native smoke, prohibited-import scan, and
+     narrow XDocs checks.
+  4. Commit one file at a time, push main, comment factual evidence on issue
+     #11, and close only after GitHub contains the implementation.
+- Acceptance:
+  - No review finding remains.
+  - Pushed commit and validation evidence precede closure.
+
+## Release Boundary
+
+This externally observable capability requires a final Mirror `minor` plan
+after all open issues are resolved. Do not version or tag during this unit.
+
+## References
+
+- [Task specification](../todo/automatic-agent-maintenance.md)
+- [CLI architecture](../architecture/cli-architecture.md)
+- [RFC migration plan](./rfc-0034-cli-compliance-migration.md)

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

@@ -5,19 +5,25 @@ parent: runx-docs
 children: []
 files:
   alpha-implementation.md: Breaks the accepted alpha into implementation and validation units.
+  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.
 documents:
   alpha-implementation.md: Plan used for the initial RunX implementation.
+  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/plans/rfc-0034-cli-compliance-migration.md

@@ -447,13 +447,17 @@ execution session rather than assuming it remains active from an earlier unit.
   4. Validate integrity and architecture.
   5. Transactionally install and verify the binary.
   6. Add the global binary directory to PATH when missing.
-  7. Download/extract `guiho-s-runx` into both global skill locations.
-  8. Download `guiho-i-runx`, discover instruction files, and reconcile their
+  7. Download `guiho-s-runx.md` and install it as `SKILL.md` in both global
+     skill locations.
+  8. Download `guiho-i-runx.md`, discover instruction files, and reconcile their
      managed blocks.
-  9. Log every action and final `runx --version` verification.
+  9. Reject empty, executable, binary, invalid UTF-8, missing-frontmatter, or
+     wrong-identity agent assets before any skill or instruction write.
+  10. Log every action and final `runx --version` verification.
 - Acceptance:
   - Isolated Windows and POSIX installer tests cover success, fallback,
-    corruption, rollback, PATH, both skills, instructions, and progress.
+    binary Markdown rejection, rollback, PATH, both skills, instructions, and
+    progress.
 
 ### Unit RX-13 - Replace The Npm Launcher With A Node-Compatible Bootstrap
 
@@ -494,18 +498,23 @@ execution session rather than assuming it remains active from an earlier unit.
   - `runx-windows-x64-baseline.exe`
   - `runx-windows-x64-modern.exe`
 - Agent asset names:
-  - `guiho-s-runx`
-  - `guiho-i-runx`
+  - `guiho-s-runx.md`
+  - `guiho-i-runx.md`
 - Actions:
   1. Replace every `macos` name and selector with `darwin`.
   2. Use Bun APIs in the binary builder rather than Node filesystem/path
      imports.
   3. Package the skill directory and instruction/prompt artifact reproducibly.
-  4. Upload only the fourteen expected assets.
-  5. Make CI fail for missing, duplicate, extra, wrongly suffixed, or legacy
+  4. Treat the `.md` suffixes as part of both public agent-asset filenames.
+  5. Extract only the exact version heading and body from `CHANGELOG.md` for
+     GitHub Release notes; fail closed if it is missing and update existing
+     releases idempotently.
+  6. Upload only the fourteen expected assets.
+  7. Make CI fail for missing, duplicate, extra, wrongly suffixed, or legacy
      assets.
 - Acceptance:
   - Automated verification observes exactly fourteen unique names.
+  - Release notes exclude changelog frontmatter and every older/newer version.
 
 ### Unit RX-15 - Align Documentation, Skill, TODO, And XDocs