busabase-sdk 0.42.0 → 0.50.0

package/dist/airapp.d.ts

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

package/dist/airapp.js

@@ -1,137 +1,4 @@
-import { z } from "zod";
-//#region ../../packages/busabase-contract/src/domains/skill/frontmatter.ts
-/**
-* `SKILL.md` frontmatter — the generic shape, independent of Busabase.
-*
-* This used to live inside `domains/package/template.ts`, which encoded an
-* assumption that no longer holds: that a Skill is a *part of* a template. Most
-* Skills are not. A Skill is a directory with a `SKILL.md` an agent reads; it
-* needs no `busabase.json`, ships no `content/`, and never installs into a
-* workspace. Busabase's own `busabase-app-creator` is one.
-*
-* Modelling it only as a template component meant there was nowhere to hang
-* checks for a plain Skill, so there were none. Hence its own file, in the
-* domain it belongs to.
-*
-* `metadata` is deliberately open: a Skill carries whatever its ecosystem
-* defines (categories, tags, risk labels, per-agent hints). The Busabase-specific
-* block that decides template-ness is layered on in `domains/package/template.ts`
-* — the template format knows about Skills, not the other way round.
-*/
-const SkillFrontmatterSchema$1 = z.object({
-	/** Identity. For a Skill inside a package this must equal the package name. */
-	name: z.string().min(1),
-	/**
-	* How an agent decides whether to reach for this Skill at all — so an empty one
-	* is not a cosmetic omission, it is a Skill that never gets picked.
-	*/
-	description: z.string().default(""),
-	metadata: z.object({}).passthrough().optional()
-});
-const TemplateAirAppRefSchema = z.object({
-	/** Slug of the `content/<dir>` holding the AirApp. */
-	slug: z.string().min(1),
-	role: z.enum([
-		"primary",
-		"admin",
-		"public",
-		"tool"
-	]),
-	label: z.string().optional()
-});
-/**
-* Secrets the app expects to find in the Vault.
-*
-* DECLARED, never created: the package format has no slot for secret values and
-* must not grow one (the same "you cannot leak what the format cannot express"
-* rule the whole format is built on). Install surfaces these as a post-install
-* prompt; the user fills them in the Vault themselves.
-*/
-const TemplateSecretSchema = z.object({
-	key: z.string().min(1),
-	description: z.string().default(""),
-	required: z.boolean().default(true)
-});
-z.object({
-	/** Template Center category, e.g. `"crm"`, `"email"`, `"content"`. */
-	category: z.string().min(1),
-	tags: z.array(z.string()).default([]),
-	/** Card/detail screenshots, package-relative (`assets/screenshots/overview.webp`). */
-	screenshots: z.array(z.string()).default([]),
-	/**
-	* 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
-	* *use*: the point of a template is that the agent already knows the job, and
-	* these are how that is made visible rather than left for the user to guess.
-	*/
-	agentPrompts: z.array(z.string()).default([]),
-	/** Single-AirApp shorthand. Mutually exclusive with `airapps`. */
-	airapp: z.string().optional(),
-	/** Multi-AirApp form. Exactly one entry must have `role: "primary"`. */
-	airapps: z.array(TemplateAirAppRefSchema).optional(),
-	/**
-	* Bumped by the author when the declared resource shape changes.
-	*
-	* Part of the ownership stamp, so BOTH doors must agree on it: the installer
-	* writes it, and a skill's own `setup.mjs` compares against it to decide
-	* whether a node it finds is its own current shape or an older one to repair.
-	* Defaulted rather than required so an author who never versions their app
-	* still gets a stamp both sides recognise.
-	*/
-	schemaVersion: z.number().int().nonnegative().default(1),
-	vaultNamespace: z.string().optional(),
-	secrets: z.array(TemplateSecretSchema).default([]),
-	requires: z.object({ airapp: z.boolean().optional() }).default({})
-});
-/**
-* `metadata.busabase` inside the root `SKILL.md`'s YAML frontmatter.
-*
-* `template: true` is an EXPLICIT opt-in, not an inference from "this skill
-* happens to contain a package". Publishing a template means accepting that
-* installers will run its AirApp code and feed its SKILL.md to their agent; that
-* deserves a deliberate flag rather than a side effect of directory shape.
-*/
-const SkillBusabaseMetadataSchema = z.object({
-	template: z.boolean().default(false),
-	folderSlug: z.string().optional(),
-	/** Resource keys the manual talks about; each must exist under `content/`. */
-	resources: z.array(z.string()).default([]),
-	risk: z.string().optional()
-});
-SkillFrontmatterSchema$1.extend({ metadata: z.object({ busabase: SkillBusabaseMetadataSchema.optional() }).passthrough().optional() });
-/** Stamp on every resource node (Base, Drive, AirApp, …) an app owns. */
-const AppResourceOwnershipSchema = z.object({
-	appId: z.string().min(1),
-	/** Stable internal handle (`"contacts"`), NOT the installed slug. */
-	resourceKey: z.string().min(1),
-	schemaVersion: z.number().int().nonnegative()
-});
-/**
-* The `resourceKey` reserved for an app's root Folder.
-*
-* `busabase-sdk` recognises an app's own Folder by looking for exactly this
-* value (`ownsAppRoot`), so the installer must write it too — a Folder stamped
-* with anything else reads as a stranger's, and the skill's own `setup.mjs`
-* then refuses to touch its own workspace with `SETUP_CONFLICT`. Exported so
-* neither side carries the string literal privately.
-*/
-const APP_ROOT_RESOURCE_KEY = "app-root";
-AppResourceOwnershipSchema.extend({
-	resourceKey: z.literal(APP_ROOT_RESOURCE_KEY),
-	version: z.string().optional(),
-	source: z.object({
-		repo: z.string().optional(),
-		ref: z.string().optional(),
-		subdir: z.string().optional()
-	}).optional(),
-	installedAt: z.string().optional()
-});
-z.object({
-	appId: z.string().min(1),
-	["isTemplateSkill"]: z.literal(true)
-});
-//#endregion
+import { t as APP_ROOT_RESOURCE_KEY } from "./template-C5oO6Au_.js";
 //#region src/airapp.ts
 /**
 * AirApp resource provisioning — how an app claims (or creates) the Folder and

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

@@ -14926,6 +14926,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -14953,6 +14954,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -14980,6 +14982,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -15009,6 +15012,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -15036,6 +15040,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -15063,6 +15068,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -15087,6 +15093,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       baseId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       enabled: z.ZodDefault<z.ZodBoolean>;
@@ -15103,6 +15110,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       baseId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       enabled: z.ZodDefault<z.ZodBoolean>;
@@ -15119,6 +15127,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       baseId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       enabled: z.ZodDefault<z.ZodBoolean>;
@@ -15137,6 +15146,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -15164,6 +15174,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -15191,6 +15202,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -15215,6 +15227,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       baseId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       enabled: z.ZodDefault<z.ZodBoolean>;
@@ -15232,6 +15245,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       baseId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       enabled: z.ZodDefault<z.ZodBoolean>;
@@ -15249,6 +15263,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       baseId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       enabled: z.ZodDefault<z.ZodBoolean>;
@@ -15268,6 +15283,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -15295,6 +15311,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -15322,6 +15339,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       enabled: z.ZodBoolean;
       createdBy: z.ZodString;
@@ -15355,6 +15373,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       status: z.ZodEnum<{
         failed: "failed";
@@ -15376,6 +15395,7 @@ declare const cloudContract: {
         "asset.uploaded": "asset.uploaded";
         changes_requested: "changes_requested";
         "record.created": "record.created";
+        "record.updated": "record.updated";
       }>;
       status: z.ZodEnum<{
         failed: "failed";
@@ -15571,6 +15591,12 @@ declare const cloudContract: {
         name: z.ZodString;
         description: z.ZodString;
         category: z.ZodString;
+        risk: z.ZodOptional<z.ZodEnum<{
+          "gated-write": "gated-write";
+          "local-write": "local-write";
+          "read-only": "read-only";
+          sandbox: "sandbox";
+        }>>;
         tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
         screenshots: z.ZodDefault<z.ZodArray<z.ZodString>>;
         agentPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -19476,6 +19502,31 @@ declare const cloudContract: {
         }>;
         value: z.ZodOptional<z.ZodUnknown>;
       }, z.core.$strip>>>;
+      valueFilters: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        fieldSlug: z.ZodString;
+        operator: z.ZodEnum<{
+          eq: "eq";
+          gt: "gt";
+          gte: "gte";
+          lt: "lt";
+          lte: "lte";
+          ne: "ne";
+        }>;
+        value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>;
+      }, z.core.$strip>, z.ZodObject<{
+        any: z.ZodArray<z.ZodObject<{
+          fieldSlug: z.ZodString;
+          operator: z.ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+          }>;
+          value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>;
+        }, z.core.$strip>>;
+      }, z.core.$strip>]>>>;
       sort: z.ZodOptional<z.ZodObject<{
         fieldSlug: z.ZodString;
         fieldType: z.ZodOptional<z.ZodString>;
@@ -19930,12 +19981,51 @@ declare const cloudContract: {
         }>;
         value: z.ZodOptional<z.ZodUnknown>;
       }, z.core.$strip>>>;
+      valueFilters: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        fieldSlug: z.ZodString;
+        operator: z.ZodEnum<{
+          eq: "eq";
+          gt: "gt";
+          gte: "gte";
+          lt: "lt";
+          lte: "lte";
+          ne: "ne";
+        }>;
+        value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>;
+      }, z.core.$strip>, z.ZodObject<{
+        any: z.ZodArray<z.ZodObject<{
+          fieldSlug: z.ZodString;
+          operator: z.ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+          }>;
+          value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>;
+        }, z.core.$strip>>;
+      }, z.core.$strip>]>>>;
     }, z.core.$strip>>>, z.ZodObject<{
       total: z.ZodNumber;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     groupBy: import("@orpc/contract").ContractProcedure<z.ZodObject<{
       baseId: z.ZodString;
-      fieldSlug: z.ZodString;
+      fieldSlug: z.ZodOptional<z.ZodString>;
+      bucketing: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        grid: "grid";
+        sql: "sql";
+      }>>>;
+      aggregates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        fn: z.ZodEnum<{
+          avg: "avg";
+          count: "count";
+          max: "max";
+          min: "min";
+          sum: "sum";
+        }>;
+        fieldSlug: z.ZodString;
+      }, z.core.$strip>>>;
       viewId: z.ZodOptional<z.ZodString>;
       filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
         fieldSlug: z.ZodString;
@@ -19950,10 +20040,36 @@ declare const cloudContract: {
         }>;
         value: z.ZodOptional<z.ZodUnknown>;
       }, z.core.$strip>>>;
+      valueFilters: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        fieldSlug: z.ZodString;
+        operator: z.ZodEnum<{
+          eq: "eq";
+          gt: "gt";
+          gte: "gte";
+          lt: "lt";
+          lte: "lte";
+          ne: "ne";
+        }>;
+        value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>;
+      }, z.core.$strip>, z.ZodObject<{
+        any: z.ZodArray<z.ZodObject<{
+          fieldSlug: z.ZodString;
+          operator: z.ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+          }>;
+          value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>;
+        }, z.core.$strip>>;
+      }, z.core.$strip>]>>>;
     }, z.core.$strip>, z.ZodObject<{
       groups: z.ZodArray<z.ZodObject<{
-        value: z.ZodNullable<z.ZodString>;
+        value: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
         count: z.ZodNumber;
+        aggregates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
       }, z.core.$strip>>;
       total: z.ZodNumber;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, import("@orpc/contract").MergedErrorMap<Record<never, never>, {

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-vnydDLvt.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-EYjDfri3.js";
 import { z } from "zod";
 //#region src/url.d.ts
 /**

package/dist/index.js

@@ -1,3 +1,4 @@
+import { n as TemplateRiskLevelSchema } from "./template-C5oO6Au_.js";
 import { t as normalizeBaseUrl } from "./url-B8GMXalA.js";
 import { ORPCError, createORPCClient } from "@orpc/client";
 import { OpenAPILink } from "@orpc/openapi-client/fetch";
@@ -1222,12 +1223,7 @@ const nodeShareSchema = z.object({
 const listNodesInputSchema = z.object({
 	parentId: z.string().nullable().optional().describe("Node to start from. Omit or null to start from the space root."),
 	depth: z.coerce.number().int().min(1).max(5).optional().describe("How many levels beneath the start point to eagerly include (default 2 once either field is set). Capped at 5."),
-	/**
-	* `active` (default) walks the live tree. `archived` returns the flat set of
-	* soft-archived nodes for the Trash view — no `parentId`/`depth` walk, since
-	* archived nodes are shown as a list, not a tree.
-	*/
-	status: z.enum(["active", "archived"]).optional().default("active"),
+	status: z.enum(["active", "archived"]).optional().default("active").describe("`active` walks the live TREE. `archived` returns a FLAT list of soft-archived nodes (the Trash view) with no parent/depth walk — so the response shape you can rely on differs between the two, not just the rows."),
 	/**
 	* Narrow to specific node types and return a FLAT list of lightweight node
 	* summaries (`children: []`) instead of walking the tree. This is what
@@ -1254,8 +1250,8 @@ const listNodesInputSchema = z.object({
 	types: z.union([z.array(z.enum(NODE_TYPES)), z.enum(NODE_TYPES)]).transform((value) => Array.isArray(value) ? value : [value]).optional().describe("Return a flat list of lightweight summaries for these node types instead of the tree. Read one node's full detail with GET /nodes/{nodeId}.")
 }).optional();
 const isDescendantInputSchema = z.object({
-	nodeId: z.string(),
-	potentialAncestorId: z.string()
+	nodeId: z.string().describe("The node walked UPWARDS from — the possible descendant."),
+	potentialAncestorId: z.string().describe("The node looked for on the way up. Answers \"is `nodeId` inside this one?\", not the reverse — swapping the two silently returns the wrong answer rather than an error.")
 });
 const isDescendantOutputSchema = z.object({ isDescendant: z.boolean() });
 const updateNodeMetadataInputSchema = z.object({
@@ -1322,8 +1318,8 @@ const updateNodeAgentPromptsInputSchema = z.object({
 	agentPrompts: customAgentPromptsSchema.nullable()
 });
 const searchNodesByNameInputSchema = z.object({
-	query: z.string().min(1),
-	limit: z.coerce.number().int().min(1).max(50).optional().default(20)
+	query: z.string().min(1).describe("Matched against node NAMES only. Use `/api/v1/search` to search content."),
+	limit: z.coerce.number().int().min(1).max(50).optional().default(20).describe("Results to return. Capped at 50 here, unlike most listings' 100.")
 });
 const nodeSearchResultSchema = z.object({
 	id: z.string(),
@@ -1514,8 +1510,8 @@ const mentionInboxPageSchema = z.object({
 	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)
+	page: z.number().int().min(1).optional().default(1).describe("1-indexed, not 0-indexed."),
+	pageSize: z.number().int().min(1).max(100).optional().default(50).describe("Mentions per page. Capped at 100.")
 });
 const markMentionsReadInputSchema = z.object({ 
 /** Stamps every unread mention row this caller has on that comment. */
