@botdocs/cli 0.10.2 → 0.11.0

package/dist/index.js

@@ -1,5 +1,115 @@
 #!/usr/bin/env node
+// ─── Node version preflight ────────────────────────────────────────────────
+// The authoritative gate lives in `bin/botdocs.cjs` (a CJS shim that runs
+// BEFORE this ESM module is loaded). The shim refuses to hand off to dist/
+// when Node major < 20, so a user on Node 16/18 sees one clean instruction
+// instead of a `SyntaxError` from any modern-syntax dep (commander, Ink,
+// the OpenAI SDK) that ESM's eager module-graph evaluation would otherwise
+// trigger before this file's top-level statements get a chance to run.
+//
+// The inline check here is kept as a belt-and-suspenders no-op for anyone
+// who invokes `node dist/index.js` directly (skipping the shim, e.g. tests
+// or a malformed install). The shared `checkNodeVersion` helper lives in
+// `./lib/node-preflight.js` so it's unit-testable across versions without
+// spawning a subprocess.
+import { checkNodeVersion } from './lib/node-preflight.js';
+{
+    const preflight = checkNodeVersion(process.versions.node);
+    if (!preflight.ok) {
+        process.stderr.write(`${preflight.message}\n`);
+        process.exit(1);
+    }
+}
+// ─── Global error handlers ─────────────────────────────────────────────────
+// Registered before the rest of the program so any async throw in commander
+// dispatch, an unhandled rejection from a fire-and-forget call, or a sync
+// crash in module init lands here instead of dumping a Node stack to stderr.
+//
+// Both handlers print a single friendly line and exit 1 — except for known
+// network-error codes, which get an actionable hint (try again / check DNS),
+// and WaitlistError, which exits 0 because being on the waitlist is the
+// expected state, not a malformed command.
+process.on('unhandledRejection', (reason) => {
+    handleFatal(reason);
+});
+process.on('uncaughtException', (err) => {
+    handleFatal(err);
+});
+/** Friendly stderr line + exit. Pulled out so both the unhandledRejection and
+ * uncaughtException paths produce identical output. Stack traces are gated
+ * behind `BOTDOCS_DEBUG=1` so the default UX stays clean; setting that env
+ * var is the documented escape hatch when filing a bug.
+ *
+ * WaitlistError checking is done by name string rather than `instanceof`
+ * because the class lives in a sibling module whose import order is
+ * arbitrary; comparing the constructor name keeps this handler independent
+ * of import-graph timing.
+ */
+function handleFatal(reason) {
+    if (reason instanceof Error &&
+        reason.name === 'WaitlistError') {
+        process.stdout.write("You're on the BotDocs waitlist. We'll email you when there's space.\n" +
+            '(Check https://botdocs.ai/waitlist for status.)\n');
+        process.exit(0);
+    }
+    const code = extractErrorCode(reason);
+    const message = friendlyNetworkMessage(code) ?? genericFriendlyMessage(reason);
+    process.stderr.write(`${message}\n`);
+    if (process.env.BOTDOCS_DEBUG === '1' && reason instanceof Error && reason.stack) {
+        process.stderr.write(`\n${reason.stack}\n`);
+    }
+    process.exit(1);
+}
+/** Walk the error chain looking for a Node `code` (errno-style string like
+ * `ENOTFOUND`). fetch wraps DNS/connection errors twice — once in the cause
+ * chain, once as the AggregateError on dual-stack lookups — so we peek
+ * through both. */
+function extractErrorCode(reason) {
+    let cur = reason;
+    for (let depth = 0; depth < 5 && cur != null; depth++) {
+        if (typeof cur === 'object') {
+            const code = cur.code;
+            if (typeof code === 'string')
+                return code;
+            const errors = cur.errors;
+            if (Array.isArray(errors) && errors.length > 0) {
+                for (const e of errors) {
+                    const c = e?.code;
+                    if (typeof c === 'string')
+                        return c;
+                }
+            }
+            cur = cur.cause;
+        }
+        else {
+            break;
+        }
+    }
+    return undefined;
+}
+/** Map a Node network errno to a human sentence. Returns undefined for codes
+ * we don't recognize so the caller falls through to the generic message. */
+function friendlyNetworkMessage(code) {
+    switch (code) {
+        case 'ENOTFOUND':
+        case 'EAI_AGAIN':
+            return "Couldn't resolve botdocs.ai. Check your network or DNS and try again.";
+        case 'ECONNREFUSED':
+            return "Couldn't connect to botdocs.ai. The service may be down — try again in a minute.";
+        case 'ECONNRESET':
+            return 'Connection reset. Try again.';
+        case 'ETIMEDOUT':
+            return 'Request timed out. Try again.';
+        default:
+            return undefined;
+    }
+}
+function genericFriendlyMessage(reason) {
+    const msg = reason instanceof Error ? reason.message : String(reason);
+    return `Unexpected error: ${msg}. Please file an issue at https://github.com/trev91/Botdocs/issues`;
+}
 import { Command } from 'commander';
