@botdocs/cli 0.3.2 → 0.4.0

package/dist/lib/backup.d.ts

@@ -0,0 +1,121 @@
+/** Only exported so tests can reset between cases. Do NOT call from production
+ * code — the whole point of the cache is that one CLI invocation = one folder. */
+export declare function _resetRunTimestampForTests(): void;
+export interface BackupResult {
+    /** Absolute path to where the backup landed (or would land, if !ok). */
+    dest: string;
+    /** Whether the backup succeeded. */
+    ok: boolean;
+    /** If !ok, the error message to surface to the user. */
+    error?: string;
+}
+/** A single file's record in a backup run's `manifest.json` sidecar.
+ *
+ * The manifest is the source of truth for what each backup file represents.
+ * Restoration MUST read from the manifest rather than path-decoding — the
+ * global-scope flattening (`/` → `_`) is lossy if filenames contain
+ * underscores. */
+export interface BackupManifestEntry {
+    /** Original absolute path of the backed-up file. */
+    originalPath: string;
+    /** Absolute path to where the backup landed. */
+    backupPath: string;
+    /** "project" if the original was under projectRoot, else "global". */
+    scope: 'project' | 'global';
+    /** ISO timestamp of when this individual file was backed up. */
+    backedUpAt: string;
+}
+export interface BackupManifest {
+    /** ISO timestamp shared by all files in this run (matches the folder name). */
+    runTimestamp: string;
+    files: BackupManifestEntry[];
+}
+/** Compute the backup destination for an existing file without actually
+ * copying. Used by --dry-run to print "would back up" lines without touching
+ * disk. */
+export declare function backupDestination(absolutePath: string, projectRoot: string, homeDir?: string): string;
+/** Backup an existing file before it's about to be overwritten.
+ *
+ * - Project-scoped files (under `projectRoot`) → `<projectRoot>/.botdocs-backup/<ts>/<rel>`
+ * - Anything else (e.g. global skills under ~/.claude/skills) → `~/.botdocs/backup/<ts>/<absPath-with-/-as-_>`
+ *
+ * Also appends an entry to the run's `manifest.json` sidecar so `botdocs undo`
+ * and `botdocs backups restore` can recover unambiguously even when the
+ * flattened global filename is ambiguous.
+ *
+ * Returns `{ ok: false, error }` rather than throwing so callers can surface a
+ * warning and proceed with the overwrite. We never want a backup failure to
+ * block the underlying install/sync. */
+export declare function backupFile(absolutePath: string, projectRoot: string, homeDir?: string): BackupResult;
+/** Returns true if the given destination path appears in any install's
+ * `files[]` with a fingerprint matching the current on-disk content. That is,
+ * "this is a file we wrote and the user hasn't edited it since." Untracked
+ * files OR tracked-but-edited files both return false → backup required.
+ *
+ * The fingerprint check is what distinguishes "we wrote this and own it" from
+ * "we wrote this but the user has since edited it" — the latter still deserves
+ * a backup before we clobber the edits. */
+export declare function isLockfileOwnedAndUnchanged(dest: string): boolean;
+/** Summary of one backup run, suitable for `botdocs backups list` output. */
+export interface BackupRunSummary {
+    /** ISO timestamp shared by every file in the run (matches the folder name). */
+    runTimestamp: string;
+    /** Where the manifest(s) for this run live: project, global, or both. */
+    scope: 'project' | 'global' | 'both';
+    /** Total files in the run, across both scopes if both exist. */
+    fileCount: number;
+    /** Primary run-root directory; the project one if both exist. */
+    rootPath: string;
+}
+/** List every backup run across both roots, newest first.
+ *
+ * Returns the union of timestamps in the project root and the global root.
+ * When a timestamp appears in both, it's reported once with `scope: 'both'`. */
+export declare function listBackupRuns(projectRoot: string, homeDir?: string): BackupRunSummary[];
+/** List every file in a specific backup run, across both manifests if present. */
+export declare function listBackupFiles(runTimestamp: string, projectRoot: string, homeDir?: string): BackupManifestEntry[];
+export interface RestoreOptions {
+    /** Optional subset filter — restore only entries whose `originalPath` ends
+     * with one of these relative paths. Useful for partial-restore from a
+     * larger run. */
+    files?: string[];
+    /** If true, don't write — just compute the plan. */
+    dryRun?: boolean;
+    /** If true, skip the "back up current state before restoring" step. The
+     * default is to back up first so `undo` is itself reversible. */
+    noBackup?: boolean;
+}
+export interface RestoreFailure {
+    entry: BackupManifestEntry;
+    error: string;
+}
+export interface RestoreResult {
+    /** Entries that were successfully restored (or would be, under --dry-run). */
+    restored: BackupManifestEntry[];
+    /** Entries we couldn't restore — backup file missing/unreadable etc.
+     * We skip these and continue with the rest of the run. */
+    failed: RestoreFailure[];
+    /** Original paths whose current state was backed up before the restore.
+     * Files that didn't exist at the original path are NOT included here —
+     * there was nothing to back up. */
+    preBackedUp: string[];
+}
+/** Restore every file recorded in a backup run's manifest to its original path.
+ *
+ * Before writing each restored file, the CURRENT contents at `originalPath` are
+ * themselves backed up under a NEW timestamp so `undo` is reversible — running
+ * `botdocs undo` twice in a row swaps the state back. Pass `noBackup: true` to
+ * skip the pre-backup (advanced). */
+export declare function restoreBackup(runTimestamp: string, projectRoot: string, options?: RestoreOptions, homeDir?: string): RestoreResult;
+export interface ClearOptions {
+    /** Drop runs whose timestamp is older than N days. If omitted, clear ALL runs. */
+    olderThanDays?: number;
+    /** If true, just compute the plan — don't delete anything. */
+    dryRun?: boolean;
+}
+export interface ClearResult {
+    cleared: BackupRunSummary[];
+    kept: BackupRunSummary[];
+}
+/** Clear backup runs, optionally filtered by age. */
+export declare function clearBackups(projectRoot: string, options?: ClearOptions, homeDir?: string): ClearResult;

