@botdocs/cli 0.8.1 → 0.9.1

package/dist/commands/ingest.d.ts

@@ -11,6 +11,10 @@ interface IngestOptions {
     /** Force the plain-text rendering path — disables the Ink TUI. Mirrors the
      * `--no-ink` flag on `login` and `sync`. */
     noInk?: boolean;
+    /** Replace existing *draft* skills that collide on slug. Published skills
+     * are never replaced — they surface as a blocking 409 either way. Set via
+     * `--force`. */
+    force?: boolean;
 }
 /** Per-file size cap. Any file larger than this is skipped with a warning. */
 export declare const PER_FILE_BYTE_CAP: number;

package/dist/commands/ingest.js

@@ -2,7 +2,8 @@ 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 { ApiError, apiFetch } from '../lib/api.js';
+import { loadAuth } from '../lib/config.js';
 import { discoverSkills, ecosystemLabel, formatBytes, STUB_BYTE_THRESHOLD, summaryKey, titleFromContent, } from '../lib/ingest-discover.js';
 import { IngestDiscoverApp } from './views/ingest-discover-app.js';
 // ---------- Cap + skip rules (shared with discovery) ----------
@@ -279,12 +280,26 @@ export const DETECTORS = {
         scanPaths: () => [],
     },
     codex: {
+        // Codex skills are nested SKILL.md directories, mirroring claude:
+        // ~/.codex/skills/<slug>/SKILL.md (developers.openai.com/codex/skills).
         pathPrefix: 'codex/',
-        extensions: ['.md'],
-        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')] : [],
+        extensions: ['/SKILL.md'],
+        nested: true,
+        slugFor: (abs, root) => {
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if (!rel.endsWith('/SKILL.md'))
+                return null;
+            const parts = rel.split('/');
+            if (parts.length < 2)
+                return null;
+            return parts[parts.length - 2] ?? null;
+        },
+        canonicalFilename: (slug) => `codex/${slug}/SKILL.md`,
+        // Global only — Codex skills live under ~/.codex/skills/.
+        scanPaths: (homeDir) => [path.join(homeDir, '.codex', 'skills')],
+        includeAdjacent: true,
+        skillRoot: (abs) => path.dirname(abs),
+        canonicalAdjacentFilename: (slug, relPath) => `codex/${slug}/${relPath}`,
     },
     copilot: {
         pathPrefix: 'copilot/instructions/',
@@ -296,36 +311,90 @@ export const DETECTORS = {
         scanPaths: (_homeDir, projectRoot, isGitRepo) => isGitRepo ? [path.join(projectRoot, '.github', 'instructions')] : [],
     },
     windsurf: {
+        // Windsurf reads project rules from <proj>/.windsurf/rules/<slug>.md
+        // (docs.windsurf.com). Flat .md rule files, project-scoped (git repo).
         pathPrefix: 'windsurf/rules/',
         extensions: ['.md'],
         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')] : [],
+        scanPaths: (_homeDir, projectRoot, isGitRepo) => isGitRepo ? [path.join(projectRoot, '.windsurf', 'rules')] : [],
     },
     gemini: {
+        // Gemini CLI has NO per-skill file directory. It uses hierarchical
+        // GEMINI.md context files (~/.gemini/GEMINI.md global, ./GEMINI.md
+        // project) — there's nothing to auto-discover and nowhere to drop a
+        // per-skill file. The entry stays present so the ecosystem still exists
+        // for compile/variants, but discovery returns nothing (like chatgpt) and
+        // install routes it to `manual` (see detectDestination).
         pathPrefix: 'gemini/instructions/',
         extensions: ['.md'],
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
         canonicalFilename: (slug) => `gemini/instructions/${slug}.md`,
-        scanPaths: (homeDir) => [path.join(homeDir, '.gemini', 'instructions')],
+        // No canonical on-disk location — nothing to discover.
+        scanPaths: () => [],
     },
     antigravity: {
+        // Antigravity skills are nested SKILL.md directories, mirroring claude:
+        // ~/.gemini/antigravity/skills/<slug>/SKILL.md (global) and
+        // <proj>/.agent/skills/<slug>/SKILL.md (project)
+        // (antigravity.google/docs/skills + Google Codelabs). Keep the existing
+        // `antigravity/skills/` canonical prefix, now nested-with-SKILL.md.
         pathPrefix: 'antigravity/skills/',
-        extensions: ['.md'],
-        nested: false,
-        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
-        canonicalFilename: (slug) => `antigravity/skills/${slug}.md`,
-        scanPaths: (homeDir) => [path.join(homeDir, '.gemini', 'antigravity', 'skills')],
+        extensions: ['/SKILL.md'],
+        nested: true,
+        slugFor: (abs, root) => {
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if (!rel.endsWith('/SKILL.md'))
+                return null;
+            const parts = rel.split('/');
+            if (parts.length < 2)
+                return null;
+            return parts[parts.length - 2] ?? null;
+        },
+        canonicalFilename: (slug) => `antigravity/skills/${slug}/SKILL.md`,
+        // Global ~/.gemini/antigravity/skills always; project <proj>/.agent/skills
+        // only inside a git repo.
+        scanPaths: (homeDir, projectRoot, isGitRepo) => {
+            const paths = [path.join(homeDir, '.gemini', 'antigravity', 'skills')];
+            if (isGitRepo)
+                paths.push(path.join(projectRoot, '.agent', 'skills'));
+            return paths;
+        },
+        includeAdjacent: true,
+        skillRoot: (abs) => path.dirname(abs),
+        canonicalAdjacentFilename: (slug, relPath) => `antigravity/skills/${slug}/${relPath}`,
     },
     opencode: {
-        pathPrefix: 'opencode/instructions/',
-        extensions: ['.md'],
-        nested: false,
-        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
-        canonicalFilename: (slug) => `opencode/instructions/${slug}.md`,
-        scanPaths: (homeDir) => [path.join(homeDir, '.config', 'opencode', 'instructions')],
+        // OpenCode skills are nested SKILL.md directories, mirroring claude:
+        // ~/.config/opencode/skills/<slug>/SKILL.md (global) and
+        // <proj>/.opencode/skills/<slug>/SKILL.md (project)
+        // (opencode.ai/docs/skills).
+        pathPrefix: 'opencode/',
+        extensions: ['/SKILL.md'],
+        nested: true,
+        slugFor: (abs, root) => {
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if (!rel.endsWith('/SKILL.md'))
+                return null;
+            const parts = rel.split('/');
+            if (parts.length < 2)
+                return null;
+            return parts[parts.length - 2] ?? null;
+        },
+        canonicalFilename: (slug) => `opencode/${slug}/SKILL.md`,
+        // Global ~/.config/opencode/skills always; project <proj>/.opencode/skills
+        // only inside a git repo.
+        scanPaths: (homeDir, projectRoot, isGitRepo) => {
+            const paths = [path.join(homeDir, '.config', 'opencode', 'skills')];
+            if (isGitRepo)
+                paths.push(path.join(projectRoot, '.opencode', 'skills'));
+            return paths;
+        },
+        includeAdjacent: true,
+        skillRoot: (abs) => path.dirname(abs),
+        canonicalAdjacentFilename: (slug, relPath) => `opencode/${slug}/${relPath}`,
     },
 };
 export const SUPPORTED_TOOLS = Object.keys(DETECTORS);
