@guiho/runx 0.4.0 → 0.5.1

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;AAuOD,QAAA,MAAiB,WAAW,iBAAwB,CAAA;AAEpD,iBAAe,MAAM,CAAC,OAAO,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB9E;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';
@@ -102,7 +103,14 @@ function createCommandTree() {
     const instruction = group('runx agent instruction', 'Manage RunX instruction blocks.', { apply: instructionApply, remove: instructionRemove, update: instructionUpdate, show: instructionShow }, state);
     const promptList = leaf('runx agent prompt list', 'List bundled RunX prompts.', {
         names: { type: 'boolean', description: 'Print prompt names only.' }, format: catalogArgs.format,
-    }, () => writeFormatted(listAgentPrompts(Boolean(state.args.names)), state.args));
+    }, () => {
+        if (state.args.names) {
+            const names = listAgentPrompts(true);
+            write(options(state.args).format === 'json' ? renderJson(names) : `${names.join('\n')}\n`);
+            return;
+        }
+        writeFormatted(listAgentPrompts(false), state.args);
+    });
     const promptShow = leaf('runx agent prompt show', 'Print one raw bundled prompt.', {
         id: { type: 'positional', description: 'Bundled prompt ID.' },
     }, async ({ args }) => {
@@ -112,14 +120,13 @@ function createCommandTree() {
     });
     const prompt = group('runx agent prompt', 'Inspect bundled agent prompts.', { list: promptList, show: promptShow }, state);
     const agent = group('runx agent', 'Manage RunX agent integration.', { skill, instruction, prompt }, state);
-    const upgradeApply = leaf('runx upgrade', 'Upgrade the canonical native RunX executable.', {
+    const upgradeArgs = {
         version: { type: 'string', valueHint: 'version', description: 'Select an exact release version.' },
         arch: { type: 'string', valueHint: 'x64|arm64', description: 'Select target architecture.' },
         variant: { type: 'string', valueHint: 'baseline|default|modern', description: 'Select x64 binary variant.' },
         'dry-run': { type: 'boolean', description: 'Plan without mutation.' },
         format: catalogArgs.format,
-    }, async () => runUpgrade(options(state.args), state.args));
-    upgradeApply.meta = { ...upgradeApply.meta, hidden: true };
+    };
     const upgradeCheck = leaf('runx upgrade check', 'Check whether a newer stable release exists.', {
         format: catalogArgs.format,
     }, async () => {
@@ -129,12 +136,23 @@ 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,
     }, async () => runUpgradeList(state.args));
-    const upgrade = group('runx upgrade', 'Inspect or upgrade a native RunX executable.', { _apply: upgradeApply, check: upgradeCheck, list: upgradeList }, state, '_apply');
+    const upgrade = defineCommand({
+        meta: { name: 'runx upgrade', description: 'Inspect or upgrade a native RunX executable.' },
+        args: { ...upgradeArgs, ...helpArgs },
+        subCommands: { check: upgradeCheck, list: upgradeList },
+        setup: helpSetup(state),
+        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.', {
         'dry-run': { type: 'boolean', description: 'Print the target without deleting it.' }, format: catalogArgs.format,
     }, async () => {
@@ -149,8 +167,9 @@ function createCommandTree() {
             state.args = context.args;
             state.command = resolveHelpCommand(state);
             await validateInvocation(state);
-            if (state.args.v || state.args.version === true)
+            if (context.rawArgs.length === 1 && ['-v', '--version'].includes(context.rawArgs[0] ?? '')) {
                 return handled(`${readVersion()}\n`);
+            }
             await handleHelp(state);
         },
         run: ({ args }) => {
@@ -215,12 +234,21 @@ 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 && rawArgs.length > 0) {
+    if (!cleanOutput) {
         const notice = await readCachedUpdateNotice(rawArgs.includes('--verbose'));
-        if (notice)
-            process.stderr.write(`${notice}\n`);
+        if (notice) {
+            if (rawArgs.length === 0)
+                write(`${notice}\n`);
+            else
+                process.stderr.write(`${notice}\n`);
+        }
     }
     spawnUpdateWorker();
     try {
@@ -235,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 {
@@ -317,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',
     };
 };

package/library/release-catalog.d.ts

@@ -2,7 +2,7 @@
  * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import type { ReleaseAsset, ReleaseCatalog, UpgradeArch, UpgradeOs, UpgradeVariant } from './upgrade-types.js';
-export { assetCandidates, fetchReleaseCatalog, findCompatibleAsset, normalizeReleaseVersion, resolveUpgradePlatform, };
+export { assetCandidates, fetchReleaseCatalog, findCompatibleAsset, normalizeReleaseVersion, paginateReleaseCatalog, resolveUpgradePlatform, };
 declare const githubReleaseSchema: import("@sinclair/typebox").TObject<{
     tag_name: import("@sinclair/typebox").TString;
     draft: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
@@ -29,4 +29,5 @@ declare const findCompatibleAsset: (release: GitHubRelease, platform: ReleasePla
 declare const assetCandidates: ({ os, arch, variant }: ReleasePlatform) => string[];
 declare const resolveUpgradePlatform: (platform?: NodeJS.Platform, architecture?: NodeJS.Architecture) => ReleasePlatform;
 declare const normalizeReleaseVersion: (tag: string) => string;
+declare const paginateReleaseCatalog: (catalog: ReleaseCatalog, page?: number, perPage?: number) => ReleaseCatalog;
 //# sourceMappingURL=release-catalog.d.ts.map

package/library/release-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release-catalog.d.ts","sourceRoot":"","sources":["../source/release-catalog.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAuB,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEnI,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,GACvB,CAAA;AAED,QAAA,MAAM,mBAAmB;;;;;;;;;;EAUS,CAAA;AAIlC,MAAM,MAAM,aAAa,GAAG,OAAO,mBAAmB,EAAE,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE1F,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,SAAS,CAAA;IACb,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,KAAK,mBAAmB,GAAG,eAAe,GAAG;IAC3C,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB,CAAA;AAID,QAAA,MAAM,mBAAmB,YAAmB,mBAAmB,KAAG,OAAO,CAAC,cAAc,CAoCvF,CAAA;AAkBD,QAAA,MAAM,mBAAmB,YAAa,aAAa,YAAY,eAAe,KAAG,YAAY,GAAG,IAM/F,CAAA;AAED,QAAA,MAAM,eAAe,0BAA2B,eAAe,KAAG,MAAM,EAUvE,CAAA;AAED,QAAA,MAAM,sBAAsB,sEAA+D,eAM1F,CAAA;AAED,QAAA,MAAM,uBAAuB,QAAS,MAAM,KAAG,MAA6D,CAAA"}
+{"version":3,"file":"release-catalog.d.ts","sourceRoot":"","sources":["../source/release-catalog.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAuB,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEnI,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,GACvB,CAAA;AAED,QAAA,MAAM,mBAAmB;;;;;;;;;;EAUS,CAAA;AAIlC,MAAM,MAAM,aAAa,GAAG,OAAO,mBAAmB,EAAE,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE1F,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,SAAS,CAAA;IACb,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,KAAK,mBAAmB,GAAG,eAAe,GAAG;IAC3C,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB,CAAA;AAID,QAAA,MAAM,mBAAmB,YAAmB,mBAAmB,KAAG,OAAO,CAAC,cAAc,CAoCvF,CAAA;AAkBD,QAAA,MAAM,mBAAmB,YAAa,aAAa,YAAY,eAAe,KAAG,YAAY,GAAG,IAM/F,CAAA;AAED,QAAA,MAAM,eAAe,0BAA2B,eAAe,KAAG,MAAM,EAUvE,CAAA;AAED,QAAA,MAAM,sBAAsB,sEAA+D,eAM1F,CAAA;AAED,QAAA,MAAM,uBAAuB,QAAS,MAAM,KAAG,MAA6D,CAAA;AAE5G,QAAA,MAAM,sBAAsB,YAAa,cAAc,SAAS,MAAM,YAAY,MAAM,KAAG,cAM1F,CAAA"}

package/library/release-catalog.js

@@ -5,7 +5,7 @@ import { Type } from '@sinclair/typebox';
 import { Value } from '@sinclair/typebox/value';
 import { compare, parse, valid } from 'semver';
 import { RunXError } from './errors.js';
-export { assetCandidates, fetchReleaseCatalog, findCompatibleAsset, normalizeReleaseVersion, resolveUpgradePlatform, };
+export { assetCandidates, fetchReleaseCatalog, findCompatibleAsset, normalizeReleaseVersion, paginateReleaseCatalog, resolveUpgradePlatform, };
 const githubReleaseSchema = Type.Object({
     tag_name: Type.String(),
     draft: Type.Optional(Type.Boolean()),
@@ -100,6 +100,14 @@ const resolveUpgradePlatform = (platform = process.platform, architecture = proc
     return { os, arch, variant: 'baseline' };
 };
 const normalizeReleaseVersion = (tag) => tag.replace(/^@guiho\/runx@/, '').replace(/^v/, '');
+const paginateReleaseCatalog = (catalog, page, perPage) => {
+    if (page === undefined && perPage === undefined)
+        return catalog;
+    const selectedPage = page ?? 1;
+    const selectedPageSize = perPage ?? 20;
+    const start = (selectedPage - 1) * selectedPageSize;
+    return { ...catalog, releases: catalog.releases.slice(start, start + selectedPageSize) };
+};
 const releaseChannel = (version, prerelease) => {
     const parsed = parse(version);
     if (!parsed)

package/library/storage.d.ts

@@ -1,7 +1,7 @@
 /**
  * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
-export { copyTextFile, ensureDirectory, globalRunXDirectory, movePath, pathExists, readTextIfExists, removePath, writeTextFile, };
+export { copyTextFile, ensureDirectory, globalRunXDirectory, movePath, pathExists, readTextIfExists, removePath, writeTextFile, writeTextFileAtomic, };
 declare function globalRunXDirectory(): string;
 declare function pathExists(path: string): Promise<boolean>;
 declare function ensureDirectory(path: string): Promise<void>;
@@ -9,5 +9,6 @@ declare function removePath(path: string): Promise<void>;
 declare function movePath(from: string, to: string): Promise<void>;
 declare function readTextIfExists(path: string): Promise<string | null>;
 declare function writeTextFile(path: string, value: string): Promise<void>;
+declare function writeTextFileAtomic(path: string, value: string): Promise<void>;
 declare function copyTextFile(source: string, target: string): Promise<void>;
 //# sourceMappingURL=storage.d.ts.map

package/library/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../source/storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,aAAa,GACd,CAAA;AAED,iBAAS,mBAAmB,IAAI,MAAM,CAErC;AAED,iBAAe,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExD;AAED,iBAAe,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED,iBAAe,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErD;AAED,iBAAe,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/D;AAED,iBAAe,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEpE;AAED,iBAAe,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE;AAED,iBAAe,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../source/storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,mBAAmB,GACpB,CAAA;AAED,iBAAS,mBAAmB,IAAI,MAAM,CAErC;AAED,iBAAe,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExD;AAED,iBAAe,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED,iBAAe,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErD;AAED,iBAAe,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/D;AAED,iBAAe,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEpE;AAED,iBAAe,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE;AAED,iBAAe,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU7E;AAED,iBAAe,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE"}

package/library/storage.js

@@ -3,7 +3,7 @@
  */
 import { $ } from 'bun';
 import { directoryName, homeDirectory, joinPath } from './path-utils.js';
-export { copyTextFile, ensureDirectory, globalRunXDirectory, movePath, pathExists, readTextIfExists, removePath, writeTextFile, };
+export { copyTextFile, ensureDirectory, globalRunXDirectory, movePath, pathExists, readTextIfExists, removePath, writeTextFile, writeTextFileAtomic, };
 function globalRunXDirectory() {
     return joinPath(homeDirectory(), '.guiho', 'runx');
 }
@@ -33,6 +33,18 @@ async function writeTextFile(path, value) {
     await ensureDirectory(directoryName(path));
     await Bun.write(path, value);
 }
+async function writeTextFileAtomic(path, value) {
+    await ensureDirectory(directoryName(path));
+    const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    try {
+        await Bun.write(temporary, value);
+        await movePath(temporary, path);
+    }
+    catch (error) {
+        await removePath(temporary);
+        throw error;
+    }
+}
 async function copyTextFile(source, target) {
     await writeTextFile(target, await Bun.file(source).text());
 }

package/package.json

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

package/skills/guiho-s-runx/SKILL.md

@@ -76,3 +76,14 @@ runx upgrade --dry-run
 
 Use `--help`, `--help-tree`, or `--help-docs` at any command scope for the
 current executable contract.
+
+## Automatic Agent Maintenance
+
+Ordinary RunX commands schedule a silent, non-blocking worker that keeps the
+bundled skill current in both global agent-tool directories and reconciles one
+compact managed block in the nearest `AGENTS.md`. A current installation is not
+rewritten. Automatic failures never fail or pollute the foreground command.
+
+Explicit `runx agent ...` commands remain the manual repair and local-scope
+interface. Explicit agent-resource removal and `runx uninstall` do not schedule
+automatic reinstallation.

package/skills/guiho-s-runx/guiho-s-runx.xdocs.md

@@ -1,6 +1,6 @@
 ---
 subject: guiho-s-runx
-description: Agent workflow for safe RunX catalog execution and verified native upgrade/list/recovery operations.
+description: Agent workflow for safe RunX catalog work, automatic resource maintenance, and verified native upgrade/list/recovery operations.
 parent: runx-skills
 children: []
 files:
@@ -17,6 +17,7 @@ keywords:
   - dry run
   - runx upgrade
   - recovery install
+  - automatic maintenance
 flags: []
 status: stable
 ---
@@ -24,3 +25,5 @@ status: stable
 The skill makes manifest inspection, UID selection, dry runs, and explicit
 confirmation the default agent workflow for RunX commands and teaches agents
 how to interpret transactional native upgrades and their recovery contract.
+Ordinary RunX invocations also reconcile the current global skill and nearest
+managed project instruction block through a silent detached worker.