busa-cli 0.10.2 → 0.11.0

package/dist/{chunk-DGRADZF2.js → chunk-QJJMAA3K.js}

@@ -284,6 +284,10 @@ var baseFieldChangeTask = {
 
 // ../../packages/busabase-contract/src/tasks/change-request.ts
 var REVIEW_GUIDANCE = "This records a HUMAN decision. Never call it unless the user explicitly asked for this specific verdict on these specific change requests. Summarising a change request for the user is not permission to approve it.";
+var singleItemError = (result) => Object.assign(new Error(result?.error ?? "Change request action returned no result"), {
+  ...result?.code ? { code: result.code } : {},
+  ...result?.data === void 0 ? {} : { data: result.data }
+});
 var changeRequestQueryTask = {
   name: "change_request_query",
   cliPath: ["change-requests", "query"],
@@ -363,18 +367,15 @@ var changeRequestReviewTask = {
       throw new Error("changeRequestIds must contain at least one id.");
     }
     const verdict = input.verdict;
-    if (ids.length === 1) {
-      return client.changeRequests.review({
-        changeRequestId: ids[0],
-        verdict,
-        ...input.reason ? { reason: input.reason } : {}
-      });
-    }
-    return client.changeRequests.reviewMany({
+    const response = await client.changeRequests.review({
       changeRequestIds: ids,
       verdict,
       ...input.reason ? { reason: input.reason } : {}
     });
+    if (ids.length !== 1) return response;
+    const result = response.results[0];
+    if (!result?.ok) throw singleItemError(result);
+    return result.changeRequest;
   }
 };
 var changeRequestMergeTask = {
@@ -401,8 +402,15 @@ var changeRequestMergeTask = {
     if (!Array.isArray(ids) || ids.length === 0) {
       throw new Error("changeRequestIds must contain at least one id.");
     }
-    if (ids.length === 1) return client.changeRequests.merge({ changeRequestId: ids[0] });
-    return client.changeRequests.mergeMany({ changeRequestIds: ids });
+    const response = await client.changeRequests.merge({ changeRequestIds: ids });
+    if (ids.length !== 1) return response;
+    const result = response.results[0];
+    if (!result?.ok) throw singleItemError(result);
+    return {
+      changeRequest: result.changeRequest,
+      record: result.record,
+      view: result.view
+    };
   }
 };
 
@@ -434,25 +442,25 @@ var nodeListTask = {
     {
       path: ["skills", "list"],
       preset: { kind: "skill" },
-      summary: "List Skill nodes with their file trees"
+      summary: "List Skill nodes (summaries; use `skills get` for one node's files)"
     },
     {
       path: ["drives", "list"],
       preset: { kind: "drive" },
-      summary: "List Drive nodes with their file trees"
+      summary: "List Drive nodes (summaries; use `drives get` for one node's files)"
     },
     {
       path: ["airapps", "list"],
       preset: { kind: "airapp" },
-      summary: "List AirApp nodes with their file trees"
+      summary: "List AirApp nodes (summaries; use `airapps get` for one node's files)"
     }
   ],
-  summary: "List Skill, Drive, or AirApp nodes with their file trees",
-  guidance: "Returns every node of the given kind together with its Asset-backed file list. For the workspace tree across all node types, use `nodes_list` instead.",
+  summary: "List Skill, Drive, or AirApp nodes",
+  guidance: "Returns a lightweight summary row for every node of the given kind \u2014 id, name, slug, type, and metadata, but NOT the node's file list. Follow up with `node_get_file_tree` for one node's files, or `node_files_list` for just the file inventory. For the workspace tree across all node types, use `nodes_list` instead.",
   annotations: { readOnly: true, destructive: false },
   params: [kindParam],
   examples: ["busabase-cli nodes list-file-trees --kind skill"],
-  execute: async (client, input) => client.fileTrees.list({ type: resolveKind(input.kind) })
+  execute: async (client, input) => client.nodes.list({ types: [resolveKind(input.kind)] })
 };
 var nodeGetTask = {
   name: "node_get_file_tree",
@@ -478,7 +486,10 @@ var nodeGetTask = {
   annotations: { readOnly: true, destructive: false },
   params: [kindParam, nodeIdParam],
   examples: ["busabase-cli nodes get-file-tree --kind airapp --node-id nod_123"],
-  execute: async (client, input) => client.fileTrees.get({ nodeId: input.nodeId, type: resolveKind(input.kind) })
+  // Reads through the unified Node detail route. The payload is unchanged apart
+  // from the `type` discriminator the union carries, so a caller still gets
+  // `{ node, entryFile, visibility, version, files }`.
+  execute: async (client, input) => client.nodes.get({ nodeId: input.nodeId, type: resolveKind(input.kind) })
 };
 var nodeListFilesTask = {
   name: "node_files_list",
@@ -567,7 +578,7 @@ var nodeFilesChangeRequestTask = {
     }
   ],
   summary: "Propose file changes inside a Skill, Drive, or AirApp node",
-  guidance: "Approval-first: this proposes a ChangeRequest for a human to review, it does not write directly. Each operation is one of create / update / delete / metadata_update. Include `baseContentHash` (from `node_file_read`) on an update so a concurrent edit is caught.",
+  guidance: 'Approval-first: this proposes a ChangeRequest for a human to review, it does not write directly. Each operation is one of create / update / delete / metadata_update. Include `baseContentHash` (from `node_file_read`) on an update so a concurrent edit is caught. For kind "airapp", keep the project runnable by `npm run dev` \u2014 editing package.json must leave a "dev" script starting a plain Node server, not a bundler dev server.',
   annotations: { readOnly: false, destructive: false },
   params: [
     kindParam,
@@ -1189,7 +1200,7 @@ var nodeCreateTask = {
       name: "files",
       appliesWhen: { param: "type", values: ["skill", "drive", "airapp"] },
       kind: "json",
-      description: 'Seed files for a Skill/Drive/AirApp: [{"path":"SKILL.md","content":"..."}]. Layered over the default scaffold unless mergeMode is "replace".'
+      description: 'Seed files for a Skill/Drive/AirApp: [{"path":"SKILL.md","content":"..."}]. Layered over the default scaffold unless mergeMode is "replace" \u2014 a path you supply REPLACES the scaffold\'s file at that path. For --type airapp the project MUST be runnable by `npm run dev`: give package.json a "dev" script running a plain Node server (`node server.js`, Hono or node:http). A bundler dev server (Vite/webpack/Next) and any native-binary dependency CANNOT boot in the AirApp runtime, and browser files must need no build step.'
     },
     {
       name: "mergeMode",
@@ -1433,11 +1444,16 @@ var recordQueryTask = {
 
 // ../../packages/busabase-contract/src/tasks/view-change.ts
 var ACTIONS = ["create", "update", "delete", "restore"];
+var mergeIntent2 = (input) => {
+  if (input.requireReview) return { autoMerge: false };
+  if (input.autoMerge) return { autoMerge: true };
+  return {};
+};
 var viewChangeTask = {
   name: "view_change_request",
   cliPath: ["views", "change-request"],
   summary: "Propose a Base view change (create / update / delete / restore)",
-  guidance: "Approval-first: proposes a ChangeRequest, it does not change the view directly. `create` needs the BASE id; update / delete / restore need the VIEW id \u2014 the endpoint split follows whichever id identifies the target, which this task handles for you.",
+  guidance: "Review is permission-aware, decided server-side: the change merges immediately when your key has write access on the Base's node and lands as a pending ChangeRequest otherwise \u2014 check the response's `materialized` field to see which happened. Pass requireReview to always propose instead of merging. Views are structure, not content \u2014 when you are building starter structure (a Base plus the views that make it usable) let it merge so the workspace is not left half-built behind a review queue, exactly as you would for `node_create` and `POST /bases`. `create` needs the BASE id; update / delete / restore need the VIEW id \u2014 the endpoint split follows whichever id identifies the target, which this task handles for you.",
   annotations: { readOnly: false, destructive: false },
   params: [
     {
@@ -1484,16 +1500,30 @@ var viewChangeTask = {
       description: "Changes to apply to the view (update only)."
     },
     { name: "message", kind: "string", description: "Explanation for the reviewer." },
-    { name: "submittedBy", kind: "string", description: "Producer label recorded on the change." }
+    { name: "submittedBy", kind: "string", description: "Producer label recorded on the change." },
+    {
+      name: "autoMerge",
+      kind: "boolean",
+      description: "Skip review and apply the change immediately if you have write access. Not a permission override \u2014 a changeRequest-level key still gets a pending CR. Default is permission-aware: merge when you can, otherwise propose."
+    },
+    {
+      name: "requireReview",
+      kind: "boolean",
+      description: "Always propose a pending ChangeRequest, even with write access."
+    }
   ],
   examples: [
     'busabase-cli views change-request --action create --base-id bas_1 --name "Published" --type table',
+    'busabase-cli views change-request --action create --base-id bas_1 --name "Published" --require-review',
     "busabase-cli views change-request --action delete --view-id viw_1"
   ],
   execute: async (client, input) => {
     const meta = {
       ...input.message ? { message: input.message } : {},
-      ...input.submittedBy ? { submittedBy: input.submittedBy } : {}
+      ...input.submittedBy ? { submittedBy: input.submittedBy } : {},
+      // Tri-state, like node_create's: omitted keeps the endpoint's
+      // permission-aware default, explicit true/false forces the branch.
+      ...mergeIntent2(input)
     };
     if (input.action === "create") {
       if (!input.baseId || !input.name) {
@@ -1556,6 +1586,8 @@ import {
   cloudContract,
   createBusabaseClient,
   DEFAULT_BASE_URL as DEFAULT_BASE_URL2,
+  getRecordByField,
+  grepAssets,
   normalizeBaseUrl as normalizeBaseUrl2
 } from "busabase-sdk";
 import {
@@ -2241,8 +2273,11 @@ async function exportFull(options) {
   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 ?? "");
+    const detail = await client.nodes.get({ nodeId, type: "doc" });
+    if (detail.type !== "doc") {
+      throw new Error(`Expected a doc node for ${nodeId}, got "${detail.type}"`);
+    }
+    await writer.addBuffer(`docs/${nodeId}.md`, detail.body ?? "");
     docBodyCount += 1;
   }
   log(`exported ${docBodyCount} doc bodies`);
@@ -2486,15 +2521,15 @@ var reportProgress = (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,",
+  "`busabase-cli export`, 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 export <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",
+  "a backup carries the audit events, comments, reviews and ACLs that an exported",
   "package must never leak."
 ].join("\n");
 var STATE_ONLY_RESTORE_MESSAGE = [
@@ -3463,7 +3498,33 @@ var listNodesInputSchema = z7.object({
    * soft-archived nodes for the Trash view — no `parentId`/`depth` walk, since
    * archived nodes are shown as a list, not a tree.
    */
-  status: z7.enum(["active", "archived"]).optional().default("active")
+  status: z7.enum(["active", "archived"]).optional().default("active"),
+  /**
+   * Narrow to specific node types and return a FLAT list of lightweight node
+   * summaries (`children: []`) instead of walking the tree. This is what
+   * replaced the four retired narrow listings (`GET /docs`, `/files`,
+   * `/folders`, `/file-trees`); file-trees are selected with their real
+   * discriminators `skill` / `drive` / `airapp`, since there is no synthetic
+   * "file-tree" node type.
+   *
+   * Omitting `types` leaves every existing caller on exactly today's
+   * behaviour (full tree, or a `parentId`/`depth`-bounded walk, or the
+   * archived flat list) — the two modes never interfere.
+   *
+   * NOTE — no `projection` parameter, deliberately. The consolidation roadmap
+   * sketched `?projection=summary`, but it also rules out adding
+   * `projection=detail` in this batch (the retired detail lists were the
+   * N+1 payloads this change exists to remove). That would leave a parameter
+   * with exactly one legal value, which is noise in OpenAPI/MCP/CLI rather
+   * than a decision a caller gets to make. Detail is `GET /nodes/{nodeId}`.
+   *
+   * A GET query param that occurs exactly once (`?types=doc`) arrives as a
+   * bare string, not a 1-element array — only a REPEATED occurrence
+   * (`?types=doc&types=file`) becomes an array. Accept both and normalize.
+   */
+  types: z7.union([z7.array(z7.enum(NODE_TYPES)), z7.enum(NODE_TYPES)]).transform((value) => Array.isArray(value) ? value : [value]).optional().describe(
+    "Return a flat list of lightweight summaries for these node types instead of the tree. Read one node's full detail with GET /nodes/{nodeId}."
+  )
 }).optional();
 var isDescendantInputSchema = z7.object({
   nodeId: z7.string(),
@@ -3631,11 +3692,19 @@ var liveEventSchema = z7.object({
     // via the audit funnel, but nothing needs reviewing). Consumed by
     // `use-live-sync.ts` to pop a desktop Notification, and by
     // busabase-cloud's host hook to persist an inbox notification row.
-    "change_request.pending_review"
+    "change_request.pending_review",
+    // A node's metadata was written directly, outside the change-request flow
+    // (`PATCH /api/v1/nodes/{nodeId}/metadata` — agents, the SDK, an MCP tool,
+    // and every rich-node editor's own Save). Carries the touched node in
+    // `nodeIds` so open dashboards refetch the node tree instead of showing a
+    // stale whiteboard/workflow/HTML document until the next reload.
+    "node.metadata_updated"
   ]),
   spaceId: z7.string(),
   actorId: z7.string(),
-  changeRequestId: z7.string(),
+  // Null for events that aren't about a change request at all
+  // (`node.metadata_updated`), which is every direct, auto-audited write.
+  changeRequestId: z7.string().nullable(),
   baseId: z7.string().nullable(),
   nodeIds: z7.array(z7.string()),
   recordIds: z7.array(z7.string()),
@@ -3946,6 +4015,9 @@ var viewSchema = z8.object({
   createdAt: z8.string(),
   updatedAt: z8.string()
 });
+var autoMergeSchema = z8.boolean().optional().describe(
+  "Whether to approve and merge this view change immediately. Omitted defaults to merging immediately if the actor has write access on the Base's node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access."
+);
 var createViewInputSchema = z8.object({
   config: viewConfigSchema.optional().default({ filters: [], sorts: [] }),
   description: z8.string().optional().default(""),
@@ -3953,7 +4025,8 @@ var createViewInputSchema = z8.object({
   name: z8.string().min(1),
   type: viewTypeSchema.optional().default("table"),
   slug: z8.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
-  submittedBy: z8.string().optional().default("local-producer")
+  submittedBy: z8.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var updateViewInputSchema = z8.object({
   config: viewConfigSchema.optional(),
@@ -3961,15 +4034,18 @@ var updateViewInputSchema = z8.object({
   message: z8.string().optional().default("Update view"),
   name: z8.string().min(1).optional(),
   type: viewTypeSchema.optional(),
-  submittedBy: z8.string().optional().default("local-producer")
+  submittedBy: z8.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var deleteViewInputSchema = z8.object({
   message: z8.string().optional().default("Delete view"),
-  submittedBy: z8.string().optional().default("local-producer")
+  submittedBy: z8.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var restoreViewInputSchema = z8.object({
   message: z8.string().optional().default("Restore view"),
-  submittedBy: z8.string().optional().default("local-producer")
+  submittedBy: z8.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var viewChangeRequestInputSchema = z8.discriminatedUnion("operation", [
   createViewInputSchema.extend({
@@ -4009,7 +4085,7 @@ var PACKAGE_COMPUTED_FIELD_TYPES = [
   "auto_number",
   "formula",
   // `lookup` is derived from OTHER records and resolved at read time, so it
-  // shows up in `headCommit.fields` like any other value — but publishing it
+  // shows up in `headCommit.fields` like any other value — but exporting it
   // would ship derived data as if it were authored, and install would strip it
   // server-side anyway.
   "lookup",
@@ -4484,16 +4560,25 @@ var createBase = async (client, node, parentNodeId, options, state, bases, field
   bases.push({ node, baseId: result.id });
   indexFields(fieldIds, node.slug, result.fields);
   for (const view of node.base.views) {
-    const changeRequest = await client.views.changeRequest({
+    const created = await client.views.changeRequest({
       operation: "create",
       baseId: result.id,
       slug: view.slug,
       name: view.name,
       description: view.description,
       config: view.config,
-      submittedBy: options.submittedBy
+      submittedBy: options.submittedBy,
+      // Structure, exactly like the Base above — so ask for it outright instead
+      // of proposing it and immediately approving+merging our own proposal,
+      // which is what this loop used to do only because the endpoint had no
+      // `autoMerge`.
+      autoMerge: true
     });
-    await approveAndMerge(client, changeRequest.id);
+    if (!created.materialized) {
+      throw new Error(
+        `View "${view.slug}" was requested immediately but the server returned a pending change request; install cannot leave a Base's views behind in review.`
+      );
+    }
     state.created.views++;
   }
 };
@@ -4716,8 +4801,32 @@ var toKeyArray = (value) => {
   return [];
 };
 var approveAndMerge = async (client, changeRequestId) => {
-  await client.changeRequests.review({ changeRequestId, verdict: "approved" });
-  return client.changeRequests.merge({ changeRequestId });
+  const reviewed = await client.changeRequests.review({
+    changeRequestIds: [changeRequestId],
+    verdict: "approved"
+  });
+  const reviewResult = reviewed.results[0];
+  if (!reviewResult?.ok) {
+    throw Object.assign(
+      new Error(reviewResult?.error ?? "Change request review returned no result"),
+      {
+        code: reviewResult?.code,
+        data: reviewResult?.data
+      }
+    );
+  }
+  const merged = await client.changeRequests.merge({ changeRequestIds: [changeRequestId] });
+  const mergeResult = merged.results[0];
+  if (!mergeResult?.ok) {
+    throw Object.assign(
+      new Error(mergeResult?.error ?? "Change request merge returned no result"),
+      {
+        code: mergeResult?.code,
+        data: mergeResult?.data
+      }
+    );
+  }
+  return mergeResult;
 };
 
 // ../../packages/busabase-package/src/collect.ts
@@ -4753,7 +4862,7 @@ var collectNode = async (client, source, options) => {
     slug: source.slug,
     name: source.name,
     description: source.description ?? "",
-    // `publish` always writes position, so round trips preserve sibling order exactly.
+    // `export` always writes position, so round trips preserve sibling order exactly.
     position: source.position
   };
   switch (source.type) {
@@ -4764,7 +4873,10 @@ var collectNode = async (client, source, options) => {
         children: await collectNodes(client, source.children ?? [], options)
       };
     case "doc": {
-      const doc = await client.docs.get({ nodeId: source.id });
+      const doc = await client.nodes.get({ nodeId: source.id, type: "doc" });
+      if (doc.type !== "doc") {
+        throw new Error(`Expected a doc node for "${source.slug}", got "${doc.type}".`);
+      }
       return { ...common, type: "doc", body: doc.body };
     }
     case "base":
@@ -4785,7 +4897,7 @@ var collectBase = async (client, source, common, options) => {
   const base = await client.bases.get({ baseId });
   if (!base) {
     throw new Error(
-      `Base node "${source.slug}" has no Base behind it (looked up ${baseId}). The space may be mid-migration; re-run publish.`
+      `Base node "${source.slug}" has no Base behind it (looked up ${baseId}). The space may be mid-migration; re-run export.`
     );
   }
   const views = await client.bases.listViews({ baseId: base.id });
@@ -4836,7 +4948,7 @@ var toPackageField = (field, context) => {
     const targetSlug = context.baseSlugById.get(targetBaseId);
     if (!targetSlug) {
       throw new Error(
-        `Field "${context.baseSlug}.${field.slug}" relates to a Base that no longer exists (${targetBaseId}). Fix the field before publishing.`
+        `Field "${context.baseSlug}.${field.slug}" relates to a Base that no longer exists (${targetBaseId}). Fix the field before exporting.`
       );
     }
     options.targetBaseSlug = targetSlug;
@@ -4948,7 +5060,10 @@ var collectFileTree = async (client, source, type, common, options) => {
   };
 };
 var collectFile = async (client, source, common, options) => {
-  const fileNode = await client.files.get({ nodeId: source.id });
+  const fileNode = await client.nodes.get({ nodeId: source.id, type: "file" });
+  if (fileNode.type !== "file") {
+    throw new Error(`Expected a file node for "${source.slug}", got "${fileNode.type}".`);
+  }
   const asset = fileNode.asset;
   if (!asset?.url) {
     options.warn(`Skipped file node "${source.slug}": it has no downloadable asset.`);
@@ -4986,7 +5101,7 @@ var assertSelfContained = (tree, options) => {
       if (field.type !== "relation" || !targetBaseSlug) continue;
       if (!packagedBaseSlugs.has(targetBaseSlug)) {
         throw new Error(
-          `Field "${node.slug}.${field.slug}" relates to Base "${targetBaseSlug}", which is outside the subtree being published. A package must be self-contained \u2014 publish a subtree that includes both Bases, or remove the field.`
+          `Field "${node.slug}.${field.slug}" relates to Base "${targetBaseSlug}", which is outside the subtree being exported. A package must be self-contained \u2014 export a subtree that includes both Bases, or remove the field.`
         );
       }
     }
@@ -5003,7 +5118,7 @@ var assertSelfContained = (tree, options) => {
     }
     if (dangling > 0) {
       options.warn(
-        `Base "${node.slug}" has ${dangling} relation value(s) pointing at records outside the published subtree \u2014 they were dropped.`
+        `Base "${node.slug}" has ${dangling} relation value(s) pointing at records outside the exported subtree \u2014 they were dropped.`
       );
     }
   }
@@ -5913,7 +6028,7 @@ var renderInstallReport = (targetFolderSlug, result) => {
   }
   return lines.join("\n");
 };
-var runPublish = async (client, nodeSlugOrId, options) => {
+var runExport = async (client, nodeSlugOrId, options) => {
   const nodes = await client.nodes.list();
   const source = findSourceNode(nodes, nodeSlugOrId);
   const warnings = [];
@@ -5930,14 +6045,14 @@ var runPublish = async (client, nodeSlugOrId, options) => {
   }
   if (options.json) {
     return {
-      published: !options.dryRun,
+      exported: !options.dryRun,
       package: manifest.name,
       outDir: options.outDir,
       files: [...files.keys()].sort(),
       warnings
     };
   }
-  return renderPublishReport(options, manifest, files, warnings);
+  return renderExportReport(options, manifest, files, warnings);
 };
 var resolveManifest = async (outDir, nameFlag, nodeName, nodeSlug) => {
   const existing = await readExistingManifest(outDir);
@@ -5959,7 +6074,7 @@ var readExistingManifest = async (outDir) => {
     return void 0;
   }
 };
-var renderPublishReport = (options, manifest, files, warnings) => {
+var renderExportReport = (options, manifest, files, warnings) => {
   const lines = [];
   lines.push(
     options.dryRun ? `Dry run \u2014 would write ${files.size} file(s) to ${options.outDir}:` : `Wrote ${files.size} file(s) to ${options.outDir}:`
@@ -5972,7 +6087,7 @@ var renderPublishReport = (options, manifest, files, warnings) => {
   }
   if (!options.dryRun) {
     lines.push("");
-    lines.push("Now publish it to GitHub:");
+    lines.push("Now push it to GitHub:");
     lines.push(`  cd ${options.outDir}`);
     lines.push(
       '  git init && git add . && git commit -m "Add ${name} package"'.replace(
@@ -6486,12 +6601,17 @@ var GENERATED_SKIP = /* @__PURE__ */ new Set([
   // The `/file-trees` group is exposed by the task layer as `nodes
   // list-file-trees` / `get-file-tree` / `files` / `read-file` /
   // `files-change-request`, each taking `--kind` (see tasks/file-tree.ts).
-  "fileTrees.list",
+  // `fileTrees.list`/`fileTrees.get` are absent because the procedures are: the
+  // two tasks that used to call them now call `nodes.list({ types })` /
+  // `nodes.get`, so there is nothing left for the generator to skip.
   "fileTrees.create",
-  "fileTrees.get",
   "fileTrees.listFiles",
   "fileTrees.readFile",
   "fileTrees.createChangeRequest"
+  // `nodes get` is the curated `docs|files|folders get` facade's underlying
+  // route, but it stays generated too: it is the ONE command that reads a node
+  // of any type without knowing the type first, which is the whole point of the
+  // consolidation.
 ]);
 function registerGeneratedCommands(program, state) {
   const getGroup = (displayName, tag) => program.commands.find((c2) => c2.name() === displayName) ?? program.command(displayName).description(tag ?? `${displayName} endpoints`);
@@ -6893,6 +7013,16 @@ Examples:
   addGlobalFlags(records.command("get")).description("Get one record").requiredOption("--record-id <id>", "record id").action(
     runAction(state, (client, opts) => client.records.get({ recordId: opts.recordId }))
   );
+  addGlobalFlags(records.command("get-by-field")).description("Get one record by an exact field value").requiredOption("--base-id <id>", "Base id").requiredOption("--field-slug <slug>", "field slug").requiredOption("--value-text <value>", "exact field value").action(
+    runAction(
+      state,
+      (client, opts) => getRecordByField(client, {
+        baseId: opts.baseId,
+        fieldSlug: opts.fieldSlug,
+        valueText: opts.valueText
+      })
+    )
+  );
   addGlobalFlags(records.command("change-requests")).description("Change Requests for a record").requiredOption("--record-id <id>", "record id").action(
     runAction(
       state,
@@ -6981,7 +7111,7 @@ Examples:
   addGlobalFlags(assetsCommand.command("grep")).description("Search every text-bearing asset in scope").requiredOption("--pattern <regex>", "literal or regex pattern").option("--flags <flags>", 'RegExp flags, e.g. "i" for case-insensitive').option("--asset-ids <ids...>", "scope: specific asset ids").option("--drive-path <path>", "scope: Drive/Skill mounted path prefix").option("--mime-types <types...>", "scope: MIME types").option("--max-matches <n>", "max matches (default 100, cap 1000)", parsePositiveInt).option("--context-lines <n>", "lines of before/after context (default 0, cap 10)", parseNum).action(
     runAction(
       state,
-      (client, opts) => client.assets.grep({
+      (client, opts) => grepAssets(client, {
         pattern: opts.pattern,
         flags: opts.flags,
         scope: opts.assetIds || opts.drivePath || opts.mimeTypes ? {
@@ -7043,19 +7173,19 @@ field with nothing linked yet does not trigger this.`
       })
     )
   );
-  addGlobalFlags(program.command("publish")).description("Export a node subtree as a Busabase package directory you can push to GitHub").argument("<node-slug-or-id>", "the folder/node to publish").requiredOption("-o, --out-dir <dir>", "output directory for the package").option("--name <name>", "package name (default: reuse busabase.json, else the node slug)").option("--dry-run", "list the files that would be written and write nothing").addHelpText(
+  addGlobalFlags(program.command("export")).description("Export a node subtree as a Busabase package directory you can push to GitHub").argument("<node-slug-or-id>", "the folder/node to export").requiredOption("-o, --out-dir <dir>", "output directory for the package").option("--name <name>", "package name (default: reuse busabase.json, else the node slug)").option("--dry-run", "list the files that would be written and write nothing").addHelpText(
     "after",
     `
-Output is deterministic: publishing twice from an unchanged space produces
+Output is deterministic: exporting twice from an unchanged space produces
 byte-identical files, so a GitHub diff shows exactly what changed.
 
 Examples:
-  busabase-cli publish support-kb -o ./support-kb-template
-  busabase-cli publish support-kb -o ./support-kb-template --name "Support KB" --dry-run`
+  busabase-cli export support-kb -o ./support-kb-template
+  busabase-cli export support-kb -o ./support-kb-template --name "Support KB" --dry-run`
   ).action(
     runArgAction(
       state,
-      (nodeSlugOrId, client, opts, config) => runPublish(client, nodeSlugOrId, {
+      (nodeSlugOrId, client, opts, config) => runExport(client, nodeSlugOrId, {
         outDir: opts.outDir,
         name: opts.name,
         dryRun: Boolean(opts.dryRun),
@@ -7067,7 +7197,7 @@ 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(
+  ).option("--state-only", "superseded by `busabase-cli export` \u2014 see the error text").addHelpText(
     "after",
     `
 A backup is full fidelity: raw rows with their original ids, every doc body, and
@@ -7079,7 +7209,7 @@ Examples:
   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\`,
+To hand content to someone else rather than back it up, use \`busabase-cli export\`,
 which writes a readable, diffable package directory you can push to GitHub.`
   ).action(
     runAction(
@@ -7138,6 +7268,44 @@ To add content to a space that is already in use, use \`busabase-cli install\` i
       );
     })
   );
+  for (const facade of [
+    {
+      group: "docs",
+      type: "doc",
+      label: "Doc",
+      detail: "body included",
+      omitted: "no bodies"
+    },
+    {
+      group: "files",
+      type: "file",
+      label: "File",
+      detail: "backing Asset included",
+      omitted: "no Asset detail"
+    },
+    {
+      group: "folders",
+      type: "folder",
+      label: "Folder",
+      detail: "direct children included",
+      omitted: "no children"
+    }
+  ]) {
+    const group = program.commands.find((c2) => c2.name() === facade.group) ?? program.command(facade.group).description(`${facade.label} nodes`);
+    addGlobalFlags(group.command("list")).description(`List ${facade.label} nodes \u2014 summaries only (${facade.omitted})`).addHelpText(
+      "after",
+      `
+OpenAPI: GET /nodes?types=${facade.type}
+  Follow up with \`${facade.group} get --node-id <id>\` for one node's full detail.`
+    ).action(runAction(state, (client) => client.nodes.list({ types: [facade.type] })));
+    addGlobalFlags(group.command("get")).description(`Get one ${facade.label} node (${facade.detail})`).requiredOption("--node-id <id>", `${facade.label} node id, or a slug unique to this type`).addHelpText("after", `
+OpenAPI: GET /nodes/{nodeId}?type=${facade.type}`).action(
+      runAction(
+        state,
+        (client, opts) => client.nodes.get({ nodeId: opts.nodeId, type: facade.type })
+      )
+    );
+  }
   registerTaskCommands(program, BUSABASE_TASKS, {
     addGlobalFlags,
     parseFieldSpecs,

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunk-DGRADZF2.js";
+} from "./chunk-QJJMAA3K.js";
 
 // src/cli.ts
 process.exit(await runCli(process.argv.slice(2)));

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   HELP,
   render,
   runCli
-} from "./chunk-DGRADZF2.js";
+} from "./chunk-QJJMAA3K.js";
 
 // src/index.ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-cli",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Command-line client for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server`. Short-name alias for busabase-cli.",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-cli",
@@ -33,7 +33,7 @@
   "dependencies": {
     "@zip.js/zip.js": "^2.8.20",
     "busabase-package": "workspace:*",
-    "busabase-sdk": "0.10.2",
+    "busabase-sdk": "0.11.0",
     "commander": "^14.0.0",
     "tar-stream": "^3.1.7",
     "yaml": "^2.9.0",