@botdocs/cli 0.2.0 → 0.3.0

package/dist/commands/edit.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { input, select } from '@inquirer/prompts';
+import { ApiError, apiFetch, fetchRawContent } from '../lib/api.js';
+import { complete, detectProvider, LlmError } from '../lib/llm.js';
+import { renderDiff } from '../lib/diff.js';
+const TEMPLATES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates', 'ecosystem-prompts');
+function loadEditPrompt() {
+    return fs.readFileSync(path.join(TEMPLATES_DIR, 'edit.md'), 'utf-8');
+}
+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}`);
+    return { username: parts[0], slug: parts[1] };
+}
+function fileForEcosystem(files, eco) {
+    if (eco === 'claude')
+        return files.find((f) => f.filename === 'claude/SKILL.md');
+    if (eco === 'claude-code')
+        return files.find((f) => f.filename.startsWith('claude-code/commands/'));
+    if (eco === 'cursor')
+        return files.find((f) => f.filename.startsWith('cursor/rules/'));
+    if (eco === 'chatgpt')
+        return files.find((f) => f.filename.startsWith('chatgpt/'));
+    if (eco === 'codex')
+        return files.find((f) => f.filename.startsWith('codex/'));
+    return undefined;
+}
+export async function edit(rawRef, options) {
+    const ref = parseRef(rawRef);
+    try {
+        detectProvider({ keyEnv: options.keyEnv });
+    }
+    catch (err) {
+        if (err instanceof LlmError) {
+            console.error(`\n  ✗ ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    let manifest;
+    try {
+        manifest = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/manifest`);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+            console.error(`\n  ✗ Skill not found: @${ref.username}/${ref.slug}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    if (manifest.type !== 'SKILL') {
+        console.error('\n  ✗ Edit only works on skills (not bundles).\n');
+        process.exit(1);
+    }
+    const target = fileForEcosystem(manifest.files, options.ecosystem);
+    if (!target) {
+        console.error(`\n  ✗ No file found for ecosystem "${options.ecosystem}".\n`);
+        process.exit(1);
+    }
+    console.log(`  ✓ Pulled ${target.filename}`);
+    const currentContent = await fetchRawContent(target.rawUrl);
+    const userRequest = await input({ message: 'What change would you like to make?' });
+    if (!userRequest.trim()) {
+        console.error('\n  ✗ No request provided. Aborting.\n');
+        process.exit(1);
+    }
+    const system = loadEditPrompt();
+    const prompt = `CURRENT FILE:\n\n${currentContent}\n\nUSER REQUEST:\n${userRequest}`;
+    let revised;
+    while (true) {
+        const resp = await complete({ system, prompt, keyEnv: options.keyEnv });
+        if (resp.text.startsWith('EDIT_IMPOSSIBLE')) {
+            console.error(`\n  ✗ ${resp.text}\n`);
+            process.exit(1);
+        }
+        revised = resp.text;
+        console.log(renderDiff(currentContent, revised));
+        const choice = await select({
+            message: 'Apply revision?',
+            choices: [
+                { name: 'accept (push as draft to BotDocs)', value: 'accept' },
+                { name: 'regenerate', value: 'regenerate' },
+                { name: 'cancel', value: 'cancel' },
+            ],
+        });
+        if (choice === 'cancel') {
+            console.log('\n  Cancelled. No changes pushed.\n');
+            return;
+        }
+        if (choice === 'accept')
+            break;
+        // else regenerate — loop
+    }
+    await apiFetch(`/api/skills/${ref.username}/${ref.slug}/draft`, {
+        method: 'POST',
+        auth: true,
+        body: { ecosystem: options.ecosystem, content: revised },
+    });
+    console.log(`\n  ✓ Pushed draft for ${rawRef} (${options.ecosystem}).`);
+    console.log(`    Visit https://botdocs.ai/@${ref.username}/${ref.slug} to publish.\n`);
+}

package/dist/commands/edit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/edit.test.js

