@smartspace/api-client 0.1.0-pr.976.50e1dfd → 0.1.0-pr.976.ba8c32f

package/dist/generated/config/zod.js

@@ -55,7 +55,7 @@ exports.accessGetAccessesResponse = zod_1.default.object({
         "principalType": zod_1.default.enum(['Unknown', 'User', 'ServicePrincipal', 'Internal']).optional(),
         "userEmailAddress": zod_1.default.string().nullish(),
         "workSpaceId": zod_1.default.string().regex(exports.accessGetAccessesResponseDataItemWorkSpaceIdRegExp).nullish()
-    })),
+    }).describe('Full read shape for an access grant. The model collides on the simple\r\nname with `SmartSpace.App.Data.Entities.EntityAccess` at the\r\nnamespace alias boundary — but the entity uses a different short name\r\n(`EntityAccess`), so no alias is required when both are imported.\r\n            \r\nDisplay names (`DisplayName`, `UserEmailAddress`) are not\r\ncolumns on the entity — they are resolved at read time from Azure AD via\r\n`IUserService` / `IAzureADClient` and filled in by the service\r\nafter loading.')),
     "total": zod_1.default.number()
 });
 /**
@@ -66,7 +66,7 @@ exports.accessAddAccessBody = zod_1.default.strictObject({
     "accessType": zod_1.default.enum(['Principal', 'Group']),
     "objectId": zod_1.default.string(),
     "workSpaceId": zod_1.default.string().regex(exports.accessAddAccessBodyWorkSpaceIdRegExp)
-});
+}).describe('Request body for creating an access grant. Access records are junction\r\nrows — there is no `UpdateAccess`; the convention is delete + create.');
 /**
  * @summary List groups from Azure AD.
  */
@@ -93,7 +93,7 @@ exports.accessGetAppRolesResponseItem = zod_1.default.object({
     "description": zod_1.default.string(),
     "id": zod_1.default.string().regex(exports.accessGetAppRolesResponseIdRegExp),
     "name": zod_1.default.string()
-});
+}).describe('Azure AD application-role model. Sourced from AAD; no local EF entity.');
 exports.accessGetAppRolesResponse = zod_1.default.array(exports.accessGetAppRolesResponseItem);
 /**
  * @summary List users assigned to a specific role in SmartSpace by providing the role's ID.
@@ -115,7 +115,7 @@ exports.accessGetUsersInRoleRolesRoleIdUsersResponse = zod_1.default.object({
         "emailAddress": zod_1.default.string().nullish(),
         "isAssigned": zod_1.default.boolean(),
         "userId": zod_1.default.string()
-    })),
+    }).describe('User model in the context of an access-grant picker — adds an\r\n`IsAssigned` flag for highlighting users who already have access to\r\nthe target resource.')),
     "total": zod_1.default.number()
 });
 /**
@@ -155,7 +155,7 @@ exports.accessSearchServicePrincipalsResponse = zod_1.default.object({
         "displayName": zod_1.default.string(),
         "id": zod_1.default.string(),
         "isAssigned": zod_1.default.boolean()
-    })),
+    }).describe('Service-principal counterpart of SmartSpace.App.Business.Models.Users.AppUserSearchResult for\r\nthe same picker UI.')),
     "total": zod_1.default.number()
 });
 /**
@@ -176,7 +176,7 @@ exports.accessSearchUsersResponse = zod_1.default.object({
         "id": zod_1.default.string(),
         "isAssigned": zod_1.default.boolean(),
         "name": zod_1.default.string()
-    })),
+    }).describe('Minimal user search result for autocomplete / picker UIs. Drops every\r\nfield that isn\'t needed to render a row — the picker only needs id, name,\r\nand email.')),
     "total": zod_1.default.number()
 });
 /**
@@ -198,7 +198,7 @@ exports.accessGetUsersInRoleUsersResponse = zod_1.default.object({
         "emailAddress": zod_1.default.string().nullish(),
         "isAssigned": zod_1.default.boolean(),
         "userId": zod_1.default.string()
-    })),
+    }).describe('User model in the context of an access-grant picker — adds an\r\n`IsAssigned` flag for highlighting users who already have access to\r\nthe target resource.')),
     "total": zod_1.default.number()
 });
 /**
@@ -259,7 +259,7 @@ exports.activityGetLoggingResponse = zod_1.default.object({
         "response": zod_1.default.string().nullish(),
         "workSpaceId": zod_1.default.string().regex(exports.activityGetLoggingResponseDataItemWorkSpaceIdRegExp).nullish(),
         "workSpaceName": zod_1.default.string().nullish()
-    })),
+    }).describe('Workspace-scoped activity row returned by the activity log endpoint. The\r\n`EventDescription`, `Prompt`, `Response`, and\r\n`QueryNumber` are deserialised from the activity\'s\r\n`DisplayName` (a JSON-serialised `WorkSpaceConfiguration`);\r\n`LlmUsages` and `DurationMs` from `MetricsJson`. Build\r\nhappens in service code — see `ActivityService.GetLogWorkSpaceAsync`.')),
     "total": zod_1.default.number()
 });
 /**
@@ -312,7 +312,7 @@ exports.blockSetsGetBlockSetsResponseItem = zod_1.default.object({
                 "sticky": zod_1.default.boolean(),
                 "type": zod_1.default.enum(['Single', 'List', 'Dictionary']),
                 "virtual": zod_1.default.boolean()
-            })),
+            }).describe('Model for an input pin on a block port. Mirrors the live\r\n`SmartSpace.App.Data.Entities.InputPinInterface` shape but exposes the\r\nparsed JSON payloads (`Metadata`, `Schema`, `Generics`,\r\n`Default`) rather than the raw `*Json` columns.')),
             "isFunction": zod_1.default.boolean(),
             "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
             "outputs": zod_1.default.record(zod_1.default.string(), zod_1.default.object({
@@ -325,9 +325,9 @@ exports.blockSetsGetBlockSetsResponseItem = zod_1.default.object({
                 "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
                 "schema": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
                 "type": zod_1.default.enum(['Single', 'List', 'Dictionary'])
-            })),
+            }).describe('Model for an output pin on a block port. Mirrors the live\r\n`SmartSpace.App.Data.Entities.OutputPinInterface` shape but exposes the\r\nparsed JSON payloads (`Metadata`, `Schema`, `Generics`)\r\nrather than the raw `*Json` columns.')),
             "type": zod_1.default.enum(['Single', 'List', 'Dictionary'])
-        })),
+        }).describe('Model for a block `PortInterface`. Inputs and Outputs are keyed by pin\r\nname (entities store them as `List<...>` with a `Key`\r\ncolumn; the model exposes them as dictionaries to match the API shape).')),
         "scopes": zod_1.default.array(zod_1.default.enum(['WorkSpace', 'DataSet'])).nullish(),
         "state": zod_1.default.record(zod_1.default.string(), zod_1.default.object({
             "default": zod_1.default.any().nullish(),
@@ -336,8 +336,8 @@ exports.blockSetsGetBlockSetsResponseItem = zod_1.default.object({
                 "pin": zod_1.default.string(),
                 "port": zod_1.default.string()
             }))
-        }))
-    }))),
+        }).describe('Model for a block `StateInterface` — a piece of state declared by a\r\nblock interface, with a JSON default value and an optional pin-ref scope.'))
+    }).describe('Model for a block interface — the schema that describes a single\r\n(name, version) pair of a block (ports, state, scope). Collides on the\r\nsimple name with `SmartSpace.App.Data.Entities.BlockInterface`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. `Name` and `Version` live on the entity but are surfaced\r\nhere too so the wire shape is self-describing (the same model travels via\r\nSignalR debug payloads where the keys are stripped).'))),
     "connectionId": zod_1.default.string().nullish(),
     "createdByUserId": zod_1.default.string().nullish(),
     "id": zod_1.default.string().regex(exports.blockSetsGetBlockSetsResponseIdRegExp),
@@ -348,8 +348,8 @@ exports.blockSetsGetBlockSetsResponseItem = zod_1.default.object({
     "usedInWorkspaces": zod_1.default.array(zod_1.default.object({
         "id": zod_1.default.string().regex(exports.blockSetsGetBlockSetsResponseUsedInWorkspacesItemIdRegExp),
         "name": zod_1.default.string()
-    }))
-});
+    }).describe('A workspace that references one of the block set\'s blocks in its active\r\nflow definition. Carries the id so the UI can deep-link to the workspace\r\ndesigner (e.g. to detach a block before deleting its set).'))
+}).describe('Model for a `BlockSet` — a versioned collection of block interfaces.\r\nCollides on the simple name with `SmartSpace.App.Data.Entities.BlockSet`;\r\nalias `DataEntities = SmartSpace.App.Data.Entities` in files that\r\nimport both. `BlockInterfaces` is keyed by block name then version to\r\nmatch the API shape consumers expect.');
 exports.blockSetsGetBlockSetsResponse = zod_1.default.array(exports.blockSetsGetBlockSetsResponseItem);
 /**
  * @summary Get the saved Python source code for a deployed custom block set.
@@ -418,7 +418,7 @@ exports.blocksGetBlocksResponse = zod_1.default.record(zod_1.default.string(), z
                 "sticky": zod_1.default.boolean(),
                 "type": zod_1.default.enum(['Single', 'List', 'Dictionary']),
                 "virtual": zod_1.default.boolean()
-            })),
+            }).describe('Model for an input pin on a block port. Mirrors the live\r\n`SmartSpace.App.Data.Entities.InputPinInterface` shape but exposes the\r\nparsed JSON payloads (`Metadata`, `Schema`, `Generics`,\r\n`Default`) rather than the raw `*Json` columns.')),
             "isFunction": zod_1.default.boolean(),
             "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
             "outputs": zod_1.default.record(zod_1.default.string(), zod_1.default.object({
@@ -431,9 +431,9 @@ exports.blocksGetBlocksResponse = zod_1.default.record(zod_1.default.string(), z
                 "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
                 "schema": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
                 "type": zod_1.default.enum(['Single', 'List', 'Dictionary'])
-            })),
+            }).describe('Model for an output pin on a block port. Mirrors the live\r\n`SmartSpace.App.Data.Entities.OutputPinInterface` shape but exposes the\r\nparsed JSON payloads (`Metadata`, `Schema`, `Generics`)\r\nrather than the raw `*Json` columns.')),
             "type": zod_1.default.enum(['Single', 'List', 'Dictionary'])
-        })),
+        }).describe('Model for a block `PortInterface`. Inputs and Outputs are keyed by pin\r\nname (entities store them as `List<...>` with a `Key`\r\ncolumn; the model exposes them as dictionaries to match the API shape).')),
         "scopes": zod_1.default.array(zod_1.default.enum(['WorkSpace', 'DataSet'])).nullish(),
         "state": zod_1.default.record(zod_1.default.string(), zod_1.default.object({
             "default": zod_1.default.any().nullish(),
@@ -442,13 +442,13 @@ exports.blocksGetBlocksResponse = zod_1.default.record(zod_1.default.string(), z
                 "pin": zod_1.default.string(),
                 "port": zod_1.default.string()
             }))
-        }))
-    }),
+        }).describe('Model for a block `StateInterface` — a piece of state declared by a\r\nblock interface, with a JSON default value and an optional pin-ref scope.'))
+    }).describe('Model for a block interface — the schema that describes a single\r\n(name, version) pair of a block (ports, state, scope). Collides on the\r\nsimple name with `SmartSpace.App.Data.Entities.BlockInterface`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. `Name` and `Version` live on the entity but are surfaced\r\nhere too so the wire shape is self-describing (the same model travels via\r\nSignalR debug payloads where the keys are stripped).'),
     "name": zod_1.default.string(),
     "sourceCodeUrl": zod_1.default.string().nullish(),
     "type": zod_1.default.enum(['Native', 'Custom', 'Debug']),
     "version": zod_1.default.string()
-})));
+}).describe('Flattened block descriptor — one `BlockInfo` per (name, version) pair\r\nacross every visible `BlockSet`. This is the shape the\r\n`BlocksController` returns; the dictionary-of-dictionaries layout is\r\nreconstructed by the service from the underlying interfaces.')));
 /**
  * @summary List the SDK's built-in blocks (smartspace.* modules) for the
 custom-blocks draft picker. App-native blocks (LLMs etc.) are
@@ -637,11 +637,11 @@ exports.dataSetsGetResponse = zod_1.default.object({
             "description": zod_1.default.string().nullish(),
             "isVector": zod_1.default.boolean(),
             "name": zod_1.default.string()
-        })),
+        }).describe('Model for a property on a DataSet — a named, optionally-vectorised field\r\nstored on each ingested item. Read-only at the model boundary; writes go\r\nthrough SmartSpace.App.Business.Models.DataSets.UpsertDataSetProperty.')),
         "scopingMode": zod_1.default.enum(['Unrestricted', 'PerSubject']),
         "subjectPath": zod_1.default.string().nullish(),
         "version": zod_1.default.string().regex(exports.dataSetsGetResponseDataItemVersionRegExp).nullish()
-    })),
+    }).describe('Model for a DataSet. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSet`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth.\r\n            \r\nThe nested Flow shape on the legacy `SmartSpace.App.Business.Models.DataSet`\r\nis intentionally dropped here — `FlowId` only. The Flow domain\r\nhasn\'t migrated yet and projecting its recursive structure (Flow →\r\nTriggers → DataSourceContainer → DataSource, Flow → ActiveFlowDefinition\r\n→ Inputs) into the model layer would couple two unmigrated domains and\r\nbloat every DataSet read with multiple JOIN fan-outs. Callers that need\r\nFlow detail fetch it via `IFlowService`.')),
     "total": zod_1.default.number()
 });
 exports.dataSetsGetItemPathDataSetIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
@@ -696,11 +696,11 @@ exports.dataSetsGetByIdResponse = zod_1.default.object({
         "description": zod_1.default.string().nullish(),
         "isVector": zod_1.default.boolean(),
         "name": zod_1.default.string()
-    })),
+    }).describe('Model for a property on a DataSet — a named, optionally-vectorised field\r\nstored on each ingested item. Read-only at the model boundary; writes go\r\nthrough SmartSpace.App.Business.Models.DataSets.UpsertDataSetProperty.')),
     "scopingMode": zod_1.default.enum(['Unrestricted', 'PerSubject']),
     "subjectPath": zod_1.default.string().nullish(),
     "version": zod_1.default.string().regex(exports.dataSetsGetByIdResponseVersionRegExp).nullish()
-});
+}).describe('Model for a DataSet. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSet`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth.\r\n            \r\nThe nested Flow shape on the legacy `SmartSpace.App.Business.Models.DataSet`\r\nis intentionally dropped here — `FlowId` only. The Flow domain\r\nhasn\'t migrated yet and projecting its recursive structure (Flow →\r\nTriggers → DataSourceContainer → DataSource, Flow → ActiveFlowDefinition\r\n→ Inputs) into the model layer would couple two unmigrated domains and\r\nbloat every DataSet read with multiple JOIN fan-outs. Callers that need\r\nFlow detail fetch it via `IFlowService`.');
 /**
  * @summary Update an existing dataset (name, description, container bindings).
  */
