@wspc/cli 0.0.14 → 0.0.16

package/spec/openapi.json

@@ -1162,7 +1162,7 @@
           "expected_version": {
             "type": "integer",
             "minimum": 0,
-            "description": "Optional optimistic lock. Omit to let the server use the current version; pass only to fail the call if someone else has mutated the event since you last read. On mismatch the server returns 409 `VERSION_CONFLICT` with `extra.expected_version` and `extra.actual_version`."
+            "description": "Optional optimistic lock. Omit to let the server use the current version; pass only to fail the call if someone else has mutated the event since you last read. On mismatch the server returns 409 `VERSION_CONFLICT` and includes the current and sent versions in the message."
           },
           "title": {
             "type": "string",
@@ -1371,7 +1371,8 @@
                         "identity_verification",
                         "dkim",
                         "mail_from",
-                        "receiving_mx"
+                        "receiving_mx",
+                        "dmarc"
                       ],
                       "description": "Why this DNS record is required, when the provider returns a purpose hint."
                     },
@@ -1464,15 +1465,6 @@
           "not_found"
         ]
       },
-      "GetAttachmentQuery": {
-        "type": "object",
-        "properties": {
-          "include_deleted": {
-            "type": "string",
-            "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`."
-          }
-        }
-      },
       "EmailDomainParam": {
         "type": "object",
         "properties": {
@@ -1485,6 +1477,15 @@
           "domain"
         ]
       },
+      "GetAttachmentQuery": {
+        "type": "object",
+        "properties": {
+          "include_deleted": {
+            "type": "string",
+            "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`."
+          }
+        }
+      },
       "GetEmailQuery": {
         "type": "object",
         "properties": {
@@ -1586,7 +1587,8 @@
                           "identity_verification",
                           "dkim",
                           "mail_from",
-                          "receiving_mx"
+                          "receiving_mx",
+                          "dmarc"
                         ],
                         "description": "Why this DNS record is required, when the provider returns a purpose hint."
                       },
@@ -3359,20 +3361,17 @@
           }
         ],
         "summary": "Accept an invite and switch into the inviting organization",
-        "description": "Switches the caller's org to the invite's org and records the previous org. The caller loses access to data scoped to their previous org.",
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X POST ${EXAMPLE_API_BASE_URL}/auth/invites/inv_01KT43YKZ8CX14WS6ENXQ8397E/accept \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc invite accept inv_01KT43YKZ8CX14WS6ENXQ8397E"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -3384,9 +3383,30 @@
             "in": "path"
           }
         ],
