@lessly/sdk-app 75.0.0 → 76.1.0

package/src/gen/types.gen.ts

@@ -65652,7 +65652,13 @@ 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
 }
 
@@ -65691,7 +65697,13 @@ 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
 }
 
@@ -65729,6 +65741,9 @@ defaultBranch: string
 }[]
 
 export interface BrainDaemonBatchStatusInput {
+/**
+ * Id of the ingestion daemon to act on, as returned by brain_daemons_list
+ */
 id: string
 }
 
@@ -65816,6 +65831,9 @@ unmeasuredCount: number
 }
 
 export interface BrainDaemonGetInput {
+/**
+ * Id of the ingestion daemon to act on, as returned by brain_daemons_list
+ */
 id: string
 }
 
@@ -65841,8 +65859,13 @@ 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
  */
@@ -65850,14 +65873,36 @@ 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
 }
 
@@ -65866,32 +65911,107 @@ 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
-byCategory: {
-[k: string]: BrainDaemonRunOutputCounts
-}
-} | null)
-routedTo: ("realtime" | "batch")
-triggered: boolean
-triggerError?: string
+/**
+ * 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
 }
-export interface BrainDaemonRunOutputCounts {
+/**
+ * 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]: {
+/**
+ * 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 BrainDaemonRunItemsInput {
 limit?: number
@@ -65911,68 +66031,212 @@ sourceKind: string
 }[]
 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
-byCategory: {
-[k: string]: BrainDaemonStatusOutputCounts
-}
-} | null)
+/**
+ * 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
 }
-export interface BrainDaemonStatusOutputCounts {
+/**
+ * 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]: {
+/**
+ * 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 BrainDaemonUpdateInput {
 id: string
@@ -66068,46 +66332,121 @@ 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
 }
 
@@ -66123,29 +66462,92 @@ 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
 }
 
@@ -66177,38 +66579,128 @@ 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
 }
 
@@ -66236,18 +66728,54 @@ 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
 }
 
@@ -66275,18 +66803,54 @@ 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
 }
 
@@ -66312,8 +66876,17 @@ 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
 }
 
@@ -66325,8 +66898,17 @@ 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
 }
 
@@ -66338,74 +66920,179 @@ 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)
 }[]
 }
@@ -66426,8 +67113,17 @@ 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 {
@@ -66435,23 +67131,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)
 }
 
@@ -66463,19 +67189,52 @@ 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
 }
 }
@@ -66492,8 +67251,17 @@ 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
 }
 
@@ -66548,6 +67316,9 @@ 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
@@ -66565,6 +67336,9 @@ days: number
  * 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
@@ -66603,27 +67377,72 @@ delivery_failed: number
  * 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)
 /**
@@ -110198,13 +111017,75 @@ 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 UsersApikeysGetInput {
+/**
+ * Id of the key to read — the `id` from users_apikeys_list.
+ */
+id: string
+}
+
+export interface UsersApikeysGetOutput {
+/**
+ * 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)
 }
 
@@ -110214,12 +111095,33 @@ 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)
 }[]
 }
@@ -110232,7 +111134,13 @@ id: string
 }
 
 export interface UsersApikeysRevokeOutput {
+/**
+ * Id of the key that was revoked.
+ */
 id: string
+/**
+ * Always true — revocation is immediate and final.
+ */
 revoked: true
 }
 
@@ -110268,21 +111176,60 @@ 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)
 }
 
@@ -111265,12 +112212,33 @@ 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)
 }[]
 }
@@ -111287,7 +112255,13 @@ 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
 }
 
@@ -111583,6 +112557,52 @@ signInFailureBaseline: (number | null)
 }
 }
 
+export interface UsersPasskeysGetInput {
+/**
+ * The end user the credential belongs to.
+ */
+userId: string
+/**
+ * Which credential to read — the `id` from `users_passkeys_list`.
+ */
+passkeyId: string
+}
+
+export interface UsersPasskeysGetOutput {
+/**
+ * Id of the credential. Pass it to users_passkeys_revoke.
+ */
+id: string
+/**
+ * The name the user gave this credential, so a person can tell their devices apart. Null when they never named it.
+ */
+name: (string | null)
+/**
+ * The authenticator MODEL’s identifier, which says what kind of device this is, never which one. Null when the authenticator withheld it.
+ */
+aaguid: (string | null)
+/**
+ * True when the platform syncs this credential, so it survives losing the device. False means it lives on that device alone.
+ */
+backedUp: boolean
+/**
+ * When the credential was registered (ISO 8601).
+ */
+createdAt: string
+/**
+ * The authenticator’s own counter as of the last assertion. 0 when the authenticator does not count.
+ */
+signCount: number
+/**
+ * When it last signed in (ISO 8601). Null when it never has.
+ */
+lastUsedAt: (string | null)
+/**
+ * How this authenticator can be reached. Empty when the browser reported nothing — the vocabulary is the platform’s and grows, so it is not an enum.
+ */
+transports: string[]
+}
+
 export interface UsersPasskeysListInput {
 /**
  * The end user whose passkeys to list.
@@ -111591,14 +112611,41 @@ userId: string
 }
 
 export interface UsersPasskeysListOutput {
+/**
+ * The credentials this user has registered, newest first. Empty when they have none.
+ */
 passkeys: {
+/**
+ * Id of the credential. Pass it to users_passkeys_revoke.
+ */
 id: string
+/**
+ * The name the user gave this credential, so a person can tell their devices apart. Null when they never named it.
+ */
 name: (string | null)
+/**
+ * The authenticator MODEL’s identifier, which says what kind of device this is, never which one. Null when the authenticator withheld it.
+ */
 aaguid: (string | null)
+/**
+ * True when the platform syncs this credential, so it survives losing the device. False means it lives on that device alone.
+ */
 backedUp: boolean
+/**
+ * When the credential was registered (ISO 8601).
+ */
 createdAt: string
+/**
+ * The authenticator’s own counter as of the last assertion. 0 when the authenticator does not count.
+ */
 signCount: number
+/**
+ * When it last signed in (ISO 8601). Null when it never has.
+ */
 lastUsedAt: (string | null)
+/**
+ * How this authenticator can be reached. Empty when the browser reported nothing — the vocabulary is the platform’s and grows, so it is not an enum.
+ */
 transports: string[]
 }[]
 }
