@phnx-labs/agents-cli 1.20.5 → 1.20.7

package/dist/commands/defaults.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Defaults command tree.
+ *
+ * `agents defaults run ...` manages selector-based defaults for `agents run`.
+ */
+import type { Command } from 'commander';
+export declare function registerDefaultsCommands(program: Command): void;

package/dist/commands/defaults.js

@@ -0,0 +1,89 @@
+/**
+ * Defaults command tree.
+ *
+ * `agents defaults run ...` manages selector-based defaults for `agents run`.
+ */
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { listRunDefaults, setRunDefault, unsetRunDefault, } from '../lib/run-defaults.js';
+function formatRunDefault(entry) {
+    const parts = [];
+    if (entry.defaults.mode)
+        parts.push(`mode ${chalk.white(entry.defaults.mode)}`);
+    if (entry.defaults.model)
+        parts.push(`model ${chalk.white(entry.defaults.model)}`);
+    return `${chalk.cyan(entry.selector.padEnd(22))} ${parts.join('  ')}`;
+}
+export function registerDefaultsCommands(program) {
+    const defaults = program
+        .command('defaults')
+        .description('Manage default options for agents-cli commands');
+    const run = defaults
+        .command('run')
+        .description('Manage selector-based defaults for `agents run`');
+    setHelpSections(run, {
+        examples: `
+      agents defaults run list
+      agents defaults run set 'claude:*' --mode auto --model opus
+      agents defaults run set claude@2.1.45 --mode plan --model sonnet
+      agents defaults run unset 'claude:*'
+    `,
+        notes: `
+      Selectors use <agent>:<version>. Use * for all versions of an agent.
+      Exact selectors override wildcard selectors field by field.
+      Explicit flags on agents run always win over configured defaults.
+    `,
+    });
+    run
+        .command('list')
+        .description('List configured run defaults')
+        .action(() => {
+        const entries = listRunDefaults();
+        if (entries.length === 0) {
+            console.log(chalk.gray('No run defaults configured.'));
+            console.log(chalk.gray("Set one with: agents defaults run set 'claude:*' --mode auto --model opus"));
+            return;
+        }
+        console.log(chalk.bold('Run Defaults\n'));
+        for (const entry of entries) {
+            console.log(`  ${formatRunDefault(entry)}`);
+        }
+    });
+    run
+        .command('set <selector>')
+        .description('Set defaults for an agent/version selector')
+        .option('--mode <mode>', "Default mode: plan, edit, auto, skip. 'full' accepted as alias for skip.")
+        .option('--model <model>', 'Default model or model alias, forwarded via --model')
+        .action((selector, options) => {
+        try {
+            const entry = setRunDefault(selector, {
+                ...(options.mode !== undefined ? { mode: options.mode } : {}),
+                ...(options.model !== undefined ? { model: options.model } : {}),
+            });
+            console.log(chalk.green('Set run default:'));
+            console.log(`  ${formatRunDefault(entry)}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    run
+        .command('unset <selector>')
+        .description('Remove defaults for an agent/version selector')
+        .action((selector) => {
+        try {
+            const removed = unsetRunDefault(selector);
+            if (removed) {
+                console.log(chalk.green(`Removed run default ${selector}`));
+            }
+            else {
+                console.log(chalk.gray(`No run default matched ${selector}`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/exec.js

@@ -85,7 +85,7 @@ export function registerRunCommand(program) {
     `,
     });
     runCmd.action(async (agentSpec, prompt, options) => {
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef }, { resolveRunDefaults },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -94,6 +94,7 @@ export function registerRunCommand(program) {
             import('../lib/versions.js'),
             import('../lib/plugins.js'),
             import('../lib/workflows.js'),
+            import('../lib/run-defaults.js'),
         ]);
         const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
         // Parse agent@version
@@ -102,6 +103,7 @@ export function registerRunCommand(program) {
         let version = rawVersion || undefined;
         let profileEnv;
         let fromProfile = false;
+        let workflowModel;
         const cwd = options.cwd ?? process.cwd();
         if (isValidAgent(rawAgent)) {
             agent = rawAgent;
@@ -133,6 +135,10 @@ export function registerRunCommand(program) {
             //   subagents/*.md     ← flat .md files copied to ~/.claude/agents/ for Agent tool discovery
             const workflowDir = resolveWorkflowRef(rawAgent, cwd);
             agent = 'claude';
+            const workflowFrontmatter = parseWorkflowFrontmatter(workflowDir);
+            if (typeof workflowFrontmatter?.model === 'string' && workflowFrontmatter.model.trim() !== '') {
+                workflowModel = workflowFrontmatter.model.trim();
+            }
             const resolvedVersion = resolveVersionAlias('claude', version);
             const versionHome = getVersionHomePath('claude', resolvedVersion ?? getGlobalDefault('claude') ?? '');
             const claudeAgentsDir = path.join(versionHome, '.claude', 'agents');
@@ -179,8 +185,7 @@ export function registerRunCommand(program) {
             // Auto-inject secrets bundles declared in the workflow's frontmatter `secrets:` field.
             // Union with any --secrets flags the user passed; dedupe. Skip when --no-auto-secrets is set.
             if (!options.noAutoSecrets) {
-                const fm = parseWorkflowFrontmatter(workflowDir);
-                const declared = fm?.secrets ?? [];
+                const declared = workflowFrontmatter?.secrets ?? [];
                 if (declared.length > 0) {
                     const existing = new Set(options.secrets);
                     const added = [];
@@ -262,9 +267,18 @@ export function registerRunCommand(program) {
                 }
             }
         }
+        const defaultVersion = version ?? resolveVersion(agent, cwd);
+        const runDefaults = fromProfile
+            ? { sources: {} }
+            : resolveRunDefaults(agent, defaultVersion, cwd);
         // Accept the four canonical modes plus 'full' as a permanent silent
         // alias for 'skip' (rewritten downstream by normalizeMode in exec.ts).
         let mode = options.mode;
+        const modeSource = runCmd.getOptionValueSource('mode');
+        const modeFromRunDefault = modeSource === 'default' && !!runDefaults.mode;
+        if (modeFromRunDefault) {
+            mode = runDefaults.mode;
+        }
         if (!['plan', 'edit', 'auto', 'skip', 'full'].includes(mode)) {
             console.error(chalk.red(`Invalid mode: ${mode}. Use plan, edit, auto, or skip ('full' accepted as alias for skip).`));
             process.exit(1);
@@ -276,13 +290,12 @@ export function registerRunCommand(program) {
         // user did not ask for read-only, they asked for "just run it." An
         // explicit --mode plan still throws (see resolveMode), because silently
         // elevating an explicit read-only request to edit is unsafe.
-        const modeSource = runCmd.getOptionValueSource('mode');
         const modeIsDefault = modeSource === 'default';
         try {
             resolveMode(agent, normalizeMode(mode));
         }
         catch (err) {
-            if (modeIsDefault) {
+            if (modeIsDefault && !modeFromRunDefault) {
                 mode = defaultModeFor(agent);
                 if (!options.quiet) {
                     process.stderr.write(chalk.gray(`[agents] ${agent} has no '${options.mode}' mode; using '${mode}'\n`));
@@ -334,6 +347,11 @@ export function registerRunCommand(program) {
         const env = hasOverrides
             ? { ...(profileEnv ?? {}), ...secretsEnv, ...(userEnv ?? {}) }
             : undefined;
+        const modelSource = runCmd.getOptionValueSource('model');
+        const model = options.model
+            ?? (!fromProfile && modelSource === undefined
+                ? (workflowModel ?? (options.fallback ? undefined : runDefaults.model))
+                : undefined);
         const execOptions = {
             agent,
             version,
@@ -342,7 +360,7 @@ export function registerRunCommand(program) {
             mode,
             effort,
             cwd: options.cwd,
-            model: options.model,
+            model,
             addDirs: options.addDir,
             json: options.json,
             headless: options.headless ?? true,

package/dist/commands/inspect.d.ts

@@ -1,14 +1,30 @@
 /**
- * `agents inspect <agent>[@version]` — single-agent, single-version detail view.
+ * `agents inspect <target>` — detail view for one agent+version or one DotAgents repo.
  *
- * Summary mode shows the per-version header (paths, shim, capabilities, resource
- * counts, sessions). Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...) list
- * one resource kind; passing a positional query to the same flag fuzzy-searches
- * for a single resource and prints its detail. Resource names render as OSC-8
- * hyperlinks to the marker file (SKILL.md / WORKFLOW.md / AGENT.md / the file
- * itself) so users can click straight to the source.
+ * Agent targets (`claude`, `claude@2.1.170`) show the per-version header (paths,
+ * shim, capabilities, resource counts, sessions). Repo targets (`user`, `system`,
+ * `project`, a registered extra-repo alias, or a filesystem path to a repo with a
+ * `.agents/` dir or to a DotAgents root itself) show the repo root, git state, and
+ * per-kind resource counts. Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...)
+ * list one resource kind for either target form; passing a positional query to the
+ * same flag fuzzy-searches for a single resource and prints its detail. Resource
+ * names render as OSC-8 hyperlinks to the marker file (SKILL.md / WORKFLOW.md /
+ * AGENT.md / the file itself) so users can click straight to the source.
  */
 import { Command } from 'commander';
+/** Resource kinds the inspect command can drill into. */
+declare const DRILLABLE_KINDS: readonly ["commands", "skills", "hooks", "mcp", "rules", "plugins", "workflows", "subagents"];
+type DrillableKind = typeof DRILLABLE_KINDS[number];
+interface ResourceItem {
+    name: string;
+    source: string;
+    /** Absolute path to the resource entry (file or directory). */
+    path: string;
+    /** Path the OSC-8 link should point at — marker file inside bundles, else `path`. */
+    linkTarget: string;
+    /** One-line description (frontmatter `description:` or first non-frontmatter line). */
+    description: string;
+}
 interface InspectOptions {
     brief?: boolean;
     json?: boolean;
@@ -23,4 +39,19 @@ interface InspectOptions {
 }
 export declare function registerInspectCommand(program: Command): void;
 export declare function inspectAction(target: string, options: InspectOptions): Promise<void>;
+export interface RepoTarget {
+    /** Display label: 'user' | 'system' | 'project', an extra-repo alias, or a path-derived name. */
+    label: string;
+    /** Absolute path to the DotAgents root (the dir holding commands/, skills/, ...). */
+    root: string;
+}
+/**
+ * Resolve a non-agent target as a DotAgents repo: the built-in layer names,
+ * a registered extra-repo alias, or a filesystem path. Paths accept either a
+ * DotAgents root itself or a repo whose `.agents/` dir should be inspected.
+ * Returns null when the target is none of these.
+ */
+export declare function resolveRepoTarget(target: string, cwd?: string): RepoTarget | null;
+/** List one resource kind from a single repo root — no layering, no overrides. */
+export declare function collectRepoKind(repo: RepoTarget, kind: DrillableKind): ResourceItem[];
 export {};

package/dist/commands/inspect.js

@@ -1,13 +1,17 @@
 /**
- * `agents inspect <agent>[@version]` — single-agent, single-version detail view.
+ * `agents inspect <target>` — detail view for one agent+version or one DotAgents repo.
  *
- * Summary mode shows the per-version header (paths, shim, capabilities, resource
- * counts, sessions). Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...) list
- * one resource kind; passing a positional query to the same flag fuzzy-searches
- * for a single resource and prints its detail. Resource names render as OSC-8
- * hyperlinks to the marker file (SKILL.md / WORKFLOW.md / AGENT.md / the file
- * itself) so users can click straight to the source.
+ * Agent targets (`claude`, `claude@2.1.170`) show the per-version header (paths,
+ * shim, capabilities, resource counts, sessions). Repo targets (`user`, `system`,
+ * `project`, a registered extra-repo alias, or a filesystem path to a repo with a
+ * `.agents/` dir or to a DotAgents root itself) show the repo root, git state, and
+ * per-kind resource counts. Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...)
+ * list one resource kind for either target form; passing a positional query to the
+ * same flag fuzzy-searches for a single resource and prints its detail. Resource
+ * names render as OSC-8 hyperlinks to the marker file (SKILL.md / WORKFLOW.md /
+ * AGENT.md / the file itself) so users can click straight to the source.
  */
+import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -15,7 +19,7 @@ import chalk from 'chalk';
 import * as yaml from 'yaml';
 import { AGENTS, getCliState } from '../lib/agents.js';
 import { supports } from '../lib/capabilities.js';
-import { readMeta } from '../lib/state.js';
+import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
 import { getAgentResources, listResources, } from '../lib/resources.js';
@@ -39,8 +43,8 @@ const CAPABILITY_NAMES = [
 // ─── Command registration ────────────────────────────────────────────────────
 export function registerInspectCommand(program) {
     const cmd = program
-        .command('inspect <agent>')
-        .description('Inspect one installed agent at one version — paths, capabilities, resources, drill into any kind.')
+        .command('inspect <target>')
+        .description('Inspect one installed agent at one version, or a DotAgents repo (user|system|project|alias|path) — paths, capabilities, resources, drill into any kind.')
         .option('--brief', 'header + capabilities only; skip resources/sessions')
         .option('--json', 'machine-readable JSON output');
     for (const kind of DRILLABLE_KINDS) {
@@ -52,6 +56,20 @@ export function registerInspectCommand(program) {
 }
 // ─── Main dispatcher ─────────────────────────────────────────────────────────
 export async function inspectAction(target, options) {
+    const agentKey = target.split('@')[0].toLowerCase();
+    if (!(agentKey in AGENTS)) {
+        const repo = resolveRepoTarget(target);
+        if (repo) {
+            await inspectRepo(repo, options);
+            return;
+        }
+        const extras = getEnabledExtraRepos();
+        console.error(chalk.red(`Unknown target: ${target}`));
+        console.error(chalk.gray(`Agents: ${Object.keys(AGENTS).join(', ')}`));
+        const aliases = extras.length > 0 ? `, ${extras.map(e => e.alias).join(', ')}` : '';
+        console.error(chalk.gray(`Repos:  user, system, project${aliases} — or a path to a repo with a .agents/ dir`));
+        process.exit(1);
+    }
     const { agent, version } = parseTarget(target);
     const versionHome = getVersionHomePath(agent, version);
     if (!fs.existsSync(versionHome)) {
@@ -75,13 +93,7 @@ export async function inspectAction(target, options) {
 }
 function parseTarget(target) {
     const [rawAgent, rawVersion] = target.split('@');
-    const agentKey = (rawAgent || '').toLowerCase();
-    if (!(agentKey in AGENTS)) {
-        console.error(chalk.red(`Unknown agent: ${rawAgent}`));
-        console.error(chalk.gray(`Known agents: ${Object.keys(AGENTS).join(', ')}`));
-        process.exit(1);
-    }
-    const agent = agentKey;
+    const agent = (rawAgent || '').toLowerCase();
     let version = rawVersion;
     if (!version || version === 'default') {
         const meta = readMeta();
@@ -110,6 +122,160 @@ function pickDrillKind(options) {
     }
     return active[0];
 }
+/** Files at a DotAgents root that mark it as one, beyond the per-kind dirs. */
+const REPO_MARKER_FILES = ['agents.yaml', 'hooks.yaml'];
+/**
+ * Resolve a non-agent target as a DotAgents repo: the built-in layer names,
+ * a registered extra-repo alias, or a filesystem path. Paths accept either a
+ * DotAgents root itself or a repo whose `.agents/` dir should be inspected.
+ * Returns null when the target is none of these.
+ */
+export function resolveRepoTarget(target, cwd) {
+    if (target === 'user')
+        return { label: 'user', root: getUserAgentsDir() };
+    if (target === 'system')
+        return { label: 'system', root: getSystemAgentsDir() };
+    if (target === 'project') {
+        const dir = getProjectAgentsDir(cwd);
+        if (!dir) {
+            console.error(chalk.red('No project .agents/ directory found from the current directory.'));
+            process.exit(1);
+        }
+        return { label: 'project', root: dir };
+    }
+    for (const extra of getEnabledExtraRepos()) {
+        if (extra.alias === target)
+            return { label: extra.alias, root: extra.dir };
+    }
+    const expanded = target.startsWith('~/') ? path.join(os.homedir(), target.slice(2)) : target;
+    const abs = path.resolve(cwd ?? process.cwd(), expanded);
+    const stat = safeStat(abs);
+    if (!stat || !stat.isDirectory())
+        return null;
+    // A dir that is itself a DotAgents root wins over its nested .agents/ —
+    // extra repos like ~/.agents-extras keep resources at the top level and use
+    // .agents/ only for worktrees.
+    if (isDotAgentsRoot(abs)) {
+        const label = path.basename(abs) === '.agents' ? path.basename(path.dirname(abs)) : path.basename(abs);
+        return { label, root: abs };
+    }
+    if (path.basename(abs) !== '.agents') {
+        const nested = path.join(abs, '.agents');
+        if (safeStat(nested)?.isDirectory()) {
+            return { label: path.basename(abs), root: nested };
+        }
+    }
+    return null;
+}
+function isDotAgentsRoot(dir) {
+    for (const marker of REPO_MARKER_FILES) {
+        if (fs.existsSync(path.join(dir, marker)))
+            return true;
+    }
+    for (const kind of DRILLABLE_KINDS) {
+        if (safeStat(path.join(dir, kind))?.isDirectory())
+            return true;
+    }
+    return false;
+}
+async function inspectRepo(repo, options) {
+    const drill = pickDrillKind(options);
+    const jsonHead = { repo: repo.label, root: repo.root };
+    if (drill) {
+        const items = collectRepoKind(repo, drill.kind);
+        if (drill.query === true || drill.query === undefined) {
+            renderItemList(repo.label, jsonHead, drill.kind, items, options);
+        }
+        else {
+            renderItemDetail(repo.label, jsonHead, drill.kind, String(drill.query), items, options);
+        }
+        return;
+    }
+    renderRepoSummary(repo, options);
+}
+/** List one resource kind from a single repo root — no layering, no overrides. */
+export function collectRepoKind(repo, kind) {
+    const dir = path.join(repo.root, kind);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const items = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const p = path.join(dir, entry.name);
+        items.push({
+            name: entry.name.replace(/\.(md|yaml|yml|toml|json)$/, ''),
+            source: repo.label,
+            path: p,
+            linkTarget: linkTarget(p),
+            description: readDescription(p),
+        });
+    }
+    return items.sort((a, b) => a.name.localeCompare(b.name));
+}
+function renderRepoSummary(repo, options) {
+    const git = repoGitInfo(repo.root);
+    const manifests = REPO_MARKER_FILES.filter(m => fs.existsSync(path.join(repo.root, m)));
+    const counts = {};
+    if (!options.brief) {
+        for (const kind of DRILLABLE_KINDS) {
+            const items = collectRepoKind(repo, kind);
+            counts[kind] = { total: items.length, bySource: { [repo.label]: items.length } };
+        }
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            repo: repo.label,
+            root: repo.root,
+            git,
+            manifests,
+            resources: options.brief ? null : Object.fromEntries(DRILLABLE_KINDS.map(kind => [kind, counts[kind].total])),
+        }, null, 2));
+        return;
+    }
+    console.log('\n' + chalk.bold(repo.label) + '  ' + chalk.gray('[dotagents repo]') + '\n');
+    const rows = [['root', termLink(repo.root, repo.root)]];
+    if (git) {
+        const dirty = git.dirty > 0 ? ` ${chalk.gray('·')} ${chalk.yellow(`${git.dirty} dirty`)}` : '';
+        const url = git.url ? ` ${chalk.gray('·')} ${chalk.gray(git.url)}` : '';
+        rows.push(['git', `${git.branch}${dirty}${url}`]);
+    }
+    if (manifests.length > 0)
+        rows.push(['manifests', manifests.join(', ')]);
+    for (const [k, v] of rows)
+        console.log(`  ${k.padEnd(10)} ${v}`);
+    if (!options.brief) {
+        console.log('\n' + chalk.bold('Resources'));
+        for (const kind of DRILLABLE_KINDS) {
+            console.log(`  ${kind.padEnd(10)} ${String(counts[kind].total).padStart(4)}`);
+        }
+    }
+    console.log('');
+    console.log(chalk.gray(`Drill in:   agents inspect ${repo.label} --skills <query>`));
+    console.log('');
+}
+function repoGitInfo(root) {
+    const git = (args) => {
+        try {
+            return execSync(`git -C ${JSON.stringify(root)} ${args}`, { stdio: ['ignore', 'pipe', 'ignore'] })
+                .toString().trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    const branch = git('rev-parse --abbrev-ref HEAD');
+    if (branch === null)
+        return null;
+    const status = git('status --porcelain');
+    const dirty = status ? status.split('\n').filter(Boolean).length : 0;
+    return { branch, dirty, url: git('remote get-url origin') };
+}
 // ─── Summary mode ────────────────────────────────────────────────────────────
 async function renderSummary(agent, version, versionHome, options) {
     const meta = readMeta();
@@ -184,17 +350,19 @@ async function renderSummary(agent, version, versionHome, options) {
 // ─── List mode ───────────────────────────────────────────────────────────────
 async function renderList(agent, version, versionHome, kind, options) {
     const items = collectKind(agent, versionHome, kind);
+    renderItemList(`${agent}@${version}`, { agent, version }, kind, items, options);
+}
+function renderItemList(header, jsonHead, kind, items, options) {
     if (options.json) {
         console.log(JSON.stringify({
-            agent,
-            version,
+            ...jsonHead,
             kind,
             count: items.length,
             items: items.map(i => ({ name: i.name, source: i.source, path: i.path, description: i.description })),
         }, null, 2));
         return;
     }
-    console.log('\n' + chalk.bold(`${agent}@${version}`) + '  ' + chalk.gray(`${kind} (${items.length})`) + '\n');
+    console.log('\n' + chalk.bold(header) + '  ' + chalk.gray(`${kind} (${items.length})`) + '\n');
     if (items.length === 0) {
         console.log(chalk.gray(`  (none installed)`));
         console.log('');
@@ -212,11 +380,14 @@ async function renderList(agent, version, versionHome, kind, options) {
 // ─── Detail mode (fuzzy) ─────────────────────────────────────────────────────
 async function renderDetail(agent, version, versionHome, kind, query, options) {
     const items = collectKind(agent, versionHome, kind);
+    renderItemDetail(`${agent}@${version}`, { agent, version }, kind, query, items, options);
+}
+function renderItemDetail(header, jsonHead, kind, query, items, options) {
     const matches = findMatches(items, query);
     if (matches.length === 0) {
         const suggestions = suggestClosest(items, query, 3);
         if (options.json) {
-            console.log(JSON.stringify({ agent, version, kind, query, match: null, suggestions: suggestions.map(s => s.name) }, null, 2));
+            console.log(JSON.stringify({ ...jsonHead, kind, query, match: null, suggestions: suggestions.map(s => s.name) }, null, 2));
         }
         else {
             console.error(chalk.red(`No ${kind} matching '${query}'.`));
@@ -231,8 +402,7 @@ async function renderDetail(agent, version, versionHome, kind, query, options) {
     if (options.json) {
         const detail = buildDetail(best.item, kind);
         console.log(JSON.stringify({
-            agent,
-            version,
+            ...jsonHead,
             kind,
             query,
             match: { ...detail, matchKind: best.matchKind },
@@ -240,7 +410,7 @@ async function renderDetail(agent, version, versionHome, kind, query, options) {
         }, null, 2));
         return;
     }
-    console.log('\n' + chalk.bold(`${agent}@${version}`) + '  ' + chalk.gray(`${kind} matching "${query}"`) + '\n');
+    console.log('\n' + chalk.bold(header) + '  ' + chalk.gray(`${kind} matching "${query}"`) + '\n');
     const matchTag = best.matchKind === 'exact' ? 'exact' : best.matchKind === 'substring' ? 'substring' : `~${best.distance}`;
     console.log(`  ${chalk.green('✓')}  ${termLink(chalk.bold.cyan(best.item.name), best.item.linkTarget)}  ${chalk.gray(`[${matchTag}, ${best.item.source}]`)}`);
     if (best.item.description) {

package/dist/commands/rules.js

@@ -4,7 +4,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { select, checkbox } from '@inquirer/prompts';
-import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { AGENTS, agentConfigDirName, ALL_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.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';
@@ -426,7 +426,7 @@ Examples:
                 return;
             }
             const home = getVersionHomePath(agentId, requestedVersion);
-            const filePath = path.join(home, `.${agentId}`, AGENTS[agentId].instructionsFile);
+            const filePath = path.join(home, agentConfigDirName(agentId), AGENTS[agentId].instructionsFile);
             if (!fs.existsSync(filePath)) {
                 console.log(chalk.yellow(`No user rules found for ${agentLabel(agentId)}@${requestedVersion}`));
                 return;
@@ -486,7 +486,7 @@ Examples:
             }
             const home = getVersionHomePath(agentId, requestedVersion);
             const agent = AGENTS[agentId];
-            const filePath = path.join(home, `.${agentId}`, agent.instructionsFile);
+            const filePath = path.join(home, agentConfigDirName(agentId), agent.instructionsFile);
             if (fs.existsSync(filePath)) {
                 fs.unlinkSync(filePath);
                 console.log(chalk.green(`Removed ${agent.instructionsFile} from ${agentLabel(agent.id)}@${requestedVersion}`));

package/dist/commands/secrets.js

@@ -1052,15 +1052,15 @@ Examples:
             password += charClass[charIndex];
         }
         if (opts.copy) {
-            const { spawn } = await import('child_process');
-            const proc = spawn('pbcopy', [], { stdio: ['pipe', 'inherit', 'inherit'] });
-            proc.stdin.write(password);
-            proc.stdin.end();
-            await new Promise((resolve, reject) => {
-                proc.on('close', (code) => code === 0 ? resolve() : reject(new Error('pbcopy failed')));
-                proc.on('error', reject);
-            });
-            console.log(chalk.green(`Password copied to clipboard (${length} chars)`));
+            try {
+                await copyToClipboard(password);
+                console.log(chalk.green(`Password copied to clipboard (${length} chars)`));
+            }
+            catch (err) {
+                console.error(chalk.red(`Clipboard copy failed: ${err.message}`));
+                console.error(chalk.gray('Re-run without --copy to print the password instead.'));
+                process.exitCode = 1;
+            }
         }
         else {
             console.log(password);
@@ -1069,3 +1069,40 @@ Examples:
     registerSecretsSyncCommands(cmd);
     registerSecretsMigrateAclCommand(cmd);
 }
+/**
+ * Copy text to the system clipboard, cross-platform.
+ * macOS: `pbcopy`. Windows: `clip`. Linux: tries `wl-copy` (Wayland), then
+ * `xclip`, then `xsel` (X11). Throws with an install hint if none are present.
+ */
+async function copyToClipboard(text) {
+    const { spawn } = await import('child_process');
+    const candidates = process.platform === 'darwin'
+        ? [['pbcopy', []]]
+        : process.platform === 'win32'
+            ? [['clip', []]]
+            : [
+                ['wl-copy', []],
+                ['xclip', ['-selection', 'clipboard']],
+                ['xsel', ['--clipboard', '--input']],
+            ];
+    let lastErr = null;
+    for (const [cmd, args] of candidates) {
+        try {
+            await new Promise((resolve, reject) => {
+                const proc = spawn(cmd, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+                proc.on('error', reject);
+                proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`${cmd} exited ${code}`))));
+                proc.stdin.write(text);
+                proc.stdin.end();
+            });
+            return;
+        }
+        catch (err) {
+            lastErr = err;
+        }
+    }
+    const hint = process.platform === 'linux'
+        ? ' Install one: wl-clipboard (Wayland) or xclip / xsel (X11).'
+        : '';
+    throw new Error(`no clipboard tool available (${lastErr?.message ?? 'none found'}).${hint}`);
+}