busabase-sdk 0.40.0 → 0.41.0

package/README.md

@@ -120,7 +120,7 @@ An app that ships its own AirApp node inside the Folder declares it too — `air
 
 **Bases evolve by appending fields.** A live Base whose fields are a strict *prefix* of the declaration is an older schema of yours: the missing suffix is added, one approval-gated `bases.fieldChangeRequest` per field, and anything left unapproved surfaces as `SETUP_PENDING` naming the requests. A field renamed, retyped, reordered, or removed is not an upgrade this can reason about, so it refuses rather than guessing which shape is right.
 
-Failures are an `AirAppSetupError` carrying a `code`: `SETUP_REQUIRED` (offer to initialize), `SETUP_PENDING` (submitted, awaiting approval — approval-first working as designed), `SETUP_CONFLICT`, `SETUP_PERMISSION`, `SCHEMA_INCOMPLETE`. `message` keeps the `"CODE: detail"` shape so code that parses the prefix keeps working.
+Failures are an `AirAppSetupError` carrying a `code`: `SETUP_REQUIRED` (offer to initialize), `SETUP_PENDING` (submitted, awaiting approval — the permission model working as designed), `SETUP_CONFLICT`, `SETUP_PERMISSION`, `SCHEMA_INCOMPLETE`. `message` keeps the `"CODE: detail"` shape so code that parses the prefix keeps working.
 
 ### `busabase-sdk/airapp-gate` — the connect UI (browser)
 

package/dist/airapp.d.ts

@@ -1,4 +1,4 @@
-import { t as BusabaseClient } from "./client-CWlHll4H.js";
+import { t as BusabaseClient } from "./client-vnydDLvt.js";
 //#region src/airapp.d.ts
 type NodeChangeRequestInput = Parameters<BusabaseClient["nodes"]["createChangeRequest"]>[0];
 type NodeOperationInput = NodeChangeRequestInput["operations"][number];

package/dist/{client-CWlHll4H.d.ts → client-vnydDLvt.d.ts}

@@ -380,6 +380,22 @@ interface NodeOutput {
    * what it equals whenever it's omitted).
    */
   hasChildren?: boolean;
+  /**
+   * This node carries its OWN live public share row (`nodes.share`, scope
+   * `public`, not expired) — what the sidebar renders its "shared" marker
+   * from, so an admin can see at a glance which nodes are published without
+   * opening every "•••" → Share dialog.
+   *
+   * Deliberately NOT the inherited answer: a node under a shared folder IS
+   * publicly reachable (that is `effective_public_scope`, which is what the
+   * ACL gates read), but it is not itself a thing anybody chose to publish,
+   * and marking a whole subtree would drown the one row that matters. Read
+   * "who made this public" off the nearest ancestor with `shared: true`.
+   *
+   * Optional/omitted means the read path didn't resolve share state at all
+   * (e.g. a node detail fetch), NOT that the node is unshared.
+   */
+  shared?: boolean;
 }
 //#endregion
 //#region ../../node_modules/@orpc/shared/dist/index.d.mts
@@ -614,6 +630,27 @@ declare const cloudContract: {
     }, z.core.$strip>, z.ZodObject<{
       ancestorIds: z.ZodArray<z.ZodString>;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    resolveRouteState: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      nodeId: z.ZodString;
+      type: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+      }>>;
+    }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+      status: z.ZodLiteral<"active">;
+      nodeId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+      status: z.ZodLiteral<"archived">;
+      nodeId: z.ZodString;
+      type: z.ZodEnum<{
+        [x: string]: string;
+      }>;
+      name: z.ZodString;
+      slug: z.ZodString;
+      archivedAt: z.ZodString;
+      canRestore: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodObject<{
+      status: z.ZodLiteral<"unavailable">;
+    }, z.core.$strip>], "status">, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     createChangeRequest: import("@orpc/contract").ContractProcedure<z.ZodObject<{
       message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
       submittedBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
@@ -7014,7 +7051,25 @@ declare const cloudContract: {
         role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       }, z.core.$strip>>>>;
       body: z.ZodString;
-      mentionsAi: z.ZodBoolean;
+      mentions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+          agent: "agent";
+          member: "member";
+        }>;
+        targetId: z.ZodString;
+        label: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        dispatchStatus: z.ZodEnum<{
+          failed: "failed";
+          linked: "linked";
+          not_applicable: "not_applicable";
+          queued: "queued";
+        }>;
+        sessionId: z.ZodNullable<z.ZodString>;
+        error: z.ZodNullable<z.ZodString>;
+      }, z.core.$strip>>>;
       createdAt: z.ZodString;
       updatedAt: z.ZodString;
     }, z.core.$strip>>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
@@ -7028,7 +7083,15 @@ declare const cloudContract: {
       subjectId: z.ZodString;
       authorId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
       body: z.ZodString;
-      mentionsAi: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+      mentions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+          agent: "agent";
+          member: "member";
+        }>;
+        id: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+      }, z.core.$strip>>>>;
     }, z.core.$strip>, z.ZodObject<{
       id: z.ZodString;
       subjectType: z.ZodEnum<{
@@ -7051,10 +7114,62 @@ declare const cloudContract: {
         role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       }, z.core.$strip>>>>;
       body: z.ZodString;
-      mentionsAi: z.ZodBoolean;
+      mentions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+          agent: "agent";
+          member: "member";
+        }>;
+        targetId: z.ZodString;
+        label: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        dispatchStatus: z.ZodEnum<{
+          failed: "failed";
+          linked: "linked";
+          not_applicable: "not_applicable";
+          queued: "queued";
+        }>;
+        sessionId: z.ZodNullable<z.ZodString>;
+        error: z.ZodNullable<z.ZodString>;
+      }, z.core.$strip>>>;
       createdAt: z.ZodString;
       updatedAt: z.ZodString;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    listMentions: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+      pageSize: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>, z.ZodObject<{
+      items: z.ZodArray<z.ZodObject<{
+        commentId: z.ZodString;
+        subjectType: z.ZodEnum<{
+          change_request: "change_request";
+          commit: "commit";
+          operation: "operation";
+          record: "record";
+        }>;
+        body: z.ZodString;
+        authorId: z.ZodString;
+        author: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+          id: z.ZodString;
+          name: z.ZodNullable<z.ZodString>;
+          email: z.ZodNullable<z.ZodString>;
+          image: z.ZodNullable<z.ZodString>;
+          role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>>;
+        createdAt: z.ZodString;
+        unread: z.ZodBoolean;
+        href: z.ZodNullable<z.ZodString>;
+      }, z.core.$strip>>;
+      total: z.ZodNumber;
+      unreadCount: z.ZodNumber;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    markMentionsRead: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      commentId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+      marked: z.ZodNumber;
+      unreadCount: z.ZodNumber;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
   };
   agent: {
     listTasks: import("@orpc/contract").ContractProcedure<import("@orpc/contract").Schema<unknown, unknown>, z.ZodArray<z.ZodObject<{
@@ -7515,7 +7630,25 @@ declare const cloudContract: {
           role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>>>;
         body: z.ZodString;
-        mentionsAi: z.ZodBoolean;
+        mentions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+          id: z.ZodString;
+          type: z.ZodEnum<{
+            agent: "agent";
+            member: "member";
+          }>;
+          targetId: z.ZodString;
+          label: z.ZodString;
+          start: z.ZodNumber;
+          end: z.ZodNumber;
+          dispatchStatus: z.ZodEnum<{
+            failed: "failed";
+            linked: "linked";
+            not_applicable: "not_applicable";
+            queued: "queued";
+          }>;
+          sessionId: z.ZodNullable<z.ZodString>;
+          error: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>>;
         createdAt: z.ZodString;
         updatedAt: z.ZodString;
       }, z.core.$strip>>;
@@ -10600,7 +10733,7 @@ declare const cloudContract: {
       fieldId: z.ZodString;
       message: z.ZodOptional<z.ZodString>;
       submittedBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-      autoMerge: z.ZodOptional<z.ZodLiteral<false>>;
+      autoMerge: z.ZodOptional<z.ZodBoolean>;
       baseId: z.ZodString;
       operation: z.ZodLiteral<"delete">;
     }, z.core.$strip>, z.ZodObject<{
@@ -10641,7 +10774,7 @@ declare const cloudContract: {
       }>>;
       message: z.ZodOptional<z.ZodString>;
       submittedBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-      autoMerge: z.ZodOptional<z.ZodLiteral<false>>;
+      autoMerge: z.ZodOptional<z.ZodBoolean>;
       baseId: z.ZodString;
       operation: z.ZodLiteral<"convert">;
     }, z.core.$strip>, z.ZodObject<{
@@ -11120,6 +11253,10 @@ declare const cloudContract: {
         whiteboard: "whiteboard";
         yaml: "yaml";
       }>;
+      selectChoiceMode: z.ZodDefault<z.ZodEnum<{
+        auto_create: "auto_create";
+        null_on_missing: "null_on_missing";
+      }>>;
       baseId: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
       totalCount: z.ZodNumber;
@@ -11133,7 +11270,7 @@ declare const cloudContract: {
     lifecycleChangeRequest: import("@orpc/contract").ContractProcedure<z.ZodDiscriminatedUnion<[z.ZodObject<{
       message: z.ZodOptional<z.ZodString>;
       submittedBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-      autoMerge: z.ZodOptional<z.ZodLiteral<false>>;
+      autoMerge: z.ZodOptional<z.ZodBoolean>;
       baseId: z.ZodString;
       operation: z.ZodLiteral<"archive">;
     }, z.core.$strip>, z.ZodObject<{
@@ -14160,7 +14297,7 @@ declare const cloudContract: {
       }, z.core.$strict>>;
       message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
       submittedBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-      autoMerge: z.ZodOptional<z.ZodLiteral<false>>;
+      autoMerge: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
       id: z.ZodString;
       baseId: z.ZodNullable<z.ZodString>;
@@ -20261,13 +20398,13 @@ declare const cloudContract: {
       deleteMode: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         archive: "archive";
       }>>>;
-      autoMerge: z.ZodOptional<z.ZodLiteral<false>>;
+      autoMerge: z.ZodOptional<z.ZodBoolean>;
       recordId: z.ZodString;
       operation: z.ZodLiteral<"delete">;
     }, z.core.$strip>, z.ZodObject<{
       message: z.ZodOptional<z.ZodString>;
       submittedBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-      autoMerge: z.ZodOptional<z.ZodLiteral<false>>;
+      autoMerge: z.ZodOptional<z.ZodBoolean>;
       recordId: z.ZodString;
       operation: z.ZodLiteral<"restore">;
     }, z.core.$strip>], "operation">, z.ZodUnion<readonly [z.ZodObject<{
@@ -24962,6 +25099,13 @@ interface NodeVO {
    * as `children.length > 0`.
    */
   hasChildren?: boolean;
+  /**
+   * This node carries its OWN live public share (`nodes.share`) — see the
+   * matching field on the contract's `NodeOutput` (contract/schemas.ts).
+   * Optional/omitted means the read path didn't resolve share state at all,
+   * NOT that the node is unshared.
+   */
+  shared?: boolean;
 }
 interface CommitVO {
   id: string;
@@ -25074,6 +25218,34 @@ interface ReviewVO {
   visibleOperationHeads: Record<string, string>;
   createdAt: string;
 }
+type CommentMentionTargetType = "member" | "agent";
+/**
+ * Dispatch state of one mention BEFORE a session exists. Once `linked`, the
+ * agent session owns running/waiting/done/failed — it is never mirrored here.
+ */
+type CommentMentionDispatchStatus = "not_applicable" | "queued" | "linked" | "failed";
+/**
+ * One mention as the composer submits it. `start`/`end` are UTF-16 code unit
+ * offsets into the comment body (see the contract schema for why).
+ */
+interface CommentMentionInputDTO {
+  type: CommentMentionTargetType;
+  id: string;
+  start: number;
+  end: number;
+}
+interface CommentMentionVO {
+  id: string;
+  type: CommentMentionTargetType;
+  targetId: string;
+  /** Server-resolved display name; falls back to the raw target id. */
+  label: string;
+  start: number;
+  end: number;
+  dispatchStatus: CommentMentionDispatchStatus;
+  sessionId: string | null;
+  error: string | null;
+}
 interface CommentVO {
   id: string;
   subjectType: CommentSubjectType;
@@ -25085,10 +25257,38 @@ interface CommentVO {
   authorId: string;
   author?: UserRefVO | null;
   body: string;
-  mentionsAi: boolean;
+  mentions: CommentMentionVO[];
   createdAt: string;
   updatedAt: string;
 }
+/**
+ * One row of the Inbox's Mentions tab.
+ *
+ * Keyed by comment, not by mention row: being named twice in one comment is
+ * legitimate (each occurrence renders its own chip) but it is still one thing
+ * to go read, so it is one entry here.
+ */
+interface MentionInboxItemVO {
+  commentId: string;
+  subjectType: CommentSubjectType;
+  body: string;
+  authorId: string;
+  author: UserRefVO | null;
+  createdAt: string;
+  unread: boolean;
+  /**
+   * Dashboard-relative path to the comment in context, or null when the
+   * subject has no page of its own (a `commit`-scoped comment not attached to
+   * a change request — there is no commit detail route). A null href still
+   * renders a row.
+   */
+  href: string | null;
+}
+interface MentionInboxPageVO {
+  items: MentionInboxItemVO[];
+  total: number;
+  unreadCount: number;
+}
 interface AgentTaskVO {
   changeRequest: ChangeRequestVO;
   trigger: "changes_requested" | "ai_mention";
@@ -25233,4 +25433,4 @@ declare function resolveConfig(config?: BusabaseConfig): ResolvedConfig;
  */
 declare function createBusabaseClient(config?: BusabaseConfig): BusabaseClient;
 //#endregion
-export { FileTreeReadFileVO as $, SearchResultKind as A, AttachmentRef as At, VaultRuntimeEnv as B, NodeSearchResultVO as C, VIEW_FIELD_MIN_WIDTH as Ct, ReviewVO as D, ViewSortVO as Dt, OperationVO as E, ViewFilterVO as Et, VaultAccessPolicy as F, CREATABLE_NODE_TYPES as Ft, AssetDetailVO as G, VaultSettingsVO as H, VaultEnvironment as I, CreatableNodeType as It, AssetVO as J, AssetTextStatus as K, VaultItemInput as L, NodeType as Lt, SourceAttributionVO as M, cloudContract as Mt, UserRefVO as N, NodeIcon as Nt, ReviewVerdict as O, ViewType as Ot, UpdateVaultSettingsDTO as P, NodeIconSchema as Pt, FileTreeNodeVO as Q, VaultItemKind as R, OperationKind as Rt, LookupRollup as S, VIEW_FIELD_MAX_WIDTH as St, OperationStatus as T, ViewFilterOperator as Tt, FileNodeMetadata as U, VaultScopeType as V, FileNodeVO as W, GrepResultVO as X, GrepInputDTO as Y, FileTreeFileVO as Z, ChangeRequestVO as _, GalleryCardSize as _t, createBusabaseClient as a, FormPageSourceVO as at, CommitVO as b, RecordLinkVO as bt, AuditAction as c, FormThemeVO as ct, ChangeRequestBatchFailureVO as d, ListFormsVO as dt, NodeDetailVO as et, ChangeRequestCountsVO as f, SubmitFormDTO as ft, ChangeRequestTargetType as g, BaseVO as gt, ChangeRequestStatus as h, BaseFieldVO as ht, ResolvedConfig as i, FormFieldBindingVO as it, SearchResultVO as j, CloudContract as jt, SearchResponseVO as k, ViewVO as kt, AuditEventVO as l, FormVO as lt, ChangeRequestReviewBatchResultVO as m, AssetAttachmentRef as mt, BusabaseConfig as n, CreateFormDTO as nt, resolveConfig as o, FormShareVO as ot, ChangeRequestMergeBatchResultVO as p, UpdateFormDTO as pt, AssetUsageVO as q, DEFAULT_BASE_URL as r, FormBoundFieldVO as rt, AgentTaskVO as s, FormSubmitResultVO as st, BusabaseClient as t, ActivityItemVO as tt, BusabaseSourceChannel as u, ListFormsDTO as ut, CommentSubjectType as v, GalleryCoverFit as vt, NodeVO as w, ViewConfigVO as wt, FieldType as x, RecordVO as xt, CommentVO as y, GanttScale as yt, VaultItemVO as z };
+export { AssetUsageVO as $, NodeVO as A, ViewConfigVO as At, UpdateVaultSettingsDTO as B, NodeIconSchema as Bt, CommentVO as C, GalleryCardSize as Ct, MentionInboxItemVO as D, RecordVO as Dt, LookupRollup as E, RecordLinkVO as Et, SearchResponseVO as F, ViewVO as Ft, VaultItemVO as G, VaultEnvironment as H, CreatableNodeType as Ht, SearchResultKind as I, AttachmentRef as It, VaultSettingsVO as J, VaultRuntimeEnv as K, SearchResultVO as L, CloudContract as Lt, OperationVO as M, ViewFilterVO as Mt, ReviewVO as N, ViewSortVO as Nt, MentionInboxPageVO as O, VIEW_FIELD_MAX_WIDTH as Ot, ReviewVerdict as P, ViewType as Pt, AssetTextStatus as Q, SourceAttributionVO as R, cloudContract as Rt, CommentSubjectType as S, BaseVO as St, FieldType as T, GanttScale as Tt, VaultItemInput as U, NodeType as Ut, VaultAccessPolicy as V, CREATABLE_NODE_TYPES as Vt, VaultItemKind as W, OperationKind as Wt, FileNodeVO as X, FileNodeMetadata as Y, AssetDetailVO as Z, ChangeRequestVO as _, ListFormsVO as _t, createBusabaseClient as a, FileTreeReadFileVO as at, CommentMentionTargetType as b, AssetAttachmentRef as bt, AuditAction as c, CreateFormDTO as ct, ChangeRequestBatchFailureVO as d, FormPageSourceVO as dt, AssetVO as et, ChangeRequestCountsVO as f, FormShareVO as ft, ChangeRequestTargetType as g, ListFormsDTO as gt, ChangeRequestStatus as h, FormVO as ht, ResolvedConfig as i, FileTreeNodeVO as it, OperationStatus as j, ViewFilterOperator as jt, NodeSearchResultVO as k, VIEW_FIELD_MIN_WIDTH as kt, AuditEventVO as l, FormBoundFieldVO as lt, ChangeRequestReviewBatchResultVO as m, FormThemeVO as mt, BusabaseConfig as n, GrepResultVO as nt, resolveConfig as o, NodeDetailVO as ot, ChangeRequestMergeBatchResultVO as p, FormSubmitResultVO as pt, VaultScopeType as q, DEFAULT_BASE_URL as r, FileTreeFileVO as rt, AgentTaskVO as s, ActivityItemVO as st, BusabaseClient as t, GrepInputDTO as tt, BusabaseSourceChannel as u, FormFieldBindingVO as ut, CommentMentionDispatchStatus as v, SubmitFormDTO as vt, CommitVO as w, GalleryCoverFit as wt, CommentMentionVO as x, BaseFieldVO as xt, CommentMentionInputDTO as y, UpdateFormDTO as yt, UserRefVO as z, NodeIcon as zt };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as FileTreeReadFileVO, A as SearchResultKind, At as AttachmentRef, B as VaultRuntimeEnv, C as NodeSearchResultVO, Ct as VIEW_FIELD_MIN_WIDTH, D as ReviewVO, Dt as ViewSortVO, E as OperationVO, Et as ViewFilterVO, F as VaultAccessPolicy, Ft as CREATABLE_NODE_TYPES, G as AssetDetailVO, H as VaultSettingsVO, I as VaultEnvironment, It as CreatableNodeType, J as AssetVO, K as AssetTextStatus, L as VaultItemInput, Lt as NodeType, M as SourceAttributionVO, Mt as cloudContract, N as UserRefVO, Nt as NodeIcon, O as ReviewVerdict, Ot as ViewType, P as UpdateVaultSettingsDTO, Pt as NodeIconSchema, Q as FileTreeNodeVO, R as VaultItemKind, Rt as OperationKind, S as LookupRollup, St as VIEW_FIELD_MAX_WIDTH, T as OperationStatus, Tt as ViewFilterOperator, U as FileNodeMetadata, V as VaultScopeType, W as FileNodeVO, X as GrepResultVO, Y as GrepInputDTO, Z as FileTreeFileVO, _ as ChangeRequestVO, _t as GalleryCardSize, a as createBusabaseClient, at as FormPageSourceVO, b as CommitVO, bt as RecordLinkVO, c as AuditAction, ct as FormThemeVO, d as ChangeRequestBatchFailureVO, dt as ListFormsVO, et as NodeDetailVO, f as ChangeRequestCountsVO, ft as SubmitFormDTO, g as ChangeRequestTargetType, gt as BaseVO, h as ChangeRequestStatus, ht as BaseFieldVO, i as ResolvedConfig, it as FormFieldBindingVO, j as SearchResultVO, jt as CloudContract, k as SearchResponseVO, kt as ViewVO, l as AuditEventVO, lt as FormVO, m as ChangeRequestReviewBatchResultVO, mt as AssetAttachmentRef, n as BusabaseConfig, nt as CreateFormDTO, o as resolveConfig, ot as FormShareVO, p as ChangeRequestMergeBatchResultVO, pt as UpdateFormDTO, q as AssetUsageVO, r as DEFAULT_BASE_URL, rt as FormBoundFieldVO, s as AgentTaskVO, st as FormSubmitResultVO, t as BusabaseClient, tt as ActivityItemVO, u as BusabaseSourceChannel, ut as ListFormsDTO, v as CommentSubjectType, vt as GalleryCoverFit, w as NodeVO, wt as ViewConfigVO, x as FieldType, xt as RecordVO, y as CommentVO, yt as GanttScale, z as VaultItemVO } from "./client-CWlHll4H.js";
+import { $ as AssetUsageVO, A as NodeVO, At as ViewConfigVO, B as UpdateVaultSettingsDTO, Bt as NodeIconSchema, C as CommentVO, Ct as GalleryCardSize, D as MentionInboxItemVO, Dt as RecordVO, E as LookupRollup, Et as RecordLinkVO, F as SearchResponseVO, Ft as ViewVO, G as VaultItemVO, H as VaultEnvironment, Ht as CreatableNodeType, I as SearchResultKind, It as AttachmentRef, J as VaultSettingsVO, K as VaultRuntimeEnv, L as SearchResultVO, Lt as CloudContract, M as OperationVO, Mt as ViewFilterVO, N as ReviewVO, Nt as ViewSortVO, O as MentionInboxPageVO, Ot as VIEW_FIELD_MAX_WIDTH, P as ReviewVerdict, Pt as ViewType, Q as AssetTextStatus, R as SourceAttributionVO, Rt as cloudContract, S as CommentSubjectType, St as BaseVO, T as FieldType, Tt as GanttScale, U as VaultItemInput, Ut as NodeType, V as VaultAccessPolicy, Vt as CREATABLE_NODE_TYPES, W as VaultItemKind, Wt as OperationKind, X as FileNodeVO, Y as FileNodeMetadata, Z as AssetDetailVO, _ as ChangeRequestVO, _t as ListFormsVO, a as createBusabaseClient, at as FileTreeReadFileVO, b as CommentMentionTargetType, bt as AssetAttachmentRef, c as AuditAction, ct as CreateFormDTO, d as ChangeRequestBatchFailureVO, dt as FormPageSourceVO, et as AssetVO, f as ChangeRequestCountsVO, ft as FormShareVO, g as ChangeRequestTargetType, gt as ListFormsDTO, h as ChangeRequestStatus, ht as FormVO, i as ResolvedConfig, it as FileTreeNodeVO, j as OperationStatus, jt as ViewFilterOperator, k as NodeSearchResultVO, kt as VIEW_FIELD_MIN_WIDTH, l as AuditEventVO, lt as FormBoundFieldVO, m as ChangeRequestReviewBatchResultVO, mt as FormThemeVO, n as BusabaseConfig, nt as GrepResultVO, o as resolveConfig, ot as NodeDetailVO, p as ChangeRequestMergeBatchResultVO, pt as FormSubmitResultVO, q as VaultScopeType, r as DEFAULT_BASE_URL, rt as FileTreeFileVO, s as AgentTaskVO, st as ActivityItemVO, t as BusabaseClient, tt as GrepInputDTO, u as BusabaseSourceChannel, ut as FormFieldBindingVO, v as CommentMentionDispatchStatus, vt as SubmitFormDTO, w as CommitVO, wt as GalleryCoverFit, x as CommentMentionVO, xt as BaseFieldVO, y as CommentMentionInputDTO, yt as UpdateFormDTO, z as UserRefVO, zt as NodeIcon } from "./client-vnydDLvt.js";
 import { z } from "zod";
 //#region src/url.d.ts
 /**
@@ -426,4 +426,4 @@ declare class Busabase {
   }>>>>;
 }
 //#endregion
-export { type ActivityItemVO, type AgentTaskVO, type FileTreeFileVO as AirAppFileVO, type FileTreeFileVO as DriveFileVO, type FileTreeFileVO, type FileTreeFileVO as SkillFileVO, type FileTreeReadFileVO as AirAppReadFileVO, type FileTreeReadFileVO as DriveReadFileVO, type FileTreeReadFileVO, type FileTreeReadFileVO as SkillReadFileVO, type FileTreeNodeVO as AirAppVO, type FileTreeNodeVO as DriveVO, type FileTreeNodeVO, type FileTreeNodeVO as SkillVO, type AssetAttachmentRef, type AssetDetailVO, type AssetTextStatus, type AssetUsageVO, type AssetVO, type AttachmentRef, type AuditAction, type AuditEventVO, type BaseFieldVO, type BaseVO, Busabase, type BusabaseAssetsClient, BusabaseChangeRequestsClient, type BusabaseClient, type BusabaseConfig, type BusabaseRecordsClient, type BusabaseSourceChannel, CREATABLE_NODE_TYPES, type ChangeRequestBatchFailureVO, type ChangeRequestCountsVO, type ChangeRequestMergeBatchResultVO, type ChangeRequestReviewBatchResultVO, type ChangeRequestStatus, type ChangeRequestTargetType, type ChangeRequestVO, type CloudContract, type CommentSubjectType, type CommentVO, type CommitVO, type CreatableNodeType, type CreateFormDTO, DEFAULT_BASE_URL, type FieldType, type FileNodeMetadata, type FileNodeVO, type FormBoundFieldVO, type FormFieldBindingVO, type FormPageSourceVO, type FormShareVO, type FormSubmitResultVO, type FormThemeVO, type FormVO, type GalleryCardSize, type GalleryCoverFit, type GanttScale, type ListFormsDTO, type ListFormsVO, type LookupRollup, type NodeDetailVO, type NodeIcon, type NodeIconSchema, type NodeSearchResultVO, type NodeType, type NodeVO, type NodeWebUrlInput, type OperationKind, type OperationStatus, type OperationVO, type RecordByFieldInput, type RecordLinkVO, type RecordVO, type ResolvedConfig, type ReviewVO, type ReviewVerdict, type SearchResponseVO, type SearchResultKind, type SearchResultVO, type SourceAttributionVO, type SubmitFormDTO, type UpdateFormDTO, type UpdateVaultSettingsDTO, type UserRefVO, type VIEW_FIELD_MAX_WIDTH, type VIEW_FIELD_MIN_WIDTH, type VaultAccessPolicy, type VaultEnvironment, type VaultItemInput, type VaultItemKind, type VaultItemVO, type VaultRuntimeEnv, type VaultScopeType, type VaultSettingsVO, type ViewConfigVO, type ViewFilterOperator, type ViewFilterVO, type ViewSortVO, type ViewType, type ViewVO, cloudContract, createBusabaseClient, getRecordByField, grepAssets, nodeWebUrl, normalizeBaseUrl, resolveConfig, toFilesOnlyGrepResult, toUnifiedFilesGrepInput };
+export { type ActivityItemVO, type AgentTaskVO, type FileTreeFileVO as AirAppFileVO, type FileTreeFileVO as DriveFileVO, type FileTreeFileVO, type FileTreeFileVO as SkillFileVO, type FileTreeReadFileVO as AirAppReadFileVO, type FileTreeReadFileVO as DriveReadFileVO, type FileTreeReadFileVO, type FileTreeReadFileVO as SkillReadFileVO, type FileTreeNodeVO as AirAppVO, type FileTreeNodeVO as DriveVO, type FileTreeNodeVO, type FileTreeNodeVO as SkillVO, type AssetAttachmentRef, type AssetDetailVO, type AssetTextStatus, type AssetUsageVO, type AssetVO, type AttachmentRef, type AuditAction, type AuditEventVO, type BaseFieldVO, type BaseVO, Busabase, type BusabaseAssetsClient, BusabaseChangeRequestsClient, type BusabaseClient, type BusabaseConfig, type BusabaseRecordsClient, type BusabaseSourceChannel, CREATABLE_NODE_TYPES, type ChangeRequestBatchFailureVO, type ChangeRequestCountsVO, type ChangeRequestMergeBatchResultVO, type ChangeRequestReviewBatchResultVO, type ChangeRequestStatus, type ChangeRequestTargetType, type ChangeRequestVO, type CloudContract, type CommentMentionDispatchStatus, type CommentMentionInputDTO, type CommentMentionTargetType, type CommentMentionVO, type CommentSubjectType, type CommentVO, type CommitVO, type CreatableNodeType, type CreateFormDTO, DEFAULT_BASE_URL, type FieldType, type FileNodeMetadata, type FileNodeVO, type FormBoundFieldVO, type FormFieldBindingVO, type FormPageSourceVO, type FormShareVO, type FormSubmitResultVO, type FormThemeVO, type FormVO, type GalleryCardSize, type GalleryCoverFit, type GanttScale, type ListFormsDTO, type ListFormsVO, type LookupRollup, type MentionInboxItemVO, type MentionInboxPageVO, type NodeDetailVO, type NodeIcon, type NodeIconSchema, type NodeSearchResultVO, type NodeType, type NodeVO, type NodeWebUrlInput, type OperationKind, type OperationStatus, type OperationVO, type RecordByFieldInput, type RecordLinkVO, type RecordVO, type ResolvedConfig, type ReviewVO, type ReviewVerdict, type SearchResponseVO, type SearchResultKind, type SearchResultVO, type SourceAttributionVO, type SubmitFormDTO, type UpdateFormDTO, type UpdateVaultSettingsDTO, type UserRefVO, type VIEW_FIELD_MAX_WIDTH, type VIEW_FIELD_MIN_WIDTH, type VaultAccessPolicy, type VaultEnvironment, type VaultItemInput, type VaultItemKind, type VaultItemVO, type VaultRuntimeEnv, type VaultScopeType, type VaultSettingsVO, type ViewConfigVO, type ViewFilterOperator, type ViewFilterVO, type ViewSortVO, type ViewType, type ViewVO, cloudContract, createBusabaseClient, getRecordByField, grepAssets, nodeWebUrl, normalizeBaseUrl, resolveConfig, toFilesOnlyGrepResult, toUnifiedFilesGrepInput };

package/dist/index.js

@@ -358,24 +358,30 @@ const iStringSchema = z.union([z.string(), iStringRecordSchema]).describe("i18n
 //#endregion
 //#region ../../packages/busabase-contract/src/contract/auto-merge.ts
 /**
-* `autoMerge` on an operation that deliberately never auto-merges.
+* `autoMerge` on a destructive-but-reversible operation.
 *
-* These schemas are NOT `.strict()` — and making them strict is not the fix. The
-* SDK and CLI ship on their own npm cadence (published ahead of the server as of
-* writing), and busabase is self-hosted, so a newer client sending a newer
-* optional field to an older server is normal traffic. Blanket strictness turns
-* that graceful degradation into a hard 400 for every field, to catch one.
+* These six operations (record delete/restore, field delete/convert, Base
+* archive, mounted-asset content edits, and file batches containing a delete)
+* used to reject `autoMerge: true` outright: they queued for human review no
+* matter who called them. That made sense while the product was positioned as
+* approval-first, but it is not how Busabase is positioned or how the rest of
+* the write surface behaves — every other write is *permission-aware*
+* (`shouldAutoMerge`): unset + write access on the target node means "just do
+* it", and only an explicit `false` forces review.
 *
-* So reject exactly the field that actually confused callers, and say WHY plus
-* what to do instead — an agent reading "unrecognized key: autoMerge" learns
-* nothing it can act on, which is how the original silent-drop bug survived.
+* A single person running their own workspace hit the old behaviour as pure
+* friction: archiving one duplicate record left a change request they then had
+* to go and approve themselves. Reversibility is what makes the permission-aware
+* default safe here — delete ARCHIVES, archive is undone by restore, and a
+* field convert is preceded by `previewFieldConversion`. Callers who do want a
+* second pair of eyes still get it by passing an explicit `autoMerge: false`,
+* which is exactly how every other endpoint in this family expresses that.
 *
-* Rejects `true` only. An explicit `false` asks for exactly what these operations
-* already do, so refusing it would be pedantry with a cost: every review-first
-* call site in this repo passes a uniform `autoMerge: false`, and clients that do
-* the same must not start collecting 400s on the subset of endpoints where the
-* flag happens to be moot. Same forward-compatibility argument that rules out
-* blanket `.strict()`.
+* The schemas that use this are NOT `.strict()`, and making them strict is not
+* the fix: the SDK and CLI ship on their own npm cadence and busabase is
+* self-hosted, so a newer client sending a newer optional field to an older
+* server is normal traffic. Blanket strictness turns that graceful degradation
+* into a hard 400 for every field, to catch one.
 *
 * This lives in its own leaf module (zod only, no sibling imports) on purpose:
 * putting it in `contract/schemas.ts` created an import cycle with the domain
@@ -383,7 +389,7 @@ const iStringSchema = z.union([z.string(), iStringRecordSchema]).describe("i18n
 * `ReferenceError: Cannot access 'autoMergeNotAccepted' before initialization`
 * that `tsc` reported as clean.
 */
-const autoMergeNotAccepted = (reason) => z.literal(false, { error: `\`autoMerge: true\` is not accepted here: ${reason}` }).optional().describe(`Only \`false\` (or omitted) is accepted. ${reason}`);
+const destructiveAutoMerge = (undoNote) => z.boolean().optional().describe(`Whether to approve and merge this change immediately. Omitted defaults to merging immediately if the actor has write access on the target node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access. ${undoNote}`);
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/base/contract/base-schemas.ts
 const fieldNameSchema = z.union([z.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")]);
@@ -530,16 +536,13 @@ const createBaseFieldInputSchema = z.object({
 * node, otherwise falls back to a pending ChangeRequest. Explicit `false` forces
 * review even with write access.
 *
-* Deliberately NOT on the `delete` and `convert` branches below. The line this
-* codebase already draws — record `update` auto-merges, record `delete`/`restore`
-* never do, and `assets.editContent` never does — is about whether CONTENT data
-* is at stake, not about the verb. Adding, renaming, reordering, or un-deleting a
-* field touches only the schema; deleting one soft-deletes its stored values with
-* it, and converting one can drop values outright (which is why
-* `previewFieldConversion` exists as a dry run). Those two stay in front of a
-* human.
+* The `delete` and `convert` branches below used to reject `autoMerge` outright.
+* They no longer do — see `contract/auto-merge.ts` for why. They carry a
+* `destructiveAutoMerge` schema instead: the same tri-state, with a description
+* that says what the operation costs to undo, so a caller who genuinely wants a
+* second pair of eyes knows to pass `false`.
 */
-const fieldAutoMergeSchema = z.boolean().optional().describe("Whether to approve and merge this field 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. Not accepted by the delete and convert operations, which always require review.");
+const fieldAutoMergeSchema = z.boolean().optional().describe("Whether to approve and merge this field 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.");
 const createFieldChangeRequestInputSchema = createBaseFieldInputSchema.extend({
 	message: z.string().optional().default("Add field"),
 	submittedBy: z.string().optional().default("local-editor"),
@@ -549,7 +552,7 @@ const deleteFieldChangeRequestInputSchema = z.object({
 	fieldId: z.string().min(1),
 	message: z.string().optional(),
 	submittedBy: z.string().optional().default("local-editor"),
-	autoMerge: autoMergeNotAccepted("deleting a field soft-deletes its stored values with it, so it always requires review. Omit the flag.")
+	autoMerge: destructiveAutoMerge("A deleted field is soft-deleted with its stored values and is brought back by the `restore` operation.")
 });
 const updateFieldChangeRequestInputSchema = z.object({
 	fieldId: z.string().min(1),
@@ -564,7 +567,15 @@ const updateFieldChangeRequestInputSchema = z.object({
 });
 const previewFieldConversionInputSchema = z.object({
 	fieldId: z.string().min(1),
-	newType: fieldTypeSchema
+	newType: fieldTypeSchema,
+	/**
+	* Mirrors `convertFieldChangeRequest.selectChoiceMode` so the dry run models the
+	* conversion the caller is actually going to submit. Under `auto_create` a value with
+	* no matching choice is not a conflict — the merge mints a choice for it — while under
+	* `null_on_missing` the same value is dropped. Defaults to `null_on_missing`, matching
+	* the mutation's own default.
+	*/
+	selectChoiceMode: z.enum(["auto_create", "null_on_missing"]).default("null_on_missing")
 });
 const previewFieldConversionOutputSchema = z.object({
 	totalCount: z.number(),
@@ -581,7 +592,7 @@ const convertFieldChangeRequestInputSchema = z.object({
 	selectChoiceMode: z.enum(["auto_create", "null_on_missing"]).default("null_on_missing"),
 	message: z.string().optional(),
 	submittedBy: z.string().optional().default("local-editor"),
-	autoMerge: autoMergeNotAccepted("converting a field's type can drop values, so it always requires review. Run previewFieldConversion first to see what would change, then omit the flag.")
+	autoMerge: destructiveAutoMerge("A convert can drop values that do not fit the new type — call `previewFieldConversion` first to see exactly which, and pass `autoMerge: false` if you want a human to sign off on that preview.")
 });
 const reorderFieldsChangeRequestInputSchema = z.object({
 	fieldIds: z.array(z.string()).min(1),
@@ -592,7 +603,7 @@ const reorderFieldsChangeRequestInputSchema = z.object({
 const archiveBaseInputSchema = z.object({
 	message: z.string().optional(),
 	submittedBy: z.string().optional().default("local-editor"),
-	autoMerge: autoMergeNotAccepted("archiving a Base removes it and every record in it from every listing at once, so it always requires review. Omit the flag.")
+	autoMerge: destructiveAutoMerge("Archiving takes the Base and every record in it out of every listing at once. That is reversible via `operation: \"restore\"`, but it is the widest-blast-radius write in this family — pass `autoMerge: false` when it should stop for a human.")
 });
 const restoreBaseInputSchema = z.object({
 	message: z.string().optional(),
@@ -875,7 +886,7 @@ const folderNodeType = {
 /**
 * Form node: an agent-authored, sandboxed web page bound to a Base via an
 * explicit field-binding contract. A submission does NOT write a record
-* directly — it produces an approval-first record-create ChangeRequest on the
+* directly — it produces a review-first record-create ChangeRequest on the
 * target Base (so the submitting act reuses the base's `record_create` op, not a
 * form-specific one). The form's own config (bindings/page/share) is owner-
 * managed and edited directly, so this node contributes no CR operations of its
@@ -1085,8 +1096,8 @@ const NodeIconSchema = z.discriminatedUnion("type", [z.object({
 //#region ../../packages/busabase-contract/src/contract/node-agent-prompt-schemas.ts
 /**
 * Per-node custom scenario prompts (`node.metadata.agentPrompts`) — the single
-* schema shared by BOTH write and read paths, per
-* `apps/busabase-cloud/content/spec/node-agent-prompts-v2.md` §7.3:
+* schema shared by BOTH write and read paths, per the node-agent-prompts
+* design (v2) §7.3:
 *
 * - Write: `busabase-cli nodes set-agent-prompts` validates a file against this
 *   schema client-side, before calling `nodes.updateMetadata` — a malformed file
@@ -1178,7 +1189,8 @@ const nodeSchema = z.lazy(() => z.object({
 	updatedAt: z.string(),
 	baseId: z.string().nullable(),
 	children: z.array(nodeSchema),
-	hasChildren: z.boolean().optional()
+	hasChildren: z.boolean().optional(),
+	shared: z.boolean().optional()
 }));
 const nodePrincipalSchema = z.object({
 	id: z.string(),
@@ -1404,6 +1416,55 @@ const commentSubjectTypeSchema = z.enum([
 	"operation",
 	"commit"
 ]);
+/**
+* Who a mention points at. `member` tags a person; `agent` names a launchable
+* Agent target and is what actually starts a session.
+*/
+const commentMentionTargetTypeSchema = z.enum(["member", "agent"]);
+/**
+* Dispatch lifecycle of ONE mention row, before a session exists.
+*
+* `not_applicable` is every member row (a person is not dispatched to).
+* Once `linked`, running/waiting/done/failed belongs to the agent session,
+* never to a second status column here.
+*/
+const commentMentionDispatchStatusSchema = z.enum([
+	"not_applicable",
+	"queued",
+	"linked",
+	"failed"
+]);
+/**
+* One mention as the composer submits it.
+*
+* `start`/`end` are **UTF-16 code unit** offsets into `body` — the same unit
+* `<textarea>` selection APIs and `String.prototype.slice` use, so nothing has
+* to convert at the UI boundary. A label containing an astral-plane character
+* (an emoji in a display name) therefore spans two units per visible glyph;
+* the server rejects a span that would split a surrogate pair.
+*
+* No `label` here on purpose: the client never supplies identity. The server
+* resolves the display name from the member/catalog it already trusts.
+*/
+const commentMentionInputSchema = z.object({
+	type: commentMentionTargetTypeSchema,
+	/** Member/actor id, or launchable agent slug (`claude-acp`, `buda:<agentId>`). */
+	id: z.string().min(1),
+	start: z.number().int().min(0),
+	end: z.number().int().min(0)
+});
+const commentMentionSchema = z.object({
+	id: z.string(),
+	type: commentMentionTargetTypeSchema,
+	targetId: z.string(),
+	/** Server-resolved display name. Falls back to the raw target id. */
+	label: z.string(),
+	start: z.number().int(),
+	end: z.number().int(),
+	dispatchStatus: commentMentionDispatchStatusSchema,
+	sessionId: z.string().nullable(),
+	error: z.string().nullable()
+});
 const commentSchema = z.object({
 	id: z.string(),
 	subjectType: commentSubjectTypeSchema,
@@ -1415,10 +1476,55 @@ const commentSchema = z.object({
 	authorId: z.string(),
 	author: userRefSchema.nullable().optional().default(null),
 	body: z.string(),
-	mentionsAi: z.boolean(),
+	mentions: z.array(commentMentionSchema).default([]),
 	createdAt: z.string(),
 	updatedAt: z.string()
 });
+/**
+* One row of the Inbox's Mentions tab: a comment the caller was `@`-mentioned
+* in, plus where to go to read it in context.
+*
+* Keyed by COMMENT, not by mention row — being named twice in one comment is
+* legitimate (each occurrence needs its own span to render its own chip), but
+* it is still one thing to go read, so it is one entry here.
+*/
+const mentionInboxItemSchema = z.object({
+	commentId: z.string(),
+	subjectType: commentSubjectTypeSchema,
+	/** Comment body, for the row's preview line. */
+	body: z.string(),
+	authorId: z.string(),
+	author: userRefSchema.nullable().optional().default(null),
+	createdAt: z.string(),
+	/** Null once read. The newest unread stamp across this comment's mentions. */
+	unread: z.boolean(),
+	/**
+	* Dashboard-relative path to the comment's context, or null when the subject
+	* has no page of its own (a `commit`-scoped comment on a comment that is not
+	* attached to a change request — the repo has no commit detail route).
+	* A null href still renders a row: swallowing the notification because we
+	* cannot link it would leave the recipient never knowing they were mentioned.
+	*/
+	href: z.string().nullable()
+});
+const mentionInboxPageSchema = z.object({
+	items: z.array(mentionInboxItemSchema),
+	total: z.number().int(),
+	/** Distinct unread comments — what the tab badge shows. */
+	unreadCount: z.number().int()
+});
+const listMentionInboxInputSchema = z.object({
+	page: z.number().int().min(1).optional().default(1),
+	pageSize: z.number().int().min(1).max(100).optional().default(50)
+});
+const markMentionsReadInputSchema = z.object({ 
+/** Stamps every unread mention row this caller has on that comment. */
+commentId: z.string() });
+const markMentionsReadOutputSchema = z.object({
+	/** How many rows were stamped; 0 when it was already read. */
+	marked: z.number().int(),
+	unreadCount: z.number().int()
+});
 const changeRequestStatusSchema = z.enum([
 	"in_review",
 	"changes_requested",
@@ -1634,7 +1740,7 @@ const createDeleteChangeRequestInputSchema = z.object({
 	message: z.string().optional().default("Delete record").describe("Explanation shown to the human reviewer. Say what is being removed and why, e.g. \"Archive duplicate contact — merged into Acme Corp\"."),
 	submittedBy: z.string().optional().default("local-producer"),
 	deleteMode: z.enum(["archive"]).optional().default("archive"),
-	autoMerge: autoMergeNotAccepted("archiving a record removes user content from every listing, so it always requires review. Omit the flag.")
+	autoMerge: destructiveAutoMerge("Archiving is reversible: the record leaves every listing but is restored intact by `operation: \"restore\"`.")
 });
 const reviseOperationInputSchema = z.object({
 	fields: z.record(z.string(), z.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 — it is the record's display title everywhere."),
@@ -1653,7 +1759,12 @@ const commentSubjectInputSchema = z.object({
 const createCommentInputSchema = commentSubjectInputSchema.extend({
 	authorId: z.string().optional().default("local-admin"),
 	body: z.string().trim().min(1),
-	mentionsAi: z.boolean().optional().default(false)
+	/**
+	* Structured mentions, owned by the composer. Never inferred from the body by
+	* regex: display names contain spaces and collide with ordinary prose, so
+	* "ask codex about this" must not invoke Codex.
+	*/
+	mentions: z.array(commentMentionInputSchema).optional().default([])
 });
 const listInputSchema = z.object({ limit: z.coerce.number().int().min(1).max(100).optional().default(50) }).optional().default({ limit: 50 });
 /**
@@ -1885,7 +1996,7 @@ const createFileTreeChangeRequestInputSchema = z.object({
 	message: z.string().optional().default("Update file tree").describe("Explanation shown to the human reviewer. Write a conventional-commit style subject — imperative verb + what + why, e.g. \"Rewrite README.md quickstart for the new auth flow\"."),
 	submittedBy: z.string().optional().default("local-producer"),
 	operations: z.array(fileTreeFileOperationInputSchema).min(1),
-	autoMerge: z.boolean().optional().describe("Whether to approve and merge these file changes immediately. Omitted defaults to merging immediately if the actor has write access on the node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access. IGNORED when any operation is a delete — those batches always require review.")
+	autoMerge: z.boolean().optional().describe("Whether to approve and merge these file changes immediately. Omitted defaults to merging immediately if the actor has write access on the node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access. Applies to every operation kind, deletes included.")
 });
 const fileTreeNodeTypeSchema = z.enum([
 	"skill",
@@ -2271,7 +2382,7 @@ const EditAssetContentInputSchema = z.object({
 	edits: z.array(AssetContentEditSchema).min(1),
 	message: z.string().optional().default("Edit file content").describe("Explanation shown to the human reviewer. Write a conventional-commit style subject — imperative verb + what + why, e.g. \"Fix typo in setup instructions\"."),
 	submittedBy: z.string().optional().default("agent"),
-	autoMerge: autoMergeNotAccepted("editContent rewrites the real mounted file bytes, so it always requires review. Omit the flag.")
+	autoMerge: destructiveAutoMerge("This rewrites the real mounted file bytes; the previous content stays in the Change Request history, so it is recoverable but not one-click undoable.")
 });
 /**
 * `GET /assets/{assetId}/content` result. oRPC contracts here are JSON in/out
@@ -2375,7 +2486,7 @@ const assetsContract = {
 		path: "/assets/{assetId}/edit-content",
 		tags: ["Assets", "Change Requests"],
 		summary: "Edit an asset's file content via string-replace edits, as a ChangeRequest",
-		successDescription: "Applied the string-replace edits (coding-agent Edit-tool semantics: unique-match or replaceAll) to the asset's current mounted Drive/Skill file content and proposed the result as a ChangeRequest (status \"in_review\") for human review. Reuses the existing filetree update-via-CR pipeline end to end, including baseContentHash optimistic-concurrency conflict protection at merge time. Requires the asset to be mounted in exactly one editable Drive/Skill location."
+		successDescription: "Applied the string-replace edits (coding-agent Edit-tool semantics: unique-match or replaceAll) to the asset's current mounted Drive/Skill file content and recorded the result as a ChangeRequest — merged immediately when the actor has write access on the mounting node, left \"in_review\" otherwise or when `autoMerge: false` is passed. Reuses the existing filetree update-via-CR pipeline end to end, including baseContentHash optimistic-concurrency conflict protection at merge time. Requires the asset to be mounted in exactly one editable Drive/Skill location."
 	}).input(EditAssetContentInputSchema).output(changeRequestSchema)
 };
 //#endregion
@@ -2731,7 +2842,7 @@ const recordGetInputSchema = z.union([z.object({ recordId: z.string().min(1).des
 const restoreRecordInputSchema = z.object({
 	message: z.string().optional(),
 	submittedBy: z.string().optional().default("local-editor"),
-	autoMerge: autoMergeNotAccepted("restoring a record brings archived content back into every listing, so it always requires review. Omit the flag.")
+	autoMerge: destructiveAutoMerge("Restoring is itself the undo of an archive, and is undone again by `operation: \"delete\"`.")
 });
 /**
 * Every record change request in one shape. These three used to be PUT, DELETE,
@@ -2924,7 +3035,7 @@ const recordContract = {
 		path: "/records/{recordId}/change-requests",
 		tags: ["Records", "Change Requests"],
 		summary: "Create record change request",
-		successDescription: "Creates a record change request selected by `operation`. Updates auto-merge when the actor has write access unless `autoMerge: false`; delete and restore remain review-first."
+		successDescription: "Creates a record change request selected by `operation`. All three operations are permission-aware: they merge immediately when the actor has write access on the Base's node, and land as a pending Change Request otherwise or when `autoMerge: false` is passed."
 	}).input(recordChangeRequestInputSchema).output(z.union([recordSchema.extend({ materialized: z.literal(true) }), changeRequestSchema.extend({ materialized: z.literal(false) })])),
 	listChangeRequests: oc.route({
 		method: "GET",
@@ -3381,7 +3492,7 @@ const formContract = {
 		path: "/forms/{nodeId}/submit",
 		tags: ["Forms"],
 		summary: "Submit a filled-in form",
-		successDescription: "Creates an approval-first record-create ChangeRequest on the target Base."
+		successDescription: "Creates a review-first record-create ChangeRequest on the target Base — a form submission always waits for a human, whoever submitted it."
 	}).input(SubmitFormInputSchema.extend({ nodeId: z.string() })).output(FormSubmitResultSchema)
 };
 //#endregion
@@ -3391,7 +3502,7 @@ const formContract = {
 *
 * The manual existed only over MCP: `instructions`, `resources/*` and the
 * `busabase_guide` tool. Anything driving the REST API — busabase-cli, a script,
-* a CI step, an AirApp — was told nothing about the approval-first rules, the
+* a CI step, an AirApp — was told nothing about the change-request rules, the
 * field types, or the AirApp runtime contract, and was then judged on whether it
 * guessed the house rules. These routes publish the same documents, built from
 * the same source, so the two surfaces cannot drift.
@@ -4593,6 +4704,28 @@ const getNodeInputSchema = z.object({
 const NodeIconUploadUrlInputSchema = RequestUploadUrlInputSchema.extend({ nodeId: z.string() });
 const NodeIconConfirmInputSchema = ConfirmUploadInputSchema.extend({ nodeId: z.string() });
 //#endregion
+//#region ../../packages/busabase-contract/src/contract/node-route-state-schemas.ts
+/**
+* Lightweight route guard for the dashboard. Archived variants intentionally
+* carry metadata only: resolving a tombstone must never hydrate node content.
+*/
+const NodeRouteStateVOSchema = z.discriminatedUnion("status", [
+	z.object({
+		status: z.literal("active"),
+		nodeId: z.string()
+	}),
+	z.object({
+		status: z.literal("archived"),
+		nodeId: z.string(),
+		type: z.enum(NODE_TYPES),
+		name: z.string(),
+		slug: z.string(),
+		archivedAt: z.string(),
+		canRestore: z.boolean()
+	}),
+	z.object({ status: z.literal("unavailable") })
+]);
+//#endregion
 //#region ../../packages/busabase-contract/src/contract/busabase.ts
 const changeRequestBatchFailureSchema = z.object({
 	changeRequestId: z.string(),
@@ -4712,6 +4845,13 @@ const busabaseContractRoutes = {
 			summary: "List a node's ancestor ids",
 			successDescription: "The node's ancestor ids, root-first, excluding the node itself (`[]` directly under the workspace root). `nodeId` accepts an id or a slug, same as `nodes.get`; pass `type` when a slug exists under more than one type. Lets a depth-bounded, lazily-expanded tree open straight to a deep node on a cold load (a refresh, a bookmark, a shared link) without one round trip per level."
 		}).input(getNodeInputSchema).output(nodeAncestorsVOSchema),
+		resolveRouteState: oc.route({
+			method: "GET",
+			path: "/nodes/route-state/{nodeId}",
+			tags: ["Nodes"],
+			summary: "Resolve whether a dashboard node route is active, archived, or unavailable",
+			successDescription: "A lightweight route state. Archived nodes return only tombstone metadata, never node content. Hidden, deleted, ambiguous, and anonymous archived nodes are all unavailable."
+		}).input(getNodeInputSchema).output(NodeRouteStateVOSchema),
 		createChangeRequest: oc.route({
 			method: "POST",
 			path: "/nodes/change-requests",
@@ -4946,7 +5086,28 @@ const busabaseContractRoutes = {
 			tags: ["Comments"],
 			summary: "Create comment",
 			successDescription: "Created comment attached to a Busabase subject."
-		}).input(createCommentInputSchema).output(commentSchema)
+		}).input(createCommentInputSchema).output(commentSchema),
+		/**
+		* The Inbox's Mentions tab: comments this caller was `@`-mentioned in.
+		*
+		* Scoped to the caller — there is no "whose mentions" input, because a
+		* mention inbox that could be pointed at somebody else would be a way to
+		* read comments across the workspace by proxy.
+		*/
+		listMentions: oc.route({
+			method: "GET",
+			path: "/comments/mentions",
+			tags: ["Comments"],
+			summary: "List comments that mention me",
+			successDescription: "One entry per comment the caller is mentioned in, newest first, with the unread count for the tab badge."
+		}).input(listMentionInboxInputSchema).output(mentionInboxPageSchema),
+		markMentionsRead: oc.route({
+			method: "POST",
+			path: "/comments/mentions/read",
+			tags: ["Comments"],
+			summary: "Mark my mentions on a comment as read",
+			successDescription: "Stamps every unread mention this caller has on that comment, and returns the remaining unread count."
+		}).input(markMentionsReadInputSchema).output(markMentionsReadOutputSchema)
 	},
 	agent: { listTasks: oc.route({
 		method: "GET",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-sdk",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Typed TypeScript/JavaScript SDK for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server` (or Busabase Cloud).",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-sdk",
@@ -61,13 +61,13 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^24.13.2",
+    "@types/node": "^26.3.0",
     "jsdom": "^27.0.0",
     "tsdown": "^0.22.14",
     "tsx": "^4.20.5",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
-    "busabase-contract": "0.40.0",
+    "busabase-contract": "0.41.0",
     "openlib": "0.1.1",
     "open-domains": "0.0.2"
   },