@@ -111623,9 +112670,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")
 }
 
@@ -111637,7 +112693,13 @@ 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.
@@ -111647,18 +112709,45 @@ aal: ("aal1" | "aal2")
  * 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)
+/**
+ * Why the session ended, when it was revoked — e.g. `signout`, `ban`, `mfa_reset`. Null while it is live. The vocabulary is additive, so it is not an enum.
+ */
 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
 }
 
@@ -111698,16 +112787,49 @@ 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
 }[]
 }
@@ -111724,6 +112846,9 @@ sessionId?: string
 }
 
 export interface UsersSessionsRevokeOutput {
+/**
+ * How many sessions were revoked. Zero when there was nothing live to revoke.
+ */
 revoked: number
 }
 
@@ -111850,37 +112975,126 @@ 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
-emailChangeLockedUntil: (string | null)
+/**
+ * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+ */
+publicMetadata: {
+[k: string]: unknown
 }
-export interface UsersUsersBanOutputPublicMetadata {
+/**
+ * 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 UsersUsersCreateInput {
 /**
@@ -111983,37 +113197,126 @@ export interface UsersUsersCreateInputPublicMetadata1 {
 }
 
 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
-emailChangeLockedUntil: (string | null)
+/**
+ * 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
 }
-export interface UsersUsersCreateOutputPublicMetadata {
+/**
+ * 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 UsersUsersDeleteInput {
 /**
@@ -112023,37 +113326,126 @@ 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
-emailChangeLockedUntil: (string | null)
+/**
+ * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+ */
+publicMetadata: {
+[k: string]: unknown
 }
-export interface UsersUsersDeleteOutputPublicMetadata {
+/**
+ * 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 UsersUsersExportInput {
 /**
@@ -112081,40 +113473,129 @@ includeDeleted?: boolean
 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 {
 /**
@@ -112124,37 +113605,126 @@ 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
-emailChangeLockedUntil: (string | null)
+/**
+ * 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
 }
-export interface UsersUsersGetOutputPublicMetadata {
+/**
+ * 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 UsersUsersImportInput {
 /**
@@ -112167,15 +113737,42 @@ 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
 }
 
@@ -112203,9 +113800,21 @@ privateMetadata?: {
 }
 
 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
 }
 
@@ -112241,40 +113850,135 @@ 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 {
 /**
@@ -112292,7 +113996,13 @@ 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
 }
 
@@ -112304,37 +114014,126 @@ 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
-emailChangeLockedUntil: (string | null)
+/**
+ * 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
 }
-export interface UsersUsersUnbanOutputPublicMetadata {
+/**
+ * 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 UsersUsersUpdateInput {
 /**
@@ -112384,37 +114183,126 @@ export interface UsersUsersUpdateInputPublicMetadata1 {
 }
 
 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
-emailChangeLockedUntil: (string | null)
+/**
+ * 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
 }
-export interface UsersUsersUpdateOutputPublicMetadata {
+/**
+ * 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 UsersWaitlistFunnelInput {
 
@@ -112429,6 +114317,64 @@ registered: number
 unconfirmed: number
 }
 
+export interface UsersWaitlistGetInput {
+/**
+ * The waitlisted user to read — the `userId` from `users_waitlist_list`.
+ */
+userId: string
+}
+
+export interface UsersWaitlistGetOutput {
+/**
+ * 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)
+}
+
 export interface UsersWaitlistImportInput {
 /**
  * The legacy signups to import, at most 500 per call — batch client-side beyond that.
@@ -112594,15 +114540,42 @@ unsafeMetadata?: {
 }
 
 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
 }
 
@@ -112617,12 +114590,30 @@ 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
 }
 
@@ -112646,23 +114637,62 @@ 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)
 }