@@ -718,11 +718,11 @@ exports.dataSetsPutBody = zod_1.default.strictObject({
             "value": zod_1.default.string()
         })).nullish(),
         "path": zod_1.default.string()
-    })).nullish(),
+    }).describe('Container reference used in create/update requests — pair of\r\n`DataSourceId` and a `Path` identifying a specific container\r\ninside that data source. The service hashes the pair to produce the\r\ncontainer id. Optional Filters restrict which records are synced.')).nullish(),
     "description": zod_1.default.string().nullish(),
     "id": zod_1.default.string().regex(exports.dataSetsPutBodyIdRegExp),
     "name": zod_1.default.string().nullish()
-});
+}).describe('Update-request shape for a DataSet — name/description plus optional\r\nre-binding of containers. Container info null = leave the existing\r\nflow alone, just update basic fields; empty = disconnect every\r\ncontainer (soft-deletes all flow triggers).');
 exports.dataSetsPutResponseDataSpaceIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSetsPutResponseFlowIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSetsPutResponseIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
@@ -741,11 +741,11 @@ exports.dataSetsPutResponse = zod_1.default.object({
         "description": zod_1.default.string().nullish(),
         "isVector": zod_1.default.boolean(),
         "name": zod_1.default.string()
-    })),
+    }).describe('Model for a property on a DataSet — a named, optionally-vectorised field\r\nstored on each ingested item. Read-only at the model boundary; writes go\r\nthrough SmartSpace.App.Business.Models.DataSets.UpsertDataSetProperty.')),
     "scopingMode": zod_1.default.enum(['Unrestricted', 'PerSubject']),
     "subjectPath": zod_1.default.string().nullish(),
     "version": zod_1.default.string().regex(exports.dataSetsPutResponseVersionRegExp).nullish()
-});
+}).describe('Model for a DataSet. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSet`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth.\r\n            \r\nThe nested Flow shape on the legacy `SmartSpace.App.Business.Models.DataSet`\r\nis intentionally dropped here — `FlowId` only. The Flow domain\r\nhasn\'t migrated yet and projecting its recursive structure (Flow →\r\nTriggers → DataSourceContainer → DataSource, Flow → ActiveFlowDefinition\r\n→ Inputs) into the model layer would couple two unmigrated domains and\r\nbloat every DataSet read with multiple JOIN fan-outs. Callers that need\r\nFlow detail fetch it via `IFlowService`.');
 /**
  * @summary Update just the basic-info fields (name + description) on a dataset.
  */
@@ -756,7 +756,7 @@ exports.dataSetsPutBasicInfoParams = zod_1.default.strictObject({
 exports.dataSetsPutBasicInfoBody = zod_1.default.strictObject({
     "description": zod_1.default.string().nullish(),
     "name": zod_1.default.string()
-});
+}).describe('Lightweight update for just the editable basic-info fields. Used by the\r\n`PUT /DataSets/{id}/basicInfo` endpoint.');
 exports.dataSetsClearPathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSetsClearParams = zod_1.default.strictObject({
     "id": zod_1.default.string().regex(exports.dataSetsClearPathIdRegExp)
@@ -824,11 +824,11 @@ exports.dataSetsSetDataspaceResponse = zod_1.default.object({
         "description": zod_1.default.string().nullish(),
         "isVector": zod_1.default.boolean(),
         "name": zod_1.default.string()
-    })),
+    }).describe('Model for a property on a DataSet — a named, optionally-vectorised field\r\nstored on each ingested item. Read-only at the model boundary; writes go\r\nthrough SmartSpace.App.Business.Models.DataSets.UpsertDataSetProperty.')),
     "scopingMode": zod_1.default.enum(['Unrestricted', 'PerSubject']),
     "subjectPath": zod_1.default.string().nullish(),
     "version": zod_1.default.string().regex(exports.dataSetsSetDataspaceResponseVersionRegExp).nullish()
