@tickernelz/paperclip-pro-adapter-codex-local 2026.925.0 → 2026.925.2

package/skills/paperclip/references/company-skills.md

@@ -2,6 +2,8 @@
 
 Use this reference when a board user, CEO, or manager asks you to find a skill, install it into the company library, or assign it to an agent.
 
+**Toolset:** `paperclipListSkills` is in the default `core` toolset. Every other tool on this page is in the `extended` toolset: it is available when the operator enables `PAPERCLIP_MCP_TOOLSETS=core,extended`; otherwise use `paperclipApiRequest`. `companyId` is optional on company-scoped tools and defaults to your company.
+
 ## What Exists
 
 - App-shipped catalog: a curated set of company skills in `@tickernelz/paperclip-pro-skills-catalog`, browseable and installable without leaving Paperclip.
@@ -11,8 +13,8 @@ Use this reference when a board user, CEO, or manager asks you to find a skill,
 
 The canonical model is:
 
-1. add the skill to the company library — either from the app catalog (`skills install`), an external source (`skills import`), or a managed local skill (`skills create`/`skills scan-projects`)
-2. attach the company skill to the agent (`skills agent sync`)
+1. add the skill to the company library — either from the app catalog (`paperclipInstallCatalogSkill`), an external source (`paperclipImportSkill`), or a managed local skill (`paperclipCreateSkill` / `paperclipCreateSkillScanProject`)
+2. attach the company skill to the agent (`paperclipSyncAgentSkill`)
 3. optionally do step 2 during hire/create with `desiredSkills`
 
 Catalog install ≠ agent attach. Installing a catalog skill only adds the row to
@@ -26,51 +28,42 @@ set.
 - Agent skill assignment: same permission model as updating that agent
 - Team installs continue to require `agents:create` because they import or create agents in addition to attaching skills.
 
-## Core Endpoints
+## Tools
 
 App-shipped catalog (read-only browse + company install):
 
-- `GET /api/skills/catalog`
-- `GET /api/skills/catalog/:catalogId`
-- `GET /api/skills/catalog/ref?ref=<id|key|slug>`
-- `GET /api/skills/catalog/:catalogId/files?path=SKILL.md`
-- `POST /api/companies/:companyId/skills/install-catalog`
+- `paperclipGetSkillCatalog` — browse catalog entries; each entry reports its `kind` (`bundled` or `optional`)
+- `paperclipGetSkillCatalogByCatalogId` — `{ "catalogId": "<catalog-id>" }`
+- resolving a catalog ref and reading catalog files have no dedicated tool: use `paperclipApiRequest` with `method: "GET"`, `path: "/skills/catalog/ref?ref=<id|key|slug>"` or `path: "/skills/catalog/<catalogId>/files?path=SKILL.md"`
+- `paperclipInstallCatalogSkill` — install a catalog skill into the company
 
 Company library:
 
-- `GET /api/companies/:companyId/skills`
-- `GET /api/companies/:companyId/skills/:skillId`
-- `GET /api/companies/:companyId/skills/:skillId/files?path=SKILL.md`
-- `POST /api/companies/:companyId/skills` (managed local create)
-- `POST /api/companies/:companyId/skills/import`
-- `POST /api/companies/:companyId/skills/scan-projects`
-- `GET /api/companies/:companyId/skills/:skillId/update-status`
-- `POST /api/companies/:companyId/skills/:skillId/install-update`
-- `POST /api/companies/:companyId/skills/:skillId/audit`
-- `POST /api/companies/:companyId/skills/:skillId/reset`
-- `DELETE /api/companies/:companyId/skills/:skillId`
+- `paperclipListSkills` — the installed company skill library
+- `paperclipGetSkill` — `{ "skillId": "<skill-id>" }`
+- reading a company skill file has no dedicated tool: use `paperclipApiRequest` with `method: "GET"`, `path: "/companies/<companyId>/skills/<skillId>/files?path=SKILL.md"`
+- `paperclipCreateSkill` — managed local create
+- `paperclipImportSkill` — import from an external source
+- `paperclipCreateSkillScanProject` — discover skills in the company project workspaces
+- `paperclipListSkillUpdateStatus` / `paperclipInstallUpdateSkill` — check and apply an update
+- `paperclipAuditSkill`, `paperclipResetSkill`, `paperclipDeleteSkill`
 
 Agent attach and hire/create composition:
 
