papercliped 1.1.0-beta.2 → 2.1.0

package/migrations/003_accounts.sql

@@ -1,66 +1,66 @@
--- Papercliped accounts: username + secret key, one stored Paperclip connection per account, and the user event log.
--- Nothing here stores a plaintext secret: `secret_hash` is a salted scrypt hash, `sealed_credential` is AES-GCM sealed in the app.
-
-create table if not exists bridge.accounts (
-  id            text   primary key,
-  username      text   not null,               -- as typed; shown only in the operator's logs
-  username_key  text   not null,               -- lowercased; unique
-  secret_hash   text   not null,               -- scrypt$N$r$p$salt$hash of the generated secret key
-  created_at    bigint not null,
-  last_login_at bigint,
-  disabled      boolean not null default false
-);
-create unique index if not exists accounts_username_key_idx on bridge.accounts (username_key);
-
--- One connection per account. A given Paperclip identity (instance + user id) can belong to only one account.
-create table if not exists bridge.account_links (
-  account_id         text   primary key references bridge.accounts (id) on delete cascade,
-  instance_url       text   not null,
-  paperclip_user_id  text,
-  sealed_credential  text,                      -- null once dropped (idle expiry / disconnect)
-  created_at         bigint not null,
-  connected_at       bigint not null,
-  last_used_at       bigint not null
-);
-create unique index if not exists account_links_identity_idx on bridge.account_links (instance_url, paperclip_user_id) where paperclip_user_id is not null;
-create index if not exists account_links_idle_idx on bridge.account_links (last_used_at) where sealed_credential is not null;
-
--- The community log: joined / left / updated / login / ... (see src/accounts/types.ts). `detail` is a short non-sensitive reason.
-create table if not exists bridge.user_events (
-  id          bigint generated always as identity primary key,
-  ts          bigint not null,
-  account_id  text,
-  username    text,
-  kind        text   not null,
-  detail      text
-);
-create index if not exists user_events_ts_idx   on bridge.user_events (ts desc);
-create index if not exists user_events_kind_idx on bridge.user_events (kind, ts desc);
-
--- A row the app rewrites on a timer so a free-tier Supabase project always sees recent write activity.
-create table if not exists bridge.heartbeat (
-  id integer primary key,
-  at bigint  not null
-);
-
-alter table bridge.grants       add column if not exists account_id text;
-alter table bridge.grants       add column if not exists username   text;
-alter table bridge.audit_events add column if not exists username   text;
-create index if not exists grants_account_idx on bridge.grants (account_id) where not revoked;
-create index if not exists audit_username_idx on bridge.audit_events (username, ts desc) where username is not null;
-
-alter table bridge.accounts      enable row level security;
-alter table bridge.account_links enable row level security;
-alter table bridge.user_events   enable row level security;
-alter table bridge.heartbeat     enable row level security;
-revoke all on bridge.accounts, bridge.account_links, bridge.user_events, bridge.heartbeat from public;
-
-do $$
-declare r text;
-begin
-  foreach r in array array['anon', 'authenticated'] loop
-    if exists (select 1 from pg_roles where rolname = r) then
-      execute format('revoke all on bridge.accounts, bridge.account_links, bridge.user_events, bridge.heartbeat from %I', r);
-    end if;
-  end loop;
-end $$;
+-- Papercliped accounts: username + secret key, one stored Paperclip connection per account, and the user event log.
+-- Nothing here stores a plaintext secret: `secret_hash` is a salted scrypt hash, `sealed_credential` is AES-GCM sealed in the app.
+
+create table if not exists bridge.accounts (
+  id            text   primary key,
+  username      text   not null,               -- as typed; shown only in the operator's logs
+  username_key  text   not null,               -- lowercased; unique
+  secret_hash   text   not null,               -- scrypt$N$r$p$salt$hash of the generated secret key
+  created_at    bigint not null,
+  last_login_at bigint,
+  disabled      boolean not null default false
+);
+create unique index if not exists accounts_username_key_idx on bridge.accounts (username_key);
+
+-- One connection per account. A given Paperclip identity (instance + user id) can belong to only one account.
+create table if not exists bridge.account_links (
+  account_id         text   primary key references bridge.accounts (id) on delete cascade,
+  instance_url       text   not null,
+  paperclip_user_id  text,
+  sealed_credential  text,                      -- null once dropped (idle expiry / disconnect)
+  created_at         bigint not null,
+  connected_at       bigint not null,
+  last_used_at       bigint not null
+);
+create unique index if not exists account_links_identity_idx on bridge.account_links (instance_url, paperclip_user_id) where paperclip_user_id is not null;
+create index if not exists account_links_idle_idx on bridge.account_links (last_used_at) where sealed_credential is not null;
+
+-- The community log: joined / left / updated / login / ... (see src/accounts/types.ts). `detail` is a short non-sensitive reason.
+create table if not exists bridge.user_events (
+  id          bigint generated always as identity primary key,
+  ts          bigint not null,
+  account_id  text,
+  username    text,
+  kind        text   not null,
+  detail      text
+);
+create index if not exists user_events_ts_idx   on bridge.user_events (ts desc);
+create index if not exists user_events_kind_idx on bridge.user_events (kind, ts desc);
+
+-- A row the app rewrites on a timer so a free-tier Supabase project always sees recent write activity.
+create table if not exists bridge.heartbeat (
+  id integer primary key,
+  at bigint  not null
+);
+
+alter table bridge.grants       add column if not exists account_id text;
+alter table bridge.grants       add column if not exists username   text;
+alter table bridge.audit_events add column if not exists username   text;
+create index if not exists grants_account_idx on bridge.grants (account_id) where not revoked;
+create index if not exists audit_username_idx on bridge.audit_events (username, ts desc) where username is not null;
+
+alter table bridge.accounts      enable row level security;
+alter table bridge.account_links enable row level security;
+alter table bridge.user_events   enable row level security;
+alter table bridge.heartbeat     enable row level security;
+revoke all on bridge.accounts, bridge.account_links, bridge.user_events, bridge.heartbeat from public;
+
+do $$
+declare r text;
+begin
+  foreach r in array array['anon', 'authenticated'] loop
+    if exists (select 1 from pg_roles where rolname = r) then
+      execute format('revoke all on bridge.accounts, bridge.account_links, bridge.user_events, bridge.heartbeat from %I', r);
+    end if;
+  end loop;
+end $$;