-});
+}).describe('Model for a DataSet. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSet`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth.\r\n            \r\nThe nested Flow shape on the legacy `SmartSpace.App.Business.Models.DataSet`\r\nis intentionally dropped here — `FlowId` only. The Flow domain\r\nhasn\'t migrated yet and projecting its recursive structure (Flow →\r\nTriggers → DataSourceContainer → DataSource, Flow → ActiveFlowDefinition\r\n→ Inputs) into the model layer would couple two unmigrated domains and\r\nbloat every DataSet read with multiple JOIN fan-outs. Callers that need\r\nFlow detail fetch it via `IFlowService`.');
 exports.dataSetsExportPathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSetsExportParams = zod_1.default.strictObject({
     "id": zod_1.default.string().regex(exports.dataSetsExportPathIdRegExp)
@@ -846,7 +846,7 @@ exports.dataSetsExportResponse = zod_1.default.object({
     "size": zod_1.default.number(),
     "threadId": zod_1.default.string().regex(exports.dataSetsExportResponseThreadIdRegExp).nullish(),
     "workspaceId": zod_1.default.string().regex(exports.dataSetsExportResponseWorkspaceIdRegExp).nullish()
-});
+}).describe('Model for a stored file blob. The simple name collides with\r\n`System.IO.File` and `SmartSpace.App.Data.Entities.FileEntity`\r\n(which is itself named to side-step the BCL collision); the\r\n`SmartSpace.App.Business.Models.Files` namespace disambiguates. When\r\nimporting both this model and the entity, alias the entity side:\r\n```using DataEntities = SmartSpace.App.Data.Entities;```\n`ThreadId` reflects the entity column `MessageThreadId`\r\n(renamed at the model boundary because the API contract has always called\r\nit `threadId`). `WorkspaceId` keeps the lower-s spelling that\r\nmatches the entity column and is already on the wire.');
 exports.dataSetsGetItemsPathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSetsGetItemsParams = zod_1.default.strictObject({
     "id": zod_1.default.string().regex(exports.dataSetsGetItemsPathIdRegExp)
@@ -946,14 +946,14 @@ exports.dataSetsAddDataSetPropertyParams = zod_1.default.strictObject({
 });
 exports.dataSetsAddDataSetPropertyBody = zod_1.default.strictObject({
     "description": zod_1.default.string().nullish(),
-    "isVector": zod_1.default.boolean().nullish(),
+    "isVector": zod_1.default.boolean().nullish().describe('Unused — the platform no longer reads this field and\r\n            it has no effect on ingestion or querying. It is retained as an optional\r\n            property purely for backward compatibility (see the description of\r\n            `POST /DataSets/{id}/properties`); omit it in new integrations.\r\n            When omitted, the stored value is preserved on update and defaults to\r\n            `false` on create.'),
     "name": zod_1.default.string()
-});
+}).describe('Upsert payload for a single DataSet property. `Name` is the key —\r\nexisting property with the same name is updated in place, otherwise a\r\nnew one is added.');
 exports.dataSetsAddDataSetPropertyResponse = zod_1.default.object({
     "description": zod_1.default.string().nullish(),
     "isVector": zod_1.default.boolean(),
     "name": zod_1.default.string()
-});
+}).describe('Model for a property on a DataSet — a named, optionally-vectorised field\r\nstored on each ingested item. Read-only at the model boundary; writes go\r\nthrough SmartSpace.App.Business.Models.DataSets.UpsertDataSetProperty.');
 exports.dataSetsDeleteDataSetPropertyPathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSetsDeleteDataSetPropertyParams = zod_1.default.strictObject({
     "id": zod_1.default.string().regex(exports.dataSetsDeleteDataSetPropertyPathIdRegExp),
@@ -1023,7 +1023,7 @@ exports.dataSetsPutScopingParams = zod_1.default.strictObject({
 exports.dataSetsPutScopingBody = zod_1.default.strictObject({
     "mode": zod_1.default.enum(['Unrestricted', 'PerSubject']),
     "subjectPath": zod_1.default.string().nullish()
-});
+}).describe('Sets the per-document scoping config on a dataset (intelligence-layer\r\n`scoping` block). When `Mode` is `Unrestricted` the\r\n`SubjectPath` is cleared; when `PerSubject`, `SubjectPath`\r\nselects the document field to match (null = the built-in owner envelope).');
 /**
  * @summary Fetch a list of all available data source types in SmartSpace.
  */
@@ -1035,7 +1035,7 @@ exports.dataSourceTypesGetResponseItem = zod_1.default.object({
             "key": zod_1.default.string(),
             "type": zod_1.default.enum(['String', 'Int', 'Bool'])
         }))
-    }),
+    }).describe('Schema metadata describing the *shape* of credentials a connector type\r\nrequires — not credential values. Exempted from\r\n`ModelFolderSafetyTests` via `LegitimateSchemaExceptions`.'),
     "defaultSyncIntervalMinutes": zod_1.default.number().nullish(),
     "id": zod_1.default.string(),
     "name": zod_1.default.string()
@@ -1047,7 +1047,7 @@ exports.dataSourceTypesGetResponse = zod_1.default.array(exports.dataSourceTypes
 exports.dataSourceTypesGetAvailableContainersBody = zod_1.default.strictObject({
     "credentials": zod_1.default.record(zod_1.default.string(), zod_1.default.string()),
     "dataSourceTypeId": zod_1.default.string()
-});
+}).describe('Request shape for the test-connection endpoint and an internal carrier\r\nfor the data-source-type service when probing credentials. Contains an\r\ninline credentials dictionary — listed under\r\n`ModelFolderSafetyTests.ExistingDebtToReview`; redesign to a\r\nKeyVault-ref-only payload is tracked in TODO.md.');
 exports.dataSourceTypesGetAvailableContainersResponseItem = zod_1.default.object({
     "children": zod_1.default.array(zod_1.default.any()).nullish(),
     "filters": zod_1.default.array(zod_1.default.object({
@@ -1069,7 +1069,7 @@ exports.dataSourceTypesGetAvailableContainersResponse = zod_1.default.array(expo
 exports.dataSourceTypesTestConnectionBody = zod_1.default.strictObject({
     "credentials": zod_1.default.record(zod_1.default.string(), zod_1.default.string()),
     "dataSourceTypeId": zod_1.default.string()
-});
+}).describe('Request shape for the test-connection endpoint and an internal carrier\r\nfor the data-source-type service when probing credentials. Contains an\r\ninline credentials dictionary — listed under\r\n`ModelFolderSafetyTests.ExistingDebtToReview`; redesign to a\r\nKeyVault-ref-only payload is tracked in TODO.md.');
 exports.dataSourceTypesTestConnectionResponse = zod_1.default.object({
     "exceptionType": zod_1.default.string().nullish(),
     "isSuccessful": zod_1.default.boolean(),
@@ -1113,7 +1113,7 @@ exports.dataSourcesGetResponse = zod_1.default.object({
         "modifiedByUserId": zod_1.default.string().nullish(),
         "name": zod_1.default.string(),
         "searchable": zod_1.default.boolean()
-    })),
+    }).describe('Full read shape for a DataSource. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSource`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth.')),
     "total": zod_1.default.number()
 });
 /**
@@ -1124,7 +1124,7 @@ exports.dataSourcesPostBody = zod_1.default.strictObject({
     "credentials": zod_1.default.record(zod_1.default.string(), zod_1.default.string()),
     "keyId": zod_1.default.string().nullish(),
     "name": zod_1.default.string()
-});
+}).describe('Create request shape — paired with SmartSpace.App.Business.Models.DataSources.UpdateDataSource even\r\nthough field overlap is partial; the `[Required]` contract differs.\r\nAccepts inline credentials at creation time (listed under\r\n`ModelFolderSafetyTests.ExistingDebtToReview`).');
 exports.dataSourcesPostResponseContainersItemDataSourceIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSourcesPostResponseContainersItemIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSourcesPostResponseIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
@@ -1149,7 +1149,7 @@ exports.dataSourcesPostResponse = zod_1.default.object({
     "modifiedByUserId": zod_1.default.string().nullish(),
     "name": zod_1.default.string(),
     "searchable": zod_1.default.boolean()
-});
+}).describe('Full read shape for a DataSource. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSource`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth.');
 /**
  * @summary Remove a specific data source from SmartSpace using its unique ID.
  */
@@ -1233,7 +1233,7 @@ exports.dataSourcesUpdateCredentialsParams = zod_1.default.strictObject({
 });
 exports.dataSourcesUpdateCredentialsBody = zod_1.default.strictObject({
     "credentials": zod_1.default.record(zod_1.default.string(), zod_1.default.string().nullable())
-});
+}).describe('Partial-update payload for connector credentials — only non-empty\r\nvalues overwrite the existing entries (see\r\n`DataSourceService.UpdateCredentialsAsync`). Listed under\r\n`ModelFolderSafetyTests.ExistingDebtToReview`.');
 /**
  * @summary Requests an on-demand sync of a data source. The request is queued;
 the sync service picks it up within ~30 seconds. Repeated requests
@@ -1250,7 +1250,7 @@ exports.dataSourcesGetAdminUsersParams = zod_1.default.strictObject({
 exports.dataSourcesGetAdminUsersResponseItem = zod_1.default.object({
     "id": zod_1.default.string(),
     "name": zod_1.default.string()
-});
+}).describe('API response shape for \"list admin users on a DataSource\" — joins the\r\njunction SmartSpace.App.Business.Models.DataSources.DataSourceAdmin with the user-service principal\r\nto surface a display name. Composed in the service; not a Mapperly\r\nprojection target (the join crosses an external service boundary).');
 exports.dataSourcesGetAdminUsersResponse = zod_1.default.array(exports.dataSourcesGetAdminUsersResponseItem);
 exports.dataSourcesDeleteAdminPathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSourcesDeleteAdminParams = zod_1.default.strictObject({
@@ -1296,11 +1296,11 @@ exports.dataSpacesGetResponse = zod_1.default.object({
                 "description": zod_1.default.string().nullish(),
                 "isVector": zod_1.default.boolean(),
                 "name": zod_1.default.string()
-            })),
+            }).describe('Model for a property on a DataSet — a named, optionally-vectorised field\r\nstored on each ingested item. Read-only at the model boundary; writes go\r\nthrough SmartSpace.App.Business.Models.DataSets.UpsertDataSetProperty.')),
             "scopingMode": zod_1.default.enum(['Unrestricted', 'PerSubject']),
             "subjectPath": zod_1.default.string().nullish(),
             "version": zod_1.default.string().regex(exports.dataSpacesGetResponseDataItemDataSetsItemVersionRegExp).nullish()
-        })),
+        }).describe('Model for a DataSet. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSet`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth.\r\n            \r\nThe nested Flow shape on the legacy `SmartSpace.App.Business.Models.DataSet`\r\nis intentionally dropped here — `FlowId` only. The Flow domain\r\nhasn\'t migrated yet and projecting its recursive structure (Flow →\r\nTriggers → DataSourceContainer → DataSource, Flow → ActiveFlowDefinition\r\n→ Inputs) into the model layer would couple two unmigrated domains and\r\nbloat every DataSet read with multiple JOIN fan-outs. Callers that need\r\nFlow detail fetch it via `IFlowService`.')),
         "id": zod_1.default.string().regex(exports.dataSpacesGetResponseDataItemIdRegExp),
         "modifiedAt": zod_1.default.iso.datetime({}),
         "modifiedByUserId": zod_1.default.string(),
@@ -1309,8 +1309,8 @@ exports.dataSpacesGetResponse = zod_1.default.object({
         "workSpaces": zod_1.default.array(zod_1.default.object({
             "id": zod_1.default.string().regex(exports.dataSpacesGetResponseDataItemWorkSpacesItemIdRegExp),
             "name": zod_1.default.string()
-        }))
-    })),
+        }).describe('Lightweight reference to a WorkSpace that uses this DataSpace. Avoids\r\npulling the full WorkSpace shape (admins, flows, configurations) when a\r\ncaller only needs to surface \"what workspaces reference this DataSpace\".'))
+    }).describe('Model for a DataSpace. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSpace`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. The fully-qualified `DataSets.DataSet` below also\r\ndisambiguates from the legacy unmigrated `Business.Models.DataSet`\r\n— implicit name resolution prefers the ancestor namespace and would\r\notherwise pick up the legacy record.')),
     "total": zod_1.default.number()
 });
 /**
@@ -1320,7 +1320,7 @@ exports.dataSpacesPostBodyDataSetIdsItemRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-
 exports.dataSpacesPostBody = zod_1.default.strictObject({
     "dataSetIds": zod_1.default.array(zod_1.default.string().regex(exports.dataSpacesPostBodyDataSetIdsItemRegExp)).nullish(),
     "name": zod_1.default.string()
-});
+}).describe('Create-request shape for a DataSpace. `DataSetIds` is an optional\r\npre-attachment of existing datasets to the new dataspace; the creating\r\nprincipal is implicitly added as the first admin.');
 exports.dataSpacesDeletePathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSpacesDeleteParams = zod_1.default.strictObject({
     "id": zod_1.default.string().regex(exports.dataSpacesDeletePathIdRegExp)
@@ -1353,11 +1353,11 @@ exports.dataSpacesGetByIdResponse = zod_1.default.object({
             "description": zod_1.default.string().nullish(),
             "isVector": zod_1.default.boolean(),
             "name": zod_1.default.string()
-        })),
+        }).describe('Model for a property on a DataSet — a named, optionally-vectorised field\r\nstored on each ingested item. Read-only at the model boundary; writes go\r\nthrough SmartSpace.App.Business.Models.DataSets.UpsertDataSetProperty.')),
         "scopingMode": zod_1.default.enum(['Unrestricted', 'PerSubject']),
         "subjectPath": zod_1.default.string().nullish(),
         "version": zod_1.default.string().regex(exports.dataSpacesGetByIdResponseDataSetsItemVersionRegExp).nullish()
-    })),
+    }).describe('Model for a DataSet. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSet`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth.\r\n            \r\nThe nested Flow shape on the legacy `SmartSpace.App.Business.Models.DataSet`\r\nis intentionally dropped here — `FlowId` only. The Flow domain\r\nhasn\'t migrated yet and projecting its recursive structure (Flow →\r\nTriggers → DataSourceContainer → DataSource, Flow → ActiveFlowDefinition\r\n→ Inputs) into the model layer would couple two unmigrated domains and\r\nbloat every DataSet read with multiple JOIN fan-outs. Callers that need\r\nFlow detail fetch it via `IFlowService`.')),
     "id": zod_1.default.string().regex(exports.dataSpacesGetByIdResponseIdRegExp),
     "modifiedAt": zod_1.default.iso.datetime({}),
     "modifiedByUserId": zod_1.default.string(),
@@ -1366,8 +1366,8 @@ exports.dataSpacesGetByIdResponse = zod_1.default.object({
     "workSpaces": zod_1.default.array(zod_1.default.object({
         "id": zod_1.default.string().regex(exports.dataSpacesGetByIdResponseWorkSpacesItemIdRegExp),
         "name": zod_1.default.string()
-    }))
-});
+    }).describe('Lightweight reference to a WorkSpace that uses this DataSpace. Avoids\r\npulling the full WorkSpace shape (admins, flows, configurations) when a\r\ncaller only needs to surface \"what workspaces reference this DataSpace\".'))
+}).describe('Model for a DataSpace. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSpace`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. The fully-qualified `DataSets.DataSet` below also\r\ndisambiguates from the legacy unmigrated `Business.Models.DataSet`\r\n— implicit name resolution prefers the ancestor namespace and would\r\notherwise pick up the legacy record.');
 /**
  * @summary Update an existing dataspace.
  */
