toolhome 0.5.0

package/skills/toolhome/references/cli-reference.md

@@ -0,0 +1,242 @@
+# CLI Reference
+
+## auth
+
+```bash
+export TOOLHOME_URL="https://tool.cyncyn.xyz"
+export TOOLHOME_CONTROL_KEY="tch_ctl_<your-control-key>"
+toolhome auth login --url "$TOOLHOME_URL" --control-key "$TOOLHOME_CONTROL_KEY"
+toolhome auth logout
+```
+
+Credentials saved to `~/.config/toolhome/config.json` (0600). Supports env vars `TOOLHOME_URL`, `TOOLHOME_CONTROL_KEY`, and `TOOLHOME_CONFIG` (an alternate config-file path).
+
+## server
+
+```bash
+toolhome server list                          # list all servers
+toolhome server get <id>                      # get a server by id
+toolhome server add <file|->                  # add from JSON file or stdin
+toolhome server update <id> <file|->          # update fields (partial)
+toolhome server delete <id>                   # delete a server
+toolhome server enable <id>                   # enable
+toolhome server disable <id>                  # disable
+toolhome server refresh <id>                  # force reconnect + snapshot
+toolhome server restart <id>                  # restart home-hosted stdio
+toolhome server test <id>                     # test connectivity
+toolhome server capabilities <id>             # show capability snapshot
+toolhome server status <id>                   # runtime status + last error
+toolhome server logs <id>                     # recent log entries
+toolhome server endpoint <id>                 # per-server endpoint URL
+```
+
+Server JSON (create):
+
+```json
+{
+  "slug": "firecrawl",
+  "name": "Firecrawl",
+  "kind": "remote",
+  "transport": { "type": "streamable-http", "url": "https://mcp.firecrawl.dev/v2/mcp" },
+  "credentialId": "<uuid>",
+  "enabled": true,
+  "settings": { "urlClientId": false }
+}
+```
+
+Home-hosted stdio:
+
+```json
+{
+  "slug": "resend",
+  "name": "Resend",
+  "kind": "home",
+  "transport": {
+    "type": "stdio",
+    "command": "/data/market/node_modules/.bin/resend-mcp",
+    "args": []
+  },
+  "credentialId": "<uuid>",
+  "enabled": true
+}
+```
+
+## credential
+
+```bash
+toolhome credential list                     # list all credentials
+toolhome credential get <id>                 # get a credential
+toolhome credential add <file|->             # add from JSON
+toolhome credential update <id> <file|->     # update
+toolhome credential delete <id>              # delete
+toolhome credential test <id>                # validate + refresh
+toolhome credential revoke <id>              # revoke OAuth tokens
+toolhome credential authorize <name>         # start OAuth flow (by name or id)
+```
+
+Authorize options:
+
+```
+--server <slug>    specify the server (auto-resolved if omitted)
+--force            clear old client + re-authorize
+--no-open          don't open browser
+--no-wait          print URL and exit
+--timeout <sec>    wait time (default 600)
+```
+
+Credential JSON (create):
+
+```json
+{ "name": "firecrawl", "payload": { "type": "bearer", "token": "fc-xxx" } }
+{ "name": "apifox", "payload": { "type": "headers", "headers": { "Authorization": "Bearer xxx", "X-Apifox-Api-Version": "2025-09-01" } } }
+{ "name": "cloudflare", "payload": { "type": "oauth" } }
+{ "name": "resend", "payload": { "type": "env", "variables": { "RESEND_API_KEY": "re_xxx" } } }
+```
+
+## access-key
+
+```bash
+toolhome access-key create <name>             # returns secret once
+toolhome access-key list
+toolhome access-key revoke <id>
+```
+
+## control-key
+
+```bash
+toolhome control-key create <name>            # returns secret once
+toolhome control-key list
+toolhome control-key revoke <id>
+```
+
+## market
+
+```bash
+toolhome market list                          # browse catalog with install status
+toolhome market install <id>                  # install MCP or CLI; browser URL for missing secrets
+toolhome market install <id> --set KEY=value  # non-secret config (repeatable --set)
+toolhome market uninstall <id>                # remove MCP server or CLI and credential
+toolhome market updates                       # installed vs catalog pin (+ upstream latest)
+toolhome market update <id>                   # update to the catalog pin (keeps credential, restarts)
+```
+
+## config
+
+```bash
+toolhome config export <file>                 # redacted export
+toolhome config export <file> --include-secrets  # full backup (0600)
+toolhome config import <file>                 # restore (atomic transaction)
+toolhome config import-harness <file> [--preview] [--upsert]
+                                              # import a Claude Desktop / Cursor mcpServers JSON;
+                                              # secrets become encrypted credentials (never echoed)
+```
+
+Harness import accepts `{ "mcpServers": { name: { command, args, env } | { url, headers } } }`.
+Secret-looking env keys (password/token/secret/key/authorization) and `Authorization` headers
+are stored as encrypted credentials; everything else lands in the server transport.
+`--upsert` re-imports as an update: existing servers are diffed (unchanged → skip,
+changed → update transport/env/credential) instead of reported as conflicts.
+
+## endpoint
+
+```bash
+toolhome endpoint aggregate                   # aggregate /mcp URL
+toolhome endpoint server <id>                 # per-server /mcp/{slug} URL
+```
+
+## diagnostics
+
+```bash
+toolhome status                               # overview (servers, credentials, keys, endpoints)
+toolhome doctor                               # health check per server
+toolhome events                               # recent events
+toolhome events --limit 100                   # includes hosted cli.exec audit events
+```
+
+## api (raw)
+
+```bash
+toolhome api GET /api/v1/openapi.json
+toolhome api POST /api/v1/servers --body ./server.json
+```
+
+## cli (hosted CLI plane)
+
+Server-side CLI hosting (Form A): register a CLI once on the ToolHome host; client
+machines never install or log in to it. Records live in the `clis` table and execs are
+audited in the events stream. The web console has a parallel **CLIs** page
+(register/edit/delete, enable toggle, and a Run sheet that streams exec output).
+
+```bash
+toolhome cli list
+toolhome cli get <id>
+toolhome cli add ./cli.json
+toolhome cli update <id> ./cli-patch.json
+toolhome cli enable <id>
+toolhome cli disable <id>
+toolhome cli delete <id>
+toolhome cli status <slug>
+toolhome cli exec <slug> -- --version
+toolhome cli exec <slug> --timeout 60000 --max-output-bytes 65536 -- <args...>
+toolhome cli exec <slug> --stdin-file ./input.txt -- <args...>
+toolhome cli exec <slug> --stdin-file - -- <args...>
+```
+
+`--stdin <text>` and `--stdin-file <path|->` are mutually exclusive. Put platform arguments after `--`; timeout is in milliseconds and cannot exceed the record's limit. Human output streams stdout/stderr; `--output json` emits NDJSON frames and an outcome. A failed or timed-out remote execution exits locally with code 1. Ctrl-C cancels the stream.
+
+```bash
+# registry (Control API, admin key)
+toolhome api GET  /api/v1/clis                       # list registered CLIs
+toolhome api POST /api/v1/clis --body ./cli.json      # register (201); prefer Market for Azure bootstrap
+toolhome api GET  /api/v1/clis/<id>                  # fetch
+echo '{"enabled":false}' | toolhome api PATCH /api/v1/clis/<id> --body -
+toolhome api DELETE /api/v1/clis/<id>                # delete
+```
+
+Exec and status live on the data plane (`POST /cli/{slug}/exec`, `GET /cli/{slug}/status`):
+
+```bash
+# exec: argv array only — never a shell string; body must be JSON
+toolhome cli exec azure-cli --timeout 30000 -- account show -o table
+# → 200 NDJSON stream: {"type":"stdout","data":...} {"type":"stderr","data":...}
+#   {"type":"exit","code":0,"durationMs":4211,"result":"ok"}
+# timeout → {"type":"exit","code":null,"durationMs":...,"result":"timeout"}
+# truncated output → exit frame carries "truncated":true
+
+toolhome api GET /cli/azure-cli/status
+# → { "installed":true, "version":"azure-cli 2.x", "loggedIn":true, "lastCheckedAt":"..." }
+```
+
+Semantics:
+
+- **argv array only**: `spawn(command, argv)` with no shell; a shell string is rejected (400).
+- **Allow-list**: `deny` rules are evaluated first; a non-empty `allow` list must match at
+  least one rule (`*` matches one argv token, rules match as argv prefixes). Denied argv is
+  rejected with 403 before any process is spawned.
+- **Credential materialization**: MCP and hosted CLI entries share the encrypted credential
+  payload format. CLI bindings project `env:<name>`, `token`, `value`, `header:<name>`, or
+  `accessToken` into the process environment. OAuth uses its stored access token and returns
+  `credential_authorization_required` until authorization is complete.
+- **Env injection**: every exec gets `CI=true`, `NO_COLOR=1`, `PAGER=cat`, `TERM=dumb`
+  (unless the record sets `interactive: true`), plus the bound credential variables.
+- **Status probe**: the declared `probe.command` runs in the same context; its stdout is
+  parsed as `version=...` / `loggedIn=true|false` lines; `installed` = exit code 0.
+- **Isolation**: `executionMode: 'host'` spawns on the ToolHome host (trusted entries);
+  `'docker'` spawns a one-shot sibling container (`docker run --rm -i <image> <argv…>`).
+  `containerVolumes` are explicit Docker named volumes forwarded with `--volume`; bind paths,
+  duplicate targets, and host credential directories are rejected.
+  credential directories are never mounted implicitly. `authStrategy: "azure-service-principal"`
+  performs a fixed `az login --service-principal` bootstrap from bound environment variables,
+  while `authStrategy: "tailscale-auth-key"` starts an in-container userspace `tailscaled` and performs a fixed `tailscale --socket=... up --auth-key` bootstrap.
+  Catalog entries may use npm, Go, GitHub Release, uv, or Docker installer backends, but those
+  backends are hidden implementation details rather than separate Market products.
+- **Audit**: every exec appends a `cli.exec` event (slug, argv, exit code, duration) visible
+  via `toolhome events` / `GET /api/v1/events`.
+
+## global options
+
+```
+--url <url>           control API URL (or TOOLHOME_URL env)
+--key <key>           control key (or TOOLHOME_CONTROL_KEY env)
+--output <human|json> output format (default human)
+```