+import { checkAuthFilePerms } from './lib/config.js';
 import { search } from './commands/search.js';
 import { publish } from './commands/publish.js';
 import { unpublish } from './commands/unpublish.js';
@@ -21,8 +131,29 @@ import { registerTeamCommands } from './commands/team.js';
 import { registerBackupCommands } from './commands/backups.js';
 import { undo } from './commands/undo.js';
 import { createRequire } from 'node:module';
+// WaitlistError is re-checked inside handleFatal() (via lazy require) so we
+// don't need a static import here — keeping the import surface minimal also
+// means the top-of-file Node-version preflight can't be defeated by an
+// import-time crash in api.js on an unsupported runtime.
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
+// NOTE: The previous `unhandledRejection` handler that only special-cased
+// WaitlistError has been replaced by the top-of-file `handleFatal` plumbing,
+// which covers waitlist, friendly network-error codes, and the generic
+// "please file an issue" fallback in one place.
+// P1-G: One-time migration check. If auth.json was written by a pre-hardening
+// CLI (default umask 022 → mode 0644 / world-readable), tighten it in place
+// and warn the user once. Non-fatal: a chmod failure or anything weird here
+// shouldn't block the CLI from running.
+try {
+    const permsCheck = checkAuthFilePerms();
+    if (permsCheck.warning) {
+        process.stderr.write(`${permsCheck.warning}\n`);
+    }
+}
+catch {
+    // Defensive: never let a perms check crash CLI startup.
+}
 const program = new Command();
 program
     .name('botdocs')
@@ -31,10 +162,14 @@ program
     .option('--json', 'Output results as JSON');
 program
     .command('init [name]')
-    .description('Scaffold a new BotDoc directory with index.md template')
-    .option('--title <title>', 'BotDoc title')
-    .option('--category <category>', 'Category')
-    .option('--canonical', 'Scaffold a multi-ecosystem skill (claude-code source + ecosystems list)')
+    .description('Scaffold a new skill directory (canonical multi-ecosystem layout by default; pass --spec for the legacy SPEC scaffold)')
+    .option('--title <title>', 'Skill title')
+    .option('--category <category>', 'Category (SPEC scaffold only)')
+    // Canonical is the default now. The flag is kept as a no-op alias so older
+    // docs/scripts that still pass it continue to work; the action handler
+    // ignores it. Hidden from help to discourage new callers.
+    .option('--canonical', 'Deprecated no-op — canonical is the default. Pass --spec for the legacy layout.')
+    .option('--spec', 'Scaffold the legacy SPEC layout (single index.md + minimal manifest, no skill type). Most authors want the default.')
     .action(async (name, opts) => {
     await init(name, { ...opts, json: program.opts().json });
 });
@@ -59,7 +194,8 @@ program
     .option('--tags <tags>', 'Comma-separated tags')
     .option('--license <license>', 'License (MIT, CC_BY_4_0, CC_BY_SA_4_0, CC0, ALL_RIGHTS_RESERVED)')
     .option('--no-compile', 'Skip auto-compile (publish whatever files are on disk as-is)')
-    .option('--yes', 'Skip any confirmation prompt (reserved for future use)')
+    .option('--dry-run', 'Preview the publish payload (title, description, files, total size) without uploading')
+    .option('--yes', 'Skip the y/N confirmation prompt (for scripts)')
     .action(async (source, options) => {
     await publish(source, { ...options, json: program.opts().json });
 });
