@botdocs/cli 0.5.0 → 0.6.0

package/README.md

@@ -60,7 +60,7 @@ botdocs publish my-skill/
 | `sync [ref]` | Check installed skills/bundles for updates and apply. |
 | `uninstall <ref>` | Remove an installed skill or bundle. |
 | `list` | Show installed skills and bundles. |
-| `ingest <path>` | Walk a directory, detect existing skills, upload as drafts. |
+| `ingest [path]` | Scan your system (or a directory), detect existing skills, upload as drafts. |
 | `team list` / `show` / `create` / `add` / `remove` / `push` / `unpush` | Manage teams: shared skill libraries for your org. |
 | `undo` | Restore the most recent backup run (reversible). |
 | `backups list` / `restore` / `diff` / `clear` | Browse, restore, diff, and prune backup runs. |
@@ -316,6 +316,62 @@ The upload always uses the canonical BotDocs filename, so when someone
 else `botdocs install`s the resulting skill it lands in the right
 on-disk location.
 
+### Zero-argument discovery mode
+
+Run `botdocs ingest` (no path) and the CLI scans your machine across
+every known on-disk location for the nine supported ecosystems:
+
+- `~/.claude/commands/` and `<repo>/.claude/commands/` (Claude Code)
+- `~/.claude/skills/**/SKILL.md` (Claude skills, nested by scope)
+- `<repo>/.cursor/rules/` (Cursor)
+- `<repo>/.codex/skills/` (Codex)
+- `<repo>/.github/instructions/` (GitHub Copilot)
+- `<repo>/.codeium/windsurf-rules/` (Windsurf)
+- `~/.gemini/instructions/` (Gemini CLI)
+- `~/.gemini/antigravity/skills/` (Antigravity)
+- `~/.config/opencode/instructions/` (OpenCode)
+
+Project-scoped scans (Cursor, Codex, Copilot, Windsurf, the project
+flavor of Claude Code) only run when the current directory is inside
+a git repo.
+
+A scan opens an interactive Ink TUI sectioned by ecosystem:
+
+```text
+BotDocs ingest
+Found 7 skills across 4 tools:
+
+  Claude Code:
+    [x] scx-pr-craft           2.1 KB · 67 lines
+    [x] pr-review-craft        1.8 KB · 54 lines
+    [ ] generic-test-cmd       0.1 KB · 4 lines    ← unchecked (< 100 bytes)
+
+  Claude skills:
+    [x] code-review            4.2 KB · 142 lines
+
+  Cursor rules:
+    [x] typescript-strict      0.8 KB · 25 lines
+
+  Gemini CLI:
+    [x] research-protocol      2.4 KB · 81 lines
+
+  ↑/↓ navigate · space toggle · a select all · n select none · enter confirm · q cancel
+```
+
+Useful flags:
+
+- `--auto` — skip the TUI and upload everything discovery finds
+  (with the < 100-byte stub filter applied).
+- `--dry-run` — list what discovery found in plain text; don't upload.
+- `--json` — emit the discovery as JSON; don't upload.
+- `--no-ink` — disable the TUI on TTYs (for screen readers or simple
+  terminals). Falls back to plain-text listing without uploading;
+  combine with `--auto` if you want one-shot ingestion.
+
+When the discovery returns nothing the CLI prints a hint pointing at
+`botdocs init` (to scaffold a new skill) or `botdocs ingest <dir>`
+(to ingest from a specific path).
+
 ## Development
 
 ```bash

package/dist/commands/ingest.d.ts

@@ -2,8 +2,46 @@ interface IngestOptions {
     bundle?: string;
     dryRun?: boolean;
     json?: boolean;
+    /** Force every file in the path to belong to a single ecosystem, instead of
+     * relying on the canonical-layout auto-detect. Set via `--from-tool=<x>`. */
     fromTool?: string;
+    /** Skip the TUI and ingest everything discovery finds (with the default
+     * stub filter applied). Set via `--auto`. */
+    auto?: boolean;
+    /** Force the plain-text rendering path — disables the Ink TUI. Mirrors the
+     * `--no-ink` flag on `login` and `sync`. */
+    noInk?: boolean;
 }
+export interface EcosystemDetector {
+    /** Path prefix the file's root-relative path must start with for auto-detect mode. */
+    pathPrefix: string;
+    /** Extension suffixes the filename must match. Tested via endsWith. */
+    extensions: string[];
+    /** Whether this ecosystem uses a nested SKILL.md layout (claude) vs flat.
+     * Discovery uses this to decide whether to recurse the scan directories. */
+    nested: boolean;
+    /**
+     * Given an absolute file path and the source root, return the slug or null
+     * if the file doesn't match this ecosystem's layout (e.g. wrong nesting).
+     */
+    slugFor: (absPath: string, root: string) => string | null;
+    /** Canonical filename inside a BotDoc directory, given the slug. */
+    canonicalFilename: (slug: string) => string;
+    /**
+     * Absolute directories to scan during zero-arg discovery mode. Receives the
+     * user's home dir, the current project root (cwd), and whether the project
+     * root is inside a git repo. Project-scoped paths should return `[]` when
+     * `isGitRepo` is false. Return `[]` for ecosystems that have no canonical
+     * on-disk location (e.g. chatgpt — manual-paste only).
+     */
+    scanPaths: (homeDir: string, projectRoot: string, isGitRepo: boolean) => string[];
+}
+/**
+ * Single source of truth for ecosystem detection. New ecosystems should be
+ * added here — both auto-detect mode and future `--from-tool` mode consult
+ * this table.
+ */
+export declare const DETECTORS: Record<string, EcosystemDetector>;
 export declare const SUPPORTED_TOOLS: readonly string[];
-export declare function ingest(rootPath: string, options: IngestOptions): Promise<void>;
+export declare function ingest(rootPath: string | undefined, options: IngestOptions): Promise<void>;
 export {};

package/dist/commands/ingest.js

@@ -1,12 +1,16 @@
+import React from 'react';
 import fs from 'node:fs';
 import path from 'node:path';
+import { render } from 'ink';
 import { apiFetch } from '../lib/api.js';
+import { discoverSkills, ecosystemLabel, formatBytes, STUB_BYTE_THRESHOLD, titleFromContent, } from '../lib/ingest-discover.js';
+import { IngestDiscoverApp } from './views/ingest-discover-app.js';
 /**
  * Single source of truth for ecosystem detection. New ecosystems should be
  * added here — both auto-detect mode and future `--from-tool` mode consult
  * this table.
  */
-const DETECTORS = {
+export const DETECTORS = {
     claude: {
         pathPrefix: 'claude/',
         extensions: ['/SKILL.md'],
@@ -22,6 +26,9 @@ const DETECTORS = {
             return parts[parts.length - 2] ?? null;
         },
         canonicalFilename: (slug) => `claude/${slug}/SKILL.md`,
+        // Discovery walks ~/.claude/skills recursively — files live one or two
+        // segments deep (`<slug>/SKILL.md` or `<scope>/<slug>/SKILL.md`).
+        scanPaths: (homeDir) => [path.join(homeDir, '.claude', 'skills')],
     },
     'claude-code': {
         pathPrefix: 'claude-code/commands/',
@@ -29,6 +36,14 @@ const DETECTORS = {
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
         canonicalFilename: (slug) => `claude-code/commands/${slug}.md`,
+        // Two locations: global ~/.claude/commands always, project .claude/commands
+        // only inside a git repo (per-repo overrides).
+        scanPaths: (homeDir, projectRoot, isGitRepo) => {
+            const paths = [path.join(homeDir, '.claude', 'commands')];
+            if (isGitRepo)
+                paths.push(path.join(projectRoot, '.claude', 'commands'));
+            return paths;
+        },
     },
     cursor: {
         pathPrefix: 'cursor/rules/',
@@ -36,6 +51,7 @@ const DETECTORS = {
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.mdc$/, '') || null,
         canonicalFilename: (slug) => `cursor/rules/${slug}.mdc`,
+        scanPaths: (_homeDir, projectRoot, isGitRepo) => isGitRepo ? [path.join(projectRoot, '.cursor', 'rules')] : [],
     },
     chatgpt: {
         pathPrefix: 'chatgpt/',
@@ -43,6 +59,8 @@ const DETECTORS = {
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
         canonicalFilename: (slug) => `chatgpt/${slug}.md`,
+        // No canonical on-disk location — ChatGPT is a manual-paste ecosystem.
+        scanPaths: () => [],
     },
     codex: {
         pathPrefix: 'codex/',
@@ -50,6 +68,7 @@ const DETECTORS = {
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
         canonicalFilename: (slug) => `codex/${slug}.md`,
+        scanPaths: (_homeDir, projectRoot, isGitRepo) => isGitRepo ? [path.join(projectRoot, '.codex', 'skills')] : [],
     },
     copilot: {
         pathPrefix: 'copilot/instructions/',
@@ -58,6 +77,7 @@ const DETECTORS = {
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.instructions\.md$/, '') || null,
         canonicalFilename: (slug) => `copilot/instructions/${slug}.instructions.md`,
+        scanPaths: (_homeDir, projectRoot, isGitRepo) => isGitRepo ? [path.join(projectRoot, '.github', 'instructions')] : [],
     },
     windsurf: {
         pathPrefix: 'windsurf/rules/',
@@ -65,6 +85,7 @@ const DETECTORS = {
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
         canonicalFilename: (slug) => `windsurf/rules/${slug}.md`,
+        scanPaths: (_homeDir, projectRoot, isGitRepo) => isGitRepo ? [path.join(projectRoot, '.codeium', 'windsurf-rules')] : [],
     },
     gemini: {
         pathPrefix: 'gemini/instructions/',
@@ -72,6 +93,7 @@ const DETECTORS = {
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
         canonicalFilename: (slug) => `gemini/instructions/${slug}.md`,
+        scanPaths: (homeDir) => [path.join(homeDir, '.gemini', 'instructions')],
     },
     antigravity: {
         pathPrefix: 'antigravity/skills/',
@@ -79,6 +101,7 @@ const DETECTORS = {
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
         canonicalFilename: (slug) => `antigravity/skills/${slug}.md`,
+        scanPaths: (homeDir) => [path.join(homeDir, '.gemini', 'antigravity', 'skills')],
     },
     opencode: {
         pathPrefix: 'opencode/instructions/',
@@ -86,6 +109,7 @@ const DETECTORS = {
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
         canonicalFilename: (slug) => `opencode/instructions/${slug}.md`,
+        scanPaths: (homeDir) => [path.join(homeDir, '.config', 'opencode', 'instructions')],
     },
 };
 export const SUPPORTED_TOOLS = Object.keys(DETECTORS);
@@ -157,9 +181,155 @@ function detectFromTool(absPath, root, content, ecosystem) {
         slug,
     };
 }
-function titleFromContent(content, slug) {
-    const m = content.match(/^#\s+(.+)$/m);
-    return m?.[1]?.trim() ?? slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+/** Group a list of discovered files into the `DetectedSkill[]` shape the
+ * `/api/cli/ingest` endpoint expects. Multiple discoveries with the same slug
+ * collapse into one logical skill with multiple files — same convention as
+ * the path-based ingest path uses. */
+function groupDiscoveredIntoSkills(discovered) {
+    const grouped = new Map();
+    for (const f of discovered) {
+        if (!grouped.has(f.slug)) {
+            grouped.set(f.slug, {
+                slug: f.slug,
+                title: f.title,
+                description: '',
+                sourceEcosystem: f.ecosystem,
+                files: [],
+            });
+        }
+        grouped.get(f.slug).files.push({
+            filename: f.canonicalFilename,
+            content: f.content,
+        });
+    }
+    return [...grouped.values()];
+}
+/** POST the grouped skills to the ingest endpoint. Honors `--json` (emit raw
+ * response) and the default human-friendly "drafts created" line. Returns
+ * nothing on success. */
+async function uploadSkills(skills, options) {
+    const result = await apiFetch('/api/cli/ingest', {
+        method: 'POST',
+        auth: true,
+        body: { skills, bundle: options.bundle ? { name: options.bundle } : undefined },
+    });
+    if (options.json) {
+        console.log(JSON.stringify(result));
+        return;
+    }
+    console.log(`\n  ✓ Drafts created. Review at:\n    https://botdocs.ai${result.reviewUrl}\n`);
+}
+/** Render a sectioned plain-text listing of discoveries. Reused for both
+ * `--dry-run` output and the non-TTY fallback. */
+function printDiscoveryPlainText(discovered) {
+    const byEcosystem = new Map();
+    for (const d of discovered) {
+        const list = byEcosystem.get(d.ecosystem) ?? [];
+        list.push(d);
+        byEcosystem.set(d.ecosystem, list);
+    }
+    console.log('');
+    console.log(`  Found ${discovered.length} skill(s) across ${byEcosystem.size} tool(s):`);
+    for (const [eco, list] of byEcosystem) {
+        console.log('');
+        console.log(`  ${ecosystemLabel(eco)}:`);
+        for (const f of list) {
+            const label = f.scope ? `${f.scope}/${f.slug}` : f.slug;
+            const stub = f.sizeBytes < STUB_BYTE_THRESHOLD ? ' (stub — excluded by default)' : '';
+            console.log(`    • ${label}   ${formatBytes(f.sizeBytes)} · ${f.lineCount} lines${stub}`);
+        }
+    }
+    console.log('');
+}
+/** The zero-argument discovery entry point. Scans known on-disk locations,
+ * routes through the TUI (or its fallbacks) per the user's options + tty
+ * state, and uploads the user's selection. */
+async function ingestDiscover(options) {
+    const discovery = discoverSkills();
+    if (discovery.files.length === 0) {
+        console.log('\n  No skills found. Try `botdocs init` to scaffold a new one, or point at a path: `botdocs ingest <dir>`\n');
+        return;
+    }
+    // --json: emit the discovery shape (no TUI, no upload) so CI / scripts can
+    // consume it. Includes per-file metadata; content is omitted to keep the
+    // payload small — callers can re-run with a path to actually upload.
+    if (options.json) {
+        const payload = discovery.files.map((f) => ({
+            ecosystem: f.ecosystem,
+            slug: f.slug,
+            scope: f.scope,
+            title: f.title,
+            sourcePath: f.sourcePath,
+            sizeBytes: f.sizeBytes,
+            lineCount: f.lineCount,
+            canonicalFilename: f.canonicalFilename,
+        }));
+        console.log(JSON.stringify({ discovered: payload, emptyEcosystems: discovery.emptyEcosystems }));
+        return;
+    }
+    // --dry-run + --auto: list the FILTERED set --auto would actually upload
+    // (stubs excluded). Helps the user verify before re-running without
+    // --dry-run.
+    if (options.dryRun && options.auto) {
+        const eligible = discovery.files.filter((f) => f.sizeBytes >= STUB_BYTE_THRESHOLD);
+        printDiscoveryPlainText(eligible);
+        console.log('  --dry-run --auto: would upload the above (stubs excluded). Not uploading.\n');
+        return;
+    }
+    // --dry-run alone: list ALL discoveries in plain text, never upload, never
+    // TUI. Stubs are marked inline so the user knows they'd be excluded.
+    if (options.dryRun) {
+        printDiscoveryPlainText(discovery.files);
+        console.log('  --dry-run: not uploading.\n');
+        return;
+    }
+    // --auto: skip the TUI and upload everything matching the defaults (stubs
+    // < STUB_BYTE_THRESHOLD bytes excluded — same rule the TUI uses).
+    if (options.auto) {
+        const eligible = discovery.files.filter((f) => f.sizeBytes >= STUB_BYTE_THRESHOLD);
+        if (eligible.length === 0) {
+            console.log('\n  No skills found (all discovered files are < 100-byte stubs). Inspect with `--dry-run`.\n');
+            return;
+        }
+        const skills = groupDiscoveredIntoSkills(eligible);
+        console.log(`\n  ✓ Uploading ${skills.length} skill(s) found by discovery (--auto):`);
+        for (const s of skills)
+            console.log(`    • ${s.slug} (${s.files.length} file(s))`);
+        await uploadSkills(skills, options);
+        return;
+    }
+    const useInk = !options.noInk && Boolean(process.stdout.isTTY);
+    if (!useInk) {
+        // Non-TTY / piped / --no-ink: print plain text and exit. We deliberately
+        // do NOT upload silently here — interactive consent matters. The user
+        // can re-run with `--json` for machine-readable output or with `--auto`
+        // for one-shot mode.
+        printDiscoveryPlainText(discovery.files);
+        console.log('  Run with --json for machine-readable output, or in a real terminal for interactive selection.\n');
+        return;
+    }
+    // TUI path. The component owns the keyboard handling; we just wait for it
+    // to call `onDone`, unmount, then upload (if confirmed). The result holder
+    // is typed via the discriminated-union directly so the post-await branch
+    // narrows correctly.
+    const resultHolder = {
+        value: { kind: 'cancelled' },
+    };
+    const instance = render(React.createElement(IngestDiscoverApp, {
+        files: discovery.files,
+        emptyEcosystems: discovery.emptyEcosystems,
+        onDone: (r) => {
+            resultHolder.value = r;
+        },
+    }));
+    await instance.waitUntilExit();
+    const result = resultHolder.value;
+    if (result.kind === 'cancelled') {
+        console.log('\n  Ingest cancelled.\n');
+        return;
+    }
+    const skills = groupDiscoveredIntoSkills(result.selected);
+    await uploadSkills(skills, options);
 }
 /** Human-readable list of all canonical path prefixes for the empty-result message. */
 function ecosystemPrefixSummary() {
@@ -168,6 +338,13 @@ function ecosystemPrefixSummary() {
         .join(', ');
 }
 export async function ingest(rootPath, options) {
+    // Zero-arg dispatch: scan known on-disk locations and route through the
+    // TUI (or its fallbacks). The existing path-based code path below stays
+    // identical.
+    if (!rootPath) {
+        await ingestDiscover(options);
+        return;
+    }
     const root = path.resolve(rootPath);
     if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
         console.error(`\n  ✗ Not a directory: ${rootPath}\n`);
@@ -222,14 +399,5 @@ export async function ingest(rootPath, options) {
         console.log('\n  --dry-run: not uploading.\n');
         return;
     }
-    const result = await apiFetch('/api/cli/ingest', {
-        method: 'POST',
-        auth: true,
-        body: { skills, bundle: options.bundle ? { name: options.bundle } : undefined },
-    });
-    if (options.json) {
-        console.log(JSON.stringify(result));
-        return;
-    }
-    console.log(`\n  ✓ Drafts created. Review at:\n    https://botdocs.ai${result.reviewUrl}\n`);
+    await uploadSkills(skills, options);
 }

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

@@ -0,0 +1,21 @@
+import React from 'react';
+import { type DiscoveredSkillFile, 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[];
+    /** 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,130 @@
+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, } from '../../lib/ingest-discover.js';
+/** Group files by ecosystem (preserving order) and emit a flat row list with
+ * one section header per ecosystem followed by its files. Empty ecosystems
+ * are surfaced separately as a trailing line, not in the row list. */
+function buildRows(files) {
+    const rows = [];
+    let lastEcosystem = null;
+    files.forEach((file, index) => {
+        if (file.ecosystem !== lastEcosystem) {
+            rows.push({ kind: 'header', ecosystem: file.ecosystem });
+            lastEcosystem = file.ecosystem;
+        }
+        rows.push({ kind: 'file', index, file });
+    });
+    return rows;
+}
+/** Default-checked rule: a file is checked iff it's >= STUB_BYTE_THRESHOLD.
+ * Returned as a Set of indices for O(1) toggle. */
+function defaultChecked(files) {
+    const out = new Set();
+    files.forEach((f, i) => {
+        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;
+}
+/** 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, checked, active, }) {
+    const label = file.scope ? `${file.scope}/${file.slug}` : file.slug;
+    const details = `${formatBytes(file.sizeBytes)} · ${file.lineCount} lines`;
+    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 } = props;
+    const { exit } = useApp();
+    const rows = useMemo(() => buildRows(files), [files]);
+    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();
+            files.forEach((_, i) => 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;
+            }
+            const selected = files.filter((_, i) => checked.has(i));
+            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, 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

@@ -137,13 +137,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/ingest-discover.d.ts

@@ -0,0 +1,95 @@
+/** 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' | '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. */
+    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;
+    /** Canonical filename for the upload payload — e.g.
+     * `claude-code/commands/foo.md`, `claude/<slug>/SKILL.md`, etc. */
+    canonicalFilename: string;
+}
+/** 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[];
+    /** 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;
+}
+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;
+/** 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;

package/dist/lib/ingest-discover.js

@@ -0,0 +1,207 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DETECTORS } from '../commands/ingest.js';
+/** Tiny H1 extractor — the same regex `ingest.ts` uses today. Falls back to a
+ * Title-Cased slug when no H1 is present. */
+export function titleFromContent(content, slug) {
+    const m = content.match(/^#\s+(.+)$/m);
+    return m?.[1]?.trim() ?? slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/** 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 function isGitRepo(start) {
+    let dir = start;
+    // Guard against an infinite loop on platforms where dirname(/) === /
+    for (let i = 0; i < 64; i++) {
+        const candidate = path.join(dir, '.git');
+        try {
+            if (fs.existsSync(candidate))
+                return true;
+        }
+        catch {
+            // Permission denied on some ancestor — treat as not-a-repo and keep walking
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+    return false;
+}
+/** 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 function buildDetectors(homeDir, cwd) {
+    const inRepo = isGitRepo(cwd);
+    const rows = [];
+    for (const [ecosystem, detector] of Object.entries(DETECTORS)) {
+        const paths = detector.scanPaths(homeDir, cwd, inRepo);
+        if (paths.length === 0)
+            continue;
+        // Anything under homeDir is "global"; anything else is "project". This
+        // mirrors how each detector's scanPaths was authored — global paths use
+        // homeDir, project paths use projectRoot.
+        for (const dir of paths) {
+            const kind = dir.startsWith(homeDir) ? 'global' : 'project';
+            rows.push({
+                ecosystem: ecosystem,
+                kind,
+                dir,
+                recursive: detector.nested,
+            });
+        }
+    }
+    return rows;
+}
+/** Recursively walk a directory collecting absolute paths. Returns an empty
+ * list if the directory doesn't exist. Caller decides how to filter results. */
+function walkAll(dir, recursive) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!recursive)
+                continue;
+            // Recurse but skip noisy dirs (node_modules etc. are unlikely under tool
+            // config trees but cheap to defend against).
+            if (entry.name === 'node_modules' || entry.name === '.git')
+                continue;
+            out.push(...walkAll(abs, true));
+        }
+        else if (entry.isFile()) {
+            out.push(abs);
+        }
+    }
+    return out;
+}
+/** For nested ecosystems, the scope is the directory segment immediately
+ * under the scan directory that contains the slug directory. For unscoped
+ * layouts (`<scanDir>/<slug>/SKILL.md`), the parent of the slug dir IS the
+ * scan dir and there's no scope. Returns undefined when no scope applies. */
+function scopeForNested(absPath, scanDir) {
+    // absPath looks like `<scanDir>/.../<scope?>/<slug>/SKILL.md`. The slug dir
+    // is the parent; the scope dir (if any) is the grandparent.
+    const slugDir = path.dirname(absPath);
+    const candidateScopeDir = path.dirname(slugDir);
+    if (candidateScopeDir === scanDir)
+        return undefined;
+    return path.basename(candidateScopeDir);
+}
+/** 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 function discoverSkills(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const cwd = options.cwd ?? process.cwd();
+    const rows = buildDetectors(homeDir, cwd);
+    const files = [];
+    const seen = new Set();
+    const empty = new Set();
+    for (const row of rows) {
+        const detector = DETECTORS[row.ecosystem];
+        const candidates = walkAll(row.dir, row.recursive);
+        // Filter to files this detector would accept. We pass the scan dir as the
+        // "root" so `slugFor` can do path-relative work — same convention the
+        // path-based ingest path uses, with `scanDir` standing in for the source
+        // tree root.
+        const matched = candidates.filter((abs) => detector.extensions.some((ext) => abs.endsWith(ext)));
+        if (matched.length === 0) {
+            if (!seen.has(row.ecosystem))
+                empty.add(row.ecosystem);
+            continue;
+        }
+        for (const abs of matched) {
+            const slug = detector.slugFor(abs, row.dir);
+            if (!slug)
+                continue;
+            let content;
+            try {
+                content = fs.readFileSync(abs, 'utf-8');
+            }
+            catch {
+                // Unreadable file — skip silently. Discovery should never throw on
+                // permission errors; users with unusual setups still get the rest.
+                continue;
+            }
+            const scope = detector.nested ? scopeForNested(abs, row.dir) : undefined;
+            const sizeBytes = Buffer.byteLength(content, 'utf-8');
+            const lineCount = content.length === 0 ? 0 : content.split(/\r?\n/).length;
+            files.push({
+                ecosystem: row.ecosystem,
+                sourcePath: abs,
+                slug,
+                scope,
+                title: titleFromContent(content, slug),
+                sizeBytes,
+                lineCount,
+                content,
+                canonicalFilename: detector.canonicalFilename(slug),
+            });
+            seen.add(row.ecosystem);
+            empty.delete(row.ecosystem);
+        }
+    }
+    // Sort stable: by ecosystem, then by display label (scope/slug) so the TUI
+    // and dry-run output are deterministic across runs.
+    files.sort((a, b) => {
+        if (a.ecosystem !== b.ecosystem)
+            return a.ecosystem.localeCompare(b.ecosystem);
+        const aLabel = a.scope ? `${a.scope}/${a.slug}` : a.slug;
+        const bLabel = b.scope ? `${b.scope}/${b.slug}` : b.slug;
+        return aLabel.localeCompare(bLabel);
+    });
+    return {
+        files,
+        emptyEcosystems: [...empty].sort(),
+        inGitRepo: isGitRepo(cwd),
+    };
+}
+/** Human-readable label per ecosystem for the TUI section header. */
+export function ecosystemLabel(ecosystem) {
+    switch (ecosystem) {
+        case 'claude-code':
+            return 'Claude Code';
+        case 'claude':
+            return 'Claude skills';
+        case 'cursor':
+            return 'Cursor rules';
+        case 'codex':
+            return 'Codex';
+        case 'copilot':
+            return 'GitHub Copilot';
+        case 'windsurf':
+            return 'Windsurf';
+        case 'gemini':
+            return 'Gemini CLI';
+        case 'antigravity':
+            return 'Antigravity';
+        case 'opencode':
+            return 'OpenCode';
+    }
+}
+/** 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 function formatBytes(n) {
+    return `${(n / 1024).toFixed(1)} KB`;
+}
+/** 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 const STUB_BYTE_THRESHOLD = 100;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botdocs/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "CLI for BotDocs — author, publish, install, and sync agent skills across Claude, Claude Code, Cursor, Codex, ChatGPT, Windsurf, Copilot, Gemini, Antigravity, and OpenCode.",
   "keywords": [
     "botdocs",

package/templates/agents.md

@@ -129,7 +129,7 @@ the user and recommend they set one.
 | `backups list / restore / diff / clear` | Browse and manage backup runs. |
 | `compile <path>` | Generate per-ecosystem drafts from a canonical source (BYOK). |
 | `edit <ref>` | LLM-assisted revision of a published skill ecosystem file (BYOK). |
-| `ingest <path>` | Walk a directory, detect existing skills across all 10 ecosystems, upload as drafts. Use `--from-tool=<ecosystem>` to ingest from real on-disk locations like `~/.claude/commands/` or `.cursor/rules/`. |
+| `ingest [path]` | Scan your system (zero-arg) or a directory, detect existing skills across all 10 ecosystems, upload as drafts. Use `--from-tool=<ecosystem>` for real on-disk locations like `~/.claude/commands/`; pass `--auto` to skip the interactive selection. |
 | `team list` | List teams you belong to. |
 | `team show <slug>` | Members + pinned skills for a team. |
 | `team push <slug> <ref>` | Pin a skill to a team (WRITE+). |