@smartytalent/mcp-tools 0.1.33-dev.1 → 0.1.33-dev.10

package/dist/tools.json

@@ -43,7 +43,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -799,7 +799,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -1540,7 +1540,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -1882,7 +1882,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -2150,7 +2150,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -3367,7 +3367,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -4632,7 +4632,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -5873,7 +5873,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -6168,7 +6168,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -6430,7 +6430,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -6729,6 +6729,32 @@
           "type": "string",
           "description": "Return only emails belonging to this conversation. Resolved via the ConversationIdIndex GSI (top-level denormalisation of relationships.conversations[0].data.id). Pass the full conversation id (e.g. `980434e7...-2`)."
         },
+        "filterDirection": {
+          "type": "string",
+          "description": "Return only emails with this direction. `inbound` = received from an external sender (Inbox), `outbound` = composed by the tenant (Sent). Resolved via the DirectionIndex GSI. Mutually exclusive with `filterStatus` and `filterConversationId` at the pagination layer.",
+          "enum": [
+            "inbound",
+            "outbound"
+          ]
+        },
+        "filterIds": {
+          "type": "string",
+          "description": "Batch-fetch emails by id. Pass a comma-separated list (e.g. `abc-1,def-2,ghi-3`). Resolves each id's shard from its suffix and issues a BatchGetItem. Used by the inbox UI to hydrate emails referenced by state rows (folder=unseen / starred / spam) without N showEmail calls. Cap: 500 ids per request; beyond that, page the state list and batch again. Bypasses pagination - the returned `data` is the full batch result with no `nextPage` cursor."
+        },
+        "filterIsSystemSpam": {
+          "type": "boolean",
+          "description": "Return only emails the system (broker / classifier) flagged as spam. Used by the Spam folder's `isSystemSpam=true` leg - the other leg comes from `/v1/states?folder=spam`. Backed by a filter-expression scan across shards for v1; promote to a sparse `SystemSpamIndex` if load warrants. Mutually exclusive with the other index-backed filters at the pagination layer."
+        },
+        "sort": {
+          "type": "string",
+          "description": "Order results by a time field. Leading `-` means descending\n(newest-first). Accepted values:\n  `-created`  newest-first by creation time (CreatedIndex)\n  `created`   oldest-first by creation time\n  `-modified` most-recently-modified first (ModifiedIndex)\n  `modified`  least-recently-modified first\nTakes effect only when no equality filter (filterStatus,\nfilterConversationId, filterDirection) dictates a different\nindex; equality filters win. Compatible with date-range filters\n(filterCreatedFrom/To, filterModifiedFrom/To) which already use\nthe same indexes; sort just picks the direction.",
+          "enum": [
+            "-created",
+            "created",
+            "-modified",
+            "modified"
+          ]
+        },
         "filterCreatedFrom": {
           "type": "string",
           "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format."
@@ -6755,7 +6781,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -6801,7 +6827,25 @@
                   "type": "string"
                 },
                 "status": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": [