@@ -452,15 +521,72 @@ function groupDiscoveredIntoSkills(discovered) {
     }
     return [...grouped.values()];
 }
+/** Narrow an unknown ApiError body to the ingest 409 `{ conflicts }` shape. */
+function parseConflicts(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const conflicts = body.conflicts;
+    if (typeof conflicts !== 'object' || conflicts === null)
+        return null;
+    const { replaceable, blocking } = conflicts;
+    if (!Array.isArray(replaceable) || !Array.isArray(blocking))
+        return null;
+    return {
+        replaceable: replaceable.filter((s) => typeof s === 'string'),
+        blocking: blocking.filter((s) => typeof s === 'string'),
+    };
+}
+/** Render the delete-hint ref for a slug. Uses the logged-in username when
+ * it's readily available (so the user can copy-paste `botdocs delete
+ * @me/slug`); falls back to the bare slug otherwise. */
+function deleteRef(slug) {
+    const username = loadAuth()?.username;
+    return username ? `@${username}/${slug}` : slug;
+}
+/** Print an actionable 409 message and exit non-zero. Honors `--json` by
+ * emitting the structured `{ ok: false, conflicts }` shape instead of prose. */
+function reportConflicts(conflicts, options) {
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, conflicts }));
+        process.exit(1);
+    }
+    if (conflicts.blocking.length > 0) {
+        const refs = conflicts.blocking.map((s) => `botdocs delete ${deleteRef(s)}`).join(', ');
+        console.error(`\n  ✗ These skills are already published and won't be replaced: ${conflicts.blocking.join(', ')}. ` +
+            `Unpublish or delete them first (${refs}), then re-ingest.`);
+    }
+    if (conflicts.replaceable.length > 0) {
+        console.error(`\n  ✗ These skills already exist as drafts: ${conflicts.replaceable.join(', ')}. ` +
+            `Re-run with --force to replace them, or delete them first.`);
+    }
+    console.error('');
+    process.exit(1);
+}
 /** 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. */
