docs: explain inactive workspace release requirements

api-reference/app-releases/activate.mdx

@@ -6,3 +6,5 @@ openapi: "/openapi/app-releases-api.json POST /api/v1/workspaces/{id}/app-releas
 Requires the v0.13 app-release capability for your account. See [app release workflows](/deploy/overview) for preparation, activation, and recovery.
 
 The handler can accept work asynchronously. Poll the release and inspect its status rather than treating an accepted request as a healthy deployment.
+
+The workspace must be running with an available network address. Otherwise, this endpoint returns HTTP 409 with an actionable message before accepting a release operation. Start the workspace explicitly, wait for it to be running, and submit the request again. Retained history and stored deployment logs remain available while it is stopped.

api-reference/app-releases/create.mdx

@@ -6,3 +6,5 @@ openapi: "/openapi/app-releases-api.json POST /api/v1/workspaces/{id}/app-releas
 Requires the v0.13 app-release capability for your account. See [app release workflows](/deploy/overview) for preparation, activation, and recovery.
 
 The handler can accept work asynchronously. Poll the release and inspect its status rather than treating an accepted request as a healthy deployment.
+
+The workspace must be running with an available network address. Otherwise, this endpoint returns HTTP 409 with an actionable message before accepting a release operation. Start the workspace explicitly, wait for it to be running, and submit the request again. Retained history and stored deployment logs remain available while it is stopped.

cli-reference/command-notes.json

@@ -1162,7 +1162,7 @@
     ]
   },
   "app-release/activate": {
-    "description": "Use this command from your local terminal. Workspace-mode syntax, when available, is listed separately below.",
+    "description": "Use this command from your local terminal. Workspace-mode syntax, when available, is listed separately below. The workspace must already be running. If it is inactive, the command stops with a warning. Start it explicitly with `rig workspace start --workspace WORKSPACE_ID`, then submit the release action again.",
     "examples": [
       {
         "description": "Run from your local terminal. Replace uppercase placeholders with your own values. This invocation performs the operation described above.",
@@ -1202,7 +1202,7 @@
     ]
   },
   "app-release/rollback": {
-    "description": "Use this command from your local terminal. Workspace-mode syntax, when available, is listed separately below.",
+    "description": "Use this command from your local terminal. Workspace-mode syntax, when available, is listed separately below. The workspace must already be running. If it is inactive, the command stops with a warning. Start it explicitly with `rig workspace start --workspace WORKSPACE_ID`, then submit the release action again.",
     "examples": [
       {
         "description": "Run from your local terminal. Replace uppercase placeholders with your own values. This invocation performs the operation described above.",

cli-reference/commands/app-release/activate.mdx

@@ -6,7 +6,7 @@ description: "Activate a ready app release staged with deploy --sync-only"
 
 Available **local and workspace**. Reference source: CLI `0.13.0-rc.5` (`824aefd6ad16`).
 
-Use this command from your local terminal. Workspace-mode syntax, when available, is listed separately below.
+Use this command from your local terminal. Workspace-mode syntax, when available, is listed separately below. The workspace must already be running. If it is inactive, the command stops with a warning. Start it explicitly with `rig workspace start --workspace WORKSPACE_ID`, then submit the release action again.
 
 ## Examples
 

cli-reference/commands/app-release/rollback.mdx

@@ -6,7 +6,7 @@ description: "Restore app code and configuration; briefly restarts affected apps
 
 Available **local and workspace**. Reference source: CLI `0.13.0-rc.5` (`824aefd6ad16`).
 
-Use this command from your local terminal. Workspace-mode syntax, when available, is listed separately below.
+Use this command from your local terminal. Workspace-mode syntax, when available, is listed separately below. The workspace must already be running. If it is inactive, the command stops with a warning. Start it explicitly with `rig workspace start --workspace WORKSPACE_ID`, then submit the release action again.
 
 ## Examples
 

deploy/app-rollback.mdx

@@ -24,6 +24,8 @@ The [release list API](/api-reference/app-releases/list) returns up to 50 record
 
 ## Roll back
 
+The workspace must already be running. If it is inactive, rollback stops with a warning; start it explicitly with `rig workspace start --workspace my-project`, wait for it to be running, and submit rollback again. History and stored logs remain available while it is stopped. The UI also disables rollback and manual deployment retry while inactive.
+
 ```bash
 rig app-release rollback --workspace my-project --release <RELEASE_ID>
 ```

deploy/stage-and-activate.mdx

@@ -5,7 +5,9 @@ description: "Prepare an incremental release without immediately changing runnin
 
 ## Prepare the release
 
-From your local project directory, target an existing workspace:
+From your local project directory, target an existing running workspace. If it is inactive, start it explicitly with `rig workspace start --workspace my-project` and wait until it is running before submitting the release. Incremental deployment and activation stop with a warning instead of starting it or queuing the action for later.
+
+Then prepare the release:
 
 ```bash
 rig deploy --workspace my-project --strategy incremental --sync-only

openapi/app-releases-api.json

@@ -103,6 +103,16 @@
                 }
               }
             }
+          },
+          "409": {
+            "description": "Workspace is inactive or not ready, or another deployment owns an app in the release. When a GitHub connection owns it, `details` has `reason: github_connection`, the refused `apps`, and the `connection` (`id`, `repository`, `branch`, `mode`)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiErrorBody"
+                }
+              }
+            }
           }
         },
         "security": [
@@ -189,6 +199,16 @@
                 }
               }
             }
+          },
+          "409": {
+            "description": "Workspace is inactive or not ready, or the release cannot be activated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiErrorBody"
+                }
+              }
+            }
           }
         },
         "security": [
@@ -704,6 +724,34 @@
           }
         },
         "additionalProperties": false
+      },
+      "ApiErrorBody": {
+        "type": "object",
+        "description": "JSON body returned for all errors.",
+        "required": [
+          "error"
+        ],
+        "properties": {
+          "error": {
+            "$ref": "#/components/schemas/ApiErrorDetail"
+          }
+        }
+      },
+      "ApiErrorDetail": {
+        "type": "object",
+        "required": [
+          "code",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "details": {},
+          "message": {
+            "type": "string"
+          }
+        }
       }
     }
   }