-- `GET /api/agents/:agentId/skills`
-- `POST /api/agents/:agentId/skills/sync`
-- `POST /api/companies/:companyId/agent-hires`
-- `POST /api/companies/:companyId/agents`
-
-If a board user, CEO, or manager is driving locally, prefer the
-`paperclip-pro skills` CLI documented in `doc/CLI.md` — it wraps every endpoint
-above, accepts company skill or catalog refs by `id`/`key`/`slug`, and prints
-the same JSON these endpoints return when called with `--json`.
+- `paperclipListAgentSkills` — `{ "id": "<agent-id>" }`
+- `paperclipSyncAgentSkill` — attach or detach company skills on an agent
+- `paperclipCreateAgentHire` — hire with `desiredSkills`
+- `paperclipCreateAgent` — direct create with `desiredSkills`
 
 ## Install A Skill Into The Company
 
 Two paths cover the common cases:
 
 1. **App-shipped catalog** (preferred when the right skill exists in the
-   bundled/optional catalog) — browse it first, then install with the catalog
-   install endpoint. No external network fetch happens.
-2. **External source** (skills.sh, GitHub, local path, or URL) — use the
-   import endpoint below.
+   bundled/optional catalog) — browse it first, then install with
+   `paperclipInstallCatalogSkill`. No external network fetch happens.
+2. **External source** (skills.sh, GitHub, local path, or URL) — use
+   `paperclipImportSkill`.
 
 ### App-shipped catalog
 
@@ -78,22 +71,16 @@ Browse, inspect, and install catalog skills before reaching for an external
 source. Bundled skills are the curated defaults for any company; optional
 skills are role- or domain-specific.
 
-```sh
-curl -sS "$PAPERCLIP_API_URL/api/skills/catalog?kind=bundled" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+Browse with `paperclipGetSkillCatalog`, inspect one entry with
+`paperclipGetSkillCatalogByCatalogId`, then install:
 
-curl -sS "$PAPERCLIP_API_URL/api/skills/catalog/ref?ref=github-pr-workflow" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
-
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/install-catalog" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "catalogSkillId": "paperclipai:bundled:software-development:github-pr-workflow"
-  }'
+```json
+{
+  "catalogSkillId": "paperclipai:bundled:software-development:github-pr-workflow"
+}
 ```
 
-The install response records provenance (`catalogId`, `catalogKey`,
+The install result records provenance (`catalogId`, `catalogKey`,
 `packageVersion`, `originHash`) on the company skill so update/audit/reset
 flows know the pinned origin. `force: true` may replace a same-key
 catalog-managed skill but never bypasses hard-stop audit findings.
@@ -115,35 +102,22 @@ Import using a **skills.sh URL**, a key-style source string, a GitHub URL, or a
 
 ### Example: skills.sh import (preferred)
 
-```sh
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/import" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "source": "https://skills.sh/google-labs-code/stitch-skills/design-md"
-  }'
+`paperclipImportSkill`:
+
+```json
+{ "source": "https://skills.sh/google-labs-code/stitch-skills/design-md" }
 ```
 
 Or equivalently using the key-style string:
 
-```sh
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/import" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "source": "google-labs-code/stitch-skills/design-md"
-  }'
+```json
+{ "source": "google-labs-code/stitch-skills/design-md" }
 ```
 
 ### Example: GitHub import
 
-```sh
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/import" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "source": "https://github.com/vercel-labs/agent-browser"
-  }'
+```json
+{ "source": "https://github.com/vercel-labs/agent-browser" }
 ```
 
 You can also use source strings such as:
@@ -152,31 +126,13 @@ You can also use source strings such as:
 - `vercel-labs/agent-browser/agent-browser`
 - `npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser`
 
-If the task is to discover skills from the company project workspaces first:
-
-```sh
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/scan-projects" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{}'
-```
+If the task is to discover skills from the company project workspaces first, call `paperclipCreateSkillScanProject` with no arguments beyond the optional `companyId`.
 
 ## Inspect What Was Installed
 
