papercliped 2.4.2 → 2.5.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.4.2",
+  "version": "2.5.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,17 @@
 
 ## Unreleased
 
+## v2.5.1 — Paperclip keys renew themselves
+
+- **Connections no longer break after 30 days.** Newer Paperclip versions expire the key Papercliped gets when you approve the sign-in after 30 days. Papercliped now renews it about a week before: it asks your Paperclip for a fresh key (named "Papercliped (your username)", same 30-day expiry), stores it encrypted and revokes the old one. Keys of people who rarely use their connection are renewed by the periodic sweep. If a renewal fails, the current key keeps working and it is tried again later. Older Paperclip versions, whose keys don't expire, work as before. Self-hosters on Postgres: run the database migration before starting this version (`npm run migrate`, or `BRIDGE_AUTO_MIGRATE=1`); keys stored before it are assumed to expire 30 days after they were connected, and the first renewal check reads the real date from Paperclip.
+- **Community cards.** Ready-to-post images for the launch and the new r/OpenSourcedd community, light and dark, 1600×900, in `web/public/brand/community/` (rebuilt by `web/scripts/community-cards.mjs`). Download them from papercliped.co/brand, and the README now opens with the launch card.
+
+## v2.5.0 — icon pack, launch-ready docs and tester feedback
+
+- **Icon pack.** papercliped.co/brand has a one-click ZIP with every Papercliped icon in light and dark: the app icon from 16 to 1024 px, a favicon, profile pictures safe for circle crops (Discord, X, GitHub, npm, MCP directories), an Android/installable-app icon, an X header, a 16:9 banner and link-preview images. They're built from the real mascot and the site's own components by `web/scripts/icon-pack.mjs`, so they always match. The website now also has a classic favicon, an Apple touch icon and a web app manifest.
+- **Docs ready for launch.** Getting started and *Any AI app* now cover Codex and Claude Code (plugin or MCP server). ChatGPT setup leads with the MCP connector in developer mode, with GPT Actions as the alternative. The glossary explains the control room, sessions and access modes. The FAQ explains which access mode a blocked pause or wake needs. Stale links to the old manage page now point to the control room.
+- **Tester feedback form.** GitHub → New issue → *Tester feedback* asks testers which app and host they used, where they got stuck and what they asked. A launch kit for maintainers (`docs/LAUNCH-KIT.md`) covers the pre-launch checklist, a founding-tester program, where to promote, ready-to-paste posts and the demo script.
+
 ## v2.4.2 — Show the real reason a plugin action failed
 
 - **Fixed: the Papercliped page inside Paperclip now shows the real reason a sign-in or save failed**, such as "That username and secret key don't match." Paperclip reports every plugin failure as HTTP 502, and a proxy in front of Paperclip (Cloudflare, for one) replaces that with its own "Bad gateway" page, so the page showed only "Request failed: 502". The plugin now returns failures as ordinary answers and the page turns them back into messages.

package/README.md

@@ -1,5 +1,12 @@
 # Papercliped
 
