@botdocs/cli 0.13.0 → 0.14.1

package/dist/commands/ingest.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { render } from 'ink';
 import open from 'open';
-import { ApiError, apiFetch, getApiUrl } from '../lib/api.js';
+import { ApiError, apiFetch, getApiUrl, friendlyFreeTierError } from '../lib/api.js';
 import { loadAuth } from '../lib/config.js';
 import { IngestSessionClient, PairingClaimError } from '../lib/ingest-session-client.js';
 import { discoverSkills, ecosystemLabel, formatBytes, STUB_BYTE_THRESHOLD, summaryKey, titleFromContent, } from '../lib/ingest-discover.js';
@@ -643,6 +643,29 @@ function reportSizeCap(err, options) {
     console.error(`\n  ✗ ${detailMessage ?? err.message}\n`);
     process.exit(1);
 }
+/** Print an actionable 403 skill-cap message and exit non-zero. Honors
+ * `--json` by emitting `{ ok: false, status: 403, error, limit, current }` so
+ * scripts can branch on the cap. The human line comes from the shared
+ * `friendlyFreeTierError` mapper so the copy stays identical to publish/install
+ * (honest free-limit wording, no fake checkout). */
+function reportSkillCap(err, options) {
+    const body = err.body;
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: false,
+            status: 403,
+            error: 'skill_cap_exceeded',
+            limit: body?.limit ?? null,
+            current: body?.current ?? null,
+        }));
+        process.exit(1);
+    }
+    // friendlyFreeTierError returns the honest cap CTA for this code; fall back
+    // to the raw server message only in the (impossible) null case so we never
+    // print an empty line.
+    console.error(`\n  ✗ ${friendlyFreeTierError(err) ?? err.message}\n`);
+    process.exit(1);
+}
 async function uploadSkills(skills, options, pair) {
     // Optional: announce intent before the API call so the paired web UI
     // shows "uploading…" rows immediately. The events POST is batched
@@ -686,6 +709,14 @@ async function uploadSkills(skills, options, pair) {
             if (conflicts)
                 reportConflicts(conflicts, options);
         }
+        // 403 skill_cap_exceeded — the whole batch was rejected because it would
+        // push the account over the free per-account skill limit. Surface the
+        // honest cap CTA (no fake checkout) and exit non-zero.
+        if (err instanceof ApiError &&
+            err.status === 403 &&
+            err.body?.error === 'skill_cap_exceeded') {
+            reportSkillCap(err, options);
+        }
         // 413 PAYLOAD_TOO_LARGE — server's `validateSkillCaps` rejected one of
         // the skills in the payload. The body's `detail.message` is the human
         // line ("file foo/bar.md is 71 KB, cap is 64 KB per file"); fall back

package/dist/commands/login.js

@@ -1,10 +1,11 @@
 import React from 'react';
+import os from 'node:os';
 import { randomBytes } from 'node:crypto';
 import open from 'open';
 import { render } from 'ink';
 import * as p from '@clack/prompts';
-import { saveAuth } from '../lib/config.js';
-import { getApiUrl } from '../lib/api.js';
+import { saveAuth, getOrCreateDeviceId } from '../lib/config.js';
+import { ApiError, getApiUrl, friendlyFreeTierError } from '../lib/api.js';
 import { LoginApp } from './views/login-app.js';
 /** Total wall-clock budget for the polling loop. After this we tell the user
  * the request expired and exit 1. Mirrors the server-side state TTL. */
@@ -36,11 +37,22 @@ async function loginWithToken(token, syncLibrary) {
         process.exit(1);
     }
     const baseUrl = getApiUrl();
+    // Stamp the device identity on the validating call so the token's device
+    // registers (and the free-tier device/session caps bind) the moment it's
+    // saved — not just on the next command. Best-effort: a failure to resolve
+    // the id never blocks login.
+    const { deviceId, machineName } = deviceIdentity();
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+    };
+    if (deviceId)
+        headers['X-Device-Id'] = deviceId;
+    if (machineName)
+        headers['X-Machine-Name'] = machineName;
     let res;
     try {
-        res = await fetch(`${baseUrl}/api/cli/whoami`, {
-            headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
-        });
+        res = await fetch(`${baseUrl}/api/cli/whoami`, { headers });
     }
     catch (err) {
         console.error(`Failed to contact ${baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
@@ -51,21 +63,70 @@ async function loginWithToken(token, syncLibrary) {
         process.exit(1);
     }
     if (!res.ok) {
-        console.error(`Token validation failed (${res.status}). Try again later.`);
+        // Surface the standard free-tier frictions with an HONEST CTA when the
+        // server gates this device on the way in:
+        //   - 403 device_cap_exceeded  → "you've reached N devices…"
+        //   - 429 session_limit_exceeded → "N active sessions already…"
+        // The shared mapper reads the JSON body's `error`/`limit` fields and
+        // returns null for anything it doesn't recognize, in which case we fall
+        // back to the generic "validation failed" line. Parsing is best-effort:
+        // a non-JSON body just falls through to the generic message.
+        const body = (await res.json().catch(() => undefined));
+        const friendly = friendlyFreeTierError(new ApiError(res.status, '', body));
+        if (friendly) {
+            console.error(friendly);
+        }
+        else {
+            console.error(`Token validation failed (${res.status}). Try again later.`);
+        }
         process.exit(1);
     }
     const user = (await res.json());
+    // Persist the SAME device id we sent on the whoami header so the device that
+    // just registered server-side matches every subsequent request.
     saveAuth({
         token,
         username: user.username,
         displayName: user.displayName,
         syncLibrary,
+        ...persistedDeviceField(deviceId),
     });
     printSignedIn(user.username, syncLibrary);
 }
+/** Best-effort stable device identity for this CLI install. Mirrors
+ * `attachDeviceHeaders` in lib/api.ts, but the login flows can't reuse it: they
+ * use raw `fetch` (there's no bearer to attach yet) and they ALSO need the id
+ * for the browser auth URL. Returns nulls if it can't be resolved (e.g. a
+ * read-only home dir) so login never hard-fails on device identity.
+ *
+ * Resolve this ONCE per login and thread the same id into both the request
+ * (header/URL) and `persistedDeviceField` — the server registers the device
+ * under the forwarded id, so the persisted id must match or the next command
+ * would present as a different device. */
+function deviceIdentity() {
+    try {
+        return { deviceId: getOrCreateDeviceId(), machineName: os.hostname() };
+    }
+    catch {
+        return { deviceId: null, machineName: null };
+    }
+}
+/** The `auth.json` fragment carrying the device id to persist. `getOrCreateDeviceId`
+ * only persists when an auth file already exists, but at login time we're
+ * writing that file for the first time — so we fold the id straight into the
+ * `saveAuth` payload. A `BOTDOCS_DEVICE_ID` override always wins at read time
+ * and is intentionally NOT persisted (so auth.json stays portable across CI
+ * runners), so we omit it in that case. */
+function persistedDeviceField(deviceId) {
+    if (process.env.BOTDOCS_DEVICE_ID?.trim())
+        return {};
+    return deviceId ? { deviceId } : {};
+}
 /** Helper: register a new state with the server and return the public auth
- * URL plus the last-6-chars suffix the user can verify in their browser. */
-async function initLoginState(baseUrl) {
+ * URL plus the last-6-chars suffix the user can verify in their browser. The
+ * caller passes the resolved device identity so the SAME id is forwarded in
+ * the URL and persisted to auth.json. */
+async function initLoginState(baseUrl, deviceId, machineName) {
     const state = randomBytes(32).toString('hex');
     const initRes = await fetch(`${baseUrl}/api/cli/auth/init`, {
         method: 'POST',
@@ -99,9 +160,19 @@ async function initLoginState(baseUrl) {
     // state carried in the URL hash fragment (#state=...), which browsers
     // never send to the server and never write to history. That refactor is
     // out of scope for the P3 bucket — tracked as a separate item.
+    //
+    // Forward this install's device identity in the URL. The browser that lands
+    // /cli-auth has no X-Device-Id header of its own, so the page relays these
+    // into the grant POST body — that's what registers the device + binds the
+    // free-tier caps at login time (rather than only on the next CLI command).
+    const params = new URLSearchParams({ state });
+    if (deviceId)
+        params.set('device', deviceId);
+    if (machineName)
+        params.set('machine', machineName);
     return {
         state,
-        authUrl: `${baseUrl}/cli-auth?state=${state}`,
+        authUrl: `${baseUrl}/cli-auth?${params.toString()}`,
         tail: state.slice(-6),
     };
 }
@@ -112,6 +183,9 @@ async function initLoginState(baseUrl) {
  * the component's effect call `useApp().exit()` to unmount. */
 async function loginInkInteractive(syncLibrary) {
     const baseUrl = getApiUrl();
+    // Resolve the device identity ONCE — forwarded to the browser via the auth
+    // URL and persisted (below) under the same id.
+    const { deviceId, machineName } = deviceIdentity();
     let status = 'initializing';
     let authUrl;
     let stateTail;
@@ -145,7 +219,7 @@ async function loginInkInteractive(syncLibrary) {
         // Phase 1: register state with the server.
         let init;
         try {
-            init = await initLoginState(baseUrl);
+            init = await initLoginState(baseUrl, deviceId, machineName);
         }
         catch (err) {
             status = 'error';
@@ -182,6 +256,7 @@ async function loginInkInteractive(syncLibrary) {
             username: granted.username,
             displayName: granted.displayName,
             syncLibrary,
+            ...persistedDeviceField(deviceId),
         });
         resolvedUsername = granted.username;
         status = 'success';
@@ -197,9 +272,12 @@ async function loginInkInteractive(syncLibrary) {
  * polling indicator; the spinner degrades gracefully when stdout isn't a TTY. */
 async function loginPlainInteractive(syncLibrary) {
     const baseUrl = getApiUrl();
+    // Resolve the device identity ONCE — forwarded to the browser via the auth
+    // URL and persisted (below) under the same id.
+    const { deviceId, machineName } = deviceIdentity();
     let init;
     try {
-        init = await initLoginState(baseUrl);
+        init = await initLoginState(baseUrl, deviceId, machineName);
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
@@ -230,6 +308,7 @@ async function loginPlainInteractive(syncLibrary) {
         username: granted.username,
         displayName: granted.displayName,
         syncLibrary,
+        ...persistedDeviceField(deviceId),
     });
     printSyncLibraryHint(syncLibrary);
 }

package/dist/commands/publish.d.ts

@@ -6,16 +6,16 @@ interface PublishOptions {
     license?: string;
     json?: boolean;
     noCompile?: boolean;
-    /** Skip the pre-POST y/N confirmation prompt. First-time authors don't
-     * always realize `publish` is immediate, so the path-form publish asks
-     * "Publish to public registry as @<user>/<slug>? [y/N]" by default.
-     * `--yes` bypasses it for scripted runs; `--json` skips it implicitly
-     * because JSON mode is for non-interactive consumers. */
+    /** Skip the pre-POST y/N confirmation prompt. The path-form publish asks
+     * "Add @<user>/<slug> to your library? [y/N]" by default so first-time
+     * authors realize it uploads immediately. `--yes` bypasses it for scripted
+     * runs; `--json` skips it implicitly because JSON mode is non-interactive. */
     yes?: boolean;
     /** Build the payload, print what would be published, exit 0 without POSTing.
      * Lets authors preview title/description/file list + total size before they
-     * commit to publishing. Skipped entirely on ref-form publish (toggling a
-     * draft → published flag is already cheap and reversible via `unpublish`). */
+     * commit to uploading. Skipped entirely on ref-form publish (flipping a
+     * skill's CLI-discoverable flag is already cheap and reversible via
+     * `unpublish`). */
     dryRun?: boolean;
 }
 export interface FileEntry {
@@ -25,13 +25,13 @@ export interface FileEntry {
 }
 export declare function publish(source: string, options: PublishOptions): Promise<void>;
 /**
- * Toggle an existing BotDoc from draft → published via the API.
+ * Make an existing skill discoverable from the CLI (install/pull/list) via the
+ * API — sets `cli_discoverable = true` server-side. The inverse of `unpublish`.
  *
  * Called from `publish()` when the source argument looks like a ref
- * (`@user/slug` or `user/slug`) instead of a local path. Strips the
- * `draft` and `ingest:<id>` tags server-side. No prompt — moving from
- * draft to published is the natural progression, and unpublishing a
- * mistake is one CLI call away.
+ * (`@user/slug` or `user/slug`) instead of a local path. No prompt — exposing
+ * your own skill to your own CLI is harmless, and `unpublish` hides it again in
+ * one call. Skills are never public; this only controls CLI reach.
  */
 declare function publishRef(rawRef: string, options: PublishOptions): Promise<void>;
 /**

package/dist/commands/publish.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import AdmZip from 'adm-zip';
 import * as p from '@clack/prompts';
-import { ApiError, apiFetch, getApiUrl, friendlyApiErrorDetail } from '../lib/api.js';
+import { ApiError, apiFetch, getApiUrl, friendlyApiErrorDetail, friendlyFreeTierError } from '../lib/api.js';
 import { parseManifest } from '../lib/manifest.js';
 import { compile } from './compile.js';
 import { ecosystemDestination } from '../lib/canonical.js';
@@ -60,9 +60,9 @@ export async function publish(source, options) {
     // user isn't logged in. The 401 would otherwise only surface after the POST,
     // making large publishes feel slow and confusing.
     requireAuth(options);
-    // Ref-form (e.g. "@user/slug" or "user/slug") → toggle the published
-    // flag via the API. Path-form continues to the existing upload flow
-    // below. Overloading by argument shape (rather than introducing
+    // Ref-form (e.g. "@user/slug" or "user/slug") → make that existing skill
+    // discoverable from the CLI via the API. Path-form continues to the upload
+    // flow below. Overloading by argument shape (rather than introducing
     // `botdocs publish-ref` or a `--ref` flag) keeps the verb intuitive:
     // a user typing `botdocs publish @me/foo` doesn't have to know it's a
     // different code path under the hood.
@@ -160,11 +160,11 @@ export async function publish(source, options) {
         console.error('Description is required. Use --description "..." or set "description" in botdocs.json.');
         process.exit(1);
     }
-    // Pre-POST confirmation. Publish is immediate and pushes the skill to the
-    // public registry — first-time authors don't always know that, so we ask
-    // y/N (defaulting to N) before sending. Skipped under --yes (scripted
-    // runs that opt in) and --json (non-interactive consumers, which also
-    // gives back-compat for callers that don't have a TTY).
+    // Pre-POST confirmation. The upload is immediate (the skill lands in your
+    // library, private, discoverable from the CLI) — first-time authors don't
+    // always know that, so we ask y/N (defaulting to N) before sending. Skipped
+    // under --yes (scripted runs that opt in) and --json (non-interactive
+    // consumers, which also gives back-compat for callers that don't have a TTY).
     if (!options.yes && !options.json) {
         const auth = loadAuth();
         // requireAuth() ran first, so auth is non-null here. The fallback is
@@ -172,11 +172,11 @@ export async function publish(source, options) {
         const username = auth?.username ?? 'me';
         const slugGuess = derivePublishSlug(source);
         const confirmed = await p.confirm({
-            message: `Publish to public registry as @${username}/${slugGuess}?`,
+            message: `Add @${username}/${slugGuess} to your library? (private — discoverable from your CLI)`,
             initialValue: false,
         });
         if (p.isCancel(confirmed) || confirmed !== true) {
-            console.log('  Publish cancelled.');
+            console.log('  Cancelled.');
             return;
         }
     }
@@ -211,7 +211,7 @@ export async function publish(source, options) {
         console.log(JSON.stringify({ ...result, url: absoluteUrl }));
     }
     else {
-        console.log(`\nPublished: ${absoluteUrl}`);
+        console.log(`\nAdded to your library: ${absoluteUrl}`);
     }
 }
 /** Translate path-publish API errors into actionable CLI messages.
@@ -284,10 +284,14 @@ function handlePathPublishError(err, options) {
         console.error(`\n  ✗ ${err.message}\n`);
     }
     else {
-        // Generic 403/429/5xx — route through the shared helper so the
-        // wording matches sync/install/edit instead of leaking ApiError's raw
-        // `message` (which is often the server's error string verbatim).
-        console.error(`\n  ✗ ${friendlyApiErrorDetail(err)}\n`);
+        // Free-tier frictions (e.g. 403 skill_cap_exceeded) get an HONEST CTA
+        // from the shared mapper before the generic 403/429/5xx wording. The
+        // mapper returns null for anything it doesn't recognize, so the
+        // friendlyApiErrorDetail fallback still covers "permission denied" /
+        // "rate-limited" / server errors. Keeps the cap message identical to
+        // the one ingest/install render.
+        const friendly = friendlyFreeTierError(err);
+        console.error(`\n  ✗ ${friendly ?? friendlyApiErrorDetail(err)}\n`);
     }
     process.exit(1);
 }
@@ -302,13 +306,13 @@ function extractDetailMessage(detail) {
     return undefined;
 }
 /**
- * Toggle an existing BotDoc from draft → published via the API.
+ * Make an existing skill discoverable from the CLI (install/pull/list) via the
+ * API — sets `cli_discoverable = true` server-side. The inverse of `unpublish`.
  *
  * Called from `publish()` when the source argument looks like a ref
- * (`@user/slug` or `user/slug`) instead of a local path. Strips the
- * `draft` and `ingest:<id>` tags server-side. No prompt — moving from
- * draft to published is the natural progression, and unpublishing a
- * mistake is one CLI call away.
+ * (`@user/slug` or `user/slug`) instead of a local path. No prompt — exposing
+ * your own skill to your own CLI is harmless, and `unpublish` hides it again in
+ * one call. Skills are never public; this only controls CLI reach.
  */
 async function publishRef(rawRef, options) {
     // Preflight: same as the path-form publish. publish() already called
@@ -337,10 +341,10 @@ async function publishRef(rawRef, options) {
         return;
     }
     if (options.json) {
-        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'published' }));
+        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'cli-visible' }));
     }
     else {
-        console.log(`✓ Published ${refLabel} — visible at https://botdocs.ai/${refLabel}`);
+        console.log(`✓ ${refLabel} is now discoverable from the CLI.`);
     }
 }
 /**

package/dist/commands/unpublish.d.ts

@@ -3,14 +3,14 @@ interface UnpublishOptions {
     json?: boolean;
 }
 /**
- * Set the `draft` flag back on a published BotDoc, hiding it from
- * `/explore` and 404ing the public URL for everyone except the author.
+ * Hide a skill from the CLI (sets `cli_discoverable = false` server-side): it
+ * stays in the author's web library, but `botdocs install`/`pull`/`list` can
+ * no longer see it. The inverse of `publish @user/slug`.
  *
- * Idempotent server-side — calling unpublish on something already a
- * draft is a no-op. Prompts for confirmation by default because the
- * effect is visible to anyone who had the URL bookmarked; skip with
- * `--yes` for scripting/CI. `--json` implies `--yes` so machine-driven
- * callers don't deadlock on the prompt.
+ * Idempotent server-side — hiding an already-hidden skill is a no-op. Prompts
+ * for confirmation by default (so a stray `unpublish` doesn't quietly pull a
+ * skill out of your agents); skip with `--yes` for scripting/CI. `--json`
+ * implies `--yes` so machine-driven callers don't deadlock on the prompt.
  */
 export declare function unpublish(rawRef: string, options: UnpublishOptions): Promise<void>;
 export {};

