browser-debugger-cli 0.11.0 → 0.13.0

package/dist/commands/dom/semanticUtils.js

@@ -5,7 +5,7 @@
  * their surrounding DOM context and to fall back gracefully when only one
  * of the two data sources is available.
  */
-import { MASKED_VALUE } from '../../runtime/dom/elementInfo.js';
+import { MASKED_VALUE, isLabelClass } from '../../runtime/dom/elementInfo.js';
 import { synthesizeA11yNode } from '../../telemetry/roleInference.js';
 import { keyAttributeItems } from '../../ui/formatters/keyAttributes.js';
 import { joinLines } from '../../ui/formatting.js';
@@ -29,9 +29,8 @@ function buildContextText(node, domContext) {
     }
     if (domContext) {
         const tagPart = `<${domContext.tag}`;
-        const classPart = domContext.classes && domContext.classes.length > 0
-            ? `.${domContext.classes.slice(0, 3).join('.')}`
-            : '';
+        const classes = (domContext.classes ?? []).filter(isLabelClass).slice(0, 3);
+        const classPart = classes.length > 0 ? `.${classes.join('.')}` : '';
         const previewPart = domContext.preview && !domContext.text ? ` "${domContext.preview}"` : '';
         return ` ${tagPart}${classPart}>${previewPart}`;
     }
@@ -86,10 +85,11 @@ function buildPropertiesText(node) {
  * link's href, a field's type and name), like `dom query` does, and is
  * followed by up to 500 characters of the element's text
  * (all of it with `dom get --full`) when it is longer than the one-line
- * preview, or, for an element without text or name, what it holds.
+ * preview or the role line shows an accessible name other than the text,
+ * or, for an element without text or name, what it holds.
  *
  * @param data - Accessibility node and optional DOM context