package/migrations/004_privacy_panel.sql

@@ -1,57 +1,57 @@
--- Privacy (anonymous display names) and the separate operator panel.
---
---  * Accounts can opt in to appear in logs and the panel as a generated alias ("Ann02") and with an anonymous label instead of
---    their Paperclip's hostname. Events and audit rows store only the DISPLAY name, so the panel's database role never sees the
---    real username of an anonymous account. (The service operator with admin access to the base tables still can; see docs/SECURITY.md.)
---  * The bridge writes periodic health samples; the panel reads them, so it can tell when the bridge is down or asleep.
---  * The panel connects with a read-only role that can see only the views and telemetry tables below — never the credential,
---    the secret hash, or real usernames.
-
-alter table bridge.accounts      add column if not exists anonymous boolean not null default false;
-alter table bridge.accounts      add column if not exists alias     text;
-alter table bridge.account_links add column if not exists instance_label text;   -- the host, or "anon-xxxxxx" for anonymous accounts
-create unique index if not exists accounts_alias_idx on bridge.accounts (lower(alias)) where alias is not null;
-
-create table if not exists bridge.node_samples (
-  id               bigint generated always as identity primary key,
-  ts               bigint not null,
-  node             text   not null,
-  db_ping_ms       real,
-  loop_lag_p99_ms  real,
-  rss_mb           real,
-  heap_mb          real,
-  uptime_s         integer,
-  version          text
-);
-create index if not exists node_samples_ts_idx   on bridge.node_samples (ts desc);
-create index if not exists node_samples_node_idx on bridge.node_samples (node, ts desc);
-alter table bridge.node_samples enable row level security;
-revoke all on bridge.node_samples from public;
-
--- Views run with the rights of the role that owns them (the migration role), so the panel role needs no access to the base tables.
-create or replace view bridge.panel_accounts as
-  select id,
-         case when anonymous and alias is not null then alias else username end as display_name,
-         (anonymous and alias is not null) as anonymous,
-         created_at, last_login_at, disabled
-    from bridge.accounts;
-
-create or replace view bridge.panel_grants as
-  select id, client_name, scopes, created_at, last_used_at, revoked, account_id, username as display_name
-    from bridge.grants;
-
-create or replace view bridge.panel_links as
-  select account_id, coalesce(instance_label, 'unknown') as instance_label, connected_at, last_used_at, (sealed_credential is not null) as has_credential
-    from bridge.account_links;
-
-revoke all on bridge.panel_accounts, bridge.panel_grants, bridge.panel_links from public;
-
-do $$
-declare r text;
-begin
-  foreach r in array array['anon', 'authenticated'] loop
-    if exists (select 1 from pg_roles where rolname = r) then
-      execute format('revoke all on bridge.node_samples, bridge.panel_accounts, bridge.panel_grants, bridge.panel_links from %I', r);
-    end if;
-  end loop;
-end $$;
+-- Privacy (anonymous display names) and the separate operator panel.
+--
+--  * Accounts can opt in to appear in logs and the panel as a generated alias ("Ann02") and with an anonymous label instead of
+--    their Paperclip's hostname. Events and audit rows store only the DISPLAY name, so the panel's database role never sees the
+--    real username of an anonymous account. (The service operator with admin access to the base tables still can; see docs/SECURITY.md.)
+--  * The bridge writes periodic health samples; the panel reads them, so it can tell when the bridge is down or asleep.
+--  * The panel connects with a read-only role that can see only the views and telemetry tables below — never the credential,
+--    the secret hash, or real usernames.
+
+alter table bridge.accounts      add column if not exists anonymous boolean not null default false;
+alter table bridge.accounts      add column if not exists alias     text;
+alter table bridge.account_links add column if not exists instance_label text;   -- the host, or "anon-xxxxxx" for anonymous accounts
+create unique index if not exists accounts_alias_idx on bridge.accounts (lower(alias)) where alias is not null;
+
+create table if not exists bridge.node_samples (
+  id               bigint generated always as identity primary key,
+  ts               bigint not null,
+  node             text   not null,
+  db_ping_ms       real,
+  loop_lag_p99_ms  real,
+  rss_mb           real,
+  heap_mb          real,
+  uptime_s         integer,
+  version          text
+);
+create index if not exists node_samples_ts_idx   on bridge.node_samples (ts desc);
+create index if not exists node_samples_node_idx on bridge.node_samples (node, ts desc);
+alter table bridge.node_samples enable row level security;
+revoke all on bridge.node_samples from public;
+
+-- Views run with the rights of the role that owns them (the migration role), so the panel role needs no access to the base tables.
+create or replace view bridge.panel_accounts as
+  select id,
+         case when anonymous and alias is not null then alias else username end as display_name,
+         (anonymous and alias is not null) as anonymous,
+         created_at, last_login_at, disabled
+    from bridge.accounts;
+
+create or replace view bridge.panel_grants as
+  select id, client_name, scopes, created_at, last_used_at, revoked, account_id, username as display_name
+    from bridge.grants;
+
+create or replace view bridge.panel_links as
+  select account_id, coalesce(instance_label, 'unknown') as instance_label, connected_at, last_used_at, (sealed_credential is not null) as has_credential
+    from bridge.account_links;
+
+revoke all on bridge.panel_accounts, bridge.panel_grants, bridge.panel_links from public;
+
+do $$
+declare r text;
+begin
+  foreach r in array array['anon', 'authenticated'] loop
+    if exists (select 1 from pg_roles where rolname = r) then
+      execute format('revoke all on bridge.node_samples, bridge.panel_accounts, bridge.panel_grants, bridge.panel_links from %I', r);
+    end if;
+  end loop;
+end $$;