package/dist/commands/unpublish.js

@@ -3,14 +3,14 @@ import { apiFetch } from '../lib/api.js';
 import { parseRef } from '../lib/ref.js';
 import { handlePublishToggleError } from './publish.js';
 /**
- * Set the `draft` flag back on a published BotDoc, hiding it from
- * `/explore` and 404ing the public URL for everyone except the author.
+ * Hide a skill from the CLI (sets `cli_discoverable = false` server-side): it
+ * stays in the author's web library, but `botdocs install`/`pull`/`list` can
+ * no longer see it. The inverse of `publish @user/slug`.
  *
- * Idempotent server-side — calling unpublish on something already a
- * draft is a no-op. Prompts for confirmation by default because the
- * effect is visible to anyone who had the URL bookmarked; skip with
- * `--yes` for scripting/CI. `--json` implies `--yes` so machine-driven
- * callers don't deadlock on the prompt.
+ * Idempotent server-side — hiding an already-hidden skill is a no-op. Prompts
+ * for confirmation by default (so a stray `unpublish` doesn't quietly pull a
+ * skill out of your agents); skip with `--yes` for scripting/CI. `--json`
+ * implies `--yes` so machine-driven callers don't deadlock on the prompt.
  */
 export async function unpublish(rawRef, options) {
     let parsed;
@@ -25,8 +25,8 @@ export async function unpublish(rawRef, options) {
     const refLabel = `@${username}/${slug}`;
     if (!options.yes && !options.json) {
         const confirmed = await p.confirm({
-            message: `Unpublish ${refLabel}? It will be hidden from /explore and the public URL ` +
-                `will 404 for everyone except you.`,
+            message: `Hide ${refLabel} from the CLI? It stays in your web library, but ` +
+                `the CLI won't be able to install, pull, or list it.`,
             initialValue: false,
         });
         if (p.isCancel(confirmed) || !confirmed) {
@@ -45,9 +45,9 @@ export async function unpublish(rawRef, options) {
         return;
     }
     if (options.json) {
-        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'draft' }));
+        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'cli-hidden' }));
     }
     else {
-        console.log(`✓ Unpublished ${refLabel} — now hidden from /explore.`);
+        console.log(`✓ ${refLabel} is now hidden from the CLI (still in your web library).`);
     }
 }

