@botdocs/cli 0.6.0 → 0.8.1

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,46 @@ 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 — when discovery marked
+ * it as the skill's primary file. Root files are the only ones surfaced in the
+ * TUI; adjacent files (scripts/, templates/) ride along when their skill is
+ * toggled. The `isRoot` flag is set authoritatively in `discoverSkills`, so
+ * the renderer never has to guess from the filename. */
+function isRootFile(file) {
+    return file.isRoot;
+}
 /** 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 +65,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 +115,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 +133,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 +163,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,15 +19,43 @@ 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;
+    /** True for the skill's primary file (SKILL.md / AGENT.md / a flat .md),
+     * false for adjacent files swept in from the skill directory
+     * (scripts/, templates/, etc.). Set authoritatively at discovery time —
+     * the TUI and plain-text renderers list ONE row per skill by filtering to
+     * `isRoot`, and adjacent files ride along when their root is selected.
+     * Marking it here avoids fragile filename-suffix guessing downstream. */
+    isRoot: boolean;
+}
+/** 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
@@ -63,6 +92,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 +104,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 +122,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,82 @@ export function discoverSkills(options = {}) {
                 sizeBytes,
                 lineCount,
                 content,
+                mode: safeMode(abs),
                 canonicalFilename: detector.canonicalFilename(slug),
-            });
+                isRoot: true,
+            };
+            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),
+                        isRoot: false,
+                    });
+                    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':

package/dist/lib/ref.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Parse a BotDoc ref like `@user/slug` or `user/slug` into its parts.
+ *
+ * Mirrors the inline `parseRef` already in `commands/install.ts` and
+ * `commands/edit.ts` — kept here for reuse by `publish`/`unpublish`.
+ * The existing duplicates can be folded into this helper in a future
+ * refactor without behavior change.
+ *
+ * Throws on a malformed input so callers can surface a clear message
+ * instead of silently dispatching a malformed API request.
+ */
+export declare function parseRef(raw: string): {
+    username: string;
+    slug: string;
+};
+/**
+ * True when `source` looks like a BotDoc ref (e.g. `@me/my-skill` or
+ * `me/my-skill`), false when it looks like a local filesystem path.
+ *
+ * Used by `botdocs publish <source>` to overload one verb by argument
+ * shape — ref-form dispatches to the publish-toggle API, anything else
+ * goes through the existing file/dir/zip upload flow.
+ *
+ * Heuristic (lean toward "is a ref" only when unambiguous):
+ *
+ * - `@…` → ref. The leading `@` is unambiguous; no filesystem path
+ *   starts with `@`.
+ * - Starts with `./`, `..`, or `/` → path. Absolute and explicit
+ *   relative paths are never refs.
+ * - Contains a `.` (e.g. `foo.md`, `foo.zip`, `dir/file.md`) → path.
+ *   File extensions are the strongest signal we're looking at a file.
+ * - Contains exactly one `/` with non-empty parts on either side → ref.
+ *   `user/slug` and `org/repo`-style.
+ * - Otherwise → path. Bare names like `my-skill` resolve as directory
+ *   paths under the existing upload flow.
+ *
+ * False positives (a real directory named `user/slug` with no `.`) will
+ * surface as a clean "BotDoc not found" 404 from the API — not silent
+ * data loss, just a clearer error than letting the upload flow choke
+ * on a non-existent path.
+ */
+export declare function isRefForm(source: string): boolean;

package/dist/lib/ref.js

@@ -0,0 +1,60 @@
+/**
+ * Parse a BotDoc ref like `@user/slug` or `user/slug` into its parts.
+ *
+ * Mirrors the inline `parseRef` already in `commands/install.ts` and
+ * `commands/edit.ts` — kept here for reuse by `publish`/`unpublish`.
+ * The existing duplicates can be folded into this helper in a future
+ * refactor without behavior change.
+ *
+ * Throws on a malformed input so callers can surface a clear message
+ * instead of silently dispatching a malformed API request.
+ */
+export function parseRef(raw) {
+    const cleaned = raw.startsWith('@') ? raw.slice(1) : raw;
+    const parts = cleaned.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error(`Invalid ref: ${raw} (expected @user/slug)`);
+    }
+    return { username: parts[0], slug: parts[1] };
+}
+/**
+ * True when `source` looks like a BotDoc ref (e.g. `@me/my-skill` or
+ * `me/my-skill`), false when it looks like a local filesystem path.
+ *
+ * Used by `botdocs publish <source>` to overload one verb by argument
+ * shape — ref-form dispatches to the publish-toggle API, anything else
+ * goes through the existing file/dir/zip upload flow.
+ *
+ * Heuristic (lean toward "is a ref" only when unambiguous):
+ *
+ * - `@…` → ref. The leading `@` is unambiguous; no filesystem path
+ *   starts with `@`.
+ * - Starts with `./`, `..`, or `/` → path. Absolute and explicit
+ *   relative paths are never refs.
+ * - Contains a `.` (e.g. `foo.md`, `foo.zip`, `dir/file.md`) → path.
+ *   File extensions are the strongest signal we're looking at a file.
+ * - Contains exactly one `/` with non-empty parts on either side → ref.
+ *   `user/slug` and `org/repo`-style.
+ * - Otherwise → path. Bare names like `my-skill` resolve as directory
+ *   paths under the existing upload flow.
+ *
+ * False positives (a real directory named `user/slug` with no `.`) will
+ * surface as a clean "BotDoc not found" 404 from the API — not silent
+ * data loss, just a clearer error than letting the upload flow choke
+ * on a non-existent path.
+ */
+export function isRefForm(source) {
+    if (!source)
+        return false;
+    if (source.startsWith('@'))
+        return true;
+    if (source.startsWith('./') || source.startsWith('../') || source.startsWith('/')) {
+        return false;
+    }
+    if (source.includes('.'))
+        return false;
+    const parts = source.split('/');
+    if (parts.length !== 2)
+        return false;
+    return Boolean(parts[0] && parts[1]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botdocs/cli",
-  "version": "0.6.0",
+  "version": "0.8.1",
   "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

@@ -119,7 +119,8 @@ the user and recommend they set one.
 | `init [name]` | Scaffold a new skill directory. |
 | `validate <source>` | Pre-publish structural check. |
 | `search <query>` | Search the registry. |
-| `publish <source>` | Publish from a file, directory, or zip. |
+| `publish <source>` | Publish from a file, directory, or zip — or pass `@user/slug` to mark an existing draft live. |
+| `unpublish <ref>` | Hide a published BotDoc from `/explore` (sets the `draft` flag back; prompts unless `--yes`). |
 | `install <ref>` | Install a skill or bundle (auto-detects destinations). |
 | `sync [ref]` | Apply available updates to installed skills. |
 | `uninstall <ref>` | Remove an installed skill or bundle. |