@@ -1381,7 +1381,7 @@ exports.dataSpacesPutBody = zod_1.default.strictObject({
     "dataSetIds": zod_1.default.array(zod_1.default.string().regex(exports.dataSpacesPutBodyDataSetIdsItemRegExp)),
     "id": zod_1.default.string().regex(exports.dataSpacesPutBodyIdRegExp),
     "name": zod_1.default.string()
-});
+}).describe('Update-request shape for a DataSpace — rename and re-bind the attached\r\ndatasets. The complete `DataSetIds` list is treated as the desired\r\nstate; datasets present today but missing here are unbound, new ones\r\nare bound in.');
 exports.dataSpacesPutResponseDataSetsItemDataSpaceIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSpacesPutResponseDataSetsItemFlowIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSpacesPutResponseDataSetsItemIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
@@ -1406,11 +1406,11 @@ exports.dataSpacesPutResponse = zod_1.default.object({
             "description": zod_1.default.string().nullish(),
             "isVector": zod_1.default.boolean(),
             "name": zod_1.default.string()
-        })),
+        }).describe('Model for a property on a DataSet — a named, optionally-vectorised field\r\nstored on each ingested item. Read-only at the model boundary; writes go\r\nthrough SmartSpace.App.Business.Models.DataSets.UpsertDataSetProperty.')),
         "scopingMode": zod_1.default.enum(['Unrestricted', 'PerSubject']),
         "subjectPath": zod_1.default.string().nullish(),
         "version": zod_1.default.string().regex(exports.dataSpacesPutResponseDataSetsItemVersionRegExp).nullish()
-    })),
+    }).describe('Model for a DataSet. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSet`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth.\r\n            \r\nThe nested Flow shape on the legacy `SmartSpace.App.Business.Models.DataSet`\r\nis intentionally dropped here — `FlowId` only. The Flow domain\r\nhasn\'t migrated yet and projecting its recursive structure (Flow →\r\nTriggers → DataSourceContainer → DataSource, Flow → ActiveFlowDefinition\r\n→ Inputs) into the model layer would couple two unmigrated domains and\r\nbloat every DataSet read with multiple JOIN fan-outs. Callers that need\r\nFlow detail fetch it via `IFlowService`.')),
     "id": zod_1.default.string().regex(exports.dataSpacesPutResponseIdRegExp),
     "modifiedAt": zod_1.default.iso.datetime({}),
     "modifiedByUserId": zod_1.default.string(),
@@ -1419,8 +1419,8 @@ exports.dataSpacesPutResponse = zod_1.default.object({
     "workSpaces": zod_1.default.array(zod_1.default.object({
         "id": zod_1.default.string().regex(exports.dataSpacesPutResponseWorkSpacesItemIdRegExp),
         "name": zod_1.default.string()
-    }))
-});
+    }).describe('Lightweight reference to a WorkSpace that uses this DataSpace. Avoids\r\npulling the full WorkSpace shape (admins, flows, configurations) when a\r\ncaller only needs to surface \"what workspaces reference this DataSpace\".'))
+}).describe('Model for a DataSpace. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSpace`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. The fully-qualified `DataSets.DataSet` below also\r\ndisambiguates from the legacy unmigrated `Business.Models.DataSet`\r\n— implicit name resolution prefers the ancestor namespace and would\r\notherwise pick up the legacy record.');
 exports.dataSpacesGetAdminUsersPathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSpacesGetAdminUsersParams = zod_1.default.strictObject({
     "id": zod_1.default.string().regex(exports.dataSpacesGetAdminUsersPathIdRegExp)
@@ -1428,9 +1428,9 @@ exports.dataSpacesGetAdminUsersParams = zod_1.default.strictObject({
 exports.dataSpacesGetAdminUsersResponseDataSpaceIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSpacesGetAdminUsersResponseItem = zod_1.default.object({
     "dataSpaceId": zod_1.default.string().regex(exports.dataSpacesGetAdminUsersResponseDataSpaceIdRegExp),
-    "displayName": zod_1.default.string(),
+    "displayName": zod_1.default.string().describe('Display name resolved from `IUserService.GetPrincipalsByIdsAsync`\r\nafter projection. Empty string when the principal lookup misses.'),
     "userId": zod_1.default.string()
-});
+}).describe('Model for a DataSpace admin junction record. The composite key is\r\n(UserId, DataSpaceId) — no surrogate id. Junction entities follow the\r\ndelete+create convention, so there is no `UpdateDataSpaceAdmin`.\r\n            \r\n`DisplayName` is filled by the service via `IUserService`\r\npost-projection — it isn\'t on the entity and can\'t be projected, so it\r\nhangs off the record as an `init`-only property rather than a\r\nconstructor parameter.');
 exports.dataSpacesGetAdminUsersResponse = zod_1.default.array(exports.dataSpacesGetAdminUsersResponseItem);
 exports.dataSpacesDeleteAdminPathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.dataSpacesDeleteAdminParams = zod_1.default.strictObject({
@@ -1472,11 +1472,11 @@ exports.dataSpacesGetDataSetsResponse = zod_1.default.object({
             "description": zod_1.default.string().nullish(),
             "isVector": zod_1.default.boolean(),
             "name": zod_1.default.string()
-        })),
+        }).describe('Model for a property on a DataSet — a named, optionally-vectorised field\r\nstored on each ingested item. Read-only at the model boundary; writes go\r\nthrough SmartSpace.App.Business.Models.DataSets.UpsertDataSetProperty.')),
         "scopingMode": zod_1.default.enum(['Unrestricted', 'PerSubject']),
         "subjectPath": zod_1.default.string().nullish(),
         "version": zod_1.default.string().regex(exports.dataSpacesGetDataSetsResponseDataItemVersionRegExp).nullish()