@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { edit } from './edit.js';
+import { captureConsole, mockFetch } from '../test-utils.js';
+import { saveAuth } from '../lib/config.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+vi.mock('../lib/llm.js', () => ({
+    complete: vi.fn(),
+    detectProvider: vi.fn(() => ({ provider: 'anthropic', keyEnv: 'BOTDOCS_ANTHROPIC_KEY' })),
+    LlmError: class extends Error {
+    },
+}));
+vi.mock('@inquirer/prompts', () => ({
+    input: vi.fn(),
+    select: vi.fn(),
+}));
+import * as llm from '../lib/llm.js';
+import * as inquirer from '@inquirer/prompts';
+describe('edit', () => {
+    let captured;
+    let restoreFetch = () => { };
+    const origHome = os.homedir;
+    let homeTmp;
+    beforeEach(() => {
+        homeTmp = fs.mkdtempSync(path.join(os.tmpdir(), 'edit-'));
+        os.homedir = () => homeTmp;
+        captured = captureConsole();
+        process.env.BOTDOCS_API_URL = 'http://test.local';
+        process.env.BOTDOCS_ANTHROPIC_KEY = 'test';
+        saveAuth({ githubToken: 't', username: 'u', displayName: 'U' });
+    });
+    afterEach(() => {
+        captured.restore();
+        restoreFetch();
+        fs.rmSync(homeTmp, { recursive: true, force: true });
+        os.homedir = origHome;
+        vi.restoreAllMocks();
+        delete process.env.BOTDOCS_ANTHROPIC_KEY;
+    });
+    it('round-trips: pulls, prompts user, calls LLM, pushes draft on accept', async () => {
+        const fm = mockFetch([
+            {
+                url: '/api/skills/alice/code-review/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'alice', slug: 'code-review' },
+                        type: 'SKILL',
+                        version: '1.0.0',
+                        sourceEcosystem: 'claude-code',
+                        files: [
+                            { filename: 'cursor/rules/code-review.mdc', rawUrl: 'http://test.local/raw/cursor' },
+                            { filename: 'claude-code/commands/code-review.md', rawUrl: 'http://test.local/raw/source' },
+                        ],
+                    },
+                },
+            },
+            { url: '/raw/cursor', response: { body: '# Original cursor rule\n', contentType: 'text/plain' } },
+            { method: 'POST', url: '/api/skills/alice/code-review/draft', response: { body: { ok: true } } },
+        ]);
+        restoreFetch = fm.restore;
+        vi.mocked(inquirer.input).mockResolvedValue('Add a section about tests');
+        vi.mocked(inquirer.select).mockResolvedValue('accept');
+        vi.mocked(llm.complete).mockResolvedValue({
+            text: '# Original cursor rule\n\n## Tests\n',
+            usage: { inputTokens: 100, outputTokens: 50 },
+            provider: 'anthropic',
+        });
+        await edit('@alice/code-review', { ecosystem: 'cursor' });
+        const draftCall = fm.calls.find((c) => c.url.endsWith('/draft'));
+        expect(draftCall).toBeDefined();
+        expect(draftCall.body.ecosystem).toBe('cursor');
+    });
+    it('cancels without pushing when user picks cancel', async () => {
+        const fm = mockFetch([
+            {
+                url: '/api/skills/alice/x/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'alice', slug: 'x' },
+                        type: 'SKILL',
+                        version: '1.0.0',
+                        sourceEcosystem: 'claude',
+                        files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/c' }],
+                    },
+                },
+            },
+            { url: '/raw/c', response: { body: 'orig', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        vi.mocked(inquirer.input).mockResolvedValue('change something');
+        vi.mocked(inquirer.select).mockResolvedValue('cancel');
+        vi.mocked(llm.complete).mockResolvedValue({
+            text: 'new',
+            usage: { inputTokens: 10, outputTokens: 5 },
+            provider: 'anthropic',
+        });
+        await edit('@alice/x', { ecosystem: 'claude' });
+        const draftCall = fm.calls.find((c) => c.url.endsWith('/draft'));
+        expect(draftCall).toBeUndefined();
+    });
+});

