@botdocs/cli 0.5.0 → 0.8.0

package/dist/commands/publish.d.ts

@@ -6,6 +6,34 @@ interface PublishOptions {
     license?: string;
     json?: boolean;
     noCompile?: boolean;
+    /** Skip confirmation prompts. Reserved for future use — publish on a
+     * ref currently doesn't prompt, but the flag is accepted so users
+     * developing scripts get a consistent surface across publish/unpublish. */
+    yes?: boolean;
 }
 export declare function publish(source: string, options: PublishOptions): Promise<void>;
-export {};
+/**
+ * Toggle an existing BotDoc from draft → published via the API.
+ *
+ * Called from `publish()` when the source argument looks like a ref
+ * (`@user/slug` or `user/slug`) instead of a local path. Strips the
+ * `draft` and `ingest:<id>` tags server-side. No prompt — moving from
+ * draft to published is the natural progression, and unpublishing a
+ * mistake is one CLI call away.
+ */
+declare function publishRef(rawRef: string, options: PublishOptions): Promise<void>;
+/**
+ * Map an `ApiError` from a publish/unpublish call to a friendly,
+ * actionable message. Shared by both verbs so the wording stays in sync.
+ *
+ * 401: most likely the user isn't logged in (or their saved token is
+ * stale). The api lib already produces a helpful "run `botdocs login`"
+ * hint — pass it through.
+ *
+ * 403: authenticated as someone who doesn't own this BotDoc.
+ *
+ * 404: BotDoc doesn't exist (or is owned by a different user — the API
+ * returns 404 rather than 403 to avoid leaking existence to non-authors).
+ */
+declare function handlePublishToggleError(err: unknown, refLabel: string, options: PublishOptions): void;
+export { publishRef, handlePublishToggleError };

package/dist/commands/publish.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import AdmZip from 'adm-zip';
-import { apiFetch } from '../lib/api.js';
+import { ApiError, apiFetch } from '../lib/api.js';
 import { parseManifest } from '../lib/manifest.js';
 import { compile } from './compile.js';
 import { ecosystemDestination } from '../lib/canonical.js';