-    })),
+    }).describe('Model for a DataSet. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.DataSet`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth.\r\n            \r\nThe nested Flow shape on the legacy `SmartSpace.App.Business.Models.DataSet`\r\nis intentionally dropped here — `FlowId` only. The Flow domain\r\nhasn\'t migrated yet and projecting its recursive structure (Flow →\r\nTriggers → DataSourceContainer → DataSource, Flow → ActiveFlowDefinition\r\n→ Inputs) into the model layer would couple two unmigrated domains and\r\nbloat every DataSet read with multiple JOIN fan-outs. Callers that need\r\nFlow detail fetch it via `IFlowService`.')),
     "total": zod_1.default.number()
 });
 /**
@@ -1496,10 +1496,10 @@ exports.dataSpacesPostDatasetBody = zod_1.default.strictObject({
             "value": zod_1.default.string()
         })).nullish(),
         "path": zod_1.default.string()
-    })).nullish(),
+    }).describe('Container reference used in create/update requests — pair of\r\n`DataSourceId` and a `Path` identifying a specific container\r\ninside that data source. The service hashes the pair to produce the\r\ncontainer id. Optional Filters restrict which records are synced.')).nullish(),
     "description": zod_1.default.string().nullish(),
     "name": zod_1.default.string()
-});
+}).describe('Create-request shape for a DataSet. The DataSpace it belongs to is\r\ncarried on the route (`/DataSpaces/{id}/datasets`) rather than the\r\nbody. Container info is optional — empty list means \"file-only\" dataset\r\nwith a freshly-created file ingestion flow.');
 exports.debugInvokeParams = zod_1.default.strictObject({
     "connectionId": zod_1.default.string(),
     "method": zod_1.default.string()
@@ -1526,7 +1526,7 @@ exports.draftsListDraftsResponseItem = zod_1.default.object({
                 "sticky": zod_1.default.boolean(),
                 "type": zod_1.default.enum(['Single', 'List', 'Dictionary']),
                 "virtual": zod_1.default.boolean()
-            })),
+            }).describe('Model for an input pin on a block port. Mirrors the live\r\n`SmartSpace.App.Data.Entities.InputPinInterface` shape but exposes the\r\nparsed JSON payloads (`Metadata`, `Schema`, `Generics`,\r\n`Default`) rather than the raw `*Json` columns.')),
             "isFunction": zod_1.default.boolean(),
             "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
             "outputs": zod_1.default.record(zod_1.default.string(), zod_1.default.object({
@@ -1539,9 +1539,9 @@ exports.draftsListDraftsResponseItem = zod_1.default.object({
                 "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
                 "schema": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
                 "type": zod_1.default.enum(['Single', 'List', 'Dictionary'])
-            })),
+            }).describe('Model for an output pin on a block port. Mirrors the live\r\n`SmartSpace.App.Data.Entities.OutputPinInterface` shape but exposes the\r\nparsed JSON payloads (`Metadata`, `Schema`, `Generics`)\r\nrather than the raw `*Json` columns.')),
             "type": zod_1.default.enum(['Single', 'List', 'Dictionary'])
-        })),
+        }).describe('Model for a block `PortInterface`. Inputs and Outputs are keyed by pin\r\nname (entities store them as `List<...>` with a `Key`\r\ncolumn; the model exposes them as dictionaries to match the API shape).')),
         "scopes": zod_1.default.array(zod_1.default.enum(['WorkSpace', 'DataSet'])).nullish(),
         "state": zod_1.default.record(zod_1.default.string(), zod_1.default.object({
             "default": zod_1.default.any().nullish(),
@@ -1550,15 +1550,15 @@ exports.draftsListDraftsResponseItem = zod_1.default.object({
                 "pin": zod_1.default.string(),
                 "port": zod_1.default.string()
             }))
-        }))
-    }))),
+        }).describe('Model for a block `StateInterface` — a piece of state declared by a\r\nblock interface, with a JSON default value and an optional pin-ref scope.'))
+    }).describe('Model for a block interface — the schema that describes a single\r\n(name, version) pair of a block (ports, state, scope). Collides on the\r\nsimple name with `SmartSpace.App.Data.Entities.BlockInterface`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. `Name` and `Version` live on the entity but are surfaced\r\nhere too so the wire shape is self-describing (the same model travels via\r\nSignalR debug payloads where the keys are stripped).'))),
     "isActive": zod_1.default.boolean(),
     "modifiedAt": zod_1.default.iso.datetime({}),
     "name": zod_1.default.string(),
     "parseError": zod_1.default.string().nullish(),
     "rowVersion": zod_1.default.string(),
     "sourceText": zod_1.default.string()
-});
+}).describe('A browser-authored Draft Custom block — a `BlockSet` row with\r\n`IsDraft = true`, scoped to one user. See `ADR-0002` for the\r\nresolution rule that decides when the owner\'s draft wins over a published\r\nCustom at the same `(name, version)`.');
 exports.draftsListDraftsResponse = zod_1.default.array(exports.draftsListDraftsResponseItem);
 /**
  * @summary Delete a draft (row + blob). Does not touch any published Custom of the same name.
@@ -1589,7 +1589,7 @@ exports.draftsGetDraftResponse = zod_1.default.object({
                 "sticky": zod_1.default.boolean(),
                 "type": zod_1.default.enum(['Single', 'List', 'Dictionary']),
                 "virtual": zod_1.default.boolean()
-            })),
+            }).describe('Model for an input pin on a block port. Mirrors the live\r\n`SmartSpace.App.Data.Entities.InputPinInterface` shape but exposes the\r\nparsed JSON payloads (`Metadata`, `Schema`, `Generics`,\r\n`Default`) rather than the raw `*Json` columns.')),
             "isFunction": zod_1.default.boolean(),
             "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
             "outputs": zod_1.default.record(zod_1.default.string(), zod_1.default.object({
@@ -1602,9 +1602,9 @@ exports.draftsGetDraftResponse = zod_1.default.object({
                 "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
                 "schema": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
                 "type": zod_1.default.enum(['Single', 'List', 'Dictionary'])
-            })),
+            }).describe('Model for an output pin on a block port. Mirrors the live\r\n`SmartSpace.App.Data.Entities.OutputPinInterface` shape but exposes the\r\nparsed JSON payloads (`Metadata`, `Schema`, `Generics`)\r\nrather than the raw `*Json` columns.')),
             "type": zod_1.default.enum(['Single', 'List', 'Dictionary'])
-        })),
+        }).describe('Model for a block `PortInterface`. Inputs and Outputs are keyed by pin\r\nname (entities store them as `List<...>` with a `Key`\r\ncolumn; the model exposes them as dictionaries to match the API shape).')),
         "scopes": zod_1.default.array(zod_1.default.enum(['WorkSpace', 'DataSet'])).nullish(),
         "state": zod_1.default.record(zod_1.default.string(), zod_1.default.object({
             "default": zod_1.default.any().nullish(),
@@ -1613,15 +1613,15 @@ exports.draftsGetDraftResponse = zod_1.default.object({
                 "pin": zod_1.default.string(),
                 "port": zod_1.default.string()
             }))
-        }))
-    }))),
+        }).describe('Model for a block `StateInterface` — a piece of state declared by a\r\nblock interface, with a JSON default value and an optional pin-ref scope.'))
+    }).describe('Model for a block interface — the schema that describes a single\r\n(name, version) pair of a block (ports, state, scope). Collides on the\r\nsimple name with `SmartSpace.App.Data.Entities.BlockInterface`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. `Name` and `Version` live on the entity but are surfaced\r\nhere too so the wire shape is self-describing (the same model travels via\r\nSignalR debug payloads where the keys are stripped).'))),
     "isActive": zod_1.default.boolean(),
     "modifiedAt": zod_1.default.iso.datetime({}),
     "name": zod_1.default.string(),
     "parseError": zod_1.default.string().nullish(),
     "rowVersion": zod_1.default.string(),
     "sourceText": zod_1.default.string()
-});
+}).describe('A browser-authored Draft Custom block — a `BlockSet` row with\r\n`IsDraft = true`, scoped to one user. See `ADR-0002` for the\r\nresolution rule that decides when the owner\'s draft wins over a published\r\nCustom at the same `(name, version)`.');
 /**
  * @summary Toggle the draft's "Start testing" flag. See ADR-0002 — owner's active draft
 overrides the published Custom at the same `(name, version)` for them only.
@@ -1643,7 +1643,7 @@ exports.draftsSaveDraftParams = zod_1.default.strictObject({
 exports.draftsSaveDraftBody = zod_1.default.strictObject({
     "expectedRowVersion": zod_1.default.string().nullish(),
     "source": zod_1.default.string()
-});
+}).describe('Save a draft\'s source. `ExpectedRowVersion` is the value the client last saw;\r\nthe server returns 409 if the DB has moved on (eg. another tab). Null is allowed\r\nonly for first-ever creation.');
 exports.draftsSaveDraftResponse = zod_1.default.object({
     "blockInterfaces": zod_1.default.record(zod_1.default.string(), zod_1.default.record(zod_1.default.string(), zod_1.default.object({
         "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
@@ -1661,7 +1661,7 @@ exports.draftsSaveDraftResponse = zod_1.default.object({
                 "sticky": zod_1.default.boolean(),
                 "type": zod_1.default.enum(['Single', 'List', 'Dictionary']),
                 "virtual": zod_1.default.boolean()
-            })),
+            }).describe('Model for an input pin on a block port. Mirrors the live\r\n`SmartSpace.App.Data.Entities.InputPinInterface` shape but exposes the\r\nparsed JSON payloads (`Metadata`, `Schema`, `Generics`,\r\n`Default`) rather than the raw `*Json` columns.')),
             "isFunction": zod_1.default.boolean(),
             "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
             "outputs": zod_1.default.record(zod_1.default.string(), zod_1.default.object({
@@ -1674,9 +1674,9 @@ exports.draftsSaveDraftResponse = zod_1.default.object({
                 "metadata": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
                 "schema": zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
                 "type": zod_1.default.enum(['Single', 'List', 'Dictionary'])
-            })),
+            }).describe('Model for an output pin on a block port. Mirrors the live\r\n`SmartSpace.App.Data.Entities.OutputPinInterface` shape but exposes the\r\nparsed JSON payloads (`Metadata`, `Schema`, `Generics`)\r\nrather than the raw `*Json` columns.')),
             "type": zod_1.default.enum(['Single', 'List', 'Dictionary'])
-        })),
+        }).describe('Model for a block `PortInterface`. Inputs and Outputs are keyed by pin\r\nname (entities store them as `List<...>` with a `Key`\r\ncolumn; the model exposes them as dictionaries to match the API shape).')),
         "scopes": zod_1.default.array(zod_1.default.enum(['WorkSpace', 'DataSet'])).nullish(),
         "state": zod_1.default.record(zod_1.default.string(), zod_1.default.object({
             "default": zod_1.default.any().nullish(),
@@ -1685,11 +1685,11 @@ exports.draftsSaveDraftResponse = zod_1.default.object({
                 "pin": zod_1.default.string(),
                 "port": zod_1.default.string()
             }))
-        }))
-    }))),
+        }).describe('Model for a block `StateInterface` — a piece of state declared by a\r\nblock interface, with a JSON default value and an optional pin-ref scope.'))
+    }).describe('Model for a block interface — the schema that describes a single\r\n(name, version) pair of a block (ports, state, scope). Collides on the\r\nsimple name with `SmartSpace.App.Data.Entities.BlockInterface`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. `Name` and `Version` live on the entity but are surfaced\r\nhere too so the wire shape is self-describing (the same model travels via\r\nSignalR debug payloads where the keys are stripped).'))),
     "parseError": zod_1.default.string().nullish(),
     "rowVersion": zod_1.default.string()
-});
+}).describe('Response after saving a draft. `ParseError` is non-null when the source\r\nfailed to parse — the text is still persisted, but `BlockInterfaces` is\r\nempty until parse succeeds (matches the editor\'s live-preview semantics).');
 /**
  * @summary Publish the draft's saved source as a tenant-visible Custom block set.
 When a published set of the same name exists, the first call returns 409
@@ -1702,7 +1702,7 @@ exports.draftsPublishDraftParams = zod_1.default.strictObject({
 exports.draftsPublishDraftBody = zod_1.default.strictObject({
     "confirmOverwrite": zod_1.default.boolean(),
     "publishAs": zod_1.default.string().nullish()
-});
+}).describe('`ConfirmOverwrite` must be true to replace an already-published set of\r\n            the same name — the first attempt 409s with the impact details so the user\r\n            opts in deliberately (see the custom-block rework design, Phase 3).');
 exports.draftsPublishDraftResponseBlockSetIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.draftsPublishDraftResponse = zod_1.default.object({
     "blockSetId": zod_1.default.string().regex(exports.draftsPublishDraftResponseBlockSetIdRegExp),
@@ -1740,7 +1740,7 @@ exports.filesUploadFilesResponseItem = zod_1.default.object({
     "size": zod_1.default.number(),
     "threadId": zod_1.default.string().regex(exports.filesUploadFilesResponseThreadIdRegExpOne).nullish(),
     "workspaceId": zod_1.default.string().regex(exports.filesUploadFilesResponseWorkspaceIdRegExpOne).nullish()
-});
+}).describe('Model for a stored file blob. The simple name collides with\r\n`System.IO.File` and `SmartSpace.App.Data.Entities.FileEntity`\r\n(which is itself named to side-step the BCL collision); the\r\n`SmartSpace.App.Business.Models.Files` namespace disambiguates. When\r\nimporting both this model and the entity, alias the entity side:\r\n```using DataEntities = SmartSpace.App.Data.Entities;```\n`ThreadId` reflects the entity column `MessageThreadId`\r\n(renamed at the model boundary because the API contract has always called\r\nit `threadId`). `WorkspaceId` keeps the lower-s spelling that\r\nmatches the entity column and is already on the wire.');
 exports.filesUploadFilesResponse = zod_1.default.array(exports.filesUploadFilesResponseItem);
 /**
  * @summary Get details for a file previously uploaded.
@@ -1768,7 +1768,7 @@ exports.filesGetFileInfoResponse = zod_1.default.object({
     "size": zod_1.default.number(),
     "threadId": zod_1.default.string().regex(exports.filesGetFileInfoResponseThreadIdRegExpOne).nullish(),
     "workspaceId": zod_1.default.string().regex(exports.filesGetFileInfoResponseWorkspaceIdRegExpOne).nullish()
-});
+}).describe('Model for a stored file blob. The simple name collides with\r\n`System.IO.File` and `SmartSpace.App.Data.Entities.FileEntity`\r\n(which is itself named to side-step the BCL collision); the\r\n`SmartSpace.App.Business.Models.Files` namespace disambiguates. When\r\nimporting both this model and the entity, alias the entity side:\r\n```using DataEntities = SmartSpace.App.Data.Entities;```\n`ThreadId` reflects the entity column `MessageThreadId`\r\n(renamed at the model boundary because the API contract has always called\r\nit `threadId`). `WorkspaceId` keeps the lower-s spelling that\r\nmatches the entity column and is already on the wire.');
 /**
  * @summary Download a previously uploaded file.
  */
