diff --git a/api-reference/app-releases/list.mdx b/api-reference/app-releases/list.mdx
index c952efa..5033b92 100644
--- a/api-reference/app-releases/list.mdx
+++ b/api-reference/app-releases/list.mdx
@@ -4,3 +4,7 @@ openapi: "/openapi/app-releases-api.json GET /api/v1/workspaces/{id}/app-release
 ---
 
 Requires the v0.13 app-release capability for your account. See [app release workflows](/deploy/overview) for preparation, activation, and recovery.
+
+Results are ordered by creation time, newest first. Set `max_results` to request a page size; it defaults to 50 and is clamped to 1–200. Pass the response's opaque `next_cursor` as `cursor` to fetch the next page. When `next_cursor` is absent, the list is complete.
+
+Expired releases are deleted during [retention cleanup](/deploy/app-rollback#retention), including their records and logs. Pagination applies to the retained history.
diff --git a/deploy/app-rollback.mdx b/deploy/app-rollback.mdx
index f592a53..b55158c 100644
--- a/deploy/app-rollback.mdx
+++ b/deploy/app-rollback.mdx
@@ -14,6 +14,14 @@ rig app-release logs --workspace my-project --release <RELEASE_ID>
 
 Choose a known-good retained release that belongs to this workspace. Review its application set and configuration before activation.
 
+## Retention
+
+Each deployment owner keeps the newest successful release record for each of its three most recently used distinct artifacts. Repeated rollback records for the same artifact are removed. Releases being prepared or activated remain available while the operation runs; ready candidates and failed releases expire after 24 hours.
+
+Retention deletes expired release records, stored configuration, diagnostic logs, and obsolete deployment idempotency records. Cleanup runs after an operation finishes and every ten minutes on the owning compute node, including stopped workspaces. Guest artifact removal waits for the workspace to run. After collection, an expired release ID returns HTTP 404 from the release and logs APIs; deploy again with a new deployment ID when another attempt is needed.
+
+The [release list API](/api-reference/app-releases/list) returns up to 50 records by default, with a maximum page size of 200. Pass its opaque `next_cursor` back as `cursor` to continue. Results stay ordered by creation time, newest first. The CLI follows each page when running `rig app-release ls`.
+
 ## Roll back
 
 ```bash
diff --git a/openapi/app-releases-api.json b/openapi/app-releases-api.json
index 67e63bf..b64db26 100644
--- a/openapi/app-releases-api.json
+++ b/openapi/app-releases-api.json
@@ -24,17 +24,52 @@
         "tags": [
           "App releases"
         ],
+        "description": "List app releases newest first using a stable creation-time cursor. Expired records are removed by retention.",
         "operationId": "list",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "Workspace ID",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "max_results",
+            "in": "query",
+            "description": "Maximum number of items to return. Defaults to 50; values are clamped to the range 1–200.",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "minimum": 0
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "description": "Opaque cursor returned by a prior call's `next_cursor`. Omit on the\nfirst page.",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
         "responses": {
           "200": {
-            "description": "App release result",
+            "description": "App releases page",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ListResponse"
+                  "$ref": "#/components/schemas/Page_AppRelease"
                 }
               }
             }
+          },
+          "400": {
+            "description": "Invalid cursor"
           }
         },
         "security": [
@@ -338,8 +373,9 @@
         },
         "additionalProperties": false
       },
-      "ListResponse": {
+      "Page_AppRelease": {
         "type": "object",
+        "description": "Paginated response envelope. `next_cursor` is omitted on the last page.",
         "required": [
           "items"
         ],
@@ -347,8 +383,84 @@
           "items": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/AppRelease"
+              "type": "object",
+              "required": [
+                "id",
+                "is_current",
+                "can_rollback",
+                "workspace_id",
+                "user_id",
+                "owner_key",
+                "idempotency_key",
+                "status",
+                "artifact_release_id",
+                "apps",
+                "created_at",
+                "updated_at"
+              ],
+              "properties": {
+                "apps": {},
+                "artifact_release_id": {
+                  "type": "string"
+                },
+                "can_rollback": {
+                  "type": "boolean"
+                },
+                "created_at": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "error": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "id": {
+                  "type": "string"
+                },
+                "idempotency_key": {
+                  "type": "string"
+                },
+                "is_current": {
+                  "type": "boolean"
+                },
+                "owner_key": {
+                  "type": "string"
+                },
+                "previous_release_id": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "source_commit": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "status": {
+                  "type": "string"
+                },
+                "updated_at": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "user_id": {
+                  "type": "string"
+                },
+                "workspace_id": {
+                  "type": "string"
+                }
+              }
             }
+          },
+          "next_cursor": {
+            "type": [
+              "string",
+              "null"
+            ]
           }
         }
       },