+        "description": "Switches the caller's org to the invite's org and records the previous org. The caller loses access to data scoped to their previous org.",
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X POST ${EXAMPLE_API_BASE_URL}/auth/invites/inv_01KT43YKZ8CX14WS6ENXQ8397E/accept \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc invite accept inv_01KT43YKZ8CX14WS6ENXQ8397E"
+          }
+        ],
         "responses": {
           "200": {
             "description": "The organization the caller now belongs to.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -3733,6 +3753,18 @@
           }
         ],
         "summary": "Create a new API key (full value returned once)",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "### Overview\nCreates and provisions a new long-lived API key for the authenticated user. The complete plaintext API key value (`api_key`) is returned **only once** in this endpoint's response and cannot be retrieved again.\n\n### When to Use\n- Use this endpoint when a user requests a new API key (e.g., `wspc keys create --label \"My Agent\"`) to isolate access for specific environments, applications, or developers.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Key Limit**: A user is limited to a maximum of 25 active API keys. Requesting a new key beyond this limit will result in a `KEY_LIMIT_EXCEEDED` error.\n- **Label Validation**: The `label` parameter must be between 1 and 60 characters after trimming whitespace. Failing to provide a valid label results in an `INVALID_LABEL` error.\n\n### Troubleshooting\n- **401 Unauthorized**: The Bearer token is missing or invalid.\n- **400 Bad Request**: The `label` parameter is empty, too long, or missing.\n- **400 Bad Request (Limit Exceeded)**: The user has hit the maximum limit of 25 active keys. An existing active key must be revoked before creating a new one.",
         "x-cli": {
           "command": "keys create",
@@ -3776,6 +3808,14 @@
         "responses": {
           "200": {
             "description": "New key created. Store `api_key` securely — the full value is not available after this response.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -4120,6 +4160,18 @@
           }
         ],
         "summary": "List active API keys",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "### Overview\nReturns a list of all active (non-revoked) API keys belonging to the authenticated user. It also includes the `current_key_id` identifying the specific key used to authenticate the current request.\n\n### When to Use\n- Use this endpoint to view active API keys (e.g., when running `wspc keys list` or displaying API key management screens in user profiles).\n- Use the `current_key_id` to identify which key is making the current call, facilitating self-rotation or auditing.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Only active keys are returned; keys that have been revoked are filtered out and excluded from the response.\n- The full secret key is never returned; only the last 4 characters (`key_last4`) are provided for identification.\n\n### Troubleshooting\n- **401 Unauthorized**: The provided Bearer token is missing, expired, or invalid. Ensure you are passing a valid, active API key.",
         "x-cli": {
           "command": "keys ls",
@@ -4156,6 +4208,14 @@
         "responses": {
           "200": {
             "description": "List of active API keys and the id of the key used for this request.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -4518,6 +4578,18 @@
           }
         ],
         "summary": "Invite an email to join the caller's organization",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "Creates a pending invite for `email` and sends an invite email. Idempotent for an existing pending invite. The invitee accepts after signing in with the invited email.",
         "x-codeSamples": [
           {
@@ -4543,6 +4615,14 @@
         "responses": {
           "201": {
             "description": "The created (or existing pending) invite.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -4904,6 +4984,18 @@
           }
         ],
         "summary": "List invites issued by the caller's organization",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "Retrieves a list of all active pending or expired organization invites issued by the caller's organization.",
         "x-codeSamples": [
           {
@@ -4920,6 +5012,14 @@
         "responses": {
           "200": {
             "description": "Invites for this org.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -5505,6 +5605,18 @@
           }
         ],
         "summary": "Get the authenticated user's organization",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "### Overview\nReturns the metadata of the organization owned by the authenticated user. In the current version, this represents the user's personal organization space containing all their projects and tokens.\n\n### When to Use\n- Use this endpoint to retrieve the organization ID and name for display or context setup (e.g., when running `wspc org show` or rendering user dashboards).\n- Use this to verify that the API token / credentials are linked to a valid organization.\n\n### Constraints\n- Requires a valid Bearer token (API Key or Session Token) in the `Authorization` header.\n- In the current API version (v1), every user is automatically provisioned a single personal organization. Selecting or switching organizations is not supported.\n\n### Troubleshooting\n- **401 Unauthorized**: The provided Bearer token is missing, expired, or invalid. Verify your `Authorization` header format (`Bearer <token>`).\n- **403 Forbidden**: The token does not have access to read organization metadata.\n- **404 Not Found**: The organization associated with this token could not be found or has been deactivated.",
         "x-codeSamples": [
           {
@@ -5521,6 +5633,14 @@
         "responses": {
           "200": {
             "description": "The authenticated user's organization.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -5887,6 +6007,18 @@
           }
         ],
         "summary": "Update the authenticated user's organization",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "### Overview\nUpdates the metadata (currently, the name) of the organization associated with the authenticated user.\n\n### Constraints\n- Requires a valid Bearer token.\n- The organization name cannot be empty or purely whitespace.\n- Maximum length is capped by `MAX_ORG_NAME_LEN`.",
         "x-codeSamples": [
           {
@@ -5912,6 +6044,14 @@
         "responses": {
           "200": {
             "description": "The updated organization metadata.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -6264,20 +6404,17 @@
           }
         ],
         "summary": "Get a single invite addressed to the caller",
-        "description": "Retrieves the metadata of a specific organization invite addressed to the caller by its ID.",
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl ${EXAMPLE_API_BASE_URL}/auth/invites/inv_01KT43YKZ8CX14WS6ENXQ8397E \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc invite show inv_01KT43YKZ8CX14WS6ENXQ8397E"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -6289,9 +6426,30 @@
             "in": "path"
           }
         ],
+        "description": "Retrieves the metadata of a specific organization invite addressed to the caller by its ID.",
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl ${EXAMPLE_API_BASE_URL}/auth/invites/inv_01KT43YKZ8CX14WS6ENXQ8397E \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc invite show inv_01KT43YKZ8CX14WS6ENXQ8397E"
+          }
+        ],
         "responses": {
           "200": {
             "description": "The invite.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -6658,6 +6816,18 @@
           }
         ],
         "summary": "Fetch the user identified by the bearer token",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "### Overview\nRetrieves the stable identity profile (user ID, email, and optional display name) of the user associated with the active Bearer token. Works for both long-lived `wspc_*` API keys and OAuth access tokens.\n\n### When to Use\n- Use this endpoint (e.g., in `wspc verify` or `wspc whoami`) to confirm that the active environment's API key or OAuth access token remains valid.\n- Use it in UIs to display the logged-in user's profile details and retrieve the stable `user_id`.\n\n### Constraints\n- Requires a valid Bearer token (either a long-lived `wspc_*` API key or a temporary OAuth access token) in the `Authorization` header.\n- **Response Fields**: The `api_key_id` field is only returned if authenticated via a WSPC API key (prefixed with `wspc_`). OAuth access tokens will omit `api_key_id`. `display_name` is omitted if not configured.\n\n### Troubleshooting\n- **401 Unauthorized**: The Bearer token is missing, malformed, or has been revoked. Ensure the `Authorization` header matches the `Bearer <token>` format.",
         "x-codeSamples": [
           {
@@ -6674,6 +6844,14 @@
         "responses": {
           "200": {
             "description": "The bearer token is valid. The response carries the stable `user_id`, the user's email, and — for `wspc_*` API keys only — the `api_key_id` that authenticated the call.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -7056,6 +7234,18 @@
           }
         ],
         "summary": "List invites addressed to the authenticated user's email",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "Retrieves all pending or expired organization invites addressed to the caller's verified email address.",
         "x-codeSamples": [
           {
@@ -7072,6 +7262,14 @@
         "responses": {
           "200": {
             "description": "Invites addressed to the caller.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -7435,20 +7633,17 @@
           }
         ],
         "summary": "List members of the authenticated user's organization",
-        "description": "### Overview\nRetrieves a paginated list of all members belonging to the authenticated user's organization, including their basic profile information, emails, and roles.\n\n### When to Use\n- Use this endpoint to list members in command-line tools (e.g., `wspc org members ls`) or to display a team directory in a user dashboard.\n- Use this to paginate through large lists of organization members using cursor-based pagination.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- In the current version (v1), organizations are single-user only, meaning this endpoint will always return exactly one member (the caller).\n- **Pagination**: Supports cursor-based pagination. The `limit` query parameter must be a positive integer, defaulting to 50 and capped at a maximum of 100. Pass `cursor` from the previous response's `next_cursor` to fetch subsequent pages.\n\n### Troubleshooting\n- **401 Unauthorized**: The Bearer token is invalid or has expired.\n- **400 Bad Request**: The query parameters `limit` or `cursor` are malformed. Ensure `limit` is an integer between 1 and 100.\n- **404 Not Found**: The organization associated with this user was not found.",
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl https://api.wspc.ai/auth/me/org/members \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc org members ls"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -7470,9 +7665,30 @@
             "in": "query"
           }
         ],
+        "description": "### Overview\nRetrieves a paginated list of all members belonging to the authenticated user's organization, including their basic profile information, emails, and roles.\n\n### When to Use\n- Use this endpoint to list members in command-line tools (e.g., `wspc org members ls`) or to display a team directory in a user dashboard.\n- Use this to paginate through large lists of organization members using cursor-based pagination.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- In the current version (v1), organizations are single-user only, meaning this endpoint will always return exactly one member (the caller).\n- **Pagination**: Supports cursor-based pagination. The `limit` query parameter must be a positive integer, defaulting to 50 and capped at a maximum of 100. Pass `cursor` from the previous response's `next_cursor` to fetch subsequent pages.\n\n### Troubleshooting\n- **401 Unauthorized**: The Bearer token is invalid or has expired.\n- **400 Bad Request**: The query parameters `limit` or `cursor` are malformed. Ensure `limit` is an integer between 1 and 100.\n- **404 Not Found**: The organization associated with this user was not found.",
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/auth/me/org/members \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc org members ls"
+          }
+        ],
         "responses": {
           "200": {
             "description": "List of organization members and optional cursor for next page.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -8795,20 +9011,17 @@
           }
         ],
         "summary": "Reject an invite",
-        "description": "Rejects an organization invite addressed to the caller. The invite will be marked as rejected.",
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X POST ${EXAMPLE_API_BASE_URL}/auth/invites/inv_01KT43YKZ8CX14WS6ENXQ8397E/reject \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc invite reject inv_01KT43YKZ8CX14WS6ENXQ8397E"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -8820,14 +9033,35 @@
             "in": "path"
           }
         ],
-        "responses": {
-          "204": {
-            "description": "Invite rejected."
+        "description": "Rejects an organization invite addressed to the caller. The invite will be marked as rejected.",
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X POST ${EXAMPLE_API_BASE_URL}/auth/invites/inv_01KT43YKZ8CX14WS6ENXQ8397E/reject \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
           },
-          "400": {
-            "description": "Request validation failed. The body, query, or path parameters did not match the operation's schema.",
-            "content": {
-              "application/json": {
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc invite reject inv_01KT43YKZ8CX14WS6ENXQ8397E"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Invite rejected.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Request validation failed. The body, query, or path parameters did not match the operation's schema.",
+            "content": {
+              "application/json": {
                 "schema": {
                   "type": "object",
                   "properties": {
@@ -9162,15 +9396,17 @@
           }
         ],
         "summary": "Remove a member from the organization",
-        "description": "### Overview\nRemoves a member from the authenticated user's organization by their user ID, restoring their original organization ID if applicable.\n\n### Constraints\n- Requires a valid Bearer token.\n- Cannot remove the organization creator/owner.",
-        "x-codeSamples": [
-          {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X DELETE https://api.wspc.ai/auth/me/org/members/usr_member \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
-          }
-        ],
         "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
           {
             "schema": {
               "type": "string",
@@ -9182,9 +9418,25 @@
             "in": "path"
           }
         ],
+        "description": "### Overview\nRemoves a member from the authenticated user's organization by their user ID, restoring their original organization ID if applicable.\n\n### Constraints\n- Requires a valid Bearer token.\n- Cannot remove the organization creator/owner.",
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X DELETE https://api.wspc.ai/auth/me/org/members/usr_member \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          }
+        ],
         "responses": {
           "204": {
-            "description": "Member removed successfully."
+            "description": "Member removed successfully.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
           },
           "400": {
             "description": "Request validation failed. The body, query, or path parameters did not match the operation's schema.",
@@ -9521,6 +9773,18 @@
         "excludeActorHeaders": true,
         "security": [],
         "summary": "Request an email magic code",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "### Overview\nInitiates the passwordless email magic-code authentication flow by sending a short, time-limited numeric verification code to the specified email address.\n\n### When to Use\n- Use this endpoint as the first step of the CLI login flow (`wspc login`) or any interactive UI where the user initiates authentication by inputting their email address.\n- Pair this request with `POST /auth/verify-code` once the user retrieves the code from their inbox.\n\n### Constraints\n- Does not require authentication (public endpoint).\n- **Security**: The same HTTP 200 response structure is returned regardless of whether the email address is already registered or not. This is an intentional security design to prevent account-existence disclosure (email harvesting).\n- **Rate Limiting**: This endpoint enforces strict rate limits based on both the requesting IP address and the target email address to prevent abuse. Too many consecutive requests will result in a `RATE_LIMITED` error.\n\n### Troubleshooting\n- **429 Too Many Requests**: The requesting IP or target email has exceeded the allowable request rate. Wait a few minutes before trying again.\n- **400 Bad Request**: The `email` payload is malformed or invalid. Verify that the email matches basic email formats.",
         "x-codeSamples": [
           {
@@ -9554,6 +9818,14 @@
         "responses": {
           "200": {
             "description": "The magic code was generated and an email was dispatched. The same response shape is returned for registered and unregistered addresses to avoid account-existence disclosure.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -9909,6 +10181,28 @@
           }
         ],
         "summary": "Soft-revoke an API key",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Id of the API key to revoke, as returned by `GET /auth/keys` (`key_<ULID>`)."
+            },
+            "required": true,
+            "description": "Id of the API key to revoke, as returned by `GET /auth/keys` (`key_<ULID>`).",
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "description": "### Overview\nPermanently revokes an active API key by its unique ID. Once revoked, the key becomes immediately invalid and will be rejected by all services.\n\n### When to Use\n- Use this endpoint to permanently deactivate an API key (e.g., when running `wspc keys revoke <id>`) due to token rotation, key leakage, or decommissioning of a machine/service.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Revocation is permanent and cannot be undone.\n- A user can revoke any key they own, including the one they are currently using to make the call. If they revoke the current key, subsequent requests using that key will return `401 Unauthorized`.\n\n### Troubleshooting\n- **401 Unauthorized**: The active token is missing, expired, or invalid.\n- **404 Not Found**: The specified key ID does not exist, belongs to another user, or has already been revoked.\n- **400 Bad Request**: The `id` path parameter format is invalid. It must be in the format `key_<ULID>`.",
         "x-cli": {
           "command": "keys rm",
@@ -9928,21 +10222,17 @@
             "source": "wspc keys rm key_abcd1234efgh5678"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Id of the API key to revoke, as returned by `GET /auth/keys` (`key_<ULID>`)."
-            },
-            "required": true,
-            "description": "Id of the API key to revoke, as returned by `GET /auth/keys` (`key_<ULID>`).",
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "responses": {
           "200": {
             "description": "Key revoked successfully.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -10287,6 +10577,28 @@
           }
         ],
         "summary": "Update an active API key's label",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Id of the API key to update."
+            },
+            "required": true,
+            "description": "Id of the API key to update.",
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "description": "### Overview\nUpdates the human-readable label of an active API key. Only active (non-revoked) keys owned by the authenticated user can be updated.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Label Validation**: The `label` parameter must be between 1 and 60 characters after trimming whitespace. Failing to provide a valid label results in an `INVALID_LABEL` error.",
         "x-cli": {
           "command": "keys edit",
@@ -10306,18 +10618,6 @@
             "source": "wspc keys edit key_01HW3K4N9V5G6Z8C2Q7B1Y0M3F --label \"New Label\""
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Id of the API key to update."
-            },
-            "required": true,
-            "description": "Id of the API key to update.",
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -10331,6 +10631,14 @@
         "responses": {
           "200": {
             "description": "API key label updated successfully.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -10893,20 +11201,17 @@
           }
         ],
         "summary": "Revoke a pending invite",
-        "description": "Permanently revokes a pending organization invite. The invitee will no longer be able to accept it.",
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X DELETE ${EXAMPLE_API_BASE_URL}/auth/me/org/invites/inv_01KT43YKZ8CX14WS6ENXQ8397E \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc org invite revoke inv_01KT43YKZ8CX14WS6ENXQ8397E"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -10918,9 +11223,30 @@
             "in": "path"
           }
         ],
+        "description": "Permanently revokes a pending organization invite. The invitee will no longer be able to accept it.",
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X DELETE ${EXAMPLE_API_BASE_URL}/auth/me/org/invites/inv_01KT43YKZ8CX14WS6ENXQ8397E \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc org invite revoke inv_01KT43YKZ8CX14WS6ENXQ8397E"
+          }
+        ],
         "responses": {
           "204": {
-            "description": "Invite revoked."
+            "description": "Invite revoked.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
           },
           "400": {
             "description": "Request validation failed. The body, query, or path parameters did not match the operation's schema.",
@@ -11485,6 +11811,18 @@
         "excludeActorHeaders": true,
         "security": [],
         "summary": "Verify a magic code and issue an API key",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous auth response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "### Overview\nCompletes the passwordless login flow by verifying the magic code received via email. If the code is correct, it registers a new user (if not already registered) and issues a long-lived WSPC API key.\n\n### When to Use\n- Use this endpoint as the second step of the login flow, exchanging the user-provided code and email address for a valid credential.\n- Store the returned `api_key` securely client-side to authorize subsequent calls to all WSPC services.\n\n### Constraints\n- Does not require authentication (public endpoint).\n- **One-time Use & Expiry**: The verification code is single-use and expires after a short period (typically a few minutes). Re-using a code or attempting to guess code values results in `INVALID_CODE` or `CODE_EXPIRED`.\n- **Account Creation**: If the email address is not linked to an existing account, a new user profile and personal organization are automatically provisioned (`created: true` in response).\n\n### Troubleshooting\n- **400 Bad Request**: The code has expired (`CODE_EXPIRED`), is incorrect (`INVALID_CODE`), or has already been used. Request a fresh code via `POST /auth/request-code`.\n- **429 Too Many Requests**: The rate limit for verification attempts on this email address has been exceeded.",
         "x-codeSamples": [
           {
@@ -11519,6 +11857,14 @@
         "responses": {
           "200": {
             "description": "Code accepted. The response carries a fresh API key for the active environment plus the user's stable id. Persist these client-side.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest auth database position observed by this request. Store and send it on the next auth request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -11921,6 +12267,18 @@
           }
         },
         "summary": "Schedule a calendar event",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "description": "### Overview\nCreate a new calendar event owned by the authenticated user.\n\n### When to Use\nBook a meeting, lunch, all-day trip, or any time-bound item. Optionally provide `attendees` to automatically dispatch invitation emails containing an `.ics` REQUEST attachment to each participant as a side effect.\n\n### Constraints\n- **Format Integrity**: `start` and `end` must be of the exact same type (both ISO 8601 datetimes with offset, or both ISO date-only for all-day).\n- **Chronological Order**: `end` must be strictly after `start`.\n- **All-Day boundary**: All-day events use RFC 5545 exclusive end (e.g., a one-day event on June 1st is specified as `start=2026-06-01` and `end=2026-06-02`).\n- **Attendee Limit**: Up to 50 unique attendees are supported after case-insensitive email address deduplication.\n\n### Troubleshooting\n- Returns 400 `VALIDATION_ERROR` if `start` and `end` format mismatch, or if `end <= start`.\n- Returns 400 `ATTENDEE_LIMIT_EXCEEDED` if more than 50 unique attendees are supplied.\n- Invitation emails are processed and dispatched asynchronously via Cloudflare `waitUntil`; the analytics counter `event_created` is emitted automatically.",
         "security": [
           {
@@ -11997,6 +12355,14 @@
         "responses": {
           "201": {
             "description": "The event was created. Response carries the full row including server-assigned `id`, `version: 1`, derived `all_day`, and (if applicable) `attendees`. Invitation emails are sent asynchronously via `waitUntil`.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -12399,25 +12765,17 @@
           }
         },
         "summary": "List calendar events",
-        "description": "### Overview\nReturn the authenticated user's events, ordered by `start` ascending, with cursor pagination.\n\n### When to Use\nRender calendar list/grid views, search for specific terms using full-text search, query events within a specific time window, or retrieve historically past events.\n\n### Constraints\n- **Default Visibility**: By default, soft-deleted events and past events (events where `end` is before the current time) are automatically hidden.\n- **Time Bounds Override**: Supplying any explicit time bound query parameter (`start_from`, `start_to`, `end_from`, `end_to`) or passing `include_past=true` overrides and disables the implicit past filter.\n- **Search Scope**: `q` performs a case-insensitive substring search across `title`, `description`, and `location`.\n- **Pagination**: The `limit` query parameter is clamped to `[1, 200]`; cursor pagination is enabled via the opaque `cursor` parameter.\n\n### Troubleshooting\n- Returns 400 `VALIDATION_ERROR` if date query bounds are invalid (e.g. `start_from > start_to` or `end_from > end_to`).",
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -G https://api.wspc.ai/calendar/events \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  --data-urlencode \"start_from=2026-06-01T00:00:00+08:00\" \\\n  --data-urlencode \"start_to=2026-06-30T23:59:59+08:00\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc event ls --from \"next Monday\" --to \"next Friday\""
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -12509,9 +12867,35 @@
             "in": "query"
           }
         ],
+        "description": "### Overview\nReturn the authenticated user's events, ordered by `start` ascending, with cursor pagination.\n\n### When to Use\nRender calendar list/grid views, search for specific terms using full-text search, query events within a specific time window, or retrieve historically past events.\n\n### Constraints\n- **Default Visibility**: By default, soft-deleted events and past events (events where `end` is before the current time) are automatically hidden.\n- **Time Bounds Override**: Supplying any explicit time bound query parameter (`start_from`, `start_to`, `end_from`, `end_to`) or passing `include_past=true` overrides and disables the implicit past filter.\n- **Search Scope**: `q` performs a case-insensitive substring search across `title`, `description`, and `location`.\n- **Pagination**: The `limit` query parameter is clamped to `[1, 200]`; cursor pagination is enabled via the opaque `cursor` parameter.\n\n### Troubleshooting\n- Returns 400 `VALIDATION_ERROR` if date query bounds are invalid (e.g. `start_from > start_to` or `end_from > end_to`).",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -G https://api.wspc.ai/calendar/events \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  --data-urlencode \"start_from=2026-06-01T00:00:00+08:00\" \\\n  --data-urlencode \"start_to=2026-06-30T23:59:59+08:00\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc event ls --from \"next Monday\" --to \"next Friday\""
+          }
+        ],
         "responses": {
           "200": {
             "description": "Events matching the filters. Empty `events` array when nothing matches. `next_cursor` is present iff there is another page.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -12919,6 +13303,28 @@
           }
         },
         "summary": "Soft-delete a calendar event",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
+            },
+            "required": true,
+            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "description": "### Overview\nSoft-delete an existing calendar event, hiding it from default listings.\n\n### When to Use\nRemove an event entirely from the user's historical view and calendar client. If the meeting was cancelled but should remain in history (notifying participants of cancellation), use `PATCH /calendar/events/{id}` with `status: cancelled` instead.\n\n### Constraints\n- **Optimistic Locking**: Supports optional optimistic locking via `expected_version` in the request body.\n- **Side Effects**: When soft-deleting an event with attendees, all participants will asynchronously receive a cancellation email containing an `.ics` CANCEL attachment via Cloudflare `waitUntil`.\n- **Recovery**: The record is preserved in the database as a soft-deleted row and can be brought back using `POST /calendar/events/{id}/restore`.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist, or has already been soft-deleted.\n- Returns 409 `VERSION_CONFLICT` if `expected_version` does not match the database value.",
         "security": [
           {
@@ -12937,18 +13343,6 @@
             "source": "wspc event rm evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
-            },
-            "required": true,
-            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -12973,6 +13367,14 @@
         "responses": {
           "200": {
             "description": "The event was soft-deleted. Response carries `id`, `deleted_at`, and the post-delete `version`. Cancellation emails are sent asynchronously.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -13344,25 +13746,17 @@
           }
         },
         "summary": "Get a calendar event by id",
-        "description": "### Overview\nFetch a single calendar event by its unique ID, returning the complete record including all attendees.\n\n### When to Use\nDisplay a detailed view of an event, or read the latest database state (capturing `version`) prior to executing an optimistic-locked PATCH update.\n\n### Constraints\n- **Deleted Events**: Soft-deleted events return 404 `NOT_FOUND` by default. You must explicitly pass `include_deleted=true` in the query parameters to retrieve a soft-deleted row.\n- **ICS Format**: To download the RFC 5545 iCalendar text representation of this event, use `GET /calendar/events/{id}.ics` instead.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist, is soft-deleted (without `include_deleted=true`), or is owned by another user.",
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl https://api.wspc.ai/calendar/events/evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc event show evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -13384,9 +13778,35 @@
             "in": "query"
           }
         ],
+        "description": "### Overview\nFetch a single calendar event by its unique ID, returning the complete record including all attendees.\n\n### When to Use\nDisplay a detailed view of an event, or read the latest database state (capturing `version`) prior to executing an optimistic-locked PATCH update.\n\n### Constraints\n- **Deleted Events**: Soft-deleted events return 404 `NOT_FOUND` by default. You must explicitly pass `include_deleted=true` in the query parameters to retrieve a soft-deleted row.\n- **ICS Format**: To download the RFC 5545 iCalendar text representation of this event, use `GET /calendar/events/{id}.ics` instead.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist, is soft-deleted (without `include_deleted=true`), or is owned by another user.",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/calendar/events/evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc event show evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
+          }
+        ],
         "responses": {
           "200": {
             "description": "The requested event. Includes `deleted_at` only when fetched with `include_deleted=true` on a soft-deleted row.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -13794,6 +14214,28 @@
           }
         },
         "summary": "Update a calendar event",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
+            },
+            "required": true,
+            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "description": "### Overview\nPartially update fields of an existing calendar event. All properties in the request body are optional.\n\n### When to Use\nReschedule an event, update its location or notes, cancel the meeting (retaining the record but notifying participants), or replace/update the attendee list.\n\n### Constraints\n- **Optimistic Locking**: Pass `expected_version` to fail with `VERSION_CONFLICT` if another mutation occurred concurrently since you last read. Omit to let the server force the update.\n- **Field Clearing**: Pass an empty string `\"\"` for `description`, `location`, or `url` to clear those fields in the database.\n- **Attendee replacement**: Providing the `attendees` property fully REPLACES the existing participant list. The server automatically diffs participants and asynchronously sends invitations (for newly added), updates (for kept), or cancellations (for removed) via Cloudflare `waitUntil`.\n- **Validation Rules**: Mismatched start/end formats or chronological order violations will fail the request.\n- **Attendee Limit**: A maximum of 50 unique attendees is allowed.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist or is soft-deleted.\n- Returns 409 `VERSION_CONFLICT` if `expected_version` is provided but stale.\n- Returns 400 `VALIDATION_ERROR` if `start` and `end` kinds do not match, or if `end <= start`.\n- Returns 400 `ATTENDEE_LIMIT_EXCEEDED` if unique attendees exceed 50.",
         "security": [
           {
@@ -13812,18 +14254,6 @@
             "source": "wspc event set evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F \\\n  --start \"tomorrow 1pm\" --end \"tomorrow 2pm\""
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
-            },
-            "required": true,
-            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -13872,6 +14302,14 @@
         "responses": {
           "200": {
             "description": "The updated event with `version` incremented. Attendee diff emails are sent asynchronously.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -14250,6 +14688,28 @@
           }
         },
         "summary": "Download event as `.ics`",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "`<event_id>.ics`. The `.ics` suffix is required so the router matches this endpoint ahead of the JSON detail route."
+            },
+            "required": true,
+            "description": "`<event_id>.ics`. The `.ics` suffix is required so the router matches this endpoint ahead of the JSON detail route.",
+            "name": "filename",
+            "in": "path"
+          }
+        ],
         "description": "### Overview\nReturn a single event rendered as an RFC 5545 `.ics` file suitable for import into major calendar clients.\n\n### When to Use\nExpose a 'Save to my calendar' link in email notifications, show a download button in a UI, or programmatically forward raw iCalendar text to third parties.\n\n### Constraints\n- **Router Match**: The path parameter `filename` must be exactly `<event_id>.ics`. The `.ics` suffix is strictly required for the router to match this endpoint ahead of the JSON detail endpoint.\n- **Response Payload**: The response is plain text containing the iCalendar specification, NOT JSON. The `Content-Type` is set to `text/calendar; charset=utf-8` with `Content-Disposition: inline; filename=\"<event_id>.ics\"`.\n- **Authentication**: Standard authentication is required (Bearer API key or OAuth access token), as this endpoint is secure.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist, is soft-deleted, or is owned by another user.",
         "security": [
           {
@@ -14268,21 +14728,17 @@
             "source": "wspc event ics evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F > event.ics"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "`<event_id>.ics`. The `.ics` suffix is required so the router matches this endpoint ahead of the JSON detail route."
-            },
-            "required": true,
-            "description": "`<event_id>.ics`. The `.ics` suffix is required so the router matches this endpoint ahead of the JSON detail route.",
-            "name": "filename",
-            "in": "path"
-          }
-        ],
         "responses": {
           "200": {
             "description": "RFC 5545 iCalendar payload as plain text. Content-Type `text/calendar; charset=utf-8`. Body begins with `BEGIN:VCALENDAR` and contains a single `VEVENT` for this event.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "text/calendar": {
                 "schema": {
@@ -14628,6 +15084,28 @@
           "hidden": true
         },
         "summary": "Restore a soft-deleted event",
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous calendar response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
+            },
+            "required": true,
+            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "description": "### Overview\nRestore a previously soft-deleted calendar event, making it active and visible in default list queries.\n\n### When to Use\nRecover an event that was accidentally soft-deleted.\n\n### Constraints\n- **Optimistic Locking**: Supports optional optimistic locking via `expected_version` in the request body.\n- **Side Effects**: When restoring an event with attendees, all participants will asynchronously receive a new invitation email containing an `.ics` REQUEST attachment via Cloudflare `waitUntil`.\n- **State Integrity**: You cannot restore a live (non-deleted) event. Restoring a live event is treated as an error.\n\n### Troubleshooting\n- Returns 404 `NOT_FOUND` if the event does not exist, or is NOT currently soft-deleted.\n- Returns 409 `VERSION_CONFLICT` if `expected_version` does not match the database value.",
         "security": [
           {
@@ -14641,18 +15119,6 @@
             "source": "curl -X POST https://api.wspc.ai/calendar/events/evt_01HW3K4N9V5G6Z8C2Q7B1Y0M3F/restore \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted)."
-            },
-            "required": true,
-            "description": "Event id (`evt_<ULID>` for new rows; legacy UUID ids remain accepted).",
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -14677,6 +15143,14 @@
         "responses": {
           "200": {
             "description": "The restored event with `version` incremented and `deleted_at` cleared. Re-invitation emails are sent asynchronously to attendees.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest calendar database position observed by this request. Store and send it on the next calendar request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -15043,12 +15517,24 @@
           "EmailAliases"
         ],
         "summary": "Create a receiving alias",
-        "description": "### Overview\nReserves and provisions a new passwordless/disposable receiving email alias address under the configured WSPC domain or a fully verified organization custom domain. All inbound emails received on this alias will be forwarded into the caller's inbox.\n\n### When to Use\n- Use this endpoint to spin up a fresh, dedicated email address (e.g., `alice-shop@wspc.app`) for specific websites, newsletters, or contexts to prevent spam or categorize incoming mail.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Alias Formatting**: The local part must be between 5 and 32 characters, start with an alphanumeric character, and only contain letters, numbers, dots, underscores, and hyphens.\n- **Custom Domains**: If the address uses a non-platform host, that domain must be registered to the caller's organization and have `status = verified`, `sending_status = verified`, and `receiving_status = verified`.\n- **Limit Check**: Each user is allowed a maximum of 10 active email aliases. Soft-deleted aliases do not count against this quota limit.\n\n### Troubleshooting\n- **401 Unauthorized**: Bearer token is missing, invalid, or expired.\n- **400 Bad Request / INVALID_CHARSET / RESERVED**: The alias local part contains invalid characters, is too short/long, or matches a reserved keyword.\n- **400 Bad Request / DOMAIN_NOT_FOUND**: The custom domain is not registered to the caller's organization.\n- **400 Bad Request / UNVERIFIED_DOMAIN**: The custom domain exists but is not verified yet.\n- **400 Bad Request / CUSTOM_DOMAIN_NOT_READY**: The custom domain exists but has not completed sending or receiving verification.\n- **409 Conflict / ALIAS_CONFLICT**: An alias with the exact requested email address already exists globally (whether active or soft-deleted by any user).\n- **429 Too Many Requests / ALIAS_LIMIT_EXCEEDED**: The user has reached the active alias cap limit of 10. A previously deleted alias must be cleaned up or wait for quota availability.",
+        "description": "### Overview\nReserves and provisions a new passwordless/disposable receiving email alias address under the configured WSPC domain or a fully verified organization custom domain. All inbound emails received on this alias will be forwarded into the caller's inbox.\n\n### When to Use\n- Use this endpoint to spin up a fresh, dedicated email address (e.g., `alice-shop@wspc.app`) for specific websites, newsletters, or contexts to prevent spam or categorize incoming mail.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Alias Formatting**: The local part must be between 5 and 32 characters, start with an alphanumeric character, and only contain letters, numbers, dots, underscores, and hyphens.\n- **Custom Domains**: If the address uses a non-platform host, that domain must be registered to the caller's organization and have `status = verified`, `sending_status = verified`, and `receiving_status = verified`.\n- **Limit Check**: Each user is allowed a maximum of 10 active email aliases. Soft-deleted aliases do not count against this quota limit.\n\n### Troubleshooting\n- **401 Unauthorized**: Bearer token is missing, invalid, or expired.\n- **400 Bad Request / INVALID_CHARSET / RESERVED**: The alias local part contains invalid characters, is too short/long, or matches a reserved keyword.\n- **400 Bad Request / ALIAS_DOMAIN_NOT_FOUND**: The custom domain is not registered to the caller's organization.\n- **400 Bad Request / UNVERIFIED_DOMAIN**: The custom domain exists but is not verified yet.\n- **400 Bad Request / ALIAS_DOMAIN_NOT_READY**: The custom domain exists but has not completed sending or receiving verification.\n- **409 Conflict / ALIAS_CONFLICT**: An alias with the exact requested email address already exists globally (whether active or soft-deleted by any user).\n- **429 Too Many Requests / ALIAS_LIMIT_EXCEEDED**: The user has reached the active alias cap limit of 10. A previously deleted alias must be cleaned up or wait for quota availability.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-cli": {
           "command": "alias add",
           "positional": [
@@ -15109,6 +15595,14 @@
         "responses": {
           "201": {
             "description": "Alias created. The requested address is live immediately.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -15129,7 +15623,7 @@
             }
           },
           "400": {
-            "description": "Invalid alias email address, local part, reserved local part, missing custom domain, unverified custom domain, or custom domain that is not ready for both sending and receiving.",
+            "description": "Invalid alias email address, local part, reserved local part, missing custom domain (`ALIAS_DOMAIN_NOT_FOUND`), unverified custom domain, or custom domain that is not ready for both sending and receiving (`ALIAS_DOMAIN_NOT_READY`).",
             "content": {
               "application/json": {
                 "schema": {
@@ -15334,6 +15828,28 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "When `true`, include soft-deleted aliases (with `deleted_at` set) alongside active ones. Defaults to `false`."
+            },
+            "required": false,
+            "description": "When `true`, include soft-deleted aliases (with `deleted_at` set) alongside active ones. Defaults to `false`.",
+            "name": "include_deleted",
+            "in": "query"
+          }
+        ],
         "x-cli": {
           "command": "alias ls",
           "display": {
@@ -15364,21 +15880,17 @@
             "source": "wspc email alias ls"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "When `true`, include soft-deleted aliases (with `deleted_at` set) alongside active ones. Defaults to `false`."
-            },
-            "required": false,
-            "description": "When `true`, include soft-deleted aliases (with `deleted_at` set) alongside active ones. Defaults to `false`.",
-            "name": "include_deleted",
-            "in": "query"
-          }
-        ],
         "responses": {
           "200": {
             "description": "Aliases owned by the caller, including soft-deleted entries when requested.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -15594,12 +16106,24 @@
           "EmailDomains"
         ],
         "summary": "Register a custom email domain",
-        "description": "### Overview\nRegisters a new organization-owned custom email domain with the upstream provider and caches the returned DNS verification records in D1.\n\n### When to Use\n- Use this endpoint when onboarding a new custom email domain such as `mail.example.com`.\n- The response contains the DNS records the organization must publish before the domain can be verified.\n- This route registers the domain and returns DNS records. Custom-domain aliases require `status`, `sending_status`, and `receiving_status` to all be `verified`.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Domain ownership is globally unique across the platform. Once any organization has reserved a domain, another org cannot register it.\n- This route requires custom domain provider credentials in production because it performs a live provider registration call.\n\n### Troubleshooting\n- **400 Bad Request / DOMAIN_INVALID / DOMAIN_RESERVED**: The hostname is malformed or belongs to the platform (`wspc.app`, `wspc.ai`, or their subdomains).\n- **409 Conflict / DOMAIN_CONFLICT**: The domain is already registered by some organization.\n- **502 Bad Gateway / DOMAIN_PROVIDER_ERROR**: The upstream provider request failed, timed out, or returned an unexpected shape.",
+        "description": "### Overview\nRegisters a new organization-owned custom email domain with the upstream provider and caches the returned DNS verification records in D1.\n\n### When to Use\n- Use this endpoint when onboarding a new custom email domain such as `mail.example.com`.\n- The response contains the DNS records the organization must publish before the domain can be verified.\n- This route registers the domain and returns DNS records. Custom-domain aliases require `status`, `sending_status`, and `receiving_status` to all be `verified`.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- Domain ownership is globally unique across the platform. Once any organization has reserved a domain, another org cannot register it.\n- This route requires custom domain provider credentials in production because it performs a live provider registration call.\n\n### Troubleshooting\n- **400 Bad Request / DOMAIN_INVALID / DOMAIN_RESERVED**: The hostname is malformed or belongs to the platform (`wspc.app` or its subdomains).\n- **409 Conflict / DOMAIN_CONFLICT**: The domain is already registered by some organization.\n- **502 Bad Gateway / DOMAIN_PROVIDER_ERROR**: The upstream provider request failed, timed out, or returned an unexpected shape.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-cli": {
           "command": "domain add",
           "positional": [
@@ -15648,6 +16172,14 @@
         "responses": {
           "201": {
             "description": "Custom domain registered and DNS verification records returned. Custom-domain aliases require full domain readiness before use.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -15944,6 +16476,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-cli": {
           "command": "domain ls",
           "display": {
@@ -15978,6 +16522,14 @@
         "responses": {
           "200": {
             "description": "Custom domains cached for the caller organization, including ownership, sending readiness, and receiving readiness state.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -16715,70 +17267,83 @@
         }
       }
     },
-    "/email/messages/{id}/attachments/{idx}": {
-      "get": {
-        "operationId": "email_attachment_get",
+    "/email/domains/{domain}": {
+      "delete": {
+        "operationId": "email_domain_delete",
         "tags": [
-          "Emails"
+          "EmailDomains"
         ],
-        "summary": "Download an attachment by index",
-        "description": "### Overview\nStreams the raw decoded bytes of a parsed attachment belonging to an inbound email. The response body is binary data instead of JSON.\n\n### When to Use\n- Use this endpoint when a user clicks to download a file attachment (such as an invoice PDF or image) or when an automated agent needs to process a file payload.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Response Headers**: The server sets the HTTP `Content-Type` matching the attachment's parsed MIME format and provides a `Content-Disposition: attachment; filename=\"<filename>\"` header.\n- **Soft-Deleted Parents**: Downloading files from soft-deleted emails is blocked with a 404 error, unless the query parameter `include_deleted=true` is provided.\n- **Path Parameter**: The `{idx}` must be a valid 0-based integer index pointing to the attachment list metadata.\n\n### Troubleshooting\n- **401 Unauthorized**: Invalid Bearer token.\n- **404 Not Found / EMAIL_NOT_FOUND**: The specified email ID does not exist or belongs to another user.\n- **404 Not Found / ATTACHMENT_NOT_FOUND**: The index `{idx}` is out of range for the email's attachment array.",
+        "summary": "Delete a custom email domain",
+        "description": "### Overview\nDeletes one active custom email domain for the caller organization. The worker first confirms no active aliases use the domain, deletes the upstream provider resource, then soft-deletes the cached D1 row.\n\n### When to Use\n- Use this when an organization no longer wants WSPC to manage a custom email domain.\n- Delete is only allowed when no active aliases use the domain.\n- Deleted domains are hidden from active list/get/verify/delete surfaces and cannot be self-restored in this version.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- This route requires custom domain provider credentials in production because it performs a live provider delete call.\n- Provider identifiers and provider raw errors are never returned to the client.\n\n### Troubleshooting\n- **400 Bad Request / DOMAIN_INVALID / DOMAIN_RESERVED**: The path hostname is malformed or reserved.\n- **404 Not Found / DOMAIN_NOT_FOUND**: The domain does not exist, belongs to another organization, or was already deleted.\n- **409 Conflict / DOMAIN_IN_USE**: Active aliases still use this domain.\n- **502 Bad Gateway / DOMAIN_PROVIDER_ERROR**: Provider delete failed, timed out, or credentials are missing.",
         "security": [
           {
             "bearerAuth": []
           }
         ],
         "x-cli": {
-          "command": "_handwritten",
-          "hidden": true
+          "command": "domain rm",
+          "positional": [
+            "domain"
+          ]
         },
         "x-codeSamples": [
           {
             "lang": "shell",
             "label": "curl",
-            "source": "curl https://api.wspc.ai/email/messages/eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F/attachments/0 \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -o invoice.pdf"
+            "source": "curl -X DELETE https://api.wspc.ai/email/domains/mail.example.com \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
           },
           {
             "lang": "bash",
             "label": "wspc CLI",
-            "source": "wspc email attachment eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F 0 --output invoice.pdf"
+            "source": "wspc domain rm mail.example.com"
           }
         ],
         "parameters": [
           {
             "schema": {
-              "type": "string"
+              "type": "string",
+              "description": "Custom domain hostname path parameter. URL-encode if your client requires it."
             },
             "required": true,
-            "name": "id",
-            "in": "path"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "idx",
+            "description": "Custom domain hostname path parameter. URL-encode if your client requires it.",
+            "name": "domain",
             "in": "path"
-          },
-          {
-            "schema": {
-              "type": "string",
-              "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`."
-            },
-            "required": false,
-            "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`.",
-            "name": "include_deleted",
-            "in": "query"
           }
         ],
         "responses": {
-          "200": {
-            "description": "Raw attachment bytes. `Content-Type` matches the attachment's parsed MIME (often `application/pdf`, `image/jpeg`, `text/calendar`, or `application/octet-stream` when unknown). `Content-Disposition: attachment; filename=\"<filename>\"`.",
+          "204": {
+            "description": "Custom domain deleted."
+          },
+          "400": {
+            "description": "Malformed or platform-reserved domain hostname.",
             "content": {
-              "application/octet-stream": {
+              "application/json": {
                 "schema": {
-                  "type": "string"
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
                 }
               }
             }
@@ -16829,7 +17394,41 @@
             }
           },
           "404": {
-            "description": "Either the parent email is unknown / soft-deleted (`EMAIL_NOT_FOUND`) or `idx` is out of range (`ATTACHMENT_NOT_FOUND`).",
+            "description": "The domain was not found for the caller organization.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Active aliases still use this domain.",
             "content": {
               "application/json": {
                 "schema": {
@@ -16955,11 +17554,43 @@
                 }
               }
             }
+          },
+          "502": {
+            "description": "The upstream provider delete failed or provider credentials are missing.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
           }
         }
-      }
-    },
-    "/email/domains/{domain}": {
+      },
       "get": {
         "operationId": "email_domain_get",
         "tags": [
@@ -17135,7 +17766,269 @@
             }
           },
           "404": {
-            "description": "The domain was not found for the caller organization.",
+            "description": "The domain was not found for the caller organization.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limit exceeded. Retry after the duration in `error.extra.retry_after_seconds`. `limit_kind` identifies which bucket was exhausted.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                },
+                "examples": {
+                  "rateLimited": {
+                    "summary": "Per-key rate limit hit",
+                    "value": {
+                      "error": {
+                        "code": "RATE_LIMITED",
+                        "message": "rate limit exceeded",
+                        "extra": {
+                          "retry_after_seconds": 60,
+                          "limit_kind": "authenticated_per_key"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Unhandled server error. The request was well-formed but the service failed unexpectedly. Safe to retry idempotent operations.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                },
+                "examples": {
+                  "internalError": {
+                    "summary": "Unhandled exception",
+                    "value": {
+                      "error": {
+                        "code": "INTERNAL_ERROR",
+                        "message": "internal error"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/email/messages/{id}/attachments/{idx}": {
+      "get": {
+        "operationId": "email_attachment_get",
+        "tags": [
+          "Emails"
+        ],
+        "summary": "Download an attachment by index",
+        "description": "### Overview\nStreams the raw decoded bytes of a parsed attachment belonging to an inbound email. The response body is binary data instead of JSON.\n\n### When to Use\n- Use this endpoint when a user clicks to download a file attachment (such as an invoice PDF or image) or when an automated agent needs to process a file payload.\n\n### Constraints\n- Requires a valid Bearer token in the `Authorization` header.\n- **Response Headers**: The server sets the HTTP `Content-Type` matching the attachment's parsed MIME format and provides a `Content-Disposition: attachment; filename=\"<filename>\"` header.\n- **Soft-Deleted Parents**: Downloading files from soft-deleted emails is blocked with a 404 error, unless the query parameter `include_deleted=true` is provided.\n- **Path Parameter**: The `{idx}` must be a valid 0-based integer index pointing to the attachment list metadata.\n\n### Troubleshooting\n- **401 Unauthorized**: Invalid Bearer token.\n- **404 Not Found / EMAIL_NOT_FOUND**: The specified email ID does not exist or belongs to another user.\n- **404 Not Found / ATTACHMENT_NOT_FOUND**: The index `{idx}` is out of range for the email's attachment array.",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "idx",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`."
+            },
+            "required": false,
+            "description": "When `true`, allow downloading an attachment whose parent email is soft-deleted. Defaults to `false`.",
+            "name": "include_deleted",
+            "in": "query"
+          }
+        ],
+        "x-cli": {
+          "command": "_handwritten",
+          "hidden": true
+        },
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/email/messages/eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F/attachments/0 \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -o invoice.pdf"
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc email attachment eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F 0 --output invoice.pdf"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Raw attachment bytes. `Content-Type` matches the attachment's parsed MIME (often `application/pdf`, `image/jpeg`, `text/calendar`, or `application/octet-stream` when unknown). `Content-Disposition: attachment; filename=\"<filename>\"`.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/octet-stream": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication is required but missing or invalid. The Bearer token (API key or OAuth access token) was absent, malformed, or rejected.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "string"
+                        },
+                        "message": {
+                          "type": "string"
+                        },
+                        "extra": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        }
+                      },
+                      "required": [
+                        "code",
+                        "message"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                },
+                "examples": {
+                  "authRequired": {
+                    "summary": "Missing Authorization header",
+                    "value": {
+                      "error": {
+                        "code": "AUTH_REQUIRED",
+                        "message": "missing bearer token"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Either the parent email is unknown / soft-deleted (`EMAIL_NOT_FOUND`) or `idx` is out of range (`ATTACHMENT_NOT_FOUND`).",
             "content": {
               "application/json": {
                 "schema": {
@@ -17278,6 +18171,46 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "When `true`, fetch the HTML body from R2 and include it as `html_body` in the response. Costs an extra R2 read; omit if you only need text."
+            },
+            "required": false,
+            "description": "When `true`, fetch the HTML body from R2 and include it as `html_body` in the response. Costs an extra R2 read; omit if you only need text.",
+            "name": "include_html",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "When `true`, allow fetching a soft-deleted email. Defaults to `false` (returns 404 for soft-deleted rows)."
+            },
+            "required": false,
+            "description": "When `true`, allow fetching a soft-deleted email. Defaults to `false` (returns 404 for soft-deleted rows).",
+            "name": "include_deleted",
+            "in": "query"
+          }
+        ],
         "x-cli": {
           "command": "email show",
           "positional": [
@@ -17310,39 +18243,17 @@
             "source": "wspc email show eml_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          },
-          {
-            "schema": {
-              "type": "string",
-              "description": "When `true`, fetch the HTML body from R2 and include it as `html_body` in the response. Costs an extra R2 read; omit if you only need text."
-            },
-            "required": false,
-            "description": "When `true`, fetch the HTML body from R2 and include it as `html_body` in the response. Costs an extra R2 read; omit if you only need text.",
-            "name": "include_html",
-            "in": "query"
-          },
-          {
-            "schema": {
-              "type": "string",
-              "description": "When `true`, allow fetching a soft-deleted email. Defaults to `false` (returns 404 for soft-deleted rows)."
-            },
-            "required": false,
-            "description": "When `true`, allow fetching a soft-deleted email. Defaults to `false` (returns 404 for soft-deleted rows).",
-            "name": "include_deleted",
-            "in": "query"
-          }
-        ],
         "responses": {
           "200": {
             "description": "The email row, attachment metadata, and (when requested) the HTML body.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -17790,40 +18701,17 @@
             "bearerAuth": []
           }
         ],
-        "x-cli": {
-          "command": "email ls",
-          "display": {
-            "shape": "list",
-            "columns": [
-              "id",
-              "from_addr",
-              "subject",
-              "is_read",
-              "received_at"
-            ],
-            "format": {
-              "id": "id-short",
-              "from_addr": "truncate",
-              "subject": "truncate",
-              "is_read": "bool-badge",
-              "received_at": "relative-time"
-            },
-            "emptyMessage": "no emails"
-          }
-        },
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -G https://api.wspc.ai/email/messages \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  --data-urlencode \"limit=20\" --data-urlencode \"unread_only=true\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc email ls --unread --limit 20"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -17886,9 +18774,50 @@
             "in": "query"
           }
         ],
+        "x-cli": {
+          "command": "email ls",
+          "display": {
+            "shape": "list",
+            "columns": [
+              "id",
+              "from_addr",
+              "subject",
+              "is_read",
+              "received_at"
+            ],
+            "format": {
+              "id": "id-short",
+              "from_addr": "truncate",
+              "subject": "truncate",
+              "is_read": "bool-badge",
+              "received_at": "relative-time"
+            },
+            "emptyMessage": "no emails"
+          }
+        },
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -G https://api.wspc.ai/email/messages \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  --data-urlencode \"limit=20\" --data-urlencode \"unread_only=true\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc email ls --unread --limit 20"
+          }
+        ],
         "responses": {
           "200": {
             "description": "A page of inbound emails. `next_cursor` is present iff there is another page; pass it back as `cursor` to continue.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -19270,6 +20199,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous email response. Send it back unchanged to continue read-after-write consistency for email D1 data.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-cli": {
           "command": "_handwritten",
           "hidden": true
@@ -19335,6 +20276,14 @@
         "responses": {
           "200": {
             "description": "The send was accepted. Response `email.id` uses `out_<ULID>` for new outbound rows; legacy UUID ids remain accepted. Inspect `idempotent_replay`: `false` means the provider was invoked on this request, `true` means an earlier identical send was replayed.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest email database position observed by this request. Store and send it on the next email request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -20056,6 +21005,28 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Optional opaque consistency bookmark returned by a previous push response. Send it back unchanged to continue read-after-write consistency.",
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Transport name to delete (e.g. `telegram`). Only transports the caller has previously registered exist; unknown values return 400 `UNKNOWN_TRANSPORT`."
+            },
+            "required": true,
+            "description": "Transport name to delete (e.g. `telegram`). Only transports the caller has previously registered exist; unknown values return 400 `UNKNOWN_TRANSPORT`.",
+            "name": "transport",
+            "in": "path"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -20074,21 +21045,17 @@
             "transport"
           ]
         },
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Transport name to delete (e.g. `telegram`). Only transports the caller has previously registered exist; unknown values return 400 `UNKNOWN_TRANSPORT`."
-            },
-            "required": true,
-            "description": "Transport name to delete (e.g. `telegram`). Only transports the caller has previously registered exist; unknown values return 400 `UNKNOWN_TRANSPORT`.",
-            "name": "transport",
-            "in": "path"
-          }
-        ],
         "responses": {
           "204": {
-            "description": "Config deleted (or no config existed — the call is idempotent)."
+            "description": "Config deleted (or no config existed — the call is idempotent).",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest push database position observed by this request. Store and send it on the next push request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
           },
           "400": {
             "description": "`transport` is not a value wspc supports.",
@@ -20324,6 +21291,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Optional opaque consistency bookmark returned by a previous push response. Send it back unchanged to continue read-after-write consistency.",
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -20376,6 +21355,14 @@
         "responses": {
           "201": {
             "description": "Config stored. The transport is now eligible to receive product notifications for this user.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest push database position observed by this request. Store and send it on the next push request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -20635,6 +21622,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Optional opaque consistency bookmark returned by a previous push response. Send it back unchanged to continue read-after-write consistency.",
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -20685,6 +21684,14 @@
         "responses": {
           "200": {
             "description": "All push transports registered for the authenticated user.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest push database position observed by this request. Store and send it on the next push request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -20920,6 +21927,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Optional opaque consistency bookmark returned by a previous push response. Send it back unchanged to continue read-after-write consistency.",
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -20972,6 +21991,14 @@
         "responses": {
           "200": {
             "description": "Test attempted. Inspect `ok` to discriminate success from a transport-layer failure (network, upstream 4xx/5xx).",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest push database position observed by this request. Store and send it on the next push request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -21257,22 +22284,20 @@
         "description": "### 🎯 Overview & Purpose\nAttach a free-text comment to a todo. Use this to record progress updates, notes, or remarks as a task moves along.\n\n### 💡 Key Features & Constraints\n* **Free text**: Comments are plain text up to 10000 characters; there is no separate \"progress\" vs \"remark\" type.\n* **Authorship**: The author is recorded as the calling user (`user_id`).\n\n### ⚠️ Common Errors & Troubleshooting\n* **`NOT_FOUND` (HTTP 404)**: Thrown if the target todo does not exist or is soft-deleted.\n* **`VALIDATION_ERROR` (HTTP 400)**: Thrown if content is empty or exceeds 10000 characters.",
         "security": [
           {
-            "bearerAuth": []
-          }
-        ],
-        "x-codeSamples": [
-          {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X POST https://api.wspc.ai/todo/items/tod_01HW3K/comments -H \"Authorization: Bearer $WSPC_API_KEY\" -H \"Content-Type: application/json\" -d '{\"content\":\"Looks good\"}'"
-          },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc todo comment add tod_01HW3K \"Looks good\""
+            "bearerAuth": []
           }
         ],
         "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
           {
             "schema": {
               "type": "string",
@@ -21285,6 +22310,18 @@
             "in": "path"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X POST https://api.wspc.ai/todo/items/tod_01HW3K/comments -H \"Authorization: Bearer $WSPC_API_KEY\" -H \"Content-Type: application/json\" -d '{\"content\":\"Looks good\"}'"
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc todo comment add tod_01HW3K \"Looks good\""
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -21305,6 +22342,14 @@
         "responses": {
           "201": {
             "description": "Created",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -21684,19 +22729,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl https://api.wspc.ai/todo/items/tod_01HW3K/comments -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc todo comment ls tod_01HW3K"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -21749,9 +22792,29 @@
             "in": "query"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/todo/items/tod_01HW3K/comments -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc todo comment ls tod_01HW3K"
+          }
+        ],
         "responses": {
           "200": {
             "description": "List",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -22154,6 +23217,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -22193,6 +23268,14 @@
         "responses": {
           "201": {
             "description": "Created",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -22573,19 +23656,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl https://api.wspc.ai/todo/projects -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc project ls"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -22598,9 +23679,29 @@
             "in": "query"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/todo/projects -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc project ls"
+          }
+        ],
         "responses": {
           "200": {
             "description": "List",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -23020,6 +24121,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -23066,6 +24179,14 @@
         "responses": {
           "201": {
             "description": "The rule was created. `materialized_instance_count` reports how many todo instances were materialized immediately within the 14-day horizon.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -23451,19 +24572,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl https://api.wspc.ai/todo/recurrence-rules \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc todo rule ls"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -23484,9 +24603,29 @@
             "in": "query"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/todo/recurrence-rules \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc todo rule ls"
+          }
+        ],
         "responses": {
           "200": {
             "description": "Active recurrence rules for the caller. Empty `rules` array when none are configured.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -23887,6 +25026,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -23929,6 +25080,14 @@
         "responses": {
           "201": {
             "description": "The todo was created. The response carries the full row including server-assigned `id`, `version`, and `created_at`.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -24321,19 +25480,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -G https://api.wspc.ai/todo/items \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  --data-urlencode \"status=open\" \\\n  --data-urlencode \"status=in_progress\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc todo ls --status open in_progress"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -24500,9 +25657,29 @@
             "in": "query"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -G https://api.wspc.ai/todo/items \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  --data-urlencode \"status=open\" \\\n  --data-urlencode \"status=in_progress\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc todo ls --status open in_progress"
+          }
+        ],
         "responses": {
           "200": {
             "description": "List of todos matching the filters. Empty `todos` array when nothing matches.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -24895,6 +26072,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -24919,6 +26108,14 @@
         "responses": {
           "201": {
             "description": "Created",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -25282,19 +26479,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl https://api.wspc.ai/todo/types -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc todo types ls"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -25324,9 +26519,29 @@
             "in": "query"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/todo/types -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc todo types ls"
+          }
+        ],
         "responses": {
           "200": {
             "description": "List",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -25705,6 +26920,29 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Comment id (`tdc_<ULID>`).",
+              "example": "tdc_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
+            },
+            "required": true,
+            "description": "Comment id (`tdc_<ULID>`).",
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -25717,22 +26955,17 @@
             "source": "wspc todo comment rm tdc_01HW3K"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string",
-              "description": "Comment id (`tdc_<ULID>`).",
-              "example": "tdc_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
-            },
-            "required": true,
-            "description": "Comment id (`tdc_<ULID>`).",
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "responses": {
           "200": {
             "description": "Soft-deleted",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -26114,19 +27347,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X PATCH https://api.wspc.ai/todo/comments/tdc_01HW3K -H \"Authorization: Bearer $WSPC_API_KEY\" -H \"Content-Type: application/json\" -d '{\"content\":\"Edited\"}'"
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc todo comment edit tdc_01HW3K \"Edited\""
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -26139,6 +27370,18 @@
             "in": "path"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X PATCH https://api.wspc.ai/todo/comments/tdc_01HW3K -H \"Authorization: Bearer $WSPC_API_KEY\" -H \"Content-Type: application/json\" -d '{\"content\":\"Edited\"}'"
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc todo comment edit tdc_01HW3K \"Edited\""
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -26159,6 +27402,14 @@
         "responses": {
           "200": {
             "description": "Updated",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -26524,19 +27775,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X DELETE https://api.wspc.ai/todo/projects/prj_01HW3K -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc project rm prj_01HW3K"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -26549,9 +27798,29 @@
             "in": "path"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X DELETE https://api.wspc.ai/todo/projects/prj_01HW3K -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc project rm prj_01HW3K"
+          }
+        ],
         "responses": {
           "200": {
             "description": "Soft-deleted",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -26917,19 +28186,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl https://api.wspc.ai/todo/projects/prj_01HW3K -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc project show prj_01HW3K"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -26942,9 +28209,29 @@
             "in": "path"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/todo/projects/prj_01HW3K -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc project show prj_01HW3K"
+          }
+        ],
         "responses": {
           "200": {
             "description": "OK",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -27309,19 +28596,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X PATCH https://api.wspc.ai/todo/projects/prj_01HW3K -H \"Authorization: Bearer $WSPC_API_KEY\" -H \"Content-Type: application/json\" -d '{\"name\":\"Renamed\"}'"
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc project update prj_01HW3K --name \"Renamed\""
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string",
@@ -27334,6 +28619,18 @@
             "in": "path"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X PATCH https://api.wspc.ai/todo/projects/prj_01HW3K -H \"Authorization: Bearer $WSPC_API_KEY\" -H \"Content-Type: application/json\" -d '{\"name\":\"Renamed\"}'"
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc project update prj_01HW3K --name \"Renamed\""
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -27367,6 +28664,14 @@
         "responses": {
           "200": {
             "description": "Updated",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -27739,6 +29044,26 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -27751,16 +29076,6 @@
             "source": "wspc todo rule rm tdr_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -27785,6 +29100,14 @@
         "responses": {
           "200": {
             "description": "The rule was soft-deleted; future materializations stop. Already-materialized todo instances remain on the user's list.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -28154,6 +29477,26 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -28166,19 +29509,17 @@
             "source": "wspc todo rule show tdr_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "responses": {
           "200": {
             "description": "The requested rule along with its template todo snapshot and the count of todo instances currently materialized from it.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -28558,6 +29899,26 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -28570,16 +29931,6 @@
             "source": "wspc todo rule set tdr_01HW3K4N9V5G6Z8C2Q7B1Y0M3F --rrule \"FREQ=WEEKLY;BYDAY=FR\""
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -28611,6 +29962,14 @@
         "responses": {
           "200": {
             "description": "The rule was updated. Returns the post-update rule with a bumped `version` and refreshed `updated_at`. Future materializations follow the new schedule; existing instances are untouched.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -28994,7 +30353,27 @@
         "description": "### 🎯 Overview & Purpose\nSoft-delete a todo item so that it no longer appears in active list queries. The record remains in the database and can be recovered later.\n\n### 🔍 When to Use\n* Use this to hide an item from your active listings without permanently losing the history or metrics.\n\n### 💡 Key Features & Constraints\n* **Cascading Delete (`cascade`)**: If the target todo has active child subtasks:\n  - If `cascade: false` (default), the deletion will fail and throw a `HAS_CHILDREN` error to prevent accidental orphaned tasks.\n  - If `cascade: true`, the target todo and all its nested child subtasks will be soft-deleted together.\n* **Optimistic Locking**: You may optionally pass `expected_version` to ensure the todo has not been modified since you last read it.\n\n### ⚠️ Common Errors & Troubleshooting\n* **`HAS_CHILDREN` (HTTP 400)**: Thrown if you attempt to delete a parent todo that has active subtasks without explicitly setting `cascade: true`.\n* **`VERSION_CONFLICT` (HTTP 409)**: Thrown if `expected_version` is provided and mismatches the database.\n* **`NOT_FOUND` (HTTP 404)**: Thrown if the target todo `id` does not exist or has already been soft-deleted.",
         "security": [
           {
-            "bearerAuth": []
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
           }
         ],
         "x-codeSamples": [
@@ -29009,16 +30388,6 @@
             "source": "wspc todo rm tod_01HW3K4N9V5G6Z8C2Q7B1Y0M3F --cascade"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -29044,6 +30413,14 @@
         "responses": {
           "200": {
             "description": "The todo was soft-deleted. `deleted_count` includes cascaded descendants when `cascade: true`.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -29432,19 +30809,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
+        "parameters": [
           {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl https://api.wspc.ai/todo/items/tod_01HW3K4N9V5G6Z8C2Q7B1Y0M3F \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
           },
-          {
-            "lang": "bash",
-            "label": "wspc CLI",
-            "source": "wspc todo show tod_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
-          }
-        ],
-        "parameters": [
           {
             "schema": {
               "type": "string"
@@ -29498,9 +30873,29 @@
             "in": "query"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl https://api.wspc.ai/todo/items/tod_01HW3K4N9V5G6Z8C2Q7B1Y0M3F \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\""
+          },
+          {
+            "lang": "bash",
+            "label": "wspc CLI",
+            "source": "wspc todo show tod_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
+          }
+        ],
         "responses": {
           "200": {
             "description": "The requested todo. Includes `children` (first-level) when `include=children`, `comments` when `include=comments`, and `deleted_at` only when fetched with `include_deleted=true` on a soft-deleted row.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -29917,6 +31312,26 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -29929,16 +31344,6 @@
             "source": "wspc todo done tod_01HW3K4N9V5G6Z8C2Q7B1Y0M3F"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -29976,6 +31381,14 @@
         "responses": {
           "200": {
             "description": "The todo was updated. The response carries the post-mutation row with the bumped `version` and refreshed `updated_at`.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -30346,6 +31759,26 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -30358,19 +31791,17 @@
             "source": "wspc todo types rm typ_01HW3K"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "responses": {
           "200": {
             "description": "Soft-deleted",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -30720,6 +32151,26 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -30732,19 +32183,17 @@
             "source": "wspc todo types show typ_01HW3K"
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "responses": {
           "200": {
             "description": "OK",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -31094,6 +32543,26 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "x-codeSamples": [
           {
             "lang": "shell",
@@ -31106,16 +32575,6 @@
             "source": "wspc todo types update typ_01HW3K --label \"Renamed\""
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -31128,6 +32587,14 @@
         "responses": {
           "200": {
             "description": "Updated",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -31479,14 +32946,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
-          {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X POST https://api.wspc.ai/todo/projects/prj_01HW3K/restore -H \"Authorization: Bearer $WSPC_API_KEY\""
-          }
-        ],
         "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
           {
             "schema": {
               "type": "string",
@@ -31499,9 +32969,24 @@
             "in": "path"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X POST https://api.wspc.ai/todo/projects/prj_01HW3K/restore -H \"Authorization: Bearer $WSPC_API_KEY\""
+          }
+        ],
         "responses": {
           "200": {
             "description": "Restored",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -31868,14 +33353,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
-          {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X POST https://api.wspc.ai/todo/items/tod_01HW3K4N9V5G6Z8C2Q7B1Y0M3F/restore \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"
-          }
-        ],
         "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
           {
             "schema": {
               "type": "string"
@@ -31885,6 +33373,13 @@
             "in": "path"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X POST https://api.wspc.ai/todo/items/tod_01HW3K4N9V5G6Z8C2Q7B1Y0M3F/restore \\\n  -H \"Authorization: Bearer $WSPC_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -31910,6 +33405,14 @@
         "responses": {
           "200": {
             "description": "The todo was restored. `restored_count` includes cascaded descendants when `cascade: true`; otherwise `descendants_in_trash_count` reports descendants left in trash.",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -32279,14 +33782,17 @@
             "bearerAuth": []
           }
         ],
-        "x-codeSamples": [
-          {
-            "lang": "shell",
-            "label": "curl",
-            "source": "curl -X POST https://api.wspc.ai/todo/types/typ_01HW3K/restore -H \"Authorization: Bearer $WSPC_API_KEY\""
-          }
-        ],
         "parameters": [
+          {
+            "name": "x-consistency-bookmark",
+            "in": "header",
+            "required": false,
+            "description": "Optional opaque consistency bookmark returned by a previous todo response. Send it back unchanged to continue read-after-write consistency.",
+            "schema": {
+              "type": "string"
+            },
+            "example": "opaque-consistency-bookmark"
+          },
           {
             "schema": {
               "type": "string"
@@ -32296,9 +33802,24 @@
             "in": "path"
           }
         ],
+        "x-codeSamples": [
+          {
+            "lang": "shell",
+            "label": "curl",
+            "source": "curl -X POST https://api.wspc.ai/todo/types/typ_01HW3K/restore -H \"Authorization: Bearer $WSPC_API_KEY\""
+          }
+        ],
         "responses": {
           "200": {
             "description": "Restored",
+            "headers": {
+              "x-consistency-bookmark": {
+                "description": "Opaque consistency bookmark for the latest todo database position observed by this request. Store and send it on the next todo request to continue read-after-write consistency.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {