@guiho/runx 0.4.1 → 0.5.1

package/docs/validation/upgrade-reliability-issue-12.md

@@ -0,0 +1,74 @@
+---
+name: RunX Upgrade Reliability Issue 12 Validation
+purpose: Record current-main evidence for GitHub issue 12.
+description: Captures focused and full transaction, catalog, routing, native, live GitHub, XDocs, and Git integrity checks.
+created: 2026-07-19
+flags:
+  - validated
+tags:
+  - validation
+  - cli
+  - reliability
+keywords:
+  - RunX
+  - issue 12
+  - 50 tests
+  - 14 assets
+owner: runx-validation
+---
+
+# RunX Upgrade Reliability Issue 12 Validation
+
+## Summary
+
+All local completion gates for GitHub issue #12 passed after correcting the
+complete-list default and Citty parent/subcommand routing. No validation
+blocker remains.
+
+## Commands Run
+
+| Command or check | Result |
+| --- | --- |
+| `bun run typecheck` | Passed |
+| focused catalog, transaction, reporting, and CLI tests | Passed: 31 tests, 222 assertions |
+| `bun test --timeout 30000` | Passed: 50 tests, 342 assertions |
+| `bun run build` | Passed |
+| `bun run binary` | Passed |
+| `bun run binaries` | Passed: twelve native targets |
+| `bun run verify-assets` | Passed: exactly fourteen unique assets |
+| live source `upgrade list --format json` | Passed: one JSON document, ten current published releases, current/latest/asset metadata |
+| live source `upgrade check --format json` | Passed: one JSON document, no parent upgrade envelope |
+| strict XDocs metadata and doctor | Passed for source and docs: zero errors and zero warnings |
+| `git diff --check` | Passed |
+
+## Transaction Evidence
+
+- The self-management suite renames a running Windows executable, places the
+  new binary at the canonical path, executes that path with `--version`, and
+  reports success only after the exact target is observed.
+- Controlled second-rename, target-version mismatch, and rollback-failure tests
+  prove nonzero structured outcomes and deterministic restoration behavior.
+- Plan and phase callbacks prove plan output precedes download work and
+  replacement starts only after download and native validation.
+
+## Catalog Evidence
+
+- GitHub `Link` pagination, SemVer/prerelease ordering, channel labels,
+  malformed payloads, candidate ordering, and missing compatible assets are
+  covered by focused tests.
+- A real Citty-route regression follows two mocked release pages, includes an
+  alpha release without an opt-in flag, parses exactly one JSON document, and
+  proves the parent upgrade action did not execute.
+- Live GitHub-backed list and check routes each returned one parseable document
+  with exit code zero.
+
+## Skipped Checks
+
+- No installed user executable was replaced.
+- No package publication, GitHub Release creation, Mirror version, or tag was
+  performed during this issue unit.
+
+## References
+
+- [Implementation review](../reviews/implementation/upgrade-reliability-issue-12-review.md)
+- [Implementation plan](../plans/upgrade-reliability-implementation.md)

package/docs/validation/upgrade-reliability-issue-13.md

@@ -0,0 +1,72 @@
+---
+name: RunX Upgrade Reliability Issue 13 Validation
+purpose: Record current-main exact recovery and installer evidence for GitHub issue 13.
+description: Captures outcome-matrix, exact target, executable installer, native text/JSON, full suite, assets, XDocs, and Git checks.
+created: 2026-07-19
+flags:
+  - validated
+tags:
+  - validation
+  - cli
+  - reliability
+keywords:
+  - RunX
+  - issue 13
+  - exact recovery
+  - installer verification
+owner: runx-validation
+---
+
+# RunX Upgrade Reliability Issue 13 Validation
+
+## Summary
+
+All local completion gates for GitHub issue #13 passed. No validation blocker
+remains.
+
+## Commands Run
+
+| Command or check | Result |
+| --- | --- |
+| `bun run typecheck` | Passed |
+| focused recovery, transaction, reporting, and installer tests | Passed: 23 tests, 126 assertions |
+| `bun test --timeout 30000` | Passed: 52 tests, 358 assertions |
+| `bun run build` | Passed |
+| `bun run binary` and `bun run binaries` | Passed: single local build and twelve native targets |
+| `bun run verify-assets` | Passed: exactly fourteen unique assets |
+| native Windows x64 already-current text smoke | Passed: exact 0.4.1 installer followed by separate stop command |
+| native Windows x64 already-current JSON smoke | Passed: resolved 0.4.1 recovery object |
+| strict XDocs metadata and doctor | Passed for source, devops, and docs: zero errors and zero warnings |
+| `git diff --check` | Passed |
+
+## Recovery Evidence
+
+- The reporter test matrix covers `upgraded`, `up-to-date`, `dry-run`,
+  `rolled-back`, and `failed`; every summary precedes the exact installer, and
+  every installer precedes the separate process-stop command.
+- Discovery failure retains a visibly labeled fallback-current repair command.
+- Download and replacement failures retain the resolved recovery object in the
+  shared upgrade envelope.
+- JSON exposes `targetVersion`, `targetSource`, `installCommand`, and
+  `stopProcessCommand` without mixing text into stdout.
+
+## Installer Evidence
+
+- Windows and POSIX recovery generators preserve full prerelease identifiers.
+- The PowerShell installer functions execute exact stable and prerelease
+  normalization, accept the real Bun executable when its reported version
+  matches, and reject a controlled mismatch.
+- Installer contract tests cover exact flags, native validation, transactional
+  replacement, rollback language, and the separate stop workflow.
+
+## Platform Boundary
+
+No WSL distribution is installed in the current Windows environment. Git for
+Windows Bash executes the installer syntax, piped startup, exact-version
+normalization, and executable verification locally; Ubuntu CI remains the
+native Linux gate.
+
+## References
+
+- [Implementation review](../reviews/implementation/upgrade-reliability-issue-13-review.md)
+- [Umbrella validation](./upgrade-reliability.md)

package/docs/validation/upgrade-reliability.md

@@ -1,11 +1,11 @@
 ---
 name: RunX Upgrade Reliability Validation
-purpose: Record release-ready verification evidence for GitHub issues 12 and 13.
-description: Results for release pagination, progress reporting, transactional replacement, rollback, recovery commands, direct installers, native builds, live release smokes, and XDocs integrity.
+purpose: Preserve the completed umbrella validation for GitHub issues 12 and 13.
+description: Summarizes current release discovery, transaction, recovery, installer, native, and structured documentation evidence.
 created: 2026-07-15
+updated: 2026-07-19
 flags:
-  - superseded
-  - needs-revalidation
+  - validated
 tags:
   - validation
   - cli
@@ -24,101 +24,40 @@ owner: runx-validation
 
 ## Current Status
 