-```sh
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
-```
-
-Read the skill entry and its `SKILL.md`:
-
-```sh
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/<skill-id>" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
-
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/<skill-id>/files?path=SKILL.md" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
-```
+Call `paperclipListSkills` for the library, then `paperclipGetSkill` with the
+`skillId` for one entry. To read its `SKILL.md`, use `paperclipApiRequest` with
+`method: "GET"`, `path: "/companies/<companyId>/skills/<skillId>/files?path=SKILL.md"`.
 
 ## Assign Skills To An Existing Agent
 
@@ -188,79 +144,43 @@ curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/<skill-i
 
 The server persists canonical company skill keys.
 
-The request must include a merge mode:
+`paperclipSyncAgentSkill` requires a merge mode:
 
 - `add` adds the named skills and keeps every other assignment.
 - `remove` removes only the named skills.
 - `replace` overwrites the complete desired skill set. Use it only after explicit confirmation.
 
-```sh
-curl -sS -X POST "$PAPERCLIP_API_URL/api/agents/<agent-id>/skills/sync" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "mode": "add",
-    "desiredSkills": [
-      "vercel-labs/agent-browser/agent-browser"
-    ]
-  }'
+```json
+{
+  "id": "<agent-id>",
+  "mode": "add",
+  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"]
+}
 ```
 
-If you need the current state first:
-
-```sh
-curl -sS "$PAPERCLIP_API_URL/api/agents/<agent-id>/skills" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
-```
+If you need the current state first, call `paperclipListAgentSkills` with
+`{ "id": "<agent-id>" }`.
 
 ## Include Skills During Hire Or Create
 
-Use the same company skill keys or references in `desiredSkills` when hiring or creating an agent:
-
-```sh
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-hires" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "QA Browser Agent",
-    "role": "qa",
-    "adapterType": "codex_local",
-    "adapterConfig": {
-      "cwd": "/abs/path/to/repo"
-    },
-    "desiredSkills": [
-      "agent-browser"
-    ]
-  }'
-```
+Use the same company skill keys or references in `desiredSkills` when hiring with `paperclipCreateAgentHire`:
 
-For direct create without approval:
-
-```sh
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agents" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "QA Browser Agent",
-    "role": "qa",
-    "adapterType": "codex_local",
-    "adapterConfig": {
-      "cwd": "/abs/path/to/repo"
-    },
-    "desiredSkills": [
-      "agent-browser"
-    ]
-  }'
+```json
+{
+  "name": "QA Browser Agent",
+  "role": "qa",
+  "adapterType": "codex_local",
+  "adapterConfig": { "cwd": "/abs/path/to/repo" },
+  "desiredSkills": ["agent-browser"]
+}
 ```
 
+For direct create without approval, pass the same arguments to `paperclipCreateAgent`.
+
 ## Notes
 
 - Built-in Paperclip runtime skills are still added automatically when required by the adapter.
-- If a reference is missing or ambiguous, the API returns `422`.
+- If a reference is missing or ambiguous, the tool returns a `422` error and nothing was installed or assigned.
 - Prefer linking back to the relevant issue, approval, and agent when you comment about skill changes.
-- Use company portability routes when you need whole-package import/export, not just a skill:
-  - `POST /api/companies/:companyId/imports/preview`
-  - `POST /api/companies/:companyId/imports/apply`
-  - `POST /api/companies/:companyId/exports/preview`
-  - `POST /api/companies/:companyId/exports`
+- Whole-package company import/export has no dedicated tool. Use `paperclipApiRequest` with `method: "POST"` and one of `path: "/companies/<companyId>/imports/preview"`, `path: "/companies/<companyId>/imports/apply"`, `path: "/companies/<companyId>/exports/preview"`, `path: "/companies/<companyId>/exports"`.
 - Use skill-only import when the task is specifically to add a skill to the company library without importing the surrounding company/team/package structure.

package/skills/paperclip/references/issue-workspaces.md

@@ -2,18 +2,19 @@
 
 Use this reference when an issue has an isolated execution workspace and you need to inspect or run that workspace's services, especially for QA/browser verification.
 
+All tools in this file are in the default `core` toolset.
+
 ## Discover the Workspace
 
