paperclipai/paperclip-docs
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-07 06:16:07 -10:00
Code Issues Packages Projects Releases Wiki Activity

Release docs for paperclip v2026.1001.0 (#142)

Browse Source 
Release docs for paperclip **v2026.1001.0** (tag `8f8a0ab7`, 77 commits
from the `v2026.916.1` merge-base `dffc2b3`).

## What's in the release

Agent characters across the app, a rebuilt Slack setup, safe routine
webhooks, experimental MCP aggregators (default-off
`enableMcpAggregators`), Railway and You.com connectors, the CreateOS
sandbox provider, queued answers during active runs, and runner-created
company skills. Two breaking changes are documented: coding agents now
run in full auto by default, and the legacy Composio broker is retired.

## How this branch was built

This branch was cut from `nightly`, with `main` merged in. Nightly had
drafted parent `master` up to `0f14d261`, which is **93 commits past the
tag**. So every page changed against `main` was checked line by line
against the tag source, and post-tag content was reverted to what ships.

**Merge with `main`:** `main` published Fireflies, Railway, and You.com
guides in #138/#141 while nightly drafted its own versions. This branch
keeps `main`'s live versions. Nightly's Fireflies and Railway drafts
describe post-tag behaviour anyway.

## Changes

- 37 doc pages vs `main`, all stamped `paperclip_version: v2026.1001.0`.
One new page: `connectors/mcp-aggregators.md`.
- `docs/reference/changelog.md`: v2026.1001.0 entry. It also rounds up
the six connector guides published since v2026.916.1.
- Zapier, Arcade, Composio, and Executor pages and catalog rows now say
they need the experimental **MCP aggregators** setting. At the tag, all
four are filtered out of **Connectors** until it is on
(`packages/shared/src/remote-mcp-connectors.ts`). This is new for
Zapier, which used to be visible to everyone.
- The connector-model version notes in `connectors.md`,
`recognized-providers.md`, and `slack.md` are moved to v2026.1001.0.
- `SCREENSHOTS_PENDING.md`: regenerated for the release window. 194 of
350 screenshots are flagged across 40 routes (file-change flags only).
- `.sync-state.json`: base moved to `v2026.1001.0`.

### ⚠ Post-tag leaks removed

Present on `master`, absent at `v2026.1001.0`. These stay on `nightly`
for a later release.

- **Memory connectors** (Zep, Supermemory, Cognee, Honcho) and the
toggle, from `18dac1e1`: `connectors.md`, `connections-apps.md`,
`mem0.md`.
- **MCP aggregators on by default** and agent provider choice, from
`8781f06a`, `aa8fc863`, `b41ccf09`, `4721f558`: `mcp-aggregators.md`,
`connectors.md`. The `--retry-provider-choice`, `--target-service`, and
`--selection-interaction-id` flags are removed from
`cli/connections.md`.
- **Slack** governed tools, personal search, Idle state, scheduled
messages and `im:write`, message mirroring, channels enabled by default,
and the MCP-access troubleshooting row, from `a10702a8`, `b0155a68`,
`8725d6ce`, `a7d3b17a`: `slack.md`,
`wire-slack-discord-notifications.md`.
- **Fireflies routine signing**: the `app_webhook` and `fireflies_hmac`
modes, payload data blocks, and the Fireflies example, from `24429024`:
`routines.md` (guide and API) and `create-a-daily-routine.md`.
- **Tasks**: the artifact media gallery (`1ccae464`), Ancestors in the
Tasks panel (`2788f20f`), retry-budget escalation to `blocked`
(`6bc830b6`), and alphabetized experimental settings (`794b09f8`).
- **Settings**: per-user keyboard shortcuts and `/api/auth/preferences`
(`01d9a121`), the `PAPERCLIP_HIDDEN_SETTINGS` `instance.experimental.*`
wildcard (`e2f1a66a`), Cloud **Invite people** on Members (`c341588b`),
and the Cloud lifecycle routes (`8c6cc7dc`).
- **Plugin SDK**: the `organizationSwitcher` slot (`7badae69`) and the
environment-creation cleanup helpers (`1dbffb4c`).
- **Agents and adapters**: the model and reasoning-effort refresh
(`cdf04a33`), covering Opus 5.5, `gpt-6-sol`/`luna`, Gemini 3.8 Flash,
Grok 4.x, Kimi K3 256k, and the Cursor/OpenCode model lists. Also Grok
in the Cloud picker (`83abfa46`) and `inheritRuntimeFrom: "caller"`
(`7944ed3d`).
- **Retired `PAPERCLIP_WAKE_PAYLOAD_JSON`** (`4b8ec588`): restored in
`environment-variables.md` and `reference/skills.md`.

### ⚠ Verification Failures

For a reviewer to confirm:

- **Codex full auto on the ACP engine.** Per the verifier, at the tag
Codex's approval-and-sandbox bypass applies on the CLI lane, while the
default ACP engine keeps Codex in its workspace sandbox with network on.
`codex.md` now says so. `agent-adapters.md` → "Agents run in full auto
by default" still lists Codex without that qualifier.
- `GET /api/agent-avatars/{version}/{palette}/{pose}.png`
(`api/agents.md`) is medium-confidence drift. It is confirmed at the tag
in `server/src/routes/agent-avatars.ts`.

The mechanical tag-accuracy gate reported **0 high-confidence leaks**,
even on the unfixed nightly content. Every leak above is behavioural or
prose, and was caught by a per-page adversarial pass against the tag
source.

### ⚠ Drift

All pre-existing and known false positives:

- env-var-missing (high):
`PAPERCLIP_WORKSPACE_GIT_SCAN_{CONCURRENCY,QUEUE_CAPACITY,TIMEOUT_MS,CACHE_TTL_MS}`
and
`PAPERCLIP_ID_CONNECTOR_{BASE_URL,ENVIRONMENT,INSTANCE_ID,SIGN_PRIVATE_KEY,SEAL_PRIVATE_KEY}`,
which sit in grouped or commented `.env.example` blocks.
- Verify: rest-route-missing (medium): the five
`/api/companies/import/transfers*` routes, registered through
`COMPANY_IMPORT_TRANSFERS_ROUTE_PATH`.

### Open nightly-draft PRs

Local branches `nightly-draft/2a99de8-sandbox-and-routine-triggers` and
`nightly-draft/3e63a7e-acp-engine` are not part of this release.

### ☐ Before merge

- Delete the duplicate `docs/connectors/you-com.md` (nightly's draft;
`main`'s `youcom.md` is the registered page). It is an orphan with a
duplicate `seo_title`; the automated run could not delete files.
- Optionally run `npm run screenshots:refresh` on this branch.

## Checks

`docs:build`, `docs:test` (all six gates), `sync:lint-links`,
`sync:verify-nav`, and `sync:verify-screenshots` all pass locally. The
only new orphan is the duplicate `docs/connectors/you-com.md`.

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

---------

Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[email protected]>
Co-authored-by: Dotta <[email protected]>
Co-authored-by: ClaudeCoder <[email protected]>
This commit is contained in:
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclipDottaClaudeCoder
 authored and GitHub committed 2026-10-03 09:04:25 +02:00
1 parent fbed190ccb
commit 186095cd39
41 files changed
+994 -231
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.sync-state.json
+5 -5
View File
@@ -1,9 +1,9 @@
{
"branch_mode": "release",
"base_release_tag": "v2026.916.1",
"base_release_sha": "d554c4789ed3930f8a53ac9fdf6503b3187097da",
"last_seen_parent_sha": "d3e0f0a238ed66a05d50ab6f627eb55874f0f57e",
"last_applied_manifest_hash": "ab7a69851d52bce02b1e45727f6c9f08df3c31797bd0d752c905e2747a402b7f",
"last_run_at": "2026-09-26T10:00:00.000Z",
"base_release_tag": "v2026.1001.0",
"base_release_sha": "8f8a0ab7effbd6a0584107d8038736c134ee5047",
"last_seen_parent_sha": "ffe5e9e2a8866767cbb48009040bfafd85b56576",
"last_applied_manifest_hash": "0d835ee5af10c7d72dfe69301670bce5a7fe798eb86bfa4f3f8ec99f9a97f8c6",
"last_run_at": "2026-10-03T09:30:00.000Z",
"last_run_outcome": "applied"
}
SCREENSHOTS_PENDING.md
+180 -10
View File
@@ -1,32 +1,202 @@
# Screenshots Pending
Regenerated by /sync-docs (release v2026.916.1). Lists screenshots whose `depends_on` parent paths changed in the current cumulative window (`v2026.916.0` -> release tag `v2026.916.1`, commit `d554c478`).
Regenerated by /sync-docs (release). Lists screenshots whose `depends_on` parent paths changed in the release window (base `v2026.916.1` — merge-base with master `dffc2b3` → release tag `v2026.1001.0` / `8f8a0ab7`, 77 commits).
**24 of 350 screenshots are flagged** across 2 routes. The window is one commit ([#13562](https://github.com/paperclipai/paperclip/pull/13562)), which changes only whether the task composer's send button starts out disabled while the pause check loads. Existing captures show the button in its normal empty-reply state, so these are dependency-touch flags, not confirmed visual changes. A recapture is optional.
**194 of 350 screenshots are stale** across 40 routes. These are file-change flags, not confirmed visual changes. The release brings agent personas, the ClipLab onboarding hero, the rebuilt Slack setup and the routine webhook wizard, so a `npm run screenshots:refresh` pass on this release branch is worthwhile; PNGs go to a PR for human review and are never auto-pushed.
| Screenshot | Route | Theme | Changed dependency paths |
|---|---|---|---|
| `dark/activity/activity-filtered-by-agent.png` | `/ACME/activity` | dark | ui/src/pages/audit/AuditFeed.tsx |
| `dark/activity/activity-filters.png` | `/ACME/activity` | dark | ui/src/pages/audit/AuditFeed.tsx |
| `dark/activity/activity-log-full.png` | `/ACME/activity` | dark | ui/src/pages/audit/AuditFeed.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/agents-list-empty.png` | `/{emptyPrefix}/agents/all` | dark | ui/src/pages/Agents.tsx |
| `dark/agents/budget.png` | `/ACME/agents/{agentId}/budget` | dark | ui/src/pages/AgentDetail.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/instructions.png` | `/ACME/agents/{agentId}/instructions` | dark | ui/src/pages/AgentDetail.tsx |
| `dark/agents/list.png` | `/ACME/agents/all` | dark | ui/src/pages/Agents.tsx |
| `dark/agents/new-agent-reports-to-field.png` | `/ACME/agents/new` | dark | ui/src/components/ReportsToPicker.tsx |
| `dark/agents/new.png` | `/ACME/agents/new` | dark | ui/src/pages/Agents.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/approvals/approvals-list.png` | `/ACME/approvals/pending` | dark | ui/src/components/ApprovalCard.tsx |
| `dark/approvals/approve-reject-buttons.png` | `/ACME/approvals/{hireApprovalId}` | dark | ui/src/pages/ApprovalDetail.tsx |
| `dark/approvals/approve-reject-revision-buttons.png` | `/ACME/approvals/{hireApprovalId}` | dark | ui/src/pages/ApprovalDetail.tsx |
| `dark/approvals/approved-approval.png` | `/ACME/approvals/{approvedApprovalId}?resolved=approved` | dark | ui/src/pages/ApprovalDetail.tsx |
| `dark/approvals/hire-approval-detail.png` | `/ACME/approvals/{hireApprovalId}` | dark | ui/src/pages/ApprovalDetail.tsx |
| `dark/approvals/revision-request-input.png` | `/ACME/approvals/{strategyApprovalId}` | dark | ui/src/pages/ApprovalDetail.tsx |
| `dark/approvals/strategy-approval-detail.png` | `/ACME/approvals/{strategyApprovalId}` | dark | ui/src/pages/ApprovalDetail.tsx |
| `dark/company/company-goal-field.png` | `/onboarding` | dark | ui/src/components/OnboardingWizard.tsx |
| `dark/company/join-requests.png` | `/ACME/inbox/requests` | dark | ui/src/pages/Inbox.tsx |
| `dark/company/new-company-form.png` | `/onboarding` | dark | ui/src/components/OnboardingWizard.tsx |
| `dark/costs/agent-budget-field.png` | `/ACME/agents/{agentId}/budget` | dark | ui/src/pages/AgentDetail.tsx |
| `dark/costs/billers.png` | `/ACME/costs` | dark | ui/src/pages/Costs.tsx |
| `dark/costs/budgets.png` | `/ACME/costs` | dark | ui/src/pages/Costs.tsx |
| `dark/costs/company-budget-field.png` | `/ACME/costs` | dark | ui/src/pages/Costs.tsx |
| `dark/costs/costs-dashboard-overview.png` | `/ACME/costs` | dark | ui/src/pages/Costs.tsx |
| `dark/costs/finance.png` | `/ACME/costs` | dark | ui/src/pages/Costs.tsx |
| `dark/costs/overview.png` | `/ACME/costs` | dark | ui/src/pages/Costs.tsx |
| `dark/costs/per-run-cost-detail.png` | `/ACME/costs` | dark | ui/src/pages/Costs.tsx |
| `dark/costs/providers.png` | `/ACME/costs` | dark | ui/src/pages/Costs.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/GitHubChatSetup.tsx, ui/src/pages/apps/chat/GitHubBotConfiguration.tsx, ui/src/pages/apps/chat/GitHubSetupPrompt.tsx, packages/shared/src/types/chat-github.ts |
| `dark/github-review/identity.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | dark | ui/src/pages/apps/chat/GitHubChatSetup.tsx, ui/src/pages/apps/chat/GitHubBotConfiguration.tsx, ui/src/pages/apps/chat/GitHubSetupPrompt.tsx, packages/shared/src/types/chat-github.ts |
| `dark/github-review/prompts.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | dark | ui/src/pages/apps/chat/GitHubChatSetup.tsx, ui/src/pages/apps/chat/GitHubBotConfiguration.tsx, ui/src/pages/apps/chat/GitHubSetupPrompt.tsx, packages/shared/src/types/chat-github.ts |
| `dark/github-review/repositories.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | dark | ui/src/pages/apps/chat/GitHubChatSetup.tsx, ui/src/pages/apps/chat/GitHubBotConfiguration.tsx, ui/src/pages/apps/chat/GitHubSetupPrompt.tsx, packages/shared/src/types/chat-github.ts |
| `dark/interactions/checkbox-confirmation-card.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.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/tasks/comment-input-box.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx |
| `dark/issues/my-issues.png` | `/ACME/inbox/mine` | dark | ui/src/pages/Inbox.tsx |
| `dark/onboarding/empty-dashboard.png` | `/{emptyPrefix}/dashboard` | dark | ui/src/pages/Dashboard.tsx |
| `dark/onboarding/goal-field.png` | `/onboarding` | dark | ui/src/components/OnboardingWizard.tsx |
| `dark/onboarding/new-company-modal-empty.png` | `/onboarding` | dark | ui/src/components/OnboardingWizard.tsx |
| `dark/org/chart.png` | `/ACME/org` | dark | ui/src/pages/OrgChart.tsx |
| `dark/org/org-chart-add-agent.png` | `/ACME/org` | dark | ui/src/pages/OrgChart.tsx |
| `dark/org/org-chart-manager-assigned.png` | `/ACME/org` | dark | ui/src/pages/OrgChart.tsx |
| `dark/org/org-chart-small-team.png` | `/ACME/org` | dark | ui/src/pages/OrgChart.tsx |
| `dark/org/org-chart-view.png` | `/ACME/org` | dark | ui/src/pages/OrgChart.tsx |
| `dark/org/skills-list.png` | `/ACME/skills` | dark | ui/src/pages/CompanySkills.tsx |
| `dark/routines/cron-picker.png` | `/ACME/routines/{routineId}/triggers` | dark | ui/src/pages/RoutineDetail.tsx |
| `dark/routines/detail.png` | `/ACME/routines/{routineId}` | dark | ui/src/pages/RoutineDetail.tsx |
| `dark/routines/list.png` | `/ACME/routines` | dark | ui/src/pages/Routines.tsx |
| `dark/routines/run-history.png` | `/ACME/routines/{routineId}` | dark | ui/src/pages/RoutineDetail.tsx |
| `dark/secrets/per-user-value-entry.png` | `/ACME/company/settings/secrets` | dark | ui/src/pages/Secrets.tsx |
| `dark/secrets/user-secret-definition.png` | `/ACME/company/settings/secrets` | dark | ui/src/pages/Secrets.tsx |
| `dark/settings/experimental.png` | `/ACME/company/settings/instance/experimental` | dark | ui/src/pages/InstanceExperimentalSettings.tsx |
| `dark/skills/add-skill-dialog-confirm.png` | `/ACME/skills` | dark | ui/src/pages/CompanySkills.tsx |
| `dark/skills/add-skill-dialog.png` | `/ACME/skills` | dark | ui/src/pages/CompanySkills.tsx |
| `dark/skills/assign-to-agent.png` | `/ACME/skills/{skillId}` | dark | ui/src/pages/CompanySkills.tsx |
| `dark/skills/file-inventory.png` | `/ACME/skills` | dark | ui/src/pages/CompanySkills.tsx |
| `dark/skills/list.png` | `/ACME/skills` | dark | ui/src/pages/CompanySkills.tsx |
| `dark/skills/skill-detail.png` | `/ACME/skills/{skillId}` | dark | ui/src/pages/CompanySkills.tsx |
| `dark/skills/skills-list.png` | `/ACME/skills` | dark | ui/src/pages/CompanySkills.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/TaskChatBubble.tsx, ui/src/components/task-chat/TaskChatTurn.tsx |
| `dark/tasks/comment-input-box.png` | `/ACME/issues/{issueId}` | dark | ui/src/pages/IssueDetail.tsx, ui/src/components/CommentThread.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 |
| `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 |
| `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, ui/src/components/IssueDocumentsSection.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 |
| `dark/work-timeline/work-timeline-handoff.png` | `/ACME/timeline` | dark | server/src/services/work-timeline.ts |
| `dark/work-timeline/work-timeline-overview.png` | `/ACME/timeline` | dark | server/src/services/work-timeline.ts |
| `light/activity/activity-filtered-by-agent.png` | `/ACME/activity` | light | ui/src/pages/audit/AuditFeed.tsx |
| `light/activity/activity-filters.png` | `/ACME/activity` | light | ui/src/pages/audit/AuditFeed.tsx |
| `light/activity/activity-log-full.png` | `/ACME/activity` | light | ui/src/pages/audit/AuditFeed.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/agents-list-empty.png` | `/{emptyPrefix}/agents/all` | light | ui/src/pages/Agents.tsx |
| `light/agents/budget.png` | `/ACME/agents/{agentId}/budget` | light | ui/src/pages/AgentDetail.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/instructions.png` | `/ACME/agents/{agentId}/instructions` | light | ui/src/pages/AgentDetail.tsx |
| `light/agents/list.png` | `/ACME/agents/all` | light | ui/src/pages/Agents.tsx |
| `light/agents/new-agent-reports-to-field.png` | `/ACME/agents/new` | light | ui/src/components/ReportsToPicker.tsx |
| `light/agents/new.png` | `/ACME/agents/new` | light | ui/src/pages/Agents.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/approvals/approvals-list.png` | `/ACME/approvals/pending` | light | ui/src/components/ApprovalCard.tsx |
| `light/approvals/approve-reject-buttons.png` | `/ACME/approvals/{hireApprovalId}` | light | ui/src/pages/ApprovalDetail.tsx |
| `light/approvals/approve-reject-revision-buttons.png` | `/ACME/approvals/{hireApprovalId}` | light | ui/src/pages/ApprovalDetail.tsx |
| `light/approvals/approved-approval.png` | `/ACME/approvals/{approvedApprovalId}?resolved=approved` | light | ui/src/pages/ApprovalDetail.tsx |
| `light/approvals/hire-approval-detail.png` | `/ACME/approvals/{hireApprovalId}` | light | ui/src/pages/ApprovalDetail.tsx |
| `light/approvals/revision-request-input.png` | `/ACME/approvals/{strategyApprovalId}` | light | ui/src/pages/ApprovalDetail.tsx |
| `light/approvals/strategy-approval-detail.png` | `/ACME/approvals/{strategyApprovalId}` | light | ui/src/pages/ApprovalDetail.tsx |
| `light/company/company-goal-field.png` | `/onboarding` | light | ui/src/components/OnboardingWizard.tsx |
| `light/company/join-requests.png` | `/ACME/inbox/requests` | light | ui/src/pages/Inbox.tsx |
| `light/company/new-company-form.png` | `/onboarding` | light | ui/src/components/OnboardingWizard.tsx |
| `light/costs/agent-budget-field.png` | `/ACME/agents/{agentId}/budget` | light | ui/src/pages/AgentDetail.tsx |
| `light/costs/billers.png` | `/ACME/costs` | light | ui/src/pages/Costs.tsx |
| `light/costs/budgets.png` | `/ACME/costs` | light | ui/src/pages/Costs.tsx |
| `light/costs/company-budget-field.png` | `/ACME/costs` | light | ui/src/pages/Costs.tsx |
| `light/costs/costs-dashboard-overview.png` | `/ACME/costs` | light | ui/src/pages/Costs.tsx |
| `light/costs/finance.png` | `/ACME/costs` | light | ui/src/pages/Costs.tsx |
| `light/costs/overview.png` | `/ACME/costs` | light | ui/src/pages/Costs.tsx |
| `light/costs/per-run-cost-detail.png` | `/ACME/costs` | light | ui/src/pages/Costs.tsx |
| `light/costs/providers.png` | `/ACME/costs` | light | ui/src/pages/Costs.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/GitHubChatSetup.tsx, ui/src/pages/apps/chat/GitHubBotConfiguration.tsx, ui/src/pages/apps/chat/GitHubSetupPrompt.tsx, packages/shared/src/types/chat-github.ts |
| `light/github-review/identity.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | light | ui/src/pages/apps/chat/GitHubChatSetup.tsx, ui/src/pages/apps/chat/GitHubBotConfiguration.tsx, ui/src/pages/apps/chat/GitHubSetupPrompt.tsx, packages/shared/src/types/chat-github.ts |
| `light/github-review/prompts.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | light | ui/src/pages/apps/chat/GitHubChatSetup.tsx, ui/src/pages/apps/chat/GitHubBotConfiguration.tsx, ui/src/pages/apps/chat/GitHubSetupPrompt.tsx, packages/shared/src/types/chat-github.ts |
| `light/github-review/repositories.png` | `/ACME/apps/chat/connect?provider=github&resume=github-review-docs-demo` | light | ui/src/pages/apps/chat/GitHubChatSetup.tsx, ui/src/pages/apps/chat/GitHubBotConfiguration.tsx, ui/src/pages/apps/chat/GitHubSetupPrompt.tsx, packages/shared/src/types/chat-github.ts |
| `light/interactions/checkbox-confirmation-card.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.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/tasks/comment-input-box.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx |
| `light/issues/my-issues.png` | `/ACME/inbox/mine` | light | ui/src/pages/Inbox.tsx |
| `light/onboarding/empty-dashboard.png` | `/{emptyPrefix}/dashboard` | light | ui/src/pages/Dashboard.tsx |
| `light/onboarding/goal-field.png` | `/onboarding` | light | ui/src/components/OnboardingWizard.tsx |
| `light/onboarding/new-company-modal-empty.png` | `/onboarding` | light | ui/src/components/OnboardingWizard.tsx |
| `light/org/chart.png` | `/ACME/org` | light | ui/src/pages/OrgChart.tsx |
| `light/org/org-chart-add-agent.png` | `/ACME/org` | light | ui/src/pages/OrgChart.tsx |
| `light/org/org-chart-manager-assigned.png` | `/ACME/org` | light | ui/src/pages/OrgChart.tsx |
| `light/org/org-chart-small-team.png` | `/ACME/org` | light | ui/src/pages/OrgChart.tsx |
| `light/org/org-chart-view.png` | `/ACME/org` | light | ui/src/pages/OrgChart.tsx |
| `light/org/skills-list.png` | `/ACME/skills` | light | ui/src/pages/CompanySkills.tsx |
| `light/routines/cron-picker.png` | `/ACME/routines/{routineId}/triggers` | light | ui/src/pages/RoutineDetail.tsx |
| `light/routines/detail.png` | `/ACME/routines/{routineId}` | light | ui/src/pages/RoutineDetail.tsx |
| `light/routines/list.png` | `/ACME/routines` | light | ui/src/pages/Routines.tsx |
| `light/routines/run-history.png` | `/ACME/routines/{routineId}` | light | ui/src/pages/RoutineDetail.tsx |
| `light/secrets/per-user-value-entry.png` | `/ACME/company/settings/secrets` | light | ui/src/pages/Secrets.tsx |
| `light/secrets/user-secret-definition.png` | `/ACME/company/settings/secrets` | light | ui/src/pages/Secrets.tsx |
| `light/settings/experimental.png` | `/ACME/company/settings/instance/experimental` | light | ui/src/pages/InstanceExperimentalSettings.tsx |
| `light/skills/add-skill-dialog-confirm.png` | `/ACME/skills` | light | ui/src/pages/CompanySkills.tsx |
| `light/skills/add-skill-dialog.png` | `/ACME/skills` | light | ui/src/pages/CompanySkills.tsx |
| `light/skills/assign-to-agent.png` | `/ACME/skills/{skillId}` | light | ui/src/pages/CompanySkills.tsx |
| `light/skills/file-inventory.png` | `/ACME/skills` | light | ui/src/pages/CompanySkills.tsx |
| `light/skills/list.png` | `/ACME/skills` | light | ui/src/pages/CompanySkills.tsx |
| `light/skills/skill-detail.png` | `/ACME/skills/{skillId}` | light | ui/src/pages/CompanySkills.tsx |
| `light/skills/skills-list.png` | `/ACME/skills` | light | ui/src/pages/CompanySkills.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/TaskChatBubble.tsx, ui/src/components/task-chat/TaskChatTurn.tsx |
| `light/tasks/comment-input-box.png` | `/ACME/issues/{issueId}` | light | ui/src/pages/IssueDetail.tsx, ui/src/components/CommentThread.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 |
| `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 |
| `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, ui/src/components/IssueDocumentsSection.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 |
| `light/work-timeline/work-timeline-handoff.png` | `/ACME/timeline` | light | server/src/services/work-timeline.ts |
| `light/work-timeline/work-timeline-overview.png` | `/ACME/timeline` | light | server/src/services/work-timeline.ts |
docs/administration/plugins.md
+11 -3
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.1001.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.
---
@@ -99,7 +99,7 @@ This used to be a Kubernetes-only shortcut. It's now a general path with a fixed
| `modal` | `paperclip.modal-sandbox-provider` |
| `novita` | `paperclip.novita-sandbox-provider` |
The table is the whole allowlist: nothing outside it can arrive through auto-provisioning, no matter what an instance is configured to ask for. Everything else — reference examples, first-party plugins, third-party packages — still gets installed by you, the ordinary way.
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.
@@ -129,7 +129,15 @@ Two environment variables let you point provisioning somewhere else on disk, whi
- `PAPERCLIP_BUNDLED_PLUGIN_ROOT` — relocates the bundled plugin catalog root. It defaults to `/app/packages/plugins`, the location inside the release image.
- `PAPERCLIP_KUBERNETES_PLUGIN_PATH` — points the `kubernetes` entry at a specific bundle path wherever it lives. This one predates the catalog and is kept for compatibility.
On a cloud-managed instance the list comes from the fleet instead, as part of the managed configuration document the harness hands the instance ([Cloud-managed instances](../reference/deploy/environment-variables.md#cloud-managed-instances) has the details). That list is checked strictly: a key that isn't in the table above, or a bundle path that resolves outside the catalog root, makes the instance refuse to start rather than load something unexpected into the host. Failing loudly at boot is the point.
On a cloud-managed instance the list comes from the fleet instead, as part of the managed configuration document the harness hands the instance ([Cloud-managed instances](../reference/deploy/environment-variables.md#cloud-managed-instances) has the details). That list is checked strictly: a key that isn't in the table above or in the image's distribution catalog, or a bundle path that resolves outside the catalog root, makes the instance refuse to start rather than load something unexpected into the host. Failing loudly at boot is the point.
### Plugins shipped inside a custom image
If you build your own Paperclip image — for a managed fleet or an in-house distribution — you can ship extra, prebuilt plugins inside it without adding them to Paperclip's built-in table. Put each plugin's built package in its own folder under a `distribution` directory in the bundled plugin catalog root, and list them in `distribution/catalog.json`. Each entry names the plugin's `key`, its `pluginKey`, the exact `version`, the `directory` it lives in, and a `digest` (`sha256:` followed by a hash of the folder's files).
Paperclip checks the catalog before it runs any plugin code. The folder's contents must match the digest, the package's version and plugin ID must match the entry, its entrypoints must already be built, and nothing in it may be a symlink. An entry can't reuse the key or plugin ID of a built-in plugin. If any of that fails, Paperclip won't load the plugin — and for a bad catalog, digest, version, or entrypoint the server refuses to start rather than load something it can't vouch for. Once an entry passes, its `key` can go in the instance's auto-install list like any built-in key.
Upgrading the image upgrades these plugins in place, but with one safeguard: if the new version asks for capabilities the installed one didn't have, the plugin lands in `upgrade_pending` and stays offline until an operator approves it on the plugin's detail page — exactly like any other upgrade. Disabled plugins stay disabled, and a plugin someone deliberately uninstalled stays uninstalled on a self-hosted instance.
---
docs/connectors.md
+20 -7
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Paperclip Connectors
seo_description: Every service Paperclip can connect, grouped by what it is for, with the access model, action permissions, and a setup guide behind each one.
---
@@ -7,7 +8,7 @@ seo_description: Every service Paperclip can connect, grouped by what it is for,
A **connector** is a saved connection to an outside service: a Gmail mailbox, a GitHub organization, a Notion workspace, a PostHog project. You set one up once, decide who and what it is for, and Paperclip carries that decision into every run.
> **Note:** These guides cover the connector model in Paperclip **v2026.916.0**. Available methods depend on your installed version, instance configuration, and provider approval. A catalog listing does not by itself establish that provider sign-in is available.
> **Note:** These guides cover the connector model in Paperclip **v2026.1001.0**. Available methods depend on your installed version, instance configuration, and provider approval. A catalog listing does not by itself establish that provider sign-in is available.
> **Warning:** **Google verification pending.** Paperclip has not yet completed Google app verification. You may see an unverified-app warning during authorization. If Google offers an **Advanced** option to continue to Paperclip, you can choose to proceed after reviewing the requested access. This option is not available for every account; Workspace administrator restrictions and other Google access requirements still apply. Contact [[email protected]](mailto:[email protected]) if you cannot connect.
@@ -41,7 +42,7 @@ Every row in the catalog lists the methods that connector supports. The names me
| Provider app registration | You create an app or bot in the provider's developer console, give it the documented permissions and events, and connect its credentials. Provider-specific channel guides describe exceptions, such as managed inboxes. |
| No credential | Nothing to sign in to. You identify the target — a store domain, a generated URL, a shared file — and that is the whole setup. |
Which methods you actually see depends on your instance. **Connect with Paperclip** is hidden unless your instance is enrolled with Paperclip Cloud and Cloud advertises a profile for that connector. Every chat channel, and AgentMail's email inboxes with them, is behind the **Chat connectors** instance setting, which is off by default. Each connector page lists its own prerequisites.
Which methods you actually see depends on your instance. **Connect with Paperclip** is hidden unless your instance is enrolled with Paperclip Cloud and Cloud advertises a profile for that connector. Every chat channel, and AgentMail's email inboxes with them, is behind the **Chat connectors** instance setting, which is off by default. The [MCP aggregators](#mcp-aggregators) are behind a separate **MCP aggregators** setting, also off by default. Each connector page lists its own prerequisites.
## The catalog
@@ -67,17 +68,28 @@ Find an app and open its setup guide.
| Connector | What you can do | Connection methods |
| --- | --- | --- |
| [Arcade](connectors/arcade.md) | Tool gateway combining the tools you select from several servers behind one URL. Agents use the exposed tools; authentication follows your gateway settings. Setup is unverified. | Gateway URL · Browser sign-in or token/headers |
| [Arcade](connectors/arcade.md) | Tool gateway combining the tools you select from several servers behind one URL. Agents use the exposed tools; authentication follows your gateway settings. Setup is unverified. Needs the experimental **MCP aggregators** setting. | Gateway URL · Browser sign-in or token/headers |
| [Asana](connectors/asana.md) | Work management for team projects, tasks, and goals. Agents work with the projects and tasks your Asana app can reach. | Your own OAuth app |
| [Composio](connectors/composio.md) | App discovery and execution through Composio Connect or a configured session. Upstream app authorization happens in Composio; broad execution actions need separate review. Setup is unverified. | Composio Connect sign-in · Configured session URL and headers |
| [Executor](connectors/executor.md) | One remote endpoint for configured integrations. Agents use its exposed actions within Executor's upstream policies. Setup is unverified. | Deployment URL · Browser sign-in or token/headers |
| [Composio](connectors/composio.md) | App discovery and execution through Composio Connect or a configured session. Upstream app authorization happens in Composio; broad execution actions need separate review. Setup is unverified. Needs the experimental **MCP aggregators** setting. | Composio Connect sign-in · Configured session URL and headers |
| [Executor](connectors/executor.md) | One remote endpoint for configured integrations. Agents use its exposed actions within Executor's upstream policies. Setup is unverified. Needs the experimental **MCP aggregators** setting. | Deployment URL · Browser sign-in or token/headers |
| [Fireflies](connectors/fireflies.md) — **Live exception; not yet stable** | Meeting transcripts, summaries, and action items the connected account can access. Setup is unverified. | Sign in with Fireflies · API key |
| [Jira](connectors/jira.md) | Atlassian's issue tracker for software teams. Agents work with the issues on the Jira site you connect. | Sign in with Jira |
| [Linear](connectors/linear.md) | Issue tracking for product and engineering teams. Agents create, update, and read issues across whatever the authorizing Linear account can reach. | Your own OAuth app |
| [Miro](connectors/miro.md) | Shared online whiteboards for diagrams, planning, and workshops. Agents work with the boards your Miro account can reach. | Sign in with Miro |
| [Notion](connectors/notion.md) | Workspace for notes, documents, and databases. Agents read and update content accessible to the Notion account you authorize. Paperclip does not add a page-level filter. | Sign in with Notion |
| [Todoist](connectors/todoist.md) | Task lists for individuals and small teams. Agents work with the tasks and projects in your Todoist account. | Sign in with Todoist |
| [Zapier](connectors/zapier.md) | Automation service that wires thousands of apps together. You choose the actions in Zapier and paste one generated URL, so the agent gets the actions you put in it. Treat that URL as a secret — its token is part of the address. | Generated MCP URL |
| [Zapier](connectors/zapier.md) | Automation service that wires thousands of apps together. You choose the actions in Zapier and paste one generated URL, so the agent gets the actions you put in it. Treat that URL as a secret — its token is part of the address. Hidden until an administrator turns on the experimental **MCP aggregators** setting. | Generated MCP URL |
### MCP aggregators
Services that connect to many apps for you and hand them to Paperclip through one MCP server. Use one for an app that has no native connector here. They are experimental: setup for all four stays hidden until an administrator turns on **MCP aggregators** in the instance's experimental settings, which is off by default. See [Connect apps through an MCP aggregator](connectors/mcp-aggregators.md) for setup.
| Connector | What you can do | Connection methods |
| --- | --- | --- |
| [Arcade](connectors/mcp-aggregators.md) | Use the tools exposed by an Arcade MCP gateway you set up. | Connect MCP server |
| [Composio](connectors/mcp-aggregators.md) | Discover and use connected apps through Composio Connect. | Composio Connect |
| [Executor](connectors/mcp-aggregators.md) | Use the tools exposed by your Executor workspace. | Connect MCP server |
| [Zapier](connectors/zapier.md) | The actions you put on a Zapier MCP server. Also listed under Productivity. Needs the experimental **MCP aggregators** setting. | Generated MCP URL |
### Communication
@@ -170,7 +182,7 @@ The catalog above describes the documented connectors for this release. If the s
**Connect it as a custom server.** If the service publishes its own remote MCP server, you can connect it directly without waiting for a catalog entry. It gets the same identity, grant, agent-selection, and per-action controls as a catalog connector. See [Connect a custom MCP server](connectors/custom-mcp-servers.md) for the compatibility requirements and the two ways to supply a URL.
**Reach it through automation you already own.** [Zapier](connectors/zapier.md) covers a long tail of apps that have no MCP server of their own. You pick the actions on Zapier's side, which also means the agent cannot exceed them.
**Reach it through an MCP aggregator.** [Arcade, Composio, Executor, and Zapier](connectors/mcp-aggregators.md) each connect to many apps on your behalf, once an administrator turns on the experimental **MCP aggregators** setting. With Zapier you pick the actions on Zapier's side, which also means the agent cannot exceed them.
**Give the agent a workspace instead.** Some work does not need a connector at all. Anything an agent can do with a shell and a CLI belongs in an execution workspace — see [Connect an agent to a GitHub repo](how-to/connect-agent-to-github.md) for the pattern, and [Add an MCP server to an agent](how-to/add-mcp-server-to-agent.md) for the adapter-level route.
@@ -197,6 +209,7 @@ Use these guides for the controls your connector exposes. Action permissions and
| [Verify a connector and fix a broken one](connectors/verify-and-troubleshoot.md) | Checking a new connection, or a working one has stopped. |
| [Reauthorize, revoke, or disconnect](connectors/reauthorize-and-disconnect.md) | Rotating a credential, removing one person's access, or deleting the connection. |
| [Connect a custom MCP server](connectors/custom-mcp-servers.md) | The service is not in the catalog, or you have a URL or config to paste. |
| [Connect apps through an MCP aggregator](connectors/mcp-aggregators.md) | The app has no native connector. |
## Related
docs/connectors/arcade.md
+2
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Arcade Connector
seo_description: Connect tools selected in an Arcade gateway, choose agent access, and check authentication and action permissions. Setup is unverified.
---
@@ -9,6 +10,7 @@ Arcade gives agents access to the tools selected in your Arcade gateway. The gat
## Before you connect
- The experimental **MCP aggregators** setting turned on. It is off by default, and until an administrator turns it on, Arcade does not appear in **Connectors**. See [MCP aggregators](mcp-aggregators.md#turn-them-on-first).
- An Arcade account and a gateway with the tools you want to expose.
- The gateway URL and the authentication mode chosen by its owner.
docs/connectors/composio.md
+2
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Composio Connector
seo_description: Connect Composio Connect or a configured session URL. Understand app authorization, aggregator permissions, and unverified setup steps.
---
@@ -9,6 +10,7 @@ Composio lets agents discover and use apps through Composio Connect. App authori
## Before you connect
- The experimental **MCP aggregators** setting turned on. It is off by default, and until an administrator turns it on, Composio does not appear in **Connectors**. See [MCP aggregators](mcp-aggregators.md#turn-them-on-first).
- A Composio account and access to the apps you intend to authorize.
- For an externally configured session, its URL and required headers from its owner.
docs/connectors/custom-mcp-servers.md
+4
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Connect a Custom MCP Server
seo_description: Add an MCP server that is not in the Paperclip catalog by URL, by pasting a config, or with a provider-generated URL, and govern it like any connector.
---
@@ -33,6 +34,8 @@ Some providers hand you a single URL with the token already embedded. Zapier is
The URL is a secret. Anyone holding it holds the access. Paperclip stores it as one, and the connection's action permissions apply the same way they do to any other connector.
Arcade, Composio, and Executor work much the same way — you paste the MCP URL their service gives you, and sign in if it asks — but each has its own catalog entry with setup steps for that provider. They are behind the experimental **MCP aggregators** setting, which is off by default. If the app you want is reachable through one of them, start with [Connect apps through an MCP aggregator](mcp-aggregators.md) instead of a custom server.
## The two generic definitions behind this
Paperclip has two catalog entries that exist to back the generic paths rather than to be browsed:
@@ -63,4 +66,5 @@ Attaching an MCP server to an agent's *runtime* — through the adapter's own co
- [How connector access works](access-model.md)
- [Set action permissions](action-permissions.md)
- [Zapier](zapier.md)
- [Connect apps through an MCP aggregator](mcp-aggregators.md)
- [Tool Gateway](../reference/api/tool-gateway.md)
docs/connectors/executor.md
+2
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Executor Connector
seo_description: Connect a hosted Executor endpoint and govern its exposed actions. Includes upstream policy boundaries and explicitly unverified setup.
---
@@ -9,6 +10,7 @@ Executor puts one endpoint in front of configured integrations. Paperclip connec
## Before you connect
- The experimental **MCP aggregators** setting turned on. It is off by default, and until an administrator turns it on, Executor does not appear in **Connectors**. See [MCP aggregators](mcp-aggregators.md#turn-them-on-first).
- An Executor deployment with the integrations and connections you intend to expose.
- A reachable remote endpoint URL and its required authentication details.
docs/connectors/mcp-aggregators.md
+77
View File
@@ -0,0 +1,77 @@
---
paperclip_version: v2026.1001.0
seo_title: Connect Apps Through an MCP Aggregator
seo_description: Reach apps that have no native Paperclip connector through Arcade, Composio, Executor, or Zapier, behind an experimental setting that is off by default.
---
# Connect apps through an MCP aggregator
Some apps have no connector of their own in Paperclip. An **MCP aggregator** fills that gap: it is an outside service that connects to many apps on your behalf and hands them to Paperclip through one MCP server. Paperclip supports four of them — **Arcade**, **Composio**, **Executor**, and **Zapier** — each with its own entry on the **Connectors** page.
Keep one thing in mind throughout: the aggregator sits between your agent and the app. It holds the app sign-ins and carries the requests. Paperclip still decides which people and agents can use the connection and which of its tools they may call, but anything the aggregator does inside the app is governed on the aggregator's side.
## Turn them on first
MCP aggregators are experimental. All four stay hidden from **Connectors** until an instance administrator turns on **MCP aggregators** in the instance's experimental settings, which is off by default. While the setting is off, Paperclip also refuses new setup, reconnect, and sign-in requests for these providers. Turning it off later hides setup only; connections you already have keep running.
## Native connectors come first
If Paperclip has its own connector for an app, use that. It is the path Paperclip reviews. An aggregator is for the app that has no native connector.
## The four providers
Each provider has its own catalog entry and its own connection. The setup screen shows the steps for the provider you picked, with a link to that provider's guide.
| Provider | What you paste | Sign-in |
| --- | --- | --- |
| **Arcade** | The MCP gateway URL for a gateway you created in Arcade, with its tools selected. | Browser sign-in when the gateway asks for it. |
| **Composio** | Nothing, usually: the **Composio Connect** URL is prefilled. Replace it only if you set up a Composio session elsewhere. | Browser sign-in with your Composio account. |
| **Executor** | The MCP URL from your Executor workspace's connection instructions. A self-hosted endpoint works if Paperclip can reach it. | Browser sign-in when prompted. |
| **Zapier** | The complete server URL from a Zapier MCP server, token included. See [Zapier](zapier.md). | None — the token is part of the URL, so treat the URL as a secret. |
## Set one up
1. In the left sidebar, select **Connectors**, find the provider, and select it.
2. **Access.** Choose which humans can use the connection and which agents may use it. These are the same choices every connector asks for; [Share a connector with people and agents](share-access.md) explains them.
3. **Connect.** Paste the address into **MCP server URL** and select **Connect**. Paperclip shows *"Connecting and discovering tools…"* while it reaches the server and reads its tool list.
4. If the provider needs a sign-in, a provider window opens. Finish there and come back; Paperclip waits for confirmation.
5. Review **Permissions** and set each tool to **Allowed**, **Ask first**, or **Off**, as on any connector — see [Set action permissions](action-permissions.md).
A URL that is not an MCP endpoint is caught straight away with *"Enter a valid MCP URL"*. A dashboard page is not an MCP endpoint, so copy the server URL the provider gives you.
### Advanced authentication
Most setups need nothing more than the URL. If your provider gave you a token or headers instead of a browser sign-in, open **Advanced authentication** and pick one of:
- **Automatic (sign in if required)** — the default for providers that support browser sign-in.
- **Bearer token** — paste the token only, without the word Bearer.
- **Custom headers** — add each header name and value the provider supplied.
- **No additional authentication** — the URL alone is enough.
Two provider-specific notes from the setup screen: for Arcade headers, use an API key as the bearer token and add the `Arcade-User-ID` header for the acting user. For Executor, an API key must be a user key; workspace and organization keys cannot open an MCP session.
### If sign-in does not finish
Cancelling the sign-in does not lose your work. Paperclip shows *"Connection cancelled. Your setup details are preserved; try again when you are ready."* and the button becomes **Try again**. If you need to stop partway, you can leave and pick it up later — the connection shows **Resume setup** with your access choices intact.
## What Paperclip controls, and what it does not
Paperclip controls access to the tools it lists for the connection. App and action permissions inside those tools are managed in the provider.
So set up both layers deliberately:
- In the provider, connect only the apps you need and expose only the actions you need.
- In Paperclip, start writes at **Off** or **Ask first**, and run **Refresh tools** after you change the provider's setup, then review what appeared.
## Old Composio connections
Composio connections made through Paperclip's earlier Composio integration no longer run. Add a new Composio connection from **Connectors**, set it up, then remove the old one. Credentials and permissions do not carry over. [Providers Paperclip recognizes but does not list](recognized-providers.md#composio-listed-again-old-connections-retired) has the details.
## Related
- [Connectors](../connectors.md)
- [Connect a custom MCP server](custom-mcp-servers.md)
- [Zapier](zapier.md)
- [How connector access works](access-model.md)
- [Set action permissions](action-permissions.md)
- [Tool Gateway](../reference/api/tool-gateway.md)
docs/connectors/recognized-providers.md
+12 -2
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Recognized but Unlisted Providers
seo_description: The provider definitions present in the Paperclip catalog but withheld from the Connectors list, and the providers that gate access behind their own approval.
---
@@ -9,7 +10,7 @@ Reference for the inventory behind the catalog. If you are looking for a connect
Two separate things get confused here, so they are listed separately. A **withheld** provider has a complete definition that Paperclip still recognizes, but it is deliberately kept out of the customer-facing list. A **provider-gated** one is not offered because the provider itself will not let an independently registered client connect.
> **Note:** Checked against Paperclip **v2026.916.0**. Catalog visibility can change between releases; recognition is not a promise of availability. Existing connections still need to be verified independently.
> **Note:** Checked against Paperclip **v2026.1001.0**. Catalog visibility can change between releases; recognition is not a promise of availability. Existing connections still need to be verified independently.
## Withheld from the Connectors list
@@ -26,7 +27,6 @@ None of these have connector pages, and none can be added from the catalog.
| Brex | `brex` |
| Candid | `candid` |
| Coda | `coda` |
| Composio | `composio` |
| Context7 | `context7` |
| Egnyte | `egnyte` |
| Embat | `embat` |
@@ -43,6 +43,16 @@ None of these have connector pages, and none can be added from the catalog.
| TickTick | `ticktick` |
| Xero | `xero` |
## Composio: listed again, old connections retired
Composio used to sit in the withheld list above. It is back in the **Connectors** list as a remote MCP connection through Composio Connect, one of the MCP aggregators. Like the other aggregators, it only appears once an administrator turns on the experimental **MCP aggregators** setting, which is off by default — see [Connect apps through an MCP aggregator](mcp-aggregators.md).
Connections made through the older Composio broker are a different matter. That broker is retired, so those connections no longer run: they show as unhealthy, their tools are not offered to agents, and calls to them are refused. Paperclip tells you what to do in the connection itself:
> *"This legacy Composio connection is no longer supported. Add a new Composio MCP connection from Connectors, then remove this connection. Existing credentials and permissions are not migrated."*
In practice: with **MCP aggregators** turned on, connect Composio again from **Connectors**, set up access and action permissions on the new connection, then remove the old one. Nothing carries over automatically.
## Gated by the provider
These three are recorded as blocked because of a requirement on the provider's side. The requirement is theirs, not Paperclip's, and it has to be lifted or granted by them — there is no setting in Paperclip that works around it.
docs/connectors/separate-accounts.md
+2 -1
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Separate Accounts for Agents
seo_description: Pick between a personal credential, one shared organization identity, and an account dedicated to a single agent, and see what each choice changes.
---
@@ -21,7 +22,7 @@ Any active member can create one. Use it for a first connector, for anything tou
### Organization identity
One account shared with eligible people in the company. Setup can label this **Any human in the company**; the connection's human audience determines whose runs may use it. You separately choose which agents may use the connection. Sharing a credential does not bypass either audience.
One account shared with eligible people in the company. Setup can label this **Any human in the organization**; the connection's human audience determines whose runs may use it. You separately choose which agents may use the connection. Sharing a credential does not bypass either audience.
Creating one is a manager operation. Paperclip enforces this on the server: *"Only a connection manager can share this credential with the organization."*
docs/connectors/slack.md
+97 -65
View File
@@ -1,40 +1,115 @@
---
paperclip_version: v2026.1001.0
seo_title: Slack Connector
seo_description: Two independent Slack setups: Slack as an agent tool, or as a channel people use to reach an agent. Which to pick, how to set up each, and fixes.
seo_description: Connect a Slack bot so people can work with an agent from Slack: guided setup, account linking, channel settings, and fixes for common problems.
---
# Slack
Slack does two unrelated jobs in Paperclip, and they are separate connections with separate credentials.
Slack gives your team a way to work with an agent without leaving the conversation. Someone mentions the agent in a channel, Paperclip turns that into a task, and the reply lands back in the thread.
> **Warning:** Slack is available, but it is not yet fully functional. Follow-up fixes are planned. Review the agent-tool limitations below before relying on it for production work; the separate chat-channel route is experimental.
There are two separate Slack connections in Paperclip, with separate credentials. For most teams, **Chat with an agent** is the one you want.
> **Warning:** Slack is available, but it is not yet fully functional. Follow-up fixes are planned. The chat route is behind an experimental setting, and the separate agent-tool route has known compatibility limitations. Review both sections before relying on Slack for production work.
## Which do you want?
| If you want | Set up | What it gives you |
| --- | --- | --- |
| Agents to search Slack and post messages as part of their own work | **Use this connection as an agent tool** | Slack actions an agent can call, governed by action permissions |
| People to start and continue work by talking to an agent in Slack | **Chat with an agent** | A Slack app that turns mentions and DMs into Paperclip tasks |
| People to start and continue work by talking to an agent in Slack | **Chat with an agent** | A Slack bot for one agent: mentions and DMs become Paperclip tasks, and replies come back in Slack |
| An agent to use Slack's own hosted MCP server with a personal Slack authorization | **Use this connection as an agent tool** | Slack's MCP actions, governed by action permissions |
Connecting one does not connect the other. They need different credentials and prerequisites. Check the agent-tool compatibility notice before planning to use both.
Connecting one does not connect the other. When **Chat connectors** is on and you pick **Slack** under **Connectors**, Paperclip asks **Choose how to connect** and offers both options.
---
## Slack as a channel
People mention the agent in a channel or send it a direct message, and Paperclip creates a task. Replies come back in the thread.
### Before you connect
- **Chat connectors** must be switched on for the instance. It is an experimental setting, off by default, enabled by an instance administrator under experimental settings.
- A publicly reachable HTTPS address for the instance. Slack delivers events by calling Paperclip; this route does not use Slack's socket mode. Paperclip Cloud already has one. If you self-host, a private address (for example, a Tailscale Serve URL only your tailnet can reach) is not enough. The wizard shows **Public HTTPS URL required** with a **Learn how to set up HTTPS** link when this is missing.
- Permission to create and install a Slack app in the workspace.
- A Paperclip account that is a member of the company, so you can link your own Slack account at the end.
### Connect it
Open **Connectors**, select **Slack**, then **Chat with an agent**. A guided setup walks you through seven steps, shown in the sidebar. You can leave at any point with **Save & exit** and come back through **Finish setup** on the connection's row; your progress is kept.
1. **Choose agent.** Pick the agent people will talk to. This agent is permanent for the connection; to represent a different agent, connect another Slack app.
2. **Create Slack app.** Review the **Slack app name**, **Bot display name**, and **Slash command**. Paperclip fills them in from the agent's name, and every later instruction uses whatever you save here. Click **Create Slack app**: Slack opens in a new tab with Paperclip's manifest already filled in. Pick your workspace, create the app, and install it. If you made the app earlier, use **I already created the app** instead. To inspect the generated configuration, open **View Slack App Manifest**.
3. **Add credentials.** The two secrets live on different Slack screens, and the wizard gives you directions next to each field:
- **Bot User OAuth Token**, from **OAuth & Permissions**. It starts with `xoxb-`.
- **Signing Secret**, from **Basic Information**. It has no token prefix. An `xapp-` app token is not the signing secret.
Click **Connect Slack app**.
4. **Verify Slack connection.** In your Slack app, choose **Event Subscriptions**. Beside the prefilled **Request URL**, click **Retry** if it isn't verified yet, and save if Slack asks. Paperclip moves on by itself once Slack has verified the connection.
5. **Add avatar** (optional). Download your agent's avatar as a 512 × 512 PNG, then upload it in Slack under **Basic Information** → **Display Information** → **App icon & Preview** and click **Save Changes**. Click **I’ve uploaded the avatar**, or **Skip for now**. The download stays available in the connection's **Settings** under **Agent avatar**.
6. **Connect your Slack account.** Copy the command Paperclip shows (your slash command followed by `connect`, for example `/yourbot connect`) and send it in your Slack workspace. It only identifies you; it does not start any agent work. When your Slack account appears in Paperclip, click **This is my Slack account**. Only confirm an account that belongs to you. You'll see **Linked to you**, then **Continue to message test**.
7. **Try it** (optional). Open a channel, invite the bot if needed, and send the suggested message, for example `@yourbot you there?`. Pick the bot from Slack's @mention suggestions so it is really notified. Continue the conversation in the thread. Paperclip checks for your message automatically; finish with **I've sent the test message** or **Skip test and finish**.
Use the generated manifest rather than configuring scopes by hand. It is the supported configuration, and hand-picked scopes are the most common reason a setup half-works.
> **Danger:** The bot token and signing secret are full credentials for the app. Paste them only into Paperclip. If either leaks, rotate it in Slack and reconnect.
### How a conversation becomes work
| In Slack | In Paperclip |
| --- | --- |
| A linked person mentions the agent in a channel | One task per new mentioned thread |
| A linked person sends the agent a direct message | The agent replies in the DM (when **Allow direct messages** is on) |
| The conversation continues in the thread | It continues on the same task |
Paperclip acknowledges with a reaction so people can see a message was picked up before the agent has finished thinking.
### Reply from Paperclip
A Slack-linked task shows a **Connected to Slack** banner with an **Open Slack** link. To post something into the Slack conversation from Paperclip, write it in the banner's composer and click **Send to channel**. Write only what should be visible in Slack. You can attach files to the same send.
### Settings and access
The connection's page has **Settings**, **Access**, **Conversations**, and **Activity** tabs.
- **Settings** repeats the suggested first message under **Chat in Slack**, and holds the avatar download and **Additional communication instructions**. Under **Where this agent can work**, **Allowed Channels** lists the channels Paperclip has discovered the bot in, and there's an **Allow direct messages** toggle.
- **Access** holds identity links and the **Allow unlinked people** setting.
**Allowed Channels** controls where the agent answers. A channel the bot is newly invited to starts switched off, apart from the channel you used for the setup test, so turn a channel on before you expect replies there.
By default, the agent replies conversationally in Slack: answer first, short paragraphs or short lists, with bigger deliverables attached or linked. Use **Additional communication instructions** (up to 4,000 characters) to add your own guidance, such as product names or audience. It applies when new tasks start, and does not grant any extra permissions.
### Access
Provider channel access determines where a message can reach the integration; it does not by itself authorize agent work. Paperclip also checks the sender's linked identity and company membership. Linked users must be active non-viewer members, and their messages run with their own Paperclip permissions.
To let a teammate use the agent, share the instructions under **Invite others to connect their Slack accounts** on the **Access** tab:
1. They send the connect command in your Slack workspace.
2. The bot sends them a private link. They open it, sign in to Paperclip, and confirm their Slack account. The link expires in 15 minutes and works once.
3. If they aren't a member of the organization yet, they choose **Request access**, and an admin approves the request before they can link.
Nobody needs to create another Slack app or share credentials.
**Allow unlinked people** is off for new connections. When on, unlinked senders are restricted guests: their tasks run only with an isolated workspace and sandbox environment, and they cannot approve, hire, spend, manage access, or reassign agents.
---
## Slack as an agent tool
An agent uses a Slack workspace credential to search messages, read channel lists, and post — on its own initiative, inside its own task.
This route connects an agent to Slack's own hosted MCP server, using a personal Slack authorization instead of a bot.
### Agent-tool compatibility notice
**The Slack agent-tool route is available but has known compatibility limitations in v2026.916.0.** That release configures OAuth endpoints and scopes that differ from Slack's current hosted MCP requirements. A successful bot installation does not verify an MCP connection.
**The Slack agent-tool route is available but has known compatibility limitations in v2026.1001.0.** That release still configures OAuth endpoints and scopes that differ from Slack's current hosted MCP requirements. A successful bot installation does not verify an MCP connection.
Slack MCP requires a registered internal or marketplace-published app, user-token OAuth endpoints, and the user scopes for the intended tools. See [Slack's MCP authentication requirements](https://docs.slack.dev/ai/slack-mcp-server/). Bot-token setup is for the separate chat-channel path below.
Slack MCP requires a registered internal or marketplace-published app, user-token OAuth endpoints, and the user scopes for the intended tools. See [Slack's MCP authentication requirements](https://docs.slack.dev/ai/slack-mcp-server/).
Wait for a release with verified Slack MCP compatibility, or contact [[email protected]](mailto:[email protected]) before attempting this route. The access notes below explain the intended tool behavior; they are not a record of successful setup on this release.
### Access and actions
Channel reach is Slack's decision: the authorized token sees what its scopes and the workspace allow, and private channels require the authorizing user or bot to be a member. Paperclip does not have a channel picker, so narrow access on the Slack side.
Channel reach is Slack's decision: the authorized token sees what its scopes and the workspace allow, and private channels require the authorizing user to be a member. Paperclip does not have a channel picker on this route, so narrow access on the Slack side.
Slack's server supplies the action list. Posting is classified as a write, so leave it on **Ask first** unless you want an agent posting to a shared workspace unprompted. Open the connection's **Permissions** tab for the live list. See [Set action permissions](action-permissions.md).
@@ -50,70 +125,26 @@ A read confirms the credential without putting a message in front of colleagues.
---
## Slack as a channel
People mention the agent in a channel or send it a direct message, and Paperclip creates a task. Replies come back in the thread.
### Before you connect
- **Chat connectors** must be switched on for the instance. It is an experimental setting, off by default, enabled by an instance administrator under experimental settings.
- A publicly reachable HTTPS address for the instance. Slack delivers events by calling Paperclip; this route does not use Slack's socket mode.
- Permission to create and install a Slack app in the workspace.
- The agent that will answer.
### Connect it
1. Open **Connectors**, select **Slack**, then **Chat with an agent**.
2. On the **Access** step, choose the identity and which agents may use the connection.
3. Paperclip generates a **Slack app manifest** containing exactly the scopes, events, and request URL this route needs. Copy it.
4. At [Slack API apps](https://api.slack.com/apps), create an app **from the manifest** rather than configuring scopes by hand, then install it in the workspace.
5. Back in Paperclip, paste the **Bot User OAuth Token** (it starts with `xoxb-`) and the **Signing Secret**.
6. Choose the agent that will answer, and finish.
Use the generated manifest. It is the supported configuration, and hand-picking scopes is the most common reason a channel setup half-works.
> **Danger:** The bot token and signing secret are full credentials for the app. Paste them only into Paperclip. If either leaks, rotate it in Slack and reconnect.
### How a conversation becomes work
| In Slack | In Paperclip |
| --- | --- |
| Someone mentions the agent in a channel | One task per new mentioned thread |
| Someone sends the agent a direct message | The agent replies in the DM |
| The conversation continues in the thread | It continues on the same task |
Paperclip acknowledges with a reaction so people can see a message was picked up before the agent has finished thinking.
### Access
Provider channel or repository access determines where a message can reach the integration; it does not by itself authorize agent work. Paperclip also checks the sender's linked identity and company membership. Linked users must be active non-viewer members. Unlinked senders depend on the connection's **Allow unlinked people** setting and any sponsor requirements. Review these controls before inviting people to use the agent.
### Try it
1. Invite the app to a private channel you control.
2. Mention it: `@YourAgent hello, can you confirm you are connected?`
3. Expect a reaction, then a threaded reply, and a matching task in Paperclip.
> **Note:** Procedure, not a recorded test result. Use a private channel for the first attempt.
---
## Troubleshooting
| Problem | Likely cause | Fix |
| --- | --- | --- |
| **Chat with an agent** is not offered | **Chat connectors** is off for the instance | Ask an administrator to enable it |
| The tool route asks for a client ID and secret | Expected — Slack requires your own OAuth app on this route | Register the app in Slack's console |
| Slack refuses to install the app | The workspace restricts app installation or requires approval | Ask a workspace administrator |
| The channel app is installed but silent | Slack cannot reach the instance, or the app was not created from Paperclip's manifest | Confirm the public HTTPS address, then recreate the app from the manifest |
| A mention in a channel does nothing | The app is not a member of that channel | Invite it to the channel |
| Private channel content is missing on the tool route | The authorizing identity is not a member | Add it to the channel in Slack |
| **Public HTTPS URL required** appears | Slack can't reach the instance | Put the instance behind a public HTTPS address, then continue |
| Slack refuses to install the app | The workspace restricts app installation or requires approval | Ask a workspace administrator, then resume with **Finish setup** |
| Paperclip warns about the signing secret | You pasted a bot or app token into **Signing Secret** | Copy **Signing Secret** from **Basic Information** |
| **Verify Slack connection** keeps waiting | Slack hasn't re-checked the Request URL since you saved credentials | In **Event Subscriptions**, click **Retry** beside the Request URL |
| Your account never appears after the connect command | The command went to a different workspace or app | Send your app's exact slash command plus `connect` in the workspace where you installed it |
| A mention in a channel does nothing | The bot isn't in the channel, the channel is off in **Allowed Channels**, or the bot was typed as plain text | Invite the bot, enable the channel, and pick the bot from @mention suggestions |
| Signature verification failures | The signing secret does not match the installed app | Copy the current signing secret and reconnect |
| Connecting the channel did not give agents Slack actions | The two routes are independent | Set up the tool connection as well |
| The tool route asks for a client ID and secret | Expected — Slack requires your own OAuth app on this route | Register the app in Slack's console |
## Limitations
One workspace per connection on either route. No channel picker in Paperclip on either route. The channel route needs public ingress and does not support socket mode. Private channels require explicit membership.
- One workspace per connection on either route.
- The chat route needs public ingress and does not support socket mode.
- The bot cannot join channels by itself; people invite it. Private channels require explicit membership.
- Removing the connection in Paperclip does not uninstall the Slack app. The app and its bot stay in your workspace until you remove them in Slack.
## Related guides
@@ -123,4 +154,5 @@ One workspace per connection on either route. No channel picker in Paperclip on
- [GitHub](github.md) — the other mixed-purpose connector, with the same tool-versus-channel split.
- [How connector access works](access-model.md)
- [Set action permissions](action-permissions.md)
- [Wire Slack/Discord notifications](../how-to/wire-slack-discord-notifications.md) — a webhook-based alternative for board alerts.
- [Slack app quickstart](https://api.slack.com/start/quickstart)
docs/connectors/you-com.md
+64
View File
@@ -0,0 +1,64 @@
---
seo_title: You.com Connector
seo_description: Give agents web search through You.com. Choose browser sign-in, an API key, or the keyless free profile, then run a quick search test and troubleshoot.
---
# You.com
Agents can search the web through You.com — useful when a task needs current information from outside your company, not just what is already in Paperclip.
## Before you connect
You have three options, and one of them needs nothing at all:
- A You.com account, for browser sign-in.
- A You.com API key from you.com/platform, if you want higher rate limits.
- Neither — the keyless free profile works without an account.
## Connect You.com
1. Open **Connectors** and select **You.com**.
2. On the **Access** step, choose the identity and which agents may use the connection.
3. Pick how to connect:
- **Sign in with You.com** — complete browser sign-in. Paperclip registers its client automatically.
- **Use an API key** — paste your key into the **You.com API key** field. Use this when browser sign-in is not suitable.
- **Use the free profile** — connect without an account. You.com limits this to a reduced, read-only tool set with its own rate limits.
All three connect to the MCP server You.com hosts, so the search actions your agents see come from that server. The free profile is a good way to try the connector before deciding whether you need a key.
## Choose access
This connector reads from the public web; it does not reach into your own data. That makes it one of the lower-stakes connectors to share.
Two things are still worth deciding:
- **Who uses the quota.** Every agent with access draws on the same account's rate limits — or the free profile's, which are tighter. If one busy agent keeps hitting limits, give it its own connection, or move to an API key.
- **What agents do with results.** Search results are outside content. An agent should treat them as information to check, not instructions to follow. See [Set action permissions](action-permissions.md) for how to keep follow-on actions in other connectors behind **Ask first**.
## Try it
```txt
Search the web with You.com for the latest release notes of a tool we use, and summarise the top three results with their links.
```
Open the links the agent returns. A search with sources you can check confirms the connection and the agent's permission.
> **Note:** Illustrative task, not a recorded test result.
## Troubleshooting and limitations
| Problem | Likely cause | Fix |
| --- | --- | --- |
| Searches fail after a burst of use | You.com rate limits, especially on the free profile | Wait and retry, or connect with an API key |
| An action you expected is missing | The free profile exposes a reduced, read-only tool set | Reconnect with sign-in or an API key |
| The API key is rejected | The key was copied incompletely or revoked | Create a new key and reconnect |
| **Needs attention** | The grant expired or was revoked | Select **Reconnect** |
Limitations: one You.com account or profile per connection. The available actions are whatever You.com's hosted server exposes.
## Related guides
- [OpenAI](openai.md), [OpenRouter](openrouter.md), [Grok](xai.md) — other AI provider connectors.
- [How connector access works](access-model.md)
- [Set action permissions](action-permissions.md)
- [You.com MCP server documentation](https://you.com/docs/build-with-agents/mcp-server)
docs/connectors/zapier.md
+2
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Zapier Connector
seo_description: Reach thousands of apps through a Zapier MCP server. The generated URL is a credential — how to set it up safely, choose exposed actions, and troubleshoot.
---
@@ -11,6 +12,7 @@ Zapier lets agents reach the apps you have already connected in your Zapier acco
## Before you connect
- The experimental **MCP aggregators** setting turned on. It is off by default, and until an administrator turns it on, Zapier does not appear in **Connectors**. See [MCP aggregators](mcp-aggregators.md#turn-them-on-first).
- A Zapier account with the apps you want to reach already connected there.
- An MCP server created in Zapier, with the specific actions you want exposed enabled on it.
docs/experimental/connections-apps.md
+4 -1
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Connections v3 Foundation
seo_description: The rebuilt connection storage and authorization layer under Paperclip Connectors: stable identities, subject-aware grants, and the mcp_remote rename.
---
@@ -18,7 +19,9 @@ seo_description: The rebuilt connection storage and authorization layer under Pa
| 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. |
One experimental flag in this area is still real and still off by default: **Chat connectors**, described as *"Show experimental chat connector setup and Board surfaces. Existing connections keep running when hidden; GitHub and other tool connectors are unaffected."* That flag governs the [chat channels](../connectors.md#chat-channels) — Slack, Discord, Microsoft Teams, Telegram, iMessage — and AgentMail's email inboxes with them. It does not govern app integrations, so the Slack and GitHub agent tools are unaffected even when their chat halves are hidden.
Two experimental flags in this area are still real and still off by default. The first is **Chat connectors**, described as *"Show experimental chat connector setup and Board surfaces. Existing connections keep running when hidden; GitHub and other tool connectors are unaffected."* That flag governs the [chat channels](../connectors.md#chat-channels) — Slack, Discord, Microsoft Teams, Telegram, iMessage — and AgentMail's email inboxes with them. It does not govern app integrations, so the Slack and GitHub agent tools are unaffected even when their chat halves are hidden.
The second is **MCP aggregators** (`enableMcpAggregators`): *"Show experimental Zapier, Arcade, Composio Connect, and Executor setup. Existing MCP connections keep running when hidden."* While it is off, those four providers are hidden from **Connectors** and new setup for them is refused. See [Connect apps through an MCP aggregator](../connectors/mcp-aggregators.md).
## The model
docs/experimental/overview.md
+8 -2
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.707.0
paperclip_version: v2026.1001.0
seo_title: Experimental Features
seo_description: Real, working features shipped behind opt-in flags while they are evaluated against live usage. What lives here, and what turning one on commits you to.
---
@@ -31,6 +31,12 @@ All experimental flags live in one place, and they're instance-wide (they apply
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 three sections — **Experimental features**, **Paperclip Developer Mode**, and **Legacy** (*"These features are going to be removed."*) — so you know roughly where to look for a name.
## If a toggle is missing
If you're on a hosted Paperclip — a managed cloud or a shared server someone else runs — the operator may have hidden some toggles, or all of them, because they manage those features for you. A hidden toggle simply doesn't appear on the page. It still has a value, though: hiding a control keeps whatever it was set to, so a feature can be on even when you can't see its card. If you need one changed, ask whoever runs your instance. Operators can read how this works in [Operator controls for hosted deployments](../administration/settings.md#operator-controls-for-hosted-deployments).
## If a toggle is locked
On an instance managed by Paperclip Cloud, some of these features are decided for you. Open the Experimental page there and you'll see a small lock badge reading **Managed by Paperclip Cloud** next to the feature's name, and its toggle greyed out — the switch still shows you whether the feature is on or off, you just can't move it. Clicking it does nothing.
@@ -50,7 +56,7 @@ Only some features are managed this way. Anything without the badge is still you
| [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) | Rebuilds 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. |
| [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**. |
| [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. |
docs/experimental/plan-decomposition-panel.md
+5 -5
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.707.0
paperclip_version: v2026.1001.0
seo_title: Task Plan Decomposition Panel
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.
---
@@ -35,14 +35,14 @@ There's nothing to configure and nothing to click besides the links — the pane
> **Note:** the panel only renders on tasks that actually have decomposition history. A task whose plan never spawned children shows nothing, even with the flag on.
## Where it lives with Chat-Style Tasks on
## Where it lives on the chat-style task page
This page describes the classic task page. If you also run the **Chat-Style Tasks** experimental feature, the same decomposition history moves into the task's properties panel, on a **Plan** tab that shows the plan document itself with the accepted-plan history underneath it — so you read the plan and what it created in one place.
This page describes the classic task page (the **Classic Task Interface** toggle under **Legacy**). On the default [chat-style task page](task-chat.md), the same decomposition history moves into the task's properties panel, on a **Plan** tab that shows the plan document itself with the accepted-plan history underneath it — so you read the plan and what it created in one place.
Two things worth knowing about that arrangement:
- The centre-column **Plan decomposition** section described above is hidden while Chat-Style Tasks is on. 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 Chat-Style Tasks is on.
- 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.
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/task-chat.md
+14 -14
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Chat-Style Tasks
seo_description: Read what an agent said and what it actually did in one stream — thinking, commands, and diffs inline, instead of a comment thread beside a transcript.
---
@@ -9,20 +10,15 @@ Watching an agent work on a task usually means reading two things at once: the c
**Chat-Style Tasks** turns the task detail page into a single live conversation. People and agents get chat bubbles. Everything an agent does between two replies streams inline as it happens — thinking, tool calls, file diffs — and then folds itself away into a one-line summary the moment the turn is done. Properties, the plan, and the task's artifacts move into a side pane you can widen or maximize.
## Turn it on
## It's on by default
1. Go to **Settings → Instance settings → Experimental**.
2. Turn on **Chat-Style Tasks** — *"Reimagines the task detail page as a live conversation with your agents: chat bubbles for people and agents, streaming activity — thinking, tool calls, diffs — that folds into a one-line summary when a turn finishes, inline plan/question/permission cards, a three-mode composer (Agent · Plan · Ask), and a resizable Properties · Plan · Artifacts pane."*
Chat-Style Tasks started life as an experimental toggle. It's now simply how the task page works — there's nothing to switch on.
The card carries an **Experimental** badge, and under the description the app tells you how reversible this is: *"Turning this off instantly restores the classic task page. No task data is affected."*
This one is yours to decide. Unlike most flags on this page it's classed as a taste setting rather than a fleet setting, so it never picks up a **Managed by Paperclip Cloud** lock badge — see [If a toggle is locked](overview.md#if-a-toggle-is-locked). It's off by default on Cloud and self-hosted instances alike.
Like every experimental flag it's instance-wide: flipping it changes the task page for everyone on the instance, not just for you.
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.
## What changes on the task page
With the flag on, the thread *is* the page. Open any task and you'll notice:
The thread *is* the page. Open any task and you'll notice:
- The **Chat / Activity / Related work** tab strip is gone. Chat is the only surface, and it fills the center column with its own scroll viewport.
- The breadcrumb, title, and header badges scroll away with the messages instead of staying pinned above them.
@@ -31,7 +27,7 @@ With the flag on, the thread *is* the page. Open any task and you'll notice:
Everything is still there. It just moved.
![The task page with Chat-Style Tasks on: the thread fills the centre column as a conversation, with the properties pane on the right](../user-guides/screenshots/light/task-chat/thread.png)
![The chat-style task page: the thread fills the centre column as a conversation, with the properties pane on the right](../user-guides/screenshots/light/task-chat/thread.png)
## Reading the thread
@@ -83,6 +79,10 @@ Plan confirmations, questions, and suggested-task cards stay inline in the threa
When a plan document is written or revised, a divider marks the spot: **Plan created**, or **Plan updated · rev 3 — see the Plan tab**.
When an agent saves a new company skill during the task, a **Skill created** card marks the spot with the skill's name and description. Click it to open the skill in its own side-pane tab — see [Skills your agents create during a task](../guides/org/skills.md#skills-your-agents-create-during-a-task).
If you answer a card while the agent is still mid-run, your response waits in the queue above the composer until the run ends — or until you **Steer** or **Interrupt** to deliver it sooner. See [Answering a card while the agent is still working](../guides/day-to-day/issues.md#answering-a-card-while-the-agent-is-still-working).
### Scrolling
The thread follows new content while you're at the bottom, and stops following the moment you scroll up. Instead of yanking you back down it shows a small round **Scroll to latest** button; click it and the thread glides back to the bottom and resumes following. Scrolling during that glide cancels it and leaves you where you are.
@@ -119,7 +119,7 @@ Its header holds up to three tabs, and a tab only appears when it has something
- **Properties** — the same task properties as always: assignee, project, blockers, and the rest.
- **Plan** — the task's plan document with its revision number and last-updated time, above the accepted-plan history. Before there's anything to show it reads *"No plan yet. The plan document, accepted plans, and their revisions will appear here."*
- **Artifacts** — a read-only list of the task's attachments and work products with their file sizes, each one a link. Empty, it reads *"No artifacts yet. Attachments and work products will appear here."*
- **Artifacts** — a read-only list of the task's work products, documents, and agent-produced files, grouped by the run that produced them. Files show their size and open in a new tab. Empty, it reads *"No artifacts yet. Work products, documents, and agent-produced files will appear here."* See [Artifacts](../guides/day-to-day/artifacts.md#reaching-artifacts-from-a-task).
With neither a plan nor artifacts, the header just says **Properties** rather than showing a one-tab strip.
@@ -127,14 +127,14 @@ With neither a plan nor artifacts, the header just says **Properties** rather th
One nice touch on the Plan tab: while a plan is waiting on your confirmation, its **accept** and **send back** buttons pin to the bottom of the pane and stay there while you scroll the plan itself — so you can read the whole thing and decide without hunting for the card back in the thread.
## When it's off
## Going back to the classic page
Purely presentational. Turning the flag off restores the classic task page exactly as it was, immediately — no migration, nothing to re-enable. Comments, runs, transcripts, plans, and attachments are the same records either way; only the rendering changes.
Purely presentational. Turning on **Classic Task Interface** restores the old task page immediately, and turning it off brings the chat-style page back — no migration either way. Comments, runs, transcripts, plans, and attachments are the same records either way; only the rendering changes.
## Caveats
- This is a redesign of a page you probably use all day, and it's under active iteration. Expect details — labels, spacing, which things fold — to move between releases.
- The flag is instance-wide, so turning it on changes the task page for every person on the instance. There's no per-user opt-in.
- **Classic Task Interface** is instance-wide, so switching back changes the task page for every person on the instance. There's no per-user opt-out.
- The Artifacts tab is read-only for now. Uploading, previewing, and deleting attachments still happen on the existing attachment surfaces.
- Live structured plan checklists (an agent ticking off plan steps as it goes) depend on adapter support and aren't wired into the live thread yet — the Plan tab shows the plan document and accepted-plan history.
docs/guides/day-to-day/artifacts.md
+6 -4
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.824.0
paperclip_version: v2026.1001.0
seo_title: Artifacts: Files Your Agents Produce
seo_description: Documents, images, video, and exports from every task in one place. Filter by type, browse stacks by task, and read files in the in-app viewer.
---
@@ -82,9 +82,11 @@ Where an artifact came from a real file, the card gives you the means to open it
The Artifacts page is the company-wide shelf. Sometimes you're already inside one task and just want to see what *this* task produced — without going back out to the shelf and filtering your way in.
If your instance has the **Chat-Style Tasks** experimental feature turned on, the task's properties panel grows an **Artifacts** tab for exactly that. It lists the files attached to the task, one row each with the filename and its size; click a row to open the file in a new tab. The tab only appears once the task actually has an attachment, and it's read-only — a quick answer to "what came out of this task?", not a place to upload or delete.
The task's properties panel has an **Artifacts** tab for exactly that. It lists the task's work products, documents, and agent-produced files, grouped by the run that produced them — newest run first, each headed by the agent's name and when the run started. Files show their filename and size; click one to open it in a new tab.
> **Experimental:** the tab only exists when **Chat-Style Tasks** is enabled in **Settings → Instance settings → Experimental**. With the flag off, a task's attachments stay in the **Attachments** section on the task page. See [Experimental features](../../experimental/overview.md).
The tab is read-only — a quick answer to "what came out of this task?", not a place to upload or delete.
> **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).
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-experimental) for the rest of what those tabs hold.
@@ -172,7 +174,7 @@ Every comment is addressable. Open a thread and use **Copy link** to grab a deep
- **Stacks** — artifacts grouped by their task (or rolled up by parent task), so related outputs stay together.
- **Cards** — previews you can read or watch in place, each linking back to the issue it came from.
- **File viewer** — a slide-over that opens a workspace file inline (with a side file browser), reachable from a file artifact or from an inline file chip an agent left in its writing.
- **Artifacts tab on a task** — with **Chat-Style Tasks** enabled, one task's files listed in its properties panel.
- **Artifacts tab on a task** — one task's outputs in its properties panel, grouped by the run that produced them.
- **Document comments** — inline, Google-Docs-style threads anchored to a passage in a Plan or Artifact document; open or resolved, authored by people or agents, and shareable by deep link.
You now know how to find, filter, and review everything your agents have made. When you want to dig into the work behind a given artifact, follow its link back to the issue and pick up the thread there.
docs/guides/day-to-day/command-palette.md
+2 -2
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.916.0
paperclip_version: v2026.1001.0
seo_title: The Command Palette
seo_description: Press Cmd+K or Ctrl+K to jump to any project, task, or page, start common actions, and search as you type without touching the sidebar.
---
@@ -46,7 +46,7 @@ The **Actions** group runs common create-flows without leaving the page you're o
| Action | What it does |
|--------|--------------|
| **Create new task** | Opens the new-task dialog. The `C` hint next to it is the standalone keyboard shortcut for the same thing. |
| **Create new task** | Opens the new-task dialog. The `C` hint next to it is the standalone keyboard shortcut for the same thing — it works once **Keyboard shortcuts** is turned on in [Instance settings → General](../../administration/settings.md#keyboard-shortcuts), an instance-wide setting that's off by default. |
| **Create new agent** | Opens the new-agent flow. |
| **Create new project** | Takes you to Projects to start a new one. |
docs/guides/day-to-day/issues.md
+23 -6
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.831.1
paperclip_version: v2026.1001.0
seo_title: Issues: Creating and Tracking Work
seo_description: Each issue is one unit of work tied to your company goal. Create them yourself or let the CEO do it, then track progress, comment, and close them.
---
@@ -350,16 +350,21 @@ Above the tabs, separately from the Properties panel, the detail view also rende
### Tabs in the properties panel (experimental)
Once a task has a plan or a few files hanging off it, one long scroll of properties stops being the fastest way to find things. With the **Chat-Style Tasks** experimental feature turned on, the properties panel splits into tabs so the plan and the task's files each get their own space.
Once a task has a plan or a few files hanging off it, one long scroll of properties stops being the fastest way to find things. On the chat-style task page — now the default — the properties panel splits into tabs so the plan and the task's files each get their own space.
> **Experimental:** these tabs only appear when **Chat-Style Tasks** is enabled in **Settings → Instance settings → Experimental**. With the flag off, the panel keeps the single stacked list of properties described above, and nothing on this page changes. See [Experimental features](../../experimental/overview.md) for how that page behaves.
> **Note:** if your instance has switched back to the old layout with **Classic Task Interface** (under **Legacy** in **Settings → Instance settings → Experimental**), the panel keeps the single stacked list of properties described above and these tabs don't appear. See [Experimental features](../../experimental/overview.md) for how that page behaves.
The tab strip sits in the panel's header bar, to the left of the window controls, and offers up to three tabs:
The tab strip sits in the panel's header bar, to the left of the window controls, and starts with up to three tabs:
- **Properties** — exactly the fields listed above, unchanged. This is always the first tab and the one you land on.
- **Plan** — the task's `plan` document plus its accepted-plan history. Appears only when the task has a plan document or at least one accepted plan.
- **Artifacts** — the task's attachments. Appears only when the task has at least one attachment.
Two more tabs can show up alongside those:
- **Tasks** — the tasks around this one: its **Subtasks** first, then any tasks this task created, grouped by project.
- **A skill tab** — when an agent creates a company skill during the task, clicking its **Skill created** card in the thread opens the skill in its own tab. See [Skills your agents create during a task](../org/skills.md#skills-your-agents-create-during-a-task).
Tabs are earned, not permanent: a task with neither a plan nor attachments shows a plain **Properties** title in the header bar instead of a one-tab strip. If you're sitting on the Plan or Artifacts tab and its content goes away — or you move to a task that never had any — the panel falls back to **Properties** rather than showing you an empty pane.
The panel itself also gains a resize grip on its left edge and a **Maximize panel** button in the header (which becomes **Restore panel** once expanded), so you can widen the pane when you're reading a long plan and shrink it again afterwards. The width you drag it to is remembered.
@@ -385,11 +390,11 @@ If either action fails, the bar tells you plainly — *"Couldn't confirm — try
#### The Artifacts tab
**Artifacts** is a plain list of the files attached to this task — one row each, showing the filename and its size. Click a row to open the file in a new tab.
**Artifacts** gathers what this task produced — work products, documents, and agent-produced files — grouped by the run that produced them, newest run first. Files show their filename and size; click one to open it in a new tab.
It's there to answer "what did this task produce?" without scrolling the thread. The tab is read-only, so there's no uploading or deleting from it, and the company-wide view of every output still lives on the [Artifacts page](./artifacts.md).
With **Chat-Style Tasks** on, the centre column's **Attachments**, **Output**, keyed-documents, and **Plan decomposition** sections all step aside — the plan and the task's files live in this panel instead, leaving the middle of the page to the conversation.
On the chat-style page, the centre column's **Attachments**, **Output**, keyed-documents, and **Plan decomposition** sections all step aside — the plan and the task's files live in this panel instead, leaving the middle of the page to the conversation.
### Output
@@ -593,6 +598,18 @@ If you'd rather not rely on each agent to pick the right audience, open **Compan
Governance only ever **narrows** — it can tighten who may respond, never widen it past what a card asked for. It's the knob for saying "confirmations on this company always go to a human," without touching every card by hand.
### Answering a card while the agent is still working
You don't have to wait for a run to finish before you respond. Accept or reject a confirmation, or answer a question card, while the agent is mid-run, and your decision is saved the moment you click — but it doesn't barge into the work in progress. Instead it lines up in the queue just above the composer, labelled with what you did and the card's title: **Accepted: …**, **Rejected: …**, or **Answered: …**.
A queued response isn't an ordinary queued message. It carries exactly what you decided — the options you picked, the answers you typed, the plan revision you approved — so you can't edit it, drag it to a new position, or discard it. Nothing can quietly change what you signed off on. From there you have three ways forward:
- **Wait.** When the current run finishes, Paperclip delivers your response once and the agent carries on from it.
- **Steer** — push your response into the turn that's running right now. This only works when the agent's runner supports steering.
- **Interrupt** — stop the current turn and start a fresh one with your response. You'll see this instead of **Steer** on some runs that can't be steered, and always on plan approvals, which need a fresh turn to switch from planning to doing.
While your response is waiting, the agent can't hand the task back to you for review — Paperclip keeps it assigned so your answer isn't left stranded. If it tries, it's told *"The user already responded. Keep the current assignee so the queued response can continue after this run."*
---
## Recovery actions
docs/guides/org/agent-adapters.md
+23 -4
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.0
seo_title: Choosing an Agent Adapter
seo_description: Compare the adapters that run your agents — Claude Code, Codex, OpenCode, HTTP webhook and more — and pick the right bridge for each role you hire.
---
@@ -23,12 +24,27 @@ Without an adapter, an agent is just a record in a database. With one, it's a wo
| `opencode_local` | Multi-provider flexibility, switchable models | OpenCode CLI installed, relevant API keys |
| `cursor` | Users already working inside Cursor | Cursor installed and configured |
| `pi_local` | Pi users wanting Pi's built-in tool set | Pi CLI installed, relevant API keys |
| `grok_local` | xAI users — runs the Grok Build CLI | Grok CLI installed, xAI API key or SuperGrok login |
| `hermes_local` | Persistent memory, 30+ tools, 80+ skills | Hermes Agent installed (Python 3.10+) |
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)
> **Note:** On Paperclip Cloud, the new-agent picker offers Claude, Codex, and OpenCode.
### Agents run in full auto by default
Agents do their work while nobody is watching, so there's no one around to answer "may I run this command?" prompts. That's why the coding adapters start in full-auto mode: Claude Code, Codex, OpenCode, and Gemini CLI agents use their tools — including tools from connected services such as MCP servers — without stopping to ask for approval.
You can dial this back per agent in the adapter's configuration. Each adapter reference page explains its own switch:
- Claude Code — `dangerouslySkipPermissions` (see [Claude Code permissions](../../reference/adapters/claude-code.md#permissions))
- Codex — `dangerouslyBypassApprovalsAndSandbox` (see [Codex permissions](../../reference/adapters/codex.md#permissions))
- OpenCode — `dangerouslySkipPermissions` (see [OpenCode](../../reference/adapters/opencode.md))
> **Tip:** Full auto is about approval prompts, not about what an agent is allowed to do in your company. Company permissions, budgets, and approval requirements still apply.
---
## Claude Code (`claude_local`)
@@ -50,9 +66,9 @@ The folder on your Mac where the agent does its work — reads files, writes out
> **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.
**Model**
Which Claude model to use. The main choices:
- `claude-opus-4-6` — most capable, best reasoning, highest cost. Good for your CEO or complex strategic agents.
- `claude-sonnet-4-6` — fast, capable, lower cost. Good for worker agents doing routine tasks.
Which Claude model to use. If you leave it blank, Paperclip uses `claude-opus-5`. Some common choices:
- `claude-opus-5` — most capable, best reasoning, highest cost. Good for your CEO or complex strategic agents.
- `claude-sonnet-5` — fast, capable, lower cost. Good for worker agents doing routine tasks.
When in doubt, start with Sonnet for workers and Opus for the CEO.
@@ -88,9 +104,12 @@ The `codex_local` adapter runs your agent using OpenAI's Codex CLI on your Mac.
The fields are the same as `claude_local` — mainly model selection and environment variables — but pointing to OpenAI instead of Anthropic.
**Model** examples for Codex:
- `gpt-5.3-codex` — the default and the normal starting point
- `gpt-5.6-sol` — the default and the normal starting point
- `gpt-6-astra` — GPT-6, with extra reasoning-effort levels
- `o4-mini` — fast and cost-effective for routine tasks
See [Codex — Models](../../reference/adapters/codex.md#models) for the full list.
![Codex local adapter configuration form](../../user-guides/screenshots/light/agents/codex-local-config.png)
---
docs/guides/org/agents.md
+25 -1
View File
@@ -1,4 +1,5 @@
---
paperclip_version: v2026.1001.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.
---
@@ -125,7 +126,7 @@ Click **Create agent**. On success Paperclip navigates you to the new agent's de
Every agent page is built from the same shell:
- A **header** with the agent's icon, name, role/title, status badge, and the action cluster (Assign Task, Run Heartbeat, Pause/Resume, overflow menu)
- 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
@@ -138,6 +139,29 @@ The action cluster in the header works on any tab:
> **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.
### Your agent's character
Every agent has its own character — a small illustrated figure in one of 17 colour palettes. It's how you tell your agents apart at a glance, and it follows the agent everywhere it shows up: the agent list and org chart, task threads and comments, the activity feed, the inbox, search results, and more.
Here's how an agent gets its look:
- **New agents** are given a palette at random when you create them. While you're setting up a new agent, you'll see a sleepy, greyed-out preview of its character; it brightens up and celebrates once the setup test passes or the agent is created. The character you saw during setup is the one the agent keeps.
- **Agents that existed before characters arrived** were each given a palette based on their ID, so they have a stable look too.
- **Imported companies** keep each agent's character when you export and re-import a company package.
On the agent detail page, the character in the header reacts to what the agent is doing:
| Agent status | Character pose |
|---|---|
| Running | Working |
| Error | Confused |
| Paused, terminated, or awaiting approval | Resting |
| Anything else | Idle |
The character animates and turns to follow your cursor. If your system is set to reduce motion, you see a still image instead. If the image can't load, Paperclip shows the agent's initials.
> **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
docs/guides/org/skills.md
+20 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.720.0
paperclip_version: v2026.1001.0
seo_title: Skills: Reusable Agent Procedures
seo_description: Package a checklist, runbook, or template once and share it across agents. Covers adding skills, folders, Skill Studio, and the cost and performance payoff.
---
@@ -205,6 +205,23 @@ If you started from a folder — say, from inside **My Skills** — the new skil
---
## Skills your agents create during a task
You don't always have to write the skill yourself. Say you ask an agent to turn a procedure it just worked out into something reusable — "save how you reviewed these release notes as a skill." An agent running on Paperclip's native runner has a **Create skill** tool for exactly that: it writes a complete, single-file `SKILL.md` and saves it straight into your company's skill library.
A few things keep this predictable:
- **It only happens in Agent mode.** The tool is available when the task runs in Agent mode (and in skill test runs), not in Ask or Plan mode — see [Work Modes](../day-to-day/work-modes.md).
- **It follows your skill policy.** Creating a skill this way goes through the same rules as creating one in Skill Studio. With no policy in place, agents are allowed; if you've restricted `skills.create`, the agent is refused just like anyone else. See [Who is allowed to change skills](#who-is-allowed-to-change-skills).
- **It doesn't attach the skill to anyone.** The new skill lands in the library only. No agent starts using it until you (or an agent allowed to) assign it — see [Assigning a skill to an agent](#assigning-a-skill-to-an-agent).
- **Retries don't make duplicates.** If the agent's request is interrupted and retried, it gets back the skill it already made instead of a second copy.
When a skill is created, a **Skill created** card appears in the task's thread with the skill's name and description. Click it and the skill opens in its own tab in the task's side panel, showing its slug, current revision, and instructions. That tab always reads the live library copy, so it's not a second version to keep in sync. Use **Open in Skill Studio** to edit it; when you come back to the task, the tab shows what you saved. If the skill is later deleted, or you don't have access to it, the tab tells you so — *"Skill no longer available."* or *"You do not have access to this skill."* — while the card in the thread stays as a record that it was created.
The creation is also logged as `company.skill_created`, and it shows up in the task's own history as well as the company activity log.
---
## Renaming a skill
Names age. The `code-review` skill you wrote in week one turns out to be your PR triage procedure, and every agent that uses it is now working from a name that misleads whoever reads the roster next. You can rename it without unpicking anything.
@@ -302,6 +319,8 @@ A **View company skills library** link at the top of the tab jumps back to the c
> **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.
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.
---
## Pinning a beta release of the Paperclip skill
docs/guides/projects-workflow/routines.md
+99 -16
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.626.0
paperclip_version: v2026.1001.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.
---
@@ -163,19 +163,20 @@ The header packs the always-available controls into one row:
The left sub-sidebar lists the routine's sections in two groups, and each section is its own sub-route (`/routines/:id/<section>`) so you can deep-link and use the browser's back button. Older `?tab=` links still resolve — they redirect to the matching section.
**Routine** (the editable parts of the template):
The first group holds the editable parts of the template:
- **Overview** — the assignment row ("For [assignee] in [project]"), priority, and the Markdown instructions editor.
- **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.
- **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.
- **Secrets** — environment values the routine's task can reference.
- **Delivery** — the concurrency and catch-up policies.
- **Secrets** — environment values the routine's task can reference.
**Operate** (the read-only history):
**Operate** keeps the routine's day-to-day operation inside the routine itself, so you never have to leave for a separate audit screen:
- **Runs** — the execution history for this specific routine.
- **Activity** — a structured audit log of edits, enables, pauses, trigger changes, and secret rotations, grouped by day.
- **History** — the routine's revision history, with the ability to restore an earlier revision.
- **Runs** — the tasks this routine has produced, which you can search and update in place (see [Run history](#run-history) below).
- **Activity** — a timeline of routine, trigger, and run events — edits, enables, pauses, trigger changes, webhook deliveries, and key rotations — grouped by day.
The routine's revision history lives behind the **History** button in the header, where you can restore an earlier revision; **Back to overview** takes you out again.
A small amber dot appears next to any section with unsaved edits, and a blue pulsing dot appears on **Runs** when a run is live. On narrow screens the sidebar collapses into a single grouped section picker at the top.
@@ -199,7 +200,9 @@ 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 — green for success, red otherwise — so you can spot a misfiring webhook without leaving the page.
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.
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.
Each card carries its own **Delete**, **Save trigger**, and — for webhook triggers — **Rotate secret** buttons.
@@ -207,9 +210,13 @@ Each card carries its own **Delete**, **Save trigger**, and — for webhook trig
![Run history](../../user-guides/screenshots/light/routines/run-history.png)
The **Runs** section lists every execution the routine has produced, newest first. Above the list, three filter dropdowns — **Source**, **Status**, and **Date** (Any time, Last 24h, Last 7d, Last 30d) — narrow the view, and the active filters show as removable chips. When a run is live, a `LiveRunWidget` pins to the top and polls every three seconds so you can watch it progress without reloading.
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.
Each row leads with two badges — the run's **source** and its **status** — then the linked issue's identifier and title (or the trigger label when there's no issue yet), with a relative "time ago" on the right. The subtitle line does double duty: a **failed** run shows its failure reason inline, while a successful run shows the resolved variable values it ran with (for example `customer="Acme"`). Rows link straight to the execution issue they produced.
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.
When you fire the routine from the **Run** button, Paperclip drops you on **Runs** so you can watch the new task appear.
Runs that didn't create a task — a tick skipped by the concurrency policy or the activity gate, for example — have nothing to list here. You'll still see them on the **Overview** under recent runs, with their status badge, and the API's [List Runs](../../reference/api/routines.md#list-runs) endpoint gives the full record including `failureReason`.
---
@@ -239,14 +246,90 @@ Every schedule trigger is saved with an explicit **timezone**, derived from the
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.
### Webhook triggers
---
Webhook triggers skip the cron editor entirely and show two fields instead:
## Webhook triggers
- **Signing mode** — `bearer`, `hmac_sha256`, `github_hmac`, or `none`. Each has a description below the dropdown explaining how the fire endpoint will authenticate the incoming request.
- **Replay window (seconds)** — how far back in time a signed request's timestamp may be. Hidden for `github_hmac` and `none`, which don't carry a timestamp.
A schedule is one way to start a routine; a webhook is the other. Instead of firing on a clock, a webhook trigger hands you a URL that an outside system POSTs to — a GitHub event, a deploy script, another SaaS tool — and that inbound call starts the routine. Reach for it whenever the work should happen *because something happened elsewhere*, not at a fixed time.
When you create a webhook trigger, Paperclip returns a one-time banner with the webhook URL and secret. **This is the only time the secret is shown** — copy it now. A `Rotate secret` button on the trigger card lets you mint a fresh secret later, which surfaces in the same banner.
You add a webhook trigger the same place you add a schedule: open a routine, go to its **Triggers** section, and add a trigger. A short wizard walks you through the rest.
### Choosing schedule or webhook
The first step asks **"When should this routine run?"** and offers two choices:
- **On a schedule** — every day, on weekdays, or once a week. That's the cron path covered above.
- **When another app sends a webhook** — when something happens in GitHub, another app, or a script.
Pick the webhook option and Paperclip asks **what's sending the webhook**: **Another app or script**, or **GitHub**. Your answer decides how deliveries are authenticated and which setup instructions you see next: **Another app or script** uses a Bearer token in the `Authorization` header, while **GitHub** uses GitHub's own signed `X-Hub-Signature-256` header. From the next step on, Paperclip also checks the webhook URL and warns you if senders might not be able to reach it — more on that in [Is your webhook URL reachable?](#is-your-webhook-url-reachable).
### Copying the URL and secret
As soon as you continue, Paperclip creates the webhook and shows you two things to copy into the sending system:
- a **Webhook URL** (labelled **Payload URL** on the GitHub path) — the address the outside system POSTs to
- the credential that proves a delivery really came from your system — an **Authorization header value** (the full `Bearer <secret>` string, ready to paste) on the generic path, or a **Secret** on the GitHub path
Copy both now. **The secret is only visible during setup** — once you leave the wizard it's hidden, and the field is replaced by a **Generate new key** button. If you didn't save it, generate a fresh one rather than hunting for the old value (see [Rotating the secret](#rotating-the-secret)).
Paperclip also gives you a copy-ready **Agent instructions** block bundling the URL, the key, and step-by-step wiring — handy when you'd rather hand the connection off to one of your agents to set up.
### The generic path (another app or script)
For a custom app or a script, the setup is:
- Add a webhook pointing at the **Webhook URL**, using the **POST** method.
- Send a **JSON object** as the body — not an array or a bare string — with **`Content-Type: application/json`**.
- Add a header named **`Authorization`** and set its value to the complete **Authorization header value** you copied — **`Bearer`**, a space, then the secret key.
- Send a unique **`Idempotency-Key`** header for each event and reuse it on retries. That way a retried setup test can never start the routine once the webhook is live.
### The GitHub path
Choose **GitHub** and Paperclip gives you GitHub-shaped steps:
1. In your repository, open **Settings → Webhooks → Add webhook**.
2. Paste the **Webhook URL** into **Payload URL**, and set **Content type** to **application/json**.
3. Paste the **Secret** into GitHub's **Secret** field. GitHub signs each request with an **`X-Hub-Signature-256`** header, so you don't use Bearer authentication on this path.
4. Choose the events that should start the routine, enable the webhook, and save.
### Is your webhook URL reachable?
A webhook only works if the sending app can actually reach the URL Paperclip gives you. When the URL looks like it won't be reachable from outside, the wizard and the trigger's saved settings show a yellow warning banner explaining why:
- **Other apps can’t reach this localhost URL** — the address points at `localhost` or a loopback address, which means "this machine" to whoever sends the request.
- **This webhook URL appears to be private** — a private-network address or an internal hostname. Only senders on the same network can reach it; public apps like GitHub usually can't.
- **This Tailscale URL may not be public** — a `.ts.net` address. Tailscale Serve is private to your tailnet even over HTTPS; senders outside the tailnet need Tailscale Funnel or another public HTTPS address. If Funnel is already on for this URL, you can carry on.
- **Use HTTPS for webhooks from other apps** — the URL is plain HTTP. Many apps refuse it, and HTTP doesn't encrypt your webhook credentials or payloads.
- **Check the webhook URL** — the address isn't a valid HTTP or HTTPS URL.
The warning is advice, not a block: you can continue for local or private-network use, such as a script on the same machine. For public senders, give Paperclip a publicly reachable HTTPS address — the banner links to [HTTPS and public access](../../reference/deploy/https.md) for the setup. Paperclip can only judge the URL itself; it can't see your DNS, firewall, or whether Funnel is on, so a URL with no warning isn't a guarantee either.
### Finishing setup to enable the webhook
A brand-new webhook trigger starts in a **setup-pending** state, and that's on purpose. While setup is pending, any delivery that arrives **only tests the connection** — it doesn't start the routine or create a task. That lets you wire things up and confirm they work without kicking off real work by accident.
The wizard's last step, **Check connection**, is where you verify it:
- Send a test event from the sending app. In GitHub, open the webhook's **Recent Deliveries** and choose **Redeliver**; in another app, use its "send test" button or simply perform the action that should fire the webhook.
- Keep the page open. The status flips to **Test event received · Connection working** once a delivery arrives and authentication passes — no run and no task are created. If you see **Event arrived, but the key was rejected**, go back, fix the key in the sending app, and resend.
- Click **Finish setup** to enable the webhook. From then on, real events start the routine.
One thing to know: **the test event is not replayed.** Finishing setup does not re-fire the delivery you sent while testing — only events that arrive *after* you enable the webhook start the routine. And if the routine itself is paused, finishing setup saves the webhook but leaves it dormant until you enable the routine's automatic triggers.
### Signing modes and the replay window
Under the hood, each webhook trigger carries a **signing mode** that decides how Paperclip authenticates an inbound call, plus — for the timestamped mode — a **replay window**:
- **Signing mode** — `bearer`, `hmac_sha256`, `github_hmac`, or `none`. The **Another app or script** path creates a `bearer` trigger, and the **GitHub** path creates a `github_hmac` one. Each option has a short description below the dropdown explaining how the fire endpoint will authenticate the request.
- **Replay window (seconds)** — how far back a signed request's timestamp may be, used only by the timestamped `hmac_sha256` mode. It defaults to 300 seconds and doesn't apply to the other modes, which don't carry a timestamp.
### 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.
### Enabling, disabling, and archiving a trigger
Each trigger has its own **enabled** state, so you can switch a single trigger off without touching the rest of the routine. You can also **archive** a trigger to retire it from the active set and **restore** it later, or **Delete** it to remove it for good. A routine can carry several triggers at once — a nightly schedule and a GitHub webhook side by side, for example — and they all fire independently.
---
docs/how-to/create-a-daily-routine.md
+17 -13
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.525.0
paperclip_version: v2026.1001.0
seo_title: Create a Routine That Runs Daily
seo_description: Describe recurring work once, attach a cron trigger, and Paperclip mints a fresh issue every tick with the same owner, parent, project, and goal.
---
@@ -291,7 +291,7 @@ Schedule isn't the only trigger. The same routine can carry any combination of `
### Webhook
Use when an external system should kick the routine off. GitHub PR opened, Stripe invoice paid, monitoring alert fired.
Use when an external system should kick the routine off. A deploy finished, a Stripe invoice was paid, a monitoring alert fired.
```bash
curl -X POST "$PAPERCLIP_API_URL/api/routines/$ROUTINE_ID/triggers" \
@@ -299,9 +299,8 @@ curl -X POST "$PAPERCLIP_API_URL/api/routines/$ROUTINE_ID/triggers" \
-H "Content-Type: application/json" \
-d '{
"kind": "webhook",
"label": "GitHub PR opened",
"signingMode": "github_hmac",
"replayWindowSec": 300
"label": "Deploy finished",
"signingMode": "bearer"
}'
```
@@ -313,10 +312,13 @@ Then call the public URL from the external system:
curl -X POST "$WEBHOOK_URL" \
-H "Authorization: Bearer $WEBHOOK_SECRET" \
-H "Content-Type: application/json" \
-d '{ "payload": { "source": "github", "event": "pull_request.opened" } }'
-H "Idempotency-Key: deploy-4812" \
-d '{ "event": "deploy.finished", "environment": "production" }'
```
Signing modes: `bearer` (default), `hmac_sha256`, `github_hmac`, or `none`. Pick `github_hmac` for GitHub, `hmac_sha256` for anything you control yourself, `bearer` for one-line scripts. Avoid `none` — the URL becomes anonymously fireable.
`bearer` checks that `Authorization: Bearer` header. It's what the UI's **Another app or script** setup creates.
Signing modes: `bearer` (the API default when you omit `signingMode`), `hmac_sha256`, `github_hmac`, or `none`. Pick `github_hmac` for GitHub, `bearer` for other apps and one-line scripts, `hmac_sha256` for timestamped signatures you compute yourself. Avoid `none` — the URL becomes anonymously fireable. The sender has to be able to reach the URL: public services need a publicly reachable HTTPS address, not `localhost` or a private network.
### Manual (`api`)
@@ -367,15 +369,17 @@ The runs you'll see:
| `completed` | The execution issue reached `done`. |
| `failed` | The execution issue failed, was cancelled, or dispatch errored. The `failureReason` field tells you which. |
In the UI you don't have to read `failureReason` yourself — the routine's **Runs** list writes the reason straight onto a skipped row as a one-line subtitle:
A skipped run tells you why in `failureReason`:
| Row subtitle | `failureReason` |
| `failureReason` | What happened |
|---|---|
| Skipped — no activity since last run | `no_external_activity` |
| Skipped — routine paused | `paused` |
| Skipped — worktree execution cutoff | `worktree_execution_cutoff` |
| `no_external_activity` | The activity gate found nothing new since the last dispatched run. |
| `paused` | The routine's project was paused at tick time. |
| `worktree_execution_cutoff` | The server is running in a development worktree that isn't cleared to execute this routine. |
Those three are the reasons with a label. A skipped run whose reason isn't one of them — a `skip_if_active` routine dropping a tick because the previous execution issue is still open, for instance — falls back to the normal row subtitle, the run's resolved variable values. That case isn't a mystery either: the row links to the execution issue that caused the skip.
A skipped run with no `failureReason` was dropped by the concurrency policy — a `skip_if_active` routine whose previous execution issue is still open, for instance. That case isn't a mystery either: its `linkedIssueId` points at the execution issue that caused the skip.
In the UI, the routine's **Runs** section lists the execution issues the routine created, where you can search them and update status, priority, or assignee in place. Skipped ticks don't create an issue, so look for them under recent runs on the routine's **Overview** instead.
For a deeper look at what the agent actually did, follow `linkedIssueId` to the execution issue and read its comments.
docs/reference/adapters/claude-code.md
+21 -6
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.916.0
paperclip_version: v2026.1001.0
seo_title: Claude Code Adapter
seo_description: Run Anthropic's Claude Code CLI on the Paperclip host, with session persistence, skills injection, and configuration managed from your agent.
---
@@ -30,7 +30,7 @@ seo_description: Run Anthropic's Claude Code CLI on the Paperclip host, with ses
| Field | Required | Notes |
|---|---:|---|
| `cwd` | no | Absolute working directory for the agent. Recommended in practice. If omitted, the adapter falls back to the current process working directory. Paperclip creates the path when permissions allow. |
| `engine` | no | How Claude Code is run: `auto` (the default — ACP preferred), `acp` (always the Agent Client Protocol), or `cli` (always the classic Claude CLI). See [ACP Engine](#acp-engine). |
| `engine` | no | How Claude Code is run: `auto` (the default — runs ACP), `acp` (always the Agent Client Protocol), or `cli` (always the classic Claude CLI). See [ACP Engine](#acp-engine). |
| `model` | no | Claude model id. Common choices include `claude-opus-4-8`, `claude-sonnet-5`, and `claude-fable-5-1`. |
| `promptTemplate` | no | Prompt template used for the run. |
| `env` | no | Environment variables passed to Claude Code. Secret refs are supported. |
@@ -39,7 +39,7 @@ seo_description: Run Anthropic's Claude Code CLI on the Paperclip host, with ses
| `effort` | no | Reasoning effort passed with `--effort` (`low`, `medium`, or `high`). In a sandbox environment whose Claude CLI is too old to advertise `--effort`, Paperclip drops the flag and warns you to upgrade the environment's Claude Code to restore reasoning-effort control. |
| `chrome` | no | Passes `--chrome` when enabled. |
| `maxTurnsPerRun` | no | Caps the number of agentic turns in one heartbeat. Defaults to `300`. |
| `dangerouslySkipPermissions` | no | Defaults to `true` because Paperclip runs Claude in headless `--print` mode. |
| `dangerouslySkipPermissions` | no | Defaults to `true` because Paperclip runs Claude in headless `--print` mode. When on, local and remote runs alike get `--dangerously-skip-permissions`, covering built-in and connected tools. See [Permissions](#permissions). |
| `timeoutSec` | no | Run timeout in seconds. On local and SSH targets, `0` means no adapter wall-clock timeout. On a sandbox target, `0` or an unset value uses the 14,400-second sandbox default; use a positive value to override it or a negative value to opt out of the adapter timeout. |
| `graceSec` | no | Grace period before a forced stop. |
| `workspaceStrategy` | no | Execution workspace strategy, such as `git_worktree`. |
@@ -49,17 +49,32 @@ seo_description: Run Anthropic's Claude Code CLI on the Paperclip host, with ses
---
## Permissions
Paperclip runs Claude Code without anyone watching, so there's no one to click "approve" on a permission prompt. With `dangerouslySkipPermissions` on (the default), Claude runs in full-auto mode: it can use its built-in tools and any tools from connected services — such as MCP servers — without stopping to ask.
This works the same whether the agent runs on the Paperclip host or on a remote target. Remote runs used to get a hand-picked list of allowed tools instead of full bypass; that list missed connected tools and anything Claude added in later releases, so remote runs now get the same full bypass as local ones.
A couple of things to know:
- **Sandboxes running as root.** Claude refuses full bypass when it runs as the root user, unless it knows it's inside a sandbox. When the agent runs in a Paperclip-managed sandbox, Paperclip sets `IS_SANDBOX=1` so Claude accepts the bypass there.
- **Other root processes.** Outside a managed sandbox, run Claude as a non-root user. Paperclip doesn't quietly fall back to a narrower permission mode — if Claude refuses to launch, the run fails so you can fix the setup.
> **Tip:** Want Claude to stop and refuse anything it would normally ask about? Set `dangerouslySkipPermissions` to `false`. Keep in mind that in a headless run, a tool that needs approval simply won't run.
---
## ACP Engine
Claude Code can run through one of two engines — ACP or the classic Claude CLI — selected by the `engine` field:
- **`auto` (default) — ACP preferred.** Paperclip runs Claude through the Agent Client Protocol (ACP) when the host meets the prerequisites, and falls back to the Claude CLI — with diagnostics explaining why — when it can't.
- **`auto` (default) — ACP.** Paperclip runs Claude through the Agent Client Protocol (ACP). If the host doesn't meet the ACP prerequisites, the run fails with a setup error explaining why — Paperclip never switches engines on its own.
- **`acp` — always ACP.** Force the Agent Client Protocol path.
- **`cli` — always the Claude CLI.** Force the classic CLI wrapper and skip ACP entirely.
ACP gives you a richer, structured live transcript: session identity, status with context-window usage, assistant and thinking token deltas, and tool-call updates that fold into a single card as they progress. That extra detail is most useful when you're watching a sandbox run stream in.
When the engine resolves to ACP (either `acp`, or `auto` on a capable host), these extra fields apply:
When the engine resolves to ACP (`auto` or `acp`), these extra fields apply:
| Field | Default | Notes |
|---|---|---|
@@ -75,7 +90,7 @@ When the engine resolves to ACP (either `acp`, or `auto` on a capable host), the
You can keep `engine` on `auto` when this agent runs in a Paperclip sandbox environment. If that sandbox provides Paperclip's bidirectional process session, Paperclip keeps the ACP engine and its structured live transcript; you do not add a separate bridge setting to the adapter config.
An environment that only runs one-shot commands cannot host an ACP session, so `auto` falls back to the Claude CLI with a diagnostic. The same fallback applies to non-sandbox remote targets such as SSH. Choose `engine: "acp"` when ACP is required and a failed prerequisite should stop the run, or `engine: "cli"` when you always want the CLI lane.
An environment that only runs one-shot commands cannot host an ACP session, so an `auto` run there fails with a setup error rather than switching to the Claude CLI. Set `engine: "cli"` when you want the CLI lane — for example on such environments.
---
docs/reference/adapters/codex.md
+24 -7
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.916.0
paperclip_version: v2026.1001.0
seo_title: Codex Adapter
seo_description: Run OpenAI's Codex CLI on the Paperclip host as a local coding agent, with persistent session state and a managed CODEX_HOME per agent.
---
@@ -30,20 +30,20 @@ seo_description: Run OpenAI's Codex CLI on the Paperclip host as a local coding
| Field | Required | Notes |
|---|---:|---|
| `cwd` | no | Absolute working directory for the agent. Recommended in practice. If omitted, the adapter falls back to the current process working directory. Paperclip creates the path when permissions allow. |
| `engine` | no | How Codex is run: `auto` (the default — ACP preferred), `acp` (always the Agent Client Protocol), or `cli` (always the classic Codex CLI). See [ACP Engine](#acp-engine). |
| `engine` | no | How Codex is run: `auto` (the default — runs ACP), `acp` (always the Agent Client Protocol), or `cli` (always the classic Codex CLI). See [ACP Engine](#acp-engine). |
| `model` | no | Codex model id. See [Models](#models). If you leave it unset, the adapter omits `--model` so the Codex CLI uses its own default. |
| `promptTemplate` | no | Prompt template used for the run. |
| `instructionsFilePath` | no | Markdown file prepended to the stdin prompt sent to `codex exec`. |
| `modelReasoningEffort` | no | Reasoning effort override passed through Codex config. Most models accept `minimal`, `low`, `medium`, `high`, or `xhigh`; `gpt-6-astra` instead accepts `low`, `medium`, `high`, `xhigh`, `max`, or `ultra`. |
| `search` | no | Runs Codex with `--search`. |
| `fastMode` | no | Enables Codex Fast mode by setting `service_tier="fast"` and `features.fast_mode=true`. Supported on `gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5`, and `gpt-5.4`, and passed through for manual model ids. When the configured model can't use it, Paperclip ignores the setting and notes why. |
| `dangerouslyBypassApprovalsAndSandbox` | no | Bypasses Codex safety checks for unattended runs. |
| `dangerouslyBypassApprovalsAndSandbox` | no | Runs Codex with `--dangerously-bypass-approvals-and-sandbox` so unattended runs never stop for approval. Defaults to on when you leave it unset — see [Permissions](#permissions). |
| `command` | no | Defaults to `codex`. |
| `extraArgs` | no | Extra CLI arguments appended to the Codex invocation. |
| `env` | no | Environment variables passed to the runtime. Secret refs are supported. |
| `timeoutSec` | no | Run timeout in seconds. On local and SSH targets, `0` means no adapter wall-clock timeout. On a sandbox target, `0` or an unset value uses the 14,400-second sandbox default; use a positive value to override it or a negative value to opt out of the adapter timeout. |
| `graceSec` | no | Grace period before a forced stop. |
| `outputInactivityTimeoutMs` | no | How long the adapter waits for Codex to produce output before treating the run as stuck. The timer resets every time Codex emits a parsed event, so a busy run never trips it. Defaults to 7 minutes (`420000`) when unset. Set it to `null` to switch the monitor off entirely — only do that for tasks you know go quiet for long stretches, since Paperclip's platform-level one-hour silent-run safety net still applies. When it fires, the adapter stops the Codex process and reports the run as failed with a message like `monitor: no codex output for 7m 0s`. |
| `outputInactivityTimeoutMs` | no | How long the adapter waits for Codex to produce output before treating the run as stuck. The timer resets whenever Codex writes output (and, on Linux, when its processes show real CPU, disk, or child-process activity), so a busy run never trips it. Defaults to 30 minutes (`1800000`) when unset. Set it to `null` to switch the monitor off entirely — only do that for tasks you know go quiet for long stretches, since Paperclip's platform-level one-hour silent-run safety net still applies. When it fires, the adapter stops the Codex process and reports the run as failed with a message like `monitor: no codex activity (output or process) for 30m 0s`. |
| `workspaceStrategy` | no | Execution workspace strategy, such as `git_worktree`. |
| `workspaceRuntime` | no | Reserved workspace runtime metadata. |
@@ -51,17 +51,34 @@ seo_description: Run OpenAI's Codex CLI on the Paperclip host as a local coding
---
## Permissions
Codex agents run in full-auto mode by default. If you leave `dangerouslyBypassApprovalsAndSandbox` unset, Paperclip passes `--dangerously-bypass-approvals-and-sandbox`, so Codex works through a task without pausing for approvals that no one is around to give.
You stay in control when you say otherwise. Paperclip skips the bypass — keeping Codex in its writable workspace sandbox, or in the mode you picked — when any of these is true (the last three only count while `dangerouslyBypassApprovalsAndSandbox` is unset):
- You set `dangerouslyBypassApprovalsAndSandbox` to `false`.
- Your `extraArgs` pick a sandbox mode or profile yourself — for example `--sandbox`, `--profile`, `--full-auto`, or a `sandbox_mode=` config override.
- Your `extraArgs` set an `approval_policy=` override, or switch network access off with `sandbox_workspace_write.network_access=false`.
- The execution target denies network access.
This bypass applies to the classic Codex CLI lane (`engine: "cli"`). The ACP engine keeps Codex in its writable workspace sandbox, with network access switched on for each turn.
> **Heads-up:** Earlier versions kept Codex in the workspace sandbox unless you opted in to the bypass. If you relied on that, set `dangerouslyBypassApprovalsAndSandbox` to `false` explicitly.
---
## ACP Engine
Codex can run through one of two engines — ACP or the classic Codex CLI — selected by the `engine` field:
- **`auto` (default) — ACP preferred.** Paperclip runs Codex through the Agent Client Protocol (ACP) when the host meets the prerequisites, and falls back to the Codex CLI — with diagnostics explaining why — when it can't.
- **`auto` (default) — ACP.** Paperclip runs Codex through the Agent Client Protocol (ACP). If the host doesn't meet the ACP prerequisites, the run fails with a setup error explaining why — Paperclip never switches engines on its own.
- **`acp` — always ACP.** Force the Agent Client Protocol path.
- **`cli` — always the Codex CLI.** Force the classic CLI wrapper and skip ACP entirely.
ACP gives you a richer, structured live transcript: session identity, status with context-window usage, assistant and thinking token deltas, and tool-call updates that fold into a single card as they progress. That extra detail is most useful when you're watching a sandbox run stream in.
When the engine resolves to ACP (either `acp`, or `auto` on a capable host), these extra fields apply:
When the engine resolves to ACP (`auto` or `acp`), these extra fields apply:
| Field | Default | Notes |
|---|---|---|
@@ -77,7 +94,7 @@ When the engine resolves to ACP (either `acp`, or `auto` on a capable host), the
You can keep `engine` on `auto` when this agent runs in a Paperclip sandbox environment. If that sandbox provides Paperclip's bidirectional process session, Paperclip keeps the ACP engine and its structured live transcript; you do not add a separate bridge setting to the adapter config.
An environment that only runs one-shot commands cannot host an ACP session, so `auto` falls back to the Codex CLI with a diagnostic. The same fallback applies to non-sandbox remote targets such as SSH. Choose `engine: "acp"` when ACP is required and a failed prerequisite should stop the run, or `engine: "cli"` when you always want the CLI lane.
An environment that only runs one-shot commands cannot host an ACP session, so an `auto` run there fails with a setup error rather than switching to the Codex CLI. Set `engine: "cli"` when you want the CLI lane — for example on such environments.
---
docs/reference/adapters/gemini-cli.md
+25 -6
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.720.0
paperclip_version: v2026.1001.0
seo_title: Gemini CLI Adapter
seo_description: Run Google's Gemini CLI on the Paperclip host, with session resume across heartbeats and configurable sandboxing for each agent you point at it.
---
@@ -32,8 +32,8 @@ seo_description: Run Google's Gemini CLI on the Paperclip host, with session res
| Field | Required | Notes |
|---|---:|---|
| `cwd` | no | Absolute working directory for the agent. Recommended in practice. If omitted, the adapter falls back to the current process working directory. Paperclip creates the path when permissions allow. |
| `engine` | no | How Gemini is run: `auto` (the default — ACP preferred), `acp` (always the Agent Client Protocol), or `cli` (always the classic Gemini CLI). See [ACP Engine](#acp-engine). |
| `model` | no | Gemini model id. Defaults to `auto`. Common choices include `gemini-2.5-pro` and `gemini-2.5-flash`. |
| `engine` | no | How Gemini is run: `auto` (the default — runs ACP), `acp` (always the Agent Client Protocol), or `cli` (always the classic Gemini CLI). See [ACP Engine](#acp-engine). |
| `model` | no | Gemini model id. Defaults to `auto`. Common choices include `gemini-3.1-pro-preview`, `gemini-2.5-pro`, and `gemini-2.5-flash`. See [Models](#models). |
| `promptTemplate` | no | Prompt template used for the run. |
| `instructionsFilePath` | no | Markdown instructions file prepended to the prompt. |
| `sandbox` | no | Enables Gemini sandbox mode. The adapter otherwise passes `--sandbox=none`. |
@@ -54,13 +54,13 @@ seo_description: Run Google's Gemini CLI on the Paperclip host, with session res
Gemini can run through one of two engines — ACP or the classic Gemini CLI — selected by the `engine` field:
- **`auto` (default) — ACP preferred.** Paperclip runs Gemini through the Agent Client Protocol (ACP) when the host meets the prerequisites, and falls back to the Gemini CLI — with diagnostics explaining why — when it can't.
- **`auto` (default) — ACP.** Paperclip runs Gemini through the Agent Client Protocol (ACP). If the host doesn't meet the ACP prerequisites, the run fails with a setup error explaining why — Paperclip never switches engines on its own.
- **`acp` — always ACP.** Force the Agent Client Protocol path.
- **`cli` — always the Gemini CLI.** Force the classic CLI wrapper and skip ACP entirely.
ACP gives you a richer, structured live transcript: session identity, status with context-window usage, assistant and thinking token deltas, and tool-call updates that fold into a single card as they progress. That extra detail is most useful when you're watching a sandbox run stream in.
When the engine resolves to ACP (either `acp`, or `auto` on a capable host), these extra fields apply:
When the engine resolves to ACP (`auto` or `acp`), these extra fields apply:
| Field | Default | Notes |
|---|---|---|
@@ -76,7 +76,24 @@ When the engine resolves to ACP (either `acp`, or `auto` on a capable host), the
You can keep `engine` on `auto` when this agent runs in a Paperclip sandbox environment. If that sandbox provides Paperclip's bidirectional process session, Paperclip keeps the ACP engine and its structured live transcript; you do not add a separate bridge setting to the adapter config.
An environment that only runs one-shot commands cannot host an ACP session, so `auto` falls back to the Gemini CLI with a diagnostic. The same fallback applies to non-sandbox remote targets such as SSH. Choose `engine: "acp"` when ACP is required and a failed prerequisite should stop the run, or `engine: "cli"` when you always want the CLI lane.
An environment that only runs one-shot commands cannot host an ACP session, so an `auto` run there fails with a setup error rather than switching to the Gemini CLI. Set `engine: "cli"` when you want the CLI lane — for example on such environments.
---
## Models
Pick a Gemini model id in the `model` field. The known options are:
- `auto` (the adapter default — Gemini CLI picks the model)
- `gemini-3.1-pro-preview`
- `gemini-3.1-pro-preview-customtools`
- `gemini-2.5-pro`
- `gemini-2.5-flash`
- `gemini-2.5-flash-lite`
- `gemini-2.0-flash`
- `gemini-2.0-flash-lite`
You can also type any model id your Gemini CLI accepts.
---
@@ -115,6 +132,8 @@ The `Test Environment` button checks:
- Authentication is available through `GEMINI_API_KEY`, `GOOGLE_API_KEY`, Google account login, or Gemini's CLI auth.
- The hello probe can run `gemini --output-format json "Respond with hello."`
The hello probe runs in the same unattended `yolo` approval mode that real runs use, unless you set `approvalMode` or turn `yolo` off.
The test also detects auth and quota failures, so a passing install check does not automatically mean the account can still run work.
---
docs/reference/adapters/grok-local.md
+10 -2
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.916.0
paperclip_version: v2026.1001.0
seo_title: Grok Local Adapter
seo_description: Run xAI's Grok Build CLI on the Paperclip host as a local coding agent that resumes the same Grok session across every heartbeat.
---
@@ -67,7 +67,15 @@ The session codec preserves the same location hints used by other local adapters
Grok Local authenticates in one of two modes, and the choice depends only on whether `XAI_API_KEY` is present in the run environment:
- **API key.** Set `XAI_API_KEY` (usually as a secret ref inside `env`) and the adapter runs against that key. This is metered billing, so Paperclip surfaces the per-run cost xAI reports.
- **Subscription (SuperGrok).** Leave `XAI_API_KEY` unset and Grok authenticates from a signed-in login instead. Paperclip points the run at a per-company Grok home (`GROK_HOME`) that holds that login's `auth.json`, so one company's login is never shared with another. Subscription runs carry no per-run dollar cost.
- **Subscription (SuperGrok).** Leave `XAI_API_KEY` unset and Grok authenticates from a signed-in login instead. Subscription runs carry no per-run dollar cost.
For subscription runs, which login Grok uses depends on where the agent runs:
- **Local runs** use the host's own `grok login` (stored in `~/.grok`) until the company's Grok home holds a usable `auth.json` — for example after a sandbox device login. Once it does, Paperclip points the run at that per-company Grok home (`GROK_HOME`), so one company's login is never shared with another. If you already set `GROK_HOME` yourself (in the host environment or the agent's `env`) and there's no usable company login, Paperclip leaves your value alone.
- **Sandbox and remote runs** always use the company's Grok home and never fall back to the host login.
- **Managed AI connections** keep the Grok home the connection selected.
> **Tip:** If the host has an `XAI_API_KEY` you don't want an agent to inherit, set `XAI_API_KEY` to an empty value in that agent's `env`. The empty override clears the inherited key and switches the agent to subscription authentication.
### Signing in for a subscription
docs/reference/adapters/kimi-local.md
+7 -7
View File
@@ -1,14 +1,14 @@
---
paperclip_version: v2026.831.1
paperclip_version: v2026.1001.0
seo_title: Kimi Code Adapter
seo_description: Run Moonshot's Kimi Code CLI on the Paperclip host as a local coding agent, on the shared ACP engine by default with an automatic headless-CLI fallback.
seo_description: Run Moonshot's Kimi Code CLI on the Paperclip host as a local coding agent, on the shared ACP engine by default, with an optional headless-CLI lane.
---
# Kimi Code
`kimi_local` runs Moonshot's Kimi Code CLI (`kimi`) on the same machine as Paperclip. Use it when you want a local coding agent that streams a structured live transcript, resumes sessions across heartbeats, and gets your Paperclip skills injected without polluting your own Kimi skills home.
Kimi Code runs on the same shared ACP engine as Claude, Codex, and Gemini by default, and falls back to a headless CLI lane when ACP prerequisites are missing.
Kimi Code runs on the same shared ACP engine as Claude, Codex, and Gemini by default. You can switch it to a headless CLI lane instead.
---
@@ -31,7 +31,7 @@ Kimi Code runs on the same shared ACP engine as Claude, Codex, and Gemini by def
| Field | Required | Notes |
|---|---:|---|
| `cwd` | no | Default absolute working directory for the agent process. Paperclip creates the path when permissions allow; if omitted, it falls back to the current process working directory. |
| `engine` | no | Which lane runs Kimi: the adapter defaults to the ACP engine (`kimi acp`) and falls back to the headless CLI when ACP prerequisites are unavailable. Set `acp` or `cli` to require a specific lane. See [ACP Engine](#acp-engine). |
| `engine` | no | Which lane runs Kimi: the adapter defaults to the ACP engine (`kimi acp`) and fails with a setup error when ACP prerequisites are unavailable. Set `acp` or `cli` to require a specific lane. See [ACP Engine](#acp-engine). |
| `model` | no | Kimi model alias (`provider/model`). Defaults to `kimi-code/kimi-for-coding`. See [Models](#models). |
| `effort` | no | Thinking effort (`low`, `medium`, `high`, `max`). CLI lane only. See [Thinking Effort](#thinking-effort). |
| `promptTemplate` | no | Prompt template used for the run. |
@@ -51,9 +51,9 @@ Kimi Code runs on the same shared ACP engine as Claude, Codex, and Gemini by def
Kimi Code runs through one of two lanes, selected by the `engine` field:
- **ACP (the default).** Paperclip runs Kimi through the Agent Client Protocol (`kimi acp`), giving you a structured live transcript — session identity, status with context-window usage, assistant and thinking token deltas, and tool-call updates that fold into a single card as they progress. This is the same machinery Claude, Codex, and Gemini use.
- **CLI (the fallback).** When ACP prerequisites are unavailable, the adapter automatically falls back to the headless CLI lane. It runs `kimi -p` with `--output-format stream-json` for non-interactive execution; the prompt is passed as an argument, not on stdin.
- **CLI (opt-in).** Set `engine: "cli"` to use the headless CLI lane. It runs `kimi -p` with `--output-format stream-json` for non-interactive execution; the prompt is passed as an argument, not on stdin.
Leave `engine` unset to get ACP with automatic CLI fallback. Set `engine: "acp"` to require ACP (a failed prerequisite stops the run), or `engine: "cli"` to always use the headless CLI lane.
Leave `engine` unset (or set `engine: "acp"`) to use ACP — if a prerequisite is missing, the run stops with a setup error instead of switching lanes. Set `engine: "cli"` to always use the headless CLI lane.
---
@@ -73,7 +73,7 @@ You can also type a model alias that is not in this list; Paperclip passes an un
The `effort` field maps a Paperclip effort value onto Kimi's supported thinking-effort tiers. Kimi exposes `low`, `high`, and `max` — there is **no `medium` tier**, so `medium` maps onto `high`.
Effort is honored on the **CLI lane only** (`engine: cli`, or the automatic CLI fallback), where it is forwarded as `KIMI_MODEL_THINKING_EFFORT` for effort-capable models — currently only `kimi-code/k3`. It is ignored for models that do not advertise effort support, and it is **not** forwarded on the default ACP engine lane. If you need effort control, pin `engine: "cli"`.
Effort is honored on the **CLI lane only** (`engine: cli`), where it is forwarded as `KIMI_MODEL_THINKING_EFFORT` for effort-capable models — currently only `kimi-code/k3`. It is ignored for models that do not advertise effort support, and it is **not** forwarded on the default ACP engine lane. If you need effort control, pin `engine: "cli"`.
---
docs/reference/adapters/opencode.md
+3 -4
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.916.0
paperclip_version: v2026.1001.0
seo_title: OpenCode Adapter
seo_description: Run OpenCode on the Paperclip host when you want provider and model routing in OpenCode's own format, plus session resume across heartbeats.
---
@@ -31,7 +31,7 @@ seo_description: Run OpenCode on the Paperclip host when you want provider and m
| `cwd` | no | Absolute working directory. Recommended. Created when permissions allow; otherwise falls back to the process working directory. |
| `model` | **yes** | OpenCode model id in `provider/model` format (e.g. `openai/gpt-5.2-codex`, `anthropic/claude-sonnet-4-5`). |
| `variant` | no | Provider-specific reasoning/profile variant passed as `--variant`. Accepts `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. |
| `dangerouslySkipPermissions` | no | Injects a temporary runtime config with `permission.external_directory=allow` so headless runs don't stall on approval prompts. Defaults to `true` for unattended Paperclip runs. |
| `dangerouslySkipPermissions` | no | Injects a temporary runtime config with `permission=allow`, so every tool and connection runs without approval prompts. Defaults to `true` for unattended Paperclip runs. |
| `promptTemplate` | no | Run prompt template. |
| `instructionsFilePath` | no | Absolute path to a Markdown instructions file prepended to the run prompt. |
| `command` | no | Defaults to `opencode`. Override only for a non-default executable path. |
@@ -55,7 +55,7 @@ OpenCode sessions are resumed with `--session` when the stored session `cwd` mat
- Runs are invoked as `opencode run --format json ...`.
- Model selection is passed via the `--model` CLI flag.
- `OPENCODE_DISABLE_PROJECT_CONFIG=true` is set automatically to prevent OpenCode from writing config into the project directory.
- When `dangerouslySkipPermissions` is enabled (the default for unattended runs), Paperclip copies your existing `opencode` config into a temporary `XDG_CONFIG_HOME`, merges `permission.external_directory=allow` into that copy's `opencode.json`, and points the run at it. This keeps unattended runs from stalling on approval prompts and never mutates your real config. The env overrides below (`PAPERCLIP_OPENCODE_PROVIDERS`, `PAPERCLIP_OPENCODE_SMALL_MODEL`) are written into this same temporary file, so they apply only when `dangerouslySkipPermissions` is on and the target runs locally.
- When `dangerouslySkipPermissions` is enabled (the default for unattended runs), Paperclip copies your existing `opencode` config into a temporary `XDG_CONFIG_HOME`, sets `permission=allow` in that copy's `opencode.json`, and points the run at it. That puts OpenCode in full-auto mode for all tools and connections, so unattended runs never stall on approval prompts, and your real config is never touched. Any `permission` rules from your own config are replaced in that temporary copy, so set `dangerouslySkipPermissions` to `false` if you need OpenCode to honour them. The env overrides below (`PAPERCLIP_OPENCODE_PROVIDERS`, `PAPERCLIP_OPENCODE_SMALL_MODEL`) are written into this same temporary file, so they apply only when `dangerouslySkipPermissions` is on and the target runs locally.
---
@@ -115,7 +115,6 @@ OpenCode supports multiple providers. Common ids:
| `openai/gpt-5.2` | OpenAI |
| `openai/gpt-5.1-codex-max` | OpenAI |
| `openai/gpt-5.1-codex-mini` | OpenAI |
| `anthropic/claude-sonnet-4-5` | Anthropic |
Run `opencode models` for the authoritative list on your machine.
docs/reference/adapters/sandbox-providers.md
+25 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.916.0
paperclip_version: v2026.1001.0
seo_title: Sandbox Providers
seo_description: Provider plugins that let Paperclip provision external compute as the execution environment for agent runs, instead of running them on the host.
---
@@ -120,6 +120,30 @@ Configure from **Settings → Instance settings → Environments**. The plugin m
---
## CreateOS (`provider: "createos"`)
Package: `@paperclipai/plugin-createos`
Reach for CreateOS when you want agent runs to execute in a CreateOS sandbox with live command output streaming back as it happens, and optional pause/resume so a warm sandbox survives between runs. It ships bundled with Paperclip like the other first-party providers, so you install it from the [Plugins](../../administration/plugins.md) page rather than pulling it from npm.
Configure it from **Settings → Instance settings → Environments** with core `driver: "sandbox"` and `provider: "createos"`. Put the CreateOS API key on the sandbox environment itself — Paperclip stores pasted API keys as company secrets. `CREATEOS_API_KEY` remains an optional host-level fallback, but only for the official endpoint `https://api.sb.createos.sh`; a custom `apiUrl` always requires an explicit key on the environment.
The driver's `configSchema` exposes:
| Field | Default | Purpose |
|---|---|---|
| `apiUrl` | `https://api.sb.createos.sh` | CreateOS API endpoint. Must be an HTTPS origin (optionally ending in `/v1`); plain HTTP is allowed on loopback only, and credentials, query strings, and fragments are rejected. Required. |
| `apiKey` | (none) | Environment-specific CreateOS API key — a pasted key or an existing Paperclip secret reference. Falls back to `CREATEOS_API_KEY` when omitted, but only for the official `https://api.sb.createos.sh` endpoint. |
| `shape` | (none) | Sandbox CPU/memory size from the CreateOS shape catalog, such as `s-1vcpu-1gb` or `s-2vcpu-4gb`. Required. |
| `rootfs` | (provider default) | Optional root filesystem or ready template ID/name. The image must supply Bash and the selected agent runtime's dependencies. |
| `region` | (provider default) | Optional region; it must match the API endpoint's region. |
| `timeoutMs` | `300000` | Operation and default per-command timeout, in milliseconds. Validated as an integer between `1` and `86400000`. This is not a sandbox lifetime. |
| `reuseLease` | `false` | Pause the sandbox after a run and resume it for later runs instead of deleting it on release. |
The driver advertises `supportsReusableLeases` and `incrementalSessionOutput`, so reusable leases (via `reuseLease`) map to CreateOS pause/resume, and command output streams back live as it's produced.
---
## Modal (`provider: "modal"`)
Package: `@paperclipai/plugin-modal`
docs/reference/api/agents.md
+40 -2
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.916.0
paperclip_version: v2026.1001.0
seo_title: Agents API
seo_description: Create agents, inspect and update configuration, manage lifecycle, rotate keys, sync skills, trigger runs, and register managed and remote agent profiles.
---
@@ -31,6 +31,8 @@ The agent payload is a normal JSON object. These are the fields you will see mos
| `name` | Human-friendly name. The server also derives a company-unique URL key from it. |
| `role` | Role label such as `ceo`, `engineer`, or `general`. |
| `title` | Optional display title. |
| `appearance` | The agent's character (avatar) identity: `{ "schemaVersion": 1, "characterVersion": "cap-v1", "paletteId": "<palette>" }`. See [Agent Avatars](#agent-avatars) for the palette ids. |
| `avatarUrl` | Read-only. A ready-made URL for the agent's character image, derived from `appearance`. |
| `reportsTo` | Parent agent in the org tree. Must be in the same company and cannot create a cycle. |
| `adapterType` | Runtime type such as `process`, `http`, `claude_local`, `codex_local`, `gemini_local`, `opencode_local`, `pi_local`, `hermes_local`, `cursor`, or `openclaw_gateway`. External adapters can also be registered. |
| `adapterConfig` | Adapter-specific config. Secret references are allowed inside `env`. |
@@ -306,6 +308,7 @@ Important behavior:
- `runtimeConfig.heartbeat.enabled` defaults to `false` if you omit it.
- `adapterConfig.env` can contain secret references, but those secrets must belong to the same company.
- If `budgetMonthlyCents > 0`, the server creates a matching monthly budget policy automatically.
- If you omit `appearance`, the server picks a random character palette for the new agent and saves it, so the agent keeps the same look from then on.
- Certain adapters apply defaults on create. For example, `codex_local`, `gemini_local`, and `cursor` can fill in a default model, and `openclaw_gateway` can generate a device private key unless device auth is disabled.
### Example
@@ -459,6 +462,7 @@ Important behavior:
- If you set `replaceAdapterConfig: true`, the update behaves more like a replacement.
- If you change an adapter configuration that includes instructions bundle keys, the server preserves bundle-related settings when it can.
- Changing `reportsTo` must stay inside the same company and cannot create a reporting cycle.
- You can change the agent's character by sending a new `appearance` object. It must match the shape shown in [Common Fields](#common-fields).
- Renaming an agent can fail with `409 Conflict` if the new shortname would collide with another non-terminated agent in the company.
- Terminated agents cannot be resumed through a status patch.
- Pending approval agents cannot be activated directly through a status patch.
@@ -878,6 +882,37 @@ Notes:
---
## Agent Avatars
Renders the character image for an agent's `appearance`.
`GET /api/agent-avatars/{version}/{palette}/{pose}.png`
You rarely need to build this URL yourself — agent responses include a ready-made `avatarUrl`, and live-run lists include `agentAppearance` and `avatarUrl` for each run. Reach for this route when you want a different size or pose.
The route only serves preset artwork. It doesn't look up any agent or company, so the URL tells it everything it needs:
| Part | Values |
|---|---|
| `version` | `cap-v1` |
| `palette` | One of `bubblegum-sky`, `pink-lemonade`, `orchid-peach`, `coral-mint`, `lime-lagoon`, `arctic-blue`, `solar-flare`, `violet-ember`, `deep-tide`, `coral-current`, `golden-hour`, `tangerine-cobalt`, `electric-grove`, `flamingo-jade`, `cherry-pop`, `turquoise-cherry`, `ultraviolet-tide` — or `muted-dream` for the greyed-out version. |
| `pose` | One of `rest`, `idle`, `listening`, `thinking`, `working`, `success`, `confused`, `sleepy`, `loading`. |
| `size` (query) | Pixel size: `16`, `20`, `24`, `32`, `40`, `48`, `64`, `96`, `128`, `256`, or `512`. Defaults to `512`. |
| `scale` (query) | `1` or `2` (for high-density screens). Defaults to `1`. |
```bash
curl -s -o ada.png \
"http://localhost:3100/api/agent-avatars/cap-v1/arctic-blue/working.png?size=128&scale=2"
```
Notes:
- Images are cached for a year and carry an `ETag`, so repeat requests can come back as `304 Not Modified`.
- Any other query parameter, or a value outside the lists above, returns `400 Bad Request`.
- If you send too many requests at once you get `429 Too Many Requests`, and if a render fails you get `503 Service Unavailable`. Both carry a `Retry-After` header — wait and try again.
---
## Adapter Helpers
These routes help you inspect and validate adapter environments.
@@ -891,8 +926,10 @@ Use them when you are choosing a model, auto-detecting a recommended model, or c
Important notes:
- The adapter type must be known to the server.
- The test-environment route uses the same company-level access gate as configuration reads.
- The test-environment route needs permission to create agents in the company — the same check as the create and hire routes.
- The server resolves secrets before running the test.
- To test a saved agent, pass its `agentId` in the test-environment body. The server fills in any environment values that came back redacted from the saved config, so you don't have to re-enter them. If you're testing a switch to a different adapter, re-enter those values instead — the server won't carry hidden values across to an unrelated adapter.
- If you leave `environmentId` out, the test runs in the saved agent's default environment (when you passed `agentId`), or else the instance's default environment. Send `environmentId: null` to test against the instance default explicitly.
---
@@ -1099,6 +1136,7 @@ AWS AgentCore authenticates through the runner environment's workload identity,
- Updating `permissions` through the main update route returns `422`.
- Creating a key for a terminated or pending approval agent returns `409`.
- Pause and resume are not available for terminated agents.
- A heartbeat-run route called with a run ID that isn't a valid UUID returns `400 Bad Request` (`Invalid heartbeat run ID`).
- Wakeup can be skipped even when the request is accepted, especially when policy or execution state blocks it.
---
docs/reference/api/company-skill-policy.md
+3 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.720.0
paperclip_version: v2026.1001.0
seo_title: Company Skill Policy API
seo_description: The guardrail on what agents may do to skills — create, import, install, edit, or remove — instead of leaving the whole library open to every agent.
---
@@ -82,6 +82,8 @@ The `subject` object is a tagged union on `type`:
| `skills.reset` | Resetting a skill. |
| `skills.remove` | Removing a skill. |
**Skills an agent creates mid-task are checked as `skills.create`.** When an agent saves a new skill from inside a task (see [Skills your agents create during a task](../../guides/org/skills.md#skills-your-agents-create-during-a-task)), the request is evaluated exactly like a Skill Studio create: action `skills.create`, source type `generated`. To stop agents creating skills this way, deny `skills.create` for those agents. A rule on `sourceTypes: ["generated"]` alone won't single this path out — creating a skill from scratch in the UI carries the same source type, so it would block both.
### Resource selectors
`resources` narrows a rule. At least one of these keys must be present, and unknown keys are rejected:
docs/reference/api/routines.md
+51 -15
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.817.0
paperclip_version: v2026.1001.0
seo_title: Routines API
seo_description: Paperclip's recurring execution layer. Run an agent on a schedule, fire it from a webhook, or kick it off manually, and see what a routine does not do.
---
@@ -365,14 +365,18 @@ Webhook triggers create a public URL and a secret. The public URL is returned on
Supported signing modes in the code are:
- `bearer`
- `hmac_sha256`
- `github_hmac`
- `none`
| Mode | What it accepts |
|---|---|
| `bearer` | A bearer token. This is the mode the UI's **Another app or script** setup creates. |
| `hmac_sha256` | A timestamped HMAC-SHA256 signature. |
| `github_hmac` | GitHub-style HMAC-SHA256 over the body, without a timestamp. This is the mode the UI's **GitHub** setup creates. |
| `none` | No authentication. Anyone with the URL can fire the trigger. |
The default is `bearer`.
When you create a webhook trigger through the API and omit `signingMode`, the default is `bearer`.
Replay windows are only used for the timestamped HMAC mode and must be between 30 and 86,400 seconds. The default is 300 seconds.
Replay windows are only used for the timestamped `hmac_sha256` mode and must be between 30 and 86,400 seconds. The default is 300 seconds.
The `webhookUrl` is built from the server's public origin. External senders such as GitHub can only deliver to a publicly reachable HTTPS address — see [HTTPS and public access](../deploy/https.md). The UI warns when a URL points at `localhost`, a private network, a Tailscale `.ts.net` host, or plain HTTP.
### API
@@ -461,6 +465,28 @@ created = response.json()
---
## Webhook Setup And Test Deliveries
A webhook trigger can start life in a **setup-pending** state. Pass `setupPending: true` in the create body to opt in; the trigger is stored but treats every inbound delivery as a connection test rather than a live firing.
While a trigger is setup-pending:
- a delivery to the [fire endpoint](#fire-public-trigger) is validated for signature and content, but **does not create a routine run or an execution issue**
- the delivery is recorded as a content-free test receipt, keyed by the request's idempotency key, so a later retry of that same test cannot start the routine after the trigger goes live
- the trigger's `lastWebhookDelivery` reflects the outcome so a client can show whether the test arrived
The `lastWebhookDelivery` object has:
| Field | Values | Notes |
|---|---|---|
| `status` | `received`, `rejected` | `received` means the signature and payload passed; `rejected` means authentication failed. |
| `receivedAt` | ISO timestamp | When the delivery landed. |
| `test` | boolean | `true` for a setup-pending test delivery. |
To finish setup, `PATCH /api/routine-triggers/{triggerId}` with `setupPending: false`. From that point on, real deliveries create runs. The test delivery you sent during setup is **not** replayed — only events received after the trigger is enabled fire the routine.
---
## Update Trigger
```http
@@ -474,6 +500,8 @@ You can update:
- `enabled`
- `cronExpression` and `timezone` for schedule triggers
- `signingMode` and `replayWindowSec` for webhook triggers
- `setupPending` — only the value `false` is accepted, which finishes setup and enables the webhook for real deliveries (see [Webhook setup and test deliveries](#webhook-setup-and-test-deliveries))
- `archived` — `true` archives the trigger (retires it from the active set), `false` restores it
If you enable a schedule trigger, the routine must still have resolvable required variables.
@@ -614,6 +642,8 @@ POST /api/routine-triggers/public/{publicId}/fire
This endpoint is for external systems that call a routine's webhook trigger directly.
The request must be sent with `Content-Type: application/json` and the body must be a JSON **object** — an array, a bare string, or a missing body is rejected. Sending the wrong content type returns `415 Unsupported Media Type`.
What the code checks:
- the `publicId` must match a webhook trigger
@@ -624,12 +654,16 @@ What the code checks:
Accepted headers depend on signing mode:
- `bearer` uses `Authorization: Bearer <secret>`
- `hmac_sha256` uses `X-Paperclip-Signature` or `X-Hub-Signature-256`
- `github_hmac` uses `X-Hub-Signature-256` or `X-Paperclip-Signature` plus `X-Paperclip-Timestamp`
- `hmac_sha256` uses `X-Paperclip-Signature` plus `X-Paperclip-Timestamp`, signing the timestamp, a dot, and the exact body
- `github_hmac` uses `X-Hub-Signature-256`, falling back to `X-Paperclip-Signature`, over the exact body with no timestamp
- `none` does not require a signature
For timestamped HMAC validation, the server enforces the replay window from the trigger.
For deduplication the server reads an idempotency key from the `Idempotency-Key` header, falling back to `X-GitHub-Delivery`. Sending the same key on a retry prevents a duplicate run — and, during setup, prevents a retried test delivery from starting the routine once the trigger is enabled.
If the trigger is still [setup-pending](#webhook-setup-and-test-deliveries), the endpoint validates the delivery and records it as a test receipt, but does not create a run.
### Example
<!-- tabs: cURL, JavaScript, Python -->
@@ -732,18 +766,20 @@ Routine runs use these statuses:
### Why a run was skipped
A suppressed automatic firing records a `failureReason` you can read back, and the UI turns each one into a one-line subtitle on the run row:
A suppressed automatic firing records a `failureReason` you can read back from this endpoint, and the trigger's last result shows the matching value:
| `failureReason` | Trigger last result | Run row subtitle | Meaning |
|---|---|---|---|
| `no_external_activity` | `skipped_no_activity` | Skipped — no activity since last run | The activity gate found nothing new since the routine's last dispatched run. |
| `paused` | `Skipped because the project is paused` | Skipped — routine paused | The routine's project was paused at tick time. |
| `worktree_execution_cutoff` | `skipped_worktree_execution_cutoff` | Skipped — worktree execution cutoff | The server is running inside a development worktree (`PAPERCLIP_IN_WORKTREE`) where automatic run execution is not armed for this routine — either the worktree isn't armed at all, or the routine was created before the worktree's activation cutoff. This applies to scheduled ticks and webhook firings alike. |
| `failureReason` | Trigger last result | Meaning |
|---|---|---|
| `no_external_activity` | `skipped_no_activity` | The activity gate found nothing new since the routine's last dispatched run. |
| `paused` | `Skipped because the project is paused` | The routine's project was paused at tick time. |
| `worktree_execution_cutoff` | `skipped_worktree_execution_cutoff` | The server is running inside a development worktree (`PAPERCLIP_IN_WORKTREE`) where automatic run execution is not armed for this routine — either the worktree isn't armed at all, or the routine was created before the worktree's activation cutoff. This applies to scheduled ticks and webhook firings alike. |
A run skipped by the concurrency policy carries no `failureReason` — it records the live execution issue in `linkedIssueId` instead.
The list view also shows the current active issue for a routine when one exists.
In the UI, a routine's **Runs** section lists the execution issues the routine created — the same issue list used elsewhere, filtered to this routine's `routine_execution` issues — so you can search them and change status, priority, or assignee in place. Runs that never created an issue, such as skipped ticks, appear only in this endpoint and in the recent runs on the routine's overview.
---
## Agent Access Rules
docs/reference/api/tool-gateway.md
+10 -13
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.916.0
paperclip_version: v2026.1001.0
seo_title: Tool Gateway API
seo_description: Agents decide what to do; the tool gateway decides whether they may. It sits between every agent and every external tool you have connected.
---
@@ -444,18 +444,7 @@ A **delegation** lets the owner of a personal grant lend that identity to an age
Most of these routes gate on **configure access** — you are the connection's creator, or you hold `tools:manage_connections` — rather than on a single permission key. Viewers and members with no active company access are refused before anything else.
#### Toolkit services and usage
When a connection fronts a provider that bundles many toolkits, you connect and disconnect each toolkit **service** on its own:
```
GET /api/tool-connections/{connectionId}/services
POST /api/tool-connections/{connectionId}/services/{toolkitSlug}/connect
GET /api/tool-connections/{connectionId}/services/{toolkitSlug}/status
DELETE /api/tool-connections/{connectionId}/services/{toolkitSlug}
```
All four require configure access. `connect` takes an optional `authConfigId` and `callbackUrl` and responds `201 Created`; `status` polls where an in-flight connect got to; and the `DELETE` disconnects the toolkit and removes the catalog tools it contributed.
#### Usage
A usage summary rounds out the per-connection view:
@@ -465,6 +454,14 @@ GET /api/tool-connections/{connectionId}/usage?range={7d|30d}
`range` defaults to `7d` and must be `7d` or `30d` — anything else returns `400 Bad Request` with `Usage range must be 7d or 30d`.
#### Legacy Composio connections
The old per-toolkit **services** routes under `/api/tool-connections/{connectionId}/services` are gone, along with the Composio broker they drove. Composio is now an ordinary remote MCP connection (see [Connect apps through an MCP aggregator](../../connectors/mcp-aggregators.md)).
A connection saved under the old broker still exists, but Paperclip no longer runs it. It reads back with `healthStatus` `error`, its tools are left out of discovery, and a tool call, catalog refresh, reconnect, or OAuth start against it is refused with `422 Unprocessable Entity` and the code `composio_broker_retired`. The message tells you what to do:
> *"This legacy Composio connection is no longer supported. Add a new Composio MCP connection from Connectors, then remove this connection. Existing credentials and permissions are not migrated."*
Profiles, entries, and bindings:
```
docs/reference/changelog.md
+29 -2
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.916.1
paperclip_version: v2026.1001.0
seo_title: Documentation Changelog
seo_description: What changed in these docs — pages added, rewritten, or expanded — with every documentation update. For product releases, see the Paperclip changelog.
---
@@ -13,6 +13,33 @@ The docs track Paperclip's [calendar-versioned](https://github.com/paperclipai/p
---
<details class="accordion" open>
<summary>Docs for v2026.1001.0 <span class="accordion-meta">October 1, 2026</span></summary>
<div class="accordion-body">
This release brings agent characters, a rebuilt Slack setup, safe routine webhooks, and experimental MCP aggregators. It also changes two defaults you may notice: coding agents now run in full auto, and the legacy Composio broker is retired. This entry also rounds up the connector guides published since v2026.916.1.
**New pages**
- [Connect apps through an MCP aggregator](../connectors/mcp-aggregators.md) — reach many apps through Arcade, Composio, Executor, or Zapier: how to turn the experimental setting on, which provider to pick, and what Paperclip governs versus what the aggregator governs.
- Connector guides published since v2026.916.1: [Arcade](../connectors/arcade.md), [Composio](../connectors/composio.md), [Executor](../connectors/executor.md), [Fireflies](../connectors/fireflies.md), [Railway](../connectors/railway.md), and [You.com](../connectors/youcom.md).
**Updated pages**
- [Agents](../guides/org/agents.md) and [Agents API](api/agents.md) — every agent now has its own illustrated character that follows it around the app. Learn how it reacts to the agent's status, how to set it with `appearance`, and how the avatar image route works.
- [Agent Adapters](../guides/org/agent-adapters.md) and the [Claude Code](adapters/claude-code.md), [Codex](adapters/codex.md), [Gemini CLI](adapters/gemini-cli.md), [OpenCode](adapters/opencode.md), [Kimi](adapters/kimi-local.md), and [Grok](adapters/grok-local.md) adapter pages — coding agents start in full auto, and each page shows how to dial that back. Also: `engine: auto` now fails with a setup error instead of quietly falling back to the CLI, and Codex's inactivity timeout default is 30 minutes.
- [Slack](../connectors/slack.md) — the seven-step setup wizard, linking your Slack account, communication guidance that follows Slack conversations into tasks, and downloading the agent's avatar for the bot.
- [Routines](../guides/projects-workflow/routines.md), [Create a Daily Routine](../how-to/create-a-daily-routine.md), and [Routines API](api/routines.md) — the trigger wizard for schedules and webhooks, one-time credentials, test deliveries, the warning when a webhook URL may not be publicly reachable, and a routine's runs listed inside the routine. The webhook signature headers for `hmac_sha256` and `github_hmac` are also corrected.
- [Issues](../guides/day-to-day/issues.md), [Chat-Style Tasks](../experimental/task-chat.md), and [Skills](../guides/org/skills.md) — answering a question or approval while the agent is still working, skills an agent creates from a finished task, and the first-task onboarding skill. Chat-Style Tasks is now described as the default, with the Classic Task Interface as the legacy toggle.
- [Tool Gateway API](api/tool-gateway.md) and [Providers Paperclip recognizes but does not list](../connectors/recognized-providers.md) — the legacy Composio broker and its per-toolkit services routes are gone. Old connections are refused with `422 composio_broker_retired` and need to be recreated as Composio MCP connections.
- [Zapier](../connectors/zapier.md), [Arcade](../connectors/arcade.md), [Composio](../connectors/composio.md), and [Executor](../connectors/executor.md) — all four are now hidden until an administrator turns on the experimental **MCP aggregators** setting.
- [Sandbox Providers](adapters/sandbox-providers.md) — the new CreateOS provider and its configuration fields.
- [Plugins](../administration/plugins.md) and [Plugin SDK](plugins/sdk.md) — shipping prebuilt plugins inside a custom image's distribution catalog, and the `appShellOverlay` slot that wraps the whole app.
- Smaller updates: [Artifacts](../guides/day-to-day/artifacts.md), [Command Palette](../guides/day-to-day/command-palette.md), [Experimental features](../experimental/overview.md), [Task Plan Decomposition Panel](../experimental/plan-decomposition-panel.md), [Connections v3](../experimental/connections-apps.md), [Connect a custom MCP server](../connectors/custom-mcp-servers.md), [Use separate accounts for people and agents](../connectors/separate-accounts.md), [Company Skill Policy](api/company-skill-policy.md), and [Skills Reference](skills.md).
</div>
</details>
<details class="accordion">
<summary>Docs for v2026.916.1 <span class="accordion-meta">September 21, 2026</span></summary>
<div class="accordion-body">
@@ -163,7 +190,7 @@ A patch release: the task conversation's send button no longer starts out disabl
**New pages**
- [Secret Folders](../administration/secret-folders.md) — organizing secrets into folders.
- [Connections & Apps](../experimental/connections-apps.md) — experimental Connections v3 (Apps) foundation.
- [Connections v3](../experimental/connections-apps.md) — experimental Connections v3 (Apps) foundation.
**Updated pages**
docs/reference/plugins/sdk.md
+8 -2
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.916.0
paperclip_version: v2026.1001.0
seo_title: Plugin SDK
seo_description: The worker-side authoring kit for Paperclip plugins. Import it in your worker entrypoint to declare a plugin and subscribe to host events.
---
@@ -37,10 +37,16 @@ Reach for the plugin SDK when you want to:
The SDK package exposes two entrypoints:
- `@paperclipai/plugin-sdk` — the worker-side surface documented on this page. Default for `definePlugin`, `runWorker`, `PluginContext`, the protocol helpers, and all manifest/protocol types.
- `@paperclipai/plugin-sdk/ui` — UI-bundle surface for plugin UI contributions. Out of scope for this page; see [Administration → Plugins](../../administration/plugins.md) for the operator-facing view.
- `@paperclipai/plugin-sdk/ui` — UI-bundle surface for plugin UI contributions. Mostly out of scope for this page; see [Administration → Plugins](../../administration/plugins.md) for the operator-facing view, and [A UI slot that wraps the whole app](#a-ui-slot-that-wraps-the-whole-app) below for the one app-wide slot.
All identifiers below are exported from `@paperclipai/plugin-sdk`. They are the source of truth — copy names verbatim.
### A UI slot that wraps the whole app
Most UI slots mount on one page or one entity. One slot type in `PLUGIN_UI_SLOT_TYPES` instead attaches to the signed-in application shell itself:
- **`appShellOverlay`** — a persistent piece of UI that lives alongside the whole app, such as a floating panel. It needs the `ui.action.register` capability and gets the same host context as a widget. It stays mounted while the user navigates between pages, and it's torn down when the user switches account or company, signs out, or enters onboarding — so cancel any requests or subscriptions when your component unmounts. Your plugin is responsible for the panel's accessibility.
---
## Public API
docs/reference/skills.md
+8 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.720.0
paperclip_version: v2026.1001.0
seo_title: Skills Reference
seo_description: The reference for company skills: file shape on disk, the install pipeline, attaching to agents, scoping rules, canonical keys, and versioning.
---
@@ -137,6 +137,13 @@ None of this rests on the agent's good manners. The disposition guard rejects an
Issue monitors are a separate mechanism from [task watchdogs](../guides/projects-workflow/task-watchdogs.md), which you attach to an issue yourself to double-check a subtree that has come to rest.
### Recent guidance in the bundled skills
A few smaller changes to the bundled skills are worth knowing about, because they change what you'll see agents do:
- **Open questions get a text box.** When an agent needs a free-text answer from you, the `paperclip` skill now gives it a complete `ask_user_questions` payload that renders a text field (a `questionSet` question with `answerMode: "text"`), instead of inventing multiple-choice options for something that isn't a choice. Choice cards are reserved for real decisions with at least two meaningful alternatives.
- **`paperclip-create-agent` on Paperclip Runner.** Runner agents don't get `PAPERCLIP_API_URL` or `PAPERCLIP_API_KEY`, so the skill now tells them to use the runner's Paperclip tools instead — `get_task_context` and `list_agents` for context, then `search_api` to find the hiring endpoints and `call_api` to call them. If those API tools aren't available, the agent reports that you need to enable runner API tools for the company, keeps the proposed hire in the conversation, and doesn't claim an agent was created.
---
## 2. Installation pipeline
site/content.json
+4
View File
@@ -185,6 +185,10 @@
"title": "Custom MCP Servers",
"file": "../docs/connectors/custom-mcp-servers.md"
},
{
"title": "MCP Aggregators",
"file": "../docs/connectors/mcp-aggregators.md"
},
{
"title": "Google Workspace Setup",
"file": "../docs/connectors/google-setup.md"