package/dist/commands/ingest.d.ts

@@ -0,0 +1,7 @@
+interface IngestOptions {
+    bundle?: string;
+    dryRun?: boolean;
+    json?: boolean;
+}
+export declare function ingest(rootPath: string, options: IngestOptions): Promise<void>;
+export {};

package/dist/commands/ingest.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { apiFetch } from '../lib/api.js';
+const IGNORED_DIRS = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.turbo']);
+function walkFiles(root) {
+    const out = [];
+    function walk(dir) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                    continue;
+                walk(path.join(dir, entry.name));
+            }
+            else {
+                out.push(path.join(dir, entry.name));
+            }
+        }
+    }
+    walk(root);
+    return out;
+}
+function detectFile(absPath, root, content) {
+    const rel = path.relative(root, absPath).split(path.sep).join('/');
+    if (rel.startsWith('claude/') && rel.endsWith('/SKILL.md')) {
+        return { filename: rel, content, ecosystem: 'claude' };
+    }
+    if (rel.startsWith('claude-code/commands/') && rel.endsWith('.md')) {
+        return { filename: rel, content, ecosystem: 'claude-code' };
+    }
+    if (rel.startsWith('cursor/rules/') && rel.endsWith('.mdc')) {
+        return { filename: rel, content, ecosystem: 'cursor' };
+    }
+    if (rel.startsWith('chatgpt/') && rel.endsWith('.md')) {
+        return { filename: rel, content, ecosystem: 'chatgpt' };
+    }
+    return null;
+}
+/** Returns the slug for a detected file by stripping ecosystem path prefix and extension. */
+function slugFor(file) {
+    if (file.ecosystem === 'claude') {
+        const dirs = file.filename.split('/');
+        return dirs[1] ?? 'untitled';
+    }
+    return path.basename(file.filename).replace(/\.(md|mdc)$/, '');
+}
+function titleFromContent(content, slug) {
+    const m = content.match(/^#\s+(.+)$/m);
+    return m?.[1]?.trim() ?? slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+export async function ingest(rootPath, options) {
+    const root = path.resolve(rootPath);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        console.error(`\n  ✗ Not a directory: ${rootPath}\n`);
+        process.exit(1);
+    }
+    const detected = [];
+    for (const filePath of walkFiles(root)) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const d = detectFile(filePath, root, content);
+        if (d)
+            detected.push(d);
+    }
+    if (detected.length === 0) {
+        console.log('\n  No skills detected. Looked for: claude/, claude-code/commands/, cursor/rules/, chatgpt/.\n');
+        return;
+    }
+    // Group into logical skills by slug
+    const grouped = new Map();
+    for (const f of detected) {
+        const slug = slugFor(f);
+        if (!grouped.has(slug)) {
+            grouped.set(slug, {
+                slug,
+                title: titleFromContent(f.content, slug),
+                description: '',
+                sourceEcosystem: f.ecosystem,
+                files: [],
+            });
+        }
+        grouped.get(slug).files.push({ filename: f.filename, content: f.content });
+    }
+    const skills = [...grouped.values()];
+    console.log(`\n  ✓ Found ${skills.length} skill(s):`);
+    for (const s of skills) {
+        console.log(`    • ${s.slug} (${s.files.length} file(s))`);
+    }
+    if (options.dryRun) {
+        console.log('\n  --dry-run: not uploading.\n');
+        return;
+    }
+    const result = await apiFetch('/api/cli/ingest', {
+        method: 'POST',
+        auth: true,
+        body: { skills, bundle: options.bundle ? { name: options.bundle } : undefined },
+    });
+    if (options.json) {
+        console.log(JSON.stringify(result));
+        return;
+    }
+    console.log(`\n  ✓ Drafts created. Review at:\n    https://botdocs.ai${result.reviewUrl}\n`);
+}

