terminal-pilot 0.0.48 → 0.0.49

package/dist/testing/cli-repl.js

@@ -1643,26 +1643,68 @@ function splitWords(value) {
   }
   return words;
 }
-function wrapWords(value, width) {
-  const words = splitWords(value);
+function leadingWhitespaceWidth(value) {
+  let index = 0;
+  while (index < value.length && isWhitespace(value[index])) {
+    index += 1;
+  }
+  return { prefix: value.slice(0, index), rest: value.slice(index) };
+}
+function takeVisiblePrefix(value, width) {
+  let visible = 0;
+  let index = 0;
+  while (index < value.length) {
+    const controlEnd = readControlSequence(value, index);
+    if (controlEnd !== void 0) {
+      index = controlEnd;
+      continue;
+    }
+    const segment = graphemeSegmenter.segment(value.slice(index))[Symbol.iterator]().next().value;
+    const cluster = segment?.segment ?? value[index] ?? "";
+    const nextWidth = clusterWidth(cluster);
+    if (visible > 0 && visible + nextWidth > width) {
+      break;
+    }
+    visible += nextWidth;
+    index += cluster.length || 1;
+  }
+  return { prefix: value.slice(0, index), rest: value.slice(index) };
+}
+function wrapWords(value, width, continuationWidth = width) {
+  const { prefix, rest } = leadingWhitespaceWidth(value);
+  const prefixWidth = visibleWidth(prefix);
+  const firstContentWidth = Math.max(1, width - prefixWidth);
+  const words = splitWords(rest);
   if (words.length === 0) {
-    return [""];
+    return [prefix];
   }
   const lines = [];
   let line = "";
+  let isFirstLine = true;
   for (const word of words) {
-    if (!line) {
-      line = word;
-      continue;
-    }
-    if (visibleWidth(line) + 1 + visibleWidth(word) <= width) {
+    const limit = isFirstLine ? firstContentWidth : continuationWidth;
+    if (line && visibleWidth(line) + 1 + visibleWidth(word) <= limit) {
       line += ` ${word}`;
       continue;
     }
-    lines.push(line);
-    line = word;
+    if (line) {
+      lines.push(isFirstLine ? `${prefix}${line}` : line);
+      isFirstLine = false;
+      line = "";
+    }
+    let remaining = word;
+    while (visibleWidth(remaining) > (isFirstLine ? firstContentWidth : continuationWidth)) {
+      const chunk = takeVisiblePrefix(
+        remaining,
+        isFirstLine ? firstContentWidth : continuationWidth
+      );
+      lines.push(isFirstLine ? `${prefix}${chunk.prefix}` : chunk.prefix);
+      isFirstLine = false;
+      remaining = chunk.rest;
+    }
+    line = remaining;
   }
-  lines.push(line);
+  lines.push(isFirstLine ? `${prefix}${line}` : line);
   return lines;
 }
 function validateLayoutValue(value, name) {
@@ -1690,37 +1732,90 @@ function formatColumns(opts) {
   validateLayoutValue(indent, "indent");
   const maxLeftContentWidth = Math.max(...rows.map((row) => visibleWidth(row.left)));
   const leftWidth = clamp(maxLeftContentWidth + gap, minLeftWidth, maxLeftWidth);
-  const rightWidth = Math.max(20, totalWidth - leftWidth - indent);
+  const rightWidth = Math.max(1, totalWidth - leftWidth - indent);
+  const leftWrapWidth = Math.max(1, totalWidth - indent);
   const firstIndent = " ".repeat(indent);
   const continuationIndent = " ".repeat(indent + leftWidth);
   return rows.flatMap((row) => {
+    const leftLeading = leadingWhitespaceWidth(row.left).prefix;
+    const leftHangIndent = " ".repeat(indent + visibleWidth(leftLeading) + 2);
+    const leftLines = wrapWords(
+      row.left,
+      leftWrapWidth,
+      Math.max(1, totalWidth - visibleWidth(leftHangIndent))
+    );
     if (row.right.length === 0) {
-      return [`${firstIndent}${row.left}`];
+      return leftLines.map(
+        (line, index) => index === 0 ? `${firstIndent}${line}` : `${leftHangIndent}${line}`
+      );
     }
     const rightLines = wrapWords(row.right, rightWidth);
-    if (visibleWidth(row.left) >= leftWidth) {
-      return [
-        `${firstIndent}${row.left}`,
-        ...rightLines.map((line) => `${continuationIndent}${line}`)
-      ];
-    }
-    const firstLine = `${firstIndent}${padEndVisible(row.left, leftWidth)}${rightLines[0]}`;
-    const continuationLines = rightLines.slice(1).map((line) => `${continuationIndent}${line}`);
-    return [firstLine, ...continuationLines];
+    const leftFitsInColumn = visibleWidth(row.left) < leftWidth;
+    if (leftFitsInColumn && leftLines.length === 1) {
+      const firstLine = `${firstIndent}${padEndVisible(leftLines[0] ?? "", leftWidth)}${rightLines[0]}`;
+      const continuationLines = rightLines.slice(1).map((line) => `${continuationIndent}${line}`);
+      return [firstLine, ...continuationLines];
+    }
+    const renderedLeft = leftLines.map(
+      (line, index) => index === 0 ? `${firstIndent}${line}` : `${leftHangIndent}${line}`
+    );
+    const renderedRight = rightLines.map((line) => `${continuationIndent}${line}`);
+    return [...renderedLeft, ...renderedRight];
   }).join("\n");
 }
+function styleHelpToken(token) {
+  switch (token.role) {
+    case "command":
+      return text.command(token.text);
+    case "argument":
+      return styleArgumentToken(token.text);
+    case "option":
+      return text.option(token.text);
+    case "dim":
+      return styleDim(token.text);
+    case "literal":
+      return token.text;
+  }
+}
+function styleArgumentToken(content) {
+  const format = resolveOutputFormat();
+  if (format === "markdown" && content.startsWith("<") && content.endsWith(">")) {
+    return text.argument(content.slice(1, -1));
+  }
+  if (format === "json") {
+    return content;
+  }
+  return text.argument(content);
+}
+function styleDim(content) {
+  const format = resolveOutputFormat();
+  if (format === "json" || format === "markdown") {
+    return content;
+  }
+  return typography.dim(content);
+}
+function joinHelpTokens(tokens) {
+  return tokens.map((token) => token.text).join("");
+}
+function renderHelpTokens(tokens) {
+  return tokens.map((token) => styleHelpToken(token)).join("");
+}
 function formatCommandList(commands) {
   return formatColumns({
-    rows: commands.map((cmd) => ({
-      left: `${" ".repeat((cmd.depth ?? 0) * 2)}${text.command(cmd.name)}`,
-      right: cmd.description
-    }))
+    rows: commands.map((cmd) => {
+      const depthPrefix = " ".repeat((cmd.depth ?? 0) * 2);
+      const styledName = cmd.nameTokens !== void 0 && cmd.nameTokens.length > 0 ? renderHelpTokens(cmd.nameTokens) : text.command(cmd.name);
+      return {
+        left: `${depthPrefix}${styledName}`,
+        right: cmd.description
+      };
+    })
   });
 }
 function formatOptionList(options) {
   return formatColumns({
     rows: options.map((opt) => ({
-      left: text.option(opt.flags),
+      left: opt.flagTokens !== void 0 && opt.flagTokens.length > 0 ? renderHelpTokens(opt.flagTokens) : text.option(opt.flags),
       right: opt.description
     }))
   });
@@ -1790,26 +1885,47 @@ function splitWords2(value) {
   }
   return words;
 }
-function wrapWords2(value, width) {
-  const words = splitWords2(value);
+function leadingWhitespace(value) {
+  let index = 0;
+  while (index < value.length && isWhitespace2(value[index])) {
+    index += 1;
+  }
+  return { prefix: value.slice(0, index), rest: value.slice(index) };
+}
+function takePrefix(value, width) {
+  return { prefix: value.slice(0, width), rest: value.slice(width) };
+}
+function wrapWords2(value, width, continuationWidth = width) {
+  const { prefix, rest } = leadingWhitespace(value);
+  const firstContentWidth = Math.max(1, width - prefix.length);
+  const words = splitWords2(rest);
   if (words.length === 0) {
-    return [""];
+    return [prefix];
   }
   const lines = [];
   let line = "";
+  let isFirstLine = true;
   for (const word of words) {
-    if (!line) {
-      line = word;
-      continue;
-    }
-    if (line.length + 1 + word.length <= width) {
+    const limit = isFirstLine ? firstContentWidth : continuationWidth;
+    if (line && line.length + 1 + word.length <= limit) {
       line += ` ${word}`;
       continue;
     }
-    lines.push(line);
-    line = word;
+    if (line) {
+      lines.push(isFirstLine ? `${prefix}${line}` : line);
+      isFirstLine = false;
+      line = "";
+    }
+    let remaining = word;
+    while (remaining.length > (isFirstLine ? firstContentWidth : continuationWidth)) {
+      const chunk = takePrefix(remaining, isFirstLine ? firstContentWidth : continuationWidth);
+      lines.push(isFirstLine ? `${prefix}${chunk.prefix}` : chunk.prefix);
+      isFirstLine = false;
+      remaining = chunk.rest;
+    }
+    line = remaining;
   }
-  lines.push(line);
+  lines.push(isFirstLine ? `${prefix}${line}` : line);
   return lines;
 }
 function formatColumns2(opts) {
@@ -1827,29 +1943,44 @@ function formatColumns2(opts) {
   const indent = opts.indent ?? 2;
   const maxLeftContentWidth = Math.max(...rows.map((row) => row.left.length));
   const leftWidth = clamp2(maxLeftContentWidth + gap, minLeftWidth, maxLeftWidth);
-  const rightWidth = Math.max(20, totalWidth - leftWidth - indent);
+  const rightWidth = Math.max(1, totalWidth - leftWidth - indent);
+  const leftWrapWidth = Math.max(1, totalWidth - indent);
   const firstIndent = " ".repeat(indent);
   const continuationIndent = " ".repeat(indent + leftWidth);
   return rows.flatMap((row) => {
+    let leftLeadingWidth = 0;
+    while (leftLeadingWidth < row.left.length && isWhitespace2(row.left[leftLeadingWidth])) {
+      leftLeadingWidth += 1;
+    }
+    const leftHangIndent = " ".repeat(indent + leftLeadingWidth + 2);
+    const leftLines = wrapWords2(
+      row.left,
+      leftWrapWidth,
+      Math.max(1, totalWidth - leftHangIndent.length)
+    );
     if (row.right.length === 0) {
-      return [`${firstIndent}${row.left}`];
+      return leftLines.map(
+        (line, index) => index === 0 ? `${firstIndent}${line}` : `${leftHangIndent}${line}`
+      );
     }
     const rightLines = wrapWords2(row.right, rightWidth);
-    if (row.left.length >= leftWidth) {
-      return [
-        `${firstIndent}${row.left}`,
-        ...rightLines.map((line) => `${continuationIndent}${line}`)
-      ];
-    }
-    const firstLine = `${firstIndent}${padEndVisible2(row.left, leftWidth)}${rightLines[0]}`;
-    const continuationLines = rightLines.slice(1).map((line) => `${continuationIndent}${line}`);
-    return [firstLine, ...continuationLines];
+    const leftFitsInColumn = row.left.length < leftWidth;
+    if (leftFitsInColumn && leftLines.length === 1) {
+      const firstLine = `${firstIndent}${padEndVisible2(leftLines[0] ?? "", leftWidth)}${rightLines[0]}`;
+      const continuationLines = rightLines.slice(1).map((line) => `${continuationIndent}${line}`);
+      return [firstLine, ...continuationLines];
+    }
+    const renderedLeft = leftLines.map(
+      (line, index) => index === 0 ? `${firstIndent}${line}` : `${leftHangIndent}${line}`
+    );
+    const renderedRight = rightLines.map((line) => `${continuationIndent}${line}`);
+    return [...renderedLeft, ...renderedRight];
   }).join("\n");
 }
 function formatCommandList2(commands) {
   return formatColumns2({
     rows: commands.map((cmd) => ({
-      left: `${" ".repeat((cmd.depth ?? 0) * 2)}${cmd.name}`,
+      left: `${" ".repeat((cmd.depth ?? 0) * 2)}${cmd.nameTokens !== void 0 && cmd.nameTokens.length > 0 ? joinHelpTokens(cmd.nameTokens) : cmd.name}`,
       right: cmd.description
     }))
   });
@@ -1857,7 +1988,7 @@ function formatCommandList2(commands) {
 function formatOptionList2(options) {
   return formatColumns2({
     rows: options.map((opt) => ({
-      left: opt.flags,
+      left: opt.flagTokens !== void 0 && opt.flagTokens.length > 0 ? joinHelpTokens(opt.flagTokens) : opt.flags,
       right: opt.description
     }))
   });
@@ -1866,6 +1997,7 @@ function formatOptionList2(options) {
 // ../toolcraft-design/src/components/table.ts
 var reset2 = "\x1B[0m";
 var ellipsis = "\u2026";
+var minCellWidth = 4;
 var graphemeSegmenter2 = new Intl.Segmenter(void 0, { granularity: "grapheme" });
 function getCell(row, name) {
   return Object.prototype.hasOwnProperty.call(row, name) ? row[name] ?? "" : "";
@@ -1999,6 +2131,39 @@ function computeColumns(columns) {
     width: getColumnWidth(column)
   }));
 }
+function frameWidth(columnCount) {
+  return columnCount * 3 + 1;
+}
+function budgetColumns(columns, maxWidth) {
+  if (maxWidth === void 0) {
+    return columns;
+  }
+  const available = maxWidth - frameWidth(columns.length);
+  const contentWidth = (cap2) => columns.reduce((total, column) => total + Math.min(column.width, cap2), 0);
+  if (columns.reduce((total, column) => total + column.width, 0) <= available) {
+    return columns;
+  }
+  let cap = minCellWidth;
+  while (contentWidth(cap + 1) <= available) {
+    cap += 1;
+  }
+  const budgeted = columns.map((column) => ({ ...column, width: Math.min(column.width, cap) }));
+  let slack = available - contentWidth(cap);
+  while (slack > 0) {
+    const growable = budgeted.filter((column, index) => column.width < columns[index].width);
+    if (growable.length === 0) {
+      break;
+    }
+    for (const column of growable) {
+      if (slack === 0) {
+        break;
+      }
+      column.width += 1;
+      slack -= 1;
+    }
+  }
+  return budgeted;
+}
 function renderBorder(columns, theme, parts) {
   const horizontal = theme.muted("\u2500");
   const segments = columns.map((column) => horizontal.repeat(column.width + 2));
@@ -2083,14 +2248,15 @@ function renderTableTerminal(options) {
   }
   const separatorOptions = options;
   const includeRowSeparators = separatorOptions.rowSeparator === true || separatorOptions.rowSeparators === true;
-  const top = renderBorder(computedColumns, theme, { left: "\u250C", mid: "\u252C", right: "\u2510" });
+  const budgetedColumns = budgetColumns(computedColumns, options.maxWidth ?? process.stdout.columns);
+  const top = renderBorder(budgetedColumns, theme, { left: "\u250C", mid: "\u252C", right: "\u2510" });
   const header = renderTerminalRow(
-    computedColumns.map((column) => theme.header(column.title)),
-    computedColumns,
+    budgetedColumns.map((column) => theme.header(column.title)),
+    budgetedColumns,
     theme
   );
-  const headerBottom = renderBorder(computedColumns, theme, { left: "\u251C", mid: "\u253C", right: "\u2524" });
-  const bottom = renderBorder(computedColumns, theme, { left: "\u2514", mid: "\u2534", right: "\u2518" });
+  const headerBottom = renderBorder(budgetedColumns, theme, { left: "\u251C", mid: "\u253C", right: "\u2524" });
+  const bottom = renderBorder(budgetedColumns, theme, { left: "\u2514", mid: "\u2534", right: "\u2518" });
   const renderedRows = [];
   for (const [index, row] of rows.entries()) {
     if (includeRowSeparators && index > 0) {
@@ -2098,8 +2264,8 @@ function renderTableTerminal(options) {
     }
     renderedRows.push(
       renderTerminalRow(
-        computedColumns.map((column) => getCell(row, column.name)),
-        computedColumns,
+        budgetedColumns.map((column) => getCell(row, column.name)),
+        budgetedColumns,
         theme
       )
     );
@@ -2192,6 +2358,19 @@ ${options.theme.muted(options.badges.map((badge) => badge[0] + badge.slice(1).to
 
 // ../toolcraft-design/src/components/template.ts
 var MAX_PARTIAL_DEPTH = 100;
+var MAX_TAG_EXCERPT_LENGTH = 40;
+var TemplateParseError = class extends Error {
+  description;
+  line;
+  column;
+  constructor(description, position) {
+    super(`${description} at line ${position.line}, column ${position.column}`);
+    this.name = "TemplateParseError";
+    this.description = description;
+    this.line = position.line;
+    this.column = position.column;
+  }
+};
 var HTML_ESCAPE = {
   "&": "&amp;",
   "<": "&lt;",
@@ -2298,13 +2477,13 @@ function parseTag(template, open) {
   if (template.startsWith("{{{", open)) {
     const close2 = template.indexOf("}}}", open + 3);
     if (close2 === -1) {
-      throw new Error("Unclosed unescaped tag");
+      throw unclosedTagError(template, open, "}}}");
     }
     return { kind: "unescaped", name: template.slice(open + 3, close2).trim(), end: close2 + 3 };
   }
   const close = template.indexOf("}}", open + 2);
   if (close === -1) {
-    throw new Error("Unclosed tag");
+    throw unclosedTagError(template, open, "}}");
   }
   const raw = template.slice(open + 2, close).trim();
   const sigil = raw[0];
@@ -2319,6 +2498,16 @@ function parseTag(template, open) {
   if (sigil === "=" && raw.endsWith("=")) return { kind: "delimiter", name, end };
   return { kind: "name", name: raw, end };
 }
+function unclosedTagError(template, open, expected) {
+  const before = template.slice(0, open);
+  const lineEnd = template.indexOf("\n", open);
+  const opened = template.slice(open, lineEnd === -1 ? template.length : lineEnd).trimEnd();
+  const tag = opened.length > MAX_TAG_EXCERPT_LENGTH ? `${opened.slice(0, MAX_TAG_EXCERPT_LENGTH)}...` : opened;
+  return new TemplateParseError(`Unclosed tag "${tag}": expected "${expected}"`, {
+    line: before.split("\n").length,
+    column: open - (before.lastIndexOf("\n") + 1) + 1
+  });
+}
 function getStandalone(template, tagStart, tagEnd, kind) {
   if (!["section", "inverted", "close", "comment", "partial", "delimiter"].includes(kind)) {
     return void 0;
@@ -2890,6 +3079,15 @@ var cursor = {
 var erase = {
   down: "\x1B[J"
 };
+function nonTtyPromptMessage(argv = process.argv) {
+  const tokens = [];
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith("-")) break;
+    tokens.push(arg);
+  }
+  const retry = [...tokens, "--yes"].join(" ");
+  return `Interactive prompt requires a TTY. Re-run with \`${retry}\` to accept defaults non-interactively, or set POE_NO_PROMPT=1 in CI.`;
+}
 var Prompt = class extends EventEmitter {
   state = "initial";
   value;
@@ -2960,7 +3158,7 @@ var Prompt = class extends EventEmitter {
     });
   }
   promptNonTty() {
-    return Promise.reject(new Error("Interactive prompt requires a TTY. Set POE_NO_PROMPT=1 to accept defaults non-interactively."));
+    return Promise.reject(new Error(nonTtyPromptMessage()));
   }
   readNonTtyLine() {
     return new Promise((resolve) => {
@@ -3484,6 +3682,9 @@ var UserError = class extends Error {
     this.name = "UserError";
   }
 };
+function isUserError(error3) {
+  return error3 instanceof UserError || error3 instanceof Error && error3.name === "UserError";
+}
 var ToolcraftBugError = class extends Error {
   constructor(message2) {
     super(message2);
@@ -5125,6 +5326,9 @@ function compactUrl(value) {
     return value;
   }
 }
+function stackedList(value) {
+  return value.map((entry) => displayScalar(entry)).join("\n") || "\u2014";
+}
 function displayRowValue(value) {
   return isUrl(value) ? compactUrl(value) : displayScalar(value);
 }
@@ -5150,7 +5354,7 @@ function renderObjectCard(result, primitives, title) {
   const scalarRows = directScalarRows(result);
   const nestedSections = directObjectSections(result);
   const arrayObjectSections = directArrayObjectSections(result);
-  const listRows = Object.entries(result).filter(([, value]) => Array.isArray(value) && !isNonEmptyArrayOfObjects(value)).map(([key, value]) => ({ label: humanizeKey(key), value: displayScalar(value) }));
+  const listRows = Object.entries(result).filter(([, value]) => Array.isArray(value) && !isNonEmptyArrayOfObjects(value)).map(([key, value]) => ({ label: humanizeKey(key), value: stackedList(value) }));
   return renderDetailCard({
     theme: primitives.getTheme(),
     title,
@@ -5852,6 +6056,13 @@ function formatOptionFlags(field, globalLongOptionFlags) {
   }
   return [`-${field.shortFlag}`, field.optionFlag, ...field.longAliases].join(", ");
 }
+function formatMissingParameterMessage(field) {
+  const message2 = `Missing required parameter "${field.displayPath}".`;
+  if (field.schema.kind !== "enum") {
+    return message2;
+  }
+  return `${message2} Expected one of: ${field.schema.values.map((value) => String(value)).join(", ")}.`;
+}
 function formatPositionalToken(field) {
   const optionalPositional = field.optional || field.hasDefault;
   if (field.variadicPosition === true) {
@@ -6333,12 +6544,31 @@ function appendHelpMetadata(description, metadata) {
     return description;
   }
   if (description.length === 0) {
-    return `(${metadata.join(", ")})`;
+    return metadata.map((entry) => `(${entry})`).join(" ");
+  }
+  return `${description} ${metadata.map((entry) => `(${entry})`).join(" ")}`;
+}
+function normalizeHelpEchoKey(value) {
+  let normalized = "";
+  for (const character of value.trim().toLowerCase()) {
+    if (character !== " " && character !== "	" && character !== "\n" && character !== "\r" && character !== "_" && character !== "." && character !== "-") {
+      normalized += character;
+    }
   }
-  return `${description} (${metadata.join(", ")})`;
+  return normalized;
+}
+function isEchoHelpDescription(description, name) {
+  if (description.length === 0) {
+    return false;
+  }
+  return normalizeHelpEchoKey(description) === normalizeHelpEchoKey(name);
+}
+function suppressEchoHelpDescription(description, name) {
+  return isEchoHelpDescription(description, name) ? "" : description;
 }
 function formatHelpFieldDescription(field) {
-  const description = field.description ?? field.displayPath;
+  const rawDescription = field.description ?? field.displayPath;
+  const description = suppressEchoHelpDescription(rawDescription, field.displayPath);
   const metadata = [];
   if (field.schema.kind === "enum" && field.schema.values.length <= 8) {
     const values = field.schema.values.map((value) => String(value)).join(", ");
@@ -6487,13 +6717,21 @@ function formatDynamicHelpMetadata(field) {
   }
   return metadata;
 }
+function createHelpOptionRow(flags, description) {
+  return {
+    flags,
+    flagTokens: tokenizeHelpFlags(flags),
+    description
+  };
+}
 function collectDynamicObjectHelpRows(schema, casing, optionPrefix, displayPrefix, metadata) {
   const rows = [];
   for (const [key, rawChildSchema] of Object.entries(schema.shape)) {
     const childSchema = unwrapOptional2(rawChildSchema);
     const optionFlag = `${optionPrefix}.${formatSegment(key, casing)}`;
     const displayPath = `${displayPrefix}.${key}`;
-    const description = childSchema.description ?? displayPath;
+    const rawDescription = childSchema.description ?? displayPath;
+    const description = suppressEchoHelpDescription(rawDescription, displayPath);
     if (childSchema.kind === "object") {
       rows.push(
         ...collectDynamicObjectHelpRows(childSchema, casing, optionFlag, displayPath, metadata)
@@ -6501,24 +6739,26 @@ function collectDynamicObjectHelpRows(schema, casing, optionPrefix, displayPrefi
       continue;
     }
     if (childSchema.kind === "record") {
-      rows.push({
-        flags: `${optionFlag}.<key> <${describeDynamicFieldType({
-          ...{
-            id: displayPath,
-            path: [],
-            displayPath,
-            optionPath: [],
-            optionPathDisplay: `${displayPath}.<key>`,
-            optionFlag: `${optionFlag}.<key>`,
-            optional: false,
-            hasDefault: false,
-            defaultValue: void 0,
-            requiredWhenActive: false,
-            schema: childSchema
-          }
-        })}>`,
-        description: appendHelpMetadata(description, metadata)
-      });
+      rows.push(
+        createHelpOptionRow(
+          `${optionFlag}.<key> <${describeDynamicFieldType({
+            ...{
+              id: displayPath,
+              path: [],
+              displayPath,
+              optionPath: [],
+              optionPathDisplay: `${displayPath}.<key>`,
+              optionFlag: `${optionFlag}.<key>`,
+              optional: false,
+              hasDefault: false,
+              defaultValue: void 0,
+              requiredWhenActive: false,
+              schema: childSchema
+            }
+          })}>`,
+          appendHelpMetadata(description, metadata)
+        )
+      );
       continue;
     }
     if (childSchema.kind === "array" && unwrapOptional2(childSchema.item).kind === "object") {
@@ -6533,13 +6773,15 @@ function collectDynamicObjectHelpRows(schema, casing, optionPrefix, displayPrefi
       );
       continue;
     }
-    rows.push({
-      flags: childSchema.kind === "boolean" ? childSchema.default === true ? `--no-${optionFlag.slice(2)}` : optionFlag : `${optionFlag} <${describeHelpValueToken(childSchema, {
-        displayPath,
-        optionFlag
-      })}>`,
-      description: appendHelpMetadata(description, metadata)
-    });
+    rows.push(
+      createHelpOptionRow(
+        childSchema.kind === "boolean" ? childSchema.default === true ? `--no-${optionFlag.slice(2)}` : optionFlag : `${optionFlag} <${describeHelpValueToken(childSchema, {
+          displayPath,
+          optionFlag
+        })}>`,
+        appendHelpMetadata(description, metadata)
+      )
+    );
   }
   return rows;
 }
@@ -6570,17 +6812,22 @@ function formatDynamicHelpFields(field, casing) {
     }
   }
   return [
-    {
-      flags: `${field.optionFlag} <${describeDynamicFieldType(field)}>`,
-      description: appendHelpMetadata(field.description ?? field.optionPathDisplay, metadata)
-    }
+    createHelpOptionRow(
+      `${field.optionFlag} <${describeDynamicFieldType(field)}>`,
+      appendHelpMetadata(
+        suppressEchoHelpDescription(
+          field.description ?? field.optionPathDisplay,
+          field.optionPathDisplay
+        ),
+        metadata
+      )
+    )
   ];
 }
 function formatSecretRows(secrets) {
-  return Object.values(secrets).map((secret) => ({
-    flags: secret.env,
-    description: formatSecretDescription(secret)
-  }));
+  return Object.values(secrets).map(
+    (secret) => createHelpOptionRow(secret.env, formatSecretDescription(secret))
+  );
 }
 function formatSecretDescription(secret) {
   if (secret.description !== void 0 && secret.description.length > 0) {
@@ -6608,20 +6855,82 @@ function formatExampleRows(examples, breadcrumb, rootUsageName) {
   ${formatExampleCommand(breadcrumb, rootUsageName, example.params)}`
   );
 }
-function wrapOptionalCommandParameterToken(token, optional) {
-  return optional ? `[${token}]` : token;
+var MAX_INLINE_OPTIONAL_PARAMETER_TOKENS = 8;
+var DEFAULT_HELP_TOTAL_WIDTH = 100;
+function tokenizeHelpFlags(flags) {
+  const tokens = [];
+  let index = 0;
+  while (index < flags.length) {
+    if (flags[index] === " ") {
+      let end2 = index + 1;
+      while (end2 < flags.length && flags[end2] === " ") {
+        end2 += 1;
+      }
+      tokens.push({ text: flags.slice(index, end2), role: "literal" });
+      index = end2;
+      continue;
+    }
+    if (flags[index] === "[" || flags[index] === "]") {
+      tokens.push({ text: flags[index], role: "dim" });
+      index += 1;
+      continue;
+    }
+    if (flags[index] === "<") {
+      const close = flags.indexOf(">", index);
+      if (close === -1) {
+        tokens.push({ text: flags.slice(index), role: "literal" });
+        break;
+      }
+      tokens.push({ text: flags.slice(index, close + 1), role: "argument" });
+      index = close + 1;
+      continue;
+    }
+    if (flags.startsWith("--", index) || flags[index] === "-" && flags[index + 1] !== void 0 && flags[index + 1] !== "-") {
+      let end2 = index + 1;
+      while (end2 < flags.length && flags[end2] !== " " && flags[end2] !== "[" && flags[end2] !== "]" && flags[end2] !== "<") {
+        end2 += 1;
+      }
+      tokens.push({ text: flags.slice(index, end2), role: "option" });
+      index = end2;
+      continue;
+    }
+    let end = index + 1;
+    while (end < flags.length && flags[end] !== " " && flags[end] !== "[" && flags[end] !== "]" && flags[end] !== "<") {
+      end += 1;
+    }
+    const piece = flags.slice(index, end);
+    tokens.push({
+      text: piece,
+      role: piece.includes("|") ? "literal" : piece.startsWith("+") ? "dim" : "literal"
+    });
+    index = end;
+  }
+  return tokens;
+}
+function wrapOptionalParameterTokens(tokens, optional) {
+  if (!optional) {
+    return tokens;
+  }
+  return [{ text: "[", role: "dim" }, ...tokens, { text: "]", role: "dim" }];
+}
+function createCommandParameterToken(text3, optional) {
+  return {
+    text: optional ? `[${text3}]` : text3,
+    optional,
+    tokens: wrapOptionalParameterTokens(tokenizeHelpFlags(text3), optional)
+  };
 }
 function formatCommandDynamicParameterTokens(field, casing) {
   const optional = field.optional || field.hasDefault;
   return formatDynamicHelpFields(field, casing).map(
-    (row) => wrapOptionalCommandParameterToken(row.flags, optional)
+    (row) => createCommandParameterToken(row.flags, optional)
   );
 }
 function formatCommandParameterTokens(command, casing, globalLongOptionFlags) {
   const collected = collectFields(command.params, casing, globalLongOptionFlags);
   const fields = assignPositionals(collected.fields, command.positional);
   return fields.filter((field) => field.global !== true).map(
-    (field) => wrapOptionalCommandParameterToken(
+    (field) => createCommandParameterToken(
       formatCommandParameterFieldFlags(field, globalLongOptionFlags),
       field.positionalIndex === void 0 && (field.optional || field.hasDefault)
     )
@@ -6629,30 +6938,65 @@ function formatCommandParameterTokens(command, casing, globalLongOptionFlags) {
     collected.dynamicFields.flatMap((field) => formatCommandDynamicParameterTokens(field, casing))
   );
 }
-function formatCommandRowName(node, casing, globalLongOptionFlags) {
+function collapseOptionalParameterTokens(parameterTokens, inlineWidthBudget = Number.POSITIVE_INFINITY) {
+  const optionalCount = parameterTokens.filter((token) => token.optional).length;
+  if (optionalCount === 0) {
+    return parameterTokens;
+  }
+  const inlineWidth = parameterTokens.reduce((total, token) => total + token.text.length + 1, 0);
+  if (optionalCount <= MAX_INLINE_OPTIONAL_PARAMETER_TOKENS && inlineWidth <= inlineWidthBudget) {
+    return parameterTokens;
+  }
+  const required = parameterTokens.filter((token) => !token.optional);
+  const collapsedText = `+${optionalCount} options`;
+  return [
+    ...required,
+    {
+      text: `[${collapsedText}]`,
+      optional: true,
+      tokens: [
+        { text: "[", role: "dim" },
+        { text: collapsedText, role: "dim" },
+        { text: "]", role: "dim" }
+      ]
+    }
+  ];
+}
+function formatCommandRowNameTokens(node, casing, globalLongOptionFlags) {
   const baseName = node.aliases.length === 0 ? node.name : `${node.name} (${node.aliases.join(", ")})`;
-  const parameterTokens = node.kind === "command" ? formatCommandParameterTokens(node, casing, globalLongOptionFlags) : [];
-  const name = parameterTokens.length === 0 ? baseName : `${baseName} ${parameterTokens.join(" ")}`;
-  return name;
+  const nameTokens = [{ text: baseName, role: "command" }];
+  const inlineWidthBudget = Math.max(
+    0,
+    (process.stdout.columns ?? DEFAULT_HELP_TOTAL_WIDTH) - 2 - baseName.length
+  );
+  const parameterTokens = node.kind === "command" ? collapseOptionalParameterTokens(
+    formatCommandParameterTokens(node, casing, globalLongOptionFlags),
+    inlineWidthBudget
+  ) : [];
+  for (const token of parameterTokens) {
+    nameTokens.push({ text: " ", role: "literal" }, ...token.tokens);
+  }
+  const name = parameterTokens.length === 0 ? baseName : `${baseName} ${parameterTokens.map((token) => token.text).join(" ")}`;
+  return { name, nameTokens };
 }
 function formatCommandRows(group, scope, casing, globalLongOptionFlags, help) {
-  if (help === "concise") {
-    return getHelpChildren(group, scope).map((child) => ({
-      name: formatCommandRowName(child, casing, globalLongOptionFlags),
-      description: child.description ?? "",
+  const toRow = (child, depth) => {
+    const { name, nameTokens } = formatCommandRowNameTokens(child, casing, globalLongOptionFlags);
+    return {
+      name,
+      nameTokens,
+      description: suppressEchoHelpDescription(child.description ?? "", child.name),
       kind: child.kind,
-      depth: 0
-    }));
+      depth
+    };
+  };
+  if (help === "concise") {
+    return getHelpChildren(group, scope).map((child) => toRow(child, 0));
   }
   const rows = [];
   const visit = (node, depth) => {
     for (const child of getHelpChildren(node, scope)) {
-      rows.push({
-        name: formatCommandRowName(child, casing, globalLongOptionFlags),
-        description: child.description ?? "",
-        kind: child.kind,
-        depth
-      });
+      rows.push(toRow(child, depth));
       if (child.kind === "group") {
         visit(child, depth + 1);
       }
@@ -6678,10 +7022,10 @@ function formatGlobalOptionsLine(ctx) {
   if (ctx.showVersion) {
     flags.push("--version");
   }
-  return flags.length > 0 ? `${text.section("Options:")} ${flags.join("  ")}` : "";
+  return flags.length > 0 ? `${text.section("Global Options:")} ${flags.join("  ")}` : "";
 }
 function formatLeafGlobalOptionsLine(ctx) {
-  return ctx.controls.verbose ? `${text.section("Options:")} -v, --verbose` : "";
+  return ctx.controls.verbose ? `${text.section("Global Options:")} -v, --verbose` : "";
 }
 function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlags) {
   const seen = /* @__PURE__ */ new Map();
@@ -6699,10 +7043,13 @@ function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlag
         if (seen.has(dedupeKey)) {
           continue;
         }
-        seen.set(dedupeKey, {
-          flags: formatHelpFieldFlags(field, globalLongOptionFlags),
-          description: formatHelpFieldDescription(field)
-        });
+        seen.set(
+          dedupeKey,
+          createHelpOptionRow(
+            formatHelpFieldFlags(field, globalLongOptionFlags),
+            formatHelpFieldDescription(field)
+          )
+        );
       }
       return;
     }
@@ -6722,6 +7069,18 @@ function formatHelpCommandList(rows) {
 function formatHelpOptionList(rows) {
   return process.stdout.isTTY !== true ? help_formatter_plain_exports.formatOptionList(rows) : formatOptionList(rows);
 }
+function sortLeafHelpOptionFields(fields) {
+  const required = [];
+  const optional = [];
+  for (const field of fields) {
+    if (!field.optional && !field.hasDefault) {
+      required.push(field);
+      continue;
+    }
+    optional.push(field);
+  }
+  return [...required, ...optional];
+}
 function buildUsageLine(breadcrumb, rootUsageName, suffix) {
   const visibleBreadcrumb = breadcrumb.filter((segment) => segment.length > 0);
   const usageBreadcrumb = breadcrumb[0] === "" ? [rootUsageName, ...visibleBreadcrumb] : visibleBreadcrumb;
@@ -6731,15 +7090,37 @@ function buildUsageLine(breadcrumb, rootUsageName, suffix) {
 }
 function formatGroupUsageSuffix(group, scope, casing, globalLongOptionFlags) {
   if (group.default !== void 0 && group.default.hidden === true && group.default.scope.includes(scope)) {
-    const parameterTokens = formatCommandParameterTokens(
-      group.default,
-      casing,
-      globalLongOptionFlags
+    const parameterTokens = collapseOptionalParameterTokens(
+      formatCommandParameterTokens(group.default, casing, globalLongOptionFlags)
     );
-    return ["[command]", "[OPTIONS]", ...parameterTokens].join(" ");
+    return ["[command]", "[OPTIONS]", ...parameterTokens.map((token) => token.text)].join(" ");
   }
   return "[command] [OPTIONS]";
 }
+function formatHelpDrillDownFooter(rootUsageName) {
+  return text.muted(`Run ${rootUsageName} <command> --help for full options.`);
+}
+function formatStyledUsageLine(usageLine) {
+  const parts = usageLine.split(" ").filter((part) => part.length > 0);
+  if (parts.length === 0) {
+    return text.usageCommand(usageLine);
+  }
+  const commandEnd = parts.findIndex(
+    (part) => part.startsWith("-") || part.startsWith("[") || part.startsWith("<")
+  );
+  const commandParts = commandEnd === -1 ? parts : parts.slice(0, commandEnd);
+  const argParts = commandEnd === -1 ? [] : parts.slice(commandEnd);
+  const command = commandParts.join(" ");
+  if (argParts.length === 0) {
+    return text.usageCommand(command);
+  }
+  return `${text.usageCommand(command)} ${renderHelpTokens(
+    argParts.flatMap((part, index) => [
+      ...index === 0 ? [] : [{ text: " ", role: "literal" }],
+      ...tokenizeHelpFlags(part)
+    ])
+  )}`;
+}
 function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUsageName, isRoot) {
   const sections = [];
   const globalLongOptionFlags = getGlobalLongOptionFlags(
@@ -6755,7 +7136,7 @@ function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUs
     globalOptions.controls.help
   );
   if (commandRows.length > 0) {
-    sections.push(`${text.sectionHeader("Commands")}
+    sections.push(`${text.section("Commands:")}
 ${formatHelpCommandList(commandRows)}`);
   }
   if (isRoot) {
@@ -6768,7 +7149,7 @@ ${formatHelpCommandList(commandRows)}`);
     const builtInLine = formatGlobalOptionsLine(globalOptions);
     if (schemaGlobalRows.length > 0) {
       sections.push(
-        `${text.sectionHeader("Options")}
+        `${text.section("Options:")}
 ${formatHelpOptionList(schemaGlobalRows)}
 ${builtInLine}`
       );
@@ -6776,6 +7157,9 @@ ${builtInLine}`
       sections.push(builtInLine);
     }
   }
+  if (commandRows.length > 0) {
+    sections.push(formatHelpDrillDownFooter(rootUsageName));
+  }
   return renderHelpDocument({
     breadcrumb,
     rootUsageName,
@@ -6798,12 +7182,21 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
   );
   const collected = collectFields(command.params, casing, globalLongOptionFlags);
   const fields = assignPositionals(collected.fields, command.positional);
-  const optionRows = fields.filter((field) => field.global !== true).map((field) => ({
-    flags: formatHelpFieldFlags(field, globalLongOptionFlags),
-    description: formatHelpFieldDescription(field)
-  })).concat(collected.dynamicFields.flatMap((field) => formatDynamicHelpFields(field, casing)));
+  const localFields = fields.filter((field) => field.global !== true);
+  const toHelpRow = (field) => createHelpOptionRow(
+    formatHelpFieldFlags(field, globalLongOptionFlags),
+    formatHelpFieldDescription(field)
+  );
+  const argumentRows = localFields.filter((field) => field.positionalIndex !== void 0).map(toHelpRow);
+  const optionRows = sortLeafHelpOptionFields(
+    localFields.filter((field) => field.positionalIndex === void 0)
+  ).map(toHelpRow).concat(collected.dynamicFields.flatMap((field) => formatDynamicHelpFields(field, casing)));
+  if (argumentRows.length > 0) {
+    sections.push(`${text.section("Arguments:")}
+${formatHelpOptionList(argumentRows)}`);
+  }
   if (optionRows.length > 0) {
-    sections.push(`${text.sectionHeader("Options")}
+    sections.push(`${text.section("Options:")}
 ${formatHelpOptionList(optionRows)}`);
   }
   const builtInLine = formatLeafGlobalOptionsLine(globalOptions);
@@ -6813,13 +7206,13 @@ ${formatHelpOptionList(optionRows)}`);
   const secretRows = formatSecretRows(command.secrets);
   if (secretRows.length > 0) {
     sections.push(
-      `${text.sectionHeader("Secrets (environment)")}
+      `${text.section("Secrets (environment):")}
 ${formatHelpOptionList(secretRows)}`
     );
   }
   if (command.examples.length > 0) {
     sections.push(
-      `${text.sectionHeader("Examples")}
+      `${text.section("Examples:")}
 ${formatExampleRows(command.examples, breadcrumb, rootUsageName).join("\n")}`
     );
   }
@@ -6941,7 +7334,7 @@ function renderHelpDocument(input) {
   if (remainingDescription.length > 0) {
     lines.push(remainingDescription, "");
   }
-  lines.push(`Usage: ${text.usageCommand(input.usageLine)}`, "");
+  lines.push(`Usage: ${formatStyledUsageLine(input.usageLine)}`, "");
   if (input.requiresAuth) {
     lines.push("Requires: authentication");
   }
@@ -7025,7 +7418,9 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
     }
     for (const field of fields) {
       if (field.positionalIndex !== void 0) {
-        command.argument(formatPositionalToken(field));
+        command.argument(
+          field.variadicPosition === true ? `[${field.displayPath}...]` : `[${field.displayPath}]`
+        );
         continue;
       }
       for (const option of createOption(field, globalLongOptionFlags)) {
@@ -7860,11 +8255,11 @@ function writeRichHeader(title) {
 function isHumanInLoopPending(result) {
   return typeof result === "object" && result !== null && result.status === "pending-approval" && typeof result.approvalId === "string" && typeof result.message === "string" && typeof result.enqueuedAt === "string";
 }
-function renderHumanInLoopPending(pending) {
+function renderHumanInLoopPending(pending, rootUsageName) {
   process.stdout.write(
     `\u2713 Queued for human approval (id: ${pending.approvalId})
   Message: ${pending.message}
-  Track:   toolcraft approvals show ${pending.approvalId}
+  Track:   ${rootUsageName} approvals show --approval-id ${pending.approvalId}
 `
   );
 }
@@ -7968,7 +8363,7 @@ function parseOptionFieldValue(field, value, errors) {
     }
     return { ok: true, value: parsedValue };
   } catch (error3) {
-    if (error3 instanceof UserError || error3 instanceof InvalidArgumentError) {
+    if (isUserError(error3) || error3 instanceof InvalidArgumentError) {
       errors.push({
         path: field.displayPath,
         message: error3.message
@@ -8550,7 +8945,7 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
       }
       errors.push({
         path: field.displayPath,
-        message: `Missing required parameter "${field.displayPath}".`
+        message: formatMissingParameterMessage(field)
       });
       continue;
     }
@@ -8601,7 +8996,7 @@ function getResolvedFlags(command) {
   const flags = command.optsWithGlobals();
   return flags;
 }
-async function executeCommand(state, services, requirementOptions, runtimeFetch, humanInLoop, runtimeEnv, runtimeFs, outputEmitter, outputFormats, promptStreams, diagnosticsOptions, onErrorReportContext) {
+async function executeCommand(state, rootUsageName, services, requirementOptions, runtimeFetch, humanInLoop, runtimeEnv, runtimeFs, outputEmitter, outputFormats, promptStreams, diagnosticsOptions, onErrorReportContext) {
   const logger2 = createLogger(outputEmitter);
   const optionValues = state.actionCommand.optsWithGlobals();
   const resolvedFlags = optionValues;
@@ -8757,7 +9152,7 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
         writeRichHeader(`${state.command.name} (fixture)`);
       }
       if (isHumanInLoopPending(result)) {
-        renderHumanInLoopPending(result);
+        renderHumanInLoopPending(result, rootUsageName);
         return;
       }
       const renderStatus = renderCLIResult(
@@ -9000,7 +9395,7 @@ function renderHttpError(error3, options) {
 async function handleRunError(error3, options) {
   const logger2 = createLogger(options.outputEmitter);
   await withOutputFormat2(options.output, async () => {
-    if (error3 instanceof UserError) {
+    if (isUserError(error3)) {
       renderCliErrorPattern(
         options.userErrorPattern === "definition" ? {
           kind: "definition",
@@ -9316,11 +9711,9 @@ function getDefaultCommanderCommandName(command) {
 function configureCommanderSuggestionOutput(command) {
   command.exitOverride();
   command.configureOutput({
-    outputError: (message2, write2) => {
-      if (message2.includes("unknown command") || message2.includes("unknown option")) {
-        return;
-      }
-      write2(message2);
+    // Every Commander error throws through exitOverride and is rendered once by handleRunError
+    // in the design-system error pattern; writing it here as well double-reports one mistake.
+    outputError: () => {
     }
   });
   command.commands.forEach((child) => configureCommanderSuggestionOutput(child));
@@ -9393,6 +9786,7 @@ async function runCLI(roots, options = {}) {
       resolvedCommandPath = formatCliCommandPath(state.commandPath);
       await executeCommand(
         state,
+        rootUsageName,
         servicesWithBuiltIns,
         requirementOptions,
         runtimeFetch,
@@ -11063,7 +11457,7 @@ var claudeCodeAgent = {
   id: "claude-code",
   name: "claude-code",
   label: "Claude Code",
-  summary: "Configure Claude Code to route through Poe.",
+  summary: "Anthropic's agentic coding tool for the terminal.",
   aliases: ["claude"],
   binaryName: "claude",
   apiShapes: ["anthropic-messages"],
@@ -11073,6 +11467,7 @@ var claudeCodeAgent = {
     }
   },
   configPath: "~/.claude.json",
+  capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
   branding: {
     colors: {
       dark: "#C15F3C",
@@ -11093,6 +11488,7 @@ var claudeDesktopAgent = {
     linux: "~/.config/Claude/claude_desktop_config.json",
     win32: "~/AppData/Roaming/Claude/claude_desktop_config.json"
   },
+  capabilities: ["mcp"],
   branding: {
     colors: {
       dark: "#D97757",
@@ -11106,7 +11502,7 @@ var codexAgent = {
   id: "codex",
   name: "codex",
   label: "Codex",
-  summary: "Configure Codex to use Poe as the model provider.",
+  summary: "OpenAI's coding agent for the terminal.",
   binaryName: "codex",
   apiShapes: ["openai-responses"],
   otelCapture: {
@@ -11120,6 +11516,7 @@ var codexAgent = {
     ]
   },
   configPath: "~/.codex/config.toml",
+  capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
   branding: {
     colors: {
       dark: "#D5D9DF",
@@ -11137,6 +11534,7 @@ var cursorAgent = {
   summary: "Cursor's CLI coding agent.",
   binaryName: "cursor-agent",
   configPath: "~/.cursor/mcp.json",
+  capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
   branding: {
     colors: {
       dark: "#FFFFFF",
@@ -11151,10 +11549,11 @@ var geminiCliAgent = {
   name: "gemini-cli",
   aliases: ["gemini"],
   label: "Gemini CLI",
-  summary: "Configure Google's Gemini CLI to use a compatible Google generations API.",
+  summary: "Google's open-source AI agent for the terminal.",
   binaryName: "gemini",
   configPath: "~/.gemini/settings.json",
   apiShapes: ["google-generations"],
+  capabilities: ["spawn", "configure", "install", "test", "skill"],
   branding: {
     colors: {
       dark: "#8AB4F8",
@@ -11168,7 +11567,7 @@ var openCodeAgent = {
   id: "opencode",
   name: "opencode",
   label: "OpenCode CLI",
-  summary: "Configure OpenCode CLI to use the Poe API.",
+  summary: "Open-source AI coding agent for the terminal.",
   binaryName: "opencode",
   apiShapes: ["openai-chat-completions"],
   otelCapture: {
@@ -11177,6 +11576,7 @@ var openCodeAgent = {
     }
   },
   configPath: "~/.config/opencode/opencode.json",
+  capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
   branding: {
     colors: {
       dark: "#4A4F55",
@@ -11190,11 +11590,12 @@ var kimiAgent = {
   id: "kimi",
   name: "kimi",
   label: "Kimi",
-  summary: "Configure Kimi CLI to use Poe API",
+  summary: "Moonshot AI's coding agent for the terminal.",
   aliases: ["kimi-cli"],
   binaryName: "kimi",
   apiShapes: ["openai-chat-completions"],
   configPath: "~/.kimi/mcp.json",
+  capabilities: ["spawn", "configure", "install", "test", "mcp"],
   branding: {
     colors: {
       dark: "#7B68EE",
@@ -11213,6 +11614,7 @@ var gooseAgent = {
   apiShapes: ["openai-chat-completions"],
   otelCapture: {},
   configPath: "~/.config/goose/config.yaml",
+  capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
   branding: {
     colors: {
       dark: "#FF6B35",
@@ -11227,8 +11629,9 @@ var piAgent = {
   name: "pi",
   aliases: ["pi-agent"],
   label: "Pi",
-  summary: "Pi coding agent (spawn-only; uses local Pi auth/settings).",
+  summary: "Minimal AI coding agent for the terminal.",
   binaryName: "pi",
+  capabilities: ["spawn"],
   branding: {
     colors: {
       dark: "#F2F2F2",
@@ -11245,6 +11648,7 @@ var poeAgentAgent = {
   summary: "Run one-shot prompts with the built-in Poe agent runtime.",
   apiShapes: ["openai-responses", "openai-chat-completions"],
   configPath: "~/.poe-code/config.json",
+  capabilities: ["configure"],
   branding: {
     colors: {
       dark: "#A465F7",
@@ -11261,6 +11665,9 @@ function freezeAgent(agent) {
   if (agent.apiShapes !== void 0) {
     Object.freeze(agent.apiShapes);
   }
+  if (agent.capabilities !== void 0) {
+    Object.freeze(agent.capabilities);
+  }
   if (agent.otelCapture?.env !== void 0) {
     Object.freeze(agent.otelCapture.env);
   }
@@ -11324,7 +11731,8 @@ var agentSkillConfigs = {
   },
   goose: {
     globalSkillDir: "~/.agents/skills",
-    localSkillDir: ".agents/skills"
+    localSkillDir: ".agents/skills",
+    dirNote: "Goose discovers skills from the shared .agents/skills convention, not a goose-specific directory."
   }
 };
 var supportedAgents = Object.freeze(Object.keys(agentSkillConfigs));
@@ -12698,6 +13106,16 @@ async function executeMutation(mutation, context, options) {
   }
 }
 
+// ../user-error/src/index.ts
+var UserError2 = class extends Error {
+  hint;
+  constructor(message2, options) {
+    super(message2, options);
+    this.name = "UserError";
+    this.hint = options?.hint;
+  }
+};
+
 // ../agent-skill-config/src/error-codes.ts
 function hasOwnErrorCode4(error3, code) {
   return error3 instanceof Error && Object.prototype.hasOwnProperty.call(error3, "code") && error3.code === code;
@@ -12749,8 +13167,11 @@ async function installSkill(agentId, skill, options) {
   const skillFilePath = `${skillFolderPath}/SKILL.md`;
   const displayPath = `${scope === "global" ? config2.globalSkillDir : config2.localSkillDir}/${skill.name}/SKILL.md`;
   const absoluteSkillPath = `${scope === "global" ? options.homeDir : options.cwd}/${skillFilePath.slice(2)}`;
-  if (await pathExists2(options.fs, absoluteSkillPath)) {
-    throw new Error(`Skill already exists: ${displayPath}`);
+  if (!options.force && await pathExists2(options.fs, absoluteSkillPath)) {
+    throw new UserError2(
+      `Skill already exists: ${displayPath}
+Re-run with --force to overwrite it, or remove it first.`
+    );
   }
   await runMutations(
     [
@@ -14828,7 +15249,7 @@ function sleep2(ms) {
 // src/cli.ts
 configureTheme({ brand: "green", label: "Terminal Pilot" });
 function getBundledPackageVersion() {
-  return true ? "0.0.48" : void 0;
+  return true ? "0.0.49" : void 0;
 }
 var pilotOptionsWithValues = /* @__PURE__ */ new Set([
   "--session",