+import { isRefForm, parseRef } from '../lib/ref.js';
 const VALID_CATEGORIES = [
     'KNOWLEDGE_MANAGEMENT',
     'DEV_WORKFLOW',
@@ -15,6 +16,16 @@ const VALID_CATEGORIES = [
 ];
 const VALID_LICENSES = ['MIT', 'CC_BY_4_0', 'CC_BY_SA_4_0', 'CC0', 'ALL_RIGHTS_RESERVED'];
 export async function publish(source, options) {
+    // Ref-form (e.g. "@user/slug" or "user/slug") → toggle the published
+    // flag via the API. Path-form continues to the existing upload flow
+    // below. Overloading by argument shape (rather than introducing
+    // `botdocs publish-ref` or a `--ref` flag) keeps the verb intuitive:
+    // a user typing `botdocs publish @me/foo` doesn't have to know it's a
+    // different code path under the hood.
+    if (isRefForm(source)) {
+        await publishRef(source, options);
+        return;
+    }
     const resolved = path.resolve(source);
     if (!fs.existsSync(resolved)) {
         console.error(`Source not found: ${source}`);
@@ -92,6 +103,79 @@ export async function publish(source, options) {
         console.log(`\nPublished: ${result.url}`);
     }
 }
+/**
+ * Toggle an existing BotDoc from draft → published via the API.
+ *
+ * Called from `publish()` when the source argument looks like a ref
+ * (`@user/slug` or `user/slug`) instead of a local path. Strips the
+ * `draft` and `ingest:<id>` tags server-side. No prompt — moving from
+ * draft to published is the natural progression, and unpublishing a
+ * mistake is one CLI call away.
+ */
+async function publishRef(rawRef, options) {
+    let parsed;
+    try {
+        parsed = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    const { username, slug } = parsed;
+    const refLabel = `@${username}/${slug}`;
+    try {
+        await apiFetch(`/api/botdocs/${username}/${slug}/publish`, {
+            method: 'POST',
+            auth: true,
+        });
+    }
+    catch (err) {
+        handlePublishToggleError(err, refLabel, options);
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'published' }));
+    }
+    else {
+        console.log(`✓ Published ${refLabel} — visible at https://botdocs.ai/${refLabel}`);
+    }
+}
+/**
+ * Map an `ApiError` from a publish/unpublish call to a friendly,
+ * actionable message. Shared by both verbs so the wording stays in sync.
+ *
+ * 401: most likely the user isn't logged in (or their saved token is
+ * stale). The api lib already produces a helpful "run `botdocs login`"
+ * hint — pass it through.
+ *
+ * 403: authenticated as someone who doesn't own this BotDoc.
+ *
+ * 404: BotDoc doesn't exist (or is owned by a different user — the API
+ * returns 404 rather than 403 to avoid leaking existence to non-authors).
+ */
+function handlePublishToggleError(err, refLabel, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, ref: refLabel, status: err.status, error: err.message }));
+        process.exit(1);
+    }
+    if (err.status === 401) {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    else if (err.status === 403) {
+        console.error(`\n  ✗ You don't own ${refLabel}.\n`);
+    }
+    else if (err.status === 404) {
+        console.error(`\n  ✗ BotDoc not found: ${refLabel}\n`);
+    }
+    else {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    process.exit(1);
+}
+export { publishRef, handlePublishToggleError };
 function readManifest(source) {
     const manifestPath = path.join(source, 'botdocs.json');
     if (!fs.existsSync(manifestPath))

package/dist/commands/unpublish.d.ts

@@ -0,0 +1,16 @@
+interface UnpublishOptions {
+    yes?: boolean;
+    json?: boolean;
+}
+/**
+ * Set the `draft` flag back on a published BotDoc, hiding it from
+ * `/explore` and 404ing the public URL for everyone except the author.
+ *
+ * Idempotent server-side — calling unpublish on something already a
+ * draft is a no-op. Prompts for confirmation by default because the
+ * effect is visible to anyone who had the URL bookmarked; skip with
+ * `--yes` for scripting/CI. `--json` implies `--yes` so machine-driven
+ * callers don't deadlock on the prompt.
+ */
+export declare function unpublish(rawRef: string, options: UnpublishOptions): Promise<void>;
+export {};

package/dist/commands/unpublish.js

@@ -0,0 +1,53 @@
+import * as p from '@clack/prompts';
+import { apiFetch } from '../lib/api.js';
+import { parseRef } from '../lib/ref.js';
+import { handlePublishToggleError } from './publish.js';
+/**
+ * Set the `draft` flag back on a published BotDoc, hiding it from
+ * `/explore` and 404ing the public URL for everyone except the author.
+ *
+ * Idempotent server-side — calling unpublish on something already a
+ * draft is a no-op. Prompts for confirmation by default because the
+ * effect is visible to anyone who had the URL bookmarked; skip with
+ * `--yes` for scripting/CI. `--json` implies `--yes` so machine-driven
+ * callers don't deadlock on the prompt.
+ */
+export async function unpublish(rawRef, options) {
+    let parsed;
+    try {
+        parsed = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    const { username, slug } = parsed;
+    const refLabel = `@${username}/${slug}`;
+    if (!options.yes && !options.json) {
+        const confirmed = await p.confirm({
+            message: `Unpublish ${refLabel}? It will be hidden from /explore and the public URL ` +
+                `will 404 for everyone except you.`,
+            initialValue: false,
+        });
+        if (p.isCancel(confirmed) || !confirmed) {
+            console.log('  Cancelled.\n');
+            return;
+        }
+    }
+    try {
+        await apiFetch(`/api/botdocs/${username}/${slug}/unpublish`, {
+            method: 'POST',
+            auth: true,
+        });
+    }
+    catch (err) {
+        handlePublishToggleError(err, refLabel, options);
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'draft' }));
+    }
+    else {
+        console.log(`✓ Unpublished ${refLabel} — now hidden from /explore.`);
+    }
+}