@@ -1797,7 +1797,7 @@ exports.filesGetUriQueryParams = zod_1.default.strictObject({
 });
 exports.filesGetUriResponse = zod_1.default.object({
     "uri": zod_1.default.string()
-});
+}).describe('Response shape for `GET /files/{id}/uri` on both the chat-api and\r\nconfig-api. Frontends call this with whatever URL the server hands them\r\n(e.g. as the `sourceUri` on a file MessageValue) and expect a JSON\r\nobject — not a bare string — so the wire format stays extensible (we can\r\nadd e.g. an expiry without breaking clients).');
 /**
  * @summary Creates a new flow run with the specified parameters
  */
@@ -1845,7 +1845,7 @@ exports.flowRunsGetFileFromFlowRunIdResponse = zod_1.default.object({
     "size": zod_1.default.number(),
     "threadId": zod_1.default.string().regex(exports.flowRunsGetFileFromFlowRunIdResponseThreadIdRegExp).nullish(),
     "workspaceId": zod_1.default.string().regex(exports.flowRunsGetFileFromFlowRunIdResponseWorkspaceIdRegExp).nullish()
-});
+}).describe('Model for a stored file blob. The simple name collides with\r\n`System.IO.File` and `SmartSpace.App.Data.Entities.FileEntity`\r\n(which is itself named to side-step the BCL collision); the\r\n`SmartSpace.App.Business.Models.Files` namespace disambiguates. When\r\nimporting both this model and the entity, alias the entity side:\r\n```using DataEntities = SmartSpace.App.Data.Entities;```\n`ThreadId` reflects the entity column `MessageThreadId`\r\n(renamed at the model boundary because the API contract has always called\r\nit `threadId`). `WorkspaceId` keeps the lower-s spelling that\r\nmatches the entity column and is already on the wire.');
 /**
  * @summary Gets a flow run including its context
  */
@@ -2082,9 +2082,9 @@ exports.modelsGetModelsResponse = zod_1.default.object({
         "properties": zod_1.default.array(zod_1.default.object({
             "name": zod_1.default.string(),
             "type": zod_1.default.enum(['Boolean', 'Number', 'String'])
-        })),
+        }).describe('Polymorphic AI-model parameter (Number / Boolean / String) — discriminator\r\nlives on `Type`. The shape is kept because the public JSON contract\r\nreturns the variant-specific fields under one collection; flattening to a\r\nsingle record would be a breaking wire-shape change for the admin UI.')),
         "virtualMachineUrl": zod_1.default.string().nullish()
-    })),
+    }).describe('Lighter list-endpoint shape — drops the nested `Deployment.Steps`\r\ncollection and keeps a flat `DeploymentStatus` + provider type for\r\nthe AI Models grid.')),
     "total": zod_1.default.number()
 });
 /**
@@ -2174,8 +2174,8 @@ exports.modelsGetModelResponse = zod_1.default.object({
     "properties": zod_1.default.array(zod_1.default.object({
         "name": zod_1.default.string(),
         "type": zod_1.default.enum(['Boolean', 'Number', 'String'])
-    }))
-});
+    }).describe('Polymorphic AI-model parameter (Number / Boolean / String) — discriminator\r\nlives on `Type`. The shape is kept because the public JSON contract\r\nreturns the variant-specific fields under one collection; flattening to a\r\nsingle record would be a breaking wire-shape change for the admin UI.'))
+}).describe('Full read model for an AI Model. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.Model`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. The folder is named `AiModels` to avoid the second namespace\r\ncollision with `SmartSpace.App.Business.Models` itself.');
 /**
  * @summary Updates or inserts a model with the specified ID.
  */
@@ -2247,10 +2247,10 @@ exports.notificationGetResponse = zod_1.default.object({
         "notificationType": zod_1.default.enum(['WorkSpaceUpdated', 'MessageThreadUpdated', 'CommentUpdated', 'AddedToThread']),
         "threadId": zod_1.default.string().regex(exports.notificationGetResponseDataItemThreadIdRegExpOne).nullish(),
         "workSpaceId": zod_1.default.string().regex(exports.notificationGetResponseDataItemWorkSpaceIdRegExpOne).nullish()
-    })),
+    }).describe('Model for a Notification. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.Notification`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. `CreatedBy` (display name) sits outside the positional ctor\r\nbecause it can\'t be expression-tree-translated — the service hydrates it\r\npost-projection via `IUserService.GetPrincipalDisplayNameByIdAsync`\r\nand emits a `with { CreatedBy = ... }`.')),
     "total": zod_1.default.number(),
     "totalUnread": zod_1.default.number()
-});
+}).describe('Notification list response shape. Two counts so callers can render an\r\n\"X unread of Y total\" badge without a second round-trip.');
 /**
  * @summary Update: mark read notifications.
  */
@@ -2361,7 +2361,7 @@ exports.syncsGetResponse = zod_1.default.object({
             "message": zod_1.default.string().nullish(),
             "start": zod_1.default.iso.datetime({}),
             "status": zod_1.default.string()
-        })).nullish(),
+        }).describe('One sync = one configured data source container: the source selection\r\n(path + filters) the sync service pulls, with its high-water mark and the\r\ndatasets subscribed to it via container flow triggers.')).nullish(),
         "statusMessage": zod_1.default.string().nullish()
     })),
     "total": zod_1.default.number()