@@ -163,6 +299,8 @@ program
     .option('--auto', 'Skip the interactive selection and ingest everything discovery finds (zero-arg mode only)')
     .option('--force', 'Replace existing draft skills with the same name (won\'t touch published skills)')
     .option('--no-ink', 'Disable the interactive TUI; use plain output (zero-arg mode only)')
+    .option('--pair', "Pair with the web onboarding step so it can mirror this ingest live; prompts for a BD-XXXXX code")
+    .option('--pair-code <code>', 'Pre-supply the pairing code (e.g. BD-A4F8K) — skips the interactive prompt; implies --pair')
     .action(async (sourcePath, opts) => {
     // Commander's --no-ink convention sets opts.ink = false; flip to noInk
     // so downstream consumers don't have to handle the inverted boolean.
@@ -200,4 +338,12 @@ program
     const { backup, ...rest } = opts;
     await undo({ ...rest, noBackup: backup === false, json: program.opts().json });
 });
-program.parse();
+// Use parseAsync so any rejected promise from an action surfaces through the
+// try/catch into handleFatal. Without this, commander dispatches actions as
+// fire-and-forget and an action's rejection would only land in
+// `unhandledRejection` — which is fine, but the explicit catch here also
+// covers commander's own synchronous errors (unknown command, missing
+// argument, etc.) with the same friendly output path.
+program.parseAsync().catch((err) => {
+    handleFatal(err);
+});

package/dist/lib/api.d.ts

@@ -1,3 +1,8 @@
+/** Default per-request timeout (ms). Exposed so tests can override without
+ * mocking `setTimeout` globally, and so callers can read the value when
+ * composing their own friendly messages. 30 s matches the longest-tolerable
+ * wait before a human assumes the CLI has hung. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
 export declare function getApiUrl(): string;
 /** Thrown by apiFetch when the server returns a non-2xx response. Carries the
  * status code and the server-provided message so callers can branch on
@@ -11,13 +16,78 @@ export declare function getApiUrl(): string;
 export declare class ApiError extends Error {
     readonly status: number;
     readonly body?: unknown;
-    constructor(status: number, message: string, body?: unknown);
+    constructor(status: number, message: string, body?: unknown, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown by apiFetch when the server replies 403 with `{ error: 'waitlisted',
+ * ... }` — meaning the caller is signed in but BotDocs is currently behind the
+ * waitlist gate and they haven't been admitted yet.
+ *
+ * Subclass of ApiError so existing `catch (err) { if (err instanceof ApiError)
+ * ... }` paths keep working; the index.ts top-level handler does an explicit
+ * `instanceof WaitlistError` check first to print a single friendly one-liner
+ * and exit 0 (this is not a user-facing error condition — the user is on the
+ * waitlist by design).
+ *
+ * Telemetry-style callers (`syncLibrary`) that already swallow errors will
+ * continue to swallow this one too — they catch every ApiError, so the new
+ * class lands inside the same catch arm.
+ */
+export declare class WaitlistError extends ApiError {
+    constructor(message: string, body?: unknown);
 }
 interface FetchOptions {
     method?: string;
     body?: unknown;
     auth?: boolean;
+    /** Per-call override of the default request timeout (ms). When the timer
+     * fires we abort the underlying fetch and throw an ApiError(0, "timed out…").
+     * Defaults to {@link DEFAULT_TIMEOUT_MS}. Set higher for known-slow paths
+     * (e.g. large uploads) or lower in tests to keep the suite snappy. */
+    timeoutMs?: number;
 }
+/** Make an HTTP call to the BotDocs API with a hard timeout and friendly
+ * error normalization.
+ *
+ * Network failures (DNS, ECONNREFUSED, socket reset, abort) are converted to
+ * `ApiError(0, ...)` so command-level handlers that already branch on
+ * `err instanceof ApiError` print a clean one-liner instead of leaking a Node
+ * stack trace. The `status === 0` sentinel lets callers tell network failure
+ * apart from a real HTTP error.
+ *
+ * Non-2xx HTTP responses still throw `ApiError(status, message, body)` as
+ * before. */
 export declare function apiFetch<T>(path: string, options?: FetchOptions): Promise<T>;
