@botdocs/cli 0.12.2 → 0.13.0

package/dist/commands/edit.js

@@ -5,6 +5,8 @@ import * as p from '@clack/prompts';
 import { ApiError, apiFetch, fetchRawContent, friendlyApiErrorDetail } from '../lib/api.js';
 import { complete, detectProvider, LlmError } from '../lib/llm.js';
 import { renderDiff } from '../lib/diff.js';
+import { loadAuth } from '../lib/config.js';
+import { fileSetHash } from '../lib/proposals.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');
@@ -16,6 +18,17 @@ function parseRef(raw) {
         throw new Error(`Invalid ref: ${raw}`);
     return { username: parts[0], slug: parts[1] };
 }
+/** True when the logged-in user owns this skill. A skill ref's username IS the
+ * author's username (the registry resolves `@user/slug` by the author's
+ * handle), so ownership is a case-insensitive username match. Drives the
+ * branch between the author's lower-friction draft loop and the cross-author
+ * proposal lane. */
+function isOwnSkill(username) {
+    const me = loadAuth()?.username;
+    if (!me)
+        return false;
+    return me.toLowerCase() === username.toLowerCase();
+}
 function fileForEcosystem(files, eco) {
     if (eco === 'claude')
         return files.find((f) => f.filename === 'claude/SKILL.md');
@@ -113,11 +126,62 @@ export async function edit(rawRef, options) {
             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`);
+    // Ownership branch (design §7): the author's own skill keeps the
+    // lower-friction draft→publish loop; a skill owned by someone else routes
+    // through the proposal lane so the change lands in the author's review queue
+    // instead of clobbering their live files.
+    if (isOwnSkill(ref.username)) {
+        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`);
+        return;
+    }
+    await proposeEdit(ref, manifest, target.filename, currentContent, revised);
+}
+/**
+ * Queue an edited file as a proposal for the skill's author to review.
+ *
+ * A proposal replaces the skill's ENTIRE file set, so we fetch every live file
+ * and swap in the revised content for the one ecosystem file we edited. The
+ * `basedFileHash` is computed over the UNMODIFIED live set — it's the drift
+ * anchor the author's accept is checked against.
+ */
+async function proposeEdit(ref, manifest, targetFilename, targetCurrentContent, revised) {
+    // Build the live file set (filename + content). We already have the edited
+    // file's current content; fetch the rest.
+    const liveFiles = await Promise.all(manifest.files.map(async (f) => ({
+        filename: f.filename,
+        content: f.filename === targetFilename ? targetCurrentContent : await fetchRawContent(f.rawUrl),
+    })));
+    const basedFileHash = fileSetHash(liveFiles);
+    // The proposed set is the live set with the edited file's content replaced.
+    const proposedFiles = liveFiles.map((f, i) => ({
+        filename: f.filename,
+        content: f.filename === targetFilename ? revised : f.content,
+        sortOrder: i,
+    }));
+    try {
+        await apiFetch(`/api/skills/${ref.username}/${ref.slug}/proposals`, {
+            method: 'POST',
+            auth: true,
+            body: {
+                files: proposedFiles,
+                agentLabel: 'cli-edit',
+                basedFileHash,
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiError) {
+            console.error(`\n  ✗ @${ref.username}/${ref.slug}: ${friendlyApiErrorDetail(err, `@${ref.username}/${ref.slug}`)}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    console.log(`\n  ✓ Proposal queued for @${ref.username}/${ref.slug} (${targetFilename}).`);
+    console.log('    The skill author will review it before it goes live.\n');
 }

package/dist/commands/proposals.d.ts

@@ -0,0 +1,69 @@
+import { Command } from 'commander';
+interface ProposalsListOptions {
+    /** Filter by status: OPEN (default) | ACCEPTED | REJECTED | all. */
+    status?: string;
+    json?: boolean;
+}
+interface AcceptOptions {
+    /** The proposal id to accept. Required. */
+    id?: string;
+    json?: boolean;
+}
+interface SynthesizeOptions {
+    /** Changelog describing the merge, shown to the reviewing author. */
+    message?: string;
+    /** Self-reported agent identity (e.g. "nightly-synth"). UNTRUSTED server-side. */
+    agentLabel?: string;
+    /** Skip the interactive confirm (for cron / non-interactive use). */
+    yes?: boolean;
+    /** Env var holding the LLM key (passed through to `complete`). */
+    keyEnv?: string;
+    json?: boolean;
+}
+/**
+ * `botdocs proposals @user/slug [--status OPEN|ACCEPTED|REJECTED|all]` — list
+ * the proposals queued against a skill as a table (or `--json`).
+ *
+ * Authors see full metadata; non-author readers see the redacted status view
+ * (Q5: visibility without the ability to accept/reject).
+ */
+export declare function proposals(rawRef: string, options: ProposalsListOptions): Promise<void>;
+/**
+ * `botdocs proposals accept @user/slug --id X` — accept a proposal, publishing
+ * it as a new version. Author-only (the server 403s non-authors).
+ *
+ * Fetches the current version first so we can send `basedOnCurrentVersion` —
+ * the optimistic-concurrency anchor. If the skill moved since (a 409
+ * stale-base), we tell the user to re-review rather than silently clobbering.
+ */
+export declare function proposalsAccept(rawRef: string, options: AcceptOptions): Promise<void>;
+/**
+ * `botdocs proposals synthesize @user/slug` — merge a skill's OPEN proposals
+ * into ONE synthesis proposal for the author to review.
+ *
+ * Runs with a SYNTHESIZER token (a low-privilege principal the author minted,
+ * scoped to this skill). The synthesizer can ONLY read the skill's proposals
+ * and create a synthesis — it can never accept, publish, or edit. The author
+ * still reviews and approves the merge through the normal accept path.
+ *
+ * Steps:
+ *   1. List OPEN proposals (permitted for a scoped synthesizer).
+ *   2. Fetch each OPEN proposal's full contents + the skill's live file set
+ *      (the DETAIL endpoint returns both `files` and `currentFiles`).
+ *   3. Merge the live set + the N proposed sets into one file set via the LLM.
+ *   4. Preview the merge (live vs merged) and confirm unless `--yes`.
+ *   5. POST the synthesis with basedFileHash = fileSetHash(live files).
+ *
+ * A 409 `duplicate_synthesis` is treated as a NO-OP SUCCESS (exit 0): the same
+ * merge already exists OPEN, so an end-of-day cron re-running this is safe.
+ */
+export declare function proposalsSynthesize(rawRef: string, options: SynthesizeOptions): Promise<void>;
+/**
+ * Register the `proposals` command (list, default) and its `accept`
+ * subcommand on the program. Done in a registrar helper (like `team`/`backups`)
+ * so the nested `accept` subcommand lives in this file rather than inline in
+ * index.ts — keeping index.ts's top-level surface clean and the quickstart
+ * drift-check parser happy (it lists only the parent verb `proposals`).
+ */
+export declare function registerProposalsCommands(program: Command): void;
+export {};

package/dist/commands/proposals.js

@@ -0,0 +1,556 @@
+import * as p from '@clack/prompts';
+import { ApiError, apiFetch, friendlyApiErrorDetail, getApiUrl } from '../lib/api.js';
+import { loadAuth } from '../lib/config.js';
+import { parseRef } from '../lib/ref.js';
+import { fileSetHash } from '../lib/proposals.js';
+import { complete, detectProvider, LlmError } from '../lib/llm.js';
+import { renderDiff } from '../lib/diff.js';
+const VALID_STATUSES = new Set(['OPEN', 'ACCEPTED', 'REJECTED', 'all']);
+/** System prompt for the merge. The model receives the live file set and N
+ * proposed change-sets and must return ONE coherent merged file set as JSON. */
+const SYNTHESIZE_SYSTEM = `You merge multiple proposed edits to an agent-skill file set into ONE coherent result.
+
+You are given:
+1. The CURRENT (live) file set — the base every proposal was derived from.
+2. N PROPOSALS, each a full proposed file set (an alternative version of the same skill).
+
+Produce a SINGLE merged file set that incorporates the intent of every proposal
+without conflicting edits. Preserve content none of the proposals touched. When
+two proposals change the same region differently, reconcile them sensibly rather
+than dropping one. Do not invent files that no proposal introduced.
+
+Output ONLY a JSON object of this exact shape, no prose, no code fences:
+{"files":[{"filename":"<path>","content":"<full file content>"}, ...]}
+
+Every filename present in the CURRENT set (or added by a proposal) must appear
+exactly once in "files" with its full final content.`;
+/** Bail before any API call if the user isn't logged in. The LIST + accept
+ * endpoints both require auth (admitted for list, author for accept). */
+function requireAuth(options) {
+    if (loadAuth())
+        return;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, error: 'not logged in', hint: 'Run `botdocs login` first.' }));
+    }
+    else {
+        console.error('\n  ✗ Not logged in. Run `botdocs login` first.\n');
+    }
+    process.exit(1);
+}
+/**
+ * `botdocs proposals @user/slug [--status OPEN|ACCEPTED|REJECTED|all]` — list
+ * the proposals queued against a skill as a table (or `--json`).
+ *
+ * Authors see full metadata; non-author readers see the redacted status view
+ * (Q5: visibility without the ability to accept/reject).
+ */
+export async function proposals(rawRef, options) {
+    requireAuth(options);
+    let ref;
+    try {
+        ref = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(`\n  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const refStr = `@${ref.username}/${ref.slug}`;
+    const status = options.status;
+    if (status && !VALID_STATUSES.has(status)) {
+        console.error(`\n  ✗ Invalid --status "${status}". Use OPEN, ACCEPTED, REJECTED, or all.\n`);
+        process.exit(1);
+    }
+    const query = status ? `?status=${encodeURIComponent(status)}` : '';
+    let data;
+    try {
+        data = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/proposals${query}`, { auth: true });
+    }
+    catch (err) {
+        handleListError(err, refStr, options);
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(data));
+        return;
+    }
+    if (data.proposals.length === 0) {
+        const label = status && status !== 'all' ? status.toLowerCase() : 'open';
+        console.log(`\n  No ${label} proposals for ${refStr}.\n`);
+        return;
+    }
+    console.log(`\n  Proposals for ${refStr} (current v${data.currentVersion}):\n`);
+    printProposalsTable(data.proposals);
+    if (data.isAuthor) {
+        console.log(`\n  Accept one with: botdocs proposals accept ${refStr} --id <id>\n`);
+    }
+    else {
+        console.log('');
+    }
+}
+/** Render the proposals as an aligned table in `botdocs search`/`list` style. */
+function printProposalsTable(rows) {
+    const idWidth = Math.max(2, ...rows.map((r) => r.id.length));
+    const fromWidth = Math.max(4, ...rows.map((r) => proposerLabel(r).length));
+    const statusWidth = Math.max(6, ...rows.map((r) => r.status.length));
+    const header = [
+        'ID'.padEnd(idWidth),
+        'From'.padEnd(fromWidth),
+        'Status'.padEnd(statusWidth),
+        'Base'.padStart(5),
+        'Files',
+    ].join('  ');
+    console.log(`  ${header}`);
+    console.log(`  ${'-'.repeat(header.length)}`);
+    for (const r of rows) {
+        const row = [
+            r.id.padEnd(idWidth),
+            proposerLabel(r).padEnd(fromWidth),
+            r.status.padEnd(statusWidth),
+            `v${r.baseVersion}`.padStart(5),
+            String(r.fileNames.length),
+        ].join('  ');
+        console.log(`  ${row}`);
+    }
+}
+/** A short, server-derived "From" label. `trust` is authoritative (set
+ * server-side from source + author identity); the self-reported `agentLabel`
+ * is appended only as a hint, never as the trust signal itself. */
+function proposerLabel(r) {
+    const base = r.trust === 'author' ? 'you' : r.trust === 'synthesis' ? 'synthesis' : 'agent';
+    if (r.agentLabel && r.trust === 'agent')
+        return `${base} (${r.agentLabel})`;
+    return base;
+}
+/**
+ * `botdocs proposals accept @user/slug --id X` — accept a proposal, publishing
+ * it as a new version. Author-only (the server 403s non-authors).
+ *
+ * Fetches the current version first so we can send `basedOnCurrentVersion` —
+ * the optimistic-concurrency anchor. If the skill moved since (a 409
+ * stale-base), we tell the user to re-review rather than silently clobbering.
+ */
+export async function proposalsAccept(rawRef, options) {
+    requireAuth(options);
+    let ref;
+    try {
+        ref = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(`\n  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const refStr = `@${ref.username}/${ref.slug}`;
+    const id = options.id;
+    if (!id) {
+        console.error('\n  ✗ --id <proposalId> is required. Run `botdocs proposals ' + refStr + '` to list ids.\n');
+        process.exit(1);
+    }
+    // Read the current version so accept can send the stale-base anchor.
+    let currentVersion;
+    try {
+        const list = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/proposals?status=all`, { auth: true });
+        currentVersion = list.currentVersion;
+    }
+    catch (err) {
+        handleListError(err, refStr, options);
+        return;
+    }
+    let result;
+    try {
+        result = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/proposals/${id}`, {
+            method: 'PATCH',
+            auth: true,
+            body: { decision: 'accept', basedOnCurrentVersion: currentVersion },
+        });
+    }
+    catch (err) {
+        handleAcceptError(err, refStr, id, options);
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, ref: refStr, id, version: result.version }));
+        return;
+    }
+    console.log(`\n  ✓ Accepted proposal ${id} — published v${result.version} of ${refStr}.\n`);
+}
+/**
+ * `botdocs proposals synthesize @user/slug` — merge a skill's OPEN proposals
+ * into ONE synthesis proposal for the author to review.
+ *
+ * Runs with a SYNTHESIZER token (a low-privilege principal the author minted,
+ * scoped to this skill). The synthesizer can ONLY read the skill's proposals
+ * and create a synthesis — it can never accept, publish, or edit. The author
+ * still reviews and approves the merge through the normal accept path.
+ *
+ * Steps:
+ *   1. List OPEN proposals (permitted for a scoped synthesizer).
+ *   2. Fetch each OPEN proposal's full contents + the skill's live file set
+ *      (the DETAIL endpoint returns both `files` and `currentFiles`).
+ *   3. Merge the live set + the N proposed sets into one file set via the LLM.
+ *   4. Preview the merge (live vs merged) and confirm unless `--yes`.
+ *   5. POST the synthesis with basedFileHash = fileSetHash(live files).
+ *
+ * A 409 `duplicate_synthesis` is treated as a NO-OP SUCCESS (exit 0): the same
+ * merge already exists OPEN, so an end-of-day cron re-running this is safe.
+ */
+export async function proposalsSynthesize(rawRef, options) {
+    requireAuth(options);
+    let ref;
+    try {
+        ref = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(`\n  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const refStr = `@${ref.username}/${ref.slug}`;
+    // Fail fast if no LLM key is configured — the merge can't run without it.
+    try {
+        detectProvider({ keyEnv: options.keyEnv });
+    }
+    catch (err) {
+        if (err instanceof LlmError) {
+            console.error(`\n  ✗ ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    const base = `/api/skills/${ref.username}/${ref.slug}/proposals`;
+    // 1. List OPEN proposals (permitted for a scoped synthesizer).
+    let list;
+    try {
+        list = await apiFetch(`${base}?status=OPEN`, { auth: true });
+    }
+    catch (err) {
+        handleSynthesizeError(err, refStr, options);
+        return;
+    }
+    const openProposals = list.proposals.filter((pr) => pr.status === 'OPEN');
+    if (openProposals.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify({ ok: true, ref: refStr, skipped: 'no_open_proposals' }));
+        }
+        else {
+            console.log(`\n  No open proposals to synthesize for ${refStr}. Nothing to do.\n`);
+        }
+        return;
+    }
+    if (openProposals.length === 1) {
+        // A "merge" of one proposal is just that proposal — synthesizing adds no
+        // value and would only create a duplicate of the existing OPEN proposal.
+        if (options.json) {
+            console.log(JSON.stringify({ ok: true, ref: refStr, skipped: 'single_open_proposal' }));
+        }
+        else {
+            console.log(`\n  Only one open proposal for ${refStr}; nothing to merge. ` +
+                `The author can review it directly.\n`);
+        }
+        return;
+    }
+    // 2. Fetch each OPEN proposal's full contents + the live file set.
+    const sourceProposalIds = openProposals.map((pr) => pr.id);
+    let details;
+    try {
+        details = await Promise.all(sourceProposalIds.map((id) => apiFetch(`${base}/${encodeURIComponent(id)}`, { auth: true })));
+    }
+    catch (err) {
+        handleSynthesizeError(err, refStr, options);
+        return;
+    }
+    // The live file set (merge base) is identical across DETAIL responses; take
+    // the first. basedFileHash anchors the synthesis to this exact base — the
+    // server's accept-time drift guard checks against it.
+    const liveFiles = details[0].currentFiles.map((f) => ({
+        filename: f.filename,
+        content: f.content,
+    }));
+    const basedFileHash = fileSetHash(liveFiles);
+    if (!options.json) {
+        console.log(`\n  Merging ${openProposals.length} open proposals for ${refStr} (live v${list.currentVersion})…`);
+    }
+    // 3. Merge client-side via the LLM.
+    let merged;
+    try {
+        merged = await mergeProposals(liveFiles, details, options.keyEnv);
+    }
+    catch (err) {
+        if (err instanceof LlmError) {
+            console.error(`\n  ✗ ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // 4. Preview + confirm (unless --yes / --json non-interactive).
+    if (!options.json) {
+        printMergePreview(liveFiles, merged);
+    }
+    if (!options.yes && !options.json) {
+        const choice = await p.confirm({
+            message: `Submit this merge as a synthesis proposal for ${refStr}?`,
+        });
+        if (p.isCancel(choice) || !choice) {
+            console.log('\n  Cancelled. No synthesis submitted.\n');
+            return;
+        }
+    }
+    // 5. POST the synthesis.
+    let result;
+    try {
+        result = await apiFetch(`${base}/synthesize`, {
+            method: 'POST',
+            auth: true,
+            body: {
+                sourceProposalIds,
+                files: merged.map((f, i) => ({
+                    filename: f.filename,
+                    content: f.content,
+                    sortOrder: i,
+                })),
+                changelog: options.message,
+                agentLabel: options.agentLabel,
+                basedFileHash,
+            },
+        });
+    }
+    catch (err) {
+        handleSynthesizeError(err, refStr, options);
+        return;
+    }
+    // The author reviews + approves the synthesis — the synthesizer cannot
+    // publish anything itself. Print a review link (the author's #proposals tab).
+    const reviewUrl = `${getApiUrl()}/${refStr}`;
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            ref: refStr,
+            proposalId: result.proposalId,
+            status: result.status,
+            sourceProposalIds,
+            url: reviewUrl,
+        }));
+        return;
+    }
+    console.log(`\n  ✓ Synthesis proposal queued for ${refStr} (id ${result.proposalId}).`);
+    console.log(`    It merges ${sourceProposalIds.length} proposals into one.`);
+    console.log(`    The author reviews and approves it before anything goes live: ${reviewUrl}\n`);
+}
+/** Build the merge prompt from the live set + the proposal details, call the
+ * LLM, and parse its JSON output into a typed merged file set.
+ *
+ * Throws {@link LlmError} on an empty/unparseable response so the caller can
+ * surface a clean message rather than POSTing garbage. */
+async function mergeProposals(liveFiles, details, keyEnv) {
+    const prompt = buildMergePrompt(liveFiles, details);
+    const resp = await complete({ system: SYNTHESIZE_SYSTEM, prompt, keyEnv });
+    return parseMergedFiles(resp.text);
+}
+/** Render the live file set + each proposal's proposed file set into the user
+ * prompt the merge model reads. */
+function buildMergePrompt(liveFiles, details) {
+    const sections = [];
+    sections.push('CURRENT (live) FILE SET:');
+    for (const f of liveFiles) {
+        sections.push(`--- FILE: ${f.filename} ---\n${f.content}`);
+    }
+    details.forEach((d, idx) => {
+        sections.push(`\nPROPOSAL ${idx + 1} (id ${d.proposal.id}):`);
+        if (d.proposal.changelog)
+            sections.push(`Changelog: ${d.proposal.changelog}`);
+        for (const f of d.files) {
+            sections.push(`--- FILE: ${f.filename} ---\n${f.content}`);
+        }
+    });
+    return sections.join('\n');
+}
+/** Parse the LLM's JSON merge output. Tolerates an accidental ```json fence by
+ * extracting the first {...} block. Throws LlmError on anything that isn't a
+ * well-formed `{ files: [{filename, content}] }`. */
+function parseMergedFiles(text) {
+    const trimmed = text.trim();
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start === -1 || end === -1 || end < start) {
+        throw new LlmError('The merge model did not return JSON. Try again.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed.slice(start, end + 1));
+    }
+    catch {
+        throw new LlmError('The merge model returned invalid JSON. Try again.');
+    }
+    const filesRaw = parsed.files;
+    if (!Array.isArray(filesRaw) || filesRaw.length === 0) {
+        throw new LlmError('The merge model returned no files. Try again.');
+    }
+    const out = [];
+    for (const f of filesRaw) {
+        if (typeof f !== 'object' || f === null) {
+            throw new LlmError('The merge model returned a malformed file entry. Try again.');
+        }
+        const { filename, content } = f;
+        if (typeof filename !== 'string' || typeof content !== 'string') {
+            throw new LlmError('The merge model returned a file without filename/content. Try again.');
+        }
+        out.push({ filename, content });
+    }
+    return out;
+}
+/** Print a per-file diff of the live set vs the merged set, so the operator can
+ * see exactly what the synthesis would change before submitting. */
+function printMergePreview(liveFiles, merged) {
+    const liveByName = new Map(liveFiles.map((f) => [f.filename, f.content]));
+    for (const f of merged) {
+        console.log(`\n  ${f.filename}:`);
+        console.log(renderDiff(liveByName.get(f.filename) ?? '', f.content));
+    }
+}
+/** Map a synthesize API error to a friendly, cron-safe CLI message.
+ *
+ * 409 `duplicate_synthesis` — the same merge already exists OPEN. Treated as a
+ *     NO-OP SUCCESS (exit 0) so a re-running cron doesn't fail.
+ * 409 `source_not_open` — a source proposal was decided since we listed it.
+ *     Re-run to pick up the new queue state.
+ * 401/403 — the token isn't a synthesizer scoped to this skill.
+ * 404 — skill not found / unreadable. */
+function handleSynthesizeError(err, refStr, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    const body = err.body;
+    // 409 duplicate — idempotent no-op success. Exit 0 so a cron is safe.
+    if (err.status === 409 && body?.error === 'duplicate_synthesis') {
+        if (options.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                ref: refStr,
+                skipped: 'duplicate_synthesis',
+                existingProposalId: body.existingProposalId ?? null,
+            }));
+        }
+        else {
+            console.log(`\n  An identical synthesis is already open for ${refStr}` +
+                (body.existingProposalId ? ` (id ${body.existingProposalId})` : '') +
+                `. Nothing to do.\n`);
+        }
+        return; // exit 0
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: false,
+            ref: refStr,
+            status: err.status,
+            error: body?.error ?? err.message,
+            message: body?.message ?? null,
+        }));
+        process.exit(1);
+    }
+    if (err.status === 401 || err.status === 403) {
+        console.error(`\n  ✗ This command needs a synthesizer token scoped to ${refStr}.` +
+            `\n    The skill author can mint one at ${getApiUrl()}/settings/tokens.\n`);
+    }
+    else if (err.status === 404) {
+        console.error(`\n  ✗ Skill not found: ${refStr}\n`);
+    }
+    else if (err.status === 409 && body?.error === 'source_not_open') {
+        console.error(`\n  ✗ One or more proposals were decided since they were listed.` +
+            `\n    Re-run \`botdocs proposals synthesize ${refStr}\` to pick up the current queue.\n`);
+    }
+    else if (err.status === 413) {
+        console.error(`\n  ✗ The merged file set is too large for ${refStr}. Trim and try again.\n`);
+    }
+    else {
+        console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
+    }
+    process.exit(1);
+}
+/** Map a LIST API error to a friendly message (shared by list + accept's
+ * version pre-fetch). */
+function handleListError(err, refStr, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, ref: refStr, status: err.status, error: err.message }));
+        process.exit(1);
+    }
+    if (err.status === 404) {
+        console.error(`\n  ✗ Skill not found: ${refStr}\n`);
+    }
+    else if (err.status === 401) {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    else {
+        console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
+    }
+    process.exit(1);
+}
+/** Map an accept API error to a friendly message.
+ *
+ * 403 — you don't own this skill (only the author can accept).
+ * 404 — the proposal or skill doesn't exist.
+ * 409 — a conflict: the proposal was already decided, or the skill moved while
+ *       you reviewed (stale base). Tell the user to re-list / re-review. */
+function handleAcceptError(err, refStr, id, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    const body = err.body;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, ref: refStr, id, status: err.status, error: err.message }));
+        process.exit(1);
+    }
+    if (err.status === 403) {
+        console.error(`\n  ✗ Only the author of ${refStr} can accept proposals.\n`);
+    }
+    else if (err.status === 404) {
+        console.error(`\n  ✗ Proposal ${id} not found for ${refStr}.\n`);
+    }
+    else if (err.status === 409) {
+        // Already decided, or the skill moved since the base was read. Either way
+        // the safe next step is to re-list and re-review.
+        const detail = body?.error ?? 'this proposal can no longer be accepted as-is';
+        console.error(`\n  ✗ ${detail}.`);
+        console.error(`    Run \`botdocs proposals ${refStr}\` to see the current state.\n`);
+    }
+    else if (err.status === 401) {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    else {
+        console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
+    }
+    process.exit(1);
+}
+/**
+ * Register the `proposals` command (list, default) and its `accept`
+ * subcommand on the program. Done in a registrar helper (like `team`/`backups`)
+ * so the nested `accept` subcommand lives in this file rather than inline in
+ * index.ts — keeping index.ts's top-level surface clean and the quickstart
+ * drift-check parser happy (it lists only the parent verb `proposals`).
+ */
+export function registerProposalsCommands(program) {
+    const proposalsCmd = program
+        .command('proposals <ref>')
+        .description('List proposals queued against a skill (author sees full metadata)')
+        .option('--status <status>', 'Filter by status: OPEN (default), ACCEPTED, REJECTED, or all')
+        .action(async (ref, opts) => {
+        await proposals(ref, { ...opts, json: program.opts().json });
+    });
+    proposalsCmd
+        .command('accept <ref>')
+        .description('Accept a proposal, publishing it as a new version (author-only)')
+        .requiredOption('--id <proposalId>', 'The proposal id to accept')
+        .action(async (ref, opts) => {
+        await proposalsAccept(ref, { ...opts, json: program.opts().json });
+    });
+    proposalsCmd
+        .command('synthesize <ref>')
+        .description("Merge a skill's open proposals into one synthesis for the author to review")
+        .option('--message <message>', 'Changelog describing the merge')
+        .option('--agent-label <label>', 'Self-reported agent identity (untrusted)')
+        .option('--key-env <name>', 'Env var holding the LLM API key (e.g. BOTDOCS_ANTHROPIC_KEY)')
+        .option('-y, --yes', 'Skip the confirmation prompt (for cron / non-interactive use)')
+        .action(async (ref, opts) => {
+        await proposalsSynthesize(ref, { ...opts, json: program.opts().json });
+    });
+}

