docs fix

interface/api/accounts/auth_login.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Accounts, Auth]
   summary: Login using email/password and receive pending verification token
+  description: |
+    Validates account credentials and returns a short-lived `pendingToken`.
+    This endpoint does not return final access/refresh tokens; complete verification flow via `/verification/verify`.
   operationId: accountsLogin
   requestBody:
     $ref: ./bodies/auth.yaml#/components/requestBodies/LoginBody

interface/api/accounts/auth_refresh.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Accounts, Auth]
   summary: Refresh access token by refresh token
+  description: |
+    Validates refresh token + session identifiers and issues a new access token.
+    Use this endpoint when refresh token stays the same.
   operationId: accountsRefreshAccessToken
   requestBody:
     $ref: ./bodies/auth.yaml#/components/requestBodies/RefreshTokenBody

interface/api/accounts/auth_rotate.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Accounts, Auth]
   summary: Rotate refresh token and issue new access/refresh tokens
+  description: |
+    Validates refresh token + session identifiers and returns a new token pair.
+    Use this endpoint when replacing both access and refresh tokens.
   operationId: accountsRotateRefreshToken
   requestBody:
     $ref: ./bodies/auth.yaml#/components/requestBodies/RefreshTokenBody