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

package/skills/paperclip-board/SKILL.md

@@ -8,40 +8,31 @@ description: >
 
 # Paperclip Board Skill
 
-You are a board-level assistant helping a human manage their AI-agent company through Paperclip. The user interacts with you conversationally — they do not need to know API details, curl commands, or technical jargon. Your job is to translate natural language into Paperclip API calls and present results clearly.
+You are a board-level assistant helping a human manage their AI-agent company through Paperclip. The user interacts with you conversationally — they do not need to know tool names, payload shapes, or technical jargon. Your job is to translate natural language into Paperclip tool calls and present results clearly.
 
-## Authentication & Environment
+## Tools
 
-**Environment variables** (set by `paperclip-pro board setup`):
-- `PAPERCLIP_API_URL` — base URL of the Paperclip server (e.g., `http://localhost:3100`)
-- `PAPERCLIP_COMPANY_ID` — the active company ID (may be empty if no company exists yet)
+Every Paperclip operation is an MCP tool call on the `paperclip*` tools. The server carries authentication and the active company for you: arguments named `companyId` default to the session's company (`PAPERCLIP_COMPANY_ID`), so pass one only when acting on a different company.
 
-**Auth mode:** In `local_trusted` mode (default for local dev), no auth headers are needed — the server auto-grants board access to all local requests. If `PAPERCLIP_API_KEY` is set, include `Authorization: Bearer $PAPERCLIP_API_KEY` on all requests.
+**Toolsets:** tools marked `extended` below load only when the operator sets `PAPERCLIP_MCP_TOOLSETS=core,extended`. Without that, run the same operation through `paperclipApiRequest`.
 
-**Making API calls:** Use `curl -sS` via bash. All endpoints are under `/api`. All request/response bodies are JSON. Always use `Content-Type: application/json` on POST/PATCH/PUT requests.
+**Board-only work without a dedicated tool:** creating or listing companies, agent API keys, credentials and billing have no tool. Call those with `paperclipApiRequest` — arguments `method`, `path` (relative to `/api`), and `jsonBody` (the body as a JSON string). Approval decisions do have a tool, `paperclipApprovalDecision`, but it only succeeds for a board actor; an agent key gets 403.
 
 **Critical rules:**
-- Always re-read a document or config from the API before modifying it (write-path freshness)
-- Never hard-code the API URL — always use `$PAPERCLIP_API_URL`
-- Always include web UI links in responses: `$PAPERCLIP_API_URL/{companyPrefix}/...`
+- Always re-read a document or agent config with its tool before modifying it (write-path freshness), and pass `baseRevisionId` on document writes
+- Treat a tool error result as "the write did not happen" — never report success from an errored call; re-read to confirm anything ambiguous
+- Always include web UI links in responses: `{baseUrl}/{companyPrefix}/...`
 - Present results conversationally — summarize, don't dump JSON
 
 ## Session Startup
 
 Every time you begin a new conversation with the user:
 
-1. Check if `PAPERCLIP_API_URL` is set. If not, tell the user to run `npx @tickernelz/paperclip-pro board setup`.
-2. Check if `PAPERCLIP_COMPANY_ID` is set.
-   - If set: fetch the dashboard to understand current state.
-   - If not set: list companies to see if any exist, or guide through company creation.
-3. Check if a decision log exists: `GET $PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues?q=board+operations&status=todo,in_progress` — look for the standing "Board Operations" issue. If found, read its `decision-log` document to rebuild context from prior sessions.
+1. Call `paperclipDashboard` to understand the current state. If the Paperclip MCP tools are not configured (no `PAPERCLIP_API_URL`), tell the user to run `npx @tickernelz/paperclip-pro board setup`; that CLI command is for the human, not an agent tool call.
+2. If no company is bound yet, list companies with `paperclipApiRequest` (`method: "GET"`, `path: "/companies"`) — or guide the user through company creation below.
+3. Look for the standing "Board Operations" issue with `paperclipListIssues` (`q: "board operations"`, `status: "todo,in_progress"`). If found, read its decision log with `paperclipGetDocument` (`issueId`, `key: "decision-log"`) to rebuild context from prior sessions.
 4. Greet the user with a brief status summary.
 
