docs(tunnels): explain session reuse and history deletion

api-reference/tunnels/delete-record.mdx

@@ -0,0 +1,20 @@
+---
+title: "Delete tunnel history"
+openapi: "/openapi/tunnels-api.json DELETE /api/v1/tunnels/{id}/record"
+playground: "none"
+---
+
+Removes an inactive tunnel record owned by the current account and returns `204`
+with no response body. This also removes its invitations, browser viewer grants,
+and pending login transactions. Deletion cannot be undone.
+
+A live tunnel or valid pending start returns `409` with error code
+`TUNNEL_RECORD_ACTIVE` and the message "Stop this tunnel before deleting its
+history". [Stop the tunnel](/api-reference/tunnels/stop) first, then delete the
+record. Stopped, expired, and already timed-out records can be removed.
+
+Deleted and other accounts' records return `404`. Deleted records no longer
+appear in [List local tunnels](/api-reference/tunnels/list) or
+[Inspect a local tunnel](/api-reference/tunnels/get).
+
+The existing `DELETE /api/v1/tunnels/{id}` remains Stop and keeps history.

api-reference/tunnels/get.mdx

@@ -14,3 +14,5 @@ before sharing an app.
 Returns an owned tunnel and its current invitation email list. Read the returned policy epoch, connection generation, and target fingerprint before [changing access](/api-reference/tunnels/update-policy).
 
 The connector target stays fixed for the lifetime of this tunnel. To serve a different local target, start a new tunnel through the [CLI](/guides/local-tunnels#start-privately).
+
+After the owner [deletes this record](/api-reference/tunnels/delete-record), inspection returns `404`.

api-reference/tunnels/list.mdx

@@ -13,4 +13,6 @@ before sharing an app.
 
 Lists the current account's tunnel records, including their hostname, target, access policy, and connection state. A record does not establish that a connector is running or that its website is reachable.
 
+Stopped and expired records remain listed until the owner [deletes their history](/api-reference/tunnels/delete-record).
+
 See [local tunnels](/guides/local-tunnels) to start a connector and share its website.

api-reference/tunnels/stop.mdx

@@ -13,4 +13,6 @@ before sharing an app.
 
 Stops the owned tunnel, revokes its connector and lease credentials, and invalidates its viewer sessions. The relay closes active traffic after observing the stopped state.
 
+Stop keeps the tunnel record in your history. Use [Delete tunnel history](/api-reference/tunnels/delete-record) to remove an inactive record.
+
 A stopped connection generation cannot be resumed. Start a new tunnel through the [CLI](/guides/local-tunnels#start-privately) when you want to serve the website again.

docs.json

@@ -334,7 +334,8 @@
                   "api-reference/tunnels/create",
                   "api-reference/tunnels/get",
                   "api-reference/tunnels/update-policy",
-                  "api-reference/tunnels/stop"
+                  "api-reference/tunnels/stop",
+                  "api-reference/tunnels/delete-record"
                 ]
               }
             ]

guides/local-tunnels.mdx

@@ -34,9 +34,12 @@ rig tunnel --port 3000
 
 Review the first-use target and capability warning. The command prints its URL
 after the local service and an authenticated connector channel are ready. Open
-that URL and sign in using the owner's Rigbox browser account. A CLI API key does
-not mint a browser viewer session; browser access uses a fresh authenticated
-Rigbox login. Private and privileged tunnel traffic uses browser access only.
+that URL using the owner's Rigbox browser account. An existing active browser
+session can be reused; sign in if your session has ended. Rigbox verifies the
+current browser token and provider session before granting access, and you
+choose Continue to app. Opening a tunnel does not itself require a new password
+or MFA check. A CLI API key does not mint a browser viewer session.
+Private and privileged tunnel traffic uses browser access only.
 Keep Rigbox account API keys on the control API; never send them to a tunnel URL.
 Public native HTTP callers can use credentials issued by their local application,
 with the explicit client header described below.
@@ -126,7 +129,8 @@ Press Ctrl-C in the foreground command, or stop from another terminal:
 rig tunnel stop --tunnel TUNNEL_ID
 ```
 
-Stop revokes the session and connector. Changing access closes flows admitted
+Stop revokes the session and connector and keeps the record in your history.
+Changing access closes flows admitted
 under the old policy. The connector renews short authority leases and closes its
 local connections if renewal fails or expires. The 15-second bound runs from a
 gateway-observed change and valid lease issuance; it does not promise instant
@@ -136,8 +140,21 @@ A session has an eight-hour maximum lifetime. A service disappearing terminates
 the connector and requires an explicit new session. A fixed port does not identify
 a process: an undetected replacement on the same port can still be reached.
 Close the tunnel before restarting or replacing the local service. Expired
-leases and sessions that never started within 60 seconds are cleaned up when you
-create another tunnel; a live session requires explicit stop.
+leases and sessions that never started within 60 seconds cannot be revived.
+Starting another tunnel marks the previous stale record expired; it remains
+in your history until you delete it.
+
+### Delete history
+
+In the Console's Tunnels page, choose Delete history for a stopped or expired
+session and confirm its removal. This removes the record from your history and
+cannot be undone. Stop an active tunnel first; deletion does not stop it for you.
+
+The API provides the same cleanup through
+[`DELETE /api/v1/tunnels/{id}/record`](/api-reference/tunnels/delete-record).
+The existing `DELETE /api/v1/tunnels/{id}` remains Stop. A live tunnel or valid
+pending start returns `409 TUNNEL_RECORD_ACTIVE` when you try to delete its
+history.
 
 ## Identity deletion
 

openapi/tunnels-api.json

@@ -197,6 +197,41 @@
           }
         ]
       }
+    },
+    "/api/v1/tunnels/{id}/record": {
+      "delete": {
+        "tags": [
+          "Tunnels"
+        ],
+        "description": "Delete inactive tunnel history. Stop an active tunnel first.",
+        "operationId": "delete_record",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": ""
+          },
+          "404": {
+            "description": ""
+          },
+          "409": {
+            "description": ""
+          }
+        },
+        "security": [
+          {
+            "bearer": []
+          }
+        ]
+      }
     }
   },
   "tags": [

scripts/api-navigation-base.json

@@ -51,7 +51,8 @@
       "api-reference/tunnels/create",
       "api-reference/tunnels/get",
       "api-reference/tunnels/update-policy",
-      "api-reference/tunnels/stop"
+      "api-reference/tunnels/stop",
+      "api-reference/tunnels/delete-record"
     ]
   },
   {