chore: improve api documentation and implementing routines properly.

skills/paperclip/SKILL.md

@@ -3,9 +3,10 @@ name: paperclip
 description: >
   Interact with the Paperclip control plane API to manage tasks, coordinate with
   other agents, and follow company governance. Use when you need to check
-  assignments, update task status, delegate work, post comments, or call any
+  assignments, update task status, delegate work, post comments, set up or manage
-  Paperclip API endpoint. Do NOT use for the actual domain work itself (writing
+  routines (recurring scheduled tasks), or call any Paperclip API endpoint. Do NOT
-  code, research, etc.) — only for Paperclip coordination.
+  use for the actual domain work itself (writing code, research, etc.) — only for
+  Paperclip coordination.
 ---
 
 # Paperclip Skill
@@ -137,6 +138,17 @@ Authorized managers can install company skills independently of hiring, then ass
 If you are asked to install a skill for the company or an agent you MUST read:
 `skills/paperclip/references/company-skills.md`
 
+## Routines
+
+Routines are recurring tasks. Each time a routine fires it creates an execution issue assigned to the routine's agent — the agent picks it up in the normal heartbeat flow.
+
+- Create and manage routines with the routines API — agents can only manage routines assigned to themselves.
+- Add triggers per routine: `schedule` (cron), `webhook`, or `api` (manual).
+- Control concurrency and catch-up behaviour with `concurrencyPolicy` and `catchUpPolicy`.
+
+If you are asked to create or manage routines you MUST read:
+`skills/paperclip/references/api-reference.md`
+
 ## Critical Rules
 
 - **Always checkout** before working. Never PATCH to `in_progress` manually.
@@ -291,6 +303,17 @@ PATCH /api/agents/{agentId}/instructions-path
 | List issue attachments                    | `GET /api/issues/:issueId/attachments`                                                     |
 | Get attachment content                    | `GET /api/attachments/:attachmentId/content`                                               |
 | Delete attachment                         | `DELETE /api/attachments/:attachmentId`                                                    |
+| List routines                             | `GET /api/companies/:companyId/routines`                                                   |
+| Get routine                               | `GET /api/routines/:routineId`                                                             |
+| Create routine                            | `POST /api/companies/:companyId/routines`                                                  |
+| Update routine                            | `PATCH /api/routines/:routineId`                                                           |
+| Add trigger                               | `POST /api/routines/:routineId/triggers`                                                   |
+| Update trigger                            | `PATCH /api/routine-triggers/:triggerId`                                                   |
+| Delete trigger                            | `DELETE /api/routine-triggers/:triggerId`                                                  |
+| Rotate webhook secret                     | `POST /api/routine-triggers/:triggerId/rotate-secret`                                      |
+| Manual run                                | `POST /api/routines/:routineId/run`                                                        |
+| Fire webhook (external)                   | `POST /api/routine-triggers/public/:publicId/fire`                                         |
+| List runs                                 | `GET /api/routines/:routineId/runs`                                                        |
 
 ## Company Import / Export
 

skills/paperclip/references/api-reference.md

@@ -597,7 +597,15 @@ Terminal states: `done`, `cancelled`
 | GET    | `/api/agents/me/inbox/mine?userId=:userId` | Mine-tab issue list for a specific board user |
 | GET    | `/api/agents/:agentId`             | Agent details + chain of command     |
 | GET    | `/api/companies/:companyId/agents` | List all agents in company           |
+| POST   | `/api/companies/:companyId/agents` | Create agent directly (no approval)  |
+| PATCH  | `/api/agents/:agentId`             | Update agent config or budget        |
+| POST   | `/api/agents/:agentId/pause`       | Temporarily stop heartbeats          |
+| POST   | `/api/agents/:agentId/resume`      | Resume a paused agent                |
+| POST   | `/api/agents/:agentId/terminate`   | Permanently deactivate agent (irreversible) |
+| POST   | `/api/agents/:agentId/keys`        | Create long-lived API key (full value shown once) |
+| POST   | `/api/agents/:agentId/heartbeat/invoke` | Manually trigger a heartbeat    |
 | GET    | `/api/companies/:companyId/org`    | Org chart tree                       |
+| GET    | `/api/companies/:companyId/adapters/:adapterType/models` | List selectable models for an adapter type |
 | PATCH  | `/api/agents/:agentId/instructions-path` | Set/clear instructions path (`AGENTS.md`) |
 | GET    | `/api/agents/:agentId/config-revisions` | List config revisions            |
 | POST   | `/api/agents/:agentId/config-revisions/:revisionId/rollback` | Roll back config |
@@ -608,6 +616,7 @@ Terminal states: `done`, `cancelled`
 | ------ | ---------------------------------- | ---------------------------------------------------------------------------------------- |
 | GET    | `/api/companies/:companyId/issues` | List issues, sorted by priority. Filters: `?status=`, `?assigneeAgentId=`, `?assigneeUserId=`, `?projectId=`, `?labelId=`, `?q=` (full-text search across title, identifier, description, comments) |
 | GET    | `/api/issues/:issueId`             | Issue details + ancestors                                                                |
+| GET    | `/api/issues/:issueId/heartbeat-context` | Compact context for heartbeat: issue state, ancestor summaries, comment cursor  |
 | POST   | `/api/companies/:companyId/issues` | Create issue                                                                             |
 | PATCH  | `/api/issues/:issueId`             | Update issue (optional `comment` field adds a comment in same call)                      |
 | POST   | `/api/issues/:issueId/checkout`    | Atomic checkout (claim + start). Idempotent if you already own it.                       |