+                    "draft",
+                    "scheduled",
+                    "sent",
+                    "suppressed",
+                    "archived",
+                    "failed",
+                    "pending"
+                  ],
+                  "description": "Lifecycle status. draft = composing, scheduled = workflow owns the send, sent = delivered to SES, suppressed = SES bounce/complaint, archived = user soft-deleted, failed = internal error, pending = transitional."
+                },
+                "direction": {
+                  "type": "string",
+                  "enum": [
+                    "inbound",
+                    "outbound"
+                  ],
+                  "description": "Whether the email was received from an external sender (inbound, populated by the broker) or composed by the tenant/system and sent out (outbound). Populated at create time; never changes."
                 },
                 "emailFrom": {
                   "type": "string"
@@ -6809,27 +6853,33 @@
                 "emailTo": {
                   "type": "string"
                 },
+                "emailCc": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "CC recipients. Each entry is an RFC 5322 address string."
+                },
+                "emailBcc": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "BCC recipients. Each entry is an RFC 5322 address string."
+                },
                 "subject": {
-                  "oneOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "additionalProperties": true
-                    }
-                  ]
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Multilingual subject keyed by IETF BCP 47 locale code (e.g. `en-US`, `pl-PL`). The DAL writes per-locale entries from the AI analyze + translate steps; the UI picks the right key based on `conversationLanguageCode`."
                 },
                 "body": {
-                  "oneOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "additionalProperties": true
-                    }
-                  ]
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Multilingual HTML body keyed by IETF BCP 47 locale code. Same shape as `subject`. Body values are HTML strings; plain-text fallback is derived on send."
                 },
                 "shortCode": {
                   "type": "string"
@@ -6846,11 +6896,78 @@
                 "isExternalSender": {
                   "type": "boolean"
                 },
+                "attachments": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "fileName": {
+                        "type": "string",
+                        "description": "Display name shown in the mail client and used as the attachment filename on send."
+                      },
+                      "url": {
+                        "type": "string",
+                        "description": "S3 URL of the stored file. For user-uploaded attachments this is the path returned by POST /v1/files; for system-generated attachments (job/persona/report PDFs) it is the resource's own S3 path."
+                      },
+                      "type": {
+                        "type": "string",
+                        "description": "Resource type this attachment belongs to. User-uploaded attachments use `files`; system-generated attachments use the owning resource type: `jobs`, `personas`, `talents`, `candidates`, `reports`, `ads`."
+                      },
+                      "fileId": {
+                        "type": "string",
+                        "description": "When `type == \"files\"`, the file resource ID so the frontend can resolve the latest file metadata (status, processing state) without parsing the URL."
+                      },
+                      "size": {
+                        "type": "integer",
+                        "description": "File size in bytes. Frontend displays it in the compose preview and mail list. Set by the upload flow from the Content-Length of the S3 object; absent on legacy rows."
+                      },
+                      "contentType": {
+                        "type": "string",
+                        "description": "MIME type (e.g. `application/pdf`, `image/png`). Drives icon selection in the UI and the Content-Type header in the outbound MIME part. Absent on legacy rows; frontend should fall back to extension inference."
+                      },
+                      "thumbnailUrl": {
+                        "type": "string",
+                        "description": "Optional S3 URL of a PNG preview (first-page render for PDFs/DOCX). Populated by the file service's conversion pipeline when a preview is available. Absent for non-previewable types."
+                      }
+                    }
+                  },
+                  "description": "Attachments on the email. For user-uploaded attachments: frontend creates a File via POST /v1/files (which returns a presigned PUT URL), uploads to S3, then references the File here with `type: \"files\"` and the returned `url`/`fileId`. For system-generated attachments (job/persona/report PDFs) the eventbus / outbound path populates these automatically."
+                },
+                "conversationLanguageCode": {
+                  "type": "string",
+                  "description": "Denormalised copy of the related conversation's languageCode (e.g. `pl-PL`, `en-US`). Avoids an N+1 fetch when the list/detail view needs to pick the right locale for the multilingual subject/body dicts. Source of truth is the conversation row; read-only from the email's perspective."
+                },
+                "parentEmailId": {
+                  "type": "string",
+                  "description": "Application-layer pointer to the email this one replies to. Used by the UI to render an 'in reply to' link in thread views. Set by the compose flow (frontend passes the parent on Reply) and by the broker when an inbound email matches an outbound via RFC 5322 In-Reply-To. Separate from meta.reference which carries the raw SMTP header chain."
+                },
+                "fromUserId": {
+                  "type": "string",
+                  "description": "Denormalised user id of the sender for outbound emails (the boe workflow user, or the human composer). Frontend joins this against its local user cache to render avatar + display name without a per-row API call. Null on inbound mail."
+                },
+                "fromCandidateId": {
+                  "type": "string",
+                  "description": "Denormalised candidate id of the sender for inbound replies from a candidate in an active conversation. Frontend joins this against its local candidate cache to render initials and the candidate name. Null on outbound mail and on anonymous inbound that didn't match a candidate."
+                },
+                "isSystemSpam": {
+                  "type": "boolean",
+                  "description": "System-level spam verdict on this email. Set by the broker (or a future classifier) at inbound time; never reflects a single user's opinion. Distinct from `status=suppressed`, which is SES reporting we cannot deliver on OUTBOUND. Frontend's Spam folder unions (my states where isSpam=true) with (emails where isSystemSpam=true)."
+                },
+                "scheduleId": {
+                  "type": "string",
+                  "description": "Foreign key to the Schedule resource driving this email's send. Populated by the wait:process workflow action right after it creates the Schedule. Null when no delayed send is pending (drafts, already-sent rows, inbound mail). To cancel the scheduled send, call DELETE /v1/schedules/{scheduleId} - the email eventbus handler listens for SCHEDULE_CANCELLED and reverts the row back to draft automatically."
+                },
+                "scheduledFireAt": {
+                  "type": "string",
+                  "description": "Denormalised copy of the owning Schedule's `fireAt` timestamp (ISO 8601). The scheduled-send banner reads this directly so the UI never has to round-trip to /v1/schedules just to render 'Send scheduled for X'. Source of truth is the Schedule; this field stays stable because Schedule.fireAt is immutable post-create."
+                },
                 "ttl": {
                   "type": "string"
                 },
                 "sendScheduleDate": {
-                  "type": "string"
+                  "type": "string",
+                  "deprecated": true,
+                  "description": "Legacy field from the retired CRUD-scheduler path. Kept as read-only metadata on old rows. New emails do not populate it; scheduling is owned by the workflow engine's wait:process action via the Schedule resource."
                 },
                 "meta": {
                   "type": "object",
@@ -6971,6 +7088,25 @@
                       }
                     }
                   }
+                },
+                "schedule": {
+                  "title": "EmailRelationshipsScheduleSchema",
+                  "type": "object",
+                  "description": "The Schedule arming this email's delayed send. Denormalised mirror of scheduleId so clients can `?include=schedule` in a single request. Populated by the email eventbus handler reacting to SCHEDULE_CREATED. Null while the email is draft / already-sent / inbound.",
+                  "properties": {
+                    "data": {
+                      "title": "EmailRelationshipsScheduleDataSchema",
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string"
+                        },
+                        "id": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
                 }
               }
             },
