@artblocks/abx-cli 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/flags.d.ts

@@ -12,6 +12,12 @@
 export type Flags = Record<string, string | undefined>;
 /** Flags where every occurrence counts (values comma-join, in argv order). */
 export declare const REPEATABLE_FLAGS: ReadonlySet<string>;
+/**
+ * Flags valid on ANY command (handled centrally in main, not by a command handler), so
+ * {@link unknownFlags} never flags them as unrecognized regardless of the per-command allowlist.
+ * `no-update-check` opts out of the startup update nudge (see update-check.ts).
+ */
+export declare const GLOBAL_FLAGS: ReadonlySet<string>;
 export declare function parseFlags(args: string[]): Flags;
 /**
  * The flag keys in `flags` that are NOT in `allowed` — for a non-fatal "unrecognized flag"

package/dist/flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEvD,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAA8B,CAAC;AAEhF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAchD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAG9E"}
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEvD,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAA8B,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAAgC,CAAC;AAE9E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAchD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAG9E"}

package/dist/flags.js

@@ -1,5 +1,11 @@
 /** Flags where every occurrence counts (values comma-join, in argv order). */
 export const REPEATABLE_FLAGS = new Set(['dep', 'schema']);
+/**
+ * Flags valid on ANY command (handled centrally in main, not by a command handler), so
+ * {@link unknownFlags} never flags them as unrecognized regardless of the per-command allowlist.
+ * `no-update-check` opts out of the startup update nudge (see update-check.ts).
+ */
+export const GLOBAL_FLAGS = new Set(['no-update-check']);
 export function parseFlags(args) {
     const out = {};
     const set = (k, v) => {
@@ -29,6 +35,6 @@ export function parseFlags(args) {
  */
 export function unknownFlags(flags, allowed) {
     const ok = new Set(allowed);
-    return Object.keys(flags).filter((k) => !ok.has(k));
+    return Object.keys(flags).filter((k) => !ok.has(k) && !GLOBAL_FLAGS.has(k));
 }
 //# sourceMappingURL=flags.js.map

package/dist/flags.js.map

@@ -1 +1 @@
-{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAaA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEhF,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,MAAM,GAAG,GAAU,EAAE,CAAC;IACtB,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE;QACnC,GAAG,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC,CAAC;IACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAClC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;aAC/C,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;;YAC7E,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAY,EAAE,OAAyB;IAClE,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACtD,CAAC"}
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAaA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAE9E,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,MAAM,GAAG,GAAU,EAAE,CAAC;IACtB,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE;QACnC,GAAG,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC,CAAC;IACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAClC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;aAC/C,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;;YAC7E,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAY,EAAE,OAAyB;IAClE,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC"}

package/dist/main.js

@@ -34,13 +34,14 @@
  *   abx storage backup-key   copy the managed Turbo/Arweave key (holds credits) to a safe path
  *   abx status               list indexed projects + node info
  *   abx doctor               check environment (key, RPC, balance, factory, storage)
- *   abx skill install        install the abx agent skill into your agent (.claude/skills; --global)
+ *   abx skill install        install the version-locked abx agent skill into your agent(s)
+ *                            (default: Claude Code + the neutral .agents/skills; --agent/--global)
  *
  * Every write picks a signing lane: default hot (env key signs), `--sign` (a human
  * approves in their own wallet via a one-shot localhost page), `--unsigned` (print
  * the tx for a multisig / offline signer). The agent picks the lane; the CLI signs.
  */
-import { appendFileSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { basename, extname, join as joinPath, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -54,6 +55,7 @@ import { DEP_RESOLUTION, deploySeedSource, deploySeriesCodeFactory, prepareCodeS
 import { checkRegistryDeps, dependencySetupCalls, parseDepFlag, resolveDepRegistryPointer } from './deps.js';
 import { composeParamsKeys, expectedChainComplete, hasOnChainUriLane, onchainUriSetupCalls, onChainUriReport } from './onchain-uri.js';
 import { parseFlags, unknownFlags } from './flags.js';
+import { AGENT_SKILL_PARENTS, checkForCliUpdate, compareVersions, installedSkillVersions, readCliVersion, readSkillVersion, SKILL_DIR_NAME, } from './update-check.js';
 import { analyzeScript, recommendLane } from './inspect.js';
 import { parseSchemaSpecs, describeSchema } from './schema.js';
 import { parseSeriesTraits, looksPerTokenAttributes, parseSeriesTraitsById } from './series-traits.js';
@@ -110,10 +112,49 @@ const step = (s) => console.log(`\n${p(`[${++stepN}]`)} ${bold(s)}`);
 const ok = (s) => console.log(`    ${g('✓')} ${s}`);
 const info = (s) => console.log(`    ${dim(s)}`);
 const warn = (s) => console.log(`    ${c.orange}⚠${c.reset}  ${s}`);
+/**
+ * Notify-only update nudge. Prints an upgrade one-liner to STDERR (never stdout — an agent may be
+ * parsing that) when a newer @artblocks/abx-cli is published, plus a nudge when a locally-installed
+ * skill has drifted behind the running CLI. Fully suppressed by CI / ABX_NO_UPDATE_CHECK /
+ * --no-update-check, and wrapped so it can NEVER break a command (all failures are swallowed).
+ */
+async function maybeNotifyUpdate(flags) {
+    try {
+        if (flags['no-update-check'] !== undefined || process.env.ABX_NO_UPDATE_CHECK || process.env.CI)
+            return;
+        const current = readCliVersion();
+        // Skill drift (cheap, offline): the skill and CLI are co-versioned, but a separately-installed
+        // skill copy doesn't move when the CLI upgrades. Nudge a reinstall when the CLI is ahead.
+        for (const v of installedSkillVersions()) {
+            if (compareVersions(current, v) > 0) {
+                console.error(`    ${c.orange}⚠${c.reset}  installed abx skill is v${v} but the CLI is v${current} — refresh it: ${g('abx skill install')}`);
+                break;
+            }
+        }
+        const latest = await checkForCliUpdate(current);
+        if (latest) {
+            console.error(`\n    ${c.orange}⚠${c.reset}  update available: ${bold('abx')} ${dim(current)} → ${g(latest)}\n` +
+                `       upgrade: ${g('npm i -g @artblocks/abx-cli@latest')} ${dim('· or invoke:')} ${g('npx abx@latest <command>')}\n` +
+                `       release notes: https://github.com/ArtBlocks/abx/releases ${dim('· silence: ABX_NO_UPDATE_CHECK=1')}\n`);
+        }
+    }
+    catch {
+        /* an update check must never break a command */
+    }
+}
 async function main() {
     loadDotEnv();
     const [cmd, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
+    // `version` / --version / -v is a crisp query — print and exit, no update nag around it.
+    if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
+        console.log(readCliVersion());
+        return;
+    }
+    // Notify-only "you're behind" nudge (cached, opt-out, stderr — see update-check.ts). Awaited so
+    // the notice lands before command output, but it hits the network at most once a day and never
+    // throws, so it can't break or meaningfully slow a command. Skipped for the pure help path below.
+    await maybeNotifyUpdate(flags);
     // SAFETY: --help / -h on ANY command is read-only — print usage, never execute.
     // (A write command must never deploy/mint/spend just because someone asked for help.)
     if (cmd && cmd !== 'help' && (flags.help !== undefined || rest.includes('-h'))) {
@@ -4220,6 +4261,21 @@ async function cmdDoctor(flags) {
         const jwk = loadArweaveJwk();
         console.log(`  ${dim('↳ Turbo/Arweave key ' + (jwk ? arweaveAddress(jwk) + ' ' : '') + 'holds your upload credits — back it up: `abx storage backup-key --out <path>`')}`);
     }
+    // Agent skill co-versioning — the skill drives this CLI and is version-locked to it (its version
+    // lives in SKILL.md frontmatter). Report any installed copy and flag drift; notify-only, so a
+    // stale/absent skill never fails doctor (`abx skill install` resyncs).
+    const cliVersion = readCliVersion();
+    const skillVersions = installedSkillVersions();
+    const staleSkills = skillVersions.filter((v) => compareVersions(cliVersion, v) > 0);
+    if (skillVersions.length === 0) {
+        console.log(`  ${dim('↳ agent skill: not installed here — `abx skill install` so a coding agent can drive abx')}`);
+    }
+    else if (staleSkills.length > 0) {
+        console.log(`  ${c.orange}⚠${c.reset} agent skill behind CLI${dim(`  installed v${staleSkills.join(', v')} · CLI v${cliVersion} — refresh: `)}${g('abx skill install')}`);
+    }
+    else {
+        check(`agent skill in sync (v${cliVersion})`, true);
+    }
     console.log('');
 }
 // ── shared output ─────────────────────────────────────────────────────────--
@@ -4518,12 +4574,15 @@ function keepAlive() {
 // ── per-command usage (printed by `<cmd> --help` / `abx help <cmd>`; read-only) ──
 const COMMAND_HELP = {
     skill: `
-  ${bold('abx skill')} ${dim('— install the abx agent skill so your coding agent can drive abx')}
-    ${g('abx skill install')}     copy the skill into ${bold('.claude/skills/abx-self-host')} in the current project
-                          ${g('--global')}          install into your home dir (~/.claude/skills) instead of the project
-                          ${g('--target <dir>')}    install under a different base dir (writes <dir>/.claude/skills/abx-self-host)
+  ${bold('abx skill')} ${dim('— install the version-locked abx agent skill so your coding agent can drive abx')}
+    ${g('abx skill install')}     copy the bundled skill (version-locked to this CLI) into your agent(s)
+                          ${dim('default: both')} ${bold('.claude/skills')} ${dim('(Claude Code) and')} ${bold('.agents/skills')} ${dim('(Cursor · Codex · Gemini · Copilot)')}
+                          ${g('--agent <name>')}    only one agent: ${dim('claude | cursor | codex | gemini | copilot')}
+                          ${g('--global')}          install into your home dir (~) instead of the current project
+                          ${g('--target <dir>')}    install the skill folder straight under <dir> (writes <dir>/abx-self-host)
     ${g('abx skill path')}        print the absolute path to the bundled skill (for ${g('npx skills add <path>')} or manual copy)
-    ${dim('Restart your agent after installing so it picks up the skill. Cross-agent install:')} ${g('npx skills add ArtBlocks/abx')}`,
+    ${dim('Restart your agent after installing so it picks up the skill. Once the repo is public, the git-based')}
+    ${dim('cross-agent installer also works (not version-locked):')} ${g('npx skills add ArtBlocks/abx --skill abx-self-host')}`,
     deploy: `
   ${bold('abx deploy')} ${dim('— deploy + index a 1/1 (no server). Sends a tx in the chosen lane.')}
     --image <path>        custody your own image (png · jpg · gif · svg · webp); else generative demo art
@@ -4979,9 +5038,11 @@ function help() {
     ${g('abx forget')} <address>    drop a project's local registration + projection (on-chain untouched)
     ${g('abx status')}              list indexed projects + node info
     ${g('abx doctor')}              check environment (key, RPC, balance, factory, storage)
-    ${g('abx skill install')}       install the abx agent skill into your agent   [--global] [--target <dir>]  ·  ${g('abx skill path')} prints the bundled skill
+    ${g('abx skill install')}       install the version-locked abx skill into your agent(s)   [--agent <name>] [--global] [--target <dir>]  ·  ${g('abx skill path')} prints the bundled skill
+    ${g('abx version')}             print the installed CLI version
 
   ${dim('Run')} ${g('abx <command> --help')} ${dim('for per-command usage. --help / -h never executes — it only prints usage.')}
+  ${dim('abx checks npm for a newer release (once a day, notify-only). Silence with')} ${g('ABX_NO_UPDATE_CHECK=1')} ${dim('or')} ${g('--no-update-check')}${dim('.')}
 `);
 }
 /** Validate an explicit --salt (a 32-byte hex). Undefined when absent. */
@@ -4999,8 +5060,13 @@ function parseSaltFlag(raw) {
 // ── skill: install the abx agent skill into the user's coding agent ───────────────────────
 // The skill is the agentic half of the toolkit — the CLI is only useful once an agent knows how
 // to drive it. It ships bundled inside the published package (packages/cli/skill/, created at
-// prepack); in dev the same command reads the canonical copy straight from the repo. A separate
-// cross-agent channel is `npx skills add ArtBlocks/abx` (the Agent Skills standard, git-based).
+// prepack); in dev the same command reads the canonical copy straight from the repo. This is the
+// CANONICAL install path precisely because the bundle is version-locked to the CLI it ships inside
+// (the version lives in SKILL.md frontmatter — see update-check.ts). By default it writes to BOTH
+// `.claude/skills` (Claude Code) and the neutral `.agents/skills` (Cursor · Codex · Gemini ·
+// Copilot all read it), so one command covers the whole ecosystem; `--agent` narrows it. A separate
+// git-based channel, `npx skills add ArtBlocks/abx --skill abx-self-host`, works once the repo is public but is NOT
+// version-locked to a local CLI — prefer `abx skill install`.
 /** Locate the skill folder: the bundled copy beside the compiled CLI (published), else the
  *  canonical repo copy (dev). Returns null if neither is present. */
 function resolveBundledSkill() {
@@ -5064,29 +5130,71 @@ function cmdScaffoldRenderer(rest, flags) {
     console.log(`    ${g('abx deploy-code --image-renderer <MyRenderer> --attributes-renderer <MyTraits> --onchain-uri --schema palette:HexColor:TokenOwner --name "…" --symbol …')}`);
     info(`full walkthrough: ${bold(`${basename(dir)}/README.md`)} · interface + invariants: https://abx.docs.artblocks.io/protocol/renderers/`);
 }
+/** Human label for each skills-parent dir — which agents pick the skill up from there. */
+const SKILL_PARENT_LABELS = {
+    '.claude/skills': 'Claude Code',
+    '.agents/skills': 'Cursor · Codex · Gemini · Copilot',
+};
+/** Resolve which skills-parent dirs `install` should write to. No `--agent` → the whole-ecosystem
+ *  default (Claude Code + the neutral `.agents/skills` everyone else reads). `--agent a,b` narrows
+ *  to those agents' dirs (de-duped, since several share `.agents/skills`). */
+function resolveInstallParents(agentFlag) {
+    if (!agentFlag || agentFlag === 'true')
+        return ['.claude/skills', '.agents/skills'];
+    const parents = new Set();
+    for (const raw of agentFlag.split(',')) {
+        const a = raw.trim().toLowerCase();
+        const parent = AGENT_SKILL_PARENTS[a];
+        if (!parent) {
+            throw new Error(`unknown --agent '${a}'. Use one of: ${Object.keys(AGENT_SKILL_PARENTS).join(', ')} (or omit --agent to install for every agent).`);
+        }
+        parents.add(parent);
+    }
+    return [...parents];
+}
+/** Copy the bundled skill folder to `dest`, replacing any prior copy so a re-install after an
+ *  upgrade never leaves stale reference files behind. */
+function installSkillTo(src, dest) {
+    mkdirSync(joinPath(dest, '..'), { recursive: true });
+    rmSync(dest, { recursive: true, force: true });
+    cpSync(src, dest, { recursive: true });
+}
 async function cmdSkill(rest, flags) {
     const sub = rest[0] ?? 'install';
     const src = resolveBundledSkill();
     if (!src) {
         throw new Error('bundled skill not found (expected <pkg>/skill or .claude/skills/abx-self-host). ' +
-            'Reinstall @artblocks/abx-cli, or install cross-agent with: npx skills add ArtBlocks/abx');
+            'Reinstall @artblocks/abx-cli, or install cross-agent with: npx skills add ArtBlocks/abx --skill abx-self-host');
     }
     if (sub === 'path') {
         console.log(src);
         return;
     }
     if (sub === 'install') {
-        const base = flags.global !== undefined ? homedir() : flags.target ?? process.cwd();
-        const destParent = joinPath(base, '.claude', 'skills');
-        const dest = joinPath(destParent, 'abx-self-host');
-        mkdirSync(destParent, { recursive: true });
-        cpSync(src, dest, { recursive: true });
-        ok(`installed the abx skill → ${dest}`);
-        info('restart your agent (Claude Code / Cursor) so it loads the skill, then ask it to launch an NFT with abx.');
-        info('cross-agent alternative (git-based): npx skills add ArtBlocks/abx');
+        const version = readSkillVersion(joinPath(src, 'SKILL.md')) ?? readCliVersion();
+        // Escape hatch: --target <dir> writes the skill folder straight under <dir> (for an agent
+        // whose skills dir we don't special-case, or a bespoke location).
+        if (typeof flags.target === 'string' && flags.target !== 'true') {
+            const dest = joinPath(resolvePath(flags.target), SKILL_DIR_NAME);
+            installSkillTo(src, dest);
+            ok(`installed the abx skill v${version} → ${dest}`);
+            info('restart your agent so it loads the skill, then ask it to launch an NFT with abx.');
+            return;
+        }
+        const base = flags.global !== undefined ? homedir() : process.cwd();
+        const parents = resolveInstallParents(flags.agent);
+        ok(`installed the abx skill v${version}${flags.global !== undefined ? ' (global, ~)' : ''}:`);
+        for (const parent of parents) {
+            const dest = joinPath(base, parent, SKILL_DIR_NAME);
+            installSkillTo(src, dest);
+            const label = SKILL_PARENT_LABELS[parent];
+            console.log(`    ${g(joinPath(parent, SKILL_DIR_NAME))}${label ? dim('  → ' + label) : ''}`);
+        }
+        info('restart your agent so it loads the skill, then ask it to launch an NFT with abx.');
+        info(`the skill is version-locked to this CLI (v${version}); re-run ${g('abx skill install')} after upgrading so the two stay in sync.`);
         return;
     }
-    throw new Error('usage: abx skill <install|path> [--global] [--target <dir>]');
+    throw new Error('usage: abx skill <install|path> [--agent claude|cursor|codex|gemini|copilot] [--global] [--target <dir>]');
 }
 main().catch((err) => {
     // Keep the actionable message; strip viem's verbose boilerplate trailer (Docs:/Version: lines) so