-export declare function fetchRawContent(rawUrl: string): Promise<string>;
+/**
+ * Fetch a raw file body by URL (absolute or API-relative).
+ *
+ * Used by install/edit/sync to pull individual file contents that the
+ * registry exposes outside the JSON API (e.g. the raw markdown for a
+ * single SKILL.md). Previously this used a bare `fetch(url)` with no
+ * timeout, so a flaky network could hang any of those commands forever.
+ *
+ * Mirrors {@link apiFetch}'s AbortController + DEFAULT_TIMEOUT_MS pattern:
+ * network failures and timeouts both surface as `ApiError(0, …)` so the
+ * callers don't need to special-case fetchRawContent vs apiFetch in
+ * their `instanceof ApiError` catch arms.
+ */
+export declare function fetchRawContent(rawUrl: string, options?: {
+    timeoutMs?: number;
+}): Promise<string>;
+/** Translate an ApiError status into a short, human-readable one-liner for
+ * the "everything else" 4xx/5xx case — the cases each command doesn't already
+ * handle structurally (e.g. 401 fatal, 409 ALREADY_EXISTS, 410 with hint, 413
+ * size cap). Promoting this here (rather than duplicating it across
+ * sync/install/publish/edit) keeps the error vocabulary consistent across
+ * commands and means a single edit changes how every command surfaces
+ * "permission denied" / "rate-limited" / "server error".
+ *
+ * `ref` is optional context — when present and the status is 404, we
+ * recommend `botdocs uninstall <ref>` so the user has an immediate next
+ * action (mirrors the 410 hint in sync). 403 wording assumes the most
+ * common cause is lost team membership rather than a stale token (real
+ * stale-token cases are 401, which is handled upstream as "Authentication
+ * failed"). */
+export declare function friendlyApiErrorDetail(err: ApiError, ref?: string): string;
 export {};

package/dist/lib/api.js

@@ -1,7 +1,51 @@
 import { loadAuth } from './config.js';
 const DEFAULT_API_URL = 'https://www.botdocs.ai';