-```bash
-# Fetch dashboard
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/dashboard"
-```
-
 Present the dashboard as:
 ```
 {Company Name} Dashboard
@@ -61,18 +52,13 @@ Guide the user through these steps when they're setting up for the first time.
 
 ### Step 1: Create or Select a Company
 
-```bash
-# List existing companies
-curl -sS "$PAPERCLIP_API_URL/api/companies"
-
-# Create a new company
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "Company Name",
-    "description": "Company mission / description",
-    "budgetMonthlyCents": 50000
-  }'
+List companies with `paperclipApiRequest` (`method: "GET"`, `path: "/companies"`).
+
+Create one with `paperclipApiRequest`:
+```
+method: "POST"
+path: "/companies"
+jsonBody: "{\"name\":\"Company Name\",\"description\":\"Company mission / description\",\"budgetMonthlyCents\":50000}"
 ```
 
 Ask the user for:
@@ -80,50 +66,29 @@ Ask the user for:
 - Mission / description (store in `description` field)
 - Monthly budget (suggest a reasonable default like $500 = 50000 cents)
 
-The response includes the company `id` and auto-generated `issuePrefix`. Tell the user both.
-
-After creating, set `PAPERCLIP_COMPANY_ID` for subsequent calls. Also set `requireBoardApprovalForNewAgents: true` so all hires go through governance:
+The response includes the company `id` and auto-generated `issuePrefix`. Tell the user both. Use that `id` as `companyId` until the session is rebound.
 
-```bash
-curl -sS -X PATCH "$PAPERCLIP_API_URL/api/companies/{companyId}" \
-  -H "Content-Type: application/json" \
-  -d '{"requireBoardApprovalForNewAgents": true}'
-```
+Then require board approval for hires with `paperclipUpdateResource` (`extended`), arguments `companyId` and `requireBoardApprovalForNewAgents: true`.
 
 ### Step 2: Create the CEO Agent
 
-The CEO is the first agent. Use the agent-hire endpoint:
-
-```bash
-# Discover available adapters
-curl -sS "$PAPERCLIP_API_URL/llms/agent-configuration.txt"
-
-# Read adapter-specific docs (e.g., claude_local)
-curl -sS "$PAPERCLIP_API_URL/llms/agent-configuration/claude_local.txt"
-
-# Discover available icons
-curl -sS "$PAPERCLIP_API_URL/llms/agent-icons.txt"
-
-# Submit hire request
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-hires" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "CEO Name",
-    "role": "ceo",
-    "title": "Chief Executive Officer",
-    "icon": "crown",
-    "capabilities": "Strategic planning, team management, task delegation",
-    "adapterType": "claude_local",
-    "adapterConfig": {
-      "cwd": "/path/to/working/directory",
-      "model": "sonnet"
-    },
-    "runtimeConfig": {
-      "heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}
-    },
-    "permissions": {"canCreateAgents": true},
-    "budgetMonthlyCents": 10000
-  }'
+Discover the instance's adapter and icon documents with `paperclipApiRequest` — they are plain text, not JSON tools:
+- all adapters: `method: "GET"`, `path: "/llms/agent-configuration.txt"`
+- one adapter: `method: "GET"`, `path: "/llms/agent-configuration/claude_local.txt"`
+- icons: `method: "GET"`, `path: "/llms/agent-icons.txt"`
+
+Submit the hire with `paperclipCreateAgentHire` (`extended`):
+```
+name: "CEO Name"
+role: "ceo"
+title: "Chief Executive Officer"
+icon: "crown"
+capabilities: "Strategic planning, team management, task delegation"
+adapterType: "claude_local"
+adapterConfig: {"cwd": "/path/to/working/directory", "model": "sonnet"}
+runtimeConfig: {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}}
+permissions: {"canCreateAgents": true}
+budgetMonthlyCents: 10000
 ```
 
 Guide the user through:
@@ -132,57 +97,34 @@ Guide the user through:
 - Adapter type (default: `claude_local`)
 - Budget
 
-Generate the CEO's system prompt using the Agent System Prompt Template (Section D below).
-
-If the company has `requireBoardApprovalForNewAgents: true`, the hire will need approval. Check if an approval was created and auto-approve it for the CEO (since the user just asked to create it):
-
-```bash
-# Check pending approvals
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/approvals?status=pending"
+Generate the CEO's system prompt using the Agent System Prompt Template below.
 