package/dist/index.js

@@ -182,7 +182,7 @@ program
 });
 program
     .command('publish <source>')
-    .description('Publish a BotDoc — pass a local path to upload, or @user/slug to mark an existing draft live')
+    .description('Add a skill to your library — pass a local path to upload, or @user/slug to make an existing skill discoverable from the CLI')
     .option('--title <title>', 'BotDoc title')
     .option('--description <description>', 'BotDoc description')
     .option('--category <category>', 'Category (knowledge_management, dev_workflow, automation, agent_config, project_scaffold, other)')
@@ -196,14 +196,14 @@ program
 });
 program
     .command('unpublish <ref>')
-    .description('Hide a published BotDoc from /explore (sets the draft flag back)')
+    .description('Hide a skill from the CLI (it stays in your web library)')
     .option('--yes', 'Skip the confirmation prompt')
     .action(async (ref, options) => {
     await unpublish(ref, { ...options, json: program.opts().json });
 });
 program
     .command('delete <ref>')
-    .description('Delete a BotDoc — drafts are hard-deleted with cascade; published BotDocs are soft-deleted (hidden, version history preserved)')
+    .description('Delete a skill — fresh skills (no installs/history) are hard-deleted with cascade; ones with history are soft-deleted (hidden, version history preserved)')
     .option('--yes', 'Skip the confirmation prompt')
     .action(async (ref, options) => {
     await deleteCmd(ref, { ...options, json: program.opts().json });

package/dist/lib/api.d.ts

@@ -105,4 +105,23 @@ export declare function fetchRawContent(rawUrl: string, options?: {
  * stale-token cases are 401, which is handled upstream as "Authentication
  * failed"). */
 export declare function friendlyApiErrorDetail(err: ApiError, ref?: string): string;
+/** The free-tier friction error codes the server returns in the JSON body's
+ * `error` field. Commands branch on these to print a consistent, HONEST CTA
+ * (no fake purchase flow — all accounts are free today). Kept as a union so a
+ * server-side rename breaks the mapping exactly once, here. */
+export type FreeTierErrorCode = 'device_cap_exceeded' | 'session_limit_exceeded' | 'skill_cap_exceeded' | 'library_conflict';
+/**
+ * Map a server error to a friendly, HONEST one-liner for the free-tier
+ * frictions (and the expired-token 401). Returns null when `err` isn't one of
+ * the handled cases, so callers fall back to `friendlyApiErrorDetail`.
+ *
+ * Honesty rule (locked product decision): there is NO purchase/upgrade flow.
+ * Messages communicate the free limit and point at "learn more" docs — they
+ * never promise a working checkout. Higher limits for teams are described as
+ * "coming".
+ *
+ * Centralized here so `install` / `create` / `sync` / `ingest` render the same
+ * vocabulary; a copy tweak is a single edit.
+ */
+export declare function friendlyFreeTierError(err: ApiError): string | null;
 export {};

package/dist/lib/api.js

@@ -1,4 +1,5 @@
-import { loadAuth } from './config.js';
+import os from 'node:os';
+import { loadAuth, getOrCreateDeviceId } from './config.js';
 const DEFAULT_API_URL = 'https://www.botdocs.ai';
 /** Default per-request timeout (ms). Exposed so tests can override without
  * mocking `setTimeout` globally, and so callers can read the value when
@@ -27,6 +28,23 @@ function isLocalhostUrl(u) {
 /** Track whether we've already printed the override-warning so the CLI doesn't
  * spam stderr across every API call in a single process run. */
 let overrideWarnPrinted = false;
+/** Attach the device-identity headers to an authenticated request.
+ *
+ * `X-Device-Id` is the stable per-install id (or the `BOTDOCS_DEVICE_ID`
+ * override); `X-Machine-Name` is a display-only hint the server stores on the
+ * device row. Called from the SAME choke point as the bearer so every
+ * authenticated request carries the device identity — the free-tier
+ * device/session caps depend on it. Best-effort: a failure to resolve the id
+ * (e.g. a read-only home dir) never blocks the request. */
+function attachDeviceHeaders(headers) {
+    try {
+        headers['X-Device-Id'] = getOrCreateDeviceId();
+        headers['X-Machine-Name'] = os.hostname();
+    }
+    catch {
+        // Best-effort — never fail a request because we couldn't stamp a device id.
+    }
+}
 export function getApiUrl() {
     const override = process.env.BOTDOCS_API_URL;
     if (!override)
@@ -148,6 +166,9 @@ export async function apiFetch(path, options = {}) {
         }
         else {
             headers['Authorization'] = `Bearer ${config.token}`;
+            // Same choke point as the bearer: stamp the device identity so the
+            // server's free-tier device/session gates see this request.
+            attachDeviceHeaders(headers);
         }
     }
     // AbortController + setTimeout is the lowest-overhead way to enforce a hard
@@ -245,6 +266,7 @@ export async function fetchRawContent(rawUrl, options = {}) {
     const config = loadAuth();
     if (config?.token) {
         headers['Authorization'] = `Bearer ${config.token}`;
+        attachDeviceHeaders(headers);
     }
     // Same pattern as apiFetch — AbortController + clearTimeout in finally so
     // the timer never outlives the request and blocks process exit.
@@ -302,3 +324,72 @@ export function friendlyApiErrorDetail(err, ref) {
         return err.message;
     return `request failed (${err.status})`;
 }
+/** Narrow an `ApiError.body` to the free-tier error shape when it carries one
+ * of the known codes. Returns null for any other body. */
+function asFreeTierErrorBody(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const code = body.error;
+    if (code === 'device_cap_exceeded' ||
+        code === 'session_limit_exceeded' ||
+        code === 'skill_cap_exceeded' ||
+        code === 'library_conflict') {
+        return { ...body, error: code };
+    }
+    return null;
+}
+/**
+ * Map a server error to a friendly, HONEST one-liner for the free-tier
+ * frictions (and the expired-token 401). Returns null when `err` isn't one of
+ * the handled cases, so callers fall back to `friendlyApiErrorDetail`.
+ *
+ * Honesty rule (locked product decision): there is NO purchase/upgrade flow.
+ * Messages communicate the free limit and point at "learn more" docs — they
+ * never promise a working checkout. Higher limits for teams are described as
+ * "coming".
+ *
+ * Centralized here so `install` / `create` / `sync` / `ingest` render the same
+ * vocabulary; a copy tweak is a single edit.
+ */
+export function friendlyFreeTierError(err) {
+    // Expired-token 401: the server already 401s an expired bearer; surface the
+    // re-login CTA. (Generic 401s are handled upstream in apiFetch with the same
+    // wording; this keeps the mapping in one place for callers that inspect the
+    // raw ApiError.)
+    if (err.status === 401) {
+        return 'Your session has expired. Run `botdocs login` to sign in again.';
+    }
+    const body = asFreeTierErrorBody(err.body);
+    if (!body)
+        return null;
+    switch (body.error) {
+        case 'device_cap_exceeded': {
+            const limit = body.limit;
+            const limitText = typeof limit === 'number' ? `${limit} devices` : 'a limited number of devices';
+            return (`Free accounts are limited to ${limitText}, and you've reached that limit. ` +
+                `Revoke a device you no longer use at https://botdocs.ai/settings, or set ` +
+                `BOTDOCS_DEVICE_ID to reuse one identity in CI. Higher limits for teams are coming — ` +
+                `learn more at https://botdocs.ai/teams.`);
+        }
+        case 'session_limit_exceeded': {
+            const limit = body.limit;
+            const limitText = typeof limit === 'number' ? `${limit} devices` : 'a limited number of devices';
+            return (`Free accounts can be active on ${limitText} at once, and you're over that limit right now. ` +
+                `Wait a few minutes for another device to go idle, or set BOTDOCS_DEVICE_ID to share one ` +
+                `identity in CI. Higher limits for teams are coming — learn more at https://botdocs.ai/teams.`);
+        }
+        case 'skill_cap_exceeded': {
+            const limit = body.limit;
+            const limitText = typeof limit === 'number' ? `${limit} skills` : 'a limited number of skills';
+            return (`Free accounts are limited to ${limitText}, and you've reached that limit. ` +
+                `Remove a skill you no longer need, or learn about higher limits for teams (coming soon) ` +
+                `at https://botdocs.ai/teams.`);
+        }
+        case 'library_conflict': {
+            const device = body.conflictingDevice;
+            const who = device ? ` from "${device}"` : '';
+            return (`Your library was changed by another device${who} since this one last synced. ` +
+                `Run \`botdocs sync\` to pull the latest, then retry.`);
+        }
+    }
+}

package/dist/lib/config.d.ts

@@ -10,10 +10,44 @@ interface AuthConfig {
     username: string;
     displayName: string;
     syncLibrary?: boolean;
+    /** Stable per-install device identity (a v4 UUID) sent to the API as
+     * `X-Device-Id` on every authenticated request. Generated once by
+     * `getOrCreateDeviceId` and NEVER rotated — the free-tier device/session
+     * caps key off it, so rotating would register a phantom new device. CI
+     * runners override it via the `BOTDOCS_DEVICE_ID` env var (see
+     * `getOrCreateDeviceId`) so they don't blow the cap across ephemeral
+     * machines. Optional for backward-compat: auth.json files written before
+     * this field existed lazily gain one on the next `getOrCreateDeviceId`. */
+    deviceId?: string;
+    /** Last server-acknowledged library generation counter (the `version`
+     * returned by POST /api/library/lockfile-sync). The CLI sends it back as
+     * `baseVersion` on the next sync so the server can detect that ANOTHER
+     * device changed the shelf in between and return a 409 `library_conflict`
+     * instead of silently clobbering. Absent until the first successful sync;
+     * a missing value is treated as "no base" (the server force-writes and
+     * stamps a fresh version). */
+    libraryVersion?: number;
 }
 export declare function saveAuth(config: AuthConfig): void;
 export declare function loadAuth(): AuthConfig | null;
 export declare function clearAuth(): void;
+/**
+ * Get the stable device identity for this CLI install, creating it if needed.
+ *
+ * Resolution order:
+ *   1. `BOTDOCS_DEVICE_ID` env var (CI/automation escape hatch) — wins when
+ *      set and non-blank; not persisted.
+ *   2. The `deviceId` already saved in ~/.botdocs/auth.json.
+ *   3. A freshly generated v4 UUID, persisted back into auth.json (when an
+ *      auth config exists) so it's stable across runs.
+ *
+ * The id is NEVER rotated once persisted — the server's device/session caps
+ * key off it. If there's no auth.json yet (user not logged in) we still return
+ * a generated id for the current process but can't persist it; `login` calls
+ * this AFTER saving auth so the id lands in the file. Returns `null` only when
+ * generation itself is impossible (never, in practice).
+ */
+export declare function getOrCreateDeviceId(): string;
 /** One-time startup migration check. If auth.json exists and was created by
  * a pre-P1-G CLI (mode 0644 / world-readable), tighten it in place AND
  * warn the user — the token may have been read by another local user, so

package/dist/lib/config.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { randomUUID } from 'node:crypto';
 // POSIX modes used for the CLI's credential storage. The token lives in
 // auth.json and is the bearer for every authenticated API call — a default
 // umask of 022 leaves the file at 0644 (world-readable) on shared dev
@@ -78,6 +79,45 @@ export function clearAuth() {
         fs.unlinkSync(file);
     }
 }
+/** Env var that pins a stable device identity, overriding the persisted one.
+ * Documented escape hatch for CI/automation: a fleet of ephemeral runners can
+ * export the same `BOTDOCS_DEVICE_ID` so they all present as one device and
+ * don't blow the free-tier device/concurrent-session caps. When set (and
+ * non-blank) it ALWAYS wins and is never persisted. */
+const DEVICE_ID_ENV = 'BOTDOCS_DEVICE_ID';
+/**
+ * Get the stable device identity for this CLI install, creating it if needed.
+ *
+ * Resolution order:
+ *   1. `BOTDOCS_DEVICE_ID` env var (CI/automation escape hatch) — wins when
+ *      set and non-blank; not persisted.
+ *   2. The `deviceId` already saved in ~/.botdocs/auth.json.
+ *   3. A freshly generated v4 UUID, persisted back into auth.json (when an
+ *      auth config exists) so it's stable across runs.
+ *
+ * The id is NEVER rotated once persisted — the server's device/session caps
+ * key off it. If there's no auth.json yet (user not logged in) we still return
+ * a generated id for the current process but can't persist it; `login` calls
+ * this AFTER saving auth so the id lands in the file. Returns `null` only when
+ * generation itself is impossible (never, in practice).
+ */
+export function getOrCreateDeviceId() {
+    const fromEnv = process.env[DEVICE_ID_ENV]?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const config = loadAuth();
+    if (config?.deviceId && config.deviceId.trim().length > 0) {
+        return config.deviceId;
+    }
+    const generated = randomUUID();
+    // Persist back onto the existing auth config so the id is stable across
+    // runs. If there's no auth.json (not logged in), we can't persist — return
+    // the generated id for this process; `login` persists it once auth exists.
+    if (config) {
+        saveAuth({ ...config, deviceId: generated });
+    }
+    return generated;
+}
 export function checkAuthFilePerms() {
     if (process.platform === 'win32')
         return { changed: false };

package/dist/lib/library-sync.d.ts

@@ -3,6 +3,12 @@
  * - file contents (lockfile never contained them, but the route also rejects them)
  * - install destinations (private to the user's machine)
  * - fingerprints (not useful server-side; minimize what we send)
- * Only refs + versions + types remain. Failures are silent so install
- * and sync flows never break on telemetry hiccups. */
+ * Only refs + versions + types remain.
+ *
+ * Sends the last server-acknowledged generation counter as `baseVersion` so
+ * the server can detect a concurrent change from another device and reply 409
+ * `library_conflict` instead of clobbering. On success we persist the new
+ * `version`. On conflict we surface a single honest notice (keep-local +
+ * advise `botdocs sync`). All OTHER failures stay silent so install/sync
+ * flows never break on a telemetry hiccup. */
 export declare function syncLibrary(): Promise<void>;

package/dist/lib/library-sync.js

@@ -1,13 +1,49 @@
-import { apiFetch } from './api.js';
+import { ApiError, apiFetch } from './api.js';
 import { loadLockfile } from './lockfile.js';
-import { loadAuth } from './config.js';
+import { loadAuth, saveAuth } from './config.js';
+/** Narrow an ApiError body to the standard `library_conflict` 409 shape. The
+ * server sends `conflictingDevice` (the device that last touched the shelf);
+ * it may be null when the device name isn't known. */
+function asLibraryConflict(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    if (body.error !== 'library_conflict')
+        return null;
+    return body;
+}
+/** Module-scoped guard so a single CLI invocation (which may call syncLibrary
+ * several times — e.g. install loops) prints the conflict notice at most once.
+ * Reset is unnecessary: the process is short-lived. */
+let conflictNoticePrinted = false;
+/** Print the honest library-conflict CTA to stderr exactly once per process.
+ *
+ * MVP policy (no auto-merge): we KEEP the local shelf untouched — the server
+ * already refused the write, so there's nothing to roll back here — and advise
+ * the user to pull the latest with `botdocs sync` before retrying. Per-member
+ * shelves are mentioned as a coming team feature (honest: no fake purchase).
+ * Goes to stderr so it never disturbs a command's stdout-rendered output. */
+function printConflictNotice(conflictingDevice) {
+    if (conflictNoticePrinted)
+        return;
+    conflictNoticePrinted = true;
+    const who = conflictingDevice ? ` from "${conflictingDevice}"` : '';
+    process.stderr.write(`\n  ⚠ Your library changed on another device${who} since this one last synced.\n` +
+        `    Kept your local copy as-is. Run \`botdocs sync\` to pull the latest, then retry.\n` +
+        `    (Per-member shelves are a coming team feature.)\n`);
+}
 /** Posts a sanitized snapshot of the lockfile to BotDocs if the user has
  * opted-in via `botdocs login --sync-library`. Sanitization strips:
  * - file contents (lockfile never contained them, but the route also rejects them)
  * - install destinations (private to the user's machine)
  * - fingerprints (not useful server-side; minimize what we send)
- * Only refs + versions + types remain. Failures are silent so install
- * and sync flows never break on telemetry hiccups. */
+ * Only refs + versions + types remain.
+ *
+ * Sends the last server-acknowledged generation counter as `baseVersion` so
+ * the server can detect a concurrent change from another device and reply 409
+ * `library_conflict` instead of clobbering. On success we persist the new
+ * `version`. On conflict we surface a single honest notice (keep-local +
+ * advise `botdocs sync`). All OTHER failures stay silent so install/sync
+ * flows never break on a telemetry hiccup. */
 export async function syncLibrary() {
     const auth = loadAuth();
     if (!auth?.syncLibrary)
@@ -15,16 +51,39 @@ export async function syncLibrary() {
     const lf = loadLockfile();
     const sanitized = {
         version: 1,
+        // Generation counter the server last acked. Separate axis from the
+        // lockfile-FORMAT `version: 1` above — this is "which revision of the
+        // shelf did I base this write on". Omitted when we've never synced.
+        baseVersion: auth.libraryVersion,
         installs: lf.installs.map((i) => ({ ref: i.ref, type: i.type, version: i.version })),
     };
     try {
-        await apiFetch('/api/library/lockfile-sync', {
+        const result = await apiFetch('/api/library/lockfile-sync', {
             method: 'POST',
             auth: true,
             body: sanitized,
         });
+        // Persist the new generation counter so the next sync sends it as
+        // baseVersion. Re-load auth in case it changed under us; guard the write
+        // so we don't resurrect a logged-out config.
+        if (typeof result.version === 'number') {
+            const current = loadAuth();
+            if (current)
+                saveAuth({ ...current, libraryVersion: result.version });
+        }
     }
-    catch {
-        // Silent — never break user flows
+    catch (err) {
+        // 409 library_conflict is the ONE telemetry failure worth surfacing — it's
+        // user-actionable (another device moved the shelf). Everything else
+        // (network blips, 5xx, the launch-day waitlist 403) stays silent so the
+        // foreground command isn't disrupted by a background sync.
+        if (err instanceof ApiError && err.status === 409) {
+            const conflict = asLibraryConflict(err.body);
+            if (conflict) {
+                printConflictNotice(conflict.conflictingDevice);
+                return;
+            }
+        }
+        // Silent — never break user flows.
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botdocs/cli",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "CLI for BotDocs — author, publish, install, and sync agent skills across Claude, Claude Code, Cursor, Codex, ChatGPT, Windsurf, Copilot, Gemini, Antigravity, and OpenCode.",
   "keywords": [
     "botdocs",