@phnx-labs/agents-cli 1.20.78 → 1.20.83

package/dist/commands/routines.js

@@ -11,8 +11,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
+import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
-import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
+import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
 import { discoverProjectRoutinesAt, enableProjectRoutines, disableProjectRoutines, syncProjectRoutines, syncAllProjectRoutines, listEnabledProjectRoots, resolveProjectRoot, displayProjectPath, listProjectRoutineFiles, } from '../lib/routines-project.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
@@ -23,7 +24,7 @@ import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
-import { loadDevices } from '../lib/devices/registry.js';
+import { loadDevices, loadDevicesSync } from '../lib/devices/registry.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { addHostOption } from '../lib/hosts/option.js';
 /**
@@ -74,6 +75,164 @@ function fireConditionLabel(job) {
     }
     return '-';
 }
+function scheduleLabel(job) {
+    let label = fireConditionLabel(job);
+    if (isOneShotRoutine(job))
+        label = `${label} (one-shot)`;
+    if (job.endAt) {
+        const end = new Date(job.endAt);
+        const endLabel = Number.isFinite(end.getTime())
+            ? end.toLocaleDateString()
+            : job.endAt;
+        label = `${label} (until ${endLabel})`;
+    }
+    return label;
+}
+function nextRunForDisplay(job, scheduler) {
+    if (isPastOneShotRoutine(job))
+        return null;
+    return scheduler.getNextRun(job.name);
+}
+function nextRunLabel(job, scheduler, now) {
+    if (isPastOneShotRoutine(job))
+        return 'expired';
+    return humanizeNextRun(scheduler.getNextRun(job.name) ?? null, now, job.timezone);
+}
+function deviceStateLabel(name, registry) {
+    const profile = registry[normalizeHost(name)] ?? registry[name];
+    if (!profile)
+        return 'unknown';
+    if (profile.reachability?.reachable === false)
+        return 'offline';
+    if (profile.reachability?.reachable === true)
+        return 'online';
+    if (profile.tailscale?.online === false)
+        return 'offline';
+    if (profile.tailscale?.online === true)
+        return 'online';
+    return 'unknown';
+}
+function titleWithDeviceState(title, name, registry) {
+    const state = deviceStateLabel(name, registry);
+    return state && state !== 'online' ? `${title} (${state})` : title;
+}
+function placementTag(job) {
+    const strategy = resolveHostStrategy(job);
+    if (strategy === 'local')
+        return job.host ? `->${job.host}` : '';
+    if (strategy === 'host')
+        return `->${job.host ?? '?'}`;
+    if (strategy === 'fleet')
+        return '->fleet';
+    return '->cloud';
+}
+function deviceLabel(job, width) {
+    const full = [job.devices?.join(',') ?? '', placementTag(job)]
+        .filter(Boolean)
+        .join(' ');
+    const raw = full.length === 0 ? 'all' : full;
+    const display = width && raw.length > width
+        ? raw.slice(0, width - 1) + '…'
+        : raw;
+    return { raw, display, dim: full.length === 0 || !jobRunsOnThisDevice(job) };
+}
+export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
+    const groups = new Map();
+    const add = (key, title, job) => {
+        const existing = groups.get(key);
+        if (existing) {
+            existing.jobs.push(job);
+            return;
+        }
+        groups.set(key, { key, title, jobs: [job] });
+    };
+    for (const job of jobs) {
+        const strategy = resolveHostStrategy(job);
+        if (strategy === 'cloud') {
+            add('cloud', 'Cloud', job);
+            continue;
+        }
+        if (strategy === 'fleet') {
+            add('fleet', 'Fleet-wide', job);
+            continue;
+        }
+        if (strategy === 'host') {
+            const host = job.host ?? 'unknown-host';
+            add(`host:${normalizeHost(host)}`, titleWithDeviceState(`Host: ${host}`, host, registry), job);
+            continue;
+        }
+        const devices = job.devices ?? [];
+        if (devices.length === 0) {
+            add('fleet', 'Fleet-wide', job);
+            continue;
+        }
+        for (const device of devices) {
+            const normalized = normalizeHost(device);
+            if (normalized === self) {
+                add('this-machine', `This machine (${self})`, job);
+            }
+            else {
+                add(`device:${normalized}`, titleWithDeviceState(`Device: ${normalized}`, normalized, registry), job);
+            }
+        }
+    }
+    const order = (group) => {
+        if (group.key === 'this-machine')
+            return 0;
+        if (group.key === 'fleet')
+            return 1;
+        if (group.key === 'cloud')
+            return 2;
+        if (group.key.startsWith('device:'))
+            return 3;
+        if (group.key.startsWith('host:'))
+            return 4;
+        return 5;
+    };
+    return [...groups.values()].sort((a, b) => order(a) - order(b) || a.title.localeCompare(b.title));
+}
+function renderRoutineRows({ jobs, scheduler, overdueSet, link, now }) {
+    const NAME_W = 24;
+    const AGENT_W = 10;
+    const REPO_W = REPO_DISPLAY_MAX;
+    const DEVICE_W = 22;
+    const SCHED_W = 34;
+    const ENABLED_W = 10;
+    const NEXT_W = 22;
+    const header = `  ${'Name'.padEnd(NAME_W)} ${'Agent'.padEnd(AGENT_W)} ${'Repo'.padEnd(REPO_W)} ${'Devices'.padEnd(DEVICE_W)} ${'Schedule'.padEnd(SCHED_W)} ${'Enabled'.padEnd(ENABLED_W)} ${'Next Run'.padEnd(NEXT_W)} Last Status`;
+    console.log(chalk.gray(header));
+    console.log(chalk.gray('  ' + '-'.repeat(NAME_W + AGENT_W + REPO_W + DEVICE_W + SCHED_W + ENABLED_W + NEXT_W + 20)));
+    for (const job of jobs) {
+        const nextStr = nextRunLabel(job, scheduler, now);
+        const schedStr = scheduleLabel(job);
+        const latestRun = getLatestRun(job.name);
+        const lastStatus = latestRun?.status || '-';
+        const sourceRepo = job.source?.repo ?? job.repo;
+        const sourceLabel = sourceRepo
+            ? (job.source?.branch ? `${sourceRepo}@${job.source.branch}` : sourceRepo)
+            : null;
+        const repoInfo = formatRepoLink(sourceLabel ?? job.repo);
+        const repoCell = link(repoInfo.display, repoInfo.href);
+        const repoPadding = Math.max(0, REPO_W - repoInfo.display.length);
+        const enabledStr = job.enabled ? chalk.green('yes') : chalk.gray('no');
+        const enabledWord = job.enabled ? 'yes' : 'no';
+        const enabledPad = Math.max(0, ENABLED_W - enabledWord.length);
+        const device = deviceLabel(job, DEVICE_W);
+        const deviceCell = device.dim ? chalk.gray(device.display) : device.display;
+        const devicePad = Math.max(0, DEVICE_W - device.display.length);
+        const statusColor = lastStatus === 'completed' ? chalk.green
+            : lastStatus === 'failed' ? chalk.red
+                : lastStatus === 'timeout' ? chalk.yellow
+                    : chalk.gray;
+        const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
+        const agentLabelPadded = job.command
+            ? chalk.magenta('command'.padEnd(10))
+            : job.workflow
+                ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
+                : (job.agent || '').padEnd(10);
+        console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
+    }
+}
 function parseRoutineTrigger(options) {
     const raw = typeof options.on === 'string' ? options.on : undefined;
     if (!raw)
@@ -280,7 +439,7 @@ export function registerRoutinesCommands(program) {
     `,
         notes: `
       A routine is a YAML file that schedules an agent invocation. It specifies:
-        - which agent to run (claude, codex, gemini, ...)
+        - which agent to run (claude, codex, antigravity, ...)
         - when to run (cron schedule or one-shot time)
         - what task to give the agent (the prompt)
         - execution constraints (mode, effort, timeout)
@@ -307,7 +466,13 @@ export function registerRoutinesCommands(program) {
         .command('list')
         .description('See all scheduled jobs, when they run next, and their last execution status')
         .option('--json', 'Emit machine-readable JSON instead of the table (used by the menu bar helper)')
+        .option('--group-by <field>', 'Group table output by device (default for terminal output)')
+        .option('--flat', 'Print the legacy flat table instead of grouped sections')
         .action((options) => {
+        if (options.groupBy && options.groupBy !== 'device') {
+            console.error(chalk.red(`Unsupported --group-by '${options.groupBy}'. Use: device`));
+            process.exit(1);
+        }
         try {
             monitorRunningJobs();
         }
@@ -338,7 +503,6 @@ export function registerRoutinesCommands(program) {
         if (options.json) {
             const nowJson = new Date();
             const payload = jobs.map((job) => {
-                const nextRun = scheduler.getNextRun(job.name);
                 const latestRun = getLatestRun(job.name);
                 return {
                     name: job.name,
@@ -356,11 +520,14 @@ export function registerRoutinesCommands(program) {
                     source: job.source ?? null,
                     sourceRepo: job.source?.repo ?? job.repo ?? null,
                     sourceBranch: job.source?.branch ?? null,
+                    runOnce: Boolean(job.runOnce),
+                    oneShot: isOneShotRoutine(job),
+                    expired: isPastOneShotRoutine(job, nowJson),
                     runsHere: jobRunsOnThisDevice(job),
                     enabled: job.enabled,
                     overdue: overdueSet.has(job.name),
-                    nextRun: nextRun ? nextRun.toISOString() : null,
-                    nextRunHuman: humanizeNextRun(nextRun ?? null, nowJson, job.timezone),
+                    nextRun: nextRunForDisplay(job, scheduler)?.toISOString() ?? null,
+                    nextRunHuman: nextRunLabel(job, scheduler, nowJson),
                     lastStatus: latestRun?.status ?? null,
                     exitCode: latestRun?.exitCode ?? null,
                     failureReason: latestRun?.errorMessage ?? null,
@@ -378,76 +545,21 @@ export function registerRoutinesCommands(program) {
         // contains raw ESC ] 8 ;; ... BEL escape sequences.
         const link = (label, url) => url && process.stdout.isTTY ? `\x1b]8;;${url}\x07${label}\x1b]8;;\x07` : label;
         const now = new Date();
-        const NAME_W = 24;
-        const AGENT_W = 10;
-        const REPO_W = REPO_DISPLAY_MAX;
-        const DEVICE_W = 22;
-        const SCHED_W = 22;
-        const ENABLED_W = 10;
-        const NEXT_W = 22;
-        const header = `  ${'Name'.padEnd(NAME_W)} ${'Agent'.padEnd(AGENT_W)} ${'Repo'.padEnd(REPO_W)} ${'Devices'.padEnd(DEVICE_W)} ${'Schedule'.padEnd(SCHED_W)} ${'Enabled'.padEnd(ENABLED_W)} ${'Next Run'.padEnd(NEXT_W)} Last Status`;
-        console.log(chalk.gray(header));
-        console.log(chalk.gray('  ' + '-'.repeat(NAME_W + AGENT_W + REPO_W + DEVICE_W + SCHED_W + ENABLED_W + NEXT_W + 20)));
-        for (const job of jobs) {
-            const nextRun = scheduler.getNextRun(job.name);
-            const nextStr = humanizeNextRun(nextRun ?? null, now, job.timezone);
-            let schedStr = fireConditionLabel(job);
-            if (job.endAt) {
-                const end = new Date(job.endAt);
-                const endLabel = Number.isFinite(end.getTime())
-                    ? end.toLocaleDateString()
-                    : job.endAt;
-                schedStr = `${schedStr} (until ${endLabel})`;
-            }
-            const latestRun = getLatestRun(job.name);
-            const lastStatus = latestRun?.status || '-';
-            // Prefer project-source repo (with optional @branch) over bare job.repo.
-            const sourceRepo = job.source?.repo ?? job.repo;
-            const sourceLabel = sourceRepo
-                ? (job.source?.branch ? `${sourceRepo}@${job.source.branch}` : sourceRepo)
-                : null;
-            const repoInfo = formatRepoLink(sourceLabel ?? job.repo);
-            const repoCell = link(repoInfo.display, repoInfo.href);
-            // Pad based on the display string, not the raw cell (which may include escape codes).
-            const repoPadding = Math.max(0, REPO_W - repoInfo.display.length);
-            const enabledStr = job.enabled ? chalk.green('yes') : chalk.gray('no');
-            // chalk adds escape codes; pad the raw word and let chalk wrap it.
-            const enabledWord = job.enabled ? 'yes' : 'no';
-            const enabledPad = Math.max(0, ENABLED_W - enabledWord.length);
-            // Placement rides in the Devices cell: eligibility →execution strategy.
-            const strategy = resolveHostStrategy(job);
-            const placementTag = strategy === 'local'
-                ? (job.host ? `→${job.host}` : '')
-                : strategy === 'host'
-                    ? `→${job.host ?? '?'}`
-                    : strategy === 'fleet'
-                        ? '→fleet'
-                        : '→cloud';
-            const deviceFull = [job.devices?.join(',') ?? '', placementTag]
-                .filter(Boolean)
-                .join(' ');
-            const deviceWord = deviceFull.length === 0
-                ? 'all'
-                : deviceFull.length > DEVICE_W
-                    ? deviceFull.slice(0, DEVICE_W - 1) + '…'
-                    : deviceFull;
-            const deviceCell = deviceFull.length === 0
-                ? chalk.gray('all')
-                : jobRunsOnThisDevice(job)
-                    ? deviceWord
-                    : chalk.gray(deviceWord);
-            const devicePad = Math.max(0, DEVICE_W - deviceWord.length);
-            const statusColor = lastStatus === 'completed' ? chalk.green
-                : lastStatus === 'failed' ? chalk.red
-                    : lastStatus === 'timeout' ? chalk.yellow
-                        : chalk.gray;
-            const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
-            const agentLabelPadded = job.command
-                ? chalk.magenta('command'.padEnd(10))
-                : job.workflow
-                    ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
-                    : (job.agent || '').padEnd(10);
-            console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
+        if (options.flat) {
+            renderRoutineRows({ jobs, scheduler, overdueSet, link, now });
+        }
+        else {
+            let registry = {};
+            try {
+                registry = loadDevicesSync();
+            }
+            catch (err) {
+                console.error(chalk.yellow(`Could not read device registry: ${err.message}`));
+            }
+            for (const group of groupRoutineJobsByDevice(jobs, registry)) {
+                console.log(chalk.bold(`\n${group.title}`));
+                renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now });
+            }
         }
         if (overdueSet.size > 0) {
             console.log();
@@ -460,7 +572,7 @@ export function registerRoutinesCommands(program) {
         .command('add [nameOrPath]')
         .description('Create a new routine from a YAML file or inline flags. Starts the scheduler automatically if it is not already running.')
         .option('-s, --schedule <cron>', 'Cron schedule in standard format (5 fields: minute hour day month weekday)')
-        .option('-a, --agent <agent>', 'Which agent runs this routine: claude, codex, gemini, cursor, or opencode')
+        .option('-a, --agent <agent>', 'Which agent runs this routine: claude, codex, antigravity, cursor, or opencode')
         .option('--workflow <name>', 'Run an installed workflow (~/.agents/workflows/<name>) via `agents run`. Mutually exclusive with --agent.')
         .option('--command <sh>', 'Run a plain shell command directly (no agent, no auth, no sandbox) — for deterministic housekeeping routines. Mutually exclusive with --agent and --workflow; --prompt is not used.')
         .option('-p, --prompt <prompt>', 'Task instruction for the agent')
@@ -519,6 +631,10 @@ export function registerRoutinesCommands(program) {
                 schedule = parsed.schedule;
                 runOnce = parsed.runOnce;
             }
+            if (!options.at && isOneShotLikeSchedule(schedule)) {
+                runOnce = true;
+                console.error(chalk.yellow(`Schedule "${schedule}" pins minute, hour, day, and month; treating it as one-shot. Prefer --at for one-time routines.`));
+            }
             if (!schedule && !trigger) {
                 console.error(chalk.red('Schedule or trigger is required (use --schedule, --at, or --on)'));
                 process.exit(1);
@@ -527,6 +643,15 @@ export function registerRoutinesCommands(program) {
                 console.error(chalk.red('An agent, workflow, or command is required (use --agent, --workflow, or --command)'));
                 process.exit(1);
             }
+            // Hard-deprecated harnesses cannot be scheduled — refuse at create time so
+            // no new recurring job silently fails against a retired backend.
+            if (options.agent) {
+                const routineAgentId = resolveAgentName(options.agent);
+                if (routineAgentId && isAgentHardDeprecated(routineAgentId)) {
+                    console.error(chalk.red(hardDeprecationError(routineAgentId)));
+                    process.exit(1);
+                }
+            }
             // Command routines run a plain shell and take no prompt; agent/workflow routines require one.
             if (!options.command && !options.prompt) {
                 console.error(chalk.red('Prompt is required (use --prompt)'));
@@ -651,6 +776,10 @@ export function registerRoutinesCommands(program) {
                 enabled: true,
                 ...parsed,
             };
+            if (isOneShotLikeSchedule(config.schedule)) {
+                config.runOnce = true;
+                console.error(chalk.yellow(`Schedule "${config.schedule}" pins minute, hour, day, and month; treating it as one-shot. Prefer --at for one-time routines.`));
+            }
             // Same duplicate-fire guard as --placement/--run-on: off-box placement
             // with no eligibility pin would fire from every daemon in the fleet.
             const fileStrategy = resolveHostStrategy(config);
@@ -678,6 +807,41 @@ export function registerRoutinesCommands(program) {
             ensureSchedulerRunning();
         }
     });
+    routinesCmd
+        .command('cleanup')
+        .description('Remove expired one-shot routines that already fired and still have a user-layer YAML file.')
+        .option('--dry-run', 'Show routines that would be removed without deleting files')
+        .action((options) => {
+        const jobs = listAllJobs()
+            .filter((job) => getJobPath(job.name) !== null)
+            .filter((job) => hasCompletedOneShotRun(job));
+        if (jobs.length === 0) {
+            console.log(chalk.gray('No completed expired one-shot routines to clean up.'));
+            return;
+        }
+        if (options.dryRun) {
+            console.log(chalk.bold('Expired one-shot routines eligible for cleanup\n'));
+            for (const job of jobs) {
+                console.log(`  ${chalk.cyan(job.name)} ${chalk.gray(scheduleLabel(job))}`);
+            }
+            console.log(chalk.gray(`\nDry run. Remove with: agents routines cleanup`));
+            return;
+        }
+        let removed = 0;
+        for (const job of jobs) {
+            if (deleteJob(job.name)) {
+                removed++;
+                console.log(chalk.green(`Removed ${job.name}`));
+            }
+        }
+        console.log(chalk.gray(`Cleaned up ${removed} expired one-shot routine(s).`));
+        try {
+            signalDaemonReload();
+        }
+        catch {
+            // The daemon may not be running; the next start will read the cleaned directory.
+        }
+    });
     routinesCmd
         .command('remove [name]')
         .description('Delete a routine. Stops scheduling future runs; past execution logs remain on disk.')

package/dist/commands/rules.js

@@ -4,7 +4,8 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { select, checkbox } from '@inquirer/prompts';
-import { AGENTS, agentConfigDirName, ALL_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { AGENTS, agentConfigDirName, MANAGED_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverInstructionsFromRepo, discoverRuleFilesFromRepo, installInstructionsCentrally, uninstallInstructions, listInstalledInstructionsWithScope, instructionsExists, getInstructionsContent, listCentralRules, } from '../lib/rules/rules.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
@@ -28,7 +29,7 @@ Examples:
   agents rules list claude@2.1.112
 
   # Install rules from your .agents repo to multiple agents
-  agents rules add --agents claude,codex,gemini
+  agents rules add --agents claude,codex,cursor
 
   # Install a shared rule file from GitHub
   agents rules add gh:anthropics/agent-rules --agents codex@0.116.0
@@ -44,13 +45,13 @@ When to use:
 
 Project rules & @-imports:
   Project rules live in <repo>/.agents/rules/. On every agent launch, the shim compiles
-  them into <repo>/AGENTS.md (with CLAUDE.md, GEMINI.md, .cursorrules symlinked to it).
+  them into <repo>/AGENTS.md (with CLAUDE.md and .cursorrules symlinked to it).
   A hand-authored AGENTS.md is preserved — the compile pipeline only overwrites files
   it owns (those starting with the auto-compile header). Delete the file to migrate.
 
   @path imports inside AGENTS.md/CLAUDE.md are resolved at session start by the agent
   itself, not by agents-cli. Support is per-agent:
-    Inlined natively:  claude, gemini
+    Inlined natively:  claude
     Literal text:      codex, cursor, opencode, copilot, amp, kiro, goose
 
   For rules that need to work across all agents, inline the content rather than using
@@ -161,7 +162,7 @@ Project rules & @-imports:
             return;
         }
         console.log(chalk.bold('Installed Rules\n'));
-        for (const aid of ALL_AGENT_IDS) {
+        for (const aid of MANAGED_AGENT_IDS) {
             const agent = AGENTS[aid];
             const installedVersions = listInstalledVersions(aid);
             const defaultVer = getGlobalDefault(aid);
@@ -200,7 +201,7 @@ Project rules & @-imports:
     rulesCmd
         .command('add [source]')
         .description('Install rule files from a source (GitHub, local path) or pick from central storage')
-        .option('-a, --agents <list>', 'Targets: claude, codex@0.116.0, or gemini@default')
+        .option('-a, --agents <list>', 'Targets: claude, codex@0.116.0, or cursor@default')
         .option('--names <list>', 'Rule file names from ~/.agents/rules/ (comma-separated)')
         .option('-y, --yes', 'Skip all prompts and use defaults')
         .addHelpText('after', `
@@ -212,7 +213,7 @@ Examples:
   agents rules add --names AGENTS.md --agents codex@0.116.0
 
   # Install all rules from a GitHub repo to multiple agents
-  agents rules add gh:team/agent-rules --agents claude,gemini
+  agents rules add gh:team/agent-rules --agents claude,codex
 
   # Sync a local rules directory to your active agents
   agents rules add ~/projects/my-rules --agents claude@default
@@ -317,7 +318,7 @@ Examples:
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
-                const result = await resolveAgentTargetsAutoInstalling(options.agents, ALL_AGENT_IDS, { yes: options.yes });
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, capableAgents('rules'), { yes: options.yes });
                 if (!result) {
                     console.log(chalk.gray('Cancelled.'));
                     return;
@@ -326,7 +327,7 @@ Examples:
                 versionSelections = result.versionSelections;
             }
             else {
-                const result = await promptAgentVersionSelection(ALL_AGENT_IDS, {
+                const result = await promptAgentVersionSelection(capableAgents('rules'), {
                     skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;
@@ -376,7 +377,7 @@ Examples:
   agents rules view codex --scope project
 
   # View rules for a specific installed version
-  agents rules view gemini@1.5.0
+  agents rules view codex@0.116.0
 `)
         .action(async (agentArg, options) => {
         const cwd = process.cwd();
@@ -393,7 +394,7 @@ Examples:
             requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
         }
         else {
-            const choices = ALL_AGENT_IDS.filter((id) => instructionsExists(id, 'user', cwd) || instructionsExists(id, 'project', cwd));
+            const choices = MANAGED_AGENT_IDS.filter((id) => instructionsExists(id, 'user', cwd) || instructionsExists(id, 'project', cwd));
             if (choices.length === 0) {
                 console.log(chalk.yellow('No rule files found.'));
                 return;
@@ -460,7 +461,7 @@ Examples:
         if (!agentArg) {
             // Only list agents that actually have a rules file installed — avoids
             // suggesting agents the user hasn't touched.
-            const candidates = ALL_AGENT_IDS.filter((id) => instructionsExists(id));
+            const candidates = MANAGED_AGENT_IDS.filter((id) => instructionsExists(id));
             requireDestructiveArg({
                 argName: 'agent',
                 command: 'agents rules remove',

package/dist/commands/secrets.d.ts

@@ -8,7 +8,7 @@
 import { type Command } from 'commander';
 import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg } from '../lib/platform/index.js';
-import { type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
+import { type SecretsBackend, type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
 /** Read all available data from stdin synchronously, trimmed. */
 /**
  * Read the raw `.env` text for `import --from <path|->`. A `-` reads the .env
@@ -109,4 +109,6 @@ export declare function assertNeverPolicyAcknowledged(policy: SecretsPolicy | un
     iUnderstand?: boolean;
     interactive: boolean;
 }): 'ok' | 'prompt';
+/** Validate a --backend value, exiting with a clear message on a bad one. */
+export declare function secretsDefaultBackend(): SecretsBackend;
 export { quoteWin32ExecArg };