@@ -1753,8 +1749,8 @@ const reviewChangeRequestInputSchema = z.object({
 	reason: z.string().optional()
 });
 const commentSubjectInputSchema = z.object({
-	subjectType: commentSubjectTypeSchema,
-	subjectId: z.string().min(1)
+	subjectType: commentSubjectTypeSchema.describe("What the comment thread hangs off, which decides how `subjectId` is interpreted."),
+	subjectId: z.string().min(1).describe("The subject's id, interpreted according to `subjectType`.")
 });
 const createCommentInputSchema = commentSubjectInputSchema.extend({
 	authorId: z.string().optional().default("local-admin"),
@@ -1766,34 +1762,33 @@ const createCommentInputSchema = commentSubjectInputSchema.extend({
 	*/
 	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 });
+const listInputSchema = z.object({ limit: z.coerce.number().int().min(1).max(100).optional().default(50).describe("Rows to return, most recent first. Capped at 100; this listing has no cursor.") }).optional().default({ limit: 50 });
 /**
 * Active-or-archived selector for listings whose archived twin was folded in.
 * Archived rows are the same shape as live ones — the only thing that ever
 * differed between `/x` and `/x/archived` was this predicate.
 */
-const listByStatusInputSchema = z.object({ status: z.enum(["active", "archived"]).optional().default("active") });
+const listByStatusInputSchema = z.object({ status: z.enum(["active", "archived"]).optional().default("active").describe("`active` (default) or the soft-archived set. Archived rows have the SAME shape as live ones — this is a predicate, not a different resource.") });
 const listChangeRequestsPagedInputSchema = z.object({
-	limit: z.coerce.number().int().min(1).max(100).optional().default(50),
-	/** Opaque base64 cursor (`createdAt|id`) for keyset pagination. */
-	cursor: z.string().optional(),
-	status: z.array(changeRequestStatusSchema).optional(),
-	mine: z.boolean().optional(),
-	affectsNodeId: z.string().min(1).optional()
+	limit: z.coerce.number().int().min(1).max(100).optional().default(50).describe("Change requests per page. Capped at 100; ask for the next page with `cursor`."),
+	cursor: z.string().optional().describe("Opaque page cursor: pass back the `nextCursor` from the previous response. Do not construct or parse it."),
+	status: z.array(changeRequestStatusSchema).optional().describe("Keep only these statuses. Omitting it returns every status, not just open ones."),
+	mine: z.boolean().optional().describe("Only change requests CREATED by the acting user — not ones awaiting their review."),
+	affectsNodeId: z.string().min(1).optional().describe("Only change requests whose target, or any of their operations, touches this node — including Base-backed nodes. To ask whether a resource already has an unfinished change request, pass this with `limit: 1` rather than paging the space: an empty result is conclusive.")
 }).optional().default({ limit: 50 });
 const listChangeRequestsResponseSchema = z.object({
 	changeRequests: z.array(changeRequestSchema),
 	nextCursor: z.string().nullable()
 });
 const changeRequestPageInputShape = {
-	page: z.coerce.number().int().min(1).optional().default(1),
-	pageSize: z.coerce.number().int().min(1).max(100).optional().default(50),
-	status: z.array(changeRequestStatusSchema).optional(),
-	mine: z.boolean().optional()
+	page: z.coerce.number().int().min(1).optional().default(1).describe("1-indexed, not 0-indexed."),
+	pageSize: z.coerce.number().int().min(1).max(100).optional().default(50).describe("Change requests per page. Capped at 100."),
+	status: z.array(changeRequestStatusSchema).optional().describe("Keep only these statuses. Omitting it returns every status, not just open ones."),
+	mine: z.boolean().optional().describe("Only change requests CREATED by the acting user — not ones awaiting their review.")
 };
 const listChangeRequestsPageInputSchema = z.object({
 	...changeRequestPageInputShape,
-	affectsNodeId: z.string().min(1).optional()
+	affectsNodeId: z.string().min(1).optional().describe("Only change requests whose target, or any of their operations, touches this node — including Base-backed nodes.")
 }).optional().default({
 	page: 1,
 	pageSize: 50
@@ -1825,9 +1820,9 @@ const SEARCH_SOURCES = [
 	"nodes"
 ];
 const searchInputSchema = z.object({
-	query: z.string().default(""),
-	limit: z.coerce.number().int().min(1).max(100).optional().default(20),
-	offset: z.coerce.number().int().min(0).optional().default(0),
+	query: z.string().default("").describe("Full-text query. An empty string matches nothing."),
+	limit: z.coerce.number().int().min(1).max(100).optional().default(20).describe("Results per page. Capped at 100; note the default is 20, not 50."),
+	offset: z.coerce.number().int().min(0).optional().default(0).describe("0-indexed skip count. This endpoint pages by offset, not by cursor."),
 	/**
 	* Restrict which content this call searches. Omitted means all three
 	* (unchanged behavior for every caller before this parameter existed).
@@ -1837,7 +1832,7 @@ const searchInputSchema = z.object({
 	* (`?sources=records&sources=files`) becomes an array. Accept both shapes
 	* and normalize to an array.
 	*/
-	sources: z.union([z.array(z.enum(SEARCH_SOURCES)), z.enum(SEARCH_SOURCES)]).transform((value) => Array.isArray(value) ? value : [value]).optional()
+	sources: z.union([z.array(z.enum(SEARCH_SOURCES)), z.enum(SEARCH_SOURCES)]).transform((value) => Array.isArray(value) ? value : [value]).optional().describe("Restrict which content is searched. Omitting it searches ALL sources. Repeat the parameter to pass several (`?sources=records&sources=files`); a single occurrence is accepted as a bare value.")
 });
 const authSpaceSchema = z.object({
 	id: z.string(),
@@ -2003,11 +1998,9 @@ const fileTreeNodeTypeSchema = z.enum([
 	"drive",
 	"airapp"
 ]);
-/** `nodeId` accepts a node id or a slug. A slug is only unique *within* a type,
-*  so pass `type` alongside it to disambiguate; a node id needs no hint. */
 const fileTreeRefSchema = z.object({
-	nodeId: z.string(),
-	type: fileTreeNodeTypeSchema.optional()
+	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 = {
 	create: oc.route({
@@ -2351,8 +2344,8 @@ z.object({
 /** `GET /assets/{assetId}/text/lines?startLine&endLine` — range capped at 2000 lines. */
 const ReadTextLinesInputSchema = z.object({
 	assetId: z.string(),
-	startLine: z.coerce.number().int().min(1),
-	endLine: z.coerce.number().int().min(1)
+	startLine: z.coerce.number().int().min(1).describe("First line to read. 1-indexed, and INCLUSIVE."),
+	endLine: z.coerce.number().int().min(1).describe("Last line to read, INCLUSIVE. A range wider than 2000 lines is silently narrowed to the first 2000 rather than rejected — the response reports `lineCountCapped` when that happened, so check it before concluding the file ends there.")
 });
 const ReadLinesVOSchema = z.object({
 	lines: z.array(z.string()),
@@ -2639,21 +2632,68 @@ const listRecordsSortSchema = z.object({
 	fieldType: z.string().optional(),
 	direction: z.enum(["asc", "desc"]).optional().default("asc")
 });
+const listRecordsValueFilterSchema = z.object({
+	fieldSlug: z.string(),
+	operator: z.enum([
+		"eq",
+		"ne",
+		"gt",
+		"gte",
+		"lt",
+		"lte"
+	]),
+	/**
+	* A number for number fields, an ISO 8601 string for date fields, a boolean
+	* for checkbox, and a string for the text-like families (where only `eq`/`ne`
+	* are exact — see `buildExactValueFilter`).
+	*/
+	value: z.union([
+		z.number(),
+		z.string(),
+		z.boolean()
+	])
+});
+/**
+* One conjunct of `valueFilters`: either a single comparison, or a disjunction
+* of them.
+*
+* `valueFilters` is an AND of these, so an entry carrying `any` makes the whole
+* list a CNF (an AND of ORs) — which is enough to express ANY boolean
+* combination of comparisons, since every formula has a CNF. That is why this
+* is one flat level rather than an arbitrarily nested tree: a recursive schema
+* would buy no expressive power, and would cost a `z.lazy` that OpenAPI
+* generation and generated clients both handle worse than a plain union.
+*
+* NOT is deliberately absent, and is not a gap: every operator here has an
+* exact negation (`eq`↔`ne`, `gt`↔`lte`, `gte`↔`lt`), so a caller pushes
+* negation down to the leaves with De Morgan before sending. Keeping NOT out of
+* the wire format keeps the server's evaluation MONOTONE, which is what makes
+* the missing-value semantics below sound.
+*
+* Missing values: a comparison against a field the record has no row for is
+* false, never true — the `EXISTS` in `buildExactValueFilter` sees no row. That
+* collapses SQL's UNKNOWN to false at each leaf, which is safe here precisely
+* because the formula is monotone: for an AND/OR tree with no NOT, "Kleene
+* three-valued result is TRUE" and "result with UNKNOWN replaced by FALSE is
+* TRUE" agree (OR is `some operand true` and AND is `all operands true` under
+* both readings). A NOT anywhere in the tree would break that equivalence,
+* which is the other reason it is not on the wire.
+*/
+const listRecordsValueFilterNodeSchema = z.union([listRecordsValueFilterSchema, z.object({ any: z.array(listRecordsValueFilterSchema).min(1) })]);
 const listRecordsInputSchema = z.object({
-	limit: z.coerce.number().int().min(1).max(100).optional().default(50),
-	baseId: z.string().optional(),
-	/** Opaque base64 cursor for keyset pagination (createdAt-keyed, or sort-keyed when `sort` is set). */
-	cursor: z.string().optional(),
+	limit: z.coerce.number().int().min(1).max(100).optional().default(50).describe("Records per page. Capped at 100; ask for the next page with `cursor`."),
+	baseId: z.string().optional().describe("Restrict to one Base. OMITTING it lists records across the WHOLE SPACE, which is rarely what a caller means and is easy to miss — every other parameter still applies, so an unscoped query looks like it worked."),
+	cursor: z.string().optional().describe("Opaque page cursor: pass back the `nextCursor` from the previous response. Do not construct or parse it — it is keyed on `createdAt`, or on the sort field when `sort` is given, and that is an implementation detail."),
+	status: z.enum(["active", "archived"]).optional().default("active").describe("`active` is the live table; `archived` is the Base's trash."),
+	filters: z.array(listRecordsFilterSchema).optional().describe("View filters — a best-effort SUPERSET, not an exact answer. They mean what the grid means (a currency number reads as \"$1,234.00\", a select as its choice label), and the server may return records that do not match, so the caller must narrow them again and must NOT trust `limit` alongside them. Use `valueFilters` when you need an exact row set."),
 	/**
-	* `active` (default) is the live table; `archived` is the Base's trash — the
-	* same keyset pagination either way, which is why these are one endpoint
-	* rather than a `/records/archived` twin.
+	* Exact value comparisons. Unlike `filters` these are authoritative — the
+	* returned rows are exactly those that match, so a caller can page and
+	* limit against them. ANDed together (and with `filters` when both are
+	* given); an entry may be a disjunction, making the list a CNF.
 	*/
-	status: z.enum(["active", "archived"]).optional().default("active"),
-	/** View filters for server-side push-down (superset; client still narrows). */
-	filters: z.array(listRecordsFilterSchema).optional(),
-	/** View sort for server-side push-down (number/date fields only). */
-	sort: listRecordsSortSchema.optional()
+	valueFilters: z.array(listRecordsValueFilterNodeSchema).optional().describe("EXACT value comparisons, unlike `filters` which are a best-effort superset. The returned rows are exactly those that match, so `limit` can be trusted alongside them. Entries are ANDed; an entry may instead be `{ any: [...] }` to OR its comparisons, which makes the list a CNF and can express any boolean combination. Requires `baseId`. Compares number, date, checkbox and text-like fields (text and select support eq/ne only); anything else is a 400 rather than a silently dropped condition."),
+	sort: listRecordsSortSchema.optional().describe("Sort by one field. Only number and date fields sort authoritatively (their typed value column matches a client's own ordering); any other field type is returned in the default order and left for the caller to sort.")
 }).optional().default({
 	limit: 50,
 	status: "active"
@@ -2663,8 +2703,8 @@ const listRecordsResponseSchema = z.object({
 	nextCursor: z.string().nullable()
 });
 const listRecordsPageInputSchema = z.object({
-	baseId: z.string().min(1),
-	viewId: z.string().min(1).optional(),
+	baseId: z.string().min(1).describe("Required here, unlike `records.list` where omitting it spans the whole space."),
+	viewId: z.string().min(1).optional().describe("Show only what this saved View would: its filters and its sort."),
 	/**
 	* Extra conditions ANDed with the View's own filters — "this View, further
 	* narrowed". The motivating case is one board column: the saved View's
@@ -2677,7 +2717,7 @@ const listRecordsPageInputSchema = z.object({
 	* That distinction is the whole point — a *superset* page can be missing
 	* records, and a board column that silently drops cards reads as data loss.
 	*/
-	filters: z.array(listRecordsFilterSchema).optional(),
+	filters: z.array(listRecordsFilterSchema).optional().describe("Extra conditions ANDed with the View's own — \"this View, further narrowed\". Unlike `records.list`'s `filters`, these are EXACT: every page is precisely what the client's own matcher would keep, so a page is never missing records it should hold."),
 	/**
 	* Scope the page to records whose `date`/`created_time`/`updated_time` field
 	* falls in `[gte, lt)` — an absolute UTC instant range, not a `filters`
@@ -2695,13 +2735,11 @@ const listRecordsPageInputSchema = z.object({
 	*/
 	dateRange: z.object({
 		fieldSlug: z.string().min(1),
-		/** Inclusive lower bound, ISO 8601 UTC instant. */
-		gte: z.string(),
-		/** Exclusive upper bound, ISO 8601 UTC instant. */
-		lt: z.string()
-	}).optional(),
-	page: z.coerce.number().int().min(1).optional().default(1),
-	pageSize: z.coerce.number().int().min(1).max(100).optional().default(50)
+		gte: z.string().describe("Inclusive lower bound, ISO 8601 UTC instant."),
+		lt: z.string().describe("EXCLUSIVE upper bound, ISO 8601 UTC instant.")
+	}).optional().describe("Scope the page to a `date`/`created_time`/`updated_time` field falling in `[gte, lt)` — a half-open range of absolute UTC instants, not a `filters` condition. Resolve the bounds yourself: a day or a month only means something in a timezone, and the server does not know the viewer's."),
+	page: z.coerce.number().int().min(1).optional().default(1).describe("1-indexed, not 0-indexed."),
+	pageSize: z.coerce.number().int().min(1).max(100).optional().default(50).describe("Records per page. Capped at 100.")
 });
 const listRecordsPageResponseSchema = z.object({
 	records: z.array(recordSchema),
@@ -2711,13 +2749,8 @@ const listRecordsPageResponseSchema = z.object({
 	pageSize: z.number().int().min(1).max(100)
 });
 const countRecordsInputSchema = z.object({
-	baseId: z.string().optional(),
-	/**
-	* Count only the rows a saved View would display (the View's filters
-	* applied; its sort is ignored — a count doesn't need an order). A View
-	* belongs to exactly one Base, so this requires `baseId`.
-	*/
-	viewId: z.string().optional(),
+	baseId: z.string().optional().describe("Restrict to one Base. Omitting it counts every record in the space. Required as soon as `viewId`, `filters` or `valueFilters` is given — a field slug only means something within one Base."),
+	viewId: z.string().optional().describe("Count only what this saved View would display. Its filters apply; its sort is ignored, since a count has no order. Requires `baseId`."),
 	/**
 	* Ad-hoc filter conditions — same shape `records.list`'s `filters` uses —
 	* for composing a condition set without a saved View (e.g. an AirApp
@@ -2728,8 +2761,23 @@ const countRecordsInputSchema = z.object({
 	* never the caller-supplied `fieldType` hint, which elsewhere is only a
 	* pushdown hint and isn't trustworthy enough for an exact count.
 	*/
-	filters: z.array(listRecordsFilterSchema).optional()
+	filters: z.array(listRecordsFilterSchema).optional().describe("Ad-hoc conditions, ANDed with the View's own when `viewId` is also given. Unlike `records.list`'s superset `filters`, the COUNT is exact either way — but a condition whose exactness cannot be proven makes the server read every candidate row instead of running one aggregate, so prefer `valueFilters` where it fits. Requires `baseId`."),
+	/**
+	* Exact value comparisons, same shape and meaning as `records.list`'s.
+	*
+	* Worth having here specifically because they are ALWAYS exact: a count
+	* scoped only by these stays a single SQL `count(*)`, where an ad-hoc view
+	* `filters` set that cannot be proven exact falls back to reading every
+	* candidate row and counting the survivors. Requires `baseId` for the same
+	* reason `filters` does — a field slug is only unambiguous within one Base.
+	*/
+	valueFilters: z.array(listRecordsValueFilterNodeSchema).optional().describe("EXACT value comparisons, same shape as `records.list`'s. Always exact, so a count scoped only by these stays a single SQL count instead of reading every candidate row. Requires `baseId`.")
 }).superRefine((value, ctx) => {
+	if (value.valueFilters?.length && !value.baseId) ctx.addIssue({
+		code: "custom",
+		path: ["baseId"],
+		message: "baseId is required when valueFilters is given"
+	});
 	if (value.viewId && !value.baseId) ctx.addIssue({
 		code: "custom",
 		path: ["baseId"],
@@ -2744,9 +2792,30 @@ const countRecordsInputSchema = z.object({
 const countRecordsResponseSchema = z.object({ 
 /** Total active records in the space (optionally scoped to a base). */
 total: z.number().int().nonnegative() });
+/**
+* A numeric aggregate over the records in a group.
+*
+* Exact for the same reason `valueFilters` are: `value_number` holds the value
+* itself, so `sum`/`avg`/`min`/`max` are ordinary SQL over a real column with
+* no formatting layer to diverge from. Restricted to number-shaped fields for
+* exactly that reason — there is no column to add up on the others.
+*
+* `count` here counts rows whose value is PRESENT, which is not the same as the
+* group's `count` (that one counts records, present value or not). Both are
+* useful and SQL distinguishes them, so both are available.
+*/
+const recordAggregateSchema = z.object({
+	fn: z.enum([
+		"sum",
+		"avg",
+		"min",
+		"max",
+		"count"
+	]),
+	fieldSlug: z.string().min(1)
+});
 const groupRecordsInputSchema = z.object({
-	/** Group within exactly one Base — a field slug is only unambiguous there. */
-	baseId: z.string().min(1),
+	baseId: z.string().min(1).describe("Required: a field slug is only unambiguous within one Base."),
 	/**
 	* The field to group by. Restricted to `select` and `checkbox`: their stored
 	* value IS the grouping key (a choice id / a boolean), so a SQL GROUP BY
@@ -2754,28 +2823,74 @@ const groupRecordsInputSchema = z.object({
 	* be truncated at the projection limit, and date keys would bucket by the
 	* server's timezone rather than the viewer's — both would report a
 	* confidently wrong split, so they're rejected instead of approximated.
+	*
+	* OMIT it to aggregate the whole filtered set as a single bucket. That is the
+	* shape a summary tile wants ("total pipeline value"), and it costs one query
+	* instead of reading every record to add them up client-side.
 	*/
-	fieldSlug: z.string().min(1),
-	/** Group only the rows a saved View would display (its filters; sort ignored). */
-	viewId: z.string().min(1).optional(),
-	/** Ad-hoc filters, ANDed with the View's own when both are given. */
-	filters: z.array(listRecordsFilterSchema).optional()
+	fieldSlug: z.string().min(1).optional().describe("The field to group by. OMIT it to aggregate the whole filtered set as a single bucket, which is what a summary tile wants. Under the default `grid` bucketing only `select` and `checkbox` can be grouped; `sql` bucketing also allows number and date fields."),
+	/**
+	* Which bucketing rules to use, and they genuinely differ.
+	*
+	* `grid` (the default, and what this endpoint has always done) buckets the
+	* way the GRID renders: an unset checkbox folds in with `false`, and an empty
+	* string folds into the null bucket. That is right for a Kanban column header
+	* — a card with no value belongs under "false", not in a fourth column.
+	*
+	* `sql` buckets the way `GROUP BY` does: a missing value gets its OWN bucket
+	* and nothing is folded. That is right for a caller reproducing SQL — an ORM
+	* driver, or anything comparing this against a database — and it is what lets
+	* such a caller trust the server's answer instead of re-grouping locally.
+	*
+	* The two disagree on real data, which is why this is a choice rather than a
+	* fix: neither is a better version of the other.
+	*/
+	bucketing: z.enum(["grid", "sql"]).optional().default("grid").describe("How records are bucketed, and the two modes disagree on real data. `grid` (default) buckets the way the grid renders: an unset checkbox counts as `false` and an empty string falls in the null bucket — right for a Kanban column header. `sql` buckets the way GROUP BY does: a missing value gets its OWN bucket and nothing is folded — right for anything reproducing SQL. `sql` also returns keys in their own type (a number for a number field) rather than as strings."),
+	/**
+	* Numeric aggregates evaluated per group, keyed in the response as
+	* `"<fn>:<fieldSlug>"`. Without this the response is counts only, exactly as
+	* before.
+	*/
+	aggregates: z.array(recordAggregateSchema).optional().describe("Numeric aggregates evaluated per group, keyed in the response as `\"<fn>:<fieldSlug>\"`. Only number-shaped fields can be aggregated; anything else is a 400. `sum`/`avg`/`min`/`max` of a group holding no values are NULL rather than 0, and `count` over a FIELD counts present values — which is not the same as the group's own `count`, which counts records."),
+	viewId: z.string().min(1).optional().describe("Group only what this saved View would display. Its filters apply; its sort is ignored."),
+	filters: z.array(listRecordsFilterSchema).optional().describe("Ad-hoc conditions, ANDed with the View's own when both are given. The grouping is exact either way, but a condition whose exactness cannot be proven makes the server read every candidate row instead of running one GROUP BY."),
+	/**
+	* Exact value comparisons, ANDed with everything above. Always exact, so a
+	* grouping scoped only by these stays a single SQL GROUP BY.
+	*/
+	valueFilters: z.array(listRecordsValueFilterNodeSchema).optional().describe("EXACT value comparisons, same shape as `records.list`'s. Always exact, so a grouping scoped only by these stays a single SQL GROUP BY.")
 });
 const groupRecordsResponseSchema = z.object({
 	groups: z.array(z.object({
 		/**
-		* The raw stored key: a `select` choice id, or `"true"`/`"false"` for a
-		* checkbox. For a select, `null` is the bucket of records with no value
-		* (what a Kanban board shows as its "Uncategorized" column). A checkbox
-		* never reports `null` — an unset checkbox counts as `"false"`, matching
-		* how view filters already treat it (`is_false` covers null/undefined).
+		* The raw stored key.
+		*
+		* Under `grid` bucketing (the default) this is always a string or null: a
+		* `select` choice id, or `"true"`/`"false"` for a checkbox, where `null`
+		* is the bucket of records with no value (a Kanban board's
+		* "Uncategorized" column) and an unset checkbox counts as `"false"`.
+		*
+		* Under `sql` bucketing it is the STORED value in its own type — a number
+		* for a number field, a boolean for a checkbox, an ISO string for a date
+		* — and `null` means the record has no value for that field, which under
+		* these rules is a bucket of its own rather than folded into another.
 		*
 		* Choice LABELS are deliberately not resolved here — the client already
 		* holds the Base's field definitions and renders labels itself, and
 		* returning ids keeps this response stable across a choice rename.
 		*/
-		value: z.string().nullable(),
-		count: z.number().int().nonnegative()
+		value: z.union([
+			z.string(),
+			z.number(),
+			z.boolean()
+		]).nullable().describe("The bucket key. Under `grid` bucketing always a string or null (a select's choice, or `\"true\"`/`\"false\"` for a checkbox, with null meaning \"no value\"). Under `sql` bucketing it is the stored value in its own type, and null is the bucket of records that have no value for the field."),
+		count: z.number().int().nonnegative().describe("Records in this bucket."),
+		/**
+		* Present only when `aggregates` was requested. Keyed `"<fn>:<fieldSlug>"`.
+		* A value of `null` means the group held no rows with that field set —
+		* which is NOT the same as `0`, and a dashboard renders them differently.
+		*/
+		aggregates: z.record(z.string(), z.number().nullable()).optional().describe("Present only when `aggregates` was requested, keyed `\"<fn>:<fieldSlug>\"`. A null value means the bucket held no records with that field set — not zero.")
 	})),
 	/** Sum of every group's count — the same number `records.count` would return. */
 	total: z.number().int().nonnegative()
@@ -2822,10 +2937,10 @@ const createBulkUpdateChangeRequestInputSchema = z.object({
 	}
 });
 const recordFieldFilterInputSchema = z.object({
-	baseId: z.string().optional(),
-	fieldSlug: z.string().min(1),
-	valueText: z.string().min(1),
-	limit: z.coerce.number().int().min(1).max(100).optional().default(50)
+	baseId: z.string().optional().describe("Restrict to one Base. Omitting it searches the whole space."),
+	fieldSlug: z.string().min(1).describe("The field's SLUG, not its display name — visible in the Base's field settings."),
+	valueText: z.string().min(1).describe("Matched by EXACT equality, not substring or fuzzy — this is the de-dup-by-key lookup. Use `/api/v1/search` for full-text."),
+	limit: z.coerce.number().int().min(1).max(100).optional().default(50).describe("Maximum matches to return. Capped at 100.")
 });
 const recordFieldGetInputSchema = z.object({
 	baseId: z.string().describe("Field selector: Base id. Requires fieldSlug and valueText."),
@@ -3099,8 +3214,8 @@ const docContract = { create: oc.route({
 */
 const ReadNodeLinesInputSchema = z.object({
 	nodeId: z.string(),
-	startLine: z.coerce.number().int().min(1),
-	endLine: z.coerce.number().int().min(1)
+	startLine: z.coerce.number().int().min(1).describe("First line to read. 1-indexed, and INCLUSIVE."),
+	endLine: z.coerce.number().int().min(1).describe("Last line to read, INCLUSIVE. A range wider than 2000 lines is silently narrowed to the first 2000 rather than rejected — the response reports `lineCountCapped` when that happened, so check it before concluding the file ends there.")
 });
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/dump/types.ts
@@ -3418,10 +3533,9 @@ const FormVOSchema = z.object({
 	updatedAt: z.string()
 });
 const ListFormsInputSchema = z.object({
-	targetBaseId: z.string().min(1),
-	limit: z.coerce.number().int().min(1).max(100).optional().default(50),
-	/** Opaque createdAt/id keyset cursor. */
-	cursor: z.string().optional()
+	targetBaseId: z.string().min(1).describe("The Base the forms WRITE INTO — required; this is not a space-wide listing."),
+	limit: z.coerce.number().int().min(1).max(100).optional().default(50).describe("Forms per page. Capped at 100; ask for the next page with `cursor`."),
+	cursor: z.string().optional().describe("Opaque page cursor: pass back the `nextCursor` from the previous response. Do not construct or parse it.")
 });
 const ListFormsVOSchema = z.object({
 	forms: z.array(FormVOSchema),
@@ -3754,9 +3868,11 @@ const installContract = {
 * Template Center catalog types (pure zod, client-safe).
 *
 * The catalog is the file `busabase-cli index` builds from a skills repository
-* — see `busabase-package/index-build`. It is re-declared here rather than
-* imported because that module is Node-only (it reads packages), and these
-* shapes are rendered in a browser.
+* — see `busabase-package/index-build`. Most shapes are re-declared here rather
+* than imported because that module is Node-only (it reads packages) and these
+* are rendered in a browser; `TemplateRiskLevelSchema` is the one exception,
+* imported from the package domain because it is already pure zod and a third
+* copy of the same enum is a worse outcome than the cross-domain import.
 *
 * Spec: `apps/busabase/content/spec/template-center.md` §6.4.
 */
@@ -3775,6 +3891,8 @@ const TemplateCardVOSchema = z.object({
 	name: z.string(),
 	description: z.string(),
 	category: z.string(),
+	/** Absent when undeclared or unrecognized — the card shows "undeclared", never a guess. */
+	risk: TemplateRiskLevelSchema.optional(),
 	tags: z.array(z.string()).default([]),
 	/**
 	* Absolute URLs, resolved server-side.
@@ -3812,9 +3930,7 @@ const TemplateCatalogVOSchema = z.object({
 	*/
 	error: z.string().optional()
 });
-const ListTemplatesDTOSchema = z.object({ 
-/** Bypass the cache — the refresh button. */
-refresh: z.boolean().optional() }).optional().default({});
+const ListTemplatesDTOSchema = z.object({ refresh: z.boolean().optional().describe("Bypass the cache and re-fetch the catalogue — what the refresh button does. Slower; leave it off for ordinary reads.") }).optional().default({});
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/templates/contract.ts
 /**
@@ -3919,6 +4035,7 @@ const vaultContract = {
 //#region ../../packages/busabase-contract/src/domains/webhook/types.ts
 const WebhookEventTypeSchema = z.enum([
 	"record.created",
+	"record.updated",
 	"ai_mention",
 	"changes_requested",
 	"asset.uploaded"
@@ -4034,7 +4151,7 @@ const WebhookDeliveryVOSchema = z.object({
 z.object({}).optional().default({});
 const ListWebhookDeliveriesInputSchema = z.object({
 	ruleId: z.string(),
-	limit: z.coerce.number().int().min(1).max(100).default(20)
+	limit: z.coerce.number().int().min(1).max(100).default(20).describe("Delivery attempts to return, newest first.")
 });
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/webhook/contract.ts
@@ -4124,10 +4241,9 @@ const activityItemSchema = z.discriminatedUnion("kind", [
 		record: recordSchema.nullable()
 	})
 ]);
-/** Keyset page request: opaque base64 cursor (`ts|kind|id`) + page size. */
 const listActivityPagedInputSchema = z.object({
-	limit: z.coerce.number().int().min(1).max(100).optional().default(50),
-	cursor: z.string().optional()
+	limit: z.coerce.number().int().min(1).max(100).optional().default(50).describe("Items per page. Capped at 100; ask for the next page with `cursor`."),
+	cursor: z.string().optional().describe("Opaque page cursor: pass back the `nextCursor` from the previous response. Do not construct or parse it.")
 }).optional().default({ limit: 50 });
 const listActivityResponseSchema = z.object({
 	items: z.array(activityItemSchema),
@@ -4135,13 +4251,13 @@ const listActivityResponseSchema = z.object({
 });
 /** Node-scoped raw activity stream request — offset/limit only, no cursor. */
 const listNodeActivityInputSchema = z.object({
-	nodeId: z.string().min(1),
-	limit: z.coerce.number().int().min(1).max(100).optional().default(50)
+	nodeId: z.string().min(1).describe("Activity is scoped to this node alone, not its subtree."),
+	limit: z.coerce.number().int().min(1).max(100).optional().default(50).describe("Most recent events to return, capped at 100. This stream has NO cursor — it is a recent window, not a pageable history; use `/api/v1/activity/paged` to walk further back.")
 });
 /** Record-scoped raw activity stream request — same shape as node, keyed on recordId. */
 const listRecordActivityInputSchema = z.object({
-	recordId: z.string().min(1),
-	limit: z.coerce.number().int().min(1).max(100).optional().default(50)
+	recordId: z.string().min(1).describe("Activity for this record's own history."),
+	limit: z.coerce.number().int().min(1).max(100).optional().default(50).describe("Most recent events to return, capped at 100. This stream has NO cursor — it is a recent window, not a pageable history; use `/api/v1/activity/paged` to walk further back.")
 });
 const EMBED_LINK_MAX_MINUTES = 1440;
 const EmbedNodeTypeSchema = z.enum([
@@ -4220,8 +4336,8 @@ const CreateEmbedLinkInputSchema = z.object({
 	})
 });
 const ListEmbedLinksInputSchema = z.object({
-	type: EmbedTargetTypeSchema.optional(),
-	typeId: z.string().min(1).optional()
+	type: EmbedTargetTypeSchema.optional().describe("Which kind of target the links point at. Omitting it returns links of every kind."),
+	typeId: z.string().min(1).optional().describe("The target's id, interpreted according to `type`.")
 }).optional().default({});
 const RevokeEmbedLinkInputSchema = z.object({ id: z.string().min(1) });
 const EmbedLinkVOSchema = z.object({

package/dist/template-C5oO6Au_.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+//#region ../../packages/busabase-contract/src/domains/skill/frontmatter.ts
+/**
+* `SKILL.md` frontmatter — the generic shape, independent of Busabase.
+*
+* This used to live inside `domains/package/template.ts`, which encoded an
+* assumption that no longer holds: that a Skill is a *part of* a template. Most
+* Skills are not. A Skill is a directory with a `SKILL.md` an agent reads; it
+* needs no `busabase.json`, ships no `content/`, and never installs into a
+* workspace. Busabase's own `busabase-app-creator` is one.
+*
+* Modelling it only as a template component meant there was nowhere to hang
+* checks for a plain Skill, so there were none. Hence its own file, in the
+* domain it belongs to.
+*
+* `metadata` is deliberately open: a Skill carries whatever its ecosystem
+* defines (categories, tags, risk labels, per-agent hints). The Busabase-specific
+* block that decides template-ness is layered on in `domains/package/template.ts`
+* — the template format knows about Skills, not the other way round.
+*/
+const SkillFrontmatterSchema$1 = z.object({
+	/** Identity. For a Skill inside a package this must equal the package name. */
+	name: z.string().min(1),
+	/**
+	* How an agent decides whether to reach for this Skill at all — so an empty one
+	* is not a cosmetic omission, it is a Skill that never gets picked.
+	*/
+	description: z.string().default(""),
+	metadata: z.object({}).passthrough().optional()
+});
+const TemplateAirAppRefSchema = z.object({
+	/** Slug of the `content/<dir>` holding the AirApp. */
+	slug: z.string().min(1),
+	role: z.enum([
+		"primary",
+		"admin",
+		"public",
+		"tool"
+	]),
+	label: z.string().optional()
+});
+/**
+* Secrets the app expects to find in the Vault.
+*
+* DECLARED, never created: the package format has no slot for secret values and
+* must not grow one (the same "you cannot leak what the format cannot express"
+* rule the whole format is built on). Install surfaces these as a post-install
+* prompt; the user fills them in the Vault themselves.
+*/
+const TemplateSecretSchema = z.object({
+	key: z.string().min(1),
+	description: z.string().default(""),
+	required: z.boolean().default(true)
+});
+z.object({
+	/** Template Center category, e.g. `"crm"`, `"email"`, `"content"`. */
+	category: z.string().min(1),
+	tags: z.array(z.string()).default([]),
+	/** Card/detail screenshots, package-relative (`assets/screenshots/overview.webp`). */
+	screenshots: z.array(z.string()).default([]),
+	/**
+	* 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
+	* *use*: the point of a template is that the agent already knows the job, and
+	* these are how that is made visible rather than left for the user to guess.
+	*/
+	agentPrompts: z.array(z.string()).default([]),
+	/** Single-AirApp shorthand. Mutually exclusive with `airapps`. */
+	airapp: z.string().optional(),
+	/** Multi-AirApp form. Exactly one entry must have `role: "primary"`. */
+	airapps: z.array(TemplateAirAppRefSchema).optional(),
+	/**
+	* Bumped by the author when the declared resource shape changes.
+	*
+	* Part of the ownership stamp, so BOTH doors must agree on it: the installer
+	* writes it, and a skill's own `setup.mjs` compares against it to decide
+	* whether a node it finds is its own current shape or an older one to repair.
+	* Defaulted rather than required so an author who never versions their app
+	* still gets a stamp both sides recognise.
+	*/
+	schemaVersion: z.number().int().nonnegative().default(1),
+	vaultNamespace: z.string().optional(),
+	secrets: z.array(TemplateSecretSchema).default([]),
+	requires: z.object({ airapp: z.boolean().optional() }).default({})
+});
+const TemplateRiskLevelSchema = z.enum([
+	"gated-write",
+	"local-write",
+	"read-only",
+	"sandbox"
+]);
+/**
+* `metadata.busabase` inside the root `SKILL.md`'s YAML frontmatter.
+*
+* `template: true` is an EXPLICIT opt-in, not an inference from "this skill
+* happens to contain a package". Publishing a template means accepting that
+* installers will run its AirApp code and feed its SKILL.md to their agent; that
+* deserves a deliberate flag rather than a side effect of directory shape.
+*/
+const SkillBusabaseMetadataSchema = z.object({
+	template: z.boolean().default(false),
+	folderSlug: z.string().optional(),
+	/** Resource keys the manual talks about; each must exist under `content/`. */
+	resources: z.array(z.string()).default([]),
+	/**
+	* Free-form on purpose — see `parseTemplateRisk`. Validating this to the enum
+	* here would turn a stranger's typo or a retired term into a hard parse
+	* failure for the whole frontmatter, which is a worse outcome than a card
+	* that cannot show a risk badge.
+	*/
+	risk: z.string().optional()
+});
+SkillFrontmatterSchema$1.extend({ metadata: z.object({ busabase: SkillBusabaseMetadataSchema.optional() }).passthrough().optional() });
+/** Stamp on every resource node (Base, Drive, AirApp, …) an app owns. */
+const AppResourceOwnershipSchema = z.object({
+	appId: z.string().min(1),
+	/** Stable internal handle (`"contacts"`), NOT the installed slug. */
+	resourceKey: z.string().min(1),
+	schemaVersion: z.number().int().nonnegative()
+});
+/**
+* The `resourceKey` reserved for an app's root Folder.
+*
+* `busabase-sdk` recognises an app's own Folder by looking for exactly this
+* value (`ownsAppRoot`), so the installer must write it too — a Folder stamped
+* with anything else reads as a stranger's, and the skill's own `setup.mjs`
+* then refuses to touch its own workspace with `SETUP_CONFLICT`. Exported so
+* neither side carries the string literal privately.
+*/
+const APP_ROOT_RESOURCE_KEY = "app-root";
+AppResourceOwnershipSchema.extend({
+	resourceKey: z.literal(APP_ROOT_RESOURCE_KEY),
+	version: z.string().optional(),
+	source: z.object({
+		repo: z.string().optional(),
+		ref: z.string().optional(),
+		subdir: z.string().optional()
+	}).optional(),
+	installedAt: z.string().optional()
+});
+z.object({
+	appId: z.string().min(1),
+	["isTemplateSkill"]: z.literal(true)
+});
+//#endregion
+export { TemplateRiskLevelSchema as n, APP_ROOT_RESOURCE_KEY as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-sdk",
-  "version": "0.42.0",
+  "version": "0.50.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",
@@ -67,9 +67,9 @@
     "tsx": "^4.20.5",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
+    "busabase-contract": "0.50.0",
     "open-domains": "0.0.2",
-    "openlib": "0.1.1",
-    "busabase-contract": "0.42.0"
+    "openlib": "0.1.1"
   },
   "engines": {
     "node": ">=24.18.0"