-The first validation pass below is superseded by independent review findings.
-The implementation has since been corrected for exact JSON envelope fidelity,
-post-backup rename/rollback state, downgrade prevention, installer failure
-classification, Ubuntu portability, and executable controlled installer tests.
-Candidate verification now has a bounded ten-second timeout in the CLI and both
-direct installers. Those corrections still require the complete release gate
-to be rerun before this document or the TODO task can return to
-`validated`/`completed`.
-
-No package publication, version apply, or tag operation was performed.
-
-## Superseded Automated Gate
-
-| Command | Result |
-| --- | --- |
-| `bun run typecheck` | Passed. |
-| `bun test` | Passed: 37 tests, 0 failures, 245 assertions across 8 files. |
-| `bun run build` | Passed; TypeScript library output compiled. |
-| `bun run binary` | Passed; local native executable compiled. |
-| `bun run binaries` | Passed; all 12 Linux, macOS, and Windows release assets compiled and were non-empty. |
-| `bun test devops/installers.spec.ts` | Superseded: the earlier suite relied partly on source-pattern checks. The replacement suite executes controlled native installer and recovery scenarios and awaits revalidation. |
-
-Generated `library/` and `bin/` outputs remain ignored and are not part of the
-committed change.
-
-## Superseded Behavior Evidence
-
-- Release-catalog tests follow `Link: rel="next"`, reject malformed/non-2xx
-  responses, apply SemVer prerelease precedence, retain invalid tags last, and
-  enforce baseline/default/modern asset candidates.
-- Reporting tests prove the complete plan precedes `Downloading`, which
-  precedes the download body and then `Validating`, `Replacing`, and
-  `Verifying`.
-- The Windows test runs a copied executable, keeps it mapped in a live process,
-  renames it, installs the new canonical executable immediately, verifies the
-  exact version, and allows only old-image cleanup to be deferred.
-- Failure tests reject non-native downloads before mutation and restore the
-  original executable after target verification failure.
-- Bun-launcher failure returns a recovery command pinned to the resolved target
-  instead of losing recovery at the generic CLI error boundary.
-- Installer tests enforce unique temporary paths, exact target versions,
-  canonical verification, rollback language/behavior, and separate stop
-  commands.
-
-## Superseded Compiled Binary Smoke
-
-The compiled `runx-windows-x64-baseline.exe` reported version `0.2.7`.
-`upgrade --dry-run` queried live GitHub release metadata and printed the full
-plan before any mutation, followed by the pinned `0.2.7` PowerShell recovery
-command and the separate safe stop command. `upgrade list --format json`
-returned one valid schema-versioned document containing all eight currently
-published releases from `0.2.7` through `0.2.0`, newest first, with current,
-latest-stable, publication, channel, and compatible-asset data.
-
-The first smoke command targeted `bin/runx.exe` after the complete matrix build
-had replaced the local single-binary output with named assets. It failed only
-because that path no longer existed; the smoke was immediately rerun against
-the actual baseline matrix asset and passed.
-
-## Superseded XDocs Gate
-
-Using an equivalent validation-only XDocs configuration with agent file writes
-disabled:
-
-- strict metadata passed for `docs/plans`, `docs/reviews/plans`, `docs/todo`,
-  `source`, `devops`, and `skills/guiho-s-runx`;
-- `xdocs doctor --warnings-as-errors --format json` returned `valid: true`,
-  zero errors, and zero warnings; and
-- `xdocs tree` returned one connected RunX tree without duplicate subjects or
-  orphans.
+Validated.
+
+The earlier blocked validation is superseded by the current-main issue-specific
+reviews and passing gates. GitHub issue #12 owns immediate verified replacement
+and the complete release catalog. GitHub issue #13 owns exact-version recovery
+instructions and direct installer verification.
+
+## Completion Evidence
+
+- The canonical executable is replaced and verified before success; only old
+  backup cleanup may be deferred on Windows.
+- Replacement, verification, and rollback failures return stable structured
+  outcomes and preserve exact recovery instructions.
+- Release discovery follows every GitHub page, applies SemVer ordering and
+  channel labels, and exposes current/latest/date/compatible-asset metadata.
+- The default public list includes all published prereleases and emits only its
+  selected Citty leaf result.
+- Every terminal upgrade outcome renders a pinned install command before a
+  separate platform process-stop command.
+- PowerShell and POSIX installers accept exact stable and prerelease versions,
+  validate native assets, verify the installed `--version`, and fail nonzero on
+  mismatch.
+- TypeScript, the complete Bun suite, library build, twelve native targets,
+  exact fourteen assets, live native text/JSON smokes, XDocs, and Git integrity
+  pass on the final implementation.
+
+## Detailed Records
+
+- [Issue 12 implementation review](../reviews/implementation/upgrade-reliability-issue-12-review.md)
+- [Issue 12 validation](./upgrade-reliability-issue-12.md)
+- [Issue 13 implementation review](../reviews/implementation/upgrade-reliability-issue-13-review.md)
+- [Issue 13 validation](./upgrade-reliability-issue-13.md)
 
 ## Release Boundary
 
