@bettercms-ai/mcp 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -1,126 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-
-/**
- * Resolved configuration for the BetterCMS MCP server.
- *
- * A single `BETTERCMS_API_URL` (origin, no path) drives both the device-auth
- * endpoints and the Management API base the SDK targets:
- *   device:     {apiUrl}/api/v1/auth/device/*
- *   management: {apiUrl}/api/v1   (SDK appends /management/content/*)
- */
-interface McpConfig {
-    apiUrl: string;
-    deviceBaseUrl: string;
-    managementBaseUrl: string;
-    credentialsPath: string;
-    clientName: string;
-}
-declare function loadConfig(env?: NodeJS.ProcessEnv): McpConfig;
-
-/** Credentials cached between runs so the device flow runs only once per env. */
-interface StoredCredentials {
-    accessToken: string;
-    refreshToken: string;
-    /** Epoch ms when the access token expires. */
-    accessTokenExpiresAt: number;
-    workspaceId: string | null;
-    projectId: string | null;
-}
-/**
- * An authorization the user has been sent off to approve but hasn't yet.
- * Persisted so a later tool call can *resume* polling that same code instead of
- * minting a fresh one — this is what lets the flow survive across the
- * "return the link → user approves → retry" round-trip in clients (VS Code)
- * that never surface the server's stderr prompt.
- */
-interface PendingDevice {
-    deviceCode: string;
-    userCode: string;
-    verificationUri: string;
-    /** verification_uri with `?code=` prefilled — the link we hand the user. */
-    verificationUriComplete: string;
-    intervalSeconds: number;
-    /** Epoch ms when the device code expires. */
-    expiresAt: number;
-}
-/** Persistence boundary for credentials (file-backed in prod, in-memory in tests). */
-interface TokenStore {
-    read(): Promise<StoredCredentials | null>;
-    write(creds: StoredCredentials): Promise<void>;
-    clear(): Promise<void>;
-    /** In-progress device authorization awaiting approval, if any. */
-    readPending(): Promise<PendingDevice | null>;
-    writePending(pending: PendingDevice): Promise<void>;
-    clearPending(): Promise<void>;
-}
-
-/** Injectable seams so tests can run without real timers / network / stderr. */
-interface DeviceAuthDeps {
-    fetch?: typeof fetch;
-    sleep?: (ms: number) => Promise<void>;
-    log?: (message: string) => void;
-    now?: () => number;
-}
-/**
- * Drives the OAuth 2.0 Device Authorization Grant (RFC 8628) against the
- * BetterCMS backend and hands the SDK a valid `content:manage` access token.
- *
- * - `getAccessToken()` returns a usable token: cached if fresh, refreshed if
- *   expired, or freshly minted via the full device flow if there's nothing valid.
- * - All human-facing output goes to stderr — stdout is the MCP JSON-RPC channel.
- */
-declare class DeviceAuthClient {
-    private readonly config;
-    private readonly store;
-    private readonly fetchImpl;
-    private readonly sleep;
-    private readonly log;
-    private readonly now;
-    private inFlight;
-    private refreshInFlight;
-    /** The single live poller for the current device code (see runDeviceFlow). */
-    private pollTask;
-    constructor(config: McpConfig, store: TokenStore, deps?: DeviceAuthDeps);
-    /** Return a valid access token, doing the least work necessary. Single-flighted. */
-    getAccessToken(): Promise<string>;
-    private resolveToken;
-    /**
-     * Resume a still-live authorization if one is persisted, otherwise start a
-     * fresh one; then grace-poll. Throws {@link DeviceAuthPendingError} (carrying
-     * the activation link) if the user hasn't approved within the grace window.
-     */
-    private runDeviceFlow;
-    /** Keep redeeming this code until it expires, detached from any tool call. One per code. */
-    private pollInBackground;
-    /** Request a fresh device code, persist it as pending, and log a breadcrumb. */
-    private startDeviceFlow;
-    /**
-     * Poll the token endpoint until `deadline`. Returns the access token on
-     * approval, or null if the deadline passes while still pending. Throws
-     * {@link DeviceAuthError} on a terminal outcome (denied / expired).
-     */
-    private pollForApproval;
-    /**
-     * Exchange the stored refresh token for a new access token. Single-flighted:
-     * the device `/refresh` endpoint is single-use (it rotates the refresh token
-     * and revokes the prior access key), so a burst of concurrent 401s must NOT
-     * each fire their own refresh — the first would rotate, and the rest would
-     * send the now-stale token, get `invalid_grant`, and wipe the freshly-minted
-     * credentials. Collapsing them into one in-flight rotation keeps the session
-     * alive without a needless re-auth.
-     */
-    refresh(): Promise<string | null>;
-    /**
-     * Forget the cached credentials and start a fresh device flow. Called when the
-     * bound project was deleted server-side (a key bound to a dead project can never
-     * succeed again) — clearing lets the user re-authorize against a LIVE project.
-     * Returns a new token if approval is fast, else throws {@link DeviceAuthPendingError}
-     * carrying the activation link (the next tool call resumes into the new project).
-     */
-    resetAndReauthorize(): Promise<string>;
-    private doRefresh;
-    private persist;
-}
+import { DeviceAuthClient } from '@bettercms-ai/device-auth';
+export { DeviceAuthClient, loadConfig } from '@bettercms-ai/device-auth';
 
 interface BuildServerDeps {
     auth: DeviceAuthClient;
@@ -133,4 +13,4 @@ interface BuildServerDeps {
  */
 declare function buildServer(deps: BuildServerDeps): McpServer;
 
-export { DeviceAuthClient, buildServer, loadConfig };
+export { buildServer };

package/dist/index.js

@@ -4,309 +4,7 @@
 import { realpathSync } from "fs";
 import { fileURLToPath } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-// src/config.ts
-import { homedir } from "os";
-import { join } from "path";
-var DEFAULT_API_URL = "https://api.bettercms.ai";
-function loadConfig(env = process.env) {
-  const apiUrl = (env.BETTERCMS_API_URL?.trim() || DEFAULT_API_URL).replace(/\/+$/, "");
-  return {
-    apiUrl,
-    deviceBaseUrl: `${apiUrl}/api/v1/auth/device`,
-    managementBaseUrl: `${apiUrl}/api/v1`,
-    credentialsPath: env.BETTERCMS_MCP_CREDENTIALS?.trim() || join(homedir(), ".bettercms", "mcp-credentials.json"),
-    clientName: env.BETTERCMS_MCP_CLIENT_NAME?.trim() || "BetterCMS MCP"
-  };
-}
-
-// src/token-store.ts
-import { mkdir, readFile, writeFile } from "fs/promises";
-import { dirname } from "path";
-var FileTokenStore = class {
-  constructor(path, key) {
-    this.path = path;
-    this.key = key;
-    this.pendingKey = `${key}::pending`;
-  }
-  path;
-  key;
-  /** Pending authorizations live under a sibling key so they never shadow creds. */
-  pendingKey;
-  async readAll() {
-    try {
-      const raw = await readFile(this.path, "utf-8");
-      const parsed = JSON.parse(raw);
-      return parsed && typeof parsed === "object" ? parsed : {};
-    } catch {
-      return {};
-    }
-  }
-  async writeAll(all) {
-    await mkdir(dirname(this.path), { recursive: true });
-    await writeFile(this.path, JSON.stringify(all, null, 2), { mode: 384 });
-  }
-  async read() {
-    const all = await this.readAll();
-    return all[this.key] ?? null;
-  }
-  async write(creds) {
-    const all = await this.readAll();
-    all[this.key] = creds;
-    await this.writeAll(all);
-  }
-  async clear() {
-    const all = await this.readAll();
-    delete all[this.key];
-    await this.writeAll(all);
-  }
-  async readPending() {
-    const all = await this.readAll();
-    return all[this.pendingKey] ?? null;
-  }
-  async writePending(pending) {
-    const all = await this.readAll();
-    all[this.pendingKey] = pending;
-    await this.writeAll(all);
-  }
-  async clearPending() {
-    const all = await this.readAll();
-    delete all[this.pendingKey];
-    await this.writeAll(all);
-  }
-};
-
-// src/device-auth.ts
-var EXPIRY_SKEW_MS = 6e4;
-var GRACE_POLL_MS = 25e3;
-var DeviceAuthError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "DeviceAuthError";
-  }
-};
-var DeviceAuthPendingError = class extends Error {
-  verificationUri;
-  verificationUriComplete;
-  userCode;
-  expiresAt;
-  constructor(pending) {
-    super("Authorization pending \u2014 approve in the browser, then retry.");
-    this.name = "DeviceAuthPendingError";
-    this.verificationUri = pending.verificationUri;
-    this.verificationUriComplete = pending.verificationUriComplete;
-    this.userCode = pending.userCode;
-    this.expiresAt = pending.expiresAt;
-  }
-};
-var DeviceAuthClient = class {
-  constructor(config, store, deps = {}) {
-    this.config = config;
-    this.store = store;
-    this.fetchImpl = deps.fetch ?? globalThis.fetch;
-    this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    this.log = deps.log ?? ((m) => process.stderr.write(`${m}
-`));
-    this.now = deps.now ?? (() => Date.now());
-  }
-  config;
-  store;
-  fetchImpl;
-  sleep;
-  log;
-  now;
-  inFlight = null;
-  refreshInFlight = null;
-  /** The single live poller for the current device code (see runDeviceFlow). */
-  pollTask = null;
-  /** Return a valid access token, doing the least work necessary. Single-flighted. */
-  async getAccessToken() {
-    if (this.inFlight) return this.inFlight;
-    this.inFlight = this.resolveToken().finally(() => {
-      this.inFlight = null;
-    });
-    return this.inFlight;
-  }
-  async resolveToken() {
-    const creds = await this.store.read();
-    if (creds && creds.accessTokenExpiresAt - this.now() > EXPIRY_SKEW_MS) {
-      return creds.accessToken;
-    }
-    if (creds?.refreshToken) {
-      const refreshed = await this.refresh();
-      if (refreshed) return refreshed;
-    }
-    return this.runDeviceFlow();
-  }
-  /**
-   * Resume a still-live authorization if one is persisted, otherwise start a
-   * fresh one; then grace-poll. Throws {@link DeviceAuthPendingError} (carrying
-   * the activation link) if the user hasn't approved within the grace window.
-   */
-  async runDeviceFlow() {
-    let pending = await this.store.readPending();
-    if (pending && pending.expiresAt - this.now() <= EXPIRY_SKEW_MS) {
-      await this.store.clearPending();
-      pending = null;
-    }
-    if (!pending) {
-      pending = await this.startDeviceFlow();
-    }
-    const graceDeadline = Math.min(this.now() + GRACE_POLL_MS, pending.expiresAt);
-    const token = this.pollTask ? await Promise.race([this.pollTask, this.sleep(GRACE_POLL_MS).then(() => null)]) : await this.pollForApproval(pending, graceDeadline);
-    if (token) return token;
-    this.pollInBackground(pending);
-    throw new DeviceAuthPendingError(pending);
-  }
-  /** Keep redeeming this code until it expires, detached from any tool call. One per code. */
-  pollInBackground(pending) {
-    if (this.pollTask) return;
-    const task = this.pollForApproval(pending, pending.expiresAt);
-    this.pollTask = task;
-    void task.catch(() => {
-    }).finally(() => {
-      if (this.pollTask === task) this.pollTask = null;
-    });
-  }
-  /** Request a fresh device code, persist it as pending, and log a breadcrumb. */
-  async startDeviceFlow() {
-    const start = await this.fetchImpl(`${this.config.deviceBaseUrl}/code`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ client_name: this.config.clientName })
-    });
-    if (!start.ok) {
-      throw new DeviceAuthError(
-        `Failed to start device authorization (HTTP ${start.status}).`
-      );
-    }
-    const code = await start.json();
-    const pending = {
-      deviceCode: code.device_code,
-      userCode: code.user_code,
-      verificationUri: code.verification_uri,
-      verificationUriComplete: code.verification_uri_complete ?? `${code.verification_uri}?code=${encodeURIComponent(code.user_code)}`,
-      intervalSeconds: code.interval,
-      expiresAt: this.now() + code.expires_in * 1e3
-    };
-    await this.store.writePending(pending);
-    this.pollTask = null;
-    this.log("");
-    this.log("\u250C\u2500 BetterCMS authorization required \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-    this.log(`\u2502 Visit: ${pending.verificationUri}`);
-    this.log(`\u2502 Enter code: ${pending.userCode}`);
-    this.log(`\u2502 Or open: ${pending.verificationUriComplete}`);
-    this.log("\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-    return pending;
-  }
-  /**
-   * Poll the token endpoint until `deadline`. Returns the access token on
-   * approval, or null if the deadline passes while still pending. Throws
-   * {@link DeviceAuthError} on a terminal outcome (denied / expired).
-   */
-  async pollForApproval(pending, deadline) {
-    let intervalMs = pending.intervalSeconds * 1e3;
-    while (this.now() < deadline) {
-      await this.sleep(intervalMs);
-      if (this.now() >= deadline) break;
-      const res = await this.fetchImpl(`${this.config.deviceBaseUrl}/token`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          device_code: pending.deviceCode,
-          grant_type: "urn:ietf:params:oauth:grant-type:device_code"
-        })
-      });
-      if (res.ok) {
-        const body = await res.json();
-        await this.store.clearPending();
-        this.log("[bettercms-mcp] authorized \u2713");
-        return this.persist(body);
-      }
-      const err = await res.json().catch(() => ({}));
-      switch (err.error) {
-        case "authorization_pending":
-          continue;
-        case "slow_down":
-          intervalMs += 5e3;
-          continue;
-        case "access_denied":
-          await this.store.clearPending();
-          throw new DeviceAuthError("Authorization was denied.");
-        case "expired_token":
-          await this.store.clearPending();
-          throw new DeviceAuthError("The device code expired before approval. Try again.");
-        default:
-          throw new DeviceAuthError(
-            `Device authorization failed: ${err.error ?? `HTTP ${res.status}`}.`
-          );
-      }
-    }
-    return null;
-  }
-  /**
-   * Exchange the stored refresh token for a new access token. Single-flighted:
-   * the device `/refresh` endpoint is single-use (it rotates the refresh token
-   * and revokes the prior access key), so a burst of concurrent 401s must NOT
-   * each fire their own refresh — the first would rotate, and the rest would
-   * send the now-stale token, get `invalid_grant`, and wipe the freshly-minted
-   * credentials. Collapsing them into one in-flight rotation keeps the session
-   * alive without a needless re-auth.
-   */
-  async refresh() {
-    if (this.refreshInFlight) return this.refreshInFlight;
-    this.refreshInFlight = this.doRefresh().finally(() => {
-      this.refreshInFlight = null;
-    });
-    return this.refreshInFlight;
-  }
-  /**
-   * Forget the cached credentials and start a fresh device flow. Called when the
-   * bound project was deleted server-side (a key bound to a dead project can never
-   * succeed again) — clearing lets the user re-authorize against a LIVE project.
-   * Returns a new token if approval is fast, else throws {@link DeviceAuthPendingError}
-   * carrying the activation link (the next tool call resumes into the new project).
-   */
-  async resetAndReauthorize() {
-    await this.store.clear();
-    await this.store.clearPending();
-    return this.getAccessToken();
-  }
-  async doRefresh() {
-    const creds = await this.store.read();
-    if (!creds?.refreshToken) return null;
-    let res;
-    try {
-      res = await this.fetchImpl(`${this.config.deviceBaseUrl}/refresh`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ refresh_token: creds.refreshToken })
-      });
-    } catch {
-      return null;
-    }
-    if (res.ok) {
-      const body = await res.json();
-      return this.persist(body);
-    }
-    const err = await res.json().catch(() => ({}));
-    if (err.error === "invalid_grant" || res.status === 401 || res.status === 403) {
-      await this.store.clear();
-    }
-    return null;
-  }
-  async persist(body) {
-    const creds = {
-      accessToken: body.access_token,
-      refreshToken: body.refresh_token,
-      accessTokenExpiresAt: this.now() + body.expires_in * 1e3,
-      workspaceId: body.workspace_id,
-      projectId: body.project_id
-    };
-    await this.store.write(creds);
-    return creds.accessToken;
-  }
-};
+import { loadConfig, FileTokenStore, DeviceAuthClient } from "@bettercms-ai/device-auth";
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -2282,6 +1980,7 @@ var LAYOUT_SECTION_ICON_SET = new Set(LAYOUT_SECTION_ICONS);
 
 // src/tools.ts
 import { BetterCMSError } from "@bettercms-ai/sdk";