-Start from the issue, not from memory:
+Start from the issue, not from memory. Call `paperclipGetIssueWorkspaceRuntime` with the issue:
 
-```sh
-curl -sS -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  "$PAPERCLIP_API_URL/api/issues/$PAPERCLIP_TASK_ID/heartbeat-context"
+```json
+{ "issueId": "PAP-1135" }
 ```
 
-Read `currentExecutionWorkspace`:
+Read `currentExecutionWorkspace` in the result:
 
-- `id` — execution workspace id for control endpoints
+- `id` — execution workspace id used by workspace-scoped tools
 - `cwd` / `branchName` — local checkout context
 - `status` / `closedAt` — whether the workspace is usable
 - `runtimeServices[]` — current services, including `serviceName`, `status`, `healthStatus`, `url`, `port`, and `runtimeServiceId`
@@ -22,35 +23,17 @@ If `currentExecutionWorkspace` is `null`, the issue does not currently have a re
 
 ## Control Services
 
-Prefer Paperclip-managed runtime service controls over manual `pnpm dev &` or ad-hoc background processes. These endpoints keep service state, URLs, logs, and ownership visible to other agents and the board.
-
-```sh
-# Start all configured services; waits for configured readiness checks.
-curl -sS -X POST \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-  -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/execution-workspaces/<workspace-id>/runtime-services/start" \
-  -d '{}'
-
-# Restart all configured services.
-curl -sS -X POST \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-  -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/execution-workspaces/<workspace-id>/runtime-services/restart" \
-  -d '{}'
-
-# Stop all running services.
-curl -sS -X POST \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-  -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/execution-workspaces/<workspace-id>/runtime-services/stop" \
-  -d '{}'
+Prefer Paperclip-managed runtime service controls over manual `pnpm dev &` or ad-hoc background processes. The tool keeps service state, URLs, logs, and ownership visible to other agents and the board.
+
+`paperclipControlIssueWorkspaceServices` resolves the issue's workspace for you. Pass `issueId` and `action`:
+
+```json
+{ "issueId": "PAP-1135", "action": "start" }
+{ "issueId": "PAP-1135", "action": "restart" }
+{ "issueId": "PAP-1135", "action": "stop" }
 ```
 
-To target a configured service, pass one of:
+`start` waits for the configured readiness checks. To target one configured service instead of all of them, add exactly one of:
 
 ```json
 { "workspaceCommandId": "web" }
@@ -58,23 +41,25 @@ To target a configured service, pass one of:
 { "serviceIndex": 0 }
 ```
 
-The response includes an updated `workspace.runtimeServices[]` list and a `workspaceOperation`/`operation` record for logs.
+The result includes an updated `workspace.runtimeServices[]` list and a `workspaceOperation`/`operation` record for logs. Treat that returned service state as the confirmation that the control actually applied; if the service you asked for is not in the result with the expected `status`, read the runtime again before claiming it is running.
 
 ## Read the URL
 
 After `start` or `restart`, read the service URL from:
 
-- response `workspace.runtimeServices[].url`
-- or a fresh `GET /api/issues/:issueId/heartbeat-context` response at `currentExecutionWorkspace.runtimeServices[].url`
+- the control result at `workspace.runtimeServices[].url`
+- or a fresh `paperclipGetIssueWorkspaceRuntime` call at `currentExecutionWorkspace.runtimeServices[].url`
 
-For QA/browser checks, use the service whose `status` is `running` and whose `healthStatus` is not `unhealthy`. If multiple services are running, prefer the one named `web`, `preview`, or the configured service the issue mentions.
+To block until a service is actually up, call `paperclipWaitForIssueWorkspaceService`:
 
-## MCP Tools
+```json
+{ "issueId": "PAP-1135", "serviceName": "web", "timeoutSeconds": 120 }
+```
 
-When the Paperclip MCP tools are available, prefer these issue-scoped tools:
+Select the service by `serviceName` or `runtimeServiceId`. `timeoutSeconds` is optional (default 60, maximum 300). The tool returns once the service is running and reports its URL when one is exposed.
+
+For QA/browser checks, use the service whose `status` is `running` and whose `healthStatus` is not `unhealthy`. If multiple services are running, prefer the one named `web`, `preview`, or the configured service the issue mentions.
 