-The branch preserves package version `0.2.7`. A future merge/release owner must
-use Mirror to plan and apply any requested patch release; this implementation
-does not publish or tag automatically.
-
-## Required Revalidation
-
-- `bun run typecheck`
-- `bun test`, including the controlled installer/recovery suite on Ubuntu and Windows
-- `bun run build`, `bun run binary`, and `bun run binaries`
-- compiled CLI text/JSON smokes, including failed and rolled-back envelopes
-- strict XDocs metadata, doctor warnings-as-errors, and tree validation
-
-The current isolated Windows worktree could not begin that rerun because
-`bun install --frozen-lockfile` was denied while opening `bun.lock` with
-`EPERM`. This is an environment validation blocker, not a passing result.
-
-## Review-Correction Checks
-
-| Command | Result |
-| --- | --- |
-| Cached TypeScript 6 compiler, `-p . --noEmit` | Passed after the review corrections. |
-| PowerShell parser for `devops/install.ps1` | Passed. |
-| Git Bash `bash -n devops/install.sh` | Passed. |
-| `git diff --check` | Passed. |
-| Focused Bun tests | Blocked before test execution by `EPERM` reading the isolated worktree and `tsconfig.json`; zero tests passed in that attempt. |
+No package publication or GitHub Release mutation was performed directly.
+Mirror versioning remains deferred to the single final open-issue release step.

package/docs/validation/validation.xdocs.md

@@ -4,20 +4,30 @@ description: Validation evidence and implementation summaries for RunX releases.
 parent: runx-docs
 children: []
 files:
+  bash-installer.md: Records Bash syntax, piped startup, exact versions, executable verification, native assets, XDocs, and Git evidence for issue 15.
   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.
   windows-self-upgrade.md: Records Windows replacement, rollback, cleanup, native build, CI, and XDocs validation evidence.
-  upgrade-reliability.md: Tracks the superseded first pass and required revalidation after independent upgrade reliability review corrections.
+  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.
+  automatic-agent-maintenance.md: Records focused and full tests, native builds, exact assets, import scan, XDocs, and Git evidence for issue 11.
+  upgrade-reliability-issue-12.md: Records transaction, complete catalog, Citty routing, native matrix, live GitHub, XDocs, and Git evidence for issue 12.
+  upgrade-reliability-issue-13.md: Records all-outcome recovery, exact target, executable installer, native text/JSON, XDocs, and Git evidence for issue 13.
+  unicode-help-tree.md: Records focused/full tests, explicit glyph/alignment assertions, native smoke, assets, XDocs, and Git evidence for issue 17.
 documents:
+  bash-installer.md: Current-main validation report for the RunX Bash installer.
   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.
   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: Revalidation record for GitHub issues 12 and 13; currently marked needs-revalidation.
+  upgrade-reliability.md: Completed umbrella validation for GitHub issues 12 and 13.
   rfc-0034-cli-compliance-migration.md: Complete RFC 0034 correction validation and patch-release readiness report.
+  automatic-agent-maintenance.md: Complete validation report for automatic RunX agent maintenance.
+  upgrade-reliability-issue-12.md: Current-main validation report for GitHub issue 12.
+  upgrade-reliability-issue-13.md: Current-main validation report for GitHub issue 13.
+  unicode-help-tree.md: Current-main validation report for the RunX Unicode help tree.
 tags:
   - validation
 keywords:

package/library/agent-maintenance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export { agentMaintenanceWorkerCwd, runAgentMaintenanceWorker, spawnAgentMaintenanceWorker, };
+type AgentWorkerSpawnOptions = {
+    readonly detached: true;
+    readonly stdout: 'ignore';
+    readonly stderr: 'ignore';
+    readonly stdin: 'ignore';
+    readonly cwd: string;
+    readonly env: Record<string, string | undefined>;
+};
+type AgentWorkerSpawner = (command: string[], options: AgentWorkerSpawnOptions) => {
+    unref(): unknown;
+};
+declare function agentMaintenanceWorkerCwd(rawArgs: string[]): string | null;
+declare function runAgentMaintenanceWorker(cwd: string): Promise<void>;
+declare function spawnAgentMaintenanceWorker(cwd: string, spawn?: AgentWorkerSpawner): boolean;
+//# sourceMappingURL=agent-maintenance.d.ts.map

