papercliped 1.1.0-beta.2 → 2.1.0

package/dist/web/routes.js

@@ -0,0 +1,132 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, join, normalize, sep } from "node:path";
+import { SITE_CSP } from "./csp.js";
+import { roleOf } from "./hosts.js";
+/** Paths the bridge itself serves on every host; the website never answers them. */
+const PROTOCOL = /^\/(mcp|actions\/|openapi\.json$|register$|authorize|token$|revoke$|\.well-known\/|api\/|manage$|healthz$|readyz$)/;
+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",
+};
+const HEADERS = { "X-Content-Type-Options": "nosniff", "Referrer-Policy": "strict-origin-when-cross-origin", "X-Frame-Options": "DENY" };
+/**
+ * Serves the React website and does the host routing:
+ *   marketing host  → the site; /docs/* moves to the docs host when there is one
+ *   docs host       → the docs landing at / and each page at /<page>; old /docs/* and /topics/* links redirect there;
+ *                     other pages go to the marketing host
+ *   api host        → protocol endpoints only (handled elsewhere); pages redirect to the marketing host
+ *   forum host      → redirects to the forum
+ * Hosts not in PUBLIC_HOSTS (and a bridge with no PUBLIC_HOSTS) get the whole site, as before.
+ */
+export class WebAppRoutes {
+    o;
+    index;
+    routes;
+    /** Doc page slugs ("permissions", "faq"…), from the /docs/<slug> entries in routes.json. */
+    docSlugs;
+    constructor(o) {
+        this.o = o;
+        this.index = readFileSync(join(o.dir, "index.html"), "utf8");
+        this.routes = new Set(JSON.parse(readFileSync(join(o.dir, "routes.json"), "utf8")));
+        this.docSlugs = new Set([...this.routes].filter((r) => r.startsWith("/docs/")).map((r) => r.slice("/docs/".length)));
+    }
+    /** Finds web/dist next to the package, or WEB_DIST. Null when the website isn't built (then the bridge's own pages are used). */
+    static locate(env, fallback) {
+        const dir = env.WEB_DIST?.trim() || fallback;
+        return existsSync(join(dir, "index.html")) && existsSync(join(dir, "routes.json")) ? dir : null;
+    }
+    canonical(role) {
+        return this.o.hosts[role][0];
+    }
+    redirect(res, to, permanent = true) {
+        res.writeHead(permanent ? 301 : 302, { Location: to, "Cache-Control": permanent ? "public, max-age=3600" : "no-store", ...HEADERS });
+        res.end();
+        return true;
+    }
+    /** The page shell, with the host map for the app's links (see web/src/lib/hosts.ts). */
+    shell(res, status, head) {
+        const map = JSON.stringify({ marketing: this.canonical("marketing"), docs: this.canonical("docs") }).replace(/"/g, "&quot;");
+        res.writeHead(status, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache", "Content-Security-Policy": SITE_CSP, ...HEADERS });
+        res.end(head ? undefined : this.index.replace('<meta name="pcl-hosts" content="{}" />', `<meta name="pcl-hosts" content="${map}" />`));
+        return true;
+    }
+    file(res, path, head) {
+        let rel;
+        try {
+            rel = normalize(decodeURIComponent(path)).replace(/^([/\\])+/, "");
+        }
+        catch {
+            return false;
+        }
+        if (!rel || rel.split(/[/\\]/).includes("..") || rel === "index.html" || rel === "routes.json")
+            return false;
+        const full = join(this.o.dir, rel);
+        if (!full.startsWith(this.o.dir.endsWith(sep) ? this.o.dir : this.o.dir + sep))
+            return false;
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            return false;
+        }
+        if (!st.isFile())
+            return false;
+        const immutable = rel.startsWith("assets" + sep) || rel.startsWith("assets/") || rel.startsWith("fonts");
+        res.writeHead(200, {
+            "Content-Type": TYPES[extname(full).toLowerCase()] ?? "application/octet-stream",
+            "Content-Length": String(st.size),
+            "Cache-Control": immutable ? "public, max-age=31536000, immutable" : "public, max-age=3600",
+            ...(rel.endsWith(".html") ? { "Content-Security-Policy": SITE_CSP } : {}),
+            ...(immutable && rel.startsWith("fonts") ? { "Access-Control-Allow-Origin": "*" } : {}),
+            ...HEADERS,
+        });
+        res.end(head ? undefined : readFileSync(full));
+        return true;
+    }
+    async handle(req, res, url) {
+        if (req.method !== "GET" && req.method !== "HEAD")
+            return false;
+        const head = req.method === "HEAD";
+        const raw = url.pathname;
+        const path = raw.length > 1 ? raw.replace(/\/+$/, "") : raw;
+        if (PROTOCOL.test(path))
+            return false;
+        const host = String(req.headers.host ?? "").toLowerCase();
+        const role = roleOf(this.o.hosts, host);
+        const q = url.search;
+        const mk = this.canonical("marketing");
+        const docs = this.canonical("docs");
+        const isDocs = /^\/(docs|topics)(\/|$)/.test(path);
+        const docsRest = isDocs ? path.replace(/^\/(docs|topics)\/?/, "") : "";
+        if (role === "forum")
+            return this.redirect(res, this.o.forumUrl || (mk ? `https://${mk}/community` : "/"), false);
+        if (role === "api")
+            return mk ? this.redirect(res, `https://${mk}${path === "/" ? "/" : path}${q}`, false) : false;
+        if (role === "marketing" && mk && host !== mk)
+            return this.redirect(res, `https://${mk}${raw}${q}`); // www → apex
+        if (role === "docs") {
+            if (isDocs)
+                return this.redirect(res, `/${docsRest}${q}`); // old /docs/x and /topics/x links
+            if (path === "/" || this.docSlugs.has(path.slice(1)))
+                return this.shell(res, 200, head);
+            if (this.routes.has(path) && mk)
+                return this.redirect(res, `https://${mk}${path}${q}`);
+        }
+        else if (isDocs) {
+            // Marketing (or unlisted) host: docs move to the docs host when there is one. /topics is an old spelling.
+            if (docs)
+                return this.redirect(res, `https://${docs}/${docsRest}${q}`);
+            if (/^\/topics(\/|$)/.test(path))
+                return this.redirect(res, `/docs${docsRest ? `/${docsRest}` : ""}${q}`);
+        }
+        if (path !== "/" && this.file(res, raw, head))
+            return true;
+        if (this.routes.has(path))
+            return this.shell(res, 200, head);
+        if (extname(path))
+            return false; // a missing file: let the bridge answer 404
+        return this.shell(res, 404, head); // the app shows its not-found page
+    }
+}

package/docs/ARCHITECTURE.md

@@ -1,73 +1,74 @@
-# Architecture, auth and distribution plan
-
-Status: research + recommendation (Oct 2026). Sources: Paperclip source/docs (`paperclipai/paperclip`, read at depth‑1 clone) and Anthropic's connector/plugin docs. Items marked **[unverified]** are inferences or come from secondary sources and need testing before we rely on them.
-
-## 1. Verdict: integrate, don't rebuild
-
-Keep Paperclip as the system of record and build *around* it. Rebuilding is not justified:
-
-- Paperclip is a large, active codebase (8k+ files, ~295 DB migrations, adapters for ~10 agent runtimes, governance, budgets, approvals, MCP gateway, plugin SDK). Our goals — control, sync, reports, API use — are all reachable through its existing REST API. Nothing we need requires different core semantics.
-- A fork forfeits upstream fixes and the Paperclip community's agents/templates (ClipHub). A rebuild would cost far more than the integration gaps below.
-- The real gaps are **auth scoping** and **transport/OAuth**, and both can be solved in a front layer or contributed upstream.
-
-## 2. What Paperclip gives us (relevant facts)
-
-| Area | Fact | Consequence |
-| --- | --- | --- |
-| API | REST under `/api`; company-scoped; JSON; errors `{error}` | Our bridge is a thin client — no DB access, no business logic |
-| Auth modes | `local_trusted` (no login, loopback) · `authenticated/private` · `authenticated/public` (Better Auth sessions) | Bridge must work with no token (local) and with a token (everything else) |
-| Operator creds | **Board API keys** (`board_api_keys`: hashed, `expiresAt`, `revokedAt`, `lastUsedAt`, bound to a *user*). **No scope or company column** | A board key = that user's full board power. Never hand one to a public third party |
-| Login for tools | CLI challenge flow: client creates a challenge → user approves at `approvalUrl` in Paperclip's UI → client polls and receives a board token | Reusable as our "Sign in with Paperclip" step (no passwords touch our code) |
-| Agent creds | Agent keys / run JWTs; pause, resume, approve etc. are **board‑only** | Operator control must use board creds (documented in README) |
-| OAuth | Paperclip is an OAuth **client** (to upstream MCP servers). It is **not** an authorization server | claude.ai / ChatGPT connectors can't authenticate to Paperclip directly |
-| MCP | Official `@paperclipai/mcp-server` is a stdio wrapper for use inside agent runs. "Gateway mode" is agent→upstream, with profiles/policies/audit. No operator‑facing remote `/mcp` | Our bridge is the missing operator-side endpoint |
-| Plugins | Real plugin runtime: manifest + worker + UI; capability‑gated worker APIs; `apiRoutes` mounted only at `/api/plugins/:id/api/*`; plugins are trusted code; capability additions → `upgrade_pending` until an operator approves; install by npm/local path/image catalog (`paperclipai plugin install`). **No public plugin marketplace** (ClipHub = company templates only) | A native plugin is possible but distribution is operator‑installed, not store‑based |
-
-## 3. How public plugins actually ship (Claude & ChatGPT)
-
-**Claude** (docs.claude.com connector + plugin docs):
-- **Plugin bundle** (skills, commands, local MCP server like ours): public GitHub repo with `.claude-plugin/plugin.json`, README, LICENSE → `claude plugin validate` → submit at `claude.ai/directory/manage` ("Plugin bundle") → automated validation + security scan, sometimes human review → publish; later versions follow the tracked branch/tag. Data‑handling questions at submit time. Org can also share privately via a git marketplace (`/plugin marketplace add owner/repo`) — works today.
-- **Remote MCP connector** (what claude.ai web/mobile/Desktop use): must be HTTPS. Auth = OAuth 2.0 (DCR or Client‑ID‑Metadata‑Document, PKCE S256, `401` + `WWW-Authenticate: Bearer resource_metadata=…`, RFC 9728 protected‑resource metadata, RFC 8414 AS metadata, form‑encoded `/token`, refresh rotation, 10 s endpoint latency), or none, or a **static header credential (beta, limited orgs)**. Callbacks: `https://claude.ai/api/mcp/auth_callback` and a port‑agnostic loopback for Claude Code. Every tool needs `title` + `readOnlyHint`/`destructiveHint` (we already set these). Reviewers need a populated test account. Custom (unlisted) connectors can be added by URL by any user/org without review.
-- Plugins that reference a remote server should submit that server as a connector too.
-
-**ChatGPT** **[unverified: from secondary sources; I could not fetch OpenAI's docs]**:
-- *Apps SDK / MCP apps*: streamable‑HTTP MCP + OAuth 2.1 (DCR, PKCE); public submission needs a verified OpenAI org, public ToS + privacy policy, support contact, demo video, test account and test cases.
-- *Custom GPT Actions*: OpenAPI + API‑key or OAuth; shareable via link or GPT Store. This is what we ship today (bearer key).
-
-## 4. Auth design for public use
-
-Problem: board keys are all‑powerful, and the connector UIs want OAuth. Solution: put an **OAuth 2.1 authorization server inside the bridge** that fronts Paperclip.
-
-```
-claude.ai / ChatGPT ──OAuth 2.1 + PKCE──▶ bridge (AS + resource server) ──board token──▶ Paperclip /api
-                                              │
-   /authorize ──▶ create Paperclip CLI-auth challenge ──▶ user approves in Paperclip UI
-                  (bridge receives board token, stores it encrypted, mints its OWN scoped token)
-```
-
-- **Sign‑in:** reuse Paperclip's challenge/approve flow, so users authenticate to *their* Paperclip, not to us.
-- **Scopes enforced by the bridge** (Paperclip can't): `paperclip:read` (reports, sync, lists) · `paperclip:control` (pause/resume/wake, issues, comments, goals) · `paperclip:admin` (terminate, approvals, budgets, raw non‑GET). Default consent = read. The bridge already classifies tools `read|write|destructive`; map those to scopes.
-- **Tokens:** short‑lived access JWT (audience = bridge URL), rotating refresh tokens, per‑user revocation (and revoke the Paperclip key on disconnect via `auth revoke-current`). Tokens bound to one company if the user picks one at consent.
-- **Registration:** support CIMD first (no client sprawl), DCR as fallback.
-- **Endpoints to add:** `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`, `/register`, `/authorize`, `/token`, `/revoke`; `401` challenge on `/mcp`.
-- **Multi‑tenancy:** every Paperclip instance has its own URL. Options: (a) *self‑hosted bridge per operator* (their own domain) — add as a **custom connector by URL**, no directory needed; (b) *one hosted multi‑tenant bridge* where the user supplies their instance URL at consent (needs SSRF‑safe URL validation + Claude "URL pattern"/custom‑connection mode, which takes longer to review); (c) *Paperclip Cloud* — a fixed URL pattern per stack, the cleanest directory story but needs Paperclip's cooperation.
-- Keep `BRIDGE_TOKEN` bearer mode for Claude Code headers, ChatGPT Actions, and the `static_headers` beta.
-
-## 5. Phased plan
-
-| Phase | Deliver | Ship channel | Status |
-| --- | --- | --- | --- |
-| 1 | stdio MCP + Claude Code plugin + Actions bridge, read‑only mode, confirm gates | git marketplace now; npm publish; submit **Plugin bundle** to Anthropic's directory | **Done** (needs live-instance test, then submit) |
-| 2 | OAuth 2.1 AS in the bridge (§4), scopes, token store, audit log | custom connector by URL on claude.ai; ChatGPT app (dev mode → submission) | **Done** (self-hosted; DCR only; see `docs/oauth.md`). Untested against real claude.ai/ChatGPT clients |
-| 2b | **Multi-tenant public service**: per-user instance URL with SSRF-safe egress, Postgres store, key ring/rotation, idle revocation, Render blueprint, threat model | hosted bridge | **Built, untested live** (see SECURITY.md) |
-| 3 | Upstream: (i) PR/issue for **scoped board API keys**; (ii) optional Paperclip‑native plugin hosting the MCP endpoint behind Paperclip's own session auth | `paperclipai plugin install`; image catalog (`distribution/catalog.json`) | Later |
-
-Phase 3(ii) caveat **[unverified]**: plugin routes live only under `/api/plugins/:id/api/*` and can't claim root paths, while OAuth discovery wants `/.well-known/*` at the origin root (Claude lets the `401` point `resource_metadata` anywhere, but AS metadata must be at the issuer's well‑known path). A reverse‑proxy rule or a core change would be needed — test before committing to it.
-
-## 6. Risks and open questions
-
-1. **Never run against a live Paperclip yet.** Do that first, read‑only, then submit.
-2. A hosted bridge holds users' board credentials: needs encryption at rest, a security review, a privacy policy and incident process. Prefer self‑hosting until then.
-3. Prompt injection: issue/comment text from agents flows into the chat model. The skill tells Claude to treat it as data; consider output‑length and tag‑stripping limits.
-4. Paperclip's API is alpha and changes fast; pin tested versions and add a contract test against a real instance in CI.
-5. Directory policies and review criteria change; re‑read before each submission.
+# Architecture, auth and distribution plan
+
+Status: research + recommendation (Oct 2026). Sources: Paperclip source/docs (`paperclipai/paperclip`, read at depth‑1 clone) and Anthropic's connector/plugin docs. Items marked **[unverified]** are inferences or come from secondary sources and need testing before we rely on them.
+
+## 1. Verdict: integrate, don't rebuild
+
+Keep Paperclip as the system of record and build *around* it. Rebuilding is not justified:
+
+- Paperclip is a large, active codebase (8k+ files, ~295 DB migrations, adapters for ~10 agent runtimes, governance, budgets, approvals, MCP gateway, plugin SDK). Our goals — control, sync, reports, API use — are all reachable through its existing REST API. Nothing we need requires different core semantics.
+- A fork forfeits upstream fixes and the Paperclip community's agents/templates (ClipHub). A rebuild would cost far more than the integration gaps below.
+- The real gaps are **auth scoping** and **transport/OAuth**, and both can be solved in a front layer or contributed upstream.
+
+## 2. What Paperclip gives us (relevant facts)
+
+| Area | Fact | Consequence |
+| --- | --- | --- |
+| API | REST under `/api`; company-scoped; JSON; errors `{error}` | Our bridge is a thin client — no DB access, no business logic |
+| Auth modes | `local_trusted` (no login, loopback) · `authenticated/private` · `authenticated/public` (Better Auth sessions) | Bridge must work with no token (local) and with a token (everything else) |
+| Operator creds | **Board API keys** (`board_api_keys`: hashed, `expiresAt`, `revokedAt`, `lastUsedAt`, bound to a *user*). **No scope or company column** | A board key = that user's full board power. Never hand one to a public third party |
+| Login for tools | CLI challenge flow: client creates a challenge → user approves at `approvalUrl` in Paperclip's UI → client polls and receives a board token | Reusable as our "Sign in with Paperclip" step (no passwords touch our code) |
+| Agent creds | Agent keys / run JWTs; pause, resume, approve etc. are **board‑only** | Operator control must use board creds (documented in README) |
+| OAuth | Paperclip is an OAuth **client** (to upstream MCP servers). It is **not** an authorization server | claude.ai / ChatGPT connectors can't authenticate to Paperclip directly |
+| MCP | Official `@paperclipai/mcp-server` is a stdio wrapper for use inside agent runs. "Gateway mode" is agent→upstream, with profiles/policies/audit. No operator‑facing remote `/mcp` | Our bridge is the missing operator-side endpoint |
+| Plugins | Real plugin runtime: manifest + worker + UI; capability‑gated worker APIs; `apiRoutes` mounted only at `/api/plugins/:id/api/*`; plugins are trusted code; capability additions → `upgrade_pending` until an operator approves; install by npm/local path/image catalog (`paperclipai plugin install`). **No public plugin marketplace** (ClipHub = company templates only) | A native plugin is possible but distribution is operator‑installed, not store‑based |
+
+## 3. How public plugins actually ship (Claude & ChatGPT)
+
+**Claude** (docs.claude.com connector + plugin docs):
+- **Plugin bundle** (skills, commands, local MCP server like ours): public GitHub repo with `.claude-plugin/plugin.json`, README, LICENSE → `claude plugin validate` → submit at `claude.ai/directory/manage` ("Plugin bundle") → automated validation + security scan, sometimes human review → publish; later versions follow the tracked branch/tag. Data‑handling questions at submit time. Org can also share privately via a git marketplace (`/plugin marketplace add owner/repo`) — works today.
+- **Remote MCP connector** (what claude.ai web/mobile/Desktop use): must be HTTPS. Auth = OAuth 2.0 (DCR or Client‑ID‑Metadata‑Document, PKCE S256, `401` + `WWW-Authenticate: Bearer resource_metadata=…`, RFC 9728 protected‑resource metadata, RFC 8414 AS metadata, form‑encoded `/token`, refresh rotation, 10 s endpoint latency), or none, or a **static header credential (beta, limited orgs)**. Callbacks: `https://claude.ai/api/mcp/auth_callback` and a port‑agnostic loopback for Claude Code. Every tool needs `title` + `readOnlyHint`/`destructiveHint` (we already set these). Reviewers need a populated test account. Custom (unlisted) connectors can be added by URL by any user/org without review.
+- Plugins that reference a remote server should submit that server as a connector too.
+
+**ChatGPT** **[unverified: from secondary sources; I could not fetch OpenAI's docs]**:
+- *Apps SDK / MCP apps*: streamable‑HTTP MCP + OAuth 2.1 (DCR, PKCE); public submission needs a verified OpenAI org, public ToS + privacy policy, support contact, demo video, test account and test cases.
+- *Custom GPT Actions*: OpenAPI + API‑key or OAuth; shareable via link or GPT Store. This is what we ship today (bearer key).
+
+## 4. Auth design for public use
+
+Problem: board keys are all‑powerful, and the connector UIs want OAuth. Solution: put an **OAuth 2.1 authorization server inside the bridge** that fronts Paperclip.
+
+```
+claude.ai / ChatGPT ──OAuth 2.1 + PKCE──▶ bridge (AS + resource server) ──board token──▶ Paperclip /api
+                                              │
+   /authorize ──▶ create Paperclip CLI-auth challenge ──▶ user approves in Paperclip UI
+                  (bridge receives board token, stores it encrypted, mints its OWN scoped token)
+```
+
+- **Sign‑in:** reuse Paperclip's challenge/approve flow, so users authenticate to *their* Paperclip, not to us.
+- **Scopes enforced by the bridge** (Paperclip can't): `paperclip:read` (reports, sync, lists) · `paperclip:control` (every tool: pause/resume/wake/terminate, issues, comments, goals, approvals, budgets, raw non‑GET). Default consent = read. The bridge already classifies tools `read|write|destructive`; map those to scopes.
+- **Tokens:** short‑lived access JWT (audience = bridge URL), rotating refresh tokens, per‑user revocation (and revoke the Paperclip key on disconnect via `auth revoke-current`). Tokens bound to one company if the user picks one at consent.
+- **Registration:** support CIMD first (no client sprawl), DCR as fallback.
+- **Endpoints to add:** `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`, `/register`, `/authorize`, `/token`, `/revoke`; `401` challenge on `/mcp`.
+- **Multi‑tenancy:** every Paperclip instance has its own URL. Options: (a) *self‑hosted bridge per operator* (their own domain) — add as a **custom connector by URL**, no directory needed; (b) *one hosted multi‑tenant bridge* where the user supplies their instance URL at consent (needs SSRF‑safe URL validation + Claude "URL pattern"/custom‑connection mode, which takes longer to review); (c) *Paperclip Cloud* — a fixed URL pattern per stack, the cleanest directory story but needs Paperclip's cooperation.
+- Keep `BRIDGE_TOKEN` bearer mode for Claude Code headers, ChatGPT Actions, and the `static_headers` beta.
+
+## 5. Phased plan
+
+| Phase | Deliver | Ship channel | Status |
+| --- | --- | --- | --- |
+| 1 | stdio MCP + Claude Code plugin + Actions bridge, read‑only mode, confirm gates | git marketplace now; npm publish; submit **Plugin bundle** to Anthropic's directory | **Done** (needs live-instance test, then submit) |
+| 2 | OAuth 2.1 AS in the bridge (§4), scopes, token store, audit log | custom connector by URL on claude.ai; ChatGPT app (dev mode → submission) | **Done** (self-hosted; DCR only; see `docs/oauth.md`). Untested against real claude.ai/ChatGPT clients |
+| 2b | **Multi-tenant public service**: per-user instance URL with SSRF-safe egress, Postgres store, key ring/rotation, idle revocation, Render blueprint, threat model | hosted bridge | **Built, untested live** (see SECURITY.md) |
+| 3a | **Paperclip plugin** (connection manager inside Paperclip, `plugin/`) | `paperclipai plugin install` from npm | **Built (v1.2.0-beta.1), untested in a live Paperclip** |
+| 3 | Upstream: (i) PR/issue for **scoped board API keys**; (ii) optional Paperclip‑native plugin hosting the MCP endpoint behind Paperclip's own session auth | `paperclipai plugin install`; image catalog (`distribution/catalog.json`) | Later |
+
+Phase 3(ii) caveat **[unverified]**: plugin routes live only under `/api/plugins/:id/api/*` and can't claim root paths, while OAuth discovery wants `/.well-known/*` at the origin root (Claude lets the `401` point `resource_metadata` anywhere, but AS metadata must be at the issuer's well‑known path). A reverse‑proxy rule or a core change would be needed — test before committing to it.
+
+## 6. Risks and open questions
+
+1. **Never run against a live Paperclip yet.** Do that first, read‑only, then submit.
+2. A hosted bridge holds users' board credentials: needs encryption at rest, a security review, a privacy policy and incident process. Prefer self‑hosting until then.
+3. Prompt injection: issue/comment text from agents flows into the chat model. The skill tells Claude to treat it as data; consider output‑length and tag‑stripping limits.
+4. Paperclip's API is alpha and changes fast; pin tested versions and add a contract test against a real instance in CI.
+5. Directory policies and review criteria change; re‑read before each submission.

package/docs/COMMUNITY.md

@@ -0,0 +1,86 @@
+# Community: Discord, Discussions and socials
+
+A ready-to-follow setup for the Papercliped Discord, plus where everything else lives. Links show up on the website only once they're set (`web/src/config/community.ts`, or `VITE_DISCORD_URL`, `VITE_X_URL`, `VITE_DISCUSSIONS_URL`, `VITE_FORUM_URL` at build time). Nothing here needs a bot.
+
+## 1. Create the server (about 20 minutes)
+
+1. Discord → **+ → Create My Own → For a club or community**. Name: **Papercliped**. Icon: `web/public/brand/mascot-dark.svg` exported to PNG (or the 512px social image).
+2. **Server Settings → Enable Community.** This turns on rules screening, a rules channel and an announcements channel.
+3. **Safety Setup:** verification level **Medium** (verified email, on Discord 5+ minutes); explicit media filter **all members**; turn on **AutoMod** with "Block commonly flagged words", "Block mention spam" (limit 5) and a custom rule that blocks messages matching `pcs_`, `pcb_` and `sk-` (secret keys and tokens), with the reply "Never post secret keys. Make a new one in the Papercliped plugin."
+4. **Invite link:** never expires, no use limit. Put it in `VITE_DISCORD_URL` (Render env for the website build) and tell a maintainer to add it to `.github/ISSUE_TEMPLATE/config.yml`.
+
+## 2. Channels
+
+| Category | Channel | Who can post | What for |
+| --- | --- | --- | --- |
+| **Start here** | `#rules` | Maintainers | Server rules (below); Community "rules screening" uses it |
+| | `#welcome` | Maintainers | What Papercliped is, links to docs and install steps |
+| | `#announcements` | Maintainers | Releases (automatic, below) and news; members can follow it into their own servers |
+| | `#get-contributor` | Everyone | Post a link to your merged PR to get the Contributor role |
+| **Community** | `#general` | Everyone | Chat |
+| | `#help` (Forum channel) | Everyone | One post per question; tags: Claude, ChatGPT, Codex, Plugin, Self-hosting, Solved |
+| | `#ideas` (Forum channel) | Everyone | Feature ideas; good ones become GitHub issues |
+| | `#show-and-tell` | Everyone | What you built with your agents; the only place for self-promotion |
+| **Build** | `#contributors` | Contributors and up | Coordinating work, reviews, design questions |
+| | `#releases-feed` | Bot (webhook) | Every GitHub release, automatically |
+| | `#maintainers` (private) | Maintainers | Moderation and security coordination; never discuss vulnerability details anywhere else |
+
+## 3. Roles
+
+| Role | Colour | Given to | Permissions beyond default |
+| --- | --- | --- | --- |
+| **Maintainer** | Cream `#e9e4b0` | People with merge and release rights on GitHub | Manage messages, timeout members, post in Start here, see `#maintainers` |
+| **Triager** | Blue | People with GitHub triage access | Manage threads in `#help`/`#ideas`, mark Solved |
+| **Contributor** | Green | Anyone with a merged pull request | Post in `#contributors` |
+| **Member** | default | Everyone who accepts the rules | Post in Community |
+
+Keep the list of Maintainers on Discord identical to GitHub's. Remove roles when people step back.
+
+## 4. Rules (paste into `#rules`)
+
+1. Be kind. Follow the [code of conduct](https://github.com/OpenSourcx/papercliped/blob/main/CODE_OF_CONDUCT.md).
+2. **Never post secret keys, tokens or Paperclip addresses with credentials.** If you do by accident, make a new key in the Papercliped plugin straight away and tell a maintainer.
+3. Security problems go to support@papercliped.co or GitHub's private reporting, never a channel.
+4. One question per `#help` post, with what you tried and the error you saw.
+5. No spam or DMs to people you don't know. Self-promotion only in `#show-and-tell`.
+6. Stay on topic: Papercliped, Paperclip and running AI agents.
+7. Maintainers' moderation decisions are final; appeal by email to support@papercliped.co.
+
+## 5. Welcome message (paste into `#welcome`)
+
+> **Welcome to Papercliped!** Papercliped connects Claude, ChatGPT, Codex and any MCP app to your Paperclip.
+>
+> • Install it: https://github.com/OpenSourcx/papercliped#add-it-to-your-ai-app
+> • Docs: https://docs.papercliped.co
+> • Stuck? Open a post in #help. Ideas go in #ideas.
+> • Want to contribute? Read https://github.com/OpenSourcx/papercliped/blob/main/CONTRIBUTING.md, then grab a `good first issue`.
+>
+> Never post your secret key or tokens.
+
+## 6. Onboarding
+
+**Server Settings → Onboarding:** default channels `#welcome`, `#general`, `#help`, `#announcements`. One question, "What do you use Papercliped with?" (Claude / ChatGPT / Codex / Plugin in Paperclip / Self-hosting). Each answer is just a tag for now; it helps us see where people come from.
+
+## 7. Releases into Discord automatically
+
+Every push to `main` becomes a GitHub release (see [RELEASING.md](RELEASING.md)). To post them:
+
+1. In `#releases-feed`: **Edit Channel → Integrations → Webhooks → New Webhook**, copy its URL.
+2. GitHub → repository **Settings → Webhooks → Add webhook**. Payload URL: the Discord URL **with `/github` added at the end**. Content type `application/json`. **Let me select individual events → Releases** only.
+3. Optionally do the same for `#announcements`, so major and minor releases are visible there; patches stay in the feed.
+
+## 8. Becoming a contributor (how roles are given)
+
+1. Someone's pull request is merged.
+2. They post the link in `#get-contributor`.
+3. A maintainer checks it and gives the Contributor role (and adds them to the release thanks).
+
+Triager and Maintainer are by invitation, decided by the maintainers together; see "From first PR to maintainer" in [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## GitHub Discussions (the forum)
+
+Turn on **Discussions** in the repository settings with the categories Q&A, Ideas, Show and tell and Announcements. Then set `FORUM_URL=https://github.com/OpenSourcx/papercliped/discussions` on the bridge (Render), so `forum.papercliped.co` redirects there, and `VITE_DISCUSSIONS_URL` / `VITE_FORUM_URL` for the website. Pin a "Start here" discussion that links the README install steps.
+
+## X (social)
+
+Create the account, set `VITE_X_URL`, and post major and minor releases from the changelog feed (`https://papercliped.co/changelog.xml`).

package/docs/DEPLOY-RENDER.md

@@ -1,3 +1,3 @@
-# Deploying on Render
-
-The deployment guide now lives in **[LAUNCH.md](LAUNCH.md)** (Supabase → Render free → Cloudflare domain → keep-alive → panel → marketplaces → npm).
+# Deploying on Render
+
+The deployment guide now lives in **[LAUNCH.md](LAUNCH.md)** (Supabase → Render free → Cloudflare domain → keep-alive → panel → marketplaces → npm).

package/docs/DOMAINS.md

@@ -0,0 +1,74 @@
+# Domains and hosts (papercliped.co)
+
+One bridge service answers every host; it routes by the `Host` header. Nothing here needs a second server.
+
+| Host | What it serves |
+| --- | --- |
+| `papercliped.co` | The website (landing, status, changelog, community, brand, privacy, terms) and every API |
+| `www.papercliped.co` | Redirects to `papercliped.co` (same path) |
+| `docs.papercliped.co` | The docs: the landing at `/` and each page at `/<page>` (e.g. `/permissions`); old `/docs/...` and `/topics/...` links redirect there |
+| `mcp.papercliped.co` | **Where AI apps connect** (`/mcp`, the OAuth issuer), ChatGPT Actions and `/openapi.json`; web pages redirect to `papercliped.co` |
+| `api.papercliped.co` | `/api/public/v1/*` and `/openapi.json`; web pages redirect to `papercliped.co` |
+| `forum.papercliped.co` | Redirects to the forum (`FORUM_URL`; GitHub Discussions to start, see `docs/COMMUNITY.md`) |
+
+Every host also answers the protocol and API paths (`/mcp`, `/authorize`, `/token`, `/register`, `/revoke`, `/.well-known/*`, `/actions/*`, `/openapi.json`, `/api/*`, `/healthz`, `/readyz`), so nothing breaks if an app or person uses another host for them.
+
+## 1. Cloudflare DNS
+In Cloudflare → `papercliped.co` → **DNS → Records**, add (Render shows the exact target, `<service>.onrender.com`):
+
+| Type | Name | Target | Proxy |
+| --- | --- | --- | --- |
+| CNAME | `@` | `<service>.onrender.com` | DNS only |
+| CNAME | `www` | `<service>.onrender.com` | DNS only |
+| CNAME | `docs` | `<service>.onrender.com` | DNS only |
+| CNAME | `mcp` | `<service>.onrender.com` | DNS only |
+| CNAME | `api` | `<service>.onrender.com` | DNS only |
+| CNAME | `forum` | `<service>.onrender.com` | DNS only |
+
+Start with **DNS only (grey cloud)** so Render can issue certificates. SSL/TLS mode: **Full (strict)**. If you later turn on proxying (orange cloud), set `BRIDGE_PROXY_HOPS=2` and keep challenges off the API paths (`docs/LAUNCH.md` §3C).
+
+## 2. Render
+Render → the service → **Settings → Custom Domains → Add** each of: `papercliped.co`, `www.papercliped.co`, `docs.papercliped.co`, `mcp.papercliped.co`, `api.papercliped.co`, `forum.papercliped.co`. Click **Verify** on each and wait for the certificates.
+
+## 3. Environment (Render → Environment)
+```
+PUBLIC_HOSTS=marketing=papercliped.co,www.papercliped.co;docs=docs.papercliped.co;api=mcp.papercliped.co,api.papercliped.co;forum=forum.papercliped.co
+FORUM_URL=https://github.com/OpenSourcx/papercliped/discussions
+```
+The first `marketing` host is the canonical one. Hosts you don't list (like `<service>.onrender.com`) still serve the whole site, so the service stays reachable while DNS changes. The Docker image builds the website and the bridge finds it at `/app/web/dist` (override with `WEB_DIST`).
+
+## 4. The OAuth issuer: mcp.papercliped.co (decided)
+`BRIDGE_PUBLIC_URL` is the OAuth issuer **and** the resource AI apps connect to, so an app's connector URL must be `<BRIDGE_PUBLIC_URL>/mcp`. Papercliped uses:
+```
+BRIDGE_PUBLIC_URL=https://mcp.papercliped.co
+```
+Connector URL: **`https://mcp.papercliped.co/mcp`** (ChatGPT Actions: `https://mcp.papercliped.co/openapi.json`). The website and docs stay on `papercliped.co`; the docs show the connector URL through the `{{MCP}}` placeholder.
+
+**Changing `BRIDGE_PUBLIC_URL` invalidates every existing token**, so everyone connected must connect again (at the time of the switch, only the owner). After switching:
+- Claude: Settings → Connectors → remove the old connector, add `https://mcp.papercliped.co/mcp`. Claude Code: `claude mcp remove papercliped` then `claude mcp add --transport http papercliped https://mcp.papercliped.co/mcp`.
+- ChatGPT: re-add the connector, or re-import `https://mcp.papercliped.co/openapi.json` into the GPT.
+- The Paperclip plugin needs nothing: it talks to `/api/manage` and `/api/public`, which work on every host (its default bridge URL stays `https://papercliped.co`).
+
+## 5. Check
+```
+curl -sI https://www.papercliped.co/status         # 301 → https://papercliped.co/status
+curl -sI https://docs.papercliped.co/              # 200 (the docs landing)
+curl -sI https://papercliped.co/docs/permissions   # 301 → https://docs.papercliped.co/permissions
+curl -s  https://api.papercliped.co/api/public/v1/status
+curl -s  https://mcp.papercliped.co/.well-known/oauth-authorization-server | head -c 200   # issuer: https://mcp.papercliped.co
+curl -sI https://forum.papercliped.co/             # 302 → the forum
+```
+
+On **Windows PowerShell**, `curl` is a different command: use `curl.exe` (built into Windows 10 and 11), and drop `| head -c 200`:
+```powershell
+curl.exe -sI https://www.papercliped.co/status
+curl.exe -sI https://docs.papercliped.co/
+curl.exe -sI https://papercliped.co/docs/permissions
+curl.exe -s  https://api.papercliped.co/api/public/v1/status
+curl.exe -s  https://mcp.papercliped.co/.well-known/oauth-authorization-server
+curl.exe -sI https://forum.papercliped.co/
+```
+"Could not resolve host" means the DNS record is missing or still spreading; a certificate error means Render hasn't verified that domain yet; a `200` where a `301` is expected means `PUBLIC_HOSTS` isn't set (or the service hasn't redeployed).
+
+## Rollback
+Remove `PUBLIC_HOSTS` and redeploy: every host serves the whole site again, with docs at `/docs`. To go back to the old Markdown pages entirely, set `WEB_DIST` to a folder that doesn't exist. DNS records and Render custom domains can stay.