@lessly/sdk-app 75.0.0 → 76.0.0

package/dist/_types/gen/types.gen.d.ts

@@ -71146,7 +71146,13 @@ export type BrainClickupSpacesListOutput = {
 export interface BrainCognitionDigestInput {
 }
 export interface BrainCognitionDigestOutput {
+    /**
+     * Id of the queued run. The completion event carries the same `run_id`, which is how a waiting step ties the event back to this call; brain_cognition_status reports the same run.
+     */
     run_id: string;
+    /**
+     * Always true — the run was queued. The call fails outright rather than reporting a false here.
+     */
     accepted: true;
 }
 export interface BrainCognitionStatusInput {
@@ -71179,7 +71185,13 @@ export interface BrainCognitionStatusOutput {
 export interface BrainCognitionSweepInput {
 }
 export interface BrainCognitionSweepOutput {
+    /**
+     * Id of the queued run. The completion event carries the same `run_id`, which is how a waiting step ties the event back to this call; brain_cognition_status reports the same run.
+     */
     run_id: string;
+    /**
+     * Always true — the run was queued. The call fails outright rather than reporting a false here.
+     */
     accepted: true;
 }
 export interface BrainConnectorBranchesListInput {
@@ -71209,6 +71221,9 @@ export type BrainConnectorReposListOutput = {
     defaultBranch: string;
 }[];
 export interface BrainDaemonBatchStatusInput {
+    /**
+     * Id of the ingestion daemon to act on, as returned by brain_daemons_list
+     */
     id: string;
 }
 export interface BrainDaemonBatchStatusOutput {
@@ -71292,6 +71307,9 @@ export interface BrainDaemonCreateOutput {
     unmeasuredCount: number;
 }
 export interface BrainDaemonGetInput {
+    /**
+     * Id of the ingestion daemon to act on, as returned by brain_daemons_list
+     */
     id: string;
 }
 export interface BrainDaemonGetOutput {
@@ -71315,52 +71333,154 @@ export interface BrainDaemonGetOutput {
     unmeasuredCount: number;
 }
 export interface BrainDaemonReingestInput {
+    /**
+     * Id of the ingestion daemon that owns these documents, as returned by brain_daemons_list
+     */
     id: string;
     /**
+     * Source paths to re-ingest, exactly as the daemon recorded them (a repo path such as docs/spec.md, a Drive file id, a ClickUp item id). 1-100 per call.
+     *
      * @minItems 1
      * @maxItems 100
      */
     paths: [string, ...(string)[]];
 }
 export interface BrainDaemonReingestOutput {
+    /**
+     * The run started to pick the cleared paths up — brain/daemon.run-completed for this id is what finishes the step. Null when no run was started (see triggered/triggerError).
+     */
+    runId: (string | null);
+    /**
+     * Paths whose ingest state was cleared, so the next run will read them again from scratch
+     */
     cleared: string[];
+    /**
+     * Paths this daemon has no ingest record for — usually a typo, or a document it never ingested
+     */
     notFound: string[];
+    /**
+     * True when a run was started to pick the cleared paths up; false when the daemon is paused, a run is already in flight, or nothing was eligible
+     */
     triggered: boolean;
+    /**
+     * Why no run was started; absent when one was
+     */
     triggerError?: string;
+    /**
+     * Paths left alone because they are in an unfinished batch; re-ask once that run has finished
+     */
     skippedPending: string[];
 }
 export interface BrainDaemonRemoveInput {
+    /**
+     * Id of the ingestion daemon to act on, as returned by brain_daemons_list
+     */
     id: string;
 }
 export interface BrainDaemonRemoveOutput {
     ok: true;
 }
 export interface BrainDaemonRunInput {
+    /**
+     * Id of the ingestion daemon to act on, as returned by brain_daemons_list
+     */
     id: string;
 }
 export interface BrainDaemonRunOutput {
+    /**
+     * True once the run has finished, whether it succeeded or failed
+     */
     done: boolean;
+    /**
+     * Id of the run being reported; null when this daemon has never run
+     */
     runId: (string | null);
+    /**
+     * Where the run stands: 'queued' waiting to start, 'running' in progress, 'done' finished, 'failed' gave up, 'none' this daemon has never run
+     */
     status: ("queued" | "running" | "done" | "failed" | "none");
+    /**
+     * Per-source progress as the connector reported it; the shape differs by connector type and is meant for display, not for binding a step to
+     */
     sources: unknown[];
+    /**
+     * Document counts for the run; null when nothing has been counted yet
+     */
     progress: ({
-        counts: BrainDaemonRunOutputCounts;
+        /**
+         * Totals for the whole run
+         */
+        counts: {
+            /**
+             * Documents that failed after retries — transient failures, worth re-running
+             */
+            error: number;
+            /**
+             * Documents the source permanently refused (403/404/401) — a permissions or deletion problem, not a transient one
+             */
+            denied: number;
+            /**
+             * Of those, how many were downloaded
+             */
+            fetched: number;
+            /**
+             * Of those, how many became memories
+             */
+            ingested: number;
+            /**
+             * Documents the run found at the source
+             */
+            discovered: number;
+            /**
+             * Documents skipped because their content had not changed since the last run
+             */
+            skippedUnchanged: number;
+        };
+        /**
+         * The same totals split by source category; the keys are the connector's own (github: markdown/issues/pulls, clickup: tasks/comments/docs/chat, gdrive: files)
+         */
         byCategory: {
-            [k: string]: BrainDaemonRunOutputCounts;
+            [k: string]: {
+                /**
+                 * Documents that failed after retries — transient failures, worth re-running
+                 */
+                error: number;
+                /**
+                 * Documents the source permanently refused (403/404/401) — a permissions or deletion problem, not a transient one
+                 */
+                denied: number;
+                /**
+                 * Of those, how many were downloaded
+                 */
+                fetched: number;
+                /**
+                 * Of those, how many became memories
+                 */
+                ingested: number;
+                /**
+                 * Documents the run found at the source
+                 */
+                discovered: number;
+                /**
+                 * Documents skipped because their content had not changed since the last run
+                 */
+                skippedUnchanged: number;
+            };
         };
     } | null);
+    /**
+     * Which lane the run went to: 'realtime' finishes in minutes, 'batch' queues the work with the model provider and can take hours
+     */
     routedTo: ("realtime" | "batch");
+    /**
+     * True when this call actually started a run; false when one was already in flight and nothing new was started
+     */
     triggered: boolean;
+    /**
+     * Why the run could not be started; absent when it was started
+     */
     triggerError?: string;
 }
-export interface BrainDaemonRunOutputCounts {
-    error: number;
-    denied: number;
-    fetched: number;
-    ingested: number;
-    discovered: number;
-    skippedUnchanged: number;
-}
 export interface BrainDaemonRunItemsInput {
     limit?: number;
     runId: string;
@@ -71378,64 +71498,208 @@ export interface BrainDaemonRunItemsOutput {
     }[];
     runId: string;
     counts: {
+        /**
+         * Documents that failed after retries — transient failures, worth re-running
+         */
         error: number;
+        /**
+         * Documents the source permanently refused (403/404/401) — a permissions or deletion problem, not a transient one
+         */
         denied: number;
+        /**
+         * Of those, how many were downloaded
+         */
         fetched: number;
+        /**
+         * Of those, how many became memories
+         */
         ingested: number;
+        /**
+         * Documents the run found at the source
+         */
         discovered: number;
+        /**
+         * Documents skipped because their content had not changed since the last run
+         */
         skippedUnchanged: number;
     };
     nextCursor: (string | null);
 }
 export interface BrainDaemonRunsInput {
+    /**
+     * Id of the ingestion daemon whose run history to read, as returned by brain_daemons_list
+     */
     id: string;
+    /**
+     * How many of the most recent runs to return (default 20, max 100)
+     */
     limit?: number;
 }
 export interface BrainDaemonRunsOutput {
+    /**
+     * The most recent runs, newest first
+     */
     runs: {
+        /**
+         * How the run was carried out: 'realtime' inline, 'batch' through the model provider's batch queue, 'reclaimed' a stalled run closed out by the janitor
+         */
         lane: ("realtime" | "batch" | "reclaimed");
+        /**
+         * Id of this run
+         */
         runId: string;
+        /**
+         * Document counts for this run
+         */
         counts: {
+            /**
+             * Documents that failed after retries — transient failures, worth re-running
+             */
             error: number;
+            /**
+             * Documents the source permanently refused (403/404/401) — a permissions or deletion problem, not a transient one
+             */
             denied: number;
+            /**
+             * Of those, how many were downloaded
+             */
             fetched: number;
+            /**
+             * Of those, how many became memories
+             */
             ingested: number;
+            /**
+             * Documents the run found at the source
+             */
             discovered: number;
+            /**
+             * Documents skipped because their content had not changed since the last run
+             */
             skippedUnchanged: number;
         };
+        /**
+         * Where the run ended up — 'queued', 'running', 'done' or 'failed'
+         */
         status: string;
+        /**
+         * How a batch run finished, in the batch pipeline's own words (e.g. finalized, timeout, crash); null for a realtime run
+         */
         outcome: (string | null);
+        /**
+         * When the run started, ISO 8601 timestamp
+         */
         startedAt: string;
+        /**
+         * Documents that failed after retries during this run
+         */
         errorCount: number;
+        /**
+         * When the run finished, ISO 8601 timestamp; null while it is still going
+         */
         finishedAt: (string | null);
+        /**
+         * Documents the source permanently refused during this run
+         */
         deniedCount: number;
+        /**
+         * Documents stored as raw text because the extraction step failed — NULL MEANS NOT MEASURED, never "clean": only realtime runs measure this, so every batch and reclaimed run reports null
+         */
         degradedCount: (number | null);
     }[];
+    /**
+     * Id of the daemon these runs belong to
+     */
     daemonId: string;
 }
 export interface BrainDaemonStatusInput {
+    /**
+     * Id of the ingestion daemon to act on, as returned by brain_daemons_list
+     */
     id: string;
 }
 export interface BrainDaemonStatusOutput {
+    /**
+     * True once the run has finished, whether it succeeded or failed
+     */
     done: boolean;
+    /**
+     * Id of the run being reported; null when this daemon has never run
+     */
     runId: (string | null);
+    /**
+     * Where the run stands: 'queued' waiting to start, 'running' in progress, 'done' finished, 'failed' gave up, 'none' this daemon has never run
+     */
     status: ("queued" | "running" | "done" | "failed" | "none");
+    /**
+     * Per-source progress as the connector reported it; the shape differs by connector type and is meant for display, not for binding a step to
+     */
     sources: unknown[];
+    /**
+     * Document counts for the run; null when nothing has been counted yet
+     */
     progress: ({
-        counts: BrainDaemonStatusOutputCounts;
+        /**
+         * Totals for the whole run
+         */
+        counts: {
+            /**
+             * Documents that failed after retries — transient failures, worth re-running
+             */
+            error: number;
+            /**
+             * Documents the source permanently refused (403/404/401) — a permissions or deletion problem, not a transient one
+             */
+            denied: number;
+            /**
+             * Of those, how many were downloaded
+             */
+            fetched: number;
+            /**
+             * Of those, how many became memories
+             */
+            ingested: number;
+            /**
+             * Documents the run found at the source
+             */
+            discovered: number;
+            /**
+             * Documents skipped because their content had not changed since the last run
+             */
+            skippedUnchanged: number;
+        };
+        /**
+         * The same totals split by source category; the keys are the connector's own (github: markdown/issues/pulls, clickup: tasks/comments/docs/chat, gdrive: files)
+         */
         byCategory: {
-            [k: string]: BrainDaemonStatusOutputCounts;
+            [k: string]: {
+                /**
+                 * Documents that failed after retries — transient failures, worth re-running
+                 */
+                error: number;
+                /**
+                 * Documents the source permanently refused (403/404/401) — a permissions or deletion problem, not a transient one
+                 */
+                denied: number;
+                /**
+                 * Of those, how many were downloaded
+                 */
+                fetched: number;
+                /**
+                 * Of those, how many became memories
+                 */
+                ingested: number;
+                /**
+                 * Documents the run found at the source
+                 */
+                discovered: number;
+                /**
+                 * Documents skipped because their content had not changed since the last run
+                 */
+                skippedUnchanged: number;
+            };
         };
     } | null);
 }
-export interface BrainDaemonStatusOutputCounts {
-    error: number;
-    denied: number;
-    fetched: number;
-    ingested: number;
-    discovered: number;
-    skippedUnchanged: number;
-}
 export interface BrainDaemonUpdateInput {
     id: string;
     name?: (string | null);
@@ -71521,46 +71785,121 @@ export interface BrainKnowledgeEntityMemoriesInput {
     entity_ref: string;
 }
 export interface BrainKnowledgeEntityMemoriesOutput {
+    /**
+     * How many memories back this entity in total, across all pages
+     */
     total: number;
+    /**
+     * The entity the memories belong to; null when `entity_ref` matched nothing
+     */
     entity: ({
+        /**
+         * How closely this entity matches the query, higher is closer; absent on an unscored read such as a plain type filter
+         */
         score?: number;
+        /**
+         * Other names the same entity appears under in the ingested text
+         */
         aliases: string[];
+        /**
+         * Id of this entity; pass it as `entity_ref` to brain_knowledge_neighborhood or brain_knowledge_entity_memories
+         */
         entity_id: string;
+        /**
+         * What the entity is, as the engine summarised it from the memories mentioning it; null when it has not written one
+         */
         description: (string | null);
+        /**
+         * Ontology type of the entity, e.g. Feature, Decision, Risk, Integration
+         */
         entity_type: string;
+        /**
+         * The name to show a person — usually the spelling the source text used
+         */
         display_name: string;
+        /**
+         * The one name this entity is stored under; use it when matching entities against each other
+         */
         canonical_name: string;
+        /**
+         * How many memories mention this entity — a rough measure of how well attested it is
+         */
         evidence_count: number;
     } | null);
+    /**
+     * One page of the memories this entity was drawn from — the same shape brain_memory_list returns
+     */
     memories: {
         /**
          * Consumer-facing label derived from the layer; 'unknown' for an unrecognised layer
          */
         kind: ("schema" | "intention" | "identity" | "basic" | "fact" | "summary" | "knowledge" | "raw" | "unknown");
+        /**
+         * Engine tags on this memory; empty when it carries none
+         */
         tags: string[];
         /**
          * Engine memory layer (l0_basic_info…l7_intention)
          */
         layer: ("l6_schema" | "l7_intention" | "l4_identity" | "l0_basic_info" | "l2_fact" | "l3_summary" | "l5_knowledge" | "l1_raw");
+        /**
+         * Free-form metadata, verbatim as the writer passed brain_memory_add's `metadata`; keys are the caller's
+         */
         custom: {
             [k: string]: unknown;
         };
+        /**
+         * Engine lifecycle status of the row — 'active' for a memory in use; superseded rows are not listed
+         */
         status: string;
+        /**
+         * The memory text itself
+         */
         content: string;
+        /**
+         * Engine user namespace the memory was written under
+         */
         user_id: string;
+        /**
+         * Engine agent namespace the memory was written under — the shared pool for a 'shared' write, the caller's own for a private one
+         */
         agent_id: string;
+        /**
+         * When the remembered EVENT happened, epoch milliseconds; null when the writer stated no time
+         */
         memory_at: (number | null);
+        /**
+         * Engine id of this memory; pass it to brain_memory_get, _update or _delete
+         */
         memory_id: string;
+        /**
+         * The engine's own inference about this memory, or null when it recorded none
+         */
         speculate: (string | null);
+        /**
+         * Engine session the memory was written in; empty when the writer opened none
+         */
         session_id: string;
+        /**
+         * When this memory row was written, epoch milliseconds
+         */
         gmt_created: number;
         /**
          * Source authority (highest→lowest): policy > official > team > informal
          */
         source_authority: ("policy" | "official" | "team" | "informal");
+        /**
+         * Id of the l1_raw memory this one was derived from; null when it was written directly
+         */
         source_raw_memory_id: (string | null);
     }[];
+    /**
+     * How long the engine took to answer, milliseconds
+     */
     elapsed_ms: number;
+    /**
+     * Engine request id for this call — quote it when reporting a problem
+     */
     request_id: string;
 }
 export interface BrainKnowledgeGraphInput {
@@ -71574,29 +71913,92 @@ export interface BrainKnowledgeGraphInput {
     scope?: ("shared" | "private" | "both");
 }
 export interface BrainKnowledgeGraphOutput {
+    /**
+     * The typed relations between those entities
+     */
     edges: {
+        /**
+         * Why the engine drew this edge, in its own words; null when it recorded none
+         */
         reason: (string | null);
+        /**
+         * Id of the node the edge points FROM (a `nodes[].id`)
+         */
         source: string;
+        /**
+         * Id of the node the edge points TO (a `nodes[].id`)
+         */
         target: string;
+        /**
+         * True when the relation reads the same in both directions
+         */
         symmetric: boolean;
+        /**
+         * Ontology type of the relation, e.g. depends_on, competes_with, owns
+         */
         relation_type: string;
     }[];
+    /**
+     * The entities in the exported graph
+     */
     nodes: {
+        /**
+         * Id of this entity; the `source` and `target` of an edge refer to it
+         */
         id: string;
+        /**
+         * How many edges touch this node — the hub concepts are the ones kept when the export is truncated
+         */
         degree: number;
+        /**
+         * Other names the same entity appears under in the ingested text
+         */
         aliases: string[];
+        /**
+         * What the entity is, as the engine summarised it; null when it has not written one
+         */
         description: (string | null);
+        /**
+         * Ontology type of the entity, e.g. Feature, Decision, Risk, Integration
+         */
         entity_type: string;
+        /**
+         * The name to show a person
+         */
         display_name: string;
+        /**
+         * The one name this entity is stored under
+         */
         canonical_name: string;
+        /**
+         * How many memories mention this entity
+         */
         evidence_count: number;
     }[];
+    /**
+     * Sizes of what was actually returned
+     */
     totals: {
+        /**
+         * Edges returned in this export
+         */
         edgeCount: number;
+        /**
+         * Nodes returned in this export
+         */
         nodeCount: number;
     };
+    /**
+     * True when `limit` cut the export short — the highest-degree nodes were kept, so what you get is the hubs
+     */
     truncated: boolean;
+    /**
+     * How long the engine took to answer, milliseconds
+     */
     elapsed_ms: number;
+    /**
+     * Engine request id for this call — quote it when reporting a problem
+     */
     request_id: string;
 }
 export interface BrainKnowledgeNeighborhoodInput {
@@ -71626,38 +72028,128 @@ export interface BrainKnowledgeNeighborhoodInput {
     relation_type?: string;
 }
 export interface BrainKnowledgeNeighborhoodOutput {
+    /**
+     * The entity that was expanded around; null when `entity_ref` matched nothing
+     */
     root: ({
+        /**
+         * How closely this entity matches the query, higher is closer; absent on an unscored read such as a plain type filter
+         */
         score?: number;
+        /**
+         * Other names the same entity appears under in the ingested text
+         */
         aliases: string[];
+        /**
+         * Id of this entity; pass it as `entity_ref` to brain_knowledge_neighborhood or brain_knowledge_entity_memories
+         */
         entity_id: string;
+        /**
+         * What the entity is, as the engine summarised it from the memories mentioning it; null when it has not written one
+         */
         description: (string | null);
+        /**
+         * Ontology type of the entity, e.g. Feature, Decision, Risk, Integration
+         */
         entity_type: string;
+        /**
+         * The name to show a person — usually the spelling the source text used
+         */
         display_name: string;
+        /**
+         * The one name this entity is stored under; use it when matching entities against each other
+         */
         canonical_name: string;
+        /**
+         * How many memories mention this entity — a rough measure of how well attested it is
+         */
         evidence_count: number;
     } | null);
+    /**
+     * The neighbours reached within `depth` hops of the root, the root excluded
+     */
     entities: {
+        /**
+         * How closely this entity matches the query, higher is closer; absent on an unscored read such as a plain type filter
+         */
         score?: number;
+        /**
+         * Other names the same entity appears under in the ingested text
+         */
         aliases: string[];
+        /**
+         * Id of this entity; pass it as `entity_ref` to brain_knowledge_neighborhood or brain_knowledge_entity_memories
+         */
         entity_id: string;
+        /**
+         * What the entity is, as the engine summarised it from the memories mentioning it; null when it has not written one
+         */
         description: (string | null);
+        /**
+         * Ontology type of the entity, e.g. Feature, Decision, Risk, Integration
+         */
         entity_type: string;
+        /**
+         * The name to show a person — usually the spelling the source text used
+         */
         display_name: string;
+        /**
+         * The one name this entity is stored under; use it when matching entities against each other
+         */
         canonical_name: string;
+        /**
+         * How many memories mention this entity — a rough measure of how well attested it is
+         */
         evidence_count: number;
     }[];
+    /**
+     * The relations that connect the root and the neighbours above
+     */
     relations: {
+        /**
+         * Why the engine drew this relation, in its own words; null when it recorded none
+         */
         reason: (string | null);
+        /**
+         * Id of the entity the relation points FROM
+         */
         source_id: string;
+        /**
+         * True when the relation reads the same in both directions, so source and target are interchangeable
+         */
         symmetric: boolean;
+        /**
+         * Id of the entity the relation points TO
+         */
         target_id: string;
+        /**
+         * Ontology type of the relation, e.g. depends_on, competes_with, owns
+         */
         relation_type: string;
+        /**
+         * Name to show for the source entity
+         */
         source_display_name: string;
+        /**
+         * Name to show for the target entity
+         */
         target_display_name: string;
+        /**
+         * Stored name of the source entity
+         */
         source_canonical_name: string;
+        /**
+         * Stored name of the target entity
+         */
         target_canonical_name: string;
     }[];
+    /**
+     * How long the engine took to answer, milliseconds
+     */
     elapsed_ms: number;
+    /**
+     * Engine request id for this call — quote it when reporting a problem
+     */
     request_id: string;
 }
 export interface BrainKnowledgeRelationsInput {
@@ -71683,18 +72175,54 @@ export interface BrainKnowledgeRelationsInput {
     target_entity?: string;
 }
 export interface BrainKnowledgeRelationsOutput {
+    /**
+     * The relations matching the filters
+     */
     relations: {
+        /**
+         * Why the engine drew this relation, in its own words; null when it recorded none
+         */
         reason: (string | null);
+        /**
+         * Id of the entity the relation points FROM
+         */
         source_id: string;
+        /**
+         * True when the relation reads the same in both directions, so source and target are interchangeable
+         */
         symmetric: boolean;
+        /**
+         * Id of the entity the relation points TO
+         */
         target_id: string;
+        /**
+         * Ontology type of the relation, e.g. depends_on, competes_with, owns
+         */
         relation_type: string;
+        /**
+         * Name to show for the source entity
+         */
         source_display_name: string;
+        /**
+         * Name to show for the target entity
+         */
         target_display_name: string;
+        /**
+         * Stored name of the source entity
+         */
         source_canonical_name: string;
+        /**
+         * Stored name of the target entity
+         */
         target_canonical_name: string;
     }[];
+    /**
+     * How long the engine took to answer, milliseconds
+     */
     elapsed_ms: number;
+    /**
+     * Engine request id for this call — quote it when reporting a problem
+     */
     request_id: string;
 }
 export interface BrainKnowledgeSearchInput {
@@ -71720,18 +72248,54 @@ export interface BrainKnowledgeSearchInput {
     entity_type?: string;
 }
 export interface BrainKnowledgeSearchOutput {
+    /**
+     * How many entities match in total, across all pages — not the length of this page
+     */
     total: number;
+    /**
+     * Matching entities, best match first
+     */
     entities: {
+        /**
+         * How closely this entity matches the query, higher is closer; absent on an unscored read such as a plain type filter
+         */
         score?: number;
+        /**
+         * Other names the same entity appears under in the ingested text
+         */
         aliases: string[];
+        /**
+         * Id of this entity; pass it as `entity_ref` to brain_knowledge_neighborhood or brain_knowledge_entity_memories
+         */
         entity_id: string;
+        /**
+         * What the entity is, as the engine summarised it from the memories mentioning it; null when it has not written one
+         */
         description: (string | null);
+        /**
+         * Ontology type of the entity, e.g. Feature, Decision, Risk, Integration
+         */
         entity_type: string;
+        /**
+         * The name to show a person — usually the spelling the source text used
+         */
         display_name: string;
+        /**
+         * The one name this entity is stored under; use it when matching entities against each other
+         */
         canonical_name: string;
+        /**
+         * How many memories mention this entity — a rough measure of how well attested it is
+         */
         evidence_count: number;
     }[];
+    /**
+     * How long the engine took to answer, milliseconds
+     */
     elapsed_ms: number;
+    /**
+     * Engine request id for this call — quote it when reporting a problem
+     */
     request_id: string;
 }
 export interface BrainMemoryAddInput {
@@ -71755,8 +72319,17 @@ export interface BrainMemoryAddInput {
     source_authority?: ("policy" | "official" | "team" | "informal");
 }
 export interface BrainMemoryAddOutput {
+    /**
+     * True when the memory was stored
+     */
     success: boolean;
+    /**
+     * Engine id of the memory just stored; keep it to read, replace or delete the memory later
+     */
     memory_id: string;
+    /**
+     * Engine request id for this call — quote it when reporting a problem
+     */
     request_id: string;
 }
 export interface BrainMemoryDeleteInput {
@@ -71766,8 +72339,17 @@ export interface BrainMemoryDeleteInput {
     memory_id: string;
 }
 export interface BrainMemoryDeleteOutput {
+    /**
+     * Always true — the call fails outright rather than reporting a false here
+     */
     success: true;
+    /**
+     * Engine request id for this call — quote it when reporting a problem
+     */
     request_id: string;
+    /**
+     * How many memory rows the engine removed for this id; 0 when it was already gone
+     */
     deleted_count: number;
 }
 export interface BrainMemoryGetInput {
@@ -71777,72 +72359,177 @@ export interface BrainMemoryGetInput {
     memory_id: string;
 }
 export interface BrainMemoryGetOutput {
+    /**
+     * Engine tags on this memory; empty when it carries none
+     */
     tags: string[];
     /**
      * Engine memory layer (l0_basic_info…l7_intention)
      */
     layer: ("l6_schema" | "l7_intention" | "l4_identity" | "l0_basic_info" | "l2_fact" | "l3_summary" | "l5_knowledge" | "l1_raw");
+    /**
+     * Free-form metadata, verbatim as the writer passed brain_memory_add's `metadata`; keys are the caller's
+     */
     custom: {
         [k: string]: unknown;
     };
+    /**
+     * Which store answered the read — 'vdb' the vector store, 'graph' the memory graph. Diagnostic; the content is the same either way.
+     */
     source: ("vdb" | "graph");
+    /**
+     * Engine lifecycle status of the row — 'active' for a memory in use
+     */
     status: string;
+    /**
+     * The memory text itself
+     */
     content: string;
+    /**
+     * Engine user namespace the memory was written under
+     */
     user_id: string;
+    /**
+     * Engine agent namespace the memory was written under
+     */
     agent_id: string;
+    /**
+     * True when this is the current version of the memory; false when a newer one has replaced it
+     */
     is_latest: boolean;
+    /**
+     * When the remembered EVENT happened, epoch milliseconds; null when the writer stated no time
+     */
     memory_at: (number | null);
+    /**
+     * Engine id of this memory — the id that was asked for
+     */
     memory_id: string;
+    /**
+     * The engine's own inference about this memory, or null when it recorded none
+     */
     speculate: (string | null);
+    /**
+     * The engine's confidence in this memory, 0..1
+     */
     confidence: number;
+    /**
+     * How long the engine took to answer, milliseconds
+     */
     elapsed_ms: number;
+    /**
+     * Engine request id for this call — quote it when reporting a problem
+     */
     request_id: string;
+    /**
+     * Ids of the memories this one replaced; null when it replaced none
+     */
     supersedes: (string[] | null);
+    /**
+     * When this memory row was written, epoch milliseconds
+     */
     gmt_created: number;
+    /**
+     * Ids of the memories that replaced this one; null while it is still current
+     */
     superseded_by: (string[] | null);
     /**
      * Source authority (highest→lowest): policy > official > team > informal
      */
     source_authority: ("policy" | "official" | "team" | "informal");
+    /**
+     * Id of the l1_raw memory this one was derived from; null when it was written directly
+     */
     source_raw_memory_id: (string | null);
 }
 export interface BrainMemoryListInput {
+    /**
+     * How many memories to return, max 1000. Omit to use the engine's own page size.
+     */
     limit?: number;
+    /**
+     * Sort by write time: 'desc' newest first, 'asc' oldest first. Omit to take the engine's own order.
+     */
     order?: ("asc" | "desc");
     /**
      * Read scope; 'both' (default) unions shared + your private
      */
     scope?: ("shared" | "private" | "both");
+    /**
+     * How many memories to skip before this page — offset 100 with limit 100 is the second page. Omit to start at the beginning.
+     */
     offset?: number;
 }
 export interface BrainMemoryListOutput {
+    /**
+     * How many memories match in total, across all pages — not the length of this page
+     */
     total: number;
+    /**
+     * One page of memories, newest first unless `order` said otherwise
+     */
     memories: {
         /**
          * Consumer-facing label derived from the layer; 'unknown' for an unrecognised layer
          */
         kind: ("schema" | "intention" | "identity" | "basic" | "fact" | "summary" | "knowledge" | "raw" | "unknown");
+        /**
+         * Engine tags on this memory; empty when it carries none
+         */
         tags: string[];
         /**
          * Engine memory layer (l0_basic_info…l7_intention)
          */
         layer: ("l6_schema" | "l7_intention" | "l4_identity" | "l0_basic_info" | "l2_fact" | "l3_summary" | "l5_knowledge" | "l1_raw");
+        /**
+         * Free-form metadata, verbatim as the writer passed brain_memory_add's `metadata`; keys are the caller's
+         */
         custom: {
             [k: string]: unknown;
         };
+        /**
+         * Engine lifecycle status of the row — 'active' for a memory in use; superseded rows are not listed
+         */
         status: string;
+        /**
+         * The memory text itself
+         */
         content: string;
+        /**
+         * Engine user namespace the memory was written under
+         */
         user_id: string;
+        /**
+         * Engine agent namespace the memory was written under — the shared pool for a 'shared' write, the caller's own for a private one
+         */
         agent_id: string;
+        /**
+         * When the remembered EVENT happened, epoch milliseconds; null when the writer stated no time
+         */
         memory_at: (number | null);
+        /**
+         * Engine id of this memory; pass it to brain_memory_get, _update or _delete
+         */
         memory_id: string;
+        /**
+         * The engine's own inference about this memory, or null when it recorded none
+         */
         speculate: (string | null);
+        /**
+         * Engine session the memory was written in; empty when the writer opened none
+         */
         session_id: string;
+        /**
+         * When this memory row was written, epoch milliseconds
+         */
         gmt_created: number;
         /**
          * Source authority (highest→lowest): policy > official > team > informal
          */
         source_authority: ("policy" | "official" | "team" | "informal");
+        /**
+         * Id of the l1_raw memory this one was derived from; null when it was written directly
+         */
         source_raw_memory_id: (string | null);
     }[];
 }
@@ -71861,8 +72548,17 @@ export interface BrainMemorySearchInput {
     scope?: ("shared" | "private" | "both");
 }
 export interface BrainMemorySearchOutput {
+    /**
+     * Ordinary hits: the facts, summaries and raw notes that match the query
+     */
     normal: BrainMemorySearchOutputItems[];
+    /**
+     * Hits describing WHO the subject is — stable identity and preference memories (l0/l4). Usually the ones worth carrying into a prompt.
+     */
     profile: BrainMemorySearchOutputItems[];
+    /**
+     * Hits the engine offers unprompted — intentions and open threads (l7) it judged relevant to the query rather than matched to it
+     */
     proactive: BrainMemorySearchOutputItems[];
 }
 export interface BrainMemorySearchOutputItems {
@@ -71870,23 +72566,53 @@ export interface BrainMemorySearchOutputItems {
      * Consumer-facing label derived from the layer; 'unknown' for an unrecognised layer
      */
     kind: ("schema" | "intention" | "identity" | "basic" | "fact" | "summary" | "knowledge" | "raw" | "unknown");
+    /**
+     * Engine tags on this memory; empty when it carries none
+     */
     tags: string[];
     /**
      * Engine memory layer (l0_basic_info…l7_intention)
      */
     layer: ("l6_schema" | "l7_intention" | "l4_identity" | "l0_basic_info" | "l2_fact" | "l3_summary" | "l5_knowledge" | "l1_raw");
+    /**
+     * How closely this hit matches the query — higher is closer. An engine-internal scale, not a percentage; compare hits against each other, never against a fixed threshold.
+     */
     score: number;
+    /**
+     * The memory text itself
+     */
     content: string;
+    /**
+     * When the remembered EVENT happened, epoch milliseconds; null when the writer stated no time
+     */
     memory_at: (number | null);
+    /**
+     * Engine id of this memory; pass it to brain_memory_get, _update or _delete
+     */
     memory_id: string;
+    /**
+     * The engine's own inference about this memory, or null when it recorded none
+     */
     speculate: (string | null);
+    /**
+     * When this memory row was written, epoch milliseconds
+     */
     gmt_created: number;
+    /**
+     * Name of the l6_schema type this memory instantiates; absent on every other layer
+     */
     schema_type?: string;
+    /**
+     * Ids of the earlier memories this one grew out of, oldest first; absent when it has no history
+     */
     evolution_chain?: string[];
     /**
      * Source authority (highest→lowest): policy > official > team > informal
      */
     source_authority: ("policy" | "official" | "team" | "informal");
+    /**
+     * Id of the l1_raw memory this one was derived from; null when it was written directly
+     */
     source_raw_memory_id: (string | null);
 }
 export interface BrainMemoryStatsInput {
@@ -71896,19 +72622,52 @@ export interface BrainMemoryStatsInput {
     scope?: ("shared" | "private" | "both");
 }
 export interface BrainMemoryStatsOutput {
+    /**
+     * Size of the engine's memory graph
+     */
     graph: {
+        /**
+         * Edges between those nodes
+         */
         edgeCount: number;
+        /**
+         * Nodes in the memory graph
+         */
         nodeCount: number;
     };
+    /**
+     * Memory counts for the requested scope
+     */
     memories: {
+        /**
+         * How many memories the scope holds in total
+         */
         total: number;
+        /**
+         * Counts for the three derived layers the engine reports; the other layers are not broken out
+         */
         byLayer: {
+            /**
+             * Count of l2_fact memories — extracted facts
+             */
             l2: number;
+            /**
+             * Count of l3_summary memories — summaries over facts
+             */
             l3: number;
+            /**
+             * Count of l4_identity memories — who the subject is
+             */
             l4: number;
         };
     };
+    /**
+     * Size of the product knowledge graph
+     */
     knowledge: {
+        /**
+         * Entities in the product knowledge graph (see brain_knowledge_search)
+         */
         entityCount: number;
     };
 }
@@ -71923,8 +72682,17 @@ export interface BrainMemoryUpdateInput {
     memory_id: string;
 }
 export interface BrainMemoryUpdateOutput {
+    /**
+     * Always true — the call fails outright rather than reporting a false here
+     */
     success: true;
+    /**
+     * Engine id of the memory that was replaced
+     */
     memory_id: string;
+    /**
+     * Engine request id for this call — quote it when reporting a problem
+     */
     request_id: string;
 }
 export interface BrainProductSharedMemoryResetInput {
@@ -71973,6 +72741,9 @@ export interface BrainUsageReportInput {
     days?: number;
 }
 export interface BrainUsageReportOutput {
+    /**
+     * A standing warning, in words, that product.rows and platform.meters have different subjects and need not match
+     */
     note: string;
     /**
      * Brain's own ledger, for THIS product only
@@ -71990,6 +72761,9 @@ export interface BrainUsageReportOutput {
          * Inclusive UTC start of the window, YYYY-MM-DD
          */
         from: string;
+        /**
+         * One row per UTC day and meter dimension — the grain to join against a billing export
+         */
         rows: {
             /**
              * 'sync' | 'batch'; '' when the push carried none
@@ -72028,27 +72802,72 @@ export interface BrainUsageReportOutput {
          * The rows rolled up per meter across the whole window
          */
         totals: {
+            /**
+             * Manifest meter slug, e.g. llm-tokens
+             */
             meter: string;
+            /**
+             * How many metered calls landed in the window
+             */
             events: number;
+            /**
+             * Tokens metered for this meter across the whole window
+             */
             tokens: number;
+            /**
+             * Of those calls, how many billing did not accept — a non-zero here means our ledger and the invoice will differ
+             */
             delivery_failed: number;
         }[];
+        /**
+         * The product this ledger belongs to — the one the call was made for
+         */
         product_id: string;
     };
     /**
      * The platform billing aggregate for the whole ORG; null if it could not be read
      */
     platform: ({
+        /**
+         * The billing plan in force for that organisation
+         */
         plan: string;
+        /**
+         * Always 'org' — a reminder that these numbers are the whole organisation's, not this product's
+         */
         scope: "org";
+        /**
+         * Per-meter allowance and month-to-date usage as billing reports it
+         */
         meters: {
+            /**
+             * What the numbers below are counted in, e.g. tokens
+             */
             unit?: string;
+            /**
+             * How much of it has been used MONTH TO DATE, for the whole org — not for the window asked for here
+             */
             used?: number;
+            /**
+             * The plan's allowance for this meter; null or absent when there is no cap
+             */
             limit?: (number | null);
+            /**
+             * Allowance left; null or absent when the meter is uncapped
+             */
             remaining?: (number | null);
+            /**
+             * True when this meter has no cap at all
+             */
             unlimited?: boolean;
+            /**
+             * Platform meter slug, e.g. llm-tokens
+             */
             meter_slug: string;
         }[];
+        /**
+         * The organisation the billing aggregate was read for
+         */
         org_id: string;
     } | null);
     /**
@@ -116863,25 +117682,70 @@ export interface UsersApikeysCreateInput {
     type: ("server" | "publishable");
 }
 export interface UsersApikeysCreateOutput {
+    /**
+     * Id of the key. Pass it to users_apikeys_revoke.
+     */
     id: string;
+    /**
+     * The full secret key, shown ONCE. Store it now — it is never returned again, and a lost key is replaced by minting a new one.
+     */
     key: string;
+    /**
+     * The label a human gave this key — which backend or environment holds it.
+     */
     name: string;
+    /**
+     * `server` for a secret backend key (usk_…), `publishable` for a browser-safe one (upk_…).
+     */
     type: ("server" | "publishable");
+    /**
+     * The full value of a publishable key, which is not a secret. Null for a server key — that value exists in exactly one response, ever.
+     */
     value: (string | null);
+    /**
+     * `usk_`/`upk_` plus six characters — enough to recognise a key, never to use one.
+     */
     prefix: string;
+    /**
+     * When the key was issued (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the key was revoked (ISO 8601). Null while it still works.
+     */
     revokedAt: (string | null);
 }
 export interface UsersApikeysListInput {
 }
 export interface UsersApikeysListOutput {
     keys: {
+        /**
+         * Id of the key. Pass it to users_apikeys_revoke.
+         */
         id: string;
+        /**
+         * The label a human gave this key — which backend or environment holds it.
+         */
         name: string;
+        /**
+         * `server` for a secret backend key (usk_…), `publishable` for a browser-safe one (upk_…).
+         */
         type: ("server" | "publishable");
+        /**
+         * The full value of a publishable key, which is not a secret. Null for a server key — that value exists in exactly one response, ever.
+         */
         value: (string | null);
+        /**
+         * `usk_`/`upk_` plus six characters — enough to recognise a key, never to use one.
+         */
         prefix: string;
+        /**
+         * When the key was issued (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * When the key was revoked (ISO 8601). Null while it still works.
+         */
         revokedAt: (string | null);
     }[];
 }
@@ -116892,7 +117756,13 @@ export interface UsersApikeysRevokeInput {
     id: string;
 }
 export interface UsersApikeysRevokeOutput {
+    /**
+     * Id of the key that was revoked.
+     */
     id: string;
+    /**
+     * Always true — revocation is immediate and final.
+     */
     revoked: true;
 }
 export interface UsersAuditListInput {
@@ -116926,21 +117796,60 @@ export interface UsersAuditListInput {
     targetType?: string;
 }
 export interface UsersAuditListOutput {
+    /**
+     * The page of audit events, newest first.
+     */
     events: {
+        /**
+         * Id of this audit row.
+         */
         id: string;
+        /**
+         * IP the action came from. Null when it was not an HTTP action.
+         */
         ip: (string | null);
+        /**
+         * What happened, as a dotted name — `user.created`, `passkey.deleted`, `email_change.override_applied`.
+         */
         action: string;
+        /**
+         * Id of the actor. Null for a system action.
+         */
         actorId: (string | null);
+        /**
+         * Action-specific detail — the reason text, counts, whatever the action recorded.
+         */
         metadata: {
             [k: string]: unknown;
         };
+        /**
+         * Id of the row the action was about. Null when there was none.
+         */
         targetId: (string | null);
+        /**
+         * Who acted: `operator` (a human or agent on the management plane), `end_user`, or `system`.
+         */
         actorType: ("operator" | "system" | "end_user");
+        /**
+         * When the action happened (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * Product the audited action happened in.
+         */
         productId: string;
+        /**
+         * User agent the action came from. Null when none was sent.
+         */
         userAgent: (string | null);
+        /**
+         * What kind of row the action was about — `user` or `product`. Null when it was about nothing in particular.
+         */
         targetType: (string | null);
     }[];
+    /**
+     * Pass back as `cursor` to fetch the next page. Null when this page is the last.
+     */
     nextCursor: (string | null);
 }
 export interface UsersConfigGetInput {
@@ -117916,12 +118825,33 @@ export interface UsersFactorsListInput {
     userId: string;
 }
 export interface UsersFactorsListOutput {
+    /**
+     * Every second factor this user has — types and status only, never material.
+     */
     factors: {
+        /**
+         * Kind of second factor: `totp` or `backup_codes`. No key material is ever returned.
+         */
         type: ("totp" | "backup_codes" | "webauthn");
+        /**
+         * Whether this factor is enrolled and usable, or still pending verification.
+         */
         status: ("unverified" | "verified");
+        /**
+         * When the factor was enrolled (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * `backup_codes` only: how many of the batch are still unspent. Null for any other factor type.
+         */
         remaining: (number | null);
+        /**
+         * When the factor was last used to sign in (ISO 8601). Null if it never was.
+         */
         lastUsedAt: (string | null);
+        /**
+         * When the user first proved the factor works (ISO 8601). Null while it is unverified.
+         */
         verifiedAt: (string | null);
     }[];
 }
@@ -117936,7 +118866,13 @@ export interface UsersFactorsResetInput {
     userId: string;
 }
 export interface UsersFactorsResetOutput {
+    /**
+     * Id of the scheduled reset. The same value arrives on `users/mfa.reset-settled`, which is what finishes this step.
+     */
     requestId: string;
+    /**
+     * When the removal happens, if nobody aborts it first (ISO 8601). The delay is this product's, not a fixed one.
+     */
     scheduledFor: string;
 }
 export interface UsersKeysListInput {
@@ -118254,9 +119190,18 @@ export interface UsersPasskeysRevokeOutput {
      * Present when the revoke was refused — today, only because it was the last way in.
      */
     error: ({
+        /**
+         * Why it was refused. Today only `passkey_last_way_in`.
+         */
         code: string;
+        /**
+         * The refusal in a sentence, safe to show a human.
+         */
         message: string;
     } | null);
+    /**
+     * `deleted` when the credential is gone, `failed` when the revoke was refused.
+     */
     status: ("deleted" | "failed");
 }
 export interface UsersSessionsGetInput {
@@ -118266,7 +119211,13 @@ export interface UsersSessionsGetInput {
     sessionId: string;
 }
 export interface UsersSessionsGetOutput {
+    /**
+     * Id of this session. Pass it to users_sessions_revoke.
+     */
     id: string;
+    /**
+     * IP the session was opened from. Null when it was not recorded.
+     */
     ip: (string | null);
     /**
      * `aal2` only if a verified second factor completed.
@@ -118276,18 +119227,42 @@ export interface UsersSessionsGetOutput {
      * The factors this session was established with.
      */
     amr: string[];
+    /**
+     * Whether the session is still usable, expired, or revoked.
+     */
     status: ("active" | "revoked");
+    /**
+     * The end user this session belongs to.
+     */
     userId: string;
+    /**
+     * When the session was opened (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the current token stops working unless refreshed (ISO 8601).
+     */
     expiresAt: string;
+    /**
+     * When the session was revoked (ISO 8601). Null while it is live.
+     */
     revokedAt: (string | null);
+    /**
+     * User agent the session was opened from. Null when none was sent.
+     */
     userAgent: (string | null);
     revokedReason: (string | null);
     /**
      * The operator behind an impersonated session, or null for an ordinary one.
      */
     impersonatedBy: (string | null);
+    /**
+     * When the session last refreshed its tokens (ISO 8601). Null if it never has.
+     */
     lastRefreshedAt: (string | null);
+    /**
+     * When the session ends no matter how often it refreshes (ISO 8601).
+     */
     absoluteExpiresAt: string;
 }
 export interface UsersSessionsImpersonateInput {
@@ -118323,16 +119298,49 @@ export interface UsersSessionsListInput {
     userId: string;
 }
 export interface UsersSessionsListOutput {
+    /**
+     * The sessions matching the filter, newest first.
+     */
     sessions: {
+        /**
+         * Id of this session. Pass it to users_sessions_revoke.
+         */
         id: string;
+        /**
+         * IP the session was opened from. Null when it was not recorded.
+         */
         ip: (string | null);
+        /**
+         * Whether the session is still usable, expired, or revoked.
+         */
         status: ("active" | "revoked");
+        /**
+         * The end user this session belongs to.
+         */
         userId: string;
+        /**
+         * When the session was opened (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * When the current token stops working unless refreshed (ISO 8601).
+         */
         expiresAt: string;
+        /**
+         * When the session was revoked (ISO 8601). Null while it is live.
+         */
         revokedAt: (string | null);
+        /**
+         * User agent the session was opened from. Null when none was sent.
+         */
         userAgent: (string | null);
+        /**
+         * When the session last refreshed its tokens (ISO 8601). Null if it never has.
+         */
         lastRefreshedAt: (string | null);
+        /**
+         * When the session ends no matter how often it refreshes (ISO 8601).
+         */
         absoluteExpiresAt: string;
     }[];
 }
@@ -118347,6 +119355,9 @@ export interface UsersSessionsRevokeInput {
     sessionId?: string;
 }
 export interface UsersSessionsRevokeOutput {
+    /**
+     * How many sessions were revoked. Zero when there was nothing live to revoke.
+     */
     revoked: number;
 }
 export interface UsersStatsGetInput {
@@ -118469,37 +119480,126 @@ export interface UsersUsersBanInput {
     userId: string;
 }
 export interface UsersUsersBanOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersBanOutputPublicMetadata;
-    unsafeMetadata: UsersUsersBanOutputPublicMetadata;
-    privateMetadata: UsersUsersBanOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersBanOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersCreateInput {
     /**
      * The user's display name.
@@ -118603,37 +119703,126 @@ export interface UsersUsersCreateInputPublicMetadata1 {
     [k: string]: unknown;
 }
 export interface UsersUsersCreateOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersCreateOutputPublicMetadata;
-    unsafeMetadata: UsersUsersCreateOutputPublicMetadata;
-    privateMetadata: UsersUsersCreateOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersCreateOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersDeleteInput {
     /**
      * The opaque user id returned by users_users_create or _list.
@@ -118641,37 +119830,126 @@ export interface UsersUsersDeleteInput {
     userId: string;
 }
 export interface UsersUsersDeleteOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersDeleteOutputPublicMetadata;
-    unsafeMetadata: UsersUsersDeleteOutputPublicMetadata;
-    privateMetadata: UsersUsersDeleteOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersDeleteOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersExportInput {
     /**
      * Rows per page, 1-500. Default 100.
@@ -118697,40 +119975,129 @@ export interface UsersUsersExportInput {
 export interface UsersUsersExportOutput {
     count: number;
     users: {
+        /**
+         * Id of this end user. Pass it to any users_users_* tool.
+         */
         id: string;
+        /**
+         * The user's display name. Null when nobody set one.
+         */
         name: (string | null);
+        /**
+         * When the user was banned (ISO 8601). Null while they are not banned.
+         */
         bannedAt: (string | null);
+        /**
+         * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+         */
         erasedAt: (string | null);
+        /**
+         * URL of the user's avatar. Null when there is none.
+         */
         imageUrl: (string | null);
+        /**
+         * Whether this is a test fixture — excluded from metering and from the default listing.
+         */
         testUser: boolean;
+        /**
+         * When the user was created (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * When the user was soft-deleted (ISO 8601). Null while the account is live.
+         */
         deletedAt: (string | null);
+        /**
+         * Product this user belongs to. Never an input — it comes from the calling identity.
+         */
         productId: string;
+        /**
+         * When the user was last changed (ISO 8601).
+         */
         updatedAt: string;
+        /**
+         * Whether this user is still on the waitlist and cannot sign in yet.
+         */
         waitlisted: boolean;
+        /**
+         * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+         */
         identifiers: {
+            /**
+             * Id of this identifier row.
+             */
             id: string;
+            /**
+             * What kind of identifier this is. Today always `email`.
+             */
             type: "email";
+            /**
+             * The address as the user typed it, for display.
+             */
             value: string;
+            /**
+             * Whether this is the identifier the user signs in with and is contacted at.
+             */
             isPrimary: boolean;
+            /**
+             * When this address was verified (ISO 8601). Null while it never was.
+             */
             verifiedAt: (string | null);
+            /**
+             * The address lowercased and NFC-normalised — what uniqueness is checked against.
+             */
             valueCanonical: string;
+            /**
+             * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+             */
             verificationStatus: ("unverified" | "verified" | "expired");
         }[];
+        /**
+         * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+         */
         lockedUntil: (string | null);
+        /**
+         * When the user last signed in (ISO 8601). Null if they never have.
+         */
         lastSignInAt: (string | null);
+        /**
+         * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+         */
+        primaryEmail: (string | null);
+        /**
+         * Whether the user must set a new password at their next sign-in.
+         */
         requiresReset: boolean;
-        publicMetadata: UsersUsersExportOutputPublicMetadata;
-        unsafeMetadata: UsersUsersExportOutputPublicMetadata;
-        privateMetadata: UsersUsersExportOutputPublicMetadata;
+        /**
+         * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+         */
+        publicMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Metadata the end user may write themselves. Treat it as untrusted.
+         */
+        unsafeMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Metadata for the management plane only. Never reaches the end user or a token.
+         */
+        privateMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Id of the primary identifier row. Null when there is no primary identifier.
+         */
+        primaryIdentifierId: (string | null);
+        /**
+         * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+         */
         emailChangeLockedUntil: (string | null);
     }[];
     exportedAt: string;
     nextCursor: (string | null);
 }
-export interface UsersUsersExportOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersGetInput {
     /**
      * The opaque user id returned by users_users_create or _list.
@@ -118738,37 +120105,126 @@ export interface UsersUsersGetInput {
     userId: string;
 }
 export interface UsersUsersGetOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersGetOutputPublicMetadata;
-    unsafeMetadata: UsersUsersGetOutputPublicMetadata;
-    privateMetadata: UsersUsersGetOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersGetOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersImportInput {
     /**
      * The users to import, at most 500 per call — batch client-side beyond that. Each row: identifiers (email), optional profile, optional password HASH, optional flags.
@@ -118779,15 +120235,42 @@ export interface UsersUsersImportInput {
     users: [unknown, ...(unknown)[]];
 }
 export interface UsersUsersImportOutput {
+    /**
+     * How many rows could not be imported at all.
+     */
     failed: number;
+    /**
+     * How many users were created.
+     */
     created: number;
+    /**
+     * One row per submitted row, in the order you sent them.
+     */
     results: {
+        /**
+         * Zero-based index of the row in the `users` array you sent.
+         */
         row: number;
+        /**
+         * Why it was skipped, or what went wrong. Null for a created row.
+         */
         reason: (string | null);
+        /**
+         * What happened to this row.
+         */
         status: ("created" | "skipped" | "failed");
+        /**
+         * The created user's id. Null for skipped and failed rows.
+         */
         userId: (string | null);
     }[];
+    /**
+     * How many rows were passed over — an address already in the directory, typically.
+     */
     skipped: number;
+    /**
+     * How many rows you submitted.
+     */
     requested: number;
 }
 export interface UsersUsersInviteInput {
@@ -118813,9 +120296,21 @@ export interface UsersUsersInviteInput {
     };
 }
 export interface UsersUsersInviteOutput {
+    /**
+     * False when the re-invite cooldown or the mail toolkit refused the send. The invite is still live.
+     */
     mailed: boolean;
+    /**
+     * The invited user, created immediately and listed straight away — they simply cannot sign in until they accept.
+     */
     userId: string;
+    /**
+     * False when this address had already been invited; the same user is returned.
+     */
     created: boolean;
+    /**
+     * When the invite link stops working (ISO 8601).
+     */
     expiresAt: string;
 }
 export interface UsersUsersListInput {
@@ -118849,40 +120344,135 @@ export interface UsersUsersListInput {
     includeWaitlisted?: boolean;
 }
 export interface UsersUsersListOutput {
+    /**
+     * The page of users, newest first.
+     */
     users: {
+        /**
+         * Id of this end user. Pass it to any users_users_* tool.
+         */
         id: string;
+        /**
+         * The user's display name. Null when nobody set one.
+         */
         name: (string | null);
+        /**
+         * When the user was banned (ISO 8601). Null while they are not banned.
+         */
         bannedAt: (string | null);
+        /**
+         * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+         */
         erasedAt: (string | null);
+        /**
+         * URL of the user's avatar. Null when there is none.
+         */
         imageUrl: (string | null);
+        /**
+         * Whether this is a test fixture — excluded from metering and from the default listing.
+         */
         testUser: boolean;
+        /**
+         * When the user was created (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * When the user was soft-deleted (ISO 8601). Null while the account is live.
+         */
         deletedAt: (string | null);
+        /**
+         * Product this user belongs to. Never an input — it comes from the calling identity.
+         */
         productId: string;
+        /**
+         * When the user was last changed (ISO 8601).
+         */
         updatedAt: string;
+        /**
+         * Whether this user is still on the waitlist and cannot sign in yet.
+         */
         waitlisted: boolean;
+        /**
+         * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+         */
         identifiers: {
+            /**
+             * Id of this identifier row.
+             */
             id: string;
+            /**
+             * What kind of identifier this is. Today always `email`.
+             */
             type: "email";
+            /**
+             * The address as the user typed it, for display.
+             */
             value: string;
+            /**
+             * Whether this is the identifier the user signs in with and is contacted at.
+             */
             isPrimary: boolean;
+            /**
+             * When this address was verified (ISO 8601). Null while it never was.
+             */
             verifiedAt: (string | null);
+            /**
+             * The address lowercased and NFC-normalised — what uniqueness is checked against.
+             */
             valueCanonical: string;
+            /**
+             * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+             */
             verificationStatus: ("unverified" | "verified" | "expired");
         }[];
+        /**
+         * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+         */
         lockedUntil: (string | null);
+        /**
+         * When the user last signed in (ISO 8601). Null if they never have.
+         */
         lastSignInAt: (string | null);
+        /**
+         * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+         */
+        primaryEmail: (string | null);
+        /**
+         * Whether the user must set a new password at their next sign-in.
+         */
         requiresReset: boolean;
-        publicMetadata: UsersUsersListOutputPublicMetadata;
-        unsafeMetadata: UsersUsersListOutputPublicMetadata;
-        privateMetadata: UsersUsersListOutputPublicMetadata;
+        /**
+         * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+         */
+        publicMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Metadata the end user may write themselves. Treat it as untrusted.
+         */
+        unsafeMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Metadata for the management plane only. Never reaches the end user or a token.
+         */
+        privateMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Id of the primary identifier row. Null when there is no primary identifier.
+         */
+        primaryIdentifierId: (string | null);
+        /**
+         * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+         */
         emailChangeLockedUntil: (string | null);
     }[];
+    /**
+     * Pass back as `cursor` to fetch the next page. Null when this page is the last.
+     */
     nextCursor: (string | null);
 }
-export interface UsersUsersListOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersSetPrimaryIdentifierInput {
     /**
      * The address to make primary. Must not already belong, verified, to another user of this product.
@@ -118898,7 +120488,13 @@ export interface UsersUsersSetPrimaryIdentifierInput {
     userId: string;
 }
 export interface UsersUsersSetPrimaryIdentifierOutput {
+    /**
+     * Id of the scheduled change. It appears in the audit rows and in the abort link mailed to the old address.
+     */
     requestId: string;
+    /**
+     * When the swap becomes applicable, if nobody aborts it first (ISO 8601). The delay is this product's `emailChange.overrideDelayHours`, 72 by default.
+     */
     scheduledFor: string;
 }
 export interface UsersUsersUnbanInput {
@@ -118908,37 +120504,126 @@ export interface UsersUsersUnbanInput {
     userId: string;
 }
 export interface UsersUsersUnbanOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersUnbanOutputPublicMetadata;
-    unsafeMetadata: UsersUsersUnbanOutputPublicMetadata;
-    privateMetadata: UsersUsersUnbanOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersUnbanOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersUpdateInput {
     /**
      * The user's display name. Pass null to clear.
@@ -118986,37 +120671,126 @@ export interface UsersUsersUpdateInputPublicMetadata1 {
     [k: string]: unknown;
 }
 export interface UsersUsersUpdateOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersUpdateOutputPublicMetadata;
-    unsafeMetadata: UsersUsersUpdateOutputPublicMetadata;
-    privateMetadata: UsersUsersUpdateOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersUpdateOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersWaitlistFunnelInput {
 }
 export interface UsersWaitlistFunnelOutput {
@@ -119194,15 +120968,42 @@ export interface UsersWaitlistImportInput {
     ];
 }
 export interface UsersWaitlistImportOutput {
+    /**
+     * How many could not be imported at all.
+     */
     failed: number;
+    /**
+     * One row per submitted row, in the order you sent them.
+     */
     results: {
+        /**
+         * Zero-based index of the row in the array you sent.
+         */
         row: number;
+        /**
+         * Why it was skipped, or what went wrong. Null for an imported row.
+         */
         reason: (string | null);
+        /**
+         * What happened to this row.
+         */
         status: ("imported" | "skipped" | "failed");
+        /**
+         * The waitlisted user this row created. Null for skipped and failed rows.
+         */
         userId: (string | null);
     }[];
+    /**
+     * How many were already on the list or otherwise passed over.
+     */
     skipped: number;
+    /**
+     * How many became waitlist entries.
+     */
     imported: number;
+    /**
+     * How many rows you submitted.
+     */
     requested: number;
 }
 export interface UsersWaitlistInviteInput {
@@ -119215,12 +121016,30 @@ export interface UsersWaitlistInviteInput {
     userIds: [string, ...(string)[]];
 }
 export interface UsersWaitlistInviteOutput {
+    /**
+     * How many of the requested users were invited.
+     */
     invited: number;
+    /**
+     * One row per user you asked for, in the order you sent them.
+     */
     results: {
+        /**
+         * Why this user was skipped. Null for an invited row.
+         */
         reason: (("suppressed" | "not_found" | "already_registered") | null);
+        /**
+         * Whether this user was invited or passed over.
+         */
         status: ("invited" | "skipped");
+        /**
+         * The user this row is about.
+         */
         userId: string;
     }[];
+    /**
+     * How many were passed over — see each row's `reason`.
+     */
     skipped: number;
 }
 export interface UsersWaitlistListInput {
@@ -119242,23 +121061,62 @@ export interface UsersWaitlistListInput {
     confirmed?: boolean;
 }
 export interface UsersWaitlistListOutput {
+    /**
+     * The page of waitlist entries, newest first.
+     */
     entries: {
+        /**
+         * Where in the funnel this entry is: `pending`, `invited`, `registered` or `withdrawn`.
+         */
         status: ("pending" | "invited" | "registered" | "withdrawn");
+        /**
+         * The waitlisted user. Every users_users_* tool takes this id.
+         */
         userId: string;
+        /**
+         * When the entry joined the waitlist (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * When the invite was sent (ISO 8601). Null while the entry is pending.
+         */
         invitedAt: (string | null);
+        /**
+         * The email address that signed up.
+         */
         identifier: string;
+        /**
+         * Where the signup came from — the campaign, referrer and landing page recorded at the time.
+         */
         attribution: {
             [k: string]: unknown;
         };
+        /**
+         * When the address confirmed a double opt-in (ISO 8601). Null when it never did.
+         */
         confirmedAt: (string | null);
+        /**
+         * When the address asked to be taken off the list (ISO 8601). Null when it did not.
+         */
         withdrawnAt: (string | null);
+        /**
+         * What was recorded to show this address consented: when, from where, and under which wording.
+         */
         consentProof: {
             [k: string]: unknown;
         };
+        /**
+         * When the invitee finished signing up (ISO 8601). Null until they do.
+         */
         registeredAt: (string | null);
+        /**
+         * Id of the live invite token. Null while the entry has not been invited.
+         */
         inviteTokenId: (string | null);
     }[];
+    /**
+     * Pass back as `cursor` to fetch the next page. Null when this page is the last.
+     */
     nextCursor: (string | null);
 }
 export interface UsersWebhooksCreateInput {