busa-sdk 0.52.0 → 0.53.0

package/dist/airapp.d.ts

@@ -1,4 +1,4 @@
-import { t as BusabaseClient } from "./client-SOzg2cGv.js";
+import { t as BusabaseClient } from "./client-CsSxFhUP.js";
 //#region src/airapp.d.ts
 type NodeChangeRequestInput = Parameters<BusabaseClient["nodes"]["createChangeRequest"]>[0];
 type NodeOperationInput = NodeChangeRequestInput["operations"][number];
@@ -57,8 +57,8 @@ interface AirAppFolderDeclaration {
  * an app's Folder and Bases are plain data-schema resources, safe to bring
  * into existence unattended, but an AirApp is a bundle of code the viewer's
  * browser will execute, so bringing it into existence always goes through
- * `publishAirApp`'s separate, always-review-first ChangeRequest instead of
- * riding along on the same `autoMerge: true` request as the data layer.
+ * `publishAirApp`'s own separate request instead of riding along on the data
+ * layer's structure request.
  * Declaring it here matters for a second reason regardless: without it, an
  * unstamped Folder holding the app's own AirApp would look like it holds an
  * unattributable stranger, and the legacy claim would be refused.
@@ -222,14 +222,31 @@ interface AirAppFileInput {
   content: string;
   mimeType?: string;
 }
+/**
+ * What one publish did. `merged` is the question a caller actually has — did
+ * this bundle go live, or is it waiting for someone?
+ *
+ * A publish is permission-aware like every other write: it merges when the
+ * app's credential holds `write` on the Folder, and falls back to a pending
+ * ChangeRequest when it does not. The CREATE path has no change request at all
+ * once it merges (the node is inserted directly), which is why that branch
+ * carries `nodeId` instead of `changeRequestId`.
+ */
 type AirAppPublishResult = {
   status: "created";
+  merged: true;
+  nodeId: string;
+} | {
+  status: "created";
+  merged: false;
   changeRequestId: string;
 } | {
   status: "updated";
+  merged: boolean;
   changeRequestId: string;
 } | {
   status: "pending";
+  merged: false;
   changeRequestId: string;
 };
 /**
@@ -244,9 +261,10 @@ declare function buildAirAppFileOperations(localFiles: AirAppFileInput[], deploy
 /**
  * Publish the app's own AirApp bundle: create it under the Folder when this
  * Space has never had it, or propose the local files as an update when it
- * already exists. Always a separate, always-review-first ChangeRequest from
- * the data layer's `provisionDeclaredResources` — see the note on
- * `AirAppNodeDeclaration` for why the two must never share a request.
+ * already exists. Always a separate request from the data layer's
+ * `provisionDeclaredResources` — see the note on `AirAppNodeDeclaration` for
+ * why the two must never share a request. Permission-aware: it merges when the
+ * app's credential can write to the Folder, and waits for review when it cannot.
  *
  * Call after `provisionDeclaredResources` has confirmed the Folder exists.
  * Every call proposes the full local file list, even when nothing actually

package/dist/airapp.js

@@ -1,4 +1,4 @@
-import { t as APP_ROOT_RESOURCE_KEY } from "./template-C5oO6Au_.js";
+import { t as APP_ROOT_RESOURCE_KEY } from "./template-D10kjpd-.js";
 //#region src/airapp.ts
 /**
 * AirApp resource provisioning — how an app claims (or creates) the Folder and
@@ -439,9 +439,10 @@ async function findPendingAirAppCreate(client, slug) {
 /**
 * Publish the app's own AirApp bundle: create it under the Folder when this
 * Space has never had it, or propose the local files as an update when it
-* already exists. Always a separate, always-review-first ChangeRequest from
-* the data layer's `provisionDeclaredResources` — see the note on
-* `AirAppNodeDeclaration` for why the two must never share a request.
+* already exists. Always a separate request from the data layer's
+* `provisionDeclaredResources` — see the note on `AirAppNodeDeclaration` for
+* why the two must never share a request. Permission-aware: it merges when the
+* app's credential can write to the Folder, and waits for review when it cannot.
 *
 * Call after `provisionDeclaredResources` has confirmed the Folder exists.
 * Every call proposes the full local file list, even when nothing actually
@@ -464,38 +465,43 @@ async function publishAirApp(client, config, files) {
 		const pendingChangeRequestId = await findPendingAirAppCreate(client, airApp.slug);
 		if (pendingChangeRequestId) return {
 			status: "pending",
+			merged: false,
 			changeRequestId: pendingChangeRequestId
 		};
-		const changeRequest = await client.fileTrees.create({
+		const result = await client.fileTrees.create({
 			type: "airapp",
 			parentNodeId: current.folder.nodeId,
 			slug: airApp.slug,
 			name: airApp.name,
 			description: airApp.description ?? "",
 			files,
-			mergeMode: "replace",
-			autoMerge: false
+			mergeMode: "replace"
 		});
-		if (changeRequest.materialized) throw setupError("SCHEMA_INCOMPLETE", "AirApp create unexpectedly materialized despite autoMerge: false");
-		return {
+		return result.materialized ? {
+			status: "created",
+			merged: true,
+			nodeId: result.node.id
+		} : {
 			status: "created",
-			changeRequestId: changeRequest.id
+			merged: false,
+			changeRequestId: result.id
 		};
 	}
 	const operations = buildAirAppFileOperations(files, (await client.fileTrees.listFiles({
 		nodeId: current.airApp.nodeId,
 		type: "airapp"
 	})).map((file) => file.path));
+	const changeRequest = await client.fileTrees.createChangeRequest({
+		nodeId: current.airApp.nodeId,
+		type: "airapp",
+		operations,
+		message: `Publish ${config.appName} AirApp`,
+		submittedBy: config.appId
+	});
 	return {
 		status: "updated",
-		changeRequestId: (await client.fileTrees.createChangeRequest({
-			nodeId: current.airApp.nodeId,
-			type: "airapp",
-			operations,
-			message: `Publish ${config.appName} AirApp`,
-			submittedBy: config.appId,
-			autoMerge: false
-		})).id
+		merged: changeRequest.status === "merged",
+		changeRequestId: changeRequest.id
 	};
 }
 //#endregion

package/dist/{client-SOzg2cGv.d.ts → client-CsSxFhUP.d.ts}

@@ -39,6 +39,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly container: true;
     readonly creatable: true;
+    readonly commonlyCreated: true;
     readonly hasDetail: true;
     readonly publicAccess: "detail";
   };
@@ -50,6 +51,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly commonlyCreated: true;
     readonly publicAccess: "detail";
   };
   readonly operations: readonly [{
@@ -206,6 +208,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly commonlyCreated: true;
     readonly publicAccess: "detail";
   };
   readonly operations: readonly [];
@@ -216,6 +219,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
   readonly capabilities: {
     readonly hasDetail: true;
     readonly creatable: true;
+    readonly commonlyCreated: true;
     readonly publicAccess: "detail";
   };
   readonly operations: readonly [{
@@ -231,6 +235,7 @@ declare const BUILTIN_NODE_TYPES: readonly [{
     readonly hasDetail: true;
     readonly creatable: true;
     readonly publicAccess: "submit";
+    readonly hidden: true;
   };
   readonly operations: readonly [];
 }, {
@@ -615,6 +620,21 @@ declare const cloudContract: {
       slug: z.ZodString;
       path: z.ZodString;
       updatedAt: z.ZodString;
+      icon: z.ZodOptional<z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"emoji">;
+        value: z.ZodString;
+      }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"attachment">;
+        url: z.ZodString;
+        attachmentId: z.ZodString;
+        originalUrl: z.ZodOptional<z.ZodString>;
+        originalAttachmentId: z.ZodOptional<z.ZodString>;
+        crop: z.ZodOptional<z.ZodObject<{
+          x: z.ZodNumber;
+          y: z.ZodNumber;
+          zoom: z.ZodNumber;
+        }, z.core.$strip>>;
+      }, z.core.$strip>], "type">>>;
     }, z.core.$strip>>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     isDescendant: import("@orpc/contract").ContractProcedure<z.ZodObject<{
       nodeId: z.ZodString;
@@ -10723,6 +10743,7 @@ declare const cloudContract: {
           targetBaseId: z.ZodOptional<z.ZodString>;
           targetBaseSlug: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        type: z.ZodOptional<z.ZodNever>;
       }, z.core.$strip>;
       message: z.ZodOptional<z.ZodString>;
       submittedBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
@@ -11711,6 +11732,54 @@ declare const cloudContract: {
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
   };
   fileTrees: {
+    previewConfig: import("@orpc/contract").ContractProcedure<import("@orpc/contract").Schema<unknown, unknown>, z.ZodObject<{
+      provider: z.ZodEnum<{
+        builtin: "builtin";
+        previewfile: "previewfile";
+      }>;
+      status: z.ZodEnum<{
+        invalid_configuration: "invalid_configuration";
+        not_configured: "not_configured";
+        ready: "ready";
+      }>;
+      credentialSource: z.ZodEnum<{
+        environment: "environment";
+        none: "none";
+        vault: "vault";
+      }>;
+      credentialConfigured: z.ZodBoolean;
+      maxFileSizeBytes: z.ZodNumber;
+      sessionTtlMinutes: z.ZodNumber;
+      vaultEncryptionConfigured: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    preparePreview: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      nodeId: z.ZodString;
+      filePath: z.ZodString;
+      type: z.ZodLiteral<"drive">;
+    }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+      state: z.ZodLiteral<"builtin">;
+      provider: z.ZodLiteral<"builtin">;
+    }, z.core.$strip>, z.ZodObject<{
+      state: z.ZodLiteral<"ready">;
+      provider: z.ZodLiteral<"previewfile">;
+      previewUrl: z.ZodString;
+      expiresAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+      state: z.ZodLiteral<"unavailable">;
+      provider: z.ZodLiteral<"previewfile">;
+      reason: z.ZodEnum<{
+        authentication_failed: "authentication_failed";
+        file_too_large: "file_too_large";
+        invalid_configuration: "invalid_configuration";
+        invalid_response: "invalid_response";
+        not_configured: "not_configured";
+        rate_limited: "rate_limited";
+        service_unavailable: "service_unavailable";
+        timeout: "timeout";
+        unsupported: "unsupported";
+      }>;
+      retryable: z.ZodBoolean;
+    }, z.core.$strip>], "state">, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     create: import("@orpc/contract").ContractProcedure<z.ZodObject<{
       parentNodeId: z.ZodOptional<z.ZodString>;
       slug: z.ZodString;
@@ -14076,7 +14145,11 @@ declare const cloudContract: {
       nodeId: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
       changeRequestId: z.ZodString;
-      status: z.ZodLiteral<"pending_review">;
+      status: z.ZodEnum<{
+        merged: "merged";
+        pending_review: "pending_review";
+      }>;
+      recordId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
   };
   assets: {
@@ -14788,6 +14861,15 @@ declare const cloudContract: {
           createdAt: z.ZodString;
           lastActivityAt: z.ZodString;
           error: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+          modelOption: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            currentValue: z.ZodString;
+            options: z.ZodArray<z.ZodObject<{
+              value: z.ZodString;
+              name: z.ZodString;
+            }, z.core.$strip>>;
+          }, z.core.$strip>>>;
         }, z.core.$strip>>;
         ownedByCurrentUser: z.ZodBoolean;
       }, z.core.$strip>>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
@@ -14812,6 +14894,15 @@ declare const cloudContract: {
         createdAt: z.ZodString;
         lastActivityAt: z.ZodString;
         error: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        modelOption: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+          id: z.ZodString;
+          name: z.ZodString;
+          currentValue: z.ZodString;
+          options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            name: z.ZodString;
+          }, z.core.$strip>>;
+        }, z.core.$strip>>>;
       }, z.core.$strip>>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
       create: import("@orpc/contract").ContractProcedure<z.ZodObject<{
         slug: z.ZodString;
@@ -14834,6 +14925,15 @@ declare const cloudContract: {
         createdAt: z.ZodString;
         lastActivityAt: z.ZodString;
         error: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        modelOption: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+          id: z.ZodString;
+          name: z.ZodString;
+          currentValue: z.ZodString;
+          options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            name: z.ZodString;
+          }, z.core.$strip>>;
+        }, z.core.$strip>>>;
       }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
       prompt: import("@orpc/contract").ContractProcedure<z.ZodObject<{
         sessionId: z.ZodString;
@@ -14869,6 +14969,39 @@ declare const cloudContract: {
       }, z.core.$strip>, z.ZodObject<{
         ok: z.ZodBoolean;
       }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+      setConfigOption: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+        sessionId: z.ZodString;
+        configId: z.ZodString;
+        value: z.ZodString;
+      }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+        agentName: z.ZodString;
+        transport: z.ZodEnum<{
+          "local-subprocess": "local-subprocess";
+          "remote-websocket": "remote-websocket";
+        }>;
+        status: z.ZodEnum<{
+          busy: "busy";
+          connecting: "connecting";
+          ended: "ended";
+          failed: "failed";
+          idle: "idle";
+          waiting_permission: "waiting_permission";
+        }>;
+        createdAt: z.ZodString;
+        lastActivityAt: z.ZodString;
+        error: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        modelOption: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+          id: z.ZodString;
+          name: z.ZodString;
+          currentValue: z.ZodString;
+          options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            name: z.ZodString;
+          }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+      }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
       subscribe: import("@orpc/contract").ContractProcedure<z.ZodObject<{
         sessionId: z.ZodString;
         afterSeq: z.ZodDefault<z.ZodNumber>;
@@ -15602,6 +15735,52 @@ declare const cloudContract: {
       pendingChangeRequests: z.ZodNumber;
       warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    fromGithubStream: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      repoUrl: z.ZodString;
+      intoFolder: z.ZodOptional<z.ZodString>;
+      rename: z.ZodOptional<z.ZodBoolean>;
+      autoMerge: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, import("@orpc/contract").Schema<AsyncIteratorObject<{
+      kind: "progress";
+      message: string;
+    } | {
+      kind: "done";
+      result: {
+        targetFolderSlug: string;
+        targetFolderNodeId: string;
+        created: {
+          folders: number;
+          docs: number;
+          bases: number;
+          views: number;
+          records: number;
+          fileTreeNodes: number;
+          files: number;
+        };
+        pendingChangeRequests: number;
+        warnings?: string[] | undefined;
+      };
+    }, unknown, void>, AsyncIteratorClass<{
+      kind: "progress";
+      message: string;
+    } | {
+      kind: "done";
+      result: {
+        targetFolderSlug: string;
+        targetFolderNodeId: string;
+        created: {
+          folders: number;
+          docs: number;
+          bases: number;
+          views: number;
+          records: number;
+          fileTreeNodes: number;
+          files: number;
+        };
+        pendingChangeRequests: number;
+        warnings: string[];
+      };
+    }, unknown, void>>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
   };
   templates: {
     list: import("@orpc/contract").ContractProcedure<z.ZodDefault<z.ZodOptional<z.ZodObject<{
@@ -15641,6 +15820,7 @@ declare const cloudContract: {
         }>>;
         tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
         screenshots: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        video: z.ZodOptional<z.ZodString>;
         agentPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
         version: z.ZodOptional<z.ZodString>;
         author: z.ZodOptional<z.ZodString>;
@@ -23110,10 +23290,24 @@ declare const SubmitFormInputSchema: z.ZodObject<{
   captchaToken: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type SubmitFormDTO = z.input<typeof SubmitFormInputSchema>;
-/** What the submit endpoint returns — the pending ChangeRequest id, never data. */
+/**
+ * What the submit endpoint returns — a ChangeRequest id and what happened to it,
+ * never the record data.
+ *
+ * `status` is permission-aware, like every other write: `merged` when the
+ * submitter holds `write` on the target Base and the submission landed straight
+ * away, `pending_review` when it is waiting for a human. An ANONYMOUS visitor can
+ * never reach `merged`: permission is resolved against the target Base, which a
+ * form does not share publicly, and a public-link request is capped at `read`
+ * even where it is shared. So a public form still always waits.
+ */
 declare const FormSubmitResultSchema: z.ZodObject<{
   changeRequestId: z.ZodString;
-  status: z.ZodLiteral<"pending_review">;
+  status: z.ZodEnum<{
+    merged: "merged";
+    pending_review: "pending_review";
+  }>;
+  recordId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type FormSubmitResultVO = z.infer<typeof FormSubmitResultSchema>;
 //#endregion
@@ -24789,6 +24983,33 @@ declare const NodeDetailVOSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 type NodeDetailVO = z.infer<typeof NodeDetailVOSchema>;
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/filetree/types.d.ts
+type FilePreviewProvider = "builtin" | "previewfile";
+type FilePreviewCredentialSource = "environment" | "vault" | "none";
+type FilePreviewConfigurationStatus = "ready" | "not_configured" | "invalid_configuration";
+type FilePreviewUnavailableReason = "not_configured" | "invalid_configuration" | "file_too_large" | "unsupported" | "authentication_failed" | "rate_limited" | "timeout" | "service_unavailable" | "invalid_response";
+interface FilePreviewConfigVO {
+  provider: FilePreviewProvider;
+  status: FilePreviewConfigurationStatus;
+  credentialSource: FilePreviewCredentialSource;
+  credentialConfigured: boolean;
+  maxFileSizeBytes: number;
+  sessionTtlMinutes: number;
+  vaultEncryptionConfigured: boolean | null;
+}
+type FilePreviewVO = {
+  state: "builtin";
+  provider: "builtin";
+} | {
+  state: "ready";
+  provider: "previewfile";
+  previewUrl: string;
+  expiresAt: string;
+} | {
+  state: "unavailable";
+  provider: "previewfile";
+  reason: FilePreviewUnavailableReason;
+  retryable: boolean;
+};
 interface FileTreeFileVO {
   path: string;
   name: string;
@@ -25087,6 +25308,10 @@ declare const UpdateVaultSettingsInputSchema: z.ZodObject<{
   }, z.core.$strip>>;
 }, z.core.$strip>;
 type UpdateVaultSettingsDTO = z.infer<typeof UpdateVaultSettingsInputSchema>;
+declare const UpdatePreviewFileCredentialInputSchema: z.ZodObject<{
+  apiKey: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type UpdatePreviewFileCredentialDTO = z.infer<typeof UpdatePreviewFileCredentialInputSchema>;
 declare const VaultItemVOSchema: z.ZodObject<{
   kind: z.ZodEnum<{
     secret: "secret";
@@ -25203,6 +25428,8 @@ interface NodeSearchResultVO {
   slug: string;
   path: string;
   updatedAt: string;
+  /** Optional: absent on an older server response. See `NodeVO.icon`. */
+  icon?: NodeIcon | null;
 }
 interface NodeVO {
   id: string;
@@ -25591,4 +25818,4 @@ declare function resolveConfig(config?: BusabaseConfig): ResolvedConfig;
  */
 declare function createBusabaseClient(config?: BusabaseConfig): BusabaseClient;
 //#endregion
-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 };
+export { AssetTextStatus as $, NodeVO as A, GalleryCardSize as At, UpdatePreviewFileCredentialDTO as B, ViewSortVO as Bt, CommentVO as C, ListFormsDTO as Ct, MentionInboxItemVO as D, AssetAttachmentRef as Dt, LookupRollup as E, UpdateFormDTO as Et, SearchResponseVO as F, VIEW_FIELD_MAX_WIDTH as Ft, VaultItemKind as G, cloudContract as Gt, VaultAccessPolicy as H, ViewVO as Ht, SearchResultKind as I, VIEW_FIELD_MIN_WIDTH as It, VaultScopeType as J, CREATABLE_NODE_TYPES as Jt, VaultItemVO as K, NodeIcon as Kt, SearchResultVO as L, ViewConfigVO as Lt, OperationVO as M, GanttScale as Mt, ReviewVO as N, RecordLinkVO as Nt, MentionInboxPageVO as O, BaseFieldVO as Ot, ReviewVerdict as P, RecordVO as Pt, AssetDetailVO as Q, SourceAttributionVO as R, ViewFilterOperator as Rt, CommentSubjectType as S, FormVO as St, FieldType as T, SubmitFormDTO as Tt, VaultEnvironment as U, AttachmentRef as Ut, UpdateVaultSettingsDTO as V, ViewType as Vt, VaultItemInput as W, CloudContract as Wt, FileNodeMetadata as X, NodeType as Xt, VaultSettingsVO as Y, CreatableNodeType as Yt, FileNodeVO as Z, OperationKind as Zt, ChangeRequestVO as _, FormFieldBindingVO as _t, createBusabaseClient as a, FilePreviewConfigurationStatus as at, CommentMentionTargetType as b, FormSubmitResultVO as bt, AuditAction as c, FilePreviewUnavailableReason as ct, ChangeRequestBatchFailureVO as d, FileTreeNodeVO as dt, AssetUsageVO as et, ChangeRequestCountsVO as f, FileTreeReadFileVO as ft, ChangeRequestTargetType as g, FormBoundFieldVO as gt, ChangeRequestStatus as h, CreateFormDTO as ht, ResolvedConfig as i, FilePreviewConfigVO as it, OperationStatus as j, GalleryCoverFit as jt, NodeSearchResultVO as k, BaseVO as kt, AuditEventVO as l, FilePreviewVO as lt, ChangeRequestReviewBatchResultVO as m, ActivityItemVO as mt, BusabaseConfig as n, GrepInputDTO as nt, resolveConfig as o, FilePreviewCredentialSource as ot, ChangeRequestMergeBatchResultVO as p, NodeDetailVO as pt, VaultRuntimeEnv as q, NodeIconSchema as qt, DEFAULT_BASE_URL as r, GrepResultVO as rt, AgentTaskVO as s, FilePreviewProvider as st, BusabaseClient as t, AssetVO as tt, BusabaseSourceChannel as u, FileTreeFileVO as ut, CommentMentionDispatchStatus as v, FormPageSourceVO as vt, CommitVO as w, ListFormsVO as wt, CommentMentionVO as x, FormThemeVO as xt, CommentMentionInputDTO as y, FormShareVO as yt, UserRefVO as z, ViewFilterVO as zt };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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-SOzg2cGv.js";
+import { $ as AssetTextStatus, A as NodeVO, At as GalleryCardSize, B as UpdatePreviewFileCredentialDTO, Bt as ViewSortVO, C as CommentVO, Ct as ListFormsDTO, D as MentionInboxItemVO, Dt as AssetAttachmentRef, E as LookupRollup, Et as UpdateFormDTO, F as SearchResponseVO, Ft as VIEW_FIELD_MAX_WIDTH, G as VaultItemKind, Gt as cloudContract, H as VaultAccessPolicy, Ht as ViewVO, I as SearchResultKind, It as VIEW_FIELD_MIN_WIDTH, J as VaultScopeType, Jt as CREATABLE_NODE_TYPES, K as VaultItemVO, Kt as NodeIcon, L as SearchResultVO, Lt as ViewConfigVO, M as OperationVO, Mt as GanttScale, N as ReviewVO, Nt as RecordLinkVO, O as MentionInboxPageVO, Ot as BaseFieldVO, P as ReviewVerdict, Pt as RecordVO, Q as AssetDetailVO, R as SourceAttributionVO, Rt as ViewFilterOperator, S as CommentSubjectType, St as FormVO, T as FieldType, Tt as SubmitFormDTO, U as VaultEnvironment, Ut as AttachmentRef, V as UpdateVaultSettingsDTO, Vt as ViewType, W as VaultItemInput, Wt as CloudContract, X as FileNodeMetadata, Xt as NodeType, Y as VaultSettingsVO, Yt as CreatableNodeType, Z as FileNodeVO, Zt as OperationKind, _ as ChangeRequestVO, _t as FormFieldBindingVO, a as createBusabaseClient, at as FilePreviewConfigurationStatus, b as CommentMentionTargetType, bt as FormSubmitResultVO, c as AuditAction, ct as FilePreviewUnavailableReason, d as ChangeRequestBatchFailureVO, dt as FileTreeNodeVO, et as AssetUsageVO, f as ChangeRequestCountsVO, ft as FileTreeReadFileVO, g as ChangeRequestTargetType, gt as FormBoundFieldVO, h as ChangeRequestStatus, ht as CreateFormDTO, i as ResolvedConfig, it as FilePreviewConfigVO, j as OperationStatus, jt as GalleryCoverFit, k as NodeSearchResultVO, kt as BaseVO, l as AuditEventVO, lt as FilePreviewVO, m as ChangeRequestReviewBatchResultVO, mt as ActivityItemVO, n as BusabaseConfig, nt as GrepInputDTO, o as resolveConfig, ot as FilePreviewCredentialSource, p as ChangeRequestMergeBatchResultVO, pt as NodeDetailVO, q as VaultRuntimeEnv, qt as NodeIconSchema, r as DEFAULT_BASE_URL, rt as GrepResultVO, s as AgentTaskVO, st as FilePreviewProvider, t as BusabaseClient, tt as AssetVO, u as BusabaseSourceChannel, ut as FileTreeFileVO, v as CommentMentionDispatchStatus, vt as FormPageSourceVO, w as CommitVO, wt as ListFormsVO, x as CommentMentionVO, xt as FormThemeVO, y as CommentMentionInputDTO, yt as FormShareVO, z as UserRefVO, zt as ViewFilterVO } from "./client-CsSxFhUP.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 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 };
+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 FilePreviewConfigVO, type FilePreviewConfigurationStatus, type FilePreviewCredentialSource, type FilePreviewProvider, type FilePreviewUnavailableReason, type FilePreviewVO, 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 UpdatePreviewFileCredentialDTO, 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

@@ -1,4 +1,4 @@
-import { n as TemplateRiskLevelSchema } from "./template-C5oO6Au_.js";
+import { n as TemplateRiskLevelSchema } from "./template-D10kjpd-.js";
 import { t as normalizeBaseUrl } from "./url-B8GMXalA.js";
 import { ORPCError, createORPCClient } from "@orpc/client";
 import { OpenAPILink } from "@orpc/openapi-client/fetch";
@@ -124,6 +124,25 @@ const AgentPermissionRequestVOSchema = z.object({
 	description: z.string().optional(),
 	options: z.array(AgentPermissionOptionVOSchema)
 });
+/**
+* The agent's `category: "model"` ACP config option, reduced to what the UI
+* needs to render a picker: which value is selected, and what it can become.
+*
+* Deliberately not the raw ACP `SessionConfigOption` — that type carries a
+* `boolean` variant and grouped select options this domain has no use for,
+* and re-exporting it here would leak an SDK shape across the contract
+* boundary for a feature that only needs "id, current value, flat choices".
+*/
+const AgentSessionModelOptionVOSchema = z.object({
+	/** The ACP `configId` to send back on `session/set_config_option`. */
+	id: z.string(),
+	name: z.string(),
+	currentValue: z.string(),
+	options: z.array(z.object({
+		value: z.string(),
+		name: z.string()
+	}))
+});
 const AgentSessionVOSchema = z.object({
 	/** Busabase's own id for the session; not the agent's ACP sessionId. */
 	id: z.string(),
@@ -135,7 +154,15 @@ const AgentSessionVOSchema = z.object({
 	createdAt: z.string(),
 	lastActivityAt: z.string(),
 	/** Set when status is "failed"; surfaced verbatim to the user. */
-	error: z.string().nullable().default(null)
+	error: z.string().nullable().default(null),
+	/**
+	* Present only while the agent's `session/new` (or a later
+	* `config_option_update`) has advertised a `category: "model"` select.
+	* `null` for agents that offer no model choice, and for every session
+	* loaded from history — a finished process cannot take a config change,
+	* so there is nothing to render a picker for.
+	*/
+	modelOption: AgentSessionModelOptionVOSchema.nullable().default(null)
 });
 /** One connected agent backend visible in the requested workspace scope. */
 const AgentConnectionVOSchema = z.object({
@@ -221,6 +248,12 @@ const RespondToAgentPermissionInputSchema = z.object({
 	requestId: z.string().min(1),
 	optionId: z.string().min(1)
 });
+/** Change the session's `category: "model"` config option via `session/set_config_option`. */
+const SetAgentSessionConfigOptionInputSchema = z.object({
+	sessionId: z.string().min(1),
+	configId: z.string().min(1),
+	value: z.string().min(1)
+});
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/agents/contract.ts
 /**
@@ -261,6 +294,12 @@ list: oc.input(ListAgentConnectionsInputSchema).output(AgentConnectionVOSchema.a
 		*/
 		respondToPermission: oc.input(RespondToAgentPermissionInputSchema).output(z.object({ ok: z.boolean() })),
 		/**
+		* Change the session's advertised model via ACP `session/set_config_option`.
+		* `value` is validated against the session's currently advertised options
+		* server-side — this is not a passthrough to the agent.
+		*/
+		setConfigOption: oc.input(SetAgentSessionConfigOptionInputSchema).output(AgentSessionVOSchema),
+		/**
 		* Live event stream for one session. Replays buffered events from `afterSeq`
 		* first so a client that reconnects mid-turn does not lose the tokens it
 		* missed, then follows live.
@@ -560,7 +599,26 @@ const updateFieldChangeRequestInputSchema = z.object({
 	patch: z.object({
 		name: fieldNameSchema.optional(),
 		required: z.boolean().optional(),
-		options: fieldOptionsSchema.optional()
+		options: fieldOptionsSchema.optional(),
+		/**
+		* Not a patch key — rejected on purpose, and the only key here that is.
+		*
+		* `update` cannot change a field's type; `convert` does, after
+		* `previewFieldConversion` has shown what happens to the stored values.
+		* But `patch` is a plain (non-strict) object, so `{ type: "markdown" }`
+		* used to be stripped silently: the request validated, the change request
+		* merged, `ok: true` came back, and the field was still whatever it was.
+		* A caller reaching for the obvious-but-wrong shape got a successful
+		* no-op, which reads exactly like a successful conversion.
+		*
+		* Blanket `.strict()` is not the fix here — see `contract/auto-merge.ts`
+		* on why these schemas stay open: the SDK ships on its own cadence
+		* against self-hosted servers, so a newer client sending a newer optional
+		* key is normal traffic, and strictness would 400 all of them to catch
+		* this one. Naming the single key that will never be legitimate keeps
+		* that forward compatibility intact.
+		*/
+		type: z.never({ message: "A field type cannot be changed with `update`. Use operation: \"convert\" with `newType`, and call `previewFieldConversion` first to see how many stored values survive it." }).optional()
 	}),
 	message: z.string().optional(),
 	submittedBy: z.string().optional().default("local-editor"),
@@ -727,6 +785,7 @@ const baseNodeType = {
 	capabilities: {
 		hasDetail: true,
 		creatable: true,
+		commonlyCreated: true,
 		publicAccess: "detail"
 	},
 	operations: [
@@ -831,6 +890,7 @@ const docNodeType = {
 	capabilities: {
 		hasDetail: true,
 		creatable: true,
+		commonlyCreated: true,
 		publicAccess: "detail"
 	},
 	operations: [{
@@ -862,6 +922,7 @@ const fileNodeType = {
 	capabilities: {
 		hasDetail: true,
 		creatable: true,
+		commonlyCreated: true,
 		publicAccess: "detail"
 	},
 	operations: []
@@ -877,6 +938,7 @@ const folderNodeType = {
 	capabilities: {
 		container: true,
 		creatable: true,
+		commonlyCreated: true,
 		hasDetail: true,
 		publicAccess: "detail"
 	},
@@ -887,9 +949,10 @@ 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 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-
+* directly — it produces a record-create ChangeRequest on the target Base (so
+* the submitting act reuses the base's `record_create` op, not a form-specific
+* one), which then merges immediately or waits for review according to the
+* submitter's permission on that Base. The form's own config (bindings/page/share) is owner-
 * managed and edited directly, so this node contributes no CR operations of its
 * own for now.
 */
@@ -897,10 +960,23 @@ const formNodeType = {
 	type: "form",
 	label: "Form",
 	icon: "form",
+	/**
+	* `hidden` until a Form can be created from a create surface at all.
+	*
+	* `busabase_forms.target_base_id` is NOT NULL and `form` registers no
+	* `node_create` materializer, so a Form built through the generic New-item
+	* flow (which only collects name/slug/description) is a node row with no form
+	* config behind it — it opens to a dead end, every time, for everyone. The
+	* type stays fully `creatable` so `forms.create` (which does take a target
+	* Base) and the REST/MCP surface are untouched; it just no longer offers an
+	* entry point that cannot succeed. Drop this once the New-item flow asks for
+	* the target Base and a materializer writes the config row.
+	*/
 	capabilities: {
 		hasDetail: true,
 		creatable: true,
-		publicAccess: "submit"
+		publicAccess: "submit",
+		hidden: true
 	},
 	operations: []
 };
@@ -1135,12 +1211,20 @@ const customPromptBodySchema = iStringSchema.refine((value) => iStringLocaleValu
 * One custom scenario prompt. `body`'s `{target}` placeholder is substituted at
 * render time with the same target string `PromptDef.body(target)` receives
 * today (see `node-agent-prompts.ts`) — this schema does not interpolate it.
+*
+* The placeholder is OPTIONAL and chooses placement only: a `body` that never
+* mentions `{target}` gets the target line prepended as its first paragraph, so
+* a custom prompt can never reach an agent without naming the node it acts on.
+* That is why the schema does not require it — forgetting it is not an error to
+* reject, it is a default to supply.
 */
 const customPromptDefSchema = z.object({
 	/** Stable id, unique within this node's custom list. */
 	key: z.string().trim().min(1, { message: "key must not be empty" }),
 	/** Defaults to `change` (same default the curated prompts use) so a prompt
-	* cannot silently bypass the approval-first policy by omission. */
+	* cannot silently opt out of the change-request path by omission — whether that
+	* path then merges immediately or waits for review is the permission layer's
+	* call, not the prompt's. */
 	intent: customPromptIntentSchema.optional(),
 	/** Short title shown in the dialog's left list. */
 	label: customPromptLabelSchema,
@@ -1327,7 +1411,14 @@ const nodeSearchResultSchema = z.object({
 	name: z.string(),
 	slug: z.string(),
 	path: z.string(),
-	updatedAt: z.string()
+	updatedAt: z.string(),
+	/**
+	* The node's own custom avatar, same shape as `NodeVO.icon`. Optional so an
+	* older server that predates this field is still a valid response — a
+	* caller that doesn't know it falls back to the type icon exactly as it
+	* always has.
+	*/
+	icon: NodeIconSchema.nullable().optional()
 });
 const userRefSchema = z.object({
 	id: z.string(),
@@ -1998,17 +2089,84 @@ const fileTreeNodeTypeSchema = z.enum([
 	"drive",
 	"airapp"
 ]);
+const filePreviewProviderSchema = z.enum(["builtin", "previewfile"]);
+const filePreviewCredentialSourceSchema = z.enum([
+	"environment",
+	"vault",
+	"none"
+]);
+const filePreviewConfigurationStatusSchema = z.enum([
+	"ready",
+	"not_configured",
+	"invalid_configuration"
+]);
+const filePreviewUnavailableReasonSchema = z.enum([
+	"not_configured",
+	"invalid_configuration",
+	"file_too_large",
+	"unsupported",
+	"authentication_failed",
+	"rate_limited",
+	"timeout",
+	"service_unavailable",
+	"invalid_response"
+]);
+const filePreviewConfigSchema = z.object({
+	provider: filePreviewProviderSchema,
+	status: filePreviewConfigurationStatusSchema,
+	credentialSource: filePreviewCredentialSourceSchema,
+	credentialConfigured: z.boolean(),
+	maxFileSizeBytes: z.number().int().positive(),
+	sessionTtlMinutes: z.number().int().positive(),
+	vaultEncryptionConfigured: z.boolean().nullable()
+});
+const filePreviewSchema = z.discriminatedUnion("state", [
+	z.object({
+		state: z.literal("builtin"),
+		provider: z.literal("builtin")
+	}),
+	z.object({
+		state: z.literal("ready"),
+		provider: z.literal("previewfile"),
+		previewUrl: z.string().url(),
+		expiresAt: z.string().datetime()
+	}),
+	z.object({
+		state: z.literal("unavailable"),
+		provider: z.literal("previewfile"),
+		reason: filePreviewUnavailableReasonSchema,
+		retryable: z.boolean()
+	})
+]);
 const fileTreeRefSchema = z.object({
 	nodeId: z.string().describe("A node id OR a slug. A slug is only unique WITHIN a type, so pass `type` alongside one; a node id needs no hint."),
 	type: fileTreeNodeTypeSchema.optional().describe("Disambiguates a slug. Unnecessary — and ignored — when `nodeId` is an id.")
 });
 const fileTreeContract = {
+	previewConfig: oc.route({
+		method: "GET",
+		path: "/file-trees/preview-config",
+		tags: ["File Trees"],
+		summary: "Get Drive file preview configuration",
+		successDescription: "Resolved preview provider state without exposing the configured API key."
+	}).output(filePreviewConfigSchema),
+	preparePreview: oc.route({
+		method: "POST",
+		path: "/file-trees/{nodeId}/preview",
+		tags: ["File Trees"],
+		summary: "Prepare a Drive file preview",
+		successDescription: "Returns the built-in provider, a short-lived PreviewFile URL, or a recoverable provider failure."
+	}).input(z.object({
+		nodeId: z.string().min(1),
+		filePath: z.string().min(1),
+		type: z.literal("drive")
+	})).output(filePreviewSchema),
 	create: oc.route({
 		method: "POST",
 		path: "/file-trees",
 		tags: ["File Trees"],
 		summary: "Create file-tree node",
-		successDescription: "Review-first by default: a pending ChangeRequest proposing the node (`materialized: false`). Returns the materialized node instead (`materialized: true`) when `autoMerge: true` is passed."
+		successDescription: "Merged in the same call when the actor has write access on the target node — the materialized node comes back (`materialized: true`). Review-first when the actor lacks write access or passes `autoMerge: false`: a pending ChangeRequest proposing the node (`materialized: false`)."
 	}).input(createFileTreeInputSchema.extend({ type: fileTreeNodeTypeSchema })).output(z.union([fileTreeNodeSchema.extend({ materialized: z.literal(true) }), changeRequestSchema.extend({ materialized: z.literal(false) })])),
 	listFiles: oc.route({
 		method: "GET",
@@ -3029,14 +3187,14 @@ const baseContract = {
 		path: "/bases",
 		tags: ["Bases"],
 		summary: "Create Base",
-		successDescription: "Review-first by default: a pending ChangeRequest proposing the Base (`materialized: false`). Returns the materialized Base instead (`materialized: true`) when `autoMerge: true` is passed."
+		successDescription: "Merged in the same call when the actor has write access on the parent node — the materialized Base comes back (`materialized: true`). Review-first when the actor lacks write access or passes `autoMerge: false`: a pending ChangeRequest proposing the Base (`materialized: false`)."
 	}).input(createBaseInputSchema).output(z.union([baseSchema.extend({ materialized: z.literal(true) }), changeRequestSchema.extend({ materialized: z.literal(false) })])),
 	createChangeRequest: oc.route({
 		method: "POST",
 		path: "/bases/{baseId}/change-requests",
 		tags: ["Bases", "Change Requests"],
 		summary: "Create Change Request in Base",
-		successDescription: "Review-first by default: a pending ChangeRequest proposing the record (`materialized: false`). Returns the materialized record instead (`materialized: true`) when `autoMerge: true` is passed."
+		successDescription: "Merged in the same call when the actor has write access on the Base's node — the materialized record comes back (`materialized: true`). Review-first when the actor lacks write access or passes `autoMerge: false`: a pending ChangeRequest proposing the record (`materialized: false`)."
 	}).input(createChangeRequestInputSchema.extend({ baseId: z.string() })).output(z.union([recordSchema.extend({ materialized: z.literal(true) }), changeRequestSchema.extend({ materialized: z.literal(false) })])),
 	createBulkChangeRequest: oc.route({
 		method: "POST",
@@ -3194,7 +3352,7 @@ const docContract = { create: oc.route({
 	path: "/docs",
 	tags: ["Docs"],
 	summary: "Create Doc node",
-	successDescription: "Review-first by default: a pending ChangeRequest proposing the Doc (`materialized: false`). Returns the materialized Doc node instead (`materialized: true`) when `autoMerge: true` is passed."
+	successDescription: "Merged in the same call when the actor has write access on the parent node — the materialized Doc node comes back (`materialized: true`). Review-first when the actor lacks write access or passes `autoMerge: false`: a pending ChangeRequest proposing the Doc (`materialized: false`)."
 }).input(createDocInputSchema).output(z.union([docSchema.extend({ materialized: z.literal(true) }), changeRequestSchema.extend({ materialized: z.literal(false) })])) };
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/doc/types.ts
@@ -3456,7 +3614,7 @@ const fileContract = { create: oc.route({
 	path: "/files",
 	tags: ["Files"],
 	summary: "Create File node",
-	successDescription: "Review-first by default: a pending ChangeRequest proposing the File node (`materialized: false`). Returns the materialized File node instead (`materialized: true`) when `autoMerge: true` is passed."
+	successDescription: "Merged in the same call when the actor has write access on the parent node — the materialized File node comes back (`materialized: true`). Review-first when the actor lacks write access or passes `autoMerge: false`: a pending ChangeRequest proposing the File node (`materialized: false`)."
 }).input(createFileNodeInputSchema).output(z.union([FileNodeVOSchema.extend({ materialized: z.literal(true) }), changeRequestSchema.extend({ materialized: z.literal(false) })])) };
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/form/types.ts
@@ -3565,10 +3723,22 @@ const SubmitFormInputSchema = z.object({
 	values: z.record(z.string(), z.unknown()),
 	captchaToken: z.string().optional()
 });
-/** What the submit endpoint returns — the pending ChangeRequest id, never data. */
+/**
+* What the submit endpoint returns — a ChangeRequest id and what happened to it,
+* never the record data.
+*
+* `status` is permission-aware, like every other write: `merged` when the
+* submitter holds `write` on the target Base and the submission landed straight
+* away, `pending_review` when it is waiting for a human. An ANONYMOUS visitor can
+* never reach `merged`: permission is resolved against the target Base, which a
+* form does not share publicly, and a public-link request is capped at `read`
+* even where it is shared. So a public form still always waits.
+*/
 const FormSubmitResultSchema = z.object({
 	changeRequestId: z.string(),
-	status: z.literal("pending_review")
+	status: z.enum(["pending_review", "merged"]),
+	/** The created record's id, present only when `status` is `merged`. */
+	recordId: z.string().optional()
 });
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/form/contract.ts
@@ -3606,7 +3776,7 @@ const formContract = {
 		path: "/forms/{nodeId}/submit",
 		tags: ["Forms"],
 		summary: "Submit a filled-in form",
-		successDescription: "Creates a review-first record-create ChangeRequest on the target Base — a form submission always waits for a human, whoever submitted it."
+		successDescription: "Creates a record-create ChangeRequest on the target Base. Merged in the same call when the submitter holds write access on that Base (`status: \"merged\"`); otherwise it waits for a reviewer (`status: \"pending_review\"`). A visitor arriving through the form's public link is capped at read and therefore always waits."
 	}).input(SubmitFormInputSchema.extend({ nodeId: z.string() })).output(FormSubmitResultSchema)
 };
 //#endregion
@@ -3757,9 +3927,10 @@ const InstallPlanVOSchema = z.object({
 	warnings: z.array(z.string()).default([]),
 	/**
 	* True when a record carries a relation VALUE. A relation stores the ids of the
-	* records it points at, and those exist only once the records are merged — so a
-	* review-first install would land every relation empty. `autoMerge` is required
-	* in that case, and the UI must say why.
+	* records it points at, and those exist only once the records are merged — so an
+	* install left for review would land every relation empty. Such a package cannot
+	* be installed by a caller whose content would queue (no write access, or an
+	* explicit `autoMerge: false`), and the UI must say why.
 	*/
 	requiresAutoMerge: z.boolean(),
 	/**
@@ -3769,10 +3940,13 @@ const InstallPlanVOSchema = z.object({
 	*
 	* It is therefore an answer to "what happens if I install like this", not a
 	* property of the package — a package whose records carry relation values
-	* reports `applicable: false` when planned WITHOUT `autoMerge` and true WITH
-	* it. A client that offers an auto-merge toggle must re-plan when it changes
-	* (the same way it re-plans when `rename` or `intoFolder` change), rather than
-	* treating one plan's `applicable` as final.
+	* reports `applicable: false` when this caller's content would QUEUE and true
+	* when it would merge. Note the plan resolves that the same permission-aware
+	* way the install itself does, so omitting `autoMerge` reports what the caller
+	* would actually get rather than assuming review. A client that offers an
+	* auto-merge toggle must re-plan when it changes (the same way it re-plans when
+	* `rename` or `intoFolder` change), rather than treating one plan's
+	* `applicable` as final.
 	*
 	* There is deliberately no `blockedReason` string here: the reason is already
 	* carried structurally by `collisions[]` (with `renamedTo`) and
@@ -3803,6 +3977,28 @@ const InstallResultVOSchema = z.object({
 	pendingChangeRequests: z.number().int().min(0),
 	warnings: z.array(z.string()).default([])
 });
+/**
+* One event from a streaming install.
+*
+* A whole install in a single response is what makes the plain `fromGithub`
+* route time out at a gateway: the work is minutes of GitHub fetch, node
+* creation, file upload and record writes, and until it finishes the connection
+* carries no bytes. A proxy in front of the app sees an idle socket and closes
+* it — the install itself keeps running server-side, so the user is told it
+* failed while it actually succeeded, which is the worst of both.
+*
+* `applyInstall` already reports its progress (`onProgress`); the non-streaming
+* route simply discarded it. Streaming those same messages keeps bytes moving
+* AND gives the user something truthful to look at during a long install.
+*/
+const InstallEventVOSchema = z.discriminatedUnion("kind", [z.object({
+	kind: z.literal("progress"),
+	/** Human-readable, already localized by the caller's own copy — display as-is. */
+	message: z.string()
+}), z.object({
+	kind: z.literal("done"),
+	result: InstallResultVOSchema
+})]);
 z.object({
 	/** Which of the five passes stopped, e.g. `Pass 4/5 (sample records)`. */
 	phase: z.string(),
@@ -3833,7 +4029,7 @@ const InstallFromGithubDTOSchema = z.object({
 	repoUrl: repoUrlField,
 	intoFolder: intoFolderField,
 	rename: renameField,
-	autoMerge: z.boolean().optional().describe("Merge the content change requests on the spot instead of leaving them for review. This trusts the package author: a package can carry skills and AirApps, i.e. code this space's agents will execute.")
+	autoMerge: z.boolean().optional().describe("Whether the package's content change requests merge on the spot. Omitted defaults to merging immediately when the caller holds write access (installing is already a space owner/admin operation, so normally they do), otherwise leaving them for review; pass explicit false to force review even with write access. Either way, installing trusts the package author: a package can carry skills and AirApps, i.e. code this space's agents will execute.")
 });
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/install/contract.ts
@@ -3865,7 +4061,18 @@ const installContract = {
 		tags: ["Install"],
 		summary: "Install a package from a GitHub repo",
 		successDescription: "Created counts plus the number of change requests left for review. Structure (folders, Bases, fields, views) is created immediately — a pending Base has no id to attach a view or record to; content (records, docs, skills, AirApps) lands as change requests unless `autoMerge` is set."
-	}).input(InstallFromGithubDTOSchema).output(InstallResultVOSchema)
+	}).input(InstallFromGithubDTOSchema).output(InstallResultVOSchema),
+	/**
+	* The same install, streamed.
+	*
+	* Kept alongside `fromGithub` rather than replacing it: that route is in the
+	* public OpenAPI surface and a plain request/response is the right shape for
+	* a script. This one exists for a human waiting at a dashboard, where the
+	* install is long enough that a silent connection gets closed by whatever
+	* proxy sits in front of the app — and long enough that a progress line is
+	* worth showing regardless.
+	*/
+	fromGithubStream: oc.input(InstallFromGithubDTOSchema).output(eventIterator(InstallEventVOSchema))
 };
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/templates/types.ts
@@ -3923,6 +4130,11 @@ const TemplateCardVOSchema = z.object({
 	* accidentally point at a different ref than the one it installs.
 	*/
 	screenshots: z.array(z.string()).default([]),
+	/**
+	* Absolute URL of the demo clip, or absent. Resolved against a different host
+	* than the screenshots — see `videoUrl` in the catalog logic.
+	*/
+	video: z.string().optional(),
 	agentPrompts: z.array(z.string()).default([]),
 	version: z.string().optional(),
 	author: z.string().optional(),
@@ -4012,6 +4224,7 @@ const VaultItemInputSchema = z.object({
 	})
 });
 const UpdateVaultSettingsInputSchema = z.object({ items: z.array(VaultItemInputSchema).max(200) });
+const UpdatePreviewFileCredentialInputSchema = z.object({ apiKey: VaultItemValueSchema.trim().min(1).nullable() });
 const VaultItemVOSchema = VaultItemInputSchema.extend({
 	id: z.string(),
 	scopeId: z.string().nullable(),
@@ -4043,6 +4256,13 @@ const vaultContract = {
 		summary: "Replace local Vault settings",
 		successDescription: "Updated local Vault secrets and variables."
 	}).input(UpdateVaultSettingsInputSchema).output(VaultSettingsVOSchema),
+	updatePreviewFileCredential: oc.route({
+		method: "PUT",
+		path: "/vault/previewfile",
+		tags: ["Vault"],
+		summary: "Set or remove the local PreviewFile credential",
+		successDescription: "The credential was updated without returning its value."
+	}).input(UpdatePreviewFileCredentialInputSchema).output(VaultSuccessSchema),
 	clear: oc.route({
 		method: "DELETE",
 		path: "/vault",

package/dist/{template-C5oO6Au_.js → template-D10kjpd-.js}

@@ -59,6 +59,19 @@ z.object({
 	/** Card/detail screenshots, package-relative (`assets/screenshots/overview.webp`). */
 	screenshots: z.array(z.string()).default([]),
 	/**
+	* Optional demo clip, package-relative (`assets/recordings/busa-crm.mp4`).
+	*
+	* No companion poster field on purpose: the detail page uses
+	* `screenshots[0]`, which the catalog already requires to be the cover. One
+	* declared path instead of two that can disagree with each other.
+	*
+	* Note for anyone adding a sibling field here: this is a plain `z.object`, so
+	* an unrecognized key in `busabase.json` is silently stripped rather than
+	* rejected. A template cannot declare a field ahead of the schema landing —
+	* it just vanishes, with no error from `busabase-cli check`.
+	*/
+	video: z.string().optional(),
+	/**
 	* Ready-made prompts shown after install ("Ask agent" prefills the first).
 	*
 	* They are the difference between a folder of tables and something a user can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-sdk",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Typed TypeScript/JavaScript SDK for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server` (or Busabase Cloud). Short-name alias for busabase-sdk.",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-sdk",