@@ -615,8 +624,13 @@ Terminal states: `done`, `cancelled`
 | GET    | `/api/issues/:issueId/comments`    | List comments                                                                            |
 | GET    | `/api/issues/:issueId/comments/:commentId` | Get a specific comment by ID                                                     |
 | POST   | `/api/issues/:issueId/comments`    | Add comment (@-mentions trigger wakeups)                                                 |
+| GET    | `/api/issues/:issueId/documents`   | List issue documents                                                                     |
+| GET    | `/api/issues/:issueId/documents/:key` | Get issue document by key                                                            |
+| PUT    | `/api/issues/:issueId/documents/:key` | Create or update issue document (send `baseRevisionId` when updating)                |
+| GET    | `/api/issues/:issueId/documents/:key/revisions` | Document revision history                                                  |
+| DELETE | `/api/issues/:issueId/documents/:key` | Delete document (board-only)                                                         |
 | GET    | `/api/issues/:issueId/approvals`   | List approvals linked to issue                                                           |
-| POST   | `/api/issues/:issueId/approvals`   | Link approval to issue                                                                    |
+| POST   | `/api/issues/:issueId/approvals`   | Link approval to issue                                                                   |
 | DELETE | `/api/issues/:issueId/approvals/:approvalId` | Unlink approval from issue                                                     |
 
 ### Companies, Projects, Goals
@@ -624,7 +638,11 @@ Terminal states: `done`, `cancelled`
 | Method | Path                                 | Description        |
 | ------ | ------------------------------------ | ------------------ |
 | GET    | `/api/companies`                     | List all companies |
+| POST   | `/api/companies`                     | Create company     |
 | GET    | `/api/companies/:companyId`          | Company details    |
+| PATCH  | `/api/companies/:companyId`          | Update company (CEO: name/description/brandColor/logoAssetId; board: all fields) |
+| POST   | `/api/companies/:companyId/logo`     | Upload company logo (multipart, field: `file`) — returns `assetId` to set via PATCH |
+| POST   | `/api/companies/:companyId/archive`  | Archive company    |
 | GET    | `/api/companies/:companyId/projects` | List projects      |
 | GET    | `/api/projects/:projectId`           | Project details    |
 | POST   | `/api/companies/:companyId/projects` | Create project (optional inline `workspace`) |
@@ -639,6 +657,22 @@ Terminal states: `done`, `cancelled`
 | PATCH  | `/api/goals/:goalId`                 | Update goal        |
 | POST   | `/api/companies/:companyId/openclaw/invite-prompt` | Generate OpenClaw invite prompt (CEO/board only) |
 
+### Routines
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET    | `/api/companies/:companyId/routines` | List all routines in company |
+| GET    | `/api/routines/:routineId` | Routine details including triggers |
+| POST   | `/api/companies/:companyId/routines` | Create routine (`assigneeAgentId` + `projectId` required; agents: own only) |
+| PATCH  | `/api/routines/:routineId` | Update routine (agents: own only, cannot reassign) |
+| POST   | `/api/routines/:routineId/triggers` | Add trigger (`schedule`, `webhook`, or `api` kind) |
+| PATCH  | `/api/routine-triggers/:triggerId` | Update trigger (e.g. disable, change cron) |
+| DELETE | `/api/routine-triggers/:triggerId` | Delete trigger |
+| POST   | `/api/routine-triggers/:triggerId/rotate-secret` | Rotate webhook signing secret (previous secret immediately invalidated) |
+| POST   | `/api/routines/:routineId/run` | Manual run (bypasses schedule; concurrency policy still applies) |
+| POST   | `/api/routine-triggers/public/:publicId/fire` | Fire webhook trigger from external system |
+| GET    | `/api/routines/:routineId/runs` | Run history (default 50) |
+
 ### Approvals, Costs, Activity, Dashboard
 
 | Method | Path                                         | Description                        |
@@ -650,14 +684,39 @@ Terminal states: `done`, `cancelled`
 | GET    | `/api/approvals/:approvalId/issues`          | Issues linked to approval          |
 | GET    | `/api/approvals/:approvalId/comments`        | Approval comments                  |
 | POST   | `/api/approvals/:approvalId/comments`        | Add approval comment               |
+| POST   | `/api/approvals/:approvalId/approve`         | Board: approve (with `decisionNote`) |
+| POST   | `/api/approvals/:approvalId/reject`          | Board: reject (with `decisionNote`) |
 | POST   | `/api/approvals/:approvalId/request-revision`| Board asks for revision            |
 | POST   | `/api/approvals/:approvalId/resubmit`        | Resubmit revised approval          |
+| POST   | `/api/companies/:companyId/cost-events`      | Report cost event (adapter-facing) |
 | GET    | `/api/companies/:companyId/costs/summary`    | Company cost summary               |
 | GET    | `/api/companies/:companyId/costs/by-agent`   | Costs by agent                     |
 | GET    | `/api/companies/:companyId/costs/by-project` | Costs by project                   |
 | GET    | `/api/companies/:companyId/activity`         | Activity log                       |
 | GET    | `/api/companies/:companyId/dashboard`        | Company health summary             |
 
+### Secrets
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET    | `/api/companies/:companyId/secrets` | List secrets (metadata only — values never returned) |
+| POST   | `/api/companies/:companyId/secrets` | Create secret — value encrypted at rest, full value shown once |
+| PATCH  | `/api/secrets/:secretId`            | Update secret value (creates new version; `"version": "latest"` refs auto-update) |
+
+Reference secrets in agent adapter config instead of inline values:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_API_KEY": {
+      "type": "secret_ref",
+      "secretId": "{secretId}",
+      "version": "latest"
+    }
+  }
+}
+```
+
 ---
 
 ## Common Mistakes