package/migrations/006_two_levels.sql

@@ -0,0 +1,5 @@
+-- Two access levels: Read only and Full control. The old third level (paperclip:admin) is folded into Full control,
+-- which now covers every tool. Existing grants keep working; this only tidies the stored scope lists.
+update bridge.grants
+   set scopes = array(select distinct s from unnest(array_replace(scopes, 'paperclip:admin', 'paperclip:control')) as s order by s desc)
+ where 'paperclip:admin' = any(scopes);

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "papercliped",
-  "version": "1.1.0-beta.2",
-  "description": "Papercliped \u2014 connect Claude and ChatGPT to your Paperclip: control agents, sync, report. MCP server + hosted multi-tenant OAuth bridge + separate operator panel.",
+  "version": "2.1.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",
   "bin": {
     "papercliped": "dist/stdio.js",
     "papercliped-bridge": "dist/http.js",
-    "papercliped-panel": "dist/panel/main.js",
     "papercliped-admin": "dist/cli.js"
   },
   "files": [
@@ -24,7 +23,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "start:stdio": "node dist/stdio.js",
@@ -33,24 +32,21 @@
     "migrate": "node dist/cli.js migrate",
     "start": "node dist/http.js",
     "admin": "node dist/cli.js",
-    "demo": "node dist/demo.js",
     "schema:sql": "node dist/cli.js schema-sql > docs/supabase-schema.sql",
-    "panel": "node dist/panel/main.js",
-    "start:panel": "node dist/panel/main.js",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.0",
     "pg": "^8.23.1",
-    "undici": "^7.30.0",
-    "zod": "^3.25.0",
-    "zod-to-json-schema": "^3.25.2"
+    "undici": "^8.11.2",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^26.6.4",
     "@types/pg": "^8.23.1",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
+    "typescript": "^7.0.2",
+    "vite": "^8.3.3",
+    "vitest": "^5.0.3"
   },
   "engines": {
     "node": ">=20.18"
@@ -59,7 +55,7 @@
     "type": "git",
     "url": "git+https://github.com/OpenSourcx/papercliped.git"
   },
