From d3b6cbf74fdff06b8780e065594532c733bdb365 Mon Sep 17 00:00:00 2001
From: "paseo-bot[bot]" <266920839+paseo-bot[bot]@users.noreply.github.com>
Date: Mon, 19 Oct 2026 17:39:48 +0200
Subject: [PATCH] docs(schedules): explain archive-on-finish behavior

The schedule and worktree guides omitted the existing retention control and its default. Document the app setting and clarify that CLI and MCP tools do not expose it.
---
 packages/website/src/schedule-docs.test.ts | 16 ++++++++++++++++
 public-docs/mcp.md                         |  2 ++
 public-docs/schedules-cli.md               |  2 ++
 public-docs/schedules.md                   |  8 ++++++++
 public-docs/worktrees.md                   |  2 ++
 5 files changed, 30 insertions(+)
 create mode 100644 packages/website/src/schedule-docs.test.ts

diff --git a/packages/website/src/schedule-docs.test.ts b/packages/website/src/schedule-docs.test.ts
new file mode 100644
index 0000000000..015d85fe6c
--- /dev/null
+++ b/packages/website/src/schedule-docs.test.ts
@@ -0,0 +1,16 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { expect, it } from "vitest";
+
+const docsRoot = path.resolve(import.meta.dirname, "../../../public-docs");
+
+it.each(["schedules.md", "schedules-cli.md", "mcp.md", "worktrees.md"])(
+  "%s makes schedule run retention discoverable",
+  async (file) => {
+    const markdown = await readFile(path.join(docsRoot, file), "utf8");
+    expect(markdown).toContain("Archive on finish");
+    if (file !== "schedules.md") {
+      expect(markdown).toContain("/docs/schedules#keep-run-workspaces");
+    }
+  },
+);
diff --git a/public-docs/mcp.md b/public-docs/mcp.md
index 58e8a2db56..f90ae2a50b 100644
--- a/public-docs/mcp.md
+++ b/public-docs/mcp.md
@@ -155,6 +155,8 @@ Both use the same cron engine, but they have deliberately different interfaces.
 
 MCP heartbeats are ephemeral: create or delete them. To change one, delete it and create a replacement. Pause, resume, update, inspect, logs, and run-once apply to new-agent schedules only.
 
+New-agent run workspaces are archived when each run ends by default. `create_schedule` and `update_schedule` do not expose **Archive on finish** (`archiveOnFinish`); [change the option in the app](/docs/schedules#keep-run-workspaces) to keep subsequent run workspaces active.
+
 ### Agent profiles
 
 | Tool            | Function                                                                                                                           |
diff --git a/public-docs/schedules-cli.md b/public-docs/schedules-cli.md
index 8f1fd62302..272d1a808b 100644
--- a/public-docs/schedules-cli.md
+++ b/public-docs/schedules-cli.md
@@ -10,6 +10,8 @@ category: Schedules
 
 `paseo schedule` creates and manages new-agent [schedules](/docs/schedules) from your terminal, useful for headless boxes and scripts. Every run starts a fresh agent.
 
+Run workspaces are archived when each run ends by default. The CLI has no **Archive on finish** flag; [change the option in the app](/docs/schedules#keep-run-workspaces) to keep subsequent run workspaces active.
+
 ## Create
 
 Overnight refactor on Codex:
diff --git a/public-docs/schedules.md b/public-docs/schedules.md
index 2f6405a2ba..b18804c117 100644
--- a/public-docs/schedules.md
+++ b/public-docs/schedules.md
@@ -35,3 +35,11 @@ Both run on a cadence you set. To start an agent from an external event instead
 - **[From chat](/docs/schedules-chat)** — ask the agent in a chat and it sets the schedule up for you.
 - **[From the CLI](/docs/schedules-cli)** — `paseo schedule create`, for headless boxes and scripts.
 - **[Over MCP](/docs/mcp)** — agents create and manage schedules programmatically.
+
+## Keep run workspaces
+
+Each new-agent schedule run creates a workspace. **Archive on finish** is on by default: when the run ends, Paseo archives that workspace and its agent. With worktree isolation, archiving also removes the worktree after its last active workspace is archived.
+
+To keep runs available, open the schedule in the app's Schedules view, turn off **Archive on finish**, and save. Paseo keeps each run's workspace and agent active until you archive them; runs that fail before creating an agent are still cleaned up. This option also applies to local isolation; archiving a local workspace leaves the project directory in place.
+
+The stored option is `target.config.archiveOnFinish`, a boolean that defaults to `true` when omitted. The CLI and MCP schedule tools do not expose this option; use the app to change it. Heartbeats use an existing agent and do not have this option.
diff --git a/public-docs/worktrees.md b/public-docs/worktrees.md
index 3302233851..5bb1db793f 100644
--- a/public-docs/worktrees.md
+++ b/public-docs/worktrees.md
@@ -40,6 +40,8 @@ With a custom root, Paseo keeps the same hashed layout under that directory:
 3. Review the diff against the base branch
 4. Merge or archive the workspace; after the last workspace using it is archived, Paseo runs teardown and removes the worktree
 
+Scheduled runs archive their workspaces when they finish by default. Turn off **Archive on finish** in the schedule's app form to [keep run workspaces](/docs/schedules#keep-run-workspaces) and their worktrees until you archive them.
+
 ## Create a worktree-backed workspace
 
 The examples below use the current directory as the source checkout. Pass `--path ~/dev/my-app` to create the workspace from another checkout.