@headband/cli 0.3.0 → 0.6.1

package/dist/index.js

@@ -35,14 +35,16 @@ __export(index_exports, {
   main: () => main,
   parseArgv: () => parseArgv,
   parseExpires: () => parseExpires,
+  parseIndexList: () => parseIndexList,
   parsePermissions: () => parsePermissions,
   run: () => run,
-  stdinIsInteractive: () => stdinIsInteractive
+  stdinIsInteractive: () => stdinIsInteractive,
+  syncClientFromFlags: () => syncClientFromFlags
 });
 module.exports = __toCommonJS(index_exports);
-var import_fs10 = require("fs");
 var import_fs11 = require("fs");
-var import_path9 = require("path");
+var import_fs12 = require("fs");
+var import_path11 = require("path");
 var import_prompts2 = __toESM(require("prompts"));
 var import_picocolors3 = __toESM(require("picocolors"));
 
@@ -58,6 +60,9 @@ var import_path = require("path");
 function isPublicSearchKey(value) {
   return /^hb_src_[A-Za-z0-9_-]+$/.test(value.trim());
 }
+function displayPrefixOf(raw) {
+  return raw.slice(0, raw.length === 55 ? 16 : 12);
+}
 function validatePublicSearchKey(value) {
   if (!value.trim()) return "Search API key is required";
   if (value.startsWith("hb_adm_")) {
@@ -292,6 +297,9 @@ var ApiError = class extends CliError {
     this.details = details;
   }
 };
+function restate(error, message) {
+  return new ApiError(message, error.status, error.code, error.details);
+}
 var DEFAULT_CODES = {
   [EXIT_CODES.generic]: "error",
   [EXIT_CODES.usage]: "usage_error",
@@ -502,6 +510,25 @@ function resolveAuth(selectors = {}) {
 }
 
 // src/api.ts
+var MAX_RETRY_AFTER_S = 10;
+var RATE_LIMIT_RETRIES = 2;
+function retryAfterSeconds(response) {
+  const raw = response.headers.get("retry-after");
+  if (raw === null || !/^\d+$/.test(raw.trim())) return null;
+  const s = parseInt(raw, 10);
+  return s <= MAX_RETRY_AFTER_S ? s : null;
+}
+function errorMessageOf(status, errorBody) {
+  const message = errorBody.error || `Request failed with status ${status}`;
+  if (status === 429 && typeof errorBody.message === "string" && errorBody.message.trim()) {
+    return `${message}. ${errorBody.message.trim()}`;
+  }
+  if (errorBody.code === "partial_failure" && Array.isArray(errorBody.errors)) {
+    return partialFailureSummary({ message, errors: errorBody.errors });
+  }
+  return message;
+}
+var defaultSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 async function readJson(response) {
   const text = await response.text();
   if (!text) return {};
@@ -521,13 +548,21 @@ async function apiRequest(baseUrl, path2, init2 = {}) {
     headers.set("authorization", `Bearer ${init2.apiKey}`);
   }
   const base = normalizeUrl(baseUrl);
+  const { rateLimitRetries = 0, sleep = defaultSleep, apiKey: _apiKey, ...fetchInit } = init2;
+  void _apiKey;
   let response;
   try {
-    response = await fetch(`${base}${path2}`, {
-      ...init2,
-      headers,
-      body: init2.body === void 0 || typeof init2.body === "string" ? init2.body : JSON.stringify(init2.body)
-    });
+    for (let attempt = 0; ; attempt++) {
+      response = await fetch(`${base}${path2}`, {
+        ...fetchInit,
+        headers,
+        body: init2.body === void 0 || typeof init2.body === "string" ? init2.body : JSON.stringify(init2.body)
+      });
+      const wait = response.status === 429 ? retryAfterSeconds(response) : null;
+      if (wait === null || attempt >= rateLimitRetries) break;
+      await response.body?.cancel().catch(() => void 0);
+      await sleep(wait * 1e3);
+    }
   } catch (error) {
     const cause = error?.cause;
     const detail = cause?.code || cause?.message || (error instanceof Error ? error.message : "");
@@ -540,7 +575,7 @@ async function apiRequest(baseUrl, path2, init2 = {}) {
   if (!response.ok) {
     const errorBody = body && typeof body === "object" ? body : {};
     throw new ApiError(
-      errorBody.error || `Request failed with status ${response.status}`,
+      errorMessageOf(response.status, errorBody),
       response.status,
       errorBody.code,
       body
@@ -549,18 +584,23 @@ async function apiRequest(baseUrl, path2, init2 = {}) {
   return body;
 }
 function createApiClient(url, profile) {
-  const request = (path2, init2 = {}) => apiRequest(url, path2, { ...init2, apiKey: profile.apiKey });
+  const request = (path2, init2 = {}) => apiRequest(url, path2, {
+    ...init2,
+    apiKey: profile.apiKey,
+    headers: profile.headers,
+    rateLimitRetries: RATE_LIMIT_RETRIES
+  });
   return {
     url: normalizeUrl(url),
     get: (path2) => request(path2, { method: "GET" }),
     post: (path2, body) => request(path2, { method: "POST", body }),
     patch: (path2, body) => request(path2, { method: "PATCH", body }),
-    delete: (path2) => request(path2, { method: "DELETE" })
+    delete: (path2, body) => request(path2, body === void 0 ? { method: "DELETE" } : { method: "DELETE", body })
   };
 }
 
 // src/auth.ts
-var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var defaultSleep2 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 function openBrowser(url) {
   try {
     if (process.platform === "darwin") {
@@ -575,7 +615,7 @@ function openBrowser(url) {
 }
 async function runDeviceFlow(url, io, options = {}) {
   const baseUrl = normalizeUrl(url);
-  const sleep = options.sleep || defaultSleep;
+  const sleep = options.sleep || defaultSleep2;
   const now = options.now || Date.now;
   const device = await apiRequest(baseUrl, "/api/cli/device", {
     method: "POST",
@@ -644,11 +684,564 @@ async function login(url, io, options = {}) {
   };
 }
 
-// src/config-load.ts
+// src/branch.ts
+var import_path5 = require("path");
+
+// src/output.ts
+var defaultIO = {
+  stdout: (message = "") => console.log(message),
+  stderr: (message = "") => console.error(message)
+};
+function printJson(io, value) {
+  io.stdout(JSON.stringify(value, null, 2));
+}
+function formatTable(rows, columns) {
+  if (rows.length === 0) return "No results.";
+  const selectedColumns = columns || Object.keys(rows[0]);
+  const widths = selectedColumns.map(
+    (column) => Math.max(
+      column.length,
+      ...rows.map(
+        (row) => String(row[column] === null || row[column] === void 0 ? "" : row[column]).length
+      )
+    )
+  );
+  const renderRow = (values) => values.map((value, index) => value.padEnd(widths[index])).join("  ").trimEnd();
+  return [
+    renderRow(selectedColumns),
+    renderRow(widths.map((width) => "-".repeat(width))),
+    ...rows.map(
+      (row) => renderRow(
+        selectedColumns.map(
+          (column) => String(row[column] === null || row[column] === void 0 ? "" : row[column])
+        )
+      )
+    )
+  ].join("\n");
+}
+function printTable(io, rows, columns) {
+  io.stdout(formatTable(rows, columns));
+}
+function summarizeHit(hit) {
+  const result = {};
+  for (const key of Object.keys(hit).slice(0, 5)) {
+    const value = hit[key];
+    result[key] = value && typeof value === "object" ? JSON.stringify(value) : value;
+  }
+  return result;
+}
+
+// src/project-file.ts
 var import_fs3 = require("fs");
+var import_os3 = require("os");
 var import_path4 = require("path");
+var PROJECT_DIR = ".headband";
+var PROJECT_FILE = "project.json";
+var PROJECT_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+var BRANCH_NAME_RE = /^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$/;
+var BRANCH_ID_RE = /^br_[a-z0-9]{12}$/;
+var CONTROL_RE = /[\u0000-\u001f\u007f]/;
+var isProjectId = (v) => typeof v === "string" && PROJECT_ID_RE.test(v);
+var isBranchId = (v) => typeof v === "string" && BRANCH_ID_RE.test(v);
+var isBranchName = (v) => typeof v === "string" && BRANCH_NAME_RE.test(v) && !BRANCH_ID_RE.test(v);
+var isOrgId = (v) => typeof v === "string" && v.length > 0 && !CONTROL_RE.test(v);
+function isProjectFile(v) {
+  return Boolean(
+    v && isOrgId(v.orgId) && isProjectId(v.projectId) && (isBranchName(v.branch) || isBranchId(v.branch))
+  );
+}
+function homeDir() {
+  return process.env.HOME || process.env.USERPROFILE || (0, import_os3.homedir)();
+}
+function currentUid() {
+  return typeof process.getuid === "function" ? process.getuid() : void 0;
+}
+function owns(path2, uid, read = import_fs3.lstatSync) {
+  if (uid === void 0) return true;
+  try {
+    return read(path2).uid === uid;
+  } catch {
+    return true;
+  }
+}
+function projectFileOwned(path2, uid = currentUid()) {
+  return owns((0, import_path4.dirname)(path2), uid) && owns(path2, uid) && owns(path2, uid, import_fs3.statSync);
+}
+function foreignOwner(path2, coversCwd) {
+  return new CliError(
+    coversCwd ? `${path2} belongs to another user. Remove it to use your own checkout here.` : `${path2} belongs to another user. Remove it, or run headband branch checkout <name> in this directory to use your own.`,
+    { code: "project_file_foreign_owner" }
+  );
+}
+function projectFileSearchDirs(startDir, home = homeDir()) {
+  const dirs = [];
+  const ceiling = home && (0, import_path4.isAbsolute)(home) ? (0, import_path4.resolve)(home) : null;
+  let dir = (0, import_path4.resolve)(startDir);
+  for (; ; ) {
+    dirs.push(dir);
+    if (dir === ceiling) break;
+    const parent = (0, import_path4.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return dirs;
+}
+function findProjectFile(cwd) {
+  for (const dir of projectFileSearchDirs(cwd)) {
+    const candidate = (0, import_path4.join)(dir, PROJECT_DIR, PROJECT_FILE);
+    if ((0, import_fs3.existsSync)(candidate)) return candidate;
+  }
+  return null;
+}
+function parseProjectFile(path2) {
+  try {
+    const v = JSON.parse((0, import_fs3.readFileSync)(path2, "utf-8"));
+    return isProjectFile(v) ? { orgId: v.orgId, projectId: v.projectId, branch: v.branch } : null;
+  } catch {
+    return null;
+  }
+}
+function readProjectFile(cwd) {
+  const path2 = findProjectFile(cwd);
+  return path2 && projectFileOwned(path2) ? parseProjectFile(path2) : null;
+}
+function projectFileTarget(cwd) {
+  const found = findProjectFile(cwd);
+  if (found && projectFileOwned(found)) return found;
+  const own = (0, import_path4.join)((0, import_path4.resolve)(cwd), PROJECT_DIR, PROJECT_FILE);
+  if (found === own) throw foreignOwner(found, true);
+  if ((0, import_fs3.existsSync)((0, import_path4.dirname)(own)) && !owns((0, import_path4.dirname)(own), currentUid())) {
+    throw foreignOwner((0, import_path4.dirname)(own), true);
+  }
+  return own;
+}
+function writeProjectFile(cwd, f) {
+  const file = { orgId: f.orgId, projectId: f.projectId, branch: f.branch };
+  if (!isProjectFile(file)) {
+    throw new CliError("The branch's org, project or name cannot go in .headband/project.json.");
+  }
+  const path2 = projectFileTarget(cwd);
+  const dir = (0, import_path4.dirname)(path2);
+  (0, import_fs3.mkdirSync)(dir, { recursive: true, mode: 448 });
+  (0, import_fs3.chmodSync)(dir, 448);
+  const temp = (0, import_path4.join)(dir, `.${PROJECT_FILE}.${process.pid}.tmp`);
+  try {
+    (0, import_fs3.writeFileSync)(temp, `${JSON.stringify(file, null, 2)}
+`, { encoding: "utf-8", mode: 384 });
+    (0, import_fs3.chmodSync)(temp, 384);
+    (0, import_fs3.renameSync)(temp, path2);
+  } catch (error) {
+    (0, import_fs3.rmSync)(temp, { force: true });
+    throw error;
+  }
+  return path2;
+}
+function checkoutFor(cwd, loginOrgId) {
+  const path2 = findProjectFile(cwd);
+  if (!path2) return null;
+  if (!projectFileOwned(path2)) throw foreignOwner(path2, (0, import_path4.dirname)((0, import_path4.dirname)(path2)) === (0, import_path4.resolve)(cwd));
+  const file = parseProjectFile(path2);
+  if (!file) {
+    throw new CliError(
+      `Can't read ${path2}. Run headband branch checkout <name> again, or delete the file to use the main branch.`,
+      { code: "project_file_unreadable" }
+    );
+  }
+  if (loginOrgId && file.orgId !== loginOrgId) {
+    throw new CliError(
+      `${(0, import_path4.dirname)((0, import_path4.dirname)(path2))} is checked out for org ${file.orgId}, but you are logged in to ${loginOrgId}. Run headband branch checkout <name> again, or log in to that org.`,
+      { code: "project_file_org_mismatch" }
+    );
+  }
+  return file;
+}
+function stringFlag(flags, name) {
+  const value = flags[name];
+  return typeof value === "string" ? value : void 0;
+}
+function branchTargetFor(flags, cwd, options = {}) {
+  const project = stringFlag(flags, "--project");
+  const branch = stringFlag(flags, "--branch");
+  if (project && !branch && !options.projectInBody) {
+    throw new UsageError(
+      "--project needs --branch on this command, which sends no project of its own. Pass --project <id> --branch <name>, or drop --project."
+    );
+  }
+  const file = checkoutFor(cwd, options.loginOrgId);
+  if (branch) {
+    if (isBranchId(branch)) return { projectId: project ?? null, branch };
+    const projectId = project ?? file?.projectId;
+    if (!projectId) {
+      throw new UsageError(
+        "--branch needs a project. Pass --project <id> or run headband branch checkout inside a project directory."
+      );
+    }
+    return { projectId, branch };
+  }
+  if (!file) return null;
+  if (project && project !== file.projectId) return null;
+  return { projectId: file.projectId, branch: file.branch };
+}
+function branchHeaderFor(flags, cwd, options = {}) {
+  const target = branchTargetFor(flags, cwd, options);
+  if (!target) return null;
+  return isBranchId(target.branch) || target.projectId === null ? target.branch : `${target.projectId}/${target.branch}`;
+}
+
+// src/branch.ts
+var COLUMNS = ["name", "primary", "protected", "expiresAt", "state"];
+var PART_2 = /* @__PURE__ */ new Set(["reset", "rollback", "restore", "set-primary"]);
+var BRANCH_USAGE = [
+  "Usage:",
+  "  headband branch list [--project <id>] [--json]",
+  "  headband branch create <name> --empty [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]",
+  "  headband branch delete <name> [--project <id>] [--yes] [--json]",
+  "  headband branch protect <name> [--project <id>] [--json]",
+  "  headband branch unprotect <name> [--project <id>] [--json]",
+  "  headband branch expire <name> (--in <2h|7d> | --at <iso> | --clear) [--project <id>] [--json]",
+  "  headband branch checkout <name> [--project <id>] [--json]",
+  "  headband branch create <name> (without --empty, a fork)   coming with bucket storage",
+  "  headband branch reset|rollback|restore|set-primary <name>  coming with bucket storage",
+  "",
+  "The project comes from --project, else the directory's checkout (.headband/project.json).",
+  "Durations take s, m, h, d or w: 30m, 2h, 7d.",
+  "",
+  "The primary branch (main) serves production. It is always protected: it cannot be",
+  "unprotected, expired or deleted. A protected branch other than main must be unprotected",
+  "before it can be deleted.",
+  "",
+  "checkout writes .headband/project.json. Every later command in that directory, or in a",
+  "directory below it, sends Headband-Branch: <project id>/<branch> with your login key, so it",
+  "works on that branch. The nearest .headband/project.json above you applies, as with git.",
+  "On those commands, --project <id> --branch <name> picks another branch for one call."
+].join("\n");
+var DURATION_UNIT_MS = {
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5,
+  w: 6048e5
+};
+function parseDuration(input) {
+  const match = /^(\d+)(s|m|h|d|w)$/.exec(input.trim());
+  if (!match) {
+    throw new UsageError(
+      `Invalid duration "${input}". Use forms like 30m, 2h, 7d (units: s/m/h/d/w).`
+    );
+  }
+  const n = parseInt(match[1], 10);
+  if (n <= 0) throw new UsageError(`Duration "${input}" must be greater than zero.`);
+  return n * DURATION_UNIT_MS[match[2]];
+}
+function expiresAtFrom(flags, now = Date.now()) {
+  const inFlag = stringFlag2(flags, "--in");
+  const atFlag = stringFlag2(flags, "--at");
+  const clear = flags["--clear"] === true;
+  const given = [inFlag !== void 0, atFlag !== void 0, clear].filter(Boolean).length;
+  if (given !== 1) {
+    throw new UsageError("Pass exactly one of --in <duration>, --at <iso> or --clear.");
+  }
+  if (clear) return null;
+  if (inFlag !== void 0) return new Date(now + parseDuration(inFlag)).toISOString();
+  const at = Date.parse(atFlag);
+  if (Number.isNaN(at)) {
+    throw new UsageError(`Invalid --at "${atFlag}". Use an ISO 8601 time.`);
+  }
+  if (at <= now) throw new UsageError("--at must be in the future.");
+  return new Date(at).toISOString();
+}
+function stringFlag2(flags, name) {
+  const value = flags[name];
+  return typeof value === "string" ? value : void 0;
+}
+function requiredName(value) {
+  if (!value) throw new UsageError("Missing branch name");
+  return value;
+}
+function projectFor(flags, checkout, missing = "Pass --project <id> or run headband branch checkout inside a project directory.") {
+  const project = stringFlag2(flags, "--project") ?? checkout()?.projectId;
+  if (!project) throw new UsageError(missing);
+  return project;
+}
+function noLoginForCheckout(auth) {
+  const instead = "or pass --project <id> --branch <name> to each command instead.";
+  if (auth.source === "env") {
+    return `branch checkout records the org of your login, and HEADBAND_API_KEY takes the place of a stored login. Unset HEADBAND_API_KEY and use headband login, ${instead}`;
+  }
+  if (auth.source === "flag") {
+    return `branch checkout records the org of your login, and --token takes the place of a stored login. Drop --token and use headband login, ${instead}`;
+  }
+  return `branch checkout records the org of your login. Run headband login, ${instead}`;
+}
+function restateRefusal(error, action, name) {
+  if (!(error instanceof ApiError)) return error;
+  if (error.code === "branch_is_primary") {
+    const what = action === "unprotect" ? "so it is always protected and cannot be unprotected" : action === "expire" ? "so it never expires" : action === "delete" ? "so it cannot be deleted" : "so it is always protected";
+    return restate(error, `${name} is the primary branch. It serves production, ${what}.`);
+  }
+  if (error.code === "branch_protected") {
+    if (action === "protect") {
+      return restate(
+        error,
+        `Branch ${name} has an expiry, and a branch with an expiry cannot be protected. Run headband branch expire ${name} --clear first.`
+      );
+    }
+    if (action === "delete" || action === "expire") {
+      return restate(
+        error,
+        `Branch ${name} is protected. Run headband branch unprotect ${name} first.`
+      );
+    }
+  }
+  return error;
+}
+async function runBranch(args, flags, deps) {
+  const { io, auth, confirm, cwd } = deps;
+  const action = args[0];
+  const json = flags["--json"] === true;
+  if (action && PART_2.has(action)) {
+    throw new UsageError(
+      `headband branch ${action} is coming with bucket storage.`,
+      "not_available"
+    );
+  }
+  const client = createApiClient(auth.url, { apiKey: auth.apiKey });
+  const checkout = () => checkoutFor(cwd, auth.profile?.orgId);
+  const path2 = (name, project) => `/v1/branches/${encodeURIComponent(name)}?project=${encodeURIComponent(project)}`;
+  if (action === "list") {
+    const project = projectFor(flags, checkout);
+    const response = await client.get(
+      `/v1/branches?project=${encodeURIComponent(project)}`
+    );
+    if (json) printJson(io, response);
+    else printTable(io, response.data.branches, COLUMNS);
+    return;
+  }
+  if (action === "create") {
+    const name = requiredName(args[1]);
+    const body = { name, empty: flags["--empty"] === true };
+    const parent = stringFlag2(flags, "--parent");
+    if (parent) body.parent = parent;
+    const expiresIn = stringFlag2(flags, "--expires-in");
+    if (expiresIn) body.expiresAt = new Date(Date.now() + parseDuration(expiresIn)).toISOString();
+    body.projectId = projectFor(flags, checkout);
+    let response;
+    try {
+      response = await client.post("/v1/branches", body);
+    } catch (error) {
+      if (error instanceof ApiError && error.code === "branches_not_open") {
+        throw restate(error, "Branches other than main are not open yet.");
+      }
+      if (error instanceof ApiError && error.code === "fork_not_available") {
+        throw restate(
+          error,
+          "Forking arrives with bucket storage. Pass --empty for an empty branch."
+        );
+      }
+      throw error;
+    }
+    if (json) printJson(io, response);
+    else printTable(io, [response.data], COLUMNS);
+    return;
+  }
+  if (action === "delete") {
+    const name = requiredName(args[1]);
+    const project = projectFor(flags, checkout);
+    if (!await confirm(`Delete branch ${name} with its indexes, keys and engines?`)) {
+      if (json) printJson(io, { cancelled: true });
+      else io.stdout("Cancelled.");
+      return;
+    }
+    const response = await client.delete(path2(name, project)).catch((error) => Promise.reject(restateRefusal(error, action, name)));
+    if (json) printJson(io, response);
+    else io.stdout(`Deleted branch ${name}.`);
+    return;
+  }
+  if (action === "protect" || action === "unprotect") {
+    const name = requiredName(args[1]);
+    const project = projectFor(flags, checkout);
+    const value = action === "protect";
+    const response = await client.patch(path2(name, project), { protected: value }).catch((error) => Promise.reject(restateRefusal(error, action, name)));
+    if (json) printJson(io, response);
+    else io.stdout(value ? `Branch ${name} is protected.` : `Branch ${name} is not protected.`);
+    return;
+  }
+  if (action === "expire") {
+    const name = requiredName(args[1]);
+    const expiresAt = expiresAtFrom(flags);
+    const project = projectFor(flags, checkout);
+    const response = await client.patch(path2(name, project), { expiresAt }).catch((error) => Promise.reject(restateRefusal(error, action, name)));
+    if (json) printJson(io, response);
+    else
+      io.stdout(
+        expiresAt ? `Branch ${name} expires at ${expiresAt}.` : `Branch ${name} no longer expires.`
+      );
+    return;
+  }
+  if (action === "checkout") {
+    const name = requiredName(args[1]);
+    const project = projectFor(flags, () => readProjectFile(cwd), "Pass --project <id>.");
+    const orgId = auth.profile?.orgId;
+    if (!orgId) throw new AuthError(noLoginForCheckout(auth));
+    projectFileTarget(cwd);
+    let branch;
+    try {
+      branch = (await client.get(path2(name, project))).data;
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404 && error.code !== "project_not_found") {
+        throw new CliError(`No branch '${name}' in project ${project}. See headband branch list.`, {
+          exitCode: EXIT_CODES.notFound,
+          code: error.code ?? "branch_not_found"
+        });
+      }
+      throw error;
+    }
+    if (branch.state === "deleting") {
+      throw new CliError(`Branch '${branch.name}' is being deleted. See headband branch list.`, {
+        exitCode: EXIT_CODES.conflict,
+        code: "branch_deleting"
+      });
+    }
+    const file = { orgId, projectId: branch.projectId, branch: branch.name };
+    const filePath = writeProjectFile(cwd, file);
+    const header = `${file.projectId}/${file.branch}`;
+    if (json) printJson(io, { path: filePath, ...file });
+    else {
+      io.stdout(`Checked out branch ${file.branch} of project ${file.projectId}.`);
+      io.stdout(`Commands under ${(0, import_path5.dirname)((0, import_path5.dirname)(filePath))} now send Headband-Branch: ${header}`);
+    }
+    return;
+  }
+  io.stdout(BRANCH_USAGE);
+  throw new UsageError("Unknown branch command");
+}
+
+// src/config-load.ts
+var import_fs4 = require("fs");
+var import_path6 = require("path");
 var import_url = require("url");
 var import_jiti = require("jiti");
+
+// ../sync/src/config.ts
+var SETTINGS_ATTRIBUTE_LIST_KEYS = [
+  "searchableAttributes",
+  "filterableAttributes",
+  "sortableAttributes",
+  "displayedAttributes"
+];
+function validateConfig(config, ormSchema) {
+  const errors = [];
+  const seenIndexNames = /* @__PURE__ */ new Set();
+  for (const index of config.indexes) {
+    if (seenIndexNames.has(index.name)) {
+      errors.push({
+        index: index.name,
+        message: `duplicate index name '${index.name}'`
+      });
+    } else {
+      seenIndexNames.add(index.name);
+    }
+    const model = ormSchema.models[index.source];
+    if (!model) {
+      errors.push({
+        index: index.name,
+        message: `unknown model '${index.source}'`
+      });
+      continue;
+    }
+    if (!model.columns[index.primaryKey]) {
+      errors.push({
+        index: index.name,
+        field: index.primaryKey,
+        message: `primaryKey '${index.primaryKey}' is not a column on model '${index.source}'`
+      });
+    }
+    const fieldNames = Object.keys(index.fields);
+    for (const [fieldName, spec] of Object.entries(index.fields)) {
+      if (spec === true) {
+        if (!model.columns[fieldName]) {
+          errors.push({
+            index: index.name,
+            field: fieldName,
+            message: `field '${fieldName}' is not a column on model '${index.source}'`
+          });
+        }
+        continue;
+      }
+      if (typeof spec === "function") {
+        continue;
+      }
+      if (spec.kind === "rel") {
+        const targetModel2 = ormSchema.models[spec.model];
+        if (!targetModel2) {
+          errors.push({
+            index: index.name,
+            field: fieldName,
+            message: `unknown model '${spec.model}'`
+          });
+          continue;
+        }
+        const hasPath2 = model.relations.some(
+          (r) => r.fromModel === index.source && r.toModel === spec.model && r.kind === "one"
+        );
+        if (!hasPath2) {
+          errors.push({
+            index: index.name,
+            field: fieldName,
+            message: `no relation path from '${index.source}' to '${spec.model}' for rel()`
+          });
+        }
+        continue;
+      }
+      const targetModel = ormSchema.models[spec.model];
+      if (!targetModel) {
+        errors.push({
+          index: index.name,
+          field: fieldName,
+          message: `unknown model '${spec.model}'`
+        });
+        continue;
+      }
+      const hasPath = model.relations.some(
+        (r) => r.fromModel === index.source && r.toModel === spec.model && r.kind === "many"
+      );
+      if (!hasPath) {
+        errors.push({
+          index: index.name,
+          field: fieldName,
+          message: `no relation path from '${spec.model}' to '${index.source}' for agg()`
+        });
+      }
+    }
+    if (index.settings) {
+      const allowedAttributes = /* @__PURE__ */ new Set([...fieldNames, index.primaryKey]);
+      for (const key of SETTINGS_ATTRIBUTE_LIST_KEYS) {
+        const list = index.settings[key];
+        if (!list) continue;
+        for (const attribute of list) {
+          if (!allowedAttributes.has(attribute)) {
+            errors.push({
+              index: index.name,
+              field: attribute,
+              message: `settings.${key} references undefined field '${attribute}'`
+            });
+          }
+        }
+      }
+      const distinctAttribute = index.settings.distinctAttribute;
+      if (distinctAttribute && !allowedAttributes.has(distinctAttribute)) {
+        errors.push({
+          index: index.name,
+          field: distinctAttribute,
+          message: `settings.distinctAttribute references undefined field '${distinctAttribute}'`
+        });
+      }
+    }
+  }
+  return errors;
+}
+
+// src/config-load.ts
 var CONFIG_FILENAMES = [
   "headband.config.ts",
   "headband.config.mts",
@@ -656,24 +1249,91 @@ var CONFIG_FILENAMES = [
   "headband.config.mjs",
   "headband.config.cjs"
 ];
+var SYNC_CONFIG_SHAPE = 'a headband.config.ts whose default export is defineConfig({ indexes: [...] }) from @headband/sync, plus a named "adapter" export such as drizzleAdapter({ db, schema, config }) from @headband/drizzle';
 function findConfigFile(cwd) {
   for (const name of CONFIG_FILENAMES) {
-    const path2 = (0, import_path4.join)(cwd, name);
-    if ((0, import_fs3.existsSync)(path2)) return path2;
+    const path2 = (0, import_path6.join)(cwd, name);
+    if ((0, import_fs4.existsSync)(path2)) return path2;
   }
   return void 0;
 }
 function isSyncConfig(value) {
   return typeof value === "object" && value !== null && Array.isArray(value.indexes);
 }
+function isAdapter(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const a = value;
+  return ["introspect", "resolveDocs", "fanOut", "listIds"].every(
+    (name) => typeof a[name] === "function"
+  );
+}
+function configShapeProblems(config) {
+  const problems = [];
+  config.indexes.forEach((def, i) => {
+    const label = typeof def?.name === "string" && def.name ? def.name : `indexes[${i}]`;
+    if (typeof def !== "object" || def === null) {
+      problems.push(`${label}: not an index definition`);
+      return;
+    }
+    if (typeof def.name !== "string" || !def.name) problems.push(`${label}: missing "name"`);
+    if (typeof def.source !== "string" || !def.source)
+      problems.push(`${label}: missing "source" (the table the documents come from)`);
+    if (typeof def.primaryKey !== "string" || !def.primaryKey)
+      problems.push(`${label}: missing "primaryKey"`);
+    if (typeof def.fields !== "object" || def.fields === null || Array.isArray(def.fields)) {
+      problems.push(`${label}: "fields" must be an object of field names`);
+    } else {
+      for (const [field, spec] of Object.entries(def.fields)) {
+        const kind = spec?.kind;
+        const ok = spec === true || typeof spec === "function" || typeof spec === "object" && spec !== null && (kind === "rel" || kind === "agg");
+        if (!ok) {
+          problems.push(
+            `${label}.${field}: a field is true, rel(model, field), agg(model, "count") or a function of the row`
+          );
+        }
+      }
+    }
+    if (def.shouldIndex !== void 0 && typeof def.shouldIndex !== "function")
+      problems.push(`${label}: "shouldIndex" must be a function`);
+  });
+  return problems;
+}
+function validateLoadedConfig(loaded) {
+  const file = (0, import_path6.basename)(loaded.path);
+  const shape = configShapeProblems(loaded.config);
+  if (shape.length > 0) {
+    throw new CliError(
+      `${file} has ${shape.length} problem(s):
+${shape.map((p) => `  ${p}`).join("\n")}`,
+      { code: "invalid_sync_config" }
+    );
+  }
+  if (!loaded.adapter) return;
+  let errors;
+  try {
+    errors = validateConfig(loaded.config, loaded.adapter.introspect());
+  } catch (err) {
+    throw new CliError(
+      `Could not check ${file} against your schema: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (errors.length === 0) return;
+  const lines = errors.map((e) => `  ${e.index}${e.field ? `.${e.field}` : ""}: ${e.message}`);
+  throw new CliError(
+    `${file} does not match your database schema (${errors.length} problem(s)):
+${lines.join("\n")}`,
+    { code: "invalid_sync_config" }
+  );
+}
 async function loadHeadbandConfig(cwd) {
   const path2 = findConfigFile(cwd);
   if (!path2) {
     throw new CliError(
-      `No headband.config.ts found in ${cwd}. Run "headband init" or create one that exports a Headband sync config.`
+      `No headband.config.ts found in ${cwd}. The schema and sync commands need ${SYNC_CONFIG_SHAPE}. See the @headband/drizzle README. (headband init writes a search UI config, not a sync config.)`,
+      { code: "sync_config_missing" }
     );
   }
-  const jiti = (0, import_jiti.createJiti)((0, import_url.pathToFileURL)((0, import_path4.join)(cwd, "headband-cli.js")).href, {
+  const jiti = (0, import_jiti.createJiti)((0, import_url.pathToFileURL)((0, import_path6.join)(cwd, "headband-cli.js")).href, {
     interopDefault: true,
     moduleCache: false,
     fsCache: false
@@ -688,19 +1348,36 @@ async function loadHeadbandConfig(cwd) {
   }
   const candidate = mod.default ?? mod;
   if (!isSyncConfig(candidate)) {
-    throw new CliError(`${path2} does not export a valid Headband sync config (missing "indexes").`);
+    throw new CliError(
+      `${path2} is not a sync config: its default export has no "indexes" array. The schema and sync commands need ${SYNC_CONFIG_SHAPE}. If this file came from "headband init", it is the search UI config; keep the sync config in its own directory or merge "indexes" into it.`,
+      { code: "invalid_sync_config" }
+    );
   }
-  const adapter = mod.adapter;
-  return { config: candidate, adapter, path: path2 };
+  const rawAdapter = mod.adapter;
+  if (rawAdapter !== void 0 && !isAdapter(rawAdapter)) {
+    throw new CliError(
+      `${path2} exports "adapter", but it is not an ORM adapter (it needs introspect, resolveDocs, fanOut and listIds). Export the result of drizzleAdapter({ db, schema, config }).`,
+      { code: "invalid_sync_config" }
+    );
+  }
+  const loaded = { config: candidate, adapter: rawAdapter, path: path2 };
+  validateLoadedConfig(loaded);
+  return loaded;
 }
-
+function missingAdapterError(command, why) {
+  return new CliError(
+    `headband.config.ts must export an "adapter" for ${command}: ${why}. Add: export const adapter = drizzleAdapter({ db, schema, config }) (from @headband/drizzle), in headband.config.ts itself.`,
+    { code: "sync_adapter_missing" }
+  );
+}
+
 // src/docs.ts
-var import_path5 = require("path");
-var import_fs4 = require("fs");
+var import_path7 = require("path");
+var import_fs5 = require("fs");
 var DOCS_BATCH_SIZE = 1e3;
 function parseDocumentsFile(path2) {
-  const content = (0, import_fs4.readFileSync)(path2, "utf-8");
-  const ext = (0, import_path5.extname)(path2).toLowerCase();
+  const content = (0, import_fs5.readFileSync)(path2, "utf-8");
+  const ext = (0, import_path7.extname)(path2).toLowerCase();
   if (ext === ".jsonl") {
     return content.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line));
   }
@@ -734,38 +1411,206 @@ async function defaultExportBatchSize(client, index) {
     return EXPORT_BATCH_SIZE;
   }
 }
-async function exportDocuments(client, options) {
-  const { index, format, batchSize, write } = options;
+async function* walkDocuments(client, options) {
+  const { index, batchSize, fields } = options;
+  let base = `/v1/documents?index=${encodeURIComponent(index)}&limit=${batchSize}`;
+  if (fields?.length) base += `&fields=${encodeURIComponent(fields.join(","))}`;
+  let cursor = "";
   let offset = 0;
-  let exported = 0;
-  let pending;
-  if (format === "json") await write("[");
   for (; ; ) {
     const page = await client.get(
-      `/v1/documents?index=${encodeURIComponent(index)}&limit=${batchSize}&offset=${offset}`
+      cursor === null ? `${base}&offset=${offset}` : `${base}&cursor=${encodeURIComponent(cursor)}`
     );
     const results = Array.isArray(page.results) ? page.results : [];
+    const total = typeof page.total === "number" ? page.total : null;
+    yield { results, total };
+    offset += results.length;
+    if (cursor !== null && page.nextCursor !== void 0) {
+      if (!page.nextCursor) return;
+      cursor = page.nextCursor;
+      continue;
+    }
+    cursor = null;
+    if (results.length < batchSize) return;
+    if (total !== null && offset >= total) return;
+  }
+}
+async function listRemoteIds(client, index, primaryKey) {
+  const batchSize = await defaultExportBatchSize(client, index);
+  const ids = [];
+  for await (const { results } of walkDocuments(client, {
+    index,
+    batchSize,
+    fields: [primaryKey]
+  })) {
     for (const doc of results) {
-      const line = JSON.stringify(doc);
-      if (format === "jsonl") {
-        await write(line);
-      } else {
-        if (pending !== void 0) await write(`  ${pending},`);
-        pending = line;
-      }
+      const id = doc?.[primaryKey];
+      if (id !== void 0 && id !== null) ids.push(String(id));
     }
-    exported += results.length;
-    offset += results.length;
-    options.onPage?.(exported, typeof page.total === "number" ? page.total : null);
-    if (results.length < batchSize) break;
-    if (typeof page.total === "number" && offset >= page.total) break;
   }
-  if (format === "json") {
+  return ids;
+}
+async function exportDocuments(client, options) {
+  const { index, format, batchSize, write } = options;
+  let exported = 0;
+  let pending;
+  const finish = async () => {
+    if (format !== "json") return;
     if (pending !== void 0) await write(`  ${pending}`);
     await write("]");
+  };
+  if (format === "json") await write("[");
+  try {
+    for await (const { results, total } of walkDocuments(client, { index, batchSize })) {
+      for (const doc of results) {
+        const line = JSON.stringify(doc);
+        if (format === "jsonl") {
+          await write(line);
+        } else {
+          if (pending !== void 0) await write(`  ${pending},`);
+          pending = line;
+        }
+      }
+      exported += results.length;
+      options.onPage?.(exported, total);
+    }
+  } catch (error) {
+    if (options.finishOnError) await finish();
+    throw new ExportInterruptedError(error, exported);
   }
+  await finish();
   return exported;
 }
+var ExportInterruptedError = class extends Error {
+  constructor(cause, exported) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.cause = cause;
+    this.exported = exported;
+    this.name = "ExportInterruptedError";
+  }
+};
+function refusedWalk(error) {
+  if (!(error instanceof ApiError) || error.code !== "feature_not_supported") return null;
+  if (!/primary key/i.test(error.message)) return null;
+  const pk = /add `([^`]+)`/.exec(error.message)?.[1] ?? null;
+  const named = ["filterableAttributes", "sortableAttributes", "displayedAttributes"].filter(
+    (name) => error.message.includes(name)
+  );
+  return { pk, lists: named.length ? named : ["filterableAttributes", "sortableAttributes"] };
+}
+var DECLARE_WAIT_MS = 15 * 6e4;
+var DECLARE_POLL_MS = 3e3;
+async function declareExportKey(client, index, io, opts = {}) {
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = opts.now ?? Date.now;
+  const probe = () => client.get(`/v1/documents?index=${encodeURIComponent(index)}&limit=1&cursor=`);
+  let refused;
+  try {
+    await probe();
+    return false;
+  } catch (error) {
+    refused = refusedWalk(error);
+    if (!refused) throw error;
+    if (!refused.pk) throw error;
+  }
+  const { pk, lists } = refused;
+  const path2 = `/v1/indexes/${encodeURIComponent(index)}/settings`;
+  const current = await client.get(path2);
+  const patch = {};
+  for (const name of lists) {
+    const list = Array.isArray(current?.[name]) ? current[name] : [];
+    if (list.includes("*") || list.includes(pk)) continue;
+    patch[name] = [...list, pk];
+  }
+  io.stderr(
+    `Declaring \`${pk}\` in ${Object.keys(patch).join(" and ") || lists.join(" and ")} on ${index}, so the export can read past 1000 documents. Visor rebuilds the index for this change, which can take minutes on a large one.`
+  );
+  if (Object.keys(patch).length > 0) {
+    try {
+      await client.patch(path2, patch);
+    } catch (error) {
+      if (!(error instanceof ApiError) || error.status < 500) throw error;
+    }
+  }
+  const deadline = now() + (opts.waitMs ?? DECLARE_WAIT_MS);
+  for (; ; ) {
+    try {
+      await probe();
+      io.stderr(`\`${pk}\` is declared. Exporting.`);
+      return true;
+    } catch (error) {
+      const waiting = refusedWalk(error) || error instanceof ApiError && error.status >= 500;
+      if (!waiting) throw error;
+    }
+    if (now() >= deadline) {
+      throw new CliError(
+        `\`${pk}\` is still not declared on ${index} after ${Math.round((opts.waitMs ?? DECLARE_WAIT_MS) / 6e4)} minutes. Visor may still be rebuilding it: run headband docs export again later.`
+      );
+    }
+    await sleep(DECLARE_POLL_MS);
+  }
+}
+function exportRefusalAdvice(error, index) {
+  if (!(error instanceof ApiError) || error.code !== "feature_not_supported") return null;
+  if (!/primary key/i.test(error.message)) return null;
+  const pk = /add `([^`]+)`/.exec(error.message)?.[1];
+  const key = pk ? `\`${pk}\`` : "the primary key";
+  const missing = ["filterableAttributes", "sortableAttributes", "displayedAttributes"].filter(
+    (name) => error.message.includes(name)
+  );
+  const lists = missing.length ? missing.join(" and ") : "filterableAttributes and sortableAttributes";
+  return [
+    `To export the whole index, run it again with --declare-key: it declares ${key} on the index`,
+    `once (Visor rebuilds the index for it), waits for it, and exports. Or declare it yourself:`,
+    `  1. headband indexes settings get ${index} > settings.json`,
+    `  2. Add ${key} to ${lists} in settings.json.`,
+    `  3. headband indexes settings set ${index} --file settings.json`,
+    `     Visor rebuilds the index for this change.`,
+    `  4. Run headband docs export again.`
+  ].join("\n");
+}
+function exportFailure(error, index) {
+  const advice = exportRefusalAdvice(error, index);
+  if (!advice || !(error instanceof ApiError)) return error;
+  return restate(error, `${error.message}
+
+${advice}`);
+}
+
+// src/content-drift.ts
+async function readRemoteDocuments(client, index, primaryKey) {
+  const batchSize = await defaultExportBatchSize(client, index);
+  const docs = /* @__PURE__ */ new Map();
+  for await (const { results } of walkDocuments(client, { index, batchSize })) {
+    for (const doc of results) {
+      const id = doc?.[primaryKey];
+      if (id !== void 0 && id !== null) docs.set(String(id), doc);
+    }
+  }
+  return docs;
+}
+function wire(value) {
+  return value === void 0 ? null : JSON.parse(JSON.stringify(value));
+}
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const entries = Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+function documentsMatch(expected, remote, primaryKey) {
+  if (!remote) return false;
+  for (const [key, raw] of Object.entries(expected)) {
+    if (key === primaryKey) {
+      if (String(raw) !== String(remote[key])) return false;
+      continue;
+    }
+    if (canonical(wire(raw)) !== canonical(wire(remote[key]))) return false;
+  }
+  return true;
+}
 
 // ../../src/lib/density/catalog-constants.ts
 function formatMemory(mb) {
@@ -774,6 +1619,7 @@ function formatMemory(mb) {
 
 // ../../src/lib/density/snippets.ts
 var ADMIN_NOTE = "Creating an index and adding a document need an admin key. A search key can only search.";
+var ENGINE_ONLY_NOTE = "This index lives only on this engine. Headband's dashboard, Search and Analytics do not list it.";
 function visorSnippets(endpoint) {
   return {
     packageName: "built-in fetch",
@@ -786,6 +1632,7 @@ function visorSnippets(endpoint) {
       "};",
       "",
       `// ${ADMIN_NOTE}`,
+      `// ${ENGINE_ONLY_NOTE}`,
       "// Creating the index is safe to repeat: an existing index is kept as it is.",
       'await fetch(`${base}/v1/indexes/movies`, { method: "PUT", headers, body: JSON.stringify({ primaryKey: "id" }) });',
       'await fetch(`${base}/v1/indexes/movies/documents`, { method: "POST", headers, body: JSON.stringify([{ id: 1, title: "The Matrix" }]) });',
@@ -795,6 +1642,7 @@ function visorSnippets(endpoint) {
     ].join("\n"),
     curl: [
       `# ${ADMIN_NOTE}`,
+      `# ${ENGINE_ONLY_NOTE}`,
       "# On a second run the index already exists and PUT keeps it. That is fine.",
       `curl -X PUT "${endpoint}/v1/indexes/movies" \\`,
       '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
@@ -830,6 +1678,7 @@ function connectSnippets(engine, endpoint) {
         "});",
         "",
         `// ${ADMIN_NOTE}`,
+        `// ${ENGINE_ONLY_NOTE}`,
         'if (!(await client.indices.exists({ index: "movies" }))) {',
         '  await client.indices.create({ index: "movies" });',
         "}",
@@ -840,6 +1689,7 @@ function connectSnippets(engine, endpoint) {
       ].join("\n"),
       curl: [
         `# ${ADMIN_NOTE}`,
+        `# ${ENGINE_ONLY_NOTE}`,
         "# On a second run this answers that the index already exists. That is fine.",
         `curl -X PUT "${endpoint}/movies" \\`,
         '  -H "Authorization: ApiKey $HEADBAND_API_KEY"',
@@ -877,6 +1727,7 @@ function connectSnippets(engine, endpoint) {
         "});",
         "",
         `// ${ADMIN_NOTE}`,
+        `// ${ENGINE_ONLY_NOTE}`,
         "// A 409 means the collection exists from an earlier run.",
         "await client.collections().create({",
         '  name: "movies",',
@@ -891,6 +1742,7 @@ function connectSnippets(engine, endpoint) {
       ].join("\n"),
       curl: [
         `# ${ADMIN_NOTE}`,
+        `# ${ENGINE_ONLY_NOTE}`,
         "# On a second run this answers that the collection already exists. That is fine.",
         `curl "${endpoint}/collections" \\`,
         '  -H "X-TYPESENSE-API-KEY: $HEADBAND_API_KEY" \\',
@@ -919,6 +1771,7 @@ function connectSnippets(engine, endpoint) {
       "});",
       "",
       `// ${ADMIN_NOTE}`,
+      `// ${ENGINE_ONLY_NOTE}`,
       "// waitTask() waits until Meilisearch has applied the change. On a second run",
       "// the create task fails because the index exists, which is fine.",
       'await client.createIndex("movies", { primaryKey: "id" }).waitTask();',
@@ -929,6 +1782,7 @@ function connectSnippets(engine, endpoint) {
     ].join("\n"),
     curl: [
       `# ${ADMIN_NOTE}`,
+      `# ${ENGINE_ONLY_NOTE}`,
       "# On a second run this task fails because the index already exists. That is fine.",
       `curl "${endpoint}/indexes" \\`,
       '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
@@ -951,54 +1805,10 @@ function connectSnippets(engine, endpoint) {
   };
 }
 
-// src/output.ts
-var defaultIO = {
-  stdout: (message = "") => console.log(message),
-  stderr: (message = "") => console.error(message)
-};
-function printJson(io, value) {
-  io.stdout(JSON.stringify(value, null, 2));
-}
-function formatTable(rows, columns) {
-  if (rows.length === 0) return "No results.";
-  const selectedColumns = columns || Object.keys(rows[0]);
-  const widths = selectedColumns.map(
-    (column) => Math.max(
-      column.length,
-      ...rows.map(
-        (row) => String(row[column] === null || row[column] === void 0 ? "" : row[column]).length
-      )
-    )
-  );
-  const renderRow = (values) => values.map((value, index) => value.padEnd(widths[index])).join("  ").trimEnd();
-  return [
-    renderRow(selectedColumns),
-    renderRow(widths.map((width) => "-".repeat(width))),
-    ...rows.map(
-      (row) => renderRow(
-        selectedColumns.map(
-          (column) => String(row[column] === null || row[column] === void 0 ? "" : row[column])
-        )
-      )
-    )
-  ].join("\n");
-}
-function printTable(io, rows, columns) {
-  io.stdout(formatTable(rows, columns));
-}
-function summarizeHit(hit) {
-  const result = {};
-  for (const key of Object.keys(hit).slice(0, 5)) {
-    const value = hit[key];
-    result[key] = value && typeof value === "object" ? JSON.stringify(value) : value;
-  }
-  return result;
-}
-
 // src/instances.ts
 var ENGINES = ["meilisearch", "elasticsearch", "typesense", "visor"];
 var CLIENTS = ["node", "curl"];
-var COLUMNS = ["id", "name", "engine", "lane", "memory", "region", "state"];
+var COLUMNS2 = ["id", "name", "engine", "lane", "memory", "region", "state"];
 var INSTANCES_USAGE = [
   "Usage:",
   "  headband instances list [--json]",
@@ -1093,7 +1903,7 @@ async function runInstances(args, flags, io, client, confirm) {
           ...summaryRow(i),
           "wake p95": i.wakeP95Ms === null || i.wakeP95Ms === void 0 ? "" : `${Math.round(i.wakeP95Ms)} ms`
         })),
-        [...COLUMNS, "wake p95"]
+        [...COLUMNS2, "wake p95"]
       );
       return;
     }
@@ -1115,7 +1925,7 @@ async function runInstances(args, flags, io, client, confirm) {
       if (idle) body.idleTimeoutS = parsePositiveInt(idle, "--idle-timeout");
       const res = await client.post("/v1/instances", body);
       if (json) return printJson(io, res);
-      printTable(io, [summaryRow(res.data)], COLUMNS);
+      printTable(io, [summaryRow(res.data)], COLUMNS2);
       io.stdout(`Endpoint: ${res.data.endpoint}`);
       io.stdout(`Connect a client: headband instances connect ${res.data.id}`);
       return;
@@ -1136,7 +1946,10 @@ async function runInstances(args, flags, io, client, confirm) {
         ["endpoint", i.endpoint],
         ["idle timeout", i.lane === "serverless" ? `${i.idleTimeoutS} s` : "n/a"],
         ["default", i.isDefault ? "yes" : "no"],
-        ["last backup", i.lastBackupAt ?? "never"],
+        [
+          "last backup",
+          i.bucketHome ? "not needed (every write is saved to object storage)" : i.lastBackupAt ?? "never"
+        ],
         ["last wake", i.lastWakeAt ?? "never"]
       ];
       const width = Math.max(...lines.map(([k]) => k.length));
@@ -1178,7 +1991,7 @@ async function runInstances(args, flags, io, client, confirm) {
       }
       const res = await client.patch(path2(id), body);
       if (json) return printJson(io, res);
-      printTable(io, [summaryRow(res.data)], COLUMNS);
+      printTable(io, [summaryRow(res.data)], COLUMNS2);
       if (res.data.pendingChanges) {
         io.stdout(
           "The engine applies the change in the background. Check it with: headband instances show " + id
@@ -1261,9 +2074,144 @@ async function runInstances(args, flags, io, client, confirm) {
   }
 }
 
-// src/schema.ts
-var import_fs6 = require("fs");
-var import_path7 = require("path");
+// src/warm.ts
+var LEVELS = ["auto", "stage", "start"];
+var COLUMNS3 = ["index", "engine", "state", "reason"];
+var WARM_USAGE = [
+  "Usage:",
+  "  headband warm <index>... [--branch <name>] [--level <auto|stage|start>] [--json]",
+  "  headband warm --project <id> [--branch <name>] [--level <auto|stage|start>] [--json]",
+  "",
+  "Wakes sleeping engines ahead of traffic. stage loads an engine's data onto its server; start also starts it.",
+  "auto, the default, starts an engine used in the last 24 hours and stages an older one. Warming is free."
+].join("\n");
+async function runWarm(args, flags, io, client) {
+  const str2 = (name) => typeof flags[name] === "string" ? flags[name] : void 0;
+  const project = str2("--project");
+  const level = str2("--level") ?? "auto";
+  if (!LEVELS.includes(level)) throw new UsageError("--level must be auto, stage or start");
+  const named = args.length > 0;
+  if (named === (project !== void 0))
+    throw new UsageError("Name the indexes to warm, or --project, but not both.\n\n" + WARM_USAGE);
+  const branch = str2("--branch");
+  const on = branch !== void 0 ? { branch } : {};
+  const body = project !== void 0 ? { project, ...on, level } : { indexes: args, ...on, level };
+  const res = await client.post("/v1/warm", body);
+  if (flags["--json"] === true) return printJson(io, res);
+  printTable(
+    io,
+    res.indexes.map((r) => ({
+      index: r.index,
+      engine: r.engine,
+      state: r.state,
+      reason: r.reason ?? ""
+    })),
+    COLUMNS3
+  );
+}
+
+// src/switch-engine.ts
+var PHASES = {
+  queued: "waiting to start",
+  copying: "copying documents",
+  draining: "holding writes while in-flight requests finish",
+  catching_up: "copying the last changes and checking every document",
+  cleaning: "switched; removing the old copy",
+  succeeded: "done",
+  failed: "stopped"
+};
+function printSettings(io, settings) {
+  if (!settings) return;
+  if (settings.carried.length > 0) io.stdout(`Carried over: ${settings.carried.join(", ")}`);
+  for (const d of settings.drops) {
+    io.stdout(`Not carried: ${d.setting}${d.kept ? " (kept, not applied)" : ""}. ${d.reason}`);
+  }
+  for (const a of settings.added) {
+    const value = Array.isArray(a.value) ? a.value.join(", ") : String(a.value);
+    io.stdout(`Added: ${a.setting} ${value}. ${a.reason}`);
+  }
+}
+async function runSwitchEngine(client, opts, io, chatter) {
+  const path2 = `/v1/indexes/${encodeURIComponent(opts.uid)}/engine`;
+  const body = { engine: opts.engine };
+  if (opts.instanceId) body.instanceId = opts.instanceId;
+  if (opts.acceptDrops) body.acceptDrops = true;
+  if (opts.declareKey) body.declareKey = true;
+  if (opts.dryRun) body.dryRun = true;
+  let started;
+  try {
+    started = await client.post(path2, body);
+  } catch (error) {
+    if (error instanceof ApiError && error.code === "settings_not_portable" && !opts.json && error.details && typeof error.details === "object") {
+      printSettings(chatter, error.details.settings);
+      chatter.stdout("Run again with --accept-drops to switch anyway.");
+    }
+    throw error;
+  }
+  if (opts.dryRun) {
+    if (opts.json) return printJson(io, started);
+    const target = started.target;
+    io.stdout(
+      `${opts.uid}: ${String(started.documents)} documents from ${String(started.fromEngine)} to ${String(started.toEngine)}, on ${target.willCreate ? "a new engine of the branch" : target.instanceId ? `engine ${target.instanceId}` : "the shared engine"}.`
+    );
+    printSettings(io, started.settings);
+    for (const n of started.notes ?? []) io.stdout(n);
+    io.stdout("Dry run: nothing was changed.");
+    return;
+  }
+  let view = started;
+  if (!opts.wait) {
+    if (opts.json) return printJson(io, view);
+    io.stdout(
+      `Switching ${opts.uid} from ${view.fromEngine} to ${view.toEngine} (${view.switchId}). Follow it with: headband indexes switch-engine ${opts.uid} --status`
+    );
+    return;
+  }
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let lastPhase = "";
+  for (; ; ) {
+    if (view.phase !== lastPhase) {
+      lastPhase = view.phase;
+      chatter.stdout(`${opts.uid}: ${PHASES[view.phase] ?? view.phase}`);
+    }
+    if (view.status === "succeeded" || view.status === "failed") break;
+    await sleep(opts.pollMs ?? 3e3);
+    const status = await client.get(path2);
+    if (!status.switch || status.switch.switchId !== view.switchId) {
+      throw new CliError("The switch is no longer listed for this index.", {
+        exitCode: EXIT_CODES.generic,
+        code: "switch_not_found"
+      });
+    }
+    view = status.switch;
+  }
+  if (opts.json) printJson(io, view);
+  else if (view.status === "succeeded") {
+    io.stdout(
+      `${opts.uid} now runs on ${view.toEngine}${view.documents.verified !== null ? `; ${view.documents.verified} documents verified` : ""}.`
+    );
+    for (const n of view.notes ?? []) io.stdout(n);
+  }
+  if (view.status === "failed") {
+    throw new CliError(view.error?.message ?? "The switch failed.", {
+      exitCode: EXIT_CODES.conflict,
+      code: view.error?.code ?? "switch_failed"
+    });
+  }
+}
+async function printSwitchStatus(client, uid, io, json) {
+  const status = await client.get(
+    `/v1/indexes/${encodeURIComponent(uid)}/engine`
+  );
+  if (json) return printJson(io, status);
+  io.stdout(`${uid} runs on ${status.engine}.`);
+  const s = status.switch;
+  if (!s) return;
+  io.stdout(
+    `Latest switch ${s.switchId}: ${s.fromEngine} to ${s.toEngine}, ${s.status} (${PHASES[s.phase] ?? s.phase}).`
+  );
+  if (s.error) io.stdout(s.error.message);
+}
 
 // ../sync/src/hash.ts
 var import_node_crypto = require("crypto");
@@ -1308,68 +2256,6 @@ function settingsHash(def) {
   return (0, import_node_crypto.createHash)("sha256").update(stableStringify(settings)).digest("hex");
 }
 
-// ../sync/src/migrations.ts
-var import_fs5 = require("fs");
-var import_path6 = require("path");
-var FILE_NAME_RE = /^(\d{4})_(.+)\.json$/;
-function sanitizeSlug(slug) {
-  const sanitized = slug.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
-  return sanitized || "migration";
-}
-function generateMigrationFile(dir, ops, meta, now = () => /* @__PURE__ */ new Date()) {
-  (0, import_fs5.mkdirSync)(dir, { recursive: true });
-  const existing = readMigrations(dir);
-  const nextVersion = existing.length === 0 ? 1 : existing[existing.length - 1].version + 1;
-  const safeSlug = sanitizeSlug(meta.slug);
-  const fileName = `${String(nextVersion).padStart(4, "0")}_${safeSlug}.json`;
-  const path2 = (0, import_path6.join)(dir, fileName);
-  const file = {
-    version: nextVersion,
-    createdAt: now().toISOString(),
-    parentHashes: meta.parentHashes,
-    ops
-  };
-  (0, import_fs5.writeFileSync)(path2, JSON.stringify(file, null, 2));
-  return path2;
-}
-function readMigrations(dir) {
-  let entries;
-  try {
-    entries = (0, import_fs5.readdirSync)(dir);
-  } catch {
-    return [];
-  }
-  const files = [];
-  for (const entry of entries) {
-    const match = FILE_NAME_RE.exec(entry);
-    if (!match) continue;
-    const path2 = (0, import_path6.join)(dir, entry);
-    const raw = (0, import_fs5.readFileSync)(path2, "utf-8");
-    let parsed;
-    try {
-      parsed = JSON.parse(raw);
-    } catch {
-      throw new Error(`Malformed migration file: ${path2}`);
-    }
-    files.push({ ...parsed, path: path2 });
-  }
-  files.sort((a, b) => a.version - b.version);
-  for (let i = 0; i < files.length; i++) {
-    const expected = i + 1;
-    if (files[i].version === expected) continue;
-    if (files.some((f, idx) => idx !== i && f.version === files[i].version)) {
-      throw new Error(`Duplicate migration version: ${files[i].version}`);
-    }
-    throw new Error(
-      `Migration version gap: expected version ${expected}, found ${files[i].version}`
-    );
-  }
-  return files;
-}
-function pendingMigrations(files, appliedVersion) {
-  return files.filter((f) => f.version > appliedVersion);
-}
-
 // ../sync/src/planner.ts
 function planMigration(config, applied, opts) {
   const ops = [];
@@ -1425,18 +2311,85 @@ function planMigration(config, applied, opts) {
   return ops;
 }
 
-// ../sync/src/client.ts
-var BASE_BACKOFF_MS = 500;
-var DEFAULT_MAX_RETRIES = 5;
-function defaultSleep2(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+// src/schema.ts
+var import_fs7 = require("fs");
+var import_path9 = require("path");
+
+// ../sync/src/migrations.ts
+var import_fs6 = require("fs");
+var import_path8 = require("path");
+var FILE_NAME_RE = /^(\d{4})_(.+)\.json$/;
+function sanitizeSlug(slug) {
+  const sanitized = slug.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+  return sanitized || "migration";
 }
-var SchemaCasError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "SchemaCasError";
+function generateMigrationFile(dir, ops, meta, now = () => /* @__PURE__ */ new Date()) {
+  (0, import_fs6.mkdirSync)(dir, { recursive: true });
+  const existing = readMigrations(dir);
+  const nextVersion = existing.length === 0 ? 1 : existing[existing.length - 1].version + 1;
+  const safeSlug = sanitizeSlug(meta.slug);
+  const fileName = `${String(nextVersion).padStart(4, "0")}_${safeSlug}.json`;
+  const path2 = (0, import_path8.join)(dir, fileName);
+  const file = {
+    version: nextVersion,
+    createdAt: now().toISOString(),
+    parentHashes: meta.parentHashes,
+    ...meta.targetHashes ? { targetHashes: meta.targetHashes } : {},
+    ops
+  };
+  (0, import_fs6.writeFileSync)(path2, JSON.stringify(file, null, 2));
+  return path2;
+}
+function readMigrations(dir) {
+  let entries;
+  try {
+    entries = (0, import_fs6.readdirSync)(dir);
+  } catch {
+    return [];
   }
-};
+  const files = [];
+  for (const entry of entries) {
+    const match = FILE_NAME_RE.exec(entry);
+    if (!match) continue;
+    const path2 = (0, import_path8.join)(dir, entry);
+    const raw = (0, import_fs6.readFileSync)(path2, "utf-8");
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error(`Malformed migration file: ${path2}`);
+    }
+    files.push({ ...parsed, path: path2 });
+  }
+  files.sort((a, b) => a.version - b.version);
+  for (let i = 0; i < files.length; i++) {
+    const expected = i + 1;
+    if (files[i].version === expected) continue;
+    if (files.some((f, idx) => idx !== i && f.version === files[i].version)) {
+      throw new Error(`Duplicate migration version: ${files[i].version}`);
+    }
+    throw new Error(
+      `Migration version gap: expected version ${expected}, found ${files[i].version}`
+    );
+  }
+  return files;
+}
+function pendingMigrations(files, appliedVersion) {
+  return files.filter((f) => f.version > appliedVersion);
+}
+
+// ../sync/src/client.ts
+var BASE_BACKOFF_MS = 500;
+var DEFAULT_MAX_RETRIES = 5;
+function defaultSleep3(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+var SchemaCasError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SchemaCasError";
+  }
+};
 var HttpError = class extends Error {
   constructor(message, status, code) {
     super(message);
@@ -1472,7 +2425,7 @@ var HeadbandClient = class {
     this.adminKey = opts.adminKey;
     this.fetchImpl = opts.fetchImpl ?? fetch;
     this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
-    this.sleep = opts.sleep ?? defaultSleep2;
+    this.sleep = opts.sleep ?? defaultSleep3;
   }
   async bulkPush(index, documents, primaryKey) {
     const body = { index, documents };
@@ -1492,11 +2445,24 @@ var HeadbandClient = class {
     );
     return isRecord2(result) && "partialFailure" in result ? { partialFailure: result.partialFailure } : {};
   }
+  /**
+   * `projectId` places the index in that project (its production branch) when the key is
+   * org-wide, such as the CLI's login key. A project key's indexes always land in its project.
+   */
   async createIndex(uid, opts) {
     const body = { uid };
     if (opts?.primaryKey !== void 0) body.primaryKey = opts.primaryKey;
+    if (opts?.projectId !== void 0) body.projectId = opts.projectId;
     await this.request("POST", "/v1/indexes", body);
   }
+  /** The index (GET /v1/indexes/{uid}): its engine among the rest. */
+  async getIndex(uid) {
+    return this.request("GET", `/v1/indexes/${encodeURIComponent(uid)}`);
+  }
+  /** Deletes an index (DELETE /v1/indexes/{uid}): `schema apply` removes a reindex it could not set up. */
+  async deleteIndex(uid) {
+    await this.request("DELETE", `/v1/indexes/${encodeURIComponent(uid)}`);
+  }
   async patchSettings(uid, settings) {
     await this.request("PATCH", `/v1/indexes/${uid}/settings`, settings);
   }
@@ -1506,9 +2472,18 @@ var HeadbandClient = class {
   async postSchemaState(state) {
     await this.request("POST", "/v1/schema/state", state, { mapConflictToCasError: true });
   }
+  /** Removes an index's applied schema state (DELETE /v1/schema/state?indexUid=). */
+  async deleteSchemaState(indexUid) {
+    await this.request("DELETE", `/v1/schema/state?indexUid=${encodeURIComponent(indexUid)}`);
+  }
   async patchAlias(index, physicalUid) {
     await this.request("PATCH", "/v1/schema/alias", { indexUid: index, physicalUid });
   }
+  /**
+   * Records a connector run (POST /v1/connectors/runs). The same `externalRunId` updates the
+   * run it created. `status` is one of started, succeeded, failed, skipped, dead_letter. An
+   * org-wide key must name its `projectId`.
+   */
   async reportRun(run2) {
     await this.request("POST", "/v1/connectors/runs", run2);
   }
@@ -1573,22 +2548,35 @@ function printOpsTable(io, ops) {
   printTable(io, opRows(ops), ["op", "index", "detail"]);
 }
 function readAppliedMarker(dir) {
-  const path2 = (0, import_path7.join)(dir, APPLIED_MARKER_FILE);
-  if (!(0, import_fs6.existsSync)(path2)) return 0;
+  const path2 = (0, import_path9.join)(dir, APPLIED_MARKER_FILE);
+  if (!(0, import_fs7.existsSync)(path2)) return 0;
   try {
-    const parsed = JSON.parse((0, import_fs6.readFileSync)(path2, "utf-8"));
+    const parsed = JSON.parse((0, import_fs7.readFileSync)(path2, "utf-8"));
     return typeof parsed.version === "number" ? parsed.version : 0;
   } catch {
     return 0;
   }
 }
 function writeAppliedMarker(dir, version) {
-  (0, import_fs6.mkdirSync)(dir, { recursive: true });
-  (0, import_fs6.writeFileSync)((0, import_path7.join)(dir, APPLIED_MARKER_FILE), JSON.stringify({ version }, null, 2));
+  (0, import_fs7.mkdirSync)(dir, { recursive: true });
+  (0, import_fs7.writeFileSync)((0, import_path9.join)(dir, APPLIED_MARKER_FILE), JSON.stringify({ version }, null, 2));
 }
-async function planSchemaDiff(deps) {
-  const applied = await deps.client.getSchemaState();
-  return planMigration(deps.config, applied, { allowDestructive: deps.allowDestructive });
+function configHashes(config, index) {
+  const def = config.indexes.find((d) => d.name === index);
+  return def ? { schemaHash: docShapeHash(def), settingsHash: settingsHash(def) } : void 0;
+}
+function orphanedStates(applied, indexUids) {
+  return applied.filter((a) => !indexUids.has(a.indexUid) && !indexUids.has(a.physicalUid));
+}
+function orphanHint(orphans) {
+  const names = orphans.map((o) => o.indexUid).join(", ");
+  return `Schema state is recorded for ${names}, but no such index exists any more. Clear it with "headband schema forget <index>", then run "headband schema generate" and "headband schema apply" to create the index again.`;
+}
+function warnOrphans(io, applied, indexUids) {
+  if (!indexUids) return [];
+  const orphans = orphanedStates(applied, indexUids);
+  if (orphans.length > 0) io.stderr(orphanHint(orphans));
+  return orphans;
 }
 async function runSchemaGenerate(deps) {
   const applied = await deps.client.getSchemaState();
@@ -1599,13 +2587,16 @@ async function runSchemaGenerate(deps) {
   }
   const appliedByUid = new Map(applied.map((a) => [a.indexUid, a]));
   const parentHashes = {};
+  const targetHashes = {};
   for (const op of ops) {
     parentHashes[op.index] = appliedByUid.get(op.index)?.schemaHash ?? "";
+    const target = configHashes(deps.config, op.index);
+    if (target) targetHashes[op.index] = target;
   }
   const path2 = generateMigrationFile(
     deps.dir,
     ops,
-    { parentHashes, slug: deps.slug ?? "migration" },
+    { parentHashes, slug: deps.slug ?? "migration", targetHashes },
     deps.now
   );
   deps.io.stdout(`Wrote ${path2}`);
@@ -1618,43 +2609,81 @@ function isConflictError(err) {
 }
 async function createIndexIdempotent(ctx, uid, opts) {
   try {
-    await ctx.client.createIndex(uid, opts);
+    await ctx.client.createIndex(uid, {
+      ...opts,
+      ...ctx.projectId ? { projectId: ctx.projectId } : {}
+    });
   } catch (err) {
     if (!isConflictError(err)) throw err;
-    ctx.io.stdout(`Index "${uid}" already exists \u2014 continuing.`);
+    ctx.io.stdout(`Index "${uid}" already exists. Continuing.`);
+  }
+}
+var ES_EVERY_FIELD = [
+  "searchableAttributes",
+  "filterableAttributes",
+  "sortableAttributes"
+];
+async function indexEngine(ctx, uid) {
+  try {
+    return (await ctx.client.getIndex(uid)).engine ?? null;
+  } catch {
+    return null;
+  }
+}
+function settingsForEngine(ctx, uid, engine, settings) {
+  if (engine !== "elasticsearch") return settings;
+  const out = { ...settings };
+  const left = [];
+  for (const key of ES_EVERY_FIELD) {
+    if (out[key] === void 0) continue;
+    delete out[key];
+    left.push(key);
+  }
+  if (left.length > 0) {
+    ctx.io.stdout(
+      `"${uid}" is on Elasticsearch, which searches, filters and sorts every field without these lists, so they are not sent: ${left.join(", ")}.`
+    );
+  }
+  return out;
+}
+async function patchSettingsBeforeBackfill(ctx, uid, settings) {
+  if (Object.keys(settings).length === 0) return false;
+  try {
+    await ctx.client.patchSettings(uid, settings);
+    return false;
+  } catch (err) {
+    if (err?.code === "settings_need_documents") {
+      ctx.io.stdout(
+        `Settings for "${uid}" need its documents first: applying them after the backfill.`
+      );
+      return true;
+    }
+    throw settingsRefused(uid, err);
   }
 }
+async function patchSettingsAfterBackfill(ctx, uid, settings) {
+  try {
+    await ctx.client.patchSettings(uid, settings);
+  } catch (err) {
+    throw settingsRefused(uid, err);
+  }
+}
+function settingsRefused(uid, err) {
+  const message = err instanceof Error ? err.message : String(err);
+  const { status, code } = err ?? {};
+  const refused = new CliError(
+    `Index "${uid}" exists, but its settings were refused: ${message.replace(/\.?$/, ".")} Change the index's settings in headband.config.ts, then re-run "headband schema apply": it picks up the existing index.`,
+    {
+      ...typeof status === "number" ? { exitCode: exitCodeForStatus(status) } : {},
+      ...typeof code === "string" ? { code } : {}
+    }
+  );
+  return Object.assign(refused, { refusal: message });
+}
 function postState(client, state) {
   return client.postSchemaState(state);
 }
-async function applyReindex(op, ctx, existing, expectedParentHash) {
-  const def = ctx.config.indexes.find((d) => d.name === op.index);
-  if (!def) {
-    throw new CliError(`Cannot reindex "${op.index}": no matching index in the loaded config.`);
-  }
-  await createIndexIdempotent(ctx, op.toPhysicalUid, { primaryKey: def.primaryKey });
-  await ctx.client.patchSettings(op.toPhysicalUid, op.settings);
-  const version = (existing?.version ?? 0) + 1;
-  const schemaHashValue = docShapeHash(def);
-  const settingsHashValue = settingsHash(def);
-  let parentHash = expectedParentHash;
-  const writeState = async (status, cursor2) => {
-    await postState(ctx.client, {
-      indexUid: op.index,
-      version,
-      schemaHash: schemaHashValue,
-      settingsHash: settingsHashValue,
-      physicalUid: op.toPhysicalUid,
-      status,
-      // The `/v1/schema/state` route only accepts a string|null
-      // backfillCursor (see route.ts) — `Id` can be numeric, so it must be
-      // stringified before crossing the wire.
-      backfillCursor: cursor2 === null ? null : String(cursor2),
-      expectedParentHash: parentHash
-    });
-    parentHash = schemaHashValue;
-  };
-  await writeState("migrating", null);
+async function backfill(ctx, def, targetUid, abortPoint, onPage) {
   let cursor = null;
   let pushed = 0;
   let excluded = 0;
@@ -1675,24 +2704,137 @@ async function applyReindex(op, ctx, existing, expectedParentHash) {
       toPush.push(doc);
     }
     if (toPush.length > 0) {
-      const result = await ctx.client.bulkPush(op.toPhysicalUid, toPush, def.primaryKey);
+      const result = await ctx.client.bulkPush(targetUid, toPush, def.primaryKey);
       if (result?.partialFailure) {
         throw new CliError(
-          `Backfill of "${op.index}" stopped: ${partialFailureSummary(result.partialFailure)}. Aborting before the alias flip. Fix the rejected documents, then re-run "headband schema apply".`
+          `Backfill of "${def.name}" stopped: ${partialFailureSummary(result.partialFailure)}. Aborting ${abortPoint}. Fix the rejected documents, then re-run "headband schema apply".`
         );
       }
       pushed += toPush.length;
     }
     cursor = page.nextCursor;
-    await writeState("migrating", cursor);
+    if (onPage) await onPage(cursor);
     if (cursor === null || page.ids.length < ctx.backfillBatchSize) break;
   }
   if (pushed + excluded !== total) {
     throw new CliError(
-      `Backfill count mismatch for "${op.index}": listed ${total} source row(s) but accounted for ${pushed + excluded} (${pushed} pushed, ${excluded} excluded by shouldIndex). Aborting before the alias flip \u2014 re-run "headband schema apply" once resolved.`
+      `Backfill count mismatch for "${def.name}": listed ${total} source row(s) but accounted for ${pushed + excluded} (${pushed} pushed, ${excluded} excluded by shouldIndex). Aborting ${abortPoint}. Re-run "headband schema apply" once resolved.`
+    );
+  }
+  ctx.io.stdout(
+    `Backfilled "${def.name}": ${pushed} document(s) pushed${excluded > 0 ? `, ${excluded} row(s) left out by shouldIndex` : ""}.`
+  );
+  return { pushed, excluded };
+}
+async function catchUp(ctx, def, targetUid, when) {
+  if (!ctx.readRemoteDocuments) return;
+  const remote = await ctx.readRemoteDocuments(targetUid, def.primaryKey);
+  const keep = /* @__PURE__ */ new Set();
+  let pushed = 0;
+  let cursor = null;
+  for (; ; ) {
+    const page = await ctx.adapter.listIds(def.source, cursor, ctx.backfillBatchSize);
+    if (page.ids.length === 0) break;
+    const docs = await ctx.adapter.resolveDocs(def.name, page.ids);
+    const toPush = [];
+    for (const doc of docs) {
+      const sourceRow = doc.__source ?? doc;
+      delete doc.__source;
+      if (def.shouldIndex && !def.shouldIndex(sourceRow)) continue;
+      const key = String(doc[def.primaryKey]);
+      keep.add(key);
+      if (!documentsMatch(doc, remote.get(key), def.primaryKey)) toPush.push(doc);
+    }
+    if (toPush.length > 0) {
+      const result = await ctx.client.bulkPush(targetUid, toPush, def.primaryKey);
+      if (result?.partialFailure) {
+        throw new CliError(
+          `Catching up "${def.name}" ${when} stopped: ${partialFailureSummary(result.partialFailure)}. Re-run "headband schema apply" once resolved.`
+        );
+      }
+      pushed += toPush.length;
+    }
+    cursor = page.nextCursor;
+    if (cursor === null || page.ids.length < ctx.backfillBatchSize) break;
+  }
+  const extra = [...remote.keys()].filter((key) => !keep.has(key));
+  for (let offset = 0; offset < extra.length; offset += ctx.backfillBatchSize) {
+    const result = await ctx.client.deleteDocs(
+      targetUid,
+      extra.slice(offset, offset + ctx.backfillBatchSize)
     );
+    if (result?.partialFailure) {
+      throw new CliError(
+        `Catching up "${def.name}" ${when} stopped: ${partialFailureSummary(result.partialFailure)}. Re-run "headband schema apply" once resolved.`
+      );
+    }
+  }
+  ctx.io.stdout(
+    `Caught up "${def.name}" ${when}: ${pushed} changed or new document(s) written, ${extra.length} removed.`
+  );
+}
+async function abandonReindex(ctx, index, physical, err) {
+  let removed;
+  try {
+    await ctx.client.deleteIndex(physical);
+    removed = `The new index "${physical}" was removed`;
+  } catch (deleteErr) {
+    const why = deleteErr instanceof Error ? deleteErr.message : String(deleteErr);
+    removed = `The new index "${physical}" could not be removed (${why}): remove it with "headband indexes delete ${physical}"`;
+  }
+  const reason = err?.refusal ?? (err instanceof Error ? err.message : String(err));
+  return new CliError(
+    `The reindex of "${index}" stopped: the new index's settings were refused: ${String(reason).replace(/\.?$/, ".")} ${removed}, and "${index}" is unchanged. Change the index's settings in headband.config.ts, then re-run "headband schema apply".`,
+    {
+      ...err instanceof CliError ? { exitCode: err.exitCode, code: err.code } : {}
+    }
+  );
+}
+async function applyReindex(op, ctx, existing, expectedParentHash) {
+  const def = ctx.config.indexes.find((d) => d.name === op.index);
+  if (!def) {
+    throw new CliError(`Cannot reindex "${op.index}": no matching index in the loaded config.`);
+  }
+  const settings = settingsForEngine(ctx, op.index, await indexEngine(ctx, op.index), op.settings);
+  await createIndexIdempotent(ctx, op.toPhysicalUid, { primaryKey: def.primaryKey });
+  let settingsAfter;
+  try {
+    settingsAfter = await patchSettingsBeforeBackfill(ctx, op.toPhysicalUid, settings);
+  } catch (err) {
+    throw await abandonReindex(ctx, op.index, op.toPhysicalUid, err);
   }
+  const version = (existing?.version ?? 0) + 1;
+  const schemaHashValue = docShapeHash(def);
+  const settingsHashValue = settingsHash(def);
+  let parentHash = expectedParentHash;
+  const writeState = async (status, cursor) => {
+    await postState(ctx.client, {
+      indexUid: op.index,
+      version,
+      schemaHash: schemaHashValue,
+      settingsHash: settingsHashValue,
+      physicalUid: op.toPhysicalUid,
+      status,
+      // The `/v1/schema/state` route only accepts a string|null
+      // backfillCursor (see route.ts). `Id` can be numeric, so it must be
+      // stringified before crossing the wire.
+      backfillCursor: cursor === null ? null : String(cursor),
+      expectedParentHash: parentHash
+    });
+    parentHash = schemaHashValue;
+  };
+  await writeState("migrating", null);
+  await backfill(
+    ctx,
+    def,
+    op.toPhysicalUid,
+    "before the alias flip",
+    (cursor) => writeState("migrating", cursor)
+  );
+  if (settingsAfter) await patchSettingsAfterBackfill(ctx, op.toPhysicalUid, settings);
+  await catchUp(ctx, def, op.toPhysicalUid, "before the alias flip");
   await ctx.client.patchAlias(op.index, op.toPhysicalUid);
+  await catchUp(ctx, def, op.index, "after the alias flip");
   await writeState("applied", null);
   return {
     indexUid: op.index,
@@ -1706,17 +2848,26 @@ async function applyReindex(op, ctx, existing, expectedParentHash) {
 async function applyOp(op, ctx, existing, expectedParentHash) {
   if (op.type === "create-index") {
     const def = ctx.config.indexes.find((d) => d.name === op.index);
-    await createIndexIdempotent(
+    if (!def) {
+      throw new CliError(
+        `Cannot create "${op.index}": no matching index in the loaded config. Regenerate with "headband schema generate".`
+      );
+    }
+    await createIndexIdempotent(ctx, op.index, { primaryKey: def.primaryKey });
+    const settings = settingsForEngine(
       ctx,
       op.index,
-      def?.primaryKey ? { primaryKey: def.primaryKey } : void 0
+      await indexEngine(ctx, op.index),
+      op.settings
     );
-    await ctx.client.patchSettings(op.index, op.settings);
+    const settingsAfter = await patchSettingsBeforeBackfill(ctx, op.index, settings);
+    await backfill(ctx, def, op.index, "before recording the index as applied");
+    if (settingsAfter) await patchSettingsAfterBackfill(ctx, op.index, settings);
     const next = {
       indexUid: op.index,
       version: 1,
-      schemaHash: def ? docShapeHash(def) : "",
-      settingsHash: def ? settingsHash(def) : "",
+      schemaHash: docShapeHash(def),
+      settingsHash: settingsHash(def),
       physicalUid: op.physicalUid,
       status: "applied"
     };
@@ -1727,7 +2878,13 @@ async function applyOp(op, ctx, existing, expectedParentHash) {
     if (!existing) {
       throw new CliError(`Cannot patch settings for "${op.index}": no applied schema state found.`);
     }
-    await ctx.client.patchSettings(op.index, op.settings);
+    const settings = settingsForEngine(
+      ctx,
+      op.index,
+      await indexEngine(ctx, op.index),
+      op.settings
+    );
+    if (Object.keys(settings).length > 0) await ctx.client.patchSettings(op.index, settings);
     const def = ctx.config.indexes.find((d) => d.name === op.index);
     const next = {
       ...existing,
@@ -1741,31 +2898,60 @@ async function applyOp(op, ctx, existing, expectedParentHash) {
     return applyReindex(op, ctx, existing, expectedParentHash);
   }
   ctx.io.stdout(
-    `Skipping engine deletion for index "${op.index}" \u2014 not yet supported by the API. Remove it manually with "headband indexes delete ${op.index}" if needed.`
+    `Skipping engine deletion for index "${op.index}": not yet supported by the API. Remove it manually with "headband indexes delete ${op.index}" if needed.`
   );
   return void 0;
 }
+function serverAppliedThrough(files, applied, config) {
+  const byUid = new Map(applied.map((a) => [a.indexUid, a]));
+  const lastFileFor = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    for (const op of file.ops) lastFileFor.set(op.index, file.version);
+  }
+  const through = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    for (const index of new Set(file.ops.map((op) => op.index))) {
+      const state = byUid.get(index);
+      if (!state || state.status !== "applied") continue;
+      const target = file.targetHashes?.[index] ?? (lastFileFor.get(index) === file.version ? configHashes(config, index) : void 0);
+      if (target && target.schemaHash === state.schemaHash && target.settingsHash === state.settingsHash) {
+        through.set(index, file.version);
+      }
+    }
+  }
+  return through;
+}
 async function runSchemaApply(deps) {
   const files = readMigrations(deps.dir);
   const appliedVersion = readAppliedMarker(deps.dir);
   const pending = pendingMigrations(files, appliedVersion);
   if (pending.length === 0) {
-    deps.io.stdout("No pending migrations to apply.");
+    deps.io.stdout(
+      files.length === 0 ? `No migration files in ${deps.dir}. Run "headband schema generate" first.` : "No pending migrations to apply."
+    );
     return { appliedFiles: 0, appliedOps: 0 };
   }
   const applied = await deps.client.getSchemaState();
   const existingByIndex = new Map(applied.map((a) => [a.indexUid, a]));
+  const appliedThrough = serverAppliedThrough(files, applied, deps.config);
   const ctx = {
     config: deps.config,
     adapter: deps.adapter,
     client: deps.client,
     backfillBatchSize: deps.backfillBatchSize ?? DEFAULT_BACKFILL_BATCH_SIZE,
-    io: deps.io
+    io: deps.io,
+    projectId: deps.projectId,
+    readRemoteDocuments: deps.readRemoteDocuments
   };
   let appliedOps = 0;
   let appliedFiles = 0;
   for (const file of pending) {
+    let skipped = 0;
     for (const op of file.ops) {
+      if ((appliedThrough.get(op.index) ?? 0) >= file.version) {
+        skipped += 1;
+        continue;
+      }
       if (op.type === "remove-index" && !deps.allowDestructive) {
         throw new CliError(
           `Migration ${file.version} contains a destructive "remove-index" op for "${op.index}". Re-run with --allow-destructive to proceed.`
@@ -1788,26 +2974,56 @@ async function runSchemaApply(deps) {
       } catch (err) {
         if (err instanceof SchemaCasError) {
           throw new CliError(
-            `Schema state for "${op.index}" was changed by another machine since this migration was generated \u2014 re-run "headband schema diff" and regenerate before retrying. (${err.message})`
+            `Schema state for "${op.index}" was changed by another machine since this migration was generated. Re-run "headband schema diff" and regenerate before retrying. (${err.message})`
           );
         }
         throw err;
       }
     }
     writeAppliedMarker(deps.dir, file.version);
+    if (skipped === file.ops.length) {
+      deps.io.stdout(
+        `Migration ${file.version}${file.path ? ` (${file.path})` : ""} is already applied on the server. Skipped.`
+      );
+      continue;
+    }
     appliedFiles += 1;
     deps.io.stdout(`Applied migration ${file.version}${file.path ? ` (${file.path})` : ""}.`);
   }
   return { appliedFiles, appliedOps };
 }
+function serverAppliedVersion(files, applied, config) {
+  const through = serverAppliedThrough(files, applied, config);
+  const known = new Set(applied.map((a) => a.indexUid));
+  let version = 0;
+  for (const file of files) {
+    const done = file.ops.every(
+      (op) => op.type === "remove-index" ? !known.has(op.index) : (through.get(op.index) ?? 0) >= file.version
+    );
+    if (!done) break;
+    version = file.version;
+  }
+  return version;
+}
 async function runSchemaStatus(deps) {
   const applied = await deps.client.getSchemaState();
   const appliedByUid = new Map(applied.map((a) => [a.indexUid, a]));
+  const orphans = new Set(
+    deps.indexUids ? orphanedStates(applied, deps.indexUids).map((o) => o.indexUid) : []
+  );
   const rows = deps.config.indexes.map((def) => {
     const existing = appliedByUid.get(def.name);
     if (!existing) {
       return { index: def.name, status: "missing", version: 0, drift: "missing" };
     }
+    if (orphans.has(def.name)) {
+      return {
+        index: def.name,
+        status: existing.status,
+        version: existing.version,
+        drift: "index missing"
+      };
+    }
     const schemaDrifted = docShapeHash(def) !== existing.schemaHash;
     const settingsDrifted = settingsHash(def) !== existing.settingsHash;
     return {
@@ -1818,16 +3034,42 @@ async function runSchemaStatus(deps) {
     };
   });
   printTable(deps.io, rows, ["index", "status", "version", "drift"]);
+  if (orphans.size > 0) {
+    deps.io.stdout(orphanHint(applied.filter((a) => orphans.has(a.indexUid))));
+  }
   const files = readMigrations(deps.dir);
-  const localVersion = readAppliedMarker(deps.dir);
+  const markerVersion = readAppliedMarker(deps.dir);
   const localHead = files.length > 0 ? files[files.length - 1].version : 0;
-  deps.io.stdout(`Local migrations applied: ${localVersion}/${localHead}`);
-  return { indexes: rows, localApplied: localVersion, localHead };
+  const present = applied.filter((a) => !orphans.has(a.indexUid));
+  const localVersion = serverAppliedVersion(files, present, deps.config);
+  deps.io.stdout(`Local migrations applied on the server: ${localVersion}/${localHead}`);
+  if (markerVersion !== localVersion) {
+    deps.io.stdout(
+      `(${APPLIED_MARKER_FILE} says ${markerVersion}. That file is only a local cache; schema apply reads the server's state.)`
+    );
+  }
+  return { indexes: rows, localApplied: localVersion, localHead, markerApplied: markerVersion };
+}
+async function runSchemaForget(deps) {
+  try {
+    await deps.client.deleteSchemaState(deps.index);
+  } catch (err) {
+    const status = err.status;
+    if (status === 404) {
+      throw new CliError(`No schema state is recorded for "${deps.index}".`, {
+        code: "schema_state_not_found"
+      });
+    }
+    throw err;
+  }
+  deps.io.stdout(
+    `Forgot the schema state of "${deps.index}". Run "headband schema generate" and "headband schema apply" to create it again.`
+  );
 }
 
 // src/sync.ts
-var import_fs7 = require("fs");
-var import_path8 = require("path");
+var import_fs8 = require("fs");
+var import_path10 = require("path");
 var import_crypto = require("crypto");
 var import_pg = require("pg");
 
@@ -1881,7 +3123,7 @@ function pgOutboxDriver(exec, opts) {
       return rows.map(mapRow);
     },
     async markDone(ids) {
-      await exec(`UPDATE ${table} SET status = 'done' WHERE id = ANY($1)`, [ids]);
+      await exec(`DELETE FROM ${table} WHERE id = ANY($1)`, [ids]);
     },
     async deadLetter(id, error) {
       await exec(
@@ -1890,10 +3132,17 @@ function pgOutboxDriver(exec, opts) {
       );
     },
     async markFailed(id, error) {
-      await exec(
-        `UPDATE ${table} SET attempts = attempts + 1, last_error = $2, status = CASE WHEN attempts + 1 >= $3 THEN 'dead_letter' ELSE 'pending' END, claimed_at = NULL WHERE id = $1`,
+      const { rows } = await exec(
+        `UPDATE ${table} SET attempts = attempts + 1, last_error = $2, status = CASE WHEN attempts + 1 >= $3 THEN 'dead_letter' ELSE 'pending' END, claimed_at = NULL WHERE id = $1 RETURNING status`,
         [id, error, maxAttempts]
       );
+      return rows?.[0]?.status === "dead_letter" ? "dead_letter" : "pending";
+    },
+    async release(ids, error) {
+      await exec(
+        `UPDATE ${table} SET last_error = $2, claimed_at = NULL WHERE id = ANY($1) AND status = 'pending'`,
+        [ids, error]
+      );
     },
     async deadLetters(limit) {
       const { rows } = await exec(
@@ -1912,6 +3161,18 @@ function pgOutboxDriver(exec, opts) {
         `SELECT count(*) AS count FROM ${table} WHERE status = 'pending'`
       );
       return Number(rows[0]?.count ?? 0);
+    },
+    async stats() {
+      const { rows } = await exec(
+        `SELECT count(*) FILTER (WHERE status = 'pending') AS pending, count(*) FILTER (WHERE status = 'dead_letter') AS dead_letter, min(created_at) FILTER (WHERE status = 'pending') AS oldest_pending_at FROM ${table}`
+      );
+      const row = rows[0] ?? {};
+      const oldest = row.oldest_pending_at;
+      return {
+        pending: Number(row.pending ?? 0),
+        deadLetter: Number(row.dead_letter ?? 0),
+        oldestPendingAt: oldest == null ? null : new Date(oldest)
+      };
     }
   };
 }
@@ -2088,18 +3349,43 @@ function rowOutcomes(rows, resolved, failures) {
   rows.forEach((row, changeIndex) => {
     const rowFailures = failuresByRow.get(changeIndex);
     if (!rowFailures) {
-      done.push(row.id);
+      done.push(row);
       return;
     }
     const permanent = rowFailures.find((f) => !f.retryable);
-    if (permanent) deadLetter.push([row.id, permanent.message]);
-    else retry.push([row.id, rowFailures[0].message]);
+    if (permanent) deadLetter.push([row, permanent.message]);
+    else retry.push([row, rowFailures[0].message]);
   });
   return { done, retry, deadLetter };
 }
-function defaultSleep3(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
+function defaultSleep4(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function errorMessage(err) {
+  if (!(err instanceof Error)) return String(err);
+  const cause = err.cause;
+  const reason = cause instanceof Error && cause.message ? cause.message : void 0;
+  if (!reason || err.message.includes(reason)) return err.message;
+  const first = err.message.split("\n")[0];
+  return /^Failed query:/.test(first) ? `${reason} (${first.length > 160 ? `${first.slice(0, 160)}\u2026` : first})` : `${err.message}: ${reason}`;
+}
+function isTransientBatchError(err) {
+  const status = err?.status;
+  if (typeof status === "number") return status === 429 || status >= 500;
+  return err instanceof TypeError && /fetch failed|network/i.test(err.message);
+}
+function describeRow(row) {
+  const ids = row.docIds.length > 5 ? [...row.docIds.slice(0, 5), "\u2026"] : row.docIds;
+  return `outbox row ${row.id} (${row.model} ${row.op} ${JSON.stringify(ids)})`;
+}
+var emptyOutcome = () => ({
+  done: [],
+  retry: [],
+  release: [],
+  deadLetter: [],
+  pushed: 0,
+  deleted: 0
+});
 async function runSyncWorker(opts) {
   const {
     config,
@@ -2113,8 +3399,9 @@ async function runSyncWorker(opts) {
     batchSize = DEFAULT_BATCH_SIZE,
     stopSignal,
     now = Date.now,
-    sleep = defaultSleep3,
-    onHeartbeat
+    sleep = defaultSleep4,
+    onHeartbeat,
+    log = (message) => console.warn(message)
   } = opts;
   const primaryKeyByIndex = new Map(config.indexes.map((def) => [def.name, def.primaryKey]));
   const report = {
@@ -2122,11 +3409,59 @@ async function runSyncWorker(opts) {
     pushed: 0,
     deleted: 0,
     deadLettered: 0,
+    retried: 0,
     outboxDepth: 0
   };
   const start = now();
   const budgetExceeded = () => budgetMs !== void 0 && now() - start >= budgetMs;
   let consecutiveFailures = 0;
+  let heartbeatWarned = false;
+  const heartbeat = async (final) => {
+    if (!onHeartbeat) return;
+    try {
+      await onHeartbeat({ ...report }, { final });
+    } catch (err) {
+      if (heartbeatWarned) return;
+      heartbeatWarned = true;
+      log(`[headband] could not record this worker run: ${errorMessage(err)}`);
+    }
+  };
+  const backoff = (attempt) => sleep(Math.min(failureDelayMs * 2 ** (attempt - 1), MAX_FAILURE_DELAY_MS));
+  const processBatch = async (batch) => {
+    const changes = batch.map((row) => ({
+      model: row.model,
+      op: row.op,
+      ids: row.docIds,
+      snapshot: row.snapshot
+    }));
+    const resolved = await resolveDirtyDocs(adapter, config, changes);
+    const { failures, pushed, deleted } = await pushResolved(
+      resolved,
+      client,
+      primaryKeyByIndex,
+      backoff
+    );
+    return { ...rowOutcomes(batch, resolved, failures), release: [], pushed, deleted };
+  };
+  const processIsolated = async (batch) => {
+    const outcome = emptyOutcome();
+    for (const row of batch) {
+      try {
+        const one = await processBatch([row]);
+        outcome.done.push(...one.done);
+        outcome.retry.push(...one.retry);
+        outcome.deadLetter.push(...one.deadLetter);
+        outcome.pushed += one.pushed;
+        outcome.deleted += one.deleted;
+      } catch (err) {
+        (isTransientBatchError(err) ? outcome.release : outcome.retry).push([
+          row,
+          errorMessage(err)
+        ]);
+      }
+    }
+    return outcome;
+  };
   for (; ; ) {
     if (budgetExceeded()) break;
     if (stopSignal && stopSignal()) break;
@@ -2136,67 +3471,77 @@ async function runSyncWorker(opts) {
       await sleep(idleDelayMs);
       continue;
     }
-    const changes = rows.map((row) => ({
-      model: row.model,
-      op: row.op,
-      ids: row.docIds,
-      snapshot: row.snapshot
-    }));
+    let outcome;
+    let wholeBatchFailed = false;
     try {
-      const resolved = await resolveDirtyDocs(adapter, config, changes);
-      const { failures, pushed, deleted } = await pushResolved(
-        resolved,
-        client,
-        primaryKeyByIndex,
-        (attempt) => sleep(Math.min(failureDelayMs * 2 ** (attempt - 1), MAX_FAILURE_DELAY_MS))
-      );
-      report.pushed += pushed;
-      report.deleted += deleted;
-      const outcome = rowOutcomes(rows, resolved, failures);
-      if (outcome.done.length > 0) await outbox.markDone(outcome.done);
-      for (const [id, message] of outcome.deadLetter) {
-        if (outbox.deadLetter) await outbox.deadLetter(id, message);
-        else await outbox.markFailed(id, message);
+      outcome = await processBatch(rows);
+    } catch (err) {
+      const transient = isTransientBatchError(err);
+      if (rows.length > 1 && !transient) {
+        outcome = await processIsolated(rows);
+      } else {
+        wholeBatchFailed = true;
+        const message = errorMessage(err);
+        const failed = rows.map((row) => [row, message]);
+        outcome = transient ? { ...emptyOutcome(), release: failed } : { ...emptyOutcome(), retry: failed };
+        log(
+          `[headband] a batch of ${rows.length} outbox row(s) failed and will be retried: ${message}`
+        );
       }
-      for (const [id, message] of outcome.retry) {
-        await outbox.markFailed(id, message);
+    }
+    report.pushed += outcome.pushed;
+    report.deleted += outcome.deleted;
+    if (outcome.done.length > 0) await outbox.markDone(outcome.done.map((row) => row.id));
+    report.drained += outcome.done.length;
+    for (const [row, message] of outcome.deadLetter) {
+      if (outbox.deadLetter) {
+        await outbox.deadLetter(row.id, message);
+        report.deadLettered += 1;
+        log(`[headband] ${describeRow(row)} moved to dead letters: ${message}`);
+      } else {
+        const status = await outbox.markFailed(row.id, message);
+        if (status === "dead_letter") report.deadLettered += 1;
+        else report.retried += 1;
+        log(`[headband] ${describeRow(row)} failed: ${message}`);
       }
-      report.drained += outcome.done.length;
-      report.deadLettered += outcome.deadLetter.length + outcome.retry.length;
-      if (outcome.retry.length > 0) {
-        consecutiveFailures += 1;
-        await sleep(
-          Math.min(failureDelayMs * 2 ** (consecutiveFailures - 1), MAX_FAILURE_DELAY_MS)
+    }
+    if (outcome.release.length > 0) {
+      if (outbox.release) {
+        await outbox.release(
+          outcome.release.map(([row]) => row.id),
+          outcome.release[0][1]
         );
+        report.retried += outcome.release.length;
       } else {
-        consecutiveFailures = 0;
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      for (const row of rows) {
-        await outbox.markFailed(row.id, message);
+        outcome.retry.push(...outcome.release);
       }
-      report.deadLettered += rows.length;
-      consecutiveFailures += 1;
-      const delay = Math.min(failureDelayMs * 2 ** (consecutiveFailures - 1), MAX_FAILURE_DELAY_MS);
-      await sleep(delay);
     }
-    if (onHeartbeat) {
-      try {
-        await onHeartbeat({ ...report });
-      } catch (err) {
-        console.error("[headband] heartbeat failed:", err);
+    for (const [row, message] of outcome.retry) {
+      const status = await outbox.markFailed(row.id, message);
+      if (status === "dead_letter") {
+        report.deadLettered += 1;
+        log(
+          `[headband] ${describeRow(row)} moved to dead letters after ${row.attempts + 1} attempt(s): ${message}`
+        );
+      } else {
+        report.retried += 1;
+        if (!wholeBatchFailed) {
+          log(
+            `[headband] ${describeRow(row)} failed (attempt ${row.attempts + 1}), will retry: ${message}`
+          );
+        }
       }
     }
-  }
-  report.outboxDepth = await outbox.depth();
-  if (onHeartbeat) {
-    try {
-      await onHeartbeat({ ...report });
-    } catch (err) {
-      console.error("[headband] heartbeat failed:", err);
+    if (outcome.retry.length > 0 || outcome.release.length > 0) {
+      consecutiveFailures += 1;
+      await backoff(consecutiveFailures);
+    } else {
+      consecutiveFailures = 0;
     }
+    await heartbeat(false);
   }
+  report.outboxDepth = await outbox.depth();
+  await heartbeat(true);
   return report;
 }
 
@@ -2204,20 +3549,37 @@ async function runSyncWorker(opts) {
 var WORKER_VERSION = "1";
 var DEFAULT_DEAD_LETTER_LIMIT = 1e3;
 var RECONCILE_PAGE_SIZE = 500;
-var OUTBOX_SQL_RELATIVE_PATH = (0, import_path8.join)("headband", "outbox.sql");
+var OUTBOX_SQL_RELATIVE_PATH = (0, import_path10.join)("headband", "outbox.sql");
 var DOCKERFILE_NAME = "Dockerfile.headband-sync";
-var DOCKERFILE_CONTENT = `FROM node:22-slim
+var DEFAULT_OUTBOX_TABLE = "headband_outbox";
+var ORM_SYNC_CONNECTOR_SLUG = "orm-sync";
+function dockerfileContent(cliVersion) {
+  const pkg = cliVersion && cliVersion !== "dev" ? `@headband/cli@${cliVersion}` : "@headband/cli";
+  return `# Runs the Headband sync worker: drains the outbox table into your Headband indexes.
+#
+# It needs, at run time:
+#   DATABASE_URL       the Postgres database that holds your tables and the outbox table
+#   HEADBAND_API_KEY   an admin key that reaches your indexes (your project's admin key)
+#   HEADBAND_URL       optional, defaults to https://headband.dev
+#
+# The worker loads headband.config.ts from /app, so npm ci must install what it imports
+# (@headband/sync, @headband/drizzle, drizzle-orm, pg).
+FROM node:22-slim
 WORKDIR /app
 COPY . .
 RUN npm ci
-CMD ["npx", "headband", "sync", "worker"]
+CMD ["npx", "--yes", "${pkg}", "sync", "worker", "--loop"]
 `;
+}
 var COMPOSE_SNIPPET = `services:
   headband-sync:
     build:
       context: .
       dockerfile: ${DOCKERFILE_NAME}
-    env_file: .env
+    environment:
+      - DATABASE_URL
+      - HEADBAND_API_KEY
+      - HEADBAND_URL
     restart: unless-stopped
 `;
 function resolveDatabaseUrl(env = process.env) {
@@ -2229,33 +3591,79 @@ function resolveDatabaseUrl(env = process.env) {
   }
   return url;
 }
+var UNDEFINED_TABLE = "42P01";
+function missingOutboxTableError(table) {
+  return new CliError(
+    `The outbox table "${table}" does not exist in the database DATABASE_URL points at. Create it once with "headband sync init --apply", or add the SQL that "headband sync init" prints to your own migrations.`,
+    { code: "outbox_table_missing" }
+  );
+}
 function buildPgOutbox(connectionString, opts) {
+  const table = opts?.table ?? DEFAULT_OUTBOX_TABLE;
   const pool = new import_pg.Pool({ connectionString });
   const exec = async (sqlText, params) => {
-    const result = await pool.query(sqlText, params);
-    return { rows: result.rows };
+    try {
+      const result = await pool.query(sqlText, params);
+      return { rows: result.rows };
+    } catch (err) {
+      if (err.code === UNDEFINED_TABLE)
+        throw missingOutboxTableError(table);
+      throw err;
+    }
   };
   return { outbox: pgOutboxDriver(exec, opts), close: () => pool.end() };
 }
-function runSyncInit(deps) {
+async function applyOutboxDDL(connectionString, ddl) {
+  const pool = new import_pg.Pool({ connectionString });
+  try {
+    await pool.query(ddl);
+  } finally {
+    await pool.end();
+  }
+}
+async function runSyncInit(deps) {
   const ddl = outboxDDL(deps.table);
+  const table = deps.table ?? DEFAULT_OUTBOX_TABLE;
   deps.io.stdout(ddl);
   if (deps.write) {
-    const path2 = (0, import_path8.join)(deps.cwd ?? process.cwd(), OUTBOX_SQL_RELATIVE_PATH);
-    (0, import_fs7.mkdirSync)((0, import_path8.join)(deps.cwd ?? process.cwd(), "headband"), { recursive: true });
-    (0, import_fs7.writeFileSync)(path2, `${ddl}
+    const path2 = (0, import_path10.join)(deps.cwd ?? process.cwd(), OUTBOX_SQL_RELATIVE_PATH);
+    (0, import_fs8.mkdirSync)((0, import_path10.join)(deps.cwd ?? process.cwd(), "headband"), { recursive: true });
+    (0, import_fs8.writeFileSync)(path2, `${ddl}
 `);
     deps.io.stdout(`Wrote ${path2}`);
   }
+  if (deps.apply) {
+    await deps.apply(ddl);
+    deps.io.stdout(`Created the outbox table "${table}" (if it was missing).`);
+  } else {
+    deps.io.stdout(
+      `
+Run this SQL once against your database: "headband sync init --apply" does it with DATABASE_URL, or add it to your own migrations.`
+    );
+  }
   return ddl;
 }
 var SHUTDOWN_SIGNALS = ["SIGINT", "SIGTERM"];
+function explainReportRunError(err) {
+  const code = err?.code;
+  const message = err instanceof Error ? err.message : String(err);
+  if (code === "project_id_required") {
+    return "your key is org-wide, so the run needs a project. Pass --project <id>, or set projectId in headband.config.ts.";
+  }
+  if (code === "invalid_connector_run" && /connectorSlug/.test(message)) {
+    return "this Headband server does not record self-hosted sync runs yet. Syncing is unaffected.";
+  }
+  return message;
+}
 async function runSyncWorkerCmd(deps) {
   const schemaHashes = Object.fromEntries(
     deps.config.indexes.map((def) => [def.name, docShapeHash(def)])
   );
   const workerVersion = deps.workerVersion ?? WORKER_VERSION;
-  let heartbeats = 0;
+  const externalRunId = (0, import_crypto.randomUUID)();
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  let batches = 0;
+  let last = { drained: 0, pushed: 0, deleted: 0, deadLettered: 0 };
   const proc = deps.process ?? process;
   let stopRequested = false;
   const handleShutdown = () => {
@@ -2280,83 +3688,274 @@ async function runSyncWorkerCmd(deps) {
       now: deps.now,
       sleep: deps.sleep,
       stopSignal: () => stopRequested,
-      onHeartbeat: async (r) => {
-        heartbeats += 1;
-        await deps.client.reportRun({
-          connectorSlug: "orm-sync",
-          status: r.deadLettered > 0 ? "error" : "success",
-          count: r.pushed + r.deleted,
-          externalRunId: (0, import_crypto.randomUUID)(),
-          details: { outboxDepth: r.outboxDepth, workerVersion, schemaHashes }
-        });
-        if (deps.reconcileEvery && deps.onReconcileTick && heartbeats % deps.reconcileEvery === 0) {
-          await deps.onReconcileTick();
+      log: (message) => deps.io.stderr(message),
+      onHeartbeat: async (r, { final }) => {
+        if (!final) {
+          batches += 1;
+          const drained = r.drained - last.drained;
+          if (drained > 0) {
+            const dead = r.deadLettered - last.deadLettered;
+            deps.io.stderr(
+              `[headband] batch ${batches}: drained ${drained} row(s), pushed ${r.pushed - last.pushed}, deleted ${r.deleted - last.deleted}${dead > 0 ? `, dead-lettered ${dead}` : ""}.`
+            );
+          }
+          last = {
+            drained: r.drained,
+            pushed: r.pushed,
+            deleted: r.deleted,
+            deadLettered: r.deadLettered
+          };
+          if (deps.reconcileEvery && deps.onReconcileTick && batches % deps.reconcileEvery === 0) {
+            try {
+              await deps.onReconcileTick();
+            } catch (err) {
+              deps.io.stderr(
+                `[headband] reconcile failed: ${err instanceof Error ? err.message : String(err)}`
+              );
+            }
+          }
         }
+        try {
+          await deps.client.reportRun({
+            connectorSlug: ORM_SYNC_CONNECTOR_SLUG,
+            ...deps.projectId ? { projectId: deps.projectId } : {},
+            status: final ? r.deadLettered > 0 ? "dead_letter" : "succeeded" : "started",
+            mode: "self_hosted",
+            command: "headband sync worker",
+            count: r.pushed + r.deleted,
+            externalRunId,
+            startedAt,
+            details: {
+              drained: r.drained,
+              pushed: r.pushed,
+              deleted: r.deleted,
+              deadLettered: r.deadLettered,
+              retried: r.retried,
+              outboxDepth: r.outboxDepth,
+              workerVersion,
+              schemaHashes
+            }
+          });
+        } catch (err) {
+          throw new Error(explainReportRunError(err));
+        }
+      }
+    });
+    deps.io.stdout(
+      `Drained ${report.drained} row(s): pushed ${report.pushed}, deleted ${report.deleted}, dead-lettered ${report.deadLettered}, left for retry ${report.retried}. Outbox depth: ${report.outboxDepth}.`
+    );
+    if (report.deadLettered > 0) {
+      deps.io.stderr(
+        `${report.deadLettered} row(s) moved to dead letters (reasons above). Fix the cause, then run: headband sync retry-dead-letters`
+      );
+    }
+    return report;
+  } finally {
+    for (const signal of SHUTDOWN_SIGNALS) {
+      proc.removeListener(signal, handleShutdown);
+    }
+  }
+}
+async function reconcileContent(deps, def, pageSize) {
+  const remote = await deps.readRemoteDocuments(def.name, def.primaryKey);
+  const keep = /* @__PURE__ */ new Set();
+  let missing = 0;
+  let stale = 0;
+  let cursor = null;
+  for (; ; ) {
+    const page = await deps.adapter.listIds(def.source, cursor, pageSize);
+    if (page.ids.length === 0) break;
+    const docs = await deps.adapter.resolveDocs(def.name, page.ids);
+    const toPush = [];
+    for (const doc of docs) {
+      const sourceRow = doc.__source ?? doc;
+      delete doc.__source;
+      if (def.shouldIndex && !def.shouldIndex(sourceRow)) continue;
+      const key = String(doc[def.primaryKey]);
+      keep.add(key);
+      const indexed = remote.get(key);
+      if (!indexed) missing += 1;
+      else if (!documentsMatch(doc, indexed, def.primaryKey)) stale += 1;
+      else continue;
+      toPush.push(doc);
+    }
+    if (deps.fix && toPush.length > 0) {
+      const result = await deps.client.bulkPush(def.name, toPush, def.primaryKey);
+      if (result?.partialFailure) {
+        throw new CliError(
+          `Repair push for "${def.name}" was incomplete: ${partialFailureSummary(result.partialFailure)}.`
+        );
+      }
+    }
+    if (page.nextCursor === null) break;
+    cursor = page.nextCursor;
+  }
+  const extraIds = [...remote.keys()].filter((key) => !keep.has(key));
+  if (deps.fix) {
+    for (let offset = 0; offset < extraIds.length; offset += pageSize) {
+      const result = await deps.client.deleteDocs(
+        def.name,
+        extraIds.slice(offset, offset + pageSize)
+      );
+      if (result?.partialFailure) {
+        throw new CliError(
+          `Removing extra documents from "${def.name}" was incomplete: ${partialFailureSummary(result.partialFailure)}.`
+        );
       }
-    });
-    deps.io.stdout(
-      `Drained ${report.drained} row(s): pushed ${report.pushed}, deleted ${report.deleted}, dead-lettered ${report.deadLettered}. Outbox depth: ${report.outboxDepth}.`
-    );
-    return report;
-  } finally {
-    for (const signal of SHUTDOWN_SIGNALS) {
-      proc.removeListener(signal, handleShutdown);
     }
   }
+  const drift = missing + extraIds.length + stale;
+  return {
+    index: def.name,
+    sourceCount: keep.size,
+    remoteCount: remote.size,
+    missing,
+    extra: extraIds.length,
+    stale,
+    drift,
+    fixed: Boolean(deps.fix) && drift !== 0
+  };
 }
-async function collectAllIds(adapter, model) {
-  const ids = [];
+async function indexableSourceIds(adapter, def, pageSize) {
+  const ids = /* @__PURE__ */ new Map();
   let cursor = null;
   for (; ; ) {
-    const page = await adapter.listIds(model, cursor, RECONCILE_PAGE_SIZE);
-    ids.push(...page.ids);
-    if (page.nextCursor === null || page.ids.length === 0) break;
+    const page = await adapter.listIds(def.source, cursor, pageSize);
+    if (page.ids.length === 0) break;
+    const docs = await adapter.resolveDocs(def.name, page.ids);
+    for (const doc of docs) {
+      const sourceRow = doc.__source ?? doc;
+      if (def.shouldIndex && !def.shouldIndex(sourceRow)) continue;
+      const id = doc[def.primaryKey];
+      if (id !== void 0 && id !== null) ids.set(String(id), id);
+    }
+    if (page.nextCursor === null) break;
     cursor = page.nextCursor;
   }
   return ids;
 }
+async function pushSourceRows(deps, def, ids, pageSize) {
+  let pushed = 0;
+  for (let offset = 0; offset < ids.length; offset += pageSize) {
+    const docs = await deps.adapter.resolveDocs(def.name, ids.slice(offset, offset + pageSize));
+    const toPush = [];
+    for (const doc of docs) {
+      const sourceRow = doc.__source ?? doc;
+      delete doc.__source;
+      if (def.shouldIndex && !def.shouldIndex(sourceRow)) continue;
+      toPush.push(doc);
+    }
+    if (toPush.length === 0) continue;
+    const result = await deps.client.bulkPush(def.name, toPush, def.primaryKey);
+    if (result?.partialFailure) {
+      throw new CliError(
+        `Repair push for "${def.name}" was incomplete: ${partialFailureSummary(result.partialFailure)}.`
+      );
+    }
+    pushed += toPush.length;
+  }
+  return pushed;
+}
 async function runSyncReconcile(deps) {
-  const ormSchema = deps.adapter.introspect();
+  const pageSize = deps.pageSize ?? RECONCILE_PAGE_SIZE;
   const rows = [];
   for (const def of deps.config.indexes) {
-    const ids = await collectAllIds(deps.adapter, def.source);
-    const sourceCount = ids.length;
+    if (deps.content && deps.readRemoteDocuments) {
+      try {
+        rows.push(await reconcileContent(deps, def, pageSize));
+        continue;
+      } catch (err) {
+        if (err instanceof CliError) throw err;
+        deps.io.stderr(
+          `Could not read the documents of "${def.name}", comparing ids only: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    const source = await indexableSourceIds(deps.adapter, def, pageSize);
+    let remoteKeys = null;
     let remoteCount = -1;
-    try {
-      const stats = await deps.getStats(def.name);
-      remoteCount = stats.numDocuments ?? 0;
-    } catch (err) {
-      deps.io.stderr(
-        `Could not fetch stats for "${def.name}": ${err instanceof Error ? err.message : String(err)}`
-      );
+    if (deps.listRemoteIds) {
+      try {
+        remoteKeys = new Set((await deps.listRemoteIds(def.name, def.primaryKey)).map(String));
+        remoteCount = remoteKeys.size;
+      } catch (err) {
+        deps.io.stderr(
+          `Could not list the documents of "${def.name}", comparing counts only: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
     }
-    const cursorAware = Boolean(ormSchema.models[def.source]?.columns?.updatedAt);
-    const drift = remoteCount === -1 ? 0 : sourceCount - remoteCount;
-    rows.push({ index: def.name, sourceCount, remoteCount, drift, cursorAware });
-    if (deps.fix && drift !== 0) {
-      const docs = await deps.adapter.resolveDocs(def.name, ids);
-      const toPush = docs.filter((doc) => {
-        const sourceRow = doc.__source ?? doc;
-        return !def.shouldIndex || def.shouldIndex(sourceRow);
-      });
-      for (const doc of toPush) delete doc.__source;
-      if (toPush.length > 0) {
-        const result = await deps.client.bulkPush(def.name, toPush, def.primaryKey);
-        if (result?.partialFailure) {
-          throw new CliError(
-            `Repair push for "${def.name}" was incomplete: ${partialFailureSummary(result.partialFailure)}.`
+    if (remoteKeys === null) {
+      try {
+        const stats = await deps.getStats(def.name);
+        remoteCount = stats.numberOfDocuments ?? stats.numDocuments ?? -1;
+      } catch (err) {
+        deps.io.stderr(
+          `Could not fetch stats for "${def.name}": ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    const row = {
+      index: def.name,
+      sourceCount: source.size,
+      remoteCount,
+      missing: null,
+      extra: null,
+      drift: remoteCount === -1 ? 0 : Math.abs(source.size - remoteCount),
+      fixed: false
+    };
+    let missingIds = [];
+    let extraIds = [];
+    if (remoteKeys) {
+      const remote = remoteKeys;
+      missingIds = [...source].filter(([key]) => !remote.has(key)).map(([, id]) => id);
+      extraIds = [...remote].filter((key) => !source.has(key));
+      row.missing = missingIds.length;
+      row.extra = extraIds.length;
+      row.drift = missingIds.length + extraIds.length;
+    }
+    if (deps.fix && row.drift !== 0) {
+      if (remoteKeys) {
+        await pushSourceRows(deps, def, missingIds, pageSize);
+        for (let offset = 0; offset < extraIds.length; offset += pageSize) {
+          const result = await deps.client.deleteDocs(
+            def.name,
+            extraIds.slice(offset, offset + pageSize)
           );
+          if (result?.partialFailure) {
+            throw new CliError(
+              `Removing extra documents from "${def.name}" was incomplete: ${partialFailureSummary(result.partialFailure)}.`
+            );
+          }
         }
+      } else {
+        await pushSourceRows(deps, def, [...source.values()], pageSize);
       }
+      row.fixed = true;
     }
+    rows.push(row);
   }
+  const contentCompared = rows.some((r) => r.stale !== void 0 && r.stale !== null);
   printTable(
     deps.io,
-    rows.map((r) => ({ ...r, remoteCount: r.remoteCount === -1 ? "unknown" : r.remoteCount })),
-    ["index", "sourceCount", "remoteCount", "drift", "cursorAware"]
+    rows.map((r) => ({
+      ...r,
+      remoteCount: r.remoteCount === -1 ? "unknown" : r.remoteCount,
+      missing: r.missing ?? "",
+      extra: r.extra ?? "",
+      stale: r.stale ?? "",
+      fixed: r.fixed ? "yes" : ""
+    })),
+    contentCompared ? ["index", "sourceCount", "remoteCount", "missing", "extra", "stale", "drift", "fixed"] : ["index", "sourceCount", "remoteCount", "missing", "extra", "drift", "fixed"]
   );
+  const unfixed = rows.filter((r) => r.drift !== 0 && !r.fixed);
+  if (unfixed.length > 0 && !deps.fix) {
+    deps.io.stderr("Drift found. Run again with --fix to repair it.");
+  }
   return rows;
 }
+function reconcileHasDrift(rows) {
+  return rows.some((r) => r.remoteCount === -1 || r.drift !== 0 && !r.fixed);
+}
 async function runSyncRetryDeadLetters(deps) {
   const rows = await deps.outbox.deadLetters(deps.limit ?? DEFAULT_DEAD_LETTER_LIMIT);
   if (rows.length === 0) {
@@ -2367,23 +3966,238 @@ async function runSyncRetryDeadLetters(deps) {
   deps.io.stdout(`Requeued ${rows.length} dead-lettered row(s).`);
   return rows.length;
 }
+async function runSelfHostedSyncStatus(deps) {
+  const now = deps.now ?? Date.now;
+  const table = deps.config.sync?.outboxTable ?? DEFAULT_OUTBOX_TABLE;
+  const mode = deps.config.sync?.mode ?? "outbox";
+  let outbox = null;
+  if (deps.outbox) {
+    const stats = deps.outbox.stats ? await deps.outbox.stats() : { pending: await deps.outbox.depth(), deadLetter: -1, oldestPendingAt: null };
+    outbox = {
+      ...stats,
+      oldestPendingAgeSeconds: stats.oldestPendingAt ? Math.max(0, Math.round((now() - stats.oldestPendingAt.getTime()) / 1e3)) : null
+    };
+  }
+  const status = {
+    config: deps.configPath,
+    outboxTable: table,
+    mode,
+    indexes: deps.config.indexes.map((def) => def.name),
+    outbox
+  };
+  const { io } = deps;
+  io.stdout(`Self-hosted sync (${deps.configPath}), ${mode} mode`);
+  io.stdout(`Indexes: ${status.indexes.join(", ") || "none"}`);
+  if (!outbox) {
+    io.stdout("Outbox: not checked. Set DATABASE_URL to see its depth and dead letters.");
+  } else {
+    printTable(
+      io,
+      [
+        {
+          table,
+          pending: outbox.pending,
+          deadLetters: outbox.deadLetter === -1 ? "unknown" : outbox.deadLetter,
+          oldestPending: outbox.oldestPendingAgeSeconds === null ? "" : `${outbox.oldestPendingAgeSeconds}s ago`
+        }
+      ],
+      ["table", "pending", "deadLetters", "oldestPending"]
+    );
+    if (outbox.deadLetter > 0) {
+      io.stdout(
+        `${outbox.deadLetter} row(s) are dead letters. Their last error is in the last_error column. Requeue them with: headband sync retry-dead-letters`
+      );
+    }
+  }
+  io.stdout("Managed Sync (replication slots) has its own commands: headband sync source list");
+  return status;
+}
 function runSyncScaffoldDocker(deps) {
-  const path2 = (0, import_path8.join)(deps.cwd, DOCKERFILE_NAME);
-  if ((0, import_fs7.existsSync)(path2) && !deps.force) {
+  const path2 = (0, import_path10.join)(deps.cwd, DOCKERFILE_NAME);
+  if ((0, import_fs8.existsSync)(path2) && !deps.force) {
     throw new CliError(`${DOCKERFILE_NAME} already exists at ${path2}. Pass --force to overwrite.`);
   }
-  (0, import_fs7.writeFileSync)(path2, DOCKERFILE_CONTENT);
+  (0, import_fs8.writeFileSync)(path2, dockerfileContent(deps.cliVersion));
   deps.io.stdout(`Wrote ${path2}`);
   deps.io.stdout("Add this service to your docker-compose.yml:");
   deps.io.stdout(COMPOSE_SNIPPET);
+  deps.io.stdout(
+    "Set DATABASE_URL (the database with your tables and the outbox) and HEADBAND_API_KEY (an admin key that reaches your indexes) where the container runs."
+  );
   return path2;
 }
 
+// src/help.ts
+var CONFIG_NOTE = [
+  "These commands read headband.config.ts in the current directory:",
+  "  export default defineConfig({ url, projectId?, indexes: [...], sync? })   (@headband/sync)",
+  "  export const adapter = drizzleAdapter({ db, schema, config })           (@headband/drizzle)",
+  "The adapter is needed by apply, worker and reconcile; diff, generate and status run without it.",
+  "When the adapter is there, the config is checked against your tables before anything runs.",
+  "The Headband URL is --url, else HEADBAND_URL, else the config's url, else your login's."
+].join("\n");
+var KEY_NOTE = [
+  "Key: your login (headband login) or HEADBAND_API_KEY. The login key is org-wide, so new",
+  "indexes go to the project named by --project <id> or the config's projectId; without one",
+  "they go to your org's Default project. Your app's own project admin key reaches only",
+  "indexes in its project, so name that project here."
+].join("\n");
+var schemaDiff = [
+  "Usage: headband schema diff [--allow-destructive] [--json]",
+  "",
+  "Compares the indexes in headband.config.ts with the schema state Headband has recorded,",
+  "and prints the operations a migration would run: create-index, patch-settings, reindex,",
+  "and with --allow-destructive, remove-index. Changes nothing. Exits 1 when changes are",
+  "pending, like git diff --exit-code, so CI can fail on an unapplied change."
+].join("\n");
+var schemaGenerate = [
+  "Usage: headband schema generate [--slug <slug>] [--dir <dir>] [--allow-destructive] [--json]",
+  "",
+  "Writes the pending operations to a numbered migration file in --dir",
+  "(default headband/migrations), for review and for git. Changes nothing on the server."
+].join("\n");
+var schemaApply = [
+  "Usage: headband schema apply [--project <id>] [--allow-destructive] [--dir <dir>] [--yes] [--json]",
+  "",
+  "Runs the migration files in --dir (default headband/migrations) that the server does not",
+  "have yet. A new index is created, given its settings, and backfilled from every source row",
+  "(rows shouldIndex rejects are left out). A schema change builds a new index beside the",
+  "live one, backfills it, then switches the name over. Settings changes apply in place.",
+  "",
+  "Applied migrations are recognised from the server's state, so a fresh checkout or CI can",
+  "apply without the local headband/migrations/.applied.json (a cache you may commit or ignore).",
+  "Needs the adapter export and DATABASE_URL (the database your adapter reads). Asks first;",
+  "--yes confirms without a terminal.",
+  "",
+  KEY_NOTE
+].join("\n");
+var schemaStatus = [
+  "Usage: headband schema status [--dir <dir>] [--json]",
+  "",
+  "Per index in headband.config.ts: the applied version and status on the server, and drift",
+  "(schema, settings, none, missing, or index missing when the index was deleted). Also how",
+  "many local migration files are applied."
+].join("\n");
+var schemaForget = [
+  "Usage: headband schema forget <index> [--yes] [--json]",
+  "",
+  "Removes the schema state Headband recorded for <index>, for an index deleted outside",
+  "schema apply (headband indexes delete clears it for you). Does not touch any index. The",
+  "next schema generate plans the index as new."
+].join("\n");
+var syncInit = [
+  "Usage: headband sync init [--table <name>] [--write] [--apply] [--json]",
+  "",
+  "Prints the SQL for the outbox table (default headband_outbox) that outbox mode writes",
+  "changes to. --write saves it to headband/outbox.sql. --apply runs it against DATABASE_URL",
+  "(CREATE TABLE IF NOT EXISTS, safe to re-run). Or add the SQL to your own migrations."
+].join("\n");
+var syncWorker = [
+  "Usage:",
+  "  headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--project <id>] [--json]",
+  "  headband sync worker --scaffold docker [--force] [--json]",
+  "",
+  "Drains the outbox table: resolves each changed row through the adapter and writes the",
+  "documents to Headband. By default it runs until stopped (Ctrl+C finishes the current",
+  "batch), so --loop changes nothing on its own. --budget-ms <ms> is for cron: the worker",
+  "stops claiming after that long, and exits early once the outbox is empty; add --loop to",
+  "keep waiting for changes until the budget ends. Each batch prints one line to stderr",
+  "(rows drained, pushed, deleted), and the run ends with a summary on stdout.",
+  "--reconcile-every <n> runs sync reconcile after",
+  "every n-th batch. A row that keeps failing goes to the dead letters (see sync status and",
+  "sync retry-dead-letters), with its error printed; one bad row never fails its batch.",
+  "Each run is recorded under the connector orm-sync (GET /v1/connectors/runs).",
+  "",
+  "Needs the adapter export, DATABASE_URL (the database with your tables and the outbox), and",
+  "a key that can write documents. A login key records runs only with --project or projectId.",
+  "",
+  "--scaffold docker writes Dockerfile.headband-sync, which runs this worker by its full",
+  "package name, and prints a docker-compose service."
+].join("\n");
+var syncReconcile = [
+  "Usage: headband sync reconcile [--content] [--fix] [--json]",
+  "",
+  "Per index, compares the source rows that belong in it (every row shouldIndex keeps) with",
+  "the documents in it, and prints how many documents are missing and how many are extra",
+  "(counts, not ids; --json gives the same counts). --fix pushes the missing ones and deletes",
+  "the extra ones. Exits 1 when drift is left. --content also compares every document with its",
+  "freshly resolved source row and counts the stale ones; with --fix it rewrites them. It reads",
+  "the whole index, so it takes about as long as a backfill.",
+  "Needs the adapter export and DATABASE_URL."
+].join("\n");
+var syncRetry = [
+  "Usage: headband sync retry-dead-letters [--json]",
+  "",
+  "Moves the outbox rows in dead_letter back to pending, so the next worker run tries them",
+  "again. Fix what failed them first: their error is in the outbox table's last_error column,",
+  "and the worker printed it. Needs DATABASE_URL."
+].join("\n");
+var syncStatus = [
+  "Usage: headband sync status [--json]",
+  "",
+  "Beside a headband.config.ts: the outbox's pending rows, dead letters and oldest pending",
+  "row (needs DATABASE_URL). Elsewhere: managed Sync's sources and synced indexes."
+].join("\n");
+var SUBCOMMAND_HELP = {
+  schema: [
+    "Usage:",
+    "  headband schema diff [--allow-destructive] [--json]",
+    "  headband schema generate [--slug <slug>] [--dir <dir>] [--allow-destructive] [--json]",
+    "  headband schema apply [--project <id>] [--allow-destructive] [--dir <dir>] [--yes] [--json]",
+    "  headband schema status [--dir <dir>] [--json]",
+    "  headband schema forget <index> [--yes] [--json]",
+    "",
+    "Versioned index schema for self-hosted sync. headband schema <command> --help says more.",
+    "",
+    CONFIG_NOTE
+  ].join("\n"),
+  sync: [
+    "Usage:",
+    "  Self-hosted sync with @headband/sync:",
+    "  headband sync init [--table <name>] [--write] [--apply] [--json]",
+    "  headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--project <id>] [--json]",
+    "  headband sync worker --scaffold docker [--force] [--json]",
+    "  headband sync reconcile [--content] [--fix] [--json]",
+    "  headband sync retry-dead-letters [--json]",
+    "  headband sync status [--json]",
+    "",
+    "  Managed Sync (replication slots, early access):",
+    "  headband sync source add|list|show|test|setup|setup-sql|set-ca|remove (see headband sync source --help)",
+    "  headband sync index create|list|show|update|validate|preview|rebuild|pause|resume|check|remove (see headband sync index --help)",
+    "",
+    "headband sync <command> --help says more.",
+    "",
+    CONFIG_NOTE
+  ].join("\n"),
+  "schema diff": `${schemaDiff}
+
+${CONFIG_NOTE}`,
+  "schema generate": `${schemaGenerate}
+
+${CONFIG_NOTE}`,
+  "schema apply": `${schemaApply}
+
+${CONFIG_NOTE}`,
+  "schema status": `${schemaStatus}
+
+${CONFIG_NOTE}`,
+  "schema forget": schemaForget,
+  "sync init": syncInit,
+  "sync worker": `${syncWorker}
+
+${CONFIG_NOTE}`,
+  "sync reconcile": `${syncReconcile}
+
+${CONFIG_NOTE}`,
+  "sync retry-dead-letters": syncRetry,
+  "sync status": syncStatus
+};
+
 // src/sync-indexes.ts
-var import_fs9 = require("fs");
+var import_fs10 = require("fs");
 
 // src/sync-sources.ts
-var import_fs8 = require("fs");
+var import_fs9 = require("fs");
 var import_pg2 = require("pg");
 
 // ../../src/lib/sync/copy.ts
@@ -2450,7 +4264,7 @@ var SOURCE_USAGE = [
 function readCaFile(deps, file) {
   let text;
   try {
-    text = (deps.readFile ?? ((p) => (0, import_fs8.readFileSync)(p, "utf8")))(file);
+    text = (deps.readFile ?? ((p) => (0, import_fs9.readFileSync)(p, "utf8")))(file);
   } catch {
     throw new CliError("Cannot read the --ca-file.");
   }
@@ -2621,10 +4435,11 @@ async function runOwnerSqlWithPg(ownerUrl, sqlText) {
 function friendlySyncError(err) {
   if (err instanceof ApiError) {
     if (err.status === 404 && err.code === "not_found") {
-      throw new CliError("Sync is not enabled for this organization yet.");
+      throw restate(err, "Sync is not enabled for this organization yet.");
     }
     if (err.status === 403 && err.code === "permission_denied") {
-      throw new CliError(
+      throw restate(
+        err,
         "This CLI key cannot manage Sync. Run headband login again to get a key that can."
       );
     }
@@ -3090,7 +4905,7 @@ var PREVIEW_MAX_IDS = 20;
 var ATTENTION_INDEX = /* @__PURE__ */ new Set(["error", "needs_rebuild", "awaiting_setup", "degraded"]);
 var ATTENTION_SOURCE = /* @__PURE__ */ new Set(["error", "awaiting_setup"]);
 var path = (id, suffix = "") => `/v1/sync/indexes/${encodeURIComponent(id)}${suffix}`;
-function readDefinition(file, readFile = (p) => (0, import_fs9.readFileSync)(p, "utf8")) {
+function readDefinition(file, readFile = (p) => (0, import_fs10.readFileSync)(p, "utf8")) {
   let text;
   try {
     text = readFile(file);
@@ -3458,6 +5273,7 @@ async function askWithPrompts(message) {
 var ENGINES2 = /* @__PURE__ */ new Set(["meilisearch", "typesense", "elasticsearch", "visor"]);
 var KEY_TYPES = /* @__PURE__ */ new Set(["admin", "search"]);
 var EXPORT_FORMATS = /* @__PURE__ */ new Set(["jsonl", "json"]);
+var SEARCH_MODES = /* @__PURE__ */ new Set(["instant", "retrieval"]);
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--url",
   "--token",
@@ -3485,6 +5301,8 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--idle-timeout",
   "--client",
   "--instance",
+  "--instances",
+  "--indexes",
   "--db-url",
   "--owner-url",
   "--tls-mode",
@@ -3502,7 +5320,14 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--format",
   "--batch",
   "--permissions",
-  "--expires"
+  "--expires",
+  "--branch",
+  "--parent",
+  "--expires-in",
+  "--in",
+  "--at",
+  "--level",
+  "--mode"
 ]);
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--json",
@@ -3514,12 +5339,21 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--write",
   "--force",
   "--fix",
+  "--content",
   "--loop",
   "--accept-broad-role",
   "--rebuild",
   "--drop-index",
   "--none",
-  "--no-revoke"
+  "--no-revoke",
+  "--empty",
+  "--clear",
+  "--apply",
+  "--accept-drops",
+  "--declare-key",
+  "--dry-run",
+  "--wait",
+  "--status"
 ]);
 var DEFAULT_MIGRATIONS_DIR = "headband/migrations";
 function parseArgv(argv) {
@@ -3553,7 +5387,7 @@ function parseArgv(argv) {
   }
   return { flags, positional };
 }
-function stringFlag(flags, name) {
+function stringFlag3(flags, name) {
   const value = flags[name];
   return typeof value === "string" ? value : void 0;
 }
@@ -3561,7 +5395,7 @@ function boolFlag(flags, name) {
   return flags[name] === true;
 }
 function requiredFlag(flags, name) {
-  const value = stringFlag(flags, name);
+  const value = stringFlag3(flags, name);
   if (!value) throw new UsageError(`Missing required option: ${name}`);
   return value;
 }
@@ -3570,7 +5404,7 @@ function requiredArg(value, what) {
   return value;
 }
 function parseLimit(flags) {
-  const raw = stringFlag(flags, "--limit");
+  const raw = stringFlag3(flags, "--limit");
   if (!raw) return void 0;
   const limit = Number(raw);
   if (!Number.isInteger(limit) || limit <= 0) {
@@ -3596,17 +5430,34 @@ function encode(value) {
 function chatterIO(io, flags) {
   return boolFlag(flags, "--json") ? { stdout: io.stderr, stderr: io.stderr } : io;
 }
-function authFromFlags(flags) {
-  return resolveAuth({
-    token: stringFlag(flags, "--token"),
-    url: stringFlag(flags, "--url"),
-    profile: stringFlag(flags, "--profile")
+function authFromFlags(flags, defaults = {}) {
+  const profile = stringFlag3(flags, "--profile");
+  const url = stringFlag3(flags, "--url") ?? (process.env.HEADBAND_URL || profile || process.env.HEADBAND_PROFILE ? void 0 : defaults.url);
+  return resolveAuth({ token: stringFlag3(flags, "--token"), url, profile });
+}
+function branchHeaders(flags, cwd, auth, options = {}) {
+  const branch = branchHeaderFor(flags, cwd, { ...options, loginOrgId: auth.profile?.orgId });
+  return branch ? { "Headband-Branch": branch } : void 0;
+}
+function clientFromFlags(flags, cwd, options = {}) {
+  const auth = authFromFlags(flags, { url: options.defaultUrl });
+  const headers = branchHeaders(flags, cwd, auth, options);
+  return createApiClient(auth.url, { apiKey: auth.apiKey, headers });
+}
+function syncClientFromFlags(flags, cwd, options = {}) {
+  const auth = authFromFlags(flags, { url: options.defaultUrl });
+  const headers = branchHeaders(flags, cwd, auth, options);
+  const fetchImpl = headers ? (input, init2) => {
+    const merged = new Headers(init2?.headers);
+    for (const [name, value] of Object.entries(headers)) merged.set(name, value);
+    return fetch(input, { ...init2, headers: merged });
+  } : void 0;
+  return new HeadbandClient({
+    url: auth.url,
+    adminKey: auth.apiKey,
+    ...fetchImpl ? { fetchImpl } : {}
   });
 }
-function clientFromFlags(flags) {
-  const auth = authFromFlags(flags);
-  return createApiClient(auth.url, { apiKey: auth.apiKey });
-}
 function stdinIsInteractive() {
   return process.stdin.isTTY === true;
 }
@@ -3643,16 +5494,24 @@ Commands:
   profiles use <name>
   projects list [--json]
   projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]
-  projects delete <id> [--force] [--yes] [--json]
+  projects delete <id> [--yes] [--json]
+  branch list [--project <id>] [--json]
+  branch create <name> --empty [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]
+  branch delete <name> [--project <id>] [--yes] [--json]
+  branch protect|unprotect <name> [--project <id>] [--json]
+  branch expire <name> (--in <2h|7d> | --at <iso> | --clear) [--project <id>] [--json]
+  branch checkout <name> [--project <id>] [--json]
+  branch reset|rollback|restore|set-primary (coming with bucket storage)
   keys list [--json]
-  keys create <name> --type <admin|search> [--project <id>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]
+  keys create <name> --type <admin|search> [--project <id>] [--branch <name>] [--instances <id,id>] [--indexes <uid,uid>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]
   keys revoke <id> [--yes] [--json]
-  indexes list [--json]
+  indexes list [--json]                      (index works in place of indexes)
   indexes create <uid> [--primary-key <pk>] [--engine <engine>] [--instance <id>] [--json]
   indexes delete <uid> [--yes] [--json]
   indexes settings get <uid> [--json]
   indexes settings set <uid> --file <settings.json> [--json]
   indexes stats <uid> [--json]
+  indexes switch-engine <uid> --engine <engine> [--accept-drops] [--dry-run] [--wait] [--json]
   instances list [--json]
   instances create <engine> [--name <name>] [--lane <lane>] [--memory <size>] [--region <region>] [--idle-timeout <s>] [--json]
   instances update <id> [--name <name>] [--lane <lane>] [--memory <size>] [--idle-timeout <s>] [--json]
@@ -3660,29 +5519,39 @@ Commands:
   instances wakes <id> [--limit <n>] [--json]
   instances delete <id> [--yes] [--json]
   instances connect <id> [--client <node|curl>] [--json]
+  warm <index>... | --project <id> [--branch <name>] [--level auto|stage|start] [--json]
   docs push <file> --index <uid> [--json]
-  docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>]
-  docs delete <docId> --index <uid> [--json]
-  search <index> <query> [--limit N] [--filter <expr>] [--json]
-  tasks list [--json]
-  tasks get <id> [--json]
+  docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>] [--declare-key]
+  docs delete <docId>... --index <uid> [--json]
+  search <index> [<query>] [--limit N] [--filter <expr>] [--mode <instant|retrieval>] [--json]
+  tasks list [--index <uid>] [--limit <n>] [--json]
+  tasks get <id> [--index <uid>] [--json]
+
+  Self-hosted sync with @headband/sync (reads headband.config.ts; see headband schema --help):
   schema diff [--allow-destructive] [--json]
   schema generate [--slug <slug>] [--dir <dir>] [--allow-destructive] [--json]
-  schema apply [--allow-destructive] [--dir <dir>] [--yes] [--json]
+  schema apply [--project <id>] [--allow-destructive] [--dir <dir>] [--yes] [--json]
   schema status [--dir <dir>] [--json]
-  sync init [--table <name>] [--write] [--json]
-  sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--json]
+  schema forget <index> [--yes] [--json]
+  sync init [--table <name>] [--write] [--apply] [--json]
+  sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--project <id>] [--json]
   sync worker --scaffold docker [--force] [--json]
-  sync reconcile [--fix] [--json]
+  sync reconcile [--content] [--fix] [--json]
   sync retry-dead-letters [--json]
+  sync status [--json]
+
+  Managed Sync (replication slots, early access):
   sync source add|list|show|test|setup|setup-sql|set-ca|remove (see headband sync source --help)
   sync index create|list|show|update|validate|preview|rebuild|pause|resume|check|remove (see headband sync index --help)
-  sync status [--json]
 
 Global options:
   --token <key>      API key for this call. Wins over HEADBAND_API_KEY and stored logins.
   --profile <name>   Stored login to use (else HEADBAND_PROFILE, else the current profile)
   --url <url>        Headband URL (else HEADBAND_URL, else the profile's, else ${DEFAULT_URL})
+  --branch <name>    Work on this branch for one call: sends Headband-Branch: <project>/<name>,
+                     with the project from --project <id>, else the checkout's
+                     (headband branch checkout). A branch id (br_...) is sent as it is.
+                     Without --branch or a checkout, calls reach the primary branches.
   --json             Print one JSON document on stdout; errors print one JSON object on stderr
   --yes              Answer yes to confirmations (required when stdin is not a terminal)
   --help             Show help
@@ -3697,8 +5566,21 @@ function printCommandHelp(command, io) {
     logout: "Usage: headband logout [--profile <name>] [--yes] [--no-revoke] [--json]",
     whoami: "Usage: headband whoami [--json]",
     profiles: "Usage:\n  headband profiles list [--json]\n  headband profiles use <name>",
-    projects: "Usage:\n  headband projects list [--json]\n  headband projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]\n  headband projects delete <id> [--force] [--yes] [--json]\n\n  delete refuses a project that still has indexes; --force deletes its indexes with it.",
-    keys: "Usage:\n  headband keys list [--json]\n  headband keys create <name> --type <admin|search> [--project <id>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]\n  headband keys revoke <id> [--yes] [--json]",
+    projects: "Usage:\n  headband projects list [--json]\n  headband projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]\n  headband projects delete <id> [--yes] [--json]\n\n  delete refuses a project that still has indexes. Delete its indexes first.",
+    branch: BRANCH_USAGE,
+    branches: BRANCH_USAGE,
+    keys: [
+      "Usage:",
+      "  headband keys list [--json]",
+      "  headband keys create <name> --type <admin|search> [--project <id>] [--branch <name>] [--instances <id,id>] [--indexes <uid,uid>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]",
+      "  headband keys revoke <id> [--yes] [--json]",
+      "",
+      "keys create mints a key for one branch: --branch (with --project, else the checkout's project),",
+      "else the checked-out branch, else the --project's primary branch. With none of these,",
+      "--type admin mints an org key, and --type search is refused: a search key needs a branch.",
+      "--instances <id,id> limits the key to those dedicated engines (on a branch: its engines among them).",
+      "--indexes <uid,uid> limits a search key to those indexes; any other index answers 404."
+    ].join("\n"),
     indexes: [
       "Usage:",
       "  headband indexes list [--json]",
@@ -3707,24 +5589,73 @@ function printCommandHelp(command, io) {
       "  headband indexes settings get <uid> [--json]",
       "  headband indexes settings set <uid> --file <settings.json> [--json]",
       "  headband indexes stats <uid> [--json]",
+      "  headband indexes switch-engine <uid> --engine <engine> [--instance <id>] [--accept-drops] [--declare-key] [--dry-run] [--wait] [--json]",
+      "  headband indexes switch-engine <uid> --status [--json]",
+      "",
+      "index is an alias: headband index switch-engine <uid> is the same command.",
       "",
       "Options for create:",
       "  --instance <id>  Create the index on one of your dedicated engines (ids from headband instances list).",
-      "                   The index takes that engine's type; --engine, if given, must match it."
+      "                   The index takes that engine's type; --engine, if given, must match it.",
+      "",
+      "Options for switch-engine (moves the index to another engine; its uid, keys and URLs stay):",
+      "  --dry-run        Show what would be copied and which settings would not carry over. Changes nothing.",
+      "  --accept-drops   Switch even though some settings will not apply on the new engine.",
+      "  --declare-key    Visor over 1000 documents: declare the primary key while it is read (rebuilds it).",
+      "  --instance <id>  Put the index on that engine of the branch instead of the branch's default.",
+      "  --wait           Follow the switch until it ends. Writes are held for about a minute at the end.",
+      "  --status         Show the index's engine and its latest switch."
     ].join("\n"),
     instances: INSTANCES_USAGE,
-    docs: "Usage:\n  headband docs push <file> --index <uid> [--json]\n  headband docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>] [--json]\n  headband docs delete <docId> --index <uid> [--json]",
-    search: "Usage: headband search <index> <query> [--limit N] [--filter <expr>] [--json]",
-    tasks: "Usage:\n  headband tasks list [--json]\n  headband tasks get <id> [--json]",
-    schema: "Usage:\n  headband schema diff [--allow-destructive] [--json]\n  headband schema generate [--slug <slug>] [--dir <dir>] [--allow-destructive] [--json]\n  headband schema apply [--allow-destructive] [--dir <dir>] [--yes] [--json]\n  headband schema status [--dir <dir>] [--json]",
-    sync: "Usage:\n  headband sync init [--table <name>] [--write] [--json]\n  headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--json]\n  headband sync worker --scaffold docker [--force] [--json]\n  headband sync reconcile [--fix] [--json]\n  headband sync retry-dead-letters [--json]\n  headband sync source add|list|show|test|setup|setup-sql|set-ca|remove (see headband sync source --help)\n  headband sync index create|list|show|update|validate|preview|rebuild|pause|resume|check|remove (see headband sync index --help)\n  headband sync status [--json]"
+    warm: WARM_USAGE,
+    docs: [
+      "Usage:",
+      "  headband docs push <file> --index <uid> [--json]",
+      "  headband docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>] [--declare-key] [--json]",
+      "  headband docs delete <docId>... --index <uid> [--json]",
+      "",
+      "docs push sends the documents in a .json (an array) or .jsonl file, 1000 at a time.",
+      "",
+      "docs export writes every document of the index:",
+      "  without --out    JSONL to stdout, one document per line, and nothing else.",
+      "  --out <file>     to a file. The format follows the extension (.json is one array,",
+      "                   anything else JSONL) unless --format says otherwise.",
+      "  --batch <n>      documents per request. Default 1000, or 250 on Typesense.",
+      "  --declare-key    a Visor index past 1000 documents whose primary key is not",
+      "                   filterable and sortable (made before 2026-10-21): declare the",
+      "                   key on it first (Visor rebuilds the index), wait, then export.",
+      "  If the export stops on an error, the documents written so far are kept in",
+      "  <file>.partial, and <file> is not written.",
+      "",
+      "docs delete removes the documents with these ids (one or more) from the index."
+    ].join("\n"),
+    search: [
+      "Usage: headband search <index> [<query>] [--limit N] [--filter <expr>] [--mode <instant|retrieval>] [--json]",
+      "",
+      'Without a query (or with ""), search browses the index: every document matches, so',
+      "--filter and --limit pick what comes back.",
+      "",
+      "--mode picks Visor's ranking: instant (the default, typo-tolerant, as-you-type) or retrieval",
+      "(BM25F, for longer queries). Indexes on the other engines ignore it."
+    ].join("\n"),
+    tasks: [
+      "Usage:",
+      "  headband tasks list [--index <uid>] [--limit <n>] [--json]",
+      "  headband tasks get <id> [--index <uid>] [--json]",
+      "",
+      "Tasks live on the engine that holds the index. With the key headband login creates (an",
+      "org key), or on a branch other than main, pass --index so Headband knows which",
+      "engine to ask. A project key of the main branch may leave it out."
+    ].join("\n"),
+    schema: SUBCOMMAND_HELP.schema,
+    sync: SUBCOMMAND_HELP.sync
   };
-  io.stdout(help[command] || "");
+  io.stdout(help[command === "index" ? "indexes" : command] || "");
 }
 async function runLogin(flags, io) {
-  const url = stringFlag(flags, "--url") || process.env.HEADBAND_URL || DEFAULT_URL;
+  const url = stringFlag3(flags, "--url") || process.env.HEADBAND_URL || DEFAULT_URL;
   const result = await login(url, chatterIO(io, flags), {
-    profileName: stringFlag(flags, "--profile")
+    profileName: stringFlag3(flags, "--profile")
   });
   if (boolFlag(flags, "--json")) printJson(io, result);
 }
@@ -3732,8 +5663,8 @@ async function runLogout(flags, io, confirm) {
   const json = boolFlag(flags, "--json");
   const chatter = chatterIO(io, flags);
   const selected = selectProfile({
-    url: stringFlag(flags, "--url"),
-    profile: stringFlag(flags, "--profile")
+    url: stringFlag3(flags, "--url"),
+    profile: stringFlag3(flags, "--profile")
   });
   if (!selected) {
     throw new AuthError("No stored login to log out of. Run: headband profiles list");
@@ -3775,7 +5706,7 @@ async function runWhoami(flags, io) {
     profile: auth.profileName ?? null,
     orgName: auth.profile?.orgName ?? null,
     orgId: auth.profile?.orgId ?? null,
-    keyPrefix: auth.profile?.keyPrefix ?? auth.apiKey.slice(0, 12),
+    keyPrefix: auth.profile?.keyPrefix ?? displayPrefixOf(auth.apiKey),
     keyId: auth.profile?.keyId ?? null,
     valid: true
   };
@@ -3827,9 +5758,9 @@ async function runProfiles(args, flags, io) {
   printCommandHelp("profiles", io);
   throw new UsageError("Unknown profiles command");
 }
-async function runProjects(args, flags, io, confirm) {
+async function runProjects(args, flags, io, confirm, cwd) {
   const action = args[0];
-  const client = clientFromFlags(flags);
+  const client = clientFromFlags(flags, cwd);
   if (action === "list") {
     const response = await client.get(
       "/v1/projects"
@@ -3854,10 +5785,8 @@ async function runProjects(args, flags, io, confirm) {
   }
   if (action === "delete") {
     const id = requiredArg(args[1], "project id");
-    const force = boolFlag(flags, "--force");
-    const question = force ? `Delete project ${id} and every index in it?` : `Delete project ${id}?`;
-    if (!await confirm(question)) return cancelled(io, flags);
-    const response = await client.delete(`/v1/projects/${encode(id)}${force ? "?force=true" : ""}`);
+    if (!await confirm(`Delete project ${id}?`)) return cancelled(io, flags);
+    const response = await client.delete(`/v1/projects/${encode(id)}`);
     if (boolFlag(flags, "--json")) printJson(io, response);
     else io.stdout(`Deleted project ${id}.`);
     return;
@@ -3903,19 +5832,73 @@ function parsePermissions(raw) {
   }
   return permissions;
 }
-async function runKeys(args, flags, io, confirm) {
+function keyRow(key) {
+  const branch = key.branch;
+  return {
+    ...key,
+    branch: branch?.name ?? "",
+    engines: enginesColumn(key.instanceIds),
+    indexes: enginesColumn(key.indexUids)
+  };
+}
+function enginesColumn(instanceIds) {
+  if (instanceIds === null) return "all";
+  if (instanceIds === void 0) return "unknown";
+  if (Array.isArray(instanceIds) && instanceIds.every((id) => typeof id === "string")) {
+    const printable = instanceIds.filter((id) => id.trim() !== "");
+    return printable.length > 0 ? printable.join(",") : "none";
+  }
+  return "none";
+}
+function parseIndexList(raw) {
+  const uids = [
+    ...new Set(
+      raw.split(",").map((x) => x.trim()).filter(Boolean)
+    )
+  ];
+  if (uids.length === 0) throw new CliError("--indexes needs at least one index uid.");
+  const bad = uids.find((uid) => !/^[A-Za-z0-9_-]{1,64}$/.test(uid));
+  if (bad) {
+    throw new CliError(
+      `Not an index uid: ${bad}. Index uids are letters, numbers, hyphens and underscores.`
+    );
+  }
+  return uids;
+}
+function parseInstanceList(raw) {
+  const ids = [
+    ...new Set(
+      raw.split(",").map((x) => x.trim()).filter(Boolean)
+    )
+  ];
+  if (ids.length === 0) {
+    throw new CliError("--instances needs at least one engine id (see `headband instances list`).");
+  }
+  const bad = ids.find((id) => !INSTANCE_ID_RE.test(id));
+  if (bad) {
+    throw new CliError(
+      `Not an engine id: ${bad}. Engine ids look like iabcdef012345 (see \`headband instances list\`).`
+    );
+  }
+  return ids;
+}
+async function runKeys(args, flags, io, confirm, cwd) {
   const action = args[0];
-  const client = clientFromFlags(flags);
+  const client = clientFromFlags(flags, cwd, { projectInBody: action === "create" });
   if (action === "list") {
     const response = await client.get("/v1/keys");
     if (boolFlag(flags, "--json")) printJson(io, response);
     else
-      printTable(io, response.data.keys, [
+      printTable(io, response.data.keys.map(keyRow), [
         "id",
         "name",
         "type",
         "keyPrefix",
         "projectId",
+        "branch",
+        "engines",
+        "indexes",
+        "environment",
         "lastUsedAt",
         "expiresAt"
       ]);
@@ -3927,20 +5910,66 @@ async function runKeys(args, flags, io, confirm) {
       name,
       type: validateKeyType(requiredFlag(flags, "--type"))
     };
-    const projectId = stringFlag(flags, "--project");
+    const target = branchTargetFor(flags, cwd, { projectInBody: true });
+    const projectId = target?.projectId ?? stringFlag3(flags, "--project");
     if (projectId) body.projectId = projectId;
-    const permissions = stringFlag(flags, "--permissions");
+    if (target) body.branch = target.branch;
+    if (stringFlag3(flags, "--instance") !== void 0) {
+      throw new CliError("Unknown option --instance for keys create. Did you mean --instances?");
+    }
+    const instances = stringFlag3(flags, "--instances");
+    if (instances !== void 0) body.instanceIds = parseInstanceList(instances);
+    if (stringFlag3(flags, "--index") !== void 0) {
+      throw new CliError("Unknown option --index for keys create. Did you mean --indexes?");
+    }
+    const indexes = stringFlag3(flags, "--indexes");
+    if (indexes !== void 0) body.indexUids = parseIndexList(indexes);
+    const permissions = stringFlag3(flags, "--permissions");
     if (permissions) body.permissions = parsePermissions(permissions);
-    const expires = stringFlag(flags, "--expires");
+    const expires = stringFlag3(flags, "--expires");
     if (expires) body.expiresAt = parseExpires(expires);
-    const response = await client.post("/v1/keys", body);
+    const response = await client.post("/v1/keys", body).catch((error) => {
+      if (error instanceof ApiError && error.code === "branch_required") {
+        throw restate(
+          error,
+          "A search key needs a branch, because only --type admin makes an org key. Pass --project <id> for that project's main branch, add --branch <name> for another branch, or run headband branch checkout first."
+        );
+      }
+      throw error;
+    });
+    if (instances !== void 0 && !Array.isArray(response.data.key.instanceIds)) {
+      const keyId = response.data.key.id;
+      throw new CliError(
+        typeof keyId === "string" && keyId ? `This API did not limit the new key to the chosen engines, so key ${keyId} reaches wider than asked. Revoke it now: headband keys revoke ${keyId}` : "This API did not limit the new key to the chosen engines, so it reaches wider than asked. Find it with `headband keys list` and revoke it with `headband keys revoke <id>`."
+      );
+    }
+    if (indexes !== void 0 && !Array.isArray(response.data.key.indexUids)) {
+      const keyId = response.data.key.id;
+      throw new CliError(
+        typeof keyId === "string" && keyId ? `This API did not limit the new key to the chosen indexes, so key ${keyId} reaches every index of its branch. Revoke it now: headband keys revoke ${keyId}` : "This API did not limit the new key to the chosen indexes, so it reaches every index of its branch. Find it with `headband keys list` and revoke it with `headband keys revoke <id>`."
+      );
+    }
     if (boolFlag(flags, "--json")) {
       printJson(io, response);
       return;
     }
     io.stdout(import_picocolors3.default.yellow("Store this API key now. It will not be shown again."));
     io.stdout(response.data.apiKey);
-    printTable(io, [response.data.key], ["id", "name", "type", "keyPrefix", "expiresAt"]);
+    printTable(
+      io,
+      [keyRow(response.data.key)],
+      [
+        "id",
+        "name",
+        "type",
+        "environment",
+        "branch",
+        "engines",
+        "indexes",
+        "keyPrefix",
+        "expiresAt"
+      ]
+    );
     return;
   }
   if (action === "revoke") {
@@ -3954,9 +5983,9 @@ async function runKeys(args, flags, io, confirm) {
   printCommandHelp("keys", io);
   throw new UsageError("Unknown keys command");
 }
-async function runIndexes(args, flags, io, confirm) {
+async function runIndexes(args, flags, io, confirm, cwd) {
   const action = args[0];
-  const client = clientFromFlags(flags);
+  const client = clientFromFlags(flags, cwd);
   if (action === "list") {
     const response = await client.get("/v1/indexes");
     if (boolFlag(flags, "--json")) printJson(io, response);
@@ -3976,9 +6005,9 @@ async function runIndexes(args, flags, io, confirm) {
   if (action === "create") {
     const uid = requiredArg(args[1], "index uid");
     const body = { uid };
-    const primaryKey = stringFlag(flags, "--primary-key");
-    const engine = stringFlag(flags, "--engine");
-    const instanceId = stringFlag(flags, "--instance");
+    const primaryKey = stringFlag3(flags, "--primary-key");
+    const engine = stringFlag3(flags, "--engine");
+    const instanceId = stringFlag3(flags, "--instance");
     if (primaryKey) body.primaryKey = primaryKey;
     if (engine) body.engine = validateEngine(engine);
     if (instanceId) body.instanceId = instanceId;
@@ -3997,12 +6026,20 @@ async function runIndexes(args, flags, io, confirm) {
         `On the instance endpoint this index is named ${response.engineIndexUid}. Use that name with the engine's own client.`
       );
     }
+    if (typeof response.projectId === "string") {
+      const where = `Created in project ${response.projectId}${typeof response.branch === "string" ? `, branch ${response.branch}` : ""}.`;
+      const chose = branchTargetFor(flags, cwd) !== null;
+      io.stdout(
+        chose ? where : `${where} To create it elsewhere, pass --project <id> --branch main, or run headband branch checkout in that project's directory.`
+      );
+    }
     return;
   }
   if (action === "delete") {
     const uid = requiredArg(args[1], "index uid");
     if (!await confirm(`Delete index ${uid}?`)) return cancelled(io, flags);
     const response = await client.delete(`/v1/indexes/${encode(uid)}`);
+    await client.delete(`/v1/schema/state?indexUid=${encode(uid)}`).catch(() => void 0);
     if (boolFlag(flags, "--json")) printJson(io, response);
     else io.stdout(`Deleted index ${uid}.`);
     return;
@@ -4017,7 +6054,7 @@ async function runIndexes(args, flags, io, confirm) {
     }
     if (settingsAction === "set") {
       const file = requiredFlag(flags, "--file");
-      const settings = JSON.parse((0, import_fs11.readFileSync)(file, "utf-8"));
+      const settings = JSON.parse((0, import_fs12.readFileSync)(file, "utf-8"));
       const response = await client.patch(`/v1/indexes/${encode(uid)}/settings`, settings);
       printJson(io, response);
       return;
@@ -4029,28 +6066,56 @@ async function runIndexes(args, flags, io, confirm) {
     printJson(io, response);
     return;
   }
+  if (action === "switch-engine") {
+    const uid = requiredArg(args[1], "index uid");
+    if (boolFlag(flags, "--status")) {
+      await printSwitchStatus(client, uid, io, boolFlag(flags, "--json"));
+      return;
+    }
+    await runSwitchEngine(
+      client,
+      {
+        uid,
+        engine: validateEngine(requiredFlag(flags, "--engine")),
+        instanceId: stringFlag3(flags, "--instance"),
+        acceptDrops: boolFlag(flags, "--accept-drops"),
+        declareKey: boolFlag(flags, "--declare-key"),
+        dryRun: boolFlag(flags, "--dry-run"),
+        wait: boolFlag(flags, "--wait"),
+        json: boolFlag(flags, "--json")
+      },
+      io,
+      chatterIO(io, flags)
+    );
+    return;
+  }
   printCommandHelp("indexes", io);
   throw new UsageError("Unknown indexes command");
 }
 function exportFormat(flags, out) {
-  const raw = stringFlag(flags, "--format") ?? (out?.toLowerCase().endsWith(".json") ? "json" : "jsonl");
+  const raw = stringFlag3(flags, "--format") ?? (out?.toLowerCase().endsWith(".json") ? "json" : "jsonl");
   if (!EXPORT_FORMATS.has(raw)) throw new UsageError("--format must be jsonl or json");
   return raw;
 }
-async function runDocsExport(flags, context) {
+async function runDocsExport(flags, context, cwd) {
   const { io } = context;
   const index = requiredFlag(flags, "--index");
-  const out = stringFlag(flags, "--out");
+  const out = stringFlag3(flags, "--out");
   const format = exportFormat(flags, out);
-  const client = clientFromFlags(flags);
+  const client = clientFromFlags(flags, cwd);
   const batchSize = parseIntFlag(flags, "--batch") ?? await defaultExportBatchSize(client, index);
+  if (boolFlag(flags, "--declare-key")) await declareExportKey(client, index, io);
   if (!out) {
     const writeLine = context.writeLine ?? ((line) => io.stdout(line));
-    await exportDocuments(client, { index, format, batchSize, write: writeLine });
+    try {
+      await exportDocuments(client, { index, format, batchSize, write: writeLine });
+    } catch (error) {
+      throw exportFailure(error instanceof ExportInterruptedError ? error.cause : error, index);
+    }
     return;
   }
   const partial = `${out}.partial`;
-  const fd = (0, import_fs10.openSync)(partial, "w", 384);
+  const fd = (0, import_fs11.openSync)(partial, "w", 384);
   let exported;
   try {
     exported = await exportDocuments(client, {
@@ -4058,32 +6123,40 @@ async function runDocsExport(flags, context) {
       format,
       batchSize,
       write: (line) => {
-        (0, import_fs10.writeSync)(fd, `${line}
+        (0, import_fs11.writeSync)(fd, `${line}
 `);
       },
-      onPage: (count, total) => io.stderr(`Exported ${count}${total === null ? "" : `/${total}`} documents`)
+      onPage: (count, total) => io.stderr(`Exported ${count}${total === null ? "" : `/${total}`} documents`),
+      finishOnError: true
     });
-    (0, import_fs10.closeSync)(fd);
+    (0, import_fs11.closeSync)(fd);
   } catch (error) {
-    (0, import_fs10.closeSync)(fd);
-    (0, import_fs10.rmSync)(partial, { force: true });
-    throw error;
+    (0, import_fs11.closeSync)(fd);
+    const kept = error instanceof ExportInterruptedError ? error.exported : 0;
+    if (kept > 0) {
+      io.stderr(
+        `Kept the ${kept} ${kept === 1 ? "document" : "documents"} exported before the error in ${partial}. ${out} was not written.`
+      );
+    } else {
+      (0, import_fs11.rmSync)(partial, { force: true });
+    }
+    throw exportFailure(error instanceof ExportInterruptedError ? error.cause : error, index);
   }
-  (0, import_fs10.renameSync)(partial, out);
+  (0, import_fs11.renameSync)(partial, out);
   if (boolFlag(flags, "--json")) printJson(io, { index, out, format, exported });
   else io.stdout(`Exported ${exported} documents to ${out}.`);
 }
-async function runDocs(args, flags, context) {
+async function runDocs(args, flags, context, cwd) {
   const { io } = context;
   const action = args[0];
   if (action === "export") {
-    await runDocsExport(flags, context);
+    await runDocsExport(flags, context, cwd);
     return;
   }
   if (action === "push") {
     const file = requiredArg(args[1], "documents file");
     const index = requiredFlag(flags, "--index");
-    const client = clientFromFlags(flags);
+    const client = clientFromFlags(flags, cwd);
     const documents = parseDocumentsFile(file);
     const count = await pushDocuments(client, index, documents, chatterIO(io, flags));
     if (boolFlag(flags, "--json")) printJson(io, { index, pushed: count });
@@ -4091,30 +6164,38 @@ async function runDocs(args, flags, context) {
     return;
   }
   if (action === "delete") {
-    const docId = requiredArg(args[1], "document id");
+    const ids = args.slice(1);
+    requiredArg(ids[0], "document id");
     const index = requiredFlag(flags, "--index");
-    const client = clientFromFlags(flags);
-    const response = await client.delete(`/v1/documents/${encode(docId)}?index=${encode(index)}`);
+    const client = clientFromFlags(flags, cwd);
+    const response = await client.delete(`/v1/documents?index=${encode(index)}`, { ids });
     if (boolFlag(flags, "--json")) printJson(io, response);
-    else io.stdout(`Deleted document ${docId}.`);
+    else
+      io.stdout(
+        ids.length === 1 ? `Deleted document ${ids[0]}.` : `Deleted ${ids.length} documents.`
+      );
     return;
   }
   printCommandHelp("docs", io);
   throw new UsageError("Unknown docs command");
 }
-async function runSearch(args, flags, io) {
+async function runSearch(args, flags, io, cwd) {
   const index = requiredArg(args[0], "search index");
   const query = args.slice(1).join(" ");
-  if (!query) throw new UsageError("Missing search query");
-  const client = clientFromFlags(flags);
+  const client = clientFromFlags(flags, cwd);
   const body = {
     index,
     q: query
   };
   const limit = parseLimit(flags);
-  const filter = stringFlag(flags, "--filter");
+  const filter = stringFlag3(flags, "--filter");
+  const mode = stringFlag3(flags, "--mode");
+  if (mode !== void 0 && !SEARCH_MODES.has(mode)) {
+    throw new UsageError("--mode must be instant or retrieval");
+  }
   if (limit) body.limit = limit;
   if (filter) body.filter = filter;
+  if (mode) body.mode = mode;
   const response = await client.post("/v1/search", body);
   if (boolFlag(flags, "--json")) {
     printJson(io, response);
@@ -4124,11 +6205,26 @@ async function runSearch(args, flags, io) {
   io.stdout(`${total} hits in ${response.processingTimeMs ?? 0}ms`);
   printTable(io, (response.hits || []).map(summarizeHit));
 }
-async function runTasks(args, flags, io) {
+function tasksIndexHint(error) {
+  if (error instanceof ApiError && error.status === 400 && (error.code === "indexUids_required" || error.code === "index_required")) {
+    throw new UsageError(
+      "Pass --index <uid>: tasks live on the engine that holds the index, and this key (an org key, or a branch other than main) does not name one.",
+      "index_required"
+    );
+  }
+  throw error;
+}
+async function runTasks(args, flags, io, cwd) {
   const action = args[0];
-  const client = clientFromFlags(flags);
+  const client = clientFromFlags(flags, cwd);
+  const index = stringFlag3(flags, "--index");
   if (action === "list") {
-    const response = await client.get("/v1/tasks");
+    const params = new URLSearchParams();
+    if (index) params.set("indexUids", index);
+    const limit = parseLimit(flags);
+    if (limit) params.set("limit", String(limit));
+    const query = params.toString();
+    const response = await client.get(`/v1/tasks${query ? `?${query}` : ""}`).catch(tasksIndexHint);
     if (boolFlag(flags, "--json")) printJson(io, response);
     else
       printTable(io, response.results ?? [], [
@@ -4143,28 +6239,43 @@ async function runTasks(args, flags, io) {
   }
   if (action === "get") {
     const id = requiredArg(args[1], "task id");
-    const response = await client.get(`/v1/tasks/${encode(id)}`);
+    const response = await client.get(`/v1/tasks/${encode(id)}${index ? `?index=${encode(index)}` : ""}`).catch(tasksIndexHint);
     printJson(io, response);
     return;
   }
   printCommandHelp("tasks", io);
   throw new UsageError("Unknown tasks command");
 }
-async function runSchema(args, flags, io, confirm) {
+async function runSchema(args, flags, io, confirm, cwd) {
   const action = args[0];
-  if (!["diff", "generate", "apply", "status"].includes(action)) {
+  if (!["diff", "generate", "apply", "status", "forget"].includes(action)) {
     printCommandHelp("schema", io);
     throw new UsageError("Unknown schema command");
   }
   const json = boolFlag(flags, "--json");
   const chatter = chatterIO(io, flags);
-  const dir = stringFlag(flags, "--dir") || DEFAULT_MIGRATIONS_DIR;
-  const auth = authFromFlags(flags);
-  const client = new HeadbandClient({ url: auth.url, adminKey: auth.apiKey });
-  const { config, adapter } = await loadHeadbandConfig(process.cwd());
+  const dir = stringFlag3(flags, "--dir") || DEFAULT_MIGRATIONS_DIR;
+  if (action === "forget") {
+    const index = requiredArg(args[1], "index name");
+    const client2 = syncClientFromFlags(flags, cwd);
+    if (!await confirm(`Forget the recorded schema state of "${index}"?`)) {
+      return cancelled(io, flags);
+    }
+    await runSchemaForget({ client: client2, index, io: chatter });
+    if (json) printJson(io, { index, forgotten: true });
+    return;
+  }
+  const { config, adapter } = await loadHeadbandConfig(cwd);
+  const clientOptions = { projectInBody: true, defaultUrl: config.url };
+  const client = syncClientFromFlags(flags, cwd, clientOptions);
+  const apiClient = clientFromFlags(flags, cwd, clientOptions);
+  const projectId = stringFlag3(flags, "--project") ?? config.projectId;
+  const indexUids = () => listIndexUids(apiClient);
   const allowDestructive = boolFlag(flags, "--allow-destructive");
   if (action === "diff") {
-    const ops = await planSchemaDiff({ config, client, allowDestructive });
+    const applied = await client.getSchemaState();
+    const ops = planMigration(config, applied, { allowDestructive });
+    warnOrphans(chatter, applied, await indexUids());
     if (json) printJson(io, { inSync: ops.length === 0, ops: opRows(ops) });
     else printOpsTable(io, ops);
     if (ops.length > 0) process.exitCode = 1;
@@ -4175,7 +6286,7 @@ async function runSchema(args, flags, io, confirm) {
       config,
       client,
       dir,
-      slug: stringFlag(flags, "--slug"),
+      slug: stringFlag3(flags, "--slug"),
       io: chatter,
       allowDestructive
     });
@@ -4184,9 +6295,7 @@ async function runSchema(args, flags, io, confirm) {
   }
   if (action === "apply") {
     if (!adapter) {
-      throw new CliError(
-        "headband.config.ts must export an `adapter` (e.g. drizzleAdapter(...)) for schema apply \u2014 it's needed to backfill documents during a reindex."
-      );
+      throw missingAdapterError("schema apply", "it reads your tables to backfill new indexes");
     }
     if (!await confirm("Apply pending schema migrations?")) {
       return cancelled(io, flags);
@@ -4197,20 +6306,47 @@ async function runSchema(args, flags, io, confirm) {
       client,
       dir,
       allowDestructive,
-      io: chatter
+      io: chatter,
+      projectId,
+      readRemoteDocuments: (uid, primaryKey) => readRemoteDocuments(apiClient, uid, primaryKey)
     });
-    if (json) printJson(io, result);
-    else
+    if (json) printJson(io, { ...result, projectId: projectId ?? null });
+    else {
       io.stdout(
         `Applied ${result.appliedOps} op(s) across ${result.appliedFiles} migration file(s).`
       );
+      if (result.appliedOps > 0 && !projectId && authFromFlags(flags, { url: config.url }).source === "profile") {
+        io.stdout(
+          "New indexes went to your org's Default project, because no project was named. A project admin key (what your app uses) reaches only its own project's indexes: name it with --project <id> or projectId in headband.config.ts."
+        );
+      }
+    }
     return;
   }
-  const status = await runSchemaStatus({ config, client, dir, io: chatter });
+  const status = await runSchemaStatus({
+    config,
+    client,
+    dir,
+    io: chatter,
+    indexUids: await indexUids()
+  });
   if (json) printJson(io, status);
 }
+async function listIndexUids(client) {
+  try {
+    const response = await client.get("/v1/indexes");
+    const uids = /* @__PURE__ */ new Set();
+    for (const row of response.results ?? []) {
+      if (row.uid) uids.add(row.uid);
+      if (row.physicalUid) uids.add(row.physicalUid);
+    }
+    return uids;
+  } catch {
+    return void 0;
+  }
+}
 function parseIntFlag(flags, name) {
-  const raw = stringFlag(flags, name);
+  const raw = stringFlag3(flags, name);
   if (!raw) return void 0;
   const value = Number(raw);
   if (!Number.isInteger(value) || value <= 0) {
@@ -4218,14 +6354,14 @@ function parseIntFlag(flags, name) {
   }
   return value;
 }
-async function runSync(args, flags, io, confirm) {
+async function runSync(args, flags, io, confirm, cwd) {
   const action = args[0];
   const json = boolFlag(flags, "--json");
   const chatter = chatterIO(io, flags);
   if (action === "source") {
     await runSyncSource(args.slice(1), flags, {
       io,
-      client: clientFromFlags(flags),
+      client: clientFromFlags(flags, cwd),
       confirm
     });
     return;
@@ -4233,51 +6369,76 @@ async function runSync(args, flags, io, confirm) {
   if (action === "index") {
     await runSyncIndex(args.slice(1), flags, {
       io,
-      client: clientFromFlags(flags),
+      client: clientFromFlags(flags, cwd),
       confirm
     });
     return;
   }
   if (action === "status") {
+    if (findConfigFile(cwd)) {
+      const { config, path: path2 } = await loadHeadbandConfig(cwd);
+      const databaseUrl = process.env.DATABASE_URL || process.env.HEADBAND_DATABASE_URL;
+      const pg = databaseUrl ? buildPgOutbox(databaseUrl, { table: config.sync?.outboxTable }) : null;
+      try {
+        const status = await runSelfHostedSyncStatus({
+          config,
+          configPath: path2,
+          outbox: pg?.outbox ?? null,
+          io: chatter
+        });
+        if (json) printJson(io, { selfHosted: status });
+      } finally {
+        await pg?.close();
+      }
+      return;
+    }
     await runSyncStatus(flags, {
       io,
-      client: clientFromFlags(flags),
+      client: clientFromFlags(flags, cwd),
       confirm
     });
     return;
   }
   if (action === "init") {
-    const cwd = process.cwd();
     const write = boolFlag(flags, "--write");
-    const ddl = runSyncInit({
+    const apply = boolFlag(flags, "--apply");
+    const databaseUrl = apply ? resolveDatabaseUrl(process.env) : void 0;
+    const table = stringFlag3(flags, "--table") ?? (findConfigFile(cwd) ? (await loadHeadbandConfig(cwd)).config.sync?.outboxTable : void 0);
+    const ddl = await runSyncInit({
       io: json ? { stdout: () => void 0, stderr: io.stderr } : io,
-      table: stringFlag(flags, "--table"),
+      table,
       write,
-      cwd
+      cwd,
+      ...databaseUrl ? { apply: (sql) => applyOutboxDDL(databaseUrl, sql) } : {}
     });
-    if (json) printJson(io, { ddl, path: write ? (0, import_path9.join)(cwd, OUTBOX_SQL_RELATIVE_PATH) : null });
+    if (json)
+      printJson(io, {
+        ddl,
+        path: write ? (0, import_path11.join)(cwd, OUTBOX_SQL_RELATIVE_PATH) : null,
+        applied: apply
+      });
     return;
   }
   if (action === "worker") {
-    const scaffold = stringFlag(flags, "--scaffold");
+    const scaffold = stringFlag3(flags, "--scaffold");
     if (scaffold) {
       if (scaffold !== "docker") throw new UsageError(`Unknown scaffold target: ${scaffold}`);
       const path2 = runSyncScaffoldDocker({
-        cwd: process.cwd(),
+        cwd,
         io: chatter,
-        force: boolFlag(flags, "--force")
+        force: boolFlag(flags, "--force"),
+        cliVersion: CLI_VERSION
       });
       if (json) printJson(io, { path: path2 });
       return;
     }
-    const auth = authFromFlags(flags);
-    const client = new HeadbandClient({ url: auth.url, adminKey: auth.apiKey });
-    const { config, adapter } = await loadHeadbandConfig(process.cwd());
+    const { config, adapter } = await loadHeadbandConfig(cwd);
     if (!adapter) {
-      throw new CliError(
-        "headband.config.ts must export an `adapter` (e.g. drizzleAdapter(...)) for sync worker."
-      );
+      throw missingAdapterError("sync worker", "it reads your tables to build each document");
     }
+    const clientOptions = { projectInBody: true, defaultUrl: config.url };
+    const client = syncClientFromFlags(flags, cwd, clientOptions);
+    const apiClient = clientFromFlags(flags, cwd, clientOptions);
     const { outbox, close } = buildPgOutbox(resolveDatabaseUrl(process.env), {
       table: config.sync?.outboxTable
     });
@@ -4288,21 +6449,22 @@ async function runSync(args, flags, io, confirm) {
         client,
         outbox,
         io: chatter,
+        projectId: stringFlag3(flags, "--project") ?? config.projectId,
         // Only override runSyncWorkerCmd's own default (loop unless
-        // --budget-ms is set) when the caller explicitly passed --loop —
-        // omitting it here keeps the bare `sync worker` default unchanged.
+        // --budget-ms is set) when the caller explicitly passed --loop.
+        // Omitting it here keeps the bare `sync worker` default unchanged.
         loop: boolFlag(flags, "--loop") ? true : void 0,
         budgetMs: parseIntFlag(flags, "--budget-ms"),
         batchSize: parseIntFlag(flags, "--batch-size"),
         reconcileEvery: parseIntFlag(flags, "--reconcile-every"),
         onReconcileTick: async () => {
-          const apiClient = clientFromFlags(flags);
           await runSyncReconcile({
             config,
             adapter,
             client,
             io: chatter,
-            getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`)
+            getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`),
+            listRemoteIds: (uid, primaryKey) => listRemoteIds(apiClient, uid, primaryKey)
           });
         }
       });
@@ -4313,28 +6475,30 @@ async function runSync(args, flags, io, confirm) {
     return;
   }
   if (action === "reconcile") {
-    const auth = authFromFlags(flags);
-    const client = new HeadbandClient({ url: auth.url, adminKey: auth.apiKey });
-    const apiClient = createApiClient(auth.url, auth);
-    const { config, adapter } = await loadHeadbandConfig(process.cwd());
+    const { config, adapter } = await loadHeadbandConfig(cwd);
     if (!adapter) {
-      throw new CliError(
-        "headband.config.ts must export an `adapter` (e.g. drizzleAdapter(...)) for sync reconcile."
-      );
+      throw missingAdapterError("sync reconcile", "it reads your tables to compare them");
     }
+    const clientOptions = { projectInBody: true, defaultUrl: config.url };
+    const client = syncClientFromFlags(flags, cwd, clientOptions);
+    const apiClient = clientFromFlags(flags, cwd, clientOptions);
     const rows = await runSyncReconcile({
       config,
       adapter,
       client,
       io: chatter,
       fix: boolFlag(flags, "--fix"),
-      getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`)
+      content: boolFlag(flags, "--content"),
+      getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`),
+      listRemoteIds: (uid, primaryKey) => listRemoteIds(apiClient, uid, primaryKey),
+      readRemoteDocuments: (uid, primaryKey) => readRemoteDocuments(apiClient, uid, primaryKey)
     });
-    if (json) printJson(io, { indexes: rows });
+    if (json) printJson(io, { indexes: rows, drift: reconcileHasDrift(rows) });
+    if (reconcileHasDrift(rows)) process.exitCode = 1;
     return;
   }
   if (action === "retry-dead-letters") {
-    const { config } = await loadHeadbandConfig(process.cwd());
+    const { config } = await loadHeadbandConfig(cwd);
     const { outbox, close } = buildPgOutbox(resolveDatabaseUrl(process.env), {
       table: config.sync?.outboxTable
     });
@@ -4349,7 +6513,7 @@ async function runSync(args, flags, io, confirm) {
   printCommandHelp("sync", io);
   throw new UsageError("Unknown sync command");
 }
-var CLI_VERSION = true ? "0.3.0" : "dev";
+var CLI_VERSION = true ? "0.6.1" : "dev";
 async function run(argv, context = { io: defaultIO }) {
   if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version")) {
     context.io.stdout(CLI_VERSION);
@@ -4359,13 +6523,17 @@ async function run(argv, context = { io: defaultIO }) {
   const command = positional[0];
   const args = positional.slice(1);
   if (boolFlag(flags, "--help") || command === "help") {
+    const subcommandHelp = command && args[0] ? SUBCOMMAND_HELP[`${command} ${args[0]}`] : void 0;
     if (command === "sync" && args[0] === "source") context.io.stdout(SOURCE_USAGE);
     else if (command === "sync" && args[0] === "index") context.io.stdout(INDEX_USAGE);
+    else if (subcommandHelp) context.io.stdout(subcommandHelp);
+    else if (command === "help" && args[0]) printCommandHelp(args[0], context.io);
     else if (command && command !== "help") printCommandHelp(command, context.io);
     else printHelp(context.io);
     return;
   }
   const confirm = (message) => confirmOrSkip(message, flags, context.ask);
+  const cwd = context.cwd ?? process.cwd();
   switch (command || "init") {
     case "init":
       if (!boolFlag(flags, "--yes") && !stdinIsInteractive()) {
@@ -4389,31 +6557,39 @@ async function run(argv, context = { io: defaultIO }) {
       await runProfiles(args, flags, context.io);
       return;
     case "projects":
-      await runProjects(args, flags, context.io, confirm);
+      await runProjects(args, flags, context.io, confirm, cwd);
+      return;
+    case "branch":
+    case "branches":
+      await runBranch(args, flags, { io: context.io, auth: authFromFlags(flags), confirm, cwd });
       return;
     case "keys":
-      await runKeys(args, flags, context.io, confirm);
+      await runKeys(args, flags, context.io, confirm, cwd);
       return;
     case "indexes":
-      await runIndexes(args, flags, context.io, confirm);
+    case "index":
+      await runIndexes(args, flags, context.io, confirm, cwd);
       return;
     case "docs":
-      await runDocs(args, flags, context);
+      await runDocs(args, flags, context, cwd);
       return;
     case "search":
-      await runSearch(args, flags, context.io);
+      await runSearch(args, flags, context.io, cwd);
       return;
     case "tasks":
-      await runTasks(args, flags, context.io);
+      await runTasks(args, flags, context.io, cwd);
       return;
     case "schema":
-      await runSchema(args, flags, context.io, confirm);
+      await runSchema(args, flags, context.io, confirm, cwd);
       return;
     case "sync":
-      await runSync(args, flags, context.io, confirm);
+      await runSync(args, flags, context.io, confirm, cwd);
       return;
     case "instances":
-      await runInstances(args, flags, context.io, clientFromFlags(flags), confirm);
+      await runInstances(args, flags, context.io, clientFromFlags(flags, cwd), confirm);
+      return;
+    case "warm":
+      await runWarm(args, flags, context.io, clientFromFlags(flags, cwd));
       return;
     default:
       printHelp(context.io);
@@ -4439,7 +6615,7 @@ async function main(argv, context = { io: defaultIO }) {
 function stdoutLineWriter(line) {
   if (process.stdout.write(`${line}
 `)) return;
-  return new Promise((resolve) => process.stdout.once("drain", () => resolve()));
+  return new Promise((resolve2) => process.stdout.once("drain", () => resolve2()));
 }
 function isDirectRun() {
   return typeof require !== "undefined" && typeof module !== "undefined" && require.main === module;
@@ -4450,18 +6626,30 @@ if (isDirectRun()) {
     throw error;
   });
   void main(process.argv.slice(2), { io: defaultIO, writeLine: stdoutLineWriter }).then((code) => {
-    if (code === EXIT_CODES.ok) return;
-    process.exitCode = code;
-    setTimeout(() => process.exit(code), 2e3).unref();
+    const exitCode = code === EXIT_CODES.ok ? Number(process.exitCode ?? 0) : code;
+    process.exitCode = exitCode;
+    exitAfterFlush(exitCode);
+    setTimeout(() => process.exit(exitCode), 2e3).unref();
   });
 }
+function exitAfterFlush(code) {
+  let pending = 2;
+  const done = () => {
+    pending -= 1;
+    if (pending === 0) process.exit(code);
+  };
+  process.stdout.write("", done);
+  process.stderr.write("", done);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CLI_VERSION,
   main,
   parseArgv,
   parseExpires,
+  parseIndexList,
   parsePermissions,
   run,
-  stdinIsInteractive
+  stdinIsInteractive,
+  syncClientFromFlags
 });