docs: fix session externalId, list pagination, and read-scope docs

From bot review of the Sessions API docs:

- externalId is read-only after create (cannot be changed or cleared, it keys
  the durable streams and token scope). Drop the "null clears it" claim from the
  OpenAPI spec and the ai-chat/sessions page.
- List sessions uses a sessions-specific pagination parameter (min 1, default 20)
  instead of the shared runs one (min 10, default 25, "runs per page").
- read:sessions grants listing the session's runs, not listing sessions.

Author: ericallam

docs/ai-chat/sessions.mdx

@@ -138,7 +138,7 @@ console.log(session.currentRunId, session.tags, session.closedAt);
 
 ### `sessions.update(idOrExternalId, body, requestOptions?)`
 
-Mutate `tags`, `metadata`, or `externalId` on an existing Session. Pass `externalId: null` to explicitly clear it.
+Mutate `tags` or `metadata` on an existing Session. `externalId` is read-only after create: it cannot be changed or cleared (it keys the session's durable streams and token scope), so sending a different value returns `422`.
 
 ### `sessions.close(idOrExternalId, body?, requestOptions?)`
 

docs/management/authentication.mdx

@@ -196,7 +196,7 @@ Unlike `TriggerClient` instances (which stay isolated unless you opt in), `auth.
 
 | Scope | Grants |
 | --- | --- |
-| `read:sessions:{id}` | Retrieve and list the session, and subscribe to and drain both its `.in` and `.out` [channels](/management/sessions/channels). |
+| `read:sessions:{id}` | Retrieve the session, list its runs, and subscribe to and drain both its `.in` and `.out` [channels](/management/sessions/channels). |
 | `write:sessions:{id}` | Append to the session's `.in` channel, and create runs on the session (including the create call itself). |
 
 Two boundaries follow from the table, and both are enforced server-side:

docs/v3-openapi.yaml

@@ -3350,7 +3350,7 @@ paths:
 
         List rows omit `triggerConfig`; retrieve a single session to read it.
       parameters:
-        - $ref: "#/components/parameters/cursorPagination"
+        - $ref: "#/components/parameters/sessionsCursorPagination"
         - $ref: "#/components/parameters/sessionsFilter"
       responses:
         "200":
@@ -3430,8 +3430,9 @@ paths:
 
 
         Requires a secret key — a session public token cannot update a session.
-        `externalId` is read-only after create: sending a different value returns
-        `422`; sending the same value (or `null` to clear) is accepted.
+        `externalId` is read-only after create: it cannot be changed or cleared.
+        Sending a value different from the current one (including `null` when one is
+        set) returns `422`; sending the same value is accepted as a no-op.
       requestBody:
         required: true
         content:
@@ -3576,6 +3577,30 @@ components:
           before:
             type: string
             description: The ID of the run to start the page before. This will set the direction of the pagination to backward.
+    sessionsCursorPagination:
+      in: query
+      name: page
+      style: deepObject
+      explode: true
+      description: |
+        Paginate the results. Specify the number of sessions per page, and the ID of the session to start the page after or before.
+
+        For object fields like `page`, use the "form" encoding style. For example, to get the next page, use `page[after]=session_1234`.
+      schema:
+        type: object
+        properties:
+          size:
+            type: integer
+            maximum: 100
+            minimum: 1
+            default: 20
+            description: Number of sessions per page. Maximum is 100.
+          after:
+            type: string
+            description: The ID of the session to start the page after. Sets the pagination direction to forward.
+          before:
+            type: string
+            description: The ID of the session to start the page before. Sets the pagination direction to backward.
     runId:
       in: path
       name: runId
@@ -4393,8 +4418,9 @@ components:
           minLength: 1
           maxLength: 256
           description: >-
-            Read-only after create. Sending a value different from the current one
-            returns `422`; sending the same value is idempotent, and `null` clears it.
+            Read-only after create: cannot be changed or cleared. Sending a value
+            different from the current one (including `null` when one is set) returns
+            `422`; sending the same value is idempotent.
     CloseSessionRequestBody:
       type: object
       description: Body for `POST /api/v1/sessions/{session}/close`. Up to 1KB.