busa-cli 0.9.8 → 0.9.10

package/dist/{chunk-37OV7S7G.js → chunk-IO4ARUEI.js}

@@ -120,7 +120,7 @@ function nodeIcon(type) {
 }
 
 // src/run.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash6 } from "crypto";
 import { readFileSync as readFileSync2 } from "fs";
 import { basename, extname as extname2 } from "path";
 import {
@@ -137,6 +137,566 @@ import {
   Option
 } from "commander";
 
+// src/backup/export/full-exporter.ts
+import { createHash as createHash2 } from "crypto";
+
+// ../../packages/busabase-contract/src/domains/dump/types.ts
+import { z } from "zod";
+var DumpTableSchema = z.enum([
+  "nodes",
+  /** Node-level access grants (permissions). Not secret — restore must keep them
+   * so a backed-up space's sharing/permission config survives a full restore. */
+  "nodePrincipals",
+  "bases",
+  "baseFields",
+  "views",
+  "records",
+  "fieldValues",
+  "recordLinks",
+  /** The physical bytes registry (open-domains/attachments) an Asset's `attachmentId` FKs into. */
+  "attachments",
+  "assets",
+  "assetUsages",
+  "assetTexts",
+  "commits",
+  "changeRequests",
+  "operations",
+  "comments",
+  "reviews",
+  "auditEvents"
+]);
+var ExportTablesInputSchema = z.object({
+  table: DumpTableSchema,
+  /** Opaque pagination cursor from a previous page's `nextCursor`; omit for the first page. */
+  cursor: z.string().optional(),
+  /** Page size, default 500, capped at 2000. */
+  limit: z.number().int().positive().max(2e3).optional().default(500)
+});
+var ExportTablesVOSchema = z.object({
+  rows: z.array(z.record(z.string(), z.unknown())),
+  nextCursor: z.string().nullable()
+});
+var ExportAssetTextInputSchema = z.object({ assetId: z.string() });
+var ExportAssetTextVOSchema = z.object({
+  assetId: z.string(),
+  /** The row's `text_storage_key` — the exact key a restore must write back to. */
+  textStorageKey: z.string(),
+  /**
+   * `null` when this row owns no separate text object and therefore needs no
+   * blob in the archive:
+   *  - auto-registered text-kind rows (`writtenBy: "auto"`), whose
+   *    `textStorageKey` IS the owning attachment's own key — those bytes are
+   *    already archived by the attachment-blob pass, and re-archiving them
+   *    would duplicate bytes and collide on restore;
+   *  - `status: "none"` rows (no extractable text), whose key is `""`.
+   */
+  downloadUrl: z.string().nullable(),
+  /** `sha256:<hex>` of the text bytes, so a backup can verify what it downloaded. */
+  textContentHash: z.string().nullable(),
+  byteCount: z.number().int().nonnegative()
+});
+var ImportBeginVOSchema = z.object({
+  sessionId: z.string()
+});
+var ImportTablesInputSchema = z.object({
+  sessionId: z.string(),
+  table: z.union([
+    DumpTableSchema,
+    z.literal("docBodies"),
+    z.literal("attachmentBlobs"),
+    z.literal("assetTextBlobs")
+  ]),
+  rows: z.array(z.record(z.string(), z.unknown()))
+});
+var ImportTablesVOSchema = z.object({
+  inserted: z.number().int().nonnegative()
+});
+var ImportSessionInputSchema = z.object({
+  sessionId: z.string()
+});
+var ImportCommitVOSchema = z.object({
+  ok: z.boolean(),
+  warnings: z.array(z.string())
+});
+var ImportAbortVOSchema = z.object({
+  ok: z.boolean()
+});
+
+// src/backup/format/archive-writer.ts
+import { createHash } from "crypto";
+import { createWriteStream } from "fs";
+import { PassThrough } from "stream";
+import { pipeline } from "stream/promises";
+import { ZstdCompress } from "zlib";
+import * as tar from "tar-stream";
+
+// src/backup/format/manifest.ts
+import { z as z2 } from "zod";
+var FORMAT_VERSION = 1;
+var ManifestSchema = z2.object({
+  formatVersion: z2.literal(FORMAT_VERSION),
+  toolVersion: z2.string(),
+  exportedAt: z2.string(),
+  spaceId: z2.string(),
+  sourceHost: z2.string(),
+  fidelity: z2.enum(["full", "state"]),
+  /** Vault items and webhook signing secrets are never written to the archive. */
+  excludesSecrets: z2.literal(true),
+  tables: z2.record(z2.string(), z2.number().int().nonnegative()),
+  blobCount: z2.number().int().nonnegative(),
+  blobBytes: z2.number().int().nonnegative(),
+  /**
+   * Extracted-text ("Drive Grep Retrieval") blobs, counted separately from the
+   * attachment blobs above because they are a different object class — derived
+   * text, content-addressed under `asset-texts/blobs/sha256/…`, one per
+   * `busabase_asset_texts` row that owns its own object.
+   *
+   * `.default(0)` rather than required: archives written before asset-text
+   * blobs were captured at all carry no such field, and those are exactly the
+   * archives an operator most needs to be able to still open — the import's
+   * integrity pass is what tells them the text is missing, which it can only
+   * do if the manifest parses in the first place.
+   */
+  textBlobCount: z2.number().int().nonnegative().optional().default(0),
+  textBlobBytes: z2.number().int().nonnegative().optional().default(0),
+  /** sha256 hex digest — see the doc comment above for exactly what it covers. */
+  checksum: z2.string()
+});
+function canonicalizeEntryChecksums(entries) {
+  return entries.slice().sort((a, b) => a.path.localeCompare(b.path)).map((e) => `${e.path}:${e.sha256}`).join("\n");
+}
+
+// src/backup/format/archive-writer.ts
+var ArchiveWriter = class _ArchiveWriter {
+  pack = tar.pack();
+  entryChecksums = [];
+  donePromise;
+  constructor(outPath) {
+    const zstd = new ZstdCompress();
+    this.donePromise = pipeline(this.pack, zstd, createWriteStream(outPath));
+  }
+  static create(outPath) {
+    return new _ArchiveWriter(outPath);
+  }
+  /** Add one archive entry from an in-memory buffer/string (small entries: manifest, base.json, etc). */
+  async addBuffer(path, data) {
+    const buf = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+    const sha256 = createHash("sha256").update(buf).digest("hex");
+    this.entryChecksums.push({ path, sha256 });
+    await new Promise((resolvePromise, reject) => {
+      this.pack.entry(
+        { name: path, size: buf.length },
+        buf,
+        (err) => err ? reject(err) : resolvePromise()
+      );
+    });
+  }
+  /** Add one archive entry streamed from a Readable (large entries: records.ndjson, blobs). */
+  async addStream(path, size, source) {
+    const hash = createHash("sha256");
+    const entry = this.pack.entry({ name: path, size });
+    const tee = new PassThrough();
+    tee.on("data", (chunk) => hash.update(chunk));
+    await pipeline(source, tee, entry);
+    this.entryChecksums.push({ path, sha256: hash.digest("hex") });
+  }
+  /**
+   * Write `manifest.json` (with the top-level checksum over every other
+   * entry) and close the archive. Must be called exactly once, after every
+   * other entry has been added.
+   */
+  async finalize(manifestWithoutChecksum) {
+    const checksum = createHash("sha256").update(canonicalizeEntryChecksums(this.entryChecksums)).digest("hex");
+    const manifest = { ...manifestWithoutChecksum, checksum };
+    const buf = Buffer.from(JSON.stringify(manifest, null, 2), "utf8");
+    await new Promise((resolvePromise, reject) => {
+      this.pack.entry(
+        { name: "manifest.json", size: buf.length },
+        buf,
+        (err) => err ? reject(err) : resolvePromise()
+      );
+    });
+    this.pack.finalize();
+    await this.donePromise;
+    return manifest;
+  }
+};
+
+// src/backup/export/full-exporter.ts
+var EXPORT_TABLES = [...DumpTableSchema.options];
+var HISTORY_TABLES = [
+  "commits",
+  "changeRequests",
+  "operations",
+  "comments",
+  "reviews",
+  "auditEvents"
+];
+async function exportFull(options) {
+  const { client, outPath, spaceId, sourceHost, includeHistory, toolVersion, onProgress } = options;
+  const pageLimit = options.pageLimit ?? 500;
+  const log = onProgress ?? (() => {
+  });
+  const writer = ArchiveWriter.create(outPath);
+  const tableCounts = {};
+  const tableRows = {};
+  const tables = includeHistory ? EXPORT_TABLES : EXPORT_TABLES.filter((t) => !HISTORY_TABLES.includes(t));
+  for (const table of tables) {
+    const rows = [];
+    let cursor;
+    do {
+      const page = await client.dump.exportTables({ table, cursor, limit: pageLimit });
+      rows.push(...page.rows);
+      cursor = page.nextCursor ?? void 0;
+    } while (cursor);
+    tableRows[table] = rows;
+    tableCounts[table] = rows.length;
+    const ndjson = `${rows.map((row) => JSON.stringify(row)).join("\n")}${rows.length ? "\n" : ""}`;
+    await writer.addBuffer(`tree/${table}.ndjson`, ndjson);
+    log(`exported ${table}: ${rows.length} rows`);
+  }
+  const docNodes = (tableRows.nodes ?? []).filter((n) => n.type === "doc");
+  let docBodyCount = 0;
+  for (const node of docNodes) {
+    const nodeId = node.id;
+    const doc = await client.docs.get({ nodeId });
+    await writer.addBuffer(`docs/${nodeId}.md`, doc.body ?? "");
+    docBodyCount += 1;
+  }
+  log(`exported ${docBodyCount} doc bodies`);
+  const attachmentsById = new Map((tableRows.attachments ?? []).map((a) => [a.id, a]));
+  const attachmentBlobRows = [];
+  let blobCount = 0;
+  let blobBytes = 0;
+  const skippedAssets = [];
+  for (const asset of tableRows.assets ?? []) {
+    const assetId = asset.id;
+    const attachment = attachmentsById.get(asset.attachmentId);
+    try {
+      if (!attachment) throw new Error("no matching attachments row (orphaned asset)");
+      const download = await client.assets.download({ assetId });
+      const resolvedUrl = new URL(download.downloadUrl, sourceHost).toString();
+      const res = await fetch(resolvedUrl);
+      if (!res.ok || !res.body) {
+        throw new Error(`HTTP ${res.status}`);
+      }
+      const buf = Buffer.from(await res.arrayBuffer());
+      attachmentBlobRows.push({
+        storageKey: attachment.storageKey,
+        mimeType: download.mimeType,
+        base64: buf.toString("base64")
+      });
+      blobCount += 1;
+      blobBytes += buf.length;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      skippedAssets.push(assetId);
+      log(`  WARNING: could not download asset ${assetId}, skipping its blob (${message})`);
+    }
+  }
+  const blobNdjson = `${attachmentBlobRows.map((row) => JSON.stringify(row)).join("\n")}${attachmentBlobRows.length ? "\n" : ""}`;
+  await writer.addBuffer("tree/attachmentBlobs.ndjson", blobNdjson);
+  log(
+    `exported ${blobCount} attachment blobs (${blobBytes} bytes), skipped ${skippedAssets.length}`
+  );
+  const textBlobRows = [];
+  const seenTextKeys = /* @__PURE__ */ new Set();
+  let textBlobCount = 0;
+  let textBlobBytes = 0;
+  const skippedAssetTexts = [];
+  for (const assetText of tableRows.assetTexts ?? []) {
+    const assetId = assetText.assetId;
+    try {
+      const info = await client.dump.exportAssetText({ assetId });
+      if (!info.downloadUrl) continue;
+      if (seenTextKeys.has(info.textStorageKey)) continue;
+      const resolvedUrl = new URL(info.downloadUrl, sourceHost).toString();
+      const res = await fetch(resolvedUrl);
+      if (!res.ok || !res.body) {
+        throw new Error(`HTTP ${res.status}`);
+      }
+      const buf = Buffer.from(await res.arrayBuffer());
+      if (info.textContentHash) {
+        const actual = `sha256:${createHash2("sha256").update(buf).digest("hex")}`;
+        if (actual !== info.textContentHash) {
+          throw new Error(
+            `content hash mismatch (expected ${info.textContentHash}, downloaded ${actual})`
+          );
+        }
+      }
+      seenTextKeys.add(info.textStorageKey);
+      textBlobRows.push({ textStorageKey: info.textStorageKey, base64: buf.toString("base64") });
+      textBlobCount += 1;
+      textBlobBytes += buf.length;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      skippedAssetTexts.push(assetId);
+      log(
+        `  WARNING: could not download text for asset ${assetId}, skipping its blob (${message})`
+      );
+    }
+  }
+  const textBlobNdjson = `${textBlobRows.map((row) => JSON.stringify(row)).join("\n")}${textBlobRows.length ? "\n" : ""}`;
+  await writer.addBuffer("tree/assetTextBlobs.ndjson", textBlobNdjson);
+  log(
+    `exported ${textBlobCount} asset-text blobs (${textBlobBytes} bytes), skipped ${skippedAssetTexts.length}`
+  );
+  const manifestWithoutChecksum = {
+    formatVersion: FORMAT_VERSION,
+    toolVersion,
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    spaceId,
+    sourceHost,
+    fidelity: "full",
+    excludesSecrets: true,
+    tables: tableCounts,
+    blobCount,
+    blobBytes,
+    textBlobCount,
+    textBlobBytes
+  };
+  return writer.finalize(manifestWithoutChecksum);
+}
+
+// src/backup/format/archive-reader.ts
+import { createHash as createHash3 } from "crypto";
+import { createReadStream } from "fs";
+import { ZstdDecompress } from "zlib";
+import * as tar2 from "tar-stream";
+var ZSTD_MAGIC = Buffer.from([40, 181, 47, 253]);
+var GZIP_MAGIC = Buffer.from([31, 139]);
+async function detectCompression(path) {
+  return new Promise((resolvePromise, reject) => {
+    const stream = createReadStream(path, { start: 0, end: 3 });
+    const chunks = [];
+    stream.on("data", (c2) => chunks.push(c2));
+    stream.on("error", reject);
+    stream.on("end", () => {
+      const head = Buffer.concat(chunks);
+      if (head.subarray(0, 4).equals(ZSTD_MAGIC)) resolvePromise("zstd");
+      else if (head.subarray(0, 2).equals(GZIP_MAGIC)) resolvePromise("gzip");
+      else reject(new Error("Unrecognized .bbdump compression (not zstd or gzip magic bytes)."));
+    });
+  });
+}
+async function readArchive(path) {
+  const compression = await detectCompression(path);
+  if (compression === "gzip") {
+    throw new Error(
+      "This .bbdump archive is gzip-compressed; `busabase-cli restore` only reads zstd archives in v1."
+    );
+  }
+  const extract2 = tar2.extract();
+  const entries = /* @__PURE__ */ new Map();
+  const checksums = [];
+  let manifestBuf;
+  await new Promise((resolvePromise, reject) => {
+    extract2.on("entry", (header, stream, next) => {
+      const chunks = [];
+      stream.on("data", (c2) => chunks.push(c2));
+      stream.on("end", () => {
+        const buf = Buffer.concat(chunks);
+        if (header.name === "manifest.json") {
+          manifestBuf = buf;
+        } else {
+          const sha256 = createHash3("sha256").update(buf).digest("hex");
+          checksums.push({ path: header.name, sha256 });
+          entries.set(header.name, buf);
+        }
+        next();
+      });
+      stream.on("error", reject);
+      stream.resume();
+    });
+    extract2.on("finish", resolvePromise);
+    extract2.on("error", reject);
+    createReadStream(path).pipe(new ZstdDecompress()).on("error", reject).pipe(extract2);
+  });
+  if (!manifestBuf) {
+    throw new Error("Archive is missing manifest.json.");
+  }
+  const manifest = ManifestSchema.parse(JSON.parse(manifestBuf.toString("utf8")));
+  const recomputed = createHash3("sha256").update(canonicalizeEntryChecksums(checksums)).digest("hex");
+  if (recomputed !== manifest.checksum) {
+    throw new Error(
+      `Archive checksum mismatch \u2014 file may be truncated or corrupted (expected ${manifest.checksum}, got ${recomputed}).`
+    );
+  }
+  return { manifest, entries };
+}
+
+// src/backup/import/full-importer.ts
+var IMPORT_ORDER = [
+  "nodes",
+  // `nodeId` / `sourceNodeId` FK into busabase_nodes — must follow "nodes".
+  "nodePrincipals",
+  "bases",
+  "baseFields",
+  "views",
+  "commits",
+  "changeRequests",
+  "operations",
+  "records",
+  "fieldValues",
+  "recordLinks",
+  "attachments",
+  "assets",
+  "assetUsages",
+  "assetTexts",
+  "comments",
+  "reviews",
+  "auditEvents"
+];
+var BATCH_SIZE = 200;
+async function importFull(options) {
+  const { client, archive, onProgress } = options;
+  const log = onProgress ?? (() => {
+  });
+  const { sessionId } = await client.dump.importBegin();
+  try {
+    const blobBuf = archive.entries.get("tree/attachmentBlobs.ndjson");
+    if (blobBuf) {
+      const blobRows = blobBuf.toString("utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+      for (let i = 0; i < blobRows.length; i += BATCH_SIZE) {
+        const batch = blobRows.slice(i, i + BATCH_SIZE);
+        await client.dump.importTables({ sessionId, table: "attachmentBlobs", rows: batch });
+      }
+      log(`imported ${blobRows.length} attachment blobs`);
+    }
+    const textBlobBuf = archive.entries.get("tree/assetTextBlobs.ndjson");
+    if (textBlobBuf) {
+      const textBlobRows = textBlobBuf.toString("utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+      for (let i = 0; i < textBlobRows.length; i += BATCH_SIZE) {
+        const batch = textBlobRows.slice(i, i + BATCH_SIZE);
+        await client.dump.importTables({ sessionId, table: "assetTextBlobs", rows: batch });
+      }
+      log(`imported ${textBlobRows.length} asset-text blobs`);
+    }
+    for (const table of IMPORT_ORDER) {
+      const buf = archive.entries.get(`tree/${table}.ndjson`);
+      if (!buf) continue;
+      const rows = buf.toString("utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+      for (let i = 0; i < rows.length; i += BATCH_SIZE) {
+        const batch = rows.slice(i, i + BATCH_SIZE);
+        await client.dump.importTables({ sessionId, table, rows: batch });
+      }
+      log(`imported ${table}: ${rows.length} rows`);
+    }
+    const docBodyRows = [...archive.entries.entries()].filter(([path]) => path.startsWith("docs/") && path.endsWith(".md")).map(([path, buf]) => ({
+      nodeId: path.slice("docs/".length, -".md".length),
+      markdown: buf.toString("utf8")
+    }));
+    if (docBodyRows.length > 0) {
+      await client.dump.importTables({ sessionId, table: "docBodies", rows: docBodyRows });
+      log(`imported ${docBodyRows.length} doc bodies`);
+    }
+    const result = await client.dump.importCommit({ sessionId });
+    return result;
+  } catch (error) {
+    await client.dump.importAbort({ sessionId }).catch(() => void 0);
+    throw error;
+  }
+}
+
+// src/backup/commands.ts
+var reportProgress = (message) => {
+  console.error(message);
+};
+var STATE_ONLY_BACKUP_MESSAGE = [
+  "--state-only backup is not implemented, and will not be \u2014 it is superseded by",
+  "`busabase-cli publish`, which writes the same state-level content as a readable,",
+  "diffable directory you can push to GitHub:",
+  "",
+  "  busabase-cli publish <node-slug> -o ./my-package",
+  "  busabase-cli install https://github.com/<you>/<repo>",
+  "",
+  "`busabase-cli backup` stays the full-fidelity backup path (raw rows, original ids,",
+  "history) \u2014 run it without --state-only. The two formats are deliberately separate:",
+  "a backup carries the audit events, comments, reviews and ACLs that a published",
+  "package must never leak."
+].join("\n");
+var STATE_ONLY_RESTORE_MESSAGE = [
+  "state-only archive restore is not implemented, and will not be \u2014 it is superseded",
+  "by `busabase-cli install`, which installs state-level content into an EXISTING",
+  "space as change requests you review before they go live:",
+  "",
+  "  busabase-cli install https://github.com/<you>/<repo> --into-folder <name>",
+  "",
+  "`busabase-cli restore` stays the full-fidelity restore path (original ids and",
+  "history, into an empty space)."
+].join("\n");
+var runBackup = async (client, options) => {
+  if (options.stateOnly) throw new Error(STATE_ONLY_BACKUP_MESSAGE);
+  const { spaceId } = options;
+  if (!spaceId) {
+    throw new Error(
+      "No space configured. Pass --space-id <id>, export BUSABASE_SPACE_ID, or run `busabase-cli login`."
+    );
+  }
+  reportProgress(
+    `Backing up space ${spaceId} \u2192 ${options.outFile} (full fidelity, history=${options.includeHistory})`
+  );
+  const manifest = await exportFull({
+    client,
+    outPath: options.outFile,
+    spaceId,
+    sourceHost: options.baseUrl,
+    includeHistory: options.includeHistory,
+    toolVersion: options.toolVersion,
+    onProgress: (message) => reportProgress(`  ${message}`)
+  });
+  const rows = Object.values(manifest.tables).reduce((total, count) => total + count, 0);
+  if (options.json) {
+    return {
+      file: options.outFile,
+      rows,
+      blobCount: manifest.blobCount,
+      blobBytes: manifest.blobBytes,
+      manifest
+    };
+  }
+  return [
+    `Done. ${rows} rows, ${manifest.blobCount} blobs (${manifest.blobBytes} bytes) \u2192 ${options.outFile}`,
+    "",
+    "Restore it into an empty space with:",
+    `  busabase-cli restore ${options.outFile}`
+  ].join("\n");
+};
+var runRestore = async (client, options) => {
+  if (options.resume) {
+    throw new Error("--resume is not implemented yet in this version.");
+  }
+  reportProgress(`Reading ${options.file} \u2026`);
+  const archive = await readArchive(options.file);
+  reportProgress(
+    `Archive: fidelity=${archive.manifest.fidelity} space=${archive.manifest.spaceId} exportedAt=${archive.manifest.exportedAt}`
+  );
+  if (archive.manifest.fidelity !== "full") throw new Error(STATE_ONLY_RESTORE_MESSAGE);
+  if (options.intoFolder) {
+    throw new Error("--into-folder only applies to state-only archives.");
+  }
+  const result = await importFull({
+    client,
+    archive,
+    onProgress: (message) => reportProgress(`  ${message}`)
+  });
+  if (options.json) {
+    return {
+      restored: result.ok,
+      file: options.file,
+      spaceId: archive.manifest.spaceId,
+      warnings: result.warnings
+    };
+  }
+  if (!result.ok || result.warnings.length > 0) {
+    return [
+      "Restore completed with warnings:",
+      ...result.warnings.map((warning) => `  \u2022 ${warning}`)
+    ].join("\n");
+  }
+  return "Restore completed successfully.";
+};
+
 // src/banner.ts
 var useColor = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
 var paint = (code, s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
@@ -206,15 +766,19 @@ function writeDotEnvFile(updates) {
 
 // src/login.ts
 import { spawn } from "child_process";
-import { createHash, randomBytes } from "crypto";
+import { createHash as createHash4, randomBytes } from "crypto";
 import { createServer } from "http";
 import { createInterface } from "readline/promises";
+
+// ../../packages/busabase-contract/src/auth/device-authorization.ts
+var BUSABASE_CLI_CLIENT_ID = "busabase-cli";
+
+// src/login.ts
 import { DEFAULT_BASE_URL, normalizeBaseUrl } from "busabase-sdk";
-var CLI_CLIENT_ID = "busabase-cli";
 var CLI_CLIENT_PLATFORM = "cli";
 var OAUTH_TIMEOUT_MS = 5 * 60 * 1e3;
 var EXPIRES_AT_KEY = "BUSABASE_TOKEN_EXPIRES_AT";
-var SESSION_TOKEN_PREFIX = "bss_";
+var LEGACY_SESSION_TOKEN_PREFIX = "bss_";
 var AUTO_REFRESH_THRESHOLD_MS = 2 * 24 * 60 * 60 * 1e3;
 var DEFAULT_LOCAL_URL = "http://localhost:15419";
 var base64url = (buffer) => buffer.toString("base64url");
@@ -272,9 +836,9 @@ async function verifyAuth(baseUrl, token) {
   }
   return await res.json();
 }
-async function oauthLogin(baseUrl, useBrowser) {
+async function loopbackOauthLogin(baseUrl, useBrowser) {
   const codeVerifier = base64url(randomBytes(32));
-  const codeChallenge = base64url(createHash("sha256").update(codeVerifier).digest());
+  const codeChallenge = base64url(createHash4("sha256").update(codeVerifier).digest());
   const state = base64url(randomBytes(16));
   const { code, redirectUri } = await new Promise(
     (resolve, reject) => {
@@ -327,7 +891,7 @@ async function oauthLogin(baseUrl, useBrowser) {
         const redirect = `http://127.0.0.1:${port}/callback`;
         const authorizeUrl = new URL(`${baseUrl}/api/oauth/authorize`);
         authorizeUrl.searchParams.set("response_type", "code");
-        authorizeUrl.searchParams.set("client_id", CLI_CLIENT_ID);
+        authorizeUrl.searchParams.set("client_id", BUSABASE_CLI_CLIENT_ID);
         authorizeUrl.searchParams.set("client_platform", CLI_CLIENT_PLATFORM);
         authorizeUrl.searchParams.set("code_challenge", codeChallenge);
         authorizeUrl.searchParams.set("code_challenge_method", "S256");
@@ -352,7 +916,7 @@ async function oauthLogin(baseUrl, useBrowser) {
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
       grant_type: "authorization_code",
-      client_id: CLI_CLIENT_ID,
+      client_id: BUSABASE_CLI_CLIENT_ID,
       client_platform: CLI_CLIENT_PLATFORM,
       code,
       code_verifier: codeVerifier,
@@ -367,7 +931,110 @@ async function oauthLogin(baseUrl, useBrowser) {
   const payload = await tokenRes.json();
   const token = payload.apiKey ?? payload.token ?? payload.accessToken;
   if (!token) throw new Error("Token exchange returned no credential.");
-  return { token, expiresAt: payload.expiresAt ?? void 0 };
+  return payload.apiKey ? { token, apiKeyExpiresAt: payload.expiresAt ?? void 0 } : { token, expiresAt: payload.expiresAt ?? void 0 };
+}
+var delay = (durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs));
+async function readDeviceResponse(response) {
+  return await response.json().catch(() => ({}));
+}
+async function deviceLogin(baseUrl, useBrowser) {
+  const origin = new URL(baseUrl).origin;
+  let codeResponse;
+  try {
+    codeResponse = await fetch(`${baseUrl}/api/auth/device/code`, {
+      method: "POST",
+      headers: { "content-type": "application/json", origin },
+      body: JSON.stringify({
+        client_id: BUSABASE_CLI_CLIENT_ID,
+        scope: "openid profile email"
+      })
+    });
+  } catch {
+    throw new Error(`Could not start device sign-in because ${baseUrl} could not be reached.`);
+  }
+  const code = await codeResponse.json().catch(() => ({}));
+  if (!codeResponse.ok) {
+    throw new Error(
+      `Could not start device sign-in (HTTP ${codeResponse.status})${code.error_description ? `: ${code.error_description}` : "."}`
+    );
+  }
+  if (!code.device_code || !code.user_code || !code.verification_uri) {
+    throw new Error("Device sign-in returned an incomplete authorization response.");
+  }
+  const verificationUrl = code.verification_uri_complete ?? code.verification_uri;
+  say("");
+  say("Authorize Busabase CLI in any browser:");
+  say(`  ${code.verification_uri}`);
+  say(`  Code: ${code.user_code}`);
+  say("");
+  if (useBrowser) openBrowser(verificationUrl);
+  say("Waiting for authorization\u2026");
+  const expiresInSeconds = Math.max(1, code.expires_in ?? 15 * 60);
+  const deadline = Date.now() + expiresInSeconds * 1e3;
+  let intervalSeconds = Math.max(1, code.interval ?? 5);
+  let consecutiveNetworkFailures = 0;
+  while (Date.now() < deadline) {
+    await delay(intervalSeconds * 1e3);
+    let tokenResponse;
+    try {
+      tokenResponse = await fetch(`${baseUrl}/api/auth/device/token`, {
+        method: "POST",
+        headers: { "content-type": "application/json", origin },
+        body: JSON.stringify({
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          device_code: code.device_code,
+          client_id: BUSABASE_CLI_CLIENT_ID
+        })
+      });
+      consecutiveNetworkFailures = 0;
+    } catch {
+      consecutiveNetworkFailures += 1;
+      if (consecutiveNetworkFailures >= 3) {
+        throw new Error(
+          "Device sign-in lost its network connection. Check connectivity and run `busabase-cli login` again."
+        );
+      }
+      continue;
+    }
+    const payload = await readDeviceResponse(tokenResponse);
+    if (tokenResponse.ok && payload.access_token) {
+      const finalizeResponse = await fetch(`${baseUrl}/api/v1/device/finalize`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${payload.access_token}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({ deviceCode: code.device_code })
+      });
+      const finalized = await finalizeResponse.json().catch(() => ({}));
+      if (!finalizeResponse.ok || !finalized.apiKey || finalized.credentialType !== "api_key") {
+        const finalizeError = typeof finalized.error === "string" ? finalized.error : finalized.error?.message ?? finalized.message;
+        throw new Error(
+          `Device sign-in could not finalize the selected API key${finalizeError ? `: ${finalizeError}` : ` (HTTP ${finalizeResponse.status})`}.`
+        );
+      }
+      return {
+        token: finalized.apiKey,
+        apiKeyExpiresAt: finalized.expiresAt ?? void 0
+      };
+    }
+    switch (payload.error) {
+      case "authorization_pending":
+        continue;
+      case "slow_down":
+        intervalSeconds += 5;
+        continue;
+      case "access_denied":
+        throw new Error("Device sign-in was denied. No credential was saved.");
+      case "expired_token":
+        throw new Error("The device code expired. Run `busabase-cli login` to request a new one.");
+      default:
+        throw new Error(
+          `Device sign-in failed${payload.error_description ? `: ${payload.error_description}` : ` (HTTP ${tokenResponse.status})`}.`
+        );
+    }
+  }
+  throw new Error("The device code expired. Run `busabase-cli login` to request a new one.");
 }
 async function refreshToken(baseUrl, token) {
   const res = await fetch(`${baseUrl}/api/oauth/refresh`, {
@@ -412,12 +1079,12 @@ async function chooseTarget() {
   say("How should this CLI connect?");
   say("  1. Local/Desktop on this computer \u2014 no account, no login");
   say("     Use when you run `busabase server` or the Busabase Desktop app locally.");
-  say("  2. Busabase Cloud \u2014 browser sign-in (recommended)");
-  say("     Best for humans: opens the browser and saves a refreshable CLI session.");
+  say("  2. Busabase Cloud \u2014 device sign-in (recommended)");
+  say("     Works locally, over SSH, and in containers; approve from any browser.");
   say("  3. Busabase Cloud \u2014 paste an API key");
   say("     Best for CI, servers, or agents where a browser is not available.");
-  say("  4. Self-hosted Busabase \u2014 browser sign-in");
-  say("     Use your team's Busabase URL when it supports OAuth login.");
+  say("  4. Self-hosted Busabase \u2014 device sign-in");
+  say("     Use your team's Busabase URL when it supports device authorization.");
   say("  5. Self-hosted Busabase \u2014 paste an API key");
   say("     Use your team's Busabase URL with a long-lived key for automation.");
   const choice = await ask("Choose 1-5 [2]: ");
@@ -434,11 +1101,11 @@ async function chooseTarget() {
     case "3":
       return { baseUrl: cloud, method: "api-key" };
     case "4":
-      return { baseUrl: await askSelfHostedUrl(), method: "oauth" };
+      return { baseUrl: await askSelfHostedUrl(), method: "device" };
     case "5":
       return { baseUrl: await askSelfHostedUrl(), method: "api-key" };
     default:
-      return { baseUrl: cloud, method: "oauth" };
+      return { baseUrl: cloud, method: "device" };
   }
 }
 async function runLogin(options) {
@@ -447,14 +1114,16 @@ async function runLogin(options) {
   let method;
   if (apiKey) {
     method = "api-key";
+  } else if (options.deviceCode) {
+    method = "device";
   } else if (options.oauth) {
-    method = "oauth";
+    method = "loopback-oauth";
   } else if (isInteractive()) {
     const target = await chooseTarget();
     baseUrl = normalizeBaseUrl(target.baseUrl);
     method = target.method;
   } else {
-    method = isLocalHost(baseUrl) ? "none" : "oauth";
+    method = isLocalHost(baseUrl) ? "none" : "device";
   }
   if (method === "none") {
     if (await probeAuthRequired(baseUrl)) {
@@ -474,10 +1143,16 @@ async function runLogin(options) {
   }
   let token;
   let expiresAt;
-  if (method === "oauth") {
-    const result = await oauthLogin(baseUrl, options.browser);
+  let apiKeyExpiresAt;
+  if (method === "device") {
+    const result = await deviceLogin(baseUrl, options.browser);
+    token = result.token;
+    apiKeyExpiresAt = result.apiKeyExpiresAt;
+  } else if (method === "loopback-oauth") {
+    const result = await loopbackOauthLogin(baseUrl, options.browser);
     token = result.token;
     expiresAt = result.expiresAt;
+    apiKeyExpiresAt = result.apiKeyExpiresAt;
   } else {
     if (!apiKey) {
       say("Create a key in the dashboard \u2192 Settings \u2192 API Keys (shown once).");
@@ -500,10 +1175,13 @@ async function runLogin(options) {
   say(`\u2713 Signed in and saved to ${dotEnvPath()}`);
   return {
     status: "signed in",
-    method,
+    method: method === "loopback-oauth" ? "oauth" : method,
+    credentialType: method === "device" ? "api_key" : expiresAt ? "session" : "api_key",
     user: verify.user?.email ?? verify.user?.name ?? verify.user?.id ?? "(unknown)",
     space: spaceId ?? "(server default)",
-    expiresAt: expiresAt ?? "(no expiry \u2014 API key)",
+    createdSpace: String(Boolean(verify.createdSpace)),
+    bootstrapRequired: String(Boolean(verify.bootstrapRequired)),
+    expiresAt: expiresAt ?? apiKeyExpiresAt ?? "(no expiry \u2014 API key)",
     baseUrl,
     config: dotEnvPath()
   };
@@ -512,10 +1190,12 @@ async function runRefresh(options) {
   const baseUrl = normalizeBaseUrl(options.baseUrl);
   const token = options.apiKey;
   if (!token) throw new Error("Not signed in \u2014 run `busabase-cli login` first.");
-  if (!token.startsWith(SESSION_TOKEN_PREFIX)) {
+  const file = loadDotEnvFile();
+  const isSavedExpiringSession = file.BUSABASE_API_KEY === token && Boolean(file.BUSABASE_TOKEN_EXPIRES_AT);
+  if (!token.startsWith(LEGACY_SESSION_TOKEN_PREFIX) && !isSavedExpiringSession) {
     return {
       status: "nothing to refresh",
-      detail: "This credential is an API key, which doesn't expire. Only OAuth sessions refresh."
+      detail: "This credential is an API key and cannot be refreshed. Only OAuth sessions refresh."
     };
   }
   let refreshed;
@@ -541,13 +1221,14 @@ async function runRefresh(options) {
   };
 }
 async function maybeAutoRefresh(baseUrl, apiKey) {
-  if (!apiKey?.startsWith(SESSION_TOKEN_PREFIX)) return;
+  if (!apiKey) return;
   const file = loadDotEnvFile();
   if (file.BUSABASE_API_KEY !== apiKey) return;
   const expiresRaw = file[EXPIRES_AT_KEY];
   if (!expiresRaw) return;
   const expiresAt = Date.parse(expiresRaw);
   if (Number.isNaN(expiresAt)) return;
+  if (expiresAt <= Date.now()) return;
   if (expiresAt - Date.now() > AUTO_REFRESH_THRESHOLD_MS) return;
   try {
     const refreshed = await refreshToken(normalizeBaseUrl(baseUrl), apiKey);
@@ -558,11 +1239,25 @@ async function maybeAutoRefresh(baseUrl, apiKey) {
   } catch {
   }
 }
+function assertCredentialNotExpired(apiKey) {
+  if (!apiKey) return;
+  const file = loadDotEnvFile();
+  if (file.BUSABASE_API_KEY !== apiKey) return;
+  const expiresRaw = file[EXPIRES_AT_KEY];
+  if (!expiresRaw) return;
+  const expiresAt = Date.parse(expiresRaw);
+  if (!Number.isNaN(expiresAt) && expiresAt <= Date.now()) {
+    throw new Error(
+      "Your saved device login has expired. Run `busabase-cli login --device-code` to authorize this CLI again."
+    );
+  }
+}
 async function runLogout(options) {
   const baseUrl = normalizeBaseUrl(options.baseUrl);
   const token = options.apiKey;
   let revoked = "no session to revoke";
-  if (token?.startsWith("bss_")) {
+  const file = loadDotEnvFile();
+  if (token && (token.startsWith(LEGACY_SESSION_TOKEN_PREFIX) || file.BUSABASE_API_KEY === token && file[EXPIRES_AT_KEY])) {
     try {
       const res = await fetch(`${baseUrl}/api/oauth/revoke`, {
         method: "POST",
@@ -585,34 +1280,34 @@ import { readFile } from "fs/promises";
 import { join as join3 } from "path";
 
 // ../../packages/busabase-contract/src/domains/package/types.ts
-import { z as z6 } from "zod";
+import { z as z8 } from "zod";
 
 // ../../packages/openlib/i18n/i-string.ts
-import { z as z2 } from "zod";
+import { z as z4 } from "zod";
 
 // ../../packages/openlib/i18n/i18n.ts
-import { z } from "zod";
+import { z as z3 } from "zod";
 var i18n = {
   defaultLocale: "en",
   locales: ["en", "zh-CN", "zh-TW", "ja", "ko", "de", "fr", "es", "pt"],
   extendLocales: ["en", "zh-CN", "zh-TW", "ja", "ko", "fr", "de", "es", "ru", "it", "vi", "pt"]
 };
-var LocaleSchema = z.enum(i18n.locales);
+var LocaleSchema = z3.enum(i18n.locales);
 
 // ../../packages/openlib/i18n/i-string.ts
-var iStringRecordSchema = z2.partialRecord(LocaleSchema, z2.string());
-var iStringSchema = z2.union([z2.string(), iStringRecordSchema]).describe("i18n string");
+var iStringRecordSchema = z4.partialRecord(LocaleSchema, z4.string());
+var iStringSchema = z4.union([z4.string(), iStringRecordSchema]).describe("i18n string");
 
 // ../../packages/busabase-contract/src/domains/base/contract/base-schemas.ts
-import { z as z3 } from "zod";
-var fieldNameSchema = z3.union([
-  z3.string().min(1),
+import { z as z5 } from "zod";
+var fieldNameSchema = z5.union([
+  z5.string().min(1),
   iStringRecordSchema.refine(
     (record) => Object.values(record).some((value) => value && value.trim().length > 0),
     "field name must have at least one non-empty locale value"
   )
 ]);
-var fieldTypeSchema = z3.enum([
+var fieldTypeSchema = z5.enum([
   "text",
   "longtext",
   "markdown",
@@ -639,85 +1334,85 @@ var fieldTypeSchema = z3.enum([
   "json",
   "yaml"
 ]);
-var fieldOptionsSchema = z3.object({
-  ai: z3.object({
-    model: z3.string().optional(),
-    prompt: z3.string().optional(),
-    reviewRequired: z3.boolean().optional(),
-    sourceFieldIds: z3.array(z3.string()).optional()
+var fieldOptionsSchema = z5.object({
+  ai: z5.object({
+    model: z5.string().optional(),
+    prompt: z5.string().optional(),
+    reviewRequired: z5.boolean().optional(),
+    sourceFieldIds: z5.array(z5.string()).optional()
   }).optional(),
   // Per-field config for `attachment` columns (all optional; logic enforces a
   // 25MB ceiling regardless).
-  attachment: z3.object({
-    maxFiles: z3.number().int().positive().optional(),
-    allowedMimeTypes: z3.array(z3.string()).optional(),
-    maxFileSize: z3.number().int().positive().optional()
+  attachment: z5.object({
+    maxFiles: z5.number().int().positive().optional(),
+    allowedMimeTypes: z5.array(z5.string()).optional(),
+    maxFileSize: z5.number().int().positive().optional()
   }).optional(),
-  choices: z3.array(
-    z3.object({
-      color: z3.string().optional(),
-      id: z3.string(),
-      name: z3.string()
+  choices: z5.array(
+    z5.object({
+      color: z5.string().optional(),
+      id: z5.string(),
+      name: z5.string()
     })
   ).optional(),
-  code: z3.object({
-    language: z3.string().optional()
+  code: z5.object({
+    language: z5.string().optional()
   }).optional(),
-  embed: z3.object({
-    aspectRatio: z3.enum(["16:9", "4:3", "1:1"]).optional(),
-    height: z3.number().int().positive().max(1200).optional(),
-    providers: z3.array(z3.string()).optional()
+  embed: z5.object({
+    aspectRatio: z5.enum(["16:9", "4:3", "1:1"]).optional(),
+    height: z5.number().int().positive().max(1200).optional(),
+    providers: z5.array(z5.string()).optional()
   }).optional(),
-  inverseFieldId: z3.string().optional(),
-  multiple: z3.boolean().optional(),
+  inverseFieldId: z5.string().optional(),
+  multiple: z5.boolean().optional(),
   // Display formatting for `number` columns (Notion-style: one number type,
   // a format option). `currency` renders via Intl.NumberFormat.
-  number: z3.object({
-    format: z3.enum(["plain", "currency"]).optional(),
-    currency: z3.string().optional(),
-    locale: z3.string().optional()
+  number: z5.object({
+    format: z5.enum(["plain", "currency"]).optional(),
+    currency: z5.string().optional(),
+    locale: z5.string().optional()
   }).optional(),
-  targetBaseId: z3.string().optional().describe("Relation target Base id (bse_\u2026). Or pass targetBaseSlug to name it by slug."),
-  targetBaseSlug: z3.string().optional().describe(
+  targetBaseId: z5.string().optional().describe("Relation target Base id (bse_\u2026). Or pass targetBaseSlug to name it by slug."),
+  targetBaseSlug: z5.string().optional().describe(
     "Relation target Base by slug \u2014 a convenience alias for targetBaseId, resolved server-side (active bases in the current space). If both are given, targetBaseId wins."
   )
 }).default({});
-var baseFieldSchema = z3.object({
-  id: z3.string(),
-  baseId: z3.string(),
-  slug: z3.string(),
+var baseFieldSchema = z5.object({
+  id: z5.string(),
+  baseId: z5.string(),
+  slug: z5.string(),
   name: fieldNameSchema,
   type: fieldTypeSchema,
-  required: z3.boolean(),
-  position: z3.number(),
+  required: z5.boolean(),
+  position: z5.number(),
   options: fieldOptionsSchema
 });
-var baseSchema = z3.object({
-  id: z3.string(),
-  nodeId: z3.string(),
-  slug: z3.string(),
-  name: z3.string(),
-  description: z3.string(),
-  reviewPolicy: z3.object({
-    kind: z3.literal("single"),
-    requiredApprovals: z3.number()
+var baseSchema = z5.object({
+  id: z5.string(),
+  nodeId: z5.string(),
+  slug: z5.string(),
+  name: z5.string(),
+  description: z5.string(),
+  reviewPolicy: z5.object({
+    kind: z5.literal("single"),
+    requiredApprovals: z5.number()
   }),
-  createdAt: z3.string(),
-  fields: z3.array(baseFieldSchema)
+  createdAt: z5.string(),
+  fields: z5.array(baseFieldSchema)
 });
-var createBaseInputSchema = z3.object({
-  parentNodeId: z3.string().optional().describe(
+var createBaseInputSchema = z5.object({
+  parentNodeId: z5.string().optional().describe(
     "Parent node id. Must be a folder or the space root; container-incapable node types (Base, Doc, AirApp, etc.) cannot hold children."
   ),
-  slug: z3.string().min(1).regex(/^[a-z0-9-]+$/),
-  name: z3.string().min(1),
-  description: z3.string().optional().default(""),
-  fields: z3.array(
-    z3.object({
-      slug: z3.string().min(1),
+  slug: z5.string().min(1).regex(/^[a-z0-9-]+$/),
+  name: z5.string().min(1),
+  description: z5.string().optional().default(""),
+  fields: z5.array(
+    z5.object({
+      slug: z5.string().min(1),
       name: fieldNameSchema,
       type: fieldTypeSchema.default("text"),
-      required: z3.boolean().default(false),
+      required: z5.boolean().default(false),
       options: fieldOptionsSchema.optional().default({})
     })
   ).default([]),
@@ -725,78 +1420,78 @@ var createBaseInputSchema = z3.object({
   // as a pending ChangeRequest (status "in_review") instead of creating it
   // immediately. Pass `autoMerge: true` only for callers that don't need human
   // review (seed/migration scripts, an explicit no-review agent task).
-  autoMerge: z3.boolean().optional().default(false)
+  autoMerge: z5.boolean().optional().default(false)
 });
-var createBaseFieldInputSchema = z3.object({
+var createBaseFieldInputSchema = z5.object({
   name: fieldNameSchema,
   // Field slugs are snake_case identifiers (e.g. `cover_image`, `publish_date`) — the
   // seed and the inline-fields path on `POST /bases` already allow underscores, so the
   // add-field endpoint must too. (Base/folder/view slugs stay kebab-case: they go in URLs.)
-  slug: z3.string().min(1).regex(/^[a-z0-9_-]+$/),
+  slug: z5.string().min(1).regex(/^[a-z0-9_-]+$/),
   type: fieldTypeSchema.default("text"),
-  required: z3.boolean().optional().default(false),
+  required: z5.boolean().optional().default(false),
   options: fieldOptionsSchema.optional().default({})
 });
 var createFieldChangeRequestInputSchema = createBaseFieldInputSchema.extend({
-  message: z3.string().optional().default("Add field"),
-  submittedBy: z3.string().optional().default("local-editor")
+  message: z5.string().optional().default("Add field"),
+  submittedBy: z5.string().optional().default("local-editor")
 });
-var deleteFieldChangeRequestInputSchema = z3.object({
-  fieldId: z3.string().min(1),
-  message: z3.string().optional(),
-  submittedBy: z3.string().optional().default("local-editor")
+var deleteFieldChangeRequestInputSchema = z5.object({
+  fieldId: z5.string().min(1),
+  message: z5.string().optional(),
+  submittedBy: z5.string().optional().default("local-editor")
 });
-var updateFieldChangeRequestInputSchema = z3.object({
-  fieldId: z3.string().min(1),
-  patch: z3.object({
+var updateFieldChangeRequestInputSchema = z5.object({
+  fieldId: z5.string().min(1),
+  patch: z5.object({
     name: fieldNameSchema.optional(),
-    required: z3.boolean().optional(),
+    required: z5.boolean().optional(),
     options: fieldOptionsSchema.optional()
   }),
-  message: z3.string().optional(),
-  submittedBy: z3.string().optional().default("local-editor")
+  message: z5.string().optional(),
+  submittedBy: z5.string().optional().default("local-editor")
 });
-var previewFieldConversionInputSchema = z3.object({
-  fieldId: z3.string().min(1),
+var previewFieldConversionInputSchema = z5.object({
+  fieldId: z5.string().min(1),
   newType: fieldTypeSchema
 });
-var previewFieldConversionOutputSchema = z3.object({
-  totalCount: z3.number(),
-  convertibleCount: z3.number(),
-  nullCount: z3.number(),
-  conflicts: z3.array(z3.object({ recordId: z3.string(), currentValue: z3.unknown() }))
+var previewFieldConversionOutputSchema = z5.object({
+  totalCount: z5.number(),
+  convertibleCount: z5.number(),
+  nullCount: z5.number(),
+  conflicts: z5.array(z5.object({ recordId: z5.string(), currentValue: z5.unknown() }))
 });
-var convertFieldChangeRequestInputSchema = z3.object({
-  fieldId: z3.string().min(1),
+var convertFieldChangeRequestInputSchema = z5.object({
+  fieldId: z5.string().min(1),
   newType: fieldTypeSchema,
-  selectChoiceMode: z3.enum(["auto_create", "null_on_missing"]).default("null_on_missing"),
-  message: z3.string().optional(),
-  submittedBy: z3.string().optional().default("local-editor")
+  selectChoiceMode: z5.enum(["auto_create", "null_on_missing"]).default("null_on_missing"),
+  message: z5.string().optional(),
+  submittedBy: z5.string().optional().default("local-editor")
 });
-var reorderFieldsChangeRequestInputSchema = z3.object({
-  fieldIds: z3.array(z3.string()).min(1),
-  message: z3.string().optional(),
-  submittedBy: z3.string().optional().default("local-editor")
+var reorderFieldsChangeRequestInputSchema = z5.object({
+  fieldIds: z5.array(z5.string()).min(1),
+  message: z5.string().optional(),
+  submittedBy: z5.string().optional().default("local-editor")
 });
-var archiveBaseInputSchema = z3.object({
-  message: z3.string().optional(),
-  submittedBy: z3.string().optional().default("local-editor")
+var archiveBaseInputSchema = z5.object({
+  message: z5.string().optional(),
+  submittedBy: z5.string().optional().default("local-editor")
 });
-var restoreBaseInputSchema = z3.object({
-  message: z3.string().optional(),
-  submittedBy: z3.string().optional().default("local-editor")
+var restoreBaseInputSchema = z5.object({
+  message: z5.string().optional(),
+  submittedBy: z5.string().optional().default("local-editor")
 });
-var restoreFieldChangeRequestInputSchema = z3.object({
-  fieldId: z3.string().min(1),
-  message: z3.string().optional(),
-  submittedBy: z3.string().optional().default("local-editor")
+var restoreFieldChangeRequestInputSchema = z5.object({
+  fieldId: z5.string().min(1),
+  message: z5.string().optional(),
+  submittedBy: z5.string().optional().default("local-editor")
 });
 
 // ../../packages/busabase-contract/src/domains/base/contract/view-schemas.ts
-import { z as z5 } from "zod";
+import { z as z7 } from "zod";
 
 // ../../packages/busabase-contract/src/contract/schemas.ts
-import { z as z4 } from "zod";
+import { z as z6 } from "zod";
 
 // ../../packages/busabase-contract/src/domains/filetree/definition.ts
 var fileTreeOperations = (type) => [
@@ -1025,128 +1720,144 @@ var OPERATION_META = Object.fromEntries(
 );
 
 // ../../packages/busabase-contract/src/contract/schemas.ts
-var nodeSchema = z4.lazy(
-  () => z4.object({
-    id: z4.string(),
-    parentId: z4.string().nullable(),
-    type: z4.enum(NODE_TYPES),
-    slug: z4.string(),
-    name: z4.string(),
-    description: z4.string(),
-    metadata: z4.object({
-      entryFile: z4.string().optional(),
-      visibility: z4.enum(["private", "workspace", "public"]).optional(),
-      version: z4.string().optional(),
-      assetId: z4.string().optional()
-    }).default({}),
-    position: z4.number(),
-    createdAt: z4.string(),
-    updatedAt: z4.string(),
-    baseId: z4.string().nullable(),
-    children: z4.array(nodeSchema),
-    hasChildren: z4.boolean().optional()
+var nodeSchema = z6.lazy(
+  () => z6.object({
+    id: z6.string(),
+    parentId: z6.string().nullable(),
+    type: z6.enum(NODE_TYPES),
+    slug: z6.string(),
+    name: z6.string(),
+    description: z6.string(),
+    metadata: z6.object({
+      entryFile: z6.string().optional(),
+      visibility: z6.enum(["private", "workspace", "public"]).optional(),
+      version: z6.string().optional(),
+      assetId: z6.string().optional()
+    }).catchall(z6.unknown()).default({}),
+    position: z6.number(),
+    createdAt: z6.string(),
+    updatedAt: z6.string(),
+    baseId: z6.string().nullable(),
+    children: z6.array(nodeSchema),
+    hasChildren: z6.boolean().optional()
   })
 );
-var nodePrincipalSchema = z4.object({
-  id: z4.string(),
-  nodeId: z4.string(),
-  principalType: z4.enum(["user", "team", "space"]),
-  principalId: z4.string(),
-  role: z4.enum(["read", "changeRequest", "write", "manage"]),
-  grantedBy: z4.string(),
-  createdAt: z4.string(),
-  updatedAt: z4.string()
+var nodePrincipalSchema = z6.object({
+  id: z6.string(),
+  nodeId: z6.string(),
+  principalType: z6.enum(["user", "team", "space"]),
+  principalId: z6.string(),
+  role: z6.enum(["read", "changeRequest", "write", "manage"]),
+  grantedBy: z6.string(),
+  createdAt: z6.string(),
+  updatedAt: z6.string()
 });
-var listNodesInputSchema = z4.object({
-  parentId: z4.string().nullable().optional().describe("Node to start from. Omit or null to start from the space root."),
-  depth: z4.coerce.number().int().min(1).max(5).optional().describe(
+var listNodesInputSchema = z6.object({
+  parentId: z6.string().nullable().optional().describe("Node to start from. Omit or null to start from the space root."),
+  depth: z6.coerce.number().int().min(1).max(5).optional().describe(
     "How many levels beneath the start point to eagerly include (default 2 once either field is set). Capped at 5."
   )
 }).optional();
-var isDescendantInputSchema = z4.object({
-  nodeId: z4.string(),
-  potentialAncestorId: z4.string()
+var isDescendantInputSchema = z6.object({
+  nodeId: z6.string(),
+  potentialAncestorId: z6.string()
+});
+var isDescendantOutputSchema = z6.object({
+  isDescendant: z6.boolean()
+});
+var updateNodeMetadataInputSchema = z6.object({
+  nodeId: z6.string(),
+  metadata: z6.record(z6.string(), z6.unknown())
 });
-var isDescendantOutputSchema = z4.object({
-  isDescendant: z4.boolean()
+var searchNodesByNameInputSchema = z6.object({
+  query: z6.string().min(1),
+  limit: z6.number().int().min(1).max(50).optional().default(20)
 });
-var userRefSchema = z4.object({
-  id: z4.string(),
-  name: z4.string().nullable(),
-  email: z4.string().nullable(),
-  image: z4.string().nullable(),
-  role: z4.string().nullable().optional()
+var nodeSearchResultSchema = z6.object({
+  id: z6.string(),
+  type: z6.enum(NODE_TYPES),
+  name: z6.string(),
+  slug: z6.string(),
+  path: z6.string(),
+  updatedAt: z6.string()
 });
-var commitSchema = z4.object({
-  id: z4.string(),
-  baseId: z4.string().nullable(),
-  targetType: z4.enum(["base", "node"]),
-  nodeId: z4.string().nullable(),
-  operationId: z4.string().nullable(),
-  parentCommitId: z4.string().nullable(),
-  fields: z4.record(z4.string(), z4.unknown()),
-  operation: z4.enum(OPERATION_KINDS),
-  message: z4.string(),
-  author: z4.string(),
+var userRefSchema = z6.object({
+  id: z6.string(),
+  name: z6.string().nullable(),
+  email: z6.string().nullable(),
+  image: z6.string().nullable(),
+  role: z6.string().nullable().optional()
+});
+var commitSchema = z6.object({
+  id: z6.string(),
+  baseId: z6.string().nullable(),
+  targetType: z6.enum(["base", "node"]),
+  nodeId: z6.string().nullable(),
+  operationId: z6.string().nullable(),
+  parentCommitId: z6.string().nullable(),
+  fields: z6.record(z6.string(), z6.unknown()),
+  operation: z6.enum(OPERATION_KINDS),
+  message: z6.string(),
+  author: z6.string(),
   authorUser: userRefSchema.nullable().optional().default(null),
-  createdAt: z4.string()
+  createdAt: z6.string()
 });
-var operationSchema = z4.object({
-  id: z4.string(),
-  changeRequestId: z4.string(),
-  baseId: z4.string().nullable(),
-  targetType: z4.enum(["base", "node"]),
-  nodeId: z4.string().nullable(),
-  operation: z4.enum(OPERATION_KINDS),
-  status: z4.enum(["pending", "merged", "archived", "failed"]),
-  targetRecordId: z4.string().nullable(),
-  targetViewId: z4.string().nullable(),
-  filePath: z4.string().nullable(),
-  sourceRecordId: z4.string().nullable(),
-  sourceCommitId: z4.string().nullable(),
-  baseCommitId: z4.string().nullable(),
-  headCommitId: z4.string(),
-  deleteMode: z4.enum(["archive"]),
-  mergedRecordId: z4.string().nullable(),
-  mergedViewId: z4.string().nullable(),
-  position: z4.number(),
-  createdAt: z4.string(),
-  updatedAt: z4.string(),
+var operationSchema = z6.object({
+  id: z6.string(),
+  changeRequestId: z6.string(),
+  baseId: z6.string().nullable(),
+  targetType: z6.enum(["base", "node"]),
+  nodeId: z6.string().nullable(),
+  operation: z6.enum(OPERATION_KINDS),
+  status: z6.enum(["pending", "merged", "archived", "failed"]),
+  targetRecordId: z6.string().nullable(),
+  targetViewId: z6.string().nullable(),
+  filePath: z6.string().nullable(),
+  sourceRecordId: z6.string().nullable(),
+  sourceCommitId: z6.string().nullable(),
+  baseCommitId: z6.string().nullable(),
+  headCommitId: z6.string(),
+  deleteMode: z6.enum(["archive"]),
+  mergedRecordId: z6.string().nullable(),
+  mergedViewId: z6.string().nullable(),
+  position: z6.number(),
+  createdAt: z6.string(),
+  updatedAt: z6.string(),
   headCommit: commitSchema,
   // Resolved canonical "before" values for the operation's target, so the UI can
   // render a true before → after field diff. Null for creations (no prior state)
   // and for kinds whose prior state isn't a field map (e.g. skill files, whose
   // previous content lives in storage). Records resolve from the base commit;
   // views resolve from the current view row ({ name, description, config }).
-  baseFields: z4.record(z4.string(), z4.unknown()).nullable()
+  baseFields: z6.record(z6.string(), z6.unknown()).nullable()
 });
-var reviewSchema = z4.object({
-  id: z4.string(),
-  changeRequestId: z4.string(),
-  reviewerId: z4.string(),
+var reviewSchema = z6.object({
+  id: z6.string(),
+  changeRequestId: z6.string(),
+  reviewerId: z6.string(),
   reviewer: userRefSchema.nullable().optional().default(null),
-  verdict: z4.enum(["approved", "rejected"]),
-  reason: z4.string().nullable(),
-  visibleOperationHeads: z4.record(z4.string(), z4.string()),
-  createdAt: z4.string()
+  verdict: z6.enum(["approved", "rejected"]),
+  reason: z6.string().nullable(),
+  visibleOperationHeads: z6.record(z6.string(), z6.string()),
+  createdAt: z6.string()
 });
-var commentSubjectTypeSchema = z4.enum(["record", "change_request", "operation", "commit"]);
-var commentSchema = z4.object({
-  id: z4.string(),
+var commentSubjectTypeSchema = z6.enum(["record", "change_request", "operation", "commit"]);
+var commentSchema = z6.object({
+  id: z6.string(),
   subjectType: commentSubjectTypeSchema,
-  subjectId: z4.string(),
-  recordId: z4.string().nullable(),
-  changeRequestId: z4.string().nullable(),
-  operationId: z4.string().nullable(),
-  commitId: z4.string().nullable(),
-  authorId: z4.string(),
+  subjectId: z6.string(),
+  recordId: z6.string().nullable(),
+  changeRequestId: z6.string().nullable(),
+  operationId: z6.string().nullable(),
+  commitId: z6.string().nullable(),
+  authorId: z6.string(),
   author: userRefSchema.nullable().optional().default(null),
-  body: z4.string(),
-  mentionsAi: z4.boolean(),
-  createdAt: z4.string(),
-  updatedAt: z4.string()
+  body: z6.string(),
+  mentionsAi: z6.boolean(),
+  createdAt: z6.string(),
+  updatedAt: z6.string()
 });
-var changeRequestStatusSchema = z4.enum([
+var changeRequestStatusSchema = z6.enum([
   "in_review",
   "changes_requested",
   "approved",
@@ -1155,53 +1866,53 @@ var changeRequestStatusSchema = z4.enum([
   "abandoned",
   "conflict"
 ]);
-var changeRequestSchema = z4.object({
-  id: z4.string(),
-  baseId: z4.string().nullable(),
-  targetType: z4.enum(["base", "node"]),
-  nodeId: z4.string().nullable(),
+var changeRequestSchema = z6.object({
+  id: z6.string(),
+  baseId: z6.string().nullable(),
+  targetType: z6.enum(["base", "node"]),
+  nodeId: z6.string().nullable(),
   status: changeRequestStatusSchema,
-  submittedBy: z4.string(),
+  submittedBy: z6.string(),
   submittedByUser: userRefSchema.nullable().optional().default(null),
-  sourceMeta: z4.record(z4.string(), z4.unknown()),
-  reviewPolicySnapshot: z4.record(z4.string(), z4.unknown()),
-  mergeSummary: z4.record(z4.string(), z4.unknown()),
-  rejectedReason: z4.string().nullable(),
-  reviewedAt: z4.string().nullable(),
-  mergedAt: z4.string().nullable(),
-  createdAt: z4.string(),
-  updatedAt: z4.string(),
+  sourceMeta: z6.record(z6.string(), z6.unknown()),
+  reviewPolicySnapshot: z6.record(z6.string(), z6.unknown()),
+  mergeSummary: z6.record(z6.string(), z6.unknown()),
+  rejectedReason: z6.string().nullable(),
+  reviewedAt: z6.string().nullable(),
+  mergedAt: z6.string().nullable(),
+  createdAt: z6.string(),
+  updatedAt: z6.string(),
   base: baseSchema.nullable(),
   node: nodeSchema.nullable(),
-  operations: z4.array(operationSchema),
+  operations: z6.array(operationSchema),
   primaryOperation: operationSchema.nullable(),
-  operationCount: z4.number(),
-  reviews: z4.array(reviewSchema)
+  operationCount: z6.number(),
+  reviews: z6.array(reviewSchema)
 });
-var agentTaskSchema = z4.object({
+var agentTaskSchema = z6.object({
   changeRequest: changeRequestSchema,
-  trigger: z4.enum(["changes_requested", "ai_mention"]),
-  reviewReason: z4.string().nullable(),
-  aiComments: z4.array(commentSchema)
+  trigger: z6.enum(["changes_requested", "ai_mention"]),
+  reviewReason: z6.string().nullable(),
+  aiComments: z6.array(commentSchema)
 });
-var searchResultSchema = z4.object({
-  id: z4.string(),
-  kind: z4.enum(["record", "change_request", "base", "file"]),
-  title: z4.string(),
-  body: z4.string(),
-  eyebrow: z4.string(),
-  href: z4.string(),
-  updatedAt: z4.string().nullable()
+var searchResultSchema = z6.object({
+  id: z6.string(),
+  kind: z6.enum(["record", "change_request", "base", "file"]),
+  title: z6.string(),
+  body: z6.string(),
+  eyebrow: z6.string(),
+  href: z6.string(),
+  updatedAt: z6.string().nullable()
 });
-var searchResponseSchema = z4.object({
-  query: z4.string(),
-  limit: z4.number(),
-  offset: z4.number(),
-  hasMore: z4.boolean(),
-  results: z4.array(searchResultSchema)
+var searchResponseSchema = z6.object({
+  query: z6.string(),
+  limit: z6.number(),
+  offset: z6.number(),
+  hasMore: z6.boolean(),
+  results: z6.array(searchResultSchema)
 });
-var liveEventSchema = z4.object({
-  kind: z4.enum([
+var liveEventSchema = z6.object({
+  kind: z6.enum([
     "change_request.created",
     "change_request.updated",
     "change_request.deleted",
@@ -1215,16 +1926,16 @@ var liveEventSchema = z4.object({
     // busabase-cloud's host hook to persist an inbox notification row.
     "change_request.pending_review"
   ]),
-  spaceId: z4.string(),
-  actorId: z4.string(),
-  changeRequestId: z4.string(),
-  baseId: z4.string().nullable(),
-  nodeIds: z4.array(z4.string()),
-  recordIds: z4.array(z4.string()),
-  viewIds: z4.array(z4.string()),
-  operationCount: z4.number()
+  spaceId: z6.string(),
+  actorId: z6.string(),
+  changeRequestId: z6.string(),
+  baseId: z6.string().nullable(),
+  nodeIds: z6.array(z6.string()),
+  recordIds: z6.array(z6.string()),
+  viewIds: z6.array(z6.string()),
+  operationCount: z6.number()
 });
-var auditActionSchema = z4.enum([
+var auditActionSchema = z6.enum([
   "record.viewed",
   "change_request.created",
   "change_request.updated",
@@ -1246,157 +1957,158 @@ var auditActionSchema = z4.enum([
   "asset.metadata_updated",
   "asset.text_written",
   "asset.text_marked_none",
+  "node.metadata_updated",
   "node.purged"
 ]);
-var auditEventSchema = z4.object({
-  id: z4.string(),
+var auditEventSchema = z6.object({
+  id: z6.string(),
   action: auditActionSchema,
-  actorId: z4.string(),
+  actorId: z6.string(),
   actor: userRefSchema.nullable().optional().default(null),
-  baseId: z4.string().nullable(),
-  recordId: z4.string().nullable(),
-  changeRequestId: z4.string().nullable(),
-  operationId: z4.string().nullable(),
-  commitId: z4.string().nullable(),
-  metadata: z4.record(z4.string(), z4.unknown()),
-  createdAt: z4.string()
+  baseId: z6.string().nullable(),
+  recordId: z6.string().nullable(),
+  changeRequestId: z6.string().nullable(),
+  operationId: z6.string().nullable(),
+  commitId: z6.string().nullable(),
+  metadata: z6.record(z6.string(), z6.unknown()),
+  createdAt: z6.string()
 });
-var createAuditEventInputSchema = z4.object({
+var createAuditEventInputSchema = z6.object({
   action: auditActionSchema,
-  actorId: z4.string().optional().default("local-viewer"),
-  baseId: z4.string().optional().nullable(),
-  recordId: z4.string().optional().nullable(),
-  changeRequestId: z4.string().optional().nullable(),
-  operationId: z4.string().optional().nullable(),
-  commitId: z4.string().optional().nullable(),
-  metadata: z4.record(z4.string(), z4.unknown()).optional().default({})
+  actorId: z6.string().optional().default("local-viewer"),
+  baseId: z6.string().optional().nullable(),
+  recordId: z6.string().optional().nullable(),
+  changeRequestId: z6.string().optional().nullable(),
+  operationId: z6.string().optional().nullable(),
+  commitId: z6.string().optional().nullable(),
+  metadata: z6.record(z6.string(), z6.unknown()).optional().default({})
 });
-var nodeOperationInputSchema = z4.discriminatedUnion("kind", [
-  z4.object({
-    kind: z4.literal("create"),
-    ref: z4.string().min(1).optional().describe(
+var nodeOperationInputSchema = z6.discriminatedUnion("kind", [
+  z6.object({
+    kind: z6.literal("create"),
+    ref: z6.string().min(1).optional().describe(
       'Optional in-change-request temp id for this node. A later operation can set parentNodeRef to this value to nest under it \u2014 e.g. create a folder with ref "growth", then create Bases with parentNodeRef "growth", all in one change request.'
     ),
-    parentNodeId: z4.string().optional(),
-    parentNodeRef: z4.string().min(1).optional().describe(
+    parentNodeId: z6.string().optional(),
+    parentNodeRef: z6.string().min(1).optional().describe(
       "Parent this node under a node an EARLIER operation in the same change request created (matched by its ref). Mutually exclusive with parentNodeId."
     ),
-    nodeType: z4.enum(CREATABLE_NODE_TYPES),
-    slug: z4.string().min(1).regex(/^[a-z0-9-]+$/),
-    name: z4.string().min(1),
-    description: z4.string().optional().default(""),
-    metadata: z4.record(z4.string(), z4.unknown()).optional().default({}),
+    nodeType: z6.enum(CREATABLE_NODE_TYPES),
+    slug: z6.string().min(1).regex(/^[a-z0-9-]+$/),
+    name: z6.string().min(1),
+    description: z6.string().optional().default(""),
+    metadata: z6.record(z6.string(), z6.unknown()).optional().default({}),
     // Base fields (nodeType "base" only); a base needs at least one field.
-    fields: z4.array(
-      z4.object({
-        slug: z4.string().min(1).regex(/^[a-z0-9-]+$/),
+    fields: z6.array(
+      z6.object({
+        slug: z6.string().min(1).regex(/^[a-z0-9-]+$/),
         name: fieldNameSchema,
         type: fieldTypeSchema.default("text"),
-        required: z4.boolean().optional().default(false),
+        required: z6.boolean().optional().default(false),
         options: fieldOptionsSchema.optional().default({})
       })
     ).optional()
   }),
-  z4.object({
-    kind: z4.literal("rename"),
-    nodeId: z4.string(),
-    slug: z4.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
-    name: z4.string().min(1).optional(),
-    description: z4.string().optional()
+  z6.object({
+    kind: z6.literal("rename"),
+    nodeId: z6.string(),
+    slug: z6.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
+    name: z6.string().min(1).optional(),
+    description: z6.string().optional()
   }),
-  z4.object({
-    kind: z4.literal("delete"),
-    nodeId: z4.string()
+  z6.object({
+    kind: z6.literal("delete"),
+    nodeId: z6.string()
   }),
-  z4.object({
-    kind: z4.literal("restore"),
-    nodeId: z4.string()
+  z6.object({
+    kind: z6.literal("restore"),
+    nodeId: z6.string()
   }),
-  z4.object({
-    kind: z4.literal("move"),
-    nodeId: z4.string(),
+  z6.object({
+    kind: z6.literal("move"),
+    nodeId: z6.string(),
     // Exactly one of parentNodeId / parentNodeRef (a ref created earlier in this CR).
-    parentNodeId: z4.string().optional(),
-    parentNodeRef: z4.string().min(1).optional(),
-    position: z4.number().int().optional()
+    parentNodeId: z6.string().optional(),
+    parentNodeRef: z6.string().min(1).optional(),
+    position: z6.number().int().optional()
   })
 ]);
-var createNodeChangeRequestInputSchema = z4.object({
-  message: z4.string().optional().default("Update node tree").describe(
+var createNodeChangeRequestInputSchema = z6.object({
+  message: z6.string().optional().default("Update node tree").describe(
     'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Reorganize marketing docs under a Campaigns folder".'
   ),
-  submittedBy: z4.string().optional().default("local-producer"),
-  autoMerge: z4.boolean().optional().default(false).describe(
+  submittedBy: z6.string().optional().default("local-producer"),
+  autoMerge: z6.boolean().optional().default(false).describe(
     "Whether to approve and merge this structural node change immediately. Defaults to false so node Change Request creation is review-first unless explicitly requested."
   ),
-  operations: z4.array(nodeOperationInputSchema).min(1)
+  operations: z6.array(nodeOperationInputSchema).min(1)
 });
-var moveNodeInputSchema = z4.object({
-  nodeId: z4.string(),
-  parentNodeId: z4.string().optional().describe("New parent folder node id. Omit to keep the current parent and only reorder."),
-  position: z4.number().int().optional().describe("New position among the target parent's children."),
-  message: z4.string().optional().describe("Reviewer-facing Change Request message."),
-  submittedBy: z4.string().optional()
+var moveNodeInputSchema = z6.object({
+  nodeId: z6.string(),
+  parentNodeId: z6.string().optional().describe("New parent folder node id. Omit to keep the current parent and only reorder."),
+  position: z6.number().int().optional().describe("New position among the target parent's children."),
+  message: z6.string().optional().describe("Reviewer-facing Change Request message."),
+  submittedBy: z6.string().optional()
 });
-var createDeleteChangeRequestInputSchema = z4.object({
-  message: z4.string().optional().default("Delete record").describe(
+var createDeleteChangeRequestInputSchema = z6.object({
+  message: z6.string().optional().default("Delete record").describe(
     'Explanation shown to the human reviewer. Say what is being removed and why, e.g. "Archive duplicate contact \u2014 merged into Acme Corp".'
   ),
-  submittedBy: z4.string().optional().default("local-producer"),
+  submittedBy: z6.string().optional().default("local-producer"),
   // Only "archive" is supported — hard delete after retention was never
   // implemented, so the API no longer accepts it (breaking change).
-  deleteMode: z4.enum(["archive"]).optional().default("archive")
+  deleteMode: z6.enum(["archive"]).optional().default("archive")
 });
-var reviseOperationInputSchema = z4.object({
-  fields: z4.record(z4.string(), z4.unknown()).describe(
+var reviseOperationInputSchema = z6.object({
+  fields: z6.record(z6.string(), z6.unknown()).describe(
     "Updated field values keyed by field slug. If you set the base's PRIMARY field (its first field), keep it a short human-readable name \u2014 it is the record's display title everywhere."
   ),
-  message: z4.string().optional().default("Revise operation").describe(
+  message: z6.string().optional().default("Revise operation").describe(
     'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Update deal stage to qualified \u2014 demo booked for July 8".'
   ),
-  author: z4.string().optional().default("local-producer"),
-  baseCommitId: z4.string().optional()
+  author: z6.string().optional().default("local-producer"),
+  baseCommitId: z6.string().optional()
 });
-var reviewChangeRequestInputSchema = z4.object({
-  verdict: z4.enum(["approved", "rejected"]),
-  reason: z4.string().optional()
+var reviewChangeRequestInputSchema = z6.object({
+  verdict: z6.enum(["approved", "rejected"]),
+  reason: z6.string().optional()
 });
-var commentSubjectInputSchema = z4.object({
+var commentSubjectInputSchema = z6.object({
   subjectType: commentSubjectTypeSchema,
-  subjectId: z4.string().min(1)
+  subjectId: z6.string().min(1)
 });
 var createCommentInputSchema = commentSubjectInputSchema.extend({
-  authorId: z4.string().optional().default("local-admin"),
-  body: z4.string().trim().min(1),
-  mentionsAi: z4.boolean().optional().default(false)
+  authorId: z6.string().optional().default("local-admin"),
+  body: z6.string().trim().min(1),
+  mentionsAi: z6.boolean().optional().default(false)
 });
-var listInputSchema = z4.object({
-  limit: z4.coerce.number().int().min(1).max(100).optional().default(50)
+var listInputSchema = z6.object({
+  limit: z6.coerce.number().int().min(1).max(100).optional().default(50)
 }).optional().default({ limit: 50 });
-var listChangeRequestsPagedInputSchema = z4.object({
-  limit: z4.coerce.number().int().min(1).max(100).optional().default(50),
+var listChangeRequestsPagedInputSchema = z6.object({
+  limit: z6.coerce.number().int().min(1).max(100).optional().default(50),
   /** Opaque base64 cursor (`createdAt|id`) for keyset pagination. */
-  cursor: z4.string().optional(),
-  status: z4.array(changeRequestStatusSchema).optional(),
-  mine: z4.boolean().optional()
+  cursor: z6.string().optional(),
+  status: z6.array(changeRequestStatusSchema).optional(),
+  mine: z6.boolean().optional()
 }).optional().default({ limit: 50 });
-var listChangeRequestsResponseSchema = z4.object({
-  changeRequests: z4.array(changeRequestSchema),
-  nextCursor: z4.string().nullable()
+var listChangeRequestsResponseSchema = z6.object({
+  changeRequests: z6.array(changeRequestSchema),
+  nextCursor: z6.string().nullable()
 });
-var changeRequestCountsSchema = z4.object({
-  review: z4.number().int().nonnegative(),
-  changes: z4.number().int().nonnegative(),
-  created: z4.number().int().nonnegative(),
-  approved: z4.number().int().nonnegative(),
-  merged: z4.number().int().nonnegative(),
-  rejected: z4.number().int().nonnegative()
+var changeRequestCountsSchema = z6.object({
+  review: z6.number().int().nonnegative(),
+  changes: z6.number().int().nonnegative(),
+  created: z6.number().int().nonnegative(),
+  approved: z6.number().int().nonnegative(),
+  merged: z6.number().int().nonnegative(),
+  rejected: z6.number().int().nonnegative()
 });
 var SEARCH_SOURCES = ["records", "files", "names"];
-var searchInputSchema = z4.object({
-  query: z4.string().default(""),
-  limit: z4.coerce.number().int().min(1).max(100).optional().default(20),
-  offset: z4.coerce.number().int().min(0).optional().default(0),
+var searchInputSchema = z6.object({
+  query: z6.string().default(""),
+  limit: z6.coerce.number().int().min(1).max(100).optional().default(20),
+  offset: z6.coerce.number().int().min(0).optional().default(0),
   /**
    * Restrict which content this call searches. Omitted means all three
    * (unchanged behavior for every caller before this parameter existed).
@@ -1406,26 +2118,26 @@ var searchInputSchema = z4.object({
    * (`?sources=records&sources=files`) becomes an array. Accept both shapes
    * and normalize to an array.
    */
-  sources: z4.union([z4.array(z4.enum(SEARCH_SOURCES)), z4.enum(SEARCH_SOURCES)]).transform((value) => Array.isArray(value) ? value : [value]).optional()
+  sources: z6.union([z6.array(z6.enum(SEARCH_SOURCES)), z6.enum(SEARCH_SOURCES)]).transform((value) => Array.isArray(value) ? value : [value]).optional()
 });
-var authSpaceSchema = z4.object({
-  id: z4.string(),
-  name: z4.string(),
-  slug: z4.string().nullable(),
-  plan: z4.string().nullable()
+var authSpaceSchema = z6.object({
+  id: z6.string(),
+  name: z6.string(),
+  slug: z6.string().nullable(),
+  plan: z6.string().nullable()
 });
-var authUserSchema = z4.object({
-  id: z4.string(),
-  name: z4.string(),
-  email: z4.string().nullable(),
-  image: z4.string().nullable()
+var authUserSchema = z6.object({
+  id: z6.string(),
+  name: z6.string(),
+  email: z6.string().nullable(),
+  image: z6.string().nullable()
 });
-var authMemberSchema = z4.object({
-  userId: z4.string(),
-  spaceId: z4.string(),
-  role: z4.string()
+var authMemberSchema = z6.object({
+  userId: z6.string(),
+  spaceId: z6.string(),
+  role: z6.string()
 });
-var authInfoSchema = z4.object({
+var authInfoSchema = z6.object({
   /** The space this request is scoped to (explicit `x-busabase-space` header, else the default). */
   space: authSpaceSchema,
   user: authUserSchema,
@@ -1435,11 +2147,15 @@ var authInfoSchema = z4.object({
    * space-scoped — when this has more than one entry, callers should confirm the
    * intended space and target it explicitly via the `x-busabase-space` header.
    */
-  spaces: z4.array(authSpaceSchema)
+  spaces: z6.array(authSpaceSchema),
+  /** Cloud only: the server created this user's first Space during this exact request. */
+  createdSpace: z6.boolean().optional(),
+  /** Cloud only: this auto-created Space still needs its idempotent starter initialization. */
+  bootstrapRequired: z6.boolean().optional()
 });
 
 // ../../packages/busabase-contract/src/domains/base/contract/view-schemas.ts
-var viewFilterOperatorSchema = z5.enum([
+var viewFilterOperatorSchema = z7.enum([
   "contains",
   "equals",
   "not_empty",
@@ -1447,82 +2163,82 @@ var viewFilterOperatorSchema = z5.enum([
   "is_true",
   "is_false"
 ]);
-var viewFilterSchema = z5.object({
-  fieldSlug: z5.string(),
+var viewFilterSchema = z7.object({
+  fieldSlug: z7.string(),
   // Stable field identity — survives slug reuse; populated on merge.
-  fieldId: z5.string().optional(),
+  fieldId: z7.string().optional(),
   operator: viewFilterOperatorSchema,
-  value: z5.unknown().optional()
+  value: z7.unknown().optional()
 });
-var viewSortSchema = z5.object({
-  direction: z5.enum(["asc", "desc"]),
-  fieldSlug: z5.string(),
-  fieldId: z5.string().optional()
+var viewSortSchema = z7.object({
+  direction: z7.enum(["asc", "desc"]),
+  fieldSlug: z7.string(),
+  fieldId: z7.string().optional()
 });
-var viewTypeSchema = z5.enum(["table", "gallery", "kanban", "calendar", "gantt"]);
-var ganttScaleSchema = z5.enum(["week", "month"]);
-var galleryCoverFitSchema = z5.enum(["cover", "fit"]);
-var galleryCardSizeSchema = z5.enum(["small", "medium", "large"]);
-var viewConfigSchema = z5.object({
-  filters: z5.array(viewFilterSchema).default([]),
-  sorts: z5.array(viewSortSchema).default([]),
-  visibleFieldSlugs: z5.array(z5.string()).nullable().optional(),
+var viewTypeSchema = z7.enum(["table", "gallery", "kanban", "calendar", "gantt"]);
+var ganttScaleSchema = z7.enum(["week", "month"]);
+var galleryCoverFitSchema = z7.enum(["cover", "fit"]);
+var galleryCardSizeSchema = z7.enum(["small", "medium", "large"]);
+var viewConfigSchema = z7.object({
+  filters: z7.array(viewFilterSchema).default([]),
+  sorts: z7.array(viewSortSchema).default([]),
+  visibleFieldSlugs: z7.array(z7.string()).nullable().optional(),
   // ── Gallery-only presentation config (ignored by table views) ──
   // Which attachment field supplies the cover image (null = no cover).
-  coverFieldSlug: z5.string().nullable().optional(),
+  coverFieldSlug: z7.string().nullable().optional(),
   coverFit: galleryCoverFitSchema.optional(),
   cardSize: galleryCardSizeSchema.optional(),
   // Whether to render the field label above each value on a card.
-  showFieldLabels: z5.boolean().optional(),
+  showFieldLabels: z7.boolean().optional(),
   // ── Kanban-only: which single-select field stacks records into columns.
-  stackByFieldSlug: z5.string().nullable().optional(),
+  stackByFieldSlug: z7.string().nullable().optional(),
   // ── Calendar-only: which date field positions records on the month grid.
-  dateFieldSlug: z5.string().nullable().optional(),
+  dateFieldSlug: z7.string().nullable().optional(),
   // ── Gantt-only: the start/end date fields bounding each record's bar, plus
   // the time-axis granularity.
-  startFieldSlug: z5.string().nullable().optional(),
-  endFieldSlug: z5.string().nullable().optional(),
+  startFieldSlug: z7.string().nullable().optional(),
+  endFieldSlug: z7.string().nullable().optional(),
   ganttScale: ganttScaleSchema.optional()
 });
-var viewSchema = z5.object({
-  id: z5.string(),
-  baseId: z5.string(),
-  slug: z5.string(),
-  name: z5.string(),
-  description: z5.string(),
+var viewSchema = z7.object({
+  id: z7.string(),
+  baseId: z7.string(),
+  slug: z7.string(),
+  name: z7.string(),
+  description: z7.string(),
   type: viewTypeSchema,
   config: viewConfigSchema,
-  status: z5.enum(["active", "archived"]),
-  createdBy: z5.string(),
+  status: z7.enum(["active", "archived"]),
+  createdBy: z7.string(),
   createdByUser: userRefSchema.nullable().optional().default(null),
-  archivedAt: z5.string().nullable(),
-  createdAt: z5.string(),
-  updatedAt: z5.string()
+  archivedAt: z7.string().nullable(),
+  createdAt: z7.string(),
+  updatedAt: z7.string()
 });
-var createViewInputSchema = z5.object({
+var createViewInputSchema = z7.object({
   config: viewConfigSchema.optional().default({ filters: [], sorts: [] }),
-  description: z5.string().optional().default(""),
-  message: z5.string().optional().default("Create view"),
-  name: z5.string().min(1),
+  description: z7.string().optional().default(""),
+  message: z7.string().optional().default("Create view"),
+  name: z7.string().min(1),
   type: viewTypeSchema.optional().default("table"),
-  slug: z5.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
-  submittedBy: z5.string().optional().default("local-producer")
+  slug: z7.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
+  submittedBy: z7.string().optional().default("local-producer")
 });
-var updateViewInputSchema = z5.object({
+var updateViewInputSchema = z7.object({
   config: viewConfigSchema.optional(),
-  description: z5.string().optional(),
-  message: z5.string().optional().default("Update view"),
-  name: z5.string().min(1).optional(),
+  description: z7.string().optional(),
+  message: z7.string().optional().default("Update view"),
+  name: z7.string().min(1).optional(),
   type: viewTypeSchema.optional(),
-  submittedBy: z5.string().optional().default("local-producer")
+  submittedBy: z7.string().optional().default("local-producer")
 });
-var deleteViewInputSchema = z5.object({
-  message: z5.string().optional().default("Delete view"),
-  submittedBy: z5.string().optional().default("local-producer")
+var deleteViewInputSchema = z7.object({
+  message: z7.string().optional().default("Delete view"),
+  submittedBy: z7.string().optional().default("local-producer")
 });
-var restoreViewInputSchema = z5.object({
-  message: z5.string().optional().default("Restore view"),
-  submittedBy: z5.string().optional().default("local-producer")
+var restoreViewInputSchema = z7.object({
+  message: z7.string().optional().default("Restore view"),
+  submittedBy: z7.string().optional().default("local-producer")
 });
 
 // ../../packages/busabase-contract/src/domains/package/types.ts
@@ -1552,131 +2268,131 @@ var PACKAGE_MAX_FILE_BYTES = 25 * 1024 * 1024;
 var PACKAGE_MAX_TOTAL_BYTES = 250 * 1024 * 1024;
 var PACKAGE_MAX_FILE_COUNT = 5e3;
 var PACKAGE_MAX_RECORDS_PER_BASE = 5e4;
-var PackageManifestSchema = z6.object({
-  format: z6.literal(PACKAGE_FORMAT),
+var PackageManifestSchema = z8.object({
+  format: z8.literal(PACKAGE_FORMAT),
   /** Default `--into-folder` name. Not the repo name — a repo can host many packages. */
-  name: z6.string().min(1),
-  description: z6.string().default(""),
+  name: z8.string().min(1),
+  description: z8.string().default(""),
   /**
    * Informational / reserved for a future marketplace index. The real version pin
    * is always the git ref in the install URL.
    */
-  version: z6.string().optional(),
-  author: z6.string().optional(),
-  license: z6.string().optional(),
-  homepage: z6.string().url().optional(),
-  tags: z6.array(z6.string()).default([])
+  version: z8.string().optional(),
+  author: z8.string().optional(),
+  license: z8.string().optional(),
+  homepage: z8.string().url().optional(),
+  tags: z8.array(z8.string()).default([])
 });
-var PackageFileTreeNodeMetaSchema = z6.object({
-  type: z6.enum(PACKAGE_FILE_TREE_NODE_TYPES),
-  name: z6.string().min(1),
-  description: z6.string().default(""),
-  position: z6.number().int().optional()
+var PackageFileTreeNodeMetaSchema = z8.object({
+  type: z8.enum(PACKAGE_FILE_TREE_NODE_TYPES),
+  name: z8.string().min(1),
+  description: z8.string().default(""),
+  position: z8.number().int().optional()
 });
-var PackageFolderMetaSchema = z6.object({
+var PackageFolderMetaSchema = z8.object({
   /** Defaults to the humanized slug when absent. */
-  name: z6.string().optional(),
-  description: z6.string().default(""),
-  position: z6.number().int().optional()
+  name: z8.string().optional(),
+  description: z8.string().default(""),
+  position: z8.number().int().optional()
 });
 var PackageFileNodeMetaSchema = PackageFolderMetaSchema;
-var PackageDocFrontmatterSchema = z6.object({
-  name: z6.string().min(1),
-  description: z6.string().default(""),
-  position: z6.number().int().optional()
+var PackageDocFrontmatterSchema = z8.object({
+  name: z8.string().min(1),
+  description: z8.string().default(""),
+  position: z8.number().int().optional()
 });
-var PackageFieldOptionsSchema = z6.object({
-  ai: z6.object({
-    model: z6.string().optional(),
-    prompt: z6.string().optional(),
-    reviewRequired: z6.boolean().optional(),
+var PackageFieldOptionsSchema = z8.object({
+  ai: z8.object({
+    model: z8.string().optional(),
+    prompt: z8.string().optional(),
+    reviewRequired: z8.boolean().optional(),
     /** Package-only — replaces `ai.sourceFieldIds`. */
-    sourceFieldSlugs: z6.array(z6.string()).optional()
+    sourceFieldSlugs: z8.array(z8.string()).optional()
   }).optional(),
-  attachment: z6.object({
-    maxFiles: z6.number().int().positive().optional(),
-    allowedMimeTypes: z6.array(z6.string()).optional(),
-    maxFileSize: z6.number().int().positive().optional()
+  attachment: z8.object({
+    maxFiles: z8.number().int().positive().optional(),
+    allowedMimeTypes: z8.array(z8.string()).optional(),
+    maxFileSize: z8.number().int().positive().optional()
   }).optional(),
-  choices: z6.array(
-    z6.object({
-      color: z6.string().optional(),
-      id: z6.string(),
-      name: z6.string()
+  choices: z8.array(
+    z8.object({
+      color: z8.string().optional(),
+      id: z8.string(),
+      name: z8.string()
     })
   ).optional(),
-  code: z6.object({
-    language: z6.string().optional()
+  code: z8.object({
+    language: z8.string().optional()
   }).optional(),
-  embed: z6.object({
-    aspectRatio: z6.enum(["16:9", "4:3", "1:1"]).optional(),
-    height: z6.number().int().positive().max(1200).optional(),
-    providers: z6.array(z6.string()).optional()
+  embed: z8.object({
+    aspectRatio: z8.enum(["16:9", "4:3", "1:1"]).optional(),
+    height: z8.number().int().positive().max(1200).optional(),
+    providers: z8.array(z8.string()).optional()
   }).optional(),
   /** Package-only — replaces `inverseFieldId`. */
-  inverseFieldSlug: z6.string().optional(),
-  multiple: z6.boolean().optional(),
-  number: z6.object({
-    format: z6.enum(["plain", "currency"]).optional(),
-    currency: z6.string().optional(),
-    locale: z6.string().optional()
+  inverseFieldSlug: z8.string().optional(),
+  multiple: z8.boolean().optional(),
+  number: z8.object({
+    format: z8.enum(["plain", "currency"]).optional(),
+    currency: z8.string().optional(),
+    locale: z8.string().optional()
   }).optional(),
   /** Native API alias — the server resolves it to `targetBaseId`. */
-  targetBaseSlug: z6.string().optional()
+  targetBaseSlug: z8.string().optional()
 }).default({});
-var PackageBaseFieldSchema = z6.object({
-  slug: z6.string().min(1),
+var PackageBaseFieldSchema = z8.object({
+  slug: z8.string().min(1),
   name: fieldNameSchema,
   type: fieldTypeSchema,
-  required: z6.boolean().default(false),
-  position: z6.number().int(),
+  required: z8.boolean().default(false),
+  position: z8.number().int(),
   options: PackageFieldOptionsSchema
 });
-var PackageViewFilterSchema = z6.object({
-  fieldSlug: z6.string().min(1),
+var PackageViewFilterSchema = z8.object({
+  fieldSlug: z8.string().min(1),
   operator: viewFilterOperatorSchema,
-  value: z6.unknown().optional()
+  value: z8.unknown().optional()
 });
-var PackageViewSortSchema = z6.object({
-  direction: z6.enum(["asc", "desc"]),
-  fieldSlug: z6.string().min(1)
+var PackageViewSortSchema = z8.object({
+  direction: z8.enum(["asc", "desc"]),
+  fieldSlug: z8.string().min(1)
 });
-var PackageViewConfigSchema = z6.object({
-  filters: z6.array(PackageViewFilterSchema).default([]),
-  sorts: z6.array(PackageViewSortSchema).default([]),
-  visibleFieldSlugs: z6.array(z6.string()).nullable().optional()
+var PackageViewConfigSchema = z8.object({
+  filters: z8.array(PackageViewFilterSchema).default([]),
+  sorts: z8.array(PackageViewSortSchema).default([]),
+  visibleFieldSlugs: z8.array(z8.string()).nullable().optional()
 });
-var PackageViewSchema = z6.object({
-  slug: z6.string().min(1),
-  name: z6.string().min(1),
-  description: z6.string().default(""),
-  type: z6.literal("table").default("table"),
+var PackageViewSchema = z8.object({
+  slug: z8.string().min(1),
+  name: z8.string().min(1),
+  description: z8.string().default(""),
+  type: z8.literal("table").default("table"),
   config: PackageViewConfigSchema.default({ filters: [], sorts: [] })
 });
-var PackageBaseSchema = z6.object({
-  name: z6.string().min(1),
-  description: z6.string().default(""),
-  position: z6.number().int().optional(),
+var PackageBaseSchema = z8.object({
+  name: z8.string().min(1),
+  description: z8.string().default(""),
+  position: z8.number().int().optional(),
   /**
    * Informational only — `reviewPolicy` is NOT settable via `bases.create`, so
    * install cannot apply it and warns when it differs from the target's default.
    */
-  reviewPolicy: z6.object({
-    kind: z6.literal("single"),
-    requiredApprovals: z6.number()
+  reviewPolicy: z8.object({
+    kind: z8.literal("single"),
+    requiredApprovals: z8.number()
   }).optional(),
-  fields: z6.array(PackageBaseFieldSchema).default([]),
-  views: z6.array(PackageViewSchema).default([])
+  fields: z8.array(PackageBaseFieldSchema).default([]),
+  views: z8.array(PackageViewSchema).default([])
 });
-var PackageRecordLineSchema = z6.object({
-  key: z6.string().min(1),
-  fields: z6.record(z6.string(), z6.unknown()).default({})
+var PackageRecordLineSchema = z8.object({
+  key: z8.string().min(1),
+  fields: z8.record(z8.string(), z8.unknown()).default({})
 });
 
-// src/package/apply.ts
-import { createHash as createHash2 } from "crypto";
+// ../../packages/busabase-package/src/apply.ts
+import { createHash as createHash5 } from "crypto";
 
-// src/package/tree.ts
+// ../../packages/busabase-package/src/tree.ts
 import { extname } from "path";
 var NODE_SLUG_PATTERN = /^[a-z0-9-]+$/;
 var assertSafeNodeSlug = (slug, context) => {
@@ -1777,7 +2493,7 @@ var walkNodes = function* (nodes) {
 };
 var collectBaseNodes = (nodes) => [...walkNodes(nodes)].filter((node) => node.type === "base");
 
-// src/package/apply.ts
+// ../../packages/busabase-package/src/apply.ts
 var RECORD_BATCH_SIZE = 200;
 var fieldKey = (baseSlug, fieldSlug) => `${baseSlug}\0${fieldSlug}`;
 var applyInstall = async (client, plan, options) => {
@@ -2047,7 +2763,7 @@ var createFileTreeNode = async (client, node, parentNodeId, options, state) => {
 var UploadTargetUnsupportedError = class extends Error {
 };
 var uploadAsset = async (client, fileName, mimeType, bytes) => {
-  const contentHash = `sha256:${createHash2("sha256").update(bytes).digest("hex")}`;
+  const contentHash = `sha256:${createHash5("sha256").update(bytes).digest("hex")}`;
   const requested = await client.assets.createUploadUrl({
     fileName,
     mimeType,
@@ -2221,7 +2937,7 @@ var approveAndMerge = async (client, changeRequestId) => {
   return client.changeRequests.merge({ changeRequestId });
 };
 
-// src/package/collect.ts
+// ../../packages/busabase-package/src/collect.ts
 var findSourceNode = (nodes, slugOrId) => {
   const stack = [...nodes];
   while (stack.length > 0) {
@@ -2512,7 +3228,7 @@ var walk = function* (nodes) {
   }
 };
 
-// src/package/github.ts
+// ../../packages/busabase-package/src/github.ts
 import { Uint8ArrayReader, ZipReader } from "@zip.js/zip.js";
 var GITHUB_ALLOWED_HOSTS = [
   "github.com",
@@ -2671,7 +3387,7 @@ var fetchGithubPackageFiles = async (repoUrl, options = {}) => {
   return { source, files };
 };
 
-// src/package/frontmatter.ts
+// ../../packages/busabase-package/src/frontmatter.ts
 import { parse, stringify } from "yaml";
 var DELIMITER = "---";
 var normalizeDocBody = (body) => body.replaceAll("\r\n", "\n").replace(/^\n+/, "").replace(/\n+$/, "");
@@ -2715,7 +3431,7 @@ ${normalizeDocBody(body)}
 `;
 };
 
-// src/package/layout-read.ts
+// ../../packages/busabase-package/src/layout-read.ts
 var decodeText = (bytes, filePath) => {
   const text = bytes.toString("utf8");
   if (text.includes("\uFFFD")) {
@@ -2933,7 +3649,7 @@ var stripExtension = (fileName) => {
   return dot > 0 ? fileName.slice(0, dot) : fileName;
 };
 
-// src/package/layout-write.ts
+// ../../packages/busabase-package/src/layout-write.ts
 import { mkdir, rm, writeFile } from "fs/promises";
 import { dirname, join as join2 } from "path";
 var sortKeysDeep = (value) => {
@@ -3124,9 +3840,20 @@ var writePackageFiles = async (files, outDir, options = {}) => {
   }
 };
 
-// src/package/plan.ts
+// ../../packages/busabase-package/src/plan.ts
+var findTargetFolder = (nodes, slug) => {
+  const roots = nodes.length === 1 && nodes[0].children ? nodes[0].children : nodes;
+  return roots.find((node) => node.slug === slug && node.type === "folder");
+};
+var resolveTargetState = async (client, targetFolderSlug) => {
+  const [nodes, bases] = await Promise.all([client.nodes.list(), client.bases.list()]);
+  return {
+    targetFolder: findTargetFolder(nodes, targetFolderSlug),
+    existingBaseSlugs: new Set(bases.map((base) => base.slug))
+  };
+};
 var buildInstallPlan = (tree, target, options = {}) => {
-  const targetFolderSlug = options.intoFolder ?? tree.manifest.name;
+  const targetFolderSlug = options.intoFolder ?? suggestSlug(tree.manifest.name);
   const warnings = [];
   const existingChildSlugs = new Set(
     (target.targetFolder?.children ?? []).map((child) => child.slug)
@@ -3338,26 +4065,21 @@ Nothing was created. Re-run with --rename to install the colliding items under s
 };
 
 // src/package/commands.ts
-var reportProgress = (message) => {
+var reportProgress2 = (message) => {
   console.error(message);
 };
 var runInstall = async (client, repoUrl, options) => {
-  reportProgress(`Fetching ${repoUrl} \u2026`);
+  reportProgress2(`Fetching ${repoUrl} \u2026`);
   const { source, files } = await fetchGithubPackageFiles(repoUrl, {
     githubToken: options.githubToken
   });
-  reportProgress(`Downloaded ${files.size} file(s) from ${source.owner}/${source.repo}.`);
+  reportProgress2(`Downloaded ${files.size} file(s) from ${source.owner}/${source.repo}.`);
   const tree = readPackageTree(files);
-  const [nodes, bases] = await Promise.all([client.nodes.list(), client.bases.list()]);
-  const targetFolderSlug = options.intoFolder ?? tree.manifest.name;
-  const plan = buildInstallPlan(
-    tree,
-    {
-      targetFolder: findTargetFolder(nodes, targetFolderSlug),
-      existingBaseSlugs: new Set(bases.map((base) => base.slug))
-    },
-    { intoFolder: options.intoFolder, rename: options.rename }
-  );
+  const targetFolderSlug = options.intoFolder ?? suggestSlug(tree.manifest.name);
+  const plan = buildInstallPlan(tree, await resolveTargetState(client, targetFolderSlug), {
+    intoFolder: options.intoFolder,
+    rename: options.rename
+  });
   if (options.dryRun) {
     const report = `${renderPlan(plan)}
 
@@ -3368,15 +4090,11 @@ Dry run \u2014 nothing was created.`;
   const result = await applyInstall(client, plan, {
     autoMerge: Boolean(options.autoMerge),
     submittedBy: `busabase-cli install (${tree.manifest.name})`,
-    onProgress: reportProgress
+    onProgress: reportProgress2
   });
   if (options.json) return { installed: true, ...result };
   return renderInstallReport(plan.targetFolderSlug, result);
 };
-var findTargetFolder = (nodes, slug) => {
-  const roots = nodes.length === 1 && nodes[0].children ? nodes[0].children : nodes;
-  return roots.find((node) => node.slug === slug && node.type === "folder");
-};
 var toPlanSummary = (plan) => ({
   targetFolder: plan.targetFolderSlug,
   package: plan.tree.manifest.name,
@@ -3412,7 +4130,7 @@ var runPublish = async (client, nodeSlugOrId, options) => {
   const source = findSourceNode(nodes, nodeSlugOrId);
   const warnings = [];
   const manifest = await resolveManifest(options.outDir, options.name, source.name, source.slug);
-  reportProgress(`Reading "${source.slug}" \u2026`);
+  reportProgress2(`Reading "${source.slug}" \u2026`);
   const tree = await collectPackageTree(client, source, {
     manifest,
     warn: (message) => warnings.push(message),
@@ -3666,7 +4384,7 @@ async function uploadAsset2(config, opts) {
   const fileName = opts.fileName ?? basename(filePath);
   const mimeType = opts.mimeType ?? guessMimeType2(filePath);
   const context = opts.context ?? "record-field";
-  const contentHash = `sha256:${createHash3("sha256").update(file).digest("hex")}`;
+  const contentHash = `sha256:${createHash6("sha256").update(file).digest("hex")}`;
   const requested = await rawRequest(config, "POST", "/api/v1/assets/upload-urls", {
     fileName,
     mimeType,
@@ -3752,6 +4470,7 @@ function runAction(state, handler) {
     const opts = cmd.optsWithGlobals();
     const config = resolveConfig(opts);
     state.config = config;
+    assertCredentialNotExpired(config.apiKey);
     await maybeAutoRefresh(config.baseUrl, config.apiKey);
     const client = createBusabaseClient(config);
     const result = await handler(client, opts, config);
@@ -3763,6 +4482,7 @@ function runArgAction(state, handler) {
     const opts = cmd.optsWithGlobals();
     const config = resolveConfig(opts);
     state.config = config;
+    assertCredentialNotExpired(config.apiKey);
     await maybeAutoRefresh(config.baseUrl, config.apiKey);
     const client = createBusabaseClient(config);
     const result = await handler(arg, client, opts, config);
@@ -3949,7 +4669,7 @@ function buildProgram(state = {}) {
     runAction(state, (_client, _opts, config) => rawFetch(config, "GET", "/api/v1/openapi.json"))
   );
   addGlobalFlags(program.command("whoami")).description("Active space, user, and membership").action(runAction(state, (client) => client.auth.verify()));
-  addGlobalFlags(program.command("login")).description("Connect the CLI to Busabase \u2014 Personal/local, Cloud, or self-hosted").option("--oauth", "force browser OAuth and skip the method prompt").option("--no-browser", "OAuth: print the sign-in URL instead of opening a browser").option("--refresh", "slide the saved OAuth session forward (no browser, no re-login)").addHelpText(
+  addGlobalFlags(program.command("login")).description("Connect the CLI to Busabase \u2014 Personal/local, Cloud, or self-hosted").option("--device-code", "force device authorization and skip the method prompt").option("--oauth", "legacy same-machine OAuth callback flow").option("--no-browser", "print the sign-in URL instead of opening a browser").option("--refresh", "slide the saved OAuth session forward (no browser, no re-login)").addHelpText(
     "after",
     `
 Busabase is an approval-first database and knowledge base for AI agents: agents
@@ -3958,14 +4678,15 @@ propose changes, humans review and merge what becomes trusted data.
 Run interactively, login explains the connection choices and writes the selected
 Busabase instance to ~/.busabase/.env:
   1. Local/Desktop on this computer \u2014 no account, no login
-  2. Busabase Cloud \u2014 browser sign-in (recommended)
+  2. Busabase Cloud \u2014 device sign-in (recommended; works over SSH)
   3. Busabase Cloud \u2014 paste an API key
-  4. Self-hosted Busabase \u2014 browser sign-in
+  4. Self-hosted Busabase \u2014 device sign-in
   5. Self-hosted Busabase \u2014 paste an API key
 The flags below skip the menu (handy for scripts / CI):
 
   busabase-cli login                                   # pick from the menu
-  busabase-cli login --oauth                           # Cloud browser sign-in
+  busabase-cli login --device-code                     # Cloud device sign-in
+  busabase-cli login --oauth                           # legacy same-machine callback
   busabase-cli login --api-key sk_\u2026                    # Cloud API key (headless/CI)
   busabase-cli login --base-url http://localhost:15419 # connect to a local server (no auth)
   busabase-cli login --refresh                         # extend the current session (auto-runs too)`
@@ -3977,6 +4698,7 @@ The flags below skip the menu (handy for scripts / CI):
       baseUrl: config.baseUrl,
       apiKey: opts.apiKey,
       spaceId: config.spaceId,
+      deviceCode: Boolean(opts.deviceCode),
       oauth: Boolean(opts.oauth),
       browser: opts.browser !== false
     });
@@ -4496,6 +5218,60 @@ Examples:
       })
     )
   );
+  addGlobalFlags(program.command("backup")).description("Back up the active space to a full-fidelity .bbdump archive").option("-o, --out-file <file>", "output archive path", "space.bbdump").option(
+    "--no-history",
+    "full-fidelity rows, but omit the history tables (commits, change requests, operations, comments, reviews, audit events)"
+  ).option("--state-only", "superseded by `busabase-cli publish` \u2014 see the error text").addHelpText(
+    "after",
+    `
+A backup is full fidelity: raw rows with their original ids, every doc body, and
+every attachment's bytes, in one integrity-checked archive. Vault items and
+webhook signing secrets are never written to it.
+
+Examples:
+  busabase-cli backup                                        # \u2192 ./space.bbdump
+  busabase-cli backup -o ./backups/acme-2026-07-19.bbdump
+  busabase-cli backup --no-history                           # smaller: current state only
+
+To hand content to someone else rather than back it up, use \`busabase-cli publish\`,
+which writes a readable, diffable package directory you can push to GitHub.`
+  ).action(
+    runAction(
+      state,
+      (client, opts, config) => runBackup(client, {
+        outFile: opts.outFile,
+        includeHistory: opts.history !== false,
+        stateOnly: Boolean(opts.stateOnly),
+        json: config.output === "json",
+        baseUrl: config.baseUrl,
+        spaceId: config.spaceId,
+        toolVersion: pkgVersion()
+      })
+    )
+  );
+  addGlobalFlags(program.command("restore")).description("Restore a .bbdump archive into an EMPTY space, preserving original ids").argument("<file>", "path to the .bbdump archive").option("--resume", "resume a previously interrupted restore (not yet implemented)").option("--into-folder <name>", "state-only archives only \u2014 see the error text").addHelpText(
+    "after",
+    `
+The archive's checksum is verified before a single row is written, and the target
+space must be EMPTY \u2014 a restore replays original ids, so it cannot merge into a
+space that already holds content.
+
+Examples:
+  busabase-cli restore ./space.bbdump
+  busabase-cli restore ./backups/acme-2026-07-19.bbdump --space-id spc_123
+
+To add content to a space that is already in use, use \`busabase-cli install\` instead.`
+  ).action(
+    runArgAction(
+      state,
+      (file, client, opts, config) => runRestore(client, {
+        file,
+        resume: Boolean(opts.resume),
+        intoFolder: opts.intoFolder,
+        json: config.output === "json"
+      })
+    )
+  );
   addGlobalFlags(program.command("api")).description("Raw request to any /api/v1 endpoint").addOption(
     new Option("--method <get|post|put|delete>", "HTTP method").choices(["get", "post", "put", "delete"]).makeOptionMandatory()
   ).requiredOption("--path <p>", "path under /api/v1, e.g. /bases").option("--query <k=v...>", "query-string param, repeatable").option("--body-json <json>", "JSON request body").action(