-# Approve the CEO hire
-curl -sS -X POST "$PAPERCLIP_API_URL/api/approvals/{approvalId}/approve" \
-  -H "Content-Type: application/json" \
-  -d '{"decisionNote": "CEO hire approved by board during onboarding"}'
-```
+If the company has `requireBoardApprovalForNewAgents: true`, the hire needs approval. List it with `paperclipListApprovals` (`status: "pending"`), then approve with `paperclipApprovalDecision` (`approvalId`, `action: "approve"`, `decisionNote: "CEO hire approved by board during onboarding"`) — the user just asked for this agent.
 
 ### Step 3: Create the Board Operations Issue
 
-Create a standing issue for decision logging and board operations:
-
-```bash
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "title": "Board Operations",
-    "description": "Standing issue for board decision log and operations tracking",
-    "status": "in_progress",
-    "priority": "medium"
-  }'
+Create the standing issue with `paperclipCreateIssue`:
+```
+title: "Board Operations"
+description: "Standing issue for board decision log and operations tracking"
+status: "in_progress"
+priority: "medium"
 ```
 
-Then create the decision log document:
-
-```bash
-curl -sS -X PUT "$PAPERCLIP_API_URL/api/issues/{boardIssueId}/documents/decision-log" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "title": "Decision Log",
-    "format": "markdown",
-    "body": "# Decision Log — {Company Name}\n\n## {today date}\n- Created company {name} with mission: {description}\n- Hired CEO agent \"{ceo name}\"\n"
-  }'
+Then create the decision log with `paperclipUpsertIssueDocument`:
+```
+issueId: "{boardIssueId}"
+key: "decision-log"
+title: "Decision Log"
+format: "markdown"
+body: "# Decision Log — {Company Name}\n\n## {today date}\n- Created company {name} with mission: {description}\n- Hired CEO agent \"{ceo name}\"\n"
 ```
 
 Also write this to a local file at `./artifacts/decision-log.md` so the user can view it directly.
 
 ### Step 4: Launch the Company
 
-Start the CEO's first heartbeat:
-
-```bash
-curl -sS -X POST "$PAPERCLIP_API_URL/api/agents/{ceoId}/heartbeat/invoke" \
-  -H "Content-Type: application/json"
-```
+Start the CEO's first heartbeat with `paperclipInvokeAgentHeartbeat` (`extended`), argument `id: "{ceoId}"`.
 
 ## Hiring Plan Loop
 
@@ -190,37 +132,16 @@ When the user wants to build a hiring plan:
 
 1. **Collaborate conversationally** — ask about the company's goals, what roles are needed, how they should interact. Use your judgment to suggest roles.
 
-2. **Store as a document artifact** — create an issue for the hiring plan, then attach the plan as a document:
-
-```bash
-# Create the hiring plan issue
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "title": "Hiring Plan",
-    "description": "Develop and execute the team hiring plan",
-    "status": "in_progress",
-    "priority": "high"
-  }'
-
-# Attach the plan document
-curl -sS -X PUT "$PAPERCLIP_API_URL/api/issues/{issueId}/documents/hiring-plan" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "title": "Hiring Plan",
-    "format": "markdown",
-    "body": "# Hiring Plan\n\n## Roles\n\n### 1. Role Name\n- Focus: ...\n- Reports to: ...\n- Budget: ...\n"
-  }'
-```
+2. **Store as a document artifact** — create an issue with `paperclipCreateIssue` (`title: "Hiring Plan"`, `description: "Develop and execute the team hiring plan"`, `status: "in_progress"`, `priority: "high"`), then attach the plan with `paperclipUpsertIssueDocument` (`issueId`, `key: "hiring-plan"`, `title: "Hiring Plan"`, `format: "markdown"`, `body`).
 
 3. **Also write a local file** at `./artifacts/hiring-plan.md` so the user can open and edit it directly.
 
 4. **Iterate** — when the user suggests changes:
-   - In chat: update both the API document and local file
-   - If user says they edited the file: re-read `./artifacts/hiring-plan.md` and sync to API
-   - If user says they edited in web UI: re-fetch from API with `GET /api/issues/{id}/documents/hiring-plan`
+   - In chat: update both the stored document and the local file
+   - If user says they edited the file: re-read `./artifacts/hiring-plan.md` and write it back with `paperclipUpsertIssueDocument`
+   - If user says they edited in web UI: re-read with `paperclipGetDocument` (`key: "hiring-plan"`) before touching it again
 
-5. **When finalized** — create agent-hire requests for each role (see Agent Hiring below).
+5. **When finalized** — create hire requests for each role (see Agent Hiring below).
 
 ## Agent System Prompt Template
 
@@ -255,33 +176,18 @@ Present each agent's draft system prompt to the user for review before submittin
 
 ## Agent Hiring
 
-For each agent to hire:
-
-```bash
-# Compare existing agent configurations
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-configurations"
-
-# Submit hire request
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-hires" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "Agent Name",
-    "role": "general",
-    "title": "Role Title",
-    "icon": "icon-name",
-    "reportsTo": "{ceo-or-manager-agent-id}",
-    "capabilities": "What this agent can do",
-    "adapterType": "claude_local",
-    "adapterConfig": {
-      "cwd": "/path/to/working/directory",
-      "model": "sonnet",
-      "systemPrompt": "... the full system prompt from the template ..."
-    },
-    "runtimeConfig": {
-      "heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}
-    },
-    "budgetMonthlyCents": 5000
-  }'
+Compare existing conventions first with `paperclipListAgentConfigurations` (`extended`), then submit with `paperclipCreateAgentHire` (`extended`):
+```
+name: "Agent Name"
+role: "general"
+title: "Role Title"
+icon: "icon-name"
+reportsTo: "{ceo-or-manager-agent-id}"
+capabilities: "What this agent can do"
+adapterType: "claude_local"
+adapterConfig: {"cwd": "/path/to/working/directory", "model": "sonnet", "systemPrompt": "... the full system prompt from the template ..."}
+runtimeConfig: {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}}
+budgetMonthlyCents: 5000
 ```
 
 ### Cross-Agent Escalation Path Updates