+import { DeviceAuthPendingError } from "@bettercms-ai/device-auth";
 var FRAMEWORK_CHOICES = ["astro", "next", "react-ts", "other"];
 var FRAMEWORK_LABELS = {
   astro: "Astro \u2014 recommended default, static by default and fastest to publish",
@@ -3183,6 +2882,16 @@ function buildToolDefs(deps) {
         z.object({ declaredBindings: z.boolean().describe("true = trust the template's declared bindings; false = text-match (the default)") }).shape,
         async (c, a) => ok("Recorded the binding mode.", await data(c, "PATCH", `/management/projects/current/binding-mode`, { declaredBindings: a.declaredBindings }))
       ),
+      def(
+        "submit_conversion_receipt",
+        "Record what the conversion codemod could and could not do",
+        "Hand BetterCMS the codemod's own account of a conversion run, so the coverage meter can say WHY a path is not declared instead of only that it is not. Submit the receipt `npx @bettercms-ai/convert` wrote (`--receipt out.json`) for the SAME `briefDigest` get_conversion_brief { complete: true } returned: `{ briefDigest, receipt }`, where the receipt carries `paths: { declared, rewritten, alreadyDeclared, pending[{ route, scope, path, kind, file, reason, message }] }`. `paths.declared` must equal rewritten + alreadyDeclared + pending.length, and each pending `reason` is one of the converter's own (IN_EXPRESSION, AMBIGUOUS_LITERAL, REPEATER_FIXED_LENGTH, PARSE_ERROR, \u2026) \u2014 a path with no receipt row simply reads `not-declared`. It is a RECORD, not a release: it changes nothing about the site, and the meter picks it up on the next get_binding_report after the next deploy. A 404 `unknown-brief` means that digest was never issued here, so convert against a brief this project actually returned. Requires a project-scoped connection carrying artifact:write, the same authority as set_binding_mode.",
+        z.object({
+          briefDigest: z.string().min(1).describe("The `briefDigest` get_conversion_brief { complete: true } returned. Must match the receipt's own."),
+          receipt: z.record(z.string(), z.unknown()).describe("The receipt `npx @bettercms-ai/convert --receipt out.json` wrote, verbatim.")
+        }).shape,
+        async (c, a) => ok("Recorded the conversion receipt.", await data(c, "POST", `/management/projects/current/conversion-receipt`, { briefDigest: a.briefDigest, receipt: a.receipt }))
+      ),
       def(
         "clone_project",
         "Clone a project",
@@ -3302,14 +3011,17 @@ function buildToolDefs(deps) {
       def(
         "get_conversion_brief",
         "Get the brief for making this site's bindings durable",
-        "The per-project brief for making this site's bindings DURABLE \u2014 read it before you touch the templates. Returns what already exists in the CMS: every live page with its route, and every bindable field path with its `label`, `kind`, the value the CMS holds now (`current`) and the copy the repo renders today (`original`, the field's defaultValue) \u2014 plus the exact attributes to declare, and the ordered steps. Call it for any site whose pages were DERIVED at import, and whenever get_next_steps reports `bindings-not-declared`. It REPLACES re-registering a schema: these pages, fields and values exist already, so create_page / add_page_field / create_content_model would build a second schema over the first \u2014 edit values with set_page_content instead. `lane` says how to get the source ('git-connected' = pull_project_source returns a repo; 'archive' = a tarball). The full recipe is section 13 of the bettercms://playbook/schema resource; get_binding_report is the receipt that says you finished.",
-        z.object({}).shape,
-        async (c) => ok("Conversion brief.", await data(c, "GET", `/management/projects/current/conversion-brief`))
+        "The per-project brief for making this site's bindings DURABLE \u2014 read it before you touch the templates. Returns what already exists in the CMS: every live page with its route, and every bindable field path with its `label`, `kind`, the value the CMS holds now (`current`) and the copy the repo renders today (`original`, the field's defaultValue) \u2014 plus the exact attributes to declare, and the ordered steps. Call it for any site whose pages were DERIVED at import, and whenever get_next_steps reports `bindings-not-declared`. It REPLACES re-registering a schema: these pages, fields and values exist already, so create_page / add_page_field / create_content_model would build a second schema over the first \u2014 edit values with set_page_content instead. `lane` says how to get the source ('git-connected' = pull_project_source returns a repo; 'archive' = a tarball). The full recipe is section 13 of the bettercms://playbook/schema resource; get_binding_report is the receipt that says you finished. Pass `complete: true` when you are about to run the CODEMOD (`npx @bettercms-ai/convert`): that returns the brief UNCAPPED and paged \u2014 nothing truncated, no page omitted \u2014 and pins the full path list under a `briefDigest`, which is the list the coverage meter in get_binding_report measures the build against. Follow `cursor` until it stops coming back; a 409 `BRIEF_CHANGED` means the brief was re-derived while you paged, so start again.",
+        z.object({
+          complete: z.boolean().optional().describe("true = the COMPLETE brief for a codemod: nothing truncated, no page omitted, paged 50 pages at a time. Page 1 pins the path list the coverage meter measures against."),
+          cursor: z.string().optional().describe("The `cursor` from the previous page. Implies complete. A 409 BRIEF_CHANGED means the brief was re-derived mid-pagination \u2014 start again with no cursor.")
+        }).shape,
+        async (c, a) => ok("Conversion brief.", await data(c, "GET", `/management/projects/current/conversion-brief${q({ complete: a.complete, cursor: a.cursor })}`))
       ),
       def(
         "get_conversion_plan",
         "Get the approved conversion to apply",
-        "The APPROVED conversion a human reviewed in the BetterCMS dashboard: the exact new contents of each template file, already checked against this project's real field paths. Apply it instead of writing the bindings by hand. Check out `baseHeadOid` (the exact commit it was written against \u2014 a plan applied to a different base is a different change), branch from there, write each file's `content` verbatim (whole file, no merge, no reformatting), then push or deploy however this project ships. `stale.head` / `stale.brief` say the repository or the CMS moved since it was approved: stop and ask for a fresh proposal rather than applying it anyway. Finish the loop the same way as a hand conversion \u2014 get_binding_report until `unmatched` is empty, then set_binding_mode { declaredBindings: true } and release once more. 404 with `code: \"no-approved-plan\"` means nobody has approved one: use get_conversion_brief and do the conversion yourself. Requires a project-scoped connection carrying artifact:write.",
+        "The APPROVED conversion a human reviewed in the BetterCMS dashboard: the exact new contents of each template file, already checked against this project's real field paths. Apply it instead of writing the bindings by hand. Check out `baseHeadOid` (the exact commit it was written against \u2014 a plan applied to a different base is a different change), branch from there, write each file's `content` verbatim (whole file, no merge, no reformatting), then push or deploy however this project ships. `stale.head` / `stale.brief` say the repository or the CMS moved since it was approved: stop and ask for a fresh proposal rather than applying it anyway. `receipt.paths.pending` lists every field the codemod could NOT bind, each with a reason (`DIALECT_UNSUPPORTED`, `PROP_TARGET_NOT_FOUND`, `REPEATER_FIXED_LENGTH`, \u2026) \u2014 apply the plan first, then bind those by hand. Finish the loop the same way as a hand conversion \u2014 get_binding_report until `unmatched` is empty, then set_binding_mode { declaredBindings: true } and release once more. 404 with `code: \"no-approved-plan\"` means nobody has approved one: use get_conversion_brief and do the conversion yourself. Requires a project-scoped connection carrying artifact:write.",
         z.object({}).shape,
         async (c) => ok("Approved conversion plan.", await data(c, "GET", `/management/projects/current/conversion-plan`))
       ),
@@ -4321,6 +4033,34 @@ first: it lists those pages, their routes, every bindable path with its current
 value, and the attributes to declare. SKIP steps 3 and 4 below and bind the keys it names \u2014
 registering the schema again builds a second one over the first.
 
+**Run the CODEMOD rather than editing by hand.** For a derived site the whole of step 5 is
+mechanical, and there is a tool that does it. THE ORDER, and every step of it matters:
+
+1. \`get_conversion_brief { complete: true }\` \u2014 the COMPLETE brief, not the capped one. It comes
+   back uncapped and paged (50 pages at a time): follow \`cursor\` until it stops coming back and
+   keep every page. The capped read truncates values and omits pages, and a codemod fed a
+   truncated \`original\` searches the source for a string that is not there. Page 1 PINS the
+   path list under a \`briefDigest\`; that pinned list is what the coverage meter measures the
+   build against, so nothing later can move the denominator. A 409 \`BRIEF_CHANGED\` mid-pagination
+   means the brief was re-derived under you \u2014 start again with no cursor.
+2. Write the pages you collected to \`brief.json\` and run
+   \`npx @bettercms-ai/convert --brief brief.json --root . --receipt receipt.json\`, then read
+   \`git diff\`. It rewrites the templates to read from BetterCMS, keeps the in-code copy as the
+   fallback, and declares each binding.
+3. REVIEW THE PENDING LIST. Every path the codemod could not do is in \`paths.pending\` with a
+   reason (\`IN_EXPRESSION\`, \`AMBIGUOUS_LITERAL\`, \`REPEATER_FIXED_LENGTH\`, \`PARSE_ERROR\`, \u2026).
+   Do those by hand, or decide they are genuinely not convertible \u2014 do not skip past them.
+4. \`submit_conversion_receipt { briefDigest, receipt }\` with the receipt file, verbatim. This is
+   what lets the coverage meter say WHY a path is undeclared instead of only that it is; without
+   it every one of them reads \`not-declared\`, which looks like a broken site rather than work
+   with a reason. It records and releases nothing.
+5. Push, or \`deploy_project\`, and wait for the release to be live (step 6 below).
+6. \`get_binding_report\`. Alongside \`unmatched\` it now carries \`coverage\` \u2014 \`declared\` (what the
+   brief listed), \`bound\` (what the build declares) and \`pending\` with the reasons. Fix what it
+   names and release again until \`coverage.pending\` is empty.
+7. \`set_binding_mode { declaredBindings: true }\` and release ONE MORE TIME \u2014 the mode applies to
+   the next release, not to the one already out.
+
 **Or let BetterCMS propose the edit.** \`get_conversion_plan\` returns an APPROVED conversion \u2014 the
 exact new contents of each template file, reviewed by a human in the dashboard and already checked
 against this project's real field paths. When there is one, apply it instead of doing step 5 by
@@ -4356,9 +4096,20 @@ conversion is yours to write.
    Prefer schema-derived bindings \u2014 the TypeGen analogue:
    \`npx @bettercms-ai/codegen --bindings-out src/bettercms.bindings.generated.ts\`, then spread
    \`{...bcms.home.hero.title}\` / \`{...bcms.blog.features.$(i)}\`. The hand form is
-   \`data-bcms-field="<path>"\` (plus \`data-bcms-kind="richtext"|"image"\`), \`data-bcms-props\`
-   for an \`href\` / \`alt\` / \`src\`, the \xA711 layout markers for nav and footer, and
-   \`<div data-bcms-field="body" data-bcms-kind="document">\` around a Portable Text render.
+   \`data-bcms-field="<path>"\` (plus \`data-bcms-kind="richtext"|"image"\`), the \xA711 layout markers
+   for nav and footer, and \`<div data-bcms-field="body" data-bcms-kind="document">\` around a
+   Portable Text render.
+   **A value that lives in an ATTRIBUTE \u2014 an \`href\`, an \`alt\`, an \`src\` \u2014 rides
+   \`data-bcms-props\`, and its grammar is PIPES, NOT JSON:**
+   \`data-bcms-props="<path>|<kind>|<domAttribute>"\`, semicolon-separated for several on one
+   element, where \`kind\` is \`text | richtext | image | url | number | array\`. A link is
+   \`data-bcms-props="cta.url|url|href"\`; an image's alt text is
+   \`data-bcms-props="hero.image.alt|text|alt"\`; an \`<a>\` wrapping an \`<img>\` carries both as
+   \`data-bcms-props="cta.url|url|href;hero.image.alt|text|alt"\`. A JSON object there parses to
+   NOTHING \u2014 the reader splits on \`;\` and \`|\` and drops what does not match \u2014 so the value stays
+   uneditable and the binding report never mentions it. The SDK helpers
+   (\`@bettercms-ai/astro\`, \`@bettercms-ai/next\`) and \`@bettercms-ai/codegen\` emit this form
+   for you; write it by hand only when you are not using them.
    Bind CONDITIONALLY (\`fromCms ? path : undefined\`) so a fallback row is never bound. A value
    rendered in N places carries the binding on ALL N \u2014 the editor keeps the copies in sync.
    **Read the LIVE SCHEMA before you bind \u2014 \`get_page\` / \`get_content_model\`, never the
@@ -4382,11 +4133,13 @@ conversion is yours to write.
       one the site renders its fallbacks and the report says \`no-element\` for every path.
 6. Push, or \`deploy_project\`; poll \`get_deploy_status\` until it is live. Then
    \`get_binding_report\` \u2014 still \`text-match\`, and \`unmatched\` should be EMPTY because the
-   values are byte-equal to what the build renders. Now \`set_binding_mode
+   values are byte-equal to what the build renders. On a converted site read \`coverage\` too: it
+   counts the PINNED brief's paths, which \`unmatched\` cannot, because \`unmatched\` only ever
+   speaks about fields that already hold a value. Now \`set_binding_mode
    {declaredBindings: true}\` and release again (an empty commit is enough). Do not flip before
    the report is clean: in declared mode an undeclared field simply stops being editable.
-7. **Receipts.** \`get_binding_report\` reads \`mode: "declared"\`, \`unmatched: []\`, and
-   \`bound > 0\`. That certifies one thing only \u2014 that every non-empty field has SOME element
+7. **Receipts.** \`get_binding_report\` reads \`mode: "declared"\`, \`unmatched: []\`,
+   \`bound > 0\`, and \u2014 for a site converted against a pinned brief \u2014 \`coverage.pending: []\`. That certifies one thing only \u2014 that every non-empty field has SOME element
    carrying its path. It CANNOT see copy that was never modelled, so diff each route's visible
    text against its entry values yourself before you call the page done. Then publish, and
    fetch the live URL cache-busted (\xA712: publish and deploy are separate claims).
@@ -4870,6 +4623,7 @@ function buildServer(deps) {
 }
 
 // src/index.ts
+import { DeviceAuthClient as DeviceAuthClient2, loadConfig as loadConfig2 } from "@bettercms-ai/device-auth";
 async function main() {
   const config = loadConfig();
   const store = new FileTokenStore(config.credentialsPath, config.apiUrl);
@@ -4897,8 +4651,8 @@ if (isMainModule()) {
   });
 }
 export {
-  DeviceAuthClient,
+  DeviceAuthClient2 as DeviceAuthClient,
   buildServer,
-  loadConfig
+  loadConfig2 as loadConfig
 };
 //# sourceMappingURL=index.js.map