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

@@ -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");
+    }
+  },
+);

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                                                                                                                           |

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:

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.

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.