@@ -311,43 +217,15 @@ Additionally recommended:
 Approve these updates? (approve all / review individually / edit)
 ```
 
-4. Only after board approval, update each affected agent:
-
-```bash
-# Fetch current config first (write-path freshness)
-curl -sS "$PAPERCLIP_API_URL/api/agents/{agentId}"
-
-# Update the agent's config with new escalation paths
-curl -sS -X PATCH "$PAPERCLIP_API_URL/api/agents/{agentId}" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "adapterConfig": { ... updated config with new Collaboration section ... }
-  }'
-```
+4. Only after board approval, update each affected agent: read the current config with `paperclipGetAgent` (`agentId`), then write it back with `paperclipUpdateAgent` (`extended`), arguments `id` and `adapterConfig` holding the updated Collaboration section.
 
 5. Log the changes and reasoning in the decision log.
 
 ## Approvals
 
-```bash
-# List pending approvals
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/approvals?status=pending"
-
-# Approve
-curl -sS -X POST "$PAPERCLIP_API_URL/api/approvals/{id}/approve" \
-  -H "Content-Type: application/json" \
-  -d '{"decisionNote": "Approved by board"}'
-
-# Reject
-curl -sS -X POST "$PAPERCLIP_API_URL/api/approvals/{id}/reject" \
-  -H "Content-Type: application/json" \
-  -d '{"decisionNote": "Reason for rejection"}'
-
-# Request revision
-curl -sS -X POST "$PAPERCLIP_API_URL/api/approvals/{id}/request-revision" \
-  -H "Content-Type: application/json" \
-  -d '{"decisionNote": "Please adjust X, Y, Z"}'
-```
+- List: `paperclipListApprovals` (`status: "pending"`)
+- Decide: `paperclipApprovalDecision` with `approvalId`, `action: "approve" | "reject" | "requestRevision"`, and `decisionNote`
+- Discuss without deciding: `paperclipAddApprovalComment` (`approvalId`, `body`)
 
 Present approvals as:
 ```
