@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/cloud/types.d.ts

@@ -1,38 +1,182 @@
+/**
+ * Cloud dispatch type definitions.
+ *
+ * Defines the provider-agnostic interface that all cloud backends (Rush, Codex,
+ * Factory) implement, plus the shared task and event types that flow through
+ * the dispatch pipeline.
+ */
+/** Identifier for a supported cloud dispatch backend. */
 export type CloudProviderId = 'rush' | 'codex' | 'factory';
-export type CloudTaskStatus = 'queued' | 'allocating' | 'running' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Lifecycle state of a cloud-dispatched task.
+ *
+ * `idle` represents a long-lived session that has stopped between turns and
+ * can be resumed via `message()`. Distinct from the terminal `completed |
+ * failed | cancelled` states, which cannot transition back to `running`.
+ */
+export type CloudTaskStatus = 'queued' | 'allocating' | 'running' | 'idle' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+/** Snapshot of a dispatched task, stored locally and refreshed from the provider. */
 export interface CloudTask {
     id: string;
     provider: CloudProviderId;
     status: CloudTaskStatus;
     agent?: string;
     prompt: string;
+    /**
+     * First (or only) repo the task targets. Kept for back-compat with callers
+     * that treat one task as one repo. For multi-repo dispatches, see `repos`.
+     */
     repo?: string;
+    /**
+     * All repos the task targets, in dispatch order. Populated for multi-repo
+     * dispatches (Rush Cloud, and any provider that supports it). `repo`
+     * mirrors `repos[0]` when both are set.
+     */
+    repos?: string[];
     branch?: string;
     prUrl?: string;
     createdAt: string;
     updatedAt: string;
     summary?: string;
 }