package/dist/commands/propose.d.ts

@@ -0,0 +1,18 @@
+interface ProposeOptions {
+    /** Proposal changelog — what this change does, for the reviewing author. */
+    message?: string;
+    /** Self-reported agent identity (e.g. "hermes-v2"). UNTRUSTED server-side. */
+    agentLabel?: string;
+    json?: boolean;
+}
+/**
+ * `botdocs propose @user/slug [path]` — queue a change to a skill for the
+ * author to review, instead of publishing directly.
+ *
+ * Collects the local files (directory or single markdown file, default cwd),
+ * computes `basedFileHash` over the skill's CURRENT live file set (the base
+ * the author will diff against), and POSTs the proposal. The author reviews +
+ * accepts/rejects from the Proposals tab or `botdocs proposals accept`.
+ */
+export declare function propose(rawRef: string, pathArg: string | undefined, options: ProposeOptions): Promise<void>;
+export {};

package/dist/commands/propose.js

@@ -0,0 +1,202 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ApiError, apiFetch, fetchRawContent, friendlyApiErrorDetail, getApiUrl } from '../lib/api.js';
+import { loadAuth } from '../lib/config.js';
+import { parseRef } from '../lib/ref.js';
+import { fileSetHash } from '../lib/proposals.js';
+import { collectFromDirectory, collectFromFile } from './publish.js';
+/** Bail before any file reading if the user isn't logged in. Mirrors
+ * publish.ts's preflight: one friendly line, exit 1. Proposing requires auth
+ * (the server attributes the proposal to the caller). */
+function requireAuth(options) {
+    if (loadAuth())
+        return;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, error: 'not logged in', hint: 'Run `botdocs login` first.' }));
+    }
+    else {
+        console.error('\n  ✗ Not logged in. Run `botdocs login` first.\n');
+    }
+    process.exit(1);
+}
+/** True when the logged-in user owns this ref. A skill ref's username IS the
+ * author's username (the registry resolves `@user/slug` by the author's
+ * handle), so ownership is a case-insensitive username match. Used only to
+ * tailor the success copy — the server is the authority on what the proposal
+ * actually does (an owner proposing still gets a proposal row, not a publish).
+ */
+function isOwnRef(username) {
+    const me = loadAuth()?.username;
+    if (!me)
+        return false;
+    return me.toLowerCase() === username.toLowerCase();
+}
+/** Pull the live published file set (filename + content) so we can compute the
+ * canonical basedFileHash the server uses for drift detection. The manifest
+ * lists files by rawUrl; we fetch each body. Returns null on a non-SKILL
+ * manifest (proposals only apply to skills). */
+async function fetchLiveFileSet(username, slug) {
+    const manifest = await apiFetch(`/api/skills/${username}/${slug}/manifest`);
+    if (manifest.type !== 'SKILL' || !manifest.files)
+        return null;
+    const files = await Promise.all(manifest.files.map(async (f) => ({
+        filename: f.filename,
+        content: await fetchRawContent(f.rawUrl),
+    })));
+    return files;
+}
+/**
+ * `botdocs propose @user/slug [path]` — queue a change to a skill for the
+ * author to review, instead of publishing directly.
+ *
+ * Collects the local files (directory or single markdown file, default cwd),
+ * computes `basedFileHash` over the skill's CURRENT live file set (the base
+ * the author will diff against), and POSTs the proposal. The author reviews +
+ * accepts/rejects from the Proposals tab or `botdocs proposals accept`.
+ */
+export async function propose(rawRef, pathArg, options) {
+    requireAuth(options);
+    let ref;
+    try {
+        ref = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(`\n  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const refStr = `@${ref.username}/${ref.slug}`;
+    // Collect the proposed files from the local path (default: cwd).
+    const source = pathArg ?? '.';
+    const resolved = path.resolve(source);
+    if (!fs.existsSync(resolved)) {
+        console.error(`\n  ✗ Source not found: ${source}\n`);
+        process.exit(1);
+    }
+    let files;
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        files = collectFromDirectory(resolved);
+    }
+    else {
+        files = collectFromFile(resolved);
+    }
+    if (files.length === 0) {
+        console.error('\n  ✗ No markdown files found to propose.\n');
+        process.exit(1);
+    }
+    if (!files.some((f) => f.filename.endsWith('.md') || f.filename.endsWith('.mdc'))) {
+        console.error('\n  ✗ A proposal needs at least one markdown file (.md or .mdc).\n');
+        process.exit(1);
+    }
+    // Fetch the live file set so basedFileHash anchors the proposal to the exact
+    // base the author will see. A drift between this and what the server stores
+    // becomes the "skill moved while you reviewed" guard on accept.
+    let liveFiles;
+    try {
+        liveFiles = await fetchLiveFileSet(ref.username, ref.slug);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+            console.error(`\n  ✗ Skill not found: ${refStr}\n`);
+            process.exit(1);
+        }
+        if (err instanceof ApiError) {
+            console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    if (liveFiles === null) {
+        console.error('\n  ✗ Proposals only apply to skills (not bundles).\n');
+        process.exit(1);
+    }
+    const basedFileHash = fileSetHash(liveFiles);
+    let result;
+    try {
+        result = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/proposals`, {
+            method: 'POST',
+            auth: true,
+            body: {
+                files: files.map((f) => ({
+                    filename: f.filename,
+                    content: f.content,
+                    sortOrder: f.sortOrder,
+                })),
+                changelog: options.message,
+                agentLabel: options.agentLabel,
+                basedFileHash,
+            },
+        });
+    }
+    catch (err) {
+        handleProposeError(err, refStr, options);
+        return;
+    }
+    const own = isOwnRef(ref.username);
+    // The #proposals deep link only renders for the author, so we only print it
+    // when the proposer owns the skill. A non-author operator gets the plain
+    // "queued for review" line with no dead link.
+    const reviewUrl = own
+        ? `${getApiUrl()}/${refStr}#proposals`
+        : `${getApiUrl()}/${refStr}`;
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            ref: refStr,
+            proposalId: result.proposalId,
+            status: result.status,
+            baseVersion: result.baseVersion,
+            url: reviewUrl,
+        }));
+        return;
+    }
+    console.log(`\n  ✓ Proposal queued for ${refStr} (id ${result.proposalId}).`);
+    if (own) {
+        console.log(`    Review it at ${reviewUrl}\n`);
+    }
+    else {
+        console.log(`    The skill author will review it. ${reviewUrl}\n`);
+    }
+}
+/** Map a propose API error to a friendly, actionable CLI message.
+ *
+ * 404 — skill not found (or unreadable; the server collapses both to 404).
+ * 413 — proposal too large.
+ * 429 — per-skill OPEN cap or per-proposer/day cap; the server sends a
+ *       structured `{ error, message }` we surface.
+ * Everything else routes through the shared helper. */
+function handleProposeError(err, refStr, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    const body = err.body;
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: false,
+            ref: refStr,
+            status: err.status,
+            error: err.message,
+            message: body?.message ?? null,
+        }));
+        process.exit(1);
+    }
+    if (err.status === 404) {
+        console.error(`\n  ✗ Skill not found: ${refStr}\n`);
+    }
+    else if (err.status === 413) {
+        console.error(`\n  ✗ Proposal too large for ${refStr}. Trim the files and try again.\n`);
+    }
+    else if (err.status === 429) {
+        // The review queue is full or you've hit the per-day proposal limit. The
+        // server's structured message is the most specific; fall back to a generic
+        // line.
+        console.error(`\n  ✗ ${body?.message ?? 'Proposal rate limit reached — try again later.'}\n`);
+    }
+    else if (err.status === 401) {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    else {
+        console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
+    }
+    process.exit(1);
+}