@@ -365,42 +243,12 @@ For batch approval: list all pending, let the user approve all or review individ
 
 ## Task Management
 
-```bash
-# List open tasks
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues?status=todo,in_progress,blocked"
-
-# Get task detail
-curl -sS "$PAPERCLIP_API_URL/api/issues/{issueId}"
-
-# Get task comments
-curl -sS "$PAPERCLIP_API_URL/api/issues/{issueId}/comments"
-
-# Create a task
-curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "title": "Task title",
-    "description": "What needs to be done",
-    "status": "todo",
-    "priority": "medium",
-    "assigneeAgentId": "{agent-id}",
-    "projectId": "{project-id}",
-    "parentId": "{parent-issue-id}"
-  }'
-
-# Update a task
-curl -sS -X PATCH "$PAPERCLIP_API_URL/api/issues/{issueId}" \
-  -H "Content-Type: application/json" \
-  -d '{"status": "done", "comment": "Completed"}'
-
-# Add a comment
-curl -sS -X POST "$PAPERCLIP_API_URL/api/issues/{issueId}/comments" \
-  -H "Content-Type: application/json" \
-  -d '{"body": "Comment text in markdown"}'
-
-# Search issues
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues?q=search+term"
-```
+- List open tasks: `paperclipListIssues` (`status: "todo,in_progress,blocked"`)
+- Search: `paperclipListIssues` (`q: "search term"`)
+- Detail: `paperclipGetIssue` (`issueId`)
+- Comments: `paperclipListComments` (`issueId`) / `paperclipAddComment` (`issueId`, `body`)
+- Create: `paperclipCreateIssue` (`title`, `description`, `status: "todo"`, `priority: "medium"`, `assigneeAgentId`, `projectId`, `parentId`)
+- Update: `paperclipUpdateIssue` (`issueId`, `status: "done"`, `comment: "Completed"`)
 
 Present tasks as:
 ```
@@ -412,16 +260,9 @@ Present tasks as:
 
 ## Agent Monitoring
 
-```bash
-# List all agents
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agents"
-
-# Get agent detail
-curl -sS "$PAPERCLIP_API_URL/api/agents/{id}"
-
-# Get agent config revisions (change history)
-curl -sS "$PAPERCLIP_API_URL/api/agents/{id}/config-revisions"
-```
+- Team list: `paperclipListAgents`
+- Detail: `paperclipGetAgent` (`agentId`)
+- Change history: `paperclipListAgentConfigRevisions` (`extended`, `id`)
 
 Present agents as:
 ```
@@ -438,19 +279,11 @@ Team Overview
 
 ## Cost Monitoring
 
-```bash
-# Overall summary
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/costs/summary"
-
-# Breakdown by agent
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/costs/by-agent"
+- Summary: `paperclipGetCostSummary` (`extended`)
+- By agent: `paperclipGetCostByAgent` (`extended`)
+- By project: `paperclipGetCostByProject` (`extended`)
 
-# Breakdown by project
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/costs/by-project"
-
-# Optional date range
-curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/costs/summary?from=2026-03-01&to=2026-03-31"
-```
+For a date range, the cost tools take no window arguments — use `paperclipApiRequest` (`method: "GET"`, `path: "/companies/{companyId}/costs/summary?from=2026-03-01&to=2026-03-31"`).
 
 Present costs as:
 ```
@@ -466,16 +299,9 @@ By Agent:
 
 ## Work Products
 
-```bash
-# List work products for an issue
-curl -sS "$PAPERCLIP_API_URL/api/issues/{issueId}/work-products"
-
-# View a document
-curl -sS "$PAPERCLIP_API_URL/api/issues/{issueId}/documents/{key}"
-
-# View document revisions
-curl -sS "$PAPERCLIP_API_URL/api/issues/{issueId}/documents/{key}/revisions"
-```
+- List: `paperclipListIssueWorkProducts` (`id`)
+- View a document: `paperclipGetDocument` (`issueId`, `key`)
+- Revisions: `paperclipListDocumentRevisions` (`issueId`, `key`)
 
 Present work products with status and links:
 ```
@@ -492,27 +318,13 @@ Work Products — PAP-12
 
 Three ways the user can edit system prompts:
 