- * @returns Role line, plus a text line for elements with longer text
+ * @returns Role line, plus a text line for elements with longer or differently named text
  */
 export function formatSemanticNodeWithContext(data) {
     const { node, domContext } = data;
@@ -99,13 +99,44 @@ export function formatSemanticNodeWithContext(data) {
     const propsText = buildPropertiesText(node);
     const inferredText = node.inferred ? ' (inferred from DOM)' : '';
     const line = `${roleText}${contextText}${keysText}${propsText}${inferredText}`;
-    if (domContext?.text)
-        return joinLines(line, elementTextLine(domContext.text));
+    const text = textNotOnRoleLine(node, domContext);
+    if (text)
+        return joinLines(line, elementTextLine(text));
     if (domContext?.childCount !== undefined && !node.name) {
-        return joinLines(line, emptyElementLine(domContext.children ?? [], domContext.childCount));
+        return joinLines(line, emptyElementLine(domContext.children ?? [], domContext.childCount, domContext.shadowChildren));
     }
     return line;
 }
+/**
+ * The element's text when the role line does not show it: text longer than
+ * the one-line preview, or the visible text of an element whose accessible
+ * name is something else (an editor named by its aria-label), unless its
+ * name or value shows that text (a long heading with inline children is
+ * named by all of it). Texts are compared ignoring case and whitespace.
+ * A sensitive field's text is never shown.
+ *
+ * @param node - Accessibility node
+ * @param domContext - DOM context with the text
+ * @returns Text for the text line, or undefined
+ */
+function textNotOnRoleLine(node, domContext) {
+    if (domContext?.sensitive)
+        return undefined;
+    const text = domContext?.text ?? (node.name ? domContext?.preview : undefined);
+    if (!text)
+        return undefined;
+    const shown = [node.name, node.value].map((value) => comparableText(value ?? ''));
+    return shown.includes(comparableText(text)) ? undefined : text;
+}
+/**
+ * Text in the form texts are compared in.
+ *
+ * @param text - Text
+ * @returns Lowercased text with whitespace collapsed
+ */
+function comparableText(text) {
+    return text.replace(/\s+/g, ' ').trim().toLowerCase();
+}
 /**
  * Resolve an a11y node, falling back to a DOM-synthesized one when only
  * DOM context is available. Returns null when neither source can produce one.

package/dist/commands/dom/wait.js

@@ -24,7 +24,7 @@ export function registerWaitCommand(dom) {
     dom
         .command('wait')
         .description('Wait until elements appear, become visible, contain a text or are gone (or the page loads)')
-        .argument('[selector]', 'CSS selector (:has-text, :visible allowed; shadow DOM and same-origin iframes searched); optional with --load')
+        .argument('[selector]', 'CSS selector (:has-text, :visible allowed; shadow DOM and same-origin iframes searched); without one, waits for the page to load (--load)')
         .option('--text <text>', 'A match must contain this text (case-insensitive)')
         .option('--visible', 'Only count visible matches')
         .option('--gone', 'Wait until no element matches (none visible, with --visible)')
@@ -44,7 +44,9 @@ export function registerWaitCommand(dom) {
  * @returns Command result
  */
 async function waitFor(selector, options) {
-    const needsSelector = options.text !== undefined || options.gone === true || !options.load;
+    const load = options.load === true ||
+        (selector === undefined && options.text === undefined && !options.gone && !options.visible);
+    const needsSelector = options.text !== undefined || options.gone === true || !load;
     if (selector === undefined && needsSelector) {
         const err = waitTargetRequiredError();
         return {
@@ -58,7 +60,7 @@ async function waitFor(selector, options) {
         ...filterDefined({ selector, text: options.text }),
         ...(options.gone && { gone: true }),
         ...(options.visible && { visible: true }),
-        ...(options.load && { load: true }),
+        ...(load && { load: true }),
         timeout: options.timeout,
     });
     if (response.status === 'error' || !response.data) {

package/dist/commands/helpJson.d.ts

@@ -78,9 +78,30 @@ export interface CommandMetadata {
     arguments: ArgumentMetadata[];
     /** Command options */
     options: OptionMetadata[];
+    /** Text shown after the options in `--help` (examples, output legend) */
+    helpText?: string;
     /** Subcommands */
     subcommands: CommandMetadata[];
 }
+/**
+ * Command summary for the compact root help: one-line description, arguments
+ * and flags with their descriptions (behaviors, defaults and choices are in
+ * `bdg <command> --help --json`).
+ */
+export interface CompactCommand {
+    /** Command name */
+    name: string;
+    /** Command aliases (only when it has some) */
+    aliases?: readonly string[];
+    /** First line of the description */
+    description: string;
+    /** Arguments as in usage, e.g. "<selector> [index]" (only when it takes some) */
+    arguments?: string;
+    /** Visible options: flags to description */
+    options?: Record<string, string>;
+    /** Subcommands (only for command groups) */
+    subcommands?: CompactCommand[];
+}
 /**
  * Runtime state information for dynamic command availability.
  */
@@ -112,7 +133,7 @@ export interface Capabilities {
     };
 }
 /**
- * Root machine-readable help structure.
+ * Root machine-readable help structure (`bdg --help --json --full`).
  */
 export interface MachineReadableHelp {
     /** CLI name */
@@ -142,10 +163,34 @@ export interface MachineReadableHelp {
     capabilities: Capabilities;
 }
 /**
- * Generates machine-readable help from a Commander program.
+ * Compact root help (`bdg --help --json`): the full help with a command tree
+ * of names, one-line descriptions and flags.
+ */
+export interface CompactHelp extends Omit<MachineReadableHelp, 'command'> {
+    /** Where the details are */
+    details: string;
+    /** Root command summary */
+    command: CompactCommand;
+}
+/**
+ * Help for one command (`bdg <command> --help --json`): its full metadata
+ * (option behaviors, defaults, choices, help text), its subcommands in compact
+ * form, and the exit codes.
+ */
+export interface CommandHelp extends Pick<MachineReadableHelp, 'name' | 'version' | 'description' | 'exitCodes'> {
+    /** Full command path, e.g. "bdg dom query" */
+    path: string;
+    /** Command metadata; subcommands summarized (ask each for its details) */
+    command: Omit<CommandMetadata, 'subcommands'> & {
+        subcommands: CompactCommand[];
+    };
+}
+/**
+ * Generates the full machine-readable help from a Commander program
+ * (`bdg --help --json --full`).
  *
  * Includes comprehensive metadata for agent discovery:
- * - Command structure and options
+ * - Command structure and options with behaviors
  * - Exit codes with semantic meanings
  * - Task-to-command mappings with CDP alternatives
  * - Runtime state and command availability
@@ -154,34 +199,52 @@ export interface MachineReadableHelp {
  *
  * @param program - Commander program instance
  * @returns Machine-readable help structure
+ */
+export declare function generateMachineReadableHelp(program: Command): MachineReadableHelp;
+/**
+ * Generates the compact root help (`bdg --help --json`): the full help with
+ * the command tree reduced to names, one-line descriptions and flags.
+ *
+ * @param program - Commander program instance
+ * @returns Compact help structure
+ */
+export declare function generateCompactHelp(program: Command): CompactHelp;
+/**
+ * The command a command line addresses: follows the words that name
+ * subcommands and skips the others (option values, arguments), stopping at a
+ * command without subcommands.
+ *
+ * @param program - Root Commander program instance
+ * @param words - Command-line words, e.g. ['dom', 'query', '.item']
+ * @returns The addressed command (the program when no word names one)
  *
  * @example
  * ```typescript
- * import { program } from 'commander';
- * import { generateMachineReadableHelp } from './help/machineReadableHelp.js';
- *
- * const help = generateMachineReadableHelp(program);
- * console.log(JSON.stringify(help, null, 2));
+ * resolveCommand(program, ['--session', 'a', 'dom', 'query', '.item']).name(); // 'query'
  * ```
  */
-export declare function generateMachineReadableHelp(program: Command): MachineReadableHelp;
+export declare function resolveCommand(program: Command, words: string[]): Command;
 /**
- * Generates machine-readable help for a specific subcommand.
+ * Full command path, e.g. "bdg dom query".
  *
- * Returns the same structure as generateMachineReadableHelp but with
- * the command field focused on the requested subcommand. If the subcommand
- * is not found, falls back to full root help.
+ * @param command - Commander command instance
+ * @returns Names from the program down to the command
+ */
+export declare function commandPath(command: Command): string;
+/**
+ * Generates machine-readable help for one command: its full metadata,
+ * compact subcommands (a group lists them like the root help does) and the
+ * exit codes.
  *
  * @param program - Root Commander program instance
- * @param commandPath - Array of command names (e.g., ['dom', 'query'])
- * @returns Machine-readable help structure for the subcommand
+ * @param command - The command (from {@link resolveCommand})
+ * @returns Help for the command
  *
  * @example
  * ```typescript
- * // Get help for 'bdg dom query'
- * const help = generateSubcommandHelp(program, ['dom', 'query']);
- * console.log(help.command.name); // 'query'
+ * const help = generateCommandHelp(program, resolveCommand(program, ['dom', 'query']));
+ * console.log(help.path); // 'bdg dom query'
  * ```
  */
-export declare function generateSubcommandHelp(program: Command, commandPath: string[]): MachineReadableHelp;
+export declare function generateCommandHelp(program: Command, command: Command): CommandHelp;
 //# sourceMappingURL=helpJson.d.ts.map

package/dist/commands/helpJson.js

@@ -4,6 +4,7 @@
 import { getAllDomainSummaries } from '../cdp/schema.js';
 import { getOptionBehavior } from './optionBehaviors.js';
 import { readLiveDaemonPid } from '../session/cleanup/staleSession.js';
+import { helpJsonDetailsNote } from '../ui/messages/commands.js';
 import { getAllDecisionTrees } from '../utils/decisionTrees.js';
 import { EXIT_CODE_REGISTRY } from '../utils/exitCodes.js';
 import { getAllTaskMappings } from '../utils/taskMappings.js';
@@ -65,6 +66,21 @@ function convertArgument(argument) {
     }
     return metadata;
 }
+/**
+ * The text a command adds after its options in `--help` (examples, output
+ * legend), collected from its `afterHelp` listeners. Commander's Command is an
+ * EventEmitter at runtime; its typings leave that out.
+ *
+ * @param command - Commander command instance
+ * @returns The text, or undefined when the command adds none
+ */
+function afterHelpText(command) {
+    const chunks = [];
+    const emitter = command;
+    emitter.emit('afterHelp', { error: false, command, write: (text) => chunks.push(text) });
+    const text = chunks.join('').trim();
+    return text || undefined;
+}
 /**
  * Recursively converts a Commander Command to CommandMetadata.
  *
@@ -75,6 +91,7 @@ function convertArgument(argument) {
  */
 function convertCommand(command) {
     const commandName = command.name();
+    const helpText = afterHelpText(command);
     return {
         name: commandName,
         aliases: command.aliases(),
@@ -82,9 +99,45 @@ function convertCommand(command) {
         usage: command.usage(),
         arguments: command.registeredArguments.map(convertArgument),
         options: command.options.map((opt) => convertOption(opt, commandName)),
+        ...(helpText && { helpText }),
         subcommands: command.commands.map(convertCommand),
     };
 }
+/**
+ * An argument as written in usage: `<name>`, `[name]`, `<name...>`.
+ *
+ * @param argument - Commander argument instance
+ * @returns Usage term
+ */
+function argumentTerm(argument) {
+    const name = `${argument.name()}${argument.variadic ? '...' : ''}`;
+    return argument.required ? `<${name}>` : `[${name}]`;
+}
+/**
+ * Recursively converts a Commander Command to its compact summary: first
+ * description line, arguments, and visible options with their descriptions.
+ * Empty fields are left out.
+ *
+ * @param command - Commander command instance
+ * @returns Compact command summary
+ */
+function convertCompactCommand(command) {
+    const aliases = command.aliases();
+    const args = command.registeredArguments.map(argumentTerm).join(' ');
+    const options = command.options.filter((option) => !option.hidden);
+    return {
+        name: command.name(),
+        ...(aliases.length > 0 && { aliases }),
+        description: command.description().split('\n')[0] ?? '',
+        ...(args && { arguments: args }),
+        ...(options.length > 0 && {
+            options: Object.fromEntries(options.map((option) => [option.flags, option.description])),
+        }),
+        ...(command.commands.length > 0 && {
+            subcommands: command.commands.map(convertCompactCommand),
+        }),
+    };
+}
 /**
  * Generates runtime state information.
  *
@@ -97,7 +150,7 @@ function convertCommand(command) {
 function generateRuntimeState() {
     const sessionActive = readLiveDaemonPid() !== null;
     const availableCommands = sessionActive
-        ? ['peek', 'tail', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'sessions', 'stop']
+        ? ['peek', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'sessions', 'stop']
         : ['bdg <url>', 'sessions', 'cleanup', '--help', '--version'];
     return {
         sessionActive,
@@ -150,10 +203,11 @@ function generateCapabilities() {
     };
 }
 /**
- * Generates machine-readable help from a Commander program.
+ * Generates the full machine-readable help from a Commander program
+ * (`bdg --help --json --full`).
  *
  * Includes comprehensive metadata for agent discovery:
- * - Command structure and options
+ * - Command structure and options with behaviors
  * - Exit codes with semantic meanings
  * - Task-to-command mappings with CDP alternatives
  * - Runtime state and command availability
@@ -162,15 +216,6 @@ function generateCapabilities() {
  *
  * @param program - Commander program instance
  * @returns Machine-readable help structure
- *
- * @example
- * ```typescript
- * import { program } from 'commander';
- * import { generateMachineReadableHelp } from './help/machineReadableHelp.js';
- *
- * const help = generateMachineReadableHelp(program);
- * console.log(JSON.stringify(help, null, 2));
- * ```
  */
 export function generateMachineReadableHelp(program) {
     return {
@@ -186,56 +231,82 @@ export function generateMachineReadableHelp(program) {
     };
 }
 /**
- * Finds a subcommand by traversing the command path.
+ * Generates the compact root help (`bdg --help --json`): the full help with
+ * the command tree reduced to names, one-line descriptions and flags.
+ *
+ * @param program - Commander program instance
+ * @returns Compact help structure
+ */
+export function generateCompactHelp(program) {
+    return {
+        ...generateMachineReadableHelp(program),
+        details: helpJsonDetailsNote(),
+        command: convertCompactCommand(program),
+    };
+}
+/**
+ * The command a command line addresses: follows the words that name
+ * subcommands and skips the others (option values, arguments), stopping at a
+ * command without subcommands.
  *
  * @param program - Root Commander program instance
- * @param commandPath - Array of command names to traverse (e.g., ['dom', 'query'])
- * @returns The target Command if found, null otherwise
+ * @param words - Command-line words, e.g. ['dom', 'query', '.item']
+ * @returns The addressed command (the program when no word names one)
+ *
+ * @example
+ * ```typescript
+ * resolveCommand(program, ['--session', 'a', 'dom', 'query', '.item']).name(); // 'query'
+ * ```
  */
-function findSubcommand(program, commandPath) {
+export function resolveCommand(program, words) {
     let current = program;
-    for (const name of commandPath) {
-        const found = current.commands.find((cmd) => cmd.name() === name || cmd.aliases().includes(name));
-        if (!found) {
-            return null;
-        }
-        current = found;
+    for (const word of words) {
+        if (current.commands.length === 0)
+            break;
+        const found = current.commands.find((cmd) => cmd.name() === word || cmd.aliases().includes(word));
+        if (found)
+            current = found;
     }
     return current;
 }
 /**
- * Generates machine-readable help for a specific subcommand.
+ * Full command path, e.g. "bdg dom query".
  *
- * Returns the same structure as generateMachineReadableHelp but with
- * the command field focused on the requested subcommand. If the subcommand
- * is not found, falls back to full root help.
+ * @param command - Commander command instance
+ * @returns Names from the program down to the command
+ */
+export function commandPath(command) {
+    const names = [];
+    for (let level = command; level; level = level.parent)
+        names.unshift(level.name());
+    return names.join(' ');
+}
+/**
+ * Generates machine-readable help for one command: its full metadata,
+ * compact subcommands (a group lists them like the root help does) and the
+ * exit codes.
  *
  * @param program - Root Commander program instance
- * @param commandPath - Array of command names (e.g., ['dom', 'query'])
- * @returns Machine-readable help structure for the subcommand
+ * @param command - The command (from {@link resolveCommand})
+ * @returns Help for the command
  *
  * @example
  * ```typescript
- * // Get help for 'bdg dom query'
- * const help = generateSubcommandHelp(program, ['dom', 'query']);
- * console.log(help.command.name); // 'query'
+ * const help = generateCommandHelp(program, resolveCommand(program, ['dom', 'query']));
+ * console.log(help.path); // 'bdg dom query'
  * ```
  */
-export function generateSubcommandHelp(program, commandPath) {
-    const targetCommand = findSubcommand(program, commandPath);
-    if (!targetCommand) {
-        return generateMachineReadableHelp(program);
-    }
+export function generateCommandHelp(program, command) {
     return {
         name: program.name(),
         version: program.version() ?? 'unknown',
         description: program.description(),
-        command: convertCommand(targetCommand),
+        path: commandPath(command),
+        command: {
+            ...convertCommand(command),
+            subcommands: command.commands.map(convertCompactCommand),
+        },
         exitCodes: [...EXIT_CODE_DOCS],
-        taskMappings: getAllTaskMappings(),
-        runtimeState: generateRuntimeState(),
-        decisionTrees: getAllDecisionTrees(),
-        capabilities: generateCapabilities(),
     };
 }
 //# sourceMappingURL=helpJson.js.map

package/dist/commands/helpTopic.d.ts

@@ -1,7 +1,7 @@
 /**
  * `bdg help <command...>` topics and Commander usage-error hints.
  */
-import type { Command } from 'commander';
+import type { Command, CommanderError } from 'commander';
 /**
  * The command path of `bdg help <path...>`: the words before the first option.
  *
@@ -29,4 +29,19 @@ export declare function splitCommanderHint(text: string): {
     message: string;
     suggestion?: string;
 };
+/**
+ * Message and suggestion for a Commander usage error: a did-you-mean for an
+ * unknown option or command, otherwise a pointer to the command's `--help`.
+ * A word typed after a single dash (`-josn`) is matched against the long
+ * options.
+ *
+ * @param error - Commander error (not a help or version display)
+ * @param command - Command the error came from (see resolveCommand)
+ * @param argv - Process arguments (to name an option as typed)
+ * @returns Message and suggestion
+ */
+export declare function usageErrorDetails(error: CommanderError, command: Command, argv?: string[]): {
+    message: string;
+    suggestion: string;
+};
 //# sourceMappingURL=helpTopic.d.ts.map

package/dist/commands/helpTopic.js

@@ -1,8 +1,9 @@
 /**
  * `bdg help <command...>` topics and Commander usage-error hints.
  */
+import { commandPath } from './helpJson.js';
 import { CommandError } from '../errors/index.js';
-import { unknownHelpTopicError } from '../errors/messages.js';
+import { missingSubcommandMessage, unknownHelpTopicError, usageHelpSuggestion, } from '../errors/messages.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { findSimilar } from '../utils/suggestions.js';
 /** Commander's typo hint on its own line, e.g. "(Did you mean query?)" */
@@ -55,4 +56,61 @@ export function splitCommanderHint(text) {
         return { message };
     return { message: message.slice(0, hint.index).trim(), suggestion: `Did you mean: ${hint[1]}?` };
 }
+/** The option named in Commander's "unknown option '--x'" message, without an `=value` */
+const UNKNOWN_OPTION = /unknown option '([^'=]+)/;
+/**
+ * The long option of a command closest to a mistyped one, hidden global
+ * options (`--session`, `--quiet`) included. Up to one edit per three letters
+ * of the name counts as a typo, so `--frob` does not suggest `--json`.
+ *
+ * @param flag - Option as typed, e.g. "--sesion"
+ * @param command - Command it was given to
+ * @returns Closest long option, if any is similar
+ */
+function closestOption(flag, command) {
+    const longs = command.options.flatMap((option) => (option.long ? [option.long] : []));
+    const maxDistance = Math.ceil(flag.replace(/^-+/, '').length / 3);
+    return findSimilar(flag, longs, { maxDistance })[0];
+}
+/**
+ * The option as typed, for one Commander split: it reads `-josn` as `-j`
+ * (`--json`) followed by `-osn`, and reports `-osn` as unknown.
+ *
+ * @param flag - Option Commander reported, e.g. "-osn"
+ * @param argv - Process arguments
+ * @returns The argument it came from, e.g. "-josn", else the option itself
+ */
+function typedOption(flag, argv) {
+    if (flag.startsWith('--'))
+        return flag;
+    const rest = flag.slice(1);
+    return (argv.find((arg) => /^-[^-]/.test(arg) && arg.length > flag.length && arg.endsWith(rest)) ?? flag);
+}
+/**
+ * Message and suggestion for a Commander usage error: a did-you-mean for an
+ * unknown option or command, otherwise a pointer to the command's `--help`.
+ * A word typed after a single dash (`-josn`) is matched against the long
+ * options.
+ *
+ * @param error - Commander error (not a help or version display)
+ * @param command - Command the error came from (see resolveCommand)
+ * @param argv - Process arguments (to name an option as typed)
+ * @returns Message and suggestion
+ */
+export function usageErrorDetails(error, command, argv = process.argv) {
+    const help = usageHelpSuggestion(commandPath(command));
+    if (error.code === 'commander.help') {
+        return { message: missingSubcommandMessage(), suggestion: help };
+    }
+    const { message, suggestion } = splitCommanderHint(error.message);
+    const flag = error.code === 'commander.unknownOption' && UNKNOWN_OPTION.exec(message)?.[1];
+    if (!flag)
+        return { message, suggestion: suggestion ?? help };
+    const typed = typedOption(flag, argv);
+    const closest = closestOption(/^-[^-]../.test(typed) ? `-${typed}` : typed, command);
+    return {
+        message: message.replace(`'${flag}'`, `'${typed}'`),
+        suggestion: closest ? `Did you mean: ${closest}?` : help,
+    };
+}
 //# sourceMappingURL=helpTopic.js.map

package/dist/commands/installSkill.d.ts

@@ -1,16 +1,26 @@
 import type { Command } from 'commander';
+import { CommandError } from '../errors/index.js';
 import type { InstalledSkill, SkillTarget } from '../types.js';
+/** What installing the skill did, and why it failed for a target, if it did */
+export interface SkillInstallResult {
+    /** Targets the skill was installed for (or left unchanged) */
+    skills: InstalledSkill[];
+    /** Error (82) for the targets that could not be written */
+    failure?: CommandError;
+}
 /**
- * Copy the bdg skill into each target's skill directory, overwriting an
- * older copy.
+ * Copy the bdg skill into each target's skill directory. A copy that differs
+ * (an older version, or one the user edited) is kept as `SKILL.md.bak`
+ * before it is overwritten. A target that cannot be written does not stop
+ * the others.
  *
  * @param targets - Agents to install for
  * @param home - Home directory the skill roots are relative to
  * @param source - SKILL.md to copy
- * @returns One entry per target, in the given order
- * @throws CommandError when the source is missing (83) or a write fails (82)
+ * @returns The targets written, in the given order, and the failure if any
+ * @throws CommandError when the source is missing (83)
  */
-export declare function installSkill(targets: SkillTarget[], home?: string, source?: string): InstalledSkill[];
+export declare function installSkill(targets: SkillTarget[], home?: string, source?: string): SkillInstallResult;
 /**
  * Register the install-skill command.
  *