papercliped 2.4.2 → 2.5.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "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,12 @@
 
 ## Unreleased
 
+## 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/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; ship key rotation before inviting people, or every tester drops off a month later. |
+| ☐ | 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/package.json

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