@botdocs/cli 0.6.0 → 0.8.0

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

@@ -1,5 +1,5 @@
 import React from 'react';
-import { type DiscoveredSkillFile, type DiscoveryEcosystem } from '../../lib/ingest-discover.js';
+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). */
@@ -11,6 +11,11 @@ export type IngestDiscoverResult = {
 };
 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[];

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

@@ -2,27 +2,60 @@ 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';
+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 files. Empty ecosystems
- * are surfaced separately as a trailing line, not in the row list. */
-function buildRows(files) {
+ * 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;
         }
-        rows.push({ kind: 'file', index, file });
+        const summary = skillSummaries?.get(summaryKey(file));
+        rows.push({ kind: 'file', index, file, summary });
     });
     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. */
+/** 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);
     });
@@ -46,17 +79,27 @@ function moveCursor(rows, current, 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, checked, active, }) {
+function FileRow({ file, summary, checked, active, }) {
     const label = file.scope ? `${file.scope}/${file.slug}` : file.slug;
-    const details = `${formatBytes(file.sizeBytes)} · ${file.lineCount} lines`;
+    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 } = props;
+    const { files, emptyEcosystems, onDone, skillSummaries } = props;
     const { exit } = useApp();
-    const rows = useMemo(() => buildRows(files), [files]);
+    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
@@ -86,7 +129,11 @@ export function IngestDiscoverApp(props) {
         }
         if (input === 'a' || input === 'A') {
             const next = new Set();
-            files.forEach((_, i) => next.add(i));
+            // 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;
@@ -100,7 +147,16 @@ export function IngestDiscoverApp(props) {
                 setEmptyConfirm(true);
                 return;
             }
-            const selected = files.filter((_, i) => checked.has(i));
+            // 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;
@@ -121,7 +177,7 @@ export function IngestDiscoverApp(props) {
                     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}`));
+                    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. */

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')

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

@@ -1,8 +1,9 @@
+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' | 'cursor' | 'codex' | 'copilot' | 'windsurf' | 'gemini' | 'antigravity' | 'opencode';
+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. */
@@ -18,16 +19,37 @@ export interface DiscoveredSkillFile {
     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. */
+    /** 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
@@ -63,6 +85,11 @@ export declare function buildDetectors(homeDir: string, cwd: string): DetectorRo
 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[];
@@ -70,6 +97,9 @@ export interface DiscoveryResult {
      * — 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;
@@ -85,6 +115,9 @@ export interface DiscoveryOptions {
  * 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.

package/dist/lib/ingest-discover.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { DETECTORS } from '../commands/ingest.js';
+import { DETECTORS, formatSweepWarnings, sweepSkillRoot, } 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) {
@@ -100,6 +100,21 @@ function scopeForNested(absPath, scanDir) {
         return undefined;
     return path.basename(candidateScopeDir);
 }
+/** Key for the per-skill summary map. Stays stable across discoveries so the
+ * TUI can look up a summary by row. */
+export function summaryKey(file) {
+    return `${file.ecosystem}::${file.scope ?? ''}/${file.slug}`;
+}
+/** Stat helper: return st_mode masked to the low 9 perm bits, or 0o644 on
+ * failure. Mirrors the same helper in commands/ingest.ts. */
+function safeMode(absPath) {
+    try {
+        return fs.statSync(absPath).mode & 0o777;
+    }
+    catch {
+        return 0o644;
+    }
+}
 /** 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.
@@ -113,6 +128,7 @@ export function discoverSkills(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const rows = buildDetectors(homeDir, cwd);
     const files = [];
+    const skillSummaries = new Map();
     const seen = new Set();
     const empty = new Set();
     for (const row of rows) {
@@ -144,7 +160,7 @@ export function discoverSkills(options = {}) {
             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({
+            const rootFile = {
                 ecosystem: row.ecosystem,
                 sourcePath: abs,
                 slug,
@@ -153,32 +169,80 @@ export function discoverSkills(options = {}) {
                 sizeBytes,
                 lineCount,
                 content,
+                mode: safeMode(abs),
                 canonicalFilename: detector.canonicalFilename(slug),
-            });
+            };
+            files.push(rootFile);
+            // Per-skill summary aggregates the root file + any adjacent sweep
+            // outputs below. We seed it now and append adjacent files inline.
+            const sumKey = summaryKey(rootFile);
+            const summary = {
+                ecosystem: row.ecosystem,
+                scope,
+                slug,
+                totalFiles: 1,
+                totalBytes: sizeBytes,
+                warnings: [],
+            };
+            skillSummaries.set(sumKey, summary);
+            // Adjacent-file sweep for detectors that opt in (claude, claude-code-agents).
+            if (detector.includeAdjacent && detector.skillRoot && detector.canonicalAdjacentFilename) {
+                const skillRoot = detector.skillRoot(abs);
+                const sweep = sweepSkillRoot(skillRoot, abs);
+                for (const adj of sweep.files) {
+                    files.push({
+                        ecosystem: row.ecosystem,
+                        sourcePath: adj.absPath,
+                        slug,
+                        scope,
+                        title: rootFile.title,
+                        // sizeBytes / lineCount on adjacent rows describe the adjacent
+                        // file itself — not the skill total. The TUI uses sizeBytes on
+                        // the ROOT row only for the stub filter; per-skill totals come
+                        // from the summary map.
+                        sizeBytes: adj.sizeBytes,
+                        lineCount: adj.content.length === 0 ? 0 : adj.content.split(/\r?\n/).length,
+                        content: adj.content,
+                        mode: adj.mode,
+                        canonicalFilename: detector.canonicalAdjacentFilename(slug, adj.relPath),
+                    });
+                    summary.totalFiles += 1;
+                    summary.totalBytes += adj.sizeBytes;
+                }
+                summary.warnings = sweep.warnings;
+            }
             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.
+    // Sort stable: by ecosystem, then by display label (scope/slug), then by
+    // canonical filename so adjacent files cluster behind their root file.
     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);
+        if (aLabel !== bLabel)
+            return aLabel.localeCompare(bLabel);
+        return a.canonicalFilename.localeCompare(b.canonicalFilename);
     });
     return {
         files,
+        skillSummaries,
         emptyEcosystems: [...empty].sort(),
         inGitRepo: isGitRepo(cwd),
     };
 }
+/** 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 function ecosystemLabel(ecosystem) {
     switch (ecosystem) {
         case 'claude-code':
             return 'Claude Code';
+        case 'claude-code-agents':
+            return 'Claude Code agents';
         case 'claude':
             return 'Claude skills';
         case 'cursor':