package/dist/commands/views/ingest-discover-app.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+import { type DiscoveredSkillFile, type DiscoveredSkillSummary, type DiscoveryEcosystem } from '../../lib/ingest-discover.js';
+/** The outcome of one TUI session. `null` selections means the user cancelled
+ * via `q`/Esc; an empty array means they hit enter with everything unchecked
+ * (the runner stays on screen — the parent never receives an empty array). */
+export type IngestDiscoverResult = {
+    kind: 'confirmed';
+    selected: DiscoveredSkillFile[];
+} | {
+    kind: 'cancelled';
+};
+export interface IngestDiscoverAppProps {
+    files: DiscoveredSkillFile[];
+    /** Per-skill aggregate stats from discovery — count, total size, sweep
+     * warnings. Keyed by `summaryKey(file)` so the row renderer can look up
+     * a skill's aggregate from the root row alone. Optional for backwards
+     * compatibility with tests that don't compute summaries. */
+    skillSummaries?: Map<string, DiscoveredSkillSummary>;
+    /** Ecosystems we scanned but found nothing for. Rendered as a single
+     * trailing "Other tools: ..." line so the user can see we looked. */
+    emptyEcosystems: DiscoveryEcosystem[];
+    /** Called with the user's choice when they confirm or cancel. The parent
+     * is responsible for unmounting on receipt. */
+    onDone: (result: IngestDiscoverResult) => void;
+}
+export declare function IngestDiscoverApp(props: IngestDiscoverAppProps): React.ReactElement;

package/dist/commands/views/ingest-discover-app.js

