papercliped 2.1.0 → 2.2.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Run your Paperclip from Claude: control agents, sync with them and get reports, at the access level you choose.",
   "author": {
     "name": "KpnWorld"

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## v2.2.1 — the Papercliped plugin now installs in Paperclip
+
+- **Fixed: the Papercliped plugin could not be installed in Paperclip.** Paperclip rejected it with a bare "400" because the sidebar entry declared a page route, which Paperclip only allows on pages. Installing it, automatically while connecting or by hand from Settings → Plugins, now works. The plugin’s tests now run Paperclip’s own manifest check so this can’t come back. If you ticked the box while connecting on 2.2.0, nothing was installed: connect again, or install it from Settings → Plugins.
+
+## v2.2.0 — install the Papercliped plugin while connecting
+
+- **The Papercliped plugin can install itself while you connect.** The "Connect your Paperclip" step has a new box, ticked by default: *Also install the Papercliped plugin in my Paperclip*. After you approve the sign-in, Papercliped asks your Paperclip to install `papercliped-paperclip-plugin` through Paperclip's own installer, using your own approved key. It installs one fixed package at the exact version that matches the service, only if you are the instance admin, and does nothing if the plugin is already there, you are not an admin, or your Paperclip has no plugin support. It never delays or fails your connection, and the outcome is logged as a short `plugin` event (installed, already, denied, unsupported or failed). Untick the box to skip it; installing by hand from Settings → Plugins still works.
+- **Docs tidy-up:** the OAuth flow diagram and the security notes no longer mention a third "Admin" level (there are exactly two: Read only and Full control), and the repository ignores generated files (`openapi.json`, `.wrangler/`, coverage output) so they can't be committed by accident.
+- **Fixed:** the website’s changelog date test only allowed 5–6 October 2026 and would have failed every later release; it now accepts any real date between the first release and today. The package check (`scripts/check-packages.mjs`) also runs on Windows now.
+
 ## v2.1.0 — two access levels, manage in Paperclip, new website
 
 - **Dependencies up to date:** Zod 4 (tool schemas and the ChatGPT Actions OpenAPI now come from Zod's built-in JSON Schema; the published contract is unchanged), the latest MCP SDK, undici 8, TypeScript 7, Vitest 5, React 19 and esbuild 0.28 in the plugin, and GitHub Actions v7. No known vulnerabilities in either package. Dependabot now also watches the website and groups minor and patch updates into one pull request per package.

package/dist/oauth/pages.js

@@ -86,6 +86,10 @@ export function instancePage(v) {
        <label class="f" for="inst">Paperclip address</label>
        <input id="inst" name="instance" type="text" inputmode="url" autocomplete="off" spellcheck="false" placeholder="https://paperclip.example.com" value="${esc(v.value ?? "")}" required>
        <small class="hint">The bridge contacts this address to sign you in and to run what you allow. Only enter an address you own.</small>
+       <label class="f" style="display:flex;gap:10px;align-items:flex-start;margin-top:16px;font-weight:400">
+         <input id="plug" name="install_plugin" type="checkbox" value="on" style="width:auto;margin-top:3px"${v.installPlugin === false ? "" : " checked"}>
+         <span>Also install the Papercliped plugin in my Paperclip<br><small class="hint">Adds a Papercliped page to Paperclip for managing connected apps. It is installed through Paperclip's own installer, only if you are its instance admin, and you can remove it any time from Settings &rarr; Plugins.</small></span>
+       </label>
        <div class="row"><button class="btn" name="action" value="continue">Continue</button>${cancel}</div>
      </form>
      <p class="fine">You'll return to <code>${esc(v.redirectHost)}</code> afterwards.</p>`);

package/dist/oauth/paperclip-login.js

@@ -1,5 +1,7 @@
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const APPROVAL_PATH = /^\/cli-auth\/[0-9a-f-]{36}\?token=[A-Za-z0-9_\-.~%]{8,300}$/i;
+/** Paperclip runs npm install server-side, which can take a while. */
+const PLUGIN_INSTALL_TIMEOUT_MS = 120_000;
 const TOKENISH = /^[\x21-\x7e]{8,600}$/; // printable ASCII, no whitespace
 export class LoginError extends Error {
     status;
@@ -80,6 +82,42 @@ export class PaperclipLogin {
         const r = await json(await this.t.fetch(`${this.t.apiUrl}/cli-auth/me`, { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }, ...this.sig() }));
         return { userId: typeof r?.userId === "string" ? r.userId.slice(0, 200) : null };
     }
+    /**
+     * The Papercliped plugin's state in this Paperclip: absent, or installed with its version.
+     * `unsupported` = no plugin system there (older Paperclip) or the key may not manage plugins.
+     */
+    async pluginState(token, pluginKey) {
+        const res = await this.t.fetch(`${this.t.apiUrl}/plugins`, { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }, ...this.sig() });
+        if (res.status === 403 || res.status === 404)
+            return { state: "unsupported" };
+        const list = await json(res);
+        if (!Array.isArray(list))
+            throw new LoginError("Paperclip returned an unexpected plugin list");
+        const hit = list.find((x) => x && typeof x === "object" && x.pluginKey === pluginKey);
+        if (!hit)
+            return { state: "absent" };
+        return { state: "installed", version: typeof hit.version === "string" ? hit.version.slice(0, 40) : null };
+    }
+    /**
+     * Install one fixed npm package at one exact version through Paperclip's own installer. Only an instance
+     * admin's key is accepted there; anyone else gets a 403, reported as "denied". Nothing user-supplied reaches this call.
+     */
+    async installPlugin(token, packageName, version) {
+        const res = await this.t.fetch(`${this.t.apiUrl}/plugins/install`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify({ packageName, version }),
+            signal: AbortSignal.timeout(Math.max(this.t.timeoutMs, PLUGIN_INSTALL_TIMEOUT_MS)),
+        });
+        if (res.status === 403)
+            return "denied";
+        if (res.status === 404)
+            return "unsupported";
+        const out = await json(res);
+        if (out?.packageName !== packageName)
+            throw new LoginError("Paperclip installed something other than the Papercliped plugin");
+        return "installed";
+    }
     /** Best effort: invalidate the board key we were issued when a grant is revoked. */
     async revoke(token) {
         try {

package/dist/oauth/provider.js

@@ -8,6 +8,7 @@ import { UnsafeUrlError, createSafeFetch, parseInstanceUrl } from "../net/safe-f
 import { Keyring, isValidCodeChallenge, randomToken, safeEqual, sha256Hex, verifyPkce } from "./crypto.js";
 import { approvePage, choosePage, consentPage, errorPage, instancePage, scopePage, secretPage, usernamePage, welcomePage } from "./pages.js";
 import { LoginError, PaperclipLogin } from "./paperclip-login.js";
+import { VERSION } from "../version.js";
 import { MemoryStore } from "./store.js";
 import { SCOPES, grantableScopes, isScope, maxRank, normalizeScope, normalizeScopes, scopeAllows, scopesUpTo } from "./scopes.js";
 const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
@@ -15,6 +16,12 @@ const PENDING_TTL_MS = 10 * 60_000;
 const CODE_TTL_MS = 60_000;
 const MAX_PENDING = 5000;
 const MAX_INSTANCE_ATTEMPTS = 5;
+/** The plugin offered on the instance step: one fixed package, pinned to this bridge's own version (both are released together). */
+const PLUGIN_PACKAGE = "papercliped-paperclip-plugin";
+/** Its id inside Paperclip (the manifest id), used to see whether it is already installed. */
+const PLUGIN_KEY = "papercliped.remote-control";
+/** Paperclip runs npm on its side for an install; allow it more time than ordinary calls. */
+const PLUGIN_INSTALL_MS = 120_000;
 const MAX_FORM_BYTES = 16 * 1024;
 const DAY_MS = 24 * 3600 * 1000;
 class OAuthError extends Error {
@@ -58,6 +65,10 @@ export class OAuthProvider {
     keyring;
     now;
     safeFetch;
+    /** Longer-lived egress-guarded fetch for the plugin install, which makes Paperclip run npm. */
+    installFetch;
+    /** Plugin installs running after a sign-in finished, so tests (and shutdown) can wait for them. */
+    background = new Set();
     multi;
     accounts;
     constructor(deps) {
@@ -68,6 +79,7 @@ export class OAuthProvider {
         this.multi = deps.oauth.mode === "multi";
         this.accounts = deps.oauth.accounts && this.multi;
         this.safeFetch = deps.safeFetch ?? createSafeFetch({ timeoutMs: deps.config.timeoutMs, maxBytes: 2_000_000 });
+        this.installFetch = deps.safeFetch ?? createSafeFetch({ timeoutMs: PLUGIN_INSTALL_MS, maxBytes: 200_000 });
         this.resource = `${deps.oauth.issuer}/mcp`;
         this.metadataUrl = `${deps.oauth.issuer}/.well-known/oauth-protected-resource`;
     }
@@ -389,6 +401,46 @@ export class OAuthProvider {
             throw new UnsafeUrlError("This service is not open to that host yet.");
         return u;
     }
+    /** Wait for plugin installs that are still running (tests and graceful shutdown). */
+    async drainBackground() {
+        await Promise.allSettled([...this.background]);
+    }
+    /**
+     * Install the Papercliped plugin into the user's Paperclip after they approved the sign-in and ticked the box.
+     * Runs after the page has been answered: npm can take a while on their side, and the connection must not wait for it
+     * or fail because of it. The outcome is recorded as a "plugin" event and never carries anything but a short word.
+     */
+    installPluginLater(p, token) {
+        const instanceUrl = p.instanceUrl;
+        if (!instanceUrl)
+            return;
+        const accountId = p.accountId ?? null;
+        const run = (async () => {
+            let outcome = "failed";
+            try {
+                const login = this.pluginLoginFor(instanceUrl);
+                const now = await login.pluginState(token, PLUGIN_KEY);
+                if (now.state === "unsupported")
+                    outcome = "unsupported";
+                else if (now.state === "installed")
+                    outcome = "already";
+                else
+                    outcome = await login.installPlugin(token, PLUGIN_PACKAGE, VERSION);
+            }
+            catch {
+                outcome = "failed";
+            }
+            await this.event("plugin", await this.who(accountId), outcome);
+        })();
+        const tracked = run.finally(() => this.background.delete(tracked));
+        this.background.add(tracked);
+    }
+    pluginLoginFor(instanceUrl) {
+        if (this.deps.loginFor)
+            return this.deps.loginFor(instanceUrl);
+        const origin = this.checkedInstance(instanceUrl).origin; // re-validated: policy can tighten between steps
+        return new PaperclipLogin({ apiUrl: `${origin}/api`, publicOrigin: origin, fetch: this.installFetch, timeoutMs: PLUGIN_INSTALL_MS });
+    }
     loginFor(instanceUrl) {
         if (this.deps.loginFor)
             return this.deps.loginFor(instanceUrl);
@@ -753,7 +805,7 @@ export class OAuthProvider {
         const c = this.ctx(rid, p, error);
         switch (p.stage) {
             case "instance":
-                return this.page(res, status, instancePage({ ...c, value: extra.value, notice: extra.notice }), p);
+                return this.page(res, status, instancePage({ ...c, value: extra.value, notice: extra.notice, installPlugin: p.installPlugin }), p);
             case "approve": {
                 const ch = this.unsealChallenge(p);
                 if (!ch || !p.instanceUrl) {
@@ -912,6 +964,7 @@ export class OAuthProvider {
             return this.html(res, 429, errorPage("Too many attempts", "Too many addresses tried. Start again from the app."));
         }
         p.attempts += 1;
+        p.installPlugin = f.get("install_plugin") === "on";
         const typed = (f.get("instance") ?? "").slice(0, 300);
         const fail = async (why, detail) => {
             await this.store.putPending(rid, p);
@@ -978,6 +1031,8 @@ export class OAuthProvider {
         }
         if (!userId)
             return this.renderStage(res, rid, p, "Paperclip did not say who you are, so we can't link a username to it.");
+        if (p.installPlugin)
+            this.installPluginLater(p, ch.boardApiToken);
         const owner = await this.store.getLinkByIdentity(p.instanceUrl, userId);
         if (p.accountId) {
             // Reconnecting an account the user already signed in to with their secret key.

package/docs/ONBOARDING-PROTOCOLS.md

@@ -0,0 +1,84 @@
+# Onboarding: how each protocol step works
+
+Notes on what happens from "add the connector" to "the AI can call tools", with the exact exchange at each step.
+**Observed** = captured from the live service (`https://mcp.papercliped.co`, v2.2.0, 2026-10-07).
+**From code** = read from `src/` but not exercised live in this pass (it needs a real Paperclip sign-in).
+
+## The whole flow
+
+```
+AI app                         Papercliped bridge                      the user's Paperclip
+  |  1 POST /mcp (no token) ------>|                                          |
+  |<----- 401 + WWW-Authenticate --|                                          |
+  |  2 GET  protected-resource ---->|   (where is the login server?)           |
+  |  3 GET  authorization-server -->|   (what endpoints, what is supported?)   |
+  |  4 POST /register ------------->|   (dynamic client registration)          |
+  |  5 open /authorize in browser ->|   (PKCE, S256)  ... sign-in pages ...    |
+  |                                 |-- 6 probe GET /api/health -------------->|
+  |                                 |-- 7 POST /api/cli-auth/challenges ------>|
+  |        user approves in Paperclip's own UI  <-----------------------------|
+  |                                 |-- 8 poll challenge, GET /cli-auth/me --->|
+  |<-- 9 redirect with ?code=... ---|                                          |
+  | 10 POST /token (code+verifier)->|                                          |
+  |<----- access + refresh token ---|                                          |
+  | 11 POST /mcp  Bearer token ---->|-- 12 tool call with the user's key ----->|
+```
+
+## 1. Unauthenticated call is answered with a pointer (Observed)
+`POST /mcp` with no token returns `401` and
+
+`WWW-Authenticate: Bearer resource_metadata="https://mcp.papercliped.co/.well-known/oauth-protected-resource", scope="paperclip:read"`
+
+This is the MCP authorization spec's discovery trigger: the client learns where to read the resource metadata. The `scope` hint is the minimum (read).
+
+## 2. Protected-resource metadata (Observed)
+`GET /.well-known/oauth-protected-resource` returns the resource (`https://mcp.papercliped.co/mcp`), its one authorization server (`https://mcp.papercliped.co`), the scopes `paperclip:read` and `paperclip:control`, and `bearer_methods_supported: ["header"]`.
+The connector URL a user pastes must equal `<BRIDGE_PUBLIC_URL>/mcp`, because the issuer is baked into every token (changing it logs everyone out).
+
+## 3. Authorization-server metadata (Observed)
+`GET /.well-known/oauth-authorization-server` lists `/authorize`, `/token`, `/register`, `/revoke`; response type `code` only; grants `authorization_code` and `refresh_token`; PKCE method `S256` only; token endpoint auth `none` (public clients); scopes `paperclip:read`, `paperclip:control`, `offline_access`; and `authorization_response_iss_parameter_supported: true` (the redirect carries `iss`, which defends against mix-up attacks).
+
+## 4. Dynamic client registration (Observed)
+`POST /register` with a name and `redirect_uris` returns a `client_id` (`pcb_c_...`), no secret (public client), and the granted grant types and scopes.
+Redirect URIs are checked against an allow-list of hosts (`claude.ai`, `claude.com`, `chatgpt.com`, plus loopback for local tools): a registration with another host is refused with `400`.
+
+## 5. /authorize and the sign-in pages (Observed first page, rest From code)
+The client opens `/authorize?response_type=code&client_id&redirect_uri&code_challenge&code_challenge_method=S256&state&scope&resource`. The bridge stores the request as a short-lived pending record and answers with **"Sign in to Papercliped"**, which has two forms:
+- **Log in** (`POST /authorize/login`): username + secret key (`pcs_...`), for returning users.
+- **Connect your Paperclip** (`POST /authorize/connect`): for new users or lost keys.
+
+Every page carries a one-time request id and a CSRF token; steps must arrive in order (an out-of-order post just re-shows the right page). The pages are plain server-rendered HTML with a strict CSP.
+
+### Connect path (From code, pages in `src/oauth/pages.ts`)
+1. **Connect your Paperclip** (`POST /authorize/instance`): the user types their Paperclip address (public `https`, port 443 unless allowed). New in 2.2.0: a box, ticked by default, "Also install the Papercliped plugin in my Paperclip". The address passes the SSRF guard (public addresses only, no redirects, size and time limits, at most 5 tries per request).
+2. **Probe**: `GET <paperclip>/api/health` must answer JSON with `status` and `deploymentMode: "authenticated"`. This is the step that failed on 2026-10-07 when the instance's database was down (the endpoint hung, which the bridge reports as "connection failed").
+3. **Challenge**: `POST <paperclip>/api/cli-auth/challenges` (Paperclip's own CLI-login flow) returns a challenge id, a secret, a pending board token and an approval link. The bridge validates every field before use.
+4. **Approve in Paperclip** (page "Approve in your Paperclip"): the user opens the approval link on their own Paperclip, signs in there (the bridge never sees that password) and approves. The page polls `/authorize/status`.
+5. **Approved** (`POST /authorize/approved`): the bridge checks the challenge is approved, then `GET /api/cli-auth/me` with the board token to learn the Paperclip user id. If that Paperclip user already has a Papercliped account the user is signed straight in. If the box was ticked, the plugin install starts in the background here (see below).
+6. **Username** (new users): choose a username (and optionally anonymity); the account is created.
+7. **Secret key**: shown once. It signs the user in next time without Paperclip's approval.
+8. **Access level**: exactly two, **Read only** (`paperclip:read`) and **Full control** (`paperclip:control`, every tool). Read only is preselected unless the app asked for control.
+9. **Decision** (`POST /authorize/decision`): the bridge issues a one-use authorization code (valid 60 seconds) bound to the client, redirect URI, PKCE challenge and scopes, and redirects to the app with `?code=...&state=...&iss=...`.
+
+### Log-in path (From code)
+Username + secret key replaces steps 1-5. If the stored Paperclip credential has expired, the bridge sends the user back through the connect path once ("Your Paperclip connection has expired").
+
+## 6. Plugin install during connect (From code, tested against a stand-in Paperclip)
+Only if the box is ticked, after step 5 succeeds and without delaying the redirect:
+1. `GET <paperclip>/api/plugins` with the user's new board token; look for plugin key `papercliped.remote-control`.
+2. Already there: stop (event detail `already`). `403/404`: stop (`unsupported`).
+3. Otherwise `POST <paperclip>/api/plugins/install` with exactly `{ packageName: "papercliped-paperclip-plugin", version: <this bridge's version> }`. Paperclip allows it only for an instance admin (`403` otherwise, recorded as `denied`). The response's package name is checked.
+   Paperclip runs `npm install <pkg>@<version> --ignore-scripts` into its own plugins folder, then checks the plugin's manifest against its schema, the plugin API version, the capabilities, page-route conflicts and the minimum host version, and registers it. A failure at any of those is a bare `400` in Paperclip's log with no reason. (Observed 2026-10-07: 2.2.0 downloaded fine, then failed the schema because its sidebar slot declared a `routePath`. Fixed in 2.2.1; the plugin's tests now run Paperclip's own `pluginManifestV1Schema`.)
+4. One `plugin` event is recorded with a single word: `installed`, `already`, `denied`, `unsupported` or `failed`. Nothing here can fail the connection.
+
+## 7. Token exchange (Observed error shape, rest From code)
+`POST /token` with `grant_type=authorization_code`, the code, `redirect_uri`, `client_id` and the PKCE `code_verifier`. A wrong or expired code returns `{"error":"invalid_grant","error_description":"Invalid or expired authorization code"}` (Observed). On success the bridge returns an opaque access token (`pcb_at_...`, 1 hour by default) and a rotating refresh token (30 days by default, `offline_access`). Tokens are stored only as hashes; the user's Paperclip key is stored sealed (encrypted) with the bridge secret.
+
+## 8. Calling tools (From code)
+`POST /mcp` with `Authorization: Bearer pcb_at_...`. The bridge looks up the grant, decrypts the user's Paperclip key, checks the grant's scopes against the tool (read-only tools need `paperclip:read`; anything that changes state needs `paperclip:control`), calls that user's Paperclip `/api`, and writes one audit event (tool name, whether it changed anything, ok or a coarse error class, scope needed, timings, the caller's grant id, username and Paperclip host; never tool arguments or results). Each connection is rate-limited (120 calls a minute by default). A refresh token swaps for a new pair and is single-use: presenting an old one a second time is treated as theft and revokes the whole connection (`Refresh token already used`). A refresh can never ask for more than the original grant.
+
+## 9. Ending a connection (From code)
+`POST /revoke`, disconnecting in the Papercliped plugin, or 30 days of inactivity revokes the grant, and the bridge asks the user's Paperclip to revoke the board key it was issued (`POST /api/cli-auth/revoke-current`, best effort).
+
+## What was not done in this pass
+No account was created and no real sign-in was approved. The steps marked From code have not been exercised against a live Paperclip in this pass.

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 scopes (read/control/admin) 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 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.
 
 > **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/oauth.md

@@ -7,7 +7,7 @@ client ──401 + resource_metadata──▶ bridge /mcp
 client ──DCR /register──────────────▶ bridge
 client ──/authorize (PKCE S256)─────▶ bridge ──create challenge──▶ Paperclip /api/cli-auth/challenges
 user   ── opens approvalUrl, signs in to Paperclip, approves ─────▶ Paperclip
-user   ── picks Read / Control / Admin, presses Allow ───────────▶ bridge (verifies approval, checks token)
+user   ── picks Read only / Full control, presses Allow ────────▶ bridge (verifies approval, checks token)
 client ──/token (code + verifier)───▶ bridge ──▶ opaque access + rotating refresh token
 client ──/mcp  Bearer pcb_at_…──────▶ bridge ──user's board token──▶ Paperclip
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "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/paperclip-plugin.md

@@ -5,7 +5,11 @@ The Papercliped plugin is where you manage Papercliped, right inside Paperclip:
 It manages your Papercliped account only. It never reads or controls your Paperclip itself, and AI apps still connect through Papercliped as before.
 
 ## Install (Paperclip admin)
-Install the npm package `papercliped-paperclip-plugin` from **Settings → Plugins** in Paperclip. Installing is done by the person who runs the Paperclip instance, never remotely. The plugin asks for these capabilities: store its own data, make outbound web requests (to Papercliped), and add a sidebar entry and a page.
+**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 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`.
 
@@ -27,6 +31,6 @@ Lost your secret key? Connect from your AI app again and choose **Connect your P
   - **Delete my account.** Removes your username, stored key and every connection. Type your username to confirm.
 
 ## Good to know
-- The plugin runs as trusted code inside Paperclip, so install it only from the official package.
+- 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.
 - The link token stays on your Paperclip server and is never shown on the page. It can only manage your account: it can't call any Paperclip tool.
 - There is no separate website page for this any more; the old `/manage` address points here.