docs(deploy): explain persistent app releases and rollback

api-reference/app-releases/activate.mdx

@@ -0,0 +1,11 @@
+---
+title: Activate or Roll Back an App Release
+openapi: POST /api/v1/workspaces/{id}/app-releases/{release_id}/activate
+description: Activate a ready candidate or restore a retained successful app release.
+---
+
+This endpoint does not require a request body. New activation work returns **202 Accepted**; selecting the already-current artifact can return **200 OK**. Poll the returned release ID, which may identify a new activation of a retained artifact.
+
+Activation briefly restarts affected services on their original ports and verifies readiness. The workspace, SSH sessions, unrelated apps, and persistent data remain in place. Code rollback does not undo database migrations or restore runtime data.
+
+An expired artifact, conflicting operation, or incompatible ownership cannot be activated. See [release and rollback guidance](/guides/releases-and-rollback).

api-reference/app-releases/get.mdx

@@ -0,0 +1,9 @@
+---
+title: Get an App Release
+openapi: GET /api/v1/workspaces/{id}/app-releases/{release_id}
+description: Retrieve the status and retained metadata of one workspace app release.
+---
+
+Statuses include `staging`, `ready`, `activating`, `succeeded`, `failed`, and `expired`. A ready candidate has finished staging but is not serving traffic until activated.
+
+Release metadata excludes the encrypted deployment payload. Use the logs endpoint for progress and errors.

api-reference/app-releases/list.mdx

@@ -0,0 +1,9 @@
+---
+title: List App Releases
+openapi: GET /api/v1/workspaces/{id}/app-releases
+description: List retained app releases and activation history for a workspace.
+---
+
+The response identifies current releases with `is_current` and available rollback targets with `can_rollback`. Use these fields instead of inferring the active version from creation time.
+
+See [app releases and rollback](/guides/releases-and-rollback) for retention and persistent-data behavior.

api-reference/app-releases/logs.mdx

@@ -0,0 +1,7 @@
+---
+title: Get App Release Logs
+openapi: GET /api/v1/workspaces/{id}/app-releases/{release_id}/logs
+description: Read staging and activation progress for an app release.
+---
+
+The response contains log lines for the selected release. Poll while an operation is running, and use the release status to determine completion. The CLI provides the same view with `rig app-release logs --workspace <workspace> --release <release-id>`.

api-reference/app-releases/stage.mdx

@@ -0,0 +1,11 @@
+---
+title: Stage an App Release
+openapi: POST /api/v1/workspaces/{id}/app-releases
+description: Prepare app source and dependencies inside an existing running workspace.
+---
+
+Returns **202 Accepted** while staging runs. Staging preserves the workspace and does not activate the candidate. Poll the release and its logs, then activate it when its status is `ready`.
+
+Reuse the same `idempotency_key` only for the same request. Duplicate submissions return the existing attempt; a changed request with the same key is rejected. Failed or interrupted installation is not silently replayed.
+
+For normal deployments, [use the CLI](/guides/deploying) to collect source files and validate the manifest. Runtime secrets belong in the request’s protected runtime configuration, not in Git or source archives.

docs.json

@@ -141,6 +141,16 @@
               "api-reference/apps/verify-domain"
             ]
           },
