papercliped 2.2.1 → 2.4.0

package/dist/site/site.js

@@ -9,10 +9,19 @@ const NAV = [
     { slug: "getting-started", title: "Getting started" },
     { slug: "what-is-papercliped", title: "What is Papercliped?" },
     { slug: "signup", title: "Create your account" },
-    { slug: "connect-your-paperclip", title: "Set up your Paperclip" },
+    { slug: "hosting", title: "Host your Paperclip" },
+    { slug: "connect-your-paperclip", title: "At home, with a tunnel" },
+    { slug: "host-vps", title: "VPS with Docker" },
+    { slug: "host-railway", title: "Railway" },
+    { slug: "host-render", title: "Render" },
+    { slug: "host-fly", title: "Fly.io" },
+    { slug: "host-coolify", title: "Coolify" },
     { slug: "other-ai-apps", title: "Any AI app (MCP)" },
     { slug: "chatgpt", title: "ChatGPT setup" },
+    { slug: "prompts", title: "Prompt gallery" },
     { slug: "permissions", title: "Permissions" },
+    { slug: "control-room", title: "The control room" },
+    { slug: "access-modes", title: "API only, Full or Agent only" },
     { slug: "manage", title: "Manage connections" },
     { slug: "paperclip-plugin", title: "Paperclip plugin" },
     { slug: "anonymous-mode", title: "Anonymous mode" },

package/docs/CONTROL-ROOM.md

@@ -0,0 +1,79 @@
+# The control room: audit, design and decisions
+
+How v2.4.0 turns the Papercliped plugin into a control room inside Paperclip. Written alongside the build. The user-facing guides are `site/docs/control-room.md` and `site/docs/access-modes.md`; this page is for people changing the code.
+
+Labels: **Observed** = read from Paperclip's installed source (2026.1001.0) or a live instance. **Decided** = a choice made for this release.
+
+## 1. What was asked
+- See every session (one connected AI app) and manage it from inside Paperclip: which tools it may use, and whether it applies to everyone or to selected agents.
+- Follow Paperclip's native design, as a control room.
+- Papercliped integrated into the app like agents: finely manageable access, **full control for every agent and the API by default**, and a main-page switch between **API only | Full | Agent only**.
+- Audit Paperclip to see what needs to be integrated with what, and document as we build.
+
+## 2. Audit of Paperclip (Observed)
+
+### What a plugin can be
+Paperclip 2026.1001.0 has a plugin system (alpha). The UI slot types are `page`, `detailTab`, `taskDetailView`, `dashboardWidget`, `sidebar`, `routeSidebar`, `sidebarPanel`, `projectSidebarItem`, `globalToolbarButton`, `appShellOverlay`, `toolbarButton`, `contextMenuItem`, `commentAnnotation`, `commentContextMenuItem`, `settingsPage`, `companySettingsPage`. Each needs a capability: `page` ← `ui.page.register`, `sidebar`/`routeSidebar` ← `ui.sidebar.register`, `detailTab` ← `ui.detailTab.register`, `dashboardWidget` ← `ui.dashboardWidget.register`.
+
+- `routeSidebar` replaces the company menu while a route is open. This is how Paperclip's own agent page gets its grouped left menu, so it is the native way to build a control room.
+- `detailTab` with `entityTypes: ["agent"]` adds a tab to every agent's page.
+- A plugin worker reads agents with `ctx.agents.list` (capability `agents.read`). The host supplies the verified company with every action call (`context.companyId`); the page's own parameters are never trusted for it.
+- A `routePath` is allowed only on `page`, `routeSidebar` and `companySettingsPage` slots. The 2.2.0 manifest put one on a `sidebar` slot, which is why Paperclip refused to install it (a bare `400`). The plugin's tests now run Paperclip's own `pluginManifestV1Schema`.
+- Paperclip refuses to **upgrade** a plugin whose new version asks for capabilities the old one didn't have (an admin must approve). Moving from 2.2.x to 2.4 therefore means remove and reinstall. Documented in `site/docs/paperclip-plugin.md`.
+- Install is `POST /api/plugins/install` (instance admin only), which runs `npm install <pkg>@<version> --ignore-scripts` into `~/.paperclip/plugins`, then validates the manifest (schema, API version, capabilities, route conflicts, minimum host version) and registers it.
+
+### What Paperclip already has that overlaps
+- **Tool access** (`/companies/:id/tools/*`, `/tool-connections`, `/tool-profiles`, grants and delegations) and a **tool gateway** (`/tool-gateway/*`, MCP gateways). These govern the tools *agents* use *outward* (GitHub, Google, remote MCP connectors). Papercliped is the opposite direction: AI apps controlling Paperclip *inward*. **Decided:** do not reuse or mirror them; they model a different thing, and a plugin can't extend them. The per-agent **Tools** tab in Paperclip's own UI (`AgentToolsTab`) is the closest native pattern, and is why Papercliped's per-agent control lives on the agent's own page too.
+- **Agent permissions** (`PATCH /agents/:id/permissions`), **authorization grants and policies** (capabilities `authorization.*`). These are Paperclip-side permissions for principals inside Paperclip. **Decided:** not used. Papercliped's limits are enforced by the bridge, which every AI call passes through, so they hold for Claude, ChatGPT and any MCP client regardless of Paperclip's version, and need no extra capability.
+- **Agent sessions** (`agent.sessions.*`, `task-sessions`, `runtime-state`). These are an agent's own runtime conversations. They are not Papercliped sessions. In the control room a **session** always means a connected AI app (an OAuth grant).
+
+### Native design (Observed from `ui/` and a live page)
+shadcn-style components on Tailwind with CSS variables (`--background`, `--card`, `--border`, `--primary`, `--sidebar-accent`, …), light and dark via a `.dark` class, Inter, Lucide icons at 16px. The plugin uses Paperclip's **own compiled classes** (every class used is checked against the live stylesheet, see `plugin/src/ui/look.ts`), the SDK's `StatusBadge`, `MetricCard`, `DataTable` and toast, and Lucide icons. On touch screens Paperclip forces buttons to at least 44px, so controls size themselves from their buttons instead of a fixed height.
+
+## 3. Design
+
+### Sessions
+A **session** is one OAuth grant (one connected AI app). `Grant.policy` (new, nullable JSON) holds `{ label, tools, agents }`; `null` for `tools` or `agents` means "all". The access **level** stays in `grant.scopes`.
+
+### The access switch
+`Account.policy` (new, nullable JSON) holds `{ mode: "api"|"full"|"agent", agents: { [agentId]: "api"|"full"|"agent"|"off" } }`. No row means Full for every agent, so nothing changes for anyone until they choose.
+
+### Tool surfaces (`src/access/policy.ts`)
+Every tool is exactly one of **read** (any read, and `GET` through the raw API tool), **agent** (create/update/comment on issues, wake agent: it hands work to agents), or **api** (every other change: pause, resume, clear error, budget, terminate, goals, approvals, non-`GET` raw API). A mode allows `read` plus: `api` → api, `agent` → agent, `full` → both. A test ties `site/docs/access-modes.md` and the generated tool reference to this classification.
+
+### Enforcement order (`evaluate`, called from `executeTool`)
+1. Session tool list. 2. For each agent the call is about (named, assigned or owner, or the assignee of the named issue): Off → refuse; the agent's (or default) mode must allow the surface; the session's agent list must include it. 3. With no agent named, the default mode must allow the surface. 4. A session limited to selected agents may only use tools that name an agent (plus companies, agents list and service status), because every other view looks across all agents. The access level (scopes) is checked before all of this, unchanged.
+
+Refusals are `403` with `{ message, policy: <code> }`, audited as `policy_blocked`, and never reach Paperclip. The message names the setting and where to change it.
+
+### Hiding agents (`src/access/guard.ts`)
+For agents set to **Off**, the Paperclip client handed to every tool is wrapped so each response has those agents' records removed (list items, rows keyed by agent id, anything referencing them), **before** the tool builds its answer. A report built from that client cannot name a hidden agent because it never received one. Server-side totals are left as the server computed them (documented). For a session limited to selected agents, `paperclip_list_agents` is narrowed to those agents.
+
+An issue's agent is not named in the call, so for sessions with limits or accounts with per-agent settings the bridge looks the issue up once (`GET /issues/:id`) before deciding; if that fails, a limited session is refused and anyone else lets the tool report the real error.
+
+### What the AI is shown
+`visibleTools(scopes, policy)` drops tools that can never run for the session (not in its tool list; no mode allows the surface; tools that look across all agents for a limited session). Tools that *might* run for some agent stay.
+
+### Management API (`src/manage/routes.ts`)
+`GET /sessions`, `POST|DELETE /sessions/:id`, `GET|POST|PUT /policy`, `GET /tools`, `GET /activity`. Input is parsed strictly (`parseAccountPolicy`, `parseSessionPolicy`): unknown tool names, empty lists, bad ids and over-long lists are refused; damaged stored JSON falls back to the safe default instead of failing a call. Activity is read from the audit table by grant id and never contains arguments or results.
+
+### Plugin (`plugin/`)
+New worker actions: `sessions`, `setSession`, `policy`, `setPolicy`, `tools`, `activity`, `agents`. Five slots: `sidebar` (entry), `page` (the control room), `routeSidebar` (its menu), `detailTab` on agents, `dashboardWidget`. Navigation is `/papercliped?s=<section>&id=<thing>` so links, back and reload work. The access switch is a three-position vertical switch with a sliding knob (arrow keys, announced as a radio group, reduced-motion respected); the same control is reused compactly for agents.
+
+### Database
+`007_control_room.sql`: `accounts.policy jsonb`, `grants.policy jsonb`. No backfill. The panel views expose neither column. The generated `docs/supabase-schema.sql` is regenerated and a test fails if it is stale.
+
+## 4. How it was verified
+- **Rule engine**: unit tests for every mode, per-agent override, Off, session tool and agent lists, issue assignee, redaction, validation and damaged-row fallback (`test/policy.test.ts`).
+- **End to end through the real server** with a fake Paperclip: switching modes changes the next call, nothing blocked reaches Paperclip, Off agents vanish from lists and reports, limited sessions, another account is never affected, activity includes blocked calls and no arguments (`test/control-room.test.ts`).
+- **Postgres**: the whole suite (memory, Postgres, and the least-privilege role) ran against a real PostgreSQL 16, including the new store methods.
+- **Plugin**: handlers against a fake bridge, the SDK test harness (capabilities are enforced there), and the UI (`plugin/test`).
+- **Paperclip's own validators**: the built manifest passes `pluginManifestV1Schema` and the host's capability validator, run on the live instance's installed code.
+- **Visual**: every page, the agent tab and the widget were rendered with Paperclip's real stylesheet in light, dark and phone width.
+
+## 5. Known limits and next steps
+- Limits apply to calls through Papercliped. The Paperclip key Papercliped holds still has the account's access (see `docs/SECURITY.md`); a bridge compromise bypasses them.
+- Server-summed totals include Off agents.
+- Activity is capped at 200 rows per request and, on the hosted service, kept 30 days (`BRIDGE_AUDIT_RETENTION_DAYS`).
+- The plugin could not be installed into a live Paperclip with these slots before release; the manifest was validated against the live host's code instead. First live install after release should be checked: left menu replaces the company menu on `/papercliped`, the agent tab appears, the widget can be added.
+- Paperclip's plugin API is alpha; `routeSidebar` and `detailTab` behaviour may change.

package/docs/SECURITY.md

@@ -3,7 +3,7 @@
 Read this before running the bridge for people other than yourself.
 
 ## What you are holding
-For every connected user the bridge stores a **Paperclip board API key**. In Paperclip that key is bound to the *user*, not to a company, and carries **all** of that user's board power (verified in Paperclip's source: `board_api_keys` has no scope column, and the challenge's `requestedCompanyId` is only used to attribute activity-log entries, not to restrict the key). The bridge's two access levels (Read only and Full control) limit what *connected AI clients* may do through the bridge. They do **not** limit what the stored key can do if the bridge itself is compromised.
+For every connected user the bridge stores a **Paperclip board API key**. In Paperclip that key is bound to the *user*, not to a company, and carries **all** of that user's board power (verified in Paperclip's source: `board_api_keys` has no scope column, and the challenge's `requestedCompanyId` is only used to attribute activity-log entries, not to restrict the key). The bridge's limits (the two access levels, the API only / Full / Agent only switch, per-agent settings and per-session tool and agent lists, see `docs/CONTROL-ROOM.md`) limit what *connected AI clients* may do through the bridge. They do **not** limit what the stored key can do if the bridge itself is compromised.
 
 > **Headline risk:** a full compromise of the running bridge (code execution on the Render service *and* access to its environment) exposes every connected user's Paperclip with full board access, until those keys are revoked. Everything below reduces the likelihood or blast radius; none of it removes that risk. Until Paperclip offers scoped/short-lived keys, tell users plainly, encourage a dedicated Paperclip user for the connection, and keep the user base small enough to be comfortable with that.
 

package/docs/SITEMAP.md

@@ -29,6 +29,8 @@ One service, routed by host (`PUBLIC_HOSTS`, `src/web/`): `papercliped.co` the w
 | `/docs/manage` | Manage connections |
 | `/docs/paperclip-plugin` | Paperclip plugin |
 | `/docs/permissions` | Permissions |
+| `/docs/control-room` | The control room |
+| `/docs/access-modes` | API only, Full or Agent only |
 | `/docs/anonymous-mode` | Anonymous mode |
 | `/docs/public-api` | Public API and status |
 | `/docs/security` | Security |
@@ -54,7 +56,7 @@ One service, routed by host (`PUBLIC_HOSTS`, `src/web/`): `papercliped.co` the w
 | Path | Purpose |
 | --- | --- |
 | `GET /manage` | Old address: redirects to `/docs/paperclip-plugin` |
-| `/api/manage/*` | JSON API used by the Paperclip plugin (bearer token only, no cookies): `plugin-link/sign-in`, `me`, `connections`, `connections/:id`, `privacy`, `plugin-links`, `plugin-links/:id`, `secret/rotate`, `paperclip/disconnect`, `account/delete` (the last three need the secret key again) |
+| `/api/manage/*` | JSON API used by the Paperclip plugin (bearer token only, no cookies): `plugin-link/sign-in`, `me`, `connections`, `connections/:id`, `sessions`, `sessions/:id`, `policy`, `tools`, `activity`, `privacy`, `plugin-links`, `plugin-links/:id`, `secret/rotate`, `paperclip/disconnect`, `account/delete` (the last three need the secret key again) |
 | Domain section in the plugin **(planned v3)** | Pro members: address, tunnel status, token, port, release |
 
 ## 4. AI client endpoints

package/docs/supabase-schema.sql

@@ -274,6 +274,17 @@ update bridge.grants
    set scopes = array(select distinct s from unnest(array_replace(scopes, 'paperclip:admin', 'paperclip:control')) as s order by s desc)
  where 'paperclip:admin' = any(scopes);
 
+-- ───── 007_control_room.sql ─────
+-- Control room: who may do what through Papercliped.
+--   accounts.policy  the access switch (api | full | agent) and per-agent overrides, as JSON. Null = Full for every agent.
+--   grants.policy    one session's limits (a name, which tools, which agents), as JSON. Null = no limits beyond its access level.
+-- The app validates both on the way in and falls back to the safe default on anything it can't read, so old rows need no backfill.
+alter table bridge.accounts add column if not exists policy jsonb;
+alter table bridge.grants   add column if not exists policy jsonb;
+
+-- Audit rows now also record calls the policy refused (error_class = policy_blocked).
+comment on column bridge.audit_events.error_class is 'invalid_input | insufficient_scope | read_only | policy_blocked | upstream_4xx | upstream_5xx | upstream_unreachable | rate_limited | unauthorized | internal';
+
 -- ───── migration bookkeeping ─────
 create table if not exists bridge.schema_migrations (version text primary key, applied_at timestamptz not null default now());
 alter table bridge.schema_migrations enable row level security;
@@ -283,6 +294,6 @@ do $$ declare r text; begin
     if exists (select 1 from pg_roles where rolname = r) then execute format('revoke all on bridge.schema_migrations from %I', r); end if;
   end loop;
 end $$;
-insert into bridge.schema_migrations (version) values ('001_init.sql'), ('002_audit.sql'), ('003_accounts.sql'), ('004_privacy_panel.sql'), ('005_beta.sql'), ('006_two_levels.sql') on conflict (version) do nothing;
+insert into bridge.schema_migrations (version) values ('001_init.sql'), ('002_audit.sql'), ('003_accounts.sql'), ('004_privacy_panel.sql'), ('005_beta.sql'), ('006_two_levels.sql'), ('007_control_room.sql') on conflict (version) do nothing;
 
 commit;

package/migrations/007_control_room.sql

@@ -0,0 +1,9 @@
+-- Control room: who may do what through Papercliped.
+--   accounts.policy  the access switch (api | full | agent) and per-agent overrides, as JSON. Null = Full for every agent.
+--   grants.policy    one session's limits (a name, which tools, which agents), as JSON. Null = no limits beyond its access level.
+-- The app validates both on the way in and falls back to the safe default on anything it can't read, so old rows need no backfill.
+alter table bridge.accounts add column if not exists policy jsonb;
+alter table bridge.grants   add column if not exists policy jsonb;
+
+-- Audit rows now also record calls the policy refused (error_class = policy_blocked).
+comment on column bridge.audit_events.error_class is 'invalid_input | insufficient_scope | read_only | policy_blocked | upstream_4xx | upstream_5xx | upstream_unreachable | rate_limited | unauthorized | internal';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "Papercliped — connect Claude, ChatGPT and any MCP app to your Paperclip: control agents, sync, report. MCP server + hosted multi-tenant OAuth bridge + public stats API.",
   "license": "MIT",
   "type": "module",

package/site/docs/access-modes.md

@@ -0,0 +1,72 @@
+# API only, Full or Agent only
+
+One switch decides how AI apps may work with your Paperclip: **API only**, **Full** or **Agent only**. **Full** is the default for every agent. You set it in the [control room](/docs/control-room), and you can set any single agent differently (or turn it **Off**).
+
+## What each position means
+| Mode | AI apps can | AI apps can't |
+| --- | --- | --- |
+| **API only** | Look at everything, and control Paperclip directly: pause and resume agents, set budgets, decide approvals, manage goals, send API requests | Hand work to agents |
+| **Full** (default) | Everything: look, control directly, and work through agents | Nothing is held back by the switch |
+| **Agent only** | Look at everything, and work through agents: create, assign and comment on issues, wake an agent | Control Paperclip directly |
+
+The AI app's access **level** (Read only or Full control) still applies on top. Read only can never change anything, whatever the switch says.
+
+## The three kinds of tool
+Every tool is exactly one of these:
+
+| Kind | Tools | Allowed in |
+| --- | --- | --- |
+| **Look** | Everything that only reads: lists, details, reports, sync, waiting for an agent, and raw `GET` requests | Every mode |
+| **Work through agents** | Create issue, Update issue, Comment on issue, Wake agent now | Full, Agent only |
+| **Direct control** | Pause agent, Resume agent, Clear agent error, Set agent budget, Terminate agent, Create goal, Update goal, Decide approval, and raw API requests that aren't `GET` | Full, API only |
+
+The full list, with what each tool does, is the [tool reference](/docs/tools).
+
+## One agent at a time
+Each agent can follow the default or be set apart:
+
+- **API only**, **Full** or **Agent only** for just that agent. For example, keep the default **Full** but set one agent to **Agent only**: AI apps can give it work but can't pause or terminate it.
+- **Off**: Papercliped can't see or touch that agent. It disappears from lists and reports, anything assigned to it is out of reach, and calls that name it are refused.
+
+A call is judged by the agent it is about: the agent it names, the agent it assigns work to, or the agent an issue is assigned to. A call that isn't about one agent (for example "list goals") follows the default.
+
+## One session at a time
+Each connected app (a **session**) can also be limited, whatever the switch says:
+
+- **Tools:** only the tools you tick.
+- **Agents:** only the agents you choose. The session then works with those agents only, and can't use views across every agent (reports, the org chart, goals, approvals).
+
+## How the layers combine
+Papercliped checks, in this order, and refuses at the first thing that doesn't allow the call:
+
+1. The session's **tool list** (if it has one).
+2. The agent's **setting**: Off refuses; otherwise its mode must allow this kind of tool.
+3. The session's **agent list** (if it has one).
+4. The access **level** (Read only, Full control).
+
+So a call goes through only if *every* layer allows it.
+
+## What the AI app sees
+- Tools that can **never** run for a session are left out of what it is shown, so it doesn't try them. A session limited to `List agents` and `Pause agent` sees exactly those two.
+- A refused call returns a message that says which setting stopped it and where to change it. In the API the response is `403` with `{ "error": { "message": "...", "policy": "<code>" } }`:
+
+| `policy` code | Meaning |
+| --- | --- |
+| `tool_not_allowed` | The session's tool list doesn't include this tool |
+| `mode_blocks` | The access switch (or that agent's setting) doesn't allow this kind of tool |
+| `agent_off` | The agent is turned off |
+| `agent_not_in_session` | The session applies to selected agents and this isn't one of them |
+| `needs_all_agents` | The session applies to selected agents, and this view looks across every agent (or the issue has no agent to check) |
+
+Blocked calls appear in [Activity](/docs/control-room) as **Blocked**, and count under `policy_blocked` in the aggregate error classes of the [public API](/docs/public-api).
+
+## Examples
+- *"I want Claude to run my agents but never change budgets or approvals."* Give that session **Tools: Work through agents + Look** (untick the Direct control tools), or set the switch to **Agent only**.
+- *"I want a reviewer app that only works on two agents."* Open its session, choose **selected agents**, tick the two. It can look at them, wake them and comment on their issues, and nothing else.
+- *"Keep my finance agent away from AI apps."* Agents → set it to **Off**.
+- *"Pause everything fast, but no new work."* Set the switch to **API only**.
+
+## Limits worth knowing
+- These settings apply to calls made **through Papercliped**. They don't change what your Paperclip account can do in Paperclip itself, and the Paperclip key Papercliped holds still has your account's access (see [Security](/docs/security)). They limit the AI app, not the key.
+- Totals the Paperclip server already summed (such as total spend) still include hidden agents. Lists, per-agent breakdowns and reports built from them don't.
+- Changing a setting takes effect on the next request. A call already running isn't interrupted.

package/site/docs/connect-your-paperclip.md

@@ -1,120 +1,166 @@
-# Set up your Paperclip for Papercliped
+# At home, with a tunnel
 
-Papercliped talks to **your** Paperclip over the internet, so your Paperclip needs a public address. This guide gets you one, step by step, whether you already own a domain or not.
+Run Paperclip on your own computer and give it a public `https://` address with a free tunnel. You don't open any ports on your router. This is the cheapest way to start, and a good way to try Papercliped before you rent a server.
 
-You don't need to open any ports on your router for any option below.
+**You'll end up with:** Paperclip on your computer, reachable at a public address like `https://paperclip.yourdomain.com` or `https://my-pc.my-tailnet.ts.net`, connected to Papercliped.
 
-## What Papercliped needs from your Paperclip
-- **A public `https://` address on port 443** that answers over the internet. Private, LAN, `localhost` and plain `http://` addresses are refused on purpose.
-- **Paperclip in authenticated mode and public exposure.** You can check from any computer:
-  ```
-  curl https://your-address/api/health
-  ```
-  A healthy answer is JSON that includes `"status":"ok"`, `"deploymentMode":"authenticated"` and `"deploymentExposure":"public"`. (On Windows PowerShell, `curl.exe https://your-address/api/health` works the same way.)
-- **No login wall or bot challenge in front of `/api/*`.** If you put something like Cloudflare Access, "Under Attack" mode or a managed challenge in front of Paperclip, it must skip `/api/*`, or Papercliped will be blocked.
-- **Paperclip must accept the new hostname.** Paperclip can reject hostnames it doesn't know, and public mode needs its public URL set. Paperclip's own settings for this include `PAPERCLIP_PUBLIC_URL` and `PAPERCLIP_ALLOWED_HOSTNAMES`; the exact steps are in Paperclip's deployment docs (search "Paperclip deployment modes" on docs.paperclip.ing). Check them there rather than guessing.
+**Good to know:** while your computer sleeps or is off, your agents and your AI app's connection stop. For a Paperclip that's always on, use a [VPS or a hosting platform](/docs/hosting).
 
-Paperclip listens on port `3100` by default, which the examples below use. If yours is different, use your port.
+## 1. Choose a tunnel
 
-## Path A: you own a domain (recommended)
-This gives you a stable address like `https://paperclip.yourdomain.com` that survives restarts. The tunnel and DNS are free on Cloudflare's free plan. The domain itself isn't: there is no free `.com`. (Cloudflare Registrar sells domains at wholesale cost, so it's one cheap option if you need to buy one.)
+| Tunnel | Your address | Stays the same? | Needs | Good for |
+| --- | --- | --- | --- | --- |
+| **Cloudflare Tunnel** | `https://paperclip.yourdomain.com` | Yes | A domain on Cloudflare (free plan) | Daily use (recommended) |
+| **Tailscale Funnel** | `https://<computer>.<tailnet>.ts.net` | Yes | A free Tailscale account | Daily use without a domain |
+| **ngrok** | one free `*.ngrok-free.app` address | Yes | A free ngrok account | Daily use without a domain |
+| **Cloudflare quick tunnel** | random `*.trycloudflare.com` | **No, changes every restart** | Nothing | Trying it for an afternoon |
 
-1. **Put your domain on Cloudflare.** Create a free Cloudflare account, add your domain, and switch its nameservers to the two Cloudflare gives you (done at the company where you bought the domain). Wait until Cloudflare shows the domain as active.
-2. **Install `cloudflared`** on the machine that runs Paperclip. Find the installer for Windows, macOS or Linux on Cloudflare's downloads page (search "cloudflared downloads").
-3. **Log in.** This opens a browser so you can pick your domain:
-   ```
-   cloudflared tunnel login
-   ```
-4. **Create the tunnel.** Pick any name:
-   ```
-   cloudflared tunnel create papercliped-paperclip
-   ```
-   It prints a tunnel ID (a UUID) and saves a credentials file in your `.cloudflared` folder. Keep that file private.
-5. **Write the config.** In your `.cloudflared` folder (`~/.cloudflared` on macOS/Linux, `%USERPROFILE%\.cloudflared` on Windows) create `config.yml`:
-   ```
-   tunnel: <TUNNEL-ID>
-   credentials-file: <PATH-TO-THE-CREDENTIALS-FILE>.json
-   ingress:
-     - hostname: paperclip.yourdomain.com
-       service: http://localhost:3100
-     - service: http_status:404
-   ```
-   The last rule is required: it answers 404 for anything else.
-6. **Point the name at the tunnel:**
-   ```
-   cloudflared tunnel route dns papercliped-paperclip paperclip.yourdomain.com
-   ```
-7. **Run it.** To try it first:
-   ```
-   cloudflared tunnel run papercliped-paperclip
-   ```
-   To keep it running (starts with your computer), install it as a service:
-   - **macOS:** `cloudflared service install` (runs when you log in) or `sudo cloudflared service install` (runs at boot).
-   - **Linux:** `cloudflared service install` (with `sudo` if needed).
-   - **Windows:** run `cloudflared.exe service install` from an Administrator PowerShell. A Windows service may not read the config from your user folder; check Cloudflare's "Run as a service on Windows" page for where it expects `config.yml`.
-8. **Check it** from any computer:
-   ```
-   curl https://paperclip.yourdomain.com/api/health
-   ```
-   You should see the JSON described above.
+Pick one and **work out your address first**: Paperclip needs to know it during setup (step 2). The tunnel sections below show how to get it.
+
+## 2. Install Paperclip in public mode
+
+You need **Node.js 24.11 or newer** (check with `node -v`; get it from nodejs.org).
+
+```
+npx paperclipai onboard
+```
+
+When it asks:
+
+- **Deployment mode:** `authenticated` (people sign in).
+- **Exposure:** `public`.
+- **Public URL:** your tunnel address from step 1, for example `https://paperclip.yourdomain.com` (with `https://`, no slash at the end).
+- **Bind:** `loopback`. The tunnel connects from your own computer, so Paperclip doesn't need to listen on your network.
+
+These choices are the same as the settings `PAPERCLIP_DEPLOYMENT_MODE=authenticated`, `PAPERCLIP_DEPLOYMENT_EXPOSURE=public` and `PAPERCLIP_PUBLIC_URL`, which you can also set as environment variables. Onboarding creates the secrets Paperclip needs and saves them in `~/.paperclip/instances/default/.env`. Start Paperclip with:
+
+```
+npx paperclipai run
+```
+
+It listens on port **3100**. (If something else already uses 3100, Paperclip quietly picks another port and prints it; use that port in the tunnel instead.)
 
-**If your computer sleeps or turns off,** the tunnel goes down and your connected AI apps stop working until it's back. Turn off sleep on the machine, or run Paperclip on an always-on computer or server.
+**Already running Paperclip on this computer** in the default `local_trusted` mode (no login)? Change it with `npx paperclipai configure --section server`: choose `authenticated`, `public`, and your tunnel address. Never put a `local_trusted` Paperclip behind a public address: anyone who finds it could control it.
 
-## Path B: you don't have a domain yet
-All of these are free. They differ in how stable the address is.
+**Prefer Docker?** Use the Compose file from the [VPS guide](/docs/host-vps#5-create-the-docker-compose-file) without the `caddy` service, add `ports: ["127.0.0.1:3100:3100"]` to the Paperclip service, and set `DOMAIN` to your tunnel's hostname.
 
-| Option | Address | Stable? | Good for |
-| --- | --- | --- | --- |
-| Tailscale Funnel | `https://<machine>.<tailnet>.ts.net` | Yes | Daily use |
-| ngrok free plan | one free static `ngrok-free.app` / `ngrok-free.dev` domain | Yes | Daily use, with a caveat below |
-| Cloudflare quick tunnel | random `*.trycloudflare.com` | **No, changes every restart** | Trying Papercliped only |
+## 3. Start the tunnel
 
-### Tailscale Funnel (stable)
-Funnel makes a service on your computer reachable from the public internet at your tailnet's `ts.net` name.
-1. Create a free Tailscale account and install Tailscale on the machine that runs Paperclip.
-2. In the Tailscale admin console, turn on **HTTPS certificates** for your tailnet and allow Funnel. (Running the `tailscale funnel` command below walks you through enabling it and updates your tailnet policy for you.)
-3. Start Funnel for Paperclip's port:
+Follow the section for the tunnel you chose, then come back for step 4.
+
+### Cloudflare Tunnel (with your domain)
+
+Stable address on your own domain. The tunnel and DNS are free on Cloudflare's free plan; the domain itself isn't (Cloudflare Registrar sells them at cost).
+
+1. **Put your domain on Cloudflare:** create a free account, add your domain, and switch its nameservers to the two Cloudflare gives you (at the company where you bought the domain). Wait until Cloudflare shows it as active.
+2. In the Cloudflare dashboard, open **Zero Trust → Networks → Tunnels → Create a tunnel**, choose **Cloudflared**, and name it `paperclip`.
+3. Cloudflare shows an install command for Windows, macOS or Linux that includes a token, like `cloudflared service install eyJ…`. Run it on this computer. It installs `cloudflared` as a service that starts with the computer. (Keep the token private; it's the key to your tunnel.)
+4. Under **Public Hostname**, add: subdomain `paperclip`, your domain, service type **HTTP**, URL **`localhost:3100`**. Save.
+
+That's it: `https://paperclip.yourdomain.com` now reaches your Paperclip. Don't turn on Cloudflare Access, Bot Fight Mode or a WAF challenge for this hostname (or exempt `/api/*`), or Papercliped will be blocked.
+
+<details><summary>Prefer the command line?</summary>
+
+```
+cloudflared tunnel login
+cloudflared tunnel create paperclip
+cloudflared tunnel route dns paperclip paperclip.yourdomain.com
+```
+
+Create `config.yml` in your `.cloudflared` folder (`~/.cloudflared` on macOS and Linux):
+
+```
+tunnel: <TUNNEL-ID>
+credentials-file: <PATH-TO-THE-CREDENTIALS-FILE>.json
+ingress:
+  - hostname: paperclip.yourdomain.com
+    service: http://localhost:3100
+  - service: http_status:404
+```
+
+Try it with `cloudflared tunnel run paperclip`, then install it as a service with `cloudflared service install` (`sudo` on Linux and for start-at-boot on macOS). **On Windows** the service runs as SYSTEM, so it doesn't read your user folder: put `config.yml` and the credentials file in `C:\Windows\System32\config\systemprofile\.cloudflared\`, then run `cloudflared.exe service install` from an Administrator PowerShell. The dashboard method above avoids all of this.
+
+</details>
+
+### Tailscale Funnel (no domain)
+
+1. Create a free Tailscale account and install Tailscale on this computer.
+2. Run:
    ```
-   tailscale funnel 3100
+   tailscale funnel --bg 3100
    ```
-   It prints your public address, like `https://my-pc.my-tailnet.ts.net`. Funnel only serves on ports 443, 8443 and 10000; use the default 443 for Papercliped.
-4. Funnel traffic has bandwidth limits you can't change. That is fine for Papercliped's small requests, but check Tailscale's Funnel docs for the current rules on your plan.
+   The first time, it walks you through turning on HTTPS certificates and Funnel for your tailnet. It prints your address, like `https://my-pc.my-tailnet.ts.net`, and keeps running in the background.
+3. Funnel only serves on ports 443, 8443 and 10000; the command above uses 443, which is what Papercliped needs. Funnel addresses always end in `.ts.net` (no custom domains), and bandwidth is limited, which is fine for Papercliped's small requests.
 
-### ngrok free plan (stable address, one catch)
-1. Create a free ngrok account. Every account gets one free static "dev domain" (for example `your-name.ngrok-free.dev`); see it in the ngrok dashboard under Domains.
+Find your address any time with `tailscale funnel status`.
+
+### ngrok (no domain)
+
+1. Create a free ngrok account. Your account gets one free static address (under **Domains** in the ngrok dashboard), like `your-name.ngrok-free.app`. You can't choose it on the free plan.
 2. Install ngrok and add your authtoken (the dashboard shows the exact command).
-3. Run, with your own domain:
+3. Run, with your own address:
    ```
-   ngrok http --url=your-name.ngrok-free.dev 3100
+   ngrok http --url=your-name.ngrok-free.app 3100
    ```
-4. **The catch:** on the free plan ngrok shows a "visit site" warning page to browsers. Papercliped's requests come from a program, not a browser, but if the connection fails with a strange HTML page, this is the likely cause. Check ngrok's free-plan docs for the current behavior and any header that skips it.
+4. On the free plan ngrok shows a "You are about to visit…" page to **web browsers** the first time. Click **Visit Site** when you open Paperclip in your browser; requests from programs like Papercliped aren't affected. If a connection ever fails with an unexpected HTML page, this page is the likely cause.
+
+To keep ngrok running after you close the terminal, see ngrok's docs on running it as a service (`ngrok service install`).
 
 ### Cloudflare quick tunnel (trial only)
-No account, no domain:
+
+No account, no domain. Install `cloudflared`, then:
+
 ```
 cloudflared tunnel --url http://localhost:3100
 ```
-It prints a random `https://something.trycloudflare.com` address. **The address changes every time you restart it**, and when it changes your Papercliped connection stops working until you connect again with the new address. Quick tunnels are for trying Papercliped for an afternoon, not for daily use.
 
-## Connect to Papercliped
-1. Make sure `curl https://your-address/api/health` works (see above).
-2. Go to [Create your account]({{URL}}/docs/signup), add Papercliped as a connector in Claude, and choose **Connect your Paperclip**.
-3. Enter your public address (just the address, no path), then approve the request in your Paperclip.
+It prints a random `https://something.trycloudflare.com` address. Use that as the public URL in step 2 (`npx paperclipai configure --section server` if you already onboarded). **The address changes every time you restart it**, and then Papercliped can't reach your Paperclip until you set the new address in Paperclip and connect again. Quick tunnels are for testing only.
+
+## 4. Create your account
+
+In another terminal on the same computer:
+
+```
+npx paperclipai auth bootstrap-ceo --base-url https://your-address
+```
+
+It prints a one-time invite link. Open it, create your account and your first company. (If you switched an existing Paperclip from `local_trusted`, it may instead print a one-time **claim** link when it starts; either works.)
+
+## 5. Check it works
+
+From another network (your phone on mobile data is a good test):
+
+```
+curl https://your-address/api/health
+```
+
+(On Windows PowerShell use `curl.exe`.) You want JSON with `"status":"ok"`, `"deploymentMode":"authenticated"`, `"deploymentExposure":"public"` and `"bootstrapStatus":"ready"`.
+
+## 6. Connect Papercliped
+
+1. Add the connector in your AI app. In Claude: **Settings → Connectors → Add custom connector**, address `{{MCP}}/mcp`.
+2. Choose **Connect your Paperclip**, enter your public address (just the address, no path) and approve the request in your Paperclip. The box **Also install the Papercliped plugin in my Paperclip** is ticked by default; it installs the [Paperclip plugin](/docs/paperclip-plugin) and its [control room](/docs/control-room) for you if you are your Paperclip's instance admin.
+3. Pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**. Every screen: [Create your account](/docs/signup).
+4. Send your first prompt: *"Catch me up on my Paperclip."* More in the [prompt gallery](/docs/prompts).
+
+## Keep it running
+
+- **Turn off sleep** on this computer, or your agents and connection stop whenever it sleeps.
+- **Start Paperclip with the computer.** The Cloudflare dashboard tunnel and Tailscale already do; for Paperclip itself, add `npx paperclipai run` to your login items (macOS), Task Scheduler (Windows) or a systemd service (Linux), or use the Docker setup, which restarts by itself.
+- **Update Paperclip** with `npx paperclipai@latest run` when your agents are idle.
 
 ## Keep it safe
-- **Expose only Paperclip.** Point the tunnel at Paperclip's port and nothing else on your computer.
+
+- **Expose only Paperclip.** Point the tunnel at port 3100 and nothing else on your computer.
+- **Never expose `local_trusted` mode.** Always `authenticated` + `public`.
 - **Keep Paperclip up to date.**
-- **Use a dedicated Paperclip user for the connection** if you can, so you can see and limit what it does.
-- **You can cut access any time:** revoke the Papercliped key in Paperclip, or disconnect apps in the [Paperclip plugin](/docs/paperclip-plugin).
-- **If the tunnel or your computer is off,** connected apps simply stop working until it's back. Nothing is lost.
+- **You can cut access any time:** disconnect apps in the [Paperclip plugin](/docs/paperclip-plugin), or revoke the key in Paperclip.
 
 ## Troubleshooting
-- **"Could not reach your Paperclip":** the tunnel isn't running, the DNS name hasn't spread yet (give a new name a few minutes), or the address isn't on port 443. Test with `curl https://your-address/api/health` from another network (for example, your phone's mobile data).
-- **"Private address" errors:** you entered a LAN address, `localhost`, or `http://`. Use the public `https://` address from your tunnel.
-- **A challenge or login page appears:** exempt `/api/*` from Cloudflare Access, "Under Attack" mode or any managed challenge.
-- **"Host not allowed" or a 4xx from Paperclip:** Paperclip doesn't know the new hostname. Set its public URL and allowed hostnames (see Paperclip's deployment docs, above) and restart it.
-- **Certificate warnings:** use the HTTPS address your tunnel provider gives you, not your own certificate on a raw IP. Tunnels handle certificates for you.
-- **Worked yesterday, not today:** the address changed (quick tunnels do this), the tunnel stopped, or the computer slept.
-
-## Not independently confirmed
-These came from vendor docs summarized through search, not read page by page. Check the vendor's current docs before relying on them: Windows service setup for `cloudflared`, Tailscale's current Funnel limits, ngrok's free-plan warning page behavior, and Paperclip's exact setting names for public URL and allowed hostnames.
+
+- **"Could not reach your Paperclip":** the tunnel or Paperclip isn't running, a new DNS name hasn't spread yet (give it a few minutes), or the address isn't on port 443. Test with `curl` from another network.
+- **"Private address" errors:** you entered a LAN address, `localhost` or `http://`. Use the public `https://` address from your tunnel.
+- **"This hostname is not allowed for this Paperclip instance":** Paperclip's public URL doesn't match the tunnel address, or exposure is still `private`. Fix it with `npx paperclipai configure --section server` and restart.
+- **A challenge or login page appears:** exempt `/api/*` from Cloudflare Access, Bot Fight Mode, "Under Attack" mode or any managed challenge.
+- **Worked yesterday, not today:** the computer slept, the tunnel stopped, or a quick tunnel's address changed.
+- More: [Troubleshooting](/docs/troubleshooting).

package/site/docs/control-room.md

@@ -0,0 +1,61 @@
+# The control room
+
+The control room is Papercliped inside Paperclip: one place to see every AI app connected to your Paperclip, what each is allowed to do, and what it has done. It opens from **Papercliped** in Paperclip's sidebar and uses Paperclip's own look, so it follows your theme.
+
+You need the [Paperclip plugin](/docs/paperclip-plugin) installed and your Papercliped account linked. Everything here takes effect on the app's **next request**: nothing needs reconnecting.
+
+## How it fits together
+Three things decide what an AI app can do. Papercliped checks all three on every call, and the strictest one wins.
+
+| Layer | Where you set it | Decides |
+| --- | --- | --- |
+| **Access switch** | Overview, Agents, dashboard widget, agent tab | Whether AI apps may control Paperclip directly, work through agents, or both ([API only, Full or Agent only](/docs/access-modes)), for every agent or one agent at a time |
+| **Session** | Sessions | Which tools one connected app may use, and which agents it applies to |
+| **Level** | Sessions | Read only or Full control, as chosen when the app connected ([Permissions](/docs/permissions)) |
+
+## The menu
+While the control room is open, Paperclip's left menu is replaced by Papercliped's, the same way it is on an agent's page. **Back to Paperclip** at the top returns you.
+
+### Overview
+The front page. The **access switch** is a three-position switch: **API only**, **Full** (the default) and **Agent only**. Click a position, or use the arrow keys when the switch has focus. It saves at once. Beside it: how many sessions you have, how many agents, the calls made today and how many were blocked, a short list of things that need a look (a session that never made a call, an agent turned off, blocked calls, a Paperclip key that is not connected), and the latest calls.
+
+### Sessions
+Every AI app connected through Papercliped is a **session**. Open one to change:
+
+- **Name.** Rename a session to tell two apps or two devices apart. Up to 60 characters.
+- **Level.** Read only or Full control.
+- **Tools.** *All tools* means every tool its level and the switch allow. Untick it to choose exactly which tools this session may use, grouped as **Look**, **Work through agents** and **Direct control**. When a session is Read only, tools that change things are greyed out with "Needs Full control".
+- **Agents.** *Everyone* (including agents you add later), or **selected agents**. A session limited to selected agents works only with those agents: it can look at them, pause them, wake them, give them work, and use issues assigned to them. It cannot use views across every agent, such as reports, the org chart, goals and approvals, because those would show agents it doesn't apply to. The page says so when you choose it.
+- **Recent calls** for just this session, and **Disconnect**.
+
+Save with **Save changes** (it stays disabled until something changed and says what's wrong if a list is empty). **Discard** puts everything back.
+
+### Agents
+Papercliped follows the access switch for every agent. Here you can set any agent apart: **Default**, **API only**, **Full**, **Agent only** or **Off**.
+
+**Off** hides the agent completely. AI apps can't see it, can't touch it, and don't see anything assigned to it or its spending in lists and reports. Use it for agents you never want an AI app near.
+
+The default for every agent can also be changed from this page. Settings for agents that no longer exist (or are in another company) are listed so you can remove them.
+
+### Tools
+All tools an AI app can use, grouped by what they do, with what the switch allows right now and how many of your sessions can use each. Use it to answer "can my laptop session pause an agent?" without opening each session.
+
+### Activity
+The newest calls through your sessions: when, which session, which tool, and the result: **OK**, **Blocked** (by your settings) or **Failed** (with the reason, such as "Paperclip unreachable"). Filter by session, or to blocked and failed only. It refreshes every 20 seconds.
+
+Activity shows *what was used and what happened*. It never records what was sent to a tool or what came back. On the hosted service it is kept for 30 days.
+
+### Settings
+Privacy (appear anonymously in the service's logs), the Paperclips linked to your account, and the account itself (a new secret key, disconnect your Paperclip, delete the account). These ask for your secret key again. See [Anonymous mode](/docs/anonymous-mode).
+
+## In the rest of Paperclip
+- **An "Papercliped" tab on every agent's page.** Set what AI apps may do with *this* agent, and see which sessions reach it.
+- **A dashboard widget.** The access switch in small, with the number of sessions and blocked calls.
+- **A sidebar entry**, with the paperclip icon, under your other sections.
+
+## Good to know
+- These settings limit what AI apps can do **through Papercliped**. They don't change what your own Paperclip account can do in Paperclip itself.
+- A blocked call returns a plain message to the AI app saying which setting stopped it and where to change it, so it doesn't keep retrying. See [Limits and errors](/docs/limits-and-errors).
+- Tools that can never run for a session (switched off by the access switch or left out of its tool list) are not shown to the AI app at all.
+- Totals the Paperclip server already added up (for example total spend) still include hidden agents. Lists, reports by agent and anything built from them don't.
+- New permissions need approval in Paperclip. If you installed an earlier version of the plugin, remove it and install it again from **Settings → Plugins** to get the control room (see [Paperclip plugin](/docs/paperclip-plugin)).