Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs: add the agent-gateway and autopilot READMEs, register /grok and its doc, and record two unregistered guards

nirholas34d2f93c1051
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f24d65d61..bba88023a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,15 +4,20 @@
Public history for [three.ws](https://three.ws), newest first. New pages come from `added` dates in data/pages.json; everything else is curated in data/changelog.json. Also available as [JSON](https://three.ws/changelog.json) and [RSS](https://three.ws/changelog.xml), live at [three.ws/changelog](https://three.ws/changelog).
+## 2026-10-09
+
+- **The desktop companion, CLI and MCP server now work with just the bridge token**: The companion bridge token is the one credential the desktop app, the companion command line and its MCP server are given, but the feed, marking a message as spoken, replying, reading contacts and checking sources all refused it, so pasting the token into the desktop app said it was wrong and an agent asking what you had heard got turned away. Those calls now accept the bridge token and only ever show the messages and contacts of the person it belongs to. It still cannot connect sources, edit contacts, change settings or rotate itself; those stay behind your signed-in account, and they now say so plainly instead of answering as if the token were wrong. (`/companion`) `[fix]`
+
## 2026-10-08
- **Chart Companion** (`/chart-companion`): Paste any DEXTools pair and a 3D agent watches the live chart with you, reacting to every real swap: cheering whale buys, flinching at dumps, calling streaks and new highs, each reaction linked to its transaction. Turn on its voice, bring your own three.ws agent, embed it with one iframe, or add it to OBS as a transparent stream overlay.
-- **DEXTools integration guide** (`/docs/dextools`): How three.ws works with DEXTools: DEXTools charts on every coin page, any pair rendered as a live 3D scene, the embeddable Social Boost card, and how to paste a DEXTools link to get an embed snippet.
- **Docs · Chart Companion** (`/docs/chart-companion`): How to watch a DEXTools chart with a 3D agent that reacts to every real swap: the URL parameters, streaming it as a transparent OBS overlay, embedding it with one iframe, bringing your own agent, and exactly how whale, streak and new-high reactions are decided.
- **Docs · DEXTools integration** (`/docs/dextools`): How three.ws and DEXTools connect: the /dextools hub, the embed builder that turns any DEXTools pair link into a 3D scene or Social Boost card snippet, the framable Boost on DEXTools card, and the counted redirect and public totals behind every visit three.ws sends to a DEXTools pair page.
+- **Docs · three.ws for Grok** (`/docs/grok`): Connect Grok Bot, Grok connectors or the xAI API to the free three.ws remote MCP server at /api/mcp-grok: text and image to 3D, rigged avatars, and a named 3D persona that lip-syncs its replies, with no account, payment or API key.
- **Launch a Paired Coin** (`/launch/paired`): Have your 3D AI agent launch a coin on Robinhood Chain paired with up to five assets at once (tokenized stocks, WETH, stablecoins, chain coins) from its own wallet: a live cost quote with each pool's opening value, an atomic opening buy, spend-policy checks, and the same launch as an API call and MCP tools.
- **Launch on Robinhood Chain** (`/launch/robinhood`): Launch a coin on Robinhood Chain through Pons, signed by your 3D AI agent's own wallet: a live cost quote, an atomic opening buy, and an API your bots can call.
- **Paired Coins** (`/markets/robinhood/paired`): Coins on Robinhood Chain that trade against up to five assets at once: tokenized stocks, WETH, stablecoins and chain coins, each in its own bonding curve with liquidity locked forever. Live pools priced in dollars, charts per pool, every trade, a buy and sell ticket, and the AI agents that launched them.
+- **three.ws for Grok** (`/grok`): One sentence gives Grok Bot a 3D studio. Text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear. Works in Grok Bot, Grok connectors and the xAI API. Free, no account, no key.
- **three.ws x DEXTools** (`/dextools`): Every way three.ws works with DEXTools: DEXTools charts in every coin chart, any DEXTools pair rendered as a live 3D scene, a Social Boost card any project can embed, and a public count of the visits three.ws sends to DEXTools pair pages. Paste a DEXTools link to get the embed snippet.
- **3D Studio results now hand every agent plain links to the model**: Every model the free 3D Studio MCP server hands back, whether freshly generated, picked from the asset catalog or saved as a persona, now comes with four plain links, both in the result data and in its first lines of text: a viewer page, the GLB file, a rendered PNG picture and a paste-ready embed snippet. Agents that cannot show a 3D widget, like Grok Bot and other browser agents, can now open, download, share and embed the model directly. A model that is still rendering comes with a viewer link that waits for the job and opens the model the moment it is ready. (`/docs/mcp-studio`) `[feature]`
- **Agent earnings are updating again**: pump.fun moved the service that reports creator fees, so the Earned figures on agent pages, agent profiles, coin pages and /analytics had stopped refreshing since the end of September. Earnings now read from pump.fun's current fees service, with a second source behind it if that one stumbles, and every agent coin is back on its 30-minute refresh. (`/analytics`) `[fix]`
diff --git a/STRUCTURE.md b/STRUCTURE.md
index db58119a4..b03760de0 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -351,11 +351,12 @@ surface-map row already covers:
| [workers/model-video2scene/](workers/model-video2scene) | Streaming video to 3D point-cloud reconstruction on Cloud Run GPU (LingBot-Map). Built and weights staged, not deployed as its own service yet, so `/capture` runs its designed unconfigured state until `GCP_VIDEO2SCENE_URL` is set |
| [workers/texture/](workers/texture) | Text-guided texturing + magic-brush region retexture GPU server |
| [workers/pump-fun-mcp/](workers/pump-fun-mcp) | Cloudflare Workers mirror of the canonical pump.fun MCP server |
-| [workers/agent-gateway/](workers/agent-gateway) | Chat gateway worker: drains `gateway_inbox` (filled by the webhook receivers in [api/gateway/](api/gateway)) through `handleEvent` in [api/_lib/gateway/core.js](api/_lib/gateway/core.js) and delivers replies, approval previews and notifications back to the chat. Not deployed |
+| [workers/agent-gateway/](workers/agent-gateway) | Chat gateway worker: drains `gateway_inbox` (filled by the webhook receivers in [api/gateway/](api/gateway)) through `handleEvent` in [api/_lib/gateway/core.js](api/_lib/gateway/core.js) and delivers replies, approval previews and notifications back to the chat. Leased per-chat claims, platform-aware retries and dead letters, a `/healthz` endpoint, and operator commands for the bots and the inbox. Built and tested, not deployed: deliveries wait in the inbox until it runs. Docs: [workers/agent-gateway/README.md](workers/agent-gateway/README.md). Tests: [workers/agent-gateway/tests/](workers/agent-gateway/tests) |
| [workers/signal-bridge/](workers/signal-bridge) | Signal leg of the chat gateway: the signal-cli REST bridge with its registration snapshotted to a Cloud Storage bucket so it survives redeploys. Single instance by design. Builds and runs locally, not deployed |
| [services/agent-screen-caster/](services/agent-screen-caster) | Self-hosted Playwright caster: an agent owner runs it on their own host with their agent id + key, and it streams the browser it drives into the agent-screen feed. No managed instance exists (the platform's own casting runs in `workers/agent-screen-pool` and `workers/agent-screen-worker`). Tests: [tests/agent-screen-caster.test.js](tests/agent-screen-caster.test.js) |
| [services/fleet-console/](services/fleet-console) | Health console for an open-source fleet: enumerates a GitHub owner's repositories, probes every deployment URL and npm package they advertise, and scores what each one actually delivers. Ships an HTTP dashboard, a CLI (`scan --attention` exits 1 when anything is broken, so cron can gate on it) and an MCP server over the same snapshot. Not deployed and not meant to be: it runs from a terminal, a cron job, or beside an agent. Tests: [tests/fleet-console.test.js](tests/fleet-console.test.js), [tests/fleet-console-server.test.js](tests/fleet-console-server.test.js) |
| [services/pump-graduations/](services/pump-graduations) | Standalone watcher for pump.fun bonding-curve graduations |
+| [services/autopilot/](services/autopilot) | Unattended production repair loop for a dedicated GCP VM: every two hours it runs the deep GCP triage, wakes a headless Claude Code session only for findings it may fix, then gates the commits on `npm test`, pushes, deploys, verifies and rolls traffic back on a failed verification, and reports to the owner over Telegram. Not provisioned: the VM, its report bucket, its push secret, the `provision.sh` its bootstrap names and its two systemd units do not exist yet. Docs: [services/autopilot/README.md](services/autopilot/README.md) |
| [services/home-relay/](services/home-relay) | Terminates the outbound WebSocket a LAN-only Home Assistant dials, and multiplexes allowlisted platform sessions onto it. Holds no database and no credential at rest: a house proves ownership with an HMAC install token, and the Home Assistant authentication happens inside the house and never crosses this process. Not a proxy, on purpose: it carries a fixed list of Home Assistant message types and refuses everything else, including every service domain that would administer the machine rather than a device. Deployed unthrottled with min-instances 1 because it holds sockets between requests. Docs: [docs/home-relay.md](docs/home-relay.md), [docs/home-relay-threat-model.md](docs/home-relay-threat-model.md). Tests: [tests/home-relay-protocol.test.js](tests/home-relay-protocol.test.js), [tests/home-relay-transport.test.js](tests/home-relay-transport.test.js) |
| [home-assistant-integration/](home-assistant-integration) | The Python that runs inside a user's house: a Home Assistant custom integration, distributed through HACS as its own public repository, that dials out to `services/home-relay`. A custom integration rather than a Home Assistant add-on because add-ons only work on OS and Supervised installs while an integration works on all four, and because HACS distributes integrations rather than add-ons. Mints its own system refresh token locally, so no Home Assistant credential ever reaches three.ws, and enforces the relay's allowlist a second time from a generated `allowlist.json` shipped byte-identical from `services/home-relay`. Publishing the public repository is owner-gated. |
diff --git a/data/guards.json b/data/guards.json
index 73301b650..15b48367d 100644
--- a/data/guards.json
+++ b/data/guards.json
@@ -1,5 +1,5 @@
{
- "updated": "2026-09-20",
+ "updated": "2026-10-09",
"summary": "Every mechanical guard that protects this repository, and the stage each one runs in. This file is the single source of truth: scripts/audit-guards.mjs proves every entry is real and every stage claim is true, docs/guards.md explains them, and /guards renders them.",
"stages": [
{
@@ -438,6 +438,31 @@
"expect": "no curated listing copy"
}
},
+ {
+ "id": "audit-mcp-surfaces",
+ "script": "scripts/build-mcp-surfaces.mjs",
+ "npm": "audit:mcp-surfaces",
+ "title": "MCP resource and prompt listings",
+ "protects": "Every hosted MCP server's registry manifest (server*.json) and the public directory at public/.well-known/mcp.json list exactly the resources, resource templates and guided prompts that server really serves.",
+ "why": "Registries and MCP clients decide what a server offers from these listings before they ever connect. The lists are generated from api/_mcp/resources.js and api/_mcp/prompts.js, so a prompt or resource added, renamed or removed in code leaves the published manifests advertising things that do not exist, or hiding things that do, until someone remembers to regenerate. This check fails when any committed listing no longer matches what the code serves.",
+ "stages": [
+ "gate"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "The public MCP directory advertising no guided prompts for the main server while the code still serves them.",
+ "violation": {
+ "json": [
+ {
+ "file": "public/.well-known/mcp.json",
+ "pointer": "servers.0.prompts",
+ "set": []
+ }
+ ]
+ },
+ "expect": "MCP resource/prompt listings are stale"
+ }
+ },
{
"id": "audit-mcp-manifests",
"script": "scripts/audit-mcp-manifests.mjs",
@@ -1607,6 +1632,22 @@
"expect": "is declared but"
}
},
+ {
+ "id": "check-xai-models",
+ "script": "scripts/check-xai-models.mjs",
+ "npm": "check:xai-models",
+ "title": "Grok model catalog matches xAI",
+ "protects": "Every Grok model id in GROK_MODELS (api/_lib/chat-models.js) is one xAI still serves, every chat model xAI serves is catalogued, and each catalogued price, context window, image input, tool calling and reasoning-effort set matches xAI's own figures.",
+ "why": "xAI ships new model ids often and retires old ones in batches. A retired id in the catalog turns the Grok rung of every LLM failover chain into a guaranteed error, a new id nobody catalogued is a better or cheaper model no one on the platform can pick, and llm-pricing.js meters Grok spend from the catalog's prices, so a stale price is a wrong spend ledger. It reads the xAI models API when GROK_API_KEY or XAI_API_KEY is set and xAI's public model docs otherwise, and exits 2 rather than 1 when neither source can be read, so an outage is never reported as drift.",
+ "stages": [
+ "manual"
+ ],
+ "needs": "network",
+ "proof": {
+ "kind": "live",
+ "reason": "The thing under test is what xAI serves today, read from its models API or its public model docs. There is no offline input whose mutation proves anything about a third party's live catalog, and the comparison never sends a prompt or spends a token."
+ }
+ },
{
"id": "i18n-home",
"script": "scripts/i18n-home-keys.mjs",
diff --git a/data/pages.json b/data/pages.json
index 7e9142753..5493611c9 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -519,6 +519,14 @@
"changefreq": "monthly",
"added": "2026-07-25"
},
+ {
+ "path": "/grok",
+ "title": "three.ws for Grok",
+ "description": "One sentence gives Grok Bot a 3D studio. Text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear. Works in Grok Bot, Grok connectors and the xAI API. Free, no account, no key.",
+ "priority": 0.8,
+ "changefreq": "monthly",
+ "added": "2026-10-08"
+ },
{
"path": "/nvidia",
"title": "three.ws on NVIDIA",
@@ -861,14 +869,6 @@
"changefreq": "monthly",
"added": "2026-08-28"
},
- {
- "path": "/docs/dextools",
- "title": "DEXTools integration guide",
- "description": "How three.ws works with DEXTools: DEXTools charts on every coin page, any pair rendered as a live 3D scene, the embeddable Social Boost card, and how to paste a DEXTools link to get an embed snippet.",
- "priority": 0.5,
- "changefreq": "monthly",
- "added": "2026-10-08"
- },
{
"path": "/docs/portal",
"title": "How Portal builds a 3D world from a URL",
@@ -4070,6 +4070,12 @@
"description": "The free, no-auth MCP server behind the ChatGPT 3D Studio app: text and image to 3D, rigged avatars, conversational refinement, and living agent personas.",
"added": "2026-07-14"
},
+ {
+ "path": "/docs/grok",
+ "title": "Docs · three.ws for Grok",
+ "description": "Connect Grok Bot, Grok connectors or the xAI API to the free three.ws remote MCP server at /api/mcp-grok: text and image to 3D, rigged avatars, and a named 3D persona that lip-syncs its replies, with no account, payment or API key.",
+ "added": "2026-10-08"
+ },
{
"path": "/docs/chatgpt-ar",
"title": "Docs · AR in ChatGPT",
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 35bcc6c05..b6e522bde 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -6776,9 +6776,9 @@ Scores are written exclusively by the authoritative game server (through the wor
}
```
-An event nobody has played yet is an empty board (`top: []`, `players: 0`) with a `200`, not an error: render the "no runs yet" state rather than a failure. `404 no_event` means no event is configured at all, which is what the live deployment answers between events.
+An event nobody has played yet is an empty board (`top: []`, `players: 0`) with a `200`, not an error: render the "no runs yet" state rather than a failure. The board keeps answering `200` after an event ends (with `live: false`), for as long as `public/event.json` still names that event. `404 no_event` means no event is configured at all, which is what the live deployment answers once the finished event is retired from `public/event.json` and before the next one is scheduled.
-<!-- runnable: 404 answers no_event whenever no event window is open in public/event.json -->
+<!-- runnable: no the status follows the event calendar in public/event.json (200 while an event is configured, 404 no_event once it is retired), so no single status is a stable contract -->
```bash
curl -s 'https://three.ws/api/play/event-leaderboard?limit=10'
```
diff --git a/docs/guards.md b/docs/guards.md
index 128ab7c0d..a2b25054f 100644
--- a/docs/guards.md
+++ b/docs/guards.md
@@ -160,6 +160,7 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| MCP safety annotations | `npm run audit:mcp-safety` | Declared `readOnlyHint` and `destructiveHint` match what handlers do. |
| MCP tool catalog freshness | `npm run audit:mcp-catalog` | `public/mcp-catalog.json` matches what the MCP servers actually expose. |
| MCP directory listing source | `npm run audit:mcp-listing` | The one file every third-party MCP directory listing is written from still matches the manifests, and no new server lands without listing copy. |
+| MCP resource and prompt listings | `npm run audit:mcp-surfaces` | Every hosted MCP server's registry manifest and `public/.well-known/mcp.json` list exactly the resources, templates and guided prompts the code serves. |
| 3D Studio OpenAPI sync | `npm run check:studio-openapi` | The Actions file in the OpenAI submission kit is byte-identical to the OpenAPI schema the site serves. |
| Live event window | `npm run check:event` | `public/event.json` describes an event that will actually happen, on every surface that reads it. |
| Cron schedule drift | `npm run check:cron-syntax`, `npm run check:cron-drift` | Valid expressions, and agreement with the running Cloud Scheduler jobs. |
@@ -193,6 +194,7 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| Fleet wallet flows | `npm run audit:wallet-flows` | Where the platform's SOL is, where it went, and whether any is leaking. |
| Relayer balances | `npm run check:relayer-balances` | Every configured Solana signer is above its documented minimum. |
| LLM spend metering | `npm run audit:llm-metering` | Every LLM lane that spends money reports a real cost, never exactly $0 and never an unknown. |
+| Grok model catalog | `npm run check:xai-models` | Every Grok model id the platform routes to is one xAI still serves, no new xAI chat model goes uncatalogued, and each catalogued price, context window and capability matches xAI's own figures. Reads the xAI models API with a key, xAI's public model docs without one. |
| Cron liveness | `npm run audit:cron-liveness` | Each cron in `vercel.json` resolves to a handler that exists, imports, answers a live request, and refuses an unauthenticated one. |
| Custodial key health | `npm run audit:custodial-keys` | Every stored custodial Solana secret still decrypts under the current `WALLET_ENCRYPTION_KEY`. |
| Home credential health | `npm run audit:home-credentials` | Every stored Home Assistant token still decrypts under the current `WALLET_ENCRYPTION_KEY`, so no connected house is sealed. |
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index 5f436094b..8c77277e4 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,30 +1,30 @@
{
- "generated_at": "2026-10-09T02:41:54.975Z",
+ "generated_at": "2026-10-09T02:58:06.112Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 3835,
+ "total": 3837,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
{
- "date": "2026-10-08",
- "type": "launch",
- "title": "Chart Companion",
- "summary": "Paste any DEXTools pair and a 3D agent watches the live chart with you, reacting to every real swap: cheering whale buys, flinching at dumps, calling streaks and new highs, each reaction linked to its transaction. Turn on its voice, bring your own three.ws agent, embed it with one iframe, or add it to OBS as a transparent stream overlay.",
- "link": "/chart-companion",
+ "date": "2026-10-09",
+ "type": "update",
+ "title": "The desktop companion, CLI and MCP server now work with just the bridge token",
+ "summary": "The companion bridge token is the one credential the desktop app, the companion command line and its MCP server are given, but the feed, marking a message as spoken, replying, reading contacts and checking sources all refused it, so pasting the token into the desktop app said it was wrong and an agent asking what you had heard got turned away. Those calls now accept the bridge token and only ever show the messages and contacts of the person it belongs to. It still cannot connect sources, edit contacts, change settings or rotate itself; those stay behind your signed-in account, and they now say so plainly instead of answering as if the token were wrong.",
+ "link": "/companion",
"tags": [
- "launch"
+ "fix"
]
},
{
"date": "2026-10-08",
"type": "launch",
- "title": "DEXTools integration guide",
- "summary": "How three.ws works with DEXTools: DEXTools charts on every coin page, any pair rendered as a live 3D scene, the embeddable Social Boost card, and how to paste a DEXTools link to get an embed snippet.",
- "link": "/docs/dextools",
+ "title": "Chart Companion",
+ "summary": "Paste any DEXTools pair and a 3D agent watches the live chart with you, reacting to every real swap: cheering whale buys, flinching at dumps, calling streaks and new highs, each reaction linked to its transaction. Turn on its voice, bring your own three.ws agent, embed it with one iframe, or add it to OBS as a transparent stream overlay.",
+ "link": "/chart-companion",
"tags": [
"launch"
]
@@ -49,6 +49,16 @@
"launch"
]
},
+ {
+ "date": "2026-10-08",
+ "type": "launch",
+ "title": "Docs · three.ws for Grok",
+ "summary": "Connect Grok Bot, Grok connectors or the xAI API to the free three.ws remote MCP server at /api/mcp-grok: text and image to 3D, rigged avatars, and a named 3D persona that lip-syncs its replies, with no account, payment or API key.",
+ "link": "/docs/grok",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-10-08",
"type": "launch",
@@ -79,6 +89,16 @@
"launch"
]
},
+ {
+ "date": "2026-10-08",
+ "type": "launch",
+ "title": "three.ws for Grok",
+ "summary": "One sentence gives Grok Bot a 3D studio. Text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear. Works in Grok Bot, Grok connectors and the xAI API. Free, no account, no key.",
+ "link": "/grok",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-10-08",
"type": "launch",
@@ -1539,28 +1559,6 @@
"tags": [
"launch"
]
- },
- {
- "date": "2026-09-16",
- "type": "update",
- "title": "A cleaner launchpad for your 3D agent's coin, with rewards you claim right here",
- "summary": "three.ws/launch is rebuilt around one flow: pick one of your 3D agents, name the coin, and launch it on pump.fun from your wallet or from the agent's own wallet. The coin's metadata links your agent's page and 3D body, a live preview and cost panel show exactly what you will pay (including a 1% three.ws fee on the dev buy), and a new My coins tab shows unclaimed creator rewards and claims them in one click, no pump.fun app needed. Launches now fit in a single transaction thanks to pump.fun's lookup table, and larger ones, like USDC-paired coins with a dev buy, use Solana transaction v1 automatically when your wallet supports it. This also fixes launches that were failing because an on-chain buyback program stopped accepting new agents.",
- "link": "/launch",
- "tags": [
- "feature",
- "improvement",
- "fix"
- ]
- },
- {
- "date": "2026-09-16",
- "type": "update",
- "title": "A flat 1% fee on trades made through three.ws",
- "summary": "Trades that three.ws builds or runs for you now carry a 1% fee, paid in the same transaction as the trade: buys and sells in the coin trade window, trades from your agent's wallet, and trades your agents make through strategies, mirror trading, orders, market making and sniping. The fee is shown before you confirm, both in the trade window and in the agent wallet's trade tab. Trades you make on other apps are not affected, and three.ws's own agents are never charged.",
- "link": "/legal/tos",
- "tags": [
- "improvement"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index f9d59ef9a..ea9af5795 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-09T02:41:54.946Z",
+ "generated_at": "2026-10-09T02:58:06.081Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -7,21 +7,21 @@
},
"entries": [
{
- "date": "2026-10-08",
- "type": "launch",
- "title": "Chart Companion",
- "summary": "Paste any DEXTools pair and a 3D agent watches the live chart with you, reacting to every real swap: cheering whale buys, flinching at dumps, calling streaks and new highs, each reaction linked to its transaction. Turn on its voice, bring your own three.ws agent, embed it with one iframe, or add it to OBS as a transparent stream overlay.",
- "link": "/chart-companion",
+ "date": "2026-10-09",
+ "type": "update",
+ "title": "The desktop companion, CLI and MCP server now work with just the bridge token",
+ "summary": "The companion bridge token is the one credential the desktop app, the companion command line and its MCP server are given, but the feed, marking a message as spoken, replying, reading contacts and checking sources all refused it, so pasting the token into the desktop app said it was wrong and an agent asking what you had heard got turned away. Those calls now accept the bridge token and only ever show the messages and contacts of the person it belongs to. It still cannot connect sources, edit contacts, change settings or rotate itself; those stay behind your signed-in account, and they now say so plainly instead of answering as if the token were wrong.",
+ "link": "/companion",
"tags": [
- "launch"
+ "fix"
]
},
{
"date": "2026-10-08",
"type": "launch",
- "title": "DEXTools integration guide",
- "summary": "How three.ws works with DEXTools: DEXTools charts on every coin page, any pair rendered as a live 3D scene, the embeddable Social Boost card, and how to paste a DEXTools link to get an embed snippet.",
- "link": "/docs/dextools",
+ "title": "Chart Companion",
+ "summary": "Paste any DEXTools pair and a 3D agent watches the live chart with you, reacting to every real swap: cheering whale buys, flinching at dumps, calling streaks and new highs, each reaction linked to its transaction. Turn on its voice, bring your own three.ws agent, embed it with one iframe, or add it to OBS as a transparent stream overlay.",
+ "link": "/chart-companion",
"tags": [
"launch"
]
@@ -46,6 +46,16 @@
"launch"
]
},
+ {
+ "date": "2026-10-08",
+ "type": "launch",
+ "title": "Docs · three.ws for Grok",
+ "summary": "Connect Grok Bot, Grok connectors or the xAI API to the free three.ws remote MCP server at /api/mcp-grok: text and image to 3D, rigged avatars, and a named 3D persona that lip-syncs its replies, with no account, payment or API key.",
+ "link": "/docs/grok",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-10-08",
"type": "launch",
@@ -76,6 +86,16 @@
"launch"
]
},
+ {
+ "date": "2026-10-08",
+ "type": "launch",
+ "title": "three.ws for Grok",
+ "summary": "One sentence gives Grok Bot a 3D studio. Text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear. Works in Grok Bot, Grok connectors and the xAI API. Free, no account, no key.",
+ "link": "/grok",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-10-08",
"type": "launch",
diff --git a/public/changelog.xml b/public/changelog.xml
index be676b3ae..670572040 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -6,6 +6,14 @@
<atom:link href="https://three.ws/changelog.xml" rel="self" type="application/rss+xml"/>
<description>What's new on three.ws: features, improvements, and releases, newest first.</description>
<language>en</language>
+ <item>
+ <title>The desktop companion, CLI and MCP server now work with just the bridge token</title>
+ <link>https://three.ws/companion</link>
+ <guid isPermaLink="false">2026-10-09:The desktop companion, CLI and MCP server now work with just the bridge token</guid>
+ <pubDate>Fri, 09 Oct 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>The companion bridge token is the one credential the desktop app, the companion command line and its MCP server are given, but the feed, marking a message as spoken, replying, reading contacts and checking sources all refused it, so pasting the token into the desktop app said it was wrong and an agent asking what you had heard got turned away. Those calls now accept the bridge token and only ever show the messages and contacts of the person it belongs to. It still cannot connect sources, edit contacts, change settings or rotate itself; those stay behind your signed-in account, and they now say so plainly instead of answering as if the token were wrong.</description>
+ </item>
<item>
<title>Chart Companion</title>
<link>https://three.ws/chart-companion</link>
@@ -14,14 +22,6 @@
<category>launch</category>
<description>Paste any DEXTools pair and a 3D agent watches the live chart with you, reacting to every real swap: cheering whale buys, flinching at dumps, calling streaks and new highs, each reaction linked to its transaction. Turn on its voice, bring your own three.ws agent, embed it with one iframe, or add it to OBS as a transparent stream overlay.</description>
</item>
- <item>
- <title>DEXTools integration guide</title>
- <link>https://three.ws/docs/dextools</link>
- <guid isPermaLink="false">2026-10-08:DEXTools integration guide</guid>
- <pubDate>Thu, 08 Oct 2026 12:00:00 GMT</pubDate>
- <category>launch</category>
- <description>How three.ws works with DEXTools: DEXTools charts on every coin page, any pair rendered as a live 3D scene, the embeddable Social Boost card, and how to paste a DEXTools link to get an embed snippet.</description>
- </item>
<item>
<title>Docs · Chart Companion</title>
<link>https://three.ws/docs/chart-companion</link>
@@ -38,6 +38,14 @@
<category>launch</category>
<description>How three.ws and DEXTools connect: the /dextools hub, the embed builder that turns any DEXTools pair link into a 3D scene or Social Boost card snippet, the framable Boost on DEXTools card, and the counted redirect and public totals behind every visit three.ws sends to a DEXTools pair page.</description>
</item>
+ <item>
+ <title>Docs · three.ws for Grok</title>
+ <link>https://three.ws/docs/grok</link>
+ <guid isPermaLink="false">2026-10-08:Docs · three.ws for Grok</guid>
+ <pubDate>Thu, 08 Oct 2026 12:00:00 GMT</pubDate>
+ <category>launch</category>
+ <description>Connect Grok Bot, Grok connectors or the xAI API to the free three.ws remote MCP server at /api/mcp-grok: text and image to 3D, rigged avatars, and a named 3D persona that lip-syncs its replies, with no account, payment or API key.</description>
+ </item>
<item>
<title>Launch a Paired Coin</title>
<link>https://three.ws/launch/paired</link>
@@ -62,6 +70,14 @@
<category>launch</category>
<description>Coins on Robinhood Chain that trade against up to five assets at once: tokenized stocks, WETH, stablecoins and chain coins, each in its own bonding curve with liquidity locked forever. Live pools priced in dollars, charts per pool, every trade, a buy and sell ticket, and the AI agents that launched them.</description>
</item>
+ <item>
+ <title>three.ws for Grok</title>
+ <link>https://three.ws/grok</link>
+ <guid isPermaLink="false">2026-10-08:three.ws for Grok</guid>
+ <pubDate>Thu, 08 Oct 2026 12:00:00 GMT</pubDate>
+ <category>launch</category>
+ <description>One sentence gives Grok Bot a 3D studio. Text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear. Works in Grok Bot, Grok connectors and the xAI API. Free, no account, no key.</description>
+ </item>
<item>
<title>three.ws x DEXTools</title>
<link>https://three.ws/dextools</link>
diff --git a/public/features.json b/public/features.json
index 8fa147b20..52d91195c 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-09T02:41:54.930Z",
+ "generated_at": "2026-10-09T02:58:06.057Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
@@ -666,6 +666,16 @@
"tags": [],
"showcase": false
},
+ {
+ "path": "/grok",
+ "title": "three.ws for Grok",
+ "description": "One sentence gives Grok Bot a 3D studio. Text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear. Works in Grok Bot, Grok connectors and the xAI API. Free, no account, no key.",
+ "added": "2026-10-08",
+ "auth": null,
+ "indexable": true,
+ "tags": [],
+ "showcase": false
+ },
{
"path": "/nvidia",
"title": "three.ws on NVIDIA",
@@ -1083,16 +1093,6 @@
"tags": [],
"showcase": false
},
- {
- "path": "/docs/dextools",
- "title": "DEXTools integration guide",
- "description": "How three.ws works with DEXTools: DEXTools charts on every coin page, any pair rendered as a live 3D scene, the embeddable Social Boost card, and how to paste a DEXTools link to get an embed snippet.",
- "added": "2026-10-08",
- "auth": null,
- "indexable": true,
- "tags": [],
- "showcase": false
- },
{
"path": "/docs/portal",
"title": "How Portal builds a 3D world from a URL",
@@ -5118,6 +5118,16 @@
"tags": [],
"showcase": false
},
+ {
+ "path": "/docs/grok",
+ "title": "Docs · three.ws for Grok",
+ "description": "Connect Grok Bot, Grok connectors or the xAI API to the free three.ws remote MCP server at /api/mcp-grok: text and image to 3D, rigged avatars, and a named 3D persona that lip-syncs its replies, with no account, payment or API key.",
+ "added": "2026-10-08",
+ "auth": null,
+ "indexable": true,
+ "tags": [],
+ "showcase": false
+ },
{
"path": "/docs/chatgpt-ar",
"title": "Docs · AR in ChatGPT",
diff --git a/public/guards.json b/public/guards.json
index 73301b650..15b48367d 100644
--- a/public/guards.json
+++ b/public/guards.json
@@ -1,5 +1,5 @@
{
- "updated": "2026-09-20",
+ "updated": "2026-10-09",
"summary": "Every mechanical guard that protects this repository, and the stage each one runs in. This file is the single source of truth: scripts/audit-guards.mjs proves every entry is real and every stage claim is true, docs/guards.md explains them, and /guards renders them.",
"stages": [
{
@@ -438,6 +438,31 @@
"expect": "no curated listing copy"
}
},
+ {
+ "id": "audit-mcp-surfaces",
+ "script": "scripts/build-mcp-surfaces.mjs",
+ "npm": "audit:mcp-surfaces",
+ "title": "MCP resource and prompt listings",
+ "protects": "Every hosted MCP server's registry manifest (server*.json) and the public directory at public/.well-known/mcp.json list exactly the resources, resource templates and guided prompts that server really serves.",
+ "why": "Registries and MCP clients decide what a server offers from these listings before they ever connect. The lists are generated from api/_mcp/resources.js and api/_mcp/prompts.js, so a prompt or resource added, renamed or removed in code leaves the published manifests advertising things that do not exist, or hiding things that do, until someone remembers to regenerate. This check fails when any committed listing no longer matches what the code serves.",
+ "stages": [
+ "gate"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "The public MCP directory advertising no guided prompts for the main server while the code still serves them.",
+ "violation": {
+ "json": [
+ {
+ "file": "public/.well-known/mcp.json",
+ "pointer": "servers.0.prompts",
+ "set": []
+ }
+ ]
+ },
+ "expect": "MCP resource/prompt listings are stale"
+ }
+ },
{
"id": "audit-mcp-manifests",
"script": "scripts/audit-mcp-manifests.mjs",
@@ -1607,6 +1632,22 @@
"expect": "is declared but"
}
},
+ {
+ "id": "check-xai-models",
+ "script": "scripts/check-xai-models.mjs",
+ "npm": "check:xai-models",
+ "title": "Grok model catalog matches xAI",
+ "protects": "Every Grok model id in GROK_MODELS (api/_lib/chat-models.js) is one xAI still serves, every chat model xAI serves is catalogued, and each catalogued price, context window, image input, tool calling and reasoning-effort set matches xAI's own figures.",
+ "why": "xAI ships new model ids often and retires old ones in batches. A retired id in the catalog turns the Grok rung of every LLM failover chain into a guaranteed error, a new id nobody catalogued is a better or cheaper model no one on the platform can pick, and llm-pricing.js meters Grok spend from the catalog's prices, so a stale price is a wrong spend ledger. It reads the xAI models API when GROK_API_KEY or XAI_API_KEY is set and xAI's public model docs otherwise, and exits 2 rather than 1 when neither source can be read, so an outage is never reported as drift.",
+ "stages": [
+ "manual"
+ ],
+ "needs": "network",
+ "proof": {
+ "kind": "live",
+ "reason": "The thing under test is what xAI serves today, read from its models API or its public model docs. There is no offline input whose mutation proves anything about a third party's live catalog, and the comparison never sends a prompt or spends a token."
+ }
+ },
{
"id": "i18n-home",
"script": "scripts/i18n-home-keys.mjs",
diff --git a/public/llms-full.txt b/public/llms-full.txt
index 68f2716a5..068588e1f 100644
--- a/public/llms-full.txt
+++ b/public/llms-full.txt
@@ -366,6 +366,12 @@ URL: https://three.ws/openai
three.ws is an OpenAI Select Partner in the OpenAI Partner Network. Connect the free three.ws 3D Studio MCP server to ChatGPT and turn a prompt into an interactive, riggable, AR-ready 3D model inline in the conversation.
+### three.ws for Grok
+
+URL: https://three.ws/grok
+
+One sentence gives Grok Bot a 3D studio. Text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear. Works in Grok Bot, Grok connectors and the xAI API. Free, no account, no key.
+
### three.ws on NVIDIA
URL: https://three.ws/nvidia
@@ -624,12 +630,6 @@ URL: https://three.ws/docs/brownout
Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.
-### DEXTools integration guide
-
-URL: https://three.ws/docs/dextools
-
-How three.ws works with DEXTools: DEXTools charts on every coin page, any pair rendered as a live 3D scene, the embeddable Social Boost card, and how to paste a DEXTools link to get an embed snippet.
-
### How Portal builds a 3D world from a URL
URL: https://three.ws/docs/portal
@@ -3077,6 +3077,12 @@ URL: https://three.ws/docs/mcp-studio
The free, no-auth MCP server behind the ChatGPT 3D Studio app: text and image to 3D, rigged avatars, conversational refinement, and living agent personas.
+### Docs · three.ws for Grok
+
+URL: https://three.ws/docs/grok
+
+Connect Grok Bot, Grok connectors or the xAI API to the free three.ws remote MCP server at /api/mcp-grok: text and image to 3D, rigged avatars, and a named 3D persona that lip-syncs its replies, with no account, payment or API key.
+
### Docs · AR in ChatGPT
URL: https://three.ws/docs/chatgpt-ar
diff --git a/public/llms.txt b/public/llms.txt
index f741faf28..7483989f4 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -96,6 +96,6 @@ Machine-readable entry points. Fetch these instead of scraping HTML.
## Optional
-- [llms-full.txt](https://three.ws/llms-full.txt): Every public page (931), grouped by section, with full descriptions.
+- [llms-full.txt](https://three.ws/llms-full.txt): Every public page (932), grouped by section, with full descriptions.
- [Sitemap](https://three.ws/sitemap): The same index for people, with search.
- [sitemap.xml](https://three.ws/sitemap.xml): XML sitemap for crawlers, including every agent and avatar page.
diff --git a/public/sitemap/index.html b/public/sitemap/index.html
index ebf49dd30..82f3c4076 100644
--- a/public/sitemap/index.html
+++ b/public/sitemap/index.html
@@ -3,16 +3,16 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
-<title>Sitemap · three.ws</title>
-<meta name="description" content="Human-readable index of every page on three.ws." />
+<title data-i18n="sitemap_index.meta_title">Sitemap · three.ws</title>
+<meta name="description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_description"/>
<meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1" />
<link rel="canonical" href="https://three.ws/sitemap" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="three.ws" />
<meta property="og:locale" content="en_US" />
<meta property="og:url" content="https://three.ws/sitemap" />
-<meta property="og:title" content="Sitemap · three.ws" />
-<meta property="og:description" content="Human-readable index of every page on three.ws." />
+<meta property="og:title" content="Sitemap · three.ws" data-i18n-attr="content:sitemap_index.meta_og_title"/>
+<meta property="og:description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_og_description"/>
<meta property="og:image" content="https://three.ws/api/page-og?s=main&amp;t=Sitemap&amp;d=Human-readable+index+of+every+page+on+three.ws.&amp;p=%2Fsitemap" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
@@ -20,8 +20,8 @@
<meta property="og:image:alt" content="Sitemap - three.ws" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@trythreews" />
-<meta name="twitter:title" content="Sitemap · three.ws" />
-<meta name="twitter:description" content="Human-readable index of every page on three.ws." />
+<meta name="twitter:title" content="Sitemap · three.ws" data-i18n-attr="content:sitemap_index.meta_twitter_title"/>
+<meta name="twitter:description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_twitter_description"/>
<meta name="twitter:image" content="https://three.ws/api/page-og?s=main&amp;t=Sitemap&amp;d=Human-readable+index+of+every+page+on+three.ws.&amp;p=%2Fsitemap" />
<script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebPage","name":"Sitemap","description":"Human-readable index of every page on three.ws.","url":"https://three.ws/sitemap","isPartOf":{"@type":"WebSite","name":"three.ws","url":"https://three.ws"},"primaryImageOfPage":"https://three.ws/api/page-og?s=main&t=Sitemap&d=Human-readable+index+of+every+page+on+three.ws.&p=%2Fsitemap"}]}</script>
<link rel="alternate" type="application/xml" title="XML sitemap" href="/sitemap.xml" />
@@ -95,33 +95,33 @@
<header><div id="nav-container"></div></header>
<main class="sm-wrap">
<div class="sm-hero">
- <h1>Sitemap</h1>
- <p><span>981</span> <span data-i18n="sitemap_index.pages_grouped">pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</span></p>
+ <h1 data-i18n="sitemap_index.sitemap">Sitemap</h1>
+ <p><span>982</span> <span data-i18n="sitemap_index.pages_grouped">pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</span></p>
<div class="sm-formats">
- <a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a>
- <a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>
- <a href="/llms-full.txt"><code>llms-full.txt</code> · long form</a>
- <a href="/api/features.json"><code>features.json</code> · machine manifest</a>
- <a href="/changelog"><code>changelog</code> · what's new</a>
- <a href="/openapi.json"><code>openapi.json</code> · HTTP API</a>
+ <a href="/sitemap.xml" data-i18n-html="sitemap_index.for_search_engines"><code>sitemap.xml</code> · for search engines</a>
+ <a href="/llms.txt" data-i18n-html="sitemap_index.for_ai_agents"><code>llms.txt</code> · for AI agents</a>
+ <a href="/llms-full.txt" data-i18n-html="sitemap_index.long_form"><code>llms-full.txt</code> · long form</a>
+ <a href="/api/features.json" data-i18n-html="sitemap_index.machine_manifest"><code>features.json</code> · machine manifest</a>
+ <a href="/changelog" data-i18n-html="sitemap_index.what_s_new"><code>changelog</code> · what's new</a>
+ <a href="/openapi.json" data-i18n-html="sitemap_index.http_api"><code>openapi.json</code> · HTTP API</a>
</div>
</div>
<div class="sm-filter">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>
- <input id="sm-filter-input" type="search" placeholder="Filter 981 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
+ <input id="sm-filter-input" type="search" placeholder="Filter 982 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
<kbd id="sm-filter-kbd" aria-hidden="true">/</kbd>
</div>
<p class="sm-filter-count" role="status" aria-live="polite"><span id="sm-filter-count"></span><span id="sm-filter-hint" aria-hidden="true"></span></p>
<section class="sm-new" id="sm-new" aria-labelledby="sm-new-title">
- <h2 id="sm-new-title">Newest<a class="sm-new-more" href="/changelog">full changelog &rarr;</a></h2>
- <p class="sm-section-desc">The 9 most recently launched pages, straight to the live surface.</p>
+ <h2 id="sm-new-title" data-i18n-html="sitemap_index.newestfull_changelog">Newest<a class="sm-new-more" href="/changelog">full changelog &rarr;</a></h2>
+ <p class="sm-section-desc" data-i18n="sitemap_index.the_9_most_recently_launched_pages_straight">The 9 most recently launched pages, straight to the live surface.</p>
<ul class="sm-list">
<li>
- <a href="/docs/dextools">
+ <a href="/grok">
<span class="sm-new-date" translate="no">Oct 8, 2026</span>
- <span class="sm-title"><span data-i18n="sitemap_index.t_docs_dextools">DEXTools integration guide</span></span>
- <span class="sm-path" translate="no">/docs/dextools</span>
- <span class="sm-desc" data-i18n="sitemap_index.d_docs_dextools">How three.ws works with DEXTools: DEXTools charts on every coin page, any pair rendered as a live 3D scene, the embeddable Social Boost card, and how to paste a DEXTools link to get an embed snippet.</span>
+ <span class="sm-title"><span data-i18n="sitemap_index.t_grok">three.ws for Grok</span></span>
+ <span class="sm-path" translate="no">/grok</span>
+ <span class="sm-desc" data-i18n="sitemap_index.d_grok">One sentence gives Grok Bot a 3D studio. Text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear. Works in Grok Bot, Grok connectors and the xAI API. Free, no account, no key.</span>
</a>
</li>
<li>
@@ -181,32 +181,32 @@
</a>
</li>
<li>
- <a href="/duels">
- <span class="sm-new-date" translate="no">Sep 30, 2026</span>
- <span class="sm-title"><span data-i18n="sitemap_index.t_duels">Trader Duels: call the winner</span></span>
- <span class="sm-path" translate="no">/duels</span>
- <span class="sm-desc" data-i18n="sitemap_index.d_duels">Call which of two pump.fun trader agents books more realized profit over a fixed UTC window. Free to play with a daily points allowance; points have no cash value. Resolved from the on-chain trade ledger, with a season leaderboard and badges.</span>
+ <a href="/docs/grok">
+ <span class="sm-new-date" translate="no">Oct 8, 2026</span>
+ <span class="sm-title"><span data-i18n="sitemap_index.t_docs_grok">Docs · three.ws for Grok</span></span>
+ <span class="sm-path" translate="no">/docs/grok</span>
+ <span class="sm-desc" data-i18n="sitemap_index.d_docs_grok">Connect Grok Bot, Grok connectors or the xAI API to the free three.ws remote MCP server at /api/mcp-grok: text and image to 3D, rigged avatars, and a named 3D persona that lip-syncs its replies, with no account, payment or API key.</span>
</a>
</li>
</ul>
</section>
<nav class="sm-toc" aria-label="Sections">
- <a href="#main">Main</a>
- <a href="#build">Build</a>
- <a href="#labs">Labs</a>
- <a href="#crypto">Crypto</a>
- <a href="#agent-tools">Agent Tools</a>
- <a href="#account">Account</a>
- <a href="#learn">Learn</a>
- <a href="#blog">Blog</a>
- <a href="#legal">Legal</a>
- <a href="#machine">Machine-readable</a>
- <a href="#news">News</a>
+ <a href="#main" data-i18n="sitemap_index.main">Main</a>
+ <a href="#build" data-i18n="sitemap_index.build">Build</a>
+ <a href="#labs" data-i18n="sitemap_index.labs">Labs</a>
+ <a href="#crypto" data-i18n="sitemap_index.crypto">Crypto</a>
+ <a href="#agent-tools" data-i18n="sitemap_index.agent_tools">Agent Tools</a>
+ <a href="#account" data-i18n="sitemap_index.account">Account</a>
+ <a href="#learn" data-i18n="sitemap_index.learn">Learn</a>
+ <a href="#blog" data-i18n="sitemap_index.blog">Blog</a>
+ <a href="#legal" data-i18n="sitemap_index.legal">Legal</a>
+ <a href="#machine" data-i18n="sitemap_index.machine_readable">Machine-readable</a>
+ <a href="#news" data-i18n="sitemap_index.news">News</a>
</nav>
<section class="sm-section" id="main">
<header>
- <h2><span data-i18n="sitemap_index.section_main">Main</span><span class="sm-count" data-count>62</span></h2>
- <p class="sm-section-desc">Entry points into the product.</p>
+ <h2><span data-i18n="sitemap_index.section_main">Main</span><span class="sm-count" data-count>63</span></h2>
+ <p class="sm-section-desc" data-i18n="sitemap_index.entry_points_into_the_product">Entry points into the product.</p>
</header>
<ul class="sm-list">
<li>
@@ -601,6 +601,13 @@
<span class="sm-desc" data-i18n="sitemap_index.d_openai">three.ws is an OpenAI Select Partner in the OpenAI Partner Network. Connect the free three.ws 3D Studio MCP server to ChatGPT and turn a prompt into an interactive, riggable, AR-ready 3D model inline in the conversation.</span>
</a>
</li>
+ <li>
+ <a href="/grok">
+ <span class="sm-title"><span data-i18n="sitemap_index.t_grok">three.ws for Grok</span></span>
+ <span class="sm-path" translate="no">/grok</span>
+ <span class="sm-desc" data-i18n="sitemap_index.d_grok">One sentence gives Grok Bot a 3D studio. Text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear. Works in Grok Bot, Grok connectors and the xAI API. Free, no account, no key.</span>
+ </a>
+ </li>
<li>
<a href="/nvidia">
<span class="sm-title"><span data-i18n="sitemap_index.t_nvidia">three.ws on NVIDIA</span></span>
@@ -648,8 +655,8 @@
<section class="sm-section" id="build">
<header>
- <h2><span data-i18n="sitemap_index.section_build">Build</span><span class="sm-count" data-count>81</span></h2>
- <p class="sm-section-desc">Create and customize an agent.</p>
+ <h2><span data-i18n="sitemap_index.section_build">Build</span><span class="sm-count" data-count>80</span></h2>
+ <p class="sm-section-desc" data-i18n="sitemap_index.create_and_customize_an_agent">Create and customize an agent.</p>
</header>
<ul class="sm-list">
<li>
@@ -897,13 +904,6 @@
<span class="sm-desc" data-i18n="sitemap_index.d_docs_brownout">Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.</span>
</a>
</li>
- <li>
- <a href="/docs/dextools">
- <span class="sm-title"><span data-i18n="sitemap_index.t_docs_dextools">DEXTools integration guide</span></span>
- <span class="sm-path" translate="no">/docs/dextools</span>
- <span class="sm-desc" data-i18n="sitemap_index.d_docs_dextools">How three.ws works with DEXTools: DEXTools charts on every coin page, any pair rendered as a live 3D scene, the embeddable Social Boost card, and how to paste a DEXTools link to get an embed snippet.</span>
- </a>
- </li>
<li>
<a href="/docs/portal">
<span class="sm-title"><span data-i18n="sitemap_index.t_docs_portal">How Portal builds a 3D world from a URL</span></span>
@@ -1225,7 +1225,7 @@
<section class="sm-section" id="labs">
<header>
<h2><span data-i18n="sitemap_index.section_labs">Labs</span><span class="sm-count" data-count>25</span></h2>
- <p class="sm-section-desc">Experimental features actively shipping. Expect fast iteration.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.experimental_features_actively_shipping_expe">Experimental features actively shipping. Expect fast iteration.</p>
</header>
<ul class="sm-list">
<li>
@@ -1409,7 +1409,7 @@
<section class="sm-section" id="crypto">
<header>
<h2><span data-i18n="sitemap_index.section_crypto">Crypto</span><span class="sm-count" data-count>159</span></h2>
- <p class="sm-section-desc">On-chain features: pay-per-call, token launches, vanity wallets.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.on_chain_features_pay_per_call_token">On-chain features: pay-per-call, token launches, vanity wallets.</p>
</header>
<ul class="sm-list">
<li>
@@ -2531,7 +2531,7 @@
<section class="sm-section" id="agent-tools">
<header>
<h2><span data-i18n="sitemap_index.section_agent-tools">Agent Tools</span><span class="sm-count" data-count>10</span></h2>
- <p class="sm-section-desc">Manage, talk to, and deploy individual agents.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.manage_talk_to_and_deploy_individual_agents">Manage, talk to, and deploy individual agents.</p>
</header>
<ul class="sm-list">
<li>
@@ -2610,7 +2610,7 @@
<section class="sm-section" id="account">
<header>
<h2><span data-i18n="sitemap_index.section_account">Account</span><span class="sm-count" data-count>14</span></h2>
- <p class="sm-section-desc">Sign-in, dashboard, billing.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.sign_in_dashboard_billing">Sign-in, dashboard, billing.</p>
</header>
<ul class="sm-list">
<li>
@@ -2716,8 +2716,8 @@
<section class="sm-section" id="learn">
<header>
- <h2><span data-i18n="sitemap_index.section_learn">Learn</span><span class="sm-count" data-count>453</span></h2>
- <p class="sm-section-desc">Docs, tutorials, and reference.</p>
+ <h2><span data-i18n="sitemap_index.section_learn">Learn</span><span class="sm-count" data-count>454</span></h2>
+ <p class="sm-section-desc" data-i18n="sitemap_index.docs_tutorials_and_reference">Docs, tutorials, and reference.</p>
</header>
<ul class="sm-list">
<li>
@@ -3742,6 +3742,13 @@
<span class="sm-desc" data-i18n="sitemap_index.d_docs_mcp_studio">The free, no-auth MCP server behind the ChatGPT 3D Studio app: text and image to 3D, rigged avatars, conversational refinement, and living agent personas.</span>
</a>
</li>
+ <li>
+ <a href="/docs/grok">
+ <span class="sm-title"><span data-i18n="sitemap_index.t_docs_grok">Docs · three.ws for Grok</span></span>
+ <span class="sm-path" translate="no">/docs/grok</span>
+ <span class="sm-desc" data-i18n="sitemap_index.d_docs_grok">Connect Grok Bot, Grok connectors or the xAI API to the free three.ws remote MCP server at /api/mcp-grok: text and image to 3D, rigged avatars, and a named 3D persona that lip-syncs its replies, with no account, payment or API key.</span>
+ </a>
+ </li>
<li>
<a href="/docs/chatgpt-ar">
<span class="sm-title"><span data-i18n="sitemap_index.t_docs_chatgpt_ar">Docs · AR in ChatGPT</span></span>
@@ -5897,7 +5904,7 @@
<section class="sm-section" id="blog">
<header>
<h2><span data-i18n="sitemap_index.section_blog">Blog</span><span class="sm-count" data-count>39</span></h2>
- <p class="sm-section-desc">Long-form announcements, launches, and writing from three.ws.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.long_form_announcements_launches_and_writing">Long-form announcements, launches, and writing from three.ws.</p>
</header>
<ul class="sm-list">
<li>
@@ -6251,7 +6258,7 @@
<section class="sm-section" id="machine">
<header>
<h2><span data-i18n="sitemap_index.section_machine">Machine-readable</span><span class="sm-count" data-count>17</span></h2>
- <p class="sm-section-desc">Indexes and well-known files for crawlers and AI agents.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.indexes_and_well_known_files_for_crawlers">Indexes and well-known files for crawlers and AI agents.</p>
</header>
<ul class="sm-list">
<li>
@@ -6379,7 +6386,7 @@
<section class="sm-section" id="news">
<header>
<h2><span data-i18n="sitemap_index.section_news">News</span><span class="sm-count" data-count>112</span></h2>
- <p class="sm-section-desc">Product launches, integrations, and announcements from three.ws.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.product_launches_integrations_and_announceme">Product launches, integrations, and announcements from three.ws.</p>
</header>
<ul class="sm-list">
<li>
@@ -7170,10 +7177,10 @@
</section>
<div class="sm-empty" id="sm-empty" hidden>
<p><span data-i18n="sitemap_index.no_pages_match">No pages match</span> &ldquo;<span id="sm-empty-q"></span>&rdquo;.</p>
- <p class="sm-empty-hint">Try a shorter word, or search everything: global search covers agents, coins, and skills too.</p>
+ <p class="sm-empty-hint" data-i18n="sitemap_index.try_a_shorter_word_or_search_everything">Try a shorter word, or search everything: global search covers agents, coins, and skills too.</p>
<div class="sm-empty-actions">
- <button type="button" id="sm-empty-clear">Clear filter</button>
- <a id="sm-empty-search" href="/search">Search all of three.ws</a>
+ <button type="button" id="sm-empty-clear" data-i18n="sitemap_index.clear_filter">Clear filter</button>
+ <a id="sm-empty-search" href="/search" data-i18n="sitemap_index.search_all_of_three_ws">Search all of three.ws</a>
</div>
</div>
</main>
diff --git a/scripts/audit-docs.mjs b/scripts/audit-docs.mjs
index 62905f89c..c63f87a14 100644
--- a/scripts/audit-docs.mjs
+++ b/scripts/audit-docs.mjs
@@ -351,6 +351,10 @@ const UNPUBLISHED_DOCS = new Map([
['ibm-community-thread', 'internal: source draft of an IBM Community post'],
['ibm-community-doc-freshness-post', 'internal: source draft of an IBM Community post'],
['ibm-community-long-running-mcp-tools-post', 'internal: source draft of an IBM Community post'],
+ ['ibm-community-long-running-mcp-tools-thread', 'internal: discussion-thread draft for the IBM Community user group, companion to its post'],
+ ['ibm-community-doc-freshness-thread', 'internal: discussion-thread draft for the IBM Community user group, companion to its post'],
+ ['ibm-community-any-skeleton-animation-post', 'internal: source draft of an IBM Community post'],
+ ['ibm-community-any-skeleton-animation-thread', 'internal: discussion-thread draft for the IBM Community user group, companion to its post'],
[
'ibm-community-governed-agents-thread',
'internal: discussion-thread draft for the IBM Community user group, held until POST /api/guardian/assess answers on production',
@@ -383,6 +387,7 @@ const UNPUBLISHED_DOCS = new Map([
['pump-fun-mcp-edge', 'owner-gated: names a crypto project other than $THREE'],
['pump-launch-repos', 'owner-gated: names a crypto project other than $THREE'],
['pump-platform-fee', 'owner-gated: names a crypto project other than $THREE'],
+ ['pons-launch', 'owner-gated: names a crypto project other than $THREE'],
['robinhood-chain-markets', 'owner-gated: names a crypto project other than $THREE'],
['solana-pumpfun', 'owner-gated: names a crypto project other than $THREE'],
['syndication', 'internal: distribution mechanics for the announcements feed'],
diff --git a/services/autopilot/README.md b/services/autopilot/README.md
new file mode 100644
index 000000000..e4d9889e5
--- /dev/null
+++ b/services/autopilot/README.md
@@ -0,0 +1,256 @@
+# autopilot
+
+An unattended production repair loop for three.ws. Every two hours it syncs
+`main`, sweeps production with the GCP triage, and, when the sweep finds
+something it is allowed to fix, starts a headless Claude Code session to fix and
+commit it. The runner (not Claude) then gates the commits on `npm test`, pushes
+to `threews main`, deploys, verifies the deploy, and rolls traffic back if the
+verification fails. Every tick leaves a full record in Cloud Storage and, when
+something happened, a short Telegram report to the owner.
+
+It is designed to run as the `autopilot` user on a dedicated Compute Engine VM,
+`three-ws-autopilot`, in project `aerial-vehicle-466722-p5`.
+
+Not to be confused with evolve (`scripts/evolve.mjs`, [docs/ops/evolve.md](../../docs/ops/evolve.md)),
+the development loop that works the `prompts/finish/` queue on a developer
+machine and is denied every owner-gated action. This loop is the opposite
+shape: it only reacts to production findings, and the owner has approved it to
+ship its own fixes.
+
+## Status
+
+**Written, not provisioned.** Checked on 2026-10-09:
+
+- There is no Compute Engine instance with `autopilot` in its name in the project.
+- The report bucket `gs://three-ws-autopilot` does not exist.
+- The push credential secret `autopilot-github-token` does not exist.
+- `three-ws-api` carries no `TELEGRAM_ALERTS_CHAT_ID`, so notifications would
+ fall back to `message.txt` unless the VM metadata attribute below is set. The
+ `telegram-bot-token` secret does exist.
+
+Three files the scripts refer to are not in the repository and never were (no
+commit in any branch has touched them):
+
+- `provision.sh`, which `bootstrap.sh` says installs it as the VM's
+ `startup-script` metadata. The VM, the bucket, the secret and the service
+ account bindings are therefore created by hand today; [Provisioning](#provisioning)
+ lists what that takes.
+- `autopilot.service` and `autopilot.timer`, which `bootstrap.sh` installs from
+ this directory into `/etc/systemd/system/`. As committed, `bootstrap.sh` stops
+ at that `install` step (`set -e`). The units have to exist before the loop can
+ run on its timer; [The systemd units](#the-systemd-units) states what they
+ must do.
+
+## Files
+
+| File | Role |
+|---|---|
+| [run.sh](run.sh) | One tick, end to end. The whole body lives in `main()` so bash parses it before running it, because the tick resets this very file to the newest `main`. |
+| [bootstrap.sh](bootstrap.sh) | VM startup script, run as root on every boot. Idempotent. |
+| [prompt.md](prompt.md) | The instructions the Claude session runs under: inputs, method, hard limits, and the required `result.json`. |
+| [claude-settings.json](claude-settings.json) | Copied to `~/.claude/settings.json` for the `autopilot` user before each session: a deny list for every ship, spend and destroy command, and the auto-updater and telemetry switched off. |
+| [notify.mjs](notify.mjs) | Composes and sends the Telegram report for one tick. |
+
+## What a tick does
+
+`run.sh`, in order. Every step writes its outcome into the tick's `status.json`.
+
+1. **Lock.** `flock` on `$AUTOPILOT_HOME/.autopilot.lock`. If the previous tick
+ is still running, this one logs `previous tick still running, skipping` and
+ exits 0.
+2. **Sync.** In `$AUTOPILOT_HOME/three.ws`: `git fetch threews main`, then a
+ forced checkout of `main` at `threews/main` and `git clean -fdq`. The clone is
+ the runner's own; nobody edits it.
+3. **Install.** `npm ci` (plus the Playwright Chromium) only when
+ `package-lock.json` changed since the last tick, otherwise just `postinstall`.
+ Always `deps:chat`. Rebuilds the avatar studio when `character-studio/`
+ changed or its build is missing.
+4. **Env.** Writes `.env.local` holding only `DATABASE_URL`, read fresh from the
+ live `three-ws-api` service with `scripts/read-service-env.mjs` so a rotated
+ credential never goes stale, and truncates `.env`.
+5. **Triage.** `npm run triage:gcp -- --json --deep --since 3h` into
+ `triage.json`. Each finding carries a class (see
+ [docs/ops/production-log-triage.md](../../docs/ops/production-log-triage.md)).
+6. **Decide.** Only `env-action` and `investigate` findings wake Claude. `owner`
+ and `self-healing` findings never do. A signature Claude deferred in an
+ earlier tick is skipped for `AUTOPILOT_DEFER_HOURS`. With nothing actionable
+ the tick ends here.
+7. **Claude.** `claude -p` with [prompt.md](prompt.md) (with `AUTOPILOT_RUN_DIR`
+ and `AUTOPILOT_HISTORY` substituted), the configured model on Vertex AI
+ (`CLAUDE_CODE_USE_VERTEX=1`, billed to the project), `--permission-mode
+ bypassPermissions`, the deny list from `claude-settings.json`, and a hard
+ timeout. The session reads the last eight tick summaries first, fixes and
+ commits, and must write `result.json`. Anything it leaves uncommitted is saved
+ as `uncommitted.patch` and discarded, never shipped.
+8. **Gate.** No new commits and `result.json` not asking for a deploy: done.
+ With commits, `npm test` must pass. On a red, the commits are pushed to a
+ review branch `autopilot/<timestamp>` instead of `main`, and nothing deploys.
+9. **Push.** To `threews main`. If `main` moved meanwhile, it rebases once and
+ retries; a rebase conflict pushes `autopilot/<timestamp>` for review instead.
+ The repository's pre-push hook (`check:rules` and the secrets scan) still
+ runs on this push.
+10. **Deploy.** The steps of `npm run deploy:gcp:full`, split so traffic can be
+ moved explicitly: `clean:worktrees -- --apply`, `build:gcp`, `check:dist`,
+ `check:pages`, `deploy:gcp:submit` (which includes the pending-migration
+ gate), `update-traffic --to-latest` (a previous rollback pins traffic, and a
+ plain deploy would then not receive any), `deploy:gcp:sync-crons`,
+ `deploy:gcp:purge-cdn`.
+11. **Verify, or roll back.** The deploy counts as live only when `smoke:prod`
+ passes, `/api/version` reports the commit just pushed, and `/api/healthz` did
+ not go from `200` to anything else. Otherwise traffic goes back to the
+ revision that was serving before, the CDN is purged again, and the tick
+ records `rollback`. The next tick's history shows the rollback, and the
+ prompt tells Claude to fix or revert the offending commit before anything
+ else.
+12. **Report.** `notify.mjs`, then the whole run directory is copied to
+ `gs://three-ws-autopilot/runs/<timestamp>/`. Local run directories older than
+ 14 days are deleted.
+
+### What Claude may and may not do
+
+The prompt's hard limits override everything else in it: no money movement of
+any kind (wallet and treasury findings are owner items), no destroying data, no
+`db:migrate` (pending migrations are reported with the `db:status` output), no
+secret values anywhere, no commit referencing a crypto project other than
+$THREE, config changes only through `gcloud run services update
+--update-env-vars`, and one small commit per problem in the house commit style.
+
+`claude-settings.json` enforces the ship and destroy half mechanically: `git
+push`, every `npm run deploy*`, `db:migrate`, `db:restamp`, `changelog:push`,
+`gcloud builds submit`, any `gcloud ... delete`, `run services replace`,
+`--set-env-vars` and `--clear-env-vars`, creating or changing secrets, and
+`gcloud projects` / `gcloud iam` are all denied. Pushing and deploying happen in
+`run.sh` only, after Claude has exited.
+
+The push credential never reaches Claude or the disk: `run.sh` reads
+`autopilot-github-token` from Secret Manager at push time and passes it to git
+as an HTTP header on the command line of that one process.
+
+## Configuration
+
+Environment variables read by `run.sh` (and `AUTOPILOT_PROJECT` /
+`AUTOPILOT_HOME` by `notify.mjs`):
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `AUTOPILOT_PROJECT` | `aerial-vehicle-466722-p5` | GCP project for Cloud Run, Secret Manager and Vertex AI. |
+| `AUTOPILOT_REGION` | `us-central1` | Cloud Run region of `three-ws-api`. |
+| `AUTOPILOT_HOME` | `$HOME` | Base directory. The clone is `$AUTOPILOT_HOME/three.ws`; tick records live in `$AUTOPILOT_HOME/runs/`. |
+| `AUTOPILOT_BUCKET` | `gs://three-ws-autopilot` | Where every run directory is uploaded. |
+| `AUTOPILOT_MODEL` | `claude-opus-5` | Model id passed to `claude --model`. |
+| `AUTOPILOT_CLAUDE_TIMEOUT` | `100m` | Hard limit on the Claude session (`timeout`, killed 2 minutes after). |
+| `AUTOPILOT_DEFER_HOURS` | `24` | How long a signature Claude deferred stays quiet. |
+| `AUTOPILOT_GH_SECRET` | `autopilot-github-token` | Secret Manager secret holding the GitHub token used to push. |
+| `AUTOPILOT_NO_SHIP` | unset | Any value: run Claude, but never test-gate, push or deploy. |
+| `AUTOPILOT_DRY_RUN` | unset | Any value: sync, install, triage and the gating decision only. Claude never starts. |
+
+State kept in `$AUTOPILOT_HOME` between ticks:
+
+| Path | Contents |
+|---|---|
+| `runs/<timestamp>/` | One tick: `status.json`, `run.log`, `triage.json`, and when they apply `claude.jsonl`, `result.json`, `history.jsonl`, `test.log`, `uncommitted.patch`, `message.txt`. |
+| `history.jsonl` | One line per tick (dry runs and ticks that failed before triage excepted): its `status.json` plus Claude's `result.json`. The last eight, newest first, are handed to the next session. |
+| `deferred.json` | Signature to the time Claude first deferred it. |
+| `.owner-signatures` | The owner-class signatures last reported, so an unchanged list is not re-sent. |
+
+## Notifications
+
+`notify.mjs <run-dir>` keeps quiet ticks quiet. It sends a message only when the
+tick did something (Claude ran, a push, deploy or rollback happened, a step
+failed) or when the set of owner-class findings changed since the last message.
+The message carries the verdict, Claude's summary, what was fixed, config changes
+applied, the ship line (tests, push, deploy), owner items with their exact
+commands, deferrals, the Claude cost, and the GCS path of the full report. It is
+cut to 4000 characters for Telegram.
+
+- **Bot token:** the `telegram-bot-token` Secret Manager secret.
+- **Destination:** the VM metadata attribute `autopilot-telegram-chat-id`, else
+ `TELEGRAM_ALERTS_CHAT_ID` on `three-ws-api`. This is the private ops chat,
+ never the public channel.
+- **Not configured:** when either is missing it says which, and the message is
+ still written to `message.txt` in the run directory (and so to the bucket).
+
+## Dry runs
+
+`run.sh` force-resets `$AUTOPILOT_HOME/three.ws` to `threews/main` and deletes
+untracked files there, so never point it at a working checkout. Give it a
+directory of its own:
+
+```bash
+export AUTOPILOT_HOME="$HOME/autopilot-dry"
+mkdir -p "$AUTOPILOT_HOME"
+git clone --origin threews https://github.com/nirholas/three.ws.git "$AUTOPILOT_HOME/three.ws"
+AUTOPILOT_DRY_RUN=1 bash "$AUTOPILOT_HOME/three.ws/services/autopilot/run.sh"
+cat "$AUTOPILOT_HOME"/runs/*/status.json
+```
+
+The first run does a full `npm ci` and the Playwright install, so it takes a
+while. It needs `jq`, `flock` and `envsubst` on the path, and `gcloud` authenticated with read access to `three-ws-api` (for
+`DATABASE_URL` and the triage). The `status.json` it leaves shows the triage
+verdict, how many findings were actionable, and `"claude": "skipped: dry run"`
+(or `"skipped: nothing Claude may act on"`). The report upload fails harmlessly
+while the bucket does not exist (`report upload to gs://three-ws-autopilot
+failed` in `run.log`).
+
+`AUTOPILOT_NO_SHIP=1` goes one step further: Claude runs and commits in the
+dedicated clone, but nothing is tested, pushed or deployed. The commits stay in
+`$AUTOPILOT_HOME/three.ws` for review (and are discarded by the next tick's
+sync).
+
+To check a report without running a tick, point `notify.mjs` at any run
+directory. Off the VM there is no metadata server, so without
+`TELEGRAM_ALERTS_CHAT_ID` on the service it writes `message.txt` and sends
+nothing:
+
+```bash
+node services/autopilot/notify.mjs "$AUTOPILOT_HOME/runs/<timestamp>"
+```
+
+## Provisioning
+
+What `bootstrap.sh` does, on every boot, as root:
+
+1. Installs `git`, `jq`, `curl`, `gettext-base` (for `envsubst`), the build
+ toolchain, the Google Cloud CLI if missing, and Node.js 24 from NodeSource if
+ the installed major is not 24.
+2. Installs the latest `@anthropic-ai/claude-code` globally (refreshed every
+ boot; the CLI's own auto-updater is off for the unattended user).
+3. Adds a 16 GB swap file, because the avatar-studio and frontend builds peak
+ above RAM on a cold build.
+4. Creates the `autopilot` user, sets its gcloud project and `run/region`,
+ clones the repository with the remote named `threews`, runs `npm ci`, and
+ installs Playwright Chromium with its system dependencies.
+5. Installs `autopilot.service` and `autopilot.timer` into systemd and enables
+ the timer.
+
+What has to exist around it, and is not scripted in this repository:
+
+- The VM `three-ws-autopilot` with `bootstrap.sh` as its `startup-script`
+ metadata, a disk large enough for the clone, `node_modules` and a full
+ `build:gcp`, and optionally the `autopilot-telegram-chat-id` metadata
+ attribute.
+- A runtime service account for the VM that can read `three-ws-api`'s
+ configuration and logs, access the `telegram-bot-token` and
+ `autopilot-github-token` secrets, submit Cloud Build builds as the pinned
+ `three-ws-build@` account, update Cloud Run traffic and env vars, invalidate the
+ `three-ws-lb` CDN cache, create Cloud Scheduler jobs, call Vertex AI, and
+ write to the report bucket.
+- The bucket `gs://three-ws-autopilot`.
+- The secret `autopilot-github-token`: a GitHub token that can push to
+ `nirholas/three.ws`.
+
+### The systemd units
+
+`run.sh` and `bootstrap.sh` together define what the two missing units must
+do: `autopilot.service` runs `services/autopilot/run.sh` from the clone as the
+`autopilot` user (a oneshot; the script holds its own lock), and
+`autopilot.timer` starts it every two hours. The tick can take well over an hour
+(a 100-minute Claude session, then tests and a full build and deploy), so the
+service must not carry a shorter timeout.
+
+## Related
+
+- [.agents/skills/gcp-triage/SKILL.md](../../.agents/skills/gcp-triage/SKILL.md): the method the session follows for each finding.
+- [scripts/gcp-triage.mjs](../../scripts/gcp-triage.mjs): the sweep and its known signatures.
+- [docs/ops/production-log-triage.md](../../docs/ops/production-log-triage.md): finding classes and the exact owner commands.
+- [docs/ops/gcp-production.md](../../docs/ops/gcp-production.md): the production runbook the deploy step follows.
diff --git a/services/autopilot/run.sh b/services/autopilot/run.sh
index 442df61fc..89f3a6800 100644
--- a/services/autopilot/run.sh
+++ b/services/autopilot/run.sh
@@ -223,6 +223,7 @@ deploy() {
return 1
fi
gcloud run services update-traffic "$SERVICE" --to-latest --region "$REGION" --project "$PROJECT" --quiet
+ npm run deploy:gcp:sync-crons || note cron_sync "failed: a newly declared cron may have no Scheduler job"
npm run deploy:gcp:purge-cdn
new_rev="$(serving_revision)"
note deploy_revision "$new_rev"
diff --git a/workers/agent-gateway/README.md b/workers/agent-gateway/README.md
new file mode 100644
index 000000000..84fa5c4e3
--- /dev/null
+++ b/workers/agent-gateway/README.md
@@ -0,0 +1,291 @@
+# agent-gateway
+
+The process behind every three.ws chat gateway. An agent owner pairs a Telegram
+or Discord chat with their account, then talks to their agent from that chat:
+plain messages, slash commands, voice notes and photos in, replies, trade
+previews with Approve / Cancel buttons, and account notifications out.
+
+The webhook receivers in the API only verify and queue. This worker does the
+work: it drains the `gateway_inbox` table, runs each delivery through the shared
+gateway core in [api/_lib/gateway/](../../api/_lib/gateway), and sends the
+answer back through the platform's own API.
+
+## How it fits
+
+```
+Telegram ──webhook──► api/gateway/telegram.js ─┐
+Discord ──interaction► api/gateway/discord.js ─┤ verify, queue
+Discord DMs + mentions ── gateway socket ──────┤ (held by this worker)
+api/_lib/gateway/notify.js (notifications) ────┘
+ ▼
+ gateway_inbox
+ │ claim one row per chat, under a lease
+ ▼
+ workers/agent-gateway (this)
+ adapter.normalize(payload) → event
+ handleEvent(event, gw) (api/_lib/gateway/core.js)
+ │
+ ▼
+ reply / preview / notification in the chat
+```
+
+- **Ordering per chat.** `claimInbox` hands out at most one open row per chat,
+ so a chat's replies leave in the order its messages arrived. Concurrency is
+ across chats, never within one.
+- **No double answers.** A claimed row is leased (`GATEWAY_LEASE_SECONDS`) and
+ the lease is renewed every third of its length while the agent turn runs, so a
+ slow turn is never reclaimed and answered twice. Running more than one
+ instance is safe because the claim is exclusive.
+- **Retries that respect the platform.** Every platform refusal is wrapped in a
+ `PlatformError` ([src/errors.js](src/errors.js)). A 4xx other than 408 and 429
+ is permanent and dead-letters at once; a 429 waits at least as long as the
+ platform asked; anything else retries with exponential backoff
+ (`GATEWAY_BACKOFF_BASE_MS`, doubling, capped at `GATEWAY_BACKOFF_MAX_MS`) up to
+ `GATEWAY_MAX_ATTEMPTS`.
+- **Nobody left in silence.** When a row is dead-lettered for a reason that is
+ ours (not a platform refusal, not a partial answer, not a timeout that may
+ still answer), the chat gets a short apology asking the owner to send it again.
+- **Housekeeping.** Every `GATEWAY_SWEEP_MS` it expires overdue trade previews
+ and edits their buttons away ("Expired. Ask your agent again for a fresh
+ quote."), and once an hour it prunes finished rows older than
+ `GATEWAY_PRUNE_KEEP_DAYS`.
+- **Privacy in logs.** Logs are one JSON line each with `severity` and `message`
+ for Cloud Logging ([src/log.js](src/log.js)). Message text from chats never
+ reaches a log: only ids, platforms and error codes.
+
+## Files
+
+| File | Role |
+|---|---|
+| [src/index.js](src/index.js) | Boot: loads config and adapters, starts the inbound listeners, the drain loop and the `/healthz` server, and handles SIGTERM. |
+| [src/config.js](src/config.js) | Reads every knob once at boot, with production defaults and clamped ranges. |
+| [src/drain.js](src/drain.js) | The platform-neutral drain loop: claim, lease renewal, timeout, acknowledge, retry, dead-letter, preview sweep, prune. |
+| [src/adapters/index.js](src/adapters/index.js) | The adapter registry. A new platform is one entry in `FACTORIES` plus its file; the drain loop never changes. |
+| [src/adapters/telegram.js](src/adapters/telegram.js) | Telegram over grammY: update normalization, the send surface, and optional `getUpdates` polling for local work. |
+| [src/adapters/discord.js](src/adapters/discord.js) | Discord over discord.js: interaction replies through the interaction webhook, bot-token REST for everything else, and the gateway connection for DMs and mentions. |
+| [src/errors.js](src/errors.js) | `PlatformError`, the permanent / retry-after / transient classification, and the backoff curve. |
+| [src/setup.js](src/setup.js) | Operator commands: register Discord slash commands, point the Telegram webhook, read the inbox, requeue a dead letter. |
+| [scripts/deploy-env.mjs](scripts/deploy-env.mjs) | Derives the Cloud Run environment from the live `three-ws-api` service at deploy time. |
+| [Dockerfile](Dockerfile), [cloudbuild.yaml](cloudbuild.yaml) | The image (built from the repo root) and the Cloud Build to Cloud Run pipeline. |
+| [tests/](tests) | Vitest suites for the drain loop, both adapters, the registry and the setup commands. |
+
+## Configuration
+
+### Platform credentials
+
+An adapter loads only when its credentials are present. A worker missing one
+boots without that platform, logs `adapter not loaded` with the missing names,
+and lists them under `skipped` in `/healthz`.
+
+| Variable | Needed for | Notes |
+|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | Telegram | The bot the receiver and the worker both speak as. On `three-ws-api` as the Secret Manager reference `telegram-bot-token`. |
+| `TELEGRAM_BOT_USERNAME` | Telegram, optional | Lets the worker tell `/cmd@ourbot` from a command addressed to another bot without a `getMe` call at boot. |
+| `TELEGRAM_WEBHOOK_SECRET` | Telegram, optional | Pins the webhook secret header. When unset, the secret is derived from the bot token (`api/_lib/gateway/webhooks.js`). |
+| `DISCORD_BOT_TOKEN`, `DISCORD_APP_ID` | Discord | Both are required for the adapter to load. |
+| `DISCORD_PUBLIC_KEY` | Discord receiver | Read by `api/gateway/discord.js` to verify interaction signatures, not by this worker, but the connections API only reports the Discord bot as available when all three Discord variables are set. |
+
+The worker also needs everything the agent turn needs: `DATABASE_URL` for the
+inbox, plus the LLM chain, market data, the rate limiter and
+`WALLET_ENCRYPTION_KEY` for the agent's own custodial wallet. In production none
+of that is configured by hand; see [Deploy](#deploy).
+
+### Tuning knobs
+
+All read by [src/config.js](src/config.js). Every one has a production default,
+so the service needs only credentials.
+
+| Variable | Default | Range | Meaning |
+|---|---|---|---|
+| `PORT` | `8080` | 1 to 65535 | Health endpoint port. Cloud Run injects it. |
+| `GATEWAY_CONCURRENCY` | `8` | 1 to 64 | Inbox rows processed at once, one per chat. |
+| `GATEWAY_POLL_MS` | `1500` | min 100 | Idle wait between claims when the inbox is empty. |
+| `GATEWAY_LEASE_SECONDS` | `90` | min 15 | How long a claimed row is held before another worker may take it. |
+| `GATEWAY_MAX_ATTEMPTS` | `5` | 1 to 20 | Attempts before a row is dead-lettered. |
+| `GATEWAY_BACKOFF_BASE_MS` | `5000` | min 0 | First retry delay; doubles per attempt. |
+| `GATEWAY_BACKOFF_MAX_MS` | `300000` | min 0 | Ceiling on a single retry delay. |
+| `GATEWAY_TURN_TIMEOUT_MS` | `300000` | min 1000 | A row still running after this is failed and its lease released. |
+| `GATEWAY_SWEEP_MS` | `60000` | min 1000 | Preview expiry sweep interval. |
+| `GATEWAY_PRUNE_KEEP_DAYS` | `7` | min 1 | Finished rows older than this are deleted (checked hourly). |
+| `GATEWAY_SHUTDOWN_GRACE_MS` | `8000` | min 0 | How long SIGTERM waits for in-flight rows before exiting. |
+| `GATEWAY_PLATFORMS` | every configured one | comma list | Restrict which adapters load, e.g. `telegram`. |
+| `GATEWAY_CHAT_KEYS` | all chats | comma list | Drain only these chats. For debugging one conversation. |
+| `GATEWAY_TELEGRAM_POLLING` | off | `1` to enable | Pull Telegram updates with `getUpdates` instead of the webhook. Local development only. |
+| `GATEWAY_DISCORD_GATEWAY` | on | `0` to disable | Hold a Discord gateway connection for DMs and mentions. |
+| `GATEWAY_DEBUG` | off | `1` to enable | Emit `DEBUG` log lines (each queued inbound delivery). |
+
+A malformed number (`GATEWAY_CONCURRENCY=eight`) stops the worker at boot
+rather than running with a guess. Out-of-range numbers are clamped.
+
+## Run locally
+
+Every script loads the repo-root `.env` and then `.env.local`
+(`node --env-file-if-exists`, so `.env.local` wins). `DATABASE_URL` lives in
+`.env.local`; the platform tokens do not, so add the ones you need for the
+session or read them from the service:
+
+```bash
+node scripts/read-service-env.mjs '^TELEGRAM_BOT_TOKEN$' --raw
+```
+
+**Read this before you start it with real tokens:** `.env.local` points at the
+production database, so a local worker with a bot token claims and answers the
+real queue for that platform. Use `GATEWAY_CHAT_KEYS` to confine it to your own
+test chat.
+
+From `workers/agent-gateway/`:
+
+```bash
+npm install # the worker's own deps (grammy, discord.js); the rest resolves from the repo root
+npm run dev # boot with ../../.env and ../../.env.local
+```
+
+For Telegram without a public URL, `GATEWAY_TELEGRAM_POLLING=1 npm run dev`
+pulls updates with `getUpdates` and queues them through the same inbox. Polling
+refuses to start while a webhook is set on the bot (Telegram only allows
+`getUpdates` after the webhook is deleted, which would cut production off), and
+logs `telegram polling refused` instead.
+
+### Example: boot it and read its health
+
+With no platform token set the worker still boots, claims nothing (the claim is
+filtered to the platforms that loaded), and reports what is missing. Run from
+`workers/agent-gateway/`:
+
+```bash
+PORT=8799 npm run dev &
+sleep 5
+curl -s -w '\nHTTP %{http_code}\n' localhost:8799/healthz
+kill %1
+```
+
+Output, abridged:
+
+```
+{"ok":false,"platforms":[],"inflight":0,"concurrency":8,"claimed":0,"completed":0,
+ "adapters":{},"skipped":[{"platform":"telegram","missing":["TELEGRAM_BOT_TOKEN"]},
+ {"platform":"discord","missing":["DISCORD_BOT_TOKEN","DISCORD_APP_ID"]}],
+ "backlog":{"open":0,"oldestSeconds":0}}
+HTTP 503
+```
+
+`/healthz` (also `/`) answers `200` when the drain loop is turning and at least
+one adapter loaded, `503` otherwise. Beyond `ok` it carries the claim, completion,
+retry and dead-letter counters, the preview sweep count, each adapter's status
+(Telegram reports `webhook` or `polling` mode), and the open backlog from
+`gateway_inbox`.
+
+### Operator commands
+
+```bash
+npm run register:discord -- --dry-run # print the slash command set, no credentials needed
+npm run register:discord -- --guild <id> # register on one guild (live immediately)
+npm run register:discord # register globally (up to an hour to appear)
+npm run webhook:telegram -- --info # read the bot's current webhook
+npm run webhook:telegram -- --dry-run # show what would be set
+npm run webhook:telegram # point the bot at https://three.ws/api/gateway/telegram and publish its command menu
+npm run inbox # queue depth, oldest open delivery, recent dead letters
+npm run setup -- requeue <id> # put one dead letter back with a fresh attempt budget
+```
+
+The Discord command set is every command in `api/_lib/gateway/commands.js` plus
+`/start`, registered top level and again as subcommands of `/three`. After
+registering, set the interactions endpoint in the Discord developer portal to
+`https://three.ws/api/gateway/discord`; the command prints it.
+
+## Tests
+
+```bash
+cd workers/agent-gateway && npm test
+```
+
+Four suites, 62 tests, about six seconds. They run against a real Postgres:
+PGlite carrying the gateway tables built from the two shipped migrations
+(`api/_lib/migrations/20260922180000_chat_gateways.sql` and
+`20260922190000_more_chat_gateways.sql`) executed verbatim
+([tests/_db.js](tests/_db.js)), so the claim, lease and dead-letter SQL is the
+production SQL. Platform traffic is replayed from recorded payloads in
+[tests/fixtures/](tests/fixtures) (Telegram text, voice, photo, callback and
+group-start updates; Discord commands, buttons and mentions).
+
+| Suite | Covers |
+|---|---|
+| `drain.test.js` | A queued `/help` answered through the real core; `/start` issuing a pairing code and storing only its hash; a duplicate delivery answered once; one row per chat at a time; held, renewed and expired leases; rows for a platform with no adapter left alone; `GATEWAY_CHAT_KEYS`; backoff then dead letter; a 429 `retry_after` honoured; a permanent refusal dead-lettered without an apology; a partially delivered turn never re-run; a timed-out turn; paired-chat approvals, strangers and `/new`; notifications delivered, or dropped when stale or unlinked; the preview sweep; start and graceful stop. |
+| `telegram-adapter.test.js` | Command parsing (including `/cmd@otherbot` in groups), update normalization, voice notes through `getFile`, the largest photo size, long replies split across messages, inline buttons added and removed, photos versus documents, late button presses, spoken replies, error mapping, and the polling guard that refuses to run while a webhook is set. |
+| `discord-adapter.test.js` | `/three` subcommands and top-level commands, button presses, mentions, audio and image attachments, the deferred reply filled first and then followups with mentions disabled, the "thinking..." placeholder removed when a command produced nothing, expired interaction tokens falling back to the channel API, notifications, audio uploads, and error mapping. |
+| `registry-setup.test.js` | Adapter selection by credentials and `GATEWAY_PLATFORMS`, the retry policy, config defaults and the malformed-number refusal, and the Discord and Telegram command sets `setup.js` registers. |
+
+## Deploy
+
+**Status: built and tested, not deployed.** There is no `agent-gateway` Cloud Run
+service yet (checked 2026-10-09). Both gateway migrations are applied to
+production, and the receivers in `api/gateway/` already queue into
+`gateway_inbox`, so deliveries wait in the inbox until this worker runs. Deploys
+are owner-gated (CLAUDE.md); the command is ready.
+
+Build from the repo root, because the image carries the root install and `api/`
+(the gateway core reaches the copilot engine, the agent wallet and the trade
+engine) plus this worker's own two dependencies and the distro `ffmpeg` the voice
+path transcodes with:
+
+```bash
+gcloud builds submit --config workers/agent-gateway/cloudbuild.yaml . \
+ --region us-central1 --project aerial-vehicle-466722-p5 \
+ --substitutions=SHORT_SHA=manual$(date +%s)
+```
+
+`SHORT_SHA` is only set for trigger-driven builds, so a manual submit must pass
+it or the image tag comes out empty.
+
+**The environment is copied, never hand-kept.** On every deploy
+[scripts/deploy-env.mjs](scripts/deploy-env.mjs) reads `gcloud run services
+describe three-ws-api` and mirrors its env: literals into an `--env-vars-file`,
+Secret Manager references into `--set-secrets` by reference, so no secret value
+passes through the script or the build log. Two classes are left out on purpose:
+Cloud Run's reserved names, and platform signers (treasury, fee-payer, relayer
+and payout keys). A chat turn signs only with the agent's own custodial key, and
+a process that reads messages from the internet has no business holding the
+platform's money keys. `WALLET_ENCRYPTION_KEY` is kept. The reason for mirroring:
+the `agent-orders` worker once ran on stale copies of `JWT_SECRET` and
+`WALLET_ENCRYPTION_KEY` and could not decrypt a single agent key.
+
+So a variable the gateway needs belongs on `three-ws-api`, and reaches the worker
+on its next deploy. Today `three-ws-api` carries `TELEGRAM_BOT_TOKEN` and none of
+the Discord variables, so a deploy now would load the Telegram adapter only and
+list Discord under `skipped` in `/healthz`. To preview what a deploy would
+mirror (names only, never values):
+
+```bash
+gcloud run services describe three-ws-api --region us-central1 --format=json > /tmp/api.json
+node workers/agent-gateway/scripts/deploy-env.mjs /tmp/api.json --print
+rm /tmp/api.json
+```
+
+The deploy flags in [cloudbuild.yaml](cloudbuild.yaml) are load-bearing:
+
+| Flag | Why |
+|---|---|
+| `--no-cpu-throttling`, `--min-instances=1` | The drain loop and the Discord gateway connection run between requests; nothing calls this service over HTTP except Cloud Run's probes. |
+| `--max-instances=1` (`_MAX_INSTANCES`) | One instance is enough for the load. More are safe because the claim is exclusive. |
+| `--no-allow-unauthenticated` | No public HTTP surface. |
+| `--vpc-connector=three-ws-vpc` | Matches `three-ws-api`: the rate limiter's Redis endpoint is a private address. |
+| `--service-account=three-ws@` | The runtime account; the build runs as the pinned `three-ws-build@` (the default compute service account was deleted). |
+
+`GATEWAY_CONCURRENCY` and `GATEWAY_MAX_ATTEMPTS` ride in as the `_CONCURRENCY`
+and `_MAX_ATTEMPTS` build substitutions.
+
+After the first deploy, point the bots at production once:
+`npm run webhook:telegram` and `npm run register:discord` (from this directory).
+
+## Operations
+
+- **Logs:** `gcloud logging read 'resource.type="cloud_run_revision" resource.labels.service_name="agent-gateway"' --freshness=1h`. Filter `severity>=WARNING` for retries and dead letters; `row dead-lettered` carries the reason.
+- **Stuck queue:** `npm run inbox` shows depth, the oldest open delivery and the latest dead letters; `npm run setup -- requeue <id>` retries one.
+- **One bad chat:** a redeploy with `GATEWAY_CHAT_KEYS` set, or a local run with it, isolates that conversation.
+
+## Related
+
+- [api/_lib/gateway/](../../api/_lib/gateway): the platform-neutral core (pairing, commands, conversation, approvals, notifications, the inbox store).
+- [api/gateway/](../../api/gateway): the Telegram and Discord webhook receivers and the owner's connections API (`/api/gateway/connections`).
+- [workers/signal-bridge](../signal-bridge): the Signal leg, a signal-cli REST bridge this worker's adapter registry is built to take next.
+- [STRUCTURE.md](../../STRUCTURE.md): where this sits among the other workers.