@@ -2376,7 +2376,7 @@ exports.syncsGetQueueResponseWaitingDataSourceIdsItemRegExp = new RegExp('^[0-9a
 exports.syncsGetQueueResponse = zod_1.default.object({
     "depth": zod_1.default.number(),
     "waitingDataSourceIds": zod_1.default.array(zod_1.default.string().regex(exports.syncsGetQueueResponseWaitingDataSourceIdsItemRegExp))
-});
+}).describe('Point-in-time view of the sync-requests queue: how many requests are\r\nwaiting and which data sources they are for. Waiting only — a message\r\nbeing processed is invisible for its visibility timeout (that state is\r\nwhat IsSyncing covers).');
 exports.syncsGetByIdPathContainerIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.syncsGetByIdParams = zod_1.default.strictObject({
     "containerId": zod_1.default.string().regex(exports.syncsGetByIdPathContainerIdRegExp)
@@ -2414,7 +2414,7 @@ exports.syncsGetByIdResponse = zod_1.default.object({
         "message": zod_1.default.string().nullish(),
         "start": zod_1.default.iso.datetime({}),
         "status": zod_1.default.string()
-    })).nullish(),
+    }).describe('One sync = one configured data source container: the source selection\r\n(path + filters) the sync service pulls, with its high-water mark and the\r\ndatasets subscribed to it via container flow triggers.')).nullish(),
     "statusMessage": zod_1.default.string().nullish()
 });
 /**
@@ -2469,7 +2469,7 @@ exports.usersGetUsersResponse = zod_1.default.object({
         "mobilePhone": zod_1.default.string().nullish(),
         "name": zod_1.default.string(),
         "permissions": zod_1.default.array(zod_1.default.enum(['WorkspaceCreate', 'WorkspaceEdit', 'WorkspaceDelete', 'DataSpaceCreate', 'DataSpaceEdit', 'DataSpaceDelete', 'ConnectorCreate', 'ConnectorEdit', 'ConnectorDelete']))
-    })),
+    }).describe('Full per-user detail returned by the admin user-management endpoints.\r\nJoins the AAD principal with the local SmartSpace.App.Business.Models.Users.UserPermission\r\njunction state and last-activity timestamp.')),
     "total": zod_1.default.number()
 });
 exports.usersGetUsersByFilterParams = zod_1.default.strictObject({
@@ -2497,7 +2497,7 @@ exports.usersSearchUsersResponseItem = zod_1.default.object({
     "id": zod_1.default.string(),
     "isAssigned": zod_1.default.boolean(),
     "name": zod_1.default.string()
-});
+}).describe('Minimal user search result for autocomplete / picker UIs. Drops every\r\nfield that isn\'t needed to render a row — the picker only needs id, name,\r\nand email.');
 exports.usersSearchUsersResponse = zod_1.default.array(exports.usersSearchUsersResponseItem);
 /**
  * @summary Retrieve user detail in SmartSpace
@@ -2511,7 +2511,7 @@ exports.usersGetUserDetailResponse = zod_1.default.object({
     "isAdmin": zod_1.default.boolean().nullish(),
     "mobilePhone": zod_1.default.string().nullish(),
     "name": zod_1.default.string()
-});
+}).describe('Lighter user model used by role-membership lookups and permission-based\r\nfilters where the full per-user activity and permission set isn\'t needed.\r\nDrops the heavier SmartSpace.App.Business.Models.Users.AppUserDetail fields to keep\r\nrole-membership payloads tight.');
 /**
  * @summary Retrieves the profile photo for a user. Returns the raw JPEG image with HTTP cache headers
 so browsers can cache the image via standard img src usage.
@@ -2545,7 +2545,7 @@ exports.usersGetAccessWorkSpacesResponse = zod_1.default.object({
         "principalType": zod_1.default.enum(['Unknown', 'User', 'ServicePrincipal', 'Internal']).optional(),
         "workSpaceId": zod_1.default.string().regex(exports.usersGetAccessWorkSpacesResponseDataItemWorkSpaceIdRegExp).nullish(),
         "workSpaceName": zod_1.default.string().nullish()
-    })),
+    }).describe('Per-workspace access summary surfaced by the \"what workspaces does this\r\nuser belong to\" lookups. Carries the workspace\'s name alongside the\r\naccess grant so callers can render the assignment list without an\r\nadditional workspace lookup.')),
     "total": zod_1.default.number()
 });
 exports.usersAdminPermissionPathUserIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
@@ -2654,7 +2654,7 @@ exports.workSpacesGetGetResponse = zod_1.default.object({
             "id": zod_1.default.string().regex(exports.workSpacesGetGetResponseDataItemConnectorsItemIdRegExpOne),
             "kind": zod_1.default.string(),
             "name": zod_1.default.string()
-        })),
+        }).describe('The shape non-admins are allowed to see: enough to pick a connector from a\r\ndropdown, and nothing more. No URL (that is infrastructure detail) and no\r\nauth settings. Used by the workspace MCP tab\'s picker and embedded in the\r\nworkspace detail response so the flow editor can list what is attached.')),
         "createdAt": zod_1.default.iso.datetime({}),
         "createdByUserId": zod_1.default.string(),
         "dataSpaces": zod_1.default.array(zod_1.default.object({
@@ -2756,7 +2756,7 @@ exports.workSpacesGetGetResponse = zod_1.default.object({
             "workspacesInfo": zod_1.default.array(zod_1.default.object({
                 "id": zod_1.default.string().regex(exports.workSpacesGetGetResponseDataItemDataSpacesItemWorkspacesInfoItemIdRegExpOne),
                 "name": zod_1.default.string()
-            })).nullish()
+            }).describe('Cross-domain lightweight workspace pointer (id + name) embedded in\r\nshapes owned by other domains (e.g. SmartSpace.App.Business.Models.DataSpace). Stays\r\nin the legacy `SmartSpace.App.Business.Models` namespace until\r\nthose domains migrate.')).nullish()
         })),
         "favorited": zod_1.default.boolean(),
         "firstPrompt": zod_1.default.string().nullish(),
@@ -2825,7 +2825,7 @@ exports.workSpacesGetGetResponse = zod_1.default.object({
             "access": zod_1.default.enum(['None', 'Read', 'Write']),
             "schema": zod_1.default.record(zod_1.default.string(), zod_1.default.any())
         }))
-    })),
+    }).describe('Full read model for a WorkSpace. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.WorkSpace`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. References pre-existing cross-domain models\r\n(SmartSpace.App.Business.Models.DataSpace, SmartSpace.App.Business.Models.ModelConfiguration,\r\nSmartSpace.App.Business.Models.Flows.FlowInput, SmartSpace.App.Business.Models.Flows.FlowVariable) — those are not\r\nre-modelled by this PR.')),
     "total": zod_1.default.number()
 });
 /**
@@ -2850,7 +2850,7 @@ exports.workSpacesPostBody = zod_1.default.strictObject({
     })),
     "name": zod_1.default.string(),
     "templateVersionId": zod_1.default.string().regex(exports.workSpacesPostBodyTemplateVersionIdRegExp).nullish()
-});
+}).describe('Request shape for creating a workspace. SmartSpace.App.Business.Models.WorkSpaces.CreateWorkSpace.Id is optional —\r\ncallers may pre-allocate the id (e.g. for idempotency / client-side\r\noptimistic UI) or let the service generate one.');
 /**
  * @summary Deletes a workspace by its ID.
  */
@@ -2889,7 +2889,7 @@ exports.workSpacesGetIdResponse = zod_1.default.object({
         "id": zod_1.default.string().regex(exports.workSpacesGetIdResponseConnectorsItemIdRegExpOne),
         "kind": zod_1.default.string(),
         "name": zod_1.default.string()
-    })),
+    }).describe('The shape non-admins are allowed to see: enough to pick a connector from a\r\ndropdown, and nothing more. No URL (that is infrastructure detail) and no\r\nauth settings. Used by the workspace MCP tab\'s picker and embedded in the\r\nworkspace detail response so the flow editor can list what is attached.')),
     "createdAt": zod_1.default.iso.datetime({}),
     "createdByUserId": zod_1.default.string(),
     "dataSpaces": zod_1.default.array(zod_1.default.object({
@@ -2991,7 +2991,7 @@ exports.workSpacesGetIdResponse = zod_1.default.object({
         "workspacesInfo": zod_1.default.array(zod_1.default.object({
             "id": zod_1.default.string().regex(exports.workSpacesGetIdResponseDataSpacesItemWorkspacesInfoItemIdRegExpOne),
             "name": zod_1.default.string()
-        })).nullish()
+        }).describe('Cross-domain lightweight workspace pointer (id + name) embedded in\r\nshapes owned by other domains (e.g. SmartSpace.App.Business.Models.DataSpace). Stays\r\nin the legacy `SmartSpace.App.Business.Models` namespace until\r\nthose domains migrate.')).nullish()
     })),
     "favorited": zod_1.default.boolean(),
     "firstPrompt": zod_1.default.string().nullish(),
@@ -3060,7 +3060,7 @@ exports.workSpacesGetIdResponse = zod_1.default.object({
         "access": zod_1.default.enum(['None', 'Read', 'Write']),
         "schema": zod_1.default.record(zod_1.default.string(), zod_1.default.any())
     }))
-});
+}).describe('Full read model for a WorkSpace. Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.WorkSpace`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import\r\nboth. References pre-existing cross-domain models\r\n(SmartSpace.App.Business.Models.DataSpace, SmartSpace.App.Business.Models.ModelConfiguration,\r\nSmartSpace.App.Business.Models.Flows.FlowInput, SmartSpace.App.Business.Models.Flows.FlowVariable) — those are not\r\nre-modelled by this PR.');
 exports.workSpacesGetWorkspaceAdminsPathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.workSpacesGetWorkspaceAdminsParams = zod_1.default.strictObject({
     "id": zod_1.default.string().regex(exports.workSpacesGetWorkspaceAdminsPathIdRegExp)
@@ -3069,7 +3069,7 @@ exports.workSpacesGetWorkspaceAdminsResponseItem = zod_1.default.object({
     "id": zod_1.default.string(),
     "isAdmin": zod_1.default.boolean(),
     "name": zod_1.default.string()
-});
+}).describe('User-on-workspace projection: the user\'s id, display name, and whether\r\nthey are a workspace admin. Composed by the service from\r\n`EntityAccess` + `WorkspaceAdmin` records + the user-directory\r\ndisplay name — not a direct entity projection.');
 exports.workSpacesGetWorkspaceAdminsResponse = zod_1.default.array(exports.workSpacesGetWorkspaceAdminsResponseItem);
 exports.workSpacesDeleteAdminPathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.workSpacesDeleteAdminPathUserIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
@@ -3097,7 +3097,7 @@ exports.workSpacesPutBody = zod_1.default.strictObject({
     "showSources": zod_1.default.boolean(),
     "summary": zod_1.default.string().nullish(),
     "tags": zod_1.default.array(zod_1.default.string()).nullish()
-});
+}).describe('Request shape for the basic-info PUT endpoint. Replaces the legacy\r\n`WorkSpaceBasicInfo` record (which lacked DataAnnotations); shape\r\nunchanged so the wire contract is preserved.');
 /**
  * @summary Marks a workspace as favorited or not for the active user.
  */
@@ -3238,13 +3238,13 @@ exports.workSpacesGetWorkspaceFilesResponse = zod_1.default.object({
             "size": zod_1.default.number(),
             "threadId": zod_1.default.string().regex(exports.workSpacesGetWorkspaceFilesResponseDataItemFileThreadIdRegExp).nullish(),
             "workspaceId": zod_1.default.string().regex(exports.workSpacesGetWorkspaceFilesResponseDataItemFileWorkspaceIdRegExp).nullish()
-        }).optional(),
+        }).optional().describe('Model for a stored file blob. The simple name collides with\r\n`System.IO.File` and `SmartSpace.App.Data.Entities.FileEntity`\r\n(which is itself named to side-step the BCL collision); the\r\n`SmartSpace.App.Business.Models.Files` namespace disambiguates. When\r\nimporting both this model and the entity, alias the entity side:\r\n```using DataEntities = SmartSpace.App.Data.Entities;```\n`ThreadId` reflects the entity column `MessageThreadId`\r\n(renamed at the model boundary because the API contract has always called\r\nit `threadId`). `WorkspaceId` keeps the lower-s spelling that\r\nmatches the entity column and is already on the wire.'),
         "flowRunId": zod_1.default.string().nullish(),
         "id": zod_1.default.string(),
         "modifiedAt": zod_1.default.iso.datetime({}).nullish(),
         "modifiedByUserId": zod_1.default.string().nullish(),
         "status": zod_1.default.enum(['Uploaded', 'Ingested', 'Ingesting'])