@@ -7050,7 +7186,25 @@
                   "type": "string"
                 },
                 "status": {
-                  "type": "string"
+                  "type": "string",
+                  "enum": [
+                    "draft",
+                    "scheduled",
+                    "sent",
+                    "suppressed",
+                    "archived",
+                    "failed",
+                    "pending"
+                  ],
+                  "description": "Lifecycle status. draft = composing, scheduled = workflow owns the send, sent = delivered to SES, suppressed = SES bounce/complaint, archived = user soft-deleted, failed = internal error, pending = transitional."
+                },
+                "direction": {
+                  "type": "string",
+                  "enum": [
+                    "inbound",
+                    "outbound"
+                  ],
+                  "description": "Whether the email was received from an external sender (inbound, populated by the broker) or composed by the tenant/system and sent out (outbound). Populated at create time; never changes."
                 },
                 "emailFrom": {
                   "type": "string"
@@ -7058,27 +7212,33 @@
                 "emailTo": {
                   "type": "string"
                 },
+                "emailCc": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "CC recipients. Each entry is an RFC 5322 address string."
+                },
+                "emailBcc": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "BCC recipients. Each entry is an RFC 5322 address string."
+                },
                 "subject": {
-                  "oneOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "additionalProperties": true
-                    }
-                  ]
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Multilingual subject keyed by IETF BCP 47 locale code (e.g. `en-US`, `pl-PL`). The DAL writes per-locale entries from the AI analyze + translate steps; the UI picks the right key based on `conversationLanguageCode`."
                 },
                 "body": {
-                  "oneOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "additionalProperties": true
-                    }
-                  ]
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Multilingual HTML body keyed by IETF BCP 47 locale code. Same shape as `subject`. Body values are HTML strings; plain-text fallback is derived on send."
                 },
                 "shortCode": {
                   "type": "string"
@@ -7095,11 +7255,78 @@
                 "isExternalSender": {
                   "type": "boolean"
                 },
+                "attachments": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "fileName": {
+                        "type": "string",
+                        "description": "Display name shown in the mail client and used as the attachment filename on send."
+                      },
+                      "url": {
+                        "type": "string",
+                        "description": "S3 URL of the stored file. For user-uploaded attachments this is the path returned by POST /v1/files; for system-generated attachments (job/persona/report PDFs) it is the resource's own S3 path."
+                      },
+                      "type": {
+                        "type": "string",
+                        "description": "Resource type this attachment belongs to. User-uploaded attachments use `files`; system-generated attachments use the owning resource type: `jobs`, `personas`, `talents`, `candidates`, `reports`, `ads`."
+                      },
+                      "fileId": {
+                        "type": "string",
+                        "description": "When `type == \"files\"`, the file resource ID so the frontend can resolve the latest file metadata (status, processing state) without parsing the URL."
+                      },
+                      "size": {
+                        "type": "integer",
+                        "description": "File size in bytes. Frontend displays it in the compose preview and mail list. Set by the upload flow from the Content-Length of the S3 object; absent on legacy rows."
+                      },
+                      "contentType": {
+                        "type": "string",
+                        "description": "MIME type (e.g. `application/pdf`, `image/png`). Drives icon selection in the UI and the Content-Type header in the outbound MIME part. Absent on legacy rows; frontend should fall back to extension inference."
+                      },
+                      "thumbnailUrl": {
+                        "type": "string",
+                        "description": "Optional S3 URL of a PNG preview (first-page render for PDFs/DOCX). Populated by the file service's conversion pipeline when a preview is available. Absent for non-previewable types."
+                      }
+                    }
+                  },
+                  "description": "Attachments on the email. For user-uploaded attachments: frontend creates a File via POST /v1/files (which returns a presigned PUT URL), uploads to S3, then references the File here with `type: \"files\"` and the returned `url`/`fileId`. For system-generated attachments (job/persona/report PDFs) the eventbus / outbound path populates these automatically."
+                },
+                "conversationLanguageCode": {
+                  "type": "string",
+                  "description": "Denormalised copy of the related conversation's languageCode (e.g. `pl-PL`, `en-US`). Avoids an N+1 fetch when the list/detail view needs to pick the right locale for the multilingual subject/body dicts. Source of truth is the conversation row; read-only from the email's perspective."
+                },
+                "parentEmailId": {
+                  "type": "string",
+                  "description": "Application-layer pointer to the email this one replies to. Used by the UI to render an 'in reply to' link in thread views. Set by the compose flow (frontend passes the parent on Reply) and by the broker when an inbound email matches an outbound via RFC 5322 In-Reply-To. Separate from meta.reference which carries the raw SMTP header chain."
+                },
+                "fromUserId": {
+                  "type": "string",
+                  "description": "Denormalised user id of the sender for outbound emails (the boe workflow user, or the human composer). Frontend joins this against its local user cache to render avatar + display name without a per-row API call. Null on inbound mail."
+                },
+                "fromCandidateId": {
+                  "type": "string",
+                  "description": "Denormalised candidate id of the sender for inbound replies from a candidate in an active conversation. Frontend joins this against its local candidate cache to render initials and the candidate name. Null on outbound mail and on anonymous inbound that didn't match a candidate."
+                },
+                "isSystemSpam": {
+                  "type": "boolean",
+                  "description": "System-level spam verdict on this email. Set by the broker (or a future classifier) at inbound time; never reflects a single user's opinion. Distinct from `status=suppressed`, which is SES reporting we cannot deliver on OUTBOUND. Frontend's Spam folder unions (my states where isSpam=true) with (emails where isSystemSpam=true)."
+                },
+                "scheduleId": {
+                  "type": "string",
+                  "description": "Foreign key to the Schedule resource driving this email's send. Populated by the wait:process workflow action right after it creates the Schedule. Null when no delayed send is pending (drafts, already-sent rows, inbound mail). To cancel the scheduled send, call DELETE /v1/schedules/{scheduleId} - the email eventbus handler listens for SCHEDULE_CANCELLED and reverts the row back to draft automatically."
+                },
+                "scheduledFireAt": {
+                  "type": "string",
+                  "description": "Denormalised copy of the owning Schedule's `fireAt` timestamp (ISO 8601). The scheduled-send banner reads this directly so the UI never has to round-trip to /v1/schedules just to render 'Send scheduled for X'. Source of truth is the Schedule; this field stays stable because Schedule.fireAt is immutable post-create."
+                },
                 "ttl": {
                   "type": "string"
                 },
                 "sendScheduleDate": {
-                  "type": "string"
+                  "type": "string",
+                  "deprecated": true,
+                  "description": "Legacy field from the retired CRUD-scheduler path. Kept as read-only metadata on old rows. New emails do not populate it; scheduling is owned by the workflow engine's wait:process action via the Schedule resource."
                 },
                 "meta": {
                   "type": "object",
@@ -7197,7 +7424,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -7486,7 +7713,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -8373,7 +8600,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -8577,6 +8804,24 @@
                       }
                     }
                   }
+                },
+                "email": {
+                  "title": "ScheduleRelationshipsEmailSchema",
+                  "type": "object",
+                  "description": "The email this schedule was armed for. Set by wait:process so the email service can denormalise scheduleId back onto the email row when SCHEDULE_CREATED fires.",
+                  "properties": {
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string"
+                        },
+                        "id": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -8824,6 +9069,24 @@
                           }
                         }
                       }