+/** Default per-request timeout (ms). Exposed so tests can override without
+ * mocking `setTimeout` globally, and so callers can read the value when
+ * composing their own friendly messages. 30 s matches the longest-tolerable
+ * wait before a human assumes the CLI has hung. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** P3 #17: localhost overrides for `BOTDOCS_API_URL` are allowed without TLS
+ * because dev servers default to `http://localhost:3000`. Anything else MUST
+ * be https — we refuse to send bearer tokens over plaintext to a non-loopback
+ * host, since a passive observer would harvest the bearer + every uploaded
+ * skill file. */
+function isLocalhostUrl(u) {
+    try {
+        const parsed = new URL(u);
+        if (parsed.protocol === 'https:')
+            return false;
+        return (parsed.hostname === 'localhost' ||
+            parsed.hostname === '127.0.0.1' ||
+            parsed.hostname === '0.0.0.0' ||
+            parsed.hostname === '[::1]');
+    }
+    catch {
+        return false;
+    }
+}
+/** Track whether we've already printed the override-warning so the CLI doesn't
+ * spam stderr across every API call in a single process run. */
+let overrideWarnPrinted = false;
 export function getApiUrl() {
-    return process.env.BOTDOCS_API_URL || DEFAULT_API_URL;
+    const override = process.env.BOTDOCS_API_URL;
+    if (!override)
+        return DEFAULT_API_URL;
+    // P3 #17: reject plaintext overrides to non-loopback hosts. A misconfigured
+    // env var pointing at `http://evil.example.com` would otherwise leak the
+    // bearer token over the wire on every API call.
+    if (!override.startsWith('https://') && !isLocalhostUrl(override)) {
+        throw new Error(`BOTDOCS_API_URL must be https:// (or http://localhost for development). ` +
+            `Got: ${override}. Refusing to send credentials over plaintext.`);
+    }
+    if (!overrideWarnPrinted) {
+        overrideWarnPrinted = true;
+        // Single line to stderr so it doesn't trash the CLI's Ink-rendered stdout.
+        if (process.stderr.isTTY) {
+            process.stderr.write(`\n  [botdocs] using BOTDOCS_API_URL=${override} (env override)\n`);
+        }
+    }
+    return override;
 }
 /** Thrown by apiFetch when the server returns a non-2xx response. Carries the
  * status code and the server-provided message so callers can branch on
@@ -15,15 +59,67 @@ export function getApiUrl() {
 export class ApiError extends Error {
     status;
     body;
-    constructor(status, message, body) {
-        super(message);
+    constructor(status, message, body, options) {
+        // Pass `cause` through to the Error super so devs running with
+        // `BOTDOCS_DEBUG=1` see the underlying network/abort error in the chain
+        // instead of just the friendly wrapper message.
+        super(message, options);
         this.name = 'ApiError';
         this.status = status;
         this.body = body;
     }
 }
+/** True when `err` looks like a fetch AbortError. Node's fetch surfaces it as
+ * a DOMException with `name === 'AbortError'`; we also accept the legacy
+ * `AbortError` Error subclass shape to be safe across Node versions. */
+function isAbortError(err) {
+    if (err == null || typeof err !== 'object')
+        return false;
+    const name = err.name;
+    return name === 'AbortError';
+}
+/** Thrown by apiFetch when the server replies 403 with `{ error: 'waitlisted',
+ * ... }` — meaning the caller is signed in but BotDocs is currently behind the
+ * waitlist gate and they haven't been admitted yet.
+ *
+ * Subclass of ApiError so existing `catch (err) { if (err instanceof ApiError)
+ * ... }` paths keep working; the index.ts top-level handler does an explicit
+ * `instanceof WaitlistError` check first to print a single friendly one-liner
+ * and exit 0 (this is not a user-facing error condition — the user is on the
+ * waitlist by design).
+ *
+ * Telemetry-style callers (`syncLibrary`) that already swallow errors will
+ * continue to swallow this one too — they catch every ApiError, so the new
+ * class lands inside the same catch arm.
+ */
+export class WaitlistError extends ApiError {
+    constructor(message, body) {
+        super(403, message, body);
+        this.name = 'WaitlistError';
+    }
+}
+/** Type guard for the `{ error: 'waitlisted', ... }` JSON shape returned by
+ * `requireAdmitted` on the web side. Matches by string discriminant so a
+ * server-side rename of the field would break this exactly once, here, rather
+ * than silently disabling the friendly path. */
+function isWaitlistedBody(body) {
+    return (typeof body === 'object' &&
+        body !== null &&
+        body.error === 'waitlisted');
+}
+/** Make an HTTP call to the BotDocs API with a hard timeout and friendly
+ * error normalization.
+ *
+ * Network failures (DNS, ECONNREFUSED, socket reset, abort) are converted to
+ * `ApiError(0, ...)` so command-level handlers that already branch on
+ * `err instanceof ApiError` print a clean one-liner instead of leaking a Node
+ * stack trace. The `status === 0` sentinel lets callers tell network failure
+ * apart from a real HTTP error.
+ *
+ * Non-2xx HTTP responses still throw `ApiError(status, message, body)` as
+ * before. */
 export async function apiFetch(path, options = {}) {
-    const { method = 'GET', body, auth = false } = options;
+    const { method = 'GET', body, auth = false, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
     const baseUrl = getApiUrl();
     const url = `${baseUrl}${path}`;
     const headers = {
@@ -42,11 +138,37 @@ export async function apiFetch(path, options = {}) {
         }
         headers['Authorization'] = `Bearer ${config.token}`;
     }
-    const response = await fetch(url, {
-        method,
-        headers,
-        body: body ? JSON.stringify(body) : undefined,
-    });
+    // AbortController + setTimeout is the lowest-overhead way to enforce a hard
+    // per-request deadline on Node's fetch — there's no built-in `timeout`
+    // option. We clear the timer in `finally` to avoid keeping the event loop
+    // alive after the request settles, which would delay process exit by up to
+    // `timeoutMs`.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        // Translate low-level network failures into the existing ApiError shape so
+        // command-level catch arms (`if (err instanceof ApiError)`) handle them
+        // without each command needing its own try/catch around `fetch`. Status 0
+        // is the sentinel for "never got a response".
+        if (isAbortError(err)) {
+            const seconds = Math.round(timeoutMs / 1000);
+            throw new ApiError(0, `Request to ${baseUrl} timed out after ${seconds}s — check your network and try again.`, undefined, { cause: err });
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ApiError(0, `Network error contacting ${baseUrl}: ${message}`, undefined, { cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
     if (!response.ok) {
         const text = await response.text();
         let message;
@@ -67,6 +189,13 @@ export async function apiFetch(path, options = {}) {
         if (response.status === 401 && auth) {
             message = 'Authentication failed. Run `botdocs login` to sign in again.';
         }
+        // Distinct error type for the launch-day waitlist. Lets the top-level
+        // CLI handler print "You're on the BotDocs waitlist..." instead of a raw
+        // 403 trace, and lets background telemetry (syncLibrary) silently swallow
+        // it without surfacing anything to the user.
+        if (response.status === 403 && isWaitlistedBody(parsedBody)) {
+            throw new WaitlistError(parsedBody.message ?? message, parsedBody);
+        }
         throw new ApiError(response.status, message, parsedBody);
     }
     const contentType = response.headers.get('content-type') || '';
@@ -75,12 +204,76 @@ export async function apiFetch(path, options = {}) {
     }
     return (await response.text());
 }
-export async function fetchRawContent(rawUrl) {
+/**
+ * Fetch a raw file body by URL (absolute or API-relative).
+ *
+ * Used by install/edit/sync to pull individual file contents that the
+ * registry exposes outside the JSON API (e.g. the raw markdown for a
+ * single SKILL.md). Previously this used a bare `fetch(url)` with no
+ * timeout, so a flaky network could hang any of those commands forever.
+ *
+ * Mirrors {@link apiFetch}'s AbortController + DEFAULT_TIMEOUT_MS pattern:
+ * network failures and timeouts both surface as `ApiError(0, …)` so the
+ * callers don't need to special-case fetchRawContent vs apiFetch in
+ * their `instanceof ApiError` catch arms.
+ */
+export async function fetchRawContent(rawUrl, options = {}) {
+    const { timeoutMs = DEFAULT_TIMEOUT_MS } = options;
     const baseUrl = getApiUrl();
     const url = rawUrl.startsWith('http') ? rawUrl : `${baseUrl}${rawUrl}`;
-    const response = await fetch(url);
+    // Same pattern as apiFetch — AbortController + clearTimeout in finally so
+    // the timer never outlives the request and blocks process exit.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetch(url, { signal: controller.signal });
+    }
+    catch (err) {
+        if (isAbortError(err)) {
+            const seconds = Math.round(timeoutMs / 1000);
+            throw new ApiError(0, `Request to ${baseUrl} timed out after ${seconds}s — check your network and try again.`, undefined, { cause: err });
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ApiError(0, `Network error contacting ${baseUrl}: ${message}`, undefined, { cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
     if (!response.ok) {
         throw new ApiError(response.status, `Failed to fetch ${rawUrl}`);
     }
     return await response.text();
 }
+/** Translate an ApiError status into a short, human-readable one-liner for
+ * the "everything else" 4xx/5xx case — the cases each command doesn't already
+ * handle structurally (e.g. 401 fatal, 409 ALREADY_EXISTS, 410 with hint, 413
+ * size cap). Promoting this here (rather than duplicating it across
+ * sync/install/publish/edit) keeps the error vocabulary consistent across
+ * commands and means a single edit changes how every command surfaces
+ * "permission denied" / "rate-limited" / "server error".
+ *
+ * `ref` is optional context — when present and the status is 404, we
+ * recommend `botdocs uninstall <ref>` so the user has an immediate next
+ * action (mirrors the 410 hint in sync). 403 wording assumes the most
+ * common cause is lost team membership rather than a stale token (real
+ * stale-token cases are 401, which is handled upstream as "Authentication
+ * failed"). */
+export function friendlyApiErrorDetail(err, ref) {
+    if (err.status === 403) {
+        return 'permission denied — you may have lost access to this skill (e.g. removed from a team). Contact the owner.';
+    }
+    if (err.status === 404) {
+        if (ref)
+            return `no longer found — run \`botdocs uninstall ${ref}\` to clean up.`;
+        return 'no longer found';
+    }
+    if (err.status === 429)
+        return 'rate-limited — try again in a moment';
+    if (err.status >= 500 && err.status < 600) {
+        return err.message ? `server error: ${err.message}` : 'server error';
+    }
+    if (err.message)
+        return err.message;
+    return `request failed (${err.status})`;
+}