package/skills/toolhome/references/deployment.md

@@ -0,0 +1,113 @@
+# Deployment Guide
+
+## Docker (Recommended)
+
+```yaml
+# docker-compose.yml
+services:
+  toolhome:
+    image: ghcr.io/crayonlu/toolhome:latest
+    init: true
+    restart: unless-stopped
+    ports:
+      - '127.0.0.1:3344:3344'
+    volumes:
+      - ./data:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+    group_add:
+      - '${DOCKER_GROUP_ID:-999}'
+    env_file: .env
+```
+
+```bash
+# .env
+TOOLHOME_MASTER_KEY=<32+ char random>
+TOOLHOME_BOOTSTRAP_CONTROL_KEY=tch_ctl_<random suffix, different from master>
+TOOLHOME_PUBLIC_URL=https://tool.cyncyn.xyz
+TOOLHOME_ALLOWED_HOSTS=tool.cyncyn.xyz
+```
+
+```bash
+docker compose up -d
+```
+
+## CI/CD (GitHub Actions)
+
+The repo includes `.github/workflows/ci.yml` with three jobs:
+
+1. **test**: server check + test, web typecheck + test
+2. **docker**: build dists -> docker build -> push `ghcr.io/crayonlu/toolhome:latest`
+3. **deploy**: download the app image artifact, build the pinned GitHub CLI image, transfer both over SSH, load them with Docker, and run `docker compose up -d`
+
+### Required GitHub Secrets
+
+| Secret        | Value                           |
+| ------------- | ------------------------------- |
+| `DEPLOY_HOST` | Server IP or hostname           |
+| `DEPLOY_USER` | SSH username                    |
+| `DEPLOY_KEY`  | SSH private key (no passphrase) |
+
+### GHCR Package Visibility
+
+After first CI push, set the package to Public:
+`github.com/<user>?tab=packages -> toolhome -> Package settings -> Change visibility -> Public`
+
+### Deployment Flow
+
+```
+git push main -> test -> docker build + push GHCR -> SSH deploy -> done
+git tag v* -> test -> docker build + push :v* tag (no deploy)
+```
+
+The current image job also updates `:latest` on tag pushes. Tags alone do not publish npm packages or create GitHub Releases. For a release, verify both independently: `npm view toolhome version` and `gh release list`. Build/check/test both planes, include `skills/toolhome` in the npm archive, publish npm with the user's 2FA confirmation when requested, and create a GitHub Release for the matching version tag. Never overwrite an already published npm version.
+
+## Reverse Proxy
+
+Put an HTTPS reverse proxy (nginx/Caddy/openresty) in front. Key requirements:
+
+- **WebSocket/SSE support**: MCP uses Streamable HTTP with SSE responses. The proxy must not buffer SSE.
+- **No CDN proxy for the domain**: If behind Cloudflare (orange cloud), SSE POST responses get buffered for ~25s. Use DNS-only (grey cloud) for the ToolHome subdomain.
+- **Valid TLS certificate**: OAuth callbacks and URL-based client metadata require HTTPS.
+
+### nginx Example
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:3344;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_buffering off;
+    proxy_read_timeout 600s;
+}
+```
+
+## Data Persistence
+
+| Path                                                | Content                                                                            | Persist?     |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------ |
+| `/data/toolhome.sqlite`                             | SQLite database (servers, credentials, keys, events)                               | Yes (volume) |
+| `/data/market/`                                     | Market-installed npm/Go/GitHub Release artifacts                                   | Yes (volume) |
+| `/data/.uv/`                                        | uv tool and cache state                                                            | Yes (volume) |
+| Docker named volumes declared by Hosted CLI entries | Platform CLI state, such as Azure `/root/.azure` or Tailscale `/var/lib/tailscale` | Yes (volume) |
+| `/app/dist/`                                        | Server code (baked in image)                                                       | No (image)   |
+| `/app/web-dist/`                                    | Web console (baked in image)                                                       | No (image)   |
+
+## Local Development
+
+```bash
+npm install
+npm run dev          # server (tsx watch)
+npm run dev:web      # web console (Vite, proxies /api to :3344)
+```
+
+## Building from Source
+
+```bash
+npm run build        # builds server dist + web dist
+docker compose up -d --build   # build image locally
+```
+
+The Dockerfile copies prebuilt `dist/` and `web/dist/` from the build context (not built in-container, to avoid memory issues on low-RAM hosts).
+
+For Docker-backed MCP or Hosted CLI entries, keep the Docker socket mount and `group_add` configuration. The curated Tailscale CLI uses userspace networking inside the sibling container and persists its identity in the declared named volume, so it does not require a host TUN device, extra capabilities, or a special network mode. A basic `docker run --rm -i` container is sufficient for the curated read-only platform CLI entries.

package/skills/toolhome/references/market-guide.md

@@ -0,0 +1,128 @@
+# Market Guide
+
+## Overview
+
+The Market is a curated catalog of MCP servers and hosted platform CLIs. One command installs the target, creates the credential, and configures the runtime. A Market entry represents the capability itself; installer technologies such as npm, Go, GitHub Release, uv, and Docker remain implementation details.
+
+## Catalog Entries (35)
+
+### Remote (OAuth)
+
+linear, slack, stripe, figma, sentry, supabase, notion, cloudflare
+
+### Remote (API Key)
+
+github (PAT), context7, exa, tavily, firecrawl, openrouter, apifox
+
+### Remote (no auth)
+
+deepwiki
+
+### Home-stdio MCP servers
+
+resend, tailscale, playwright, postgres, sqlite, memory, sequential-thinking, mosaic
+
+### Uvx-backed MCP server
+
+fetch
+
+### Docker-backed MCP server
+
+markitdown
+
+### Hosted platform CLIs
+
+azure-cli (`az`), gh-cli (`gh`), tailscale-cli, lark-cli, firecrawl-cli (`firecrawl`), wrangler-cli (`wrangler`), vercel-cli, aliyun-cli (`aliyun`)
+
+### Existing host binary
+
+host-shell (`/bin/sh`), explicit opt-in for trusted shell execution. This is the ninth CLI entry; there are 26 MCP entries.
+
+### Deployment coverage
+
+| Installer / source                | CLI execution | Curated CLI examples                        |
+| --------------------------------- | ------------- | ------------------------------------------- |
+| npm                               | host          | Lark, Firecrawl, Wrangler, Vercel           |
+| GitHub Release archive            | host          | Aliyun (linux-amd64 only)                   |
+| Docker image or inline Dockerfile | docker        | Azure, GitHub, Tailscale                    |
+| Existing host binary              | host          | host-shell                                  |
+| Go module                         | host          | Backend supported; no curated CLI entry yet |
+| uv / Python                       | host          | Backend supported; no curated CLI entry yet |
+
+There is no Cargo, apt, Homebrew, arbitrary installer-script, or remote-SSH installer backend. To use other binaries, provision them on the ToolHome host and register them with `toolhome cli add`. The catalog is curated, not an exhaustive list of platform CLIs. All five artifact installers are shared by MCP and CLI; the two execution modes are `host` and `docker`. Docker deployment includes npm, Go, uv, curl, tar, unzip, and the Docker client. Sibling containers additionally require the host socket and its group permissions.
+
+Hosted CLI entries are parallel to MCP entries. The catalog describes the platform command, pinned artifact, credential requirements, and allowed argv; it does not expose npm, Go, uv, or Docker as products.
+
+npm-backed CLI entries (`lark-cli`, `firecrawl-cli`, `wrangler-cli`, `vercel-cli`) install into the persistent market volume and run in host mode. Credentials are injected as environment variables (`FIRECRAWL_API_KEY`, `CLOUDFLARE_API_TOKEN`, `VERCEL_TOKEN`); `lark-cli` ships no token env var — run `lark-cli auth login --no-wait --json` through exec, complete the device flow in a browser, then finish with `lark-cli auth login --device-code <code>`. Its npm package downloads the platform binary on first execution, so the first command needs a generous exec timeout. `aliyun-cli` installs a pinned GitHub Release tarball (linux-amd64) and authenticates through `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET`, and `ALIBABA_CLOUD_REGION_ID`; bare probe commands (its `aliyun version` probe) resolve next to the installed binary.
+
+`gh-cli` installs without any credential and authenticates afterwards through the GitHub device flow. CI preloads `toolhome/gh-cli:2.97.0` for the managed deployment. Fresh self-hosted instances build it from the pinned upstream release when the image is unavailable; this requires access to Alpine and GitHub and supports amd64/arm64. The managed CI image sets a deployment-specific `GH_HOST` relay; the catalog fallback uses GitHub directly. Match the login hostname to the installed image's configuration. Login state persists in the `toolhome-gh-cli-state` named volume:
+
+```bash
+toolhome cli exec gh-cli --stdin $'\n' -- auth login --hostname github.com --git-protocol https --web
+# copy the one-time code, open https://github.com/login/device, then wait for the exec to finish
+toolhome cli exec gh-cli -- auth status
+```
+
+`gh auth token` stays denied so stored tokens can never reach argv logs; a token alternative is still possible via `gh auth login --with-token` with the token fed through exec stdin.
+
+> ⚠️ The npm package name `mcp-server-fetch` is **squatted** by a canary (npx-confusion) package that runs code on install. The official Fetch server is Python — the catalog installs it via `uvx`, never via npm.
+
+## Installation
+
+```bash
+toolhome market list                                    # browse with install status
+toolhome market install resend                          # enter missing secret at browser URL
+toolhome market install context7                        # enter missing secret at browser URL
+toolhome market install deepwiki                        # no config needed
+toolhome market install fetch                           # uvx (Python), no config
+toolhome market uninstall resend
+```
+
+### How It Works
+
+**Remote entries**: Creates a credential (bearer/headers/oauth) + a remote server with the upstream URL. For OAuth entries, run `toolhome credential authorize <name>` after install.
+
+**Home-stdio entries**: The installer backend runs the pinned npm recipe, creates an env credential, and creates a home server with the stdio command pointing to the installed binary. The install is async with progress logging.
+
+**Uvx entries**: The installer backend runs `uv tool install <package>` (Python packages from PyPI), then creates a home server that executes the installed binary from the persistent `UV_TOOL_BIN_DIR`. It does not run `uvx <package>` again during every MCP refresh, so the pinned artifact is reused without a second dependency resolution. Some entries pin extra dependencies via `--with` (e.g. `mcp-server-fetch` pins `mcp<2` because upstream still imports the pre-2.0 `McpError` name).
+
+**Hosted CLI entries**: A CLI entry provisions a first-class CLI record and installs its pinned artifact through the entry's hidden npm, Go, GitHub Release, uvx, or Docker recipe. Execution remains argv-only and uses the same encrypted credential payloads as MCP. A declarative binding maps credential material to the platform CLI environment, for example `GH_TOKEN <- bearer token` or `AZURE_CLIENT_ID <- env:CLIENT_ID`. OAuth-backed CLI records use the stored access token and return `credential_authorization_required` until the credential is authorized. ToolHome never mounts a user's local `~/.azure`, `~/.config/gh`, `~/.aws`, or similar directory by default.
+
+Azure service-principal entries use `authStrategy: "azure-service-principal"`: the runner starts `/bin/sh` inside the pinned Azure image, executes a fixed non-interactive `az login --service-principal` from `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID`, then executes the allow-listed `az` argv. The named `/root/.azure` volume preserves CLI state across runs without importing a user's local Azure profile.
+
+Tailscale entries use `authStrategy: "tailscale-auth-key"` and an explicit named `/var/lib/tailscale` volume. Each invocation starts `tailscaled` in userspace-networking mode inside the pinned container, waits for its socket, performs the fixed `tailscale --socket=/var/run/tailscale/tailscaled.sock up --auth-key="$TS_AUTHKEY" --reset` bootstrap, then executes the allow-listed `tailscale` argv through that socket. This avoids requiring host TUN devices or kernel capabilities; the state volume preserves the node identity. The entry remains limited to the catalog's read-only `version`, `status`, and `netcheck` commands.
+
+### Hosted CLI Authentication
+
+MCP and CLI credentials share the encrypted `CredentialPayload` storage format and a common materialization layer:
+
+- `env` credentials pass variables through, or select them with `env:<name>` bindings.
+- `bearer` credentials bind with `token`.
+- `api-key` credentials bind with `value`.
+- `headers` credentials bind with `header:<Header-Name>`.
+- `oauth` credentials bind with `accessToken` after authorization.
+
+The MCP side still owns OAuth provider discovery, refresh, and callback handling. The CLI side only consumes the stored access token; it does not implement a second OAuth transport.
+
+### Install Location
+
+Home-stdio packages, Go binaries, and GitHub Release binaries install to `TOOLHOME_MARKET_DIR` (default `<dataDir>/market`), which is a persistent Docker volume. Packages survive container restarts. Uvx tools and caches install to `<dataDir>/.uv`, also persistent.
+
+### Installation Progress
+
+- CLI: shows `installing: npm install <package>...` with live progress
+- Web console: InstallSheet shows spinner + current step + live npm output log
+- API: `POST /market/:id/install` returns a `jobId`; `GET /market/install/:jobId` polls status
+
+## Adding Custom Servers (outside Market)
+
+For servers not in the catalog, use the standard CLI:
+
+```bash
+echo '{"name":"custom","payload":{"type":"bearer","token":"xxx"}}' | toolhome credential add -
+echo '{"slug":"custom","name":"Custom","kind":"remote","transport":{"type":"streamable-http","url":"https://example.com/mcp"},"credentialId":"<id>","enabled":true}' | toolhome server add -
+```
+
+## Market Catalog Source
+
+The catalog is defined in `src/market/catalog.ts` (bundled). To add entries, edit this file and redeploy. A remote catalog URL (`TOOLHOME_MARKET_URL`) is planned for future updates without redeployment.

package/skills/toolhome/references/oauth-guide.md

@@ -0,0 +1,96 @@
+# OAuth Guide
+
+## Two Registration Methods
+
+ToolHome supports two OAuth client registration methods for upstream MCP servers:
+
+1. **URL-based Client Metadata** (RFC 9728, default): ToolHome publishes a client metadata document at `https://<public-url>/oauth/upstream/client/<credential-id>`. The upstream authorization server fetches this document to register the client.
+
+2. **Dynamic Client Registration (DCR)**: ToolHome POSTs client metadata to the upstream's `registration_endpoint`. The server returns a client ID.
+
+The method is controlled by `settings.urlClientId` per server:
+
+- `true` (default) = URL-based
+- `false` = DCR
+- `undefined` = inherit global `TOOLHOME_OAUTH_URL_CLIENT_ID` (default `true`)
+
+## Per-Server Configuration
+
+Set via CLI:
+
+```bash
+echo '{"settings":{"urlClientId":false}}' | toolhome server update <id> -
+```
+
+Or via the web console: Server edit form -> "OAuth client registration" dropdown.
+
+## Provider Compatibility
+
+| Provider       | Recommended Method         | Notes                                                                                                                  |
+| -------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **Cloudflare** | DCR (`urlClientId: false`) | URL-based fails: 503 fetching from proxied origin                                                                      |
+| **Notion**     | DCR (`urlClientId: false`) | URL-based fails: "Invalid client"                                                                                      |
+| **Linear**     | DCR (`urlClientId: false`) | URL-based fails: "Invalid client"                                                                                      |
+| **GitHub**     | PAT (not OAuth)            | OAuth server doesn't support DCR; metadata discovery requires auth. Use a Personal Access Token as a bearer credential |
+| **Slack**      | URL-based (default)        | No DCR endpoint; URL-based should work                                                                                 |
+| **Stripe**     | URL-based (default)        | No DCR endpoint                                                                                                        |
+| **Figma**      | URL-based (default)        | No DCR endpoint                                                                                                        |
+| **Sentry**     | URL-based (default)        | No DCR endpoint                                                                                                        |
+| **Supabase**   | URL-based (default)        | No DCR endpoint                                                                                                        |
+| **Vercel**     | Not compatible             | Only approves localhost callbacks; incompatible with remote gateway                                                    |
+
+## Authorization Flow
+
+```bash
+toolhome credential authorize <name>
+```
+
+1. Resolves credential by name (or ID)
+2. Calls `POST /api/v1/credentials/:id/authorize`
+3. Opens the authorization URL in the browser
+4. Waits, polling credential status every 2s
+5. Reports success, failure, or timeout (default 600s)
+
+### Force Re-authorization
+
+```bash
+toolhome credential authorize <name> --force
+```
+
+Clears the stored client information and re-registers. Use when switching registration methods or changing accounts.
+
+## Troubleshooting OAuth
+
+### "Incompatible auth server: does not support dynamic client registration"
+
+The upstream doesn't have a `registration_endpoint`. Switch to URL-based:
+
+```bash
+echo '{"settings":{"urlClientId":true}}' | toolhome server update <id> -
+```
+
+### "Invalid client. The clientId provided does not match."
+
+URL-based metadata was rejected by the upstream. Switch to DCR:
+
+```bash
+echo '{"settings":{"urlClientId":false}}' | toolhome server update <id> -
+```
+
+### "invalid_redirect_uri"
+
+The upstream only approves specific redirect URIs (e.g., Vercel only allows `http://localhost:<port>/callback`). This is incompatible with a remote gateway. Use a PAT or keep the MCP in the harness locally.
+
+### OAuth metadata fetch fails (503)
+
+If the ToolHome domain is behind a CDN/proxy (e.g., Cloudflare), the upstream's auth server may fail to fetch the client metadata document. Fix: use DNS-only (grey cloud) for the domain, or switch to DCR.
+
+### Credential shows "Expired"
+
+OAuth access tokens expire (typically 1 hour). ToolHome refreshes them lazily on connection. The web console auto-refreshes expired OAuth credentials on page load. Manual refresh:
+
+```bash
+toolhome credential test <id>
+# or
+toolhome server refresh <server-id>
+```