-- `paperclipGetIssueWorkspaceRuntime` — reads `currentExecutionWorkspace` and service URLs for an issue.
-- `paperclipControlIssueWorkspaceServices` — starts, stops, or restarts the current issue workspace services.
-- `paperclipWaitForIssueWorkspaceService` — waits until a selected service is running and returns its URL when exposed.
+## Workspace-Scoped Read
 
-These tools resolve the issue's workspace id for you, so QA agents do not need to know the lower-level execution workspace endpoint first.
+When you already hold an execution workspace id — for example from another agent's comment — `paperclipGetExecutionWorkspace` with `{ "id": "<execution-workspace-id>" }` returns that workspace and its runtime services. Prefer the issue-scoped tools above when you start from an issue: they resolve the workspace id for you.

package/skills/paperclip/references/routines.md

@@ -9,6 +9,8 @@ A routine has:
 - A catch-up policy (what to do with missed scheduled runs)
 - An activity gate policy (whether quiet scheduled ticks should be skipped)
 
+**Toolset:** the routine tools are in the `extended` toolset. They are available when the operator enables `PAPERCLIP_MCP_TOOLSETS=core,extended`; otherwise use `paperclipApiRequest` for the same operations.
+
 **Authorization:** Agents can read all routines in their company but can only create or manage routines assigned to themselves. Board operators have full access, including reassignment.
 
 ---
@@ -26,15 +28,16 @@ Paused routines do not fire. Archived routines do not fire and cannot be unarchi
 
 ## Creating a Routine
 