@@ -0,0 +1,186 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from 'react';
+import { Box, Text, useApp, useInput } from 'ink';
+import { theme } from './theme.js';
+import { ecosystemLabel, formatBytes, STUB_BYTE_THRESHOLD, summaryKey, } from '../../lib/ingest-discover.js';
+/** A file is a "root" — selectable at the skill level — if its canonical
+ * filename matches the ecosystem's root pattern. Root files are the only
+ * ones surfaced in the TUI; adjacent files (scripts/, templates/) ride
+ * along when their skill is toggled. */
+function isRootFile(file) {
+    const cf = file.canonicalFilename;
+    // claude/<slug>/SKILL.md or claude-code/agents/<slug>/AGENT.md are nested
+    // root files; everything else is flat (filename matches canonical exactly
+    // and ends with the ecosystem's primary extension).
+    if (cf.endsWith('/SKILL.md'))
+        return true;
+    if (cf.endsWith('/AGENT.md'))
+        return true;
+    // For flat ecosystems (claude-code commands, cursor rules, etc.) there's
+    // no adjacent sweep today, so every discovered file IS a root.
+    if (!cf.endsWith('/SKILL.md') && !cf.endsWith('/AGENT.md')) {
+        // Heuristic: if this file's slug + scope appears exactly once in the
+        // discovery, treat it as the root.
+        return true;
+    }
+    return false;
+}
+/** Group files by ecosystem (preserving order) and emit a flat row list with
+ * one section header per ecosystem followed by its skill rows. Empty
+ * ecosystems are surfaced separately as a trailing line, not in the row list.
+ *
+ * Only root files become rows. Adjacent files are tracked via the summary
+ * map so the row can show aggregate counts/sizes. */
+function buildRows(files, skillSummaries) {
+    const rows = [];
+    let lastEcosystem = null;
+    files.forEach((file, index) => {
+        if (!isRootFile(file))
+            return;
+        if (file.ecosystem !== lastEcosystem) {
+            rows.push({ kind: 'header', ecosystem: file.ecosystem });
+            lastEcosystem = file.ecosystem;
+        }
+        const summary = skillSummaries?.get(summaryKey(file));
+        rows.push({ kind: 'file', index, file, summary });
+    });
+    return rows;
+}
+/** Default-checked rule: a file is checked iff its OWN size is at or above
+ * STUB_BYTE_THRESHOLD. The stub filter looks at the root file's size only
+ * — a SKILL.md stub + heavy scripts/ should NOT pass (the user hasn't
+ * filled in the spec), but a SKILL.md with real content + small scripts
+ * should. Returned as a Set of indices for O(1) toggle. */
+function defaultChecked(files) {
+    const out = new Set();
+    files.forEach((f, i) => {
+        if (!isRootFile(f))
+            return;
+        if (f.sizeBytes >= STUB_BYTE_THRESHOLD)
+            out.add(i);
+    });
+    return out;
+}
+/** Find the first selectable (file) row in the flattened list. Used to seed
+ * the cursor — we never park it on a header. */
+function firstSelectableIndex(rows) {
+    return rows.findIndex((r) => r.kind === 'file');
+}
+/** Move the cursor by `delta` (±1) and skip past header rows. Caller guarantees
+ * `rows` contains at least one file row. */
+function moveCursor(rows, current, delta) {
+    const max = rows.length - 1;
+    let next = current + delta;
+    while (next >= 0 && next <= max) {
+        if (rows[next]?.kind === 'file')
+            return next;
+        next += delta;
+    }
+    // Off the end — stay where we were.
+    return current;
+}
+/** Build the "details" suffix shown to the right of a row label. For a
+ * multi-file skill we report aggregate count + size (`12.4 KB · 4 files`);
+ * for a single-file skill we keep the legacy `<size> · <lines> lines` so
+ * existing plain-text snapshots still parse. */
+function detailsFor(file, summary) {
+    if (summary && summary.totalFiles > 1) {
+        return `${formatBytes(summary.totalBytes)} · ${summary.totalFiles} files`;
+    }
+    return `${formatBytes(file.sizeBytes)} · ${file.lineCount} lines`;
+}
+/** Render a single file row. The checkbox uses `[x]`/`[ ]` so the output is
+ * legible in plain-text snapshots; the active row gets a leading `▶`. */
+function FileRow({ file, summary, checked, active, }) {
+    const label = file.scope ? `${file.scope}/${file.slug}` : file.slug;
+    const details = detailsFor(file, summary);
+    return (_jsxs(Box, { children: [_jsx(Box, { width: 2, children: _jsx(Text, { color: active ? theme.cyan : undefined, children: active ? '▶' : ' ' }) }), _jsxs(Text, { color: active ? theme.cyan : undefined, children: [checked ? '[x] ' : '[ ] ', label] }), _jsx(Text, { color: theme.zinc, children: `   ${details}` })] }));
+}
+export function IngestDiscoverApp(props) {
+    const { files, emptyEcosystems, onDone, skillSummaries } = props;
+    const { exit } = useApp();
+    const rows = useMemo(() => buildRows(files, skillSummaries), [files, skillSummaries]);
+    const [cursor, setCursor] = useState(() => firstSelectableIndex(rows));
+    const [checked, setChecked] = useState(() => defaultChecked(files));
+    // When the user hits enter with zero selections we don't unmount — we just
+    // surface a hint and let them keep toggling. This flag drives that hint.
+    const [emptyConfirm, setEmptyConfirm] = useState(false);
+    useInput((input, key) => {
+        if (key.upArrow) {
+            setCursor((c) => moveCursor(rows, c, -1));
+            return;
+        }
+        if (key.downArrow) {
+            setCursor((c) => moveCursor(rows, c, 1));
+            return;
+        }
+        if (input === ' ') {
+            const row = rows[cursor];
+            if (row?.kind !== 'file')
+                return;
+            const next = new Set(checked);
+            if (next.has(row.index))
+                next.delete(row.index);
+            else
+                next.add(row.index);
+            setChecked(next);
+            setEmptyConfirm(false);
+            return;
+        }
+        if (input === 'a' || input === 'A') {
+            const next = new Set();
+            // Only root rows are selectable — match the same gate buildRows uses.
+            files.forEach((f, i) => {
+                if (isRootFile(f))
+                    next.add(i);
+            });
+            setChecked(next);
+            setEmptyConfirm(false);
+            return;
+        }
+        if (input === 'n' || input === 'N') {
+            setChecked(new Set());
+            return;
+        }
+        if (key.return) {
+            if (checked.size === 0) {
+                setEmptyConfirm(true);
+                return;
+            }
+            // Each checked index points at a ROOT row. Expand to the full skill —
+            // every file with the same ecosystem + scope + slug rides along.
+            const selectedKeys = new Set();
+            for (const i of checked) {
+                const f = files[i];
+                if (!f)
+                    continue;
+                selectedKeys.add(summaryKey(f));
+            }
+            const selected = files.filter((f) => selectedKeys.has(summaryKey(f)));
+            onDone({ kind: 'confirmed', selected });
+            exit();
+            return;
+        }
+        if (input === 'q' || input === 'Q' || key.escape) {
+            onDone({ kind: 'cancelled' });
+            exit();
+            return;
+        }
+    });
+    // Empty discovery — render a helpful empty state and exit on any key. This
+    // is reachable when discovery returned files but they were all filtered out
+    // somehow (defensive — the caller currently bails before mounting us).
+    if (files.length === 0) {
+        return (_jsx(Box, { flexDirection: "column", paddingX: 1, paddingY: 1, children: _jsx(Text, { children: "No skills found in any known location." }) }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, paddingY: 1, children: [_jsx(Text, { bold: true, color: theme.cyan, children: "BotDocs ingest" }), _jsxs(Text, { color: theme.zinc, children: ["Found ", files.length, " skill", files.length === 1 ? '' : 's', " across", ' ', countEcosystems(files), " tool", countEcosystems(files) === 1 ? '' : 's', ":"] }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: rows.map((row, i) => {
+                    if (row.kind === 'header') {
+                        return (_jsx(Box, { marginTop: i === 0 ? 0 : 1, children: _jsxs(Text, { bold: true, color: theme.violet, children: [ecosystemLabel(row.ecosystem), ":"] }) }, `h-${row.ecosystem}`));
+                    }
+                    return (_jsx(FileRow, { file: row.file, summary: row.summary, checked: checked.has(row.index), active: i === cursor }, `f-${row.index}`));
+                }) }), emptyEcosystems.length > 0 ? (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: theme.zinc, children: ["Other tools: 0 skills found (", emptyEcosystems.map(ecosystemLabel).join(', '), ")"] }) })) : null, emptyConfirm ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: theme.amber, children: "Nothing selected. Use space to toggle, then enter." }) })) : null, _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: theme.zinc, children: "\u2191/\u2193 navigate \u00B7 space toggle \u00B7 a select all \u00B7 n select none \u00B7 enter confirm \u00B7 q cancel" }) })] }));
+}
+/** Count distinct ecosystems in the discovery — used in the header line. */
+function countEcosystems(files) {
+    return new Set(files.map((f) => f.ecosystem)).size;
+}

