papercliped 1.1.0-beta.2 → 2.1.0

package/.claude-plugin/marketplace.json

@@ -1,11 +1,14 @@
-{
-  "name": "papercliped",
-  "owner": { "name": "KpnWorld" },
-  "plugins": [
-    {
-      "name": "papercliped",
-      "source": "./",
-      "description": "Control Paperclip agents, sync with them, and pull reports from Claude."
-    }
-  ]
-}
+{
+  "name": "papercliped",
+  "owner": {
+    "name": "KpnWorld"
+  },
+  "plugins": [
+    {
+      "name": "papercliped",
+      "source": "./",
+      "description": "Run your Paperclip from Claude: control agents, sync with them and get reports, at the access level you choose."
+    }
+  ],
+  "description": "Papercliped: run your Paperclip from Claude Code."
+}

package/.claude-plugin/plugin.json

@@ -1,8 +1,17 @@
-{
-  "name": "papercliped",
-  "version": "1.0.0-beta.1",
-  "description": "Control Paperclip agents, sync with them, and pull reports from Claude.",
-  "author": { "name": "KpnWorld" },
-  "license": "MIT",
-  "keywords": ["paperclip", "agents", "orchestration", "mcp"]
-}
+{
+  "name": "papercliped",
+  "version": "2.1.0",
+  "description": "Run your Paperclip from Claude: control agents, sync with them and get reports, at the access level you choose.",
+  "author": {
+    "name": "KpnWorld"
+  },
+  "license": "MIT",
+  "keywords": [
+    "paperclip",
+    "agents",
+    "orchestration",
+    "mcp"
+  ],
+  "homepage": "https://papercliped.co",
+  "repository": "https://github.com/OpenSourcx/papercliped"
+}

package/.mcp.json