-```
-POST /api/companies/{companyId}/routines
+`paperclipCreateRoutine` — `companyId` is optional and defaults to your company.
+
+```json
 {
   "title": "Weekly CEO briefing",
   "description": "Compile status report and post to Slack",
   "assigneeAgentId": "{agentId}",
   "projectId": "{projectId}",
-  "goalId": "{goalId}",           // optional
-  "parentIssueId": "{issueId}",   // optional — parent for run issues
+  "goalId": "{goalId}",
+  "parentIssueId": "{issueId}",
   "priority": "medium",
   "status": "active",
   "concurrencyPolicy": "coalesce_if_active",
@@ -59,6 +62,8 @@ POST /api/companies/{companyId}/routines
 | `activityGatePolicy` | no | `always` (default) or `require_external_activity`; see below |
 | `activityGateScope` | no | `company` (default) or `project`; see below |
 
+The result is the created routine. Read its `id` from there for triggers and runs.
+
 ---
 
 ## Concurrency Policies
@@ -106,7 +111,7 @@ The gate excludes activity generated by the routine's own dispatched run issues,
 
 ### Example: skip quiet nights
 
-This hourly watcher runs after company activity, follows up while delegated work continues, and stops consuming runs once the company settles overnight:
+This hourly watcher runs after company activity, follows up while delegated work continues, and stops consuming runs once the company settles overnight. Create it with `paperclipCreateRoutine`:
 
 ```json
 {
@@ -127,19 +132,18 @@ Add a schedule trigger with `cronExpression: "0 * * * *"`. The first tick runs.
 
 A routine can have multiple triggers of different kinds.
 
-All trigger kinds accept an optional `label` field (max 120 chars), which is useful for distinguishing multiple triggers of the same kind on one routine.
-
-```
-POST /api/routines/{routineId}/triggers
-```
+`paperclipCreateRoutineTrigger` takes the routine as `id` and the trigger configuration nested under `body`. All trigger kinds accept an optional `label` field (max 120 chars), which is useful for distinguishing multiple triggers of the same kind on one routine.
 
 ### Schedule (cron)
 
 ```json
 {
-  "kind": "schedule",
-  "cronExpression": "0 9 * * 1",
-  "timezone": "Europe/Amsterdam"
+  "id": "{routineId}",
+  "body": {
+    "kind": "schedule",
+    "cronExpression": "0 9 * * 1",
+    "timezone": "Europe/Amsterdam"
+  }
 }
 ```
 
@@ -151,81 +155,85 @@ POST /api/routines/{routineId}/triggers
 
 ```json
 {
-  "kind": "webhook",
-  "signingMode": "hmac_sha256",
-  "replayWindowSec": 300
+  "id": "{routineId}",
+  "body": {
+    "kind": "webhook",
+    "signingMode": "hmac_sha256",
+    "replayWindowSec": 300
+  }
 }
 ```
 
 - `signingMode`: `bearer` (default) or `hmac_sha256`
 - `replayWindowSec`: 30-86400 (default 300)
-- Response includes the webhook URL (`publicId`-based) and the signing secret
-- Fire externally: `POST /api/routine-triggers/public/{publicId}/fire`
-  - Bearer: `Authorization: Bearer <secret>`
+- The result includes the webhook URL (`publicId`-based) and the signing secret
+- External systems fire that returned URL directly:
+  - Bearer: `Authorization` header carrying the returned secret
   - HMAC: `X-Paperclip-Signature` + `X-Paperclip-Timestamp` headers
 
 ### API (manual only)
 
 ```json
 {
-  "kind": "api"
+  "id": "{routineId}",
+  "body": { "kind": "api" }
 }
 ```
 
-No configuration. Fire via the manual run endpoint.
+No configuration. Fire it with the manual run tool below.
 
 ---
 
 ## Updating and Deleting Triggers
 
-```
-PATCH /api/routine-triggers/{triggerId}
-{ "enabled": false, "cronExpression": "0 10 * * 1" }
+`paperclipUpdateRoutineTrigger` takes the trigger as `id`:
 
-DELETE /api/routine-triggers/{triggerId}
+```json
+{ "id": "{triggerId}", "enabled": false, "cronExpression": "0 10 * * 1" }
 ```
 
-To rotate a webhook secret (the old secret is immediately invalidated):
+`paperclipDeleteRoutineTrigger` takes the trigger as `id`:
 
+```json
+{ "id": "{triggerId}" }
 ```
-POST /api/routine-triggers/{triggerId}/rotate-secret
-```
+
+Rotating a webhook secret has no dedicated tool. Use `paperclipApiRequest` with `method: "POST"`, `path: "/routine-triggers/{triggerId}/rotate-secret"`. The old secret is immediately invalidated.
 
 ---
 
 ## Manual Run
 
-Fires a run immediately, bypassing the schedule. Concurrency policy still applies.
+`paperclipRunRoutine` fires a run immediately, bypassing the schedule. Concurrency policy still applies.
 
-```
-POST /api/routines/{routineId}/run
+```json
 {
+  "id": "{routineId}",
   "source": "manual",
-  "triggerId": "{triggerId}",       // optional — attributes run to a specific trigger
-  "payload": { "context": "..." }, // optional — passed to the run issue
-  "idempotencyKey": "unique-key"   // optional — prevents duplicate runs
+  "triggerId": "{triggerId}",
+  "payload": { "context": "..." },
+  "idempotencyKey": "unique-key"
 }
 ```
 
+`triggerId` attributes the run to a specific trigger, `payload` is passed to the run issue, and `idempotencyKey` prevents duplicate runs. All three are optional.
+
 ---
 
 ## Updating a Routine
 
-All create fields are updatable. Agents cannot reassign a routine to another agent.
+All create fields are updatable with `paperclipUpdateRoutine`. Agents cannot reassign a routine to another agent.
 
-```
-PATCH /api/routines/{routineId}
-{ "status": "paused", "title": "New title" }
+```json
+{ "id": "{routineId}", "status": "paused", "title": "New title" }
 ```
 
 ---
 
 ## Reading Routines and Runs
 
-```
-GET /api/companies/{companyId}/routines
-GET /api/routines/{routineId}
-GET /api/routines/{routineId}/runs?limit=50
-```
+- `paperclipListRoutines` — routines in the company; `companyId` defaults to yours
+- `paperclipGetRoutine` — `{ "id": "{routineId}" }`
+- `paperclipListRoutineRuns` — `{ "id": "{routineId}" }`
 
-Use the generic API endpoint tables in `skills/paperclip/references/api-reference.md` when you need a full cross-domain reference. Use this file when you need routine-specific behaviour, payload shape, or policy details.
+Use `paperclipApiRequest` when a routine operation has no dedicated tool. Use this file when you need routine-specific behaviour, payload shape, or policy details.