package/dist/index.js

@@ -2,6 +2,8 @@
 import { Command } from 'commander';
 import { search } from './commands/search.js';
 import { publish } from './commands/publish.js';
+import { unpublish } from './commands/unpublish.js';
+import { delete_ as deleteCmd } from './commands/delete.js';
 import { login } from './commands/login.js';
 import { whoami } from './commands/whoami.js';
 import { init } from './commands/init.js';
@@ -50,16 +52,31 @@ program
 });
 program
     .command('publish <source>')
-    .description('Publish a BotDoc from a file, directory, or zip archive')
+    .description('Publish a BotDoc — pass a local path to upload, or @user/slug to mark an existing draft live')
     .option('--title <title>', 'BotDoc title')
     .option('--description <description>', 'BotDoc description')
     .option('--category <category>', 'Category (knowledge_management, dev_workflow, automation, agent_config, project_scaffold, other)')
     .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)')
     .action(async (source, options) => {
     await publish(source, { ...options, json: program.opts().json });
 });
+program
+    .command('unpublish <ref>')
+    .description('Hide a published BotDoc from /explore (sets the draft flag back)')
+    .option('--yes', 'Skip the confirmation prompt')
+    .action(async (ref, options) => {
+    await unpublish(ref, { ...options, json: program.opts().json });
+});
+program
+    .command('delete <ref>')
+    .description('Delete a BotDoc — drafts are hard-deleted with cascade; published BotDocs are soft-deleted (hidden, version history preserved)')
+    .option('--yes', 'Skip the confirmation prompt')
+    .action(async (ref, options) => {
+    await deleteCmd(ref, { ...options, json: program.opts().json });
+});
 program
     .command('login')
     .description('Authenticate by opening your browser; or pass --token for non-interactive use')