package/dist/commands/publish.d.ts

@@ -18,7 +18,7 @@ interface PublishOptions {
      * draft → published flag is already cheap and reversible via `unpublish`). */
     dryRun?: boolean;
 }
-interface FileEntry {
+export interface FileEntry {
     filename: string;
     content: string;
     sortOrder: number;
@@ -49,6 +49,8 @@ declare function publishRef(rawRef: string, options: PublishOptions): Promise<vo
  */
 declare function handlePublishToggleError(err: unknown, refLabel: string, options: PublishOptions): void;
 export { publishRef, handlePublishToggleError };
+export declare function collectFromFile(filePath: string): FileEntry[];
+export declare function collectFromDirectory(dirPath: string): FileEntry[];
 /**
  * Recursively collect publishable markdown files under `currentDir`.
  *

package/dist/commands/publish.js

@@ -460,12 +460,12 @@ function derivePublishSlug(source) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
-function collectFromFile(filePath) {
+export function collectFromFile(filePath) {
     const content = fs.readFileSync(filePath, 'utf-8');
     const filename = path.basename(filePath);
     return [{ filename, content, sortOrder: 0 }];
 }
-function collectFromDirectory(dirPath) {
+export function collectFromDirectory(dirPath) {
     const files = [];
     walkDirectory(dirPath, dirPath, files);
     files.sort((a, b) => a.sortOrder - b.sortOrder);

package/dist/index.js

@@ -126,6 +126,8 @@ import { ingest, SUPPORTED_TOOLS as INGEST_SUPPORTED_TOOLS } from './commands/in
 import { checkUpdates } from './commands/check-updates.js';
 import { compile } from './commands/compile.js';
 import { edit } from './commands/edit.js';
+import { propose } from './commands/propose.js';
+import { registerProposalsCommands } from './commands/proposals.js';
 import { registerTeamCommands } from './commands/team.js';
 import { registerBackupCommands } from './commands/backups.js';
 import { undo } from './commands/undo.js';
@@ -325,6 +327,19 @@ program
     .action(async (ref, opts) => {
     await edit(ref, { ...opts, json: program.opts().json });
 });
+program
+    .command('propose <ref> [path]')
+    .description('Queue a change to a skill for its author to review (instead of publishing directly)')
+    .option('--message <message>', 'Changelog describing the proposed change')
+    .option('--agent-label <label>', 'Self-reported agent identity (e.g. hermes-v2); shown to the author as unverified')
+    .action(async (ref, pathArg, opts) => {
+    await propose(ref, pathArg, { ...opts, json: program.opts().json });
+});
+// `proposals` (list, default) + its `accept` subcommand. Registered via a
+// helper (like team/backups) so the nested `accept` lives in proposals.ts —
+// `botdocs proposals @user/slug` lists; `botdocs proposals accept @user/slug
+// --id X` accepts.
+registerProposalsCommands(program);
 registerTeamCommands(program);
 registerBackupCommands(program);
 program

package/dist/lib/proposals.d.ts

@@ -0,0 +1,37 @@
+/** A file for hashing — ONLY filename + content participate. */
+export interface HashableFile {
+    filename: string;
+    content: string;
+}
+/**
+ * Canonical file-set hash. Mirrors the server's `fileSetHash` exactly so the
+ * `basedFileHash` the CLI sends matches what the server would compute over the
+ * same live file set. Sort is by filename ascending using the same comparison
+ * the server uses (`<` / `>` on the raw filename string).
+ */
+export declare function fileSetHash(files: ReadonlyArray<HashableFile>): string;
+/**
+ * Canonical SYNTHESIS idempotency hash. DISTINCT from {@link fileSetHash}
+ * (which is the drift anchor / `basedFileHash`). The server keys the
+ * partial-unique index `botdoc_proposals_synthesis_hash_uq` on this value so
+ * the same OPEN synthesis (same sources + same merged content) can't be
+ * created twice — the CLI computes it before POSTing only so the value is
+ * stable client-side; the server recomputes + enforces it.
+ *
+ * MUST match `apps/web/src/lib/proposals.ts#sourceHash` byte-for-byte:
+ *
+ *   sha256-hex( JSON.stringify({
+ *     sources: [...new Set(synthesizedFrom)].sort(),
+ *     files:   [...mergedFiles]
+ *                .sort by filename ascending (same `<`/`>` compare as fileSetHash)
+ *                .map(f => [f.filename, sha256hex(f.content)]),
+ *   }) )
+ *
+ * Notes (identical exclusions to fileSetHash):
+ *   - `sources` is deduplicated + lexicographically sorted, so source-id
+ *     ordering / duplicates don't change the hash.
+ *   - `files` pairs each filename with the sha256 of its content (not the raw
+ *     body) to keep the JSON small.
+ *   - `mode`/`sortOrder` are NOT part of the hash.
+ */
+export declare function sourceHash(synthesizedFrom: ReadonlyArray<string>, mergedFiles: ReadonlyArray<HashableFile>): string;

package/dist/lib/proposals.js

@@ -0,0 +1,72 @@
+/**
+ * proposals.ts — shared helpers for the CLI proposal lane.
+ *
+ * The load-bearing piece here is {@link fileSetHash}: the canonical file-set
+ * hash that the server computes in `apps/web/src/lib/proposals.ts#fileSetHash`.
+ * The two MUST agree byte-for-byte — the server uses it as the drift anchor
+ * (`basedFileHash`) the CLI sends on every `propose`. Any divergence (sort
+ * order, framing byte, included fields) would make the server reject or
+ * mis-detect drift for every proposal.
+ *
+ * Canonical spec (identical on both sides):
+ *   - sha256, hex digest
+ *   - over each file sorted by filename ascending (JS default string compare)
+ *   - of:  filename + "\u0000" + content + "\u0000"
+ *   - `mode` and `sortOrder` are NOT part of the hash.
+ */
+import { createHash } from 'node:crypto';
+/** NUL framing byte between/after each (filename, content) pair. Defined once
+ * so the intent is obvious and it can never be mistaken for a space. */
+const NUL = '\u0000';
+/**
+ * Canonical file-set hash. Mirrors the server's `fileSetHash` exactly so the
+ * `basedFileHash` the CLI sends matches what the server would compute over the
+ * same live file set. Sort is by filename ascending using the same comparison
+ * the server uses (`<` / `>` on the raw filename string).
+ */
+export function fileSetHash(files) {
+    const sorted = [...files].sort((a, b) => a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0);
+    const hash = createHash('sha256');
+    for (const f of sorted) {
+        hash.update(f.filename);
+        hash.update(NUL);
+        hash.update(f.content);
+        hash.update(NUL);
+    }
+    return hash.digest('hex');
+}
+/** sha256-hex of a single string (a file's content). Helper for {@link sourceHash}. */
+function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+/**
+ * Canonical SYNTHESIS idempotency hash. DISTINCT from {@link fileSetHash}
+ * (which is the drift anchor / `basedFileHash`). The server keys the
+ * partial-unique index `botdoc_proposals_synthesis_hash_uq` on this value so
+ * the same OPEN synthesis (same sources + same merged content) can't be
+ * created twice — the CLI computes it before POSTing only so the value is
+ * stable client-side; the server recomputes + enforces it.
+ *
+ * MUST match `apps/web/src/lib/proposals.ts#sourceHash` byte-for-byte:
+ *
+ *   sha256-hex( JSON.stringify({
+ *     sources: [...new Set(synthesizedFrom)].sort(),
+ *     files:   [...mergedFiles]
+ *                .sort by filename ascending (same `<`/`>` compare as fileSetHash)
+ *                .map(f => [f.filename, sha256hex(f.content)]),
+ *   }) )
+ *
+ * Notes (identical exclusions to fileSetHash):
+ *   - `sources` is deduplicated + lexicographically sorted, so source-id
+ *     ordering / duplicates don't change the hash.
+ *   - `files` pairs each filename with the sha256 of its content (not the raw
+ *     body) to keep the JSON small.
+ *   - `mode`/`sortOrder` are NOT part of the hash.
+ */
+export function sourceHash(synthesizedFrom, mergedFiles) {
+    const sources = [...new Set(synthesizedFrom)].sort();
+    const files = [...mergedFiles]
+        .sort((a, b) => (a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0))
+        .map((f) => [f.filename, sha256Hex(f.content)]);
+    return sha256Hex(JSON.stringify({ sources, files }));
+}

package/package.json

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