-export interface CloudEvent {
-    type: 'status' | 'output' | 'done' | 'error';
+/**
+ * Single event emitted by a running cloud task.
+ *
+ * Discriminated union mirroring the local `SessionEvent` taxonomy so cloud
+ * streams can be rendered with the same UI primitives as local sessions. The
+ * `unknown` variant catches event names the provider emits that the client
+ * doesn't recognize — surfacing them rather than silently dropping is the
+ * point.
+ */
+export type CloudEvent = {
+    type: 'text';
+    content: string;
+    timestamp?: string;
+} | {
+    type: 'thinking';
+    content: string;
+    timestamp?: string;
+} | {
+    type: 'tool_use';
+    tool: string;
+    input: unknown;
+    timestamp?: string;
+} | {
+    type: 'tool_result';
+    tool: string;
+    output: unknown;
+    timestamp?: string;
+} | {
+    type: 'status';
+    status: CloudTaskStatus;
+    timestamp?: string;
+} | {
+    type: 'usage';
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    timestamp?: string;
+} | {
+    type: 'done';
+    status?: CloudTaskStatus;
+    prUrl?: string;
+    summary?: string;
+    timestamp?: string;
+} | {
+    type: 'error';
+    message: string;
+    timestamp?: string;
+} | {
+    type: 'unknown';
+    name: string;
     data: string;
     timestamp?: string;
+};
+/** Reference to a skill that should ride along with a cloud dispatch. */
+export interface SkillRef {
+    id: string;
+    version?: string;
+}
+/** A vision attachment carried along with a prompt (base64-encoded image bytes). */
+export interface ImageAttachment {
+    data: string;
+    mimeType: 'image/png' | 'image/jpeg' | 'image/webp';
 }
+/** Maximum images allowed per dispatch (matches Cursor Background Agents). */
+export declare const MAX_IMAGES_PER_DISPATCH = 5;
+/** Parameters for dispatching a new cloud task. */
 export interface DispatchOptions {
     prompt: string;
     agent?: string;
+    /**
+     * Legacy single-repo target. Still honored: if `repos` is empty, this
+     * becomes the only repo. Providers that support multi-repo treat
+     * `repos = [repo]` and `repo` as equivalent.
+     */
     repo?: string;
+    /**
+     * One or more repos the dispatch targets. Repeatable on the CLI via
+     * `--repo`. Providers handle multi-repo differently:
+     *   - Rush Cloud clones each into /workspace/<owner>/<name>/
+     *   - Codex Cloud rejects (multi-repo requires an env that bundles them)
+     *   - Factory (local) clones each into the workspace before dispatch
+     */
+    repos?: string[];
     branch?: string;
     timeout?: string;
     model?: string;
+    /**
+     * Skills to ship with the dispatch. Providers that support skills mount
+     * them in the pod's skills directory before the agent runs. Providers
+     * without skill support reject via `capabilities().skills === false`.
+     */
+    skills?: SkillRef[];
+    /**
+     * Image attachments for vision-enabled dispatch (e.g., "fix this UI bug,
+     * here's the screenshot"). Capped at MAX_IMAGES_PER_DISPATCH.
+     */
+    images?: ImageAttachment[];
     /** Provider-specific options (e.g., codex env ID, factory computer name). */
-    providerOptions?: Record<string, string>;
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * Collapse `repo` + `repos` into a single deduped list. Exported so callers,
+ * tests, and every provider share the same resolution — one source of truth
+ * for "which repos does this dispatch target?".
+ */
+export declare function resolveDispatchRepos(options: DispatchOptions): string[];
+/**
+ * What a provider can actually do. Replaces the single-bool `supports()` so
+ * callers can ask "does this provider support cancel?" without trying and
+ * catching. The CLI gates feature-specific calls on these flags and surfaces
+ * a typed error instead of letting throws bubble.
+ */
+export interface ProviderCapabilities {
+    /** Configured + reachable (auth present, binary installed, etc.). */
+    available: boolean;
+    dispatch: boolean;
+    status: boolean;
+    list: boolean;
+    stream: boolean;
+    cancel: boolean;
+    message: boolean;
+    multiRepo: boolean;
+    skills: boolean;
+    images: boolean;
 }
+/**
+ * Contract that every cloud backend must implement.
+ *
+ * Each provider translates between the unified dispatch interface and its
+ * backend-specific API (Rush Factory Floor, Codex Cloud CLI, Droid daemon).
+ *
+ * `message()` may transition a task from `idle` back to `running`.
+ */
 export interface CloudProvider {
     id: CloudProviderId;
     name: string;
-    /** Whether the provider is configured and can handle this dispatch. */
-    supports(options: DispatchOptions): boolean;
+    /** Static capability map for this provider. Read before calling feature methods. */
+    capabilities(): ProviderCapabilities;
     dispatch(options: DispatchOptions): Promise<CloudTask>;
     status(taskId: string): Promise<CloudTask>;
     list(filter?: {
@@ -41,9 +185,10 @@ export interface CloudProvider {
     /** Stream live output. Yields events until task completes or caller breaks. */
     stream(taskId: string): AsyncIterable<CloudEvent>;
     cancel(taskId: string): Promise<void>;
-    /** Send a follow-up message to a finished/needs_review task. */
+    /** Send a follow-up message to a finished/idle/needs_review task. */
     message(taskId: string, content: string): Promise<void>;
 }
+/** Per-provider configuration stored in the `cloud.providers` section of agents.yaml. */
 export interface CloudProviderConfig {
     rush?: Record<string, string>;
     codex?: {
@@ -53,8 +198,8 @@ export interface CloudProviderConfig {
         computer?: string;
     };
 }
+/** Top-level `cloud` section of agents.yaml. */
 export interface CloudConfig {
     default_provider?: CloudProviderId;
     providers?: CloudProviderConfig;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/lib/cloud/types.js

@@ -1,2 +1,34 @@
-export {};
-//# sourceMappingURL=types.js.map
+/**
+ * Cloud dispatch type definitions.
+ *
+ * Defines the provider-agnostic interface that all cloud backends (Rush, Codex,
+ * Factory) implement, plus the shared task and event types that flow through
+ * the dispatch pipeline.
+ */
+/** Maximum images allowed per dispatch (matches Cursor Background Agents). */
+export const MAX_IMAGES_PER_DISPATCH = 5;
+/**
+ * Collapse `repo` + `repos` into a single deduped list. Exported so callers,
+ * tests, and every provider share the same resolution — one source of truth
+ * for "which repos does this dispatch target?".
+ */
+export function resolveDispatchRepos(options) {
+    const out = [];
+    const seen = new Set();
+    const candidates = [];
+    if (options.repos)
+        candidates.push(...options.repos);
+    if (options.repo)
+        candidates.push(options.repo);
+    for (const raw of candidates) {
+        const trimmed = typeof raw === 'string' ? raw.trim() : '';
+        if (!trimmed)
+            continue;
+        const key = trimmed.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(trimmed);
+    }
+    return out;
+}

package/dist/lib/command-skills.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Convert slash-command markdown files into Codex skills for Codex releases
+ * that no longer load the legacy prompts/ directory.
+ */
+import type { AgentId } from './types.js';
+export declare function shouldInstallCommandAsSkill(agent: AgentId, version: string): boolean;
+export declare function commandSkillName(commandName: string): string;
+export declare function buildCommandSkillContent(commandName: string, sourcePath: string): string;
+export declare function skillSourceExists(skillName: string, skillSourceDirs: Array<string | null | undefined>): boolean;
+export declare function installCommandSkillToVersion(agentDir: string, commandName: string, sourcePath: string, skillSourceDirs?: Array<string | null | undefined>): {
+    success: boolean;
+    skipped?: boolean;
+    error?: string;
+};
+export declare function listCommandSkillsInVersion(agentDir: string): string[];
+export declare function commandSkillMatches(agentDir: string, commandName: string, sourcePath: string): boolean;
+export declare function removeCommandSkillFromVersion(agentDir: string, commandName: string): {
+    success: boolean;
+    error?: string;
+};

package/dist/lib/command-skills.js

@@ -0,0 +1,142 @@
+/**
+ * Convert slash-command markdown files into Codex skills for Codex releases
+ * that no longer load the legacy prompts/ directory.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { supports } from './capabilities.js';
+import { safeJoin } from './paths.js';
+const COMMAND_SKILL_MARKER = 'agents_command';
+function readCommandMetadata(sourcePath) {
+    const content = fs.readFileSync(sourcePath, 'utf-8');
+    const lines = content.split('\n');
+    if (lines[0] !== '---') {
+        return { description: '', body: content };
+    }
+    const endIndex = lines.slice(1).findIndex((line) => line === '---');
+    if (endIndex < 0) {
+        return { description: '', body: content };
+    }
+    const frontmatterEnd = endIndex + 1;
+    const frontmatter = lines.slice(1, frontmatterEnd).join('\n');
+    const body = lines.slice(frontmatterEnd + 1).join('\n').trimStart();
+    try {
+        const parsed = yaml.parse(frontmatter);
+        const description = typeof parsed?.description === 'string' ? parsed.description.trim() : '';
+        return { description, body };
+    }
+    catch {
+        return { description: '', body };
+    }
+}
+function readSkillCommandMarker(skillMdPath) {
+    if (!fs.existsSync(skillMdPath))
+        return null;
+    const content = fs.readFileSync(skillMdPath, 'utf-8');
+    const lines = content.split('\n');
+    if (lines[0] !== '---')
+        return null;
+    const endIndex = lines.slice(1).findIndex((line) => line === '---');
+    if (endIndex < 0)
+        return null;
+    try {
+        const frontmatter = lines.slice(1, endIndex + 1).join('\n');
+        const parsed = yaml.parse(frontmatter);
+        return typeof parsed?.[COMMAND_SKILL_MARKER] === 'string' ? parsed[COMMAND_SKILL_MARKER] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function shouldInstallCommandAsSkill(agent, version) {
+    if (agent !== 'codex')
+        return false;
+    return !supports(agent, 'commands', version).ok && supports(agent, 'skills', version).ok;
+}
+export function commandSkillName(commandName) {
+    return commandName;
+}
+export function buildCommandSkillContent(commandName, sourcePath) {
+    const { description, body } = readCommandMetadata(sourcePath);
+    const skillDescription = description || `Slash command converted from /${commandName}`;
+    return [
+        '---',
+        `name: ${JSON.stringify(commandSkillName(commandName))}`,
+        `description: ${JSON.stringify(skillDescription)}`,
+        `${COMMAND_SKILL_MARKER}: ${JSON.stringify(commandName)}`,
+        '---',
+        '',
+        `# /${commandName}`,
+        '',
+        `This skill contains the behavior from the legacy \`/${commandName}\` slash command.`,
+        'When invoked with `$' + commandSkillName(commandName) + '`, treat the text after the skill name as the original command arguments.',
+        '',
+        body.trimEnd(),
+        '',
+    ].join('\n');
+}
+export function skillSourceExists(skillName, skillSourceDirs) {
+    return skillSourceDirs.some((dir) => {
+        if (!dir)
+            return false;
+        const candidate = path.join(dir, skillName);
+        return fs.existsSync(candidate) && fs.lstatSync(candidate).isDirectory();
+    });
+}
+export function installCommandSkillToVersion(agentDir, commandName, sourcePath, skillSourceDirs = []) {
+    const skillName = commandSkillName(commandName);
+    if (skillSourceExists(skillName, skillSourceDirs)) {
+        return { success: false, skipped: true, error: `Skill '${skillName}' already exists` };
+    }
+    const skillsDir = safeJoin(agentDir, 'skills');
+    const skillDir = safeJoin(skillsDir, skillName);
+    try {
+        fs.rmSync(skillDir, { recursive: true, force: true });
+        fs.mkdirSync(skillDir, { recursive: true });
+        fs.writeFileSync(safeJoin(skillDir, 'SKILL.md'), buildCommandSkillContent(commandName, sourcePath), 'utf-8');
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+export function listCommandSkillsInVersion(agentDir) {
+    const skillsDir = path.join(agentDir, 'skills');
+    if (!fs.existsSync(skillsDir))
+        return [];
+    const names = [];
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const marker = readSkillCommandMarker(path.join(skillsDir, entry.name, 'SKILL.md'));
+        if (marker)
+            names.push(marker);
+    }
+    return names.sort();
+}
+export function commandSkillMatches(agentDir, commandName, sourcePath) {
+    const skillMdPath = path.join(agentDir, 'skills', commandSkillName(commandName), 'SKILL.md');
+    if (!fs.existsSync(skillMdPath))
+        return false;
+    try {
+        return fs.readFileSync(skillMdPath, 'utf-8') === buildCommandSkillContent(commandName, sourcePath);
+    }
+    catch {
+        return false;
+    }
+}
+export function removeCommandSkillFromVersion(agentDir, commandName) {
+    const skillDir = path.join(agentDir, 'skills', commandSkillName(commandName));
+    const skillMdPath = path.join(skillDir, 'SKILL.md');
+    if (readSkillCommandMarker(skillMdPath) !== commandName) {
+        return { success: true };
+    }
+    try {
+        fs.rmSync(skillDir, { recursive: true, force: true });
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}

package/dist/lib/commands.d.ts

@@ -1,14 +1,26 @@
+/**
+ * Slash command management -- discovery, installation, and syncing.
+ *
+ * Commands are markdown files in ~/.agents/commands/ exposed as `/command-name`
+ * shortcuts by agents. This module discovers them, converts between formats
+ * (markdown for Claude/Codex, TOML for Gemini), and installs them into
+ * agent version homes.
+ */
 import type { AgentId, CommandInstallation } from './types.js';
+/** Scope of a command: user-global or project-local. */
 export type CommandScope = 'user' | 'project';
+/** Parsed metadata from a command file's YAML frontmatter. */
 export interface CommandMetadata {
     name: string;
     description: string;
 }
+/** Result of validating command metadata. */
 export interface ValidationResult {
     valid: boolean;
     errors: string[];
     warnings: string[];
 }
+/** A command discovered in a repository's commands/ directory. */
 export interface DiscoveredCommand {
     name: string;
     description: string;
@@ -16,16 +28,22 @@ export interface DiscoveredCommand {
     isShared: boolean;
     validation: ValidationResult;
 }
+/** A command installed in an agent's config directory. */
 export interface InstalledCommand {
     name: string;
     scope: CommandScope;
     path: string;
     description?: string;
 }
+/** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
 export declare function parseCommandMetadata(filePath: string): CommandMetadata | null;
+/** Validate command metadata, returning errors and warnings. */
 export declare function validateCommandMetadata(metadata: CommandMetadata | null, commandName: string): ValidationResult;
+/** Discover all command markdown files in a repository's commands/ directory. */
 export declare function discoverCommands(repoPath: string): DiscoveredCommand[];
+/** Find the source path for a command in a repository. */
 export declare function resolveCommandSource(repoPath: string, commandName: string): string | null;
+/** Install a command into an agent's config directory, with optional format conversion. */
 export declare function installCommand(sourcePath: string, agentId: AgentId, commandName: string, method?: 'symlink' | 'copy'): CommandInstallation & {
     error?: string;
     warnings?: string[];
@@ -77,7 +95,9 @@ export declare function iterCommandsCapableVersions(filter?: {
     agent: AgentId;
     version: string;
 }>;
+/** Remove a command from an agent's config directory. */
 export declare function uninstallCommand(agentId: AgentId, commandName: string): boolean;
+/** List command names installed for an agent in the active version home. */
 export declare function listInstalledCommands(agentId: AgentId): string[];
 /**
  * Check if a command exists for an agent.
@@ -106,7 +126,8 @@ export declare function installCommandCentrally(sourcePath: string, commandName:
     warnings?: string[];
 };
 /**
- * List commands from central ~/.agents/commands/ directory.
+ * List commands from user (~/.agents/commands/) and system (~/.agents-system/commands/) dirs.
+ * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralCommands(): string[];
 /**
@@ -118,4 +139,3 @@ export declare function getCommandInfo(name: string): {
     path: string;
     content: string;
 } | null;
-//# sourceMappingURL=commands.d.ts.map

package/dist/lib/commands.js

@@ -1,10 +1,20 @@
+/**
+ * Slash command management -- discovery, installation, and syncing.
+ *
+ * Commands are markdown files in ~/.agents/commands/ exposed as `/command-name`
+ * shortcuts by agents. This module discovers them, converts between formats
+ * (markdown for Claude/Codex, TOML for Gemini), and installs them into
+ * agent version homes.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { AGENTS, COMMANDS_CAPABLE_AGENTS, ensureCommandsDir } from './agents.js';
 import { markdownToToml } from './convert.js';
-import { getCommandsDir, getProjectAgentsDir } from './state.js';
+import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
+import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
+/** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
 export function parseCommandMetadata(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
@@ -40,6 +50,7 @@ export function parseCommandMetadata(filePath) {
         return null;
     }
 }
+/** Validate command metadata, returning errors and warnings. */
 export function validateCommandMetadata(metadata, commandName) {
     const errors = [];
     const warnings = [];
@@ -61,6 +72,7 @@ export function validateCommandMetadata(metadata, commandName) {
     }
     return { valid: errors.length === 0, errors, warnings };
 }
+/** Discover all command markdown files in a repository's commands/ directory. */
 export function discoverCommands(repoPath) {
     const commands = [];
     const commandsDir = path.join(repoPath, 'commands');
@@ -93,6 +105,7 @@ function extractDescription(content) {
     const firstLine = content.split('\n').find((l) => l.trim() && !l.startsWith('---'));
     return firstLine?.slice(0, 80) || '';
 }
+/** Find the source path for a command in a repository. */
 export function resolveCommandSource(repoPath, commandName) {
     const commandPath = path.join(repoPath, 'commands', `${commandName}.md`);
     if (fs.existsSync(commandPath)) {
@@ -100,6 +113,7 @@ export function resolveCommandSource(repoPath, commandName) {
     }
     return null;
 }
+/** Install a command into an agent's config directory, with optional format conversion. */
 export function installCommand(sourcePath, agentId, commandName, method = 'symlink') {
     // Validate command metadata before installation
     const metadata = parseCommandMetadata(sourcePath);
@@ -149,6 +163,11 @@ export function getVersionCommandsDir(agent, version) {
  * List command names (without extension) installed in a specific version home.
  */
 export function listCommandsInVersionHome(agent, version) {
+    const versionHome = getVersionHomePath(agent, version);
+    const agentDir = path.join(versionHome, `.${agent}`);
+    if (shouldInstallCommandAsSkill(agent, version)) {
+        return listCommandSkillsInVersion(agentDir);
+    }
     const dir = getVersionCommandsDir(agent, version);
     if (!fs.existsSync(dir))
         return [];
@@ -166,6 +185,11 @@ function versionCommandMatches(agent, version, commandName) {
     const sourcePath = path.join(getCommandsDir(), `${commandName}.md`);
     if (!fs.existsSync(sourcePath))
         return false;
+    const versionHome = getVersionHomePath(agent, version);
+    const agentDir = path.join(versionHome, `.${agent}`);
+    if (shouldInstallCommandAsSkill(agent, version)) {
+        return commandSkillMatches(agentDir, commandName, sourcePath);
+    }
     const agentConfig = AGENTS[agent];
     const ext = agentConfig.format === 'toml' ? '.toml' : '.md';
     const installedPath = path.join(getVersionCommandsDir(agent, version), `${commandName}${ext}`);
@@ -220,6 +244,14 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
     if (!fs.existsSync(sourcePath)) {
         return { success: false, error: `Command '${commandName}' not found in central` };
     }
+    const versionHome = getVersionHomePath(agent, version);
+    const agentDir = path.join(versionHome, `.${agent}`);
+    if (shouldInstallCommandAsSkill(agent, version)) {
+        return installCommandSkillToVersion(agentDir, commandName, sourcePath, [
+            getSkillsDir(),
+            ...getEnabledExtraRepos().map((repo) => path.join(repo.dir, 'skills')),
+        ]);
+    }
     const agentConfig = AGENTS[agent];
     const commandsDir = getVersionCommandsDir(agent, version);
     fs.mkdirSync(commandsDir, { recursive: true });
@@ -249,6 +281,11 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
  * Remove a single command from a specific version home.
  */
 export function removeCommandFromVersion(agent, version, commandName) {
+    const versionHome = getVersionHomePath(agent, version);
+    const agentDir = path.join(versionHome, `.${agent}`);
+    if (shouldInstallCommandAsSkill(agent, version)) {
+        return removeCommandSkillFromVersion(agentDir, commandName);
+    }
     const ext = AGENTS[agent].format === 'toml' ? '.toml' : '.md';
     const targetPath = path.join(getVersionCommandsDir(agent, version), `${commandName}${ext}`);
     if (!fs.existsSync(targetPath) && !fs.lstatSync(targetPath, { throwIfNoEntry: false })) {
@@ -281,6 +318,7 @@ export function iterCommandsCapableVersions(filter) {
     }
     return pairs;
 }
+/** Remove a command from an agent's config directory. */
 export function uninstallCommand(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
@@ -293,6 +331,7 @@ export function uninstallCommand(agentId, commandName) {
     }
     return false;
 }
+/** List command names installed for an agent in the active version home. */
 export function listInstalledCommands(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
@@ -448,7 +487,7 @@ export function installCommandCentrally(sourcePath, commandName) {
             warnings: validation.warnings,
         };
     }
-    const centralDir = getCommandsDir();
+    const centralDir = getUserCommandsDir();
     if (!fs.existsSync(centralDir)) {
         fs.mkdirSync(centralDir, { recursive: true });
     }
@@ -466,17 +505,19 @@ export function installCommandCentrally(sourcePath, commandName) {
     }
 }
 /**
- * List commands from central ~/.agents/commands/ directory.
+ * List commands from user (~/.agents/commands/) and system (~/.agents-system/commands/) dirs.
+ * User dir takes priority; deduplication preserves first occurrence.
  */
 export function listCentralCommands() {
-    const centralDir = getCommandsDir();
-    if (!fs.existsSync(centralDir)) {
-        return [];
+    const seen = new Set();
+    for (const dir of [getUserCommandsDir(), getCommandsDir()]) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const f of fs.readdirSync(dir).filter((f) => f.endsWith('.md'))) {
+            seen.add(f.replace('.md', ''));
+        }
     }
-    return fs
-        .readdirSync(centralDir)
-        .filter((f) => f.endsWith('.md'))
-        .map((f) => f.replace('.md', ''));
+    return Array.from(seen);
 }
 /**
  * Get detailed info about a command from central storage.
@@ -496,4 +537,3 @@ export function getCommandInfo(name) {
         content,
     };
 }
-//# sourceMappingURL=commands.js.map

package/dist/lib/convert.d.ts

@@ -1,11 +1,20 @@
+/**
+ * Format conversion between Markdown (Claude/Codex) and TOML (Gemini) command files.
+ *
+ * Handles frontmatter parsing and bidirectional translation so that slash commands
+ * authored in one format can be synced to agents that expect the other.
+ */
+/** Parsed YAML frontmatter from a Markdown command file. */
 export interface MarkdownFrontmatter {
     description?: string;
     [key: string]: unknown;
 }
+/** Extract YAML frontmatter and body from a Markdown string. Returns empty frontmatter if none found. */
 export declare function parseMarkdownFrontmatter(content: string): {
     frontmatter: MarkdownFrontmatter;
     body: string;
 };
+/** Convert a Markdown command file to Gemini's TOML format, translating $ARGUMENTS to {{args}}. */
 export declare function markdownToToml(skillName: string, markdown: string): string;
+/** Convert a Gemini TOML command file back to Markdown format, translating {{args}} to $ARGUMENTS. */
 export declare function tomlToMarkdown(toml: string): string;
-//# sourceMappingURL=convert.d.ts.map