@@ -137,13 +154,18 @@ program
     await checkUpdates({ ...opts, json: program.opts().json });
 });
 program
-    .command('ingest <path>')
-    .description('Walk a directory of existing skill files and create drafts in your BotDocs account for review')
+    .command('ingest [path]')
+    .description('Scan your system for skills and ingest them as drafts (or ingest a specific directory)')
     .option('--bundle <name>', 'Group all detected skills into a single bundle draft')
-    .option('--dry-run', 'Show what would be detected without uploading')
+    .option('--dry-run', 'Show what would be ingested without uploading')
     .option('--from-tool <ecosystem>', `Treat every file in the path as belonging to a single ecosystem (one of: ${INGEST_SUPPORTED_TOOLS.join(', ')}). Useful when ingesting directly from ~/.claude/commands/, .cursor/rules/, etc.`)
+    .option('--auto', 'Skip the interactive selection and ingest everything discovery finds (zero-arg mode only)')
+    .option('--no-ink', 'Disable the interactive TUI; use plain output (zero-arg mode only)')
     .action(async (sourcePath, opts) => {
-    await ingest(sourcePath, { ...opts, json: program.opts().json });
+    // Commander's --no-ink convention sets opts.ink = false; flip to noInk
+    // so downstream consumers don't have to handle the inverted boolean.
+    const { ink, ...rest } = opts;
+    await ingest(sourcePath, { ...rest, noInk: ink === false, json: program.opts().json });
 });
 program
     .command('compile <path>')

package/dist/lib/auto-detect.js