package/dist/commands/ingest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/ingest.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ingest } from './ingest.js';
+import { captureConsole, mockFetch, withTempDir } from '../test-utils.js';
+vi.mock('../lib/config.js', () => ({
+    loadAuth: () => ({ githubToken: 'test-token', username: 'alice', displayName: 'Alice' }),
+    saveAuth: vi.fn(),
+    clearAuth: vi.fn(),
+}));
+describe('ingest', () => {
+    let tmp;
+    let captured;
+    let restoreFetch = () => { };
+    beforeEach(() => {
+        tmp = withTempDir();
+        process.env.BOTDOCS_API_URL = 'http://test.local';
+        captured = captureConsole();
+    });
+    afterEach(() => {
+        restoreFetch();
+        captured.restore();
+        tmp.cleanup();
+        vi.restoreAllMocks();
+    });
+    it('detects skills from claude/cursor/claude-code subtrees and POSTs them', async () => {
+        const root = path.join(tmp.dir, 'skills');
+        fs.mkdirSync(path.join(root, 'claude', 'code-review'), { recursive: true });
+        fs.mkdirSync(path.join(root, 'cursor', 'rules'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'claude', 'code-review', 'SKILL.md'), '# Code Review\n\nA spec.');
+        fs.writeFileSync(path.join(root, 'cursor', 'rules', 'pr-summary.mdc'), '# PR Summary\n\nA rule.');
+        const fm = mockFetch([
+            {
+                method: 'POST',
+                url: '/api/cli/ingest',
+                response: { body: { draftId: 'd1', reviewUrl: '/ingest/d1' } },
+            },
+        ]);
+        restoreFetch = fm.restore;
+        await ingest(root, {});
+        expect(fm.calls).toHaveLength(1);
+        const body = fm.calls[0].body;
+        const slugs = body.skills.map((s) => s.slug).sort();
+        expect(slugs).toEqual(['code-review', 'pr-summary']);
+        expect(captured.stdout.join('\n')).toMatch(/d1/);
+    });
+    it('respects --bundle to wrap skills into a bundle draft', async () => {
+        const root = path.join(tmp.dir, 'skills');
+        fs.mkdirSync(path.join(root, 'claude', 'code-review'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'claude', 'code-review', 'SKILL.md'), '# CR');
+        const fm = mockFetch([
+            { method: 'POST', url: '/api/cli/ingest', response: { body: { draftId: 'd2', reviewUrl: '/ingest/d2' } } },
+        ]);
+        restoreFetch = fm.restore;
+        await ingest(root, { bundle: 'Eng Skills' });
+        const body = fm.calls[0].body;
+        expect(body.bundle?.name).toBe('Eng Skills');
+    });
+    it('--dry-run prints findings without uploading', async () => {
+        const root = path.join(tmp.dir, 'skills');
+        fs.mkdirSync(path.join(root, 'claude', 'code-review'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'claude', 'code-review', 'SKILL.md'), '# CR');
+        const fm = mockFetch([]);
+        restoreFetch = fm.restore;
+        await ingest(root, { dryRun: true });
+        expect(fm.calls).toHaveLength(0);
+        expect(captured.stdout.join('\n')).toMatch(/code-review/);
+    });
+    it('skips node_modules, .git, dist, and other well-known ignored directories', async () => {
+        const root = path.join(tmp.dir, 'project');
+        // A real skill we want detected
+        fs.mkdirSync(path.join(root, 'claude', 'real'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'claude', 'real', 'SKILL.md'), '# Real');
+        // node_modules + dist + .git with planted skill files that MUST be ignored
+        fs.mkdirSync(path.join(root, 'node_modules', 'claude', 'fake'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'node_modules', 'claude', 'fake', 'SKILL.md'), '# Fake');
+        fs.mkdirSync(path.join(root, '.git', 'claude', 'fake'), { recursive: true });
+        fs.writeFileSync(path.join(root, '.git', 'claude', 'fake', 'SKILL.md'), '# Fake');
+        fs.mkdirSync(path.join(root, 'dist', 'claude', 'fake'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'dist', 'claude', 'fake', 'SKILL.md'), '# Fake');
+        const fm = mockFetch([
+            { method: 'POST', url: '/api/cli/ingest', response: { body: { draftId: 'd', reviewUrl: '/ingest/d' } } },
+        ]);
+        restoreFetch = fm.restore;
+        await ingest(root, {});
+        const body = fm.calls[0].body;
+        expect(body.skills.map((s) => s.slug)).toEqual(['real']);
+    });
+    it('groups multi-ecosystem files under the same slug into one logical skill', async () => {
+        // A skill named "code-review" has both a Claude SKILL.md and a Cursor rule.
+        // Without grouping these, the test ingest would POST 2 skills with the same slug
+        // and one would silently win in the DB.
+        const root = path.join(tmp.dir, 'skills');
+        fs.mkdirSync(path.join(root, 'claude', 'code-review'), { recursive: true });
+        fs.mkdirSync(path.join(root, 'cursor', 'rules'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'claude', 'code-review', 'SKILL.md'), '# Code Review\n\nClaude version.');
+        fs.writeFileSync(path.join(root, 'cursor', 'rules', 'code-review.mdc'), '# Code Review\n\nCursor version.');
+        const fm = mockFetch([
+            { method: 'POST', url: '/api/cli/ingest', response: { body: { draftId: 'd', reviewUrl: '/ingest/d' } } },
+        ]);
+        restoreFetch = fm.restore;
+        await ingest(root, {});
+        const body = fm.calls[0].body;
+        // The two files should collapse into ONE skill named code-review with both files
+        const codeReview = body.skills.find((s) => s.slug === 'code-review');
+        expect(codeReview).toBeDefined();
+        expect(codeReview.files).toHaveLength(2);
+    });
+});