@@ -1,14 +1,8 @@
-{
-  "mcpServers": {
-    "paperclip": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/stdio.js"],
-      "env": {
-        "PAPERCLIP_API_URL": "${PAPERCLIP_API_URL:-http://localhost:3100}",
-        "PAPERCLIP_API_KEY": "${PAPERCLIP_API_KEY:-}",
-        "PAPERCLIP_COMPANY_ID": "${PAPERCLIP_COMPANY_ID:-}",
-        "PAPERCLIP_READ_ONLY": "${PAPERCLIP_READ_ONLY:-}"
-      }
-    }
-  }
-}
+{
+  "mcpServers": {
+    "paperclip": {
+      "type": "http",
+      "url": "https://mcp.papercliped.co/mcp"
+    }
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## Unreleased
+
+## 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.
+
+- **Install in one step from Claude Code and Codex.** Both plugin marketplaces live in this repository: `/plugin marketplace add OpenSourcx/papercliped` in Claude Code, `codex plugin marketplace add OpenSourcx/papercliped` in Codex. The plugin now connects to the hosted server (`https://mcp.papercliped.co/mcp`) instead of a local build that wasn't in the repository; people running Paperclip on their own machine use `npx papercliped@latest` (see the README).
+- **A README that gets you running:** what Papercliped is and copy-paste setup for Claude, Claude Code, Codex, ChatGPT, any MCP app and local Paperclips, without visiting the docs.
+- **Every push is a release.** CI publishes both npm packages, tags the commit and writes the GitHub release from the changelog and the commit descriptions. `scripts/version.mjs` bumps Major.Minor.Patch in every file, and a release skill for Claude and Codex (`.claude/skills/release`, `.agents/skills/release`) explains when to use which, and how to adopt the same flow in other repositories.
+- **Ready for contributors:** `SECURITY.md` (private reporting, response times), a contributor guide with the path from first PR to maintainer, `CLAUDE.md`/`AGENTS.md` for AI coding agents, and a complete Discord setup in `docs/COMMUNITY.md`.
+
+- **New website, phase 1 (foundation):** `web/`, a static React + Tailwind site with self-hosted fonts (Bricolage Grotesque, Inter, JetBrains Mono), the mascot as an animated component (eyes follow the pointer, blinks; still with reduced motion), a component kit and a `/kit` showcase page. **Seasonal themes:** the default `clip` theme plus two palettes per season, each with light and dark, rotating on a schedule that is the same for everyone on a given day; visitors can pick a theme and light/dark/system mode. Every theme passes WCAG AA contrast (tested), every route is checked in headless Chromium under the strict CSP, and nothing is loaded from third parties. Not yet served by the bridge (phase 4).
+- **New website, phase 2 (pages):** a full landing page (live user count, an interactive how-it-works stepper, a permission playground generated from the real tool list, the two plugins, security highlights, FAQ), a **changelog page** built from this file with New/Improved/Fixed filters and an Atom feed (`/changelog.xml`), a **community page** (a suggest-a-feature form that pre-fills a GitHub issue, bug reports, contributing; social links only appear once they exist), a **brand page** with mascot and wordmark downloads and usage rules, and privacy and terms rendered from the same Markdown as the bridge. Playful but accessible interactions (lifting buttons, tilting cards, a mascot that hops), checked for sideways scrolling on a 375px phone. Also: `CODE_OF_CONDUCT.md`, issue and pull request templates, `docs/COMMUNITY.md` (forum and Discord plan), sitemap, robots.txt and a social preview image.
+
+- **Public stats API** (no sign-in): `GET /api/public/v1/info`, `status`, `stats`, `series` and `errors` (plus `openapi.json`) publish aggregate users, live connections, sign-in success and failure reasons, request success rate, latency percentiles, error mix and load. Aggregate only: no usernames, aliases, ids, Paperclip addresses, app names or IPs, and no per-user breakdown (tested against memory and Postgres). GET-only, CORS-open without credentials, cached 30 s, 60 requests per minute per address. Types in `src/public-api/types.ts`. New docs page: **Public API and status**.
+- **Status page** on the new website (`/status`): live status badge, people, connections, request and sign-in success, latency percentiles, and charts for requests and errors, response time and sign-ins, plus error-mix, sign-in-failure and top-tool bars. Every chart has a text summary and a table view and never relies on colour alone; it refreshes every 30 seconds.
+- **Removed the operator panel from this repository** (`papercliped-panel`, `src/panel/`, the demo, `PANEL_*` settings, `docs/panel-role.sql`). The operator dashboard now lives in a separate, access-controlled service. Nothing changed in the database: the telemetry tables and the read-only `panel_*` views are still written and kept for it. `npm run build` now cleans `dist/` first.
+
+- **New website, phase 3 (docs):** a docs site at `/docs` with a three-column layout (collapsible sections with counts, the article with breadcrumb, last-updated date, copy link and edit-on-GitHub, and an "On this page" outline that follows your scroll), previous/next links, copy buttons on code, and **Ctrl/Cmd-K search** built at compile time (no outside service). The **GitHub star count** shows in the header: the bridge fetches it from GitHub and caches it for an hour (`GET /api/public/v1/repo`), so browsers never call GitHub directly.
+- **Much more documentation:** new pages What is Papercliped? (with a glossary), Run it yourself, Tool reference (generated from the code), Manage API, Environment variables, Command line, Limits and errors, and FAQ. Docs now have 20 pages in five sections; the bridge serves the same pages until the new site goes live.
+
+- **The bridge serves the new website** (from `web/dist`, built into the Docker image) with **host routing** (`PUBLIC_HOSTS`): `papercliped.co` for the site, `docs.papercliped.co/topics` for the docs, `mcp.`/`api.papercliped.co` for MCP, OAuth and the APIs, `forum.` redirects to the forum, `www` redirects to the apex. Old `/docs/...` links redirect to the docs host. Every host still answers the protocol and API paths. Unknown pages return a real 404. Without the built site (e.g. the npm package), the bridge serves its Markdown pages as before. Setup and the issuer decision: `docs/DOMAINS.md`.
+- **Sign-in, consent and manage pages restyled** with the website's fonts (Bricolage Grotesque, Inter, JetBrains Mono) and colours, including dark mode. Still plain server-rendered HTML.
+- **New tool `papercliped_service_status`** (read only): the AI can check whether the hosted service is working, from the public status API. The catalogue is now 30 tools.
+- **Paperclip plugin:** a "Papercliped service" card shows the bridge's public status (no link needed).
+
+- **AI apps now connect at `https://mcp.papercliped.co/mcp`** (the OAuth issuer moves to `mcp.papercliped.co`; the website, docs and `/manage` stay on `papercliped.co`). Docs show the connector address through a new `{{MCP}}` placeholder, so self-hosted bridges show their own. Anyone connected before must remove the connector and add the new address.
+
+- **Website redesign:** a bolder homepage (a centred headline, pill buttons, a gradient pill hero with the mascot in the middle; click it for a wave), a shorter header (Product, Docs, Resources, Community, search, GitHub stars, Get started). The docs get their own header (links left, "papercliped Docs" centred, search and stars right), a sidebar grouped into Learn, Reference and Project with icons, counts and collapsible sections, and a page header with breadcrumb, tag and a Copy link menu (view the Markdown source, suggest an edit). The changelog moves into the docs layout as expandable release cards.
+- **Light and dark now follow your device automatically.** The manual System/Light/Dark switch is gone (an old saved choice is cleared); the seasonal palettes still rotate on their own.
+
+- **Two access levels: Read only and Full control.** Full control is now every tool (pause, wake, terminate, issues, goals, comments, approvals, budgets and raw API writes), so you can run your Paperclip from anywhere. The separate "Admin" level is gone; existing admin grants and apps that still ask for it get Full control (migration `006_two_levels.sql` tidies stored grants). The sign-in page, the manage page, the Paperclip plugin, the docs and the website playground all show the two levels.
+
+- **Managing your account moved into Paperclip.** The Papercliped plugin is now the connection manager: link it with your username and secret key (checked once, not stored), then change levels, disconnect apps, switch anonymity, see and remove linked Paperclips, make a new secret key (this Paperclip stays linked), disconnect your Paperclip or delete your account. The `/manage` web page, its cookie sign-in, one-time link codes and the beta opt-in are gone (`/manage` now points to the plugin docs); the manage API accepts plugin tokens only.
+
+- **Docs live at `docs.papercliped.co/<page>`** (for example `docs.papercliped.co/permissions`), with a real docs landing at `docs.papercliped.co/`: search, the connector address, four start-here cards and every topic. Old `/topics/...` and `papercliped.co/docs/...` links redirect.
+
+- **A cleaner homepage hero:** instead of decorative art, a live demo of the product. An AI app on the left steers a Paperclip on the right (pause an agent, weekly report, approve a request), using the real tool names, with tabs to replay each one. The footer gets X, GitHub and Discord icons (X and Discord point to the community page until their addresses are set).
+
+- **The Papercliped page in Paperclip, rebuilt** with Paperclip's own components (status badges, metric cards, tables, toasts) so it looks native: a service panel, an account summary, and tabs for Connected apps (level dropdown, two-step disconnect), Privacy, Linked Paperclips and Account (new secret key shown once with copy, disconnect Paperclip, delete account). Covered by UI tests against the real plugin actions.
+
+## v2.0.0 — stable open-source build
+
+Papercliped v2 is the free, open-source foundation: the bridge, the connector for Claude and any MCP app, and the Paperclip plugin. Paid features (managed subdomains, pricing, legal) are planned for v3 (`docs/V3-SUBDOMAINS.md`).
+
+- **New home: `https://papercliped.co`.** Every reference to the old domain is gone. The Paperclip plugin's default bridge URL is now `https://papercliped.co`. Operators: set `BRIDGE_PUBLIC_URL=https://papercliped.co`; apps connected under the old address must connect again (the OAuth issuer changed). Cloudflare + Render setup: `docs/LAUNCH.md` §3.
+- **Two plugins, documented side by side:** Papercliped for AI apps (Claude, ChatGPT, any MCP client) and the Papercliped plugin for Paperclip. New docs page: **Any AI app (MCP)**.
+- **Automated npm publishing** through GitHub Actions with npm trusted publishing (OIDC, no token): one tag publishes `papercliped` and `papercliped-paperclip-plugin` and creates the GitHub release (`docs/RELEASING.md`). CI now also packs both packages and installs them as a user would, and a test keeps every version string in step.
+- **Foundation:** CodeQL, Dependabot, dependency audit and read-only permissions in CI; `CONTRIBUTING.md`; `docs/SITEMAP.md` (every page and endpoint); new docs page **Set up your Paperclip** (public address with or without a domain); the security doc covers plugin links.
+- Fixed: the Claude Code install command in the README (`/plugin install papercliped@papercliped`).
+
+Not tested live: the Paperclip plugin has never run inside a real Paperclip, and the release workflow has not run yet (it can only run on GitHub).
+
+## v1.2.0-beta.1 — Paperclip plugin
+
+- **Paperclip plugin** (`plugin/`, npm `papercliped-paperclip-plugin`, a separate package built on `@paperclipai/plugin-sdk`): a **Papercliped** sidebar entry and page inside Paperclip to link your account, list connected apps, switch them between Read only and Full control (beta), disconnect them, toggle anonymity, and unlink. The bridge URL is configurable (https only).
+- **Plugin link API**: `POST /api/manage/plugin-link` (beta, browser session) makes a one-time `pcl_…` code (10 minutes, single use); `POST /api/manage/plugin-link/exchange` trades it for a long-lived `pcb_pl_…` token (rate-limited by address; wrong, used and expired codes answer identically); `GET /api/manage/plugin-links`; `DELETE /api/manage/plugin-links/:id`. The `/manage` page gains a **Link Paperclip plugin** section.
+- **Plugin tokens** are accepted as `Authorization: Bearer` on the manage API (no CSRF header needed). They hold no scopes, so they cannot call any Paperclip tool or the MCP endpoint, and they cannot mint codes, change the beta, sign out, or reach any action that needs the secret key (rotate key, disconnect Paperclip, delete account); those return 403 and need the browser. A token can remove only itself.
+- **Making a new secret key now also revokes every plugin link.**
+- New docs page: Paperclip plugin.
+- New docs page: **Set up your Paperclip**, a step-by-step guide to getting a public https address (Cloudflare Tunnel with your own domain, or Tailscale Funnel, ngrok or a Cloudflare quick tunnel without one).
+
+Not tested: the plugin has never run inside a live Paperclip. It is covered by unit tests against a fake bridge and the SDK's test harness only.
+
 ## v1.1.0-beta.2 — connection manager, public site
 
 - **Beta connection manager** at `/manage` and a management API (`/api/manage/*`): sign in with username + secret key, see every connected app, switch it between Read only and Full control (beta) with immediate effect, disconnect it, toggle anonymity, make a new secret key, disconnect your Paperclip, delete your account. Sensitive actions re-ask for the secret key; Admin is never grantable from here. Opt in with **Join the beta** on the permission screen (migration `005_beta.sql`, applied automatically).
@@ -8,7 +72,6 @@
 - Windows-friendly test suite; `npm publish` only builds.
 - Set `SITE_CONTACT` (an email or support URL) so the privacy and terms pages show a real contact.
 
-Not in this release: a native Paperclip plugin that embeds the manager inside Paperclip (it needs the Paperclip plugin SDK).
 
 ## v1.0.0-beta.1 — first public beta
 

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 KpnWorld
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 KpnWorld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,122 +1,122 @@
-# papercliped — Claude & ChatGPT plugin for Paperclip
+# Papercliped
 
-Drive a [Paperclip](https://github.com/paperclipai/paperclip) instance (AI-agent company orchestrator) from Claude or ChatGPT through Paperclip's REST API.
+**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.
 
-| Goal | How |
-| --- | --- |
-| Control Paperclip and agents | pause / resume / wake / clear-error / terminate agents, set budgets, create & assign issues, manage goals, decide approvals |
-| Sync with agents | `paperclip_sync_snapshot` (state now), `paperclip_sync_changes` (cursor-based "what changed"), `paperclip_wait_for_agent` (follow a run to completion) |
-| Reports | status, costs, agent performance, activity digest — markdown for people plus structured data |
-| Use the API | every tool is a thin call to Paperclip's `/api`; `paperclip_api_request` reaches anything without a dedicated tool |
+[![CI](https://github.com/OpenSourcx/papercliped/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenSourcx/papercliped/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/papercliped)](https://www.npmjs.com/package/papercliped)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-One tool catalogue (`src/tools.ts`, 29 tools) feeds three surfaces, so they cannot drift:
+Free and open source. Website: [papercliped.co](https://papercliped.co) · Docs: [docs.papercliped.co](https://docs.papercliped.co)
+
+> Papercliped is an independent community project, not made by the Paperclip team.
+
+## Add it to your AI app
+
+You need a Paperclip with a public `https` address ([no domain? see this](https://docs.papercliped.co/connect-your-paperclip)). The first time you connect, you approve the request inside your own Paperclip, pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**.
+
+The connector address for every app is:
 
 ```
-Claude Code / Claude Desktop ──stdio──▶ ┐
-Any MCP client ──Streamable HTTP /mcp─▶ ├─ tools ─▶ Paperclip /api
-ChatGPT Custom GPT ──/actions/* + /openapi.json─▶ ┘
+https://mcp.papercliped.co/mcp
 ```
 
-> Paperclip already ships `@paperclipai/mcp-server` for issues/goals/approvals *from inside an agent run*. This bridge is the **operator-side** complement: agent lifecycle control, dashboard/cost/activity reports, sync, and an HTTP transport. They can be installed side by side.
+### Claude (web, desktop and mobile)
 
-## Install
+**Settings → Connectors → Add custom connector**, paste `https://mcp.papercliped.co/mcp`, then **Connect**.
+
+### Claude Code
+
+Install the plugin (adds the tools, a Paperclip skill and `/paperclip-status`, `/paperclip-sync`, `/paperclip-report`):
+
+```
+/plugin marketplace add OpenSourcx/papercliped
+/plugin install papercliped@papercliped
+```
+
+Or just the MCP server:
 
 ```sh
-git clone https://github.com/OpenSourcx/papercliped && cd papercliped
-npm install        # also builds (prepare script)
-npm test
+claude mcp add --transport http paperclip https://mcp.papercliped.co/mcp
 ```
 
-### Credentials (read this first)
+Then run `/mcp` to sign in.
+
+### Codex
 
-Pause/resume/wake/approve are **board-only** in Paperclip, so an agent API key will get `403`s. Use a **board API token**:
+Install the plugin:
 
 ```sh
-paperclipai auth login      # then copy the board token, or use your instance's token flow
-export PAPERCLIP_API_URL=http://localhost:3100
-export PAPERCLIP_API_KEY=<board token>      # not needed in local_trusted mode
-export PAPERCLIP_COMPANY_ID=<optional default company>
-export PAPERCLIP_READ_ONLY=1                # optional: reports + sync only, no writes
+codex plugin marketplace add OpenSourcx/papercliped
+codex plugin add papercliped@papercliped
 ```
 
-## Claude Code (plugin)
+Or just the MCP server (Codex starts the sign-in for you):
 
-```
-/plugin marketplace add OpenSourcx/papercliped
-/plugin install paperclip@papercliped
+```sh
+codex mcp add paperclip --url https://mcp.papercliped.co/mcp
 ```
 
-You get the MCP tools, a `paperclip` skill (sync-first workflow + confirm-before-destructive rules) and `/paperclip-status`, `/paperclip-sync`, `/paperclip-report`.
-The env vars above are read from your shell. Or without the plugin: `claude mcp add paperclip -- node /path/to/papercliped/dist/stdio.js`.
+### ChatGPT
 
-## Claude Desktop
+Turn on **Developer mode** (Settings → Apps → Advanced settings), choose **Create app**, paste `https://mcp.papercliped.co/mcp` and pick OAuth. Menu names change often; the [ChatGPT guide](https://docs.papercliped.co/chatgpt) has the current steps and the Custom GPT (Actions) option.
 
-```json
-{ "mcpServers": { "paperclip": {
-  "command": "node", "args": ["/path/to/papercliped/dist/stdio.js"],
-  "env": { "PAPERCLIP_API_URL": "http://localhost:3100", "PAPERCLIP_API_KEY": "…" } } } }
-```
+### Any other MCP app
+
+Add a remote MCP server (Streamable HTTP, OAuth) at `https://mcp.papercliped.co/mcp`. See [Any AI app](https://docs.papercliped.co/other-ai-apps).
 
-## ChatGPT (Custom GPT Actions)
+### Paperclip on your own machine (no public address)
 
-Run the HTTP bridge somewhere ChatGPT can reach over HTTPS, then import its OpenAPI. Step-by-step: [docs/chatgpt.md](docs/chatgpt.md).
+Run Papercliped locally instead. It talks straight to your Paperclip; nothing goes through papercliped.co. Use a Paperclip **board** token (agent keys can't pause or approve):
 
 ```sh
-export BRIDGE_TOKEN=$(openssl rand -hex 32)     # required; the bridge refuses to start without it
-export BRIDGE_PUBLIC_URL=https://bridge.example.com
-npm run start:http                               # 127.0.0.1:3939 — put TLS in front (Caddy, Cloudflare Tunnel, …)
-```
+# Claude Code
+claude mcp add paperclip --env PAPERCLIP_API_URL=http://localhost:3100 --env PAPERCLIP_API_KEY=<board token> -- npx -y papercliped@latest
 
-Endpoints (all but `/healthz`, `/openapi.json` and the OAuth endpoints need `Authorization: Bearer <BRIDGE_TOKEN or OAuth access token>`): `POST /mcp` (MCP Streamable HTTP, stateless), `POST /actions/{tool}` (JSON in/out), `GET /openapi.json`. With `BRIDGE_OAUTH=1`: `/.well-known/oauth-*`, `/register`, `/authorize`, `/token`, `/revoke`.
+# Codex
+codex mcp add paperclip --env PAPERCLIP_API_URL=http://localhost:3100 --env PAPERCLIP_API_KEY=<board token> -- npx -y papercliped@latest
+```
 
-### Three ways to run it
+Add `--env PAPERCLIP_READ_ONLY=1` for reports and sync only.
 
-| Mode | For | Auth | State |
-| --- | --- | --- | --- |
-| **stdio** (`node dist/stdio.js`) | you, on your machine (Claude Code/Desktop) | your env vars | none |
-| **HTTP + `BRIDGE_TOKEN`** | ChatGPT Actions, Claude Code headers, one instance | static bearer | none |
-| **HTTP + OAuth, `BRIDGE_MODE=single`** | a team fronting *their one* Paperclip | OAuth 2.1, scoped | JSON file or Postgres |
-| **HTTP + OAuth, `BRIDGE_MODE=multi`** | **a public service**: every user connects their own (publicly reachable, https) Paperclip | OAuth 2.1, scoped | Postgres (required) |
+## What you can ask
 
-**Operator panel** (a separate program, `papercliped-panel`): latency, system faults, success rate, user count and a community log — see [docs/LAUNCH.md §7](docs/LAUNCH.md); preview with `npm run demo`. **Supabase schema:** paste [docs/supabase-schema.sql](docs/supabase-schema.sql) into the SQL editor. **Launch guide (Render free, domain, marketplaces, npm):** [docs/LAUNCH.md](docs/LAUNCH.md).
+- "What are my agents working on?" · "Which agents are over budget?"
+- "Pause the Web Engineer." · "Wake the CEO and assign it the onboarding issue."
+- "Approve the hire request." · "Weekly cost report, please."
 
-Public hosting on Render + Supabase: **[docs/DEPLOY-RENDER.md](docs/DEPLOY-RENDER.md)** · threat model and residual risks: **[docs/SECURITY.md](docs/SECURITY.md)** · policy templates: [docs/legal/](docs/legal/).
+There are 30 tools ([full list](https://docs.papercliped.co/tools)). **Read only** can look at agents, issues, goals, costs and reports. **Full control** can use every tool. The AI asks before anything that can't be undone, and you can change the level or disconnect at any time.
 
-### Connect claude.ai / Claude Desktop / ChatGPT apps (OAuth)
+## Manage your connections in Paperclip
 
-Set `BRIDGE_OAUTH=1`, `BRIDGE_PUBLIC_URL`, `BRIDGE_SECRET`, `BRIDGE_DATA_FILE` (see [.env.example](.env.example)), then add `https://<your bridge>/mcp` as a custom connector. Users sign in through Paperclip's own approval page and choose Read / Control / Admin. Full guide, scopes and security model: [docs/oauth.md](docs/oauth.md).
+Install the **Papercliped plugin for Paperclip** (npm `papercliped-paperclip-plugin`, from **Settings → Plugins** in Paperclip). It adds a Papercliped page where you see every connected app, switch its level, disconnect it, go anonymous, and look after your account. [Plugin guide](https://docs.papercliped.co/paperclip-plugin).
 
-## Safety model
+## Security and privacy
 
-- OAuth connections get scoped tokens (read/control/admin), enforced in the bridge, with every call audit-logged. See [docs/oauth.md](docs/oauth.md).
-- `PAPERCLIP_READ_ONLY=1` blocks every mutating tool (and non-GET `paperclip_api_request`) before anything is sent to Paperclip.
-- `paperclip_terminate_agent` needs `confirm: true`; non-GET raw API calls need it too. Tools carry MCP `destructiveHint`/`readOnlyHint`, and OpenAPI `x-openai-isConsequential`, so clients prompt before consequential calls.
-- The HTTP bridge binds to loopback by default, uses constant-time token comparison, caps bodies at 1 MB, and times out upstream calls (30 s).
-- The bridge holds a powerful credential. Anyone with `BRIDGE_TOKEN` controls your agents; scope the Paperclip token and use read-only mode where you can.
+- You approve every connection inside your own Paperclip; no passwords pass through Papercliped.
+- Levels are enforced by Papercliped on every call, and every call is audit-logged.
+- Paperclip keys are encrypted at rest; tokens and secret keys are stored only as one-way hashes.
+- Only public `https` Paperclip addresses are reachable from the hosted service.
+- No trackers or third-party scripts on the website.
 
-## Known limits — please read
+Threat model: [docs/SECURITY.md](docs/SECURITY.md). Report a vulnerability: [SECURITY.md](SECURITY.md). Privacy: [papercliped.co/privacy](https://papercliped.co/privacy).
 
-- **Tested against a mock of Paperclip's documented API, not a live instance.** Endpoint paths and fields were taken from Paperclip's docs and server source (`docs/api/*`, `server/src/routes/*`); report/sync code reads response fields defensively. Run it against your instance with `PAPERCLIP_READ_ONLY=1` first.
-- **claude.ai web / Desktop / mobile connectors and ChatGPT MCP apps** need OAuth: set `BRIDGE_OAUTH=1` (see [docs/oauth.md](docs/oauth.md)). OAuth scopes limit *what* a connection may do, not *which company* it may touch (Paperclip board keys are user-wide; verified in its source). Not yet implemented: CIMD, a grant-admin web UI (use `npm run admin`).
-- **A public bridge holds other people's Paperclip keys.** A bridge compromise exposes all of them until revoked. Read [docs/SECURITY.md](docs/SECURITY.md) before opening it up. The code is unaudited and the Render/Supabase/claude.ai/ChatGPT specifics are untested against the live services.
-- **Hosted mode only reaches Paperclips on the public internet over https.** `localhost`/private-network instances use the local stdio plugin.
-- `paperclip_sync_changes` polls the activity log (no push). Activity has no server-side `since` filter, so it fetches up to `limit` recent entries and filters locally; raise `limit` if you poll infrequently on a busy company.
-- ChatGPT Actions allow ~30 operations per GPT; the catalogue is at 29. Adding tools means removing some for that surface.
+## Run it yourself
 
-## Layout
+The hosted service runs exactly this code. To host your own (for a team, or to keep everything on your infrastructure), see [Run it yourself](https://docs.papercliped.co/self-hosting), [docs/oauth.md](docs/oauth.md) and the [launch guide](docs/LAUNCH.md) (Render + Supabase, free tiers).
 
+```sh
+git clone https://github.com/OpenSourcx/papercliped && cd papercliped
+npm install && npm test
 ```
-src/tools.ts      tool catalogue (schemas + Paperclip calls)     src/reports.ts  report builders
-src/execute.ts    validation, read-only enforcement, errors      src/openapi.ts  OpenAPI from the catalogue
-src/mcp.ts        MCP server    src/stdio.ts   src/server.ts + http.ts  HTTP bridge
-src/oauth/        OAuth 2.1 server: provider, stores (memory/JSON + Postgres), crypto/key ring, scopes, consent pages, Paperclip login adapter
-src/telemetry/    audit events, batching recorder, system sampler, timing   src/panel/  separate operator panel (routes, page, config, server)
-src/net/          SSRF-safe fetch + instance URL validation (multi-tenant egress guard)
-migrations/       Postgres schema (dedicated `bridge` schema, RLS)   Dockerfile   container image (Render free web service)   src/cli.ts  admin CLI
-.claude-plugin/ .mcp.json skills/ commands/    Claude Code plugin
-test/             end-to-end tests against a mock Paperclip
-```
 
-## Privacy
+## Community and contributing
+
+- Questions and ideas: [GitHub Discussions](https://github.com/OpenSourcx/papercliped/discussions) and Discord ([papercliped.co/community](https://papercliped.co/community))
+- Bugs and feature requests: [issues](https://github.com/OpenSourcx/papercliped/issues/new/choose)
+- Contributing (setup, checks, the path from first PR to maintainer): [CONTRIBUTING.md](CONTRIBUTING.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- Every push to `main` is a release: [changelog](CHANGELOG.md) · [how releases work](docs/RELEASING.md)
+
+## License
 
-Local modes: no telemetry and no backend; the bridge sends requests only to the Paperclip instance you configure and returns responses to the AI client that called it. Your credential lives in environment variables on your machine. Hosted mode (OAuth) additionally stores, per connection, an encrypted Paperclip key, hashed tokens and an audit log — see [docs/legal/PRIVACY.md](docs/legal/PRIVACY.md) (template) and [docs/SECURITY.md](docs/SECURITY.md). Data you expose to Claude or ChatGPT is then subject to that provider's own terms and privacy policy. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the security model and distribution plan.
+[MIT](LICENSE)

package/commands/paperclip-report.md

@@ -1,5 +1,5 @@
----
-description: Produce a Paperclip report — status, costs, performance or activity
-argument-hint: "[status|costs|performance|activity]"
----
-Produce the report named in "$ARGUMENTS" (default `status`): `status` → `paperclip_report_status`, `costs` → `paperclip_report_costs`, `performance` → `paperclip_report_agent_performance`, `activity` → `paperclip_report_activity` (since the start of today, UTC). Present the markdown, then add 2–3 sentences of analysis: what looks off and what you would do about it.
+---
+description: Produce a Paperclip report — status, costs, performance or activity
+argument-hint: "[status|costs|performance|activity]"
+---
+Produce the report named in "$ARGUMENTS" (default `status`): `status` → `paperclip_report_status`, `costs` → `paperclip_report_costs`, `performance` → `paperclip_report_agent_performance`, `activity` → `paperclip_report_activity` (since the start of today, UTC). Present the markdown, then add 2–3 sentences of analysis: what looks off and what you would do about it.

package/commands/paperclip-status.md

@@ -1,4 +1,4 @@
----
-description: Show a Paperclip status report (agents, tasks, spend, approvals)
----
-Call `paperclip_report_status` and present the result. Then list any agents in error or paused and any pending approvals, and suggest next steps — but do not take any action without asking.
+---
+description: Show a Paperclip status report (agents, tasks, spend, approvals)
+---
+Call `paperclip_report_status` and present the result. Then list any agents in error or paused and any pending approvals, and suggest next steps — but do not take any action without asking.

package/commands/paperclip-sync.md

@@ -1,5 +1,5 @@
----
-description: Sync with Paperclip agents — current state plus what changed since last sync
-argument-hint: "[cursor from previous sync]"
----
-Call `paperclip_sync_snapshot`. If a cursor was given ($ARGUMENTS), also call `paperclip_sync_changes` with it. Summarise what each agent is doing, what changed, and end with the new cursor so the next sync can continue from it.
+---
+description: Sync with Paperclip agents — current state plus what changed since last sync
+argument-hint: "[cursor from previous sync]"
+---
+Call `paperclip_sync_snapshot`. If a cursor was given ($ARGUMENTS), also call `paperclip_sync_changes` with it. Summarise what each agent is doing, what changed, and end with the new cursor so the next sync can continue from it.

package/dist/accounts/alias.js

@@ -19,7 +19,7 @@ const POOL = [...new Set(NAMES)];
 export const ALIAS_RE = /^[A-Z][a-z]{1,2}\d{2}$/;
 export const generateAlias = (rand = (n) => randomInt(n)) => `${POOL[rand(POOL.length)]}${String(rand(100)).padStart(2, "0")}`;
 export const isAlias = (s) => !!s && ALIAS_RE.test(s);
-/** The name that appears in logs, the panel and audit rows. */
+/** The name that appears in logs, the operator dashboard and audit rows. */
 export const displayName = (a) => (a.anonymous && a.alias ? a.alias : a.username);
 /**
  * A stable label standing in for a tenant's Paperclip hostname when its owner is anonymous ("anon-3f9a1c"). It keeps one tenant's

package/dist/accounts/username.js

@@ -16,7 +16,7 @@ const ALLOWED = /^[A-Za-z0-9._#]+$/;
 const STARTS_OK = /^[A-Za-z0-9]/;
 const HAS_NUMBER_OR_SYMBOL = /[0-9._#]/;
 /** Compared against the letters-only form of a name, so "admin.1" and "root_9" are caught too. */
-const RESERVED = new Set(["admin", "administrator", "root", "system", "support", "staff", "official", "moderator", "papercliped", "paperclip", "cliped", "kpnworld", "kpnsolute", "anthropic", "claude", "openai", "chatgpt"]);
+const RESERVED = new Set(["admin", "administrator", "root", "system", "support", "staff", "official", "moderator", "papercliped", "paperclip", "cliped", "kpnworld", "anthropic", "claude", "openai", "chatgpt"]);
 export const usernameKey = (username) => username.toLowerCase();
 export function validateUsername(raw) {
     if (typeof raw !== "string")

package/dist/cli.js

@@ -3,17 +3,17 @@ import { readConfig, readDatabase, readHttpConfig } from "./config.js";
 import { consolidatedSql, migrate } from "./migrate.js";
 import { OAuthProvider } from "./oauth/provider.js";
 import { createStore } from "./store-factory.js";
-const USAGE = `paperclip-bridge-admin <command>
-
-  schema-sql     print ONE paste-able SQL script (all migrations) for the Supabase SQL editor
-  migrate        apply database migrations (uses DATABASE_MIGRATE_URL if set, else DATABASE_URL; needs a direct/session connection)
-  users          list accounts: real username, alias (if anonymous), when last signed in (OPERATOR ONLY: this un-masks aliases)
-  delete-user <username>  delete an account, its stored credential and grants (asks that Paperclip to revoke the key)
-  grants         list live grants (no secrets are shown)
-  revoke <id>    revoke one grant and delete its stored credential
-  sweep          revoke grants idle longer than BRIDGE_IDLE_REVOKE_DAYS
-  revoke-all --yes  incident response: revoke EVERY grant, delete all stored credentials, ask each tenant's Paperclip to revoke its key
-  rotate-keys    re-seal stored credentials with the current BRIDGE_SECRET (put the old one in BRIDGE_SECRET_PREVIOUS first)
+const USAGE = `paperclip-bridge-admin <command>
+
+  schema-sql     print ONE paste-able SQL script (all migrations) for the Supabase SQL editor
+  migrate        apply database migrations (uses DATABASE_MIGRATE_URL if set, else DATABASE_URL; needs a direct/session connection)
+  users          list accounts: real username, alias (if anonymous), when last signed in (OPERATOR ONLY: this un-masks aliases)
+  delete-user <username>  delete an account, its stored credential and grants (asks that Paperclip to revoke the key)
+  grants         list live grants (no secrets are shown)
+  revoke <id>    revoke one grant and delete its stored credential
+  sweep          revoke grants idle longer than BRIDGE_IDLE_REVOKE_DAYS
+  revoke-all --yes  incident response: revoke EVERY grant, delete all stored credentials, ask each tenant's Paperclip to revoke its key
+  rotate-keys    re-seal stored credentials with the current BRIDGE_SECRET (put the old one in BRIDGE_SECRET_PREVIOUS first)
 `;
 async function main() {
     const [cmd, arg] = process.argv.slice(2);

package/dist/http.js

@@ -4,7 +4,12 @@ import { migrate } from "./migrate.js";
 import { OAuthProvider } from "./oauth/provider.js";
 import { createHttpServer } from "./server.js";
 import { ManageRoutes } from "./manage/routes.js";
+import { PublicApiRoutes } from "./public-api/routes.js";
 import { SiteRoutes } from "./site/site.js";
+import { VERSION } from "./version.js";
+import { fileURLToPath } from "node:url";
+import { parseHosts } from "./web/hosts.js";
+import { WebAppRoutes } from "./web/routes.js";
 import { createStore } from "./store-factory.js";
 import { AuditRecorder, NodeReporter, SystemSampler } from "./telemetry/recorder.js";
 import { MemoryStore } from "./oauth/store.js";
@@ -24,7 +29,8 @@ async function main() {
         console.error("Refusing to start: set BRIDGE_TOKEN (e.g. `openssl rand -hex 32`) and/or BRIDGE_OAUTH=1. The bridge exposes control of your agents.");
         process.exit(1);
     }
-    // One store serves OAuth state, accounts and audit telemetry; the operator panel is a separate program that reads it.
+    // One store serves OAuth state, accounts and audit telemetry. The public stats API reads aggregates from it; the private
+    // operator dashboard (a separate, access-controlled service) reads the same telemetry tables.
     const store = http.oauth ? createStore(http.oauth) : new MemoryStore();
     try {
         await store.ping();
@@ -56,13 +62,21 @@ async function main() {
     const site = siteUrl
         ? new SiteRoutes({
             url: siteUrl,
+            mcpUrl: http.oauth?.issuer ?? http.publicUrl ?? undefined,
             contact: process.env.SITE_CONTACT?.trim() || "https://github.com/OpenSourcx/papercliped/issues",
             effective: process.env.SITE_EFFECTIVE_DATE?.trim() || "2026-10-06",
             stats: async () => ({ users: await store.countAccounts(), connections: await store.liveGrantCount() }),
         })
         : undefined;
-    const manage = provider && http.oauth?.mode === "multi" ? new ManageRoutes(provider, { secureCookie: !!siteUrl?.startsWith("https:") }) : undefined;
-    const server = createHttpServer(config, http, { oauth: provider, recorder, site, manage });
+    const publicApi = new PublicApiRoutes({ store, version: VERSION, docsUrl: "https://papercliped.co/docs/public-api", publicUrl: siteUrl ?? undefined, proxyHops: http.oauth?.proxyHops ?? 0 });
+    // The React website, when built (web/dist next to the package, or WEB_DIST); otherwise the bridge's own Markdown pages.
+    const hosts = parseHosts(process.env.PUBLIC_HOSTS);
+    const webDir = WebAppRoutes.locate(process.env, fileURLToPath(new URL("../web/dist", import.meta.url)));
+    const web = webDir ? new WebAppRoutes({ dir: webDir, hosts, forumUrl: process.env.FORUM_URL?.trim() || null }) : undefined;
+    if (web)
+        console.error(`website: ${webDir}${process.env.PUBLIC_HOSTS ? ` (hosts: ${process.env.PUBLIC_HOSTS})` : ""}`);
+    const manage = provider && http.oauth?.mode === "multi" ? new ManageRoutes(provider) : undefined;
+    const server = createHttpServer(config, http, { oauth: provider, recorder, site, manage, publicApi, web });
     server.listen(http.port, http.host, () => {
         const o = http.oauth;
         console.error(`paperclip-bridge listening on http://${http.host}:${http.port}` +