package/library/agent-maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-maintenance.d.ts","sourceRoot":"","sources":["../source/agent-maintenance.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,GAC5B,CAAA;AAED,KAAK,uBAAuB,GAAG;IAC7B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACjD,CAAA;AACD,KAAK,kBAAkB,GAAG,CACxB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,uBAAuB,KAC7B;IAAE,KAAK,IAAI,OAAO,CAAA;CAAE,CAAA;AAQzB,iBAAS,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAOnE;AAED,iBAAe,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnE;AAED,iBAAS,2BAA2B,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,kBAAsE,GAC5E,OAAO,CAmBT"}

package/library/agent-maintenance.js

@@ -0,0 +1,49 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { maintainAgentIntegration } from './agents.js';
+import { RunXError } from './errors.js';
+import { directoryName, resolvePath } from './path-utils.js';
+export { agentMaintenanceWorkerCwd, runAgentMaintenanceWorker, spawnAgentMaintenanceWorker, };
+const workerFlag = '--maintain-agent-integration-worker';
+const workerArgsSchema = Type.Tuple([
+    Type.Literal(workerFlag),
+    Type.String({ minLength: 1 }),
+]);
+function agentMaintenanceWorkerCwd(rawArgs) {
+    if (rawArgs[0] !== workerFlag)
+        return null;
+    try {
+        return resolvePath(Value.Decode(workerArgsSchema, rawArgs)[1]);
+    }
+    catch (error) {
+        throw new RunXError(`Invalid agent-maintenance worker invocation: ${error instanceof Error ? error.message : String(error)}`, 2);
+    }
+}
+async function runAgentMaintenanceWorker(cwd) {
+    await maintainAgentIntegration(resolvePath(cwd));
+}
+function spawnAgentMaintenanceWorker(cwd, spawn = (command, options) => Bun.spawn(command, options)) {
+    if (Bun.env.RUNX_DISABLE_AGENT_MAINTENANCE_WORKER === '1')
+        return false;
+    const effectiveCwd = resolvePath(cwd);
+    const command = process.execPath.toLowerCase().includes('bun')
+        ? [process.execPath, Bun.main, workerFlag, effectiveCwd]
+        : [process.execPath, workerFlag, effectiveCwd];
+    try {
+        spawn(command, {
+            detached: true,
+            stdout: 'ignore',
+            stderr: 'ignore',
+            stdin: 'ignore',
+            cwd: directoryName(process.execPath),
+            env: { ...process.env, RUNX_DISABLE_AGENT_MAINTENANCE_WORKER: '1' },
+        }).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/library/agents.d.ts

@@ -2,11 +2,15 @@
  * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import type { AgentScope } from './types.js';
-export { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, };
+export { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, maintainAgentIntegration, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, };
 type EmbeddedResources = {
     skill: string;
     prompt: string;
 } | undefined;
+type AgentMaintenanceResult = {
+    readonly skills: string[];
+    readonly instructions: string[];
+};
 declare global {
     var __RUNX_EMBEDDED_RESOURCES__: EmbeddedResources;
 }
@@ -33,4 +37,5 @@ declare function listAgentPrompts(namesOnly?: false): Array<{
     description: string;
 }>;
 declare function showAgentPrompt(id: string): Promise<string>;
+declare function maintainAgentIntegration(cwd: string): Promise<AgentMaintenanceResult>;
 //# sourceMappingURL=agents.d.ts.map

package/library/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,GACjB,CAAA;AAED,KAAK,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAA;AAEtE,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,2BAA2B,EAAE,iBAAiB,CAAA;CACnD;AAOD,iBAAe,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAElF;AAED,iBAAe,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEjF;AAED,iBAAe,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIpF;AAED,iBAAS,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAIpF;AAED,iBAAe,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAQtI;AAED,iBAAe,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEpE;AAED,iBAAe,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAErE;AAED,iBAAe,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYrE;AAED,iBAAe,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEtD;AAED,iBAAS,gBAAgB,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,EAAE,CAAA;AACpD,iBAAS,gBAAgB,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAOxF,iBAAe,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,GACjB,CAAA;AAED,KAAK,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAA;AACtE,KAAK,sBAAsB,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAChC,CAAA;AAED,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,2BAA2B,EAAE,iBAAiB,CAAA;CACnD;AASD,iBAAe,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAElF;AAED,iBAAe,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEjF;AAED,iBAAe,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIpF;AAED,iBAAS,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAIpF;AAED,iBAAe,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAQtI;AAED,iBAAe,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEpE;AAED,iBAAe,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAErE;AAED,iBAAe,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYrE;AAED,iBAAe,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEtD;AAED,iBAAS,gBAAgB,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,EAAE,CAAA;AACpD,iBAAS,gBAAgB,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAOxF,iBAAe,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED,iBAAe,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAoBpF"}

package/library/agents.js

@@ -2,13 +2,15 @@
  * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import { RunXError } from './errors.js';
-import { homeDirectory, joinPath, resolvePath } from './path-utils.js';
-import { ensureDirectory, pathExists, readTextIfExists, removePath, writeTextFile } from './storage.js';
-export { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, };
+import { directoryName, homeDirectory, joinPath, resolvePath } from './path-utils.js';
+import { ensureDirectory, pathExists, readTextIfExists, removePath, writeTextFile, writeTextFileAtomic } from './storage.js';
+export { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, maintainAgentIntegration, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, };
 const skillId = 'guiho-s-runx';
 const promptId = 'guiho-i-runx';
 const managedStart = '<!-- BEGIN RUNX — DO NOT EDIT THIS SECTION -->';
 const managedEnd = '<!-- END RUNX -->';
+const legacyManagedStart = '<!-- BEGIN RUNX AGENT INSTRUCTIONS -->';
+const legacyManagedEnd = '<!-- END RUNX AGENT INSTRUCTIONS -->';
 async function installAgentSkill(scope, cwd) {
     return writeSkillTargets(scope, cwd);
 }
@@ -69,6 +71,26 @@ async function showAgentPrompt(id) {
         throw new RunXError(`Unknown RunX prompt: ${id}`, 2);
     return readBundledPrompt();
 }
+async function maintainAgentIntegration(cwd) {
+    const skill = await readBundledSkill();
+    const skills = [];
+    for (const directory of skillDirectories('global', cwd)) {
+        const path = joinPath(directory, 'SKILL.md');
+        if (await readTextIfExists(path) === skill)
+            continue;
+        await writeTextFileAtomic(path, skill);
+        skills.push(path);
+    }
+    const instructionPath = await nearestAgentsPath(cwd);
+    const existing = await readTextIfExists(instructionPath) ?? '';
+    const next = replaceManagedBlock(existing, instructionBlock());
+    const instructions = [];
+    if (next !== existing) {
+        await writeTextFileAtomic(instructionPath, next);
+        instructions.push(instructionPath);
+    }
+    return { skills, instructions };
+}
 async function writeSkillTargets(scope, cwd) {
     const skill = await readBundledSkill();
     const installed = [];
@@ -115,23 +137,48 @@ function instructionBlock() {
     return `${managedStart}
 ## RunX Command Catalog
 
-Load the \`guiho-s-runx\` skill before working with \`runx.yaml\`. Inspect with
-\`runx check --format json\` and \`runx list --format json\`, select stable UIDs,
-use \`runx run <uid> --dry-run\` before unfamiliar work, and add \`--yes\` only
-after explicit approval for a confirmation-gated command.
+Load the \`guiho-s-runx\` skill whenever discovering commands, creating or
+updating catalog entries, validating \`runx.yaml\`, inspecting command details,
+or executing RunX commands.
+Start with \`runx check --format json\` and \`runx list --format json\`, select
+stable UIDs, use \`runx describe <uid>\`, and run
+\`runx run <uid> --dry-run\` before unfamiliar or side-effecting work.
 ${managedEnd}
 `;
 }
 function replaceManagedBlock(existing, block) {
-    const pattern = new RegExp(`${escapeRegExp(managedStart)}[\\s\\S]*?${escapeRegExp(managedEnd)}\\s*`, 'g');
-    const stripped = existing.replace(pattern, '').trimEnd();
+    const stripped = removeKnownManagedBlocks(existing).trimEnd();
     return `${stripped}${stripped ? '\n\n' : ''}${block}`;
 }
 function removeManagedBlock(existing) {
-    const pattern = new RegExp(`\\s*${escapeRegExp(managedStart)}[\\s\\S]*?${escapeRegExp(managedEnd)}\\s*`, 'g');
-    const next = existing.replace(pattern, '\n').trimEnd();
+    const next = removeKnownManagedBlocks(existing, true).trimEnd();
     return next ? `${next}\n` : '';
 }
+function removeKnownManagedBlocks(existing, includeLeadingWhitespace = false) {
+    let output = existing;
+    for (const [start, end] of [
+        [managedStart, managedEnd],
+        [legacyManagedStart, legacyManagedEnd],
+    ]) {
+        const prefix = includeLeadingWhitespace ? '\\s*' : '';
+        const pattern = new RegExp(`${prefix}${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}\\s*`, 'g');
+        output = output.replace(pattern, includeLeadingWhitespace ? '\n' : '');
+    }
+    return output;
+}
+async function nearestAgentsPath(cwd) {
+    const effectiveCwd = resolvePath(cwd);
+    let current = effectiveCwd;
+    while (true) {
+        const candidate = joinPath(current, 'AGENTS.md');
+        if (await pathExists(candidate))
+            return candidate;
+        const parent = directoryName(current);
+        if (parent === current)
+            return joinPath(effectiveCwd, 'AGENTS.md');
+        current = parent;
+    }
+}
 async function readBundledSkill() {
     if (globalThis.__RUNX_EMBEDDED_RESOURCES__?.skill)
         return globalThis.__RUNX_EMBEDDED_RESOURCES__.skill;

package/library/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AA8BH,OAAO,KAAK,EAAkB,UAAU,EAAkB,MAAM,OAAO,CAAA;AAIvE,OAAO,EACL,MAAM,EACN,uBAAuB,EACvB,WAAW,GACZ,CAAA;AAsPD,QAAA,MAAiB,WAAW,iBAAwB,CAAA;AAEpD,iBAAe,MAAM,CAAC,OAAO,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB9E;AAED,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,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"}

package/library/cli.js

@@ -4,6 +4,7 @@
 import { Type } from '@sinclair/typebox';
 import { Value } from '@sinclair/typebox/value';
 import { defineCommand, renderUsage, runCommand as runCittyCommand } from 'citty';
+import { agentMaintenanceWorkerCwd, runAgentMaintenanceWorker, spawnAgentMaintenanceWorker } from './agent-maintenance.js';
 import { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, } from './agents.js';
 import { RunXError } from './errors.js';
 import { runCommand } from './executor.js';
@@ -12,7 +13,7 @@ import { initializeRunXManifest } from './init.js';
 import { readManifest, resolveCommand } from './manifest.js';
 import { resolvePath } from './path-utils.js';
 import { renderDescription, renderExecutionPlan, renderJson, renderList } from './render.js';
-import { fetchReleaseCatalog, resolveUpgradePlatform } from './release-catalog.js';
+import { fetchReleaseCatalog, paginateReleaseCatalog, resolveUpgradePlatform } from './release-catalog.js';
 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';
@@ -135,7 +136,7 @@ function createCommandTree() {
     const upgradeList = leaf('runx upgrade list', 'List RunX releases newest first.', {
         page: { type: 'string', valueHint: 'positive-integer', description: 'Select result page.' },
         'per-page': { type: 'string', valueHint: 'positive-integer', description: 'Select page size.' },
-        'pre-releases': { type: 'boolean', description: 'Include prerelease versions.' },
+        'pre-releases': { type: 'boolean', description: 'Accepted explicitly; prereleases are always included.' },
         arch: { type: 'string', valueHint: 'x64|arm64', description: 'Select target architecture.' },
         variant: { type: 'string', valueHint: 'baseline|default|modern', description: 'Select x64 variant.' },
         format: catalogArgs.format,
@@ -145,7 +146,11 @@ function createCommandTree() {
         args: { ...upgradeArgs, ...helpArgs },
         subCommands: { check: upgradeCheck, list: upgradeList },
         setup: helpSetup(state),
-        run: async () => runUpgrade(options(state.args), state.args),
+        run: async () => {
+            if (state.command === upgradeCheck || state.command === upgradeList)
+                return;
+            await runUpgrade(options(state.args), state.args);
+        },
     });
     state.commands.set('upgrade', upgrade);
     const uninstall = leaf('runx uninstall', 'Uninstall the native RunX executable.', {
@@ -229,6 +234,11 @@ async function runCli(rawArgs = process.argv.slice(2)) {
         await runUpdateWorker();
         return;
     }
+    const maintenanceWorkerCwd = agentMaintenanceWorkerCwd(rawArgs);
+    if (maintenanceWorkerCwd !== null) {
+        await runAgentMaintenanceWorker(maintenanceWorkerCwd);
+        return;
+    }
     const { command, state } = createCommandTree();
     const cleanOutput = rawArgs.some((arg) => ['-h', '--help', '-v', '--version', '--help-tree', '--help-docs'].includes(arg) || arg.startsWith('--help-tree-depth'));
     if (!cleanOutput) {
@@ -253,6 +263,14 @@ async function runCli(rawArgs = process.argv.slice(2)) {
             throw new CliUsageError(error.message, await renderUsage(state.command));
         throw error;
     }
+    finally {
+        if (shouldScheduleAgentMaintenance(rawArgs)) {
+            spawnAgentMaintenanceWorker(resolvePath(state.args.cwd ?? process.cwd()));
+        }
+    }
+}
+function shouldScheduleAgentMaintenance(rawArgs) {
+    return !['agent', 'uninstall'].includes(rawArgs[0] ?? '');
 }
 async function runCliWithErrorHandling(rawArgs) {
     try {
@@ -335,11 +353,10 @@ async function runUpgradeList(args) {
     const requestedArch = args.arch ? decode(archSchema, args.arch, '--arch') : process.arch;
     const platform = resolveUpgradePlatform(process.platform, requestedArch);
     const variant = decode(variantSchema, args.variant ?? 'baseline', '--variant');
-    const page = positiveInteger(args.page ?? '1', '--page');
-    const perPage = positiveInteger(args.perPage ?? '20', '--per-page');
+    const page = args.page ? positiveInteger(args.page, '--page') : undefined;
+    const perPage = args.perPage ? positiveInteger(args.perPage, '--per-page') : undefined;
     const catalog = await fetchReleaseCatalog({ ...platform, variant, currentVersion: readVersion() });
-    const filtered = args.preReleases ? catalog.releases : catalog.releases.filter((release) => !release.prerelease);
-    const paged = { ...catalog, releases: filtered.slice((page - 1) * perPage, page * perPage) };
+    const paged = paginateReleaseCatalog(catalog, page, perPage);
     write(options(args).format === 'json' ? renderJson(paged) : renderReleaseCatalog(paged));
 }
 async function runUpgrade(optionsValue, args) {

package/library/recovery.js

@@ -15,7 +15,7 @@ const createRecoveryInstructions = (targetVersion, os, targetSource = 'resolved'
     return {
         targetVersion,
         targetSource,
-        installCommand: `curl -fsSL ${installerBaseUrl}/install.sh | sh -s -- --version '${escapeShell(targetVersion)}'`,
+        installCommand: `curl -fsSL ${installerBaseUrl}/install.sh | bash -s -- --version '${escapeShell(targetVersion)}'`,
         stopProcessCommand: 'pkill -x runx',
     };
 };