+          {
+            "group": "App Releases",
+            "pages": [
+              "api-reference/app-releases/list",
+              "api-reference/app-releases/stage",
+              "api-reference/app-releases/get",
+              "api-reference/app-releases/activate",
+              "api-reference/app-releases/logs"
+            ]
+          },
           {
             "group": "App Logs",
             "pages": [

guides/deploy-button.mdx

@@ -11,8 +11,8 @@ A **Deploy to Rigbox** button opens workspace creation with a repository, branch
 2. Connect GitHub. Select an existing fork, including a renamed fork, or choose **Fork on GitHub**. Forking opens a separate tab. Return to Rigbox and select **Refresh after forking**, then **Continue with my fork**.
 3. If the fork is missing, grant the Rigbox GitHub App access to it and refresh the connection. Choose the correct GitHub account when you have several connected accounts.
 4. Choose **New workspace**, or select a workspace you already own. Previous deployments of the same example are marked in the destination list.
-5. Review the apps and resource allocation. Choose **Deploy with defaults**, or **Customize** to edit resources, app settings, and YAML. Required settings and secrets must be supplied; invalid manifests and insufficient capacity block deployment.
-6. Rigbox starts the workspace, queues deployment, and opens its detail page. Follow the build and deployment progress there. HTTP services get app links; CLI tools are available from the workspace terminal or SSH.
+5. Review the apps, deployment strategy, and resource allocation. Choose **Deploy with defaults**, or **Customize** to edit resources, app settings, and YAML. Required settings and secrets must be supplied; invalid manifests and insufficient capacity block deployment.
+6. Rigbox starts the workspace, queues deployment, and opens its detail page. Follow app-release progress and logs there (or image-build logs for an image deployment). HTTP services get app links; CLI tools are available from the workspace terminal or SSH.
 
 The badge source must be a public GitHub repository. Your fork is checked using GitHub repository identity and ancestry, so renaming a fork is supported. The GitHub App needs access to the selected fork; the flow does not expand its permissions or retain a GitHub user token.
 
@@ -26,9 +26,19 @@ Redeploying the same target reuses its branch. Existing connections keep their c
 
 ## Existing workspaces
 
-Rigbox imports the workspace's actual vCPU, RAM, disk, and base image into the configuration preview. Confirm **root-filesystem and app replacement** before deploying. Persistent volumes are retained; changes stored only on the root filesystem are replaced.
+Rigbox imports the workspace's actual vCPU, RAM, disk, and base image into the configuration preview. New connections default to **app releases** unless the manifest explicitly selects image mode. App deployment preserves workspace identity, root files, development tools, and SSH sessions. It stages code separately from your development checkout, then briefly restarts affected services on their existing ports.
 
-If the workspace already has a different automatic deployment connection, review and explicitly confirm replacing it. Rigbox keeps one active automatic deployment connection per workspace. Adding apps without replacing the root filesystem is a separate planned capability.
+**Image replacement** is an explicit advanced strategy. Confirm root-filesystem replacement before using it on an existing workspace. Persistent volumes are retained; arbitrary root-filesystem changes are replaced. Some catalog examples retain image mode because their installers change system packages or global tool configuration.
+
+Existing image-based connections keep their strategy until you explicitly review a change. Changing strategy does not automatically adopt existing apps: conflicting app ownership requires a separate import and cannot be bypassed by matching an app name. Never delete an app or enable reimaging merely to work around that conflict.
+
+If the workspace already has another automatic deployment connection, explicitly review replacement. Rigbox keeps one active automatic deployment connection per workspace. Resource changes and volume provisioning are separate workspace operations; incremental deployment requires declared volumes to exist already.
+
+## App releases and rollback
+
+The workspace detail page shows app-release history and deployment logs. Restore a retained release to return affected apps to its code and configuration. Services briefly restart; the workspace and SSH sessions stay in place. Database migrations, uploads, and other persistent data are not rolled back. Your Git branch stays unchanged, so its next push can deploy newer code again.
+
+No preview workspace, alternate port, promotion, or blue-green stage is part of this flow. See [Releases and rollback](/guides/releases-and-rollback) for the separate app and image operations.
 
 ## Secrets and retries
 

guides/deploying.mdx

@@ -1,11 +1,11 @@
 ---
 title: Deploying with rig deploy
-description: Ship a project to a workspace from a single rig.yaml — the standard rsync deploy, reproducible frozen-image builds, multi-app graphs, and blue-green promotion.
+description: Deploy app releases inside a persistent workspace, with explicit image replacement available for environment rebuilds.
 ---
 
 `rig deploy` is the one command that takes a project on your machine and runs it as a live app in a Rigbox workspace. It reads a `rig.yaml` in the project directory, resolves a target workspace, syncs your code, and brings the service up behind a public subdomain.
 
-For push-to-deploy workflows, use the [GitHub Actions guide](/guides/github-actions). It deploys to a bound workspace with a short-lived credential.
+For push-to-deploy workflows, connect the GitHub App in workspace creation or settings, use a [Deploy button](/guides/deploy-button), or configure [GitHub Actions](/guides/github-actions).
 
 ```bash
 cd my-app
@@ -179,31 +179,73 @@ health:
 
 ## Deploy modes
 
-`rig deploy` picks its mode from `rig.yaml`. There is **no `--reproducible` flag** — the app-level `reproducible: true` key is the only signal.
+Choose `--strategy incremental|image` or declare `workspace.deployment.strategy` in `rig.yaml`. The explicit CLI option takes precedence over the manifest. Without an explicit strategy, the legacy `reproducible: true` setting retains image behavior; otherwise source apps default to incremental. New GitHub connections use the reviewed explicit strategy, and existing bindings retain their previous behavior.
 
-### Standard deploy
+### Incremental app releases
 
-With `reproducible` unset (or `false`) and local source, `rig deploy`:
-
-1. Rsyncs the app directory into the workspace.
-2. Runs `install:` on the VM.
-3. (Re)starts the service.
-
-This is the default and fits most apps with fast installs.
+An incremental deployment keeps the workspace running and installs app files in a managed release directory, separate from your development checkout. It stages source, installs dependencies when needed, builds the app, then briefly restarts affected services on their original ports and checks health. Your SSH session, tools, unrelated apps, and development files remain in place.
 
 ```yaml
 name: my-app
+workspace:
+  deployment:
+    strategy: incremental
 port: 8080
+install: npm ci
+dependencyInputs: [package.json, package-lock.json]
+build: npm run build
 start: node server.js
-install: npm ci && npm run build
 health: { path: /healthz, timeoutSeconds: 30 }
 ```
 
+`dependencyInputs` lists exact files relative to the app source directory. Use it only when those files describe all installation inputs. Matching inputs and runtime allow safe reuse; missing or empty inputs run installation conservatively. Source-dependent work belongs in `build`, not a dependency-only installation step. Avoid mutable shared environments and globally installed dependencies; Python apps should use a release-local virtual environment.
+
+For an installation whose dependencies can remain read-only, declare the generated directories with `dependencyOutputs`. Rigbox retains these immutable outputs separately, so source-only updates reuse the same dependency environment instead of copying its entire file tree:
+
+```yaml
+install: npm ci --omit=dev
+dependencyInputs: [package.json, package-lock.json]
+dependencyOutputs: [node_modules]
+start: node server.js
+```
+
+This optional mode requires nonempty `install` and `dependencyInputs`, and currently cannot be combined with `build`, `configure`, or `reconfigure` hooks. Output paths must be safe, non-overlapping relative directories; they cannot overlap source files or dependency inputs. Runtime writes belong in `RIGBOX_APP_DATA_DIR`, not in cached dependencies. Omit `dependencyOutputs` to retain ordinary release-local copying. Each release keeps its dependency version for rollback; changing installation inputs can require another full installation and additional storage.
+
+Install/build commands run under an unprivileged app identity inside the guest. They cannot use sudo or modify arbitrary workspace paths. Services use that identity and receive `RIGBOX_APP_DATA_DIR`, a persistent app-owned directory outside release files. This data survives app updates and app rollback, but it is not a substitute for backups or a promise about workspace deletion. Declared workspace volumes must already exist; provisioning volumes and changing workspace resources are separate operations.
+
+CLI apps declare controlled entrypoints rather than writing global symlinks themselves:
+
+```yaml
+name: tools
+kind: cli
+workspace:
+  deployment:
+    strategy: incremental
+executables:
+  workspace-info: bin/workspace-info
+```
+
+Each executable path is relative to the release. Rigbox registers the command, preserving the SSH user's arguments, terminal input, and working directory. A CLI health command is optional when executables are declared; otherwise provide an explicit `health.command`. Activation changes subsequent invocations, not already-running CLI processes.
+
+Source transfer excludes environment files, version-control metadata, dependency directories, and generated build output. It rejects symlinks and oversized payloads. Keep runtime secrets in Rigbox secret inputs, never in source files. Custom working directories are not supported by the managed release layout.
+
+To resume a specific attempt explicitly, keep the deployment identifier stable:
+
+```bash
+rig deploy --strategy incremental --deployment-id release-2026-09-08
+```
+
+Identifiers contain 1–128 letters, numbers, dots, underscores, or hyphens. Duplicate submissions use persisted deployment state; a failed attempt is not implicitly replayed. Inspect its app-release logs before explicitly retrying with the same identifier; do not create another workspace as a retry mechanism. Installation scripts with external side effects must still be written defensively.
+
+Use `rig app-release ls --workspace <workspace>` and `rig app-release rollback --workspace <workspace> --release <id>` for app history and rollback. Restoring a release briefly restarts its apps, without restoring database contents or undoing migrations. Existing unmanaged apps require explicit ownership import; a matching name is not enough to adopt them. No fallback reimage occurs after an incremental failure.
+
+Managed app runtime configuration remains in `rig.yaml`. To change commands, parameters, or environment, update the manifest and deploy a new release. Direct parameter/environment edits and source-refresh shortcuts are rejected for release-managed apps so retained configuration stays accurate. Display name, access controls, and ordinary service start/stop/restart remain separate controls when no deployment operation is active.
+
 ### Reproducible deploy
 
-> **`reproducible: true` in `rig.yaml` makes the deploy reproducible — the same `install:` script, frozen once.**
+> **Image mode is an explicit environment rebuild. It replaces the workspace root filesystem; it is separate from an app release.**
 
-When an app sets `reproducible: true`, `rig deploy` runs its `install:` script in an isolated builder workspace and freezes the result into a content-addressed image. It boots the target from that image digest. With `source.kind: local`, app code is then synced from your machine. With `source.kind: git`, the builder fetches the resolved commit and the CLI does not overlay the local checkout.
+With `workspace.deployment.strategy: image` (or legacy `reproducible: true` when no explicit strategy is set), `rig deploy` runs its `install:` script in an isolated builder workspace and freezes the result into a content-addressed image. It boots the target from that image digest. With `source.kind: local`, app code is then synced from your machine. With `source.kind: git`, the builder fetches the resolved commit and the CLI does not overlay the local checkout.
 
 ```yaml
 name: ai-chat
@@ -216,7 +258,7 @@ start: uvicorn chat:app --host 0.0.0.0 --port 8080
 health: { path: /healthz, timeoutSeconds: 30 }
 ```
 
-Nothing about the manifest changes except the flag: the same `install:` you would run on every standard deploy is what gets frozen. The image is always built on top of the platform base image (`workspace.image`, default `base`), so the agent and systemd are present and you keep the platform's opinions while layering your own dependencies on top.
+In image mode: the same `install:` you would run on every standard deploy is what gets frozen. The image is always built on top of the platform base image (`workspace.image`, default `base`), so the agent and systemd are present and you keep the platform's opinions while layering your own dependencies on top.
 
 <Note>
 Install dependencies to system paths, such as pip `--break-system-packages`, so deployed code can find them. Git source is fetched into the build at its resolved commit; local source is synced after the image is ready.
@@ -286,8 +328,8 @@ Every reproducible deploy also auto-records a **release** (an image digest + run
 
 #### When to use which
 
-- **`install:` alone** — simple apps with fast installs. The default.
-- **`reproducible: true`** — heavier or slower installs you want frozen and byte-identical across deploys and rollbacks. `rig deploy` freezes and mounts the image for you, and only rebuilds when the build inputs change.
+- **Incremental strategy** — normal app updates in a persistent development workspace, with retained app releases.
+- **Image strategy** — reviewed environment rebuilds and installers that require system-level changes. Existing image connections retain their behavior until an explicitly reviewed migration.
 
 ---
 
@@ -314,6 +356,8 @@ Application environment values are stored in plaintext metadata and are readable
 
 ## Blue-green deploys and promotion
 
+These are separate advanced operations. Incremental app releases do not create preview workspaces, move your SSH connection, change ports, or promise uninterrupted service.
+
 For zero-downtime rollouts, stage a change, verify it, then swap production over atomically — either a whole-workspace clone (`rig deploy --bluegreen preview`) or an in-VM sibling (`rig deploy --bluegreen <suffix>`), each cut over with `--promote`. See **[Blue-green deploys & promotion](/guides/bluegreen)** for both flows, the service-host-vs-live-environment boundary, and rollback.
 
 ---