-    })),
+    }).describe('Model for an ingested blob — pairs a stored SmartSpace.App.Business.Models.Files.IngestedBlob.File with its\r\ningestion lifecycle (status, owning dataset, originating flow run).\r\n`CreatedByUserName` is filled in by the service post-projection\r\n(display-name lookup via `IUserService`); it is not part of the EF\r\nprojection because it cannot be expression-tree-translated.')),
     "total": zod_1.default.number()
 });
 /**
@@ -3275,13 +3275,13 @@ exports.workSpacesWorkspaceFilesResponseItem = zod_1.default.object({
         "size": zod_1.default.number(),
         "threadId": zod_1.default.string().regex(exports.workSpacesWorkspaceFilesResponseFileThreadIdRegExp).nullish(),
         "workspaceId": zod_1.default.string().regex(exports.workSpacesWorkspaceFilesResponseFileWorkspaceIdRegExp).nullish()
-    }).optional(),
+    }).optional().describe('Model for a stored file blob. The simple name collides with\r\n`System.IO.File` and `SmartSpace.App.Data.Entities.FileEntity`\r\n(which is itself named to side-step the BCL collision); the\r\n`SmartSpace.App.Business.Models.Files` namespace disambiguates. When\r\nimporting both this model and the entity, alias the entity side:\r\n```using DataEntities = SmartSpace.App.Data.Entities;```\n`ThreadId` reflects the entity column `MessageThreadId`\r\n(renamed at the model boundary because the API contract has always called\r\nit `threadId`). `WorkspaceId` keeps the lower-s spelling that\r\nmatches the entity column and is already on the wire.'),
     "flowRunId": zod_1.default.string().nullish(),
     "id": zod_1.default.string(),
     "modifiedAt": zod_1.default.iso.datetime({}).nullish(),
     "modifiedByUserId": zod_1.default.string().nullish(),
     "status": zod_1.default.enum(['Uploaded', 'Ingested', 'Ingesting'])
-});
+}).describe('Model for an ingested blob — pairs a stored SmartSpace.App.Business.Models.Files.IngestedBlob.File with its\r\ningestion lifecycle (status, owning dataset, originating flow run).\r\n`CreatedByUserName` is filled in by the service post-projection\r\n(display-name lookup via `IUserService`); it is not part of the EF\r\nprojection because it cannot be expression-tree-translated.');
 exports.workSpacesWorkspaceFilesResponse = zod_1.default.array(exports.workSpacesWorkspaceFilesResponseItem);
 /**
  * @summary Removes a file from the workspace and the ingested content.
@@ -3433,7 +3433,7 @@ exports.connectorsGetConnectorsResponseItem = zod_1.default.object({
     "modifiedByUserId": zod_1.default.string(),
     "name": zod_1.default.string(),
     "url": zod_1.default.string()
-});
+}).describe('Admin read shape for a connector. Carries the auth SETTINGS (type, header,\r\nscheme) because an admin editing the connector needs to see them — but\r\nnever the vault reference and never the value. Collides on the simple name\r\nwith `SmartSpace.App.Data.Entities.Connector`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files importing both.');
 exports.connectorsGetConnectorsResponse = zod_1.default.array(exports.connectorsGetConnectorsResponseItem);
 /**
  * @summary Creates a connector and its shared credential in one call: the value
@@ -3447,7 +3447,7 @@ exports.connectorsCreateConnectorBody = zod_1.default.strictObject({
     "name": zod_1.default.string(),
     "secret": zod_1.default.string().nullish(),
     "url": zod_1.default.string()
-});
+}).describe('Create request. One form writes both rows: the connector (identity) and\r\nits single shared connection (credential). `Secret` is write-only —\r\nit goes straight to Key Vault and is never returned by any admin endpoint.');
 /**
  * @summary Picker list for workspace editors: id, name and kind only. Gated on
 WorkspaceEdit rather than Admin because attaching a connector to a
@@ -3462,7 +3462,7 @@ exports.connectorsGetConnectorSummariesResponseItem = zod_1.default.object({
     "id": zod_1.default.string().regex(exports.connectorsGetConnectorSummariesResponseIdRegExp),
     "kind": zod_1.default.string(),
     "name": zod_1.default.string()
-});
+}).describe('The shape non-admins are allowed to see: enough to pick a connector from a\r\ndropdown, and nothing more. No URL (that is infrastructure detail) and no\r\nauth settings. Used by the workspace MCP tab\'s picker and embedded in the\r\nworkspace detail response so the flow editor can list what is attached.');
 exports.connectorsGetConnectorSummariesResponse = zod_1.default.array(exports.connectorsGetConnectorSummariesResponseItem);
 exports.connectorsDeleteConnectorPathIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.connectorsDeleteConnectorParams = zod_1.default.strictObject({
@@ -3486,7 +3486,7 @@ exports.connectorsGetConnectorResponse = zod_1.default.object({
     "modifiedByUserId": zod_1.default.string(),
     "name": zod_1.default.string(),
     "url": zod_1.default.string()
-});
+}).describe('Admin read shape for a connector. Carries the auth SETTINGS (type, header,\r\nscheme) because an admin editing the connector needs to see them — but\r\nnever the vault reference and never the value. Collides on the simple name\r\nwith `SmartSpace.App.Data.Entities.Connector`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files importing both.');
 /**
  * @summary Updates a connector. Omit `Secret` to leave the credential
 untouched; supply one to rotate it.
@@ -3502,7 +3502,7 @@ exports.connectorsUpdateConnectorBody = zod_1.default.strictObject({
     "name": zod_1.default.string(),
     "secret": zod_1.default.string().nullish(),
     "url": zod_1.default.string()
-});
+}).describe('Update request. `Kind` is absent on purpose — changing what a\r\nconnector IS would invalidate every flow referencing it; delete and\r\nrecreate instead.\r\n            \r\n`Secret` null means \"leave the credential alone\". A non-null value\r\nrotates it: a new version of the SAME vault secret, so the row\'s reference\r\nnever changes and no orphan is left behind.');
 exports.connectorsUpdateConnectorResponseIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.connectorsUpdateConnectorResponse = zod_1.default.object({
     "authHeaderName": zod_1.default.string().nullish(),
@@ -3517,7 +3517,7 @@ exports.connectorsUpdateConnectorResponse = zod_1.default.object({
     "modifiedByUserId": zod_1.default.string(),
     "name": zod_1.default.string(),
     "url": zod_1.default.string()
-});
+}).describe('Admin read shape for a connector. Carries the auth SETTINGS (type, header,\r\nscheme) because an admin editing the connector needs to see them — but\r\nnever the vault reference and never the value. Collides on the simple name\r\nwith `SmartSpace.App.Data.Entities.Connector`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files importing both.');
 /**
  * @summary Retrieve a Shared Access Signature (SAS) for a specific item within a data space's documents in SmartSpace, using the dataSpaceId.
  */
@@ -3542,7 +3542,7 @@ exports.managedSecretsGetManagedSecretsResponseItem = zod_1.default.object({
     "modifiedAt": zod_1.default.iso.datetime({}),
     "modifiedByUserId": zod_1.default.string(),
     "name": zod_1.default.string()
-});
+}).describe('Read/list shape for a managed secret. Deliberately carries NO value property\r\nand NO vault reference — secret values are write-only through the admin\r\nsurface and only ever leave via the machine-only resolve endpoint\r\n(SmartSpace.App.Business.Models.ManagedSecrets.ResolvedManagedSecret). Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.ManagedSecret`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import both.');
 exports.managedSecretsGetManagedSecretsResponse = zod_1.default.array(exports.managedSecretsGetManagedSecretsResponseItem);
 /**
  * @summary Creates a named secret: writes the value to Key Vault and stores only
@@ -3551,7 +3551,7 @@ the vault reference.
 exports.managedSecretsCreateManagedSecretBody = zod_1.default.strictObject({
     "name": zod_1.default.string(),
     "value": zod_1.default.string()
-});
+}).describe('Create request shape. `Name` must match the token-safe pattern so it\r\nembeds cleanly in flow-definition secret tokens; the same rule is enforced\r\nas a business rule in `ManagedSecretService` (single source:\r\n`CreateManagedSecret.Pattern`). `Value` is write-only — it goes to\r\nKey Vault and is never returned by any admin endpoint.');
 /**
  * @summary Deletes a secret: removes the Key Vault secret and hard-deletes the row.
  */
@@ -3568,7 +3568,7 @@ exports.managedSecretsOverwriteManagedSecretValueParams = zod_1.default.strictOb
 });
 exports.managedSecretsOverwriteManagedSecretValueBody = zod_1.default.strictObject({
     "value": zod_1.default.string()
-});
+}).describe('Overwrite-value request shape (rotation). Writes a new version of the same\r\nKey Vault secret — the row\'s vault reference is reused, never re-minted.');
 exports.managedSecretsOverwriteManagedSecretValueResponseIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.managedSecretsOverwriteManagedSecretValueResponse = zod_1.default.object({
     "createdAt": zod_1.default.iso.datetime({}),
@@ -3577,7 +3577,7 @@ exports.managedSecretsOverwriteManagedSecretValueResponse = zod_1.default.object
     "modifiedAt": zod_1.default.iso.datetime({}),
     "modifiedByUserId": zod_1.default.string(),
     "name": zod_1.default.string()
-});
+}).describe('Read/list shape for a managed secret. Deliberately carries NO value property\r\nand NO vault reference — secret values are write-only through the admin\r\nsurface and only ever leave via the machine-only resolve endpoint\r\n(SmartSpace.App.Business.Models.ManagedSecrets.ResolvedManagedSecret). Collides on the simple name with\r\n`SmartSpace.App.Data.Entities.ManagedSecret`; alias\r\n`DataEntities = SmartSpace.App.Data.Entities` in files that import both.');
 exports.messageThreadsGetWorkspaceExecutionsPathWorkSpaceIdRegExp = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 exports.messageThreadsGetWorkspaceExecutionsParams = zod_1.default.strictObject({
     "workSpaceId": zod_1.default.string().regex(exports.messageThreadsGetWorkspaceExecutionsPathWorkSpaceIdRegExp)