package/dist/commands/init.d.ts

@@ -2,6 +2,7 @@ interface InitOptions {
     title?: string;
     category?: string;
     json?: boolean;
+    canonical?: boolean;
 }
 export declare function init(dirName: string | undefined, options: InitOptions): Promise<void>;
 export {};

package/dist/commands/init.js

@@ -1,5 +1,6 @@
 import { writeFileSync, mkdirSync, existsSync } from 'fs';
-import { join } from 'path';
+import { dirname, join } from 'path';
+import { relative } from 'node:path';
 export async function init(dirName, options) {
     const name = dirName || 'my-botdoc';
     const dir = join(process.cwd(), name);
@@ -14,6 +15,38 @@ export async function init(dirName, options) {
     }
     mkdirSync(dir, { recursive: true });
     const title = options.title || name.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+    if (options.canonical) {
+        const sourceFile = join(dir, 'claude-code', 'commands', `${name}.md`);
+        mkdirSync(dirname(sourceFile), { recursive: true });
+        writeFileSync(sourceFile, `# ${title}\n\n## Overview\n\nDescribe the skill.\n`, 'utf-8');
+        const manifest = {
+            type: 'skill',
+            version: '1.0.0',
+            title,
+            description: '',
+            sourceEcosystem: 'claude-code',
+            ecosystems: ['claude', 'claude-code', 'cursor', 'chatgpt'],
+            license: 'MIT',
+        };
+        writeFileSync(join(dir, 'botdocs.json'), JSON.stringify(manifest, null, 2), 'utf-8');
+        if (options.json) {
+            console.log(JSON.stringify({
+                success: true,
+                directory: name,
+                files: [relative(dir, sourceFile), 'botdocs.json'],
+                canonical: true,
+            }));
+        }
+        else {
+            console.log(`\n  Created ${name}/`);
+            console.log(`    claude-code/commands/${name}.md  — your canonical source`);
+            console.log(`    botdocs.json                     — declares ecosystems to generate`);
+            console.log(`\n  Edit the source file, then:`);
+            console.log(`    botdocs compile ${name}/`);
+            console.log(`    botdocs publish ${name}/\n`);
+        }
+        return;
+    }
     const indexContent = `# ${title}
 
 ## Overview

package/dist/commands/install-instructions.d.ts

@@ -0,0 +1,8 @@
+interface InstallOptions {
+    print?: boolean;
+    json?: boolean;
+    shellHook?: boolean;
+    removeShellHook?: boolean;
+}
+export declare function installInstructions(target: string | undefined, options: InstallOptions): Promise<void>;
+export {};

package/dist/commands/install-instructions.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectShell, installShellHook, uninstallShellHook } from '../lib/shell-hook.js';
+/** Markers around the managed block so re-running the command updates the
+ * section in place instead of duplicating it. Anything outside the markers
+ * (the user's own content) is left untouched. */
+const BEGIN = '<!-- BEGIN @botdocs/cli -->';
+const END = '<!-- END @botdocs/cli -->';
+const TEMPLATES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates');
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function buildBlock() {
+    const template = fs.readFileSync(path.join(TEMPLATES_DIR, 'agents.md'), 'utf-8');
+    return `${BEGIN}\n${template.trim()}\n${END}\n`;
+}
+export async function installInstructions(target, options) {
+    if (options.removeShellHook) {
+        const shell = detectShell();
+        if (!shell) {
+            console.error('\n  ✗ Could not detect shell (set $SHELL).\n');
+            process.exit(1);
+        }
+        const result = uninstallShellHook(shell);
+        if (options.json) {
+            console.log(JSON.stringify({ removed: result.removed, path: result.path }));
+        }
+        else {
+            console.log(`\n  ${result.removed ? '✓ Removed' : 'No hook found in'} ${result.path}\n`);
+        }
+        return;
+    }
+    if (options.shellHook) {
+        const shell = detectShell();
+        if (!shell) {
+            console.error('\n  ✗ Could not detect shell (set $SHELL or use a supported shell: zsh, bash, fish).\n');
+            process.exit(1);
+        }
+        const result = installShellHook(shell);
+        if (options.json) {
+            console.log(JSON.stringify({ action: result.action, path: result.path, shell }));
+        }
+        else {
+            console.log(`\n  ✓ ${result.action === 'created' ? 'Created' : 'Updated'} shell hook at ${result.path}`);
+            console.log(`    Open a new terminal to start seeing update notices.\n`);
+        }
+        return;
+    }
+    const targetDir = path.resolve(target ?? '.');
+    const file = path.join(targetDir, 'AGENTS.md');
+    const block = buildBlock();
+    if (options.print) {
+        process.stdout.write(block);
+        return;
+    }
+    if (!fs.existsSync(targetDir)) {
+        console.error(`\n  ✗ Target directory does not exist: ${targetDir}\n`);
+        process.exit(1);
+    }
+    let action;
+    if (fs.existsSync(file)) {
+        const existing = fs.readFileSync(file, 'utf-8');
+        if (existing.includes(BEGIN) && existing.includes(END)) {
+            const re = new RegExp(`${escapeRegExp(BEGIN)}[\\s\\S]*?${escapeRegExp(END)}\\n?`);
+            const next = existing.replace(re, block);
+            fs.writeFileSync(file, next, 'utf-8');
+            action = 'updated';
+        }
+        else {
+            const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+            fs.writeFileSync(file, existing + sep + block, 'utf-8');
+            action = 'appended';
+        }
+    }
+    else {
+        fs.writeFileSync(file, block, 'utf-8');
+        action = 'created';
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ action, path: file }));
+        return;
+    }
+    const verb = { created: 'Created', updated: 'Updated', appended: 'Appended to' }[action];
+    console.log(`\n  ✓ ${verb} ${path.relative(process.cwd(), file)}`);
+    console.log(`    Any agent that reads AGENTS.md (Claude Code, Cursor, Codex, Copilot) will\n` +
+        `    now know how to use the botdocs CLI.\n`);
+}

package/dist/commands/install.d.ts

@@ -0,0 +1,8 @@
+interface InstallOptions {
+    project?: string;
+    flat?: boolean;
+    clean?: boolean;
+    json?: boolean;
+}
+export declare function install(rawRef: string, options: InstallOptions): Promise<void>;
+export {};