-  "homepage": "https://papercliped.kpnsolute.com",
+  "homepage": "https://papercliped.co",
   "keywords": [
     "paperclip",
     "mcp",

package/site/docs/chatgpt.md

@@ -3,7 +3,7 @@
 Requires a ChatGPT plan that can create GPTs with Actions.
 
 1. Create a GPT, then **Configure → Create new action**.
-2. **Import from URL:** `{{URL}}/openapi.json`.
+2. **Import from URL:** `{{MCP}}/openapi.json`.
 3. **Authentication:** OAuth, using the endpoints listed at `{{URL}}/.well-known/oauth-authorization-server`.
 4. Add these instructions:
 

package/site/docs/cli.md

@@ -0,0 +1,27 @@
+# Command line
+
+Papercliped installs these commands (`npx -p papercliped@latest <command>`, or from a clone after `npm run build`).
+
+| Command | What it runs |
+| --- | --- |
+| `papercliped` | The MCP server over stdio, for one Paperclip (local use) |
+| `papercliped-bridge` | The HTTP bridge (MCP over HTTP, ChatGPT Actions, OAuth, the public site and APIs) |
+| `papercliped-admin` | Operator commands, below |
+
+## papercliped-admin
+Run it with the same environment as the bridge (it reads the same database).
+
+| Command | What it does |
+| --- | --- |
+| `migrate` | Apply database migrations |
+| `schema-sql` | Print the full schema as one SQL script (for pasting into Supabase) |
+| `users` | List accounts: name, anonymity, status, last sign-in |
+| `delete-user <username>` | Delete an account and everything tied to it |
+| `grants` | List live connections |
+| `revoke <grant id>` | Disconnect one connection |
+| `revoke-all --yes` | Disconnect every connection |
+| `sweep` | Revoke connections idle longer than `BRIDGE_IDLE_REVOKE_DAYS` |
+| `rotate-keys` | Re-seal stored Paperclip keys with the current `BRIDGE_SECRET` (after rotating it) |
+
+## npm scripts (in a clone)
+`npm test`, `npm run build`, `npm run start:http`, `npm run start:stdio`, `npm run openapi` (writes `openapi.json`), `npm run migrate`, `npm run schema:sql`.

package/site/docs/connect-your-paperclip.md

@@ -0,0 +1,120 @@
+# Set up your Paperclip for Papercliped
+
+Papercliped talks to **your** Paperclip over the internet, so your Paperclip needs a public address. This guide gets you one, step by step, whether you already own a domain or not.
+
+You don't need to open any ports on your router for any option below.
+
+## What Papercliped needs from your Paperclip
+- **A public `https://` address on port 443** that answers over the internet. Private, LAN, `localhost` and plain `http://` addresses are refused on purpose.
+- **Paperclip in authenticated mode and public exposure.** You can check from any computer:
+  ```
+  curl https://your-address/api/health
+  ```
+  A healthy answer is JSON that includes `"status":"ok"`, `"deploymentMode":"authenticated"` and `"deploymentExposure":"public"`. (On Windows PowerShell, `curl.exe https://your-address/api/health` works the same way.)
+- **No login wall or bot challenge in front of `/api/*`.** If you put something like Cloudflare Access, "Under Attack" mode or a managed challenge in front of Paperclip, it must skip `/api/*`, or Papercliped will be blocked.
+- **Paperclip must accept the new hostname.** Paperclip can reject hostnames it doesn't know, and public mode needs its public URL set. Paperclip's own settings for this include `PAPERCLIP_PUBLIC_URL` and `PAPERCLIP_ALLOWED_HOSTNAMES`; the exact steps are in Paperclip's deployment docs (search "Paperclip deployment modes" on docs.paperclip.ing). Check them there rather than guessing.
+
+Paperclip listens on port `3100` by default, which the examples below use. If yours is different, use your port.
+
+## Path A: you own a domain (recommended)
+This gives you a stable address like `https://paperclip.yourdomain.com` that survives restarts. The tunnel and DNS are free on Cloudflare's free plan. The domain itself isn't: there is no free `.com`. (Cloudflare Registrar sells domains at wholesale cost, so it's one cheap option if you need to buy one.)
+
+1. **Put your domain on Cloudflare.** Create a free Cloudflare account, add your domain, and switch its nameservers to the two Cloudflare gives you (done at the company where you bought the domain). Wait until Cloudflare shows the domain as active.
+2. **Install `cloudflared`** on the machine that runs Paperclip. Find the installer for Windows, macOS or Linux on Cloudflare's downloads page (search "cloudflared downloads").
+3. **Log in.** This opens a browser so you can pick your domain:
+   ```
+   cloudflared tunnel login
+   ```
+4. **Create the tunnel.** Pick any name:
+   ```
+   cloudflared tunnel create papercliped-paperclip
+   ```
+   It prints a tunnel ID (a UUID) and saves a credentials file in your `.cloudflared` folder. Keep that file private.
+5. **Write the config.** In your `.cloudflared` folder (`~/.cloudflared` on macOS/Linux, `%USERPROFILE%\.cloudflared` on Windows) create `config.yml`:
+   ```
+   tunnel: <TUNNEL-ID>
+   credentials-file: <PATH-TO-THE-CREDENTIALS-FILE>.json
+   ingress:
+     - hostname: paperclip.yourdomain.com
+       service: http://localhost:3100
+     - service: http_status:404
+   ```
+   The last rule is required: it answers 404 for anything else.
+6. **Point the name at the tunnel:**
+   ```
+   cloudflared tunnel route dns papercliped-paperclip paperclip.yourdomain.com
+   ```
+7. **Run it.** To try it first:
+   ```
+   cloudflared tunnel run papercliped-paperclip
+   ```
+   To keep it running (starts with your computer), install it as a service:
+   - **macOS:** `cloudflared service install` (runs when you log in) or `sudo cloudflared service install` (runs at boot).
+   - **Linux:** `cloudflared service install` (with `sudo` if needed).
+   - **Windows:** run `cloudflared.exe service install` from an Administrator PowerShell. A Windows service may not read the config from your user folder; check Cloudflare's "Run as a service on Windows" page for where it expects `config.yml`.
+8. **Check it** from any computer:
+   ```
+   curl https://paperclip.yourdomain.com/api/health
+   ```
+   You should see the JSON described above.
+
+**If your computer sleeps or turns off,** the tunnel goes down and your connected AI apps stop working until it's back. Turn off sleep on the machine, or run Paperclip on an always-on computer or server.
+
+## Path B: you don't have a domain yet
+All of these are free. They differ in how stable the address is.
+
+| Option | Address | Stable? | Good for |
+| --- | --- | --- | --- |
+| Tailscale Funnel | `https://<machine>.<tailnet>.ts.net` | Yes | Daily use |
+| ngrok free plan | one free static `ngrok-free.app` / `ngrok-free.dev` domain | Yes | Daily use, with a caveat below |
+| Cloudflare quick tunnel | random `*.trycloudflare.com` | **No, changes every restart** | Trying Papercliped only |
+
+### Tailscale Funnel (stable)
+Funnel makes a service on your computer reachable from the public internet at your tailnet's `ts.net` name.
+1. Create a free Tailscale account and install Tailscale on the machine that runs Paperclip.
+2. In the Tailscale admin console, turn on **HTTPS certificates** for your tailnet and allow Funnel. (Running the `tailscale funnel` command below walks you through enabling it and updates your tailnet policy for you.)
+3. Start Funnel for Paperclip's port:
+   ```
+   tailscale funnel 3100
+   ```
+   It prints your public address, like `https://my-pc.my-tailnet.ts.net`. Funnel only serves on ports 443, 8443 and 10000; use the default 443 for Papercliped.
+4. Funnel traffic has bandwidth limits you can't change. That is fine for Papercliped's small requests, but check Tailscale's Funnel docs for the current rules on your plan.
+
+### ngrok free plan (stable address, one catch)
+1. Create a free ngrok account. Every account gets one free static "dev domain" (for example `your-name.ngrok-free.dev`); see it in the ngrok dashboard under Domains.
+2. Install ngrok and add your authtoken (the dashboard shows the exact command).
+3. Run, with your own domain:
+   ```
+   ngrok http --url=your-name.ngrok-free.dev 3100
+   ```
+4. **The catch:** on the free plan ngrok shows a "visit site" warning page to browsers. Papercliped's requests come from a program, not a browser, but if the connection fails with a strange HTML page, this is the likely cause. Check ngrok's free-plan docs for the current behavior and any header that skips it.
+
+### Cloudflare quick tunnel (trial only)
+No account, no domain:
+```
+cloudflared tunnel --url http://localhost:3100
+```
+It prints a random `https://something.trycloudflare.com` address. **The address changes every time you restart it**, and when it changes your Papercliped connection stops working until you connect again with the new address. Quick tunnels are for trying Papercliped for an afternoon, not for daily use.
+
+## Connect to Papercliped
+1. Make sure `curl https://your-address/api/health` works (see above).
+2. Go to [Create your account]({{URL}}/docs/signup), add Papercliped as a connector in Claude, and choose **Connect your Paperclip**.
+3. Enter your public address (just the address, no path), then approve the request in your Paperclip.
+
+## Keep it safe
+- **Expose only Paperclip.** Point the tunnel at Paperclip's port and nothing else on your computer.
+- **Keep Paperclip up to date.**
+- **Use a dedicated Paperclip user for the connection** if you can, so you can see and limit what it does.
+- **You can cut access any time:** revoke the Papercliped key in Paperclip, or disconnect apps in the [Paperclip plugin](/docs/paperclip-plugin).
+- **If the tunnel or your computer is off,** connected apps simply stop working until it's back. Nothing is lost.
+
+## Troubleshooting
+- **"Could not reach your Paperclip":** the tunnel isn't running, the DNS name hasn't spread yet (give a new name a few minutes), or the address isn't on port 443. Test with `curl https://your-address/api/health` from another network (for example, your phone's mobile data).
+- **"Private address" errors:** you entered a LAN address, `localhost`, or `http://`. Use the public `https://` address from your tunnel.
+- **A challenge or login page appears:** exempt `/api/*` from Cloudflare Access, "Under Attack" mode or any managed challenge.
+- **"Host not allowed" or a 4xx from Paperclip:** Paperclip doesn't know the new hostname. Set its public URL and allowed hostnames (see Paperclip's deployment docs, above) and restart it.
+- **Certificate warnings:** use the HTTPS address your tunnel provider gives you, not your own certificate on a raw IP. Tunnels handle certificates for you.
+- **Worked yesterday, not today:** the address changed (quick tunnels do this), the tunnel stopped, or the computer slept.
+
+## Not independently confirmed
+These came from vendor docs summarized through search, not read page by page. Check the vendor's current docs before relying on them: Windows service setup for `cloudflared`, Tailscale's current Funnel limits, ngrok's free-plan warning page behavior, and Paperclip's exact setting names for public URL and allowed hostnames.

