@guiho/runx 0.2.0

package/library/manifest.js

@@ -0,0 +1,112 @@
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { Type } from '@sinclair/typebox';
+import { TypeCompiler } from '@sinclair/typebox/compiler';
+import { RunXError, invariant } from './errors.js';
+const identifier = '^[a-z][a-z0-9-]*$';
+export const CommandSchema = Type.Object({
+    uid: Type.String({ pattern: identifier }),
+    id: Type.String({ pattern: identifier }),
+    group: Type.String({ pattern: identifier }),
+    summary: Type.String({ minLength: 1 }),
+    description: Type.String({ minLength: 1 }),
+    command: Type.String({ minLength: 1 }),
+    cwd: Type.Optional(Type.String({ minLength: 1 })),
+    shell: Type.Optional(Type.Union([
+        Type.Literal('auto'),
+        Type.Literal('bash'),
+        Type.Literal('sh'),
+        Type.Literal('powershell'),
+        Type.Literal('cmd'),
+    ])),
+    tags: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    confirm: Type.Optional(Type.Union([Type.Literal('never'), Type.Literal('always')])),
+}, { additionalProperties: false });
+export const ManifestSchema = Type.Object({
+    version: Type.Literal(1),
+    project: Type.Optional(Type.Object({ name: Type.String({ minLength: 1 }) }, { additionalProperties: false })),
+    groups: Type.Record(Type.String({ pattern: identifier }), Type.Object({ summary: Type.String({ minLength: 1 }) }, { additionalProperties: false })),
+    commands: Type.Array(CommandSchema, { minItems: 1 }),
+}, { additionalProperties: false });
+const manifestCheck = TypeCompiler.Compile(ManifestSchema);
+export const findManifest = async (cwd, explicitFile) => {
+    if (explicitFile) {
+        const candidate = resolve(cwd, explicitFile);
+        if (await Bun.file(candidate).exists())
+            return candidate;
+        throw new RunXError(`Manifest not found: ${candidate}`);
+    }
+    let current = resolve(cwd);
+    while (true) {
+        const candidate = resolve(current, 'runx.yaml');
+        if (await Bun.file(candidate).exists())
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    throw new RunXError('No runx.yaml found. Run this command inside a configured project or pass --file <path>.');
+};
+export const readManifest = async (cwd, explicitFile) => {
+    const path = await findManifest(cwd, explicitFile);
+    let parsed;
+    try {
+        parsed = Bun.YAML.parse(await Bun.file(path).text());
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown YAML parsing error.';
+        throw new RunXError(`Invalid YAML in ${path}: ${message}`);
+    }
+    if (!manifestCheck.Check(parsed)) {
+        const errors = [...manifestCheck.Errors(parsed)].map((error) => `${error.path || '/'}: ${error.message}`);
+        throw new RunXError(`Invalid RunX manifest ${path}:\n${errors.join('\n')}`);
+    }
+    const manifest = parsed;
+    validateManifestSemantics(manifest, path);
+    return { manifest, path };
+};
+export const resolveCommand = (manifest, manifestPath, selector) => {
+    const commands = manifest.commands;
+    let command = commands.find((entry) => entry.uid === selector);
+    if (!command && selector.includes('/')) {
+        command = commands.find((entry) => `${entry.group}/${entry.id}` === selector);
+    }
+    if (!command && /^\d+$/.test(selector)) {
+        command = commands[Number.parseInt(selector, 10) - 1];
+    }
+    if (!command) {
+        const matches = commands.filter((entry) => entry.id === selector);
+        if (matches.length > 1) {
+            throw new RunXError(`Ambiguous command ID "${selector}". Use one of: ${matches.map((entry) => `${entry.group}/${entry.id} (${entry.uid})`).join(', ')}`);
+        }
+        command = matches[0];
+    }
+    if (!command)
+        throw new RunXError(`Unknown command selector: ${selector}`);
+    const manifestDirectory = dirname(manifestPath);
+    const commandCwd = resolve(manifestDirectory, command.cwd ?? '.');
+    const relativeCwd = relative(manifestDirectory, commandCwd);
+    invariant(!isAbsolute(relativeCwd) && !relativeCwd.startsWith('..'), `Command ${command.uid} has a cwd outside the manifest directory.`);
+    return {
+        ...command,
+        index: commands.indexOf(command) + 1,
+        selector: `${command.group}/${command.id}`,
+        manifestPath,
+        cwd: commandCwd,
+    };
+};
+const validateManifestSemantics = (manifest, path) => {
+    const uids = new Set();
+    const selectors = new Set();
+    for (const command of manifest.commands) {
+        if (!manifest.groups[command.group])
+            throw new RunXError(`Command ${command.uid} references unknown group "${command.group}" in ${path}.`);
+        if (uids.has(command.uid))
+            throw new RunXError(`Duplicate command UID "${command.uid}" in ${path}.`);
+        const selector = `${command.group}/${command.id}`;
+        if (selectors.has(selector))
+            throw new RunXError(`Duplicate command selector "${selector}" in ${path}.`);
+        uids.add(command.uid);
+        selectors.add(selector);
+    }
+};

package/library/render.d.ts

@@ -0,0 +1,6 @@
+import type { ResolvedCommand, RunXManifest } from './types.js';
+export declare const renderJson: (value: unknown) => string;
+export declare const renderList: (manifest: RunXManifest, manifestPath: string) => string;
+export declare const renderDescription: (command: ResolvedCommand) => string;
+export declare const renderExecutionPlan: (command: ResolvedCommand) => string;
+//# sourceMappingURL=render.d.ts.map

package/library/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../source/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE/D,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,MAA+C,CAAA;AAE3F,eAAO,MAAM,UAAU,aAAc,YAAY,gBAAgB,MAAM,KAAG,MAoBzE,CAAA;AAED,eAAO,MAAM,iBAAiB,YAAa,eAAe,KAAG,MAW1C,CAAA;AAEnB,eAAO,MAAM,mBAAmB,YAAa,eAAe,KAAG,MAO5C,CAAA"}

package/library/render.js

@@ -0,0 +1,40 @@
+export const renderJson = (value) => JSON.stringify(value, null, 2) + '\n';
+export const renderList = (manifest, manifestPath) => {
+    const rows = manifest.commands.map((command, index) => ({
+        index: index + 1,
+        uid: command.uid,
+        selector: `${command.group}/${command.id}`,
+        summary: command.summary,
+        confirm: command.confirm ?? 'never',
+    }));
+    const width = (key, label) => Math.max(label.length, ...rows.map((row) => String(row[key]).length));
+    const indexWidth = width('index', 'IDX');
+    const uidWidth = width('uid', 'UID');
+    const selectorWidth = width('selector', 'SELECTOR');
+    const lines = [`RunX commands from ${manifestPath}`, '', `${'IDX'.padEnd(indexWidth)}  ${'UID'.padEnd(uidWidth)}  ${'SELECTOR'.padEnd(selectorWidth)}  SUMMARY`];
+    for (const row of rows) {
+        const confirmation = row.confirm === 'always' ? ' [confirm]' : '';
+        lines.push(`${String(row.index).padEnd(indexWidth)}  ${row.uid.padEnd(uidWidth)}  ${row.selector.padEnd(selectorWidth)}  ${row.summary}${confirmation}`);
+    }
+    return lines.join('\n') + '\n';
+};
+export const renderDescription = (command) => [
+    `${command.uid} (${command.selector})`,
+    '',
+    command.description,
+    '',
+    `index: ${command.index}`,
+    `cwd: ${command.cwd}`,
+    `shell: ${command.shell ?? 'auto'}`,
+    `confirmation: ${command.confirm ?? 'never'}`,
+    `tags: ${(command.tags ?? []).join(', ') || 'none'}`,
+    `command: ${command.command}`,
+].join('\n') + '\n';
+export const renderExecutionPlan = (command) => [
+    `uid: ${command.uid}`,
+    `selector: ${command.selector}`,
+    `manifest: ${command.manifestPath}`,
+    `cwd: ${command.cwd}`,
+    `shell: ${command.shell ?? 'auto'}`,
+    `command: ${command.command}`,
+].join('\n') + '\n';

package/library/self-management.d.ts

@@ -0,0 +1,13 @@
+import type { UpdateResult } from './types.js';
+export declare const checkForLatestVersion: () => Promise<UpdateResult>;
+export declare const listAvailableVersions: () => Promise<string[]>;
+export declare const upgradeSelf: (dryRun: boolean) => Promise<UpdateResult & {
+    executablePath: string;
+    scheduled: boolean;
+}>;
+export declare const uninstallSelf: (dryRun: boolean) => Promise<{
+    executablePath: string;
+    scheduled: boolean;
+    dryRun: boolean;
+}>;
+//# sourceMappingURL=self-management.d.ts.map

package/library/self-management.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-management.d.ts","sourceRoot":"","sources":["../source/self-management.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAM9C,eAAO,MAAM,qBAAqB,QAAa,OAAO,CAAC,YAAY,CAYlE,CAAA;AAED,eAAO,MAAM,qBAAqB,QAAa,OAAO,CAAC,MAAM,EAAE,CAK9D,CAAA;AAED,eAAO,MAAM,WAAW,WAAkB,OAAO,KAAG,OAAO,CAAC,YAAY,GAAG;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAkBxH,CAAA;AAED,eAAO,MAAM,aAAa,WAAkB,OAAO,KAAG,OAAO,CAAC;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAW5H,CAAA"}

package/library/self-management.js

@@ -0,0 +1,82 @@
+import { chmod, rename, rm } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { RunXError } from './errors.js';
+import { readVersion } from './help.js';
+const repositoryApi = 'https://api.github.com/repos/CGuiho/runx/releases';
+export const checkForLatestVersion = async () => {
+    const currentVersion = readVersion();
+    try {
+        const response = await fetch(`${repositoryApi}/latest`, { headers: { accept: 'application/vnd.github+json' } });
+        if (!response.ok)
+            return { currentVersion, latestVersion: currentVersion, updateAvailable: false };
+        const release = await response.json();
+        const latestVersion = release.tag_name.replace(/^@guiho\/runx@/, '').replace(/^v/, '');
+        const asset = findAsset(release);
+        return { currentVersion, latestVersion, updateAvailable: compareVersions(latestVersion, currentVersion) > 0, url: asset?.browser_download_url };
+    }
+    catch {
+        return { currentVersion, latestVersion: currentVersion, updateAvailable: false };
+    }
+};
+export const listAvailableVersions = async () => {
+    const response = await fetch(`${repositoryApi}?per_page=20`, { headers: { accept: 'application/vnd.github+json' } });
+    if (!response.ok)
+        throw new RunXError(`Could not retrieve RunX releases: HTTP ${response.status}`);
+    const releases = await response.json();
+    return releases.map((release) => release.tag_name.replace(/^@guiho\/runx@/, '').replace(/^v/, ''));
+};
+export const upgradeSelf = async (dryRun) => {
+    const executablePath = requireNativeExecutable();
+    const update = await checkForLatestVersion();
+    if (!update.updateAvailable || !update.url)
+        return { ...update, executablePath, scheduled: false };
+    if (dryRun)
+        return { ...update, executablePath, scheduled: false };
+    const response = await fetch(update.url);
+    if (!response.ok)
+        throw new RunXError(`Could not download RunX update: HTTP ${response.status}`);
+    const temporaryPath = `${executablePath}.new`;
+    await Bun.write(temporaryPath, await response.arrayBuffer());
+    if (process.platform !== 'win32') {
+        await chmod(temporaryPath, 0o755);
+        await rename(temporaryPath, executablePath);
+        return { ...update, executablePath, scheduled: false };
+    }
+    scheduleWindowsReplacement(temporaryPath, executablePath);
+    return { ...update, executablePath, scheduled: true };
+};
+export const uninstallSelf = async (dryRun) => {
+    const executablePath = requireNativeExecutable();
+    if (dryRun)
+        return { executablePath, scheduled: false, dryRun: true };
+    if (process.platform === 'win32') {
+        const command = `ping 127.0.0.1 -n 2 > nul & del /f /q "${executablePath}"`;
+        Bun.spawn(['cmd.exe', '/d', '/s', '/c', command], { detached: true, stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
+        return { executablePath, scheduled: true, dryRun: false };
+    }
+    await rm(executablePath);
+    return { executablePath, scheduled: false, dryRun: false };
+};
+const findAsset = (release) => release.assets.find((asset) => asset.name === assetName());
+const assetName = () => `runx-${process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'darwin' : 'linux'}-${process.arch}${process.platform === 'win32' ? '.exe' : ''}`;
+const requireNativeExecutable = () => {
+    const executablePath = process.execPath;
+    if (basename(executablePath).toLowerCase().startsWith('bun'))
+        throw new RunXError('Self-management requires a native RunX executable installed from a GitHub release.');
+    return executablePath;
+};
+const scheduleWindowsReplacement = (temporaryPath, executablePath) => {
+    const command = `ping 127.0.0.1 -n 2 > nul & move /y "${temporaryPath}" "${executablePath}" > nul`;
+    Bun.spawn(['cmd.exe', '/d', '/s', '/c', command], { detached: true, stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
+};
+const compareVersions = (left, right) => {
+    const parse = (value) => value.split(/[.+-]/).map((part) => Number.parseInt(part, 10) || 0);
+    const a = parse(left);
+    const b = parse(right);
+    for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+        const difference = (a[index] ?? 0) - (b[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+};

package/library/types.d.ts

@@ -0,0 +1,31 @@
+import type { Static } from '@sinclair/typebox';
+import type { CommandSchema, ManifestSchema } from './manifest.js';
+export type RunXManifest = Static<typeof ManifestSchema>;
+export type RunXCommand = Static<typeof CommandSchema>;
+export type ResolvedCommand = RunXCommand & {
+    index: number;
+    selector: string;
+    manifestPath: string;
+    cwd: string;
+};
+export type OutputFormat = 'text' | 'json';
+export type ParsedArgs = {
+    command?: string;
+    positionals: string[];
+    flags: Record<string, boolean | string | string[]>;
+};
+export type CliOptions = {
+    cwd: string;
+    file?: string;
+    format: OutputFormat;
+    verbose: boolean;
+};
+export type AgentTool = 'agents' | 'claude' | 'all';
+export type AgentScope = 'local' | 'global';
+export type UpdateResult = {
+    currentVersion: string;
+    latestVersion: string;
+    updateAvailable: boolean;
+    url?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/library/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAElE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAA;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAA;AAEtD,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAA;AAE1C,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;CACnD,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEnD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE3C,MAAM,MAAM,YAAY,GAAG;IACzB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,OAAO,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@guiho/runx",
+  "description": "A language-agnostic, documented command catalog and local CLI executor.",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./library/guiho-runx.js",
+  "types": "./library/guiho-runx.d.ts",
+  "exports": {
+    ".": {
+      "types": "./library/guiho-runx.d.ts",
+      "import": "./library/guiho-runx.js"
+    }
+  },
+  "bin": {
+    "runx": "scripts/runx-bin.ts"
+  },
+  "files": [
+    "library/",
+    "scripts/",
+    "skills/",
+    "docs/",
+    "devops/",
+    "README.md",
+    "DOCS.md",
+    "CHANGELOG.md",
+    "LICENSE.md",
+    "SECURITY.md"
+  ],
+  "keywords": [
+    "automation",
+    "bun",
+    "cli",
+    "commands",
+    "runx",
+    "task-runner",
+    "yaml"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Cristovao GUIHO",
+    "email": "cg@guiho.co",
+    "url": "https://guiho.co/cg"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CGuiho/runx.git"
+  },
+  "homepage": "https://github.com/CGuiho/runx#readme",
+  "bugs": {
+    "url": "https://github.com/CGuiho/runx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run --watch source/guiho-runx-bin.ts",
+    "build": "rm -rf library && tsc -p .",
+    "binary": "bun build source/guiho-runx-native-bin.ts --compile --outfile bin/runx",
+    "binaries": "bun run devops/build-binaries.ts",
+    "test": "bun test",
+    "typecheck": "tsc -p . --noEmit",
+    "check": "bun run typecheck && bun test",
+    "clean": "rm -rf .temp",
+    "clean-build": "rm -rf library bundle bin",
+    "clean-installation": "rm -rf node_modules bun.lock",
+    "_tc": "bun run typecheck",
+    "_ci": "bun run clean && bun run clean-build && bun run clean-installation",
+    "_uid": "bun nanoid --alphabet abcdefghijklmnopqrstuvwxyz0123456789"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.52"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^7.0.2"
+  }
+}

package/scripts/runx-bin.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+
+const args = process.argv.slice(2)
+const binaryPath = new URL(`../vendor/runx${process.platform === 'win32' ? '.exe' : ''}`, import.meta.url)
+const sourcePath = new URL('../source/guiho-runx-bin.ts', import.meta.url)
+
+if (await Bun.file(binaryPath).exists()) {
+  const child = Bun.spawn([Bun.fileURLToPath(binaryPath), ...args], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
+  process.exit(await child.exited)
+}
+
+if (await Bun.file(sourcePath).exists()) {
+  const child = Bun.spawn([process.execPath, Bun.fileURLToPath(sourcePath), ...args], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
+  process.exit(await child.exited)
+}
+
+console.error('error: RunX executable is unavailable. Install an official native release or reinstall @guiho/runx.')
+process.exit(1)

package/scripts/scripts.xdocs.md

@@ -0,0 +1,20 @@
+---
+subject: runx-scripts
+description: Package-manager launcher scripts for RunX.
+parent: runx
+children: []
+files:
+  runx-bin.ts: Executes a packaged native binary when present or the source CLI in a checkout.
+documents: {}
+tags:
+  - scripts
+  - cli
+keywords:
+  - runx
+  - launcher
+flags: []
+status: stable
+---
+
+The package launcher preserves the `runx` bin command in development checkouts
+and installed packages.

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

@@ -0,0 +1,57 @@
+---
+name: guiho-s-runx
+description: Use when inspecting, creating, validating, organizing, documenting, or running a RunX `runx.yaml` command catalog. This includes listing available project commands, choosing a command by UID or selector, reviewing command descriptions, dry runs, confirmation-gated execution, and agent-safe project automation.
+---
+
+# GUIHO RunX
+
+Use RunX as the command catalog for a project. It documents executable local
+commands but does not make them inherently safe: a manifest is trusted code.
+
+## Inspect Before Executing
+
+1. From the intended project directory, run `runx check --format json`.
+2. Run `runx list --format json` to inspect groups, UIDs, summaries, tags, and
+   confirmation requirements.
+3. Choose a stable `uid` for automation. An index is only for the current list
+   and an unqualified ID can be ambiguous.
+4. Run `runx describe <uid>` before an unfamiliar or high-impact command.
+5. Run `runx run <uid> --dry-run` before a real execution when the command has
+   filesystem, database, release, deployment, or production effects.
+
+## Execute Safely
+
+- Use `runx run <uid>` or the short alias `runx r <uid>`.
+- `runx <selector>` is allowed as a human shorthand only when it cannot be
+  confused with a built-in command; agents should prefer explicit `runx run`.
+- If `confirm: always` is set, RunX requires `--yes`.
+- Add `--yes` only after the user explicitly authorizes the specific command.
+- Do not treat a group name such as `development` or `operations` as a safety
+  guarantee. Read the command description and command text.
+- Do not add secrets to `runx.yaml`. Use the project's existing environment or
+  secret-management workflow.
+
+## Maintain Manifests
+
+- Keep `uid`, `id`, `group`, `summary`, `description`, and `command` present.
+- Keep UIDs stable; never reuse a UID for a materially different command.
+- Use a group for organization, a concise summary for listings, and a complete
+  description for prerequisites, effects, and risk.
+- Set `confirm: always` for destructive, release, deployment, migration, and
+  production-impacting commands when confirmation is useful.
+- Run `runx check` after every manifest change. It rejects unknown fields,
+  duplicate UIDs/selectors, missing descriptions, invalid working directories,
+  and unsupported shell choices.
+
+## Useful Commands
+
+```text
+runx                         Show the RunX home page and usage.
+runx list                    List the nearest manifest.
+runx describe <uid>          Explain one command without execution.
+runx run <uid> --dry-run     Inspect the execution plan.
+runx r <uid>                 Run through the short alias.
+runx agents install local    Install this skill into .agents/skills.
+runx --help-tree             Show the command hierarchy.
+runx --help-docs             Show manifest documentation guidance.
+```

package/skills/guiho-s-runx/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "RunX"
+  short_description: "Manage documented RunX command catalogs safely."
+  default_prompt: "Use the RunX CLI to inspect, validate, and run commands from runx.yaml safely."

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

@@ -0,0 +1,22 @@
+---
+subject: guiho-s-runx
+description: Agent workflow for inspecting, validating, and safely executing RunX manifest commands.
+parent: runx-skills
+children: []
+files:
+  SKILL.md: RunX-specific agent instructions and safe execution workflow.
+documents:
+  SKILL.md: RunX-specific agent instructions and safe execution workflow.
+tags:
+  - agents
+  - runx
+keywords:
+  - runx
+  - command catalog
+  - dry run
+flags: []
+status: stable
+---
+
+The skill makes manifest inspection, UID selection, dry runs, and explicit
+confirmation the default agent workflow for RunX commands.

package/skills/skills.xdocs.md

@@ -0,0 +1,19 @@
+---
+subject: runx-skills
+description: Bundled agent skills that teach AI agents to operate RunX command catalogs safely.
+parent: runx
+children:
+  - guiho-s-runx
+files: {}
+documents: {}
+tags:
+  - agents
+  - skills
+keywords:
+  - runx
+  - agent skill
+flags: []
+status: stable
+---
+
+Bundled skills ship with RunX and can be installed through `runx agents install`.