+<a href="https://papercliped.co">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/OpenSourcx/papercliped/main/web/public/brand/community/papercliped-launch-dark.png">
+    <img alt="Papercliped: run your Paperclip from any AI app. Claude, ChatGPT, Codex or any MCP app. Connector: https://mcp.papercliped.co/mcp" src="https://raw.githubusercontent.com/OpenSourcx/papercliped/main/web/public/brand/community/papercliped-launch-light.png">
+  </picture>
+</a>
+
 **Run your [Paperclip](https://github.com/paperclipai/paperclip) from any AI app.** Papercliped connects Claude, ChatGPT, Codex and any MCP app to your Paperclip, the open-source orchestrator for companies of AI agents. Check on agents, pause or wake them, assign issues, decide approvals and get status, cost and activity reports, without opening the dashboard.
 
 [![CI](https://github.com/OpenSourcx/papercliped/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenSourcx/papercliped/actions/workflows/ci.yml)

package/dist/oauth/paperclip-login.js

@@ -3,6 +3,15 @@ const APPROVAL_PATH = /^\/cli-auth\/[0-9a-f-]{36}\?token=[A-Za-z0-9_\-.~%]{8,300
 /** 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
+/** How long Paperclip keeps a board key it issued without an explicit expiry (its BOARD_API_KEY_TTL_MS). */
+export const PAPERCLIP_KEY_TTL_MS = 30 * 24 * 3600 * 1000;
+/** null = never expires; undefined = not said. Anything unreadable counts as not said. */
+function expiryOf(v) {
+    if (v === null)
+        return null;
+    const t = typeof v === "string" ? Date.parse(v) : NaN;
+    return Number.isFinite(t) ? t : undefined;
+}
 export class LoginError extends Error {
     status;
     constructor(message, status) {
@@ -118,6 +127,38 @@ export class PaperclipLogin {
             throw new LoginError("Paperclip installed something other than the Papercliped plugin");
         return "installed";
     }
+    /**
+     * The calling key's id and expiry, from Paperclip's own key listing. `unsupported` = this Paperclip has no key
+     * listing (versions from before board keys expired). expiresAt: null = never expires, undefined = not listed.
+     */
+    async keyInfo(token) {
+        const auth = { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" } };
+        const me = await json(await this.t.fetch(`${this.t.apiUrl}/cli-auth/me`, { ...auth, ...this.sig() }));
+        const keyId = typeof me?.keyId === "string" && UUID.test(me.keyId) ? me.keyId : null;
+        const res = await this.t.fetch(`${this.t.apiUrl}/board-api-keys`, { ...auth, ...this.sig() });
+        if (res.status === 404)
+            return { state: "unsupported" };
+        const list = await json(res);
+        if (!Array.isArray(list))
+            throw new LoginError("Paperclip returned an unexpected key list");
+        const mine = keyId ? list.find((k) => k && typeof k === "object" && k.id === keyId) : undefined;
+        return { state: "ok", keyId, expiresAt: mine ? expiryOf(mine.expiresAt) : undefined };
+    }
+    /** A new board key for the same Paperclip user, with Paperclip's default expiry. `unsupported` = no key API there. */
+    async createKey(token, name) {
+        const res = await this.t.fetch(`${this.t.apiUrl}/board-api-keys`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify({ name: name.slice(0, 120) }),
+            ...this.sig(),
+        });
+        if (res.status === 404)
+            return { state: "unsupported" };
+        const k = await json(res);
+        if (typeof k?.token !== "string" || !TOKENISH.test(k.token))
+            throw new LoginError("Paperclip returned an invalid credential");
+        return { state: "created", keyId: typeof k.id === "string" && UUID.test(k.id) ? k.id : null, token: k.token, expiresAt: expiryOf(k.expiresAt) };
+    }
     /** Best effort: invalidate the board key we were issued when a grant is revoked. */
     async revoke(token) {
         try {

package/dist/oauth/pg-store.js

@@ -23,6 +23,7 @@ const toGrant = (r) => ({
     resource: r.resource,
     instanceUrl: r.instance_url,
     sealedCredential: r.sealed_credential,
+    credentialExpiresAt: r.credential_expires_at == null ? null : num(r.credential_expires_at),
     accountId: r.account_id ?? null,
     username: r.username ?? null,
     createdAt: num(r.created_at),
@@ -69,9 +70,9 @@ export class PgStore {
                order by last_used_at desc offset $2))`, [t - CLIENT_IDLE_MS, MAX_CLIENTS]);
     }
     async putGrant(g) {
-        await this.q(`insert into bridge.grants (id, client_id, client_name, user_id, scopes, resource, instance_url, sealed_credential, created_at, last_used_at, revoked, account_id, username)
-       values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13)
-       on conflict (id) do update set sealed_credential = excluded.sealed_credential, scopes = excluded.scopes, revoked = excluded.revoked, last_used_at = excluded.last_used_at`, [g.id, g.clientId, g.clientName, g.userId, g.scopes, g.resource, g.instanceUrl, g.sealedCredential, g.createdAt, g.lastUsedAt, g.revoked, g.accountId ?? null, g.username ?? null]);
+        await this.q(`insert into bridge.grants (id, client_id, client_name, user_id, scopes, resource, instance_url, sealed_credential, created_at, last_used_at, revoked, account_id, username, credential_expires_at)
+       values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14)
+       on conflict (id) do update set sealed_credential = excluded.sealed_credential, credential_expires_at = excluded.credential_expires_at, scopes = excluded.scopes, revoked = excluded.revoked, last_used_at = excluded.last_used_at`, [g.id, g.clientId, g.clientName, g.userId, g.scopes, g.resource, g.instanceUrl, g.sealedCredential, g.createdAt, g.lastUsedAt, g.revoked, g.accountId ?? null, g.username ?? null, g.credentialExpiresAt ?? null]);
     }
     async getGrant(id) {
         const r = await this.q("select * from bridge.grants where id = $1", [id]);
@@ -178,7 +179,7 @@ export class PgStore {
         return { id: x.id, username: x.username, usernameKey: x.username_key, secretHash: x.secret_hash, createdAt: num(x.created_at), lastLoginAt: x.last_login_at == null ? null : num(x.last_login_at), disabled: x.disabled, anonymous: !!x.anonymous, alias: x.alias ?? null, beta: !!x.beta, policy: x.policy ?? null };
     }
     static toLink(x) {
-        return { accountId: x.account_id, instanceUrl: x.instance_url, paperclipUserId: x.paperclip_user_id, sealedCredential: x.sealed_credential, createdAt: num(x.created_at), connectedAt: num(x.connected_at), lastUsedAt: num(x.last_used_at), instanceLabel: x.instance_label ?? null };
+        return { accountId: x.account_id, instanceUrl: x.instance_url, paperclipUserId: x.paperclip_user_id, sealedCredential: x.sealed_credential, credentialExpiresAt: x.credential_expires_at == null ? null : num(x.credential_expires_at), createdAt: num(x.created_at), connectedAt: num(x.connected_at), lastUsedAt: num(x.last_used_at), instanceLabel: x.instance_label ?? null };
     }
     async createAccount(a) {
         try {
@@ -283,8 +284,8 @@ export class PgStore {
     }
     async putLink(l) {
         try {
-            await this.q(`insert into bridge.account_links (account_id, instance_url, paperclip_user_id, sealed_credential, created_at, connected_at, last_used_at, instance_label) values ($1,$2,$3,$4,$5,$6,$7,$8)
-         on conflict (account_id) do update set instance_url = excluded.instance_url, paperclip_user_id = excluded.paperclip_user_id, sealed_credential = excluded.sealed_credential, connected_at = excluded.connected_at, last_used_at = excluded.last_used_at, instance_label = excluded.instance_label`, [l.accountId, l.instanceUrl, l.paperclipUserId, l.sealedCredential, l.createdAt, l.connectedAt, l.lastUsedAt, l.instanceLabel ?? null]);
+            await this.q(`insert into bridge.account_links (account_id, instance_url, paperclip_user_id, sealed_credential, created_at, connected_at, last_used_at, instance_label, credential_expires_at) values ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+         on conflict (account_id) do update set instance_url = excluded.instance_url, paperclip_user_id = excluded.paperclip_user_id, sealed_credential = excluded.sealed_credential, credential_expires_at = excluded.credential_expires_at, connected_at = excluded.connected_at, last_used_at = excluded.last_used_at, instance_label = excluded.instance_label`, [l.accountId, l.instanceUrl, l.paperclipUserId, l.sealedCredential, l.createdAt, l.connectedAt, l.lastUsedAt, l.instanceLabel ?? null, l.credentialExpiresAt ?? null]);
             return true;
         }
         catch (e) {
@@ -312,6 +313,18 @@ export class PgStore {
     async listIdleLinks(cutoff) {
         return (await this.q("select * from bridge.account_links where sealed_credential is not null and last_used_at < $1", [cutoff])).rows.map(PgStore.toLink);
     }
+    async listExpiringLinks(before) {
+        return (await this.q("select * from bridge.account_links where sealed_credential is not null and credential_expires_at < $1", [before])).rows.map(PgStore.toLink);
+    }
+    async listExpiringGrants(before) {
+        return (await this.q("select * from bridge.grants where not revoked and sealed_credential is not null and credential_expires_at < $1", [before])).rows.map(toGrant);
+    }
+    async swapCredential(h, expect, next, expiresAt) {
+        const sql = h.kind === "link"
+            ? "update bridge.account_links set sealed_credential = $3, credential_expires_at = $4 where account_id = $1 and sealed_credential = $2"
+            : "update bridge.grants set sealed_credential = $3, credential_expires_at = $4 where id = $1 and sealed_credential = $2 and not revoked";
+        return ((await this.q(sql, [h.id, expect, next, expiresAt])).rowCount ?? 0) === 1;
+    }
     async revokeAccountGrants(accountId) {
         const c = await this.pool.connect();
         try {

package/dist/oauth/provider.js

@@ -7,11 +7,11 @@ import { hostAllowed } from "../config.js";
 import { UnsafeUrlError, createSafeFetch, parseInstanceUrl } from "../net/safe-fetch.js";
 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 { LoginError, PAPERCLIP_KEY_TTL_MS, PaperclipLogin } from "./paperclip-login.js";
 import { parseAccountPolicy, parseSessionPolicy, readAccountPolicy, readSessionPolicy, surfaceOfTool } from "../access/policy.js";
 import { tools as ALL_TOOLS } from "../tools.js";
 import { VERSION } from "../version.js";
-import { MemoryStore } from "./store.js";
+import { MemoryStore, credentialExpiry } 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]"]);
 const PENDING_TTL_MS = 10 * 60_000;
@@ -28,6 +28,12 @@ const PLUGIN_KEY = "papercliped.remote-control";
 const PLUGIN_INSTALL_MS = 120_000;
 const MAX_FORM_BYTES = 16 * 1024;
 const DAY_MS = 24 * 3600 * 1000;
+/** Renew a stored Paperclip key this long before Paperclip expires it. */
+const ROTATE_BEFORE_MS = 7 * DAY_MS;
+/** After a rotation attempt, wait this long before trying that key again (shared across processes). */
+const ROTATE_RETRY_MS = 10 * 60_000;
+/** Revoke the replaced key only after this, so calls already under way with it (here or in another process) finish. */
+const ROTATE_GRACE_MS = 60_000;
 class OAuthError extends Error {
     code;
     status;
@@ -75,6 +81,10 @@ export class OAuthProvider {
     background = new Set();
     multi;
     accounts;
+    /** Key rotations under way in this process, by holder: callers wait for one instead of starting another. */
+    rotations = new Map();
+    /** Holder → when this process may try a failed rotation again. */
+    rotateRetryAt = new Map();
     constructor(deps) {
         this.deps = deps;
         this.now = deps.now ?? Date.now;
@@ -158,7 +168,8 @@ export class OAuthProvider {
     /** The Paperclip client for a grant. In account mode the credential and instance come from the account's link. */
     async resolveClient(grant) {
         if (!this.accounts || !grant.accountId) {
-            const apiKey = grant.sealedCredential ? this.keyring.unseal(grant.sealedCredential) : null;
+            const sealed = grant.sealedCredential ? await this.currentKey(this.heldOnGrant(grant, grant.sealedCredential)) : null;
+            const apiKey = sealed ? this.keyring.unseal(sealed) : null;
             if (!this.multi)
                 return { client: new PaperclipClient({ ...this.deps.config, apiKey }) };
             if (!grant.instanceUrl)
@@ -171,7 +182,7 @@ export class OAuthProvider {
             throw new ReconnectRequired("This account's Paperclip connection has expired; reconnect to continue.");
         const origin = this.checkedInstance(link.instanceUrl).origin; // re-validated on every use (policy can tighten)
         await this.store.touchLink(grant.accountId);
-        const apiKey = this.keyring.unseal(link.sealedCredential);
+        const apiKey = this.keyring.unseal(await this.currentKey(this.heldOnLink(link, link.sealedCredential)));
         return { client: new PaperclipClient({ ...this.deps.config, apiUrl: `${origin}/api`, apiKey, companyId: null }, this.safeFetch), instanceHost: link.instanceLabel ?? new URL(origin).host };
     }
     /** Convenience for callers that only need the client. */
@@ -201,22 +212,23 @@ export class OAuthProvider {
             /* instance no longer allowed / key gone: nothing more we can do */
         }
     }
-    /** Revoke idle grants and idle account connections, delete their stored credentials, prune telemetry. Run periodically. */
+    /** Revoke idle grants and idle account connections, delete their stored credentials, renew Paperclip keys close to expiry, prune telemetry. Run periodically. */
     async sweep() {
         const days = this.deps.oauth.idleRevokeDays;
         await this.store.prune();
-        if (!days)
-            return 0;
-        const cutoff = this.now() - days * DAY_MS;
         let n = 0;
-        const idle = await this.store.listIdleGrants(cutoff);
-        for (const g of idle)
-            await this.revokeGrant(g.id);
-        n += idle.length;
-        for (const l of await this.store.listIdleLinks(cutoff)) {
-            await this.dropConnection(l, "idle");
-            n += 1;
+        if (days) {
+            const cutoff = this.now() - days * DAY_MS;
+            const idle = await this.store.listIdleGrants(cutoff);
+            for (const g of idle)
+                await this.revokeGrant(g.id);
+            n += idle.length;
+            for (const l of await this.store.listIdleLinks(cutoff)) {
+                await this.dropConnection(l, "idle");
+                n += 1;
+            }
         }
+        await this.rotateExpiring();
         return n;
     }
     /** Forget an account's stored Paperclip credential (the username stays) and tell its Paperclip to revoke the key. */
@@ -237,6 +249,125 @@ export class OAuthProvider {
             /* best effort */
         }
     }
+    // ───────────── Paperclip key rotation ─────────────
+    // Paperclip expires the board keys it issues (30 days by default). Each stored key is renewed about a week before
+    // that: the old key asks Paperclip for a new one, the new one is swapped in only if the old one is still stored
+    // (compare-and-swap), and only then is the old one revoked. Any failure leaves the working key in place.
+    heldOnLink(l, sealed) {
+        return { kind: "link", id: l.accountId, instanceUrl: l.instanceUrl, sealed, expiresAt: credentialExpiry(l.credentialExpiresAt, l.connectedAt) };
+    }
+    heldOnGrant(g, sealed) {
+        return { kind: "grant", id: g.id, instanceUrl: g.instanceUrl, sealed, expiresAt: credentialExpiry(g.credentialExpiresAt, g.createdAt) };
+    }
+    /** The sealed key to call Paperclip with: the stored one, or its replacement when it was due and got renewed. */
+    async currentKey(k) {
+        if (k.expiresAt === null || k.expiresAt - this.now() > ROTATE_BEFORE_MS)
+            return k.sealed;
+        const slot = `${k.kind}:${k.id}`;
+        let run = this.rotations.get(slot);
+        if (!run) {
+            if ((this.rotateRetryAt.get(slot) ?? 0) > this.now())
+                return k.sealed;
+            run = this.rotate(k, slot).finally(() => this.rotations.delete(slot));
+            this.rotations.set(slot, run);
+        }
+        return (await run) ?? k.sealed;
+    }
+    /** Renew every stored key that expires within the rotation window, so keys of people who rarely call get renewed too. */
+    async rotateExpiring() {
+        const before = this.now() + ROTATE_BEFORE_MS;
+        for (const l of await this.store.listExpiringLinks(before))
+            if (l.sealedCredential)
+                await this.currentKey(this.heldOnLink(l, l.sealedCredential));
+        for (const g of await this.store.listExpiringGrants(before))
+            if (g.sealedCredential)
+                await this.currentKey(this.heldOnGrant(g, g.sealedCredential));
+    }
+    /** One rotation. Resolves to the new sealed key, or null to keep using the stored one. Never throws. */
+    async rotate(k, slot) {
+        let outcome = null;
+        let who = null;
+        try {
+            // One rotation per key across every process: whoever takes the claim does it; the others keep the old key, which still works.
+            if (!(await this.store.hit(`rotate:${slot}`, 1, ROTATE_RETRY_MS))) {
+                this.rotateRetryAt.set(slot, this.now() + ROTATE_RETRY_MS);
+                return null;
+            }
+            const token = this.keyring.unseal(k.sealed);
+            if (k.kind === "grant" && token === this.deps.config.apiKey) {
+                // The operator's own PAPERCLIP_API_KEY (bridge admin token sign-in): not ours to replace.
+                await this.store.swapCredential(k, k.sealed, k.sealed, null);
+                return null;
+            }
+            let name = "Papercliped";
+            if (k.kind === "link") {
+                const a = await this.store.getAccount(k.id);
+                if (a)
+                    name = `Papercliped (${a.username})`;
+                who = a ? { accountId: a.id, username: displayName(a) } : { accountId: k.id, username: "" };
+            }
+            else {
+                const g = await this.store.getGrant(k.id);
+                if (g)
+                    name = `Papercliped (${g.username ?? g.clientName})`;
+                who = g ? { accountId: g.accountId ?? null, username: g.username ?? null } : null;
+            }
+            const login = this.loginFor(k.instanceUrl);
+            outcome = "failed";
+            const info = await login.keyInfo(token);
+            if (info.state === "unsupported" || info.expiresAt === null) {
+                // Older Paperclip, or a key that never expires: nothing to renew, now or later.
+                outcome = null;
+                await this.store.swapCredential(k, k.sealed, k.sealed, null);
+                return null;
+            }
+            if (info.expiresAt !== undefined && info.expiresAt - this.now() > ROTATE_BEFORE_MS) {
+                outcome = null; // the stored expiry was an estimate; Paperclip's own is later
+                await this.store.swapCredential(k, k.sealed, k.sealed, info.expiresAt);
+                return null;
+            }
+            const made = await login.createKey(token, name);
+            if (made.state === "unsupported") {
+                outcome = null;
+                await this.store.swapCredential(k, k.sealed, k.sealed, null);
+                return null;
+            }
+            const next = this.keyring.seal(made.token);
+            if (!(await this.store.swapCredential(k, k.sealed, next, made.expiresAt === undefined ? this.now() + PAPERCLIP_KEY_TTL_MS : made.expiresAt))) {
+                // Reconnected, rotated elsewhere or disconnected meanwhile: what is stored now wins; drop the key we just made.
+                outcome = null;
+                await login.revoke(made.token);
+                return null;
+            }
+            outcome = "rotated";
+            this.revokeReplaced(login, token);
+            return next;
+        }
+        catch (e) {
+            outcome = "failed";
+            this.rotateRetryAt.set(slot, this.now() + ROTATE_RETRY_MS);
+            // Paperclip no longer accepts this key (expired or revoked): it can never be renewed, so stop trying. Using it
+            // still gets the reconnect hint, and reconnecting stores a fresh key with a fresh expiry.
+            if (e instanceof LoginError && e.status === 401)
+                await this.store.swapCredential(k, k.sealed, k.sealed, null).catch(() => false);
+            return null;
+        }
+        finally {
+            if (outcome)
+                await this.event("key", who, outcome);
+        }
+    }
+    /** Revoke a key that rotation replaced, after a grace period for calls still using it. Best effort: it expires on its own anyway. */
+    revokeReplaced(login, token) {
+        const grace = this.deps.rotationGraceMs ?? ROTATE_GRACE_MS;
+        if (grace <= 0) {
+            const run = login.revoke(token);
+            const tracked = run.finally(() => this.background.delete(tracked));
+            this.background.add(tracked);
+            return;
+        }
+        setTimeout(() => void login.revoke(token), grace).unref();
+    }
     // ───────────── account management (the Paperclip plugin's connection manager) ─────────────
     // Everything here acts on ONE account and is reached only through ManageRoutes, with a plugin token or the secret key.
     /** Username + secret key, throttled exactly like the sign-in page (shared counters, so there is no cheaper way to guess). */
@@ -918,7 +1049,7 @@ export class OAuthProvider {
         const t = this.now();
         const acct = await this.store.getAccount(accountId);
         const instanceLabel = acct ? this.instanceLabelFor(acct, instanceUrl, old) : new URL(instanceUrl).host;
-        const ok = await this.store.putLink({ accountId, instanceUrl, paperclipUserId, sealedCredential: this.keyring.seal(credential), createdAt: old?.createdAt ?? t, connectedAt: t, lastUsedAt: t, instanceLabel });
+        const ok = await this.store.putLink({ accountId, instanceUrl, paperclipUserId, sealedCredential: this.keyring.seal(credential), credentialExpiresAt: t + PAPERCLIP_KEY_TTL_MS, createdAt: old?.createdAt ?? t, connectedAt: t, lastUsedAt: t, instanceLabel });
         if (ok && old?.sealedCredential) {
             let same = false;
             try {
@@ -1163,7 +1294,7 @@ export class OAuthProvider {
         }
         if (!created)
             return this.renderStage(res, rid, p, "Could not reserve an anonymous name right now. Please try again.", { value: typed });
-        const linked = await this.store.putLink({ accountId: account.id, instanceUrl: p.instanceUrl, paperclipUserId: p.paperclipUserId, sealedCredential: this.keyring.seal(ch.boardApiToken), createdAt: t, connectedAt: t, lastUsedAt: t, instanceLabel: this.instanceLabelFor(account, p.instanceUrl) });
+        const linked = await this.store.putLink({ accountId: account.id, instanceUrl: p.instanceUrl, paperclipUserId: p.paperclipUserId, sealedCredential: this.keyring.seal(ch.boardApiToken), credentialExpiresAt: t + PAPERCLIP_KEY_TTL_MS, createdAt: t, connectedAt: t, lastUsedAt: t, instanceLabel: this.instanceLabelFor(account, p.instanceUrl) });
         if (!linked) {
             await this.store.deleteAccount(account.id); // lost a race for this Paperclip identity
             p.stage = "choose";
@@ -1291,6 +1422,8 @@ export class OAuthProvider {
             resource: this.resource,
             instanceUrl: entry.instanceUrl,
             sealedCredential: entry.sealedCredential,
+            // A key from an approved sign-in expires with Paperclip's default; the operator's own PAPERCLIP_API_KEY is never rotated.
+            credentialExpiresAt: entry.sealedCredential && this.keyring.unseal(entry.sealedCredential) !== this.deps.config.apiKey ? t + PAPERCLIP_KEY_TTL_MS : null,
             accountId: entry.accountId ?? null,
             username: entry.username ?? null,
             createdAt: t,

package/dist/oauth/store.js

@@ -1,7 +1,12 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { AliasTakenError } from "../accounts/types.js";
+import { PAPERCLIP_KEY_TTL_MS } from "./paperclip-login.js";
 import { HIST_EDGES, isFault } from "../telemetry/types.js";
+/** A stored credential's expiry; old rows without one are assumed to carry Paperclip's default TTL from `issuedAt`. */
+export function credentialExpiry(expiresAt, issuedAt) {
+    return expiresAt === undefined ? issuedAt + PAPERCLIP_KEY_TTL_MS : expiresAt;
+}
 const MAX_USER_EVENTS = 20_000;
 const MAX_CLIENTS = 1000;
 const CLIENT_IDLE_MS = 7 * 24 * 3600 * 1000;
@@ -134,6 +139,21 @@ export class MemoryStore {
     async listIdleGrants(cutoff) {
         return Object.values(this.d.grants).filter((g) => !g.revoked && g.lastUsedAt < cutoff);
     }
+    async listExpiringGrants(before) {
+        return Object.values(this.d.grants).filter((g) => {
+            const exp = g.sealedCredential && !g.revoked ? credentialExpiry(g.credentialExpiresAt, g.createdAt) : null;
+            return exp !== null && exp < before;
+        });
+    }
+    async swapCredential(h, expect, next, expiresAt) {
+        const row = h.kind === "link" ? this.lnks[h.id] : this.d.grants[h.id];
+        if (!row || row.sealedCredential !== expect || (h.kind === "grant" && row.revoked))
+            return false;
+        row.sealedCredential = next;
+        row.credentialExpiresAt = expiresAt;
+        this.save();
+        return true;
+    }
     async putAccess(hash, r) {
         this.d.access[hash] = r;
         this.save();
@@ -358,6 +378,12 @@ export class MemoryStore {
     async listIdleLinks(cutoff) {
         return Object.values(this.lnks).filter((l) => l.sealedCredential && l.lastUsedAt < cutoff);
     }
+    async listExpiringLinks(before) {
+        return Object.values(this.lnks).filter((l) => {
+            const exp = l.sealedCredential ? credentialExpiry(l.credentialExpiresAt, l.connectedAt) : null;
+            return exp !== null && exp < before;
+        });
+    }
     async revokeAccountGrants(accountId) {
         let n = 0;
         for (const g of Object.values(this.d.grants)) {

package/dist/web/routes.js

@@ -7,7 +7,7 @@ const PROTOCOL = /^\/(mcp|actions\/|openapi\.json$|register$|authorize|token$|re
 const TYPES = {
     ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".json": "application/json",
     ".svg": "image/svg+xml", ".png": "image/png", ".ico": "image/x-icon", ".woff2": "font/woff2", ".xml": "application/xml; charset=utf-8",
-    ".txt": "text/plain; charset=utf-8", ".md": "text/plain; charset=utf-8", ".webmanifest": "application/manifest+json",
+    ".txt": "text/plain; charset=utf-8", ".md": "text/plain; charset=utf-8", ".webmanifest": "application/manifest+json", ".zip": "application/zip",
 };
 const HEADERS = { "X-Content-Type-Options": "nosniff", "Referrer-Policy": "strict-origin-when-cross-origin", "X-Frame-Options": "DENY" };
 /**

package/docs/LAUNCH-KIT.md

@@ -0,0 +1,133 @@
+# Launch kit
+
+Everything for the public launch: what must be true first, how to get the first testers, where to post, and copy you can paste. Assets are in the [icon pack](../web/public/brand/papercliped-icons.zip) (also at papercliped.co/brand). For deploying the service, see [LAUNCH.md](LAUNCH.md).
+
+## 1. Before launch day
+
+| | Check | How |
+| --- | --- | --- |
+| ☐ | The latest release is live | `https://mcp.papercliped.co/api/public/v1/info` shows the version in `package.json`; papercliped.co/prompts and docs.papercliped.co/hosting load. If not, Render → **Manual Deploy → Deploy latest commit**. |
+| ☐ | Connections survive past 30 days | Paperclip expires approved keys after 30 days; the bridge renews each key a week before (v2.5.1). Run the `008_key_rotation.sql` migration (`npm run migrate`) on the production database when deploying it. |
+| ☐ | A full run-through on a fresh Paperclip | Follow [Host your Paperclip](https://docs.papercliped.co/hosting) start to finish on one guide (Railway or a VPS), connect Claude **and** ChatGPT, run five prompts from the gallery, flip the access switch in the control room. Fix anything that trips you up. |
+| ☐ | Discord and X exist | Create them with the icon pack (below), then set `VITE_DISCORD_URL` / `VITE_X_URL` on Render and rebuild. Set up Discord per [COMMUNITY.md](COMMUNITY.md), plus a `#testers` channel. |
+| ☐ | GitHub is launch-ready | Turn on Discussions, set the repository social preview to `social-light-1200x630.png`, pin a "Start here" discussion, add topics: `mcp`, `paperclip`, `ai-agents`, `claude`, `chatgpt`, `codex`, `mcp-server`. |
+| ☐ | A 60-second demo video | Script in section 6. Every post below uses it. |
+| ☐ | Baseline numbers | Note users and connections on papercliped.co/status, so you can tell which post worked. |
+
+### Which icon goes where
+
+| Place | File |
+| --- | --- |
+| Discord server icon, X / GitHub / npm profile picture, directory listings | `avatar-light-1024.png` (`avatar-dark-*` on dark themes) |
+| X header | `x-header-light-1500x500.png` |
+| Discord server banner, YouTube thumbnail base, Product Hunt gallery | `banner-light-960x540.png` |
+| GitHub social preview, link previews | `social-light-1200x630.png` |
+| App icon where a rounded tile fits (Product Hunt logo, docs, slides) | `icon-light-512.png` or `icon-light.svg` |
+
+## 2. The first testers ("founding operators")
+
+Aim for **20–50 people who already run Paperclip** before the big public posts. They find the setup problems, and their quotes become your social proof.
+
+**Where to find them**
+1. **Paperclip's Discord** (linked from Paperclip's README). Ask a moderator first where community projects may be shared; then post the tester call below.
+2. **Replies on X** to people posting about Paperclip: a short, personal reply with the demo, not a link dump.
+3. **Your own network** and anyone who has starred or forked Paperclip and posts about AI agents.
+
+**What they get**
+- A **Founding operator** role in Discord and a `#testers` channel with direct access to the maintainers.
+- Their name in the release notes and a thanks section in the README (only if they want it).
+- Fixes within days: every reported setup problem gets a patch release.
+
+**What they do (20 minutes)**
+1. Pick a hosting guide and get their Paperclip public (or use the one they have).
+2. Connect one AI app with **Full control**.
+3. Run five prompts from the gallery: *Morning catch-up*, *Give an agent a task*, *Wake and wait*, *What's waiting* (approvals), *Weekly review*.
+4. Open the control room in Paperclip and switch to **Agent only**, then ask the AI to pause an agent (it should refuse and say why).
+5. Fill in the **Tester feedback** form: GitHub → Issues → New issue → *Tester feedback*.
+
+**Tester call (paste in Discord / DMs)**
+> Looking for 20 Paperclip operators to try **Papercliped** before launch: free and open source, it lets you run your Paperclip from Claude, ChatGPT or Codex by just asking ("catch me up", "give the Web Engineer this task and wake them", "approve the hire"). Takes about 20 minutes. You get a Founding operator role, direct line to us, and fixes within days. Interested? Reply or DM me. 🧷
+
+## 3. Where to promote, in order
+
+| # | Channel | When | Notes |
+| --- | --- | --- | --- |
+| 1 | Paperclip Discord | Testers week, then launch day | The highest-intent audience there is. Follow their rules. |
+| 2 | X | Launch day, then daily | Thread + demo. Tag Paperclip's account. One gallery prompt a day afterwards, with a short clip. |
+| 3 | MCP directories | Launch week | Section 5. Permanent traffic from people searching for connectors. |
+| 4 | Anthropic's connector directory and Claude Code plugin listings | Launch week | Puts Papercliped inside Claude's own UI. |
+| 5 | Show HN | A weekday, 8–10am US Eastern | Stay and answer every comment for the first 3 hours. |
+| 6 | Reddit | Spread over a week | r/ClaudeAI, r/ChatGPT, r/selfhosted (lead with the hosting guides), r/AI_Agents, r/mcp. Different text per sub; read each sub's self-promotion rules first. |
+| 7 | dev.to / Hashnode | Launch week | Cross-post one hosting guide each ("Host Paperclip on Railway in 15 minutes") with a canonical link to the docs. These rank in search for a long time. |
+| 8 | Product Hunt | 2–4 weeks after launch | Once Discord is active and you have tester quotes. |
+| 9 | Paperclip's docs or README | After launch | Ask the Paperclip maintainers to list Papercliped as a community integration. |
+
+## 4. Copy
+
+**One-liner:** Run your Paperclip from Claude, ChatGPT or Codex: just ask.
+
+**Short description (directories, 160 chars):** Free, open-source MCP connector for Paperclip. Manage agents, issues, approvals, budgets and reports from Claude, ChatGPT, Codex or any MCP app.
+
+**Long description**
+> Papercliped connects Claude, ChatGPT, Codex and any MCP app to your Paperclip, the open-source orchestrator for companies of AI agents. Instead of clicking through the dashboard, ask: "Catch me up", "Give the Web Engineer this task and wake them", "Approve the hire", "Weekly cost report". You approve every connection inside your own Paperclip, choose Read only or Full control, and decide in the control room whether AI apps control Paperclip directly, work through agents, or both — per agent if you like. 30 tools, ready-made reports, 40+ prompts to copy, and step-by-step guides to host Paperclip at home, on a VPS, Railway, Render, Fly.io or Coolify. Free and MIT licensed.
+
+**X thread**
+1. Running a company of AI agents on Paperclip? Now you can run it from Claude, ChatGPT or Codex. Just ask. 🧷 Papercliped is free and open source. [demo video]
+2. "Catch me up on my Paperclip." "Give the Web Engineer this task and wake them." "Approve the hire." "Weekly cost report." 40+ ready-to-copy prompts → papercliped.co/prompts
+3. You stay in control: approve every connection inside your own Paperclip, pick Read only or Full control, and set per-agent rules in the control room.
+4. No public Paperclip yet? Step-by-step guides for your own computer (free tunnel), a VPS, Railway, Render, Fly.io and Coolify → docs.papercliped.co/hosting
+5. Connect: paste https://mcp.papercliped.co/mcp into your AI app. Code: github.com/OpenSourcx/papercliped ⭐
+
+**Show HN**
+- Title: `Show HN: Papercliped – run your AI agent company from Claude or ChatGPT (open source)`
+- URL: the GitHub repository.
+- First comment:
+> Hi HN! Paperclip is an open-source orchestrator where you run a "company" of AI agents (CEO, engineers, budgets, approvals). I kept opening its dashboard to do small things, so I built Papercliped: an MCP server that lets Claude, ChatGPT, Codex or any MCP client operate it in plain language.
+>
+> How it works: you add one connector URL, approve the sign-in inside your own Paperclip (no passwords pass through), and pick Read only or Full control. A control room inside Paperclip decides per agent whether AI apps may control it directly, only hand it work, or not see it at all. Every call is checked and audit-logged; Paperclip keys are encrypted at rest.
+>
+> It's MIT licensed, hosted for free, and you can self-host the bridge or run it locally with `npx papercliped`. I'd love feedback on the permission model and on what you'd want to ask your agents.
+
+**Reddit (r/selfhosted angle)**
+> **I wrote step-by-step guides for hosting Paperclip (AI agent orchestrator) on a VPS, Railway, Render, Fly.io, Coolify or at home with a tunnel** — official Docker image, persistent disk, first-admin setup, backups. They end with connecting it to Claude/ChatGPT through Papercliped, the open-source MCP bridge I maintain, but the hosting part stands on its own: docs.papercliped.co/hosting. Corrections welcome.
+
+## 5. Directories
+
+Submit the short and long descriptions above, the avatar icon, the banner, the connector URL `https://mcp.papercliped.co/mcp` (Streamable HTTP, OAuth) and the repository URL. Check each site's current submission steps.
+
+- **Official MCP Registry** (registry.modelcontextprotocol.io): published with its `mcp-publisher` tool from a `server.json`; lists remote servers and npm packages (`papercliped`).
+- **Smithery**, **Glama**, **PulseMCP**, **mcp.so**: submit forms or GitHub-based listings.
+- **awesome-mcp-servers** lists on GitHub: a one-line pull request under the right category.
+- **Anthropic's connector directory** and the **Claude Code plugin** listings: the plugin marketplace is already in this repository (`.claude-plugin/marketplace.json`).
+- **Codex plugin** listings, if a public directory exists; the marketplace is in `.agents/plugins/marketplace.json`.
+
+## 6. Demo video (60 seconds)
+
+Screen-record at 1080p, split screen: AI app on the left, Paperclip dashboard on the right. No music needed; captions on.
+
+1. (0–5 s) Title card: the banner image. Caption: *Run your Paperclip from any AI app.*
+2. (5–20 s) Type *"Catch me up on my Paperclip."* Show the answer.
+3. (20–40 s) *"Give the Web Engineer an issue to fix the signup page, wake them, and tell me when they're done."* Show the issue appear and the agent start in Paperclip.
+4. (40–50 s) *"Approve the hire request."* The approval flips in the dashboard.
+5. (50–60 s) Control room: flip the switch to **Agent only**. End card: `papercliped.co · free and open source`.
+
+Record a vertical 30-second cut of steps 2–4 for X and short-video platforms.
+
+## 7. Launch day
+
+| Time (US Eastern) | Do |
+| --- | --- |
+| Day before | Final run-through; status page green; release notes up; demo uploaded. |
+| 8:00 | Show HN post + first comment. |
+| 8:15 | X thread; post in Paperclip's Discord; announce in your own Discord. |
+| 8:30–12:00 | Answer every comment and question. Log every setup problem as an issue. |
+| 12:00 | First Reddit post. |
+| Evening | Patch release for anything found today. Thank testers publicly. |
+| Next 7 days | One Reddit sub per day, one gallery prompt per day on X, directories submitted, one dev.to guide. |
+
+## 8. Measure
+
+- **papercliped.co/status**: users, connections, sign-in success and errors. Check daily for two weeks and note which post ran the day before.
+- **GitHub**: stars, traffic (Insights → Traffic → referring sites), issues labelled `feedback`.
+- **npm**: weekly downloads of `papercliped` and `papercliped-paperclip-plugin`.
+- **Sign-in failures** on the status page are setup problems: each one is a docs fix waiting to happen.

package/docs/supabase-schema.sql

@@ -285,6 +285,23 @@ 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';
 
+-- ───── 008_key_rotation.sql ─────
+-- Paperclip key rotation: Paperclip expires the board keys it issues (30 days by default), so the bridge renews
+-- each stored key about a week before it lapses. credential_expires_at is when Paperclip expires the stored key
+-- (ms epoch); null = it never expires (older Paperclip, or a key Paperclip did not issue us), so it is never rotated.
+alter table bridge.account_links add column if not exists credential_expires_at bigint;
+alter table bridge.grants        add column if not exists credential_expires_at bigint;
+
+-- Keys stored before this migration came from an approved sign-in: assume Paperclip's default 30 days from then.
+-- The first rotation check reads the real expiry from Paperclip and corrects it (or clears it if the key never expires).
+update bridge.account_links set credential_expires_at = connected_at + 2592000000
+ where sealed_credential is not null and credential_expires_at is null;
+update bridge.grants set credential_expires_at = created_at + 2592000000
+ where sealed_credential is not null and not revoked and credential_expires_at is null;
+
+create index if not exists account_links_expiry_idx on bridge.account_links (credential_expires_at) where sealed_credential is not null;
+create index if not exists grants_expiry_idx on bridge.grants (credential_expires_at) where sealed_credential is not null and not revoked;
+
 -- ───── 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;
@@ -294,6 +311,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'), ('007_control_room.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'), ('008_key_rotation.sql') on conflict (version) do nothing;
 
 commit;

package/migrations/008_key_rotation.sql

@@ -0,0 +1,15 @@
+-- Paperclip key rotation: Paperclip expires the board keys it issues (30 days by default), so the bridge renews
+-- each stored key about a week before it lapses. credential_expires_at is when Paperclip expires the stored key
+-- (ms epoch); null = it never expires (older Paperclip, or a key Paperclip did not issue us), so it is never rotated.
+alter table bridge.account_links add column if not exists credential_expires_at bigint;
+alter table bridge.grants        add column if not exists credential_expires_at bigint;
+
+-- Keys stored before this migration came from an approved sign-in: assume Paperclip's default 30 days from then.
+-- The first rotation check reads the real expiry from Paperclip and corrects it (or clears it if the key never expires).
+update bridge.account_links set credential_expires_at = connected_at + 2592000000
+ where sealed_credential is not null and credential_expires_at is null;
+update bridge.grants set credential_expires_at = created_at + 2592000000
+ where sealed_credential is not null and not revoked and credential_expires_at is null;
+
+create index if not exists account_links_expiry_idx on bridge.account_links (credential_expires_at) where sealed_credential is not null;
+create index if not exists grants_expiry_idx on bridge.grants (credential_expires_at) where sealed_credential is not null and not revoked;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.4.2",
+  "version": "2.5.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/chatgpt.md

@@ -1,5 +1,16 @@
 # ChatGPT setup
 
+There are two ways. The MCP connector is quicker and gives ChatGPT every tool; GPT Actions works on plans without developer mode.
+
+## Option 1: MCP connector (recommended)
+1. In ChatGPT open **Settings → Apps → Advanced settings** and turn on **Developer mode** (your plan and workspace must allow it).
+2. Choose **Create app** (or **Add connector**), name it Papercliped, and use the address `{{MCP}}/mcp` with **OAuth** sign-in.
+3. ChatGPT opens the Papercliped sign-in: choose **Connect your Paperclip**, approve in your Paperclip, and pick **Read only** or **Full control**.
+4. In a new chat, turn the Papercliped app on from the tools menu and ask *"Catch me up on my Paperclip."*
+
+ChatGPT renames these menus often. If yours look different, search ChatGPT's help for "developer mode" or "custom connectors".
+
+## Option 2: a custom GPT with Actions
 Requires a ChatGPT plan that can create GPTs with Actions.
 
 1. Create a GPT, then **Configure → Create new action**.

package/site/docs/faq.md

@@ -25,7 +25,7 @@ Newer Paperclip versions include an experimental, off-by-default MCP endpoint fo
 Yes: run it locally with `npx papercliped@latest`. The hosted bridge needs a public https address; see [Host your Paperclip](/docs/hosting).
 
 ## Why does pausing an agent fail with 403?
-Pause, resume, wake and approve need a Paperclip **board** token, and a connection at **Full control**. Check your level in the [Paperclip plugin](/docs/paperclip-plugin).
+Pause, resume, wake and approve need a connection at **Full control**, and an [access mode](/docs/access-modes) that allows them: pausing and approvals are *direct control* (blocked in Agent only), waking is *work through agents* (blocked in API only). A blocked call names the setting to change; check it in the [control room](/docs/control-room).
 
 ## Why was a call blocked, or a tool missing?
 Your own settings. Open **Papercliped** in Paperclip: the switch (API only, Full, Agent only), an agent's setting, or the session's tool and agent lists decide what an AI app may do, and **Activity** shows each blocked call and the reason. See [API only, Full or Agent only](/docs/access-modes).
@@ -34,7 +34,7 @@ Your own settings. Open **Papercliped** in Paperclip: the switch (API only, Full
 Yes. In the [control room](/docs/control-room), open **Agents** and set it to **Off**: AI apps can't see it, touch it, or see what's assigned to it.
 
 ## How do I stop it?
-Disconnect the app on the manage page, revoke the key in your Paperclip, or delete your account. It stops at once.
+Disconnect the session in the [control room](/docs/control-room), revoke the key in your Paperclip, or delete your account. It stops at once.
 
 ## I lost my secret key.
 Choose **Connect your Paperclip** when signing in and approve in Paperclip: you keep your account and can make a new key.

package/site/docs/getting-started.md

@@ -1,18 +1,18 @@
 # Getting started
 
-Papercliped connects Claude (and ChatGPT) to **your** Paperclip. You keep control: you choose how much the AI may do, and you can cut access at any time.
+Papercliped connects Claude, ChatGPT, Codex and any MCP app to **your** Paperclip, so you can run it by asking instead of clicking through the dashboard. You keep control: you choose how much the AI may do, and you can cut access at any time.
 
 ## What you need
 - A Paperclip that is reachable over the internet at an `https://` address (for example `https://workforce.example.com`). Private, local and `http://` addresses are refused on purpose. No public address yet? See [Host your Paperclip](/docs/hosting).
-- A Claude account that can add connectors, or Claude Code.
+- An AI app that can add a remote MCP server: Claude (web, desktop or mobile), Claude Code, ChatGPT, Codex, or [another app](/docs/other-ai-apps).
 
 ## Connect from Claude
 1. In Claude open **Settings → Connectors → Add custom connector**.
 2. Use the address `{{MCP}}/mcp` and click **Connect**.
 3. On the Papercliped page choose **Connect your Paperclip**, enter your Paperclip's address, and approve the request in your Paperclip.
 4. Pick a **username** (see below). Papercliped then shows your **secret key once**. Save it in a password manager.
-5. Choose how much to allow (see [Permissions](/docs/permissions)) and click **Allow**.
-6. Ask Claude something like "List my Paperclip agents."
+5. Choose how much to allow (see [Permissions](/docs/permissions)) and click **Allow**. Leave **Also install the Papercliped plugin** ticked to get the [control room](/docs/control-room) inside your Paperclip.
+6. Ask Claude something like *"Catch me up on my Paperclip."* Then try more from the [prompt gallery](/docs/prompts).
 
 ## Claude Code
 ```
@@ -20,6 +20,13 @@ claude mcp add --transport http papercliped {{MCP}}/mcp
 ```
 Or install the plugin: `/plugin marketplace add OpenSourcx/papercliped`, then `/plugin install papercliped@papercliped`.
 
+## Codex
+```
+codex plugin marketplace add OpenSourcx/papercliped
+codex plugin add papercliped@papercliped
+```
+Or just the MCP server: `codex mcp add paperclip --url {{MCP}}/mcp`.
+
 ## Run it yourself (npm)
 ```
 npx papercliped@latest
@@ -33,7 +40,7 @@ Any app that supports MCP can use Papercliped. See [Any AI app (MCP)](/docs/othe
 The Papercliped plugin for Paperclip is where you manage everything: the [control room](/docs/control-room) for connected apps, what each may do and which agents it applies to, plus privacy and your account. See [Paperclip plugin](/docs/paperclip-plugin).
 
 ## ChatGPT
-Papercliped publishes an OpenAPI description at `{{MCP}}/openapi.json` for GPT Actions. See [ChatGPT setup](/docs/chatgpt).
+Add Papercliped as an MCP app in developer mode, or build a custom GPT with Actions. See [ChatGPT setup](/docs/chatgpt).
 
 See [Create your account](/docs/signup) for every screen in detail.
 

package/site/docs/other-ai-apps.md

@@ -11,6 +11,28 @@ The app opens the Papercliped sign-in page. Choose **Connect your Paperclip** (o
 
 Where the setting lives differs per app (often "Connectors", "MCP servers" or "Tools"). Check your app's own docs for the menu.
 
+## Claude Code
+Install the plugin (adds the tools, a Paperclip skill and the `/paperclip-status`, `/paperclip-sync` and `/paperclip-report` commands):
+```
+/plugin marketplace add OpenSourcx/papercliped
+/plugin install papercliped@papercliped
+```
+Or add just the MCP server, then run `/mcp` to sign in:
+```
+claude mcp add --transport http paperclip {{MCP}}/mcp
+```
+
+## Codex
+Install the plugin:
+```
+codex plugin marketplace add OpenSourcx/papercliped
+codex plugin add papercliped@papercliped
+```
+Or add just the MCP server (Codex starts the sign-in for you):
+```
+codex mcp add paperclip --url {{MCP}}/mcp
+```
+
 ## Apps that only run local MCP servers
 Run Papercliped on your own computer instead. It talks straight to your Paperclip, with no account needed:
 ```
@@ -25,4 +47,4 @@ Self-host the bridge with a static key (`BRIDGE_TOKEN`) and send it as `Authoriz
 Use the custom MCP connector where your plan offers it, or GPT Actions with `{{MCP}}/openapi.json`. See [ChatGPT setup](/docs/chatgpt).
 
 ## What every app gets
-The same tools everywhere: list and control agents, issues, goals and approvals, sync what changed, and reports on status, costs, agent performance and activity. What an app may change depends on the level you chose; you can change it at any time on the [manage page]({{URL}}/manage).
+The same tools everywhere: list and control agents, issues, goals and approvals, sync what changed, and reports on status, costs, agent performance and activity. What an app may change depends on the level you chose and your [access mode](/docs/access-modes); change either at any time in the [control room](/docs/control-room) inside your Paperclip. Not sure what to ask? Try the [prompt gallery](/docs/prompts).

package/site/docs/security.md

@@ -14,6 +14,7 @@ What Papercliped does to protect you, and what it cannot.
 - **OAuth 2.1 with PKCE**, short-lived access tokens, rotating refresh tokens with reuse detection.
 - **Rate limits** on sign-in, secret-key attempts and tool calls.
 - **A separate operator dashboard** (an access-controlled service, not part of the open-source bridge) reads the database through a read-only role that can see only safe views: never your key, secret hash or an anonymous account's real name.
+- **Keys are renewed, not made permanent.** Paperclip expires the keys it issues (30 days on newer versions). About a week before that, Papercliped asks Paperclip for a fresh key with the same expiry, stores it encrypted, and revokes the old one. It never asks for a key that doesn't expire. In Paperclip the key is named "Papercliped (your username)". If renewal fails, the current key keeps working and Papercliped tries again later.
 - Revocation is immediate on disconnect, and idle keys are removed after 30 days.
 
 ## What it cannot do

package/site/docs/troubleshooting.md

@@ -4,7 +4,7 @@
 
 **"This hostname is not allowed for this Paperclip instance."** Paperclip doesn't recognise the address. Set `PAPERCLIP_DEPLOYMENT_EXPOSURE=public` and `PAPERCLIP_PUBLIC_URL` to exactly the address you use, then restart Paperclip. See [What every option needs](/docs/hosting#what-every-option-needs).
 
-**It stopped working after about a month.** Newer Paperclip versions make keys approved through the sign-in prompt expire after 30 days. When the AI says the Paperclip credential was rejected, disconnect and connect again from your AI app, then approve in Paperclip.
+**"The Paperclip credential behind this connection was rejected."** Newer Paperclip versions expire keys after 30 days. Papercliped renews yours automatically about a week before that, so this should not happen on its own. It does if the key was revoked in Paperclip, the renewal kept failing until the key expired (for example, Paperclip was unreachable that whole week), or your Paperclip account lost access. Disconnect and connect again from your AI app, then approve in Paperclip.
 
 **Agents stop mid-task now and then.** Something restarted Paperclip: an update, a redeploy, or a host that sleeps. Runs in progress end on every restart. Use an always-on host and update when agents are idle.
 

package/site/docs/what-is-papercliped.md

@@ -1,6 +1,6 @@
 # What is Papercliped?
 
-Papercliped connects AI apps (Claude, ChatGPT and anything that speaks MCP) to **your** Paperclip, so you can run your AI-agent company by asking: "What are my agents doing?", "Pause the one that's over budget", "Give me this week's costs."
+Papercliped connects AI apps (Claude, ChatGPT, Codex and anything that speaks MCP) to **your** Paperclip, so you can run your AI-agent company by asking: "What are my agents doing?", "Pause the one that's over budget", "Give me this week's costs."
 
 Paperclip is an open-source orchestrator for companies of AI agents. Papercliped is an independent, open-source project (MIT); it isn't made by the Paperclip team.
 
@@ -34,4 +34,6 @@ See the [tool reference](/docs/tools) for all of them.
 - **Account**: your Papercliped username and secret key, used to sign in again and manage connections.
 - **Secret key**: a key starting with `pcs_`, shown once; Papercliped keeps only a one-way hash.
 - **Board token**: a Paperclip credential with operator rights. Papercliped stores it encrypted and only uses it within your level.
-- **Connection manager**: the [Paperclip plugin](/docs/paperclip-plugin), where you change levels, disconnect apps and manage your account.
+- **Control room**: the Papercliped page inside your Paperclip (from the [Paperclip plugin](/docs/paperclip-plugin)), where you manage sessions, access modes, agents and your account. See [The control room](/docs/control-room).
+- **Session**: one connected AI app. You can name it, change its level, and limit it to some tools or agents.
+- **Access mode**: API only, Full or Agent only: whether AI apps control Paperclip directly, work through agents, or both. See [Access modes](/docs/access-modes).