Screenshots: recapture all for v2026.1012.0 and align guides with the release UI (#150)

## Summary

Every docs screenshot is retaken from Paperclip **v2026.1012.0**, in
light and dark. Verifying them showed that about 50 guides described UI
the release had moved or renamed, so those guides are updated too.

**Screenshots**
- 138 automated captures (276 PNGs), all stamped `v2026.1012.0`
(`bba6a45`). The final run had no failed steps or skipped captures, and
the luminance and theme check passes on all 278 files.
- Four independent reviewers checked every light shot against its
caption, then a fix round cleared the findings.
- 37 captures (74 PNGs) are retired: none is embedded on any page, or
the screen no longer exists in the release.
- The capture pipeline (`scripts/screenshots/*`) is fixed for the
release UI:
- turns off the remote "Introducing Connectors" announcement that
covered most shots;
  - masks local temp paths as `~/acme/…`;
- keeps the demo company quiet during capture (no recovery loops, no
capture-created activity rows);
- seeds the states the guides describe: status cards, 50/80/100%
budgets, a blocked inbox, schedule triggers, a checkbox confirmation,
skills-capable agents and more;
- uses updated routes and steps for the moved UI, and gains
`scrollToTop`, `readyText`, per-target `experimental` flags, and comma
lists for `--only`.
- **The budget shots show a fixed incident card.** In v2026.1012.0 a
warning-threshold incident is labelled "hard stop · This scope is
paused", which is wrong. The fix is
[paperclipai/paperclip#16201](https://github.com/paperclipai/paperclip/pull/16201).
The costs and budget shots were captured from v2026.1012.0 with that
patch applied, and the budget guides say so and explain what
v2026.1012.0 itself shows.

**Docs aligned with the release UI**
- **Audit:** costs, budgets, runs and the timeline moved under Audit.
That covers Costs and Budgets, Activity Log, Work Timeline, Set a
monthly budget, and Dashboard.
- **Agents:** the agent page's side menu (**Overview**, **Harness /
Runtime**), the two-step **New agent** dialog, **Run now**, and the org
chart as a view toggle. That covers Agents, Your first agent, Watching
agents work, Key concepts, Org structure, Agent adapters and Adapters.
- **Projects, routines, tasks, approvals:** current tabs, buttons and
flows.
- **Skills, plugins, company, settings:** current labels, including
instant-join invites, the Experimental settings list, and **Settings →
Experimental** paths on 21 pages.
- **Removed features:** Auto-Create Recovery Tasks and Cloud Sync are
marked as removed in this release.
- Every rewrite was checked against the v2026.1012.0 UI source, then by
two independent verifiers. A changelog entry is added under
v2026.1012.0.

## Checks
- [x] `npm run docs:build`
- [x] `npm run docs:test` (all suites)
- [x] `sync:lint-links` and `sync:verify-nav`: only the 4 intentional
orphans remain
- [x] SEO metadata and crawlable links

## Known, accepted
- The activity feeds lead with agent setup events rather than task
events.
- The dashboard agent strip shows two cards for Ada.
- Agent budgets can only be created from the CLI or API in this release,
and the guides say so.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>

SCREENSHOTS_PENDING.md

@@ -1,134 +1,5 @@
 # Screenshots Pending
 
-Regenerated by /sync-docs (release). Lists screenshots whose `depends_on` parent paths changed in the release window: base release tag `v2026.1005.0` (`467125fa`) -> release tag `v2026.1012.0` (`bba6a45f`), 132 commits, 1,242 files.
+Regenerated by /sync-docs. Lists screenshots whose `depends_on` parent paths changed since they were captured.
 
-**126 of 350 screenshots are stale** across 26 routes. None were recaptured in this release; refresh separately with `npm run screenshots:refresh`. PNGs go to a PR for human review and are never auto-pushed.
-
-| Screenshot | Route | Theme | Changed dependency paths |
-|---|---|---|---|
-| `dark/agents/adapter-type-dropdown.png` | `/ACME/agents/new` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/agents/agent-detail-idle.png` | `/ACME/agents/{agentId}` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/agent-detail-run-history.png` | `/ACME/agents/{agentId}/runs` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/agent-status-running.png` | `/ACME/agents/{longRunnerAgentId}` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/budget-and-heartbeat-fields.png` | `/ACME/agents/new` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/agents/budget.png` | `/ACME/agents/{agentId}/budget` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/claude-local-config-filled.png` | `/ACME/agents/new` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/agents/codex-local-config.png` | `/ACME/agents/new` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/agents/configuration.png` | `/ACME/agents/{agentId}/configuration` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/dashboard.png` | `/ACME/agents/{agentId}/dashboard` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/heartbeat-toggle-disabled.png` | `/ACME/agents/{agentId}/configuration` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/agents/heartbeat-toggle-enabled.png` | `/ACME/agents/{agentId}/configuration` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/agents/http-adapter-config.png` | `/ACME/agents/{httpAgentId}/configuration` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/agents/instructions.png` | `/ACME/agents/{agentId}/instructions` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/run-history-in-progress.png` | `/ACME/agents/{longRunnerAgentId}/runs` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/run-transcript-view.png` | `/ACME/agents/{runnerAgentId}/runs/{runnerRunId}` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/runs.png` | `/ACME/agents/{agentId}/runs` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/skills.png` | `/ACME/agents/{agentId}/skills` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/agents/test-environment-fail.png` | `/ACME/agents/new` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/agents/test-environment-success.png` | `/ACME/agents/{runnerAgentId}/configuration` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/company/company-budget-setting.png` | `/ACME/agents/{agentId}/configuration` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/company/join-requests.png` | `/ACME/inbox/requests` | dark | ui/src/pages/Inbox.tsx |
-| `dark/costs/agent-budget-field.png` | `/ACME/agents/{agentId}/budget` | dark | ui/src/pages/AgentDetail.tsx |
-| `dark/dashboard/activity-feed.png` | `/ACME/dashboard` | dark | ui/src/pages/Dashboard.tsx |
-| `dark/dashboard/agent-status-panel.png` | `/ACME/dashboard` | dark | ui/src/pages/Dashboard.tsx |
-| `dark/dashboard/cost-summary-panel.png` | `/ACME/dashboard` | dark | ui/src/pages/Dashboard.tsx |
-| `dark/dashboard/dashboard-overview.png` | `/ACME/dashboard` | dark | ui/src/pages/Dashboard.tsx |
-| `dark/dashboard/task-breakdown-panel.png` | `/ACME/dashboard` | dark | ui/src/pages/Dashboard.tsx |
-| `dark/experimental/recovery-preview.png` | `/ACME/company/settings/instance/experimental` | dark | ui/src/pages/InstanceExperimentalSettings.tsx |
-| `dark/github-review/connect.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | dark | ui/src/pages/apps/chat/GitHubSetupPrompt.tsx |
-| `dark/github-review/identity.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | dark | ui/src/pages/apps/chat/GitHubSetupPrompt.tsx |
-| `dark/github-review/prompts.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | dark | ui/src/pages/apps/chat/GitHubSetupPrompt.tsx |
-| `dark/github-review/repositories.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | dark | ui/src/pages/apps/chat/GitHubSetupPrompt.tsx |
-| `dark/interactions/checkbox-confirmation-card.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx, ui/src/components/IssueThreadInteractionCard.tsx |
-| `dark/issues/detail-activity.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx |
-| `dark/issues/detail-chat.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx |
-| `dark/issues/detail-sidebar.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx |
-| `dark/issues/inbox-requests.png` | `/ACME/inbox/requests` | dark | ui/src/pages/Inbox.tsx |
-| `dark/issues/inbox-unread.png` | `/ACME/inbox/unread` | dark | ui/src/pages/Inbox.tsx |
-| `dark/issues/inbox.png` | `/ACME/inbox/mine` | dark | ui/src/pages/Inbox.tsx |
-| `dark/issues/list.png` | `/ACME/issues` | dark | ui/src/pages/IssueDetail.tsx |
-| `dark/issues/my-issues.png` | `/ACME/inbox/mine` | dark | ui/src/pages/Inbox.tsx |
-| `dark/onboarding/budget-field.png` | `/ACME/agents/{agentId}/configuration` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/onboarding/empty-dashboard.png` | `/{emptyPrefix}/dashboard` | dark | ui/src/pages/Dashboard.tsx |
-| `dark/org/reassign.png` | `/ACME/agents/{agentId}/configuration` | dark | ui/src/components/AgentConfigForm.tsx |
-| `dark/secrets/dispatch-check.png` | `/ACME/company/settings/secrets` | dark | server/src/services/secrets.ts |
-| `dark/settings/experimental.png` | `/ACME/company/settings/instance/experimental` | dark | ui/src/pages/InstanceExperimentalSettings.tsx |
-| `dark/task-chat/composer-modes.png` | `/ACME/issues/{issueId}` | dark | ui/src/components/task-chat/TaskChatComposer.tsx |
-| `dark/task-chat/thread.png` | `/ACME/issues/{issueId}` | dark | ui/src/components/TaskChatThread.tsx, ui/src/components/task-chat/TaskChatTurn.tsx |
-| `dark/tasks/comment-input-box.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx |
-| `dark/tasks/inbox-newly-created-tasks.png` | `/ACME/inbox/recent` | dark | ui/src/pages/Inbox.tsx |
-| `dark/tasks/inbox-view-with-filters.png` | `/ACME/inbox/all` | dark | ui/src/pages/Inbox.tsx |
-| `dark/tasks/inbox-view.png` | `/ACME/inbox/mine` | dark | ui/src/pages/Inbox.tsx |
-| `dark/tasks/new-task-form-empty.png` | `/ACME/inbox/mine` | dark | ui/src/pages/Inbox.tsx |
-| `dark/tasks/new-task-form-filled.png` | `/ACME/inbox/mine` | dark | ui/src/pages/Inbox.tsx |
-| `dark/tasks/task-detail-in-progress.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx |
-| `dark/tasks/task-detail-with-comments.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx |
-| `dark/tasks/task-done-status.png` | `/ACME/issues/done` | dark | ui/src/pages/Inbox.tsx |
-| `dark/watchdogs/watchdog-thread-outcome.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx |
-| `dark/work-modes/ask-mode-answer.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx, ui/src/components/IssueChatThread.tsx |
-| `dark/work-modes/plan-mode-plan.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx |
-| `dark/work-modes/standard-mode-run.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx, ui/src/components/IssueChatThread.tsx |
-| `dark/work-modes/work-mode-picker.png` | `/ACME/inbox/mine` | dark | ui/src/components/NewIssueDialog.tsx |
-| `light/agents/adapter-type-dropdown.png` | `/ACME/agents/new` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/agents/agent-detail-idle.png` | `/ACME/agents/{agentId}` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/agent-detail-run-history.png` | `/ACME/agents/{agentId}/runs` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/agent-status-running.png` | `/ACME/agents/{longRunnerAgentId}` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/budget-and-heartbeat-fields.png` | `/ACME/agents/new` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/agents/budget.png` | `/ACME/agents/{agentId}/budget` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/claude-local-config-filled.png` | `/ACME/agents/new` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/agents/codex-local-config.png` | `/ACME/agents/new` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/agents/configuration.png` | `/ACME/agents/{agentId}/configuration` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/dashboard.png` | `/ACME/agents/{agentId}/dashboard` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/heartbeat-toggle-disabled.png` | `/ACME/agents/{agentId}/configuration` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/agents/heartbeat-toggle-enabled.png` | `/ACME/agents/{agentId}/configuration` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/agents/http-adapter-config.png` | `/ACME/agents/{httpAgentId}/configuration` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/agents/instructions.png` | `/ACME/agents/{agentId}/instructions` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/run-history-in-progress.png` | `/ACME/agents/{longRunnerAgentId}/runs` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/run-transcript-view.png` | `/ACME/agents/{runnerAgentId}/runs/{runnerRunId}` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/runs.png` | `/ACME/agents/{agentId}/runs` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/skills.png` | `/ACME/agents/{agentId}/skills` | light | ui/src/pages/AgentDetail.tsx |
-| `light/agents/test-environment-fail.png` | `/ACME/agents/new` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/agents/test-environment-success.png` | `/ACME/agents/{runnerAgentId}/configuration` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/company/company-budget-setting.png` | `/ACME/agents/{agentId}/configuration` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/company/join-requests.png` | `/ACME/inbox/requests` | light | ui/src/pages/Inbox.tsx |
-| `light/costs/agent-budget-field.png` | `/ACME/agents/{agentId}/budget` | light | ui/src/pages/AgentDetail.tsx |
-| `light/dashboard/activity-feed.png` | `/ACME/dashboard` | light | ui/src/pages/Dashboard.tsx |
-| `light/dashboard/agent-status-panel.png` | `/ACME/dashboard` | light | ui/src/pages/Dashboard.tsx |
-| `light/dashboard/cost-summary-panel.png` | `/ACME/dashboard` | light | ui/src/pages/Dashboard.tsx |
-| `light/dashboard/dashboard-overview.png` | `/ACME/dashboard` | light | ui/src/pages/Dashboard.tsx |
-| `light/dashboard/task-breakdown-panel.png` | `/ACME/dashboard` | light | ui/src/pages/Dashboard.tsx |
-| `light/experimental/recovery-preview.png` | `/ACME/company/settings/instance/experimental` | light | ui/src/pages/InstanceExperimentalSettings.tsx |
-| `light/github-review/connect.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | light | ui/src/pages/apps/chat/GitHubSetupPrompt.tsx |
-| `light/github-review/identity.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | light | ui/src/pages/apps/chat/GitHubSetupPrompt.tsx |
-| `light/github-review/prompts.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | light | ui/src/pages/apps/chat/GitHubSetupPrompt.tsx |
-| `light/github-review/repositories.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | light | ui/src/pages/apps/chat/GitHubSetupPrompt.tsx |
-| `light/interactions/checkbox-confirmation-card.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx, ui/src/components/IssueThreadInteractionCard.tsx |
-| `light/issues/detail-activity.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx |
-| `light/issues/detail-chat.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx |
-| `light/issues/detail-sidebar.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx |
-| `light/issues/inbox-requests.png` | `/ACME/inbox/requests` | light | ui/src/pages/Inbox.tsx |
-| `light/issues/inbox-unread.png` | `/ACME/inbox/unread` | light | ui/src/pages/Inbox.tsx |
-| `light/issues/inbox.png` | `/ACME/inbox/mine` | light | ui/src/pages/Inbox.tsx |
-| `light/issues/list.png` | `/ACME/issues` | light | ui/src/pages/IssueDetail.tsx |
-| `light/issues/my-issues.png` | `/ACME/inbox/mine` | light | ui/src/pages/Inbox.tsx |
-| `light/onboarding/budget-field.png` | `/ACME/agents/{agentId}/configuration` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/onboarding/empty-dashboard.png` | `/{emptyPrefix}/dashboard` | light | ui/src/pages/Dashboard.tsx |
-| `light/org/reassign.png` | `/ACME/agents/{agentId}/configuration` | light | ui/src/components/AgentConfigForm.tsx |
-| `light/secrets/dispatch-check.png` | `/ACME/company/settings/secrets` | light | server/src/services/secrets.ts |
-| `light/settings/experimental.png` | `/ACME/company/settings/instance/experimental` | light | ui/src/pages/InstanceExperimentalSettings.tsx |
-| `light/task-chat/composer-modes.png` | `/ACME/issues/{issueId}` | light | ui/src/components/task-chat/TaskChatComposer.tsx |
-| `light/task-chat/thread.png` | `/ACME/issues/{issueId}` | light | ui/src/components/TaskChatThread.tsx, ui/src/components/task-chat/TaskChatTurn.tsx |
-| `light/tasks/comment-input-box.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx |
-| `light/tasks/inbox-newly-created-tasks.png` | `/ACME/inbox/recent` | light | ui/src/pages/Inbox.tsx |
-| `light/tasks/inbox-view-with-filters.png` | `/ACME/inbox/all` | light | ui/src/pages/Inbox.tsx |
-| `light/tasks/inbox-view.png` | `/ACME/inbox/mine` | light | ui/src/pages/Inbox.tsx |
-| `light/tasks/new-task-form-empty.png` | `/ACME/inbox/mine` | light | ui/src/pages/Inbox.tsx |
-| `light/tasks/new-task-form-filled.png` | `/ACME/inbox/mine` | light | ui/src/pages/Inbox.tsx |
-| `light/tasks/task-detail-in-progress.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx |
-| `light/tasks/task-detail-with-comments.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx |
-| `light/tasks/task-done-status.png` | `/ACME/issues/done` | light | ui/src/pages/Inbox.tsx |
-| `light/watchdogs/watchdog-thread-outcome.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx |
-| `light/work-modes/ask-mode-answer.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx, ui/src/components/IssueChatThread.tsx |
-| `light/work-modes/plan-mode-plan.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx |
-| `light/work-modes/standard-mode-run.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx, ui/src/components/IssueChatThread.tsx |
-| `light/work-modes/work-mode-picker.png` | `/ACME/inbox/mine` | light | ui/src/components/NewIssueDialog.tsx |
+**0 of 278 screenshots are stale.** All 276 automated captures were recaptured against release tag `v2026.1012.0` (`bba6a45f`) on 2026-10-13. The remaining 2 files (`dashboard/dashboard-overview-annotated`, light and dark) are hand-annotated on purpose and are not captured by the pipeline.

docs/administration/company.md

@@ -1,7 +1,7 @@
 ---
-paperclip_version: v2026.1005.0
+paperclip_version: v2026.1012.0
 seo_title: Company Administration
-seo_description: Set your company name and logo, manage members and invites, review join requests, and export or import the whole company from one cluster of screens.
+seo_description: Set your organization name and logo, manage members and invites, review join requests, and export or import the whole organization in one place.
 ---
 
 # Company Administration
@@ -14,18 +14,18 @@ This guide walks through each of those surfaces in the order you typically meet
 
 ## General Settings
 
-The **General** page groups the settings that apply to the whole organization rather than to any one agent or project. Open it from the sidebar under the organization name.
+The **General** page groups the settings that apply to the whole organization rather than to any one agent or project. Open **Settings**, and **General** is the first item in the settings sidebar — it's where you land.
 
-Company and instance settings now share one navigation, so this is also where the instance-wide general controls appear. If you are an instance admin, the deployment and auth readiness summary, backup retention, log censoring, and AI feedback-sharing controls all render on this same **General** page — see [Settings](./settings.md#instance-general) for what each one does. Keyboard shortcuts are no longer a setting at all — they're [always on](./settings.md#keyboard-shortcuts) for every signed-in user. The sections below cover the organization-specific settings.
+Company and instance settings now share one navigation, so this is also where the instance-wide general controls appear. Below the organization sections you'll find the deployment and auth readiness summary, log censoring, backup retention, AI feedback sharing, and a **Sign out** button (unless an operator has hidden it) — see [Settings](./settings.md#instance-general) for what each one does. Keyboard shortcuts are no longer a setting at all — they're [always on](./settings.md#keyboard-shortcuts) for every signed-in user. The sections below cover the organization-specific settings.
 
-![Company general settings](../user-guides/screenshots/light/company/settings.png)
+![The General settings page, showing the organization name, description, and logo fields](../user-guides/screenshots/light/company/settings.png)
 
 ### Name and description
 
 The **General** section has two fields:
 
-- **Company name** — the display name shown in the company switcher and across the UI.
-- **Description** — an optional one-line description shown on the company profile. Leave it empty if you do not want one.
+- **Organization name** — the display name shown in the organization switcher and across the UI.
+- **Description** — an optional one-line description shown on the organization profile. Leave it empty if you do not want one.
 
 Changes are not persisted until you click **Save changes**. The save button only appears when one of the fields is dirty, and it is disabled if the name is empty.
 
@@ -45,22 +45,19 @@ The **Hiring** section contains one switch:
 
 The toggle saves immediately; there is no separate save button for this setting.
 
-### Feedback Sharing
+### Interaction governance
 
-The **Feedback Sharing** section controls whether AI outputs you explicitly vote on in Paperclip may also be shared with Paperclip Labs. The toggle is labelled **Allow sharing voted AI outputs with Paperclip Labs**.
+The **Interaction governance** section sets, for each kind of interaction card (suggested tasks, questions, confirmations, and so on), who may respond by default and the strictest audience allowed. Each kind has a **Default policy** and a **Cap**. See [Setting company-wide interaction governance](../guides/day-to-day/issues.md#setting-company-wide-interaction-governance) for how the two work together.
 
-Two things to know:
+### Feedback sharing, Export, and Import
 
-- Votes are always stored locally, regardless of this setting. The toggle only controls whether the voted outputs become eligible for sharing.
-- The section displays the current terms version, and, once sharing is enabled, the timestamp of when it was turned on and who enabled it. A **Read our terms of service** link is shown when the terms URL is configured.
+There's no organization-level feedback toggle on this page anymore. Whether thumbs-up / thumbs-down votes can send AI output to Paperclip Labs is now the instance-wide **AI feedback sharing** setting, further down the same page — see [Settings](./settings.md#ai-feedback-sharing).
 
-### Company Packages shortcuts
-
-Below the feedback section, a **Company Packages** panel links out to the dedicated **Export** and **Import** pages. These are the same pages covered in the last two sections of this guide; the Settings page itself does not perform the export or import.
+The old **Company Packages** shortcuts are gone too. **Export** and **Import** are now their own items in the settings sidebar, and they open the pages covered in the last two sections of this guide.
 
 ### Danger Zone
 
-At the bottom of the page is a **Danger Zone** with an **Archive company** button. Archiving hides the company from the sidebar and persists the change in the database. A confirmation dialog appears before the archive takes effect, and the UI automatically switches you to the next non-archived company if one is available.
+At the bottom of the page is a **Danger Zone** with an **Archive organization** button. Archiving hides the organization from the sidebar and persists the change in the database. A confirmation dialog appears before the archive takes effect, and the UI automatically switches you to the next non-archived organization if one is available.
 
 Archiving also quiets the company so it stops doing work in the background: every active agent is paused (with the pause reason `company_archived`), and any queued or in-flight wake-up requests are cancelled. Archiving is not destructive — unlike deletion, your agents, projects, and issues are all preserved — but the company will not wake its agents again until you bring it back.
 
@@ -113,7 +110,7 @@ Click **Save access** to persist the changes, or **Cancel** to close the dialog
 
 ### Adding and removing members
 
-The Members page does not have an "Add member" button. New humans enter the organization through the invite flow described in the next section, which either produces a direct membership or a pending join request depending on how the invite is consumed. To remove a human, set their **Status** to `suspended` through the Edit dialog; the row stays visible so the audit trail is preserved.
+The Members page does not have an "Add member" button. New humans enter the organization through the invite flow described in the next section, which makes them a member as soon as they accept. To remove a human, set their **Status** to `suspended` through the Edit dialog; the row stays visible so the audit trail is preserved.
 
 ### Pending human joins
 
@@ -123,13 +120,13 @@ If you hold the `joins:approve` grant and there are pending human join requests,
 
 ## Invites
 
-The **Invites** tab of the Members page creates invite links for new humans. Each link is single-use — the first successful use consumes the link and creates or reuses a join request before approval.
+The **Invites** tab of the Members page creates invite links for new humans. Each link is single-use — the first successful use consumes the link. A person who accepts gets the selected role as soon as they sign in; only agent invites still create a join request that someone has to approve.
 
-![Invite link creator](../user-guides/screenshots/light/company/invites.png)
+![The Invites tab, with the Invite a person card and its role choices above the invite history](../user-guides/screenshots/light/company/invites.png)
 
 ### Creating an invite
 
-The **Create invite** card has one required choice: which role the invite should request by default. The options are the four roles described above — **Viewer**, **Operator** (the default), **Admin**, and **Owner** — each rendered with a short description and a one-line summary of what the role gets.
+The **Invite a person** card has one required choice, under **Choose a role**: which role the invite should grant. The options are the four roles described above — **Viewer**, **Operator** (the default), **Admin**, and **Owner** — each rendered with a short description and a one-line summary of what the role gets.
 
 Clicking **Create invite** does three things:
 
@@ -137,7 +134,7 @@ Clicking **Create invite** does three things:
 2. Copies the URL to your clipboard if the browser allows it.
 3. Shows the invite in a **Latest invite link** panel below the form.
 
-If the clipboard is unavailable, Paperclip shows a warning toast and you can copy the URL manually from the field. The invite URL is clickable as an **Open invite** button for quick testing in another tab.
+If the clipboard is unavailable, Paperclip shows a warning toast. Use the **Copy link** button next to the URL, or copy it manually from the field.
 
 ### Invite expiry and state
 
@@ -148,25 +145,25 @@ Invite links have four possible states, shown as a badge in the history table: *
 Below the creator is a paginated **Invite history** table with one row per invite:
 
 - **State** — the badge above.
-- **Role** — the default role the invite requests.
+- **For** — who the invite is for: the role it grants for a human invite, or **Agent** for an agent invite.
 - **Invited by** — the name and email of the human who created the invite.
 - **Created** — the creation timestamp.
-- **Join request** — a link to the join request queue if the invite has produced one.
+- **Join request** — a **Review request** link to the join request queue if the invite has produced one.
 - **Action** — a **Revoke** button for invites still in the `Active` state.
 
 The table shows five invites at a time and includes a **View more** button when there are more pages. An **Open join request queue** link in the header jumps to the full queue.
 
 ### What the invited person sees
 
-When a human opens the invite URL, they land on a Paperclip join page that creates a join request tied to the invite. If the invite carries a default role (for example **Operator**), that role is attached to the request so approvers can see it in context. The member does not become active until someone with `joins:approve` approves the request.
+When a human opens the invite URL, they land on a Paperclip join page. Once they sign in and accept, they join the organization right away with the role the invite carries (for example **Operator**) — no separate approval step. Agent invites work differently: they create a join request, and the agent doesn't join until someone with `joins:approve` approves it.
 
 ---
 
 ## Join Requests
 
-The **Join Request Queue** consolidates every join request — human and agent — that has come in against the company. Open it from `/inbox/requests`, or from the **Open join request queue** link in Invites.
+The **Join Request Queue** consolidates every join request — human and agent — that has come in against the organization. Open it from `/inbox/requests`, or from the **Open join request queue** link in the **Invite history** on the Invites tab. Because human invites now grant access as soon as they're accepted, most of what lands here is agent requests.
 
-![Join request queue](../user-guides/screenshots/light/company/join-requests.png)
+![The Join Request Queue with its Status and Request type filters; the list is empty when nothing is waiting](../user-guides/screenshots/light/company/join-requests.png)
 
 ### Filters
 
@@ -190,24 +187,27 @@ For requests in `pending approval`, the card also shows **Approve** and **Reject
 
 ### Permissions
 
-The queue requires the `joins:approve` grant. Accounts without it see a "You do not have permission to review join requests for this company." message instead of the list.
+The queue requires the `joins:approve` grant. Accounts without it see a "You do not have permission to review join requests for this organization." message instead of the list.
 
 ---
 
 ## Export
 
-The **Company Export** page turns the current company — its agents, projects, tasks, skills, and settings — into a portable markdown package you can download as a zip. Open it from the **Org Chart** header or from the **Export** shortcut on the Settings page.
+The **Export** page turns the current organization — its agents, projects, tasks, skills, and settings — into a portable markdown package you can download as a zip. It's a full page, not a dialog: open it from **Export** in the settings sidebar, or from the **Export organization** button above the Org Chart.
 
-![Export dialog](../user-guides/screenshots/light/company/export.png)
+![The Export page, with the Package files tree on the left and a file preview on the right](../user-guides/screenshots/light/company/export.png)
 
 ### What gets included
 
-When the page loads, Paperclip builds a preview of everything that would be exported. By default the preview includes the company metadata, every non-terminated agent, every non-archived project, and every issue. The preview is rendered as a left-hand **Package files** tree, with a selected-file preview on the right.
+When the page loads, Paperclip builds a preview of everything that would be exported. The preview is rendered as a left-hand **Package files** tree, with a selected-file preview on the right.
 
-The sticky bar at the top of the page shows:
+At the top of the tree, **What to include** has a checkbox per category: **Agents**, **Projects**, **Skills**, **Routines**, **Tasks**, and **Attachments**. Agents, projects, and skills start checked. Tasks, routines, and attachments start unchecked — task and routine history is opt-in because it can be large — so tick them if you want that history in the package. **Attachments** travel with tasks and routines, so it stays greyed out until one of those is checked.
 
-- The company name and a running count of **selected / total files**.
-- Any warnings Paperclip produced while building the preview.
+The bar at the top of the page shows:
+
+- The organization name and a running count of the files you're exporting, with the estimated zip size.
+- An amber warnings count (for example, `2 warnings`) when the preview flagged anything you should look at before downloading.
+- A **Not included in this export** notice listing anything that never goes into a package (approvals, cost events, and activity log entries, for example).
 - A single **Export N files** button that downloads the zip.
 
 ### Selecting what to export
@@ -216,7 +216,7 @@ Every entry in the file tree has a checkbox. Unchecking a file or a directory re
 
 - The tree is searchable with the input above it. Search expands matching directories automatically and restores the previous expansion state when you clear the query.
 - `README.md` and `.paperclip.yaml` are regenerated on the fly so they always reflect the current selection.
-- The `tasks/` directory is paginated — ten entries visible by default, with a **Show more issues** button. Checked and search-matched tasks are always pinned above the fold.
+- The `tasks/` directory is paginated — ten entries visible by default, with a **Show more tasks** button. Checked and search-matched tasks are always pinned above the fold.
 - Clicking a file opens its content in the preview pane. The URL updates as you navigate so you can deep-link to a specific file in the export.
 
 ### Downloading
@@ -229,9 +229,9 @@ For a deeper description of what lives in each file, see [Export & Import](../gu
 
 ## Import
 
-The **Company Import** page is the reverse direction: it takes an exported package and loads it into Paperclip, either as a new company or on top of an existing one.
+The **Import** page is the reverse direction: it takes an exported package and loads it into Paperclip, either as a new organization or on top of an existing one. Open it from **Import** in the settings sidebar, or from the **Import organization** button above the Org Chart.
 
-![Import dialog](../user-guides/screenshots/light/company/import.png)
+![The Import page, with the Import source, Target, and Collision strategy controls](../user-guides/screenshots/light/company/import.png)
 
 ### Choosing a source
 
@@ -244,8 +244,8 @@ The **Import source** section supports two source types:
 
 The **Target** drop-down has two options:
 
-- **Create new company** — the default. An optional **New company name** field lets you override the name from the package.
-- **Existing company** — apply the package on top of the currently selected company.
+- **Create new organization** — the default. An optional **New organization name** field lets you override the name from the package.
+- **Existing company: *name*** — apply the package on top of the currently selected organization.
 
 ### Collision strategy
 

docs/administration/plugins.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.1001.0
+paperclip_version: v2026.1012.0
 seo_title: Plugins: Extending Paperclip
 seo_description: Add dashboard widgets, file browsers, and custom tooling. Covers the Plugin Manager, installing, self-installing plugins, enabling, and handling upgrades.
 ---
@@ -56,7 +56,7 @@ An errored plugin stays installed — you don't need to uninstall and reinstall
 
 ## Installing a plugin
 
-![Install a plugin](../user-guides/screenshots/light/plugins/install.png)
+![The Plugin Manager, with the Install Plugin button in the top right and the Available Plugins list below](../user-guides/screenshots/light/plugins/install.png)
 
 There are two ways to install a plugin yourself. (A small set of sandbox provider plugins also arrives on its own at startup — see *Plugins that install themselves* below.)
 
@@ -101,7 +101,7 @@ This used to be a Kubernetes-only shortcut. It's now a general path with a fixed
 
 The table is the whole built-in allowlist. The only other way a plugin can arrive through auto-provisioning is if the release image itself ships it in a distribution catalog (see [Plugins shipped inside a custom image](#plugins-shipped-inside-a-custom-image) below). Everything else — reference examples, first-party plugins, third-party packages — still gets installed by you, the ordinary way.
 
-Once provisioned, these behave like any other installed plugin: same status badges, same detail page, same Configuration tab. You still choose whether and how to use one, by configuring a sandbox environment under **Settings → Instance settings → Environments**. See [Sandbox Providers](../reference/adapters/sandbox-providers.md) for each provider's fields.
+Once provisioned, these behave like any other installed plugin: same status badges, same detail page, same Configuration tab. You still choose whether and how to use one, by configuring a sandbox environment under **Settings → Environments**. See [Sandbox Providers](../reference/adapters/sandbox-providers.md) for each provider's fields.
 
 ### When it runs, and what you might not see
 
@@ -182,14 +182,14 @@ This gate exists so plugins can't quietly grow permissions on you between versio
 
 ## The plugin detail page
 
-Clicking a plugin's name — or the **Configure** button — opens the plugin detail page. This is where a plugin gets to show you its own surface inside Paperclip.
+Clicking a plugin's name — or the **Configure** button on its row under **Installed Plugins** — opens the plugin detail page. Bundled plugins you've already installed also get an **Open Settings** button in the **Available Plugins** list (it reads **Review** while the plugin isn't `ready`), which goes to the same page. This is where a plugin gets to show you its own surface inside Paperclip.
 
-![Plugin detail page](../user-guides/screenshots/light/plugins/detail.png)
+![A plugin's detail page, with its status and version badges next to the name and the Configuration and Status tabs below](../user-guides/screenshots/light/plugins/detail.png)
 
 The detail page has two tabs:
 
 - **Configuration** — the plugin's description, author, categories, and settings form (or a custom settings UI the plugin ships).
-- **Status** — runtime diagnostics: worker process state, recent scheduled jobs, recent webhook deliveries, live health checks, and a rolling log of recent entries.
+- **Status** — runtime diagnostics: worker process state, recent scheduled jobs, recent webhook deliveries, live health checks, and a rolling log of recent entries. A right-hand column adds **Details** and the plugin's **Permissions**.
 
 A plugin can also declare a **page slot**. When it does, the plugin gets its own route at `/<company-prefix>/plugins/<plugin-id>` and renders whatever it wants there — a full page, a dashboard, a multi-step flow. This is how something like the file-browser example adds a Files tab to project pages, or how a hypothetical CRM plugin might add a Contacts view to the sidebar.
 
@@ -205,7 +205,7 @@ If two plugins happen to contribute a page on the same route, Paperclip refuses
 
 Most plugins have some configuration: an API key, a base URL, a default folder, a list of watched repositories. Paperclip gives plugins two ways to expose that to you.
 
-![Plugin settings](../user-guides/screenshots/light/plugins/settings.png)
+![A plugin's Configuration tab, with the About card above the Settings form](../user-guides/screenshots/light/plugins/settings.png)
 
 **Auto-generated forms.** If the plugin ships a JSON Schema describing its configuration, Paperclip renders a form automatically on the Configuration tab. You fill in the fields, click **Save Configuration**, and Paperclip stores the values securely. For plugins that support it, a **Test Configuration** button appears alongside save — it sends the current form values to the plugin's worker and reports back whether the config works, without persisting anything.
 
@@ -215,9 +215,9 @@ Most plugins have some configuration: an API key, a base URL, a default folder,
 
 Fields the plugin marks as secret (API keys, tokens, passwords) are stored encrypted and never redisplayed in plain text. The form shows a masked placeholder once a secret has been saved; to change it, type a new value and save again. Leaving the masked placeholder as-is keeps the existing secret.
 
-### Permissions sidebar
+### Permissions card
 
-To the right of the settings form, the **Permissions** card lists the capabilities the plugin's manifest declares — a short, readable list of what this plugin is allowed to touch (for example, "read issues in this company", "write to project workspaces", "send outbound webhooks"). These are the same capabilities the `upgrade_pending` gate checks against on upgrade. If a plugin's permissions list doesn't match what you think it should be doing, that's a signal to investigate before enabling it.
+The **Permissions** card lives on the plugin's **Status** tab, in the right-hand column under **Details**. It lists the capabilities the plugin's manifest declares, one per line, by their capability names (for example `issues.read` or `projects.read`). If the plugin doesn't ask for any, the card says *No special permissions requested.* These are the same capabilities the `upgrade_pending` gate checks against on upgrade. If a plugin's permissions list doesn't match what you think it should be doing, that's a signal to investigate before enabling it.
 
 ---
 
@@ -225,15 +225,15 @@ To the right of the settings form, the **Permissions** card lists the capabiliti
 
 Plugins don't just sit there. Many of them run scheduled jobs — a sync every 15 minutes, a nightly reconciliation, a cleanup pass every Sunday — or receive webhooks from external services. The **Status** tab on the plugin detail page is where you see that activity.
 
-![Plugin jobs log](../user-guides/screenshots/light/plugins/jobs-log.png)
+![A plugin's Status tab, with the Runtime Dashboard showing the worker process, recent job runs, and recent webhook deliveries](../user-guides/screenshots/light/plugins/jobs-log.png)
 
-The tab shows:
+The tab shows the following. The first three sit together in a **Runtime Dashboard** card; health and logs get cards of their own.
 
-- **Worker process** — whether the worker is running, its process ID, uptime, and how many crashes it has recovered from. If the worker crashes repeatedly, the crash count and last-crash timestamp surface here before anything looks broken in the rest of the UI.
-- **Recent job runs** — the last handful of scheduled jobs the plugin fired, each with a status dot (green success, red failed, blue running, grey cancelled, amber queued), the trigger that caused it, and a relative time. A green dot and a short duration is the thing you want to see repeating.
-- **Recent webhook deliveries** — incoming webhooks, each with a status and duration. Useful when you're debugging an integration that isn't firing.
-- **Health status** — aggregate check results, polled every 30 seconds while the plugin is `ready`. If a specific check is failing (for example, "can reach external API"), you'll see it called out here long before it becomes a crash.
-- **Recent logs** — the last 50 log entries the worker emitted, colour-coded by level. This is your first stop when something looks off.
+- **Worker Process** — whether the worker is running, its process ID, uptime, and how many crashes it has recovered from. If the worker crashes repeatedly, the crash count and last-crash timestamp surface here before anything looks broken in the rest of the UI.
+- **Recent Job Runs** — the last handful of scheduled jobs the plugin fired, each with a status dot (green success, red failed, blue running, grey cancelled, amber queued), the trigger that caused it, and a relative time. A green dot and a short duration is the thing you want to see repeating.
+- **Recent Webhook Deliveries** — incoming webhooks, each with a status and duration. Useful when you're debugging an integration that isn't firing.
+- **Health Status** — aggregate check results, polled every 30 seconds while the plugin is `ready`. If a specific check is failing (for example, "can reach external API"), you'll see it called out here long before it becomes a crash.
+- **Recent Logs** — the last 50 log entries the worker emitted, colour-coded by level. This is your first stop when something looks off.
 
 The whole tab refreshes on a 30-second cycle, so you can leave it open while you tweak config or trigger a manual run elsewhere in Paperclip.
 
@@ -289,7 +289,7 @@ A cheat sheet for operating the Plugin Manager day-to-day:
 | Temporarily stop a plugin's jobs | Click the power button on the plugin row (green to grey) |
 | Bring a plugin back online | Click the power button again, or **Enable** from the detail page |
 | Fix a plugin stuck in `error` | Detail page → Status tab → read the log, then re-enable |
-| Approve an upgrade that asks for new permissions | Detail page → review Permissions → **Enable** |
+| Approve an upgrade that asks for new permissions | Detail page → Status tab → review Permissions → **Enable** |
 | Change configuration | Detail page → Configuration tab → edit form → **Save Configuration** |
 | Verify a config before committing | Detail page → Configuration tab → **Test Configuration** (when available) |
 | Permanently remove a plugin | Trash icon on the plugin row → confirm |

docs/administration/settings.md

@@ -10,7 +10,7 @@ Paperclip has two settings surfaces, and it matters which one you're looking at.
 
 **Profile** is *your* account — your display name and the avatar that shows up next to your comments. Changing it only affects how *you* appear. Other board users on the same instance have their own profiles and see their own.
 
-**Instance Settings** is the admin surface. Anything you change there applies to the whole Paperclip instance — every company, every user, every agent that runs against this install. If you're running Paperclip on a VPS that hosts five companies, a toggle on the Instance page flips for all five.
+**Instance settings** are the admin controls. They don't live on a separate instance page — you reach them from the same **Settings** navigation as your organization (tabs like **Access**, **Experimental**, **Plugins**, and **Adapters**, plus the instance sections on **General**). Anything you change there applies to the whole Paperclip instance — every company, every user, every agent that runs against this install. If you're running Paperclip on a VPS that hosts five companies, an instance toggle flips for all five.
 
 Company and instance settings now share one navigation. The instance-wide **General** controls described below live on the organization's own **General** page (see [Company Administration](./company.md#general-settings)), so instance admins reach them from the same place as the organization settings rather than a separate area.
 
@@ -48,13 +48,15 @@ Shortcuts stay out of your way while you type: they ignore key presses inside te
 
 ## Instance: General
 
-![Instance general settings](../user-guides/screenshots/light/settings/instance-general.png)
+![The General settings page, with the organization fields at the top; the instance-wide sections sit further down the same page](../user-guides/screenshots/light/settings/instance-general.png)
 
-This is the top of Instance Settings. It's where you see how the instance was deployed and flip a few cross-cutting toggles.
+There's no separate instance General page anymore. Open **Settings** and you land on **General** — the first item in the settings sidebar. The top of that page holds your organization's own settings (**Organization name**, **Description**, **Logo**, hiring, and interaction governance). Scroll past **Interaction governance** and you reach the instance-wide sections described below, sitting just above the **Danger Zone**. This is where you see how the instance was deployed and flip a few cross-cutting toggles.
+
+> **Upgrading from an older release?** Old links to the instance General or Heartbeats pages still work — they redirect to this **General** page.
 
 ### Deployment and auth
 
-At the top of the page, a small mode badge tells you which deployment profile this instance is running under. The text underneath explains what that means in practice:
+Next to the **Deployment and auth** heading, a small mode badge tells you which deployment profile this instance is running under. The text underneath explains what that means in practice:
 
 - **Local trusted** — the instance is treating browser requests as a local board operator. No sign-in is required. This is the default when you run Paperclip on your own machine.
 - **Authenticated public** — sign-in is required and the instance is intended to sit on a public URL.
@@ -74,9 +76,9 @@ Hides the username segment inside home-directory paths and similar operator-visi
 
 ### Backup retention
 
-Controls how long automatic database backups are kept at each tier. Paperclip takes daily backups and then thins them out over time:
+Controls how long automatic database backups are kept at each tier. Paperclip backs up roughly every hour and then thins the backups out over time:
 
-- **Daily** — full daily backups kept for the selected number of days.
+- **Daily** — every backup is kept for the selected number of days.
 - **Weekly** — one backup per week kept for the selected number of weeks.
 - **Monthly** — one backup per month kept for the selected number of months.
 
@@ -84,17 +86,17 @@ Each tier is a preset picker, so you can only choose from vetted retention windo
 
 ### AI feedback sharing
 
-Controls whether thumbs-up / thumbs-down votes on AI output can send the voted output to Paperclip Labs. Three states exist:
+Controls whether thumbs-up / thumbs-down votes on AI output can send the voted output to Paperclip Labs. There are two buttons, plus a starting state:
 
-- **Prompt (default)** — no choice has been made yet. The next time you vote, Paperclip will ask once and save your answer.
+- **No default saved yet** — the starting state. There's no button for it; the card just tells you the next thumbs up or thumbs down will ask once and then save your answer here.
 - **Always allow** — voted AI outputs are shared automatically.
 - **Don't allow** — voted AI outputs stay local.
 
-The local vote is always saved regardless — this setting only controls whether the *content* leaves your instance. There's a link to the terms of service on the same card.
+The local vote is always saved regardless — this setting only controls whether the *content* leaves your instance. A **Read our terms of service** link sits on the same card.
 
 ### Sign out
 
-A plain **Sign out** button at the bottom. It ends your session and sends you back to the login page. On a local-trusted instance there's usually nothing to sign out of, but the button is always present.
+A plain **Sign out** button, the last of the instance sections (just above the **Danger Zone**). It ends your session and sends you back to the login page. On a local-trusted instance there's usually nothing to sign out of, but the button is still shown unless your operator has hidden it.
 
 ---
 
@@ -143,7 +145,7 @@ Beneath the checkbox grid, **Current memberships** lists what's actually on reco
 
 ![Instance adapters](../user-guides/screenshots/light/settings/instance-adapters.png)
 
-The Adapters sub-page (Instance Settings → **Adapters**) is the operator view of every adapter currently registered against this Paperclip install. Adapters are how Paperclip talks to an AI runtime — Claude's local CLI, Codex, OpenAI, OpenClaw, and so on — so this is the surface you use when you need to add a new runtime, hide one from agent hiring menus, or upgrade a runtime's package to a newer release.
+The Adapters page (**Settings → Adapters**) is the operator view of every adapter currently registered against this Paperclip install. Adapters are how Paperclip talks to an AI runtime — Claude's local CLI, Codex, OpenAI, OpenClaw, and so on — so this is the surface you use when you need to add a new runtime, hide one from agent hiring menus, or upgrade a runtime's package to a newer release.
 
 > **Alpha:** The external adapter system is still under active development. APIs and storage format may change between releases — reach for this page when you need it, but expect the details to keep evolving.
 
@@ -198,7 +200,7 @@ For the full catalog of adapters Paperclip supports out of the box, along with t
 
 ## Instance: Experimental
 
-![Experimental flags](../user-guides/screenshots/light/settings/experimental.png)
+![The Experimental settings page, with the warning banner above the Experimental features cards](../user-guides/screenshots/light/settings/experimental.png)
 
 Experimental flags opt the instance into features that aren't yet defaults. They're gated here because they may change behaviour, performance, or migrations before they graduate.
 
@@ -210,29 +212,57 @@ An experimental flag in Paperclip is a feature that:
 - Is being evaluated against real usage before it becomes the default, and
 - May be renamed, reworked, or promoted to a core setting in a future release.
 
-Turning one on is not dangerous in the "this will break your data" sense — but experimental features come **without compatibility guarantees**. They may break, change, or be removed at any time, and Paperclip doesn't promise migration or long-term support for them. The app shows a warning to this effect when you enable one. Flip flags when you have a reason to, not for curiosity; don't lean on an experimental feature for a workflow that has to stay stable, and expect to re-read the release notes if you upgrade.
+Turning one on is not dangerous in the "this will break your data" sense — but experimental features come **without compatibility guarantees**. They may break, change, or be removed at any time, and Paperclip doesn't promise migration or long-term support for them. The page carries a warning to this effect at the top. Flip flags when you have a reason to, not for curiosity; don't lean on an experimental feature for a workflow that has to stay stable, and expect to re-read the release notes if you upgrade.
 
 ### The available flags
 
-Each flag has its own page in the [Experimental](../experimental/overview.md) section with motivation, setup, and usage instructions. In brief:
+Open **Settings → Experimental**. The page groups its toggles into up to three sections and lists the cards alphabetically within each one. Where a flag has its own page in the [Experimental](../experimental/overview.md) section (or elsewhere in these docs), the name links to it.
 
-- **[Enable Environments](../experimental/environments.md)** — environment management in instance settings, plus project and agent environment assignment (including custom sandbox images).
-- **[Enable Isolated Workspaces](../experimental/isolated-workspaces.md)** — execution-workspace controls in project configuration and isolated (git-worktree) checkouts for task runs. If you're not using isolated workspaces, leave this off; turning it on exposes extra UI you don't need.
+**Experimental features** — *"Optional product features that are still being evaluated."*
+
+- **[Agent Chat](../experimental/agent-chat.md)** — one ongoing conversation per agent. **Chat** leads the **Work** group and opens an agent rail beside the nav; agents clarify your goal and hand real work off to tasks.
+- **[Assistant connections (MCP)](../experimental/assistant-connections.md)** — connect Codex, Claude, and other assistants to your Paperclip organization so people can review work, delegate tasks, and add feedback. Needs an authenticated instance with a configured public URL.
+- **Beta skills** — lets agents pin beta releases of the Paperclip core skill. Turning it off returns every agent to the default live skill, without removing the pins you saved.
+- **[Built-in Agents](../reference/api/built-in-agents.md)** — shows Paperclip-managed built-in agent surfaces (built-in roster badges, the **Built-in agents** tab, and the built-in agent setup controls) and makes the built-in-agent API available. Turn it on before you provision `briefs`, `learning`, or `reflection-coach`; with it off, the built-in-agent routes return `404 Not Found`.
+- **[Cases](../reference/api/cases.md)** — durable work products (blog posts, tweet storms…) that tasks create and iterate on. Adds the **Cases** tab and the agent case API. Turning it off hides the tab and blocks the API; existing case data is kept.
+- **[Chat connectors](../connectors.md#chat-channels-experimental)** — connect agents to Slack, GitHub, Discord, Microsoft Teams, and Telegram conversations. Turning it off hides chat setup, but existing chat connections keep running.
+- **[Combined Inbox + Task List](../experimental/task-chat.md#an-optional-combined-task-list)** — folds Inbox into **Tasks**: one Tasks row carries the unread badge, and a **Views** menu reaches every inbox and task view.
+- **[Decisions](../guides/day-to-day/decisions.md)** — shows the **Decisions** item in the main sidebar, the attention home that surfaces the tasks awaiting your input.
+- **[Enable Environments](../experimental/environments.md)** — environment management in company settings, plus project and agent environment assignment (including custom sandbox images).
+- **[Enable External Objects](../experimental/external-objects.md)** — detects external URLs in issues and shows live status for referenced pull requests, tickets, and other work objects.
+- **[Enable Isolated Workspaces](../experimental/isolated-workspaces.md)** — execution-workspace controls in project configuration and isolated (git-worktree) checkouts for task runs. If you're not using isolated workspaces, leave this off. Once it's on, a **Use Isolated Workspaces By Default** card appears at the bottom of this section.
 - **[Experimental File Viewer](../experimental/file-viewer.md)** — task-detail controls for browsing and previewing workspace files.
-- **[Enable External Objects](../experimental/external-objects.md)** — detects external URLs in issues and shows live status for referenced pull requests and tickets.
-- **[Task Plan Decomposition Panel](../experimental/plan-decomposition-panel.md)** — accepted-plan decomposition history on task detail pages, for debugging sub-task creation.
-- **[Agent Chat](../experimental/agent-chat.md)** — one persistent conversation per agent, behind a **Chat** sidebar entry; agents hand work off to tasks and report back when they're done.
-- **[Assistant connections (MCP)](../experimental/assistant-connections.md)** — lets external assistants sign in as a person to review work and delegate tasks. Experimental and off by default.
-- **[Memory connectors](../connectors/memory-connectors.md)** — exposes Mem0, Zep, Supermemory, Cognee, and Honcho setup. Experimental and off by default; hiding setup does not stop saved connections.
-- **[Paperclip Runner](../reference/adapters/paperclip-runner.md)** — enables explicitly configured native runs. Experimental; on by default on self-hosted instances and off by default on Cloud unless managed configuration changes it. Enabling the flag does not migrate existing agents.
-- **[Combined Inbox + Task List](../experimental/task-chat.md#an-optional-combined-task-list)** — combines inbox and task views under **Tasks**. Experimental and off by default.
-- **[Task Watchdogs](../experimental/task-watchdogs.md)** — per-task watchdog agents that verify stopped task subtrees and restore live paths.
-- **[Cloud Sync](../experimental/cloud-sync.md)** — **retired.** Removed upstream together with its experimental toggle, so it no longer appears in this list on a current build. To move a company between instances, use [company Import/Export](../how-to/back-up-and-restore-a-company.md).
-- **[Server Info Debug View](../experimental/server-info-debug-view.md)** — a "Server" section in the account drawer with restart time, running commit, and checkout state.
-- **[Auto-Restart Dev Server When Idle](../experimental/auto-restart-dev-server.md)** — only relevant under `pnpm dev:once`; restarts a stale dev boot once all local agent runs finish. For development on Paperclip itself, not production.
-- **[Auto-Create Recovery Tasks](../experimental/auto-create-recovery-tasks.md)** — lets the heartbeat scheduler create recovery tasks for stalled task dependency chains, with a lookback window and preview.
-- **Enable Built-in Agents** — makes the built-in-agent controls and API available. Turn it on before you provision `briefs`, `learning`, or `reflection-coach`; with it off, the built-in-agent routes return `404 Not Found`.
-- **Streamlined Left Navigation Bar** — **on by default now**, so you don't need to flip anything to get it. It trims the sidebar: Projects move under the **Work** section as a single **Projects** link with its own page, and the agents list shows only your active agents (the five most recently active). Turning this flag **off** is the opt-out — it restores the classic sidebar, where each project gets its own collapsible entry and there's no top-level Projects link.
+- **First task: propose with a plan document** — when someone's first request is a single task, the chief of staff writes a short plan document and a checkbox card instead of a one-card confirmation. Applies to organizations created after you flip it.
+- **[Memory connectors](../connectors/memory-connectors.md)** — exposes Mem0, Zep, Supermemory, Cognee, and Honcho setup. Hiding setup does not stop saved connections.
+- **[Paperclip Runner](../reference/adapters/paperclip-runner.md)** — lets new Codex agents select the experimental Rust Paperclip Runner. On by default on self-hosted instances and off by default on Cloud unless managed configuration changes it. Turning it off hides the choice without affecting existing native runs.
+- **[Simplified English Interactions](../reference/skills/optional/content/simplified-english.md)** — tells agents to write confirmations, questions, suggested tasks, and checkbox prompts in ASD-STE100 Simplified Technical English, with brief context on what each decision needs.
+- **[Status Cards](../experimental/status-cards.md)** — the shared status-card board and its gated API. Enabling Status Cards also enables Summaries.
+- **Streamlined UI** — **on by default**. The simplified main sidebar, shared Tasks and Inbox presentation, focused task detail layout, and contextual navigation across Agents, Routines, Skills, and Settings. Turning it off restores the legacy shell and navigation; task and page data are unchanged.
+- **[Summaries](../reference/api/summary-slots.md)** — Summarizer-generated status slots on project and workspace pages, with on-demand refresh and revision history. Status Cards requires Summaries, so disabling Summaries also disables Status Cards.
+
+**Paperclip Developer Mode** — *"Internal tools for developing, testing, and debugging Paperclip."* You won't need these for day-to-day use.
+
+- **[Auto-Restart Dev Server When Idle](../experimental/auto-restart-dev-server.md)** — only relevant under `pnpm dev:once`; restarts a stale dev boot once all local agent runs finish.
+- **Managed Environment Only** — hides the local environment and runs all agents in the platform-managed environment.
+- **Paperclip Developer Mode** — shows internal maintainer tools and observability links, including Honeycomb trace queries on run pages.
+- **Run tasks in this worktree** — only appears when the server is running inside a git worktree.
+- **[Server Info Debug View](../experimental/server-info-debug-view.md)** — a "Server" section in the account drawer with the server restart time and running commit.
+- **Smoke Lab** — adds a **Smoke Lab** tab under **Apps → Developer** and an **Integration smoke** card on the dashboard for exercising integration paths against local fixtures. Private (non-public) deployments only.
+- **[Task Plan Decomposition](../experimental/plan-decomposition-panel.md)** — accepted-plan decomposition history on task detail pages, for debugging sub-task creation.
+
+**Legacy** — *"These features are going to be removed."*
+
+- **[Classic Task Interface](../experimental/task-chat.md)** — restores the previous task detail page: the page-level header, the plain comment thread, and the fixed Properties sidebar.
+- **[Goals Sidebar Link](../guides/projects-workflow/goals.md)** — restores the **Goals** item in the main sidebar while the goals surface is being evaluated.
+
+#### No longer on this page
+
+If you're coming from an older release, a few toggles you may remember are gone:
+
+- **[Task Watchdogs](../experimental/task-watchdogs.md)** — no flag any more. Watchdog controls are always available on tasks.
+- **[Auto-Create Recovery Tasks](../experimental/auto-create-recovery-tasks.md)** — retired, along with its preview and run actions.
+- **[Cloud Sync](../experimental/cloud-sync.md)** — retired, toggle included. To move a company between instances, use [company Import/Export](../how-to/back-up-and-restore-a-company.md).
+- **Streamlined Left Navigation Bar** — replaced by **Streamlined UI**.
 
 Toggles take effect immediately on save. If one misbehaves, flip it back off — no migration is required.
 

docs/experimental/agent-chat.md

@@ -12,7 +12,7 @@ Not every conversation with an agent starts as a well-formed task. Sometimes you
 
 ## Turn it on
 
-1. Go to **Settings → Instance settings → Experimental**.
+1. Go to **Settings → Experimental**.
 2. Turn on **Agent Chat**. It is experimental and off by default; enabling it adds persistent conversations with your agents.
 
 Like every flag on that page, it's instance-wide. On Paperclip Cloud this one may be managed for you, in which case it shows the **Managed by Paperclip Cloud** lock — see [If a toggle is locked](overview.md#if-a-toggle-is-locked).

docs/experimental/assistant-connections.md

@@ -12,7 +12,7 @@ This feature is experimental. **Assistant connections (MCP)** (`enablePublicMcp`
 
 ## Turn it on
 
-1. Open **Settings → Instance settings → Experimental** as an instance administrator.
+1. Open **Settings → Experimental** as an instance administrator.
 2. Turn on **Assistant connections (MCP)**.
 3. Return to **Connectors → Assistant Connection (MCP)**.
 

docs/experimental/auto-create-recovery-tasks.md

@@ -1,24 +1,26 @@
 ---
-paperclip_version: v2026.831.1
+paperclip_version: v2026.1012.0
 seo_title: Auto-Create Recovery Tasks
 seo_description: Dependency chains die quietly behind paused agents, missing reviewers, and cancelled blockers. Recovery tasks wake that work instead of letting it wait.
 ---
 
 # Auto-Create Recovery Tasks
 
+> **Removed in this release.** The **Auto-Create Recovery Tasks** card is gone from **Settings → Experimental** in v2026.1012.0, along with its **Preview** and **Run now** actions and the API behind them. Paperclip still runs its built-in dependency wake backstop, but it no longer creates recovery tasks through this setting. The rest of this page describes the feature as it worked on older builds.
+
 A task dependency chain can die quietly: a blocker assigned to a paused agent, an `in_review` issue whose reviewer no longer exists, work still blocked by a cancelled task. Nothing is scheduled to wake anyone, so downstream work waits forever.
 
 Paperclip's liveness detection finds those dead chains on every scheduler heartbeat. With **Auto-Create Recovery Tasks** on, it goes one step further: for each stalled chain with recent activity, it creates a high-priority **recovery task** — *"Unblock liveness incident for PAP-1234"* — assigns it to the most appropriate available agent, and wires it in as a blocker so the original work resumes automatically once the incident is resolved.
 
-![The Auto-Create Recovery Tasks card with its preview dialog](../user-guides/screenshots/light/experimental/recovery-preview.png)
+## How you turned it on (older builds)
 
-## Turn it on
+On builds before v2026.1012.0, this is how the setting worked:
 
-1. Go to **Settings → Instance settings → Experimental** and find the **Auto-Create Recovery Tasks** card — *"Let the heartbeat scheduler create recovery tasks for task dependency chains found inside the configured lookback window."*
-2. Set **Lookback hours** (1–720, default 24). Only chains whose dependency path saw activity inside this window get recovery tasks — older, abandoned graphs are left untouched.
-3. Flip the toggle. Before enabling, Paperclip shows a **Confirm auto-recovery** preview: every recovery task that would be created right now, each with the stuck issue, the detected state, the reason, and the recovery target. Choose **Enable only** (turn it on without acting on current findings) or **Enable and create N** (turn it on and create them immediately).
+1. You went to **Settings → Experimental** and found the **Auto-Create Recovery Tasks** card — *"Let the heartbeat scheduler create recovery tasks for task dependency chains found inside the configured lookback window."*
+2. You set **Lookback hours** (1–720, default 24). Only chains whose dependency path saw activity inside this window got recovery tasks — older, abandoned graphs were left untouched.
+3. You flipped the toggle. Before enabling, Paperclip showed a **Confirm auto-recovery** preview: every recovery task that would be created right then, each with the stuck issue, the detected state, the reason, and the recovery target. You chose **Enable only** (turn it on without acting on current findings) or **Enable and create N** (turn it on and create them immediately).
 
-The card also has stand-alone **Preview** and **Run now** buttons, so you can inspect findings any time or trigger a sweep on demand, and **Save hours** to adjust the window later. The footer confirms the active window: *"Current window: last N hours."*
+The card also had stand-alone **Preview** and **Run now** buttons, so you could inspect findings any time or trigger a sweep on demand, and **Save hours** to adjust the window later. The footer confirmed the active window: *"Current window: last N hours."*
 
 ## What counts as a dead chain
 

docs/experimental/auto-restart-dev-server.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.707.0
+paperclip_version: v2026.1012.0
 seo_title: Auto-Restart Dev Server When Idle
 seo_description: For people developing Paperclip itself: let the dev runner watch backend sources and pending migrations, and restart the server when a boot goes stale.
 ---
@@ -11,7 +11,7 @@ This flag is for people developing **Paperclip itself**. When you run the app wi
 ## Turn it on
 
 1. Run the app under `pnpm dev:once`.
-2. Go to **Settings → Instance settings → Experimental**.
+2. Go to **Settings → Experimental**.
 3. Turn on **Auto-Restart Dev Server When Idle** — *"In `pnpm dev:once`, wait for all queued and running local agent runs to finish, then restart the server automatically when backend changes or migrations make the current boot stale."*
 
 ## How it behaves

docs/experimental/cloud-sync.md

@@ -1,50 +1,27 @@
 ---
-paperclip_version: v2026.707.0
-seo_title: Cloud Sync to a Paperclip Upstream
-seo_description: Push a local company — agents, projects, issues, skills, portability files — into a Paperclip Cloud stack, previewing exactly what would change first.
+paperclip_version: v2026.1012.0
+seo_title: Cloud Sync (Retired)
+seo_description: Cloud Sync, which pushed a local company into a Paperclip Cloud stack, is gone in this release. Here is what replaced it and where old links now go.
 ---
 
-# Cloud Sync
+# Cloud Sync (retired)
 
-> **Deprecated — being removed.** Host-to-host Cloud Sync has been retired upstream and replaced by full-fidelity **company Import/Export**, which moves a company — agents, projects, issues, skills, portability files — between any two instances (local-to-local, over a URL, or from GitHub) without the experimental flag or a live upstream connection. See [Back up and restore a company](../how-to/back-up-and-restore-a-company.md). This page is kept temporarily for anyone on an older build and will be removed in a future release.
+> **Removed in this release.** Cloud Sync no longer exists in Paperclip v2026.1012.0. There's no **Cloud upstream** screen, no **Cloud Sync** toggle on **Settings → Experimental**, no `paperclipai cloud push` command, and no cloud-upstream API. To move a company to another instance, including a hosted one, use company **Export** and **Import** instead. See [Back up and restore a company](../how-to/back-up-and-restore-a-company.md).
 
-**Cloud Sync** connects a locally-run Paperclip instance to a Paperclip Cloud upstream so you can push a local company — agents, projects, issues, skills, portability files — into a cloud stack. You preview exactly what would change, resolve conflicts, push, and then review activation before any automation resumes on the cloud side.
+## What it was
 
-![The Cloud upstream screen](../user-guides/screenshots/light/experimental/cloud-upstream.png)
+On older builds, **Cloud Sync** connected a locally run Paperclip instance to a Paperclip Cloud upstream. You could preview a push, resolve conflicts, push a local company (agents, projects, issues, skills, portability files) into a cloud stack, and then choose which agents, routines, and monitors woke up on the cloud side.
 
-## Why it exists
+## What you'll see now
 
-Plenty of companies start life on a laptop. Cloud Sync is the migration path: move that local company to a hosted stack without hand-exporting, with a dry-run preview and schema-compatibility check first, and with cloud automations **paused until you explicitly activate them** so nothing fires unexpectedly mid-move.
+If you follow an old link or bookmark to the Cloud upstream page (`/company/settings/cloud-upstream`), Paperclip sends you to the **Export** page instead:
 
-## Turn it on
+![On this release, the old Cloud upstream address opens the Export page](../user-guides/screenshots/light/experimental/cloud-upstream.png)
 
-1. Go to **Settings → Instance settings → Experimental**.
-2. Turn on **Cloud Sync** — *"Show local Paperclip Cloud upstream connection, preview, push, retry, and activation review surfaces."*
-
-Unlike most flags on the page, this one gates the API too: with it off, the cloud-upstream endpoints refuse requests and `paperclipai cloud push` errors out — not just hidden UI.
-
-## Using it
-
-1. Open **Company Settings → Cloud upstream** (the nav item appears once the flag is on).
-2. **Connect** — paste your Paperclip Cloud stack URL and approve the authorization grant on the cloud side.
-3. **Preview push** — a summary of what will be sent, with warnings, conflicts, and a schema-compatibility check. Push stays disabled until the schemas are compatible.
-4. **Push to cloud** — creates a push run with live progress, a downloadable report, and **Retry**/**Re-run** on failure.
-5. **Review activation** — after a push completes, the activation table lets you decide which entity types (agents, routines, monitors) wake up on the cloud stack.
-
-The step-by-step recipe — including the CLI flow and troubleshooting — is in [Sync a local company to a Paperclip Cloud upstream](../how-to/sync-to-cloud-upstream.md).
-
-## When it's off
-
-The Cloud upstream page shows *"Cloud sync is disabled. Enable it in Instance Settings to show upstream connection and push tools."*, the *Send to Paperclip Cloud* button disappears, and the API and CLI refuse cloud-sync operations. Saved connections and run history are preserved and return when you re-enable.
-
-## Caveats
-
-- Requires board-level access on the local instance and enough rights on the cloud stack to approve the authorization grant.
-- The target stack must advertise the `cloud_sync` transfer feature.
-- Pushes are gated on schema compatibility between the two stacks — upgrade the older side if the preview reports a mismatch.
+From there you can export the company to a portable package and import it on the other instance. Import/Export moves the same things Cloud Sync did, and it works local-to-local, over a URL, or from GitHub, with no live upstream connection and no experimental flag.
 
 ## Where to go next
 
-- [Sync a local company to a Paperclip Cloud upstream](../how-to/sync-to-cloud-upstream.md) — the full how-to.
-- [Company export & import](../administration/company.md) — the offline alternative for moving companies.
+- [Back up and restore a company](../how-to/back-up-and-restore-a-company.md): the replacement workflow.
+- [Company export & import](../administration/company.md): the Export and Import pages in detail.
 - [Experimental features overview](overview.md)

docs/experimental/connections-apps.md

@@ -14,7 +14,7 @@ seo_description: The rebuilt connection storage and authorization layer under Pa
 
 | Then | Now |
 | --- | --- |
-| **Apps** had to be turned on in **Settings → Instance settings → Experimental**. | Always enabled. `enableApps` is a deprecated compatibility key: *"Apps is always enabled; stored and managed values are ignored."* The Experimental settings page no longer renders the toggle. |
+| **Apps** had to be turned on in **Settings → Experimental**. | Always enabled. `enableApps` is a deprecated compatibility key: *"Apps is always enabled; stored and managed values are ignored."* The Experimental settings page no longer renders the toggle. |
 | The navigation item was **Apps**. | The sidebar item is **Connectors**. The route is still `/apps`. |
 | A Wave 1 catalog, described as plumbing rather than a store. | A full catalog with setup flows, per-action permissions, and a review queue. See [Connectors](../connectors.md). |
 | "Setup flows are partial." | Setup flows are the product surface. Each provider page documents the exact paths Paperclip supports for it. |

docs/experimental/environments.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.707.0
+paperclip_version: v2026.1012.0
 seo_title: Environments: Remote Execution Targets
 seo_description: Run agents somewhere other than the Paperclip host. Define named targets over SSH or a provider sandbox, and assign them per instance, project, or agent.
 ---
@@ -16,15 +16,15 @@ One machine doesn't fit every agent. Some work needs isolation from the host, so
 
 ## Turn it on
 
-1. Go to **Settings → Instance settings → Experimental**.
+1. Go to **Settings → Experimental**.
 2. Turn on **Enable Environments** — *"Show environment management in company settings and allow project and agent environment assignment controls."*
 
-The **Environments** entry under Instance settings is always visible, but until you flip the flag the page only tells you to enable it. The flag also reveals the environment pickers on agent and project configuration.
+The **Environments** tab in **Settings** is always visible, but until you flip the flag it only asks you to enable Environments in the experimental settings. The flag also reveals the environment pickers on agent and project configuration.
 
 ## Set up your first environment
 
-1. Open **Settings → Instance settings → Environments**.
-2. Click **Add environment** and pick a driver:
+1. Open **Settings → Environments**.
+2. Click the **+** button (its tooltip reads **Add environment**) and pick a driver:
    - **Local** — runs on the Paperclip host (the default behavior, as an explicit choice).
    - **SSH** — a remote machine: host, user, key, and remote path.
    - **Sandbox** — a sandbox provider installed as a plugin (see [Sandbox Providers](../reference/adapters/sandbox-providers.md)); each provider brings its own config fields.

docs/experimental/external-objects.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.707.0
+paperclip_version: v2026.1012.0
 seo_title: External Objects: Live Links on Issues
 seo_description: Turn dead references to pull requests, tickets, and deployments into live status you can read from inside Paperclip instead of opening another tab.
 ---
@@ -8,13 +8,13 @@ seo_description: Turn dead references to pull requests, tickets, and deployments
 
 Issues constantly reference work that lives somewhere else — a GitHub pull request, a ticket in another tracker, a deployment. Normally those are dead links: to know whether that PR merged, you leave Paperclip and go look.
 
-With **External Objects** on, Paperclip detects external URLs anywhere in an issue — title, description, comments, documents — and renders them as live status pills instead of plain links. A referenced GitHub pull request shows up as *Open*, *Draft*, *Merged*, or *Closed* right where it's mentioned, plus in a rollup panel on the issue.
+With **External Objects** on, Paperclip detects external URLs anywhere in an issue — title, description, comments, documents — and shows their live status instead of leaving them as plain links. A referenced GitHub pull request gets a small status icon right where it's mentioned, and a row in the issue's **Properties** panel that reads like *PR 8512 - Merged*.
 
-![External object status on an issue](../user-guides/screenshots/light/experimental/external-objects.png)
+![A task whose comment links a GitHub pull request and issue with inline status icons, and a Properties panel listing them as PR 8512 - Merged and Issue 4419 - Closed](../user-guides/screenshots/light/experimental/external-objects.png)
 
 ## Turn it on
 
-1. Go to **Settings → Instance settings → Experimental**.
+1. Go to **Settings → Experimental**.
 2. Turn on **Enable External Objects** — *"Detect external URLs in issues and show resolved status for pull requests, tickets, and other referenced work objects."*
 
 ## Using it
@@ -22,8 +22,9 @@ With **External Objects** on, Paperclip detects external URLs anywhere in an iss
 There's nothing to configure per issue — just paste URLs where you'd naturally write them:
 
 - **Detection.** Whenever an issue, comment, or document is created or updated, Paperclip extracts its URLs. GitHub pull-request and issue URLs (`github.com/{owner}/{repo}/pull/{n}` or `/issues/{n}`) are recognized as first-class work objects out of the box; anything else becomes a generic link object. Plugins can register additional detectors for other systems.
-- **Status pills.** Recognized references render inline as a pill with a provider icon, the object (e.g. `owner/repo#123`), and its state — with a distinct look for merged PRs, an `×N` counter when the same object is referenced several times, and a dashed border when the status is stale, unreachable, or needs authentication. A newly detected object starts as *"Not yet refreshed"* until it's resolved.
-- **The External objects panel.** The issue's Related Work area gains an **External objects** section — *"Remote work referenced from this issue — pull requests, deployments, tickets in other systems, and more."* — listing every detected object with its status and where it was mentioned, sorted severity-first.
+- **Inline status icons.** In descriptions and comments, a recognized link keeps its original text, with a small status icon in front of it. Hover the link to see the object and its state (for example *Open*, *Merged*, or *Closed*). A newly detected object starts as *"Not yet refreshed"* until it's resolved.
+- **Properties rows.** The issue's **Properties** panel (under **Relationships**) gets one row per object, labelled with the provider and type — for example *GitHub Pull Request* or *GitHub Issue* — with a value like *PR 8512 - Merged* or *Issue 4419 - Closed*. Merged PRs get their own color. The most urgent statuses sort first; if there are more than five, a **References** row lets you expand the rest.
+- **The External objects panel.** The issue's Related Work area gains an **External objects** section — *"Remote work referenced from this issue — pull requests, deployments, tickets in other systems, and more."* — listing every detected object as a status pill, with an `×N` counter when it's mentioned several times and a dashed border when the status is stale, unreachable, or needs authentication.
 - **Lists and sidebar.** Issue list rows get a compact status badge and the list toolbar gains an external-object status filter; project rows in the sidebar roll up the dominant status.
 
 ## GitHub access
@@ -32,12 +33,12 @@ Public repositories resolve without setup. For private repos (and friendlier rat
 
 ## When it's off
 
-Hidden and inert: detection stops, pills fall back to plain links, the panel and filters disappear. Already-detected objects are kept and reappear if you re-enable.
+Hidden and inert: detection stops, links go back to plain links, and the Properties rows, panel, and filters disappear. Already-detected objects are kept and reappear if you re-enable.
 
 ## Caveats
 
 - **GitHub is the only built-in resolver** at this release, and only `github.com` URLs in the exact PR/issue path shape — GitHub Enterprise hosts and other trackers need a plugin that provides object detection.
-- Resolved statuses have a short TTL (about five minutes) and there's no background poller yet at this release — statuses refresh lazily, and agents can force a refresh through the API. Expect pills to read *stale* or *"Not yet refreshed"* between resolutions.
+- Resolved statuses have a short TTL (about five minutes) and there's no background poller yet at this release — statuses refresh lazily, and agents can force a refresh through the API. Expect statuses to read *stale* or *"Not yet refreshed"* between resolutions.
 
 ## Where to go next
 

docs/experimental/file-viewer.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.707.0
+paperclip_version: v2026.1012.0
 seo_title: Experimental File Viewer
 seo_description: Read the reports, code changes, and screenshots an agent produced without leaving the task — the files, not just the comment thread that describes them.
 ---
@@ -14,7 +14,7 @@ The Experimental File Viewer fixes that. It adds controls to every task detail p
 
 ## Turn it on
 
-1. Go to **Settings → Instance settings → Experimental**.
+1. Go to **Settings → Experimental**.
 2. Turn on **Experimental File Viewer** — *"Show task detail controls for browsing and previewing workspace files relative to a task."*
 
 The setting is instance-wide and takes effect immediately.

docs/experimental/isolated-workspaces.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.707.0
+paperclip_version: v2026.1012.0
 seo_title: Isolated Workspaces
 seo_description: Give each task run its own git worktree on its own branch, so several agents can work a project at once without fighting over one shared checkout.
 ---
@@ -16,7 +16,7 @@ A shared checkout is a bottleneck and a hazard: two concurrent runs editing the
 
 ## Turn it on
 
-1. Go to **Settings → Instance settings → Experimental**.
+1. Go to **Settings → Experimental**.
 2. Turn on **Enable Isolated Workspaces** — *"Show execution workspace controls in project configuration and allow isolated workspace behavior for new and existing task runs."*
 
 This is the single switch for all the workspace UI: the **Workspaces** sidebar item, the per-project **Execution Workspaces** configuration, the workspace-mode picker on new and existing tasks, and the project **Workspaces** tab.

docs/experimental/overview.md

@@ -26,9 +26,11 @@ Check the feature's own page before changing its flag: hiding a surface and disa
 
 All experimental flags live in one place, and they're instance-wide (they apply to every company on your Paperclip instance):
 
-1. Open **Settings → Instance settings → Experimental**.
+1. Open **Settings → Experimental**.
 2. Find the feature's card and flip its toggle.
 
+**Experimental** sits near the bottom of the settings sidebar.
+
 Changes take effect immediately — no restart, no migration. Each feature page in this section repeats the exact toggle name to look for.
 
 The page groups its toggles into up to three sections — **Experimental features**, **Paperclip Developer Mode**, and **Legacy** — and lists the cards alphabetically within each one, so you can scan for a name. If every toggle in the developer or legacy section is hidden, that section heading disappears too.
@@ -49,26 +51,65 @@ Only some features are managed this way. Anything without the badge is still you
 
 ## The features
 
+The tables follow the page's own sections and order. Where a feature has a page in these docs, its name links there.
+
+### Experimental features
+
 | Feature | What it adds |
 | --- | --- |
-| [Environments](environments.md) | Environment management in settings, plus project and agent environment assignment — including custom sandbox images. |
-| [Isolated Workspaces](isolated-workspaces.md) | Execution-workspace controls: per-run isolated copies of a project so agents don't step on each other. |
+| [Agent Chat](agent-chat.md) | One ongoing conversation per agent. **Chat** leads the **Work** group; agents clarify your goal, hand real work off to tasks, and report back when those tasks are done. |
+| [Assistant connections (MCP)](assistant-connections.md) | Connect an external assistant as your user through OAuth, with separate read, write, and configuration scopes. |
+| Beta skills | Lets agents pin beta releases of the Paperclip core skill. Turning it off returns every agent to the default live skill without removing saved pins. |
+| [Built-in Agents](../reference/api/built-in-agents.md) | Paperclip-managed built-in agent surfaces: roster badges, the **Built-in agents** tab, and setup controls. |
+| [Cases](../reference/api/cases.md) | Durable work products that tasks create and iterate on. Adds the **Cases** tab and the agent case API. |
+| [Chat connectors](../connectors.md#chat-channels-experimental) | Connect agents to Slack, GitHub, Discord, Microsoft Teams, and Telegram conversations. Existing chat connections keep running when it's off. |
+| [Combined Inbox + Task List](task-chat.md#an-optional-combined-task-list) | Reach inbox and task views from one **Tasks** navigation entry. |
+| [Decisions](../guides/day-to-day/decisions.md) | Shows the **Decisions** item in the main sidebar, where the tasks awaiting your input collect. |
+| [Enable Environments](environments.md) | Environment management in settings, plus project and agent environment assignment — including custom sandbox images. |
+| [Enable External Objects](external-objects.md) | Detects external URLs in issues and shows live status for referenced pull requests, tickets, and other work objects. |
+| [Enable Isolated Workspaces](isolated-workspaces.md) | Execution-workspace controls: per-run isolated copies of a project so agents don't step on each other. Turning it on reveals a **Use Isolated Workspaces By Default** card. |
 | [Experimental File Viewer](file-viewer.md) | Task-detail controls for browsing and previewing workspace files relative to a task. |
-| [External Objects](external-objects.md) | Detects external URLs in issues and shows live status for referenced pull requests, tickets, and other work objects. |
-| [Task Plan Decomposition Panel](plan-decomposition-panel.md) | Shows accepted-plan decomposition history on task detail pages. |
-| [Chat-Style Tasks](task-chat.md) | **Now the default.** The task detail page as a live conversation: chat bubbles, streaming activity that folds into a one-line summary, a three-mode composer, and a resizable Properties · Plan · Artifacts pane. The old page is behind the **Classic Task Interface** toggle under **Legacy**. |
-| [Agent Chat](agent-chat.md) | One ongoing conversation per agent, reached from a **Chat** entry in the sidebar. Agents clarify your goal, hand real work off to tasks, and report back in the chat when those tasks are done. |
-| [Assistant connections (MCP)](assistant-connections.md) | **Experimental; off by default.** Connect an external assistant as your user through OAuth, with separate read, write, and configuration scopes. |
-| [Task-pinned AI routing](task-pinned-ai-routing.md) | **Experimental; off by default.** Rotate new tasks across a pool of saved AI accounts while each task keeps its account. Needs a router plugin, and the `enableAiConnectionRouters` flag has no toggle on the Experimental page. |
-| [Memory connectors](../connectors/memory-connectors.md) | **Experimental; off by default.** Set up Mem0, Zep, Supermemory, Cognee, or Honcho for agents. Existing connections keep running when setup is hidden. |
-| [Paperclip Runner](../reference/adapters/paperclip-runner.md) | **Experimental.** Native agent execution, enabled by default for self-hosted instances and disabled by default on Cloud. Agents must be explicitly configured to use it. |
-| [Combined Inbox + Task List](task-chat.md#an-optional-combined-task-list) | **Experimental; off by default.** Reach inbox and task views from one **Tasks** navigation entry. |
-| [Task Watchdogs](task-watchdogs.md) | Watchdog agents that verify stopped task subtrees and restore live paths when work should continue. |
-| [Status Cards](status-cards.md) | A shared board of living summaries: one message per card, compiled into a watch query and kept current by the Summarizer. |
-| [Cloud Sync](cloud-sync.md) | **Retired.** Host-to-host Cloud Sync has been removed upstream, toggle included — you won't find it on the Experimental page any more. Use [company Import/Export](../how-to/back-up-and-restore-a-company.md) to move a company between instances. |
+| First task: propose with a plan document | For a single-task first request, the chief of staff writes a short plan document and a checkbox card. Applies to organizations created after you flip it. |
+| [Memory connectors](../connectors/memory-connectors.md) | Set up Mem0, Zep, Supermemory, Cognee, or Honcho for agents. Existing connections keep running when setup is hidden. |
+| [Paperclip Runner](../reference/adapters/paperclip-runner.md) | Native agent execution, on by default for self-hosted instances and off by default on Cloud. Agents must be explicitly configured to use it. |
+| [Simplified English Interactions](../reference/skills/optional/content/simplified-english.md) | Agents write confirmations, questions, and suggested tasks in ASD-STE100 Simplified Technical English. |
+| [Status Cards](status-cards.md) | A shared board of living summaries, kept current by the Summarizer. Enabling it also enables Summaries. |
+| Streamlined UI | **On by default.** The simplified sidebar, focused task detail layout, and contextual navigation. Turning it off restores the legacy shell and navigation. |
+| [Summaries](../reference/api/summary-slots.md) | Summarizer-generated status slots on project and workspace pages. Status Cards needs it. |
+
+### Paperclip Developer Mode
+
+Internal tools for developing, testing, and debugging Paperclip itself.
+
+| Feature | What it adds |
+| --- | --- |
+| [Auto-Restart Dev Server When Idle](auto-restart-dev-server.md) | Restarts a stale `pnpm dev:once` boot once all local runs finish. |
+| Managed Environment Only | Hides the local environment and runs all agents in the platform-managed environment. |
+| Paperclip Developer Mode | Internal maintainer tools and observability links, such as Honeycomb trace queries on run pages. |
+| Run tasks in this worktree | Only shown when the server runs inside a git worktree. |
 | [Server Info Debug View](server-info-debug-view.md) | A "Server" section in the account drawer with the server restart time and running commit. |
-| [Auto-Restart Dev Server When Idle](auto-restart-dev-server.md) | For Paperclip developers: restarts a stale `pnpm dev:once` boot once all local runs finish. |
-| [Auto-Create Recovery Tasks](auto-create-recovery-tasks.md) | Lets the scheduler create recovery tasks for stalled task dependency chains. |
+| Smoke Lab | A **Smoke Lab** tab under **Apps → Developer** and an **Integration smoke** dashboard card. Private deployments only. |
+| [Task Plan Decomposition](plan-decomposition-panel.md) | Shows accepted-plan decomposition history on task detail pages. |
+
+### Legacy
+
+*"These features are going to be removed."*
+
+| Feature | What it adds |
+| --- | --- |
+| [Classic Task Interface](task-chat.md) | Restores the previous task detail page. The chat-style task page is now the default. |
+| [Goals Sidebar Link](../guides/projects-workflow/goals.md) | Restores the **Goals** item in the main sidebar. |
+
+### Not on the page
+
+These have pages in this section but no toggle in this release:
+
+| Feature | Status |
+| --- | --- |
+| [Task-pinned AI routing](task-pinned-ai-routing.md) | Experimental and off by default, but the `enableAiConnectionRouters` flag has no card on the Experimental page. Needs a router plugin. |
+| [Task Watchdogs](task-watchdogs.md) | **No flag any more.** Watchdog controls are always available on tasks. |
+| [Auto-Create Recovery Tasks](auto-create-recovery-tasks.md) | **Retired**, along with its toggle and its preview and run actions. |
+| [Cloud Sync](cloud-sync.md) | **Retired**, toggle included. Use [company Import/Export](../how-to/back-up-and-restore-a-company.md) to move a company between instances. |
 
 ## Where to go next
 

docs/experimental/plan-decomposition-panel.md

@@ -1,12 +1,12 @@
 ---
-paperclip_version: v2026.1001.0
-seo_title: Task Plan Decomposition Panel
+paperclip_version: v2026.1012.0
+seo_title: Task Plan Decomposition
 seo_description: See the machinery that turns an accepted plan into child tasks, and the guarantee it runs exactly once even across retries and interrupted runs.
 ---
 
-# Task Plan Decomposition Panel
+# Task Plan Decomposition
 
-When an agent's plan is accepted, Paperclip decomposes it into child tasks — and it guarantees that decomposition happens **exactly once**, even if the agent retries or a run is interrupted mid-creation. Normally that machinery is invisible: you just see sub-tasks appear. The Task Plan Decomposition Panel makes it visible.
+When an agent's plan is accepted, Paperclip decomposes it into child tasks — and it guarantees that decomposition happens **exactly once**, even if the agent retries or a run is interrupted mid-creation. Normally that machinery is invisible: you just see sub-tasks appear. The **Task Plan Decomposition** flag makes it visible.
 
 It adds a read-only **Plan decomposition** section to task detail pages showing, per accepted plan revision, how many child tasks were requested, how many were actually created, and which ones — so you can validate that sub-task creation behaved correctly.
 
@@ -16,8 +16,8 @@ This panel is a debugging and validation surface. The app's own description is c
 
 ## Turn it on
 
-1. Go to **Settings → Instance settings → Experimental**.
-2. Turn on **Task Plan Decomposition Panel** — *"Show accepted-plan decomposition history on task detail pages."*
+1. Go to **Settings → Experimental**.
+2. Under **Paperclip Developer Mode**, turn on **Task Plan Decomposition** — *"Show accepted-plan decomposition history on task detail pages."*
 
 The setting is instance-wide and takes effect immediately.
 
@@ -42,7 +42,7 @@ This page describes the classic task page (the **Classic Task Interface** toggle
 Two things worth knowing about that arrangement:
 
 - The centre-column **Plan decomposition** section described above is hidden on the chat-style page. It hasn't gone anywhere; it's in the Plan tab.
-- The Plan tab shows the history on its own, without this **Task Plan Decomposition Panel** flag. Turning this flag off hides the section from the classic task page, but the Plan tab keeps showing accepted plans as long as you're on the chat-style page.
+- The Plan tab shows the history on its own, without this **Task Plan Decomposition** flag. Turning this flag off hides the section from the classic task page, but the Plan tab keeps showing accepted plans as long as you're on the chat-style page.
 
 See [Issues](../guides/day-to-day/issues.md#tabs-in-the-properties-panel-experimental) for the rest of what the Plan tab holds, including approving a plan from the panel.
 

docs/experimental/server-info-debug-view.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.707.0
+paperclip_version: v2026.1012.0
 seo_title: Server Info Debug View
 seo_description: Answer which commit a server is actually running from inside the app. Adds a Server section to the account drawer for support and development work.
 ---
@@ -12,12 +12,12 @@ seo_description: Answer which commit a server is actually running from inside th
 
 ## Turn it on
 
-1. Go to **Settings → Instance settings → Experimental**.
-2. Turn on **Server Info Debug View** — *"Show a 'Server' section in the account drawer with the current server restart time and running commit."*
+1. Go to **Settings → Experimental**.
+2. Turn on **Server Info Debug View** — *"Show a "Server" section in the account drawer with the current server restart time and running commit."* You'll find it in the **Paperclip Developer Mode** section further down the page.
 
 ## Using it
 
-Click your avatar at the bottom of the sidebar to open the account drawer. Below **Sign out**, the **Server** section shows three rows:
+Click your avatar at the bottom of the sidebar to open the account drawer. The **Server** section is the last thing in the drawer, below the menu rows (**Settings**, **Invite** when you're allowed to invite people, **Documentation**, the **Switch to dark mode** / **Switch to light mode** toggle, and — on instances that require sign-in — **Sign out**). It shows three rows:
 
 - **Last restarted** — the dev-server restart time when available, otherwise the process start time.
 - **Running commit** — short SHA and commit subject (or *"Commit unavailable"* on deployments without git metadata).

docs/experimental/status-cards.md

@@ -1,4 +1,5 @@
 ---
+paperclip_version: v2026.1012.0
 seo_title: Status Cards: Answers Without Filtering
 seo_description: Pin the questions you ask daily — is the launch blocked, what changed this week, what is the next action — and read the answer without working the board.
 ---
@@ -11,8 +12,8 @@ A **status card** does that for you and keeps the answer on a shelf. You write o
 
 ## Turn it on
 
-1. Go to **Settings → Instance settings → Experimental**.
-2. Turn on **Status Cards** — *"Enable the experimental shared status-card board, update engine, and gated API."*
+1. Go to **Settings → Experimental**.
+2. Turn on **Status Cards** — *"Enable the experimental shared status-card board and its gated API. Existing card data is kept when this is disabled."*
 
 This flag gates the whole feature, not just the UI. With it off, the **Status** item disappears from the sidebar, `/status` redirects you to the dashboard, and every status-card API route responds `404 Not Found` with `{ "error": "Status cards are not enabled" }`.
 

docs/experimental/task-chat.md

@@ -14,11 +14,11 @@ Watching an agent work on a task usually means reading two things at once: the c
 
 Chat-Style Tasks started life as an experimental toggle. It's now simply how the task page works — there's nothing to switch on.
 
-If you'd rather have the old page back, go to **Settings → Instance settings → Experimental** and, under **Legacy** (*"These features are going to be removed."*), turn on **Classic Task Interface**. It restores the previous task detail page — the page-level header, the plain comment thread, and the fixed Properties sidebar — and the chat-only features described below aren't available there. The card notes that *"Switching takes effect immediately. No task data is affected."* Like every flag on that page, it's instance-wide.
+If you'd rather have the old page back, go to **Settings → Experimental** and, under **Legacy** (*"These features are going to be removed."*), turn on **Classic Task Interface**. It restores the previous task detail page — the page-level header, the plain comment thread, and the fixed Properties sidebar — and the chat-only features described below aren't available there. The card notes that *"Switching takes effect immediately. No task data is affected."* Like every flag on that page, it's instance-wide.
 
 ## An optional combined task list
 
-The task conversation described here is standard behavior. **Combined Inbox + Task List** (setting key `enableCombinedInboxTasks`) is a separate experimental option, off by default, under **Settings → Instance settings → Experimental**. It only takes effect while **Streamlined UI** is on; if your instance has switched **Streamlined UI** off, turning this on changes nothing and the separate **Inbox** row stays.
+The task conversation described here is standard behavior. **Combined Inbox + Task List** (setting key `enableCombinedInboxTasks`) is a separate experimental option, off by default, under **Settings → Experimental**. It only takes effect while **Streamlined UI** is on; if your instance has switched **Streamlined UI** off, turning this on changes nothing and the separate **Inbox** row stays.
 
 With that option on in the streamlined interface, **Tasks** carries the unread and failed-run badge, and the separate **Inbox** sidebar row disappears. Open **Views** on Tasks to switch between **Mine**, **Unread**, **Blocked**, **Recent**, and **Everything**, or the organization views **All tasks**, **Active**, **Backlog**, and **Done**. Your inbox actions and task filters still belong to their respective views. Existing inbox links take you to the corresponding task view.
 

docs/experimental/task-watchdogs.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.707.0
+paperclip_version: v2026.1012.0
 seo_title: Task Watchdogs (Experimental)
 seo_description: A watchdog wakes when an agent misreads a blocker, claims done without proof, or gives up on a recoverable error, so the issue tree never just goes quiet.
 ---
@@ -10,12 +10,9 @@ Sometimes an agent stops work for the wrong reason — it misreads a blocker, de
 
 A **task watchdog** is an agent you attach to a task to double-check stopped work. When the watched task and all its descendants have come to rest with no live path forward, the watchdog wakes up, reads the evidence, and either accepts the stop or restores a live path so work continues.
 
-![A watchdog reporting its verdict in the task thread](../user-guides/screenshots/light/watchdogs/watchdog-thread-outcome.png)
-
 ## Turn it on
 
-1. Go to **Settings → Instance settings → Experimental**.
-2. Turn on **Task Watchdogs** — *"Show task detail controls for configuring watchdog agents that verify stopped task subtrees and restore live paths when work should continue."*
+There's nothing to turn on any more. Task watchdogs used to sit behind a **Task Watchdogs** toggle on the Experimental settings page; that flag has been removed, and the watchdog controls are now always available on every task. If you remember the toggle from an older release, you won't find it on **Settings → Experimental** now.
 
 ## Using it
 
@@ -32,9 +29,9 @@ When it does wake, the stopped-state comment it posts lists each stopped task wi
 
 The full lifecycle — when a watchdog wakes, what it's allowed to do, and how it differs from the other things called "watchdog" — is covered in the [Task Watchdogs guide](../guides/projects-workflow/task-watchdogs.md).
 
-## When it's off
+## Removing a watchdog
 
-The flag hides the configuration UI only. **Watchdogs you already configured keep running** — the scheduler evaluates them regardless of the flag, so this is a hide, not a kill switch. To actually stop a watchdog, remove it from the task's Watchdog row before turning the flag off.
+Because there's no flag, there's no global off switch either. To stop a watchdog, open the task, click its **Watchdog** row, and choose **Remove**.
 
 ## Caveats
 

docs/guides/day-to-day/activity-log.md

@@ -1,17 +1,20 @@
 ---
-seo_title: The Activity Log
-seo_description: A permanent, timestamped record of every status change, comment, hire, and approval in your company — built for accountability and for debugging.
+paperclip_version: v2026.1012.0
+seo_title: Audit Activity Log
+seo_description: The Activity tab under Audit is a permanent, timestamped record of every status change, comment, hire, and approval — for accountability and debugging.
 ---
 
-# Activity Log
+# Audit: Activity
 
-The Activity Log is the complete record of everything that has ever happened in your company. Every time an agent changes a task's status, posts a comment, gets hired or paused, spends budget, or has a proposal approved — that event is recorded here with a timestamp and the name of whoever caused it.
+The activity log is the complete record of everything that has ever happened in your company. Every time an agent changes a task's status, posts a comment, gets hired or paused, spends budget, or has a proposal approved — that event is recorded here with a timestamp and the name of whoever caused it.
 
-The log exists for two reasons. First, accountability: you can always see what actually happened and who did it. Second, debugging: when something goes wrong, the Activity Log is your first place to look.
+The log exists for two reasons. First, accountability: you can always see what actually happened and who did it. Second, debugging: when something goes wrong, the activity log is your first place to look.
 
-If the question you're really asking is "what did my *agents* do, and on whose behalf?", you don't need a different page anymore. Activity is now one page for both questions: flip the scope toggle to narrow from every actor down to agent actions only, without leaving the feed. See [Focusing on agent actions](#focusing-on-agent-actions) below.
+You'll find it under **Audit** in the sidebar. The Audit page has five tabs — **Activity**, **Runs**, **Costs**, **Budgets**, and **Timeline** — and it opens on **Activity**, which is what this guide covers. (Costs and Budgets are covered in the [Costs guide](./costs.md), and Timeline in the [Work Timeline guide](./work-timeline.md).)
 
-![Activity Log page showing a full chronological feed of events with actor names, action descriptions, and timestamps](../../user-guides/screenshots/light/activity/activity-log-full.png)
+If the question you're really asking is "what did my *agents* do, and on whose behalf?", you don't need a different page. The Activity tab answers both questions: flip the scope toggle from **Activity** to **Agent Actions** to narrow from every actor down to agent work, without leaving the feed. See [Focusing on agent actions](#focusing-on-agent-actions) below.
+
+![Audit page open on the Activity tab, showing the Activity / Agent Actions toggle, the filter bar, and a chronological feed of events with actor names, action descriptions, and timestamps](../../user-guides/screenshots/light/activity/activity-log-full.png)
 
 ---
 
@@ -36,26 +39,26 @@ Each record includes:
 
 ## Reading the Activity Log
 
-The Activity Log is available from the left sidebar. It opens to a chronological feed of all events, most recent first.
+Click **Audit** in the left sidebar. The page opens on the **Activity** tab: a chronological feed of all events, most recent first.
 
-Each row in the feed shows the actor's name, what they did, and when. Clicking a row jumps you to the related issue, approval, agent, project, goal, or run — useful when you want to inspect the thing that changed.
+Each row in the feed reads like a sentence — the actor's name, what they did, and the thing they did it to — with a relative timestamp on the right (hover it for the exact date and time). The raw action name, such as `issue.updated`, sits underneath in small type. Click the linked task or other item in a row to jump to it — useful when you want to inspect the thing that changed.
 
-![Activity Log detail view for a single event, showing actor, action, before/after values, and timestamp](../../user-guides/screenshots/light/activity/activity-log-full.png)
+![Rows in the Audit Activity feed, each showing the actor, a plain-language action, the linked task, the raw action name, and a relative timestamp](../../user-guides/screenshots/light/activity/activity-log-full.png)
 
-> **Tip:** The Activity Log and the task comment threads show different things. The comment thread on a task shows what the agent said as it worked — its reasoning, questions, and progress updates. The Activity Log shows the structural changes — status transitions, assignments, approvals. Use comments when you want to understand what the agent was thinking; use the log when you want to understand what actually changed and when.
+> **Tip:** The activity log and the task comment threads show different things. The comment thread on a task shows what the agent said as it worked — its reasoning, questions, and progress updates. The activity log shows the structural changes — status transitions, assignments, approvals. Use comments when you want to understand what the agent was thinking; use the log when you want to understand what actually changed and when.
 
 ---
 
 ## Filtering
 
-When you're looking for something specific, use the filters at the top of the Activity page.
+When you're looking for something specific, use the filters at the top of the Activity tab.
 
-![Activity Log with the filter bar open, showing the scope toggle plus agent, responsible user, action, entity, and date range filters](../../user-guides/screenshots/light/activity/activity-filters.png)
+![Audit Activity tab with the filter bar open, showing the scope toggle plus agent, responsible user, action, entity, and date range filters](../../user-guides/screenshots/light/activity/activity-filters.png)
 
 Start with the **scope toggle**. It switches between two views of the same feed:
 
-- **All actors** — everything that happened, from every kind of actor: humans, agents, plugins, and the system itself.
-- **Agent actions only** — just the rows where an agent did the work. This is the default.
+- **Activity** — everything that happened, from every kind of actor: humans, agents, plugins, and the system itself. This is the default.
+- **Agent Actions** — just the rows where an agent did the work.
 
 Below the toggle you can narrow further:
 
@@ -65,7 +68,7 @@ Below the toggle you can narrow further:
 - **Entity** — the kind of thing that changed, such as a task, agent, project, goal, or company.
 - **From** and **To** dates — a day range.
 
-![Activity Log filtered to show one category of events](../../user-guides/screenshots/light/activity/activity-filtered-by-agent.png)
+![Audit Activity feed narrowed with the filter bar, showing only the matching events](../../user-guides/screenshots/light/activity/activity-filtered-by-agent.png)
 
 The feed loads newest first and pages as you scroll, so there's no 200-row ceiling — you can follow a thread as far back as it goes.
 
@@ -73,7 +76,7 @@ The feed loads newest first and pages as you scroll, so there's no 200-row ceili
 
 ## Focusing on agent actions
 
-Sometimes you don't want *everything* that happened; you want to answer a narrower question — what did my agents do, and who was responsible for each of those actions? Flip the scope toggle to **Agent actions only** and the feed answers exactly that, without sending you to a different page.
+Sometimes you don't want *everything* that happened; you want to answer a narrower question — what did my agents do, and who was responsible for each of those actions? Flip the scope toggle to **Agent Actions** and the feed answers exactly that, without sending you to a different page.
 
 Two things stand out in this view:
 
@@ -82,16 +85,16 @@ Two things stand out in this view:
 
 Each row spells out the action in plain language, links the task it touched, quotes the comment excerpt when there is one, and offers a **View run** link when the action came out of an agent run. The raw action name (for example `issue.comment_added`) sits at the end of the row in small type, in case you need the exact string.
 
-You can also read a single agent's history without leaving its page: open the agent and switch to its **Activity** tab. It's the same feed, pinned to that one agent.
+You can also jump straight to a single agent's history: open the agent, and in the **Audit** section of its overview click **Activity**. You land on this same feed in **Agent Actions** mode, pinned to that one agent (a "Scoped to one agent" note appears above the filters).
 
 ### Who can see what
 
 Everyone on your team can open Activity, but there are two tiers of detail:
 
-- **Any company member** can read the feed with the scope set to **All actors**. You'll see every kind of actor — human, agent, plugin, and system — but the sensitive attribution fields (which agent, which run, and the responsible person) are stripped out.
+- **Any company member** can read the feed with the scope set to **Activity**. You'll see every kind of actor — human, agent, plugin, and system — but the sensitive attribution fields (which agent, which run, and the responsible person) are stripped out.
 - **Members with the `audit:view_agent_actions` permission** see complete rows. They can turn on the attribution filters — agent, responsible user, and actor type — and they can export the feed to CSV. No role hands this permission out by default, so it's always a deliberate grant; see [Roles & Permissions](../../administration/roles-and-permissions.md).
 
-If you set an attribution filter without the permission, Paperclip tells you the filter needs `audit:view_agent_actions` rather than silently returning stripped-down rows.
+Without the permission, the **Agent Actions** toggle is greyed out. If you set an attribution filter without the permission, Paperclip tells you the filter needs `audit:view_agent_actions` rather than silently returning stripped-down rows.
 
 ### Exporting
 
@@ -103,7 +106,7 @@ One thing to know before you press it: the export is itself logged as an `audit.
 
 ## Using Activity to Debug
 
-The Activity Log is most valuable when something has gone wrong and you need to understand why. Here are the most common scenarios and how to approach them.
+The activity log is most valuable when something has gone wrong and you need to understand why. Here are the most common scenarios and how to approach them.
 
 ---
 
@@ -137,7 +140,7 @@ If there are no heartbeat events at all recently, the agent's heartbeat schedule
 
 Open the task from the activity feed and look for related heartbeat events. If you see heartbeats completing but no task update events, the agent may be running but not making progress. Read the most recent comments on the task itself.
 
-If there are no recent heartbeat events at all, the agent may have been paused or may have hit a budget limit — check the agent's status on the dashboard.
+If there are no recent heartbeat events at all, the agent may have been paused or may have hit a budget limit — check the agent's status on the dashboard, or the **Budgets** tab under **Audit**.
 
 ---
 
@@ -145,10 +148,10 @@ If there are no recent heartbeat events at all, the agent may have been paused o
 
 Unlike agent run transcripts (which are stored per-run and can scroll off), activity records are kept permanently. You can always go back and audit what happened months ago. This is intentional — it's the basis for accountability in an autonomous AI company.
 
-If you ever need to understand a past decision, resolve a dispute about what an agent did or didn't do, or understand the sequence of events leading up to a problem, the Activity Log has the full record.
+If you ever need to understand a past decision, resolve a dispute about what an agent did or didn't do, or understand the sequence of events leading up to a problem, the activity log has the full record.
 
 ---
 
-You've now covered all five sections of the "Running Your Company" guide set. You know how to read the dashboard, manage tasks, handle approvals, control costs, and use the Activity Log to understand what's happening. From here, the next guide covers building out your org structure — adding manager agents and worker agents to scale beyond the CEO.
+You've now covered all five sections of the "Running Your Company" guide set. You know how to read the dashboard, manage tasks, handle approvals, control costs, and use the activity log under **Audit** to understand what's happening. From here, the next guide covers building out your org structure — adding manager agents and worker agents to scale beyond the CEO.
 
 [Building Your Org Structure →](../org/org-structure.md)

docs/guides/day-to-day/approvals.md

@@ -1,4 +1,5 @@
 ---
+paperclip_version: v2026.1012.0
 seo_title: Approvals: Staying in Control
 seo_description: Agents pause for your sign-off before consequential actions. Review hires and strategies, then approve, reject, or send them back for revision.
 ---
@@ -9,7 +10,7 @@ Approvals are how you stay in control even as your agents work autonomously. Wit
 
 Think of it like a board seat. The agents run the day-to-day company. But the big calls — who gets hired, what the strategy is — still come to you.
 
-![Approvals list page showing pending approvals with type badges, requesting agent names, and creation timestamps](../../user-guides/screenshots/light/approvals/approvals-list.png)
+![Approvals list page showing pending approval cards with type badges, a summary of each request, and inline Approve and Reject buttons](../../user-guides/screenshots/light/approvals/approvals-list.png)
 
 ---
 
@@ -22,11 +23,12 @@ The first approvals most people encounter in Paperclip are:
 When an agent (usually the CEO, or a manager like a CTO) decides it needs help and wants to bring on a new subordinate, it can't just create the agent itself. Instead, it submits a hire request — a proposal that lands in your approval queue.
 
 The hire request tells you:
-- The proposed agent's name and role
+- The proposed agent's name, role, and title
 - What capabilities and responsibilities it would have
-- Which AI system would power it (the adapter) and how it's configured
-- What monthly budget it's requesting
-- Which agent it would report to
+- Which AI system would power it (the adapter)
+- Any skills it wants
+
+The full request can also carry the adapter configuration, a monthly budget, and which agent the hire would report to. Those don't appear in the summary, so open **See full request** to check them.
 
 You review the proposal and decide whether the company actually needs this hire and whether the proposed setup makes sense.
 
@@ -50,7 +52,7 @@ Later on, you may also see budget-related approvals when a budget policy hits a
 
    You can open it from a direct link, from the dashboard's pending approvals card, or from an approval-related inbox item. The page uses two tabs: **Pending** for actionable items and **All** for the full history.
 
-   ![Approvals list showing a pending hire request and a pending strategy approval](../../user-guides/screenshots/light/approvals/approvals-list.png)
+   ![The Approvals page on the Pending tab, listing pending approvals such as a CEO strategy proposal and a board approval request](../../user-guides/screenshots/light/approvals/approvals-list.png)
 
    Pending approvals have a yellow badge. Items in `revision_requested` are still treated as actionable until the requester follows up and resubmits.
 
@@ -65,7 +67,14 @@ The Approvals page is organised as a tab bar across the top:
 
 ![Approvals tab bar with Pending and All tabs and a pending count pill](../../user-guides/screenshots/light/approvals/queue-filters.png)
 
-Within each tab, approvals are sorted newest first. Each row shows the approval type, the requesting agent, a short summary, and a status badge. Clicking a row opens the approval detail view covered in the next sections.
+Within each tab, approvals are sorted newest first. Each approval is a card showing:
+
+- A type badge (**Hire Agent**, **CEO Strategy**, **Budget Override**, or **Board Approval**) and, when an agent filed the request, a **Requested by** line with that agent's name.
+- The request's subject and when it was created ("Approval request created 16m ago").
+- A status badge, such as **Pending** or **Approved**.
+- A summary of the request — for example the proposed hire's name, role, and adapter, or a board approval's summary and recommended action.
+- **Approve** and **Reject** buttons, so you can decide right from the list on anything still actionable (budget overrides are the exception; see below).
+- A **View details** link that opens the approval detail view covered in the next sections.
 
 > **Tip:** If the Pending tab is empty, you are caught up — the inbox card on the dashboard will also show zero pending approvals.
 
@@ -75,18 +84,17 @@ Within each tab, approvals are sorted newest first. Each row shows the approval
 
 Clicking a hire request opens its detail view. The page is laid out in three parts:
 
-1. **A header card** with the approval type icon, the proposed agent's name and role, the current status badge, and the approval id (useful when referencing it in a comment or a support channel).
-2. **The proposal payload** — the structured summary of what the requesting agent is asking for. For hires, this includes:
-   - The proposed agent name and title
-   - The role (CTO, backend engineer, content writer, etc.) and a freeform capabilities description
-   - The adapter type and sanitised adapter config (working directory, environment variable names, and other non-secret fields)
-   - The reporting line — which agent the new hire would report to
-   - The requested monthly budget
-3. **A "See full request" expander** that reveals the raw JSON payload for the rare case you need to inspect a specific field the summary view does not highlight.
+1. **A header** with the approval type icon, a title like "Hire Agent: Senior Engineer", the current status badge, and the approval id (useful when referencing it in a comment or a support channel). When an agent filed the request, a **Requested by** line names it.
+2. **The proposal summary** — the structured fields of what's being asked for. For hires, these are:
+   - **Name**, **Role**, **Title**, and **Icon** for the proposed agent
+   - **Capabilities** — a freeform description of what the agent will do
+   - **Adapter** — the adapter type that would power it
+   - **Skills** — any skills the hire asks for
+3. **A See full request expander** that reveals the raw JSON payload. The summary doesn't show the adapter configuration, the requested monthly budget, or the reporting line, so open this to check them before you decide.
 
-Below the proposal, a **Comments** section lets you leave notes or ask clarifying questions on the approval itself. Comments on an approval are visible to the requesting agent the next time it wakes.
+The **Approve**, **Reject**, and **Request revision** buttons sit right below. Under the card, a **Comments** section lets you leave notes or ask clarifying questions on the approval itself. Comments on an approval are visible to the requesting agent the next time it wakes.
 
-![Hire approval detail showing proposed agent name, role, capabilities description, adapter type, and budget](../../user-guides/screenshots/light/approvals/hire-approval-detail.png)
+![Hire approval detail showing the proposed agent's name, role, title, icon, capabilities, and adapter type](../../user-guides/screenshots/light/approvals/hire-approval-detail.png)
 
 ### Reviewing a hire request
 
@@ -99,30 +107,31 @@ Below the proposal, a **Comments** section lets you leave notes or ask clarifyin
    Ask yourself:
    - Does the company actually need this role right now?
    - Are the proposed capabilities appropriate for the work to be done?
-   - Is the budget request reasonable? (A new worker agent typically needs less than a manager agent)
-   - Is the adapter configuration correct — do the environment variables look right, is the working directory sensible?
+   - Is the budget request reasonable? (A new worker agent typically needs less than a manager agent.) Check it under **See full request**.
+   - Is the adapter configuration correct — do the environment variables look right, is the working directory sensible? This is also in the full request.
 
 3. **Make your decision**
 
-   ![Approve, Reject, and Request Revision buttons at the bottom of an approval detail](../../user-guides/screenshots/light/approvals/approve-reject-revision-buttons.png)
+   ![Approve, Reject, and Request revision buttons on an approval detail](../../user-guides/screenshots/light/approvals/approve-reject-revision-buttons.png)
 
    - **Approve** — the hire proceeds. The new agent is created, configured, and queued to wake automatically.
    - **Reject** — the hire is denied. The requesting agent is notified and will not retry unless instructed.
-   - **Request Revision** — you're not approving as-is, but you're not saying no. The agent will revise and resubmit.
+   - **Request revision** — you're not approving as-is, but you're not saying no. The agent will revise and resubmit.
 
-> **Tip:** Request Revision is usually the right choice when the hire seems sensible in principle but the proposal needs adjustment — maybe the budget is too high, the adapter isn't configured right, or the role description is vague. Be specific in your revision note about what you want changed.
+> **Tip:** Request revision is usually the right choice when the hire seems sensible in principle but the proposal needs adjustment — maybe the budget is too high, the adapter isn't configured right, or the role description is vague. Be specific in a comment about what you want changed.
 
 ---
 
 ## Strategy Approval Detail
 
-A strategy approval detail has the same three-part layout as a hire, but the payload is very different. Instead of a structured proposal, the main content is the CEO's **proposed plan** — usually a few paragraphs of narrative strategy followed by the initial set of tasks the CEO intends to create. Specifically, you will see:
+A strategy approval detail has the same layout as a hire, but the content is different. Instead of a structured proposal, the main content is the CEO's **proposed plan**. Specifically, you will see:
 
-- **The plan body** rendered as markdown, so any headings, bullets, or links the CEO wrote appear formatted.
-- **Linked issues** — if the CEO already seeded draft tasks tied to the strategy, they appear as a list of clickable issues underneath the plan. Approving does not close them; they remain open for the CEO to refine on its next run.
-- **Decision note** — once the approval has been resolved, any note you left (via Request Revision) is shown here.
+- **Title** — the name of the strategy.
+- **The plan body** — shown as plain text in a scrollable box, exactly as the CEO wrote it.
+- **Linked Tasks** — if the CEO already seeded tasks tied to the strategy, they appear as a list of clickable tasks underneath the plan. Approving doesn't close them; they stay open until the requesting agent follows up and closes them.
+- **Decision note** — shown when the approval carries one.
 
-![Strategy approval detail showing the CEO's proposed plan and a list of linked draft issues](../../user-guides/screenshots/light/approvals/strategy-approval-detail.png)
+![Strategy approval detail showing the CEO's proposed plan with Approve, Reject, and Request revision buttons](../../user-guides/screenshots/light/approvals/strategy-approval-detail.png)
 
 ### Reviewing a strategy approval
 
@@ -130,7 +139,7 @@ A strategy approval detail has the same three-part layout as a hire, but the pay
 
    The strategy detail shows the CEO's proposed plan — usually several paragraphs outlining goals, priorities, and the initial set of tasks it intends to create.
 
-   ![Strategy approval detail showing the CEO's proposed strategic plan and the tasks it intends to create](../../user-guides/screenshots/light/approvals/strategy-approval-detail.png)
+   ![Strategy approval detail showing the CEO's proposed strategic plan](../../user-guides/screenshots/light/approvals/strategy-approval-detail.png)
 
 2. **Read the strategy with your company goal in mind**
 
@@ -144,27 +153,27 @@ A strategy approval detail has the same three-part layout as a hire, but the pay
 
    If the strategy looks right, **Approve** it. The CEO will immediately start creating tasks based on the plan.
 
-   If something's off, **Request Revision**. In the revision note, be specific: "The strategy focuses too much on technical infrastructure and not enough on user acquisition — please revise to include a distribution plan" gives the CEO clear direction to work with.
+   If something's off, click **Request revision**, then use the **Comments** box to say what you want changed. Be specific: "The strategy focuses too much on technical infrastructure and not enough on user acquisition — please revise to include a distribution plan" gives the CEO clear direction to work with.
 
-   ![Revision request input box with a text field for explaining what changes are needed](../../user-guides/screenshots/light/approvals/revision-request-input.png)
+   ![The Comments box on an approval, where you explain what changes you need before posting with Post comment](../../user-guides/screenshots/light/approvals/revision-request-input.png)
 
 > **Tip:** Don't worry if the first strategy isn't perfect — you can request revisions as many times as needed before approving. Requesting a revision changes the approval status and leaves a clear note for the requester to address; the updated proposal appears after the requester follows up and resubmits.
 
 ---
 
-## Approve, Reject, or Request Revision
+## Approve, Reject, or Request revision
 
-Every actionable approval (anything in `pending` or `revision_requested`) shows the same three buttons at the bottom of the detail card. Use them deliberately — each one means something different to the requesting agent.
+Every pending approval shows the same three buttons on the detail card, just below the proposal. (Once you've requested a revision, **Request revision** is replaced by **Mark resubmitted**, while **Approve** and **Reject** stay available.) Use them deliberately — each one means something different to the requesting agent.
 
-![Approve, Reject, and Request Revision buttons at the bottom of an approval detail](../../user-guides/screenshots/light/approvals/approve-reject-revision-buttons.png)
+![Approve, Reject, and Request revision buttons on an approval detail](../../user-guides/screenshots/light/approvals/approve-reject-revision-buttons.png)
 
-- **Approve** (green) — you accept the proposal as submitted. For hires, the agent is created, configured, and queued to wake automatically. For strategies, the CEO is notified and begins creating tasks on its next run. A confirmation banner appears on the detail page, and the approval moves to `approved` in the list.
+- **Approve** (green) — you accept the proposal as submitted. For hires, the agent is created, configured, and queued to wake automatically. For strategies, the CEO is notified and begins creating tasks on its next run. An **Approval confirmed** banner appears on the detail page, and the approval moves to `approved` in the list.
 - **Reject** (red) — you are saying no to the proposal outright. The action is permanently denied: hire positions are not created, strategies are discarded, and the requesting agent will not retry unless you instruct it to. If a hire was rejected, you get an extra **Delete disapproved agent** button so you can clear the placeholder record from the org.
-- **Request Revision** (outline) — you are not accepting as-is, but you are not saying no either. The approval enters `revision_requested`. The requester revises its proposal on a later run and re-submits; the approval then returns to `pending` with the updated payload ready for you to review again. Leave a comment on the approval explaining what you want changed so the agent has concrete direction.
+- **Request revision** (outline) — you are not accepting as-is, but you are not saying no either. The approval enters `revision_requested`. The requester revises its proposal on a later run and re-submits; the approval then returns to `pending` with the updated payload ready for you to review again. Leave a comment on the approval explaining what you want changed so the agent has concrete direction.
 
-> **Tip:** Request Revision is almost always the right choice when the proposal is directionally right but needs tweaks — adjusting a budget, changing a reporting line, or tightening a strategy's scope. Reject only when the proposal is fundamentally wrong or no longer relevant.
+> **Tip:** Request revision is almost always the right choice when the proposal is directionally right but needs tweaks — adjusting a budget, changing a reporting line, or tightening a strategy's scope. Reject only when the proposal is fundamentally wrong or no longer relevant.
 
-**Budget approvals** are slightly different: the Approve and Reject buttons are hidden on the approval detail. Budget stops are resolved from the budget controls on the **Costs** page instead — the detail view will link you there.
+**Budget approvals** are slightly different: the Approve and Reject buttons are hidden, both on the list and on the approval detail. Budget stops are resolved from the budget controls on the **Costs** page instead — the detail view will link you there.
 
 ---
 
@@ -182,13 +191,13 @@ Every actionable approval (anything in `pending` or `revision_requested`) shows
 - For a strategy: the CEO must create a new strategy from scratch — it won't automatically retry.
 - Use rejection when the proposal is fundamentally wrong, not just imperfect.
 
-**If you Request Revision:**
+**If you request a revision:**
 - The approval enters "revision_requested" state.
-- Your note is saved on the approval for the requester to address.
+- Your comments stay on the approval for the requester to address.
 - The agent revises the proposal and resubmits it on a later run. The approval moves back to "pending".
 - You'll see the updated proposal the next time you open it.
 
-![An approved approval showing the approved status badge and the timestamp of the decision](../../user-guides/screenshots/light/approvals/approved-approval.png)
+![An approved approval showing the Approval confirmed banner, the approved status badge, and a Back to approvals button](../../user-guides/screenshots/light/approvals/approved-approval.png)
 
 The full revision cycle looks like this:
 

docs/guides/day-to-day/artifacts.md

@@ -107,7 +107,7 @@ The tab is read-only — a quick answer to "what came out of this task?", not a
 
 Implementation reference: [artifact cards](https://github.com/paperclipai/paperclip/blob/bba6a45f0d364cfd962ac59b3bdf2426a8222adb/ui/src/components/artifacts/IssueArtifactCard.tsx), [CSV preview limits](https://github.com/paperclipai/paperclip/blob/bba6a45f0d364cfd962ac59b3bdf2426a8222adb/ui/src/lib/artifact-card-data.ts), and [media gallery](https://github.com/paperclipai/paperclip/blob/bba6a45f0d364cfd962ac59b3bdf2426a8222adb/ui/src/components/ImageGalleryModal.tsx).
 
-> **Note:** if your instance has switched back to the old layout with **Classic Task Interface** (under **Legacy** in **Settings → Instance settings → Experimental**), there's no Artifacts tab — a task's attachments stay in the **Attachments** section on the task page. See [Experimental features](../../experimental/overview.md).
+> **Note:** if your instance has switched back to the old layout with **Classic Task Interface** (under **Legacy** in **Settings → Experimental**), there's no Artifacts tab — a task's attachments stay in the **Attachments** section on the task page. See [Experimental features](../../experimental/overview.md).
 
 Either way, the Artifacts page remains the place to see everything at once, across every task and project. See [Issues](./issues.md#tabs-in-the-properties-panel) for the rest of what those tabs hold.
 

docs/guides/day-to-day/blocked-inbox.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.513.0
+paperclip_version: v2026.1012.0
 seo_title: Blocked Inbox: Triaging Stalled Work
 seo_description: The Blocked tab surfaces issues waiting on a decision, a recovery run, an external person, or a paused owner — and shows who owns each unblock.
 ---
@@ -10,7 +10,7 @@ The **Blocked** tab in your Inbox is where stopped work goes to be triaged. The
 
 If you've ever had an agent quietly sitting on `status = blocked` while you wondered why nothing was moving, this is the view that calls it out.
 
-![Inbox](../../user-guides/screenshots/light/issues/inbox.png)
+![The Inbox Blocked tab listing blocked tasks and why each is waiting](../../user-guides/screenshots/light/issues/inbox-blocked.png)
 
 ---
 

docs/guides/day-to-day/costs.md

@@ -1,16 +1,21 @@
 ---
 paperclip_version: v2026.1012.0
-seo_title: Costs: Budgets, Providers, and Spend
-seo_description: Set limits Paperclip enforces automatically. Five tabs cover overview, budgets, providers, billers, and finance, with headline spend metrics on top.
+seo_title: Costs and Budgets: Spend and Limits
+seo_description: Track spend and set limits Paperclip enforces automatically, from the Costs and Budgets tabs under Audit — overview, providers, billers, and finance.
 ---
 
-# Costs
+# Costs and Budgets
 
 > **Warning:** AI agents make real API calls that cost real money. Every time an agent works — every heartbeat, every task, every comment it reads and writes — it sends and receives text through a provider like Anthropic or OpenAI, which charges you per token (roughly per word). This isn't a Paperclip fee; it's a cost you pay directly to the AI provider. Read this guide before your agents start running in earnest.
 
 Paperclip's budget system exists to make sure you're never surprised. You set limits, and the platform enforces them automatically — an agent won't spend a cent beyond what you allow.
 
-The **Costs** page in the sidebar is where all of this lives. It has five tabs — **Overview**, **Budgets**, **Providers**, **Billers**, and **Finance** — plus a shared date-range selector and four headline metrics at the top. This guide walks through each tab, then folds in the core concepts around how costs work, how budgets protect you, and how to tune spend over time.
+All of this lives under **Audit** in the sidebar. The Audit page has five tabs — **Activity**, **Runs**, **Costs**, **Budgets**, and **Timeline** — and two of them are the subject of this guide:
+
+- **Costs** — where your money went. It has its own row of views — **Overview**, **Providers**, **Billers**, and **Finance** — plus a shared date-range selector and four headline metrics at the top.
+- **Budgets** — the limits that stop spend, and the incidents raised when a limit is hit.
+
+This guide walks through each view, then folds in the core concepts around how costs work, how budgets protect you, and how to tune spend over time. (Older `/costs` and `/budgets` links still work — they redirect into Audit.)
 
 ---
 
@@ -26,9 +31,9 @@ Paperclip records every one of these calls: which agent made it, which model it
 
 If you multiply an agent's token count by the provider's list price, you'll usually land somewhere above what Paperclip reports. That gap is normally prompt caching doing its job, not an error in the arithmetic.
 
-Agents re-send a lot of the same text on every heartbeat — their identity, their standing instructions, the task they're working on. Providers cache that repeated context and charge much less for a cached token than for a fresh one. You can see the split yourself in the per-model rows on the **Providers** tab, where cached-input tokens are counted separately from input tokens.
+Agents re-send a lot of the same text on every heartbeat — their identity, their standing instructions, the task they're working on. Providers cache that repeated context and charge much less for a cached token than for a fresh one. You can see the split yourself in the per-model rows on the **Providers** view, where cached-input tokens are counted separately from input tokens.
 
-Paperclip records the **cache-adjusted** cost: what the provider actually billed after the cache discount, rather than an estimate derived from raw token counts. When an adapter reports a discounted amount separately, that discounted amount is the one that lands in the cost ledger, counts against your budgets, and rolls up into every total on this page. When an adapter reports only a single cost figure, Paperclip treats that figure as the billed amount.
+Paperclip records the **cache-adjusted** cost: what the provider actually billed after the cache discount, rather than an estimate derived from raw token counts. When an adapter reports a discounted amount separately, that discounted amount is the one that lands in the cost ledger, counts against your budgets, and rolls up into every total on the Costs tab. When an adapter reports only a single cost figure, Paperclip treats that figure as the billed amount.
 
 The practical rule: the dollars you see are billed dollars. A run with a large cached-input count and a small dollar figure is healthy — it means the agent's context is being reused instead of re-billed. If you want to reason about a run in detail, read the token columns and the dollar figure together rather than trying to derive one from the other.
 
@@ -36,13 +41,13 @@ Beyond per-request inference costs, there are also **account-level** charges —
 
 ---
 
-## Page Header and Date Range
+## Costs Tab: Header and Date Range
 
-Every tab on the Costs page shares the same header, so it's worth understanding what you're looking at before diving into the individual views.
+Open **Audit** in the sidebar and click the **Costs** tab. Every view on the Costs tab shares the same header, so it's worth understanding what you're looking at before diving into the individual views.
 
-The page title reads **Costs**, with a subtitle that reminds you what's tracked: inference spend, platform fees, credits, and live quota windows.
+The header reads **Costs**, with a subtitle that reminds you what's tracked: inference spend, platform fees, credits, and live quota windows.
 
-To the right of the title is a **date-range selector** — a row of preset buttons (**Month to Date**, **Last 7 Days**, **Last 30 Days**, **Year to Date**, **All Time**, and **Custom**) that scopes every chart, table, and metric on the page. If you pick **Custom**, two date inputs appear and you enter the start and end date manually. Until both custom dates are filled in, most of the tabs show a prompt to pick a range before loading data.
+To the right of the title is a **date-range selector** — a row of preset buttons (**Month to Date**, **Last 7 Days**, **Last 30 Days**, **Year to Date**, **All Time**, and **Custom**) that scopes every chart, table, and metric on the Costs tab. If you pick **Custom**, two date inputs appear and you enter the start and end date manually. Until both custom dates are filled in, most of the views show a prompt to pick a range before loading data.
 
 Below the header is a strip of four **metric tiles** that summarise the current range:
 
@@ -55,11 +60,11 @@ These tiles always reflect the selected date range, not an all-time total.
 
 ---
 
-## Overview Tab
+## Overview
 
-![Overview tab](../../user-guides/screenshots/light/costs/overview.png)
+![Overview view on the Audit Costs tab](../../user-guides/screenshots/light/costs/overview.png)
 
-The **Overview** tab is the default landing view. It gives you a single-screen readout of spend health without forcing you to drill into any one dimension.
+**Overview** is the default view when you open the Costs tab. It gives you a single-screen readout of spend health without forcing you to drill into any one dimension.
 
 ### Inference ledger card
 
@@ -89,7 +94,7 @@ Below the ledger cards is the **By agent** card. Each agent that generated infer
 - Agent name and avatar, plus a `terminated` badge if the agent has been retired.
 - Total cost for the range, right-aligned.
 - Token breakdown: `in <input+cached> · out <output>`.
-- Run-type breakdown: `N api · N subscription` — how many runs went through API-priced calls versus subscription-backed calls (see **Billers** below for the distinction).
+- Run-type breakdown: `N api · N subscription` — how many runs went through API-priced calls versus subscription-backed calls (see [Billers](#billers) below for the distinction).
 
 If an agent has a per-model breakdown available, a caret appears on the left of the row. Clicking the row expands it to show one line per `provider / model / billingType` combination with its share of that agent's spend, the cost, the token count, and which biller handled the call. This is the fastest way to see "why is this particular agent spending so much" — you can immediately tell whether it's one runaway model or a healthy mix.
 
@@ -103,164 +108,19 @@ Under the project card is a compact **finance timeline** showing the most recent
 
 ### Active budget incidents (overview)
 
-If any agent or project has breached its hard-stop budget, up to two **Budget incident cards** appear at the top of the Overview tab, above everything else. Each card shows the scope, the breach details, and two resolution buttons — **Keep paused** or **Raise budget and resume** (with an amount input). The full incident list lives on the Budgets tab.
+If any agent or project has breached its hard-stop budget, up to two **Budget incident cards** appear at the top of the Overview, above everything else. Each card shows the scope, the breach details, and two resolution buttons — **Keep paused** or **Raise budget & resume** (with a **New budget (USD)** input). The full incident list lives on the [Budgets tab](#budgets-tab).
 
 ---
 
-## Budgets Tab
+## Providers
 
-![Budgets tab](../../user-guides/screenshots/light/costs/budgets.png)
+![Providers view on the Audit Costs tab](../../user-guides/screenshots/light/costs/providers.png)
 
-The **Budgets** tab is where you configure the spend ceilings that protect your company. Think of it as the control plane for hard stops — the place where you decide, in dollars, how much any given scope is allowed to spend before Paperclip pulls the emergency brake.
-
-### Budget Levels
-
-Paperclip operates two levels of budget protection that work together:
-
-**Company budget** — the total monthly ceiling for your entire company. All agents combined cannot spend more than this. Set it conservatively when starting out.
-
-**Per-agent budget** — an individual monthly ceiling for each agent. This is enforced independently of the company total. An agent at 100% pauses even if the company still has budget remaining. This protects you from any single agent spending disproportionately.
-
-A third scope, **project budget**, acts as a lifetime cap on an execution-bound project — useful for one-off work where you want to say "this project can never cost more than $200" regardless of the month.
-
-All budgets are displayed in dollars in the Paperclip UI.
-
-### Budget control plane
-
-At the top of the Budgets tab is a **Budget control plane** card with four headline metrics:
-
-- **Active incidents** — open soft or hard threshold crossings.
-- **Pending approvals** — budget override approvals awaiting board action.
-- **Paused agents** — count of agents currently blocked from running because of a budget breach.
-- **Paused projects** — count of projects currently blocked from execution because of a budget breach.
-
-If all four show zero, your budget posture is clean.
-
-### What Happens When Limits Are Hit
-
-Paperclip enforces budgets automatically, in two stages:
-
-```
-$0 ─────────────────────── 80% ──────── 100%
-   Normal operation         ⚠              🛑
-                          Warning        Auto-paused
-```
-
-**At 80%:** Paperclip records a warning so you can intervene before the hard stop. The agent continues running.
-
-**At 100%:** The agent is automatically paused. No further heartbeats are triggered. The agent stops all activity until either you increase its budget or the calendar month resets.
-
-An auto-paused agent doesn't lose its work — any tasks it had in progress remain assigned to it and will pick up again once the agent is resumed.
-
-### Active incidents
-
-If any budget policy has been breached, an **Active incidents** section appears under the control plane. Each incident card shows:
-
-- The scope (company, agent, or project) and its name.
-- The policy details — how much was configured and how much was actually spent.
-- Two actions:
-  - **Keep paused** — acknowledge the breach and leave the scope paused. Useful when you want the agent to stop for the rest of the month and resume naturally at rollover.
-  - **Raise budget and resume** — increase the policy's amount (you enter the new cap in the card) and immediately un-pause the scope.
-
-Both actions are logged and become part of the audit trail.
-
-### Budget policies by scope
-
-Below the incidents, the rest of the tab is organised into three sections — **Company budgets**, **Agent budgets**, and **Project budgets** — with one Budget policy card per configured policy in each section.
-
-Each policy card shows:
-
-- The scope (who this applies to) and the window kind (monthly recurring for company and agent, lifetime for project).
-- The current cap and the current spend against it.
-- An editable amount field and a **Save** button.
-
-If no policies exist yet, a single empty-state card appears with a pointer to set agent and project budgets from their detail pages and to use the existing company monthly budget control.
-
-### Setting a Company Budget
-
-1. **Open the Costs page**
-
-   Company-wide budget controls live on the **Costs** page, under the **Budgets** tab.
-
-   ![Company settings page showing the Monthly Budget field](../../user-guides/screenshots/light/costs/company-budget-field.png)
-
-2. **Set the monthly budget**
-
-   Enter a dollar amount in the Monthly Budget field. This is the maximum your entire company can spend in a calendar month.
-
-   > **Tip:** Start conservative — $50–100/month is enough for experimentation with a small team. You can always increase it once you have a feel for how much your agents are spending.
-
-3. **Save**
-
-### Setting Per-Agent Budgets
-
-Each agent should have its own budget. This limits exposure from any single agent and makes your cost picture easier to read.
-
-1. **Open the agent's Budget tab**
-
-   Click the agent's name in the sidebar or in the Agents list, then open **Budget** on the agent detail page.
-
-   ![Agent budget field in the agent configuration panel](../../user-guides/screenshots/light/costs/agent-budget-field.png)
-
-2. **Set the monthly budget**
-
-   Enter a dollar amount. Some rough guidance on how to think about agent budgets:
-
-   | Agent role | Typical monthly budget |
-   |------------|------------------------|
-   | CEO | $30–50 — runs frequently, high context per run |
-   | Manager (CTO, CMO, etc.) | $20–40 — active but more focused than CEO |
-   | Worker agent (engineer, writer, etc.) | $10–25 — executes tasks but less strategic reasoning |
-
-   These are starting points, not rules. Watch actual spend for the first two weeks and adjust from there.
-
-3. **Save**
-
-### Increasing a Budget or Resuming a Paused Agent
-
-If an agent hits its 100% limit and auto-pauses, you have two options:
-
-**Option 1: Increase the agent's monthly budget**
-
-1. Open the agent's settings
-2. Update the Monthly Budget field to a higher amount
-3. Save
-
-The agent will resume immediately. It won't wait for the month to roll over.
-
-**Option 2: Wait for the month to reset**
-
-On the 1st of each UTC month, all monthly budgets reset to zero. A paused agent that's been paused purely for budget reasons will become active again automatically at rollover.
-
-> **Note:** If you don't want the agent to resume automatically at month rollover, manually pause it first. Otherwise it will start running again as soon as the new month begins.
-
-### Viewing Budget Status at Different Thresholds
-
-For reference, here's what to expect at each stage:
-
-![Agent budget bar at approximately 50% — green, no warning](../../user-guides/screenshots/light/costs/agent-budget-50pct.png)
-
-*Normal operation — green bar, no action needed.*
-
-![Agent budget bar at 80% — amber warning state](../../user-guides/screenshots/light/costs/agent-budget-80pct-warning.png)
-
-*Warning threshold reached — this is your signal to intervene before the hard stop.*
-
-![Agent budget bar at 100% — red, agent shown as paused](../../user-guides/screenshots/light/costs/agent-budget-100pct-paused.png)
-
-*Budget exhausted — agent is auto-paused. Increase budget or wait for month reset.*
-
----
-
-## Providers Tab
-
-![Providers tab](../../user-guides/screenshots/light/costs/providers.png)
-
-The **Providers** tab breaks spend down by who the inference was actually performed by — Anthropic, OpenAI, Google, and any other model provider your agents use. This is the view you want when you're asking "how much am I sending Anthropic this month?" or "is my OpenAI usage growing?".
+The **Providers** view breaks spend down by who the inference was actually performed by — Anthropic, OpenAI, Google, and any other model provider your agents use. This is the view you want when you're asking "how much am I sending Anthropic this month?" or "is my OpenAI usage growing?".
 
 ### Provider sub-tabs
 
-At the top of the tab is a sub-tab bar. The first entry is **All providers** — an aggregate showing tokens and cents across everything. After that comes one sub-tab per provider that generated events in the selected range. Each sub-tab label includes the provider's display name, its token count, and its cost, so you can read the split without clicking in.
+At the top of the view is a sub-tab bar. The first entry is **All providers** — an aggregate showing tokens and cents across everything. After that comes one sub-tab per provider that generated events in the selected range. Each sub-tab label includes the provider's display name, its token count, and its cost, so you can read the split without clicking in.
 
 ### Provider card
 
@@ -287,15 +147,15 @@ Underneath the quota bars, Paperclip also shows **window spend** — what the pr
 
 ---
 
-## Billers Tab
+## Billers
 
-![Billers tab](../../user-guides/screenshots/light/costs/billers.png)
+![Billers view on the Audit Costs tab](../../user-guides/screenshots/light/costs/billers.png)
 
-The **Billers** tab answers a different question than **Providers**: not "who ran the inference?" but "who charged me for it?". In most companies these are the same entity, but they can diverge — for example, when you run Claude models through a subscription plan (Anthropic is the biller *and* provider) versus through the API (Anthropic is still the biller, but the pricing model is different), or when a gateway or reseller handles the billing relationship on your behalf.
+The **Billers** view answers a different question than **Providers**: not "who ran the inference?" but "who charged me for it?". In most companies these are the same entity, but they can diverge — for example, when you run Claude models through a subscription plan (Anthropic is the biller *and* provider) versus through the API (Anthropic is still the biller, but the pricing model is different), or when a gateway or reseller handles the billing relationship on your behalf.
 
 ### Biller sub-tabs
 
-Like the Providers tab, the Billers tab has a sub-tab bar at the top. **All billers** shows an aggregate grid; each per-biller sub-tab shows the same card standalone. Sub-tab labels include the biller's display name, token count, and cost.
+Like Providers, the Billers view has a sub-tab bar at the top. **All billers** shows an aggregate grid; each per-biller sub-tab shows the same card standalone. Sub-tab labels include the biller's display name, token count, and cost.
 
 ### Biller spend card
 
@@ -312,19 +172,19 @@ The Biller view is how you reconcile invoices. When the Anthropic invoice lands
 
 ### Attribution
 
-Every cost event in Paperclip is tagged with both a provider (who did the inference) and a biller (who charges you). For simple setups the two are identical, and you can largely ignore the Billers tab. For more complex setups — multiple accounts with the same provider, subscription-plus-API combinations, or a centralised gateway — the Billers tab is how you keep the accounting clean.
+Every cost event in Paperclip is tagged with both a provider (who did the inference) and a biller (who charges you). For simple setups the two are identical, and you can largely ignore the Billers view. For more complex setups — multiple accounts with the same provider, subscription-plus-API combinations, or a centralised gateway — the Billers view is how you keep the accounting clean.
 
 ---
 
-## Finance Tab
+## Finance
 
-![Finance tab](../../user-guides/screenshots/light/costs/finance.png)
+![Finance view on the Audit Costs tab](../../user-guides/screenshots/light/costs/finance.png)
 
-The **Finance** tab is the account-level ledger — everything that isn't a per-request inference cost. Subscription fees, invoice reconciliations, credit top-ups, refunds, and adjustments all land here. If the Providers and Billers tabs show what your agents did, the Finance tab shows what actually hit your accounts.
+The **Finance** view is the account-level ledger — everything that isn't a per-request inference cost. Subscription fees, invoice reconciliations, credit top-ups, refunds, and adjustments all land here. If the Providers and Billers views show what your agents did, the Finance view shows what actually hit your accounts.
 
 ### Finance summary card
 
-At the top of the tab is the **Finance ledger** card with four metric tiles — the same four from the page header, expanded into full-width tiles:
+At the top of the view is the **Finance ledger** card with four metric tiles — the same four from the page header, expanded into full-width tiles:
 
 - **Debits** — total debited dollars in the range, plus the count of events.
 - **Credits** — refunds, offsets, and credit returns.
@@ -333,17 +193,17 @@ At the top of the tab is the **Finance ledger** card with four metric tiles —
 
 ### By biller
 
-The **By biller** card groups finance events by who charged or credited you. Each **FinanceBillerCard** shows the biller, its debit and credit totals for the range, and an event count. This is the usual starting point for reconciling against a specific vendor's invoices.
+The **By biller** card groups finance events by who charged or credited you. Each biller row shows the biller, its debit and credit totals for the range, and an event count. This is the usual starting point for reconciling against a specific vendor's invoices.
 
 If no finance events exist yet, the card prompts you to add them once biller invoices or credits land.
 
 ### Finance timeline
 
-Below the biller grid is a **FinanceTimelineCard** listing individual finance events chronologically. Each row shows the event type (e.g. subscription debit, credit top-up, invoice adjustment), amount, biller, timestamp, and whether it's estimated or authoritative. This is where you spot the specific event you're trying to trace.
+Below the biller grid is the **Recent financial events** card, listing individual finance events chronologically. Each row shows the event type (e.g. subscription debit, credit top-up, invoice adjustment), amount, biller, timestamp, and whether it's estimated or authoritative. This is where you spot the specific event you're trying to trace.
 
-### By kind
+### Financial event mix
 
-To the right of the timeline is the **By kind** card. Instead of grouping by who charged you, it groups by *what kind of event* — all subscription debits together, all credits together, all adjustments together. Useful when you're answering "how much are we spending on subscriptions versus pay-as-you-go?".
+To the right of the timeline is the **Financial event mix** card. Instead of grouping by who charged you, it groups by *what kind of event* — all subscription debits together, all credits together, all adjustments together. Useful when you're answering "how much are we spending on subscriptions versus pay-as-you-go?".
 
 ### Estimated versus actual
 
@@ -351,9 +211,163 @@ Paperclip separates estimated debits from authoritative ones because your provid
 
 The **Estimated** metric at the top tells you, at a glance, how much of your finance ledger is still provisional. A small number means most of your ledger is invoice-backed; a large number means a lot of estimated spend is waiting for reconciliation.
 
-### Exporting finance data
+---
 
-Finance events can be exported for use in external accounting systems. The export carries the same fields you see in the timeline (event kind, biller, debit/credit amounts, timestamps, authoritative flag) so the resulting file can be reconciled against provider invoices or uploaded into a ledger.
+## Budgets Tab
+
+![Audit page on the Budgets tab, showing the Budget control plane card and budget policy cards](../../user-guides/screenshots/light/costs/budgets.png)
+
+Open **Audit** in the sidebar and click the **Budgets** tab. This is where you configure the spend ceilings that protect your company. It's a peer of the Costs tab rather than part of it, and it doesn't use the date-range selector — budgets always work on their own windows. Think of it as the control plane for hard stops — the place where you decide, in dollars, how much any given scope is allowed to spend before Paperclip pulls the emergency brake.
+
+### Budget Levels
+
+Paperclip operates two levels of budget protection that work together:
+
+**Organization budget** — the total monthly ceiling for your entire company. All agents combined cannot spend more than this. Set it conservatively when starting out.
+
+**Per-agent budget** — an individual monthly ceiling for each agent. This is enforced independently of the company total. An agent at 100% pauses even if the company still has budget remaining. This protects you from any single agent spending disproportionately.
+
+A third scope, **project budget**, acts as a lifetime cap on an execution-bound project — useful for one-off work where you want to say "this project can never cost more than $200" regardless of the month. You set it from the project's own **Budget** tab.
+
+All budgets are displayed in dollars in the Paperclip UI.
+
+### Budget control plane
+
+At the top of the Budgets tab is a **Budget control plane** card with four headline metrics:
+
+- **Active incidents** — open soft or hard threshold crossings.
+- **Pending approvals** — budget override approvals awaiting board action.
+- **Paused agents** — count of agents currently blocked from running because of a budget breach.
+- **Paused projects** — count of projects currently blocked from execution because of a budget breach.
+
+If all four show zero, your budget posture is clean.
+
+### What Happens When Limits Are Hit
+
+Paperclip enforces budgets automatically, in two stages:
+
+```
+$0 ─────────────────────── 80% ──────── 100%
+   Normal operation         ⚠              🛑
+                          Warning        Auto-paused
+```
+
+**At 80%:** Paperclip records a warning so you can intervene before the hard stop. The warning doesn't pause the agent. Its incident card is an amber **… budget warning** with **Raise budget** and **Dismiss warning**. In v2026.1012.0 itself, this card still shows the hard-stop design and says the scope is paused. The screenshots show the corrected card from [the fix](https://github.com/paperclipai/paperclip/pull/16201), which ships in a later release. Until then, trust the policy card's **Warning** badge: the warning itself doesn't pause the agent.
+
+**At 100%:** The agent is automatically paused. No further heartbeats are triggered. The agent stops all activity until either you increase its budget or the calendar month resets.
+
+An auto-paused agent doesn't lose its work — any tasks it had in progress remain assigned to it and will pick up again once the agent is resumed.
+
+### Active incidents
+
+If any budget policy has been breached, an **Active incidents** section appears under the control plane. Each incident card shows:
+
+- The scope (company, agent, or project) and its name.
+- The policy details — how much was configured and how much was actually spent.
+- Two actions:
+  - **Keep paused** — acknowledge the breach and leave the scope paused. Useful when you want the agent to stop for the rest of the month and resume naturally at rollover.
+  - **Raise budget & resume** — increase the policy's amount (you enter the new cap in **New budget (USD)**; it must be higher than what's already been spent) and immediately un-pause the scope.
+
+Both actions are logged and become part of the audit trail.
+
+### Budget policies by scope
+
+Below the incidents, the rest of the tab is organised into up to three sections — **Organization Budgets**, **Agent Budgets**, and **Project Budgets** — with one budget policy card per configured policy. A section only appears once it has at least one policy in it.
+
+Each policy card shows:
+
+- The scope type and name (who this applies to) and the window — **Monthly UTC budget** for organization and agent policies, **Lifetime budget** for projects.
+- A status badge: **Healthy**, **Warning**, **Hard stop**, or **Paused**.
+- **Observed** spend (with the percentage of the limit used) next to the **Budget** cap and the soft-alert threshold.
+- A **Remaining** amount with a utilisation bar — green while healthy, amber once the warning threshold is crossed, red at the hard stop.
+- A **Budget (USD)** field with a **Set budget** or **Update budget** button.
+
+If no policies exist yet, a single empty-state card says so: "No budget policies yet. Set agent and project budgets from their detail pages, or use the existing organization monthly budget control." In practice, here's where each kind of policy starts:
+
+- **Agents** — hire the agent through the API with a monthly budget, or give an existing agent a cap with the CLI or API (see [Set a monthly budget](../../how-to/set-monthly-budget.md)).
+- **Projects** — open the project and click its **Budget** tab. You can set a lifetime cap there even before any policy exists.
+- **Organization** — use the organization monthly budget control.
+
+Once a policy exists, its card here is where you change it.
+
+### Setting a Company Budget
+
+1. **Open Audit → Budgets**
+
+   Click **Audit** in the sidebar, then the **Budgets** tab. The company-wide policy appears under **Organization Budgets**.
+
+   ![Organization budget policy card on Audit → Budgets, showing observed spend, the Budget (USD) field, and the Update budget button](../../user-guides/screenshots/light/costs/company-budget-field.png)
+
+2. **Set the monthly budget**
+
+   Enter a dollar amount in the **Budget (USD)** field. This is the maximum your entire company can spend in a calendar month.
+
+   If there's no Organization Budgets card yet, set the first company budget through the API — [Set a monthly budget](../../how-to/set-monthly-budget.md) shows the one-line call. The card appears as soon as the policy exists.
+
+   > **Tip:** Start conservative — $50–100/month is enough for experimentation with a small team. You can always increase it once you have a feel for how much your agents are spending.
+
+3. **Click Update budget** (or **Set budget** if the cap is currently zero)
+
+### Setting Per-Agent Budgets
+
+Each agent should have its own budget. This limits exposure from any single agent and makes your cost picture easier to read.
+
+1. **Find the agent's budget card**
+
+   Click **Audit** in the sidebar, then the **Budgets** tab, and find the agent under **Agent Budgets**. (From an agent's own page you can get here too: click **Budgets** under **Audit** in the agent's side menu.)
+
+   ![Agent budget policy card on Audit → Budgets, showing the agent's observed spend, monthly cap, and Budget (USD) field](../../user-guides/screenshots/light/costs/agent-budget-field.png)
+
+   If the agent has no card yet, it doesn't have a budget policy. Agents hired through the API with a monthly budget get one automatically, but the setup flow in the app doesn't set one. To give any other agent a cap, use the CLI's `budget agent:update` command (see [Cost & budget commands](../../reference/cli/cost.md)) or the [Set agent budget](../../reference/api/costs.md#set-agent-budget) API. [Set a monthly budget](../../how-to/set-monthly-budget.md) walks through the API call.
+
+   Projects work differently: open the project and click its **Budget** tab to set a lifetime cap, even if the project has no policy yet.
+
+2. **Set the monthly budget**
+
+   Enter a dollar amount in **Budget (USD)**. Some rough guidance on how to think about agent budgets:
+
+   | Agent role | Typical monthly budget |
+   |------------|------------------------|
+   | CEO | $30–50 — runs frequently, high context per run |
+   | Manager (CTO, CMO, etc.) | $20–40 — active but more focused than CEO |
+   | Worker agent (engineer, writer, etc.) | $10–25 — executes tasks but less strategic reasoning |
+
+   These are starting points, not rules. Watch actual spend for the first two weeks and adjust from there.
+
+3. **Click Update budget** (or **Set budget** if the cap is currently zero)
+
+### Increasing a Budget or Resuming a Paused Agent
+
+If an agent hits its 100% limit and auto-pauses, you have two options:
+
+**Option 1: Increase the agent's monthly budget**
+
+1. Open **Audit → Budgets**. The breach shows up as a card under **Active incidents**, and the agent's policy card under **Agent Budgets** is marked **Paused**.
+2. Either enter a higher amount in the incident card's **New budget (USD)** field and click **Raise budget & resume**, or type it into the policy card's **Budget (USD)** field and click **Update budget**.
+
+The agent will resume immediately. It won't wait for the month to roll over.
+
+**Option 2: Wait for the month to reset**
+
+On the 1st of each UTC month, all monthly budgets reset to zero. A paused agent that's been paused purely for budget reasons will become active again automatically at rollover.
+
+> **Note:** If you don't want the agent to resume automatically at month rollover, manually pause it first. Otherwise it will start running again as soon as the new month begins.
+
+### Viewing Budget Status at Different Thresholds
+
+For reference, here's what an agent's policy card on **Audit → Budgets** looks like at each stage:
+
+![Agent budget policy card at about 50% — Healthy badge and a green utilisation bar](../../user-guides/screenshots/light/costs/agent-budget-50pct.png)
+
+*Normal operation — **Healthy**, green bar, no action needed.*
+
+![Agent budget policy card at about 80% — amber Warning badge and an amber utilisation bar](../../user-guides/screenshots/light/costs/agent-budget-80pct-warning.png)
+
+*Warning threshold reached — the badge flips to **Warning**. This is your signal to intervene before the hard stop.*
+
+![Agent budget policy card at 100% — Paused badge, a full red bar, and a note that heartbeats are paused until the budget is raised or the incident is dismissed](../../user-guides/screenshots/light/costs/agent-budget-100pct-paused.png)
+
+*Budget exhausted — the card shows **Paused** and the agent is auto-paused. Increase the budget or wait for the month to reset.*
 
 ---
 
@@ -361,23 +375,25 @@ Finance events can be exported for use in external accounting systems. The expor
 
 ### From the Dashboard
 
-The Cost Summary panel on the dashboard shows each agent's current month spend as a bar chart. Green = normal, amber = approaching limit (80%+), red = paused at 100%.
+The **Month Spend** card on the dashboard shows what the company has spent this month and how that compares with the company budget (for example, `62% of $100.00 budget`). If any budget has been breached, a red banner above the cards counts the active incidents and paused agents.
 
-![Cost Summary dashboard panel showing per-agent budget bars, two green and one amber](../../user-guides/screenshots/light/costs/costs-dashboard-overview.png)
+Check the card whenever you open Paperclip. Click it to jump to the Costs tab under Audit, where the **Overview** breaks spend down by agent and by project:
 
-Check this panel whenever you open Paperclip. A bar that has jumped unexpectedly since your last check is worth investigating.
+![Overview on the Audit Costs tab, showing the date-range presets, the four headline metric tiles, the inference and finance ledger cards, and the By agent breakdown](../../user-guides/screenshots/light/costs/costs-dashboard-overview.png)
 
-### From the Agent Detail Page
+An agent whose total has jumped unexpectedly since your last check is worth investigating.
 
-Click on any agent, then open **Runs** to see per-run spend and **Budget** to see the current cap and utilization.
+### Drilling into One Agent
 
-![Per-run cost detail showing model, input tokens, output tokens, and dollar cost for each heartbeat](../../user-guides/screenshots/light/costs/per-run-cost-detail.png)
+In the **By agent** card on the Costs tab's Overview, click an agent's row to expand it. You get one line per provider and model the agent used, with its share of the agent's spend, the cost, the token count, and the biller.
 
-This is useful when you want to understand why a particular agent is spending more than expected.
+![By agent card on the Audit Costs tab with one agent's row expanded into per-model lines showing provider, model, share of spend, cost, and tokens](../../user-guides/screenshots/light/costs/per-run-cost-detail.png)
 
-### From the Costs page
+From an agent's own page, the **Audit** section of its overview links straight to that agent's **Runs** (to inspect individual heartbeats) and **Budgets** (to see its cap and utilisation). This is useful when you want to understand why a particular agent is spending more than expected.
 
-For anything cross-agent — "which provider got the most money this week?", "which project ate the most budget?", "how much of our ledger is still estimated?" — go straight to the Costs page and pick the tab that matches the question. Overview for a general health check, Providers/Billers for vendor accounting, Finance for invoice reconciliation, Budgets for hard-stop management.
+### From Audit
+
+For anything cross-agent — "which provider got the most money this week?", "which project ate the most budget?", "how much of our ledger is still estimated?" — open **Audit** and pick the tab and view that match the question. On the **Costs** tab: Overview for a general health check, Providers/Billers for vendor accounting, Finance for invoice reconciliation. The **Budgets** tab is for hard-stop management.
 
 ---
 
@@ -391,14 +407,14 @@ For anything cross-agent — "which provider got the most money this week?", "wh
 
 **Pause agents during off-hours.** If your company doesn't need to run 24/7, manually pause agents at the end of the working day and resume them in the morning. Most of the autonomous work can happen within a defined window.
 
-**Watch the cost-per-run on new agents.** After a new agent completes its first few heartbeats, check the per-run cost on its detail page. If it's higher than expected, check what it's doing: long context chains, excessive tool use, or a misconfigured prompt can all inflate cost.
+**Watch the cost-per-run on new agents.** After a new agent completes its first few heartbeats, check its spend in the **By agent** card on the Costs tab. If it's higher than expected, check what it's doing: long context chains, excessive tool use, or a misconfigured prompt can all inflate cost.
 
-**Prefer subscriptions when usage is predictable.** If you have an agent whose workload is steady and fits comfortably inside a provider's plan window (e.g. an Anthropic Pro subscription), routing through the subscription biller can be cheaper than pay-as-you-go API pricing. Use the Providers tab's quota-window view to confirm the subscription has headroom before committing an agent to it.
+**Prefer subscriptions when usage is predictable.** If you have an agent whose workload is steady and fits comfortably inside a provider's plan window (e.g. an Anthropic Pro subscription), routing through the subscription biller can be cheaper than pay-as-you-go API pricing. Use the Providers view's quota windows to confirm the subscription has headroom before committing an agent to it.
 
-**Reconcile finance regularly.** Invoice-authoritative numbers are always more accurate than estimates. A few minutes a month importing the real invoice into the Finance tab keeps your ledger honest and catches pricing changes early.
+**Reconcile finance regularly.** Invoice-authoritative numbers are always more accurate than estimates. A few minutes a month importing the real invoice into the Finance view keeps your ledger honest and catches pricing changes early.
 
 ---
 
-Your company's finances are now under control. The next guide covers the Activity Log — the complete audit trail of everything that has ever happened in your company, and how to use it to understand and debug agent behaviour.
+Your company's finances are now under control. The next guide covers the **Activity** tab under Audit — the complete audit trail of everything that has ever happened in your company, and how to use it to understand and debug agent behaviour.
 
-[Activity Log →](./activity-log.md)
+[Audit: Activity →](./activity-log.md)

docs/guides/day-to-day/dashboard.md

@@ -1,4 +1,5 @@
 ---
+paperclip_version: v2026.1012.0
 seo_title: The Dashboard
 seo_description: Your control centre: agent status, overview cards, and the recent activity feed — plus how to read all three at a glance and catch trouble early.
 ---
@@ -15,9 +16,11 @@ Think of it like the cockpit instruments on a plane. You don't need to read ever
 
 ## Agents Section
 
-At the top of the dashboard, Paperclip shows your live agent activity and a set of overview cards. This is the quickest way to tell whether work is moving.
+At the top of the dashboard, Paperclip shows your live agent activity in the **Agents** panel, followed by a row of overview cards. This is the quickest way to tell whether work is moving.
 
-![Agent Status panel showing counts by state: active, running, error, and paused](../../user-guides/screenshots/light/dashboard/agent-status-panel.png)
+The first overview card, **Agents Enabled**, rolls your agent states into one number: the total count of enabled agents, with a line underneath that breaks out how many are running, paused, or in error. Click the card to jump to your agents list.
+
+![Agents Enabled overview card showing the total enabled agents, with a "1 running, 1 paused, 0 errors" breakdown underneath](../../user-guides/screenshots/light/dashboard/agent-status-panel.png)
 
 Here's what each state means:
 
@@ -28,7 +31,7 @@ Here's what each state means:
 | **Error** | The agent's last heartbeat failed. It is not working and hasn't stopped gracefully. |
 | **Paused** | The agent has been deliberately stopped — either by you, or automatically because it hit its budget limit. |
 
-> **Warning:** Any agent showing "error" needs attention. The error won't fix itself. Click through to the agent's detail page and open its **Runs** tab to see the transcript of what went wrong — then fix the underlying issue (usually an API key problem, a budget running out, or a misconfigured adapter).
+> **Warning:** Any agent showing "error" needs attention. The error won't fix itself. Open the agent, then use the **Runs** link in the **Audit** section of its overview to see the transcript of what went wrong — then fix the underlying issue (usually an API key problem, a budget running out, or a misconfigured adapter).
 
 The most common healthy pattern early on: one agent **running** while the others stay **active**. If you see multiple agents in error or paused unexpectedly, that's worth investigating before leaving things to run.
 
@@ -38,22 +41,38 @@ The most common healthy pattern early on: one agent **running** while the others
 
 The four cards across the top summarize the company at a glance:
 
-![Task Breakdown panel showing task counts by status: backlog, todo, in_progress, in_review, done, blocked](../../user-guides/screenshots/light/dashboard/task-breakdown-panel.png)
-
 - **Agents Enabled** — how many agents are available to work, plus how many are currently running, paused, or in error.
 - **Tasks In Progress** — how many issues are actively being worked, plus how many remain open or blocked.
 - **Month Spend** — how much the company has spent this month against the current company budget.
 - **Pending Approvals** — how many approvals are waiting on you, including budget-related approvals when they exist.
 
+If any budget has been breached, a red banner appears above the cards with the number of active budget incidents, how many agents and projects are paused, and an **Open budgets** link.
+
+---
+
+## Charts, Recent Activity, and Recent Tasks
+
+Below the cards sit three charts covering the last 14 days: **Run Activity**, **Tasks by Status**, and **Success Rate**. They're good for spotting trends — a dip in success rate or a pile-up of blocked tasks shows up here before it shows up anywhere else.
+
+Further down, two lists sit side by side: **Recent Activity** on the left and **Recent Tasks** on the right (on narrower screens, Recent Activity comes first and Recent Tasks stacks below it).
+
 ---
 
 ## Recent Activity Feed
 
-The Activity feed at the bottom (or side, depending on your screen size) of the dashboard shows the most recent events across your whole company — task status changes, comments, approvals, agent state changes, and budget events.
+The **Recent Activity** list shows the 10 most recent events across your whole company — task status changes, comments, approvals, agent state changes, and budget events.
 
-![Recent Activity feed showing the latest events with timestamps, actors, and descriptions](../../user-guides/screenshots/light/dashboard/activity-feed.png)
+![Recent Activity list on the dashboard showing the latest events, each with the actor, what they did, the task it touched, and a relative timestamp](../../user-guides/screenshots/light/dashboard/activity-feed.png)
 
-This feed isn't meant for deep investigation — it's a pulse check. Scan it after a few hours away and you'll quickly understand what's been happening. For detailed investigation, the full Activity page is a dedicated screen (covered in the [Activity Log guide](./activity-log.md)).
+This feed isn't meant for deep investigation — it's a pulse check. Scan it after a few hours away and you'll quickly understand what's been happening. For detailed investigation, open **Audit** in the sidebar (covered in the [Audit: Activity guide](./activity-log.md)).
+
+---
+
+## Recent Tasks
+
+Next to the activity feed, the **Recent Tasks** list shows the tasks that changed most recently, each with its status icon, assignee, task identifier, and how long ago it was updated. Click any row to open the task.
+
+![Recent Tasks list on the dashboard showing recently updated tasks with status icons, assignees, identifiers, and relative timestamps](../../user-guides/screenshots/light/dashboard/task-breakdown-panel.png)
 
 ---
 

docs/guides/day-to-day/issues.md

@@ -12,9 +12,7 @@ Most of the time, your CEO agent creates issues automatically as part of its str
 
 The product language uses **task** and **issue** for the same piece of work. The UI calls the page **Tasks**; the underlying API route is `/api/issues`.
 
-*This screenshot shows the earlier Issues list layout; the current sidebar calls this page Tasks.*
-
-![Earlier Issues list layout](../../user-guides/screenshots/light/issues/list.png)
+![The Tasks page, listing every task in the company with sub-tasks nested under their parent](../../user-guides/screenshots/light/issues/list.png)
 
 ---
 
@@ -34,7 +32,7 @@ For everything else, trust the CEO and review work via the dashboard and approva
 
 ## Opening the Issues page
 
-Open **Tasks** to see the work across your company. The API calls these records issues, and the route remains `/issues`. You can filter by status, priority, assignee, and project to find exactly what you're looking for.
+Open **Tasks** to see the work across your company. The API calls these records issues, and the route remains `/issues`. You can filter by status, responsible agent or person, project, and more to find exactly what you're looking for.
 
 1. **Click "Tasks" in the left sidebar**
 
@@ -42,7 +40,7 @@ Open **Tasks** to see the work across your company. The API calls these records
 
 2. **Use the filters to narrow down**
 
-   The filter bar at the top lets you filter by status, priority, assignee, project, labels, and (when isolated workspaces are enabled) execution workspace. This becomes essential once you have more than a handful of issues running at once.
+   The **Filter** button in the toolbar lets you filter by **Status**, **Responsible**, **Creator**, **Project**, **Labels**, and (when isolated workspaces are enabled) **Workspace**. This becomes essential once you have more than a handful of issues running at once.
 
    Common filter combinations:
    - Status = **blocked** — see everything that's waiting for intervention
@@ -54,9 +52,9 @@ Open **Tasks** to see the work across your company. The API calls these records
 3. **Group and arrange the list**
 
    The list supports:
-   - **Group by** — `None`, `Type`, or `Workspace` (when isolated workspaces are enabled).
+   - **Group** — **Status**, **Responsible**, **Project**, **Workspace**, **Parent Task**, or **None** (list view only).
    - **Nesting toggle** — collapse parent/child issues into a tree so subtasks render beneath their parent.
-   - **Column picker** — choose which trailing columns are visible (status, priority, assignee, project, labels, updated time, and others).
+   - **Column picker** — choose which trailing columns are visible: **Responsible**, **Kicked off by**, **Project**, **Workspace**, **Parent task**, **Tags**, and **Last updated**.
 
    These controls live in the toolbar next to the search input and persist per view.
 
@@ -94,7 +92,7 @@ Implementation reference: [Tasks page and live updates](https://github.com/paper
 
 6. **Click Create task**, or press **⌘+Enter** (**Ctrl+Enter** on Windows and Linux).
 
-   The task opens after creation. Its **Properties** panel lets you adjust priority, status, parent, project, and the other task fields. Status, reviewers, approvers, and a [task watchdog](#task-watchdogs) aren't set in the new-task dialog — add them from **Properties** once the task exists. A paused assignee can receive the task, but won't start until you resume it.
+   The task opens after creation. Its **Properties** panel lets you adjust status, parent, project, and the other task fields. Status, reviewers, approvers, and a [task watchdog](#task-watchdogs) aren't set in the new-task dialog — add them from **Properties** once the task exists. A paused assignee can receive the task, but won't start until you resume it.
 
 When you create a subtask from an existing task, the dialog shows **Sub-task of** and uses **Create sub-task**. If the project supports isolated workspaces, the creation bar can also offer **Worktrees**: choose a new worktree or reuse an existing one. An unavailable selection produces an inline error so you can retry or choose another. See [Execution workspaces](../projects-workflow/workspaces.md).
 
@@ -185,7 +183,7 @@ The issue is no longer needed and won't be completed. This is also a terminal st
 
 The separate Inbox is the default navigation. The experimental **Combined Inbox + Task List** option is off by default. When you enable it in the streamlined interface, its views move into **Tasks → Views**, and the unread badge moves to Tasks. See [An optional combined task list](../../experimental/task-chat.md#an-optional-combined-task-list).
 
-The **Inbox** is the human-facing triage view. Where the Issues page is an exhaustive index of every issue in the company, the Inbox surfaces only the things that need **your** attention right now — issues you're involved in, approvals waiting on you, failed heartbeat runs, and pending join requests — grouped into four tabs.
+The **Inbox** is the human-facing triage view. Where the Issues page is an exhaustive index of every issue in the company, the Inbox surfaces only the things that need **your** attention right now — issues you're involved in, approvals waiting on you, failed heartbeat runs, and pending join requests — grouped into five tabs: **Mine**, **Recent**, **Unread**, **Blocked**, and **All**.
 
 ![Inbox](../../user-guides/screenshots/light/issues/inbox.png)
 
@@ -224,7 +222,7 @@ The Inbox toolbar mirrors the Issues page:
 
 - A search input with URL-bound `q` parameter.
 - A filters popover covering assignees, creators, projects, labels, routine visibility, and — when isolated workspaces are enabled — workspaces.
-- A group-by control (`None`, `Type`, or `Workspace`).
+- A group-by control (**None**, **Type**, **Responsible**, **Project**, or — when isolated workspaces are enabled — **Workspace**).
 - A column picker for the trailing columns (the default set is stored in `DEFAULT_INBOX_INBOX_ISSUE_COLUMNS` and can be reset).
 - A nesting toggle to collapse parent/child issue groups.
 
@@ -251,60 +249,58 @@ On Mine, the same slot hosts the archive button when the row is archivable.
 
 ---
 
-## My Issues
+## Your personal queue: Inbox → Mine
 
-The **My Issues** page is a lighter, personal queue sibling to the Inbox. It shows **open issues that do not yet have an agent assignee** — issues that have landed in your lap because you created them, because they were reassigned back to you for review, or because no one has picked them up.
+Earlier versions of Paperclip had a separate **My Issues** page. It's gone now — your personal queue is the **Mine** tab of the Inbox (`/inbox/mine`), which also pulls in the approvals and failed runs that are waiting on you.
 
-![My Issues](../../user-guides/screenshots/light/issues/my-issues.png)
+![Inbox → Mine, showing your tasks alongside approvals waiting on you](../../user-guides/screenshots/light/issues/my-issues.png)
 
-Under the hood, My Issues fetches the same company issues list the Issues page uses, and filters to:
-
-- `assigneeAgentId` is empty, and
-- `status` is not `done` and not `cancelled`.
-
-This is a very different lens from Inbox:
-
-| | Inbox | My Issues |
-|---|---|---|
-| Purpose | Triage everything waiting on you | Personal open queue |
-| Surfaces approvals and failed runs | Yes | No |
-| Shows unread markers | Yes | No |
-| Includes recent/participant issues | Yes | No |
-| Archive per-row | Yes (on Mine) | No |
-| Tabs | Mine / Recent / Unread / All | Single list |
-
-In practice: use **Inbox → Mine** for day-to-day triage, and **My Issues** when you want the plain list of things that are still sitting on you as a human because no agent has been assigned yet.
+Approval rows on Mine carry inline **Approve** and **Reject** buttons, so you can decide straight from the queue. Use **Recent**, **Unread**, **Blocked**, and **All** when you need a wider lens.
 
 ---
 
 ## The Issue Detail Sidebar
 
-Opening any issue lands you on the detail view. Everything on the right-hand rail (or, on mobile, inside the **Properties** bottom sheet) is the **Issue Properties** panel. Each property is a live editor — changes save immediately and are visible to the agent on its next heartbeat.
+Opening any task lands you on the detail view. On the default chat-style page, the conversation fills the center and the **Properties** tab of the side panel on the right holds the task's fields (on mobile, they sit inside the **Properties** bottom sheet). Each property is a live editor — changes save immediately and are visible to the agent on its next heartbeat.
 
-*The screenshot below shows the property fields in the older Classic Task Interface; the default task page places them in a tabbed side panel.*
+![A task's Properties tab in the side panel, beside the conversation](../../user-guides/screenshots/light/issues/detail-sidebar.png)
 
-![Property fields in the Classic Task Interface](../../user-guides/screenshots/light/issues/detail-sidebar.png)
+The fields are grouped into sections, in this order. Some rows only appear when they have something to show.
 
-The sidebar exposes the following fields, in order:
+**Work**
 
-- **Status** — the lifecycle status (see reference above). Clicking the status icon opens a picker.
-- **Priority** — `critical`, `high`, `medium`, or `low`.
-- **Labels** — free-form company-scoped labels with a colour. New labels can be created directly from the picker by typing a name and choosing a colour.
+- **Status** — the lifecycle status (see reference above). Click it to open a picker.
 - **Assignee** — an agent or a user. The arrow button next to a resolved agent opens that agent's profile. Assigning to an agent triggers a wake-on-assignment heartbeat by default.
-- **Project** — the project this issue belongs to. The arrow button deep-links to the project page.
-- **Parent** — the parent issue this one is a subtask of. Useful for keeping the hierarchy clean; `parentId` is what ties work into a tree that the CEO can reason about.
-- **Blocked by** — a list of other issues that are blocking this one. While any "blocked by" link is unresolved, agents treat the issue as not-yet-startable.
-- **Blocking** — the inverse view: issues that depend on this one. Read-only from this issue; you edit it from the other side.
-- **Sub-issues** — direct children. Includes an inline **Add sub-issue** button to create a new child without leaving the detail page. Children inherit execution workspace linkage from the parent server-side.
-- **Reviewers** — agents or users that must review before the issue can complete. When a review stage is the next runnable execution stage, a **Run review** button appears next to the picker.
-- **Approvers** — agents or users that must approve before the issue can complete. Same runnable-stage behaviour as Reviewers but for the approval stage.
-- **Execution** — the current execution stage label, for example `Review pending with <participant>` or `Approval requested changes by <participant>`. Read-only; it is driven by the execution policy.
-- **Depth** — the depth of this issue in its parent hierarchy.
-- **Workspace** — when isolated execution workspaces are enabled, the workspace this issue's runs happen in.
-- **Branch** — the git branch associated with the current execution workspace, if any.
-- **Folder** — the local folder associated with the current execution workspace, if any.
-- **Created by** — the user or agent that created the issue.
+- **Model** — appears when the assigned agent's adapter offers model options, so you can pick one for this task.
+- **Project** — the project this task belongs to. The arrow button deep-links to the project page.
+- **Labels** — free-form company-scoped labels with a colour. You can create a new label straight from the picker by typing a name and choosing a colour.
+
+**Relationships**
+
+- **Parent** — the parent task this one is a subtask of. `parentId` is what ties work into a tree the CEO can reason about.
+- **Blocked by** — other tasks blocking this one. While any "blocked by" link is unresolved, agents treat the task as not-yet-startable.
+- **Blocking** — the inverse view: tasks that depend on this one. Read-only here; you edit it from the other side.
+- **Subtasks** — direct children, shown as pills. Open the picker to see the full list and use **Add subtask** to create a new child without leaving the page. Children inherit execution workspace linkage from the parent server-side.
+
+**Execution**
+
+- **Reviewers** — agents or users who must review before the task can complete. When a review stage is the next runnable execution stage, a **Run review now** button appears next to the picker.
+- **Approvers** — agents or users who must approve before the task can complete. Same runnable-stage behaviour as Reviewers, but for the approval stage, with a **Run approval now** button.
+- **Execution** — the current execution stage label, for example `Review pending with <participant>`. Read-only; it's driven by the execution policy.
+- **Monitor** — an optional date and time for a scheduled check-in on the task. When one is set, the row shows the next check time.
+- **Watchdog** — the agent that watches this task's subtree for stalls. See [Task watchdogs](#task-watchdogs).
+
+**Workspace** (when the task has a workspace)
+
+- **Execution**, **Workspace**, **Service**, **Branch**, **Folder** — which execution workspace the task's runs use, plus its running service, git branch, and local folder.
+
+**About**
+
+- **Originating** — the user or agent that created the task.
 - **Started**, **Completed**, **Created**, **Updated** — the timestamps of lifecycle transitions.
+- **Depth** — how deep this task sits in its parent hierarchy (only shown for subtasks).
+
+The older **Classic Task Interface** shows the same fields in a stacked sidebar, with a **Sub-tasks** row and an inline **Add sub-task** button.
 
 In **Classic Task Interface**, the detail view also renders these sections outside Properties:
 
@@ -334,7 +330,7 @@ Implementation reference: [side-panel tabs and launcher](https://github.com/pape
 
 Open **Plan** and you get the plan itself, rendered, rather than a link to go find it. Above the text a small line tells you which version you're reading — for example *"Revision 3 · updated Aug 3, 2:15 PM"* — so you can tell at a glance whether the agent has revised the plan since you last looked.
 
-Below the plan sits the accepted-plan history: each accepted revision and the child tasks it created. That's the same **Plan decomposition** view described in [Task Plan Decomposition Panel](../../experimental/plan-decomposition-panel.md), moved here so the plan and what it produced read together.
+Below the plan sits the accepted-plan history: each accepted revision and the child tasks it created. That's the same **Plan decomposition** view described in [Task Plan Decomposition](../../experimental/plan-decomposition-panel.md), moved here so the plan and what it produced read together.
 
 #### Approving a plan from the panel
 
@@ -458,9 +454,7 @@ References also roll up into **badges** on issue rows and in the sidebar and inb
 
 On the default page, the conversation fills the center column: comments and live agent activity appear together, and completed turns fold down to a summary. **Classic Task Interface** has a separate **Chat** tab for the same task history.
 
-*This screenshot shows the Chat tab in Classic Task Interface.*
-
-![Classic Task Interface Chat tab](../../user-guides/screenshots/light/issues/detail-chat.png)
+![The default task page, with the conversation in the center and the composer at the bottom](../../user-guides/screenshots/light/issues/detail-chat.png)
 
 The task conversation combines four data sources into a single timeline:
 
@@ -509,9 +503,9 @@ This binding is what makes the Chat tab auditable: you can always trace a statem
 
 In **Classic Task Interface**, the **Activity** tab is the chronological system log for the issue. The default task page keeps the conversation in the center; you can inspect individual runs from its folded turns and open the company audit trail for system activity.
 
-*This screenshot shows the Activity tab in Classic Task Interface.*
+*This screenshot shows the Activity tab in Classic Task Interface, which you can turn on under **Legacy** in Experimental settings. The default task page has no Activity tab.*
 
-![Classic Task Interface Activity tab](../../user-guides/screenshots/light/issues/detail-activity.png)
+![The Activity tab in Classic Task Interface](../../user-guides/screenshots/light/issues/detail-activity.png)
 
 The tab assembles three streams:
 
@@ -648,7 +642,7 @@ Issue detail footers now expose a **previous / next** navigator so you can walk
 
 The navigator (`IssueSiblingNavigation`) walks two relationships in order:
 
-1. **Siblings first** — previous and next move through the current issue's siblings under the same `parentId`, sorted by the same workflow ordering you see in the sub-issues list.
+1. **Siblings first** — previous and next move through the current issue's siblings under the same `parentId`, sorted by the same workflow ordering you see in the **Subtasks** list.
 2. **Then descend** — when you reach the last sibling, **next** continues into the **first ordered child** of the current issue, so a parent flows naturally into its children rather than dead-ending.
 
 Two caveats are baked into the ordering:
@@ -663,11 +657,10 @@ The footer also fixes a long-standing race in **issue link quicklooks**: hoverin
 ## A quick mental model
 
 - **Issues page** — every piece of work in the company, with filtering and grouping. Indexed.
-- **Inbox** — human triage. Mine / Recent / Unread / All, with archive and mark-all-read.
-- **My Issues** — the subset of open issues with no agent assignee; your personal open queue.
-- **Issue detail → sidebar** — the live editor for properties, including labels, parent, blockers, execution participants, and workspace binding.
-- **Issue detail → Chat** — conversation, runs, and the composer.
-- **Issue detail → Activity** — read-only system log and cost summary.
+- **Inbox** — human triage. Mine / Recent / Unread / Blocked / All, with archive and mark-all-read. **Mine** is your personal queue.
+- **Task detail → Properties** — the live editor for properties, including labels, parent, blockers, subtasks, execution participants, and workspace binding.
+- **Task detail → conversation** — comments, runs, and the composer.
+- **Classic Task Interface → Activity** — read-only system log and cost summary.
 
 You now know how to create, assign, track, triage, and close issues. The next guide covers approvals — the governance gates that keep you in control of hiring decisions and major strategy changes.
 

docs/guides/day-to-day/work-timeline.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.707.0
+paperclip_version: v2026.1012.0
 seo_title: The Work Timeline
 seo_description: A Gantt-style view of every agent run on one shared time axis: when agents worked, how work passed between them, and where it overlapped.
 ---
@@ -8,6 +8,8 @@ seo_description: A Gantt-style view of every agent run on one shared time axis:
 
 The Work Timeline is a company-scoped page that draws all of your agents' work on one shared time axis: a compact, Gantt-style view of when agents worked, how work passed between them, and where it overlapped. It answers "what did this company actually do over that stretch of time" at a glance, without opening runs one by one.
 
+To open it, click **Audit** in the sidebar and switch to the **Timeline** tab. (Older `/timeline` links still work — they redirect there.)
+
 ## Background
 
 Every run in Paperclip already has a detailed record, and the run view is the right tool for tracing what one agent did during one execution. It is the wrong tool for breadth. A multi-agent company does most of its interesting work in parallel, and much of it while you are not watching. After an overnight batch you might have dozens of runs spread across several agents, and the two things you most want to know, who handed work to whom and what ran at the same time, are exactly what a pile of individual run views cannot show. Handoffs and overlap are relationships between runs; they only become visible when the runs share an axis.
@@ -20,11 +22,11 @@ Think of the page as a Gantt chart drawn after the fact. A planning Gantt shows
 
 Each horizontal lane belongs to one actor — an agent or an automation, labeled with its avatar. (A human isn't given a lane of their own; they appear as the avatar that kicked a piece of work off.) Each bar in a lane is a work period: a stretch of time that actor was executing. The time axis is shared by every lane, and that shared axis is what makes the two signals readable.
 
-![The company Work Timeline: one lane per actor, bars for work periods, overlapping work visible across lanes.](../../user-guides/screenshots/light/work-timeline/work-timeline-overview.png)
+![The Work Timeline on the Timeline tab under Audit: one lane per actor, bars for work periods, overlapping work visible across lanes.](../../user-guides/screenshots/light/work-timeline/work-timeline-overview.png)
 
 A handoff reads across lanes: one actor's bar ends, and at about the same point on the axis a bar begins in another lane. Work stopped in one lane and picked up in another. Where Paperclip can see the delegation, hovering a bar draws a connector line to the bar it handed off to, so a handoff isn't left to visual inference alone.
 
-![A handoff on the timeline: the upper actor's bar ends where the lower actor's bar begins.](../../user-guides/screenshots/light/work-timeline/work-timeline-handoff.png)
+![A handoff on the Audit Timeline tab: the upper actor's bar ends where the lower actor's bar begins.](../../user-guides/screenshots/light/work-timeline/work-timeline-handoff.png)
 
 Overlap reads down the page: bars in different lanes covering the same stretch of the axis. A vertical slice through the chart is your company's parallelism at that moment. Gaps in a lane are time the actor was not executing, and a dense column of parallel bars is a busy stretch.
 
@@ -32,19 +34,19 @@ Overlap reads down the page: bars in different lanes covering the same stretch o
 
 The page is company-scoped: one timeline covers every agent in the company across the window you choose, so cross-agent patterns appear without any assembly on your part. It opens on a rolling seven-day window; a range control (**Today**, **7 days**, **30 days**) plus a custom start and end date let you widen or narrow it, up to a 31-day maximum. Zoom controls and a draggable minimap along the bottom pan and zoom into a busy stretch, and a legend keys the bar colours — delegated work, automation, cancelled runs, and a **Now** marker. The chart is a scrollable SVG built to pan across a long span, not to shrink all of history onto one screen. Behind the page sits a dedicated company endpoint with hardened security filters: it only ever shows work you are authorised to see, and it exists to serve this view.
 
-The timeline is a reading surface, not a replacement for the records underneath it. A bar tells you that an actor was working and for how long, not what the work contained. When a shape on the timeline raises a question, the answer lives in the task thread, the run log, or the Activity Log.
+The timeline is a reading surface, not a replacement for the records underneath it. A bar tells you that an actor was working and for how long, not what the work contained. When a shape on the timeline raises a question, the answer lives in the task thread, the run log, or the activity log on the **Activity** tab.
 
-## Timeline or Activity Log
+## Timeline or Activity
 
-Paperclip already keeps a complete record of everything that has ever happened in a company: the Activity Log, which records every event with a timestamp and the name of whoever caused it. The two views answer different questions.
+Paperclip already keeps a complete record of everything that has ever happened in a company: the **Activity** tab under **Audit**, which records every event with a timestamp and the name of whoever caused it. The two views answer different questions.
 
-The Activity Log is the event ledger. It is ordered and discrete: what happened, one entry per event, in sequence. That makes it the place for accountability and debugging, and a poor place to see duration or simultaneity. You cannot see that two agents worked through the same hour without doing timestamp arithmetic across entries.
+The Activity tab is the event ledger. It is ordered and discrete: what happened, one entry per event, in sequence. That makes it the place for accountability and debugging, and a poor place to see duration or simultaneity. You cannot see that two agents worked through the same hour without doing timestamp arithmetic across entries.
 
 The timeline is the time view: who was working when. It makes duration and simultaneity visible at the cost of event-level detail. Adjacent bars across lanes are a strong cue that work was handed off, but the causal record of that handoff, the comment or status change that moved it, lives in the ledger and the task thread.
 
-In practice the two compose. After an overnight batch or a busy release period, start with the timeline to see the shape of what happened, then drop into the Activity Log or a specific run for the events behind any bar that surprises you. If you are auditing exactly what happened and who did it, the ledger is the record. And if what you want is to follow a single agent live while it executes, that is a different job again; the [Watching Agents Work](../getting-started/watching-agents-work.md) guide covers it.
+In practice the two compose. After an overnight batch or a busy release period, start with the timeline to see the shape of what happened, then switch to the **Activity** tab or open a specific run for the events behind any bar that surprises you. If you are auditing exactly what happened and who did it, the ledger is the record. And if what you want is to follow a single agent live while it executes, that is a different job again; the [Watching Agents Work](../getting-started/watching-agents-work.md) guide covers it.
 
 ## Further reading
 
-- [Activity Log](./activity-log.md), the event ledger: every event in the company, in order, with actor and timestamp.
+- [Audit: Activity](./activity-log.md), the event ledger: every event in the company, in order, with actor and timestamp.
 - [Watching Agents Work](../getting-started/watching-agents-work.md), following a single agent live through an execution cycle.

docs/guides/getting-started/five-minute-path.md

@@ -1,14 +1,14 @@
 ---
 seo_title: Quickstart: Your First Agent in 5 Minutes
 seo_description: Install Paperclip, create a company, hire a CEO agent, and approve its first strategy — a working AI company in about five minutes.
-paperclip_version: v2026.831.1
+paperclip_version: v2026.1012.0
 ---
 
 # Quickstart Path
 
 The shortest route from a running Paperclip instance to an agent that has just completed work for you. After Paperclip is installed, the path takes about 5 minutes: create a company, hire a CEO agent, approve its first strategy, watch tasks land on the board.
 
-![The Paperclip dashboard showing an active CEO agent, a budget bar, and recent activity](../../user-guides/screenshots/light/dashboard/dashboard-overview.png)
+![The Paperclip dashboard showing live agent cards, a budget incident banner, summary cards including Month Spend, and recent activity](../../user-guides/screenshots/light/dashboard/dashboard-overview.png)
 
 ---
 

docs/guides/getting-started/watching-agents-work.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.1005.0
+paperclip_version: v2026.1012.0
 seo_title: Watching Your Agents Work
 seo_description: Turn on the CEO's heartbeat and follow its first execution cycle: read the run transcript, review the strategy, and watch tasks reach the board.
 ---
@@ -27,39 +27,39 @@ The CEO cannot create tasks or assign work until you approve its strategy. This
 
 1. **Enable the CEO's heartbeat**
 
-   Go to the **Agents** page and open the CEO agent's detail page. Find the heartbeat toggle — it shows as disabled (grey) when the agent is first created.
+   Go to the **Agents** page and open the CEO. In the agent's side menu, click **Harness / Runtime** and scroll down to the **Run Policy** card. The **Heartbeat on interval** switch is off when the agent is first created.
 
-   ![The agent detail page with the heartbeat toggle in its disabled state](../../user-guides/screenshots/light/agents/heartbeat-toggle-disabled.png)
+   ![The Run Policy card on the Harness / Runtime page with Heartbeat on interval switched off](../../user-guides/screenshots/light/agents/heartbeat-toggle-disabled.png)
 
-   Click the toggle to enable it.
+   Switch it on, set **Run heartbeat every … sec** (3600 is once an hour), and click **Save changes** at the bottom of the page.
 
-   ![The agent detail page with the heartbeat toggle in its enabled state](../../user-guides/screenshots/light/agents/heartbeat-toggle-enabled.png)
+   ![The Run Policy card with Heartbeat on interval switched on and the interval field showing](../../user-guides/screenshots/light/agents/heartbeat-toggle-enabled.png)
 
-   The CEO is now active. It won't do anything visible until its first scheduled heartbeat fires — which, depending on your configured interval, could be immediate or up to an hour away.
+   The CEO now wakes on a timer. It won't do anything visible until its first scheduled heartbeat fires — which, depending on your interval, could be soon or up to an hour away.
 
-   > **Tip:** If you want the CEO to run right now without waiting for the schedule, click **Run Heartbeat** on the agent detail page. This manually triggers a heartbeat immediately.
+   > **Tip:** If you want the CEO to run right now without waiting for the schedule, click **Run now** in the header of the agent's page. This starts a heartbeat immediately and takes you to the live run.
 
 2. **Wait for the first heartbeat to run**
 
    Once a heartbeat fires, the agent status changes from **idle** to **running**.
 
-   ![The agent detail page showing the CEO in "running" status with a live progress indicator](../../user-guides/screenshots/light/agents/agent-status-running.png)
+   ![The CEO's Overview page showing a Live Run card while a heartbeat is in progress](../../user-guides/screenshots/light/agents/agent-status-running.png)
 
-   You can watch this happen in real time. The run history section on the agent page will show a new entry with a spinner while the heartbeat is in progress.
+   You can watch this happen in real time. On the agent's **Overview**, the top card switches to **Live Run** while the heartbeat is in progress. For the full history, click **Runs** under **Audit** in the agent's side menu — the **Audit** page opens on its **Runs** tab, filtered to the CEO, with the new run at the top.
 
-   ![The run history section showing a heartbeat in progress](../../user-guides/screenshots/light/agents/run-history-in-progress.png)
+   ![The Audit page's Runs tab filtered to the CEO, with a run in progress at the top](../../user-guides/screenshots/light/agents/run-history-in-progress.png)
 
    The first heartbeat typically takes a few minutes to complete — the CEO is reading your goal, reasoning about strategy, and composing a proposal. Subsequent heartbeats on routine tasks are usually faster.
 
-   When the heartbeat finishes, the agent status returns to **idle** and the run history entry shows as complete.
+   When the heartbeat finishes, the agent status returns to **idle** and the run shows as **succeeded** (or **failed**, if something went wrong).
 
 3. **Review the CEO's strategy**
 
    After its first heartbeat, the CEO almost always creates a strategy approval. Open the **Approvals** page from the dashboard, a direct link, or any approval-related prompt in the app.
 
-   You'll see a pending approval with the type **Strategy**.
+   You'll see a pending approval labelled **CEO Strategy**.
 
-   ![The approvals queue showing a pending strategy approval from the CEO](../../user-guides/screenshots/light/approvals/approvals-queue-strategy.png)
+   ![The Approvals page's Pending tab with a pending CEO Strategy approval in the queue](../../user-guides/screenshots/light/approvals/approvals-queue-strategy.png)
 
    Click the approval to open it.
 
@@ -89,7 +89,7 @@ The CEO cannot create tasks or assign work until you approve its strategy. This
 
 5. **Watch tasks appear**
 
-   Once the strategy is approved, the CEO starts creating work on the board. Navigate to **Issues** in the sidebar.
+   Once the strategy is approved, the CEO starts creating work on the board. Click **Tasks** in the sidebar.
 
    ![The task inbox showing newly created tasks from the CEO's first planning heartbeat](../../user-guides/screenshots/light/tasks/inbox-newly-created-tasks.png)
 
@@ -98,25 +98,24 @@ The CEO cannot create tasks or assign work until you approve its strategy. This
    Each task will have:
    - A title describing the work
    - A description with more detail
-   - A priority level
    - A status
-   - A comment thread (which starts empty, but fills up as the agent works)
+   - A conversation (which starts empty, but fills up as the agent works)
 
-6. **Read a task's comment thread**
+6. **Follow a task's conversation**
 
-   Open any task that the CEO has moved to `in_progress`. Scroll down to the **Comments** section.
+   Open any task that the CEO has moved to `in_progress`. The task page is a conversation: the agent's updates and your messages run down the middle, with the task's properties (status, assignee, project, and so on) in a panel on the right.
 
-   ![A task detail page showing the comment thread with the CEO's working notes](../../user-guides/screenshots/light/tasks/task-detail-with-comments.png)
+   ![A task page showing the conversation between you and the agent, with the Properties panel on the right](../../user-guides/screenshots/light/tasks/task-detail-with-comments.png)
 
-   Agents post comments as they work — explaining what they're doing, what decisions they made, and what they found. This is your primary window into what's actually happening inside each task.
+   Agents post updates as they work — explaining what they're doing, what decisions they made, and what they found. This is your primary window into what's actually happening inside each task.
 
-   You can post your own comments here too. Your comment reaches the agent the task is assigned to, so this is how you give direct feedback or ask questions without waiting for the next scheduled heartbeat. @-mentioning a different agent (e.g. `@CEO`) only adds context — it doesn't start a run. To bring another agent in, assign the task to them or request their review.
+   You can reply too, using the message box at the bottom ("Message CEO — describe what you want done…"). Your message reaches the agent the task is assigned to, so this is how you give direct feedback or ask questions without waiting for the next scheduled heartbeat. @-mentioning a different agent (e.g. `@CEO`) only adds context — it doesn't start a run. To bring another agent in, assign the task to them or request their review.
 
 ---
 
 ## Reading the run transcript
 
-For a deeper look at what happened during any heartbeat, go to the **Agents** page, open the CEO, and click **Runs**. Click any completed run to open the transcript.
+For a deeper look at what happened during any heartbeat, go to the **Agents** page, open the CEO, and click **Runs** under **Audit** in its side menu. Click any completed run to open the transcript.
 
 ![The run transcript view showing the full log of what the CEO did during a single heartbeat](../../user-guides/screenshots/light/agents/run-transcript-view.png)
 
@@ -130,7 +129,7 @@ The following situations come up frequently in a company's first few hours. Here
 
 **No strategy approval appeared after the first heartbeat**
 
-First, check the **Approvals** page — it may be there but not visible from where you're looking. If it's genuinely not there, go to **Agents → CEO → Runs** and open the most recent run. The transcript will show whether the heartbeat completed successfully or encountered an error.
+First, check the **Approvals** page — it may be there but not visible from where you're looking. If it's genuinely not there, open the CEO and click **Runs** under **Audit** in its side menu, then open the most recent run. The transcript will show whether the heartbeat completed successfully or encountered an error.
 
 **The CEO assigned all tasks to itself**
 
@@ -138,13 +137,13 @@ This is correct behaviour when the CEO has no reports yet. It can't delegate to
 
 **The agent is stuck in "running" for more than 30 minutes**
 
-A heartbeat that takes longer than expected is usually caused by one of three things: the task is complex, the agent has hit a loop, or the API is slow. Check the **Runs** tab to see if there's a live transcript updating. If the transcript has stopped updating, the run may have stalled. In that case, you can manually stop it from the agent detail page.
+A heartbeat that takes longer than expected is usually caused by one of three things: the task is complex, the agent has hit a loop, or the API is slow. Open the run (click the **Live Run** card on the agent's **Overview**) to see if the transcript is still updating. If it has stopped updating, the run may have stalled. In that case, click **Cancel** in the run's header to stop it.
 
 **Agent status shows "error"**
 
-Open **Runs** and click the failed run. The transcript will show the error message. Common causes are an expired API key, an invalid model name, or a file permission issue in the working directory.
+Open the agent's **Runs** (under **Audit** in its side menu) and click the failed run. The transcript will show the error message. Common causes are an expired API key, an invalid model name, or a file permission issue in the working directory.
 
-> **Warning:** An agent in "error" status won't fire new heartbeats until the underlying issue is resolved. Check and fix the error, then click **Resume** on the agent detail page to restart it.
+> **Warning:** An agent in "error" status won't fire new heartbeats until the underlying issue is resolved. Check and fix the error, then click **Clear error** in the header of the agent's page to return it to idle.
 
 ---
 

docs/guides/getting-started/your-first-agent.md

@@ -1,4 +1,5 @@
 ---
+paperclip_version: v2026.1012.0
 seo_title: Hire Your First Agent
 seo_description: An agent is a role, an AI system, a budget, and a set of wake-up rules. Choose each when hiring, plus fixes for the snags that trip people up.
 ---
@@ -17,8 +18,8 @@ The CEO is always the first agent you create. It has a special role: reading the
 
 You'll need:
 - A company already created (see [Create Your First Company](./your-first-company.md))
-- An API key from Anthropic (for the `claude_local` adapter) or OpenAI (for `codex_local`) — see the [Installation guide](./installation.md) for how to get one
-- **For `claude_local`:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed on your Mac
+- A way to pay for the AI: a Claude or ChatGPT subscription you can sign in with, or an API key from Anthropic (for Claude Code) or OpenAI (for Codex) — see the [Installation guide](./installation.md) for how to get one
+- **For Claude Code:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed on your Mac
 
 ---
 
@@ -28,99 +29,93 @@ You'll need:
 
    ![The empty agents list with a New Agent button](../../user-guides/screenshots/light/agents/agents-list-empty.png)
 
-2. **Set the agent's name**
+2. **Name your agent**
 
-   Give the agent a name (e.g. "CEO"). If this is your first agent, Paperclip automatically makes it the **CEO**.
+   A dialog titled **Meet your next agent** opens. It has two short steps — **1. Name** and **2. Adapter** — shown at the top.
 
-   ![The new agent form showing the Name and Role fields filled in for a CEO agent](../../user-guides/screenshots/light/agents/new-agent-name-role.png)
+   Type a name in **Agent name** (e.g. "CEO") and click **Choose adapter**.
 
-   The **CEO role** is special: it has no "Reports To" field, because the CEO reports directly to the board — to you. Every other agent you hire later will have a "Reports To" field where you (or the CEO) assigns a manager.
+   ![The "Meet your next agent" dialog with the Agent name field](../../user-guides/screenshots/light/agents/new-agent-name-role.png)
+
+   There's no role to pick. The first agent in a company is always the **CEO**, and Paperclip sets that for you. The CEO reports directly to the board — to you. Agents you hire later start with a general role and report to the CEO; you can change both afterwards on each agent's **Harness / Runtime** page.
 
 3. **Choose an adapter**
 
-   An adapter tells Paperclip how to run your agent. Click the **Adapter Type** dropdown to see your options.
+   An adapter tells Paperclip how to run your agent. The dialog now asks **Choose an adapter**, with one card per adapter. Pick one and click **Configure agent**.
 
-   ![The adapter type dropdown showing available adapter options](../../user-guides/screenshots/light/agents/adapter-type-dropdown.png)
+   ![Step 2 of the new agent dialog, "Choose an adapter", with a card for each available adapter](../../user-guides/screenshots/light/agents/adapter-type-dropdown.png)
 
    <!-- tabs: Claude Code (Recommended), Codex -->
 
    <!-- tab: Claude Code (Recommended) -->
 
-   **Claude Code** runs a Claude Code agent directly on your Mac. The agent has full access to your filesystem in its working directory, can run terminal commands, write and edit files, and call the Claude API on your behalf.
+   **Claude Code** runs a Claude Code agent directly on your Mac. The agent can work with files in its workspace, run terminal commands, write and edit code, and call Claude on your behalf.
 
    This is the most capable and most commonly used adapter for Paperclip agents.
 
    **Prerequisites:** Claude Code must be installed on your Mac. If you haven't installed it, follow the [Claude Code installation guide](https://docs.anthropic.com/en/docs/claude-code) — it's a separate Anthropic product. Come back here once it's installed.
 
-   **Configuration fields:**
-
-   ![The Claude Code adapter configuration form with all fields filled in](../../user-guides/screenshots/light/agents/claude-local-config-filled.png)
-
-   - **Working directory** — The folder on your Mac where the agent will do its work. This is where files get created, edited, and read. If you're not sure what to use, create a folder called `paperclip-workspace` on your Desktop and paste that path here (e.g. `/Users/yourname/Desktop/paperclip-workspace`).
-
-   - **Model** — Which Claude model powers this agent. `claude-opus-4-6` is the most capable and best for strategic roles like the CEO. `claude-sonnet-4-6` is faster and cheaper, and works well for more routine tasks.
-
-   - **Environment variables** — Add `ANTHROPIC_API_KEY` and either paste the key as a plain value or store it as a Paperclip secret. This is how the adapter gets access to Claude.
-
-   - **Test environment** — Use this button to confirm Paperclip can see Claude Code and that your `ANTHROPIC_API_KEY` binding works before you create the agent.
-
-   > **Tip:** If you're unsure about the working directory, create a new folder called `paperclip-workspace` on your Desktop. Use that path until you decide on a better home for your agents' work.
-
    <!-- tab: Codex -->
 
-   **Codex** runs an OpenAI Codex agent directly on your Mac. Like `claude_local`, it has access to your filesystem and can run commands within its working directory — but it's powered by OpenAI's models rather than Anthropic's.
+   **Codex** runs an OpenAI Codex agent directly on your Mac. Like Claude Code, it can work with files and run commands in its workspace — but it's powered by OpenAI's models rather than Anthropic's.
 
    **Prerequisites:** You'll need the OpenAI Codex CLI installed. Check the [OpenAI documentation](https://platform.openai.com) for installation instructions.
 
-   **Configuration fields:**
-
-   - **Working directory** — The folder on your Mac where the agent will do its work. Create a folder called `paperclip-workspace` on your Desktop if you don't have a preferred location.
-
-   - **Model** — Which OpenAI model to use. `gpt-5.3-codex` is the default and a sensible starting point for a CEO agent.
-
-   - **Environment variables** — Add `OPENAI_API_KEY` and either paste the key as a plain value or store it as a Paperclip secret.
-
-   - **Test environment** — Use this button to verify the adapter can see your OpenAI key binding before you create the agent.
-
    <!-- /tabs -->
 
-4. **Configure the heartbeat interval**
+4. **Connect your model provider**
 
-   The create form's run policy is deliberately simple: you can decide whether this agent runs on an interval, and how often.
+   After the dialog closes, you land on a setup page with your agent's (still sleepy) character at the top and the steps down the left: **Connect**, **Configure**, and **Confirmation**.
 
-   ![The budget and heartbeat configuration fields for the new agent](../../user-guides/screenshots/light/agents/budget-and-heartbeat-fields.png)
+   On **Connect**, pick the **Environment** the agent runs in (the default is fine to start with), then connect Claude or OpenAI — either sign in with your subscription or provide an API key. Paperclip stores a key you enter as a secret, so it never sits in plain text in the agent's settings.
 
-   For a CEO, once per hour is a reasonable starting cadence. You can make it faster later once the company is active and you have a feel for the cost.
+5. **Configure and test**
 
-   > **Tip:** Don't set the interval too short early on. Every heartbeat costs money. For a CEO, once per hour is a good starting point. You can increase frequency later once you understand your company's rhythm.
+   On **Configure**, choose the **Model** that powers this agent. For Claude Code, `claude-opus-4-6` is the most capable and best for strategic roles like the CEO; `claude-sonnet-4-6` is faster and cheaper for routine work. For Codex, the default model is a sensible starting point. Some adapters also offer a **Thinking effort** setting — leave it on **Auto** if you're not sure.
 
-5. **Create the agent**
+   ![A Claude Code agent's Harness / Runtime page showing the Adapter card with Model and Thinking effort](../../user-guides/screenshots/light/agents/claude-local-config-filled.png)
 
-   Click **Create agent**. Paperclip creates the agent and takes you to the agent detail page. You should see the agent with a status of **idle** — meaning it's configured and ready, but hasn't fired a heartbeat yet.
+   *The screenshot shows the same Model and Thinking effort settings on an existing agent's **Harness / Runtime** page — that's where you change them after setup.*
 
-   ![The agent detail page showing the CEO agent in idle status](../../user-guides/screenshots/light/agents/agent-detail-idle.png)
+   At the bottom, the **Test your agent** card checks that your runtime and model can respond. Click **Run test**. When it says **Connection successful**, you're good to go.
 
-   The heartbeat is disabled by default when you first create an agent. You'll enable it in the next guide, once you're ready to let the CEO start working.
+6. **Finish setup**
 
-6. **Set the budget after creation**
+   Click **Finish setup**. Paperclip creates the agent and shows **Your agent is ready**, with the adapter, model, and environment it'll use.
 
-   Budgets are configured after the agent exists. Open the agent's **Budget** tab and set a monthly cap that fits the role.
+   From here, click **Edit configuration** to open the agent's settings, or **Assign CEO a Task** (the button uses your agent's name) to give it its first job. You can also open the agent from the **Agents** list. You should see it with a status of **idle** — configured and ready, but it hasn't run a heartbeat yet.
+
+   ![An agent's Overview page in idle status](../../user-guides/screenshots/light/agents/agent-detail-idle.png)
+
+7. **Decide on a heartbeat schedule**
+
+   New agents start with their timed heartbeat switched off. They still wake when you give them work or click **Run now** — they just don't wake on a timer. You'll turn the timer on in the next guide, once you're ready to let the CEO start working.
+
+   The setting lives in the **Run Policy** card on the agent's **Harness / Runtime** page: switch on **Heartbeat on interval** and set **Run heartbeat every … sec**.
+
+   ![The Run Policy card on the Harness / Runtime page with the Heartbeat on interval switch](../../user-guides/screenshots/light/agents/budget-and-heartbeat-fields.png)
+
+   > **Tip:** Don't set the interval too short early on. Every heartbeat costs money. For a CEO, once per hour (3600 seconds) is a good starting point. You can make it faster later once you understand your company's rhythm.
+
+8. **Think about a budget**
+
+   The setup flow doesn't set a spending cap. Once the agent has a budget policy, you manage it from **Audit → Budgets**; to create one, use the CLI or API (see [Agents: Budgets](../org/agents.md#budgets)). [Costs & budgets](../day-to-day/costs.md) explains how agent and company budgets work together.
 
    > **Warning:** The CEO is typically the most active agent — it runs on every heartbeat and does more complex reasoning than worker agents. Budget it slightly higher than you would a worker. $30–50 per month is a reasonable starting point for a CEO. You can always adjust this later.
 
-   Remember: this agent budget is separate from the company budget. Both apply — if either limit is reached, the agent pauses.
+   Remember: an agent budget is separate from the company budget. Both apply — if either limit is reached, the agent pauses.
 
-7. **Test the environment again if needed**
+9. **Test again if needed**
 
-   Before enabling the CEO's heartbeat, you can verify that the adapter is configured correctly. On the agent detail page, click **Test environment**.
+   You can re-run the check any time. Open the agent, go to **Harness / Runtime**, and scroll to the **Test your agent** card at the bottom. Click **Run test** (or **Test again** if you've tested before).
 
-   Paperclip will attempt to connect to the adapter — in the case of `claude_local`, it will check that Claude Code is installed and accessible, and that the environment variable binding is valid.
+   Paperclip checks the runtime — for Claude Code, that Claude Code is installed and reachable and that your connection works — and waits for the model to respond.
 
-   ![The test environment result showing a success state](../../user-guides/screenshots/light/agents/test-environment-success.png)
+   ![The Test your agent card showing Connection successful](../../user-guides/screenshots/light/agents/test-environment-success.png)
 
-   If the test succeeds, you're ready. If it fails:
+   If the test succeeds, you're ready. If it fails, the card says **Couldn't connect** or **Connection needs attention**, with details underneath:
 
-   ![The test environment result showing a failure with an error message](../../user-guides/screenshots/light/agents/test-environment-fail.png)
+   ![The Test your agent card showing a failed connection with an error message](../../user-guides/screenshots/light/agents/test-environment-fail.png)
 
    See the troubleshooting section below.
 
@@ -128,15 +123,15 @@ You'll need:
 
 ## Troubleshooting
 
-**"Test Environment" fails**
+**"Test your agent" fails**
 
 The two most common causes:
-- The environment variable binding is wrong — double-check that you've set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`, and that the value itself is correct with no extra spaces.
+- The provider connection is wrong — double-check the API key you entered (no extra spaces) or sign in to your subscription again. On an existing agent, the key is set as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` under **Environment variables** on **Harness / Runtime**.
 - Claude Code isn't installed, or isn't at the path Paperclip expects — confirm you can open Claude Code from your Mac independently of Paperclip.
 
 **Agent shows "error" status after its first heartbeat**
 
-Open the **Runs** tab on the agent detail page, then click the most recent run. You'll see a full transcript of what happened. Error messages in the transcript will point to what went wrong.
+On the agent's page, click **Runs** under **Audit** in the side menu. That opens the **Audit** page's **Runs** list filtered to this agent; click the most recent run. You'll see a full transcript of what happened. Error messages in the transcript will point to what went wrong.
 
 **Budget immediately shows near 100%**
 

docs/guides/getting-started/your-first-company.md

@@ -1,7 +1,7 @@
 ---
 seo_title: Create Your First Company
 seo_description: A company holds your goal, your agents, your task board, and your budget. Set one up before hiring, and learn when running more than one makes sense.
-paperclip_version: v2026.831.1
+paperclip_version: v2026.1012.0
 ---
 
 # Create Your First Company
@@ -22,9 +22,9 @@ Make sure Paperclip is installed and running. If you haven't done that yet, star
 
 1. **Open the setup wizard**
 
-   When you first open Paperclip, it drops you straight into the setup wizard. If you're adding another one later, open the organization switcher at the top of the sidebar and choose **Create new organization…**.
+   When you first open Paperclip, it drops you straight into the setup wizard. If you're adding another one later, open the organization switcher at the top of the sidebar and choose **Create organization**.
 
-   ![The sidebar organization switcher with the Create new organization option highlighted](../../user-guides/screenshots/light/onboarding/sidebar-new-company-button.png)
+   ![The sidebar organization switcher open, listing your organizations with the Create organization option below them](../../user-guides/screenshots/light/onboarding/sidebar-new-company-button.png)
 
    > **Heads up:** In the app, a company is now labelled an **organization** — same container, newer name. This guide says "company" to match the rest of the docs; the buttons you click say "organization".
 

docs/guides/org/adapters.md

@@ -1,4 +1,5 @@
 ---
+paperclip_version: v2026.1012.0
 seo_title: The Adapter Manager
 seo_description: Enable, disable, configure, reload, and remove adapters. Covers the built-in set plus installing external adapters to extend which runtimes you can use.
 ---
@@ -125,11 +126,11 @@ Built-in rows never show the trash icon. They cannot be removed.
 
 The Adapter Manager itself does **not** hold configuration for a specific adapter. Adapter config lives on each _agent_ that uses the adapter: working directory, model selection, timeouts, environment variables, and whatever extra fields the adapter declares through its UI schema.
 
-To configure a built-in adapter, open the agent you want to change and edit its adapter config on the agent form.
+To configure a built-in adapter, open the agent you want to change, click **Harness / Runtime** in its side menu, and edit the **Adapter** and **Configuration** cards. Click **Save changes** when you're done.
 
-To configure an external adapter, the same pattern applies — the Agent Manager renders the form fields the external adapter's `createServerAdapter()` reports through its UI schema, including any custom widgets the adapter ships.
+To configure an external adapter, the same pattern applies — the agent's **Harness / Runtime** page renders the form fields the external adapter's `createServerAdapter()` reports through its UI schema, including any custom widgets the adapter ships.
 
-![Adapter configuration](../../user-guides/screenshots/light/adapters/detail.png)
+![The Adapter and Configuration cards on an agent's Harness / Runtime page, where per-agent adapter settings live](../../user-guides/screenshots/light/adapters/detail.png)
 
 For field-by-field walkthroughs of the common built-ins, see [Agent Adapters](./agent-adapters.md). For the technical contract that adapters implement (including the UI parser schema), see [Adapter UI Parser](../../reference/adapters/adapter-ui-parser.md).
 
@@ -139,9 +140,9 @@ For field-by-field walkthroughs of the common built-ins, see [Agent Adapters](./
 
 Adapters are simpler than plugins — there's no background worker, no scheduled jobs, and no long-running state to go wrong. "Health" for an adapter mostly comes down to: _did the module load, and does it report any models?_
 
-![Health status](../../user-guides/screenshots/light/adapters/health.png)
+![The Built-in Adapters list, with each row's meta line showing the adapter type and model count](../../user-guides/screenshots/light/adapters/health.png)
 
-The row meta line (`type · package · N models`) is your first signal:
+The meta line under each row's name is your first signal. It shows the adapter `type` and how many models it reports — for example `claude_local · 13 models`. External adapters whose npm package name differs from their type also show the package in between (`type · package · N models`).
 
 - **`0 models`** on a model-listing adapter usually means the adapter loaded but couldn't reach its provider (missing API key, offline, auth failure). Check the agent's environment variables and the provider's status page.
 - **Row missing after install** — the install failed. Reopen the install dialog; the error toast will have explained why (invalid package, manifest missing, `createServerAdapter()` not exported).

docs/guides/org/agent-adapters.md

@@ -30,7 +30,7 @@ Without an adapter, an agent is just a record in a database. With one, it's a wo
 
 For most people getting started, **`claude_local`** is the right choice. It runs directly on your Mac using the same Claude that powers Anthropic's Claude.ai, and it only needs Claude Code plus an API key wired through environment variables.
 
-![Adapter type dropdown showing all available options](../../user-guides/screenshots/light/agents/adapter-type-dropdown.png)
+![Step 2 of the new agent dialog, "Choose an adapter", with a card for each available adapter](../../user-guides/screenshots/light/agents/adapter-type-dropdown.png)
 
 > **Note:** On Paperclip Cloud, the new-agent picker offers Claude, Codex, OpenCode, and Grok. Grok agents connect with an xAI subscription or API key during setup.
 
@@ -60,7 +60,7 @@ You can dial this back per agent in the adapter's configuration. Each adapter re
 
 The `claude_local` adapter runs your agent using Claude Code — Anthropic's command-line AI tool — directly on your Mac. When Paperclip triggers a heartbeat, it launches Claude Code with the agent's context and task, waits for the run to complete, and reads back what Claude did.
 
-**What it means in practice:** Your agent thinks like Claude, can read and write files on your computer, browse the web, and run terminal commands — all within the working directory you specify. It's capable of doing real coding work, writing documents, doing research, and more.
+**What it means in practice:** Your agent thinks like Claude, can read and write files on your computer, browse the web, and run terminal commands — all within the workspace of the task it's working on. It's capable of doing real coding work, writing documents, doing research, and more.
 
 ### Prerequisites
 
@@ -69,10 +69,8 @@ The `claude_local` adapter runs your agent using Claude Code — Anthropic's com
 
 ### Configuration fields
 
-**Working directory**
-The folder on your Mac where the agent does its work — reads files, writes outputs, runs commands. If you're using this agent for a software project, point this to your project folder. If you're not sure, create a new folder called `paperclip-workspace` on your Desktop and use that.
-
-> **Tip:** Give each agent its own working directory if they're doing different kinds of work. Shared directories can lead to agents accidentally overwriting each other's files.
+**Working directory (deprecated)**
+You won't see this field when you create a new agent. It only appears when you edit an older local agent that already has a working directory saved, and it's there as a legacy fallback. New agents get their folder from the task's project workspace instead, so set up a [project workspace](../projects-workflow/workspaces.md) rather than pointing each agent at a folder. If an older agent still shows the field, you can leave it as it is or clear it once the agent's work lives in a project.
 
 **Model**
 Which Claude model to use. If you leave it blank, Paperclip uses `claude-opus-5`. Some common choices:
@@ -84,14 +82,14 @@ When in doubt, start with Sonnet for workers and Opus for the CEO. The **effort*
 **Environment variables**
 The agent form includes an **Environment variables** section. Add `ANTHROPIC_API_KEY` there, either as a plain value or as a secret reference. If you're not sure what key name to use, `ANTHROPIC_API_KEY` is the standard one.
 
-**Timeout (seconds)**
-How long a single heartbeat run is allowed to take before Paperclip cuts it off. 300 seconds (5 minutes) is a safe default for most tasks. Complex coding tasks may need longer — you can increase it to 600 or more. Setting it too low will cause agents to time out mid-task.
+**Timeout (sec)**
+How long a single heartbeat run is allowed to take before Paperclip cuts it off. You'll find it on an existing agent's **Harness / Runtime** page under **Run Policy → Advanced Run Policy**. It starts at `0`, which means no timeout. If you set one, leave plenty of headroom — complex coding tasks can run for 10 minutes or more, and a limit that's too low cuts agents off mid-task.
 
-![Claude local adapter configuration form with all fields filled in](../../user-guides/screenshots/light/agents/claude-local-config-filled.png)
+![The Adapter card on an agent's Harness / Runtime page, showing the Claude Code adapter type, Model, and Thinking effort, with the top of the Configuration card below](../../user-guides/screenshots/light/agents/claude-local-config-filled.png)
 
 ### Common errors
 
-**"Claude Code not found"** — Claude Code isn't installed, or isn't on the system PATH. Install it from [claude.ai/code](https://claude.ai/code) and then use the Test Environment button to verify Paperclip can find it.
+**"Claude Code not found"** — Claude Code isn't installed, or isn't on the system PATH. Install it from [claude.ai/code](https://claude.ai/code) and then click **Run test** in the **Test your agent** card (at the bottom of the agent's **Harness / Runtime** page) to verify Paperclip can find it.
 
 **"API key invalid"** — Check that the environment variable name matches exactly what you've configured, and that the key itself starts with `sk-ant-`. Anthropic keys are case-sensitive.
 
@@ -110,7 +108,7 @@ The `codex_local` adapter runs your agent using OpenAI's Codex CLI on your Mac.
 
 ### Configuration fields
 
-The fields are the same as `claude_local` — mainly model selection and environment variables — but pointing to OpenAI instead of Anthropic.
+The fields are the same as `claude_local` — mainly model selection and environment variables — but pointing to OpenAI instead of Anthropic. As with Claude Code, **Working directory (deprecated)** only appears when you edit an older agent that already has one saved.
 
 **Model** examples for Codex:
 - `gpt-5.6-sol` — the default and the normal starting point
@@ -156,16 +154,16 @@ The `http` adapter connects to a web server or cloud function that you control.
 
 ### Configuration fields
 
-**Endpoint URL**
-The full URL Paperclip will POST to when a heartbeat fires. This must be publicly accessible or reachable from your Paperclip instance.
+**Webhook URL** (`url`)
+The full URL Paperclip will call when a heartbeat fires. This must be publicly accessible or reachable from your Paperclip instance. It's the one HTTP-specific field shown in the **Configuration** card on the agent's **Harness / Runtime** page.
 
-**Authentication**
-A secret token that Paperclip includes in the request header, so your server can verify the call came from Paperclip and not someone else.
+**Headers** (`headers`)
+Extra request headers — typically a secret token, so your server can verify the call came from Paperclip and not someone else. Set this in the adapter config through the API or a company export; the form doesn't show it.
 
-**Timeout**
-How long Paperclip waits for a response before treating the heartbeat as failed.
+**Timeout** (`timeoutMs`)
+How long Paperclip waits for a response, in milliseconds, before treating the heartbeat as failed. Also set through the API or a company export.
 
-![HTTP adapter configuration form](../../user-guides/screenshots/light/agents/http-adapter-config.png)
+![The Harness / Runtime page for an agent using the HTTP adapter, with HTTP selected under Adapter type](../../user-guides/screenshots/light/agents/http-adapter-config.png)
 
 > **Note:** The HTTP adapter is aimed at developers building custom agent integrations. If you're using a standard AI provider locally, `claude_local` or `codex_local` is the simpler choice.
 

docs/guides/org/agents.md

@@ -1,7 +1,7 @@
 ---
 paperclip_version: v2026.1012.0
 seo_title: Agents: Your AI Employees
-seo_description: Hire agents, browse the agent list, and work the detail page — dashboard, instructions, and references — for the AI employees doing your company's work.
+seo_description: Hire agents, browse the agent list, and work the agent page — overview, instructions, harness and runtime — for the AI employees doing your company's work.
 ---
 
 # Agents
@@ -10,7 +10,7 @@ Agents are the AI employees that make up your Paperclip company. They're where t
 
 Agents in Paperclip are AI employees that wake up, do work, and go back to sleep. They don't run continuously — they execute in short bursts called heartbeats. Between heartbeats the agent is dormant: it consumes no budget, holds no context in memory, and takes no action. A heartbeat is triggered by something concrete (a schedule, an assignment, a review request, a manual invoke), the adapter brings the agent runtime online just long enough to make progress, and then the agent exits and the adapter records what happened.
 
-This guide walks through the entire agent surface in Paperclip: the list page you land on when you click **Agents**, the flow for hiring a new one, and every tab on the agent detail page. If you're new to Paperclip, read this top to bottom. If you're here to change one specific thing — a budget limit, a model, an instruction file — jump to the matching tab section.
+This guide walks through the entire agent surface in Paperclip: the list page you land on when you click **Agents**, the flow for hiring a new one, and every section of the agent's own page. If you're new to Paperclip, read this top to bottom. If you're here to change one specific thing — a model, an instruction file, a budget limit — jump to the matching section.
 
 ---
 
@@ -22,38 +22,39 @@ The agent list is the front door. Open **Agents** in the sidebar and you land on
 
 ### Filter tabs
 
-Four tabs across the top scope what you see:
+Tabs across the top scope what you see:
 
-- **All** — every agent in the company (minus terminated ones, unless you opt in)
+- **All** — every agent in the company
 - **Active** — agents currently able to run; includes `active`, `running`, and `idle`
 - **Paused** — agents that are manually paused or paused by the budget system
 - **Error** — agents whose last heartbeat failed
+- **Built-in** — Paperclip's managed built-in agents (only shown when built-in agents are turned on for your instance)
 
 The tab you're on is part of the URL (`/agents/active`, `/agents/paused`, etc.), so you can bookmark a filter or share a link that lands on one.
 
-### Terminated agents
+### Terminated and pending agents
 
-Terminated agents are hidden by default. Click the **Filters** control on the right of the tab bar and check **Show terminated** to include them. The count badge next to the button tells you at a glance when this filter is active.
+Terminated agents don't appear in the list at all, and neither do agents still waiting for hire approval. A pending hire lives in its approval thread until you decide on it — see [Approvals](../day-to-day/approvals.md).
 
 ### List view vs org chart view
 
-On desktop you can toggle between two visual layouts:
+Two small icon buttons next to **New Agent** switch between layouts:
 
 - **List view** — a flat sorted list, one row per agent
-- **Org chart view** — a hierarchical tree that mirrors the reporting chain (the CEO at the top, their direct reports indented under them, and so on)
+- **Org chart view** — a hierarchical tree that mirrors the reporting chain (the CEO at the top, their direct reports under them, and so on)
 
-On mobile, the list is forced — there's no room for the tree. The view preference is kept across page reloads.
+The org chart lives here now — there's no separate Org page. See [Org structure](./org-structure.md) for how to read it.
 
 ### What each row shows
 
 Every agent row shows the same pieces of information, just arranged differently in the two views:
 
-- **Status dot** on the far left, colour-coded by status (green for active, blue for running, amber for paused, red for error, grey for terminated)
-- **Name and role** (e.g. "Ada — Backend Engineer")
+- **Character** on the far left — the agent's illustrated figure (an amber warning icon replaces it if the agent's reporting chain is broken)
+- **Name, role, and title** (e.g. "Ada" with "Engineer - Backend Engineer" underneath)
 - **Live run pill** — a pulsing blue "Live" badge when the agent has a run currently in flight; click it to jump straight into the live transcript
-- **Adapter label** — which AI runtime powers this agent (Claude, Codex, Cursor, Gemini, OpenCode, OpenClaw)
+- **Model and adapter** — the model the agent runs and which AI runtime powers it (shown on wider screens)
 - **Last heartbeat** — a relative time like "4m ago"
-- **Status badge** — a readable version of the status dot
+- **Status badge** — the agent's current status, such as `idle`, `running`, or `paused`
 
 Clicking anywhere on the row opens the agent's detail page. Clicking the live pill opens the run directly.
 
@@ -72,51 +73,50 @@ Paperclip has two paths for adding an agent to the company:
 1. You (a board user) create one directly from **New Agent** on the agent list.
 2. An existing agent (typically the CEO or a manager) proposes a hire, which lands in your approval queue. See [Approvals](../day-to-day/approvals.md) for how that side works.
 
-This section is about the direct path — the `New Agent` form.
+This section is about the direct path — clicking **New Agent** yourself.
 
-![Hire a new agent](../../user-guides/screenshots/light/agents/new.png)
+![The "Meet your next agent" dialog, step 1 of 2, asking for the agent's name](../../user-guides/screenshots/light/agents/new.png)
 
-### Name and title
+### Step 1: Name
 
-The first two fields at the top of the form:
+Clicking **New Agent** opens a short dialog titled **Meet your next agent**. A progress line at the top shows the two steps: **1. Name** and **2. Adapter**.
 
-- **Agent name** (required) — the display name, e.g. "Ada" or "CTO"
-- **Title** (optional) — a role label that appears in the subtitle, e.g. "VP of Engineering"
+Type the new agent's name in **Agent name** (for example "Ada") and click **Choose adapter**. That's the only thing this step asks for.
 
-If this is the first agent in the company, Paperclip pre-fills both fields with "CEO" to make the CEO-first flow frictionless.
+### Step 2: Adapter
 
-### Role and reporting chain
+The dialog switches to **Choose an adapter** and asks how your agent should work. Pick one of the adapter cards — this decides which AI runtime powers the agent (Claude Code, Codex, OpenCode, a remote gateway, and so on). If you pick Paperclip Runner, a **Runner** dropdown appears so you can choose which runtime it drives.
 
-Two chips beneath the name row let you set governance context:
-
-- **Role** — one of Paperclip's built-in roles (CEO, CTO, manager, general, worker, etc.). When you're hiring the first agent, this field is locked to `CEO` and you cannot change it — the very first hire in a company is always the CEO. Subsequent hires default to `general` and you can pick a different role from the popover.
-- **Reports to** — picks the manager this agent will report to. Disabled on the first hire (the CEO reports to you). Used by the org chart on the agent list and by the escalation chain agents follow when they're blocked.
-
-### Adapter and configuration
-
-Below the chips, the shared agent configuration form takes over. This is the same form you'll see on the **Configuration** tab later, which means everything you set here can be edited after the agent exists.
-
-The adapter picker is the most important decision at hire time. Your choice controls:
-
-- Which AI runtime powers the agent (Claude Code, Codex local, Cursor, Gemini, OpenCode, OpenClaw gateway)
-- Which models you can pick from
-- Which adapter-specific options show up (sandbox bypass flags, model-provider formats, session handling)
-
-When you change the adapter type, Paperclip resets the form to that adapter's defaults — for example, switching to `codex_local` pre-selects the default Codex model and sets the sandbox/approvals bypass to its recommended default. For OpenCode, you must pick an explicit model in `provider/model` format; Paperclip fetches the available list from your OpenCode installation and validates the choice before letting you submit.
+Click **Configure agent** to move on, or **Back** to change the name.
 
 See [Agent adapters](./agent-adapters.md) for a full tour of each adapter and when to use it.
 
-### Company skills
+### Connect, configure, and finish
 
-The form's skills section lists every skill in your company library that isn't a built-in Paperclip runtime skill (those are attached automatically). Tick the ones the new agent should have. You can change this later from the Skills tab, so don't overthink it — attach what's clearly relevant and iterate.
+After the dialog, you land on a setup page with your agent's character and name at the top and the remaining steps down the left:
 
-See [Skills](./skills.md) for how the library works and how to add skills to it.
+1. **Connect** — only for adapters that sign in to a model provider (Claude, Codex, Grok). Pick an **Environment** and connect your account.
+2. **Configure** — choose the **Runtime** options (the model, plus any adapter-specific fields like an API key) and the **Environment** the agent runs in. The **Test your agent** card at the bottom runs a quick check that your runtime and model can respond; click **Run test** before you finish.
+3. **Confirmation** — click **Finish setup**. Paperclip creates the agent and shows **Your agent is ready**, with buttons to **Edit configuration** or assign the new agent its first task.
+
+### What Paperclip fills in for you
+
+The setup flow keeps things short, so a few settings are chosen for you. You can change all of them afterwards on the agent's [Harness / Runtime](#harness-runtime) page:
+
+- **Role** — the very first agent in a company is always the CEO. Everyone after that starts with the `general` role.
+- **Reports to** — new agents report to your CEO. The CEO reports to you.
+- **Title** — left blank.
+- **Heartbeat on interval** — off. The agent wakes when it's given work or when you click **Run now**, not on a timer.
+
+There's no budget field in the setup flow. Budgets are managed from **Audit → Budgets** — see [Budgets](#budgets) below.
+
+Skills aren't picked during setup either. Paperclip's own runtime skills are attached automatically; attach company skills from the agent's [Skills](#skills) page once it exists. See [Skills](./skills.md) for how the library works.
 
 ### Approvals when agents hire agents
 
-When *you* create an agent from this form, it's created immediately. When an *agent* creates one — by calling Paperclip's hire API — the request goes into the approval queue instead, and the new agent sits in `pending_approval` status until you decide. The proposal tells you the proposed agent's name and role, its capabilities, the adapter, the monthly budget it's asking for, and who it would report to. Review it like any other approval: Approve, Reject, or Request Revision. See [Approvals — Reviewing a Hire Request](../day-to-day/approvals.md#reviewing-a-hire-request) for details.
+When *you* create an agent through **New Agent**, it's usually ready straight away. (If your organization requires approval for new agents, the confirmation step says **Agent submitted for approval** instead.) When an *agent* creates one — by calling Paperclip's hire API — the request goes into the approval queue instead, and the new agent sits in `pending_approval` status until you decide. The proposal summary shows the proposed agent's **Name**, **Role**, **Title**, **Icon**, **Capabilities**, **Adapter**, and any requested **Skills**. The monthly budget it's asking for and who it would report to aren't in the summary — open **See full request** to check them in the raw payload. Review it like any other approval: **Approve**, **Reject**, or **Request revision**. See [Approvals — Reviewing a Hire Request](../day-to-day/approvals.md#reviewing-a-hire-request) for details.
 
-Agents that draft hires with the bundled `paperclip-create-agent` skill now write a short role description for the new agent — who it is and what it owns — instead of a long operating manual. Reporting line, capabilities, and skills go in their own fields of the request. Any company-specific instructions you asked for are kept. If you want more in the new agent's `AGENTS.md`, ask for it, or add it on the [Instructions tab](#instructions-tab) after the hire.
+Agents that draft hires with the bundled `paperclip-create-agent` skill now write a short role description for the new agent — who it is and what it owns — instead of a long operating manual. Reporting line, capabilities, and skills go in their own fields of the request. Any company-specific instructions you asked for are kept. If you want more in the new agent's `AGENTS.md`, ask for it, or add it on the agent's [Instructions](#instructions) page after the hire.
 
 ### What a new agent can do out of the box
 
@@ -137,26 +137,36 @@ A few things keep this in check:
 
 See [Roles & Permissions](../../administration/roles-and-permissions.md#the-permission-keys) for what each key allows.
 
-### Create
-
-Click **Create agent**. On success Paperclip navigates you to the new agent's detail page, where you can refine everything that follows.
-
 ---
 
 ## The Agent Detail Page
 
 Every agent page is built from the same shell:
 
-- A **header** with the agent's character, name, role/title, status badge, and the action cluster (Assign Task, Run Heartbeat, Pause/Resume, overflow menu)
-- A **tab bar** with six tabs: Dashboard, Instructions, Skills, Configuration, Runs, Budget
-- The **selected tab's content** below
+- A **header** with the agent's character, name, adapter, and title, plus a row of actions
+- A **side menu** that lists the agent's pages, grouped into four sections
+- The **selected page's content** to the right
 
-The action cluster in the header works on any tab:
+The side menu groups the pages like this:
 
+| Section | Pages |
+|---|---|
+| **Agent** | [Overview](#overview), [Instructions](#instructions), [Skills](#skills) |
+| **Runtime** | [Harness / Runtime](#harness-runtime), [Secrets & variables](#secrets-tools-and-channels), [Tools](#secrets-tools-and-channels), [Channels](#secrets-tools-and-channels) |
+| **Governance** | [Permissions / Trust](#permissions-trust), [API Keys](#api-keys), [Revisions](#revisions) |
+| **Audit** | Activity, [Runs](#runs), Costs, [Budgets](#budgets) |
+
+The four **Audit** links don't open pages inside the agent. They take you to the company-wide **Audit** page, already filtered to this agent. That's where run history, spending, and budgets live now.
+
+The actions in the header work on every page:
+
+- **Star** — stars the agent so it's easy to find again
 - **Assign Task** — opens the new-task dialog with this agent pre-selected as assignee
-- **Run Heartbeat** — manually triggers a heartbeat right now (useful for testing instructions changes)
+- **Run now** — wakes the agent for a heartbeat right away and takes you to the new run (useful for testing instruction changes)
+- **Run with provider trace** — the same, but also records the exact traffic to the model provider for that run. Only instance administrators (or a local single-user setup) see this button, and the trace expires after 24 hours.
 - **Pause / Resume** — toggles the agent between `paused` and `active`
-- **Overflow menu** — Copy Agent ID, Reset Sessions, Terminate
+- **Clear error** — appears when the agent is in `error`, and returns it to idle
+- **More actions (`⋯`)** — Duplicate Agent, Copy Agent ID, Reset Sessions, Terminate
 
 > **Danger:** Terminate permanently shuts the agent down. Use Pause if you might want it back. See [Approvals — Board Override Powers](../day-to-day/approvals.md#board-override-powers) for the broader discussion of Pause vs Terminate vs Delete.
 
@@ -183,11 +193,11 @@ The character animates and turns to follow your cursor. If your system is set to
 
 > **Note:** There's no palette picker in the app yet. If you want to change an agent's character, send a new `appearance` value through the API — see [Agents API — Update Agent](../../reference/api/agents.md#update-agent).
 
-When the agent is in `pending_approval` status the Run Heartbeat button is disabled and a banner at the top of the page reminds you the agent cannot be invoked until the board approves the hire.
-
 ### Banners at the top of the page
 
-Two amber banners can appear above the tab bar, and they mean different things:
+When the agent is in `pending_approval` status, a banner at the top of the page says **This agent is pending board approval and cannot be invoked yet.**, with an **Approve agent** button beside it.
+
+Two amber banners can also appear near the top of the page, and they mean different things:
 
 - **Invalid org chain** — the agent's reporting chain is broken (a terminated manager, a manager that no longer exists, or a loop). This one blocks work: you can't assign to the agent until you repair the chain, and the banner tells you how.
 - **Escalation path is paused** — the agent can run perfectly well, but somewhere up its `reports_to` chain sits a **paused** agent. This one is a warning only. Nothing is blocked; the agent just has nowhere useful to escalate to, and any escalation an agent tries to route there is refused rather than accepted. The banner text names the paused manager and gives you the two fixes: unpause that manager, or change who this agent reports to.
@@ -198,50 +208,44 @@ This is worth checking after an instance import, which pauses every agent by def
 
 ---
 
-## Dashboard Tab
+## Overview
 
-The Dashboard is the summary view — the one you open when you want to know "what has this agent been doing?"
+<a id="dashboard-tab"></a>
 
-![Dashboard tab](../../user-guides/screenshots/light/agents/dashboard.png)
+**Overview** is the agent's home page — the one you open when you want to know "who is this agent, and what has it been doing?"
 
-### Latest run card
+![An agent's Overview page with the Latest Run card, the Identity, Harness / Runtime, Capabilities, and Skills cards, and Recent Tasks](../../user-guides/screenshots/light/agents/dashboard.png)
 
-At the top, Paperclip shows either the currently running heartbeat (with a pulsing live indicator and a soft glow) or the most recent finished one. The card includes:
+### Latest Run
 
-- The run status icon (check, cross, spinner, clock, timer, slash)
-- A short run ID
-- An invocation-source pill: Timer, Assignment, On-demand, or Automation — so you can see at a glance why the agent ran
-- A relative timestamp
-- A two-to-three-line excerpt from the run's result summary, rendered as markdown
+At the top, Paperclip shows either the run in progress (labelled **Live Run**) or the most recent finished one (**Latest Run**), with its short run ID, status, the task it worked on, and how long ago it happened. Click it to open that run's detail.
 
-Clicking the card jumps to the run detail, same as picking the run from the Runs tab.
+### The four summary cards
 
-### Activity charts
+Below that, four cards sum up the agent at a glance:
 
-A row of four compact charts covering the last 14 days:
+- **Identity** — the agent's status, **Role**, **Title**, who it **Reports to**, and how many **Direct reports** it has
+- **Harness / Runtime** — the **Adapter**, **Model**, current **Session**, and **Last run**. The **Configure** link jumps to the [Harness / Runtime](#harness-runtime) page.
+- **Capabilities** — the agent's capability summary, or "No capability summary has been added." if it's empty
+- **Skills** — the skills enabled for this agent. The **Manage** link jumps to the [Skills](#skills) page.
 
-- **Run Activity** — runs per day
-- **Issues by Priority** — the priority mix of issues this agent has touched
-- **Issues by Status** — the status mix of the same set of issues
-- **Success Rate** — proportion of successful heartbeats
+### Recent Tasks
 
-The charts share a common 14-day window; they're designed to answer "is this agent productive?" without needing to scroll through run logs.
+A list of up to six tasks this agent has worked on, most recent first. **See All** opens the full task list filtered to this agent. Use it to pick up context before you run the agent or reassign work.
 
-### Recent issues
+### Audit
 
-A list of up to 10 issues this agent has participated in, sorted by recency, with status badges. A **See All** link opens the full filtered issues page. Use this to pick up context before running a manual heartbeat or reassigning work.
-
-### Costs
-
-At the bottom, a summary of the agent's total input tokens, output tokens, cached tokens, and total cost, followed by a per-run cost table for the most recent 10 runs. For a deeper view of spending — and the rules for how the numbers are computed — see [Costs & budgets](../day-to-day/costs.md).
+At the bottom, four shortcuts — **Activity**, **Runs**, **Costs**, and **Budgets** — open the company-wide Audit page filtered to this agent. Spending charts and per-run costs live there now; see [Costs & budgets](../day-to-day/costs.md).
 
 ---
 
-## Instructions Tab
+## Instructions
 
-The Instructions tab is where you edit what the agent *is* — its role description and any other files it should keep. For most agents it is also the agent's own folder: a place it can keep notes and working material from one task to the next.
+<a id="instructions-tab"></a>
 
-![Instructions tab](../../user-guides/screenshots/light/agents/instructions.png)
+The **Instructions** page is where you edit what the agent *is* — its role description and any other files it should keep. For most agents it is also the agent's own folder: a place it can keep notes and working material from one task to the next.
+
+![An agent's Instructions page with the file list and the AGENTS.md editor](../../user-guides/screenshots/light/agents/instructions.png)
 
 ### Managed vs external bundles
 
@@ -250,7 +254,7 @@ Local adapters (Claude Code, Codex, Cursor, Gemini, OpenCode) support an **instr
 - **Managed** — Paperclip keeps one folder per agent in its own storage. You edit it here, and the agent can add its own files to it. This is the mode that keeps agent files across tasks (see below).
 - **External** — you give Paperclip a `rootPath` on disk and it reads/writes the files there; useful when the instructions already live in a repo you want to keep canonical. External folders keep their existing behaviour and aren't treated as the agent's persistent personal folder.
 
-The mode toggle and root path field sit at the top of the tab. Changing them is a normal edit — the floating Save/Cancel bar appears as soon as the form is dirty.
+The mode toggle and root path field sit at the top of the page. Changing them is a normal edit — the **Save changes** and **Discard** buttons at the bottom of the page light up as soon as something changes.
 
 ### The entry file
 
@@ -258,7 +262,7 @@ Every bundle has an **entry file**, usually `AGENTS.md`. That's the file the ada
 
 ### Agent files persist across tasks
 
-With a managed bundle, the folder on this tab is the agent's single, current home directory. When a run starts, Paperclip gives the agent a private copy of that folder and points the `AGENT_HOME` environment variable at it. The agent reads its instructions there, and it can also create its own files and subfolders — notes, memory, reference material, even images or other binary files. Paperclip saves validated changes at turn boundaries: a warm native Codex session keeps the same writable copy between turns, while other sessions are collected after the provider stops. Only files the agent changed or deleted are synchronized back, so the next task starts from the saved folder.
+With a managed bundle, the folder on this page is the agent's single, current home directory. When a run starts, Paperclip gives the agent a private copy of that folder and points the `AGENT_HOME` environment variable at it. The agent reads its instructions there, and it can also create its own files and subfolders — notes, memory, reference material, even images or other binary files. Paperclip saves validated changes at turn boundaries: a warm native Codex session keeps the same writable copy between turns, while other sessions are collected after the provider stops. Only files the agent changed or deleted are synchronized back, so the next task starts from the saved folder.
 
 A few things are worth knowing:
 
@@ -356,7 +360,7 @@ Existing agents keep whatever files they already have — Paperclip doesn't rewr
 
 The left pane shows the agent's files and folders. Click a file to open it in the markdown editor on the right. Add a file with the **+** button (**Add agent file**) at the top of the file list — type a name such as `TOOLS.md`, or a path with folders. Delete a file with the **Delete** button above the editor (it isn't offered for the entry file). Rename is via delete + create for now.
 
-The editor handles text files up to 1 MiB. For a binary file, or one too large to edit, the tab shows a download link instead.
+The editor handles text files up to 1 MiB. For a binary file, or one too large to edit, the page shows a download link instead.
 
 The markdown editor supports inline image uploads (drag-and-drop or paste) — images are uploaded to the company asset store and inserted as markdown image links.
 
@@ -366,111 +370,151 @@ For adapters that don't support a filesystem bundle (OpenClaw gateway and some r
 
 ### When changes take effect
 
-Edits are saved on **Save** (via the floating Save/Cancel bar that appears on any dirty state). The agent uses the new instructions on its next run — runs already in flight are not interrupted. Changes the agent makes to its own folder during a run are saved when the run stops; check the run's detail view for any storage or sync warning. If you want to see your change immediately, click **Run Heartbeat** in the header after saving.
+Edits are saved when you click **Save changes** in the bar at the bottom of the page (or **Discard** to throw them away). The agent uses the new instructions on its next run — runs already in flight are not interrupted. Changes the agent makes to its own folder during a run are saved when the run stops; check the run's detail view for any storage or sync warning. If you want to see your change immediately, click **Run now** in the header after saving.
 
 ---
 
-## Skills Tab
+## Skills
 
-The Skills tab controls which company skills are attached to this specific agent. It is a per-agent view over the shared [company skill library](./skills.md) — the library is where skills are authored and imported, this tab is where you decide which agents get which skills.
+<a id="skills-tab"></a>
 
-![Skills tab](../../user-guides/screenshots/light/agents/skills.png)
+The **Skills** page controls which company skills are attached to this specific agent. It is a per-agent view over the shared [company skill library](./skills.md) — the library is where skills are authored and imported, this page is where you decide which agents get which skills.
 
-### Sections on the tab
+![An agent's Skills page with toggle switches, grouped into "Enabled on this agent" and "Available from the library"](../../user-guides/screenshots/light/agents/skills.png)
 
-The tab splits skills into three sections:
+### The header
 
-1. **Optional company skills** — every skill in the company library that this agent *could* use. Tick or untick the checkbox on each row to enable or disable it for the agent.
-2. **Required by Paperclip** — skills the runtime itself insists on (for example, the built-in Paperclip API skill that teaches the agent how to check out tasks and post comments). These show with a locked checkbox and a tooltip explaining why they can't be turned off.
-3. **User-installed skills, not managed by Paperclip** — skills that already exist on disk in the agent's workspace but weren't installed through Paperclip. They're displayed for visibility but can't be toggled from here. Edit them at their source (or import them into the library). This section is collapsed by default.
+The top of the page shows how many library skills are on (for example, "3 of 12 enabled"), a pill saying how skills reach the agent — **Kept in workspace**, **Applied on next run**, or **Tracked only** (the adapter doesn't support skill management from Paperclip) — and a save indicator. On the right you'll find a **Search skills** box and a **Browse skills store** button that takes you to the company library.
+
+### Sections on the page
+
+Skills are grouped into sections, each with a count:
+
+1. **Enabled on this agent** — library skills this agent currently uses. Flip a row's toggle off to remove it.
+2. **Available from the library** — every other skill in the company library. Flip a row's toggle on to give it to this agent.
+3. **Automatic and detected skills (read-only)** — skills Paperclip applies automatically, plus skills that already exist on disk in the agent's workspace but weren't installed through Paperclip. Each row shows a lock icon instead of a toggle, with an origin and location hint so you can find the file. This section only appears when there's something to show, and you can collapse it.
 
 ### Each skill row
 
-Every row shows the skill's name, its description (the routing logic the agent uses to decide whether to load it), and, for non-managed skills, an origin and location hint so you can find the file on disk. A **View** link jumps to the skill's detail page in the company library where you can edit the source.
+Every row shows the skill's icon, name, a category chip, a one-line summary, and where the skill came from. Click a library skill's row to open its detail page in the company library, where you can edit the source.
 
 ### Autosave
 
-Changes save automatically about 250 ms after you stop clicking — you'll see "Saving soon…" and then the indicator clears. No Save button to press.
+Changes save automatically shortly after you stop toggling — you'll see **Saving soon…**, then **Saving…**, then **Saved**. No Save button to press. If a save fails, the indicator says **Couldn’t save**.
 
-### Where skills run
+### When the adapter can't manage skills
 
-The footer shows a small status block:
-
-- **Adapter** — which runtime this agent uses
-- **Skills applied** — "Kept in the workspace" (persistent), "Applied when the agent runs" (ephemeral), or "Tracked only" (the adapter doesn't support skill management from Paperclip)
-- **Selected skills** — the count
-
-If the skill mode is `unsupported` (e.g. `openclaw_gateway`), the checkboxes are disabled with a tooltip directing you to manage skills in the adapter directly.
+Some adapters (for example `openclaw_gateway`) don't let Paperclip manage skills. The page shows a banner explaining why, and the toggles are disabled. Manage skills in the adapter directly. The adapter in use is listed at the bottom of the page.
 
 ### Warnings
 
-If you toggled a skill key that no longer exists in the company library, Paperclip shows an amber "Requested skills missing from the company library" warning. Either re-import the skill, or untick the missing key.
+If the agent has a skill enabled that no longer exists in the company library, Paperclip shows an amber row saying it "is enabled but missing from the organization library", with a **Remove** button. Either re-import the skill, or click **Remove**.
 
 For a deeper discussion of what skills are, how to write good ones, and how they keep the agent's context small, see [Skills](./skills.md).
 
 ---
 
-## Configuration Tab
+## Harness / Runtime
 
-The Configuration tab is where you change the agent's **runtime settings** — which adapter it uses, which model it runs, what heartbeat interval it has, what environment variables it needs, and a few adapter-specific knobs. It is *not* where you change what the agent *does* (that's Instructions) or what it knows (that's Skills). It's where you change how it's wired.
+<a id="configuration-tab"></a>
 
-![Configuration tab](../../user-guides/screenshots/light/agents/configuration.png)
+The **Harness / Runtime** page is where you change how the agent is *wired* — its name and reporting line, which adapter and model it uses, where it runs, its environment variables, and when it wakes up. It is *not* where you change what the agent *does* (that's [Instructions](#instructions)) or what it knows (that's [Skills](#skills)).
 
-### The shared configuration form
+![An agent's Harness / Runtime page showing the Agent identity and Adapter cards](../../user-guides/screenshots/light/agents/configuration.png)
 
-The same `AgentConfigForm` you met in the hiring flow drives this tab, with two differences: the Instructions and prompt-template fields are hidden here (they live on their own tab) and the adapter-specific options are fully editable.
+### The cards on the page
 
-Common fields:
+The page is a stack of cards, top to bottom:
 
-- **Adapter** — dropdown of every adapter enabled for your instance. Switching adapters is a structural change and typically resets model/options to safe defaults for the new adapter. Pick deliberately.
-- **Model** — the list Paperclip fetched from the adapter. Some adapters (OpenCode, Gemini local) require a specific format; the form will block submission with an inline error if the model can't be validated.
-- **Working directory (cwd)** — the filesystem path the adapter runs in. Relative instruction paths resolve from here.
-- **Heartbeat interval** — the minimum number of seconds between automatic heartbeats. This is a floor, not a guarantee; a busy agent with many assignments may run more often if events (approvals, assignments, comments on its tasks) trigger wakes. @-mentions don't wake an agent; they're context only.
-- **Heartbeat enabled** — toggle on/off. A disabled agent only runs on explicit event triggers or when you click **Run Heartbeat** manually.
+- **Agent identity** — **Name**, **Title**, and **Reports to**. Change the reporting line here to move the agent in the org chart.
+- **Adapter** — **Adapter type** (every adapter enabled for your instance), **Model**, and adapter-specific fields such as **Thinking effort**. Switching adapters is a structural change and usually resets the model and options to safe defaults for the new adapter, so pick deliberately. Some adapters (OpenCode, for example) need the model in a specific format; the form shows an inline error if the model can't be validated.
+- **Configuration** — adapter-specific settings, with less common options such as **Command** and **Extra args** tucked under **Advanced**.
+- **Environment** — where the agent runs. Leave it on the company default or pick a specific environment.
+- **Environment variables** — values passed to the agent's runtime on every run.
+- **Run Policy** — when the agent wakes up on its own (see below).
+- **Debugging** — the **Capture raw provider traces** switch. Only instance administrators see this card.
 
-Adapter-specific fields (Claude login, Codex sandbox bypass, Cursor options, etc.) appear as extra rows underneath. Adapter-specific fields only modify this agent — changing them has no effect on any other agent.
+Adapter-specific fields only affect this agent — changing them has no effect on any other agent.
 
-### API Keys section
+### Run Policy
 
-Below the form, still on the Configuration tab, is a dedicated **API Keys** block. This is the same UI described under the Keys tab below — it's embedded here because issuing a key is a configuration-time action. See [Keys](#keys) for the details.
+The **Run Policy** card controls the agent's heartbeat:
 
-### Configuration revisions
+- **Heartbeat on interval** — turn this on to have the agent wake on a timer, then set how often under **Run heartbeat every … sec**. The interval is a floor, not a guarantee: a busy agent may run more often when events (assignments, approvals, comments on its tasks) wake it. @-mentions don't wake an agent; they're context only. With the switch off, the agent only runs when something wakes it or when you click **Run now**.
+- **Advanced Run Policy** — expand this for **Timeout (sec)**, **Interrupt grace period (sec)**, **Wake on demand**, **Cooldown (sec)**, **Max concurrent runs**, and **Continue after max-turn stop**.
 
-At the bottom of the tab is a collapsible **Configuration Revisions** section. Every time you save a change to this agent's configuration, Paperclip records a revision with a timestamp, the keys that changed, and a diff. Up to the most recent 10 are shown when expanded.
+New agents start with **Heartbeat on interval** switched off.
 
-Each revision row includes a **Rollback** action: clicking it restores the agent to that exact configuration, atomically. Rollback is itself saved as a new revision, so you can always undo an undo.
+### Test your agent
 
-> **Tip:** Use rollback when a change breaks an agent and you don't have time to debug. Pause the agent, roll back to the last known-good revision, resume, and investigate the bad change later.
+At the bottom of the page, the **Test your agent** card checks that the runtime and model can respond. Click **Run test**; the card changes to **Connection successful** when everything checks out, or shows what needs attention if it doesn't. Run it again after you change the adapter, model, or environment.
 
-### Save flow
+### Saving changes
 
-Edits are dirty-tracked. A floating Save/Cancel bar (desktop) or a fixed bottom bar (mobile) appears as soon as any field differs from the persisted state. Save is blocking — you'll see "Saving…" on the button. Cancel reverts every dirty field back to its saved value in one shot.
+Edits are tracked as you make them. The bar at the bottom of the page shows "You have unsaved changes." with **Discard** and **Save changes** buttons. **Discard** puts every changed field back the way it was. Saving creates a new entry on the [Revisions](#revisions) page.
 
 ---
 
-## Runs Tab
+## Secrets, Tools, and Channels
 
-The Runs tab is your audit trail. Every heartbeat the agent has ever done is listed here, newest first, with filters, a detail view, and live streaming for runs in progress.
+The rest of the **Runtime** section in the side menu covers what the agent can reach:
 
-![Runs tab](../../user-guides/screenshots/light/agents/runs.png)
+- **Secrets & variables** — under **Secret access**, choose which of your organization's secrets this agent may use. Environment variables themselves are set on [Harness / Runtime](#harness-runtime).
+- **Tools** — the connected apps and tools this agent can use, and its effective access.
+- **Channels** — the chat channels this agent takes part in.
+
+---
+
+## Permissions / Trust
+
+The **Permissions / Trust** page sets how much the agent is trusted and what it's allowed to do:
+
+- **Trust** — the **Trust preset** decides how broadly the agent can read and act on Paperclip work. See [Trust and low-trust review](../../administration/trust-and-low-trust-review.md).
+- **Permissions** — switches for **Can create new agents**, **Can create/import skills**, and **Can assign tasks**. Task assignment is switched on automatically for the CEO and for any agent that can create agents.
+
+These switches save as soon as you flip them.
+
+---
+
+## Revisions
+
+<a id="configuration-revisions"></a>
+
+Every time you save a change to this agent's configuration, Paperclip records a revision. The **Revisions** page lists them under **Configuration Revisions**, newest first. Each entry shows a short ID, when it was made, where the change came from, and which settings changed.
+
+Click **Restore** on any entry to put the agent back to that exact configuration. Restoring is itself saved as a new revision, so you can always undo an undo.
+
+> **Tip:** Use restore when a change breaks an agent and you don't have time to debug. Pause the agent, restore the last known-good revision, resume, and investigate the bad change later.
+
+---
+
+## Runs
+
+<a id="runs-tab"></a>
+
+Run history doesn't live on the agent's page any more. Click **Runs** under **Audit** in the agent's side menu (or the **Runs** shortcut at the bottom of [Overview](#overview)) and you land on the company-wide **Audit** page, on its **Runs** tab, already filtered to this agent.
+
+![The Audit page's Runs tab filtered to one agent, listing recent runs with status, trigger, and timing](../../user-guides/screenshots/light/agents/runs.png)
 
 ### The run list
 
-Each entry in the list shows:
+Two filters sit above the list:
 
-- A status icon (succeeded, failed, running, queued, timed out, cancelled)
-- A short run ID
-- The run's invocation source pill (Timer / Assignment / On-demand / Automation)
-- Input + output tokens and cost (when cost is non-zero)
-- A relative timestamp
-- A short excerpt from the result summary
+- **Agent** — pick one agent, or **All agents**
+- **Status** — pick a run status, or **All statuses**
 
-On desktop, the list sits in a narrow left column and clicking a run opens the detail to the right — you can step through runs quickly without navigating away. On mobile the list takes the whole screen and tapping a run pushes into a detail view with a Back button.
+**Clear filters** resets both. Each entry shows:
 
-Paperclip auto-selects the latest run on desktop so you always have something in the detail pane when you land on the tab.
+- The agent's name, a short run ID, and a status badge
+- A one-line summary of the run
+- Why it ran (Timer, Assignment, On-demand, Automation), how long it took, and how long ago it started
+
+The list shows the most recent runs, newest first.
 
 ### The run detail
 
+Click a run to open it. The run detail opens on the agent's page, with the agent's other runs in a narrow column on the left so you can step through them without navigating away. On mobile, a **Back to runs** link takes you back to the list.
+
 The detail view has several stacked blocks:
 
 - **Status & timing** — status badge, start time, end/elapsed time, duration, a Cancel button (live runs only)
@@ -480,12 +524,12 @@ The detail view has several stacked blocks:
 - **Invocation card** — the exact command, working directory, prompt, context, and environment the adapter used, with secrets redacted (`***REDACTED***`) and JWT values masked
 - **Transcript** — the full conversation between the agent and the model, rendered with tool calls inline
 - **Log viewer** — raw stdout/stderr/system chunks with timestamps, useful when the transcript isn't enough
-- **Touched issues** — the set of issues the agent interacted with during this run, with links and a **Clear sessions for touched issues** action (handy after a bad run corrupted session state)
-- **Claude login** (Claude adapters) — a one-click "Login with Claude" action that bootstraps the adapter against a fresh Claude auth
+- **Touched issues** — the set of issues the agent interacted with during this run, with links and a **clear session for these tasks** link (handy after a bad run corrupted session state)
+- **Claude login** (Claude Code agents) — when a run fails because Claude Code needs authentication, a **Login to Claude Code** button runs `claude login` for you
 
 ### Live runs
 
-When a run is in-flight, the transcript and log viewer stream in real time. The header shows an animated status, an elapsed-time counter, and a cancel button. The Scroll-to-bottom helper sticks you to the latest output until you scroll up to read history, at which point it lets go so you don't get yanked around.
+When a run is in flight, the transcript and log viewer stream in real time. The header shows an animated status, an elapsed-time counter, and a cancel button. The scroll-to-bottom helper sticks you to the latest output until you scroll up to read history, at which point it lets go so you don't get yanked around.
 
 ### Cancelling, retrying, resuming
 
@@ -493,74 +537,63 @@ When a run is in-flight, the transcript and log viewer stream in real time. The
 - **Retry** — creates a new run with the same task context. Use when a run failed for a recoverable reason (transient network error, adapter glitch).
 - **Resume** — only appears when a run failed because the adapter process was lost. Paperclip re-wakes the agent and passes a `resumeFromRunId` so the next run can pick up instead of restarting.
 
-### Filters and sorting
-
-The list is sorted by creation time descending. There are no additional filters on the Runs tab itself — use the Dashboard's charts for aggregate views, or jump to individual issues to see per-task run history.
-
 ---
 
-## Budget Tab
+## Budgets
 
-Every agent can have its own budget. The Budget tab is where you set it, watch the current spend, and configure how Paperclip should react when limits are approached or breached.
+<a id="budget-tab"></a>
 
-![Budget tab](../../user-guides/screenshots/light/agents/budget.png)
+Every agent can have its own monthly budget. Agent budgets live on the company-wide **Audit** page, on its **Budgets** tab — click **Budgets** under **Audit** in the agent's side menu to get there.
 
-### Anatomy of an agent budget
+![The Audit page's Budgets tab with the Budget control plane summary and active budget incidents](../../user-guides/screenshots/light/agents/budget.png)
 
-A budget has four pieces:
+### What's on the Budgets tab
 
-- **Window kind** — either **Monthly UTC** (spending resets on the first of each month, UTC) or **Lifetime** (never resets; the agent gets this much total, ever)
-- **Amount** — the spending cap in cents (displayed as dollars)
-- **Warn percent** — the soft-alert threshold, e.g. 80%. When spend crosses this, the agent moves to `warning` status and the header shows an amber indicator.
-- **Hard stop** — the enforcement behaviour when spend reaches 100%. By default, Paperclip pauses the agent (`pauseOnExceed = true`) so it consumes no further budget until a board user resumes it or raises the limit.
+- **Budget control plane** — counts of **Active incidents**, **Pending approvals**, **Paused agents**, and **Paused projects**
+- **Active incidents** — any budget that has crossed its warning or hard-stop threshold. Resolve a hard stop here with **Raise budget & resume**, or click **Keep paused**.
+- **Agent budgets** — one card per agent that has a budget, showing the cap, the spend against it, and what's **Remaining**. Change the amount and click **Update budget** (or **Set budget** if no cap is configured yet).
 
-### The policy card
+The Budgets tab shows every budget in the company; it isn't filtered to one agent, so look for your agent's card under **Agent budgets**.
 
-The card on this tab shows:
-
-- An icon and colour corresponding to the current state (Healthy wallet, Warning triangle, Hard-stop shield)
-- The window label (Monthly UTC budget / Lifetime budget)
-- Current spend vs. cap, as a number and as a progress bar
-- The soft-alert threshold
-- Pause status and pause reason, if paused
-
-### Editing the budget
-
-Use the edit control on the card to change the amount. Depending on your permissions and the agent's reporting chain, some fields may be read-only — in particular, subordinate agents can propose budget increases but not approve them. When a policy's hard stop is hit, a **Budget Override** approval may be created for you to approve a one-time increase or a permanent raise.
+> **Note:** An agent only gets a card once it has a budget. Agents hired through the API with a monthly budget get one automatically, but the setup flow in the app doesn't set one. To give any other agent a cap, use the CLI's `budget agent:update` command (see [Cost & budget commands](../../reference/cli/cost.md)) or the [Set agent budget](../../reference/api/costs.md#set-agent-budget) API.
 
 ### What happens at each threshold
 
 - **Below the warn threshold** — normal. The agent runs as scheduled.
-- **Between warn and hard stop** — `warning` status. The agent keeps running. Consider triaging: is the agent doing what you want, or is it burning budget on low-value work?
-- **At or above the hard stop** — `paused` status with `pauseReason = "budget"`. The agent stops taking heartbeats until you resume, raise the cap, or the window resets (monthly only).
+- **Between warn and hard stop** — the budget is in `warning`. The agent keeps running. Consider triaging: is the agent doing what you want, or is it burning budget on low-value work?
+- **At or above the hard stop** — the agent is paused with `pauseReason = "budget"`. It stops taking heartbeats until you raise the cap and resume it, or the monthly window resets.
+
+When a hard stop is hit, a **Budget Override** approval may be created for you to approve a one-time increase or a permanent raise.
 
 ### Agent-level vs company-level
 
-This tab configures **this agent's** budget. Paperclip also tracks a company-level budget that sums across agents. See [Costs & budgets](../day-to-day/costs.md) for how the two interact, how API costs are computed, and how to tune budgets as a portfolio rather than one agent at a time.
+Agent budgets cap a single agent. Paperclip also tracks an organization-wide budget that sums across agents. See [Costs & budgets](../day-to-day/costs.md) for how the two interact, how API costs are computed, and how to tune budgets as a portfolio rather than one agent at a time.
 
 ---
 
-## Keys
+## API Keys
+
+<a id="keys"></a>
 
 An agent authenticates to the Paperclip API with a short-lived JWT for in-process runs. When the agent runs *outside* a managed heartbeat — for example a local CLI operator checking assignments, a CI job triggering a webhook, a remote adapter that needs a standing token — it uses a long-lived **API key** instead.
 
-The Keys panel sits on the Configuration tab (under the configuration form, above the revisions collapsible).
+API keys have their own page: open **API Keys** under **Governance** in the agent's side menu.
 
 ### Issuing a key
 
-1. Type a name for the key (e.g. `production`, `ci`, `local-cli`). A clear name makes audits easier later.
+1. Under **Create API Key**, type a name for the key (e.g. `production`, `ci`, `local-cli`). A clear name makes audits easier later.
 2. Click **Create**.
-3. Paperclip shows the full token in a yellow banner. **Copy it now** — the plaintext token is only shown this once. After you dismiss the banner, Paperclip only stores a hash and can never show it again.
+3. Paperclip shows the full token in a banner: "API key created — copy it now, it will not be shown again." **Copy it now** — after you dismiss the banner, Paperclip only stores a hash and can never show it again.
 
-The banner has a show/hide eye toggle so you can reveal the token to paste it, and a copy-to-clipboard button. When you're done, click **Dismiss**.
+The banner has a show/hide toggle so you can reveal the token to paste it, and a copy-to-clipboard button. When you're done, click **Dismiss**.
 
 ### Active keys
 
-Every un-revoked key is listed below the create form, showing its name and creation timestamp. You can see how many keys exist and when each was made — useful for rotation reviews.
+Every un-revoked key is listed under **Active Keys**, showing its name and creation date — useful for rotation reviews.
 
 ### Revoking a key
 
-Click **Revoke** next to any active key. The key moves to the **Revoked Keys** section at the bottom of the panel (displayed with a strikethrough and dimmed), and is immediately rejected by the Paperclip API. Revocation is permanent — revoked keys are never reused. To rotate a key, create a new one, swap it in wherever the old one is used, then revoke the old one.
+Click **Revoke** next to any active key. The key moves to the **Revoked Keys** section at the bottom of the page and is immediately rejected by the Paperclip API. Revocation is permanent — revoked keys are never reused. To rotate a key, create a new one, swap it in wherever the old one is used, then revoke the old one.
 
 ### Where keys flow
 
@@ -585,7 +618,7 @@ Every heartbeat follows the same six-step arc:
 5. **Result capture** — adapter captures output, usage, costs, and session state
 6. **Run record** — Paperclip stores the run result for audit and debugging
 
-Each of those steps corresponds to something visible in the Runs tab: the trigger shows up as the invocation source pill, the adapter invocation is the Invocation card, the agent process is the transcript and logs, the API calls appear in the touched-issues list, the result capture populates the metrics block, and the run record is the run itself.
+Each of those steps corresponds to something visible in a run's detail view: the trigger shows up as the invocation source pill, the adapter invocation is the Invocation card, the agent process is the transcript and logs, the API calls appear in the touched-issues list, the result capture populates the metrics block, and the run record is the run itself.
 
 ### Agent identity
 
@@ -615,7 +648,7 @@ These are exactly what you'll see in the Invocation card on any run — Papercli
 
 Agents maintain conversation context across heartbeats through session persistence. The adapter serializes session state (e.g. Claude Code session ID) after each run and restores it on the next wake. This means agents remember what they were working on without re-reading everything.
 
-On the Runs tab, each run shows a **session ID before** and **session ID after**. A differing pair means the session rotated during the run; an equal pair means the agent continued the same conversation. The overflow menu's **Reset Sessions** action wipes this state when you want the agent to start fresh on its next heartbeat.
+In a run's detail view, you see a **session ID before** and **session ID after**. A differing pair means the session rotated during the run; an equal pair means the agent continued the same conversation. The **Reset Sessions** action in the header's more-actions menu wipes this state when you want the agent to start fresh on its next heartbeat.
 
 ### Agent status
 
@@ -638,7 +671,7 @@ The heartbeat model has a few practical consequences worth keeping in mind:
 
 - **An agent that isn't doing work isn't costing you anything** (past whatever the last run spent). Between heartbeats there's no idle burn.
 - **Changing configuration takes effect on the next heartbeat, not the current one.** If you edit Instructions while a heartbeat is running, that run uses the old instructions. The next run uses the new ones.
-- **Manual Run Heartbeat is your friend when testing changes.** Save your edit, click Run Heartbeat, watch the live run stream in the Runs tab. Much faster than waiting for the timer.
+- **Run now is your friend when testing changes.** Save your edit, click **Run now**, and watch the live run stream in. Much faster than waiting for the timer.
 - **Paused agents are cheap.** If you're not sure whether to keep an agent, pause it. It will stop accumulating spend and its history is preserved for when you come back.
 
 ---
@@ -649,22 +682,21 @@ A few end-to-end recipes for things you'll do often.
 
 ### Try a new instruction quickly
 
-1. Open the agent and go to the **Instructions** tab.
-2. Edit the entry file (usually `AGENTS.md`). Save.
-3. Click **Run Heartbeat** in the header.
-4. Switch to the **Runs** tab. The new run is selected automatically on desktop; on mobile tap it from the list.
-5. Watch the transcript stream. If the agent behaves as you want, you're done. If not, repeat.
+1. Open the agent and go to its **Instructions** page.
+2. Edit the entry file (usually `AGENTS.md`). Click **Save changes**.
+3. Click **Run now** in the header. Paperclip takes you straight to the new run.
+4. Watch the transcript stream. If the agent behaves as you want, you're done. If not, repeat.
 
 This loop is tight on purpose — changes apply on the next heartbeat, and manual invoke gives you that heartbeat on demand.
 
 ### Diagnose a misbehaving agent
 
-1. Open the **Runs** tab, find the most recent failed run.
+1. Click **Runs** under **Audit** in the agent's side menu, set **Status** to failed, and open the most recent failed run.
 2. Read the transcript for where the agent got confused.
 3. Open the **Invocation** card to confirm it received the right environment, working directory, and instruction path.
 4. Check **Touched issues** — did it actually work on what it was supposed to?
-5. If the session is bad, use **Clear sessions for touched issues** or the overflow menu's **Reset Sessions**.
-6. If the configuration is at fault, roll back on the **Configuration** tab.
+5. If the session is bad, use the run's **clear session for these tasks** link or the overflow menu's **Reset Sessions**.
+6. If the configuration is at fault, restore a known-good version on the **Revisions** page.
 
 ### Temporarily mute an agent
 
@@ -676,18 +708,18 @@ Use pause liberally — it's reversible, cheap, and the right default when somet
 
 ### Rotate an API key
 
-1. Open the **Configuration** tab, scroll to **API Keys**.
+1. Open the agent's **API Keys** page (under **Governance** in the side menu).
 2. Click **Create**, name the new key (e.g. `production-2026-04`), copy the token shown in the yellow banner.
 3. Swap the new token into whatever system was using the old one.
-4. Back on the Keys panel, click **Revoke** next to the old key.
+4. Back on the **API Keys** page, click **Revoke** next to the old key.
 5. Confirm the revoked key moves to the bottom **Revoked Keys** section.
 
 ### Raise a capped agent's budget
 
-1. Open the **Budget** tab. The policy card shows current status, spend, and pause reason.
-2. Edit the amount on the policy card.
-3. If the change is within your authority, it saves immediately. If the agent is subordinate and an override is required, a Budget Override approval is created — see [Approvals](../day-to-day/approvals.md).
-4. Once the cap is raised and the agent is off hard-stop, click **Resume** in the header if it was paused by budget.
+1. Click **Budgets** under **Audit** in the agent's side menu.
+2. If the agent hit its hard stop, find its card under **Active incidents** and click **Raise budget & resume** — that raises the cap and resumes the agent in one step.
+3. Otherwise, find the agent's card under **Agent budgets**, change the amount, and click **Update budget**.
+4. If the agent is still paused, click **Resume** in the header of its page. If a Budget Override approval was created instead, see [Approvals](../day-to-day/approvals.md).
 
 ---
 

docs/guides/org/delegation.md

@@ -60,7 +60,7 @@ When reviewing a strategy:
 - Are the workstreams reasonable and prioritised correctly?
 - Does the hiring plan make sense for the scope?
 
-If the plan looks right, approve it. If not, click **Request Revision** and describe what needs to change. The CEO reads your comment, revises the plan, and resubmits. You can go back and forth as many times as needed before approving.
+If the plan looks right, approve it. If not, click **Request revision** and leave a comment describing what needs to change. The CEO reads your comment, revises the plan, and resubmits. You can go back and forth as many times as needed before approving.
 
 > **Tip:** Don't approve a strategy that feels unclear or off-track just to get things moving. A vague approval leads to vague work. It's worth a round of revisions.
 
@@ -202,7 +202,7 @@ A new CEO starts with a one-line role description rather than a built-in routing
 
 ### Strategy was approved but nothing happened
 
-After you approve a strategy, Paperclip queues the CEO to wake automatically so follow-up work usually starts shortly after approval. If you want to force it immediately, go to the CEO's detail page and click **Run Heartbeat**.
+After you approve a strategy, Paperclip queues the CEO to wake automatically so follow-up work usually starts shortly after approval. If you want to force it immediately, go to the CEO's detail page and click **Run now**.
 
 ### A specific task is stuck
 

docs/guides/org/members-and-access.md

@@ -20,12 +20,12 @@ That's why the same surfaces keep showing up for both:
 
 - an **invite link** can onboard a human *or* an agent (you choose when you create it);
 - a **join request** can be a person asking to join or an agent asking to enroll;
-- the **members list** shows humans and agents side by side;
+- **memberships** are stored the same way for humans and agents (though the **Members** page in settings lists only the people — agents live on the **Agents** page);
 - **permission grants** attach to a person or an agent identically.
 
 You mostly deal with the human side, but knowing it's one system explains why the invite and approval flows feel symmetrical.
 
-![The Members page lists human and agent principals together](../../user-guides/screenshots/light/company/access.png)
+![The Organization Members page listing the company's human members with their email, role, and status](../../user-guides/screenshots/light/company/access.png)
 
 ---
 

docs/guides/org/org-structure.md

@@ -1,4 +1,5 @@
 ---
+paperclip_version: v2026.1012.0
 seo_title: Building Your Org Structure
 seo_description: Reporting lines tell each agent who manages them, who delegates work, and who to escalate to. Common structures, plus adding managers and workers.
 ---
@@ -81,36 +82,38 @@ Manager-level agents (CTO, CMO, Head of Design, etc.) report directly to the CEO
 
    ![Agents list page showing the New Agent button](../../user-guides/screenshots/light/agents/agents-list-empty.png)
 
-2. **Set the name, title, and role**
+2. **Name the agent and pick an adapter**
 
-   Give the agent a clear name (e.g. "Sam"), a title (e.g. "CTO"), and choose the closest role. The role helps the CEO understand what this agent is responsible for when assigning work.
+   The **Meet your next agent** dialog asks for an **Agent name** (e.g. "Sam"). Click **Choose adapter**, pick an adapter, then click **Configure agent**.
 
-   ![New agent form with name and role fields](../../user-guides/screenshots/light/agents/new-agent-name-role.png)
+   ![The "Meet your next agent" dialog asking for the new agent's name](../../user-guides/screenshots/light/agents/new-agent-name-role.png)
 
-3. **Set "Reports to" to the CEO**
+3. **Finish setup**
 
-   In the **Reports to** dropdown, select your CEO agent. This places the new agent one level below the CEO in the hierarchy.
+   On the setup page, connect your model provider if asked, choose a model, run **Test your agent**, and click **Finish setup**. See [Agent Adapters](./agent-adapters.md) if you need help with this step.
 
-   ![New agent form showing the Reports to dropdown with CEO selected](../../user-guides/screenshots/light/agents/new-agent-reports-to-field.png)
+   New agents report to your CEO automatically, so a manager is already one level below the CEO in the hierarchy when setup finishes.
 
-4. **Choose an adapter and save**
+4. **Give it a title (and check its manager)**
 
-   Configure the adapter (see [Agent Adapters](./agent-adapters.md) if you need help with this step). Click **Create agent**.
+   Click **Edit configuration** on the confirmation screen (or open the agent and click **Harness / Runtime** in its side menu). In the **Agent identity** card, add a **Title** (e.g. "CTO") and confirm **Reports to** shows your CEO. Click **Save changes**.
 
-   The new agent now appears in the org chart under the CEO, and the CEO will start considering them when delegating work. You can set the agent's budget afterward on its **Budget** tab.
+   ![The Agent identity card on Harness / Runtime, with the Reports to picker open and the CEO selected](../../user-guides/screenshots/light/agents/new-agent-reports-to-field.png)
+
+   The new agent now appears in the org chart under the CEO, and the CEO will start considering them when delegating work. Agent budgets are managed from **Audit → Budgets**.
 
 ---
 
 ## Adding workers
 
-Workers report to a manager rather than directly to the CEO. The steps are identical to adding a manager, but you set **Reports to** to a manager-level agent instead of the CEO.
+Workers report to a manager rather than directly to the CEO. The steps are identical to adding a manager — except that, after setup, you change **Reports to** from the CEO to a manager-level agent.
 
 For example, to add a Backend Engineer who reports to your CTO:
 
-1. Click **New Agent**
-2. Name: "Jordan — Backend Engineer", role: `backend_engineer`
-3. **Reports to**: select your CTO agent
-4. Configure the adapter, then **Create agent**
+1. Click **New Agent**, name it "Jordan", and pick an adapter
+2. Configure the adapter, then click **Finish setup**
+3. Open **Harness / Runtime**, set **Title** to "Backend Engineer" and **Reports to** to your CTO
+4. Click **Save changes**
 
 The CTO can now delegate subtasks to Jordan. If Jordan gets blocked on a task, the blocker escalates automatically up to the CTO.
 
@@ -120,30 +123,30 @@ The CTO can now delegate subtasks to Jordan. If Jordan gets blocked on a task, t
 
 You can reassign an agent to a different manager at any time — after a reorg, or when you want to move someone to a different workstream.
 
-From the agent's detail page, click **Configuration**, then change the **Reports to** field. The change takes effect immediately. Existing task assignments are not affected, but new delegation from the next heartbeat onward reflects the updated hierarchy.
+Open the agent, click **Harness / Runtime** in its side menu, and change **Reports to** in the **Agent identity** card. Click **Save changes** and the change takes effect immediately. Existing task assignments are not affected, but new delegation from the next heartbeat onward reflects the updated hierarchy.
 
 ---
 
 ## Viewing the org chart
 
-Click **Org** in the left sidebar. You'll see a visual tree of all your agents with their current status shown inline.
+Click **Agents** in the left sidebar, then click the **Org chart view** button (next to **New Agent**). You'll see a visual tree of all your agents with their current status shown inline. Click **List view** to switch back.
 
-![Org chart view showing the full reporting hierarchy with agent status indicators](../../user-guides/screenshots/light/org/org-chart-small-team.png)
+![The Agents page in Org chart view, showing the full reporting hierarchy with agent status indicators](../../user-guides/screenshots/light/org/org-chart-small-team.png)
 
 ---
 
 ## The org chart view
 
-The Org page renders your company as an **interactive tree**. Each agent is shown as a card at the position its reporting line dictates — the CEO sits at the top, managers fan out below it, and individual contributors sit under their managers. Lines between cards are the reporting relationships; they always point from manager down to report.
+The org chart view renders your company as an **interactive tree**. Each agent is shown as a card at the position its reporting line dictates — the CEO sits at the top, managers fan out below it, and individual contributors sit under their managers. Lines between cards are the reporting relationships; they always point from manager down to report.
 
 The card itself surfaces everything you usually need at a glance:
 
-- Agent **icon** with a small coloured **status dot** (green for active, yellow for paused or idle, red for error, cyan for running, grey for terminated).
+- The agent's **character** with a small coloured **status dot** (green for active, yellow for paused or idle, red for error, cyan for running, grey for terminated).
 - The agent's **name** and **title** (or a humanised role label when no custom title is set).
 - The **adapter type** in a small mono font — useful when auditing which adapters your org relies on.
 - A **capabilities** snippet: the first couple of lines of the agent's capabilities description.
 
-Two companion buttons live above the chart: **Import company** and **Export company**, which take you to the import/export flows when you want to share or clone an org.
+The filter tabs above the chart (**All**, **Active**, **Paused**, **Error**, plus **Built-in** when the experimental **Built-in Agents** setting is on) work here too, so you can see just the paused part of your org, for example. To share or clone an org, use **Export** and **Import** in company settings — see [Export & import](../power/export-import.md).
 
 ![Interactive org chart showing the CEO at the top with managers and workers connected by reporting lines](../../user-guides/screenshots/light/org/chart.png)
 
@@ -154,9 +157,9 @@ The chart area supports full pan and zoom:
 - **Drag** anywhere on the background to pan — the cursor switches to a grab hand to make this obvious.
 - **Scroll / pinch** to zoom in and out. Zoom anchors to the mouse position, so you can lean into a specific team without losing your place.
 - Use the **+**, **−**, and **Fit** buttons in the top-right corner for precise zoom control. **Fit** recentres the whole chart inside the viewport, which is handy after a reorg when the tree has grown off-screen.
-- **Click a card** to open the full agent detail page. Dragging on a card does not pan — clicks are always routed to the agent.
+- **Click a card** to open the agent's page. Dragging on a card does not pan — clicks are always routed to the agent.
 
-For the text-only reporting view, the sidebar **Org** entry also exposes a collapsible tree (used by screen readers and by anyone who prefers a compact outline). The two views share the same underlying hierarchy; changes made in one appear in the other immediately.
+For a text-only view, switch to **List view**. It shows the same agents as a flat list sorted by name, without the reporting lines — use the org chart when you want to see who reports to whom. Changes made on an agent's page appear in both views.
 
 ---
 
@@ -164,11 +167,11 @@ For the text-only reporting view, the sidebar **Org** entry also exposes a colla
 
 You can reassign any agent to a different manager without leaving the chart. The flow is:
 
-1. **Click the card of the agent you want to move.** The chart opens the agent's detail page.
-2. **Switch to the Configuration tab** and change the **Reports to** field to the new manager.
-3. **Save.** The reporting line is updated immediately, and when you return to the Org page, the card re-parents under the new manager. Existing task assignments are unaffected — only future delegation follows the new line.
+1. **Click the card of the agent you want to move.** The chart opens the agent's page.
+2. **Click Harness / Runtime** in the agent's side menu and change **Reports to** in the **Agent identity** card to the new manager.
+3. **Click Save changes.** The reporting line is updated immediately, and when you return to the org chart, the card re-parents under the new manager. Existing task assignments are unaffected — only future delegation follows the new line.
 
-![Agent configuration with the Reports to dropdown expanded, selecting a new manager](../../user-guides/screenshots/light/org/reassign.png)
+![The Agent identity card on Harness / Runtime with the Reports to picker open, selecting a new manager](../../user-guides/screenshots/light/org/reassign.png)
 
 A few guardrails apply:
 
@@ -176,7 +179,7 @@ A few guardrails apply:
 - You cannot remove the CEO's own reporting line — the CEO always reports to the board.
 - Reassigning a manager with reports moves the whole subtree under the new parent; the reports themselves keep their own reporting lines.
 
-> **Tip:** If you are doing a bigger reorg (swapping teams between two managers, for example), open the Org page in one tab and the agent configuration in another. The chart refreshes automatically when you save, so you can use it as a live preview of the new structure.
+> **Tip:** If you are doing a bigger reorg (swapping teams between two managers, for example), open the Agents page's org chart view in one browser tab and the agent's Harness / Runtime page in another. The chart refreshes automatically when you save, so you can use it as a live preview of the new structure.
 
 ---
 
@@ -186,8 +189,8 @@ The lines between cards are not just decorative — they encode the company's de
 
 - Every line points from a **manager** (top) to a **direct report** (bottom). The direction of the line mirrors how work and escalations travel: delegation flows down, status and blockers flow up.
 - **Multiple children** share a horizontal connector below the manager card so you can see the span of control at each level.
-- **Separate subtrees** mean separate reporting lines. If you ever end up with more than one root, it usually means an agent lost its manager (for example, after a termination) — fix it from the agent's configuration by setting **Reports to** again.
-- **Terminated agents** appear with a grey dot and faded styling. They stay on the chart as a historical record until you remove them.
+- **Separate subtrees** mean separate reporting lines. If you ever end up with more than one root, it usually means an agent lost its manager (for example, after a termination) — fix it on the agent's **Harness / Runtime** page by setting **Reports to** again.
+- **Terminated agents** don't appear on the chart. If a terminated agent had reports, they move up and show directly under the next visible manager — a cue to give them a new **Reports to**.
 
 Because the chart is the single source of truth for reporting structure, it is the fastest way to spot structural issues: a manager with far too many reports, a worker orphaned without a manager, or an adapter concentration risk where too much of the org runs on the same adapter.
 

docs/guides/org/skills.md

@@ -55,35 +55,44 @@ Skills keep the base context small. An agent with 10 skills doesn't load all 10
 
 ## Adding a skill
 
-Skills are managed from the company-level **Skills** page. The page has a left-hand list of every installed skill and a right-hand pane that shows the selected skill's files, description, and usage. Two controls live above the skill list: a filter box to search by name, key, slug, or source, and an input where you can paste a source string to import a skill from elsewhere.
+Skills are managed from the company-level **Skills** page. A side menu switches between **Installed**, **Discover**, **Sources**, and (under **Author**) **My Skills**. The **Installed skills** view shows every skill in your library as a card, with how many agents use it and where it came from. Click a card to open that skill's detail page.
 
-You can add a skill in one of several ways, depending on where it is coming from.
+Above the cards you'll find a **Search installed skills…** box, a **Sort** menu, a scan button (the circular arrow), and two buttons: **New folder**, for organizing your library, and **+ New ▾**. Every way of adding a skill starts from the **New** menu:
+
+- **Create new skill** — write one from scratch in Skill Studio.
+- **Discover skills** — browse skills from every available source.
+- **Import from GitHub** — link a repository under **Sources**.
+- **Manage sources** — open the **Sources** list.
+- **Import from path or URL** — paste a local path, GitHub URL, or `skills.sh` command.
+- **Import skills from project** — scan a project's workspaces for skills.
+
+The sections below walk through each one, depending on where your skill is coming from.
 
 ### 1. Import from a GitHub repository
 
-If your skills live in a GitHub repository, the best home for them is **Skills → Sources**. Choose **Import from GitHub**, pick a repository, tick the skills you want, and Paperclip keeps them linked to that repository so you can refresh them later. [Sync skills from a GitHub repository](#sync-skills-from-a-github-repository) below walks through it.
+If your skills live in a GitHub repository, the best home for them is **Skills → Sources**. Choose **New → Import from GitHub**, pick a repository, tick the skills you want, and Paperclip keeps them linked to that repository so you can refresh them later. [Sync skills from a GitHub repository](#sync-skills-from-a-github-repository) below walks through it.
 
-You can still paste a GitHub URL (or a `skills.sh` install command) into the source field at the top of the Skills page and press **Add**. A plain GitHub repository, folder, or `SKILL.md` URL is filed under **Sources** too, so it gets the same refresh controls. GitHub-sourced skills are pinned to a specific commit — you can check for updates and upgrade the pin from the skill detail pane.
+You can also choose **New → Import from path or URL**. That opens an **Import a skill** dialog with one field — paste a GitHub URL (or a `skills.sh` install command) and click **Import**. The dialog also links out to **Browse skills.sh** and **Search GitHub** if you're still looking for something. A plain GitHub repository, folder, or `SKILL.md` URL is filed under **Sources** too, so it gets the same refresh controls. GitHub-sourced skills are pinned to a specific commit — you can check for updates and upgrade the pin from the skill detail pane.
 
-![Add skill dialog with the source input, search button, and link to skills.sh](../../user-guides/screenshots/light/skills/add-skill-dialog.png)
+![The Installed skills view, with the search box, Sort menu, scan button, and the New and New folder buttons above the skill cards](../../user-guides/screenshots/light/skills/add-skill-dialog.png)
 
 ### 2. Import from a gist
 
-Gists work through the same source field. Paste the gist URL and Paperclip treats it like a remote file source — useful when you want to share a one-off procedure without setting up a full repository.
+Gists work through the same **Import from path or URL** dialog. Paste the gist URL and Paperclip treats it like a remote file source — useful when you want to share a one-off procedure without setting up a full repository.
 
 ### 3. Import from a local file or folder
 
-You can also paste a local path (Linux, WSL, or Windows) into the source field. Paperclip walks the folder, finds any `SKILL.md` files, and imports them. This is the right choice when you already keep skills in a project workspace on disk — the scan button (circular arrow next to the plus icon) re-runs the local import across every project workspace in the company so newly added `SKILL.md` folders show up automatically.
+You can also paste a local path (Linux, WSL, or Windows) into the **Import from path or URL** dialog. Paperclip walks the folder, finds any `SKILL.md` files, and imports them. This is the right choice when you already keep skills in a project workspace on disk — the scan button (the circular arrow next to **New**, labelled *Scan project workspaces for skills*) re-runs the local import across every project workspace in the company so newly added `SKILL.md` folders show up automatically.
 
 For safety, a local path has to sit inside a folder Paperclip already knows about: your company's managed skills folder, one of your project workspaces, or the folder Paperclip cloned a project into for you (a managed checkout). That last one means a project Paperclip checks out on your behalf can import its own skills in place, even if it has no workspace registered. A path anywhere else is refused with *"Local skill source is outside approved company workspace roots"* — add the folder as a project workspace first, or copy the skill somewhere Paperclip manages.
 
 ### 4. Import from the skills.sh marketplace
 
-[skills.sh](https://skills.sh) is a community catalog of ready-made skills. Each listing provides a copy-ready install command; paste it into the source field and Paperclip imports the skill along with its source metadata (you will see a small skills.sh badge on the skill row).
+[skills.sh](https://skills.sh) is a community catalog of ready-made skills. Each listing provides a copy-ready install command; paste it into **New → Import from path or URL** and Paperclip imports the skill along with its source metadata (you will see a small skills.sh badge on the skill row).
 
 ### 5. Import skills straight from a project
 
-If your skills already live in a repository that one of your projects points at, you don't need to hunt for the path yourself. The **Import skills from project** dialog does the looking for you: *"Pick a project, scan its workspaces for skills, and import them as references."*
+If your skills already live in a repository that one of your projects points at, you don't need to hunt for the path yourself. Choose **New → Import skills from project** and the dialog does the looking for you: *"Pick a project, scan its workspaces for skills, and import them as references."*
 
 It walks you through three steps.
 
@@ -91,7 +100,7 @@ It walks you through three steps.
 
 **Choose what to import.** Paperclip scans that project's workspaces for `SKILL.md` files and shows everything it found, grouped by workspace and then by the folder it was found in. Tick the ones you want. A **Search discovered skills…** box narrows a long list. If a skill's slug collides with something already in your library, the row is flagged as a conflict and an **Import as** field appears so you can give the incoming copy a different, lowercase URL-safe slug instead of overwriting anything.
 
-If the scan comes up empty you'll see **No skills found**, along with a note about which well-known agent-harness folders were searched. Skills kept somewhere non-standard can still come in through **Import from path or URL** — the same source field described above.
+If the scan comes up empty you'll see **No skills found**, along with a note about which well-known agent-harness folders were searched. Skills kept somewhere non-standard can still come in through **Import from path or URL**, described above.
 
 **Review the result.** The last step summarises how many skills were imported, updated, and skipped, and each imported skill gets an **Open** link straight into Skill Studio.
 
@@ -99,11 +108,12 @@ One thing worth understanding before you use this: *"No files were copied. These
 
 ### Creating a skill from scratch
 
-If none of those sources apply, click the **+** button next to the scan icon. A small form appears inline with three fields:
+If none of those sources apply, choose **New → Create new skill**. Skill Studio opens a **Create a new skill** page that walks you through four steps — **Basics**, **Design**, **Content**, and **Review** — and you can jump between them at any time:
 
-- **Skill name** — the human-readable name shown in the list.
-- **Optional shortname / slug** — the `kebab-case` key the agent uses to reference this skill. If you leave this blank, Paperclip derives it from the name.
-- **Short description** — the routing logic ("Use when… Don't use when…") the agent reads before loading the skill body.
+- **Basics** — the skill name (the human-readable name shown on its card), an optional shortname (the `kebab-case` key the agent uses to reference this skill — leave it blank and Paperclip derives it from the name), and a one-line description. Write the description as routing logic ("Use when… Don't use when…"), because that's what the agent reads before loading the skill body.
+- **Design** — a **Color** for the skill's tile and optional **Categories**.
+- **Content** — the instructions body itself.
+- **Review** — check everything and pick the **Sharing** scope (**Organization** or **Private**).
 
 Click **Create skill** and the skill is added to the library as a Paperclip-managed, editable entry.
 
@@ -330,7 +340,7 @@ For the policy document shape, the eight skill actions, and how a decision is re
 
 ## File inventory
 
-Every skill is a folder, not a single file. Expanding a skill in the sidebar reveals its **file inventory** — the full tree of files underneath the skill's root. The inventory pinpoints each file with a few pieces of metadata that matter in practice:
+Every skill is a folder, not a single file. Open a skill's detail page and switch to its **Files** tab (next to **Overview**, **Versions**, and **Agents**) to see its **file inventory** — the full tree of files underneath the skill's root. The inventory pinpoints each file with a few pieces of metadata that matter in practice:
 
 - **Entry file** — the top-level `SKILL.md` that agents read first. It is always sorted to the top of the tree and contains the skill's frontmatter (name, description) plus the instructions body.
 - **Other files** — subfolders such as `references/` or `scripts/` hold supporting material (examples, style guides, helper scripts). The file kind icon tells you at a glance whether each leaf is markdown, a reference document, or a script.
@@ -338,24 +348,27 @@ Every skill is a folder, not a single file. Expanding a skill in the sidebar rev
 - **Deprecated** — when a skill is retired, it is marked deprecated in the library and hidden from agent skill menus. Existing agents keep working until you detach the skill from them.
 - **Virtual** — some entries in the inventory are virtual: they represent content the adapter synthesises at runtime (for example, materialised runtime skills for adapters that do not support skills natively). Virtual entries are tagged in the row and cannot be edited directly.
 
-![Skill detail pane showing the file tree with SKILL.md plus a references folder, and metadata badges for source, pin, key, and editable state](../../user-guides/screenshots/light/skills/file-inventory.png)
+![A skill's detail page on the Files tab, with SKILL.md in the file list, View, Code, and Edit controls above the rendered file, and the Location, Tags, Agents, and Source column on the right](../../user-guides/screenshots/light/skills/file-inventory.png)
 
-The header above the file viewer shows:
+Above the file viewer you'll see the file's name, a **View** / **Code** toggle, and **Edit** when the skill is editable. The skill's metadata sits in a column on the right of the page, whichever tab you're on:
 
-- The **Source** badge (skills.sh, GitHub, local folder, or Paperclip) with the source label — clicking the label copies the path to the workspace when applicable.
-- The **Pin** for GitHub-sourced skills — the short commit SHA Paperclip is locked to, plus a **Check for updates** button and, when an update exists, an **Install update** action.
-- The skill **Key** (the stable identifier adapters use).
-- The **Mode** — Editable or Read only.
-- **Used by** — the list of agents currently attached to this skill.
+- **Location** — the folder the skill is filed in, with **Copy path** and **Move** buttons.
+- **Tags** — the skill's tags, with an **Add a tag…** field.
+- **Agents** — the agents currently attached to this skill, with an **Add to agent** button.
+- **Source** — where the skill came from (for example a Paperclip workspace, a local folder, or GitHub), with its path or locator underneath.
+- **Updates** — GitHub-sourced skills only. Shows the pinned commit Paperclip is locked to, a **Check for updates** button and, when an update exists, an **Install update** action.
+- **Settings** — the skill's configuration, at the bottom of the column.
+
+The skill **Key** (the stable identifier adapters use) and its **Mode** (Editable or Read only) live on the **Overview** tab, in the details under **About**.
 
 ---
 
 ## Adapter sync preferences
 
-Different adapters handle skills differently. The Agent → Skills tab surfaces this as a **skill application mode** just above the skill list:
+Different adapters handle skills differently. The Agent → Skills tab surfaces this as a small **skill application mode** badge next to the "*N* of *M* enabled" count, above the skill list — hover it for details:
 
-- **Kept in the workspace** (`persistent`) — the adapter writes skill files into the agent's workspace directory and leaves them there between runs. Most long-running local adapters use this mode.
-- **Applied when the agent runs** (`ephemeral`) — the adapter materialises skill files for each run, then cleans up afterwards. This is the default for sandboxed adapters that treat the workspace as disposable.
+- **Kept in workspace** (`persistent`) — the adapter writes skill files into the agent's workspace directory and leaves them there between runs. Most long-running local adapters use this mode.
+- **Applied on next run** (`ephemeral`) — the adapter materialises skill files for each run, then cleans up afterwards. This is the default for sandboxed adapters that treat the workspace as disposable.
 - **Tracked only** (`unsupported`) — Paperclip cannot push skills into the adapter, so it only records which skills you have assigned. Adapters like `openclaw_gateway` fall into this category; you will see a banner directing you to manage skills inside the remote runtime (for example, OpenClaw) rather than from Paperclip.
 
 Assignments still save regardless of mode — the mode only controls whether Paperclip physically syncs the skill files. Warnings surface in an amber banner when, for example, a desired skill is missing from the company library or the adapter rejected a sync.
@@ -364,21 +377,25 @@ Assignments still save regardless of mode — the mode only controls whether Pap
 
 ## Assigning a skill to an agent
 
-Skills live at the company level, but each agent decides which of those skills to use. To assign or remove skills for an agent:
+Skills live at the company level, but each agent decides which of those skills to use. You can attach skills from either side: from the skill, or from the agent.
+
+**From the skill.** Open the skill's detail page from the **Installed** view. In the right-hand column, under **Agents**, click **Add to agent**. A picker opens with a **Filter agents** box, a **Version** menu, and a checkbox per agent — tick the agents that should get the skill and click **Save**.
+
+![A skill's detail page with the Add to agent picker open, showing the agent checklist and the Version menu](../../user-guides/screenshots/light/skills/assign-to-agent.png)
+
+**From the agent.** To see and change everything one agent uses:
 
 1. **Open the agent's detail page** from the Agents list or the org chart.
-2. **Switch to the Skills tab.**
-3. You will see three groups:
-   - **Required skills** — entries the adapter marks as mandatory. You cannot disable these.
-   - **Optional skills** — every skill in the company library that the agent *could* use. Each row has a checkbox; tick it to assign the skill, untick to detach.
-   - **Unmanaged skills** — read-only rows for skills the adapter picked up from somewhere Paperclip does not control (for example, a global skill bundle on the host). These are shown for visibility only.
-4. Changes autosave about 250 ms after you stop clicking — the small "Saving soon..." / "Saving changes..." indicator in the top-right confirms when Paperclip has persisted the update. The agent will pick up the new skill list on its next run.
+2. **Switch to the Skills tab.** The top line reads "*N* of *M* enabled", next to the skill application mode badge and a **Search skills** box.
+3. You will see these groups:
+   - **Enabled on this agent** — the skills this agent uses now. Flip a row's switch off to detach it.
+   - **Available from the library** — every other skill in the company library that the agent *could* use. Flip a row's switch on to assign it.
+   - **Automatic and detected skills (read-only)** — a collapsible group for skills the adapter supplies or picked up from somewhere Paperclip does not control (for example, a global skill bundle on the host). These are shown for visibility only.
+4. Changes autosave shortly after you stop clicking — a small status chip shows "Saving soon…", then "Saving…", then "Saved". The agent will pick up the new skill list on its next run.
 
-![Agent Skills tab with required, optional, and unmanaged sections, plus a link to the company skill library](../../user-guides/screenshots/light/skills/assign-to-agent.png)
+A **Browse skills store** button at the top of the tab jumps to the company-wide Skills page, so you can open the underlying skill to tweak its instructions without losing your place.
 
-A **View company skills library** link at the top of the tab jumps back to the company-wide Skills page, so you can open the underlying skill to tweak its instructions without leaving context.
-
-> **Tip:** If a skill you expect is not in the optional list, it is not in the company library yet. Add it from the Skills page first, then come back.
+> **Tip:** If a skill you expect is not under **Available from the library**, it is not in the company library yet. Add it from the Skills page first, then come back.
 
 You may notice a `first-task` skill in your library and on the first agent you created during onboarding. That's Paperclip's own guide for your very first task — how the agent reads your answer to the opening question, proposes a plan or a single task, and waits for your go-ahead before hiring or doing the work. It only applies to that onboarding task, not to the agent's other work, and other agents don't get it automatically.
 
@@ -392,7 +409,7 @@ The bundled `paperclip` skill — the base procedure every agent follows on each
 
 ### Turn it on first
 
-The picker stays hidden until someone enables it. Open **Settings → Instance settings → Experimental** and flip the **Beta skills** card: *"Allow agents to pin beta releases of the Paperclip core skill. Disabling this returns every agent to the default live skill without removing saved pins."*
+The picker stays hidden until someone enables it. Open **Settings → Experimental** and flip the **Beta skills** card: *"Allow agents to pin beta releases of the Paperclip core skill. Disabling this returns every agent to the default live skill without removing saved pins."*
 
 It is off by default everywhere — cloud and self-hosted alike — and it is not one of the cloud-managed flags, so it stays yours to turn on and off on any instance. See [Experimental features](../../experimental/overview.md) for how that page behaves.
 

docs/guides/projects-workflow/custom-sandbox-images.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.707.0
+paperclip_version: v2026.1012.0
 seo_title: Custom Sandbox Images
 seo_description: Stop re-installing the same CLIs and dependencies on every run. Build and capture a sandbox image, then manage which one future runs start from.
 ---
@@ -20,7 +20,7 @@ This guide covers how to turn the feature on, where it lives, how to build and c
 
 Custom images are part of sandbox environments, and environments are an **experimental** feature — the whole environments UI is hidden until you opt in.
 
-1. Go to **Settings → Instance settings → Experimental**.
+1. Go to **Settings → Experimental**.
 2. Turn on **Enable Environments**.
 
 That switch is described in the UI as *"Show environment management in company settings and allow project and agent environment assignment controls."* With it on, an **Environments** screen appears under **Settings → Instance settings**, where you create and edit the environments your agents run in.

docs/guides/projects-workflow/projects.md

@@ -1,7 +1,7 @@
 ---
-paperclip_version: v2026.529.0
+paperclip_version: v2026.1012.0
 seo_title: Projects: Grouping Related Work
-seo_description: Projects bind work to a repository, a working directory, and a budget envelope. Tour the overview, issues, workspaces, configuration, and budget tabs.
+seo_description: Projects bind work to a repository, a working directory, and a budget envelope. Tour the tasks, workspaces, configuration, and budget tabs.
 ---
 
 # Projects
@@ -10,31 +10,35 @@ A project is the container Paperclip uses to group related work. If goals answer
 
 Every issue in Paperclip lives under a project. Every execution workspace is scoped to a project. Budgets can be pinned to a project. When you tell an agent "work on the marketing site", you are really telling it "work on issues in the Marketing Site project, using the code and configuration the project points at". Projects are how the abstract strategy the CEO writes becomes something concrete an agent can check out and run.
 
-This guide walks through the project list, then the five tabs you see when you open a project: **Overview**, **Issues**, **Workspaces**, **Configuration**, and **Budget**.
+This guide walks through the project list, then the tabs you see when you open a project: **Tasks**, **Workspaces**, **Configuration**, and **Budget** (plus any tabs your plugins add, such as **Files**).
 
 ---
 
 ## Project List
 
-The Projects page lists every active (non-archived) project in the currently selected company, sorted by creation order, with an **Add Project** button in the top right.
+The Projects page lists every active (non-archived) project in the currently selected company. A **Sort: Name** control sits at the top left and an **Add Project** button at the top right.
 
-![Project list](../../user-guides/screenshots/light/projects/list.png)
+![The Projects page with the Sort: Name control, a My Projects section listing two projects, and the Add Project button](../../user-guides/screenshots/light/projects/list.png)
+
+Projects are grouped into **My Projects** and, if you've left any, **Other Projects** (shown dimmed). Each section header shows how many projects it holds.
 
 ### Row anatomy
 
 Each row is a single project entry. Reading left to right you see:
 
-- **Color swatch** — a small square in the project's color. The color is chosen when the project is created and can be changed on the project detail page. Use it to visually scan related projects; it has no functional meaning.
-- **Project name** — the main title. Clicking anywhere on the row opens the project detail page and defaults to the Issues tab (unless you previously visited the project, in which case Paperclip restores the tab you last used).
-- **Description** (subtitle) — the first line of the project description if one has been set. If the project has no description, this area is empty.
-- **Target date** — the project's target completion date if set. Shown on the right in muted text. Projects without a target date omit this field.
-- **Status badge** — the current project status: `backlog`, `planned`, `in_progress`, `completed`, or `cancelled`. The badge color is consistent with issue status badges used elsewhere in the app.
+- **Project tile** — a small square with the project's icon (a folder unless you've picked another). If the project has a color, the tile is tinted with it; otherwise it stays neutral gray.
+- **Project name** — the main title. Clicking the row opens the project detail page and defaults to the Tasks tab (unless you previously visited the project, in which case Paperclip restores the tab you last used).
+- **Description** (subtitle) — the project description if one has been set. If the project has no description, this area is empty.
+- **Task count** — how many tasks the project holds, for example "9 tasks".
+- **Budget** and **Target date** — shown in muted text only when the project has a budget or a target date set.
+- **Status badge** — the current project status, such as `planned` or `in progress`. The badge color is consistent with issue status badges used elsewhere in the app.
+- **Join / Leave** and a **star** — personal controls for your sidebar (see [Keeping projects (and agents) in your sidebar](#keeping-projects-and-agents-in-your-sidebar)).
 
 Archived projects are filtered out of this list. You can still reach them by following a direct link, and you can unarchive them from the project's Configuration tab.
 
-### Filters and actions
+### Sorting and actions
 
-The list itself does not expose filter controls; it simply shows every active project in the company. If you need to narrow things down, the navigation crumbs at the top of the page and the company switcher in the sidebar are the main tools.
+The list doesn't have filters, but you can change the order. Click **Sort: Name** and choose **Name**, **Updated**, **Created**, or **Target date**. Click the active option again to flip between ascending and descending.
 
 The top-right **Add Project** button opens the New Project dialog, where you can set the name, description, target date, initial status, and color. The Configuration tab is where you come back later to change repository bindings, environment variables, and execution workspace behaviour — the create dialog only covers the minimum a project needs to exist.
 
@@ -52,143 +56,140 @@ Each join or leave is recorded in the company activity log, so the change is aud
 
 ---
 
-## Overview Tab
+## The project header
 
-The Overview tab is the light-weight, human-readable summary of a project. It is the right place to land when someone asks "what is this project about?" without diving into issues or configuration.
+Open a project and the top of the page gives you its identity at a glance:
 
-![Overview tab](../../user-guides/screenshots/light/projects/overview.png)
+- **Icon and color** — click the tile next to the name to pick a different icon or color.
+- **Name** — click it to rename the project inline.
+- **Star** — the star button in the top right pins the project for quick access.
+- **Project summary** — a card where Paperclip's built-in Summarizer agent keeps the latest project status, next step, and operator-needed items. Until the Summarizer is configured, the card shows a **Set up Summarizer** button instead.
 
-### What you see
+Below the header sit the tabs. There's no separate Overview tab any more: the project's description lives on the Configuration tab, and its day-to-day progress lives on the Tasks tab.
 
-- **Description** — an inline-editable markdown block. Click anywhere in the description area to start editing; the value saves when you blur the editor. If there is no description yet, you see a placeholder prompting you to add one. Images can be pasted or dropped and will be uploaded to the project's asset area.
-- **Status** — the current project status rendered as a status badge. To change the status you open the Configuration tab; the Overview tab is read-only for this field.
-- **Target date** — shown when one has been configured. Like status, the Overview tab only displays this; editing lives in Configuration.
+Paperclip doesn't keep a single "percent complete" field for a project. Progress is the shape of the Tasks tab — how many tasks are `todo`, `in_progress`, `in_review`, `done`, or `cancelled`.
 
-### Linked goals and progress
+### Tabs added by plugins
 
-Goals linked to the project are surfaced in the properties panel on the right of the project page (not in the Overview body itself). Linking a project to one or more goals is how the CEO's strategy connects to executable work: a goal describes an outcome, and any project linked to it inherits that outcome as its reason for existing. See the [Goals guide](./goals.md) for how goals are defined and how to link or unlink them.
-
-Progress on a project is implicit: Paperclip does not maintain a single "percent complete" field. Instead, progress is the shape of the Issues tab — how many issues are `todo`, `in_progress`, `in_review`, `done`, or `cancelled`. If you want a rolled-up view, read the Issues tab with the status grouping turned on.
-
-### When to use the Overview tab
-
-Use Overview as:
-
-- A landing page for collaborators who are new to the project.
-- A place to keep a short, living summary of scope and non-goals.
-- The first tab you open when an approval references a project you did not set up.
-
-For everything else — triage, configuration, workspaces, budget — use the other tabs.
+Plugins can add their own tabs after **Budget**. For example, the example File Browser plugin adds a **Files** tab with a file browser and editor for the project's workspace. If you see a tab not covered in this guide, it comes from a plugin installed on your instance.
 
 ---
 
-## Issues Tab
+## Tasks Tab
 
-The Issues tab is the project's task board. It is the same issue list you see on the global Issues page, pre-filtered to this project. For most day-to-day work this is the tab you will spend the most time on.
+The Tasks tab is the project's task board. It's the same task list you see on the global Tasks page, pre-filtered to this project. For most day-to-day work this is the tab you'll spend the most time on, and it's where a project opens by default.
 
-![Issues tab](../../user-guides/screenshots/light/projects/issues.png)
+![Tasks tab](../../user-guides/screenshots/light/projects/issues.png)
 
 ### What is shown
 
-The tab renders the shared issues list component, so the columns, grouping, and sorting controls are identical to the global view:
+The tab uses the shared task list, so the view, grouping, filter, and sort controls are identical to the global view:
 
-- Issues are grouped by status (`todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`, `backlog`) by default.
-- Each row shows the issue identifier, title, assignee, priority, and any live-run indicator when an agent is currently executing against the issue.
+- Each row shows the task identifier, title, status icon, and when it was last updated, plus a live-run indicator when an agent is currently working on it.
+- Sub-tasks nest under their parent, and you can collapse a parent to hide them.
 - Live run indicators refresh every few seconds while the tab is open, so you can watch a run pick up, advance, and finish without refreshing the page.
 
 ### Filtering and view state
 
-Your view settings on this tab — grouping, sort order, which statuses are collapsed — are persisted separately from the global issues view under a per-project key. Switching to another project and back restores the same layout. Switching to the global issues list does not disturb the project-scoped view.
+Your view settings on this tab — grouping, sort order, which groups are collapsed — are saved separately from the global task view, per project. Switching to another project and back restores the same layout. Switching to the global task list doesn't disturb the project-scoped view.
 
-There is no separate "filter by project" control here because the list is already scoped to the project. You can still filter by assignee, priority, label, or free-text search within the project.
+There's no "filter by project" control here because the list is already scoped to the project. You can still filter by status, responsible agent or person, creator, label, and more from the **Filter** button, or use the **Search tasks...** box.
 
-### Creating issues in the project
+### Creating tasks in the project
 
-Issues created from this tab default to the current project, so you do not have to set the project field by hand. If you need to create an issue in a different project, either switch to that project first or use the global issue creation dialog and pick the project explicitly.
+Tasks created with the **New Task** button on this tab default to the current project, so you don't have to set the project field by hand. To create a task in a different project, switch to that project first or use the global **New Task** dialog and pick the project explicitly.
 
 ### Relationship to execution workspaces
 
-Each issue may be tied to an execution workspace — a specific working copy of the project's code — when the issue is picked up by an agent. The Workspaces tab (next section) groups issues by the workspace they are running in, which is often a more useful lens once work is in flight. See [Execution Workspaces](./workspaces.md) for the underlying model.
+Each task may be tied to an execution workspace — a specific working copy of the project's code — when an agent picks it up. The Workspaces tab (next section) groups tasks by the workspace they're running in, which is often a more useful lens once work is in flight. See [Execution Workspaces](./workspaces.md) for the underlying model.
 
 ---
 
 ## Workspaces Tab
 
-The Workspaces tab shows the execution workspaces currently attached to the project. It only appears when the company has the **isolated workspaces** experimental setting enabled and the project has at least one non-default workspace with activity. On projects without isolated workspaces, Paperclip redirects you to the Issues tab instead.
+The Workspaces tab shows the workspaces attached to the project: the project's own checkout plus any execution workspaces agents have created. It only appears when the **isolated workspaces** experimental setting is enabled for your instance. Without it, Paperclip sends you to the Tasks tab instead.
 
 ![Workspaces tab](../../user-guides/screenshots/light/projects/workspaces.png)
 
-### What a workspace row represents
+### What a workspace card shows
 
-Each row on the Workspaces tab is a summary card combining:
+Each workspace is a card. A tag at the top tells you which kind it is — **Execution workspace** or **Project workspace** — next to when it was last updated and, if it has runtime services, how many are running. Inside the card you'll find:
 
-- A workspace identity — its name, underlying working directory or git worktree path, and status.
-- The issues currently running in that workspace, so you can see what work is tied to it.
-- Runtime service controls — Start, Stop, and Restart buttons for any runtime services the workspace exposes (dev servers, watchers, databases). Runtime services are not auto-started; you control them from this card.
-- A **Close workspace** action that opens the workspace close dialog. Closing a workspace stops its runtime services and archives it.
+- The workspace name, plus its branch, path, and any running service URL. Copy buttons sit next to the branch and path.
+- **Linked tasks** — the tasks currently tied to that workspace, so you can see what work is running there.
+- **Start services** / **Stop services** — controls for any runtime services the workspace defines (dev servers, watchers, databases). Runtime services aren't auto-started; you control them from this card.
+- **Close workspace** — on execution workspaces only. It opens the close dialog; closing stops the workspace's runtime services and archives it.
 
-Workspaces whose status is `cleanup_failed` are grouped into a separate section labelled **Cleanup attention needed**, rendered in amber. These are workspaces that could not be fully torn down and need a human decision — either retry the close action, or investigate the underlying path manually.
+Execution workspaces whose status is `cleanup_failed` are grouped into a separate section labelled **Cleanup attention needed**, rendered in amber. These couldn't be fully torn down and need a human decision: use **Retry close** on the card, or investigate the underlying path yourself.
 
-### Project primary vs. isolated workspaces
+### Project workspace vs. execution workspaces
 
-The project's primary working directory is not shown as a separate row here — it is the implicit default every issue runs in when no isolated workspace is provisioned. This tab lists the non-default workspaces only. For the full mental model of primary, isolated, and reused workspaces, see [Execution Workspaces](./workspaces.md).
+The project's primary checkout always shows up here as a **Project workspace** card (in the screenshot above, the one called `main`). It's the default every task runs in when no isolated workspace is provisioned, so it has no close control. Execution workspaces are the isolated checkouts Paperclip creates for individual tasks. For the full mental model of primary, isolated, and reused workspaces, see [Execution Workspaces](./workspaces.md).
 
 ### When agents create workspaces
 
-Agents create isolated workspaces implicitly when they pick up an issue that is configured to run in isolation, or when you explicitly request one. The Workspaces tab is the place to monitor, manage, and close those workspaces over time. If the list grows long, closing the oldest completed ones is safe — once the underlying branch has been merged or discarded, the workspace no longer serves a purpose.
+Agents create isolated workspaces when they pick up a task that's configured to run in isolation, or when you explicitly request one. The Workspaces tab is where you monitor, manage, and close them over time. If the list grows long, closing the oldest completed ones is safe — once the underlying branch has been merged or discarded, the workspace no longer serves a purpose.
 
 ---
 
 ## Configuration Tab
 
-The Configuration tab is where the project's editable properties live. Most of these fields auto-save as you edit: you will see a small **Saving / Saved / Failed** indicator next to the field, and there is no explicit save button.
+The Configuration tab is where the project's editable properties live. Most fields save as you edit: you'll see a small **Saving** / **Saved** indicator next to the field label. The one exception is the source repositories section, which has its own **Save changes** button (described below).
 
 ![Configuration tab](../../user-guides/screenshots/light/projects/configuration.png)
 
 ### Basic properties
 
 - **Name** — the project name shown in the list and in every breadcrumb. Changing it is safe; links that use the project's slug continue to resolve.
-- **Description** — the full description, rendered as markdown. Matches the description on the Overview tab; edit either location and the value stays in sync.
-- **Status** — one of `backlog`, `planned`, `in_progress`, `completed`, or `cancelled`. Use this to communicate the overall state of the project to the team and to the CEO; it does not affect whether agents can pick up issues in the project.
-- **Goals** — the list of goals the project is linked to. Add or remove goal links here; linked goals appear on the Overview area and in the properties panel. See the [Goals guide](./goals.md) for the goal model.
+- **Description** — the full description, rendered as markdown. Click it to edit; it saves when you leave the editor.
+- **Env** — environment variables for the project (see below).
+- **Updated**, **Target Date**, and **Created** — read-only dates. Target Date only appears when the project has one.
 
-### Repository binding and working directory
+### Source repos
 
-Projects can be bound to either a local folder (`cwd`), a remote repository (`repoUrl`), or both:
+The **Source repos** section (marked optional) is where you connect the project to GitHub:
 
-- **Local folder only** — for projects where the code lives on the machine Paperclip is running on. Agents work directly in this folder (or in isolated worktrees derived from it).
-- **Remote repository only** — for projects where Paperclip clones or references a remote repository. Useful when no local checkout exists yet.
-- **Both** — the most common setup: a local checkout that also tracks a remote URL. Both references are kept so tooling that needs one or the other has it available.
+- **Add GitHub repo** picks a repository from your connected GitHub accounts. If you haven't connected GitHub yet, you can connect it from here. Once a repo is added, the button becomes **Add another repo**.
+- **Existing repo URL** shows a repository URL bound the older way, as a plain link. Click **Edit** to change it.
 
-The **Choose path** action helps you pick a local folder via the native OS file picker.
+Repository changes don't auto-save. When you've made your picks, click **Save changes** (or **Discard changes** to undo). You'll see **Changes saved** once they're stored.
+
+### Codebase and local folder
+
+Below the first divider, the **Codebase** section shows where the project's code lives on the machine running Paperclip. Use **Set local folder** (or **Change local folder**) to point the project at a directory. Agents work directly in this folder, or in isolated worktrees derived from it. If the project's primary workspace defines runtime services, they're listed here too.
 
 ### Environment variables
 
-Each project can define environment variables that are injected into agent runs and execution workspace commands. These are managed through the environment variable editor on this tab:
+Each project can define environment variables that are injected into agent runs and execution workspace commands. You manage them in the **Env** row:
 
-- Add, rename, and delete variables inline.
+- Use **Add variable** to add one, and rename or delete variables inline.
 - Secret-valued variables are stored via the secrets store and rendered masked.
-- Variables set at the project level override nothing at the company level; they simply extend the environment an agent sees when it runs inside this project.
+- Project variables extend the environment an agent sees when it runs inside this project; they don't change anything at the company level.
 
 ### Execution workspace configuration
 
-When isolated workspaces are enabled for the company, the Configuration tab exposes the per-project knobs:
+When isolated workspaces are enabled, the Configuration tab shows an **Execution Workspaces** section with the per-project knobs:
 
-- **Execution workspace enabled** — whether this project participates in isolated workspaces at all. If off, every issue runs in the project primary workspace.
-- **Default mode** — the default workspace mode for new issues: isolated (new workspace), reuse existing, or project primary. Individual issues can override.
+- **Enable isolated task checkouts** — whether this project uses isolated workspaces at all. If off, every task runs in the project's primary checkout.
+- **New tasks default to isolated checkout** — when on, new tasks get their own isolated workspace by default. When off, new tasks stay on the primary checkout unless someone opts in. Individual tasks can override.
+- **Shared workspace concurrency** — how runs share the primary checkout: **Auto**, **Serialize**, or **Allow**.
+
+Click **Show advanced checkout settings** for the rest:
+
+- **Environment** — which environment isolated runs use (only shown when environments are enabled and more than one is available).
 - **Base ref** — the git ref (branch, tag, or commit) new isolated workspaces branch from.
-- **Branch template** — the naming convention Paperclip uses when it creates new branches for isolated workspaces (e.g. a template that includes the issue identifier).
-- **Worktree parent directory** — where Paperclip places new git worktrees on disk.
-- **Provision command** — an optional command run after a new workspace is created (for example, to install dependencies).
+- **Branch template** — the naming convention Paperclip uses for new branches (for example, a template that includes the task identifier).
+- **Worktree parent dir** — where Paperclip places new git worktrees on disk.
+- **Provision command** and **Runtime provision command** — optional commands run when a new workspace is set up (for example, to install dependencies).
 - **Teardown command** — an optional command run before a workspace is closed.
 
-These settings map to the behaviours described in [Execution Workspaces](./workspaces.md). You will usually set them once per project and rarely touch them again.
+These settings map to the behaviours described in [Execution Workspaces](./workspaces.md). You'll usually set them once per project and rarely touch them again.
 
 ### Archive and unarchive
 
-At the bottom of the Configuration tab is the **Archive** action. Archiving hides the project from the project list and from most pickers, but it does not delete anything: issues, workspaces, and history remain intact. Archived projects can be unarchived from the same control.
+At the bottom of the Configuration tab, in the **Danger Zone**, is the **Archive project** button. Paperclip asks you to **Confirm** before it archives. Archiving hides the project from the sidebar and project selectors, but it doesn't delete anything: tasks, workspaces, and history stay intact. On an archived project the same control reads **Unarchive project**.
 
-When you archive, the page navigates back to the dashboard and shows a confirmation toast. If the archive fails (for example because of a server error), a failure toast appears and the project remains active.
+When you archive, the page navigates back to the dashboard and shows a confirmation toast. If the archive fails (for example because of a server error), a failure toast appears and the project stays active.
 
 ### Pause by budget hard stop
 

docs/guides/projects-workflow/routines.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.1005.0
+paperclip_version: v2026.1012.0
 seo_title: Heartbeats and Routines: Scheduling Work
 seo_description: Why timer heartbeats are opt-in, and how routines schedule recurring work without paused agents, surprise token bills, or a dashboard you fight with.
 ---
@@ -92,32 +92,36 @@ For most cases the defaults (coalesce if active, skip missed) are what you want:
 
 ![Routines list](../../user-guides/screenshots/light/routines/list.png)
 
-The Routines page is reached from the sidebar and opens on a **Routines** tab plus a **Recent Runs** tab. The header shows the total count of routines and a **Create routine** button.
+The Routines page is reached from **Routines** in the sidebar. There are no tabs: the header carries a **View all runs** button and a **Create routine** button, and the routine list sits right below, with a count of how many routines are in view.
 
-### List columns and badges
+### List rows and badges
 
-Each routine row surfaces:
+Each routine row shows:
 
 - **Title** — the routine name. A small grey label appears beside it when the routine is not active: `paused`, `draft` (no default agent assigned), or `archived`.
-- **Project** — a coloured square and the project name, or "No project" when the routine has none set.
+- **Project** — a coloured dot and the project name, or "No project" when the routine has none set.
 - **Default agent** — the agent's icon and name, or "No default agent" for drafts.
-- **Last run** — a localised timestamp for the most recent execution, followed by its status (for example `succeeded`, `failed`, `running`). Rows that have never fired show "Never".
-- **Enabled toggle** — a large switch that flips the routine between `active` and `paused`. The label to the right reads `On`, `Off`, `Draft`, or `Archived`. The toggle is disabled for archived routines.
-- **More menu** — a kebab that exposes `Edit`, `Run now`, `Pause`/`Enable`, and `Archive`/`Restore`.
+- **Last run** — a localised timestamp for the most recent execution, followed by its status. Rows that have never fired show "Never".
+- **Run now** — a button that fires the routine straight away (see below).
+- **Enabled toggle** — a switch that flips the routine between `active` and `paused`. The label beside it reads `On`, `Off`, `Draft`, or `Archived`. The toggle is disabled for archived routines.
+- **More menu** — the `⋯` button exposes **Edit**, **Run now**, **Pause**/**Enable**, and **Archive**/**Restore**.
 
-Clicking the row opens the detail page. Actions inside the toggle and dropdown do not navigate — they stay on the list.
+Clicking the row opens the detail page. The buttons, toggle, and menu don't navigate — they keep you on the list.
 
-### Grouping and filtering
+### Folders, sorting, and grouping
 
-Above the list you'll find a **Group** popover with three options:
+Routines can live in folders. By default the list is grouped by folder, and routines you haven't filed yet sit in an **Unfiled** group. Until you've made a folder, a banner suggests grouping your routines, with a **Create your first folder** button (you can dismiss it), and the toolbar shows a **New folder** button.
 
-- **Project** — groups routines by their default project, with "No project" as its own section.
-- **Agent** — groups by default assignee, with "Unassigned" for draft routines.
-- **None** — the flat default.
+Once you have folders, a folder rail lets you jump between **All routines**, each folder, and **Unfiled**. Use a folder's menu to **Rename** it, **Edit color**, or **Delete** it — deleting a folder moves its routines to Unfiled rather than deleting them. To file several routines at once, click **Select**, tick the routines, and use **Move to...**; click **Done** when you're finished.
 
-Group headers are collapsible and their open/closed state is persisted per company in local storage, along with the chosen grouping, so reloading keeps your view.
+Two controls sit above the list:
 
-The list does not have a separate text search — the count in the header and the collapsible groups are the main way to navigate larger libraries.
+- **Sort** — order routines by **Updated**, **Created**, **Last run**, or **Title**. Click the active option again to flip between ascending and descending.
+- **Group** — group by **Folder** (the default), **Project**, **Agent**, or **None**. Project grouping puts routines without one under "No project"; Agent grouping puts drafts under "Unassigned".
+
+Group headers are collapsible, and your sort, grouping, and collapsed groups are remembered per company, so reloading keeps your view.
+
+The list doesn't have a separate text search — folders, grouping, and the collapsible groups are the main way to navigate larger libraries.
 
 ### Creating a routine from the list
 
@@ -136,11 +140,11 @@ Draft routines without a default agent are valid — they save and stay paused u
 - **Pause** flips the routine's status to `paused`. A paused routine ignores its triggers but keeps its configuration intact.
 - **Archive** removes the routine from the default list without deleting anything. Archived routines can be restored later.
 
-### Recent Runs tab
+### Seeing every run
 
-The second tab on the Routines page is a read-only issue list filtered to `originKind = routine_execution`. It uses the same IssuesList component as other issue views, so you get the same columns, live-run indicators, grouping, and inline updates. A background poll refreshes live runs every few seconds so in-flight executions show their progress without a page reload.
+To check on executions, click **View all runs** in the page header. It takes you to the **Runs** section of the Audit area (`/activity/runs`), where every heartbeat run is listed with its status and links to the work it produced. It's the fastest way to answer "did all my morning routines run?"
 
-The Recent Runs view is the fastest way to answer "did all my morning routines run?" — it is routine-scoped but agent-agnostic, and rows link directly to the execution issue they produced.
+If **Streamlined UI** is turned off in Experimental settings, the Routines page instead shows **Routines** and **Recent Runs** tabs. Recent Runs is a task list filtered to the execution tasks your routines created, with live-run indicators that refresh every few seconds.
 
 ---
 
@@ -165,7 +169,7 @@ The left sub-sidebar lists the routine's sections in two groups, and each sectio
 
 The first group holds the editable parts of the template:
 
-- **Overview** — the assignment row ("For [assignee] in [project]"), priority, and the Markdown instructions editor. It also shows a quick summary of the routine's **Triggers** and **Next run** (for a webhook-only routine that reads **On webhook delivery**), plus the five most recent runs with **View all runs** and **View routine activity** links.
+- **Overview** — the assignment row ("For [assignee] in [project]") and the Markdown instructions editor. It also shows a quick summary of the routine's **Triggers** and **Next run** (for a webhook-only routine that reads **On webhook delivery**), plus the five most recent runs with **View all runs** and **View routine activity** links.
 - **Triggers** — every trigger attached to the routine, each as its own card, plus a composer to add new ones.
 - **Variables** — the `{{name}}` placeholders detected in the title and instructions.
 - **Delivery** — the concurrency and catch-up policies.
@@ -200,19 +204,25 @@ Editing the description is a routine save like any other, and Paperclip surfaces
 
 ### Trigger cards and human-readable schedules
 
-On the **Triggers** section, each trigger is a card headed by its kind icon and label. For a schedule trigger, Paperclip shows the cron in **plain English** right under the label — "Every weekday at 09:00", "Every day at 10:00", "Every 15 minutes", "Day 1 of every month at 09:00" — translated from the raw expression as you edit it. (Shapes the translator doesn't recognise simply omit the plain-English line and keep the raw cron.) The card's top-right corner shows a `Next:` line with the resolved local timestamp of the next fire for schedule triggers, a `Webhook` label for webhook triggers, or `API` for manual ones. If a trigger has fired before, its last result also shows there as a badge — red when the last firing failed, neutral otherwise, and simply **Task created** when it produced a task — so you can spot a misfiring webhook without leaving the page.
+On the **Triggers** section, each trigger is a card with its kind icon, a title, and a short status line underneath. For a schedule trigger, the title is the cron in **plain English** — "Every weekday at 09:00", "Every day at 10:00", "Every 15 minutes" — translated from the raw expression. (Shapes the translator doesn't recognise fall back to the title **Schedule**.) The status line shows the schedule's time zone. Other kinds are titled **Webhook**, **GitHub webhook**, or **API trigger**, and their status line tells you how things stand — for example "Ready · Waiting for an event", "Receiving events", or "Authentication failed · Check the key in your app". A paused trigger simply reads **Paused**.
 
-Webhook cards also show the trigger's **Webhook URL** in a read-only field you can click to select and copy, with a reminder to send a POST with `Content-Type: application/json` and to keep the URL private when signing is disabled.
+On the right of each card you'll find an **Edit** button (**Edit schedule**, **Edit webhook**, or **Edit api**) and a trash-can icon that removes the trigger. Removing shows a short "removed" note with an **Undo** button, in case you clicked it by mistake. A trigger whose setup isn't finished shows **Resume setup** instead of Edit.
 
-Each card carries its own **Delete**, **Save trigger**, and — for webhook triggers — **Rotate secret** buttons.
+Click **Edit** to expand the card (the button then reads **Close**):
+
+- **Schedule triggers** show the schedule editor and a **Time zone** field, with **Save schedule** and **Cancel** buttons.
+- **Webhook triggers** show the **Webhook URL** in a read-only field you can copy, a **Replace key** button when the webhook is signed, and a **Check connection** button that waits for an event from your app.
+- **API triggers** just note that the trigger starts the routine through the API.
+
+Every expanded card also has a **Pause trigger** button (or **Enable trigger** if it's paused), so you can stop a trigger from firing without removing it.
 
 ### Run history
 
 ![Run history](../../user-guides/screenshots/light/routines/run-history.png)
 
-The **Runs** section shows every task this routine has created, using the same issue list you know from the rest of Paperclip. That means you get the familiar columns — status, priority, and assignee — along with search and the list's own view controls, all scoped to this one routine. A run that's in progress right now is marked as live.
+The **Runs** section shows every task this routine has created, using the same issue list you know from the rest of Paperclip. That means you get the familiar columns — status and assignee — along with search and the list's own view controls, all scoped to this one routine. A run that's in progress right now is marked as live.
 
-Because it's a real issue list, you can manage runs right here: change a task's status, priority, or assignee inline without opening it, and the routine's run data refreshes as soon as the update lands. Click a row to open the task itself; the breadcrumb brings you back to **Runs** when you're done. Your view choices are remembered per routine.
+Because it's a real issue list, you can manage runs right here: change a task's status or assignee inline without opening it, and the routine's run data refreshes as soon as the update lands. Click a row to open the task itself; the breadcrumb brings you back to **Runs** when you're done. Your view choices are remembered per routine.
 
 When you fire the routine from the **Run** button, Paperclip drops you on **Runs** so you can watch the new task appear.
 
@@ -244,7 +254,7 @@ Below the controls, a one-line human description summarises the current setting
 
 Every schedule trigger is saved with an explicit **timezone**, derived from the browser's `Intl.DateTimeFormat().resolvedOptions().timeZone` at creation time. The scheduler evaluates cron expressions in that timezone, not in UTC. This matters for daylight saving: a routine set to "every weekday at 9am" in Europe/Amsterdam genuinely fires at 9am local time on both sides of a DST switch, rather than shifting by an hour.
 
-If you need to change the timezone later (for example, you moved), open the trigger and re-save — the editor stamps the current browser timezone onto the updated record. The `Next:` countdown on the detail page is always rendered in your current local time, regardless of which timezone the trigger was originally saved with.
+If you need to change the timezone later (for example, you moved), click **Edit schedule** on the trigger card, update the **Time zone** field, and click **Save schedule**. The card's status line always shows the timezone the trigger is saved with.
 
 ---
 
@@ -343,7 +353,7 @@ Under the hood, each webhook trigger carries a **signing mode** that decides how
 
 ### Rotating the secret
 
-If a secret leaks — or you just want to reissue credentials — use **Rotate secret** on the trigger card (the wizard's **Generate new key** button does the same thing). Rotation mints a fresh secret, invalidates the old one immediately, and **keeps the same webhook URL**, so you only have to update the secret in the sending app, never the endpoint. The new secret is shown once, in the same banner, so copy it right away.
+If a secret leaks — or you just want to reissue credentials — click **Edit webhook** on the trigger card, then **Replace key** and confirm the "Replace the webhook key?" prompt (the wizard's **Generate new key** button does the same thing). Rotation mints a fresh secret, invalidates the old one immediately, and **keeps the same webhook URL**, so you only have to update the secret in the sending app, never the endpoint. The new secret is shown once, in the same banner, so copy it right away.
 
 ### Enabling, disabling, and archiving a trigger
 

docs/guides/projects-workflow/task-watchdogs.md

@@ -44,8 +44,6 @@ It will not take "I couldn't" or "waiting for approval" at face value — that's
 
 The review's outcome lands back in the watched issue's thread, so the record of who checked what — and what they found — lives with the work itself. The activity feed labels changes made through a watchdog review, so when you skim a thread later you can tell which actions came from the watchdog and which from the assignees.
 
-![A watchdog review outcome posted back to the task thread, with its disposition and verified evidence.](../../user-guides/screenshots/light/watchdogs/watchdog-thread-outcome.png)
-
 One refinement makes the loop livable: Paperclip fingerprints the stopped state it has already reviewed. If nothing has changed since the last review, no new review task is created. A stalled tree gets looked at once per distinct state, not once per scan, so the watchdog never fills the thread with duplicate reviews of the same silence.
 
 ---

docs/guides/projects-workflow/workspaces.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.824.0
+paperclip_version: v2026.1012.0
 seo_title: Execution Workspaces
 seo_description: Give agents a real folder with your code checked out. Covers workspace modes, keeping reused workspaces consistent, runtime services, and HTTPS previews.
 ---
@@ -18,7 +18,7 @@ This guide covers what execution workspaces are, how they relate to projects, an
 
 Workspaces are an **experimental** feature, so the **Workspaces** screen is hidden until you opt in.
 
-1. Go to **Instance settings → Experimental**.
+1. Go to **Settings → Experimental**.
 2. Turn on **Enable Isolated Workspaces**.
 
 Once it's on, a **Workspaces** item appears in the sidebar, and a **Workspaces** tab appears on any project that has workspace activity. With the setting off, the sidebar item isn't shown and visiting `/workspaces` directly just sends you back to your issues.

docs/guides/welcome/key-concepts.md

@@ -1,4 +1,5 @@
 ---
+paperclip_version: v2026.1012.0
 seo_title: Key Concepts: Companies, Agents, Tasks
 seo_description: The seven ideas behind Paperclip — company, agent, task, heartbeat, adapter, budget, approval — explained with analogies before the technical detail.
 ---
@@ -43,7 +44,7 @@ Every single thing in Paperclip — every agent, every task, every dollar spent
 
 Agents are organised in a strict hierarchy. Every agent reports to exactly one manager. The CEO is the only agent with no manager — it reports directly to you, the board.
 
-![The org chart view showing agents in a hierarchy, with the CEO at the top and direct reports beneath](../../user-guides/screenshots/light/org/org-chart-view.png)
+![The Agents page in Org chart view, showing agents in a hierarchy with the CEO at the top and direct reports beneath](../../user-guides/screenshots/light/org/org-chart-view.png)
 
 > **Note:** The CEO agent is always the first agent you create. It's the entry point — once the CEO is running, it creates tasks and can request to hire its own reports.
 
@@ -86,7 +87,7 @@ They can also be marked `blocked` if an agent is waiting on something, or `cance
 
 **What you do with it:**
 - Configure how often each agent's heartbeat fires (e.g. every hour)
-- Use **Run Heartbeat** on the agent detail page when you want to trigger one manually
+- Use **Run now** on the agent's page when you want to trigger one manually
 - Use comments and assignments to wake agents on demand when their run policy allows it
 
 Each heartbeat is logged with a full transcript so you can read exactly what the agent did and why.
@@ -94,11 +95,11 @@ Each heartbeat is logged with a full transcript so you can read exactly what the
 A heartbeat can be triggered by:
 - **Schedule** — a timer fires at your configured interval
 - **Task assignment** — a new task is assigned to the agent
-- **Comment mention** — the agent is @-mentioned in a task comment
-- **Manual invoke** — you click **Run Heartbeat** on the agent detail page
+- **New comment** — someone comments on a task assigned to the agent (an @-mention on its own doesn't wake an agent)
+- **Manual invoke** — you click **Run now** on the agent's page
 - **Approval resolution** — a pending approval the agent submitted is approved or rejected
 
-![The agent detail page showing run history with heartbeat transcripts](../../user-guides/screenshots/light/agents/agent-detail-run-history.png)
+![The Audit page's Runs tab filtered to one agent, listing its recent heartbeat runs](../../user-guides/screenshots/light/agents/agent-detail-run-history.png)
 
 ---
 
@@ -113,7 +114,7 @@ A heartbeat can be triggered by:
 **What you do with it:**
 - Choose an adapter type when you hire an agent (Claude Code is the most common starting point)
 - Configure adapter-specific settings: which model to use, where files should be written, and which environment variables or secrets the agent needs
-- Use the "Test Environment" button to verify the adapter is working before enabling the agent
+- Use **Run test** in the **Test your agent** card to verify the adapter is working before enabling the agent
 
 Available adapter types:
 
@@ -145,13 +146,13 @@ For most people getting started, `claude_local` is the right choice.
 - Set a company-level budget (the ceiling for the whole organisation)
 - Set per-agent budgets (each agent has its own limit within the company ceiling)
 - Monitor spend on the dashboard's cost panel
-- Increase or decrease budgets at any time from the agent's settings
+- Increase or decrease budgets at any time from **Audit → Budgets**, once the agent has a budget policy; create one with the CLI or API (see [Agents: Budgets](../org/agents.md#budgets))
 
 Budget behaviour:
 - At **80% utilisation**: Paperclip shows a warning so you can intervene before the hard stop
 - At **100% utilisation**: the agent is automatically paused and no more heartbeats fire
 
-![The cost summary panel showing per-agent budget bars with current spend](../../user-guides/screenshots/light/costs/agent-budget-bar.png)
+![The Budgets tab on the Audit page, with the Budget control plane summary and active budget incidents](../../user-guides/screenshots/light/costs/agent-budget-bar.png)
 
 > **Warning:** The company budget and the per-agent budgets are separate. An agent can be paused by its own budget limit even if the company has remaining budget. Set both carefully.
 
@@ -178,7 +179,7 @@ The first two approval types most beginners encounter are:
 
 Paperclip can also surface budget override approvals when a hard stop is hit, and other board-level approval requests in more advanced flows.
 
-![The approvals list showing pending strategy and hire_agent approvals](../../user-guides/screenshots/light/approvals/approvals-list.png)
+![The Approvals page listing pending approvals, such as a CEO strategy proposal and a board approval request](../../user-guides/screenshots/light/approvals/approvals-list.png)
 
 > **Tip:** Approvals don't expire on their own. If an approval is pending, agents that are waiting on it will pause at that point until you take action. Keep an eye on your approval queue.
 

docs/how-to/add-a-human-teammate.md

@@ -1,22 +1,22 @@
 ---
-paperclip_version: v2026.831.1
+paperclip_version: v2026.1012.0
 seo_title: Add a Human Teammate
 seo_description: Bring a co-founder, operator, or read-only viewer into your company as a board member, and pick the access level that matches what they need to do.
 ---
 
 # Add a human teammate
 
-Paperclip companies aren't single-player. You can bring other people in as board members — a co-founder who watches the same agents, an operator who triages the inbox, a viewer who just wants read access to the dashboard. This is the end-to-end flow, done from the app: you create an invite link, they open it and ask to join, and you approve them.
+Paperclip companies aren't single-player. You can bring other people in as board members — a co-founder who watches the same agents, an operator who triages the inbox, a viewer who just wants read access to the dashboard. This is the end-to-end flow, done from the app: you create an invite link, they open it, and they're in.
 
 The whole round-trip takes a couple of minutes. Invites are **copy-link only** — Paperclip doesn't email anyone, so you share the link yourself.
 
-**Before you start:** creating invites needs the `users:invite` permission, and approving the person who shows up needs `joins:approve`. Owners and Admins have both by default. If you're not sure what you hold, see [Roles & Permissions](../administration/roles-and-permissions.md).
+**Before you start:** creating invites needs the `users:invite` permission. Owners and Admins have it by default. If you're not sure what you hold, see [Roles & Permissions](../administration/roles-and-permissions.md).
 
 ---
 
 ## 1. Decide what role they should land in
 
-Every invite carries a **default role** that gets attached to the join request so you can see it in context at approval time. Pick the smallest role that lets them do their job:
+Every invite carries a role, and that's the role your teammate gets the moment they accept. Pick the smallest role that lets them do their job:
 
 - **Viewer** — read-only. Good for stakeholders.
 - **Operator** — can assign tasks. The default, and the right call for most hands-on teammates.
@@ -29,50 +29,47 @@ You can always change this after they're in (step 5), so don't overthink it. The
 
 ## 2. Create the invite link
 
-![Invites tab of the Members page](../user-guides/screenshots/light/company/invites.png)
+![The Invites tab of the Members page, with the Invite a person card](../user-guides/screenshots/light/company/invites.png)
 
-Open **Settings → Members** and switch to the **Invites** tab. In the **Create invite** card, pick the default role from step 1 — each option shows a short description of what that role gets — and click **Create invite**. Paperclip does three things at once:
+Open **Settings → Members** and switch to the **Invites** tab. In the **Invite a person** card, pick the role from step 1 under **Choose a role** — each option shows a short description of what that role gets — and click **Create invite**. Paperclip does three things at once:
 
 1. generates a fresh, single-use invite link against your current Paperclip domain;
 2. copies the URL to your clipboard (if the browser allows it — otherwise a toast tells you to copy it manually);
 3. drops the link into the **Latest invite link** panel, and adds a row to the **Invite history** table below with an **Active** badge.
 
-The **Open invite** button next to the link lets you preview the join page in another tab. The link is **single-use** and expires after 72 hours — if it goes stale, just create another. For the full tour, see [Company Administration → Invites](../administration/company.md#invites).
+Use the **Copy link** button next to the URL if you need to copy it again. The link is **single-use** and expires after 72 hours — if it goes stale, just create another. For the full tour, see [Company Administration → Invites](../administration/company.md#invites).
 
 ---
 
 ## 3. Share the link
 
-Send the URL however you normally share a secret — a DM, your password manager, a private channel. Anyone who opens an active link can file a join request against your company, so treat it like a short-lived password and don't post it anywhere public. Changed your mind about one that's still outstanding? Hit **Revoke** on its row in the **Invite history** table.
+Send the URL however you normally share a secret — a DM, your password manager, a private channel. Whoever accepts an active link joins your company with the role it carries, so treat it like a short-lived password and don't post it anywhere public. Changed your mind about one that's still outstanding? Hit **Revoke** on its row in the **Invite history** table.
 
 ---
 
-## 4. Your teammate opens the link and requests to join
+## 4. Your teammate opens the link and joins
 
-When they open the URL they land on a Paperclip join page branded with your company's name and logo. If they don't have an account yet, the page walks them through sign-up first, then returns them to the invite. Accepting **does not** grant access immediately — it creates a **pending join request** tied to the invite, capturing their name, email, and source IP for you to review.
+When they open the URL they land on a Paperclip join page branded with your company's name and logo. If they don't have an account yet, the page walks them through sign-up first, then returns them to the invite. Once they're signed in and accept, they join **right away** with the invite's role — there's no approval step for human invites. They see **You joined the organization** and an **Open board** button.
 
-On their side they see a "waiting for approval" state. Nothing they do from here touches your company data until you approve them.
+Paperclip still records a join request behind the scenes, already approved, so the invite's **Join request** column and the audit trail stay complete.
 
 > **If they see "Email and password sign up is not enabled":** your instance has self-service sign-up turned off, so the invitee can't create the account they need to accept the invite. This is controlled by the `auth.disableSignUp` config field (or the `PAPERCLIP_AUTH_DISABLE_SIGN_UP` environment variable). To let invited teammates register, make sure sign-up is enabled — set `auth.disableSignUp` to `false` (its default) or confirm `PAPERCLIP_AUTH_DISABLE_SIGN_UP` isn't set to `true` — then restart the instance and have them reopen the invite link. See [Enable multi-user login](./enable-multi-user-login.md) for the full authenticated-mode setup.
 
 ---
 
-## 5. Approve them (and fine-tune access)
+## 5. Fine-tune their access
 
-There are two places in the app to approve, both showing the requester and the invite context before you decide:
+Your teammate is already an **active** member with the invite's role. To adjust their role or hand out extra permissions, open **Settings → Members**, click **Edit** on their row, and set the role, status, and any explicit grants in the grants grid, then save. (Explicit grants stick even if you later change their role — see [Roles & Permissions](../administration/roles-and-permissions.md#how-grants-combine-precedence).)
 
-- **Settings → Members** — when there are pending human joins, a **Pending human joins** card sits above the members list with **Approve human** / **Reject human** buttons on each entry. This is the quickest path.
-- **Join Request Queue** (`/inbox/requests`) — the full queue for both human and agent requests, with **Status** and **Request type** filters. Each card carries the requester, the invite context, and the submission details.
+> **Seeing a pending request anyway?** Requests filed before human invites started joining people instantly can still be waiting. If you hold `joins:approve`, a **Pending human joins** card sits above the members list with **Approve human** / **Reject human** buttons. The full **Join Request Queue** (`/inbox/requests`) covers both human and agent requests, with **Status** and **Request type** filters — today it's mostly where agent requests land.
 
-![Join request queue](../user-guides/screenshots/light/company/join-requests.png)
-
-Click **Approve human** and the person becomes an **active** member with the invite's default role. To adjust their role or hand out extra permissions, stay on **Settings → Members**, click **Edit** on their row, and set the role, status, and any explicit grants in the grants grid, then save. (Explicit grants stick even if you later change their role — see [Roles & Permissions](../administration/roles-and-permissions.md#how-grants-combine-precedence).)
+![The Join Request Queue with its Status and Request type filters; the list is empty when nothing is waiting](../user-guides/screenshots/light/company/join-requests.png)
 
 ---
 
 ## 6. Verify
 
-They now appear in **Settings → Members** with an `active` status badge and the role you gave them. That's it — they can sign in and see the company. Every step above (invite created, join requested, approved, membership activated) is written to the [activity log](../guides/day-to-day/activity-log.md), so the whole onboarding is auditable after the fact.
+They now appear in **Settings → Members** with an `active` status badge and the role you gave them. That's it — they can sign in and see the company. Every step above (invite created, invite accepted, membership activated) is written to the [activity log](../guides/day-to-day/activity-log.md), so the whole onboarding is auditable after the fact.
 
 ---
 
@@ -84,7 +81,8 @@ Every step above has a CLI counterpart, handy for scripting onboarding. They map
 # Create the invite (returns the invite URL)
 paperclipai invite create --company-id <company-id> --payload-json '{"role":"operator"}'
 
-# See who's waiting, then approve
+# Human invites join on accept; agent requests (and any older
+# pending ones) still need approval
 paperclipai join list --company-id <company-id> --status pending
 paperclipai join approve <request-id> --company-id <company-id>
 

docs/how-to/debug-stuck-heartbeat.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.720.0
+paperclip_version: v2026.1012.0
 seo_title: Debug a Stuck Heartbeat
 seo_description: The handful of symptoms behind almost every agent-not-working report, each diagnosed from the Run history on the agent's detail page.
 ---
@@ -116,4 +116,4 @@ If you would rather not pay for these wakes at all, the cure is upstream: have y
 
 - [Watching Agents Work](../guides/getting-started/watching-agents-work.md) — what a healthy first heartbeat looks like.
 - [Heartbeats & Routines](../guides/projects-workflow/routines.md) — timer vs assignment-driven wakes.
-- [Activity Log](../guides/day-to-day/activity-log.md) — structural events when comments don't tell the full story.
+- [Audit: Activity](../guides/day-to-day/activity-log.md) — structural events when comments don't tell the full story.

docs/how-to/handle-board-approvals-for-hires.md

@@ -1,4 +1,5 @@
 ---
+paperclip_version: v2026.1012.0
 seo_title: Handle Board Approvals for Hires
 seo_description: A manager agent cannot hire on its own; it files a request and waits. Read the proposal, approve it, and Paperclip wakes the requester to carry on.
 ---
@@ -48,17 +49,17 @@ The same body works whether `requireBoardApprovalForNewAgents` is on or off —
 
 ## 3. Review in the board UI
 
-Open **Approvals**. Hire requests show up in the **Pending** tab.
+Open **Approvals**. Hire requests show up in the **Pending** tab as **Hire Agent** cards. You can **Approve** or **Reject** straight from the card, but click **View details** to read the whole proposal first.
 
-![Hire approval detail showing proposed name, role, adapter config, and budget](../user-guides/screenshots/light/approvals/hire-approval-detail.png)
+![Hire approval detail showing the proposed agent's name, role, title, icon, capabilities, and adapter type](../user-guides/screenshots/light/approvals/hire-approval-detail.png)
 
-The detail page summarises the proposal (name, role, capabilities, adapter, reporting line, monthly budget) and exposes the raw payload under **See full request**. Three buttons sit at the bottom:
+The detail page summarises the proposal — **Name**, **Role**, **Title**, **Icon**, **Capabilities**, **Adapter**, and any requested **Skills**. The reporting line (`reportsTo`), the monthly budget (`budgetMonthlyCents`), and the adapter config aren't in the summary, so open **See full request** to check them in the raw payload. Three buttons sit below:
 
-![Approve, Reject, and Request Revision buttons](../user-guides/screenshots/light/approvals/approve-reject-revision-buttons.png)
+![Approve, Reject, and Request revision buttons](../user-guides/screenshots/light/approvals/approve-reject-revision-buttons.png)
 
 - **Approve** — activates the pending agent, creates a monthly budget policy when `budgetMonthlyCents > 0`, and queues the requesting manager to wake.
 - **Reject** — terminates the draft agent and notifies the requester; it will not retry on its own.
-- **Request Revision** — saves your `decisionNote` and waits for the manager to resubmit.
+- **Request revision** — moves the approval to `revision_requested` and waits for the manager to resubmit. The button doesn't take a note, so explain what you want in the **Comments** box (or send a `decisionNote` through the API, below).
 
 The same actions are available on the API:
 
@@ -108,7 +109,7 @@ A rejected hire wakes the requesting manager with `PAPERCLIP_APPROVAL_STATUS=rej
 
 The manager won't retry on its own. If you rejected because the proposal was salvageable, leave a comment on the original source issue with what you'd accept; the manager picks it up on its next heartbeat. If the role is fundamentally wrong, reassign the issue or close it.
 
-For "almost right" proposals, prefer **Request Revision** — it keeps the same approval record and the same `sourceIssueId` link, and the manager edits the payload in place via:
+For "almost right" proposals, prefer **Request revision** — it keeps the same approval record and the same `sourceIssueId` link, and the manager edits the payload in place via:
 
 ```bash
 curl -X POST "$PAPERCLIP_API_URL/api/approvals/$APPROVAL_ID/resubmit" \

docs/how-to/require-board-approval-before-spend.md

@@ -1,4 +1,5 @@
 ---
+paperclip_version: v2026.1012.0
 seo_title: Require Board Approval Before Spend
 seo_description: Caps are reactive. For lumpy, discrete spend — a $40/month SaaS signup — make agents ask a human first instead of warning you at 80 percent.
 ---
@@ -19,7 +20,7 @@ This guide wires that pattern end-to-end on a test company. Time to working appr
 | Direction | Reactive — fires after the dollars are spent | Proactive — fires before the action happens |
 | Granularity | Aggregate per scope (company, agent, project) per month | Per-decision, with the proposal in the payload |
 | What stops | The whole scope pauses (no more heartbeats) | Only the specific spend; the agent keeps working other tasks |
-| Who acts | Board resolves the incident on the Costs page | Board approves/rejects on the Approvals page |
+| Who acts | Board resolves the incident under **Audit → Budgets** | Board approves/rejects on the Approvals page |
 
 Use **both**. The cap is your safety net — it catches what slips through the contract. The approval gate is the contract: anything above $X, anything recurring, anything outside a pre-approved provider list, requires a board decision before the agent commits.
 
@@ -139,11 +140,11 @@ Open it. The detail view shows the three structured fields up top (title, summar
 
 The decision buttons sit at the bottom — same three buttons every approval gets:
 
-![Approve, Reject, and Request Revision buttons](../user-guides/screenshots/light/approvals/approve-reject-revision-buttons.png)
+![Approve, Reject, and Request revision buttons](../user-guides/screenshots/light/approvals/approve-reject-revision-buttons.png)
 
 - **Approve** — the agent is woken with `PAPERCLIP_APPROVAL_STATUS=approved` and proceeds with the spend.
 - **Reject** — the agent is woken with `PAPERCLIP_APPROVAL_STATUS=rejected` and abandons the spend per its instructions.
-- **Request Revision** — the approval enters `revision_requested`, your `decisionNote` is stored, and the agent is *not* automatically woken (see the gotcha at the end of Section 5).
+- **Request revision** — the approval enters `revision_requested` and the agent is *not* automatically woken (see the gotcha at the end of Section 5). The button doesn't take a note, so explain what you want in the **Comments** box (or send a `decisionNote` through the API, below).
 
 The same actions are available on the API:
 
@@ -238,7 +239,7 @@ Two important details about the wake:
 - **The wake covers `approved` and `rejected` only.** `request-revision` does not fire `PAPERCLIP_APPROVAL_ID`. The board's `decisionNote` is stored on the approval; the agent learns about it on its next normal heartbeat (or sooner if you also leave a comment on the source issue, which *does* fire a wake — see [Debug a stuck heartbeat](./debug-stuck-heartbeat.md) for the full set of wake reasons).
 - **Re-fetch the approval and the linked issues.** The env vars only carry the id and the verdict. The payload, the `decisionNote`, and the linked-issue list all live on the API and may have changed since the agent submitted the request — particularly after a revision round.
 
-For BYO-agent runtimes that don't get Paperclip-driven wakes at all (the polling pattern in [Bring your own agent → Option C](./bring-your-own-agent.md#option-c--custom-script-no-paperclip-adapter)), poll the approval directly: `GET /api/approvals/$APPROVAL_ID` returns the current status. Loop with backoff and bail when `status != "pending"`.
+For BYO-agent runtimes that don't get Paperclip-driven wakes at all (the polling pattern in [Bring your own agent → Option C](./bring-your-own-agent.md#option-c-custom-script-no-paperclip-adapter)), poll the approval directly: `GET /api/approvals/$APPROVAL_ID` returns the current status. Loop with backoff and bail when `status != "pending"`.
 
 ---
 
@@ -248,7 +249,7 @@ Before relying on the gate in production, prove the loop closes. Use a throwaway
 
 1. **Make sure the agent's instructions name the gate.** Open the agent → **Instructions**, paste a minimal version of the rule from Section 2, save.
 
-2. **Trigger the spend.** Assign the agent an issue that should hit the gate ("Sign up for the demo SaaS account"). Run a heartbeat — either let one fire on schedule or click **Run Heartbeat** in the agent header.
+2. **Trigger the spend.** Assign the agent an issue that should hit the gate ("Sign up for the demo SaaS account"). Run a heartbeat — either let one fire on schedule or click **Run now** in the agent header.
 
 3. **Confirm the approval lands.** Open **Approvals → Pending**. You should see the request, with the proposal payload your agent submitted. Confirm `issueIds` links to the source issue.
 

docs/how-to/rotate-provider-api-key.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.525.0
+paperclip_version: v2026.1012.0
 seo_title: Update or Rotate a Provider API Key
 seo_description: Swap the credential a running agent uses — after a provider rotation, an expiry, or a move from subscription login to a console-issued key.
 ---
@@ -29,15 +29,15 @@ Paperclip lets you bind a provider key into an agent's `adapterConfig.env` in on
 
 Use this when the key was pasted directly into the adapter form.
 
-1. Open **Agents → {agent}** and click **Edit**.
-2. Scroll to the **Environment variables** section.
+1. Open **Agents → {agent}** and choose **Harness / Runtime** in the agent's sidebar.
+2. Scroll to the **Environment variables** card.
 3. Find the provider's key name (for example `ANTHROPIC_API_KEY`) and replace the value with the new key.
-4. Click **Test environment**. The adapter spins up a check against the provider; a green result confirms the new key authenticates.
-5. Save the agent.
+4. Click **Save changes**.
+5. In the **Test your agent** card at the bottom, click **Run test**. The adapter spins up a check against the provider; **Connection successful** confirms the new key authenticates.
 
 The next heartbeat picks up the new value. No restart needed.
 
-![Adapter form with environment variables section](../user-guides/screenshots/light/agents/claude-local-config-filled.png)
+![The Environment variables card on an agent's Harness / Runtime page, with a GITHUB_TOKEN row bound to a secret and an Add variable link](../user-guides/screenshots/light/agents/test-environment-fail.png)
 
 > **Warning:** Plain values are stored on the agent record. If you're running with `PAPERCLIP_SECRETS_STRICT_MODE=true`, the server rejects new inline values for any env key whose name matches a sensitive-keyword regex (`api_key`, `token`, `auth`, `authorization`, `bearer`, `secret`, `password`, `credential`, `jwt`, `private_key`, `cookie`, `connectionstring`). Either turn strict mode off temporarily, or use Path B.
 

docs/how-to/set-monthly-budget.md

@@ -1,4 +1,5 @@
 ---
+paperclip_version: v2026.1012.0
 seo_title: Set a Monthly Budget and Enforce It
 seo_description: A misconfigured loop can run a four-figure tab in a weekend. Set a cap Paperclip enforces automatically, with warnings before the hard stop.
 ---
@@ -75,9 +76,13 @@ Project policies default to lifetime caps — useful for one-shot work ("this pr
 
 ## 3. Where the warnings show up
 
-At 80% (or whatever `warnPercent` you set) Paperclip records a **soft incident** against the policy. At 100% it records a **hard incident** and pauses the scope. Both surface on the Budgets tab as cards above the policy list:
+At 80% (or whatever `warnPercent` you set) Paperclip records a **soft incident** against the policy. At 100% it records a **hard incident** and pauses the scope. In the UI, open **Audit** in the sidebar and switch to the **Budgets** tab. Open incidents appear there as cards above the policy list:
 
-![Budgets tab showing the control plane and active incidents grid](../user-guides/screenshots/light/costs/budgets.png)
+![Audit page on the Budgets tab, showing the Budget control plane card, active incidents, and budget policy cards](../user-guides/screenshots/light/costs/budgets.png)
+
+A warning shows as an amber **… budget warning** card with **Raise budget** and **Dismiss warning**. A hard stop shows as a red **… hard stop** card with **Raise budget & resume** and **Keep paused**.
+
+> **Heads-up:** in v2026.1012.0 itself, the warning card still uses the hard-stop design. It is headed **… hard stop** and says *"This scope is paused"*, but the warning itself does not pause anything. The screenshots show the corrected card from [the fix](https://github.com/paperclipai/paperclip/pull/16201), which ships in a later release. Until then, check the policy card: **Warning** does not pause work. Only **Hard stop** or **Paused** means this policy has stopped it.
 
 Paperclip does not push outbound webhooks today. If you want Slack or Discord pings on incidents, run a routine that diffs `GET /api/companies/{COMPANY_ID}/budgets/overview` against a cursor and posts to a webhook — the same shape as the approval notifier. See [Wire Slack/Discord notifications](./wire-slack-discord-notifications.md).
 
@@ -128,9 +133,9 @@ When the hard incident fires:
 1. The affected scope (company, agent, or project) is paused immediately. No more heartbeats are scheduled.
 2. Any in-progress run for the scope is cancelled — the issue stays where it was, the agent stops working it.
 3. The Budget control plane card increments **Paused agents** / **Paused projects**.
-4. The incident appears as a card on the Budgets tab and on the Overview tab (above the fold).
+4. The incident appears as a card on the **Budgets** tab under **Audit**, and at the top of the **Costs** tab's **Overview**.
 
-![Per-agent budget bar at 100% — red, agent shown as paused](../user-guides/screenshots/light/costs/agent-budget-100pct-paused.png)
+![Agent budget policy card on Audit → Budgets at 100% — full red bar, Paused status, and a note that heartbeats are paused until the budget is raised or the incident is dismissed](../user-guides/screenshots/light/costs/agent-budget-100pct-paused.png)
 
 Two things to know:
 
@@ -207,7 +212,7 @@ If the test agent never paused, the most likely culprits are: (a) the agent was
 
 ## See also
 
-- [Costs guide](../guides/day-to-day/costs.md) — the full UI walkthrough for the Costs page (Overview, Budgets, Providers, Billers, Finance).
+- [Costs guide](../guides/day-to-day/costs.md) — the full UI walkthrough for the **Costs** and **Budgets** tabs under **Audit** (including the Overview, Providers, Billers, and Finance views).
 - [Costs API reference](../reference/api/costs.md) — every endpoint touched here, plus reading routes (`/costs/summary`, `/costs/by-agent`, `/costs/window-spend`).
 - [Handle board approvals for hires](./handle-board-approvals-for-hires.md) — the same governance flow but for new agent budgets at hire time.
 - [Require board approval before an agent spends money](./require-board-approval-before-spend.md) — the proactive half of spend control: the agent stops and asks the board before committing to a discrete spend, so the cap here is the safety net rather than the only line of defence.

docs/reference/adapters/paperclip-runner.md

@@ -12,7 +12,7 @@ Paperclip Runner is experimental. Its `enableNativeRunner` setting is **on by de
 
 ## Before you start
 
-- An instance with **Paperclip Runner** enabled under **Settings → Instance settings → Experimental**.
+- An instance with **Paperclip Runner** enabled under **Settings → Experimental**.
 - An active agent and a task in standard, planning, or ask work mode.
 - A prepared execution environment and compatible model credential.
 - The pinned runtime required by the selected provider.

docs/reference/api/checkbox-confirmations.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.1005.0
+paperclip_version: v2026.1012.0
 seo_title: Checkbox Confirmations API
 seo_description: An issue-thread interaction that asks a person to select any subset of a known option list, then confirm or reject the whole request in one action.
 ---
@@ -10,7 +10,7 @@ A checkbox confirmation is an issue-thread interaction that asks the board or a
 
 Create one with `kind: request_checkbox_confirmation` on the interactions routes below. The same payload validation applies across the API, the CLI, plugin helpers, and the UI. Available since v2026.609.0.
 
-![A checkbox confirmation card in an issue thread: prompt, markdown details, a five-option list with three options checked, select-all and clear-selection controls, and custom accept and reject buttons.](../../user-guides/screenshots/light/interactions/checkbox-confirmation-card.png)
+![A checkbox confirmation card in a task thread: title and prompt, a five-option list with three options checked, a collapsed Details section, a selection summary, and custom accept and reject buttons.](../../user-guides/screenshots/light/interactions/checkbox-confirmation-card.png)
 
 All routes are mounted under `/api` and authenticate with `Authorization: Bearer {token}`.
 

docs/reference/changelog.md

@@ -40,6 +40,15 @@ This release lets outside assistants join your team. Claude Code, Codex, OpenCod
 - [Trust & Low-Trust Review](../administration/trust-and-low-trust-review.md) — low-trust agents can take self-assigned work inside their scope, accept work from a person who messages them or assigns them a task directly, and update their own `AGENTS.md` when you ask from their chat.
 - Smaller updates: [Settings](../administration/settings.md), [Experimental overview](../experimental/overview.md), [Task watchdogs](../guides/projects-workflow/task-watchdogs.md) (the new 5- and 15-minute silence thresholds), [Docker](deploy/docker.md), [Sandbox Providers](adapters/sandbox-providers.md) (exe.dev **Source VM**), [Plugin SDK](plugins/sdk.md) (AI connection routers), [Artifacts](../guides/day-to-day/artifacts.md), [Work Modes](../guides/day-to-day/work-modes.md), the memory connector guides, and [Verify and troubleshoot](../connectors/verify-and-troubleshoot.md).
 
+**Screenshots and interface refresh**
+
+Every screenshot was recaptured from Paperclip v2026.1012.0, in light and dark. Some screens moved in this release, so the guides that show them were updated to match:
+
+- [Costs and Budgets](../guides/day-to-day/costs.md), [Activity Log](../guides/day-to-day/activity-log.md), [Work Timeline](../guides/day-to-day/work-timeline.md) and [Set a monthly budget](../how-to/set-monthly-budget.md): costs, budgets, runs and the timeline now live under **Audit**. Set agent budgets from the CLI or API, and project budgets from the project's **Budget** tab.
+- [Agents](../guides/org/agents.md), [Your first agent](../guides/getting-started/your-first-agent.md), [Watching agents work](../guides/getting-started/watching-agents-work.md) and [Org Structure](../guides/org/org-structure.md): the agent page's side menu, including **Overview** and **Harness / Runtime**. Also the two-step **New agent** dialog, **Run now**, and the org chart as a view on the Agents page.
+- [Projects](../guides/projects-workflow/projects.md), [Routines](../guides/projects-workflow/routines.md), [Issues](../guides/day-to-day/issues.md), [Approvals](../guides/day-to-day/approvals.md), [Skills](../guides/org/skills.md), [Company settings](../administration/company.md), [Settings](../administration/settings.md) and [Plugins](../administration/plugins.md): current tab names, buttons and flows. That covers instant-join invites, the Experimental settings list, and **Settings → Experimental** paths across the docs.
+- Screenshots that showed screens no longer in this release were retired, including Auto-Create Recovery Tasks. [Cloud Sync](../experimental/cloud-sync.md) and [Auto-Create Recovery Tasks](../experimental/auto-create-recovery-tasks.md) are now marked as removed.
+
 </div>
 </details>
 

docs/reference/deploy/environment-variables.md

@@ -1,5 +1,5 @@
 ---
-paperclip_version: v2026.1005.0
+paperclip_version: v2026.1012.0
 seo_title: Environment Variables Reference
 seo_description: Every variable Paperclip reads for server configuration, plus the ones it injects into agent processes at runtime — the list to wire deployments from.
 ---
@@ -133,7 +133,7 @@ Only an **absent** variable means self-hosted. Everything else is treated as a h
 
 ### What it can and can't reach
 
-`features` may only target the boolean feature-flag keys of the instance's experimental settings — the ones on **Settings → Instance settings → Experimental**. Server-managed bookkeeping fields (activation cutoffs, lookback hours) aren't booleans and are excluded by construction, so a managed document can't touch them.
+`features` may only target the boolean feature-flag keys of the instance's experimental settings — the ones on **Settings → Experimental**. Server-managed bookkeeping fields (activation cutoffs, lookback hours) aren't booleans and are excluded by construction, so a managed document can't touch them.
 
 On top of that, each flag carries a tier in the build's feature catalog: `preference` (a tenant's own taste setting the harness leaves alone), `managed` (the harness may set it), or `floor` (pinned in code). Only `managed` keys are accepted. A key whose tier differs in the running build is version skew between the document's `catalogVersion` and the app, and the server refuses to start rather than apply a control with mismatched semantics.
 

docs/reference/skills.md

@@ -726,7 +726,7 @@ Walk down this list in order. The first match is usually the problem.
 
 ### "I pinned a beta release but the agent still runs the default"
 
-- Check **Beta skills** on **Settings → Instance settings → Experimental**. With `enableBetaSkills` off, saved pins are ignored rather than deleted, and every agent resolves to the live skill.
+- Check **Beta skills** on **Settings → Experimental**. With `enableBetaSkills` off, saved pins are ignored rather than deleted, and every agent resolves to the live skill.
 - A pin only applies while its skill is in the agent's desired set. Detaching the skill drops the pin along with it.
 - Confirm the pin actually persisted: with the flag **on**, `GET /api/agents/{agentId}/skills` reports it under `desiredSkillEntries`. With the flag off that response reports `versionId: null` even though the pin is still stored on the agent — so use it to check a pin, not to conclude one was lost.