+                    },
+                    "email": {
+                      "title": "ScheduleRelationshipsEmailSchema",
+                      "type": "object",
+                      "description": "The email this schedule was armed for. Set by wait:process so the email service can denormalise scheduleId back onto the email row when SCHEDULE_CREATED fires.",
+                      "properties": {
+                        "data": {
+                          "type": "object",
+                          "properties": {
+                            "type": {
+                              "type": "string"
+                            },
+                            "id": {
+                              "type": "string"
+                            }
+                          }
+                        }
+                      }
                     }
                   }
                 }
@@ -9176,7 +9439,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -9909,7 +10172,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -10232,7 +10495,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -10497,7 +10760,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -10942,7 +11205,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -11275,7 +11538,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -11603,7 +11866,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -11642,33 +11905,689 @@
               ]
             },
             "attributes": {
-              "title": "NoteAttributesSchema",
+              "title": "NoteAttributesSchema",
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "status": {
+                  "type": "string"
+                },
+                "details": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Multilingual note details keyed by language code"
+                },
+                "source": {
+                  "type": "string",
+                  "description": "Source of the note"
+                },
+                "ttl": {
+                  "type": "string",
+                  "description": "Time-to-live expiration timestamp"
+                },
+                "meta": {
+                  "type": "object",
+                  "additionalProperties": true
+                },
+                "timestamps": {
+                  "title": "ResourceTimestampsSchema",
+                  "type": "object",
+                  "properties": {
+                    "created": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "modified": {
+                      "type": "string",
+                      "format": "date-time"
+                    }
+                  }
+                }
+              }
+            },
+            "relationships": {
+              "title": "NoteRelationshipsSchema",
+              "type": "object",
+              "properties": {
+                "candidate": {
+                  "title": "NoteRelationshipsCandidateSchema",
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "title": "NoteRelationshipsCandidateDataSchema",
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string"
+                        },
+                        "id": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
+                },
+                "translations": {
+                  "title": "NoteRelationshipsTranslationsSchema",
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "title": "NoteRelationshipsTranslationsDataSchema",
+                        "type": "object",
+                        "properties": {
+                          "type": {
+                            "type": "string"
+                          },
+                          "id": {
+                            "type": "string"
+                          }
+                        }
+                      }
+                    }
+                  }
+                },
+                "report": {
+                  "title": "NoteRelationshipsReportSchema",
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "title": "NoteRelationshipsReportDataSchema",
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string"
+                        },
+                        "id": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
+                },
+                "operation": {
+                  "title": "NoteRelationshipsOperationSchema",
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "title": "NoteRelationshipsOperationDataSchema",
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string"
+                        },
+                        "id": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "_meta": {
+      "method": "POST",
+      "path": "/v1/notes",
+      "operationId": "createNote"
+    }
+  },
+  {
+    "name": "notes_options",
+    "description": "Notes Options",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    },
+    "_meta": {
+      "method": "OPTIONS",
+      "path": "/v1/notes",
+      "operationId": "notesOptions"
+    }
+  },
+  {
+    "name": "show_note",
+    "description": "Show Note",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    },
+    "_meta": {
+      "method": "GET",
+      "path": "/v1/notes/{noteId}",
+      "operationId": "showNote"
+    }
+  },
+  {
+    "name": "update_note",
+    "description": "Update Note",
+    "inputSchema": {
+      "title": "UpdateNoteRequestBody",
+      "type": "object",
+      "required": [
+        "data"
+      ],
+      "properties": {
+        "data": {
+          "title": "UpdateNoteRequestBodyData",
+          "type": "object",
+          "required": [
+            "type",
+            "id",
+            "attributes"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "notes"
+              ]
+            },
+            "id": {
+              "type": "string"
+            },
+            "attributes": {
+              "title": "NoteAttributesSchema",
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "status": {
+                  "type": "string"
+                },
+                "details": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Multilingual note details keyed by language code"
+                },
+                "source": {
+                  "type": "string",
+                  "description": "Source of the note"
+                },
+                "ttl": {
+                  "type": "string",
+                  "description": "Time-to-live expiration timestamp"
+                },
+                "meta": {
+                  "type": "object",
+                  "additionalProperties": true
+                },
+                "timestamps": {
+                  "title": "ResourceTimestampsSchema",
+                  "type": "object",
+                  "properties": {
+                    "created": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "modified": {
+                      "type": "string",
+                      "format": "date-time"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "_meta": {
+      "method": "PATCH",
+      "path": "/v1/notes/{noteId}",
+      "operationId": "updateNote"
+    }
+  },
+  {
+    "name": "delete_note",
+    "description": "Delete Note",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    },
+    "_meta": {
+      "method": "DELETE",
+      "path": "/v1/notes/{noteId}",
+      "operationId": "deleteNote"
+    }
+  },
+  {
+    "name": "note_options",
+    "description": "Note Options",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    },
+    "_meta": {
+      "method": "OPTIONS",
+      "path": "/v1/notes/{noteId}",
+      "operationId": "noteOptions"
+    }
+  },
+  {
+    "name": "list_states",
+    "description": "List States",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "filterResourceType": {
+          "type": "string",
+          "description": "Only return states for this resource type.",
+          "enum": [
+            "emails",
+            "candidates",
+            "conversations",
+            "jobs",
+            "talents",
+            "personas",
+            "reports",
+            "tasks"
+          ]
+        },
+        "filterResourceIds": {
+          "type": "string",
+          "description": "Comma-separated list of resource ids to batch-fetch. Requires `filterResourceType`."
+        },
+        "folder": {
+          "type": "string",
+          "description": "Folder-style filter. Tagged-union: the fixed folders are an enum,\nand the label folder is a `label:<labelId>` template. Orthogonal\nto filterResourceType and filterResourceIds which scope within\nthe folder.\n\nFixed folders:\n  `all`     - default, no folder filter\n  `unseen`  - only unread rows (sparse UnseenIndex)\n  `starred` - only starred rows (sparse StarredIndex)\n  `spam`    - only user-spam-marked rows (sparse SpamIndex)\n\nLabel folder:\n  `label:<labelId>` - rows whose `flags.labels` contains labelId\n\nTypeScript callers should narrow this to\n`'all' | 'unseen' | 'starred' | 'spam' | \\`label:${string}\\``\nin their client wrapper; OpenAPI cannot express template-literal\nunions natively."
+        },
+        "pageSize": {
+          "type": "integer",
+          "description": "Specifies the number of items to retrieve per page. The maximum value is 100."
+        },
+        "pageAfter": {
+          "type": "string",
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
+        },
+        "pageBefore": {
+          "type": "string",
+          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+        }
+      }
+    },
+    "_meta": {
+      "method": "GET",
+      "path": "/v1/states",
+      "operationId": "listStates"
+    }
+  },
+  {
+    "name": "create_state",
+    "description": "Upsert State",
+    "inputSchema": {
+      "title": "CreateStateRequestBody",
+      "type": "object",
+      "required": [
+        "data"
+      ],
+      "properties": {
+        "data": {
+          "title": "CreateStateRequestBodyData",
+          "type": "object",
+          "required": [
+            "type",
+            "attributes"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "states"
+              ]
+            },
+            "attributes": {
+              "title": "StateAttributesSchema",
+              "type": "object",
+              "properties": {
+                "userId": {
+                  "type": "string",
+                  "description": "Owner of this state row. Always the authenticated user; never set by the client."
+                },
+                "resourceType": {
+                  "type": "string",
+                  "enum": [
+                    "emails",
+                    "candidates",
+                    "conversations",
+                    "jobs",
+                    "talents",
+                    "personas",
+                    "reports",
+                    "tasks"
+                  ],
+                  "description": "The kind of resource this state describes. Lives in the composite id as `{resourceType}:{resourceId}`."
+                },
+                "resourceId": {
+                  "type": "string",
+                  "description": "Id of the resource this state describes (e.g. an emailId, candidateId)."
+                },
+                "isSeen": {
+                  "type": "boolean",
+                  "description": "True if the user has opened the resource at least once. Derived from the presence of `seenAt`; clients can write either `isSeen` or `seenAt` on upsert."
+                },
+                "isStarred": {
+                  "type": "boolean",
+                  "description": "True if the user has starred/favourited the resource."
+                },
+                "isSpam": {
+                  "type": "boolean",
+                  "description": "True if the user marked this resource as spam. Distinct from the email service's `suppressed` status, which is SES-driven on outbound delivery; this is an inbound, per-user action."
+                },
+                "seenAt": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp of the user's most recent open. Absent means never seen."
+                },
+                "starredAt": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp of when the user starred the resource. Absent means not starred; used as the sort key for the `Starred` folder."
+                },
+                "spamAt": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp of when the user marked the resource as spam. Absent means not spam; used as the sort key for the `Spam` folder."
+                },
+                "resourceCreatedAt": {
+                  "type": "string",
+                  "description": "Denormalised copy of the underlying resource's own `created` timestamp. Used as the sparse unread-index sort key so the unread feed surfaces oldest resources first, not oldest state rows."
+                },
+                "flags": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "description": "Open-ended per-resource flags (e.g. `{muted: true}` on conversations, `{pinned: true}` on candidates). First-class state goes on the top-level attributes; ad-hoc state lives here."
+                },
+                "timestamps": {
+                  "title": "ResourceTimestampsSchema",
+                  "type": "object",
+                  "properties": {
+                    "created": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "modified": {
+                      "type": "string",
+                      "format": "date-time"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "_meta": {
+      "method": "POST",
+      "path": "/v1/states",
+      "operationId": "createState"
+    }
+  },
+  {
+    "name": "states_options",
+    "description": "States Options",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    },
+    "_meta": {
+      "method": "OPTIONS",
+      "path": "/v1/states",
+      "operationId": "statesOptions"
+    }
+  },
+  {
+    "name": "show_state",
+    "description": "Show State",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    },
+    "_meta": {
+      "method": "GET",
+      "path": "/v1/states/{stateId}",
+      "operationId": "showState"
+    }
+  },
+  {
+    "name": "update_state",
+    "description": "Update State",
+    "inputSchema": {
+      "title": "UpdateStateRequestBody",
+      "type": "object",
+      "required": [
+        "data"
+      ],
+      "properties": {
+        "data": {
+          "title": "UpdateStateRequestBodyData",
+          "type": "object",
+          "required": [
+            "type",
+            "id",
+            "attributes"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "states"
+              ]
+            },
+            "id": {
+              "type": "string"
+            },
+            "attributes": {
+              "title": "StateAttributesSchema",
+              "type": "object",
+              "properties": {
+                "userId": {
+                  "type": "string",
+                  "description": "Owner of this state row. Always the authenticated user; never set by the client."
+                },
+                "resourceType": {
+                  "type": "string",
+                  "enum": [
+                    "emails",
+                    "candidates",
+                    "conversations",
+                    "jobs",
+                    "talents",
+                    "personas",
+                    "reports",
+                    "tasks"
+                  ],
+                  "description": "The kind of resource this state describes. Lives in the composite id as `{resourceType}:{resourceId}`."
+                },
+                "resourceId": {
+                  "type": "string",
+                  "description": "Id of the resource this state describes (e.g. an emailId, candidateId)."
+                },
+                "isSeen": {
+                  "type": "boolean",
+                  "description": "True if the user has opened the resource at least once. Derived from the presence of `seenAt`; clients can write either `isSeen` or `seenAt` on upsert."
+                },
+                "isStarred": {
+                  "type": "boolean",
+                  "description": "True if the user has starred/favourited the resource."
+                },
+                "isSpam": {
+                  "type": "boolean",
+                  "description": "True if the user marked this resource as spam. Distinct from the email service's `suppressed` status, which is SES-driven on outbound delivery; this is an inbound, per-user action."
+                },
+                "seenAt": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp of the user's most recent open. Absent means never seen."
+                },
+                "starredAt": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp of when the user starred the resource. Absent means not starred; used as the sort key for the `Starred` folder."
+                },
+                "spamAt": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp of when the user marked the resource as spam. Absent means not spam; used as the sort key for the `Spam` folder."
+                },
+                "resourceCreatedAt": {
+                  "type": "string",
+                  "description": "Denormalised copy of the underlying resource's own `created` timestamp. Used as the sparse unread-index sort key so the unread feed surfaces oldest resources first, not oldest state rows."
+                },
+                "flags": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "description": "Open-ended per-resource flags (e.g. `{muted: true}` on conversations, `{pinned: true}` on candidates). First-class state goes on the top-level attributes; ad-hoc state lives here."
+                },
+                "timestamps": {
+                  "title": "ResourceTimestampsSchema",
+                  "type": "object",
+                  "properties": {
+                    "created": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "modified": {
+                      "type": "string",
+                      "format": "date-time"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "_meta": {
+      "method": "PATCH",
+      "path": "/v1/states/{stateId}",
+      "operationId": "updateState"
+    }
+  },
+  {
+    "name": "delete_state",
+    "description": "Delete State",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    },
+    "_meta": {
+      "method": "DELETE",
+      "path": "/v1/states/{stateId}",
+      "operationId": "deleteState"
+    }
+  },
+  {
+    "name": "state_options",
+    "description": "State Options",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    },
+    "_meta": {
+      "method": "OPTIONS",
+      "path": "/v1/states/{stateId}",
+      "operationId": "stateOptions"
+    }
+  },
+  {
+    "name": "list_labels",
+    "description": "List Labels",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "filterStatus": {
+          "type": "string",
+          "description": "filterStatus parameter",
+          "enum": [
+            "active",
+            "archived"
+          ]
+        },
+        "pageSize": {
+          "type": "integer",
+          "description": "Specifies the number of items to retrieve per page. The maximum value is 100."
+        }
+      }
+    },
+    "_meta": {
+      "method": "GET",
+      "path": "/v1/labels",
+      "operationId": "listLabels"
+    }
+  },
+  {
+    "name": "create_label",
+    "description": "Create Label",
+    "inputSchema": {
+      "title": "CreateLabelRequestBody",
+      "type": "object",
+      "required": [
+        "data"
+      ],
+      "properties": {
+        "data": {
+          "title": "CreateLabelRequestBodyData",
+          "type": "object",
+          "required": [
+            "type",
+            "attributes"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "labels"
+              ]
+            },
+            "attributes": {
+              "title": "LabelAttributesSchema",
               "type": "object",
               "properties": {
                 "name": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "Display name. Unique within a scope by convention but not enforced."
                 },
-                "status": {
-                  "type": "string"
+                "color": {
+                  "type": "string",
+                  "description": "Hex or CSS-named color the UI uses to render the label pill."
                 },
-                "details": {
-                  "type": "object",
-                  "additionalProperties": {
-                    "type": "string"
-                  },
-                  "description": "Multilingual note details keyed by language code"
+                "description": {
+                  "type": "string"
                 },
-                "source": {
+                "scope": {
                   "type": "string",
-                  "description": "Source of the note"
+                  "enum": [
+                    "tenant",
+                    "user"
+                  ],
+                  "description": "tenant = visible to every user in the tenant; user = visible only to the owner."
                 },
-                "ttl": {
+                "ownerId": {
                   "type": "string",
-                  "description": "Time-to-live expiration timestamp"
+                  "description": "Set server-side from the caller. Tenant-scope: tenantId. User-scope: the authenticated user's full userId."
                 },
-                "meta": {
-                  "type": "object",
-                  "additionalProperties": true
+                "resourceTypes": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Optional UI hint: if set, the frontend only exposes this label in the picker for these resource types (emails, candidates, ...). Not enforced server-side."
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "active",
+                    "archived"
+                  ],
+                  "description": "Archived labels stay readable (for historical assignments) but disappear from the default list."
                 },
                 "timestamps": {
                   "title": "ResourceTimestampsSchema",
@@ -11685,87 +12604,6 @@
                   }
                 }
               }
-            },
-            "relationships": {
-              "title": "NoteRelationshipsSchema",
-              "type": "object",
-              "properties": {
-                "candidate": {
-                  "title": "NoteRelationshipsCandidateSchema",
-                  "type": "object",
-                  "properties": {
-                    "data": {
-                      "title": "NoteRelationshipsCandidateDataSchema",
-                      "type": "object",
-                      "properties": {
-                        "type": {
-                          "type": "string"
-                        },
-                        "id": {
-                          "type": "string"
-                        }
-                      }
-                    }
-                  }
-                },
-                "translations": {
-                  "title": "NoteRelationshipsTranslationsSchema",
-                  "type": "object",
-                  "properties": {
-                    "data": {
-                      "type": "array",
-                      "items": {
-                        "title": "NoteRelationshipsTranslationsDataSchema",
-                        "type": "object",
-                        "properties": {
-                          "type": {
-                            "type": "string"
-                          },
-                          "id": {
-                            "type": "string"
-                          }
-                        }
-                      }
-                    }
-                  }
-                },
-                "report": {
-                  "title": "NoteRelationshipsReportSchema",
-                  "type": "object",
-                  "properties": {
-                    "data": {
-                      "title": "NoteRelationshipsReportDataSchema",
-                      "type": "object",
-                      "properties": {
-                        "type": {
-                          "type": "string"
-                        },
-                        "id": {
-                          "type": "string"
-                        }
-                      }
-                    }
-                  }
-                },
-                "operation": {
-                  "title": "NoteRelationshipsOperationSchema",
-                  "type": "object",
-                  "properties": {
-                    "data": {
-                      "title": "NoteRelationshipsOperationDataSchema",
-                      "type": "object",
-                      "properties": {
-                        "type": {
-                          "type": "string"
-                        },
-                        "id": {
-                          "type": "string"
-                        }
-                      }
-                    }
-                  }
-                }
-              }
             }
           }
         }
@@ -11773,48 +12611,48 @@
     },
     "_meta": {
       "method": "POST",
-      "path": "/v1/notes",
-      "operationId": "createNote"
+      "path": "/v1/labels",
+      "operationId": "createLabel"
     }
   },
   {
-    "name": "notes_options",
-    "description": "Notes Options",
+    "name": "labels_options",
+    "description": "Labels Options",
     "inputSchema": {
       "type": "object",
       "properties": {}
     },
     "_meta": {
       "method": "OPTIONS",
-      "path": "/v1/notes",
-      "operationId": "notesOptions"
+      "path": "/v1/labels",
+      "operationId": "labelsOptions"
     }
   },
   {
-    "name": "show_note",
-    "description": "Show Note",
+    "name": "show_label",
+    "description": "Show Label",
     "inputSchema": {
       "type": "object",
       "properties": {}
     },
     "_meta": {
       "method": "GET",
-      "path": "/v1/notes/{noteId}",
-      "operationId": "showNote"
+      "path": "/v1/labels/{labelId}",
+      "operationId": "showLabel"
     }
   },
   {
-    "name": "update_note",
-    "description": "Update Note",
+    "name": "update_label",
+    "description": "Update Label",
     "inputSchema": {
-      "title": "UpdateNoteRequestBody",
+      "title": "UpdateLabelRequestBody",
       "type": "object",
       "required": [
         "data"
       ],
       "properties": {
         "data": {
-          "title": "UpdateNoteRequestBodyData",
+          "title": "UpdateLabelRequestBodyData",
           "type": "object",
           "required": [
             "type",
@@ -11825,40 +12663,53 @@
             "type": {
               "type": "string",
               "enum": [
-                "notes"
+                "labels"
               ]
             },
             "id": {
               "type": "string"
             },
             "attributes": {
-              "title": "NoteAttributesSchema",
+              "title": "LabelAttributesSchema",
               "type": "object",
               "properties": {
                 "name": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "Display name. Unique within a scope by convention but not enforced."
                 },
-                "status": {
-                  "type": "string"
+                "color": {
+                  "type": "string",
+                  "description": "Hex or CSS-named color the UI uses to render the label pill."
                 },
-                "details": {
-                  "type": "object",
-                  "additionalProperties": {
-                    "type": "string"
-                  },
-                  "description": "Multilingual note details keyed by language code"
+                "description": {
+                  "type": "string"
                 },
-                "source": {
+                "scope": {
                   "type": "string",
-                  "description": "Source of the note"
+                  "enum": [
+                    "tenant",
+                    "user"
+                  ],
+                  "description": "tenant = visible to every user in the tenant; user = visible only to the owner."
                 },
-                "ttl": {
+                "ownerId": {
                   "type": "string",
-                  "description": "Time-to-live expiration timestamp"
+                  "description": "Set server-side from the caller. Tenant-scope: tenantId. User-scope: the authenticated user's full userId."
                 },
-                "meta": {
-                  "type": "object",
-                  "additionalProperties": true
+                "resourceTypes": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Optional UI hint: if set, the frontend only exposes this label in the picker for these resource types (emails, candidates, ...). Not enforced server-side."
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "active",
+                    "archived"
+                  ],
+                  "description": "Archived labels stay readable (for historical assignments) but disappear from the default list."
                 },
                 "timestamps": {
                   "title": "ResourceTimestampsSchema",
@@ -11882,34 +12733,34 @@
     },
     "_meta": {
       "method": "PATCH",
-      "path": "/v1/notes/{noteId}",
-      "operationId": "updateNote"
+      "path": "/v1/labels/{labelId}",
+      "operationId": "updateLabel"
     }
   },
   {
-    "name": "delete_note",
-    "description": "Delete Note",
+    "name": "delete_label",
+    "description": "Delete Label",
     "inputSchema": {
       "type": "object",
       "properties": {}
     },
     "_meta": {
       "method": "DELETE",
-      "path": "/v1/notes/{noteId}",
-      "operationId": "deleteNote"
+      "path": "/v1/labels/{labelId}",
+      "operationId": "deleteLabel"
     }
   },
   {
-    "name": "note_options",
-    "description": "Note Options",
+    "name": "label_options",
+    "description": "Label Options",
     "inputSchema": {
       "type": "object",
       "properties": {}
     },
     "_meta": {
       "method": "OPTIONS",
-      "path": "/v1/notes/{noteId}",
-      "operationId": "noteOptions"
+      "path": "/v1/labels/{labelId}",
+      "operationId": "labelOptions"
     }
   },
   {
@@ -11954,7 +12805,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -12531,7 +13382,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -12879,7 +13730,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -13237,7 +14088,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -13541,7 +14392,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -13793,7 +14644,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -14113,7 +14964,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -14229,7 +15080,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -14327,7 +15178,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -14429,7 +15280,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -14634,7 +15485,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -14891,7 +15742,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -14954,12 +15805,62 @@
                   "description": "The type of search to perform"
                 },
                 "query": {
-                  "type": "object",
-                  "description": "Search query parameters sent to OpenSearch. Supported keys for talent search: Semantic (full-text match) - \"search\" (multi-match across all text fields), \"name\", \"quickInsights\", \"skillsAndExpertise\", \"professionalExperience\", \"education\", \"experienceAndSeniority\", \"jobPositions\", \"keywords\", \"certifications\", \"industryExperience\", \"languagesSpoken\", \"locationPreferences\", \"personalityAndSoftSkills\", \"availability\", \"workPreferences\", \"workAuthorization\". Filters (exact match) - \"status\", \"source\", \"email\", \"gender\", \"shortCode\", \"isTalentPool\", \"relocationWillingness\", \"requiresSponsorship\", \"careerBreak\". IDs - \"jobId\", \"talentId\"."
+                  "description": "Search query parameters sent to OpenSearch. Shape varies by finder `type`. OpenAPI can't express the full type/query correlation as a strict discriminated union (the discriminator lives on the sibling `type` field, not on `query` itself), so this is encoded as `oneOf` over per-type query schemas. Clients should pick the shape matching the `type` they are posting.",
+                  "oneOf": [
+                    {
+                      "$ref": "#/components/schemas/FinderQueryTalentsSchema"
+                    },
+                    {
+                      "$ref": "#/components/schemas/FinderQueryCandidatesSchema"
+                    },
+                    {
+                      "$ref": "#/components/schemas/FinderQueryJobsSchema"
+                    },
+                    {
+                      "$ref": "#/components/schemas/FinderQueryEmailsSchema"
+                    }
+                  ]
                 },
                 "results": {
+                  "title": "FinderResultsSchema",
                   "type": "object",
-                  "description": "The search results returned from OpenSearch (auto-populated)"
+                  "description": "OpenSearch-shaped results attached to the finder record after the search runs. Hits array items carry whatever subset of the index schema was projected.",
+                  "properties": {
+                    "total": {
+                      "type": "integer",
+                      "description": "Count of matching documents before pagination."
+                    },
+                    "hits": {
+                      "type": "array",
+                      "items": {
+                        "title": "FinderResultHitSchema",
+                        "type": "object",
+                        "description": "Single hit from the OpenSearch query. The `id` equals the underlying resource id (emailId, talentId, candidateId, jobId, ...) so the frontend can navigate directly to that resource. Additional fields vary by finder `type`.",
+                        "properties": {
+                          "id": {
+                            "type": "string",
+                            "description": "The underlying resource id (emailId / talentId / candidateId / jobId)."
+                          },
+                          "tenantId": {
+                            "type": "string"
+                          },
+                          "status": {
+                            "type": "string"
+                          },
+                          "source": {
+                            "type": "string"
+                          },
+                          "created": {
+                            "type": "string"
+                          },
+                          "shortCode": {
+                            "type": "string"
+                          }
+                        },
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 },
                 "status": {
                   "type": "string",
@@ -15187,12 +16088,62 @@
                   "description": "The type of search to perform"
                 },
                 "query": {
-                  "type": "object",
-                  "description": "Search query parameters sent to OpenSearch. Supported keys for talent search: Semantic (full-text match) - \"search\" (multi-match across all text fields), \"name\", \"quickInsights\", \"skillsAndExpertise\", \"professionalExperience\", \"education\", \"experienceAndSeniority\", \"jobPositions\", \"keywords\", \"certifications\", \"industryExperience\", \"languagesSpoken\", \"locationPreferences\", \"personalityAndSoftSkills\", \"availability\", \"workPreferences\", \"workAuthorization\". Filters (exact match) - \"status\", \"source\", \"email\", \"gender\", \"shortCode\", \"isTalentPool\", \"relocationWillingness\", \"requiresSponsorship\", \"careerBreak\". IDs - \"jobId\", \"talentId\"."
+                  "description": "Search query parameters sent to OpenSearch. Shape varies by finder `type`. OpenAPI can't express the full type/query correlation as a strict discriminated union (the discriminator lives on the sibling `type` field, not on `query` itself), so this is encoded as `oneOf` over per-type query schemas. Clients should pick the shape matching the `type` they are posting.",
+                  "oneOf": [
+                    {
+                      "$ref": "#/components/schemas/FinderQueryTalentsSchema"
+                    },
+                    {
+                      "$ref": "#/components/schemas/FinderQueryCandidatesSchema"
+                    },
+                    {
+                      "$ref": "#/components/schemas/FinderQueryJobsSchema"
+                    },
+                    {
+                      "$ref": "#/components/schemas/FinderQueryEmailsSchema"
+                    }
+                  ]
                 },
                 "results": {
+                  "title": "FinderResultsSchema",
                   "type": "object",
-                  "description": "The search results returned from OpenSearch (auto-populated)"
+                  "description": "OpenSearch-shaped results attached to the finder record after the search runs. Hits array items carry whatever subset of the index schema was projected.",
+                  "properties": {
+                    "total": {
+                      "type": "integer",
+                      "description": "Count of matching documents before pagination."
+                    },
+                    "hits": {
+                      "type": "array",
+                      "items": {
+                        "title": "FinderResultHitSchema",
+                        "type": "object",
+                        "description": "Single hit from the OpenSearch query. The `id` equals the underlying resource id (emailId, talentId, candidateId, jobId, ...) so the frontend can navigate directly to that resource. Additional fields vary by finder `type`.",
+                        "properties": {
+                          "id": {
+                            "type": "string",
+                            "description": "The underlying resource id (emailId / talentId / candidateId / jobId)."
+                          },
+                          "tenantId": {
+                            "type": "string"
+                          },
+                          "status": {
+                            "type": "string"
+                          },
+                          "source": {
+                            "type": "string"
+                          },
+                          "created": {
+                            "type": "string"
+                          },
+                          "shortCode": {
+                            "type": "string"
+                          }
+                        },
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 },
                 "status": {
                   "type": "string",
@@ -15317,7 +16268,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",
@@ -15590,7 +16541,7 @@
         },
         "pageAfter": {
           "type": "string",
-          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
         },
         "pageBefore": {
           "type": "string",