terminal-pilot 0.0.48 → 0.0.50

package/node_modules/@poe-code/agent-defs/README.md

@@ -4,7 +4,8 @@ Shared catalog of supported coding-agent definitions.
 
 This package owns the declarative agent metadata used by CLI, SDK, spawn,
 configuration, and UI surfaces: stable ids, labels, aliases, config paths,
-binary names, API-shape support, OTEL capture wiring, and brand colors.
+binary names, API-shape support, OTEL capture wiring, brand colors, and the
+capability matrix that says which commands accept each agent.
 
 ## Usage
 
@@ -24,6 +25,18 @@ const codex = allAgents.find((agent) => agent.id === "codex");
 - `formatAgentSpecifier(specifier)`: formats an agent specifier.
 - `normalizeAgentId(input)`: normalizes the agent part through the registry.
 - Agent definition exports such as `codexAgent`, `claudeCodeAgent`, `geminiCliAgent`, and `piAgent`.
+- `listAgentsWithCapability(capability, options?)`: ids supporting a capability, optionally including aliases.
+- `agentSupportsCapability(input, capability)`: resolves aliases, then checks the matrix.
+- `formatAgentCapabilityError({ agent, capability })`: the shared message for a rejected agent argument.
+
+## Capability Matrix
+
+Each `AgentDefinition` declares its `capabilities` (`spawn`, `configure`,
+`install`, `test`, `skill`, `mcp`). This is the single published source for every
+command's allow-list, so `spawn`/`configure`/`install`/`test`/`skill` cannot
+drift apart. `src/cli/commands/agent-capability-matrix.test.ts` pins each
+capability to the registry that implements it, and fails if a registry gains or
+loses an agent without the matrix being updated.
 
 ## Config Options
 

package/node_modules/@poe-code/agent-defs/dist/agents/claude-code.js

@@ -2,7 +2,7 @@ export const 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"],
@@ -12,6 +12,7 @@ export const claudeCodeAgent = {
         }
     },
     configPath: "~/.claude.json",