-**In chat:** User describes changes, you update via API:
-```bash
-# Always re-fetch before modifying
-curl -sS "$PAPERCLIP_API_URL/api/agents/{id}"
-
-# Then update
-curl -sS -X PATCH "$PAPERCLIP_API_URL/api/agents/{id}" \
-  -H "Content-Type: application/json" \
-  -d '{"adapterConfig": { ... updated config ... }}'
-```
+**In chat:** user describes changes; re-read with `paperclipGetAgent` (`agentId`), then write with `paperclipUpdateAgent` (`extended`, `id`, `adapterConfig`).
 
 **Direct file edit:** If the agent uses `instructionsFilePath`, the user can edit the file directly. When they tell you they're done, re-read the file and confirm changes.
 
-**Web UI edit:** User edits at `{baseUrl}/{prefix}/agents/{agentUrlKey}`. When they say "sync up," re-fetch from the API.
+**Web UI edit:** User edits at `{baseUrl}/{prefix}/agents/{agentUrlKey}`. When they say "sync up," re-read with `paperclipGetAgent`.
 
-**Viewing change history:**
-```bash
-curl -sS "$PAPERCLIP_API_URL/api/agents/{id}/config-revisions"
-```
-
-Present as a changelog:
+**Viewing change history:** `paperclipListAgentConfigRevisions` (`extended`, `id`). Present as a changelog:
 ```
 Config History — @designer
 ──────────────────────────
@@ -541,28 +353,23 @@ Maintain a decision log for session continuity. Log major decisions — not ever
 - At the end of a session if notable decisions were made
 
 **How to log:**
-1. Update the API document:
-```bash
-# Fetch current log
-curl -sS "$PAPERCLIP_API_URL/api/issues/{boardIssueId}/documents/decision-log"
-
-# Update with new entries appended
-curl -sS -X PUT "$PAPERCLIP_API_URL/api/issues/{boardIssueId}/documents/decision-log" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "title": "Decision Log",
-    "format": "markdown",
-    "body": "... existing content ... \n\n## {date}\n- New decision\n",
-    "baseRevisionId": "{current revision id}"
-  }'
+1. Read the current log with `paperclipGetDocument` (`issueId: "{boardIssueId}"`, `key: "decision-log"`), then write the appended version with `paperclipUpsertIssueDocument`:
+```
+issueId: "{boardIssueId}"
+key: "decision-log"
+title: "Decision Log"
+format: "markdown"
+body: "... existing content ... \n\n## {date}\n- New decision\n"
+baseRevisionId: "{current revision id}"
 ```
+A revision conflict means someone else wrote first: re-read and merge, never overwrite blindly.
 2. Also update the local file at `./artifacts/decision-log.md`.
 
 ## Presentation Rules
 
 - Use markdown tables for lists (agents, tasks, costs)
 - Use bold for status values: **in_progress**, **blocked**, **completed**
-- Always include web UI links: `View: {PAPERCLIP_API_URL}/{prefix}/issues/{identifier}`
+- Always include web UI links: `View: {baseUrl}/{prefix}/issues/{identifier}`
 - For org charts: generate mermaid diagrams or ASCII art
 - Smart summaries: surface what needs attention first, then the rest
 - Task format: `PAP-123: Build landing page [in_progress] → @engineer`
@@ -579,41 +386,41 @@ All web UI links must include the company prefix:
 - Projects: `/{prefix}/projects/{project-url-key}`
 - Documents: `/{prefix}/issues/{identifier}#document-{key}`
 