@@ -6,6 +6,8 @@ export function detectDestination(srcRelative, ctx) {
         const remainder = src.slice('claude/'.length);
         // claude/SKILL.md → keep the leaf filename
         // claude/<inner>/SKILL.md → strip the inner-name segment, keep the leaf
+        // claude/<inner>/scripts/helper.sh → strip the inner-name, keep the
+        //   relpath (`scripts/helper.sh`) so adjacent files land in subdirs.
         const finalName = remainder.includes('/')
             ? remainder.replace(/^[^/]+\//, '')
             : remainder;
@@ -15,6 +17,23 @@ export function detectDestination(srcRelative, ctx) {
             dest: path.join(ctx.homeDir, '.claude', 'skills', skillPath, finalName),
         };
     }
+    if (src.startsWith('claude-code/agents/')) {
+        // Layout mirrors claude skills:
+        //   claude-code/agents/<slug>/AGENT.md            → .claude/agents/<slug>/AGENT.md
+        //   claude-code/agents/<slug>/scripts/helper.sh   → .claude/agents/<slug>/scripts/helper.sh
+        // Strip the `claude-code/agents/<slug>/` prefix to get the relpath, then
+        // join under the project's `.claude/agents/<slug>/` dir. Single-file
+        // agents (no nested layout) still work via the same code path because
+        // the strip below leaves them with the bare filename.
+        const remainder = src.slice('claude-code/agents/'.length);
+        const finalName = remainder.includes('/')
+            ? remainder.replace(/^[^/]+\//, '')
+            : remainder;
+        return {
+            kind: 'project',
+            dest: path.join(ctx.projectDir, '.claude', 'agents', ctx.slug, finalName),
+        };
+    }
     if (src.startsWith('claude-code/commands/')) {
         return {
             kind: 'project',

package/dist/lib/ingest-discover.d.ts

@@ -0,0 +1,128 @@
+import { formatSweepWarnings, type AdjacentSweepWarning } from '../commands/ingest.js';
+/** The set of ecosystems discovery can find on-disk. ChatGPT is intentionally
+ * omitted — it has no canonical install location (manual-paste in the install
+ * flow). The string identifiers mirror the canonical-path prefixes used by
+ * the publish/install machinery so converting back is a string operation. */
+export type DiscoveryEcosystem = 'claude-code' | 'claude-code-agents' | 'claude' | 'cursor' | 'codex' | 'copilot' | 'windsurf' | 'gemini' | 'antigravity' | 'opencode';
+export interface DiscoveredSkillFile {
+    /** The ecosystem this file was discovered under. Drives canonical-filename
+     * mapping when we POST to /api/cli/ingest. */
+    ecosystem: DiscoveryEcosystem;
+    /** Absolute path on disk. */
+    sourcePath: string;
+    /** Slug derived from the filename (ext stripped, dir-extracted for nested
+     * SKILL.md). For `~/.claude/skills/<scope>/<slug>/SKILL.md`, the slug is
+     * `<slug>` (the leaf directory). */
+    slug: string;
+    /** Optional scope segment for nested ecosystems (currently only
+     * `claude` SKILL.md trees — `~/.claude/skills/<scope>/<slug>/SKILL.md`). */
+    scope?: string;
+    /** First H1 from the file contents, or a Title-Cased slug fallback. */
+    title: string;
+    /** File size in bytes. Used to default-uncheck tiny stub files. For the
+     * root file (SKILL.md / AGENT.md / a flat .md) this is the file's own size
+     * — NOT a sum across the skill. The stub filter must look at the root
+     * size, not adjacent files, so a SKILL.md stub + heavy scripts doesn't
+     * sneak past as "real content". */
+    sizeBytes: number;
+    /** Line count of the file contents. Surfaced in the TUI alongside size. */
+    lineCount: number;
+    /** Raw file contents, kept in memory through the upload step. */
+    content: string;
+    /** POSIX permission triple captured from `fs.statSync`. Defaults to 0o644
+     * when stat fails. Restored on `botdocs install` so executable bits on
+     * adjacent files (scripts/*.sh, etc.) survive the round-trip. */
+    mode: number;
+    /** Canonical filename for the upload payload — e.g.
+     * `claude-code/commands/foo.md`, `claude/<slug>/SKILL.md`, etc. */
+    canonicalFilename: string;
+}
+/** Per-skill aggregate stats produced by discovery — surfaced in the TUI and
+ * the plain-text fallback so the user can see how big a skill is before
+ * confirming the upload. */
+export interface DiscoveredSkillSummary {
+    ecosystem: DiscoveryEcosystem;
+    scope?: string;
+    slug: string;
+    totalFiles: number;
+    /** Sum of `sizeBytes` across every file in the skill. */
+    totalBytes: number;
+    /** Sweep warnings (binary skip, oversize, cap hit). Empty when none. */
+    warnings: AdjacentSweepWarning[];
+}
+/** One row in the per-ecosystem scan table. Each row describes a single
+ * absolute directory to scan + how to convert each discovered file into a
+ * `DiscoveredSkillFile`. Derived from the shared `DETECTORS` table — see
+ * `buildDetectors` below for the fan-out logic. */
+export interface DetectorRow {
+    ecosystem: DiscoveryEcosystem;
+    /** `'global'` paths live under HOME and always scan regardless of repo
+     * state; `'project'` paths live under CWD and only appear when CWD is a git
+     * repo (since they're per-repo settings). */
+    kind: 'global' | 'project';
+    /** Absolute directory to scan. */
+    dir: string;
+    /** When true, walk the directory tree recursively (used for claude skills
+     * which live one or two scope-segments deep). When false, only direct
+     * children are considered. Mirrors `DETECTORS.<ecosystem>.nested`. */
+    recursive: boolean;
+}
+/** Tiny H1 extractor — the same regex `ingest.ts` uses today. Falls back to a
+ * Title-Cased slug when no H1 is present. */
+export declare function titleFromContent(content: string, slug: string): string;
+/** Walk up from `start` looking for a `.git` directory. Returns true if any
+ * ancestor is a git repo. Used to gate project-scoped scans (cursor, codex,
+ * copilot, windsurf) which only make sense for repos. */
+export declare function isGitRepo(start: string): boolean;
+/** Build the per-row scan table for a given home + cwd by fanning out the
+ * shared `DETECTORS.<ecosystem>.scanPaths()` results. Project rows are
+ * naturally absent when `cwd` is outside a git repo because each project
+ * detector returns `[]` for that case.
+ *
+ * Split out as its own exported function so tests can assert the row shape
+ * without spinning up a fixture tree on disk. */
+export declare function buildDetectors(homeDir: string, cwd: string): DetectorRow[];
+export interface DiscoveryResult {
+    /** All discovered files, flattened across ecosystems. */
+    files: DiscoveredSkillFile[];
+    /** Per-skill aggregate summary (count + size + warnings). Keyed by
+     * `<ecosystem>::<scope?>/<slug>` so multi-scope claude skills don't
+     * collide. The TUI uses this to render per-skill totals without
+     * re-summing the files array. */
+    skillSummaries: Map<string, DiscoveredSkillSummary>;
+    /** Ecosystems we attempted to scan but found nothing for. Used by the TUI
+     * to render a "Other tools: 0 skills found (...)" trailing line. */
+    emptyEcosystems: DiscoveryEcosystem[];
+    /** True when CWD is inside a git repo. The TUI uses this only for messaging
+     * — the gate itself is applied inside `buildDetectors`. */
+    inGitRepo: boolean;
+}
+/** Key for the per-skill summary map. Stays stable across discoveries so the
+ * TUI can look up a summary by row. */
+export declare function summaryKey(file: Pick<DiscoveredSkillFile, 'ecosystem' | 'scope' | 'slug'>): string;
+export interface DiscoveryOptions {
+    /** Override $HOME. Defaults to `os.homedir()`. */
+    homeDir?: string;
+    /** Override cwd. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/** Scan all known on-disk locations and return a flat list of discoveries.
+ * Reads file contents synchronously — discovery is one-shot and typically
+ * touches a handful of small files, so the simplicity wins over async sprawl.
+ *
+ * Single source of truth for which ecosystems we know about is the shared
+ * `DETECTORS` table in `commands/ingest.ts`. Each detector's `scanPaths`
+ * decides where to look on disk, `slugFor` extracts the slug, and
+ * `canonicalFilename` produces the upload-shaped filename. */
+export declare function discoverSkills(options?: DiscoveryOptions): DiscoveryResult;
+/** Re-export the warning formatter so callers (TUI, plain-text) can share
+ * one rendering. */
+export { formatSweepWarnings };
+/** Human-readable label per ecosystem for the TUI section header. */
+export declare function ecosystemLabel(ecosystem: DiscoveryEcosystem): string;
+/** Format a byte count as "0.1 KB" / "2.4 KB" etc. — matches the spec sample.
+ * Single decimal place keeps narrow rows aligned in the TUI. */
+export declare function formatBytes(n: number): string;
+/** Files smaller than this are unchecked by default (likely stub files the
+ * user hasn't filled in yet). 100 bytes ≈ a one-line H1 plus a blank line. */
+export declare const STUB_BYTE_THRESHOLD = 100;