@botdocs/cli 0.3.2 → 0.4.0

package/README.md

@@ -1,11 +1,12 @@
 # botdocs
 
-The official CLI for [BotDocs](https://botdocs.ai) — clone, search,
-publish, and endorse concept specifications.
+The official CLI for [BotDocs](https://botdocs.ai) — author, publish,
+install, and sync agent skills.
 
-A BotDoc is a structured spec an AI agent can build from. This CLI is the
-fastest way to pull one onto your machine, ship one of your own, or report
-back after you've built something on top.
+BotDocs is the registry teams use to share agent skills across the
+agents their developers run (Claude Code, Cursor, Codex, ChatGPT). This
+CLI is the fastest way to install a team's skills, stay in sync, and
+publish your own.
 
 ## Install
 
@@ -30,54 +31,66 @@ Requires Node.js 20 or newer.
 ## Quick start
 
 ```bash
-# scaffold a new spec in ./my-spec/
-botdocs init my-spec
-
-# validate before publishing
-botdocs validate my-spec/
-
-# log in (GitHub device code, one time)
+# log in (opens your browser, sign in with any provider, one time)
 botdocs login
 
-# publish from a directory
-botdocs publish my-spec/
+# install a team's shared skills
+botdocs install @teamco/eng-skills
 
-# clone someone else's spec
-botdocs clone @alice/agent-router
+# stay in sync with your team
+botdocs sync
 
-# tell them how it went after you built from it
-botdocs endorse @alice/agent-router --rating positive \
-  --comment "Built a working POC in 40 minutes."
+# scaffold and publish your own skill
+botdocs init my-skill
+botdocs validate my-skill/
+botdocs publish my-skill/
 ```
 
 ## Commands
 
 | Command | Purpose |
 |---|---|
-| `init [name]` | Scaffold a new BotDoc directory (`--canonical` for a multi-ecosystem skill). |
+| `init [name]` | Scaffold a new skill directory (`--canonical` for a multi-ecosystem skill). |
 | `compile <path>` | Generate per-ecosystem skill drafts from a canonical source (BYOK). |
 | `edit <ref>` | LLM-assisted revision of a published skill ecosystem file (BYOK). |
 | `validate <source>` | Pre-publish structural check on a directory or file. |
-| `clone <user/slug>` | Download every file in a BotDoc to a local directory. |
 | `search <query>` | Search the public registry. |
 | `publish <source>` | Publish from a file, directory, or zip archive. |
-| `diff <user/slug>` | Preview remote changes before pulling. |
-| `pull <user/slug>` | Update a previously-cloned BotDoc. |
 | `install <ref>` | Install a skill or bundle (auto-detects destinations). |
 | `sync [ref]` | Check installed skills/bundles for updates and apply. |
 | `uninstall <ref>` | Remove an installed skill or bundle. |
 | `list` | Show installed skills and bundles. |
 | `ingest <path>` | Walk a directory, detect existing skills, upload as drafts. |
-| `endorse <user/slug>` | Rate a BotDoc after you've built from it (requires a prior clone). |
+| `team list` / `show` / `create` / `add` / `remove` / `push` / `unpush` | Manage teams: shared skill libraries for your org. |
+| `undo` | Restore the most recent backup run (reversible). |
+| `backups list` / `restore` / `diff` / `clear` | Browse, restore, diff, and prune backup runs. |
 | `check-updates` | Check installed refs for available updates (1h cached). |
 | `install-instructions [target]` | Write/refresh `AGENTS.md` (or install a shell hook with `--shell-hook`). |
-| `login` | Authenticate via the GitHub device-code flow (`--sync-library` enables `/library`). |
+| `login` | Authenticate by opening your browser; pass `--token bd_xxx` for headless/CI (`--sync-library` enables `/library`). |
 | `whoami` | Show the currently authenticated user. |
 
 Every command accepts `--json` for machine-readable output.
 
 Run `botdocs <command> --help` for full flags on any command.
 
+## Look & feel
+
+`botdocs login` and `botdocs sync` are interactive and live by default — a
+cyan-to-violet gradient brand mark, an animated polling spinner, and
+per-file status rows that update in place. The CLI auto-detects when it's
+running in a real terminal vs. a piped/CI environment and renders the
+right thing without any flags. If you prefer plain output even on a TTY
+(screen-reader friendly, or just calmer), pass `--no-ink` to either
+command:
+
+```bash
+botdocs login --no-ink
+botdocs sync --no-ink
+```
+
+`botdocs sync --json` keeps emitting the same machine-readable JSON it
+always has — it never touches the Ink renderer.
+
 ## Configuration
 
 | Variable | Default | Purpose |
@@ -85,7 +98,11 @@ Run `botdocs <command> --help` for full flags on any command.
 | `BOTDOCS_API_URL` | `https://botdocs.ai` | Override the registry API endpoint (useful for local development). |
 
 Auth is stored at `~/.botdocs/auth.json` after `botdocs login`. Delete it
-to log out.
+to log out. The default `botdocs login` opens your browser at
+`/cli-auth`, where you sign in with whichever provider you prefer
+(GitHub, Google, or email-OTP) and confirm the terminal session. For
+non-interactive environments, mint a token at `/settings/tokens` and
+run `botdocs login --token bd_xxx` instead.
 
 ## Teaching agents to use this CLI
 
@@ -150,7 +167,13 @@ botdocs init my-skill --canonical          # scaffolds claude-code source
 # edit claude-code/commands/my-skill.md
 
 botdocs compile my-skill/                  # generates claude/SKILL.md,
-                                            # cursor/rules/my-skill.mdc, etc.
+                                            # cursor/rules/my-skill.mdc,
+                                            # codex/my-skill.md,
+                                            # copilot/instructions/my-skill.instructions.md,
+                                            # windsurf/rules/my-skill.md,
+                                            # gemini/instructions/my-skill.md,
+                                            # antigravity/skills/my-skill.md,
+                                            # opencode/instructions/my-skill.md, etc.
 
 botdocs publish my-skill/                  # auto-compiles if stale; --no-compile to skip
 ```
@@ -168,6 +191,27 @@ botdocs edit @you/my-skill --ecosystem cursor
 Haiku) when set, otherwise fall back to `BOTDOCS_OPENAI_KEY`
 (GPT-4o mini). Use `--key-env <NAME>` to point at a different env var.
 
+## Teams
+
+A team is a curated library of skills shared across its members. Skills
+stay user-owned; teams *pin* skills to indicate "these are the ones we
+use." Members install/sync the pinned set automatically.
+
+```bash
+botdocs team create teamco --name "Team Co"          # admin-only side: create
+botdocs team add teamco @bob --role write            # add a member
+botdocs team push teamco @alice/eng-review-skill     # pin a skill (WRITE+)
+botdocs team push teamco @alice/eng --version 3      # pin to a specific version
+
+botdocs team list                                    # what teams am I in?
+botdocs team show teamco                             # members + pinned skills
+botdocs sync                                         # pulls personal + team pins
+```
+
+`botdocs sync` walks the team's pinned skills and installs/updates them
+locally, marking the lockfile entry with the team they came from. Pinning
+is curation, not access control — skills are public in v1.
+
 ## Skills + bundles
 
 Skills are bundles of files that ship to specific destinations on disk
@@ -190,22 +234,64 @@ botdocs sync
 `botdocs list` shows what you have installed; `botdocs uninstall <ref>`
 removes it.
 
-Authors who want to share their existing collection of skills run
-`botdocs ingest <path>` — the CLI walks the directory, detects each
-skill, and uploads them as drafts in your BotDocs account for review
-before publishing.
+### Safety: backups before overwrite
+
+`install` and `sync` will never silently clobber a hand-written file at
+a colliding destination. Before any overwrite of a file the lockfile
+doesn't claim as "ours and unchanged," the original is copied to a
+timestamped backup directory:
+
+- Project-scoped files → `<cwd>/.botdocs-backup/<ISO-ts>/<relative-path>`
+- Global-scoped files (e.g. `~/.claude/skills/...`) → `~/.botdocs/backup/<ISO-ts>/<flattened-path>`
 
-## Endorsing
+A single CLI invocation reuses the same `<ts>` folder, so all backups
+from one run live together. A one-line warning is printed to stdout
+for each backup taken. If the existing file matches a fingerprint we
+recorded — i.e. we wrote it ourselves and the user hasn't edited it
+since — no backup is taken (there's nothing to save). Backup failures
+(e.g. permission errors) print a warning but don't block the install.
 
-Endorsements are reserved for builders who actually used the spec — the
-server will reject an endorsement if it can't see a prior clone from the
-same account. If you hit that error the CLI will point you at:
+Pass `--no-backup` on `install` or `sync` to opt out — useful in CI
+where backups are noise.
+
+#### Undo and the `backups` surface
+
+Backups are reversible. If you realize an `install` or `sync` clobbered
+something you wanted to keep:
 
 ```bash
-botdocs clone @user/slug
+botdocs undo              # restore the most recent backup run
+botdocs undo --dry-run    # preview without writing
+botdocs undo --yes        # skip the confirm prompt (scripts)
 ```
 
-…build something on top, then come back and run `endorse`.
+Before writing the restored content, the CURRENT state at each path is
+itself backed up under a new timestamp — so `botdocs undo` is reversible.
+Running it twice in a row swaps the state back. Pass `--no-backup` to
+skip the pre-backup (loses reversibility).
+
+For more granular control, the `backups` group browses, partial-restores,
+diffs, and prunes:
+
+```bash
+botdocs backups list                              # every run, newest first
+botdocs backups list <ts>                         # files in a specific run
+botdocs backups restore <ts>                      # restore the full run
+botdocs backups restore <ts> --files a.mdc,b.mdc  # restore a subset
+botdocs backups diff <ts> <relpath>               # diff backup vs current
+botdocs backups clear                             # delete all runs (confirm)
+botdocs backups clear --older-than 30d            # delete runs older than N days
+botdocs backups clear --dry-run                   # preview without deleting
+```
+
+Each backup run records a `manifest.json` sidecar mapping original→backup,
+so restoration is unambiguous even when global-scope filenames flatten
+ambiguously (e.g. paths containing `_`).
+
+Authors who want to share their existing collection of skills run
+`botdocs ingest <path>` — the CLI walks the directory, detects each
+skill, and uploads them as drafts in your BotDocs account for review
+before publishing.
 
 ## Development
 

package/dist/commands/backups.d.ts

@@ -0,0 +1,4 @@
+import { Command } from 'commander';
+import { type BackupRunSummary } from '../lib/backup.js';
+export declare function registerBackupCommands(program: Command): void;
+export type { BackupRunSummary };

package/dist/commands/backups.js

@@ -0,0 +1,291 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import * as p from '@clack/prompts';
+import { clearBackups, listBackupFiles, listBackupRuns, restoreBackup, } from '../lib/backup.js';
+import { hasChanges, renderDiff } from '../lib/diff.js';
+/** Show every backup run, newest first. */
+async function backupsList(timestamp, options) {
+    const projectRoot = process.cwd();
+    if (timestamp) {
+        // List files in a specific run.
+        const entries = listBackupFiles(timestamp, projectRoot);
+        if (options.json) {
+            console.log(JSON.stringify({ runTimestamp: timestamp, files: entries }));
+            return;
+        }
+        if (entries.length === 0) {
+            console.log(`\n  No backup run found with timestamp: ${timestamp}\n`);
+            return;
+        }
+        console.log(`\n  Backup run: ${timestamp}`);
+        console.log(`  Files: ${entries.length}\n`);
+        for (const e of entries) {
+            const rel = path.relative(projectRoot, e.originalPath) || e.originalPath;
+            console.log(`    [${e.scope}] ${rel}`);
+        }
+        console.log('');
+        return;
+    }
+    const runs = listBackupRuns(projectRoot);
+    if (options.json) {
+        console.log(JSON.stringify({ runs }));
+        return;
+    }
+    if (runs.length === 0) {
+        console.log('\n  No backup runs.\n');
+        return;
+    }
+    console.log('');
+    for (const r of runs) {
+        console.log(`  ${r.runTimestamp}  (${r.scope}, ${r.fileCount} file${r.fileCount === 1 ? '' : 's'})`);
+    }
+    console.log('');
+}
+/** Restore a specific backup run, optionally a subset via --files. */
+async function backupsRestore(timestamp, options) {
+    const projectRoot = process.cwd();
+    const entries = listBackupFiles(timestamp, projectRoot);
+    if (entries.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify({ restored: [], failed: [], preBackedUp: [], message: 'No such run.' }));
+        }
+        else {
+            console.log(`\n  No backup run found with timestamp: ${timestamp}\n`);
+        }
+        return;
+    }
+    const filters = options.files
+        ? options.files.split(',').map((f) => f.trim()).filter((f) => f.length > 0)
+        : undefined;
+    const targetCount = filters
+        ? entries.filter((e) => filters.some((f) => e.originalPath.endsWith(f))).length
+        : entries.length;
+    if (!options.json) {
+        const verb = options.dryRun ? 'Would restore' : 'Restore';
+        console.log(`\n  ${verb} ${targetCount} file(s) from ${timestamp}`);
+        if (!options.noBackup && !options.dryRun) {
+            console.log('  (current state will be backed up first — reversible)');
+        }
+        console.log('');
+    }
+    if (!options.dryRun && !options.yes && !options.json) {
+        const confirmed = await p.confirm({
+            message: `Restore ${targetCount} file(s) from ${timestamp}?`,
+            initialValue: false,
+        });
+        if (p.isCancel(confirmed) || !confirmed) {
+            console.log('  Cancelled.\n');
+            return;
+        }
+    }
+    const result = restoreBackup(timestamp, projectRoot, {
+        files: filters,
+        dryRun: options.dryRun,
+        noBackup: options.noBackup,
+    });
+    if (options.json) {
+        console.log(JSON.stringify({
+            runTimestamp: timestamp,
+            dryRun: options.dryRun ?? false,
+            restored: result.restored.map((e) => e.originalPath),
+            failed: result.failed.map((f) => ({ originalPath: f.entry.originalPath, error: f.error })),
+            preBackedUp: result.preBackedUp,
+        }));
+        return;
+    }
+    reportRestoreResult(result, projectRoot, options.dryRun ?? false);
+}
+function reportRestoreResult(result, projectRoot, dryRun) {
+    const verb = dryRun ? 'Would restore' : 'Restored';
+    console.log(`  ✓ ${verb} ${result.restored.length} file(s)`);
+    for (const e of result.restored) {
+        const rel = path.relative(projectRoot, e.originalPath) || e.originalPath;
+        console.log(`    ${rel}`);
+    }
+    if (result.failed.length > 0) {
+        console.log(`\n  ⚠ ${result.failed.length} file(s) failed:`);
+        for (const f of result.failed) {
+            const rel = path.relative(projectRoot, f.entry.originalPath) || f.entry.originalPath;
+            console.log(`    ${rel}  (${f.error})`);
+        }
+    }
+    console.log('');
+}
+/** Heuristic: read the first 8 KB of a buffer and treat the presence of a NUL
+ * byte as "binary." Good enough for telling backup text files apart from
+ * compiled binaries. */
+function isBinary(buf) {
+    const limit = Math.min(buf.length, 8192);
+    for (let i = 0; i < limit; i++) {
+        if (buf[i] === 0)
+            return true;
+    }
+    return false;
+}
+/** Show a unified diff between the backup and the current on-disk file. */
+async function backupsDiff(timestamp, relpath, options) {
+    const projectRoot = process.cwd();
+    const entries = listBackupFiles(timestamp, projectRoot);
+    const entry = entries.find((e) => e.originalPath.endsWith(relpath));
+    if (!entry) {
+        if (options.json) {
+            console.log(JSON.stringify({ error: 'no matching file in backup run' }));
+        }
+        else {
+            console.log(`\n  No file matching "${relpath}" in run ${timestamp}\n`);
+        }
+        return;
+    }
+    if (!fs.existsSync(entry.backupPath)) {
+        if (options.json) {
+            console.log(JSON.stringify({ error: 'backup file missing on disk', backupPath: entry.backupPath }));
+        }
+        else {
+            console.log(`\n  Backup file missing on disk: ${entry.backupPath}\n`);
+        }
+        return;
+    }
+    const backupBuf = fs.readFileSync(entry.backupPath);
+    const currentBuf = fs.existsSync(entry.originalPath)
+        ? fs.readFileSync(entry.originalPath)
+        : Buffer.alloc(0);
+    if (isBinary(backupBuf) || isBinary(currentBuf)) {
+        if (options.json) {
+            console.log(JSON.stringify({
+                originalPath: entry.originalPath,
+                backupPath: entry.backupPath,
+                binary: true,
+                differs: !backupBuf.equals(currentBuf),
+            }));
+        }
+        else {
+            console.log(`\n  ${entry.originalPath}: differs (binary)\n`);
+        }
+        return;
+    }
+    const backupStr = backupBuf.toString('utf-8');
+    const currentStr = currentBuf.toString('utf-8');
+    if (options.json) {
+        console.log(JSON.stringify({
+            originalPath: entry.originalPath,
+            backupPath: entry.backupPath,
+            binary: false,
+            differs: hasChanges(currentStr, backupStr),
+        }));
+        return;
+    }
+    // Diff direction: show current → backup (i.e. what restoring would do).
+    console.log(`\n  ${entry.originalPath}\n`);
+    console.log(renderDiff(currentStr, backupStr));
+}
+/** Parse `--older-than 30d` → 30. Returns undefined when the flag isn't set. */
+function parseOlderThan(raw) {
+    if (!raw)
+        return undefined;
+    const m = raw.match(/^(\d+)\s*d?$/);
+    if (!m) {
+        throw new Error(`Invalid --older-than value: ${raw} (expected e.g. "30d" or "30")`);
+    }
+    return parseInt(m[1], 10);
+}
+async function backupsClear(options) {
+    const projectRoot = process.cwd();
+    let olderThanDays;
+    try {
+        olderThanDays = parseOlderThan(options.olderThan);
+    }
+    catch (err) {
+        if (options.json) {
+            console.log(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        }
+        else {
+            console.error(`\n  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        process.exit(1);
+    }
+    // First do a dry-run to see what's affected.
+    const preview = clearBackups(projectRoot, { olderThanDays, dryRun: true });
+    if (preview.cleared.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify({ cleared: [], kept: preview.kept }));
+        }
+        else {
+            console.log('\n  Nothing to clear.\n');
+        }
+        return;
+    }
+    if (!options.json) {
+        const verb = options.dryRun ? 'Would clear' : 'Clear';
+        console.log(`\n  ${verb} ${preview.cleared.length} backup run(s):`);
+        for (const r of preview.cleared) {
+            console.log(`    ${r.runTimestamp}  (${r.scope}, ${r.fileCount} file${r.fileCount === 1 ? '' : 's'})`);
+        }
+        console.log('');
+    }
+    if (options.dryRun) {
+        if (options.json) {
+            console.log(JSON.stringify({ dryRun: true, cleared: preview.cleared, kept: preview.kept }));
+        }
+        return;
+    }
+    // Double-confirm for destructive clears unless --yes. The "double" here is
+    // showing the list first AND requiring a y/N — printing the list makes the
+    // single prompt informed enough that a second prompt would be noise.
+    if (!options.yes && !options.json) {
+        const confirmed = await p.confirm({
+            message: `Permanently delete ${preview.cleared.length} backup run(s)?`,
+            initialValue: false,
+        });
+        if (p.isCancel(confirmed) || !confirmed) {
+            console.log('  Cancelled.\n');
+            return;
+        }
+    }
+    const result = clearBackups(projectRoot, { olderThanDays });
+    if (options.json) {
+        console.log(JSON.stringify({ cleared: result.cleared, kept: result.kept }));
+        return;
+    }
+    console.log(`  ✓ Cleared ${result.cleared.length} backup run(s).\n`);
+}
+export function registerBackupCommands(program) {
+    const backups = program
+        .command('backups')
+        .description('Browse, restore, diff, and clear backup runs from install/sync overwrites');
+    backups
+        .command('list [timestamp]')
+        .description('List backup runs newest first; with a timestamp, list files in that run')
+        .action(async (timestamp) => {
+        await backupsList(timestamp, { json: program.opts().json });
+    });
+    backups
+        .command('restore <timestamp>')
+        .description('Restore a backup run (or a subset with --files)')
+        .option('--files <list>', 'Comma-separated relpath suffixes to restore (default: all files in the run)')
+        .option('--dry-run', 'Show what would be restored without writing')
+        .option('--yes', 'Skip the confirmation prompt')
+        .option('--no-backup', 'Skip backing up the current state before restoring (advanced)')
+        .action(async (timestamp, opts) => {
+        const { backup, ...rest } = opts;
+        await backupsRestore(timestamp, {
+            ...rest,
+            noBackup: backup === false,
+            json: program.opts().json,
+        });
+    });
+    backups
+        .command('diff <timestamp> <relpath>')
+        .description('Show a diff between the backup and the current file')
+        .action(async (timestamp, relpath) => {
+        await backupsDiff(timestamp, relpath, { json: program.opts().json });
+    });
+    backups
+        .command('clear')
+        .description('Delete backup runs (all, or filtered by age)')
+        .option('--older-than <duration>', 'Only clear runs older than this (e.g. "30d")')
+        .option('--dry-run', 'Show what would be cleared without deleting')
+        .option('--yes', 'Skip the confirmation prompt')
+        .action(async (opts) => {
+        await backupsClear({ ...opts, json: program.opts().json });
+    });
+}