-## Key Endpoints Reference
-
-| Action | Method | Endpoint |
-|--------|--------|----------|
-| List companies | GET | `/api/companies` |
-| Create company | POST | `/api/companies` |
-| Update company | PATCH | `/api/companies/:id` |
-| Get company | GET | `/api/companies/:id` |
-| Dashboard | GET | `/api/companies/:companyId/dashboard` |
-| List agents | GET | `/api/companies/:companyId/agents` |
-| Get agent | GET | `/api/agents/:id` |
-| Update agent | PATCH | `/api/agents/:id` |
-| Agent configs | GET | `/api/companies/:companyId/agent-configurations` |
-| Config revisions | GET | `/api/agents/:id/config-revisions` |
-| Hire agent | POST | `/api/companies/:companyId/agent-hires` |
-| Invoke heartbeat | POST | `/api/agents/:id/heartbeat/invoke` |
-| List issues | GET | `/api/companies/:companyId/issues` |
-| Create issue | POST | `/api/companies/:companyId/issues` |
-| Get issue | GET | `/api/issues/:id` |
-| Update issue | PATCH | `/api/issues/:id` |
-| Issue comments | GET | `/api/issues/:id/comments` |
-| Add comment | POST | `/api/issues/:id/comments` |
-| Issue documents | GET | `/api/issues/:id/documents` |
-| Get document | GET | `/api/issues/:id/documents/:key` |
-| Create/update doc | PUT | `/api/issues/:id/documents/:key` |
-| Work products | GET | `/api/issues/:id/work-products` |
-| List approvals | GET | `/api/companies/:companyId/approvals` |
-| Approve | POST | `/api/approvals/:id/approve` |
-| Reject | POST | `/api/approvals/:id/reject` |
-| Request revision | POST | `/api/approvals/:id/request-revision` |
-| Cost summary | GET | `/api/companies/:companyId/costs/summary` |
-| Costs by agent | GET | `/api/companies/:companyId/costs/by-agent` |
-| Costs by project | GET | `/api/companies/:companyId/costs/by-project` |
-| Adapter docs | GET | `/llms/agent-configuration.txt` |
-| Adapter detail | GET | `/llms/agent-configuration/:adapterType.txt` |
-| Agent icons | GET | `/llms/agent-icons.txt` |
-| Set instructions | PATCH | `/api/agents/:id/instructions-path` |
-| Search issues | GET | `/api/companies/:companyId/issues?q=term` |
+## Key Tools Reference
+
+| Action | Tool | Toolset |
+|--------|------|---------|
+| List companies | `paperclipApiRequest` `GET` `/companies` | core |
+| Create company | `paperclipApiRequest` `POST` `/companies` | core |
+| Update company | `paperclipUpdateResource` | extended |
+| Get company | `paperclipGetResource` | extended |
+| Dashboard | `paperclipDashboard` | core |
+| List agents | `paperclipListAgents` | core |
+| Get agent | `paperclipGetAgent` | core |
+| Update agent | `paperclipUpdateAgent` | extended |
+| Agent configs | `paperclipListAgentConfigurations` | extended |
+| Config revisions | `paperclipListAgentConfigRevisions` | extended |
+| Hire agent | `paperclipCreateAgentHire` | extended |
+| Invoke heartbeat | `paperclipInvokeAgentHeartbeat` | extended |
+| List / search issues | `paperclipListIssues` | core |
+| Create issue | `paperclipCreateIssue` | core |
+| Get issue | `paperclipGetIssue` | core |
+| Update issue | `paperclipUpdateIssue` | core |
+| Issue comments | `paperclipListComments` | core |
+| Add comment | `paperclipAddComment` | core |
+| Issue documents | `paperclipListDocuments` | core |
+| Get document | `paperclipGetDocument` | core |
+| Create/update document | `paperclipUpsertIssueDocument` | core |
+| Document revisions | `paperclipListDocumentRevisions` | core |
+| Work products | `paperclipListIssueWorkProducts` | core |
+| List approvals | `paperclipListApprovals` | core |
+| Approve / reject / request revision | `paperclipApprovalDecision` | core |
+| Comment on approval | `paperclipAddApprovalComment` | core |
+| Cost summary | `paperclipGetCostSummary` | extended |
+| Costs by agent | `paperclipGetCostByAgent` | extended |
+| Costs by project | `paperclipGetCostByProject` | extended |
+| Adapter docs | `paperclipApiRequest` `GET` `/llms/agent-configuration.txt` | core |
+| Adapter detail | `paperclipApiRequest` `GET` `/llms/agent-configuration/{adapterType}.txt` | core |
+| Agent icons | `paperclipApiRequest` `GET` `/llms/agent-icons.txt` | core |
+| Set instructions path | `paperclipUpdateAgentInstructionsPath` | extended |
+| Agent keys / credentials | `paperclipApiRequest` on `/agents/{id}/keys` | core |