package/site/docs/environment.md

@@ -0,0 +1,64 @@
+# Environment variables
+
+Every setting the bridge reads, with its default. Only set what you need. Never put secrets in issues or commits.
+
+## Papercliped status tool
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `PAPERCLIPED_URL` | `https://papercliped.co` | Where the `papercliped_service_status` tool reads the public status API (https only) |
+
+## Paperclip (all modes)
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `PAPERCLIP_API_URL` | `http://localhost:3100` | Your Paperclip (local and single modes). `/api` is added if missing. |
+| `PAPERCLIP_API_KEY` | none | Board token for local and single modes (not needed in Paperclip's `local_trusted` mode) |
+| `PAPERCLIP_COMPANY_ID` | none | Default company for tools that take one |
+| `PAPERCLIP_READ_ONLY` | off | `1` blocks every change before it reaches Paperclip |
+| `PAPERCLIP_TIMEOUT_MS` | `30000` | Timeout for each Paperclip call |
+| `PAPERCLIP_PUBLIC_URL` | none | Single mode: the Paperclip address users' browsers open to approve sign-in, if different from the API address |
+
+## HTTP bridge
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `BRIDGE_HOST` | `127.0.0.1` (`0.0.0.0` when `PORT` is set) | Address to listen on |
+| `BRIDGE_PORT` / `PORT` | `3939` | Port |
+| `BRIDGE_PUBLIC_URL` | none | The public https origin. With OAuth it is the issuer: changing it disconnects every app |
+| `BRIDGE_TOKEN` | none | Static bearer token (single-Paperclip setups, ChatGPT Actions). Not allowed in multi mode |
+| `BRIDGE_PROXY_HOPS` | `0` | Trusted reverse proxies in front (for client addresses in rate limits); `1` on Render, `2` behind Cloudflare proxying too |
+| `BRIDGE_AUDIT_RETENTION_DAYS` | `30` | Audit rows older than this are deleted hourly |
+| `BRIDGE_AUDIT_STDERR` | on | Also print each audit event as a JSON line |
+| `BRIDGE_KEEPALIVE` | on | Free tiers: self-ping and database heartbeat every 10 minutes |
+| `PUBLIC_HOSTS` | none | Host roles for one service on several hosts, e.g. `marketing=papercliped.co,www.papercliped.co;docs=docs.papercliped.co;api=mcp.papercliped.co;forum=forum.papercliped.co` (see `docs/DOMAINS.md`) |
+| `FORUM_URL` | the marketing host's `/community` | Where the forum host redirects |
+| `WEB_DIST` | `web/dist` next to the package | The built website; without it the bridge serves its own Markdown pages |
+| `SITE_CONTACT` | the GitHub issues page | Contact shown on the privacy and terms pages |
+| `SITE_EFFECTIVE_DATE` | `2026-10-06` | Date shown on the privacy and terms pages |
+
+## OAuth (claude.ai, ChatGPT apps)
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `BRIDGE_OAUTH` | off | `1` turns on the built-in OAuth 2.1 server |
+| `BRIDGE_SECRET` | required | At least 32 characters (`openssl rand -hex 32`); seals stored credentials. Back it up |
+| `BRIDGE_SECRET_PREVIOUS` | none | Comma-separated old secrets, for rotation |
+| `BRIDGE_MODE` | `single` | `single` (one Paperclip) or `multi` (each user connects their own) |
+| `BRIDGE_LOGIN` | `paperclip` | `paperclip` (approve in Paperclip) or `static` (operator password = `BRIDGE_TOKEN`; single mode only) |
+| `BRIDGE_DATA_FILE` | none | JSON file for state (single mode, no database) |
+| `BRIDGE_ACCESS_TTL_SEC` | `3600` | Access token lifetime |
+| `BRIDGE_REFRESH_TTL_SEC` | `2592000` (30 days) | Refresh token lifetime |
+| `BRIDGE_IDLE_REVOKE_DAYS` | `30` | Revoke connections unused this long (`0` = never) |
+| `BRIDGE_CALLS_PER_MINUTE` | `120` | Tool calls per minute per connection |
+| `BRIDGE_OAUTH_REDIRECT_HOSTS` | claude.ai, claude.com, chatgpt.com, chat.openai.com, platform.openai.com | Hosts allowed as OAuth redirect targets |
+| `BRIDGE_INSTANCE_ALLOWLIST` | any | Multi mode: only these Paperclip hosts (`*.example.com` allowed) |
+| `BRIDGE_INSTANCE_DENYLIST` | none | Multi mode: never these hosts |
+| `BRIDGE_ALLOWED_PORTS` | `443` | Multi mode: ports a Paperclip address may use |
+| `BRIDGE_ALLOW_EPHEMERAL` | off | Multi mode without a database, for local experiments only |
+
+## Database (Postgres)
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `DATABASE_URL` | none | Postgres connection (required in multi mode) |
+| `DATABASE_SSL` | `verify` | `verify`, `require` or `off` |
+| `DATABASE_CA` | none | CA certificate (PEM; `\n` for newlines) for `verify` |
+| `DATABASE_POOL_MAX` | `10` | Connection pool size |
+| `BRIDGE_AUTO_MIGRATE` | off | Apply migrations at start |
+| `DATABASE_MIGRATE_URL` | `DATABASE_URL` | A different (admin) connection for migrations |

package/site/docs/faq.md

@@ -0,0 +1,31 @@
+# FAQ
+
+## Is Papercliped free?
+Yes. It's free and open source under the MIT licence. The hosted bridge at papercliped.co runs the same code you can run yourself.
+
+## Is it made by Paperclip?
+No. Papercliped is an independent community project that uses Paperclip's public API.
+
+## What does the AI see?
+Only what it asks for through the tools, within your level. Issue and comment text written by agents can reach the AI; treat it as data, not instructions.
+
+## What do you store?
+Your username, a hash of your secret key, your Paperclip's address, an encrypted Paperclip key, connection records and a 30-day activity log. Details in [Privacy](/privacy).
+
+## Can I use it without a public Paperclip?
+Yes: run it locally with `npx papercliped@latest`. The hosted bridge needs a public https address; see [Set up your Paperclip](/docs/connect-your-paperclip).
+
+## 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).
+
+## 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.
+
+## 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.
+
+## Does it work with ChatGPT?
+Yes, through ChatGPT's MCP connectors or GPT Actions. See [ChatGPT setup](/docs/chatgpt).
+
+## Where do I report a bug or suggest something?
+On GitHub: [open an issue](https://github.com/OpenSourcx/papercliped/issues), or use the community page on papercliped.co. Security problems go privately to support@papercliped.co.

package/site/docs/getting-started.md

@@ -3,12 +3,12 @@
 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.
 
 ## 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.
+- 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 [Set up your Paperclip](/docs/connect-your-paperclip).
 - A Claude account that can add connectors, or Claude Code.
 
 ## Connect from Claude
 1. In Claude open **Settings → Connectors → Add custom connector**.
-2. Use the address `{{URL}}/mcp` and click **Connect**.
+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**.
@@ -16,18 +16,24 @@ Papercliped connects Claude (and ChatGPT) to **your** Paperclip. You keep contro
 
 ## Claude Code
 ```
-claude mcp add --transport http papercliped {{URL}}/mcp
+claude mcp add --transport http papercliped {{MCP}}/mcp
 ```
 Or install the plugin: `/plugin marketplace add OpenSourcx/papercliped`, then `/plugin install papercliped@papercliped`.
 
 ## Run it yourself (npm)
 ```
-npx papercliped@beta
+npx papercliped@latest
 ```
 This starts a local server for one Paperclip, using `PAPERCLIP_API_URL` and `PAPERCLIP_API_KEY`.
 
+## Other AI apps
+Any app that supports MCP can use Papercliped. See [Any AI app (MCP)](/docs/other-ai-apps).
+
+## Inside your Paperclip
+The Papercliped plugin for Paperclip is where you manage everything: connected apps, levels, privacy and your account. See [Paperclip plugin](/docs/paperclip-plugin).
+
 ## ChatGPT
-Papercliped publishes an OpenAPI description at `{{URL}}/openapi.json` for GPT Actions. See [ChatGPT setup](/docs/chatgpt).
+Papercliped publishes an OpenAPI description at `{{MCP}}/openapi.json` for GPT Actions. See [ChatGPT setup](/docs/chatgpt).
 
 See [Create your account](/docs/signup) for every screen in detail.