+ * response) and the default human-friendly "drafts created" line. On a 409
+ * slug-conflict, prints an actionable message and exits non-zero rather than
+ * letting the ApiError bubble up as a stack trace. 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 },
-    });
+    let result;
+    try {
+        result = await apiFetch('/api/cli/ingest', {
+            method: 'POST',
+            auth: true,
+            body: {
+                skills,
+                bundle: options.bundle ? { name: options.bundle } : undefined,
+                force: options.force,
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 409) {
+            const conflicts = parseConflicts(err.body);
+            if (conflicts)
+                reportConflicts(conflicts, options);
+        }
+        throw err;
+    }
     if (options.json) {
         console.log(JSON.stringify(result));
         return;

package/dist/index.js

@@ -106,7 +106,7 @@ program
 });
 program
     .command('install <ref>')
-    .description('Install a skill or bundle locally (skills go to ~/.claude/skills/, project files to .cursor/rules/, .codex/skills/, .github/instructions/, etc.)')
+    .description('Install a skill or bundle locally (skills go to ~/.claude/skills/, project files to .cursor/rules/, .github/instructions/, .windsurf/rules/, etc.)')
     .option('--project <dir>', 'Override the project root used for project-local files')
     .option('--flat', 'Skip the {scope} subdirectory in install paths (collision-prone, not recommended)')
     .option('--clean', 'Wipe-and-reinstall instead of additive')
@@ -160,6 +160,7 @@ program
     .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('--force', 'Replace existing draft skills with the same name (won\'t touch published skills)')
     .option('--no-ink', 'Disable the interactive TUI; use plain output (zero-arg mode only)')
     .action(async (sourcePath, opts) => {
     // Commander's --no-ink convention sets opts.ink = false; flip to noInk

package/dist/lib/api.d.ts

@@ -1,10 +1,17 @@
 export declare function getApiUrl(): string;
 /** Thrown by apiFetch when the server returns a non-2xx response. Carries the
  * status code and the server-provided message so callers can branch on
- * different HTTP error codes (404 vs 403 vs 5xx) with friendly hints. */
+ * different HTTP error codes (404 vs 403 vs 5xx) with friendly hints.
+ *
+ * `body` holds the parsed JSON error payload when the server returned one
+ * (e.g. ingest's `{ error, conflicts }`). It's `undefined` when the response
+ * body wasn't JSON. Callers that need structured fields (not just the
+ * `message` string) read it — most callers ignore it and the existing
+ * `status` + `message` branching keeps working unchanged. */
 export declare class ApiError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    readonly body?: unknown;
+    constructor(status: number, message: string, body?: unknown);
 }
 interface FetchOptions {
     method?: string;

package/dist/lib/api.js

@@ -5,13 +5,21 @@ export function getApiUrl() {
 }
 /** Thrown by apiFetch when the server returns a non-2xx response. Carries the
  * status code and the server-provided message so callers can branch on
- * different HTTP error codes (404 vs 403 vs 5xx) with friendly hints. */
+ * different HTTP error codes (404 vs 403 vs 5xx) with friendly hints.
+ *
+ * `body` holds the parsed JSON error payload when the server returned one
+ * (e.g. ingest's `{ error, conflicts }`). It's `undefined` when the response
+ * body wasn't JSON. Callers that need structured fields (not just the
+ * `message` string) read it — most callers ignore it and the existing
+ * `status` + `message` branching keeps working unchanged. */
 export class ApiError extends Error {
     status;
-    constructor(status, message) {
+    body;
+    constructor(status, message, body) {
         super(message);
         this.name = 'ApiError';
         this.status = status;
+        this.body = body;
     }
 }
 export async function apiFetch(path, options = {}) {
@@ -42,8 +50,13 @@ export async function apiFetch(path, options = {}) {
     if (!response.ok) {
         const text = await response.text();
         let message;
+        // `parsedBody` is the structured error payload when the server sent JSON
+        // (e.g. ingest's `{ error, conflicts }`). Left undefined for non-JSON
+        // bodies so callers can distinguish "no structured data" from "{}".
+        let parsedBody;
         try {
             const json = JSON.parse(text);
+            parsedBody = json;
             message = json.error || text;
         }
         catch {
@@ -54,7 +67,7 @@ export async function apiFetch(path, options = {}) {
         if (response.status === 401 && auth) {
             message = 'Authentication failed. Run `botdocs login` to sign in again.';
         }
-        throw new ApiError(response.status, message);
+        throw new ApiError(response.status, message, parsedBody);
     }
     const contentType = response.headers.get('content-type') || '';
     if (contentType.includes('application/json')) {

package/dist/lib/auto-detect.js

@@ -47,10 +47,24 @@ export function detectDestination(srcRelative, ctx) {
         };
     }
     if (src.startsWith('codex/')) {
-        return {
-            kind: 'project',
-            dest: path.join(ctx.projectDir, '.codex', 'skills', path.basename(src)),
-        };
+        // Codex skills are nested SKILL.md directories at
+        // ~/.codex/skills/<slug>/SKILL.md (developers.openai.com/codex/skills).
+        // New canonical form: codex/<slug>/SKILL.md (+ adjacent files). Strip the
+        // `codex/<slug>/` prefix and keep the relpath under ~/.codex/skills/<slug>/.
+        //
+        // Backward-compat: BotDocs published before this fix stored flat
+        // `codex/<slug>.md`. We detect the flat form (no inner slash) and route it
+        // to the new nested destination ~/.codex/skills/<slug>/SKILL.md so already-
+        // published docs still install where Codex reads them.
+        const remainder = src.slice('codex/'.length);
+        const codexBase = path.join(ctx.homeDir, '.codex', 'skills');
+        if (!remainder.includes('/')) {
+            // Flat legacy form `codex/<slug>.md` → nested SKILL.md.
+            const slug = remainder.replace(/\.md$/, '');
+            return { kind: 'global', dest: path.join(codexBase, slug, 'SKILL.md') };
+        }
+        const finalName = remainder.replace(/^[^/]+\//, '');
+        return { kind: 'global', dest: path.join(codexBase, ctx.slug, finalName) };
     }
     if (src.startsWith('copilot/instructions/')) {
         // GitHub Copilot custom instructions live in .github/instructions/
@@ -61,36 +75,66 @@ export function detectDestination(srcRelative, ctx) {
         };
     }
     if (src.startsWith('windsurf/rules/')) {
-        // Windsurf (Codeium) reads project rules from .codeium/windsurf-rules/
-        // (https://docs.codeium.com/windsurf/cascade#windsurfrules).
+        // Windsurf reads project rules from <proj>/.windsurf/rules/<slug>.md
+        // (docs.windsurf.com). Flat .md rule, project-scoped. The canonical form
+        // is already flat, so basename() is the right leaf either way.
         return {
             kind: 'project',
-            dest: path.join(ctx.projectDir, '.codeium', 'windsurf-rules', path.basename(src)),
+            dest: path.join(ctx.projectDir, '.windsurf', 'rules', path.basename(src)),
         };
     }
-    if (src.startsWith('gemini/instructions/')) {
-        // Gemini CLI reads global instructions from ~/.gemini/instructions/
-        // (https://github.com/google-gemini/gemini-cli).
-        return {
-            kind: 'global',
-            dest: path.join(ctx.homeDir, '.gemini', 'instructions', path.basename(src)),
-        };
+    if (src.startsWith('gemini/')) {
+        // Gemini CLI has NO per-skill file directory — it uses hierarchical
+        // GEMINI.md context files (~/.gemini/GEMINI.md global, ./GEMINI.md
+        // project). There's no real path to write to, so route to `manual` (like
+        // chatgpt): install surfaces the content for the user to paste into their
+        // GEMINI.md or @import it, rather than fabricating ~/.gemini/instructions/.
+        return { kind: 'manual', dest: src };
     }
     if (src.startsWith('antigravity/skills/')) {
-        // Google Antigravity reads skills from ~/.gemini/antigravity/skills/
-        // (shares the gemini config tree).
-        return {
-            kind: 'global',
-            dest: path.join(ctx.homeDir, '.gemini', 'antigravity', 'skills', path.basename(src)),
-        };
+        // Antigravity skills are nested SKILL.md directories
+        // (antigravity.google/docs/skills). Project: <proj>/.agent/skills/<slug>/…
+        // Global mirror: ~/.gemini/antigravity/skills/<slug>/… We prefer the
+        // project destination when a project dir applies (matching cursor/codex-
+        // commands which default to project).
+        //
+        // New canonical form: antigravity/skills/<slug>/SKILL.md (+ adjacent).
+        // Strip the `antigravity/skills/<slug>/` prefix, keep the relpath.
+        //
+        // Backward-compat: docs published before this fix stored flat
+        // `antigravity/skills/<slug>.md`. Detect the flat form and route it to the
+        // new nested destination so already-published docs still install.
+        const remainder = src.slice('antigravity/skills/'.length);
+        const agentBase = path.join(ctx.projectDir, '.agent', 'skills');
+        if (!remainder.includes('/')) {
+            const slug = remainder.replace(/\.md$/, '');
+            return { kind: 'project', dest: path.join(agentBase, slug, 'SKILL.md') };
+        }
+        const finalName = remainder.replace(/^[^/]+\//, '');
+        return { kind: 'project', dest: path.join(agentBase, ctx.slug, finalName) };
     }
-    if (src.startsWith('opencode/instructions/')) {
-        // OpenCode (SST) reads instructions from ~/.config/opencode/instructions/
-        // (https://github.com/sst/opencode).
-        return {
-            kind: 'global',
-            dest: path.join(ctx.homeDir, '.config', 'opencode', 'instructions', path.basename(src)),
-        };
+    if (src.startsWith('opencode/')) {
+        // OpenCode skills are nested SKILL.md directories (opencode.ai/docs/skills).
+        // Project: <proj>/.opencode/skills/<slug>/… Global mirror:
+        // ~/.config/opencode/skills/<slug>/… We prefer the project destination
+        // when a project dir applies (matching cursor/codex-commands).
+        //
+        // New canonical form: opencode/<slug>/SKILL.md (+ adjacent). Strip the
+        // `opencode/<slug>/` prefix, keep the relpath.
+        //
+        // Backward-compat: docs published before this fix stored flat
+        // `opencode/instructions/<slug>.md`. Detect that legacy prefix and route
+        // it to the new nested destination so already-published docs still install.
+        const opencodeBase = path.join(ctx.projectDir, '.opencode', 'skills');
+        if (src.startsWith('opencode/instructions/')) {
+            const slug = path.basename(src).replace(/\.md$/, '');
+            return { kind: 'project', dest: path.join(opencodeBase, slug, 'SKILL.md') };
+        }
+        const remainder = src.slice('opencode/'.length);
+        const finalName = remainder.includes('/')
+            ? remainder.replace(/^[^/]+\//, '')
+            : remainder;
+        return { kind: 'project', dest: path.join(opencodeBase, ctx.slug, finalName) };
     }
     if (src.startsWith('chatgpt/')) {
         return { kind: 'manual', dest: src };

package/package.json

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