papercliped 2.2.1 → 2.4.0

package/site/docs/hosting.md

@@ -0,0 +1,105 @@
+# Host your Paperclip
+
+Papercliped connects your AI app to **your** Paperclip over the internet, so your Paperclip needs a public `https://` address. This section takes you from nothing to a running Paperclip with a public address, connected to Papercliped, with one complete guide per hosting option.
+
+Already have Paperclip running at a public `https://` address? Skip to [Connect Papercliped](#connect-papercliped).
+
+## Pick where to run it
+
+| Option | Cost per month (Oct 2026, approx.) | Effort | Best for | Guide |
+| --- | --- | --- | --- | --- |
+| **Your own computer + a tunnel** | Free (plus a domain, if you want one) | Medium | Trying it out; a computer that's always on | [At home, with a tunnel](/docs/connect-your-paperclip) |
+| **A VPS with Docker** (Hetzner, DigitalOcean, Linode…) | about €5–12 | Medium | Best value for daily use, full control | [VPS with Docker](/docs/host-vps) |
+| **Railway** | about $10–25 (usage-based) | Easy | The fewest steps, no server to look after | [Railway](/docs/host-railway) |
+| **Render** | about $25+ (2 GB plan) plus disk | Easy | A dashboard you already know | [Render](/docs/host-render) |
+| **Fly.io** | about $11–22 plus volume | Medium | Command-line people, pick your region | [Fly.io](/docs/host-fly) |
+| **Coolify** on a VPS | your VPS (8 GB recommended) | Easy–medium | A point-and-click panel on your own server | [Coolify](/docs/host-coolify) |
+
+Prices change; check the provider's pricing page before you sign up.
+
+**Not recommended:** free tiers that **sleep** (Render free, Railway's free plan) or hosts with **no persistent disk** (DigitalOcean App Platform). Paperclip keeps its database, secrets key, uploads, agent workspaces and agent logins on disk, and a sleeping server stops your agents mid-task. Use a DigitalOcean *Droplet* with the [VPS guide](/docs/host-vps) instead.
+
+**Not sure?** Start at home with a tunnel to try everything for free. When you want it running all the time, move to a VPS (cheapest) or Railway (easiest).
+
+## What every option needs
+
+Every guide sets these up. If you're doing something we don't cover, this is the checklist.
+
+1. **Paperclip in authenticated, public mode.** Paperclip has two modes: `local_trusted` (no login, only on your own computer) and `authenticated` (people sign in). An internet-facing Paperclip must be `authenticated` with `public` exposure. Never put a `local_trusted` Paperclip behind a public address.
+2. **Its public address set explicitly.** Paperclip builds sign-in links and checks hostnames from it.
+3. **Two long random secrets.** One for sign-ins, one for signing tool-action approvals.
+4. **A persistent disk** at Paperclip's data folder (`/paperclip` in the Docker image, `~/.paperclip` otherwise).
+5. **At least 2 GB of memory, 4 GB if you run several agents.** Agents run as programs inside the same machine.
+6. **Always on.** A restart or redeploy stops any agent run in progress, so avoid hosts that sleep, and update when your agents are idle.
+7. **Nothing blocking `/api/*`.** No login wall, bot challenge or "under attack" mode in front of Paperclip's API, or Papercliped can't reach it.
+
+### The settings
+
+| Setting | Value | Why |
+| --- | --- | --- |
+| `PAPERCLIP_DEPLOYMENT_MODE` | `authenticated` | People sign in (the Docker image's default) |
+| `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `public` | Internet-facing. The Docker image defaults to `private`, which refuses unknown hostnames |
+| `PAPERCLIP_PUBLIC_URL` | `https://paperclip.example.com` | Your public address, exactly as people will type it |
+| `BETTER_AUTH_SECRET` | 64 random hex characters | Signs sign-in sessions. Required |
+| `PAPERCLIP_TOOL_ACTION_SIGNING_SECRET` | 64 random hex characters | Signs tool-action approvals |
+| `PORT` | `3100` | Paperclip's port (the image's default; some hosts need it set) |
+| `DATABASE_URL` | optional | Leave unset to use Paperclip's built-in Postgres on the disk, or point it at a managed Postgres |
+| `TRUST_PROXY` | optional | Tells Paperclip which proxy in front of it to believe about the visitor's address (`uniquelocal` behind Caddy in Docker). Leave unset if unsure |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | optional | Keys for the agents that use Claude Code or Codex. You can sign in inside the server instead (see each guide) |
+
+Make a secret with:
+
+```
+openssl rand -hex 32
+```
+
+No `openssl`? Any password manager can generate a 64-character random password; use letters and numbers only.
+
+### Your first account
+
+In public mode, Paperclip doesn't show a "claim this instance" button (anyone on the internet could press it). Instead you run one command on the server, which prints a **one-time invite link** for the first admin:
+
+```
+npx --yes paperclipai auth bootstrap-ceo --data-dir /paperclip --base-url https://paperclip.example.com
+```
+
+Each guide shows exactly where to run it. Open the link, create your account, and you're the admin. Once you have your account, you can close public sign-ups by setting `PAPERCLIP_AUTH_DISABLE_SIGN_UP=true` and restarting; invite teammates from inside Paperclip.
+
+### Your agents' keys
+
+The official Paperclip image already includes the Claude Code, Codex, OpenCode and Gemini command-line tools, plus git and the GitHub CLI. Your agents need one of:
+
+- **An API key** as a setting: `ANTHROPIC_API_KEY` for Claude Code agents, `OPENAI_API_KEY` for Codex agents.
+- **Your subscription login**, done once inside the server (for example `claude` or `codex`, then follow the sign-in). The login is saved on the persistent disk, so it survives restarts.
+
+## Check it works
+
+From any computer (your phone on mobile data is a good test):
+
+```
+curl https://paperclip.example.com/api/health
+```
+
+On Windows PowerShell use `curl.exe`. A healthy answer is JSON that includes:
+
+```
+"status":"ok", "deploymentMode":"authenticated", "deploymentExposure":"public", "bootstrapStatus":"ready"
+```
+
+`"bootstrapStatus":"bootstrap_pending"` means nobody has created the first account yet (see [Your first account](#your-first-account)).
+
+## Connect Papercliped
+
+1. Add the connector in your AI app. In Claude: **Settings → Connectors → Add custom connector**, address `{{MCP}}/mcp`. Other apps: [Any AI app](/docs/other-ai-apps), [ChatGPT](/docs/chatgpt).
+2. On the Papercliped page choose **Connect your Paperclip** and enter your public address (just `https://paperclip.example.com`, no path).
+3. Approve the request in your Paperclip (you'll be asked to sign in), pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**. Details: [Create your account](/docs/signup).
+4. Leave **Also install the Papercliped plugin** ticked to manage your connections from inside Paperclip ([Paperclip plugin](/docs/paperclip-plugin)).
+5. Send your first prompt: *"Catch me up on my Paperclip."* Then try more from the [prompt gallery](/docs/prompts).
+
+## Keep it safe
+
+- Use long random secrets and keep them out of chats, screenshots and Git.
+- Keep Paperclip up to date, and update when agents are idle.
+- Back up the data disk (each guide says how).
+- Expose only Paperclip, nothing else on the machine.
+- You can cut Papercliped's access at any time: disconnect apps in the [Paperclip plugin](/docs/paperclip-plugin), or revoke the key in Paperclip.

package/site/docs/limits-and-errors.md

@@ -21,6 +21,7 @@ Tool errors come back to your AI app with a message it can read. Over HTTP (Chat
 | --- | --- | --- | --- |
 | `400` | `invalid_input` | The request didn't match the tool's inputs | Usually the AI retries with fixed input |
 | `403` | `insufficient_scope` | The connection's level is too low for this tool | Switch the app to Full control in the [Paperclip plugin](/docs/paperclip-plugin) |
+| `403` | `policy_blocked` | Your settings don't allow this call: the access switch, an agent's setting, or the session's tool or agent list. The error carries a `policy` code (see [API only, Full or Agent only](/docs/access-modes)) | Change the setting in the [control room](/docs/control-room) if you want it allowed |
 | `403` | `read_only` | The bridge runs with `PAPERCLIP_READ_ONLY` | Ask the operator |
 | `401`, `403`, `404`, `409`… | `upstream_4xx` | Paperclip refused (e.g. your Paperclip key was revoked: reconnect) | Check the message |
 | `5xx` | `upstream_5xx` | Paperclip had an error | Try again later |

package/site/docs/manage-api.md

@@ -14,7 +14,14 @@ The token has no scopes: it can't call MCP, Actions or any Paperclip tool. It la
 | --- | --- |
 | `POST /plugin-link/sign-in` | Link: username + secret key → plugin token |
 | `GET /me` | Name, anonymity, connected Paperclip |
-| `GET /connections` | Connected apps with level and last use |
+| `GET /connections` | Connected apps with level and last use (also `GET /sessions`, which is the same list under the name the control room uses) |
+| `GET /sessions` | Sessions: each with `label`, `level`, `tools` (or `null` for all) and `agents` (or `null` for everyone) |
+| `POST /sessions/:id` `{ "label", "tools", "agents", "level" }` | Change one session. Leave a field out to keep it; `null` clears a limit. Takes effect on the next request |
+| `DELETE /sessions/:id` | Disconnect a session |
+| `GET /policy` | The access switch and per-agent settings: `{ "mode": "api" \| "full" \| "agent", "agents": { "<agent id>": "api" \| "full" \| "agent" \| "off" } }` |
+| `POST /policy` (or `PUT`) | Replace them with the same shape |
+| `GET /tools` | Every tool with its `access` and its `surface` (`read`, `agent` or `api`) |
+| `GET /activity?session=:id&limit=:n` | The newest tool calls (names and outcomes only), up to 200 |
 | `POST /connections/:id` `{ "level": "read" \| "control" }` | Change an app's level |
 | `DELETE /connections/:id` | Disconnect an app |
 | `POST /privacy` `{ "anonymous": true }` | Turn anonymity on or off |
@@ -26,6 +33,10 @@ The token has no scopes: it can't call MCP, Actions or any Paperclip tool. It la
 
 The last three need your secret key in the request.
 
+A session's `tools` must be known tool names and `agents` agent ids; an empty list is refused (use `null` for "all"). Per-agent settings equal to the default are dropped. See [API only, Full or Agent only](/docs/access-modes).
+
+The activity list holds, for each call: `at`, `tool`, `ok`, `blocked`, `status`, `error` (a coarse class such as `policy_blocked`), `ms`, `session` and `app`. It never holds what was sent to a tool or what came back.
+
 ## Errors
 `400` bad input, `401` wrong username or key when linking, or the token is unknown, expired or revoked, `403` wrong secret key for a sensitive action, `404` no such connection or link (also for other people's), `429` too many requests.
 

package/site/docs/paperclip-plugin.md

@@ -1,15 +1,17 @@
 # Paperclip plugin
 
-The Papercliped plugin is where you manage Papercliped, right inside Paperclip: a **Papercliped** entry in the sidebar and a page where you see every connected AI app, switch each between **Read only** and **Full control**, disconnect apps, turn anonymity on or off, and look after your account.
+The Papercliped plugin puts Papercliped inside Paperclip. It adds the [control room](/docs/control-room): a **Papercliped** entry in the sidebar that opens a page where you see every connected AI app, choose what each may do and which agents it applies to, set [API only, Full or Agent only](/docs/access-modes) for every agent or one at a time, read what was used and what was blocked, and look after your account. It also adds a **Papercliped** tab on every agent's page and a widget for the dashboard.
 
-It manages your Papercliped account only. It never reads or controls your Paperclip itself, and AI apps still connect through Papercliped as before.
+The plugin manages your Papercliped account and the limits on AI apps. It reads your agents' names, roles and status to list them, and never changes anything in Paperclip. AI apps still connect through Papercliped as before.
 
 ## Install (Paperclip admin)
 **Automatic (recommended).** When you connect your Paperclip from an AI app, the address step has a box, ticked by default: **Also install the Papercliped plugin in my Paperclip**. After you approve the sign-in, Papercliped asks your Paperclip to install it using Paperclip's own installer and your own approved key. It installs one fixed package, `papercliped-paperclip-plugin`, at the exact version that matches the service, and only when you are the Paperclip's instance admin. If you are not an admin, if it is already installed, or if your Paperclip can't install plugins, nothing happens and your connection works as usual. Untick the box to skip it.
 
 **By hand.** Install the npm package `papercliped-paperclip-plugin` from **Settings → Plugins** in Paperclip (instance admin only). You can remove it there at any time, whichever way it was installed.
 
-The plugin asks for these capabilities: store its own data, make outbound web requests (to Papercliped), and add a sidebar entry and a page.
+The plugin asks for these capabilities: store its own data, make outbound web requests (to Papercliped), read agents (to list them), and add a sidebar entry, a page with its own menu, an agent tab and a dashboard widget.
+
+**Updating from an earlier version.** Paperclip won't update a plugin to a version that asks for new permissions without an admin's approval, so go to **Settings → Plugins**, remove Papercliped, and install it again (or connect your Paperclip again with the install box ticked). You may need to link your account again; your Papercliped account, sessions and settings are kept at Papercliped and are not affected.
 
 The bridge address defaults to `https://papercliped.co`. If you host your own bridge, change **Papercliped bridge URL** in the plugin's settings. It must be `https`.
 
@@ -22,13 +24,22 @@ Papercliped checks the key once and hands the plugin a link token. The key itsel
 Lost your secret key? Connect from your AI app again and choose **Connect your Paperclip**: you keep your account and get a new key.
 
 ## What you can do
-- **Connected apps:** see each app's level and when it was last used, switch it between Read only and Full control (it applies on the app's next request), or disconnect it.
-- **Privacy:** appear anonymously in the service's logs, or switch back.
-- **Linked Paperclips:** see every Paperclip linked to your account, unlink this one, or remove an old one.
-- **Account** (asks for your secret key again):
-  - **Make a new secret key.** Shown once. The old key stops working and other linked Paperclips have to link again; this one stays linked.
-  - **Disconnect my Paperclip.** Papercliped forgets your Paperclip key and asks your Paperclip to revoke it. Every app stops working and the plugin unlinks. Your account stays.
-  - **Delete my account.** Removes your username, stored key and every connection. Type your username to confirm.
+The [control room](/docs/control-room) has six sections:
+
+- **Overview:** the access switch (API only, Full, Agent only), your numbers, and what needs a look.
+- **Sessions:** every connected app. Name it, set its level, choose its tools and which agents it applies to, see its recent calls, or disconnect it. It applies on the app's next request.
+- **Agents:** what Papercliped may do with each agent, including turning one off.
+- **Tools:** every tool, by what it does and what your settings allow.
+- **Activity:** recent calls, including the ones that were blocked.
+- **Settings:**
+  - **Privacy:** appear anonymously in the service's logs, or switch back.
+  - **Linked Paperclips:** see every Paperclip linked to your account, unlink this one, or remove an old one.
+  - **Account** (asks for your secret key again):
+    - **Make a new secret key.** Shown once. The old key stops working and other linked Paperclips have to link again; this one stays linked.
+    - **Disconnect my Paperclip.** Papercliped forgets your Paperclip key and asks your Paperclip to revoke it. Every app stops working and the plugin unlinks. Your account stays.
+    - **Delete my account.** Removes your username, stored key and every connection. Type your username to confirm.
+
+Outside the control room: the **Papercliped tab** on an agent's page sets what AI apps may do with that one agent, and the **dashboard widget** shows the access switch in small.
 
 ## Good to know
 - The plugin runs as trusted code inside Paperclip, so install it only from the official package. The automatic install is limited to that one package and to the version that matches the service, and it is always your choice on the connect screen.

package/site/docs/permissions.md

@@ -7,6 +7,14 @@ You decide how much the AI may do each time you connect. There are two levels.
 | **Read only** (default) | View agents, tasks, goals, costs and reports. Cannot change anything. |
 | **Full control** | Every tool: everything above, plus pause, resume, wake or terminate agents, create and update issues and goals, comment, decide approvals, change budgets and send any API request. Run your Paperclip from anywhere, without opening the dashboard. |
 
+## Beyond the two levels
+The level is chosen when an app connects. After that, the [control room](/docs/control-room) gives you finer control, without reconnecting anything:
+
+- **An access switch** for every agent: [API only, Full or Agent only](/docs/access-modes), and any agent can be set differently or turned off.
+- **Per-session limits:** name a session, choose exactly which tools it may use, and choose whether it applies to everyone or only selected agents.
+
+These only ever narrow what a level allows; they never grant more than the level.
+
 ## Good to know
 - Papercliped enforces these levels itself on every call, and refuses anything outside the level you chose.
 - Your Paperclip key has the access your Paperclip account has. The levels limit what the **AI app** can do through Papercliped; they do not shrink the key itself. That is why the key is stored encrypted and why you can revoke it at any time.

package/site/docs/prompts.md

@@ -0,0 +1,349 @@
+# Prompt gallery
+
+Papercliped lets you run your Paperclip by talking to your AI app, so you don't have to click through the dashboard to make a task, wake an agent or answer an approval. Copy a prompt, replace the parts in [brackets], and send it. Your AI app picks the right tools.
+
+Each prompt says the level it needs. **Read only** prompts only look; **Full control** prompts change something, and your AI app asks before anything that can't be undone. Browse and copy them on [papercliped.co/prompts]({{URL}}/prompts).
+
+## Tips
+
+- **Use names, not ids.** Say "the Web Engineer" or "the onboarding issue"; your AI app looks up the ids.
+- **More than one company?** Start with "Use [company name] for this chat."
+- **Ask for a preview.** Add "show me before you create anything" to any prompt that makes several changes.
+- **Chain steps.** "Wake X, wait until they finish, then summarise" works in one message.
+- **Not sure what's possible?** Ask "What can you do with my Paperclip?"
+
+## Start your day
+
+Get the whole picture in one message instead of clicking through the dashboard.
+
+### Morning catch-up
+
+> Catch me up on my Paperclip: what each agent is doing right now, anything blocked or in error, and approvals waiting on me.
+
+Read only · `paperclip_sync_snapshot`, `paperclip_list_approvals`
+
+### What changed overnight
+
+> What happened in my Paperclip since yesterday evening? Group it by agent and skip the routine heartbeats.
+
+Read only · `paperclip_report_activity`
+
+### Needs my attention
+
+> Is anything in my Paperclip waiting on me? Approvals, agents in error, blocked issues, budgets close to the limit.
+
+Read only · `paperclip_report_status`
+
+### Which company
+
+> Which Paperclip companies can you see? Use [company name] for the rest of this chat.
+
+Read only · `paperclip_list_companies`
+
+## Hand out work
+
+Create, assign and move issues by describing them. Assigning an issue to an agent with status todo is how you give it work.
+
+### Give an agent a task
+
+> Create an issue "[title]" for [agent name]: [what you want done, and what done looks like]. Set it to todo so they pick it up.
+
+Full control · `paperclip_list_agents`, `paperclip_create_issue`
+
+### Turn notes into issues
+
+> Here are my notes from today's call. Turn each action item into an issue in [project name], assign each to the agent whose role fits best, and show me the list before creating them.
+> 
+> [paste your notes]
+
+Full control · `paperclip_list_projects`, `paperclip_list_agents`, `paperclip_create_issue`
+
+### What's open
+
+> List the open issues in [project name] by priority, with who's on each one.
+
+Read only · `paperclip_list_projects`, `paperclip_list_issues`
+
+### Explain an issue
+
+> Explain issue [issue number or title]: what it's for, which goal it serves, the plan, and where it's stuck.
+
+Read only · `paperclip_get_issue`
+
+### Reassign
+
+> Move every todo issue from [agent A] to [agent B] and add a comment on each saying why: [reason].
+
+Full control · `paperclip_list_issues`, `paperclip_update_issue`
+
+### Unblock with a comment
+
+> On [issue], add a comment for the assignee: [your answer or decision]. Then set it back to in progress.
+
+Full control · `paperclip_comment_issue`, `paperclip_update_issue`
+
+### Bump priority
+
+> Make [issue] urgent and tell the assignee in a comment that it now comes before everything else.
+
+Full control · `paperclip_update_issue`
+
+### Close what's done
+
+> Find issues in review that the assignee says are finished, show them to me, and mark the ones I confirm as done.
+
+Full control · `paperclip_list_issues`, `paperclip_update_issue`
+
+## Run your agents
+
+Check on agents, wake them, pause them and get them out of error.
+
+### Who's doing what
+
+> List my agents with their status, role, and what each one is working on.
+
+Read only · `paperclip_list_agents`
+
+### Org chart
+
+> Show me my org chart: who reports to whom.
+
+Read only · `paperclip_org_chart`
+
+### Wake an agent
+
+> Wake [agent name] so they start on their queue now.
+
+Full control · `paperclip_wake_agent`
+
+### Pause for now
+
+> Pause [agent name] until I say otherwise.
+
+Full control · `paperclip_pause_agent`
+
+### Resume everyone
+
+> Resume every paused agent except [agent name].
+
+Full control · `paperclip_list_agents`, `paperclip_resume_agent`
+
+### Fix agents in error
+
+> Which agents are in error, and what was the last thing each was doing? Clear the error on the ones I pick and wake them again.
+
+Full control · `paperclip_list_agents`, `paperclip_get_agent`, `paperclip_clear_agent_error`, `paperclip_wake_agent`
+
+### One agent, in detail
+
+> Tell me everything about [agent name]: status, manager, budget, spend this month and current task.
+
+Read only · `paperclip_get_agent`
+
+### Let an agent go
+
+> I want to retire [agent name]. Reassign their open issues to [other agent], then terminate them. Ask me before the terminate step.
+
+Full control · `paperclip_list_issues`, `paperclip_update_issue`, `paperclip_terminate_agent`
+
+Terminating can't be undone. Your AI app asks first; pausing is the reversible option.
+
+## Follow along
+
+Start something and let your AI app watch it to the end.
+
+### Wake and wait
+
+> Wake [agent name], wait until they finish their run, then tell me what they did.
+
+Full control · `paperclip_wake_agent`, `paperclip_wait_for_agent`, `paperclip_report_activity`
+
+### Hand off and watch
+
+> Give [agent name] this task: [task]. Wake them, follow the run to the end, and summarise the result and any comments they left.
+
+Full control · `paperclip_create_issue`, `paperclip_wake_agent`, `paperclip_wait_for_agent`, `paperclip_get_issue`
+
+### Keep me posted
+
+> Check what changed in my Paperclip since you last looked and tell me only what's new.
+
+Read only · `paperclip_sync_changes`
+
+## Approvals
+
+Hires, plans and budget overrides waiting on you.
+
+### What's waiting
+
+> List pending approvals with who asked, what for, and what it would cost.
+
+Read only · `paperclip_list_approvals`
+
+### Approve a hire
+
+> Approve [agent]'s request to hire a [role].
+
+Full control · `paperclip_list_approvals`, `paperclip_decide_approval`
+
+### Ask for changes
+
+> Send the [plan or request] back for revision with this note: [what to change].
+
+Full control · `paperclip_list_approvals`, `paperclip_decide_approval`
+
+### Review them one by one
+
+> Go through each pending approval with me one at a time: summarise it, give me your recommendation, and wait for my decision before moving on.
+
+Full control · `paperclip_list_approvals`, `paperclip_decide_approval`
+
+## Goals and projects
+
+Keep the plan up to date in plain words.
+
+### Goal tree
+
+> Show my goals as a tree, with status, and which ones have no open issues behind them.
+
+Read only · `paperclip_list_goals`, `paperclip_list_issues`
+
+### New goal
+
+> Create a company goal: "[goal]". Then suggest three team goals under it and create the ones I approve.
+
+Full control · `paperclip_list_goals`, `paperclip_create_goal`
+
+### Mark achieved
+
+> Mark the goal "[goal]" as achieved.
+
+Full control · `paperclip_list_goals`, `paperclip_update_goal`
+
+### Projects overview
+
+> List my projects and, for each, how many issues are open, in progress and done.
+
+Read only · `paperclip_list_projects`, `paperclip_list_issues`
+
+## Budgets and costs
+
+See where the money goes and set limits. Agents pause themselves at 100% of their budget.
+
+### Spend this month
+
+> How much have my agents spent this month, against budget, per agent and per project?
+
+Read only · `paperclip_report_costs`
+
+### Close to the limit
+
+> Which agents are above 80% of their monthly budget?
+
+Read only · `paperclip_list_agents`
+
+### Set a budget
+
+> Set [agent name]'s monthly budget to $[amount].
+
+Full control · `paperclip_set_agent_budget`
+
+### Pause the overspender
+
+> Pause any agent that's over budget and tell me what each one was working on.
+
+Full control · `paperclip_list_agents`, `paperclip_pause_agent`
+
+### Value for money
+
+> Which agents give me the most finished work per dollar, and which the least?
+
+Read only · `paperclip_report_agent_performance`
+
+## Reports
+
+Ready-made reports you can paste into a doc, email or chat.
+
+### Executive summary
+
+> Write a short executive summary of my Paperclip: what got done, what's stuck, spend, and decisions I need to make.
+
+Read only · `paperclip_report_status`
+
+### Weekly review
+
+> Weekly report: issues closed and blocked per agent, spend against last week, and the three things I should look at.
+
+Read only · `paperclip_report_agent_performance`, `paperclip_report_costs`, `paperclip_report_activity`
+
+### Activity log
+
+> Give me today's activity as a timeline.
+
+Read only · `paperclip_report_activity`
+
+### Team table
+
+> Make a table of every agent: role, status, issues done this month, spend, and cost per finished issue.
+
+Read only · `paperclip_report_agent_performance`
+
+## Recipes
+
+Longer prompts that chain several steps. Copy, adjust the names, send.
+
+### Daily stand-up
+
+> Run a stand-up for my Paperclip: for each agent, what they finished since yesterday, what they're on now, and what's blocking them. Then list approvals waiting on me and anything over budget. End with the three decisions I should make today.
+
+Read only · `paperclip_sync_snapshot`, `paperclip_report_activity`, `paperclip_list_approvals`, `paperclip_report_costs`
+
+### Kick off a project
+
+> I'm starting "[project]". Create a goal for it, break it into 5 to 8 issues, assign each to the best-fit agent as todo, and wake the agents who got work. Show me the plan before you create anything.
+
+Full control · `paperclip_list_agents`, `paperclip_create_goal`, `paperclip_create_issue`, `paperclip_wake_agent`
+
+### End-of-week tidy
+
+> Tidy up my Paperclip for the week: close issues that are finished, comment on anything stuck for more than 3 days asking the assignee what they need, and give me a cost summary.
+
+Full control · `paperclip_list_issues`, `paperclip_update_issue`, `paperclip_comment_issue`, `paperclip_report_costs`
+
+### Cost clamp
+
+> Keep this month under $[amount]: show the current spend and forecast, suggest new budgets per agent, and set the ones I approve.
+
+Full control · `paperclip_report_costs`, `paperclip_list_agents`, `paperclip_set_agent_budget`
+
+### Incident mode
+
+> Something's wrong. Pause every agent except [agent name], list what each paused agent was doing, and tell me what changed in the last hour.
+
+Full control · `paperclip_list_agents`, `paperclip_pause_agent`, `paperclip_report_activity`
+
+## Anything else
+
+For Paperclip features without a dedicated tool, and for checking the connection.
+
+### Use any Paperclip feature
+
+> List the routines in my company. (There's no dedicated tool, so use the Paperclip API.)
+
+Full control · `paperclip_api_request`
+
+Reading needs Read only. Anything that changes data needs Full control and your confirmation.
+
+### Is Papercliped up?
+
+> Is the Papercliped service working right now?
+
+Read only · `papercliped_service_status`
+
+### What can you do?
+
+> What can you do with my Paperclip at my current access level? Give me five examples.
+
+Read only · `paperclip_list_companies`
+
+Got a prompt that works well? Share it in [the community]({{URL}}/community) or open a pull request that adds it to `web/src/content/prompts.json`. Every tool is listed in the [tool reference](/docs/tools).

package/site/docs/public-api.md

@@ -47,7 +47,7 @@ curl "{{URL}}/api/public/v1/stats?window=24h"
 
 **Sign-in failure reasons** (a fixed list): `bad_credentials`, `rate_limited`, `denied`, `expired`, `unreachable`, `invalid_instance`, `too_many_attempts`, `other`.
 
-**Error classes** (a fixed list): `invalid_input`, `insufficient_scope`, `read_only`, `upstream_4xx`, `upstream_5xx`, `upstream_unreachable`, `rate_limited`, `unauthorized`, `internal`, `other`. Anything the service records outside these lists is counted as `other`, never shown as text.
+**Error classes** (a fixed list): `invalid_input`, `insufficient_scope`, `read_only`, `policy_blocked`, `upstream_4xx`, `upstream_5xx`, `upstream_unreachable`, `rate_limited`, `unauthorized`, `internal`, `other`. Anything the service records outside these lists is counted as `other`, never shown as text.
 
 ## Series
 Each bucket has `t` (start time), `requests`, `errors`, `faults`, `p95Ms`, `authCompleted`, `authFailed` and `newUsers`. Every bucket in the window is present, with zeros when nothing happened.

package/site/docs/signup.md

@@ -3,7 +3,7 @@
 Creating a Papercliped account takes about a minute. You do it the first time you connect Claude (or ChatGPT).
 
 ## Before you start
-- Your Paperclip must be reachable at a public `https://` address, for example `https://workforce.example.com`. Need one? Follow [Set up your Paperclip](/docs/connect-your-paperclip), with or without your own domain.
+- Your Paperclip must be reachable at a public `https://` address, for example `https://workforce.example.com`. Need one? Follow [Host your Paperclip](/docs/hosting): at home with a tunnel, on a VPS, or on Railway, Render, Fly.io or Coolify.
 - You must be able to sign in to that Paperclip, because you approve the connection there.
 
 ## Steps