package/dist/commands/edit.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { input, select } from '@inquirer/prompts';
+import * as p from '@clack/prompts';
 import { ApiError, apiFetch, fetchRawContent } from '../lib/api.js';
 import { complete, detectProvider, LlmError } from '../lib/llm.js';
 import { renderDiff } from '../lib/diff.js';
@@ -63,7 +63,15 @@ export async function edit(rawRef, options) {
     }
     console.log(`  ✓ Pulled ${target.filename}`);
     const currentContent = await fetchRawContent(target.rawUrl);
-    const userRequest = await input({ message: 'What change would you like to make?' });
+    const userRequestRaw = await p.text({
+        message: 'What change would you like to make?',
+        placeholder: 'e.g. "Add a section about testing"',
+    });
+    if (p.isCancel(userRequestRaw)) {
+        p.cancel('Edit cancelled.');
+        process.exit(0);
+    }
+    const userRequest = userRequestRaw;
     if (!userRequest.trim()) {
         console.error('\n  ✗ No request provided. Aborting.\n');
         process.exit(1);
@@ -79,15 +87,15 @@ export async function edit(rawRef, options) {
         }
         revised = resp.text;
         console.log(renderDiff(currentContent, revised));
-        const choice = await select({
+        const choice = await p.select({
             message: 'Apply revision?',
-            choices: [
-                { name: 'accept (push as draft to BotDocs)', value: 'accept' },
-                { name: 'regenerate', value: 'regenerate' },
-                { name: 'cancel', value: 'cancel' },
+            options: [
+                { value: 'accept', label: 'Accept (push as draft to BotDocs)' },
+                { value: 'regenerate', label: 'Regenerate' },
+                { value: 'cancel', label: 'Cancel' },
             ],
         });
-        if (choice === 'cancel') {
+        if (p.isCancel(choice) || choice === 'cancel') {
             console.log('\n  Cancelled. No changes pushed.\n');
             return;
         }

package/dist/commands/install.d.ts

@@ -3,6 +3,10 @@ interface InstallOptions {
     flat?: boolean;
     clean?: boolean;
     json?: boolean;
+    /** When true, skip backups before overwriting existing files. Intended for
+     * CI where backups are noise; default behavior backs up untracked or
+     * locally-edited files to `.botdocs-backup/<ts>/` before the overwrite. */
+    noBackup?: boolean;
 }
 export declare function install(rawRef: string, options: InstallOptions): Promise<void>;
 export {};

package/dist/commands/install.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { ApiError, apiFetch, fetchRawContent } from '../lib/api.js';
 import { detectDestination } from '../lib/auto-detect.js';
 import { fingerprintContent, fingerprintFile, loadLockfile, upsertInstall, } from '../lib/lockfile.js';
+import { backupFile, isLockfileOwnedAndUnchanged } from '../lib/backup.js';
 import { syncLibrary } from '../lib/library-sync.js';
 function parseRef(raw) {
     const cleaned = raw.startsWith('@') ? raw.slice(1) : raw;
@@ -25,16 +26,33 @@ function buildContext(scope, slug, options) {
 function ensureDir(filePath) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
 }
-async function downloadAndWrite(file, dest, options) {
+async function downloadAndWrite(file, dest, options, projectDir) {
     const content = await fetchRawContent(file.rawUrl);
     if (fs.existsSync(dest) && !options.clean) {
         const existingFp = fingerprintFile(dest);
         const tmpFp = fingerprintContent(content);
         if (existingFp === tmpFp) {
-            // Already present at same fingerprint — additive no-op.
+            // Already present at same fingerprint — additive no-op. No backup
+            // needed: we're about to write the same bytes anyway.
             return { src: file.filename, dest, fingerprint: existingFp };
         }
     }
+    // About to overwrite. If the existing file isn't something we own and
+    // haven't touched, take a backup first so a hand-written rule at a
+    // colliding path isn't silently lost.
+    if (fs.existsSync(dest) && !options.noBackup && !isLockfileOwnedAndUnchanged(dest)) {
+        const result = backupFile(dest, projectDir);
+        if (!options.json) {
+            if (result.ok) {
+                const relSrc = path.relative(process.cwd(), dest);
+                const relDest = path.relative(process.cwd(), result.dest);
+                console.log(`  ⚠ Backed up existing file: ${relSrc} → ${relDest}`);
+            }
+            else {
+                console.log(`  ⚠ Could not back up ${dest}: ${result.error} — proceeding with overwrite.`);
+            }
+        }
+    }
     ensureDir(dest);
     fs.writeFileSync(dest, content, 'utf-8');
     return { src: file.filename, dest, fingerprint: fingerprintFile(dest) };
@@ -54,7 +72,7 @@ async function installSkill(ref, manifest, options, scope) {
             }
             continue;
         }
-        const installed = await downloadAndWrite(file, detection.dest, options);
+        const installed = await downloadAndWrite(file, detection.dest, options, ctx.projectDir);
         if (installed)
             filesInstalled.push(installed);
     }

package/dist/commands/login.d.ts

@@ -1,5 +1,12 @@
 interface LoginOptions {
     syncLibrary?: boolean;
+    /** Skip the browser flow and store this token directly. Used for CI/headless
+     * environments where the user has already minted a token at /settings/tokens. */
+    token?: string;
+    /** Force the plain-text rendering path even on a real TTY. Useful for users
+     * who prefer screen-reader-friendly output, or anyone disturbed by live
+     * redraws. The non-TTY path is taken automatically when stdout is piped. */
+    noInk?: boolean;
 }
 export declare function login(options?: LoginOptions): Promise<void>;
 export {};