package/dist/lib/backup.js

@@ -0,0 +1,387 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fingerprintFile, loadLockfile } from './lockfile.js';
+let runTimestamp = null;
+/** A single timestamp per CLI invocation, lazily generated on first backup.
+ * Cached at the module level so multiple backups in the same `botdocs install`
+ * or `botdocs sync` run all land under the same `<ts>` folder, making them
+ * easy to inspect and restore as a unit. */
+function getRunTimestamp() {
+    if (!runTimestamp) {
+        runTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    }
+    return runTimestamp;
+}
+/** Only exported so tests can reset between cases. Do NOT call from production
+ * code — the whole point of the cache is that one CLI invocation = one folder. */
+export function _resetRunTimestampForTests() {
+    runTimestamp = null;
+}
+/** Resolve symlinks for the parent directory so comparisons hold up against
+ * platform quirks (macOS prefixes `/var/...` with `/private`, etc.). Falls
+ * back to the original path if the parent doesn't exist yet. */
+function realParentResolve(p) {
+    const abs = path.resolve(p);
+    const parent = path.dirname(abs);
+    try {
+        const realParent = fs.realpathSync(parent);
+        return path.join(realParent, path.basename(abs));
+    }
+    catch {
+        return abs;
+    }
+}
+/** Determine whether a path is under projectRoot (project-scoped) or not. */
+function isProjectScoped(absolutePath, projectRoot) {
+    const normProject = realParentResolve(projectRoot);
+    const normAbs = realParentResolve(absolutePath);
+    const rel = path.relative(normProject, normAbs);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+/** Root directory for a backup run's folder. Either:
+ * - Project: `<projectRoot>/.botdocs-backup/<ts>`
+ * - Global:  `<homeDir>/.botdocs/backup/<ts>` */
+function backupRunRoot(scope, ts, projectRoot, homeDir) {
+    if (scope === 'project') {
+        return path.join(realParentResolve(projectRoot), '.botdocs-backup', ts);
+    }
+    return path.join(homeDir, '.botdocs', 'backup', ts);
+}
+/** Compute the backup destination for an existing file without actually
+ * copying. Used by --dry-run to print "would back up" lines without touching
+ * disk. */
+export function backupDestination(absolutePath, projectRoot, homeDir = os.homedir()) {
+    const ts = getRunTimestamp();
+    const normAbs = realParentResolve(absolutePath);
+    if (isProjectScoped(absolutePath, projectRoot)) {
+        const normProject = realParentResolve(projectRoot);
+        const rel = path.relative(normProject, normAbs);
+        return path.join(normProject, '.botdocs-backup', ts, rel);
+    }
+    // Global-scoped: flatten the absolute path into a single filename by
+    // replacing path separators with `_`. Predictable, but lossy if filenames
+    // already contain `_` — the manifest.json sidecar is the source of truth
+    // for restoration.
+    const flattened = normAbs.replace(/[/\\]/g, '_');
+    return path.join(homeDir, '.botdocs', 'backup', ts, flattened);
+}
+/** Read a manifest.json from disk, returning a fresh empty manifest if the
+ * file doesn't exist or can't be parsed. */
+function readManifest(manifestPath, ts) {
+    if (!fs.existsSync(manifestPath)) {
+        return { runTimestamp: ts, files: [] };
+    }
+    try {
+        const raw = fs.readFileSync(manifestPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof parsed.runTimestamp === 'string' &&
+            Array.isArray(parsed.files)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through to a fresh manifest — better to lose one stale corrupt
+        // file than block all future backups in this folder.
+    }
+    return { runTimestamp: ts, files: [] };
+}
+/** Write the manifest atomically: write to `<path>.tmp` then rename. Protects
+ * against partial writes if the CLI is interrupted mid-backup. */
+function writeManifestAtomic(manifestPath, manifest) {
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    const tmp = `${manifestPath}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2), 'utf-8');
+    fs.renameSync(tmp, manifestPath);
+}
+/** Append a single entry to the appropriate manifest.json for this run. */
+function appendToManifest(entry, projectRoot, homeDir) {
+    const ts = getRunTimestamp();
+    const runRoot = backupRunRoot(entry.scope, ts, projectRoot, homeDir);
+    const manifestPath = path.join(runRoot, 'manifest.json');
+    const manifest = readManifest(manifestPath, ts);
+    manifest.files.push(entry);
+    writeManifestAtomic(manifestPath, manifest);
+}
+/** Backup an existing file before it's about to be overwritten.
+ *
+ * - Project-scoped files (under `projectRoot`) → `<projectRoot>/.botdocs-backup/<ts>/<rel>`
+ * - Anything else (e.g. global skills under ~/.claude/skills) → `~/.botdocs/backup/<ts>/<absPath-with-/-as-_>`
+ *
+ * Also appends an entry to the run's `manifest.json` sidecar so `botdocs undo`
+ * and `botdocs backups restore` can recover unambiguously even when the
+ * flattened global filename is ambiguous.
+ *
+ * Returns `{ ok: false, error }` rather than throwing so callers can surface a
+ * warning and proceed with the overwrite. We never want a backup failure to
+ * block the underlying install/sync. */
+export function backupFile(absolutePath, projectRoot, homeDir = os.homedir()) {
+    const dest = backupDestination(absolutePath, projectRoot, homeDir);
+    // No-op if the source doesn't exist — nothing to back up. We return ok:true
+    // so callers don't print a spurious warning.
+    if (!fs.existsSync(absolutePath)) {
+        return { dest, ok: true };
+    }
+    try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(absolutePath, dest);
+        // Record the canonical original→backup mapping in the run's manifest so
+        // restoration doesn't have to round-trip through the lossy flattening.
+        const scope = isProjectScoped(absolutePath, projectRoot)
+            ? 'project'
+            : 'global';
+        appendToManifest({
+            originalPath: realParentResolve(absolutePath),
+            backupPath: dest,
+            scope,
+            backedUpAt: new Date().toISOString(),
+        }, projectRoot, homeDir);
+        return { dest, ok: true };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { dest, ok: false, error: message };
+    }
+}
+/** Returns true if the given destination path appears in any install's
+ * `files[]` with a fingerprint matching the current on-disk content. That is,
+ * "this is a file we wrote and the user hasn't edited it since." Untracked
+ * files OR tracked-but-edited files both return false → backup required.
+ *
+ * The fingerprint check is what distinguishes "we wrote this and own it" from
+ * "we wrote this but the user has since edited it" — the latter still deserves
+ * a backup before we clobber the edits. */
+export function isLockfileOwnedAndUnchanged(dest) {
+    if (!fs.existsSync(dest))
+        return false;
+    const lf = loadLockfile();
+    let currentFp;
+    try {
+        currentFp = fingerprintFile(dest);
+    }
+    catch {
+        // If we can't read the file to fingerprint it, treat as unowned —
+        // caller will attempt a backup and that path will surface the error.
+        return false;
+    }
+    for (const install of lf.installs) {
+        for (const file of install.files) {
+            if (file.dest === dest && file.fingerprint === currentFp) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/** Path to the project-scope backup root (the parent of all `<ts>` folders). */
+function projectBackupRoot(projectRoot) {
+    return path.join(realParentResolve(projectRoot), '.botdocs-backup');
+}
+/** Path to the global-scope backup root. */
+function globalBackupRoot(homeDir) {
+    return path.join(homeDir, '.botdocs', 'backup');
+}
+/** List every timestamp folder under a backup root, returning their basenames. */
+function listTimestampsIn(root) {
+    if (!fs.existsSync(root))
+        return [];
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+}
+/** Load the manifest at `<runRoot>/manifest.json` if it exists. */
+function loadManifest(runRoot) {
+    const manifestPath = path.join(runRoot, 'manifest.json');
+    if (!fs.existsSync(manifestPath))
+        return null;
+    try {
+        const raw = fs.readFileSync(manifestPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof parsed.runTimestamp === 'string' &&
+            Array.isArray(parsed.files)) {
+            return parsed;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/** List every backup run across both roots, newest first.
+ *
+ * Returns the union of timestamps in the project root and the global root.
+ * When a timestamp appears in both, it's reported once with `scope: 'both'`. */
+export function listBackupRuns(projectRoot, homeDir = os.homedir()) {
+    const projectTs = new Set(listTimestampsIn(projectBackupRoot(projectRoot)));
+    const globalTs = new Set(listTimestampsIn(globalBackupRoot(homeDir)));
+    const all = new Set([...projectTs, ...globalTs]);
+    const summaries = [];
+    for (const ts of all) {
+        const inProject = projectTs.has(ts);
+        const inGlobal = globalTs.has(ts);
+        let scope;
+        let rootPath;
+        let fileCount;
+        if (inProject && inGlobal) {
+            scope = 'both';
+            rootPath = path.join(projectBackupRoot(projectRoot), ts);
+            const pm = loadManifest(path.join(projectBackupRoot(projectRoot), ts));
+            const gm = loadManifest(path.join(globalBackupRoot(homeDir), ts));
+            fileCount = (pm?.files.length ?? 0) + (gm?.files.length ?? 0);
+        }
+        else if (inProject) {
+            scope = 'project';
+            rootPath = path.join(projectBackupRoot(projectRoot), ts);
+            fileCount = loadManifest(rootPath)?.files.length ?? 0;
+        }
+        else {
+            scope = 'global';
+            rootPath = path.join(globalBackupRoot(homeDir), ts);
+            fileCount = loadManifest(rootPath)?.files.length ?? 0;
+        }
+        summaries.push({ runTimestamp: ts, scope, fileCount, rootPath });
+    }
+    // ISO timestamp folder names sort lexicographically into chronological order.
+    summaries.sort((a, b) => (a.runTimestamp < b.runTimestamp ? 1 : -1));
+    return summaries;
+}
+/** List every file in a specific backup run, across both manifests if present. */
+export function listBackupFiles(runTimestamp, projectRoot, homeDir = os.homedir()) {
+    const projectManifest = loadManifest(path.join(projectBackupRoot(projectRoot), runTimestamp));
+    const globalManifest = loadManifest(path.join(globalBackupRoot(homeDir), runTimestamp));
+    const entries = [];
+    if (projectManifest)
+        entries.push(...projectManifest.files);
+    if (globalManifest)
+        entries.push(...globalManifest.files);
+    return entries;
+}
+/** Match an entry against the user's `--files a,b,c` filter. We do a suffix
+ * match so the caller can pass `.cursor/rules/foo.mdc` without having to know
+ * the absolute path. Empty filter = match everything. */
+function matchesFileFilter(entry, filters) {
+    if (!filters || filters.length === 0)
+        return true;
+    return filters.some((f) => entry.originalPath.endsWith(f));
+}
+/** Restore every file recorded in a backup run's manifest to its original path.
+ *
+ * Before writing each restored file, the CURRENT contents at `originalPath` are
+ * themselves backed up under a NEW timestamp so `undo` is reversible — running
+ * `botdocs undo` twice in a row swaps the state back. Pass `noBackup: true` to
+ * skip the pre-backup (advanced). */
+export function restoreBackup(runTimestamp, projectRoot, options = {}, homeDir = os.homedir()) {
+    const all = listBackupFiles(runTimestamp, projectRoot, homeDir);
+    const entries = all.filter((e) => matchesFileFilter(e, options.files));
+    const restored = [];
+    const failed = [];
+    const preBackedUp = [];
+    for (const entry of entries) {
+        if (!fs.existsSync(entry.backupPath)) {
+            failed.push({ entry, error: `backup file missing: ${entry.backupPath}` });
+            continue;
+        }
+        let content;
+        try {
+            content = fs.readFileSync(entry.backupPath);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            failed.push({ entry, error: `read failed: ${message}` });
+            continue;
+        }
+        if (options.dryRun) {
+            restored.push(entry);
+            continue;
+        }
+        // Pre-backup the current state at originalPath so this restore is itself
+        // reversible. Skip if --no-backup, or if the file doesn't exist (nothing
+        // to back up). The pre-backup writes to a new run-timestamp folder.
+        if (!options.noBackup && fs.existsSync(entry.originalPath)) {
+            const result = backupFile(entry.originalPath, projectRoot, homeDir);
+            if (result.ok) {
+                preBackedUp.push(entry.originalPath);
+            }
+            // If pre-backup fails, we proceed with the restore — the user asked
+            // for the restore, not the pre-backup, and we don't want a permissions
+            // hiccup on the pre-backup to block recovery.
+        }
+        try {
+            fs.mkdirSync(path.dirname(entry.originalPath), { recursive: true });
+            fs.writeFileSync(entry.originalPath, content);
+            restored.push(entry);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            failed.push({ entry, error: `write failed: ${message}` });
+        }
+    }
+    return { restored, failed, preBackedUp };
+}
+/** Parse the folder name back into a real Date for `--older-than-days` math.
+ * The folder name is an ISO timestamp with `:` and `.` replaced by `-`, so
+ * undo: every `-` that comes after the first `T` gets turned back. */
+function parseRunTimestamp(ts) {
+    // Format: 2026-05-13T12-34-56-789Z
+    const tIndex = ts.indexOf('T');
+    if (tIndex < 0)
+        return null;
+    const datePart = ts.slice(0, tIndex);
+    const timePart = ts.slice(tIndex + 1);
+    // timePart: 12-34-56-789Z → 12:34:56.789Z
+    const m = timePart.match(/^(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/);
+    if (!m)
+        return null;
+    const iso = `${datePart}T${m[1]}:${m[2]}:${m[3]}.${m[4]}Z`;
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return null;
+    return d;
+}
+/** Clear backup runs, optionally filtered by age. */
+export function clearBackups(projectRoot, options = {}, homeDir = os.homedir()) {
+    const all = listBackupRuns(projectRoot, homeDir);
+    const cleared = [];
+    const kept = [];
+    const cutoff = options.olderThanDays !== undefined
+        ? Date.now() - options.olderThanDays * 86_400_000
+        : null;
+    for (const run of all) {
+        let shouldClear = cutoff === null;
+        if (cutoff !== null) {
+            const runDate = parseRunTimestamp(run.runTimestamp);
+            shouldClear = runDate !== null && runDate.getTime() < cutoff;
+        }
+        if (shouldClear) {
+            if (!options.dryRun) {
+                // Remove BOTH the project-side and global-side folders for this
+                // timestamp if they exist. listBackupRuns merges them into a single
+                // summary, but the on-disk folders are separate.
+                const projectDir = path.join(projectBackupRoot(projectRoot), run.runTimestamp);
+                const globalDir = path.join(globalBackupRoot(homeDir), run.runTimestamp);
+                if (fs.existsSync(projectDir)) {
+                    fs.rmSync(projectDir, { recursive: true, force: true });
+                }
+                if (fs.existsSync(globalDir)) {
+                    fs.rmSync(globalDir, { recursive: true, force: true });
+                }
+            }
+            cleared.push(run);
+        }
+        else {
+            kept.push(run);
+        }
+    }
+    return { cleared, kept };
+}

package/dist/lib/canonical.d.ts

@@ -1,4 +1,4 @@
-export type Ecosystem = 'claude' | 'claude-code' | 'cursor' | 'chatgpt' | 'codex';
+export type Ecosystem = 'claude' | 'claude-code' | 'cursor' | 'chatgpt' | 'codex' | 'copilot' | 'antigravity' | 'gemini' | 'opencode' | 'windsurf';
 export declare const SUPPORTED_ECOSYSTEMS: Ecosystem[];
 export declare function autoDetectSourceEcosystem(skillRoot: string): Ecosystem | null;
 export declare function ecosystemDestination(eco: Ecosystem, slug: string): string;

package/dist/lib/canonical.js

@@ -1,12 +1,31 @@
 import fs from 'node:fs';
 import path from 'node:path';
-export const SUPPORTED_ECOSYSTEMS = ['claude', 'claude-code', 'cursor', 'chatgpt', 'codex'];
+export const SUPPORTED_ECOSYSTEMS = [
+    'claude',
+    'claude-code',
+    'cursor',
+    'chatgpt',
+    'codex',
+    'copilot',
+    'antigravity',
+    'gemini',
+    'opencode',
+    'windsurf',
+];
+// Source-of-truth for each path is documented in `ecosystemDestination`
+// below; this map only governs which on-disk directory we look at when
+// auto-detecting the source ecosystem of a skill.
 const ECOSYSTEM_FILE_GLOB = {
     claude: ['claude/SKILL.md'],
     'claude-code': ['claude-code/commands'],
     cursor: ['cursor/rules'],
     chatgpt: ['chatgpt'],
     codex: ['codex'],
+    copilot: ['copilot/instructions'],
+    antigravity: ['antigravity/skills'],
+    gemini: ['gemini/instructions'],
+    opencode: ['opencode/instructions'],
+    windsurf: ['windsurf/rules'],
 };
 function readSize(filePath) {
     if (!fs.existsSync(filePath))
@@ -50,6 +69,29 @@ export function ecosystemDestination(eco, slug) {
             return `chatgpt/${slug}.md`;
         case 'codex':
             return `codex/${slug}.md`;
+        case 'copilot':
+            // GitHub Copilot custom instructions:
+            // https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot
+            return `copilot/instructions/${slug}.instructions.md`;
+        case 'antigravity':
+            // Google Antigravity skills live under the gemini config tree at
+            // ~/.gemini/antigravity/skills/<slug>.md — see install destination in
+            // `auto-detect.ts`. The source mirror is `antigravity/skills/<slug>.md`.
+            return `antigravity/skills/${slug}.md`;
+        case 'gemini':
+            // Gemini CLI reads markdown instructions from ~/.gemini/instructions/
+            // (https://github.com/google-gemini/gemini-cli). Source path mirrors
+            // the install destination.
+            return `gemini/instructions/${slug}.md`;
+        case 'opencode':
+            // OpenCode (SST) reads markdown instructions from
+            // ~/.config/opencode/instructions/ (https://github.com/sst/opencode).
+            return `opencode/instructions/${slug}.md`;
+        case 'windsurf':
+            // Windsurf (Codeium) project rules:
+            // https://docs.codeium.com/windsurf/cascade#windsurfrules — files live
+            // under .codeium/windsurf-rules/ in each project.
+            return `windsurf/rules/${slug}.md`;
     }
 }
 export function readSourceContent(skillRoot, sourceEcosystem, slug) {

package/dist/lib/config.d.ts

@@ -1,5 +1,12 @@
+/** Persistent CLI credentials.
+ *
+ * `token` is an opaque api_tokens value (bd_<hex>) issued by the web app —
+ * either via /settings/tokens or via the browser-mediated /cli-auth flow.
+ * Earlier CLI versions stored a GitHub access token under `githubToken`; that
+ * field is gone and any stale auth.json file will be ignored (the server
+ * 401s and the user is told to run `botdocs login` again). */
 interface AuthConfig {
-    githubToken: string;
+    token: string;
     username: string;
     displayName: string;
     syncLibrary?: boolean;

package/dist/lib/config.js

@@ -1,22 +1,30 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-const CONFIG_DIR = path.join(os.homedir(), '.botdocs');
-const AUTH_FILE = path.join(CONFIG_DIR, 'auth.json');
+// Resolved lazily so tests can swap os.homedir between cases without having
+// to monkey-patch a captured constant.
+function getConfigDir() {
+    return path.join(os.homedir(), '.botdocs');
+}
+function getAuthFile() {
+    return path.join(getConfigDir(), 'auth.json');
+}
 function ensureConfigDir() {
-    if (!fs.existsSync(CONFIG_DIR)) {
-        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    const dir = getConfigDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
     }
 }
 export function saveAuth(config) {
     ensureConfigDir();
-    fs.writeFileSync(AUTH_FILE, JSON.stringify(config, null, 2), 'utf-8');
+    fs.writeFileSync(getAuthFile(), JSON.stringify(config, null, 2), 'utf-8');
 }
 export function loadAuth() {
-    if (!fs.existsSync(AUTH_FILE))
+    const file = getAuthFile();
+    if (!fs.existsSync(file))
         return null;
     try {
-        const data = fs.readFileSync(AUTH_FILE, 'utf-8');
+        const data = fs.readFileSync(file, 'utf-8');
         return JSON.parse(data);
     }
     catch {
@@ -24,7 +32,8 @@ export function loadAuth() {
     }
 }
 export function clearAuth() {
-    if (fs.existsSync(AUTH_FILE)) {
-        fs.unlinkSync(AUTH_FILE);
+    const file = getAuthFile();
+    if (fs.existsSync(file)) {
+        fs.unlinkSync(file);
     }
 }

package/dist/lib/lockfile.d.ts

@@ -11,6 +11,15 @@ export interface InstalledRef {
     files: InstalledFile[];
     /** For bundles: the refs they expanded into. */
     skills?: string[];
+    /** Where this install came from. Defaults to a personal install when absent.
+     * Used by `botdocs sync` to identify team-pinned skills (which are managed
+     * by the team and may be pinned to a specific version). */
+    source?: {
+        type: 'personal';
+    } | {
+        type: 'team';
+        slug: string;
+    };
 }
 export interface Lockfile {
     version: 1;

package/dist/lib/prompts.d.ts

@@ -1,5 +1,15 @@
 export type CleanUpdateChoice = 'apply' | 'skip' | 'diff';
+/** Prompt for a clean-update decision (upstream has new content; local is
+ * unchanged since last install). The "diff" option lets the user inspect the
+ * change before deciding; callers should loop on "diff" themselves. */
 export declare function promptCleanUpdate(label: string): Promise<CleanUpdateChoice>;
 export type ConflictChoice = 'skip' | 'overwrite';
+/** Prompt for a conflict resolution when local has diverged from the
+ * lockfile fingerprint AND upstream has new content. Distinct from
+ * `promptCleanUpdate` because the user's edits are at risk; the destructive
+ * option ("overwrite") is gated behind `confirmOverwrite` below. */
 export declare function promptConflict(label: string): Promise<ConflictChoice>;
+/** Second confirmation for destructive overwrites — the user has already said
+ * "overwrite" via `promptConflict`, but we want a y/N before clobbering their
+ * edits. Defaults to false so a stray Enter doesn't blow away work. */
 export declare function confirmOverwrite(label: string): Promise<boolean>;