+    capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
     branding: {
         colors: {
             dark: "#C15F3C",

package/node_modules/@poe-code/agent-defs/dist/agents/claude-desktop.js

@@ -9,6 +9,7 @@ export const claudeDesktopAgent = {
         linux: "~/.config/Claude/claude_desktop_config.json",
         win32: "~/AppData/Roaming/Claude/claude_desktop_config.json"
     },
+    capabilities: ["mcp"],
     branding: {
         colors: {
             dark: "#D97757",

package/node_modules/@poe-code/agent-defs/dist/agents/codex.js

@@ -2,7 +2,7 @@ export const 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: {
@@ -16,6 +16,7 @@ export const codexAgent = {
         ]
     },
     configPath: "~/.codex/config.toml",
+    capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
     branding: {
         colors: {
             dark: "#D5D9DF",

package/node_modules/@poe-code/agent-defs/dist/agents/cursor.js

@@ -6,6 +6,7 @@ export const 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",

package/node_modules/@poe-code/agent-defs/dist/agents/gemini-cli.js

@@ -3,10 +3,11 @@ export const 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",

package/node_modules/@poe-code/agent-defs/dist/agents/goose.js

@@ -7,6 +7,7 @@ export const gooseAgent = {
     apiShapes: ["openai-chat-completions"],
     otelCapture: {},
     configPath: "~/.config/goose/config.yaml",
+    capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
     branding: {
         colors: {
             dark: "#FF6B35",

package/node_modules/@poe-code/agent-defs/dist/agents/kimi.js

@@ -2,11 +2,12 @@ export const 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",

package/node_modules/@poe-code/agent-defs/dist/agents/opencode.js

@@ -2,7 +2,7 @@ export const 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: {
@@ -11,6 +11,7 @@ export const openCodeAgent = {
         }
     },
     configPath: "~/.config/opencode/opencode.json",
+    capabilities: ["spawn", "configure", "install", "test", "skill", "mcp"],
     branding: {
         colors: {
             dark: "#4A4F55",

package/node_modules/@poe-code/agent-defs/dist/agents/pi.js

@@ -3,8 +3,9 @@ export const 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",

package/node_modules/@poe-code/agent-defs/dist/agents/poe-agent.js

@@ -5,6 +5,7 @@ export const 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",

package/node_modules/@poe-code/agent-defs/dist/capabilities.d.ts

@@ -0,0 +1,14 @@
+import type { AgentCapability } from "./types.js";
+export declare function listAgentsWithCapability(capability: AgentCapability, options?: {
+    includeAliases?: boolean;
+}): readonly string[];
+export declare function agentSupportsCapability(input: string, capability: AgentCapability): boolean;
+/**
+ * The single message for every agent argument that misses. It distinguishes a
+ * typo (unknown id, plus a did-you-mean) from a real capability gap ("pi
+ * supports: spawn"), and always names the agents the command does accept.
+ */
+export declare function formatAgentCapabilityError(input: {
+    agent: string;
+    capability: AgentCapability;
+}): string;

package/node_modules/@poe-code/agent-defs/dist/capabilities.js

@@ -0,0 +1,63 @@
+import { allAgents, resolveAgentId } from "./registry.js";
+export function listAgentsWithCapability(capability, options) {
+    const names = [];
+    for (const agent of allAgents) {
+        if (!agent.capabilities?.includes(capability)) {
+            continue;
+        }
+        names.push(agent.id);
+        if (options?.includeAliases) {
+            names.push(...(agent.aliases ?? []));
+        }
+    }
+    return names;
+}
+export function agentSupportsCapability(input, capability) {
+    const id = resolveAgentId(input);
+    return id !== undefined && listAgentsWithCapability(capability).includes(id);
+}
+const MAX_SUGGESTION_DISTANCE = 3;
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_unused, index) => index);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current[j] = Math.min(substitution, previous[j] + 1, current[j - 1] + 1);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** Every candidate tied for the smallest edit distance, when one is close enough. */
+function suggest(input, candidates) {
+    const needle = input.trim().toLowerCase();
+    const scored = candidates
+        .map((candidate) => ({ candidate, score: editDistance(needle, candidate.toLowerCase()) }))
+        .filter((entry) => entry.score <= MAX_SUGGESTION_DISTANCE);
+    if (scored.length === 0) {
+        return [];
+    }
+    const best = Math.min(...scored.map((entry) => entry.score));
+    return scored.filter((entry) => entry.score === best).map((entry) => entry.candidate);
+}
+/**
+ * The single message for every agent argument that misses. It distinguishes a
+ * typo (unknown id, plus a did-you-mean) from a real capability gap ("pi
+ * supports: spawn"), and always names the agents the command does accept.
+ */
+export function formatAgentCapabilityError(input) {
+    const allowed = listAgentsWithCapability(input.capability, { includeAliases: true });
+    const allowList = `Agents supporting ${input.capability}: ${allowed.length > 0 ? allowed.join(", ") : "none"}.`;
+    const id = resolveAgentId(input.agent);
+    if (!id) {
+        const near = suggest(input.agent, allowed);
+        const hint = near.length > 0 ? ` Did you mean: ${near.join(", ")}?` : "";
+        return `Unknown agent "${input.agent}".${hint} ${allowList}`;
+    }
+    const supported = ["spawn", "configure", "install", "test", "skill", "mcp"].filter((capability) => listAgentsWithCapability(capability).includes(id));
+    const supports = supported.length > 0
+        ? `${id} supports: ${supported.join(", ")}.`
+        : `${id} is not supported by poe-code agent commands.`;
+    return `Agent "${id}" does not support ${input.capability}. ${supports} ${allowList}`;
+}

package/node_modules/@poe-code/agent-defs/dist/index.d.ts

@@ -1,5 +1,6 @@
-export type { AgentDefinition, ApiShapeId, OtelCaptureDefinition } from "./types.js";
+export type { AgentCapability, AgentDefinition, ApiShapeId, OtelCaptureDefinition } from "./types.js";
 export type { AgentSpecifier } from "./specifier.js";
 export { claudeCodeAgent, claudeDesktopAgent, codexAgent, cursorAgent, geminiCliAgent, openCodeAgent, kimiAgent, gooseAgent, piAgent, poeAgentAgent } from "./agents/index.js";
 export { allAgents, resolveAgentId } from "./registry.js";
+export { agentSupportsCapability, formatAgentCapabilityError, listAgentsWithCapability } from "./capabilities.js";
 export { parseAgentSpecifier, formatAgentSpecifier, normalizeAgentId } from "./specifier.js";

package/node_modules/@poe-code/agent-defs/dist/index.js

@@ -1,3 +1,4 @@
 export { claudeCodeAgent, claudeDesktopAgent, codexAgent, cursorAgent, geminiCliAgent, openCodeAgent, kimiAgent, gooseAgent, piAgent, poeAgentAgent } from "./agents/index.js";
 export { allAgents, resolveAgentId } from "./registry.js";
+export { agentSupportsCapability, formatAgentCapabilityError, listAgentsWithCapability } from "./capabilities.js";
 export { parseAgentSpecifier, formatAgentSpecifier, normalizeAgentId } from "./specifier.js";

package/node_modules/@poe-code/agent-defs/dist/registry.js

@@ -6,6 +6,9 @@ function freezeAgent(agent) {
     if (agent.apiShapes !== undefined) {
         Object.freeze(agent.apiShapes);
     }
+    if (agent.capabilities !== undefined) {
+        Object.freeze(agent.capabilities);
+    }
     if (agent.otelCapture?.env !== undefined) {
         Object.freeze(agent.otelCapture.env);
     }

package/node_modules/@poe-code/agent-defs/dist/types.d.ts

@@ -1,4 +1,10 @@
 export type ApiShapeId = "openai-chat-completions" | "openai-responses" | "anthropic-messages" | "google-generations";
+/**
+ * The poe-code surfaces an agent can be used with. This is the single
+ * published source for each command's allow-list; `agent-capability-matrix.test.ts`
+ * pins every value to the registry that implements it, so the sets cannot drift.
+ */
+export type AgentCapability = "spawn" | "configure" | "install" | "test" | "skill" | "mcp";
 export interface OtelCaptureDefinition {
     env?: Record<string, string>;
     args?: (endpoint: string, content: boolean) => string[];
@@ -11,6 +17,7 @@ export interface AgentDefinition {
     aliases?: string[];
     /** Binary name for CLI agents. Optional for GUI-only apps like Claude Desktop. */
     binaryName?: string;
+    readonly capabilities?: readonly AgentCapability[];
     readonly apiShapes?: readonly ApiShapeId[];
     readonly otelCapture?: OtelCaptureDefinition;
     configPath?: string;

package/node_modules/@poe-code/agent-skill-config/dist/apply.d.ts

@@ -13,6 +13,8 @@ export type InstallSkillOptions = {
     scope: ApplyOptions["scope"];
     dryRun?: boolean;
     observers?: ApplyOptions["observers"];
+    /** Overwrite an existing SKILL.md instead of refusing to install over it. */
+    force?: boolean;
 };
 export type InstallSkillResult = {
     skillPath: string;

package/node_modules/@poe-code/agent-skill-config/dist/apply.js

@@ -1,4 +1,5 @@
 import { fileMutation, runMutations, templateMutation } from "@poe-code/config-mutations";
+import { UserError } from "@poe-code/user-error";
 import { resolveAgentSupport } from "./configs.js";
 import { hasOwnErrorCode } from "./error-codes.js";
 import { createTemplateLoader } from "./templates.js";
@@ -45,7 +46,7 @@ export async function configure(agentId, options) {
         if (await pathExists(options.fs, targetPath)) {
             const existing = await options.fs.readFile(targetPath, "utf8");
             if (existing !== (await templateLoader(templateId))) {
-                throw new Error(`Skill already exists: ${targetPath}`);
+                throw new UserError(`Skill already exists and differs from the bundled ${templateId}: ${targetPath}\nMove or delete it, then re-run this command to install the poe-code version.`);
             }
         }
     }
@@ -75,27 +76,30 @@ export async function unconfigure(agentId, options) {
     const scope = options.scope ?? "global";
     const config = support.config;
     const skillDir = scope === "global" ? config.globalSkillDir : toHomeRelative(config.localSkillDir);
+    const displayDir = scope === "global" ? config.globalSkillDir : config.localSkillDir;
     const homeDir = scope === "global" ? options.homeDir : options.cwd;
     const templateLoader = createTemplateLoader();
     const removeBundledSkills = [];
     for (const templateId of bundledSkillTemplateIds) {
-        const targetPath = `${scope === "global" ? options.homeDir : options.cwd}/${skillDir.slice(2)}/${templateId}`;
-        if (await pathExists(options.fs, targetPath)) {
-            const existing = await options.fs.readFile(targetPath, "utf8");
-            if (existing === (await templateLoader(templateId))) {
-                removeBundledSkills.push(fileMutation.remove({
-                    target: `${skillDir}/${templateId}`,
-                    label: `Remove bundled skill ${templateId} from ${skillDir}`
-                }));
-            }
+        const targetPath = `${homeDir}/${skillDir.slice(2)}/${templateId}`;
+        if (!(await pathExists(options.fs, targetPath))) {
+            continue;
+        }
+        const existing = await options.fs.readFile(targetPath, "utf8");
+        if (options.force || existing === (await templateLoader(templateId))) {
+            removeBundledSkills.push(fileMutation.remove({
+                target: `${skillDir}/${templateId}`,
+                label: `Remove bundled skill ${templateId} from ${displayDir}`
+            }));
         }
     }
     await runMutations([
         ...removeBundledSkills,
+        // Never force-remove the shared skills root: it holds skills poe-code does not
+        // manage. It is only removed once poe-code's own skills left it empty.
         fileMutation.removeDirectory({
             path: skillDir,
-            force: options.force,
-            label: `Remove skills directory ${skillDir}`
+            label: `Remove empty skills directory ${displayDir}`
         })
     ], {
         fs: options.fs,
@@ -132,8 +136,8 @@ export async function installSkill(agentId, skill, options) {
     const skillFilePath = `${skillFolderPath}/SKILL.md`;
     const displayPath = `${scope === "global" ? config.globalSkillDir : config.localSkillDir}/${skill.name}/SKILL.md`;
     const absoluteSkillPath = `${scope === "global" ? options.homeDir : options.cwd}/${skillFilePath.slice(2)}`;
-    if (await pathExists(options.fs, absoluteSkillPath)) {
-        throw new Error(`Skill already exists: ${displayPath}`);
+    if (!options.force && (await pathExists(options.fs, absoluteSkillPath))) {
+        throw new UserError(`Skill already exists: ${displayPath}\nRe-run with --force to overwrite it, or remove it first.`);
     }
     await runMutations([
         fileMutation.ensureDirectory({

package/node_modules/@poe-code/agent-skill-config/dist/bridge-active-skills.js

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { getAgentConfig, resolveAgentSupport, resolveSkillDir, supportedAgents } from "./configs.js";
+import { UserError } from "@poe-code/user-error";
 import { hasOwnErrorCode } from "./error-codes.js";
 import { appendExcludeBlock, removeExcludeBlock } from "./git-exclude.js";
 import { resolveSkillReference } from "./resolve-skill-reference.js";
@@ -88,8 +89,9 @@ function formatResolutionFailureError(failures) {
                 lines.push(`  - ${searchedPath}`);
             }
         }
+        lines.push("Install one with poe-code skill install <agent> --name <name> --file <path>.");
     }
-    return new Error(lines.join("\n"));
+    return new UserError(lines.join("\n"));
 }
 function copyDirectory(sourcePath, targetPath) {
     fs.mkdirSync(targetPath, { recursive: true });

package/node_modules/@poe-code/agent-skill-config/dist/configs.d.ts

@@ -1,6 +1,8 @@
 export interface AgentSkillConfig {
     globalSkillDir: string;
     localSkillDir: string;
+    /** Set only when the directories deviate from the agent's own dot-directory. */
+    dirNote?: string;
 }
 export type SkillScope = "global" | "local";
 export declare const supportedAgents: readonly string[];

package/node_modules/@poe-code/agent-skill-config/dist/configs.js

@@ -24,7 +24,8 @@ const 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."
     }
 };
 export const supportedAgents = Object.freeze(Object.keys(agentSkillConfigs));

package/node_modules/@poe-code/frontmatter/README.md

@@ -6,7 +6,9 @@ Shared YAML frontmatter parsing for poe-code packages.
 
 ```ts
 import {
+  FrontmatterKindError,
   FrontmatterParseError,
+  isFrontmatterKindError,
   parseFrontmatter,
   parseFrontmatterDocument,
   stringifyFrontmatter
@@ -17,6 +19,7 @@ import {
 - `parseFrontmatterDocument(source)` returns `{ frontmatter, body, errors, lineCounter }` for callers that need YAML diagnostics.
 - `stringifyFrontmatter(frontmatter, body)` writes `---` fences, YAML, and the body.
 - `FrontmatterParseError` is thrown for malformed frontmatter, invalid YAML, non-object frontmatter, and stringify failures.
+- `FrontmatterKindError` extends `FrontmatterParseError` and carries `expectedKind` / `foundKind` so callers can report a document kind mismatch instead of a missing file. `isFrontmatterKindError(error)` narrows to it.
 
 When no leading frontmatter block exists, parsing returns `{ frontmatter: {}, body: source }`.
 The returned `body` is sliced from the original input and is otherwise byte-for-byte unchanged.

package/node_modules/@poe-code/frontmatter/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { splitFrontmatterBlock, type FrontmatterBlock, type SplitFrontmatterResult } from "./fences.js";
-export { FrontmatterParseError, parseFrontmatter, parseFrontmatterDocument, type ParsedFrontmatter, type ParsedFrontmatterDocument, type ParseFrontmatterOptions } from "./parse.js";
+export { FrontmatterKindError, FrontmatterParseError, isFrontmatterKindError, parseFrontmatter, parseFrontmatterDocument, type ParsedFrontmatter, type ParsedFrontmatterDocument, type ParseFrontmatterOptions } from "./parse.js";
 export { stringifyFrontmatter } from "./stringify.js";

package/node_modules/@poe-code/frontmatter/dist/index.js

@@ -1,3 +1,3 @@
 export { splitFrontmatterBlock } from "./fences.js";
-export { FrontmatterParseError, parseFrontmatter, parseFrontmatterDocument } from "./parse.js";
+export { FrontmatterKindError, FrontmatterParseError, isFrontmatterKindError, parseFrontmatter, parseFrontmatterDocument } from "./parse.js";
 export { stringifyFrontmatter } from "./stringify.js";

package/node_modules/@poe-code/frontmatter/dist/parse.d.ts

@@ -16,5 +16,14 @@ export interface ParseFrontmatterOptions {
 export declare class FrontmatterParseError extends Error {
     constructor(message: string);
 }
+export declare class FrontmatterKindError extends FrontmatterParseError {
+    readonly expectedKind: string;
+    readonly foundKind: string;
+    constructor(message: string, kinds: {
+        expected: string;
+        found: string;
+    });
+}
+export declare function isFrontmatterKindError(error: unknown): error is FrontmatterKindError;
 export declare function parseFrontmatter(source: string, options?: ParseFrontmatterOptions): ParsedFrontmatter;
 export declare function parseFrontmatterDocument(source: string, options?: ParseFrontmatterOptions): ParsedFrontmatterDocument;

package/node_modules/@poe-code/frontmatter/dist/parse.js

@@ -6,6 +6,22 @@ export class FrontmatterParseError extends Error {
         this.name = "FrontmatterParseError";
     }
 }
+export class FrontmatterKindError extends FrontmatterParseError {
+    expectedKind;
+    foundKind;
+    constructor(message, kinds) {
+        super(message);
+        this.name = "FrontmatterKindError";
+        this.expectedKind = kinds.expected;
+        this.foundKind = kinds.found;
+    }
+}
+export function isFrontmatterKindError(error) {
+    return (error instanceof Error &&
+        error.name === "FrontmatterKindError" &&
+        typeof error.expectedKind === "string" &&
+        typeof error.foundKind === "string");
+}
 export function parseFrontmatter(source, options = {}) {
     const split = splitFrontmatter(source);
     if (split.raw === undefined) {

package/node_modules/@poe-code/user-error/README.md

@@ -0,0 +1,56 @@
+# @poe-code/user-error
+
+The shared user-error type every workspace package throws for expected user
+mistakes, and the guard the CLI renders them with.
+
+`src/cli/errors.ts` cannot be imported from `packages/*`, so package code used to
+throw a plain `Error` for recoverable conditions. `src/cli/bootstrap.ts` then
+treated each one as a crash: an `Error:` prefix plus a `See logs at
+~/.poe-code/logs/errors.log` pointer to a log that adds nothing for a typo. This
+package gives packages a classification the CLI honours.
+
+## Usage
+
+```ts
+import { UserError, isUserError } from "@poe-code/user-error";
+
+throw new UserError('Unknown agent "clyde". Try: claude, codex, gemini.');
+
+throw new UserError("No API key found.", {
+  hint: "Create one at https://poe.com/api_key",
+  cause: readError
+});
+
+if (isUserError(error)) {
+  // render the message as guidance: no stack trace, no log pointer
+}
+```
+
+Throw a `UserError` when the user can fix the condition themselves, and say how:
+name the value that was rejected and the valid ones, the path that was searched,
+or the URL that issues the key. Keep plain `Error` for genuine failures — those
+should reach the log.
+
+## Public API
+
+- `UserError`: `Error` subclass with `name === "UserError"` and an optional
+  `hint` for the recovery step. Accepts the standard `cause` option.
+- `isUserError(error)`: true for a `UserError` **or** any `Error` whose `name` is
+  `"UserError"`.
+
+## Cross-bundle recognition
+
+`isUserError` matches on `error.name`, not `instanceof`. `toolcraft` publishes its
+own `UserError` (`packages/toolcraft/src/user-error.ts`) as a separately released
+framework, and an instance crossing a bundle boundary fails `instanceof` against
+this package's class. Name matching recognises both, and mirrors the existing
+`isSilentError()` precedent in `src/cli/errors.ts`. toolcraft deliberately does
+not depend on this package — the coupling would run the wrong way.
+
+## Config Options
+
+This package reads no configuration.
+
+## Environment Variables
+
+This package reads no environment variables.

package/node_modules/@poe-code/user-error/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * An expected user mistake: bad input, a missing file, an unknown id, absent
+ * credentials. Thrown where the condition is detected so the CLI can render the
+ * message as guidance instead of dressing it in system-failure chrome.
+ */
+export declare class UserError extends Error {
+    readonly hint?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        hint?: string;
+    });
+}
+/**
+ * Detects user errors by name as well as identity, so an instance created in
+ * another bundle (toolcraft publishes its own `UserError`) is still recognised
+ * where `instanceof` would fail.
+ */
+export declare function isUserError(error: unknown): boolean;

package/node_modules/@poe-code/user-error/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * An expected user mistake: bad input, a missing file, an unknown id, absent
+ * credentials. Thrown where the condition is detected so the CLI can render the
+ * message as guidance instead of dressing it in system-failure chrome.
+ */
+export class UserError extends Error {
+    hint;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "UserError";
+        this.hint = options?.hint;
+    }
+}
+/**
+ * Detects user errors by name as well as identity, so an instance created in
+ * another bundle (toolcraft publishes its own `UserError`) is still recognised
+ * where `instanceof` would fail.
+ */
+export function isUserError(error) {
+    return error instanceof Error && error.name === "UserError";
+}

package/node_modules/@poe-code/user-error/package.json

@@ -0,0 +1,24 @@
+{
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/guard-package-dist.mjs && tsc"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/poe-platform/poe-code.git",
+    "directory": "packages/user-error"
+  }
+}

package/node_modules/toolcraft-design/dist/acp/components.d.ts

@@ -1,4 +1,11 @@
-export declare function renderAgentMessage(text: string): void;
+/**
+ * Status of the agent output being rendered.
+ *
+ * `streaming` covers partial/in-progress content, which has not reached any outcome yet and so must not
+ * claim success. `success`/`error` are terminal outcomes known to the caller.
+ */
+export type AcpOutputState = "streaming" | "success" | "error";
+export declare function renderAgentMessage(text: string, state?: AcpOutputState): void;
 export declare function renderToolStart(kind: string, title: string): void;
 export declare function renderToolComplete(kind: string): void;
 export declare function renderReasoning(text: string): void;